crypto: GnuTLS API Reference Manual

## crypto crypto |

## Functions

int | gnutls_cipher_add_auth ()
int | gnutls_cipher_decrypt ()
int | gnutls_cipher_decrypt2 ()
void | gnutls_cipher_deinit ()
int | gnutls_cipher_encrypt ()
int | gnutls_cipher_encrypt2 ()
int | gnutls_cipher_get_block_size ()
int | gnutls_cipher_init ()
void | gnutls_cipher_set_iv ()
int | gnutls_cipher_tag ()
int | gnutls_hash ()
void | gnutls_hash_deinit ()
int | gnutls_hash_fast ()
int | gnutls_hash_get_len ()
int | gnutls_hash_init ()
void | gnutls_hash_output ()
int | gnutls_hmac ()
void | gnutls_hmac_deinit ()
int | gnutls_hmac_fast ()
int | gnutls_hmac_get_len ()
int | gnutls_hmac_init ()
void | gnutls_hmac_output ()
int | gnutls_rnd ()

## Types and Values

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

## Description

## Functions

### 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 |

#### Returns

Zero or a negative error code on error.

Since: 3.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 |

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

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 |

#### Returns

Zero or a negative error code on error.

Since: 2.12.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_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 |

#### Returns

Zero or a negative error code on error.

Since: 2.10.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.

#### Parameters

handle | is a gnutls_cipher_hd_t type |

#### Returns

Zero or a negative error code on error.

Since: 2.12.0

### gnutls_cipher_get_block_size ()

    int
    gnutls_cipher_get_block_size (gnutls_cipher_algorithm_t algorithm);

#### Parameters

algorithm | is an encryption algorithm |

#### Returns

the block size of the encryption algorithm.

Since: 2.10.0

### 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_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_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 |

#### Returns

Zero or a negative error code on error.

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_fast ()

    int
    gnutls_hash_fast (gnutls_digest_algorithm_t algorithm,
                      const void *text,
                      size_t textlen,
                      void *digest);

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

#### Parameters

algorithm | the hash algorithm to use |
digest | is the output value of the hash |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_hash_get_len ()

    int
    gnutls_hash_get_len (gnutls_digest_algorithm_t algorithm);

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_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_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_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 |

#### Returns

Zero or a negative error code on error.

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_fast ()

    int
    gnutls_hmac_fast (gnutls_mac_algorithm_t algorithm,
                      const void *key,
                      size_t keylen,
                      const void *text,
                      size_t textlen,
                      void *digest);

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

#### Parameters

algorithm | the hash algorithm to use |
key | the key to use |
keylen | the length of the key |
digest | is the output value of the hash |

#### Returns

Zero or a negative error code on error.

Since: 2.10.0

### gnutls_hmac_get_len ()

    int
    gnutls_hmac_get_len (gnutls_mac_algorithm_t algorithm);

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_init ()

    int
    gnutls_hmac_init (gnutls_hmac_hd_t *dig,
                      gnutls_mac_algorithm_t algorithm,
                      const void *key,
                      size_t keylen);

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.

#### Parameters

dig | is a gnutls_hmac_hd_t type |
algorithm | the HMAC algorithm to use |
key | the key to be used for encryption |
keylen | the length of the key |

#### 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_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.

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

## Types and Values

### gnutls_cipher_hd_t

    typedef struct api_cipher_hd_st *gnutls_cipher_hd_t;

### 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. |
GNUTLS_RND_KEY | Fatal in many sessions if broken. |