SSL_CIPHER_get_name

SSL_CIPHER_GET_NAME(3)    BSD 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_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, 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), AESCGM(128), AESCGM(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_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: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.

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.

BSD                              April 14, 2020                              BSD