OpenBSD manual page server

Manual Page Search Parameters
SSL_CIPHER_GET_NAME(3) Library Functions Manual SSL_CIPHER_GET_NAME(3)

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

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

() returns a pointer to the name of cipher.

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

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

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

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

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

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

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

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

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

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

() 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 () consists of several fields separated by whitespace:

⟨ciphername⟩
Textual representation of the cipher name.
⟨protocol version⟩
Protocol version: , , 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: , , , RSA, or TLSv1.3.
Au=⟨authentication⟩
Authentication method: , , RSA, TLSv1.3, or None. None is the representation of anonymous ciphers.
Enc=⟨symmetric encryption method⟩
Encryption method with number of secret bits: , , , , , , , , , , or None.
Mac=⟨message authentication code⟩
Message digest: , , , , , , , or .

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.

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

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

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.

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

July 16, 2024 OpenBSD-7.6