]>
Commit | Line | Data |
---|---|---|
615513ba RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
803e4e93 | 5 | SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties |
615513ba RL |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
c3e64028 NL |
11 | const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); |
12 | int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); | |
13 | char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); | |
7689ed34 | 14 | char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); |
98c9ce2f DSH |
15 | int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c); |
16 | int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c); | |
615513ba RL |
17 | |
18 | =head1 DESCRIPTION | |
19 | ||
20 | SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the | |
baf245ec | 21 | B<cipher> is NULL, it returns "(NONE)". |
615513ba | 22 | |
baf245ec RS |
23 | SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. |
24 | If B<cipher> is NULL, 0 is returned. | |
615513ba | 25 | |
fc1d88f0 | 26 | SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol |
baf245ec | 27 | version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL. |
615513ba | 28 | |
98c9ce2f DSH |
29 | SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>. |
30 | If there is no cipher (e.g. for ciphersuites with no encryption) then | |
31 | B<NID_undef> is returned. | |
32 | ||
33 | SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC | |
34 | used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then | |
35 | B<NID_undef> is returned. | |
36 | ||
baf245ec RS |
37 | SSL_CIPHER_description() returns a textual description of the cipher used |
38 | into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it | |
39 | must be at least 128 bytes, otherwise a buffer will be allocated using | |
40 | OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails, | |
41 | B<NULL> is returned. | |
615513ba | 42 | |
baf245ec RS |
43 | The string returned by SSL_CIPHER_description() consists of several fields |
44 | separated by whitespace: | |
803e4e93 LJ |
45 | |
46 | =over 4 | |
47 | ||
48 | =item <ciphername> | |
49 | ||
50 | Textual representation of the cipher name. | |
51 | ||
52 | =item <protocol version> | |
53 | ||
baf245ec | 54 | Protocol version, such as B<TLSv1.2>, when the cipher was first defined. |
803e4e93 LJ |
55 | |
56 | =item Kx=<key exchange> | |
57 | ||
baf245ec | 58 | Key exchange method such as B<RSA>, B<ECDHE>, etc. |
803e4e93 LJ |
59 | |
60 | =item Au=<authentication> | |
61 | ||
baf245ec | 62 | Authentication method such as B<RSA>, B<None>, etc.. None is the |
803e4e93 LJ |
63 | representation of anonymous ciphers. |
64 | ||
52d160d8 | 65 | =item Enc=<symmetric encryption method> |
803e4e93 | 66 | |
baf245ec | 67 | Encryption method, with number of secret bits, such as B<AESGCM(128)>. |
803e4e93 LJ |
68 | |
69 | =item Mac=<message authentication code> | |
70 | ||
baf245ec | 71 | Message digest, such as B<SHA256>. |
803e4e93 LJ |
72 | |
73 | =back | |
74 | ||
b1e21f8f LJ |
75 | Some examples for the output of SSL_CIPHER_description(): |
76 | ||
baf245ec RS |
77 | ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD |
78 | RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 | |
615513ba | 79 | |
baf245ec | 80 | =head1 HISTORY |
803e4e93 | 81 | |
baf245ec RS |
82 | SSL_CIPHER_get_version() was updated to always return the correct protocol |
83 | string in OpenSSL 1.1. | |
615513ba | 84 | |
baf245ec RS |
85 | SSL_CIPHER_description() was changed to return B<NULL> on error, |
86 | rather than a fixed string, in OpenSSL 1.1 | |
615513ba RL |
87 | |
88 | =head1 SEE ALSO | |
89 | ||
9b86974e RS |
90 | L<ssl(3)>, L<SSL_get_current_cipher(3)>, |
91 | L<SSL_get_ciphers(3)>, L<ciphers(1)> | |
615513ba RL |
92 | |
93 | =cut |