doc/crypto-api.texi

   1
   2 @subheading gnutls_cipher_add_auth
   3 @anchor{gnutls_cipher_add_auth}
   4 @deftypefun {int} {gnutls_cipher_add_auth} (gnutls_cipher_hd_t @var{handle}, const void * @var{text}, size_t @var{text_size})
   5 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
   6
   7 @var{text}: the data to be authenticated
   8
   9 @var{text_size}: The length of the data
  10
  11 This function operates on authenticated encryption with
  12 associated data (AEAD) ciphers and authenticate the
  13 input data. This function can only be called once
  14 and before any encryption operations.
  15
  16 @strong{Returns:} Zero or a negative error code on error.
  17
  18 @strong{Since:} 3.0
  19 @end deftypefun
  20
  21 @subheading gnutls_cipher_decrypt
  22 @anchor{gnutls_cipher_decrypt}
  23 @deftypefun {int} {gnutls_cipher_decrypt} (gnutls_cipher_hd_t @var{handle}, void * @var{ciphertext}, size_t @var{ciphertextlen})
  24 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
  25
  26 @var{ciphertext}: the data to encrypt
  27
  28 @var{ciphertextlen}: The length of data to encrypt
  29
  30 This function will decrypt the given data using the algorithm
  31 specified by the context.
  32
  33 Note that in AEAD ciphers, this will not check the tag. You will
  34 need to compare the tag sent with the value returned from @code{gnutls_cipher_tag()} .
  35
  36 @strong{Returns:} Zero or a negative error code on error.
  37
  38 @strong{Since:} 2.10.0
  39 @end deftypefun
  40
  41 @subheading gnutls_cipher_decrypt2
  42 @anchor{gnutls_cipher_decrypt2}
  43 @deftypefun {int} {gnutls_cipher_decrypt2} (gnutls_cipher_hd_t @var{handle}, const void * @var{ciphertext}, size_t @var{ciphertextlen}, void * @var{text}, size_t @var{textlen})
  44 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
  45
  46 @var{ciphertext}: the data to encrypt
  47
  48 @var{ciphertextlen}: The length of data to encrypt
  49
  50 @var{text}: the decrypted data
  51
  52 @var{textlen}: The available length for decrypted data
  53
  54 This function will decrypt the given data using the algorithm
  55 specified by the context.
  56
  57 Note that in AEAD ciphers, this will not check the tag. You will
  58 need to compare the tag sent with the value returned from @code{gnutls_cipher_tag()} .
  59
  60 @strong{Returns:} Zero or a negative error code on error.
  61
  62 @strong{Since:} 2.12.0
  63 @end deftypefun
  64
  65 @subheading gnutls_cipher_deinit
  66 @anchor{gnutls_cipher_deinit}
  67 @deftypefun {void} {gnutls_cipher_deinit} (gnutls_cipher_hd_t @var{handle})
  68 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
  69
  70 This function will deinitialize all resources occupied by the given
  71 encryption context.
  72
  73 @strong{Since:} 2.10.0
  74 @end deftypefun
  75
  76 @subheading gnutls_cipher_encrypt
  77 @anchor{gnutls_cipher_encrypt}
  78 @deftypefun {int} {gnutls_cipher_encrypt} (gnutls_cipher_hd_t @var{handle}, void * @var{text}, size_t @var{textlen})
  79 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
  80
  81 @var{text}: the data to encrypt
  82
  83 @var{textlen}: The length of data to encrypt
  84
  85 This function will encrypt the given data using the algorithm
  86 specified by the context.
  87
  88 @strong{Returns:} Zero or a negative error code on error.
  89
  90 @strong{Since:} 2.10.0
  91 @end deftypefun
  92
  93 @subheading gnutls_cipher_encrypt2
  94 @anchor{gnutls_cipher_encrypt2}
  95 @deftypefun {int} {gnutls_cipher_encrypt2} (gnutls_cipher_hd_t @var{handle}, const void * @var{text}, size_t @var{textlen}, void * @var{ciphertext}, size_t @var{ciphertextlen})
  96 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
  97
  98 @var{text}: the data to encrypt
  99
 100 @var{textlen}: The length of data to encrypt
 101
 102 @var{ciphertext}: the encrypted data
 103
 104 @var{ciphertextlen}: The available length for encrypted data
 105
 106 This function will encrypt the given data using the algorithm
 107 specified by the context.
 108
 109 @strong{Returns:} Zero or a negative error code on error.
 110
 111 @strong{Since:} 2.12.0
 112 @end deftypefun
 113
 114 @subheading gnutls_cipher_get_block_size
 115 @anchor{gnutls_cipher_get_block_size}
 116 @deftypefun {int} {gnutls_cipher_get_block_size} (gnutls_cipher_algorithm_t @var{algorithm})
 117 @var{algorithm}: is an encryption algorithm
 118
 119
 120 @strong{Returns:} the block size of the encryption algorithm.
 121
 122 @strong{Since:} 2.10.0
 123 @end deftypefun
 124
 125 @subheading gnutls_cipher_get_iv_size
 126 @anchor{gnutls_cipher_get_iv_size}
 127 @deftypefun {int} {gnutls_cipher_get_iv_size} (gnutls_cipher_algorithm_t @var{algorithm})
 128 @var{algorithm}: is an encryption algorithm
 129
 130 Get block size for encryption algorithm.
 131
 132 @strong{Returns:} block size for encryption algorithm.
 133
 134 @strong{Since:} 3.2.0
 135 @end deftypefun
 136
 137 @subheading gnutls_cipher_get_tag_size
 138 @anchor{gnutls_cipher_get_tag_size}
 139 @deftypefun {int} {gnutls_cipher_get_tag_size} (gnutls_cipher_algorithm_t @var{algorithm})
 140 @var{algorithm}: is an encryption algorithm
 141
 142
 143 @strong{Returns:} the tag size of the authenticated encryption algorithm.
 144
 145 @strong{Since:} 3.2.2
 146 @end deftypefun
 147
 148 @subheading gnutls_cipher_init
 149 @anchor{gnutls_cipher_init}
 150 @deftypefun {int} {gnutls_cipher_init} (gnutls_cipher_hd_t * @var{handle}, gnutls_cipher_algorithm_t @var{cipher}, const gnutls_datum_t * @var{key}, const gnutls_datum_t * @var{iv})
 151 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 152
 153 @var{cipher}: the encryption algorithm to use
 154
 155 @var{key}: The key to be used for encryption
 156
 157 @var{iv}: The IV to use (if not applicable set NULL)
 158
 159 This function will initialize an context that can be used for
 160 encryption/decryption of data. This will effectively use the
 161 current crypto backend in use by gnutls or the cryptographic
 162 accelerator in use.
 163
 164 @strong{Returns:} Zero or a negative error code on error.
 165
 166 @strong{Since:} 2.10.0
 167 @end deftypefun
 168
 169 @subheading gnutls_cipher_set_iv
 170 @anchor{gnutls_cipher_set_iv}
 171 @deftypefun {void} {gnutls_cipher_set_iv} (gnutls_cipher_hd_t @var{handle}, void * @var{iv}, size_t @var{ivlen})
 172 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 173
 174 @var{iv}: the IV to set
 175
 176 @var{ivlen}: The length of the IV
 177
 178 This function will set the IV to be used for the next
 179 encryption block.
 180
 181 @strong{Since:} 3.0
 182 @end deftypefun
 183
 184 @subheading gnutls_cipher_tag
 185 @anchor{gnutls_cipher_tag}
 186 @deftypefun {int} {gnutls_cipher_tag} (gnutls_cipher_hd_t @var{handle}, void * @var{tag}, size_t @var{tag_size})
 187 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 188
 189 @var{tag}: will hold the tag
 190
 191 @var{tag_size}: The length of the tag to return
 192
 193 This function operates on authenticated encryption with
 194 associated data (AEAD) ciphers and will return the
 195 output tag.
 196
 197 @strong{Returns:} Zero or a negative error code on error.
 198
 199 @strong{Since:} 3.0
 200 @end deftypefun
 201
 202 @subheading gnutls_hash
 203 @anchor{gnutls_hash}
 204 @deftypefun {int} {gnutls_hash} (gnutls_hash_hd_t @var{handle}, const void * @var{text}, size_t @var{textlen})
 205 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 206
 207 @var{text}: the data to hash
 208
 209 @var{textlen}: The length of data to hash
 210
 211 This function will hash the given data using the algorithm
 212 specified by the context.
 213
 214 @strong{Returns:} Zero or a negative error code on error.
 215
 216 @strong{Since:} 2.10.0
 217 @end deftypefun
 218
 219 @subheading gnutls_hash_deinit
 220 @anchor{gnutls_hash_deinit}
 221 @deftypefun {void} {gnutls_hash_deinit} (gnutls_hash_hd_t @var{handle}, void * @var{digest})
 222 @var{handle}: is a @code{gnutls_hash_hd_t}  structure.
 223
 224 @var{digest}: is the output value of the hash
 225
 226 This function will deinitialize all resources occupied by
 227 the given hash context.
 228
 229 @strong{Since:} 2.10.0
 230 @end deftypefun
 231
 232 @subheading gnutls_hash_fast
 233 @anchor{gnutls_hash_fast}
 234 @deftypefun {int} {gnutls_hash_fast} (gnutls_digest_algorithm_t @var{algorithm}, const void * @var{text}, size_t @var{textlen}, void * @var{digest})
 235 @var{algorithm}: the hash algorithm to use
 236
 237 @var{text}: the data to hash
 238
 239 @var{textlen}: The length of data to hash
 240
 241 @var{digest}: is the output value of the hash
 242
 243 This convenience function will hash the given data and return output
 244 on a single call.
 245
 246 @strong{Returns:} Zero or a negative error code on error.
 247
 248 @strong{Since:} 2.10.0
 249 @end deftypefun
 250
 251 @subheading gnutls_hash_get_len
 252 @anchor{gnutls_hash_get_len}
 253 @deftypefun {int} {gnutls_hash_get_len} (gnutls_digest_algorithm_t @var{algorithm})
 254 @var{algorithm}: the hash algorithm to use
 255
 256 This function will return the length of the output data
 257 of the given hash algorithm.
 258
 259 @strong{Returns:} The length or zero on error.
 260
 261 @strong{Since:} 2.10.0
 262 @end deftypefun
 263
 264 @subheading gnutls_hash_init
 265 @anchor{gnutls_hash_init}
 266 @deftypefun {int} {gnutls_hash_init} (gnutls_hash_hd_t * @var{dig}, gnutls_digest_algorithm_t @var{algorithm})
 267 @var{dig}: is a @code{gnutls_hash_hd_t}  structure.
 268
 269 @var{algorithm}: the hash algorithm to use
 270
 271 This function will initialize an context that can be used to
 272 produce a Message Digest of data.  This will effectively use the
 273 current crypto backend in use by gnutls or the cryptographic
 274 accelerator in use.
 275
 276 @strong{Returns:} Zero or a negative error code on error.
 277
 278 @strong{Since:} 2.10.0
 279 @end deftypefun
 280
 281 @subheading gnutls_hash_output
 282 @anchor{gnutls_hash_output}
 283 @deftypefun {void} {gnutls_hash_output} (gnutls_hash_hd_t @var{handle}, void * @var{digest})
 284 @var{handle}: is a @code{gnutls_hash_hd_t}  structure.
 285
 286 @var{digest}: is the output value of the hash
 287
 288 This function will output the current hash value
 289 and reset the state of the hash.
 290
 291 @strong{Since:} 2.10.0
 292 @end deftypefun
 293
 294 @subheading gnutls_hmac
 295 @anchor{gnutls_hmac}
 296 @deftypefun {int} {gnutls_hmac} (gnutls_hmac_hd_t @var{handle}, const void * @var{text}, size_t @var{textlen})
 297 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 298
 299 @var{text}: the data to hash
 300
 301 @var{textlen}: The length of data to hash
 302
 303 This function will hash the given data using the algorithm
 304 specified by the context.
 305
 306 @strong{Returns:} Zero or a negative error code on error.
 307
 308 @strong{Since:} 2.10.0
 309 @end deftypefun
 310
 311 @subheading gnutls_hmac_deinit
 312 @anchor{gnutls_hmac_deinit}
 313 @deftypefun {void} {gnutls_hmac_deinit} (gnutls_hmac_hd_t @var{handle}, void * @var{digest})
 314 @var{handle}: is a @code{gnutls_hmac_hd_t}  structure.
 315
 316 @var{digest}: is the output value of the MAC
 317
 318 This function will deinitialize all resources occupied by
 319 the given hmac context.
 320
 321 @strong{Since:} 2.10.0
 322 @end deftypefun
 323
 324 @subheading gnutls_hmac_fast
 325 @anchor{gnutls_hmac_fast}
 326 @deftypefun {int} {gnutls_hmac_fast} (gnutls_mac_algorithm_t @var{algorithm}, const void * @var{key}, size_t @var{keylen}, const void * @var{text}, size_t @var{textlen}, void * @var{digest})
 327 @var{algorithm}: the hash algorithm to use
 328
 329 @var{key}: the key to use
 330
 331 @var{keylen}: The length of the key
 332
 333 @var{text}: the data to hash
 334
 335 @var{textlen}: The length of data to hash
 336
 337 @var{digest}: is the output value of the hash
 338
 339 This convenience function will hash the given data and return output
 340 on a single call.
 341
 342 @strong{Returns:} Zero or a negative error code on error.
 343
 344 @strong{Since:} 2.10.0
 345 @end deftypefun
 346
 347 @subheading gnutls_hmac_get_len
 348 @anchor{gnutls_hmac_get_len}
 349 @deftypefun {int} {gnutls_hmac_get_len} (gnutls_mac_algorithm_t @var{algorithm})
 350 @var{algorithm}: the hmac algorithm to use
 351
 352 This function will return the length of the output data
 353 of the given hmac algorithm.
 354
 355 @strong{Returns:} The length or zero on error.
 356
 357 @strong{Since:} 2.10.0
 358 @end deftypefun
 359
 360 @subheading gnutls_hmac_init
 361 @anchor{gnutls_hmac_init}
 362 @deftypefun {int} {gnutls_hmac_init} (gnutls_hmac_hd_t * @var{dig}, gnutls_mac_algorithm_t @var{algorithm}, const void * @var{key}, size_t @var{keylen})
 363 @var{dig}: is a @code{gnutls_hmac_hd_t}  structure.
 364
 365 @var{algorithm}: the HMAC algorithm to use
 366
 367 @var{key}: The key to be used for encryption
 368
 369 @var{keylen}: The length of the key
 370
 371 This function will initialize an context that can be used to
 372 produce a Message Authentication Code (MAC) of data.  This will
 373 effectively use the current crypto backend in use by gnutls or the
 374 cryptographic accelerator in use.
 375
 376 Note that despite the name of this function, it can be used
 377 for other MAC algorithms than HMAC.
 378
 379 @strong{Returns:} Zero or a negative error code on error.
 380
 381 @strong{Since:} 2.10.0
 382 @end deftypefun
 383
 384 @subheading gnutls_hmac_output
 385 @anchor{gnutls_hmac_output}
 386 @deftypefun {void} {gnutls_hmac_output} (gnutls_hmac_hd_t @var{handle}, void * @var{digest})
 387 @var{handle}: is a @code{gnutls_hmac_hd_t}  structure.
 388
 389 @var{digest}: is the output value of the MAC
 390
 391 This function will output the current MAC value
 392 and reset the state of the MAC.
 393
 394 @strong{Since:} 2.10.0
 395 @end deftypefun
 396
 397 @subheading gnutls_hmac_set_nonce
 398 @anchor{gnutls_hmac_set_nonce}
 399 @deftypefun {void} {gnutls_hmac_set_nonce} (gnutls_hmac_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len})
 400 @var{handle}: is a @code{gnutls_cipher_hd_t}  structure.
 401
 402 @var{nonce}: the data to set as nonce
 403
 404 @var{nonce_len}: The length of data
 405
 406 This function will set the nonce in the MAC algorithm.
 407
 408 @strong{Since:} 3.2.0
 409 @end deftypefun
 410
 411 @subheading gnutls_mac_get_nonce_size
 412 @anchor{gnutls_mac_get_nonce_size}
 413 @deftypefun {size_t} {gnutls_mac_get_nonce_size} (gnutls_mac_algorithm_t @var{algorithm})
 414 @var{algorithm}: is an encryption algorithm
 415
 416 Returns the size of the nonce used by the MAC in TLS.
 417
 418 @strong{Returns:} length (in bytes) of the given MAC nonce size, or 0.
 419
 420 @strong{Since:} 3.2.0
 421 @end deftypefun
 422
 423 @subheading gnutls_rnd
 424 @anchor{gnutls_rnd}
 425 @deftypefun {int} {gnutls_rnd} (gnutls_rnd_level_t @var{level}, void * @var{data}, size_t @var{len})
 426 @var{level}: a security level
 427
 428 @var{data}: place to store random bytes
 429
 430 @var{len}: The requested size
 431
 432 This function will generate random data and store it to output
 433 buffer.
 434
 435 This function is thread-safe and also fork-safe.
 436
 437 @strong{Returns:} Zero on success, or a negative error code on error.
 438
 439 @strong{Since:} 2.12.0
 440 @end deftypefun
 441
 442 @subheading gnutls_rnd_refresh
 443 @anchor{gnutls_rnd_refresh}
 444 @deftypefun {void} {gnutls_rnd_refresh} ()
 445
 446 This function refreshes the random generator state.
 447 That is the current precise time, CPU usage, and
 448 other values are input into its state.
 449
 450 On a slower rate input from /dev/urandom is mixed too.
 451
 452 @strong{Since:} 3.1.7
 453 @end deftypefun
 454