SSL_CIPHER_GET_NAME(3) | Library Functions Manual | SSL_CIPHER_GET_NAME(3)

# NAME

`SSL_CIPHER_get_name`, `SSL_CIPHER_get_bits`, `SSL_CIPHER_get_version`, `SSL_CIPHER_get_cipher_nid`, `SSL_CIPHER_get_digest_nid`, `SSL_CIPHER_get_handshake_digest`, `SSL_CIPHER_get_kx_nid`, `SSL_CIPHER_get_auth_nid`, `SSL_CIPHER_is_aead`, `SSL_CIPHER_find`, `SSL_CIPHER_get_id`, `SSL_CIPHER_description` — get SSL_CIPHER properties

# SYNOPSIS

library “libssl” libcrypto
`#include <openssl/ssl.h>`

const char *
`SSL_CIPHER_get_name`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_get_bits`(const SSL_CIPHER *cipher, int *alg_bits);

const char *
`SSL_CIPHER_get_version`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_get_cipher_nid`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_get_digest_nid`(const SSL_CIPHER *cipher);

const EVP_MD *
`SSL_CIPHER_get_handshake_digest`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_get_kx_nid`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_get_auth_nid`(const SSL_CIPHER *cipher);

int
`SSL_CIPHER_is_aead`(const SSL_CIPHER *cipher);

const SSL_CIPHER *
`SSL_CIPHER_find`(SSL *ssl, const unsigned char *ptr);

unsigned long
`SSL_CIPHER_get_id`(const SSL_CIPHER *cipher);

char *
`SSL_CIPHER_description`(const SSL_CIPHER *cipher, char *buf, int size);

# DESCRIPTION

`SSL_CIPHER_get_name`() returns a pointer to the name of cipher.

`SSL_CIPHER_get_bits`() returns the number of secret bits used for cipher. If alg_bits is not `NULL`, the number of bits processed by the chosen algorithm is stored into it.

`SSL_CIPHER_get_version`() returns a string which indicates the SSL/TLS protocol version that first defined the cipher. This is currently "TLSv1/SSLv3". In some cases it should possibly return "TLSv1.2" but the function does not; use `SSL_CIPHER_description`() instead.

`SSL_CIPHER_get_cipher_nid`() returns the cipher NID corresponding to the cipher. If there is no cipher (e.g. for cipher suites with no encryption), then `NID_undef` is returned.

`SSL_CIPHER_get_digest_nid`() returns the digest NID corresponding to the MAC used by the cipher during record encryption/decryption. If there is no digest (e.g. for AEAD cipher suites), then `NID_undef` is returned.

`SSL_CIPHER_get_handshake_digest`() returns the EVP_MD object representing the digest used during a TLS handshake with the cipher c, which may be different to the digest used in the message authentication code for encrypted records.

`SSL_CIPHER_get_kx_nid`() returns the key exchange NID corresponding to the method used by the cipher. If there is no key exchange, then `NID_undef` is returned. Examples of possible return values include `NID_kx_rsa`, `NID_kx_dhe`, and `NID_kx_ecdhe`.

`SSL_CIPHER_get_auth_nid`() returns the authentication NID corresponding to the method used by the cipher. If there is no authentication, `NID_undef` is returned. Examples of possible return values include `NID_auth_rsa` and `NID_auth_ecdsa`.

`SSL_CIPHER_is_aead`() returns 1 if the cipher is AEAD (e.g. GCM or ChaCha20/Poly1305), or 0 if it is not AEAD.

`SSL_CIPHER_find`() returns a pointer to a SSL_CIPHER structure which has the cipher ID specified in ptr. The ptr parameter is an array of length two which stores the two-byte TLS cipher ID (as allocated by IANA) in network byte order. SSL_CIPHER_find returns `NULL` if an error occurs or the indicated cipher is not found.

`SSL_CIPHER_get_id`() returns the ID of the given cipher, which must not be `NULL`. The ID here is an OpenSSL-specific concept, which stores a prefix of 0x0300 in the higher two bytes and the IANA-specified cipher suite ID in the lower two bytes. For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so `SSL_CIPHER_get_id`() returns 0x03000001.

`SSL_CIPHER_description`() copies a textual description of cipher into the buffer buf, which must be at least size bytes long. The cipher argument must not be a `NULL` pointer. If buf is `NULL`, a buffer is allocated using asprintf(3); that buffer should be freed using the free(3) function. If len is too small to hold the description, a pointer to the static string "Buffer too small" is returned. If memory allocation fails, which can happen even if a buf of sufficient size is provided, a pointer to the static string "OPENSSL_malloc Error" is returned and the content of buf remains unchanged.

The string returned by `SSL_CIPHER_description`() consists of several fields separated by whitespace:

⟨ciphername⟩
  Textual representation of the cipher name.
⟨protocol version⟩
  Protocol version: SSLv3, TLSv1.2, or TLSv1.3. The TLSv1.0 ciphers are flagged with SSLv3. No new ciphers were added by TLSv1.1.
Kx=⟨key exchange⟩
  Key exchange method: DH, ECDH, GOST, RSA, or TLSv1.3.
Au=⟨authentication⟩
  Authentication method: ECDSA, GOST01, RSA, TLSv1.3, or None. None is the representation of anonymous ciphers.
Enc=⟨symmetric encryption method⟩
  Encryption method with number of secret bits: 3DES(168), RC4(128), AES(128), AES(256), AESGCM(128), AESGCM(256), Camellia(128), Camellia(256), ChaCha20-Poly1305, GOST-28178-89-CNT, or None.
Mac=⟨message authentication code⟩
  Message digest: MD5, SHA1, SHA256, SHA384, AEAD, GOST94, GOST89IMIT, or STREEBOG256.

# RETURN VALUES

`SSL_CIPHER_get_name`() returns an internal pointer to a NUL-terminated string. `SSL_CIPHER_get_version`() returns a pointer to a static NUL-terminated string. If cipher is a `NULL` pointer, both functions return a pointer to the static string "(NONE)".

`SSL_CIPHER_get_bits`() returns a positive integer representing the number of secret bits or 0 if cipher is a `NULL` pointer.

`SSL_CIPHER_get_cipher_nid`(), `SSL_CIPHER_get_digest_nid`(), `SSL_CIPHER_get_kx_nid`(), and `SSL_CIPHER_get_auth_nid`() return an NID constant or `NID_undef` if an error occurred. `SSL_CIPHER_get_handshake_digest`() returns a valid EVP_MD object or `NULL` if an error occurred.

`SSL_CIPHER_is_aead`() returns 1 if the cipher is AEAD or 0 otherwise.

`SSL_CIPHER_find`() returns a pointer to a valid SSL_CIPHER structure or `NULL` if an error occurred.

`SSL_CIPHER_get_id`() returns a 32-bit unsigned integer.

`SSL_CIPHER_description`() returns buf or a newly allocated string on success or a pointer to a static string on error.

# EXAMPLES

An example for the output of `SSL_CIPHER_description`():

    ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD

A complete list can be retrieved by invoking the following command:

`$ openssl ciphers -v ALL:COMPLEMENTOFALL`

# SEE ALSO

openssl(1), ssl(3), SSL_get_ciphers(3), SSL_get_current_cipher(3)

# HISTORY

`SSL_CIPHER_description`() first appeared in SSLeay 0.8.0. `SSL_CIPHER_get_name`(), `SSL_CIPHER_get_bits`(), and `SSL_CIPHER_get_version`() first appeared in SSLeay 0.8.1. These functions have been available since OpenBSD 2.4.

`SSL_CIPHER_get_id`() first appeared in OpenSSL 1.0.1 and has been available since OpenBSD 5.3.

`SSL_CIPHER_get_cipher_nid`(), `SSL_CIPHER_get_digest_nid`(), `SSL_CIPHER_get_kx_nid`(), `SSL_CIPHER_get_auth_nid`(), and `SSL_CIPHER_is_aead`() first appeared in OpenSSL 1.1.0 and have been available since OpenBSD 6.3. `SSL_CIPHER_find`() first appeared in OpenSSL 1.1.0 and has been available since OpenBSD 7.0. `SSL_CIPHER_get_handshake_digest`() first appeared in OpenSSL 1.1.1 and has been available since OpenBSD 7.6.

# BUGS

If `SSL_CIPHER_description`() cannot handle a built-in cipher, the according description of the cipher property is "unknown". This case should not occur.

June 13, 2025 | Debian