SSL_CIPHER_get_name(3) - OpenBSD manual pages

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_kx_nid, SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead, SSL_CIPHER_get_id, SSL_CIPHER_description — get SSL_CIPHER properties

SYNOPSIS

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

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

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_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_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 chipher 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 or TLSv1.2. 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, or RSA.
Au=⟨authentication⟩: Authentication method: DSS, ECDSA, GOST01, RSA, or None. None is the representation of anonymous ciphers.
Enc=⟨symmetric encryption method⟩: Encryption method with number of secret bits: DES(56), 3DES(168), RC4(64), RC4(128), IDEA(128), AES(128), AES(256), AESCGM(128), AESCGM(256), Camellia(128), Camellia(256), ChaCha20-Poly1305, ChaCha20-Poly1305-Old, GOST-28178-89-CNT, or None.
Mac=⟨message authentication code⟩: Message digest: MD5, SHA1, SHA256, SHA384, AEAD, GOST94, GOST89IMIT, STREEBOG256, STREEBOG512.

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_is_aead() returns 1 if the cipher is AEAD or 0 otherwise.

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

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.

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.

OpenBSD manual page server