crypto: GnuTLS API Reference Manual

## crypto crypto |

## Functions

int | gnutls_cipher_init ()
int | gnutls_cipher_encrypt ()
int | gnutls_cipher_decrypt ()
int | gnutls_cipher_decrypt2 ()
int | gnutls_cipher_encrypt2 ()
int | gnutls_cipher_encrypt3 ()
int | gnutls_cipher_decrypt3 ()
void | gnutls_cipher_set_iv ()
int | gnutls_cipher_tag ()
int | gnutls_cipher_add_auth ()
void | gnutls_cipher_deinit ()
unsigned | gnutls_cipher_get_block_size ()
int | gnutls_aead_cipher_set_key ()
int | gnutls_aead_cipher_decrypt ()
int | gnutls_aead_cipher_encrypt ()
int | gnutls_aead_cipher_encryptv ()
int | gnutls_aead_cipher_encryptv2 ()
int | gnutls_aead_cipher_decryptv2 ()
void | gnutls_aead_cipher_deinit ()
size_t | gnutls_mac_get_nonce_size ()
void | gnutls_hmac_set_nonce ()
int | gnutls_hmac ()
void | gnutls_hmac_output ()
void | gnutls_hmac_deinit ()
unsigned | gnutls_hmac_get_len ()
gnutls_hmac_hd_t | gnutls_hmac_copy ()
int | gnutls_hash_init ()
int | gnutls_hash ()
void | gnutls_hash_output ()
void | gnutls_hash_deinit ()
unsigned | gnutls_hash_get_len ()
gnutls_hash_hd_t | gnutls_hash_copy ()
int | gnutls_hkdf_extract ()
int | gnutls_hkdf_expand ()
int | gnutls_pbkdf2 ()
int | gnutls_rnd ()
void | gnutls_rnd_refresh ()
int | (*gnutls_cipher_init_func) ()
int | (*gnutls_cipher_setkey_func) ()
int | (*gnutls_cipher_setiv_func) ()
int | (*gnutls_cipher_getiv_func) ()
int | (*gnutls_cipher_encrypt_func) ()
int | (*gnutls_cipher_decrypt_func) ()
int | (*gnutls_cipher_auth_func) ()
void | (*gnutls_cipher_tag_func) ()
int | (*gnutls_cipher_aead_encrypt_func) ()
int | (*gnutls_cipher_aead_decrypt_func) ()
void | (*gnutls_cipher_deinit_func) ()
int | gnutls_crypto_register_cipher ()
int | gnutls_crypto_register_aead_cipher ()
int | (*gnutls_mac_init_func) ()
int | (*gnutls_mac_setkey_func) ()
int | (*gnutls_mac_setnonce_func) ()
int | (*gnutls_mac_hash_func) ()
int | (*gnutls_mac_output_func) ()
void | (*gnutls_mac_deinit_func) ()
int | (*gnutls_mac_fast_func) ()
void * | (*gnutls_mac_copy_func) ()
int | gnutls_crypto_register_mac ()
int | (*gnutls_digest_init_func) ()
int | (*gnutls_digest_hash_func) ()
int | (*gnutls_digest_output_func) ()
void | (*gnutls_digest_deinit_func) ()
int | (*gnutls_digest_fast_func) ()
void * | (*gnutls_digest_copy_func) ()
int | gnutls_crypto_register_digest ()
int | gnutls_encode_ber_digest_info ()
int | gnutls_decode_ber_digest_info ()
int | gnutls_decode_rs_value ()
int | gnutls_encode_rs_value ()
int | gnutls_encode_gost_rs_value ()
int | gnutls_decode_gost_rs_value ()

## Types and Values

typedef | gnutls_cipher_hd_t
enum | gnutls_cipher_flags_t
typedef | gnutls_hash_hd_t
typedef | gnutls_hmac_hd_t
enum | gnutls_rnd_level_t

## Description

## Functions

### gnutls_cipher_init ()

    int
    gnutls_cipher_init (gnutls_cipher_hd_t *handle,
                        gnutls_cipher_algorithm_t cipher,
                        const gnutls_datum_t *key,
                        const gnutls_datum_t *iv);

This function will initialize the `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.

#### Parameters

handle | is a gnutls_cipher_hd_t type |
cipher | the encryption algorithm to use |
key | the key to be used for encryption/decryption |
iv | the IV to use (if not applicable set NULL) |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_cipher_encrypt ()

    int
    gnutls_cipher_encrypt (const gnutls_cipher_hd_t handle,
                           void *text,
                           size_t textlen);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ptext | the data to encrypt |
ptext_len | the length of data to encrypt |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_cipher_decrypt ()

    int
    gnutls_cipher_decrypt (const gnutls_cipher_hd_t handle,
                           void *ciphertext,
                           size_t ciphertextlen);

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 `gnutls_cipher_tag()`.

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ctext | the data to decrypt |
ctext_len | the length of data to decrypt |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_cipher_decrypt2 ()

    int
    gnutls_cipher_decrypt2 (gnutls_cipher_hd_t handle,
                            const void *ciphertext,
                            size_t ciphertextlen,
                            void *text,
                            size_t textlen);

This function will decrypt the given data using the algorithm specified by the context. For block ciphers the `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 `gnutls_cipher_tag()`.

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ctext | the data to decrypt |
ctext_len | the length of data to decrypt |
ptext | the decrypted data |
ptext_len | the available length for decrypted data |

#### Returns

Zero or a negative error code on error.

Since: 2.12.0

### gnutls_cipher_encrypt2 ()

    int
    gnutls_cipher_encrypt2 (gnutls_cipher_hd_t handle,
                            const void *text,
                            size_t textlen,
                            void *ciphertext,
                            size_t ciphertextlen);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ptext | the data to encrypt |
ptext_len | the length of data to encrypt |
ctext | the encrypted data |
ctext_len | the available length for encrypted data |

#### Returns

Zero or a negative error code on error.

Since: 2.12.0

### gnutls_cipher_encrypt3 ()

    int
    gnutls_cipher_encrypt3 (gnutls_cipher_hd_t handle,
                            const void *ptext,
                            size_t ptext_len,
                            void *ctext,
                            size_t *ctext_len,
                            unsigned  flags);

This function will encrypt the given data using the algorithm specified by the context. For block ciphers, `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 `flags` . Currently, the only available padding scheme is `GNUTLS_CIPHER_PADDING_PKCS7`.

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ptext | the data to encrypt |
ptext_len | the length of data to encrypt |
ctext | the encrypted data |
ctext_len | the length of encrypted data (initially must hold the maximum available size) |
flags | flags for padding |

#### Returns

Zero or a negative error code on error.

Since: 3.7.7

### gnutls_cipher_decrypt3 ()

    int
    gnutls_cipher_decrypt3 (gnutls_cipher_hd_t handle,
                            const void *ctext,
                            size_t ctext_len,
                            void *ptext,
                            size_t *ptext_len,
                            unsigned  flags);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ctext | the data to decrypt |
ctext_len | the length of data to decrypt |
ptext | the decrypted data |
ptext_len | the available length for decrypted data |
flags | flags for padding |

#### Returns

Zero or a negative error code on error.

Since: 3.7.7

### gnutls_cipher_set_iv ()

    void
    gnutls_cipher_set_iv (gnutls_cipher_hd_t handle,
                          void *iv,
                          size_t ivlen);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
iv | the IV to set |
ivlen | the length of the IV |

Since: 3.0

### gnutls_cipher_tag ()

    int
    gnutls_cipher_tag (gnutls_cipher_hd_t handle,
                       void *tag,
                       size_t tag_size);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |
tag | will hold the tag |
tag_size | the length of the tag to return |

#### Returns

Zero or a negative error code on error.

Since: 3.0

### gnutls_cipher_add_auth ()

    int
    gnutls_cipher_add_auth (gnutls_cipher_hd_t handle,
                            const void *text,
                            size_t text_size);

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.

#### Parameters

handle | is a gnutls_cipher_hd_t type |
ptext | the data to be authenticated |
ptext_size | the length of the data |

#### Returns

Zero or a negative error code on error.

Since: 3.0

### gnutls_cipher_deinit ()

    void
    gnutls_cipher_deinit (gnutls_cipher_hd_t handle);

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

#### Parameters

handle | is a gnutls_cipher_hd_t type |

Since: 2.10.0

### gnutls_cipher_get_block_size ()

    unsigned
    gnutls_cipher_get_block_size ();

#### Parameters

algorithm | is an encryption algorithm |

#### Returns

the block size of the encryption algorithm.

Since: 2.10.0

### gnutls_aead_cipher_set_key ()

    int
    gnutls_aead_cipher_set_key (gnutls_aead_cipher_hd_t handle,
                                const gnutls_datum_t *key);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
key | The key to be used for encryption |

#### Returns

Zero or a negative error code on error.

Since: 3.7.5

### gnutls_aead_cipher_decrypt ()

    int
    gnutls_aead_cipher_decrypt (gnutls_aead_cipher_hd_t handle,
                                const void *nonce,
                                size_t nonce_len,
                                const void *auth,
                                size_t auth_len,
                                size_t tag_size,
                                const void *ctext,
                                size_t ctext_len,
                                void *ptext,
                                size_t *ptext_len);

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.

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
nonce | the nonce to set |
nonce_len | The length of the nonce |
auth | additional data to be authenticated |
auth_len | The length of the data |
tag_size | The size of the tag to use (use zero for the default) |
ctext | the data to decrypt (including the authentication tag) |
ctext_len | the length of data to decrypt (includes tag size) |
ptext | the decrypted data |
ptext_len | the length of decrypted data (initially must hold the maximum available size) |

#### Returns

Zero or a negative error code on verification failure or other error.

Since: 3.4.0

### gnutls_aead_cipher_encrypt ()

    int
    gnutls_aead_cipher_encrypt (gnutls_aead_cipher_hd_t handle,
                                const void *nonce,
                                size_t nonce_len,
                                const void *auth,
                                size_t auth_len,
                                size_t tag_size,
                                const void *ptext,
                                size_t ptext_len,
                                void *ctext,
                                size_t *ctext_len);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
nonce | the nonce to set |
nonce_len | The length of the nonce |
auth | additional data to be authenticated |
auth_len | The length of the data |
tag_size | The size of the tag to use (use zero for the default) |
ptext | the data to encrypt |
ptext_len | The length of data to encrypt |
ctext | the encrypted data including authentication tag |
ctext_len | the length of encrypted data (initially must hold the maximum available size, including space for tag) |

#### Returns

Zero or a negative error code on error.

Since: 3.4.0

### gnutls_aead_cipher_encryptv ()

    int
    gnutls_aead_cipher_encryptv (gnutls_aead_cipher_hd_t handle,
                                 const void *nonce,
                                 size_t nonce_len,
                                 const giovec_t *auth_iov,
                                 int auth_iovcnt,
                                 size_t tag_size,
                                 const giovec_t *iov,
                                 int iovcnt,
                                 void *ctext,
                                 size_t *ctext_len);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
nonce | the nonce to set |
nonce_len | The length of the nonce |
auth_iov | additional data to be authenticated |
auth_iovcnt | The number of buffers in `auth_iov` |
tag_size | The size of the tag to use (use zero for the default) |
iov | the data to be encrypted |
iovcnt | The number of buffers in `iov` |
ctext | the encrypted data including authentication tag |
ctext_len | the length of encrypted data (initially must hold the maximum available size, including space for tag) |

#### Returns

Zero or a negative error code on error.

Since: 3.6.3

### gnutls_aead_cipher_encryptv2 ()

    int
    gnutls_aead_cipher_encryptv2 (gnutls_aead_cipher_hd_t handle,
                                  const void *nonce,
                                  size_t nonce_len,
                                  const giovec_t *auth_iov,
                                  int auth_iovcnt,
                                  const giovec_t *iov,
                                  int iovcnt,
                                  void *tag,
                                  size_t *tag_size);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
nonce | the nonce to set |
nonce_len | The length of the nonce |
auth_iov | additional data to be authenticated |
auth_iovcnt | The number of buffers in `auth_iov` |
iov | the data to be encrypted |
iovcnt | The number of buffers in `iov` |
tag | The authentication tag |
tag_size | The size of the tag to use (use zero for the default) |

#### Returns

Zero or a negative error code on error.

Since: 3.6.10

### gnutls_aead_cipher_decryptv2 ()

    int
    gnutls_aead_cipher_decryptv2 (gnutls_aead_cipher_hd_t handle,
                                  const void *nonce,
                                  size_t nonce_len,
                                  const giovec_t *auth_iov,
                                  int auth_iovcnt,
                                  const giovec_t *iov,
                                  int iovcnt,
                                  void *tag,
                                  size_t tag_size);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |
nonce | the nonce to set |
nonce_len | The length of the nonce |
auth_iov | additional data to be authenticated |
auth_iovcnt | The number of buffers in `auth_iov` |
iov | the data to decrypt |
iovcnt | The number of buffers in `iov` |
tag | The authentication tag |
tag_size | The size of the tag to use (use zero for the default) |

#### Returns

Zero or a negative error code on error.

Since: 3.6.10

### gnutls_aead_cipher_deinit ()

    void
    gnutls_aead_cipher_deinit (gnutls_aead_cipher_hd_t handle);

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

#### Parameters

handle | is a gnutls_aead_cipher_hd_t type. |

Since: 3.4.0

### gnutls_mac_get_nonce_size ()

    size_t
    gnutls_mac_get_nonce_size ();

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

#### Parameters

algorithm | is an encryption algorithm |

#### Returns

length (in bytes) of the given MAC nonce size, or 0.

Since: 3.2.0

### gnutls_hmac_set_nonce ()

    void
    gnutls_hmac_set_nonce (gnutls_hmac_hd_t handle,
                           const void *nonce,
                           size_t nonce_len);

This function will set the nonce in the MAC algorithm.

#### Parameters

handle | is a gnutls_hmac_hd_t type |
nonce | the data to set as nonce |
nonce_len | the length of data |

Since: 3.2.0

### gnutls_hmac ()

    int
    gnutls_hmac (gnutls_hmac_hd_t handle,
                 const void *text,
                 size_t textlen);

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

#### Parameters

handle | is a gnutls_hmac_hd_t type |
ptext | the data to hash |
ptext_len | the length of data to hash |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_hmac_output ()

    void
    gnutls_hmac_output (gnutls_hmac_hd_t handle,
                        void *digest);

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

#### Parameters

handle | is a gnutls_hmac_hd_t type |
digest | is the output value of the MAC |

Since: 2.10.0

### gnutls_hmac_deinit ()

    void
    gnutls_hmac_deinit (gnutls_hmac_hd_t handle,
                        void *digest);

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

#### Parameters

handle | is a gnutls_hmac_hd_t type |
digest | is the output value of the MAC |

Since: 2.10.0

### gnutls_hmac_get_len ()

    unsigned
    gnutls_hmac_get_len ();

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

#### Parameters

algorithm | the hmac algorithm to use |

#### Returns

The length or zero on error.

Since: 2.10.0

### gnutls_hmac_copy ()

    gnutls_hmac_hd_t
    gnutls_hmac_copy (gnutls_hmac_hd_t handle);

This function will create a copy of MAC context, containing all its current state. Copying contexts for MACs registered using `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.

#### Parameters

handle | is a gnutls_hmac_hd_t type |

#### Returns

new MAC context or NULL in case of an error.

Since: 3.6.9

### gnutls_hash_init ()

    int
    gnutls_hash_init (gnutls_hash_hd_t *dig,
                      gnutls_digest_algorithm_t algorithm);

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.

#### Parameters

dig | is a gnutls_hash_hd_t type |
algorithm | the hash algorithm to use |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_hash ()

    int
    gnutls_hash (gnutls_hash_hd_t handle,
                 const void *text,
                 size_t textlen);

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

#### Parameters

handle | is a gnutls_hash_hd_t type |
ptext | the data to hash |
ptext_len | the length of data to hash |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_hash_output ()

    void
    gnutls_hash_output (gnutls_hash_hd_t handle,
                        void *digest);

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

#### Parameters

handle | is a gnutls_hash_hd_t type |
digest | is the output value of the hash |

Since: 2.10.0

### gnutls_hash_deinit ()

    void
    gnutls_hash_deinit (gnutls_hash_hd_t handle,
                        void *digest);

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

#### Parameters

handle | is a gnutls_hash_hd_t type |
digest | is the output value of the hash |

Since: 2.10.0

### gnutls_hash_get_len ()

    unsigned
    gnutls_hash_get_len ();

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

#### Parameters

algorithm | the hash algorithm to use |

#### Returns

The length or zero on error.

Since: 2.10.0

### gnutls_hash_copy ()

    gnutls_hash_hd_t
    gnutls_hash_copy (gnutls_hash_hd_t handle);

This function will create a copy of Message Digest context, containing all its current state. Copying contexts for Message Digests registered using `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.

#### Parameters

handle | is a gnutls_hash_hd_t type |

#### Returns

new Message Digest context or NULL in case of an error.

Since: 3.6.9

### gnutls_hkdf_extract ()

    int
    gnutls_hkdf_extract (gnutls_mac_algorithm_t mac,
                         const gnutls_datum_t *key,
                         const gnutls_datum_t *salt,
                         void *output);

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

#### Parameters

mac | the mac algorithm used internally |
key | the initial keying material |
salt | the optional salt |
output | the output value of the extract operation |

#### Returns

Zero or a negative error code on error.

Since: 3.6.13

### gnutls_hkdf_expand ()

    int
    gnutls_hkdf_expand (gnutls_mac_algorithm_t mac,
                        const gnutls_datum_t *key,
                        const gnutls_datum_t *info,
                        void *output,
                        size_t length);

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

#### Parameters

mac | the mac algorithm used internally |
key | the pseudorandom key created with HKDF-Extract |
info | the optional informational data |
output | the output value of the expand operation |
length | the desired length of the output key |

#### Returns

Zero or a negative error code on error.

Since: 3.6.13

### gnutls_pbkdf2 ()

    int
    gnutls_pbkdf2 (gnutls_mac_algorithm_t mac,
                   const gnutls_datum_t *key,
                   const gnutls_datum_t *salt,
                   unsigned  iter_count,
                   void *output,
                   size_t length);

This function will derive a variable length keying material from a password according to PKCS #5 PBKDF2.

#### Parameters

mac | the mac algorithm used internally |
key | the initial keying material |
salt | the salt |
iter_count | the iteration count |
output | the output value |
length | the desired length of the output key |

#### Returns

Zero or a negative error code on error.

Since: 3.6.13

### gnutls_rnd ()

    int
    gnutls_rnd (gnutls_rnd_level_t level,
                void *data,
                size_t len);

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

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

#### Parameters

level | a security level |
data | place to store random bytes |
len | The requested size |

#### Returns

Zero on success, or a negative error code on error.

Since: 2.12.0

### gnutls_rnd_refresh ()

    void
    gnutls_rnd_refresh (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.

Since: 3.1.7

### gnutls_cipher_init_func ()

    int
    (*gnutls_cipher_init_func) (gnutls_cipher_algorithm_t Param1,
                                void **ctx,
                                int enc);

### gnutls_cipher_setkey_func ()

    int
    (*gnutls_cipher_setkey_func) (void *ctx,
                                  const void *key,
                                  size_t keysize);

### gnutls_cipher_setiv_func ()

    int
    (*gnutls_cipher_setiv_func) (void *ctx,
                                 const void *iv,
                                 size_t ivsize);

### gnutls_cipher_getiv_func ()

    int
    (*gnutls_cipher_getiv_func) (void *ctx,
                                 void *iv,
                                 size_t ivsize);

### gnutls_cipher_encrypt_func ()

    int
    (*gnutls_cipher_encrypt_func) (void *ctx,
                                   const void *plain,
                                   size_t plainsize,
                                   void *encr,
                                   size_t encrsize);

### gnutls_cipher_decrypt_func ()

    int
    (*gnutls_cipher_decrypt_func) (void *ctx,
                                   const void *encr,
                                   size_t encrsize,
                                   void *plain,
                                   size_t plainsize);

### gnutls_cipher_auth_func ()

    int
    (*gnutls_cipher_auth_func) (void *ctx,
                                const void *data,
                                size_t datasize);

### gnutls_cipher_tag_func ()

    void
    (*gnutls_cipher_tag_func) (void *ctx,
                               void *tag,
                               size_t tagsize);

### gnutls_cipher_aead_encrypt_func ()

    int
    (*gnutls_cipher_aead_encrypt_func) (void *ctx,
                                        const void *nonce,
                                        size_t noncesize,
                                        const void *auth,
                                        size_t authsize,
                                        size_t tag_size,
                                        const void *plain,
                                        size_t plainsize,
                                        void *encr,
                                        size_t encrsize);

### gnutls_cipher_aead_decrypt_func ()

    int
    (*gnutls_cipher_aead_decrypt_func) (void *ctx,
                                        const void *nonce,
                                        size_t noncesize,
                                        const void *auth,
                                        size_t authsize,
                                        size_t tag_size,
                                        const void *encr,
                                        size_t encrsize,
                                        void *plain,
                                        size_t plainsize);

### gnutls_cipher_deinit_func ()

    void
    (*gnutls_cipher_deinit_func) (void *ctx);

### gnutls_crypto_register_cipher ()

    int
    gnutls_crypto_register_cipher (gnutls_cipher_algorithm_t algorithm,
                                   int priority,
                                   gnutls_cipher_init_func init,
                                   gnutls_cipher_setkey_func setkey,
                                   gnutls_cipher_setiv_func setiv,
                                   gnutls_cipher_encrypt_func encrypt,
                                   gnutls_cipher_decrypt_func decrypt,
                                   gnutls_cipher_deinit_func deinit);

`gnutls_crypto_register_cipher` is deprecated and should not be used in newly-written code.

since 3.7.0 it is no longer possible to override cipher implementation

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 `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.

#### Parameters

algorithm | is the gnutls algorithm identifier |
priority | is the priority of the algorithm |
init | A function which initializes the cipher |
setkey | A function which sets the key of the cipher |
setiv | A function which sets the nonce/IV of the cipher (non-AEAD) |
encrypt | A function which performs encryption (non-AEAD) |
decrypt | A function which performs decryption (non-AEAD) |
deinit | A function which deinitializes the cipher |

#### Returns

`GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since: 3.4.0

### gnutls_crypto_register_aead_cipher ()

    int
    gnutls_crypto_register_aead_cipher (gnutls_cipher_algorithm_t algorithm,
                                        int priority,
                                        gnutls_cipher_init_func init,
                                        gnutls_cipher_setkey_func setkey,
                                        gnutls_cipher_aead_encrypt_func aead_encrypt,
                                        gnutls_cipher_aead_decrypt_func aead_decrypt,
                                        gnutls_cipher_deinit_func deinit);

`gnutls_crypto_register_aead_cipher` is deprecated and should not be used in newly-written code.

since 3.7.0 it is no longer possible to override cipher implementation

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 `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.

#### Parameters

algorithm | is the gnutls AEAD cipher identifier |
priority | is the priority of the algorithm |
init | A function which initializes the cipher |
setkey | A function which sets the key of the cipher |
aead_encrypt | Perform the AEAD encryption |
aead_decrypt | Perform the AEAD decryption |
deinit | A function which deinitializes the cipher |

#### Returns

`GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since: 3.4.0

### gnutls_mac_init_func ()

    int
    (*gnutls_mac_init_func) (gnutls_mac_algorithm_t Param1,
                             void **ctx);

### gnutls_mac_setkey_func ()

    int
    (*gnutls_mac_setkey_func) (void *ctx,
                               const void *key,
                               size_t keysize);

### gnutls_mac_setnonce_func ()

    int
    (*gnutls_mac_setnonce_func) (void *ctx,
                                 const void *nonce,
                                 size_t noncesize);

### gnutls_mac_hash_func ()

    int
    (*gnutls_mac_hash_func) (void *ctx,
                             const void *text,
                             size_t textsize);

### gnutls_mac_output_func ()

    int
    (*gnutls_mac_output_func) (void *src_ctx,
                               void *digest,
                               size_t digestsize);

### gnutls_mac_deinit_func ()

    void
    (*gnutls_mac_deinit_func) (void *ctx);

### gnutls_mac_fast_func ()

    int
    (*gnutls_mac_fast_func) (gnutls_mac_algorithm_t Param1,
                             const void *nonce,
                             size_t nonce_size,
                             const void *key,
                             size_t keysize,
                             const void *text,
                             size_t textsize,
                             void *digest);

### gnutls_mac_copy_func ()

    void *
    (*gnutls_mac_copy_func) (const void *ctx);

### gnutls_crypto_register_mac ()

    int
    gnutls_crypto_register_mac (gnutls_mac_algorithm_t mac,
                                int priority,
                                gnutls_mac_init_func init,
                                gnutls_mac_setkey_func setkey,
                                gnutls_mac_setnonce_func setnonce,
                                gnutls_mac_hash_func hash,
                                gnutls_mac_output_func output,
                                gnutls_mac_deinit_func deinit,
                                gnutls_mac_fast_func hash_fast);

`gnutls_crypto_register_mac` is deprecated and should not be used in newly-written code.

since 3.7.0 it is no longer possible to override cipher implementation

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.

#### Parameters

algorithm | is the gnutls MAC identifier |
priority | is the priority of the algorithm |
init | A function which initializes the MAC |
setkey | A function which sets the key of the MAC |
setnonce | A function which sets the nonce for the mac (may be `NULL` for common MAC algorithms) |
hash | Perform the hash operation |
output | Provide the output of the MAC |
deinit | A function which deinitializes the MAC |
hash_fast | Perform the MAC operation in one go |

#### Returns

`GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since: 3.4.0

### gnutls_digest_init_func ()

    int
    (*gnutls_digest_init_func) (gnutls_digest_algorithm_t Param1,
                                void **ctx);

### gnutls_digest_hash_func ()

    int
    (*gnutls_digest_hash_func) (void *ctx,
                                const void *text,
                                size_t textsize);

### gnutls_digest_output_func ()

    int
    (*gnutls_digest_output_func) (void *src_ctx,
                                  void *digest,
                                  size_t digestsize);

### gnutls_digest_deinit_func ()

    void
    (*gnutls_digest_deinit_func) (void *ctx);

### gnutls_digest_fast_func ()

    int
    (*gnutls_digest_fast_func) (gnutls_digest_algorithm_t Param1,
                                const void *text,
                                size_t textsize,
                                void *digest);

### gnutls_digest_copy_func ()

    void *
    (*gnutls_digest_copy_func) (const void *ctx);

### gnutls_crypto_register_digest ()

    int
    gnutls_crypto_register_digest (gnutls_digest_algorithm_t digest,
                                   int priority,
                                   gnutls_digest_init_func init,
                                   gnutls_digest_hash_func hash,
                                   gnutls_digest_output_func output,
                                   gnutls_digest_deinit_func deinit,
                                   gnutls_digest_fast_func hash_fast);

`gnutls_crypto_register_digest` is deprecated and should not be used in newly-written code.

since 3.7.0 it is no longer possible to override cipher implementation

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.

#### Parameters

algorithm | is the gnutls digest identifier |
priority | is the priority of the algorithm |
init | A function which initializes the digest |
hash | Perform the hash operation |
output | Provide the output of the digest |
deinit | A function which deinitializes the digest |
hash_fast | Perform the digest operation in one go |

#### Returns

`GNUTLS_E_SUCCESS` on success, otherwise a negative error code.

Since: 3.4.0

### gnutls_encode_ber_digest_info ()

    int
    gnutls_encode_ber_digest_info (gnutls_digest_algorithm_t hash,
                                   const gnutls_datum_t *digest,
                                   gnutls_datum_t *output);

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

#### Parameters

info | an RSA BER encoded DigestInfo structure |
hash | the hash algorithm that was used to get the digest |
digest | must contain the digest data |
output | will contain the allocated DigestInfo BER encoded data |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.5.0

### gnutls_decode_ber_digest_info ()

    int
    gnutls_decode_ber_digest_info (const gnutls_datum_t *info,
                                   gnutls_digest_algorithm_t *hash,
                                   unsigned char *digest,
                                   unsigned int *digest_size);

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

#### Parameters

info | an RSA BER encoded DigestInfo structure |
hash | will contain the hash algorithm of the structure |
digest | will contain the hash output of the structure |
digest_size | will contain the hash size of the structure; initially must hold the maximum size of `digest` |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.5.0

### gnutls_decode_rs_value ()

    int
    gnutls_decode_rs_value (const gnutls_datum_t *sig_value,
                            gnutls_datum_t *r,
                            gnutls_datum_t *s);

This function will decode the provided `sig_value` , into `r` and `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 `gnutls_free()`.

#### Parameters

sig_value | holds a Dss-Sig-Value DER or BER encoded structure |
r | will contain the r value |
s | will contain the s value |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.6.0

### gnutls_encode_rs_value ()

    int
    gnutls_encode_rs_value (gnutls_datum_t *sig_value,
                            const gnutls_datum_t *r,
                            const gnutls_datum_t *s);

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 `gnutls_free()`.

#### Parameters

sig_value | will hold a Dss-Sig-Value DER encoded structure |
r | must contain the r value |
s | must contain the s value |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.6.0

### gnutls_encode_gost_rs_value ()

    int
    gnutls_encode_gost_rs_value (gnutls_datum_t *sig_value,
                                 const gnutls_datum_t *r,
                                 const gnutls_datum_t *s);

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 `gnutls_free()`.

#### Parameters

sig_value | will hold a GOST signature according to RFC 4491 section 2.2.2 |
r | must contain the r value |
s | must contain the s value |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.6.0

### gnutls_decode_gost_rs_value ()

    int
    gnutls_decode_gost_rs_value (const gnutls_datum_t *sig_value,
                                 gnutls_datum_t *r,
                                 gnutls_datum_t *s);

This function will decode the provided `sig_value` , into `r` and `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 `gnutls_free()`.

#### Parameters

sig_value | will holds a GOST signature according to RFC 4491 section 2.2.2 |
r | will contain the r value |
s | will contain the s value |

#### Returns

On success, `GNUTLS_E_SUCCESS` (0) is returned, otherwise an error code is returned.

Since: 3.6.0

## Types and Values

### gnutls_cipher_hd_t

    typedef struct api_cipher_hd_st *gnutls_cipher_hd_t;

### enum gnutls_cipher_flags_t

Enumeration of flags to control block cipher padding, used by `gnutls_cipher_encrypt3()` and `gnutls_cipher_decrypt3()`.

#### Members

GNUTLS_CIPHER_PADDING_PKCS7 | Flag to indicate PKCS#7 padding |

Since: 3.7.7

### gnutls_hash_hd_t

    typedef struct hash_hd_st *gnutls_hash_hd_t;

### gnutls_hmac_hd_t

    typedef struct hmac_hd_st *gnutls_hmac_hd_t;

### enum gnutls_rnd_level_t

Enumeration of random quality levels.

#### Members

GNUTLS_RND_NONCE | Non-predictable random number. Fatal in parts of session if broken, i.e., vulnerable to statistical analysis. |
GNUTLS_RND_RANDOM | Pseudo-random cryptographic random number. Fatal in session if broken. Example use: temporal keys. |
GNUTLS_RND_KEY | Fatal in many sessions if broken. Example use: Long-term keys. |