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);
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
SEE ALSO
openssl(1), ssl(3), SSL_get_ciphers(3), SSL_get_current_cipher(3)
HISTORY
SSL_CIPHER_get_name
(),
SSL_CIPHER_get_bits
(),
SSL_CIPHER_get_version
(), and
SSL_CIPHER_description
() appeared before SSLeay 0.8
and 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.