path: root/doc/crypto-api.texi

@subheading gnutls_aead_cipher_decrypt
@anchor{gnutls_aead_cipher_decrypt}
@deftypefun {int} {gnutls_aead_cipher_decrypt} (gnutls_aead_cipher_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len}, const void * @var{auth}, size_t @var{auth_len}, size_t @var{tag_size}, const void * @var{ctext}, size_t @var{ctext_len}, void * @var{ptext}, size_t * @var{ptext_len})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{nonce}: the nonce to set

@var{nonce_len}: The length of the nonce

@var{auth}: additional data to be authenticated

@var{auth_len}: The length of the data

@var{tag_size}: The size of the tag to use (use zero for the default)

@var{ctext}: the data to decrypt (including the authentication tag)

@var{ctext_len}: the length of data to decrypt (includes tag size)

@var{ptext}: the decrypted data

@var{ptext_len}: the length of decrypted data (initially must hold the maximum available size)

This function will decrypt the given data using the algorithm
specified by the context. This function must be provided the complete
data to be decrypted, including the authentication tag. On several
AEAD ciphers, the authentication tag is appended to the ciphertext,
though this is not a general rule. This function will fail if
the tag verification fails.

@strong{Returns:} Zero or a negative error code on verification failure or other error.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_aead_cipher_decryptv2
@anchor{gnutls_aead_cipher_decryptv2}
@deftypefun {int} {gnutls_aead_cipher_decryptv2} (gnutls_aead_cipher_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len}, const giovec_t * @var{auth_iov}, int @var{auth_iovcnt}, const giovec_t * @var{iov}, int @var{iovcnt}, void * @var{tag}, size_t @var{tag_size})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{nonce}: the nonce to set

@var{nonce_len}: The length of the nonce

@var{auth_iov}: additional data to be authenticated

@var{auth_iovcnt}: The number of buffers in  @code{auth_iov} 

@var{iov}: the data to decrypt

@var{iovcnt}: The number of buffers in  @code{iov} 

@var{tag}: The authentication tag

@var{tag_size}: The size of the tag to use (use zero for the default)

This is similar to @code{gnutls_aead_cipher_decrypt()} , but it performs
in-place encryption on the provided data buffers.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.10
@end deftypefun

@subheading gnutls_aead_cipher_deinit
@anchor{gnutls_aead_cipher_deinit}
@deftypefun {void} {gnutls_aead_cipher_deinit} (gnutls_aead_cipher_hd_t @var{handle})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

This function will deinitialize all resources occupied by the given
authenticated-encryption context.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_aead_cipher_encrypt
@anchor{gnutls_aead_cipher_encrypt}
@deftypefun {int} {gnutls_aead_cipher_encrypt} (gnutls_aead_cipher_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len}, const void * @var{auth}, size_t @var{auth_len}, size_t @var{tag_size}, const void * @var{ptext}, size_t @var{ptext_len}, void * @var{ctext}, size_t * @var{ctext_len})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{nonce}: the nonce to set

@var{nonce_len}: The length of the nonce

@var{auth}: additional data to be authenticated

@var{auth_len}: The length of the data

@var{tag_size}: The size of the tag to use (use zero for the default)

@var{ptext}: the data to encrypt

@var{ptext_len}: The length of data to encrypt

@var{ctext}: the encrypted data including authentication tag

@var{ctext_len}: the length of encrypted data (initially must hold the maximum available size, including space for tag)

This function will encrypt the given data using the algorithm
specified by the context. The output data will contain the
authentication tag.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_aead_cipher_encryptv
@anchor{gnutls_aead_cipher_encryptv}
@deftypefun {int} {gnutls_aead_cipher_encryptv} (gnutls_aead_cipher_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len}, const giovec_t * @var{auth_iov}, int @var{auth_iovcnt}, size_t @var{tag_size}, const giovec_t * @var{iov}, int @var{iovcnt}, void * @var{ctext}, size_t * @var{ctext_len})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{nonce}: the nonce to set

@var{nonce_len}: The length of the nonce

@var{auth_iov}: additional data to be authenticated

@var{auth_iovcnt}: The number of buffers in  @code{auth_iov} 

@var{tag_size}: The size of the tag to use (use zero for the default)

@var{iov}: the data to be encrypted

@var{iovcnt}: The number of buffers in  @code{iov} 

@var{ctext}: the encrypted data including authentication tag

@var{ctext_len}: the length of encrypted data (initially must hold the maximum available size, including space for tag)

This function will encrypt the provided data buffers using the algorithm
specified by the context. The output data will contain the
authentication tag.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.3
@end deftypefun

@subheading gnutls_aead_cipher_encryptv2
@anchor{gnutls_aead_cipher_encryptv2}
@deftypefun {int} {gnutls_aead_cipher_encryptv2} (gnutls_aead_cipher_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len}, const giovec_t * @var{auth_iov}, int @var{auth_iovcnt}, const giovec_t * @var{iov}, int @var{iovcnt}, void * @var{tag}, size_t * @var{tag_size})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{nonce}: the nonce to set

@var{nonce_len}: The length of the nonce

@var{auth_iov}: additional data to be authenticated

@var{auth_iovcnt}: The number of buffers in  @code{auth_iov} 

@var{iov}: the data to be encrypted

@var{iovcnt}: The number of buffers in  @code{iov} 

@var{tag}: The authentication tag

@var{tag_size}: The size of the tag to use (use zero for the default)

This is similar to @code{gnutls_aead_cipher_encrypt()} , but it performs
in-place encryption on the provided data buffers.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.10
@end deftypefun

@subheading gnutls_aead_cipher_init
@anchor{gnutls_aead_cipher_init}
@deftypefun {int} {gnutls_aead_cipher_init} (gnutls_aead_cipher_hd_t * @var{handle}, gnutls_cipher_algorithm_t @var{cipher}, const gnutls_datum_t * @var{key})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{cipher}: the authenticated-encryption algorithm to use

@var{key}: The key to be used for encryption

This function will initialize an context that can be used for
encryption/decryption of data. This will effectively use the
current crypto backend in use by gnutls or the cryptographic
accelerator in use.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_aead_cipher_set_key
@anchor{gnutls_aead_cipher_set_key}
@deftypefun {int} {gnutls_aead_cipher_set_key} (gnutls_aead_cipher_hd_t @var{handle}, const gnutls_datum_t * @var{key})
@var{handle}: is a @code{gnutls_aead_cipher_hd_t}  type.

@var{key}: The key to be used for encryption

This function will set a new key without re-initializing the
context.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.7.5
@end deftypefun

@subheading gnutls_cipher_add_auth
@anchor{gnutls_cipher_add_auth}
@deftypefun {int} {gnutls_cipher_add_auth} (gnutls_cipher_hd_t @var{handle}, const void * @var{ptext}, size_t @var{ptext_size})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ptext}: the data to be authenticated

@var{ptext_size}: the length of the data

This function operates on authenticated encryption with
associated data (AEAD) ciphers and authenticate the
input data. This function can only be called once
and before any encryption operations.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_cipher_decrypt
@anchor{gnutls_cipher_decrypt}
@deftypefun {int} {gnutls_cipher_decrypt} (gnutls_cipher_hd_t @var{handle}, void * @var{ctext}, size_t @var{ctext_len})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ctext}: the data to decrypt

@var{ctext_len}: the length of data to decrypt

This function will decrypt the given data using the algorithm
specified by the context.

Note that in AEAD ciphers, this will not check the tag. You will
need to compare the tag sent with the value returned from @code{gnutls_cipher_tag()} .

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_cipher_decrypt2
@anchor{gnutls_cipher_decrypt2}
@deftypefun {int} {gnutls_cipher_decrypt2} (gnutls_cipher_hd_t @var{handle}, const void * @var{ctext}, size_t @var{ctext_len}, void * @var{ptext}, size_t @var{ptext_len})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ctext}: the data to decrypt

@var{ctext_len}: the length of data to decrypt

@var{ptext}: the decrypted data

@var{ptext_len}: the available length for decrypted data

This function will decrypt the given data using the algorithm
specified by the context. For block ciphers the  @code{ctext_len} must be
a multiple of the block size. For the supported ciphers the plaintext
data length will equal the ciphertext size.

Note that in AEAD ciphers, this will not check the tag. You will
need to compare the tag sent with the value returned from @code{gnutls_cipher_tag()} .

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_cipher_decrypt3
@anchor{gnutls_cipher_decrypt3}
@deftypefun {int} {gnutls_cipher_decrypt3} (gnutls_cipher_hd_t @var{handle}, const void * @var{ctext}, size_t @var{ctext_len}, void * @var{ptext}, size_t * @var{ptext_len}, unsigned @var{flags})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ctext}: the data to decrypt

@var{ctext_len}: the length of data to decrypt

@var{ptext}: the decrypted data

@var{ptext_len}: the available length for decrypted data

@var{flags}: flags for padding

This function will decrypt the given data using the algorithm
specified by the context. If  @code{flags} is specified, padding for the
decrypted data will be removed accordingly and  @code{ptext_len} will be
updated.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.7.7
@end deftypefun

@subheading gnutls_cipher_deinit
@anchor{gnutls_cipher_deinit}
@deftypefun {void} {gnutls_cipher_deinit} (gnutls_cipher_hd_t @var{handle})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

This function will deinitialize all resources occupied by the given
encryption context.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_cipher_encrypt
@anchor{gnutls_cipher_encrypt}
@deftypefun {int} {gnutls_cipher_encrypt} (gnutls_cipher_hd_t @var{handle}, void * @var{ptext}, size_t @var{ptext_len})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ptext}: the data to encrypt

@var{ptext_len}: the length of data to encrypt

This function will encrypt the given data using the algorithm
specified by the context.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_cipher_encrypt2
@anchor{gnutls_cipher_encrypt2}
@deftypefun {int} {gnutls_cipher_encrypt2} (gnutls_cipher_hd_t @var{handle}, const void * @var{ptext}, size_t @var{ptext_len}, void * @var{ctext}, size_t @var{ctext_len})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ptext}: the data to encrypt

@var{ptext_len}: the length of data to encrypt

@var{ctext}: the encrypted data

@var{ctext_len}: the available length for encrypted data

This function will encrypt the given data using the algorithm
specified by the context. For block ciphers the  @code{ptext_len} must be
a multiple of the block size. For the supported ciphers the encrypted
data length will equal the plaintext size.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_cipher_encrypt3
@anchor{gnutls_cipher_encrypt3}
@deftypefun {int} {gnutls_cipher_encrypt3} (gnutls_cipher_hd_t @var{handle}, const void * @var{ptext}, size_t @var{ptext_len}, void * @var{ctext}, size_t * @var{ctext_len}, unsigned @var{flags})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{ptext}: the data to encrypt

@var{ptext_len}: the length of data to encrypt

@var{ctext}: the encrypted data

@var{ctext_len}: the length of encrypted data (initially must hold the maximum available size)

@var{flags}: flags for padding

This function will encrypt the given data using the algorithm
specified by the context. For block ciphers,  @code{ptext_len} is
typically a multiple of the block size. If not, the caller can
instruct the function to pad the last block according to  @code{flags} .
Currently, the only available padding scheme is
@code{GNUTLS_CIPHER_PADDING_PKCS7} .

If  @code{ctext} is not @code{NULL} , it must hold enough space to store
resulting cipher text. To check the required size, this function
can be called with  @code{ctext} set to @code{NULL} . Then  @code{ctext_len} will be
updated without performing actual encryption.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.7.7
@end deftypefun

@subheading gnutls_cipher_get_block_size
@anchor{gnutls_cipher_get_block_size}
@deftypefun {unsigned} {gnutls_cipher_get_block_size} (gnutls_cipher_algorithm_t @var{algorithm})
@var{algorithm}: is an encryption algorithm


@strong{Returns:} the block size of the encryption algorithm.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_cipher_get_iv_size
@anchor{gnutls_cipher_get_iv_size}
@deftypefun {unsigned} {gnutls_cipher_get_iv_size} (gnutls_cipher_algorithm_t @var{algorithm})
@var{algorithm}: is an encryption algorithm

This function returns the size of the initialization vector (IV) for the
provided algorithm. For algorithms with variable size IV (e.g., AES-CCM),
the returned size will be the one used by TLS.

@strong{Returns:} block size for encryption algorithm.

@strong{Since:} 3.2.0
@end deftypefun

@subheading gnutls_cipher_get_tag_size
@anchor{gnutls_cipher_get_tag_size}
@deftypefun {unsigned} {gnutls_cipher_get_tag_size} (gnutls_cipher_algorithm_t @var{algorithm})
@var{algorithm}: is an encryption algorithm

This function returns the tag size of an authenticated encryption
algorithm. For non-AEAD algorithms, it returns zero.

@strong{Returns:} the tag size of the authenticated encryption algorithm.

@strong{Since:} 3.2.2
@end deftypefun

@subheading gnutls_cipher_init
@anchor{gnutls_cipher_init}
@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})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{cipher}: the encryption algorithm to use

@var{key}: the key to be used for encryption/decryption

@var{iv}: the IV to use (if not applicable set NULL)

This function will initialize the  @code{handle} context to be usable
for encryption/decryption of data. This will effectively use the
current crypto backend in use by gnutls or the cryptographic
accelerator in use.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_cipher_set_iv
@anchor{gnutls_cipher_set_iv}
@deftypefun {void} {gnutls_cipher_set_iv} (gnutls_cipher_hd_t @var{handle}, void * @var{iv}, size_t @var{ivlen})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{iv}: the IV to set

@var{ivlen}: the length of the IV

This function will set the IV to be used for the next
encryption block.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_cipher_tag
@anchor{gnutls_cipher_tag}
@deftypefun {int} {gnutls_cipher_tag} (gnutls_cipher_hd_t @var{handle}, void * @var{tag}, size_t @var{tag_size})
@var{handle}: is a @code{gnutls_cipher_hd_t}  type

@var{tag}: will hold the tag

@var{tag_size}: the length of the tag to return

This function operates on authenticated encryption with
associated data (AEAD) ciphers and will return the
output tag.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.0
@end deftypefun

@subheading gnutls_crypto_register_aead_cipher
@anchor{gnutls_crypto_register_aead_cipher}
@deftypefun {int} {gnutls_crypto_register_aead_cipher} (gnutls_cipher_algorithm_t @var{algorithm}, int @var{priority}, gnutls_cipher_init_func @var{init}, gnutls_cipher_setkey_func @var{setkey}, gnutls_cipher_aead_encrypt_func @var{aead_encrypt}, gnutls_cipher_aead_decrypt_func @var{aead_decrypt}, gnutls_cipher_deinit_func @var{deinit})
@var{algorithm}: is the gnutls AEAD cipher identifier

@var{priority}: is the priority of the algorithm

@var{init}: A function which initializes the cipher

@var{setkey}: A function which sets the key of the cipher

@var{aead_encrypt}: Perform the AEAD encryption

@var{aead_decrypt}: Perform the AEAD decryption

@var{deinit}: A function which deinitializes the cipher

This function will register a cipher algorithm to be used by
gnutls.  Any algorithm registered will override the included
algorithms and by convention kernel implemented algorithms have
priority of 90 and CPU-assisted of 80.  The algorithm with the lowest priority will be
used by gnutls.

In the case the registered init or setkey functions return @code{GNUTLS_E_NEED_FALLBACK} ,
GnuTLS will attempt to use the next in priority registered cipher.

The functions registered will be used with the new AEAD API introduced in
GnuTLS 3.4.0. Internally GnuTLS uses the new AEAD API.

@strong{Deprecated:} since 3.7.0 it is no longer possible to override cipher implementation

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_crypto_register_cipher
@anchor{gnutls_crypto_register_cipher}
@deftypefun {int} {gnutls_crypto_register_cipher} (gnutls_cipher_algorithm_t @var{algorithm}, int @var{priority}, gnutls_cipher_init_func @var{init}, gnutls_cipher_setkey_func @var{setkey}, gnutls_cipher_setiv_func @var{setiv}, gnutls_cipher_encrypt_func @var{encrypt}, gnutls_cipher_decrypt_func @var{decrypt}, gnutls_cipher_deinit_func @var{deinit})
@var{algorithm}: is the gnutls algorithm identifier

@var{priority}: is the priority of the algorithm

@var{init}: A function which initializes the cipher

@var{setkey}: A function which sets the key of the cipher

@var{setiv}: A function which sets the nonce/IV of the cipher (non-AEAD)

@var{encrypt}: A function which performs encryption (non-AEAD)

@var{decrypt}: A function which performs decryption (non-AEAD)

@var{deinit}: A function which deinitializes the cipher

This function will register a cipher algorithm to be used by
gnutls.  Any algorithm registered will override the included
algorithms and by convention kernel implemented algorithms have
priority of 90 and CPU-assisted of 80.  The algorithm with the lowest priority will be
used by gnutls.

In the case the registered init or setkey functions return @code{GNUTLS_E_NEED_FALLBACK} ,
GnuTLS will attempt to use the next in priority registered cipher.

The functions which are marked as non-AEAD they are not required when
registering a cipher to be used with the new AEAD API introduced in
GnuTLS 3.4.0. Internally GnuTLS uses the new AEAD API.

@strong{Deprecated:} since 3.7.0 it is no longer possible to override cipher implementation

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_crypto_register_digest
@anchor{gnutls_crypto_register_digest}
@deftypefun {int} {gnutls_crypto_register_digest} (gnutls_digest_algorithm_t @var{algorithm}, int @var{priority}, gnutls_digest_init_func @var{init}, gnutls_digest_hash_func @var{hash}, gnutls_digest_output_func @var{output}, gnutls_digest_deinit_func @var{deinit}, gnutls_digest_fast_func @var{hash_fast})
@var{algorithm}: is the gnutls digest identifier

@var{priority}: is the priority of the algorithm

@var{init}: A function which initializes the digest

@var{hash}: Perform the hash operation

@var{output}: Provide the output of the digest

@var{deinit}: A function which deinitializes the digest

@var{hash_fast}: Perform the digest operation in one go

This function will register a digest algorithm to be used by gnutls.
Any algorithm registered will override the included algorithms and
by convention kernel implemented algorithms have priority of 90
and CPU-assisted of 80.
The algorithm with the lowest priority will be used by gnutls.

@strong{Deprecated:} since 3.7.0 it is no longer possible to override cipher implementation

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_crypto_register_mac
@anchor{gnutls_crypto_register_mac}
@deftypefun {int} {gnutls_crypto_register_mac} (gnutls_mac_algorithm_t @var{algorithm}, int @var{priority}, gnutls_mac_init_func @var{init}, gnutls_mac_setkey_func @var{setkey}, gnutls_mac_setnonce_func @var{setnonce}, gnutls_mac_hash_func @var{hash}, gnutls_mac_output_func @var{output}, gnutls_mac_deinit_func @var{deinit}, gnutls_mac_fast_func @var{hash_fast})
@var{algorithm}: is the gnutls MAC identifier

@var{priority}: is the priority of the algorithm

@var{init}: A function which initializes the MAC

@var{setkey}: A function which sets the key of the MAC

@var{setnonce}: A function which sets the nonce for the mac (may be @code{NULL}  for common MAC algorithms)

@var{hash}: Perform the hash operation

@var{output}: Provide the output of the MAC

@var{deinit}: A function which deinitializes the MAC

@var{hash_fast}: Perform the MAC operation in one go

This function will register a MAC algorithm to be used by gnutls.
Any algorithm registered will override the included algorithms and
by convention kernel implemented algorithms have priority of 90
and CPU-assisted of 80.
The algorithm with the lowest priority will be used by gnutls.

@strong{Deprecated:} since 3.7.0 it is no longer possible to override cipher implementation

@strong{Returns:} @code{GNUTLS_E_SUCCESS}  on success, otherwise a negative error code.

@strong{Since:} 3.4.0
@end deftypefun

@subheading gnutls_decode_ber_digest_info
@anchor{gnutls_decode_ber_digest_info}
@deftypefun {int} {gnutls_decode_ber_digest_info} (const gnutls_datum_t * @var{info}, gnutls_digest_algorithm_t * @var{hash}, unsigned char * @var{digest}, unsigned int * @var{digest_size})
@var{info}: an RSA BER encoded DigestInfo structure

@var{hash}: will contain the hash algorithm of the structure

@var{digest}: will contain the hash output of the structure

@var{digest_size}: will contain the hash size of the structure; initially must hold the maximum size of  @code{digest} 

This function will parse an RSA PKCS@code{1}  1.5 DigestInfo structure
and report the hash algorithm used as well as the digest data.

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_decode_gost_rs_value
@anchor{gnutls_decode_gost_rs_value}
@deftypefun {int} {gnutls_decode_gost_rs_value} (const gnutls_datum_t * @var{sig_value}, gnutls_datum_t * @var{r}, gnutls_datum_t * @var{s})
@var{sig_value}: will holds a GOST signature according to RFC 4491 section 2.2.2

@var{r}: will contain the r value

@var{s}: will contain the s value

This function will decode the provided  @code{sig_value} , into  @code{r} and  @code{s} elements.
See RFC 4491 section 2.2.2 for the format of signature value.

The output values may be padded with a zero byte to prevent them
from being interpreted as negative values. The value
should be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_decode_rs_value
@anchor{gnutls_decode_rs_value}
@deftypefun {int} {gnutls_decode_rs_value} (const gnutls_datum_t * @var{sig_value}, gnutls_datum_t * @var{r}, gnutls_datum_t * @var{s})
@var{sig_value}: holds a Dss-Sig-Value DER or BER encoded structure

@var{r}: will contain the r value

@var{s}: will contain the s value

This function will decode the provided  @code{sig_value} , 
into  @code{r} and  @code{s} elements. The Dss-Sig-Value is used for DSA and ECDSA
signatures.

The output values may be padded with a zero byte to prevent them
from being interpreted as negative values. The value
should be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_encode_ber_digest_info
@anchor{gnutls_encode_ber_digest_info}
@deftypefun {int} {gnutls_encode_ber_digest_info} (gnutls_digest_algorithm_t @var{hash}, const gnutls_datum_t * @var{digest}, gnutls_datum_t * @var{output})
@var{hash}: the hash algorithm that was used to get the digest

@var{digest}: must contain the digest data

@var{output}: will contain the allocated DigestInfo BER encoded data

This function will encode the provided digest data, and its
algorithm into an RSA PKCS@code{1}  1.5 DigestInfo structure. 

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.5.0
@end deftypefun

@subheading gnutls_encode_gost_rs_value
@anchor{gnutls_encode_gost_rs_value}
@deftypefun {int} {gnutls_encode_gost_rs_value} (gnutls_datum_t * @var{sig_value}, const gnutls_datum_t * @var{r}, const gnutls_datum_t  * @var{s})
@var{sig_value}: will hold a GOST signature according to RFC 4491 section 2.2.2

@var{r}: must contain the r value

@var{s}: must contain the s value

This function will encode the provided r and s values, into binary
representation according to RFC 4491 section 2.2.2, used for GOST R
34.10-2001 (and thus also for GOST R 34.10-2012) signatures.

The output value should be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_encode_rs_value
@anchor{gnutls_encode_rs_value}
@deftypefun {int} {gnutls_encode_rs_value} (gnutls_datum_t * @var{sig_value}, const gnutls_datum_t * @var{r}, const gnutls_datum_t * @var{s})
@var{sig_value}: will hold a Dss-Sig-Value DER encoded structure

@var{r}: must contain the r value

@var{s}: must contain the s value

This function will encode the provided r and s values, 
into a Dss-Sig-Value structure, used for DSA and ECDSA
signatures.

The output value should be deallocated using @code{gnutls_free()} .

@strong{Returns:} On success, @code{GNUTLS_E_SUCCESS}  (0) is returned, otherwise
an error code is returned.

@strong{Since:} 3.6.0
@end deftypefun

@subheading gnutls_hash
@anchor{gnutls_hash}
@deftypefun {int} {gnutls_hash} (gnutls_hash_hd_t @var{handle}, const void * @var{ptext}, size_t @var{ptext_len})
@var{handle}: is a @code{gnutls_hash_hd_t}  type

@var{ptext}: the data to hash

@var{ptext_len}: the length of data to hash

This function will hash the given data using the algorithm
specified by the context.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hash_copy
@anchor{gnutls_hash_copy}
@deftypefun {gnutls_hash_hd_t} {gnutls_hash_copy} (gnutls_hash_hd_t @var{handle})
@var{handle}: is a @code{gnutls_hash_hd_t}  type

This function will create a copy of Message Digest context, containing all
its current state. Copying contexts for Message Digests registered using
@code{gnutls_crypto_register_digest()}  is not supported and will always result in
an error. In addition to that, some of the Message Digest implementations do
not support this operation. Applications should check the return value and
provide a proper fallback.

@strong{Returns:} new Message Digest context or NULL in case of an error.

@strong{Since:} 3.6.9
@end deftypefun

@subheading gnutls_hash_deinit
@anchor{gnutls_hash_deinit}
@deftypefun {void} {gnutls_hash_deinit} (gnutls_hash_hd_t @var{handle}, void * @var{digest})
@var{handle}: is a @code{gnutls_hash_hd_t}  type

@var{digest}: is the output value of the hash

This function will deinitialize all resources occupied by
the given hash context.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hash_fast
@anchor{gnutls_hash_fast}
@deftypefun {int} {gnutls_hash_fast} (gnutls_digest_algorithm_t @var{algorithm}, const void * @var{ptext}, size_t @var{ptext_len}, void * @var{digest})
@var{algorithm}: the hash algorithm to use

@var{ptext}: the data to hash

@var{ptext_len}: the length of data to hash

@var{digest}: is the output value of the hash

This convenience function will hash the given data and return output
on a single call.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hash_get_len
@anchor{gnutls_hash_get_len}
@deftypefun {unsigned} {gnutls_hash_get_len} (gnutls_digest_algorithm_t @var{algorithm})
@var{algorithm}: the hash algorithm to use

This function will return the length of the output data
of the given hash algorithm.

@strong{Returns:} The length or zero on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hash_init
@anchor{gnutls_hash_init}
@deftypefun {int} {gnutls_hash_init} (gnutls_hash_hd_t * @var{dig}, gnutls_digest_algorithm_t @var{algorithm})
@var{dig}: is a @code{gnutls_hash_hd_t}  type

@var{algorithm}: the hash algorithm to use

This function will initialize an context that can be used to
produce a Message Digest of data.  This will effectively use the
current crypto backend in use by gnutls or the cryptographic
accelerator in use.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hash_output
@anchor{gnutls_hash_output}
@deftypefun {void} {gnutls_hash_output} (gnutls_hash_hd_t @var{handle}, void * @var{digest})
@var{handle}: is a @code{gnutls_hash_hd_t}  type

@var{digest}: is the output value of the hash

This function will output the current hash value
and reset the state of the hash.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hkdf_expand
@anchor{gnutls_hkdf_expand}
@deftypefun {int} {gnutls_hkdf_expand} (gnutls_mac_algorithm_t @var{mac}, const gnutls_datum_t * @var{key}, const gnutls_datum_t * @var{info}, void * @var{output}, size_t @var{length})
@var{mac}: the mac algorithm used internally

@var{key}: the pseudorandom key created with HKDF-Extract

@var{info}: the optional informational data

@var{output}: the output value of the expand operation

@var{length}: the desired length of the output key

This function will derive a variable length keying material from
the pseudorandom key using the HKDF-Expand function as defined in
RFC 5869.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.13
@end deftypefun

@subheading gnutls_hkdf_extract
@anchor{gnutls_hkdf_extract}
@deftypefun {int} {gnutls_hkdf_extract} (gnutls_mac_algorithm_t @var{mac}, const gnutls_datum_t * @var{key}, const gnutls_datum_t * @var{salt}, void * @var{output})
@var{mac}: the mac algorithm used internally

@var{key}: the initial keying material

@var{salt}: the optional salt

@var{output}: the output value of the extract operation

This function will derive a fixed-size key using the HKDF-Extract
function as defined in RFC 5869.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.13
@end deftypefun

@subheading gnutls_hmac
@anchor{gnutls_hmac}
@deftypefun {int} {gnutls_hmac} (gnutls_hmac_hd_t @var{handle}, const void * @var{ptext}, size_t @var{ptext_len})
@var{handle}: is a @code{gnutls_hmac_hd_t}  type

@var{ptext}: the data to hash

@var{ptext_len}: the length of data to hash

This function will hash the given data using the algorithm
specified by the context.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_copy
@anchor{gnutls_hmac_copy}
@deftypefun {gnutls_hmac_hd_t} {gnutls_hmac_copy} (gnutls_hmac_hd_t @var{handle})
@var{handle}: is a @code{gnutls_hmac_hd_t}  type

This function will create a copy of MAC context, containing all its current
state. Copying contexts for MACs registered using
@code{gnutls_crypto_register_mac()}  is not supported and will always result in an
error. In addition to that, some of the MAC implementations do not support
this operation. Applications should check the return value and provide a
proper fallback.

@strong{Returns:} new MAC context or NULL in case of an error.

@strong{Since:} 3.6.9
@end deftypefun

@subheading gnutls_hmac_deinit
@anchor{gnutls_hmac_deinit}
@deftypefun {void} {gnutls_hmac_deinit} (gnutls_hmac_hd_t @var{handle}, void * @var{digest})
@var{handle}: is a @code{gnutls_hmac_hd_t}  type

@var{digest}: is the output value of the MAC

This function will deinitialize all resources occupied by
the given hmac context.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_fast
@anchor{gnutls_hmac_fast}
@deftypefun {int} {gnutls_hmac_fast} (gnutls_mac_algorithm_t @var{algorithm}, const void * @var{key}, size_t @var{keylen}, const void * @var{ptext}, size_t @var{ptext_len}, void * @var{digest})
@var{algorithm}: the hash algorithm to use

@var{key}: the key to use

@var{keylen}: the length of the key

@var{ptext}: the data to hash

@var{ptext_len}: the length of data to hash

@var{digest}: is the output value of the hash

This convenience function will hash the given data and return output
on a single call. Note, this call will not work for MAC algorithms
that require nonce (like UMAC or GMAC).

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_get_key_size
@anchor{gnutls_hmac_get_key_size}
@deftypefun {unsigned} {gnutls_hmac_get_key_size} (gnutls_mac_algorithm_t @var{algorithm})
@var{algorithm}: the mac algorithm to use

This function will return the size of the key to be used with this
algorithm. On the algorithms which may accept arbitrary key sizes,
the returned size is the MAC key size used in the TLS protocol.

@strong{Returns:} The key size or zero on error.

@strong{Since:} 3.6.12
@end deftypefun

@subheading gnutls_hmac_get_len
@anchor{gnutls_hmac_get_len}
@deftypefun {unsigned} {gnutls_hmac_get_len} (gnutls_mac_algorithm_t @var{algorithm})
@var{algorithm}: the hmac algorithm to use

This function will return the length of the output data
of the given hmac algorithm.

@strong{Returns:} The length or zero on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_init
@anchor{gnutls_hmac_init}
@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})
@var{dig}: is a @code{gnutls_hmac_hd_t}  type

@var{algorithm}: the HMAC algorithm to use

@var{key}: the key to be used for encryption

@var{keylen}: the length of the key

This function will initialize an context that can be used to
produce a Message Authentication Code (MAC) of data.  This will
effectively use the current crypto backend in use by gnutls or the
cryptographic accelerator in use.

Note that despite the name of this function, it can be used
for other MAC algorithms than HMAC.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_output
@anchor{gnutls_hmac_output}
@deftypefun {void} {gnutls_hmac_output} (gnutls_hmac_hd_t @var{handle}, void * @var{digest})
@var{handle}: is a @code{gnutls_hmac_hd_t}  type

@var{digest}: is the output value of the MAC

This function will output the current MAC value
and reset the state of the MAC.

@strong{Since:} 2.10.0
@end deftypefun

@subheading gnutls_hmac_set_nonce
@anchor{gnutls_hmac_set_nonce}
@deftypefun {void} {gnutls_hmac_set_nonce} (gnutls_hmac_hd_t @var{handle}, const void * @var{nonce}, size_t @var{nonce_len})
@var{handle}: is a @code{gnutls_hmac_hd_t}  type

@var{nonce}: the data to set as nonce

@var{nonce_len}: the length of data

This function will set the nonce in the MAC algorithm.

@strong{Since:} 3.2.0
@end deftypefun

@subheading gnutls_mac_get_nonce_size
@anchor{gnutls_mac_get_nonce_size}
@deftypefun {size_t} {gnutls_mac_get_nonce_size} (gnutls_mac_algorithm_t @var{algorithm})
@var{algorithm}: is an encryption algorithm

Returns the size of the nonce used by the MAC in TLS.

@strong{Returns:} length (in bytes) of the given MAC nonce size, or 0.

@strong{Since:} 3.2.0
@end deftypefun

@subheading gnutls_pbkdf2
@anchor{gnutls_pbkdf2}
@deftypefun {int} {gnutls_pbkdf2} (gnutls_mac_algorithm_t @var{mac}, const gnutls_datum_t * @var{key}, const gnutls_datum_t * @var{salt}, unsigned @var{iter_count}, void * @var{output}, size_t @var{length})
@var{mac}: the mac algorithm used internally

@var{key}: the initial keying material

@var{salt}: the salt

@var{iter_count}: the iteration count

@var{output}: the output value

@var{length}: the desired length of the output key

This function will derive a variable length keying material from
a password according to PKCS @code{5}  PBKDF2.

@strong{Returns:} Zero or a negative error code on error.

@strong{Since:} 3.6.13
@end deftypefun

@subheading gnutls_rnd
@anchor{gnutls_rnd}
@deftypefun {int} {gnutls_rnd} (gnutls_rnd_level_t @var{level}, void * @var{data}, size_t @var{len})
@var{level}: a security level

@var{data}: place to store random bytes

@var{len}: The requested size

This function will generate random data and store it to output
buffer. The value of  @code{level} should be one of @code{GNUTLS_RND_NONCE} ,
@code{GNUTLS_RND_RANDOM}  and @code{GNUTLS_RND_KEY} . See the manual and
@code{gnutls_rnd_level_t}  for detailed information.

This function is thread-safe and also fork-safe.

@strong{Returns:} Zero on success, or a negative error code on error.

@strong{Since:} 2.12.0
@end deftypefun

@subheading gnutls_rnd_refresh
@anchor{gnutls_rnd_refresh}
@deftypefun {void} {gnutls_rnd_refresh} ( @var{void})

This function refreshes the random generator state.
That is the current precise time, CPU usage, and
other values are input into its state.

On a slower rate input from /dev/urandom is mixed too.

@strong{Since:} 3.1.7
@end deftypefun