]>
Commit | Line | Data |
---|---|---|
615513ba RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
9c39fa1e | 5 | SSL_CIPHER_get_name, |
bbb4ceb8 PY |
6 | SSL_CIPHER_standard_name, |
7 | OPENSSL_cipher_name, | |
9c39fa1e MC |
8 | SSL_CIPHER_get_bits, |
9 | SSL_CIPHER_get_version, | |
10 | SSL_CIPHER_description, | |
11 | SSL_CIPHER_get_cipher_nid, | |
12 | SSL_CIPHER_get_digest_nid, | |
13 | SSL_CIPHER_get_handshake_digest, | |
14 | SSL_CIPHER_get_kx_nid, | |
15 | SSL_CIPHER_get_auth_nid, | |
22d1a340 PY |
16 | SSL_CIPHER_is_aead, |
17 | SSL_CIPHER_find, | |
50966bfa PY |
18 | SSL_CIPHER_get_id, |
19 | SSL_CIPHER_get_protocol_id | |
c952780c | 20 | - get SSL_CIPHER properties |
615513ba RL |
21 | |
22 | =head1 SYNOPSIS | |
23 | ||
24 | #include <openssl/ssl.h> | |
25 | ||
c3e64028 | 26 | const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher); |
bbb4ceb8 PY |
27 | const char *SSL_CIPHER_standard_name(const SSL_CIPHER *cipher); |
28 | const char *OPENSSL_cipher_name(const char *stdname); | |
c3e64028 NL |
29 | int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits); |
30 | char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher); | |
7689ed34 | 31 | char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size); |
98c9ce2f DSH |
32 | int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c); |
33 | int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c); | |
9c39fa1e | 34 | const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c); |
3ec13237 TS |
35 | int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c); |
36 | int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c); | |
37 | int SSL_CIPHER_is_aead(const SSL_CIPHER *c); | |
22d1a340 PY |
38 | const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr); |
39 | uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c); | |
50966bfa | 40 | uint32_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c); |
615513ba RL |
41 | |
42 | =head1 DESCRIPTION | |
43 | ||
44 | SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the | |
baf245ec | 45 | B<cipher> is NULL, it returns "(NONE)". |
615513ba | 46 | |
bbb4ceb8 PY |
47 | SSL_CIPHER_standard_name() returns a pointer to the standard RFC name of |
48 | B<cipher>. If the B<cipher> is NULL, it returns "(NONE)". If the B<cipher> | |
ee1ed1d3 DB |
49 | has no standard name, it returns B<NULL>. If B<cipher> was defined in both |
50 | SSLv3 and TLS, it returns the TLS name. | |
bbb4ceb8 PY |
51 | |
52 | OPENSSL_cipher_name() returns a pointer to the OpenSSL name of B<stdname>. | |
53 | If the B<stdname> is NULL, or B<stdname> has no corresponding OpenSSL name, | |
ee1ed1d3 DB |
54 | it returns "(NONE)". Where both exist, B<stdname> should be the TLS name rather |
55 | than the SSLv3 name. | |
bbb4ceb8 | 56 | |
baf245ec RS |
57 | SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. |
58 | If B<cipher> is NULL, 0 is returned. | |
615513ba | 59 | |
fc1d88f0 | 60 | SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol |
baf245ec | 61 | version that first defined the cipher. It returns "(NONE)" if B<cipher> is NULL. |
615513ba | 62 | |
98c9ce2f | 63 | SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>. |
c4de074e | 64 | If there is no cipher (e.g. for cipher suites with no encryption) then |
98c9ce2f DSH |
65 | B<NID_undef> is returned. |
66 | ||
67 | SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC | |
9c39fa1e MC |
68 | used by B<c> during record encryption/decryption. If there is no digest (e.g. |
69 | for AEAD cipher suites) then B<NID_undef> is returned. | |
70 | ||
71 | SSL_CIPHER_get_handshake_digest() returns an EVP_MD for the digest used during | |
72 | the SSL/TLS handshake when using the SSL_CIPHER B<c>. Note that this may be | |
73 | different to the digest used to calculate the MAC for encrypted records. | |
98c9ce2f | 74 | |
3ec13237 | 75 | SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method |
21d94d44 DSH |
76 | used by B<c>. If there is no key exchange, then B<NID_undef> is returned. |
77 | If any appropriate key exchange algorithm can be used (as in the case of TLS 1.3 | |
c4de074e | 78 | cipher suites) B<NID_kx_any> is returned. Examples (not comprehensive): |
3ec13237 TS |
79 | |
80 | NID_kx_rsa | |
81 | NID_kx_ecdhe | |
82 | NID_kx_dhe | |
83 | NID_kx_psk | |
84 | ||
85 | SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method | |
86 | used by B<c>. If there is no authentication, then B<NID_undef> is returned. | |
21d94d44 | 87 | If any appropriate authentication algorithm can be used (as in the case of |
c4de074e | 88 | TLS 1.3 cipher suites) B<NID_auth_any> is returned. Examples (not comprehensive): |
3ec13237 TS |
89 | |
90 | NID_auth_rsa | |
91 | NID_auth_ecdsa | |
92 | NID_auth_psk | |
93 | ||
94 | SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or | |
95 | ChaCha20/Poly1305), and 0 if it is not AEAD. | |
96 | ||
22d1a340 PY |
97 | SSL_CIPHER_find() returns a B<SSL_CIPHER> structure which has the cipher ID stored |
98 | in B<ptr>. The B<ptr> parameter is a two element array of B<char>, which stores the | |
99 | two-byte TLS cipher ID (as allocated by IANA) in network byte order. This parameter | |
a9c0d8be DB |
100 | is usually retrieved from a TLS packet by using functions like |
101 | L<SSL_client_hello_get0_ciphers(3)>. SSL_CIPHER_find() returns NULL if an | |
102 | error occurs or the indicated cipher is not found. | |
22d1a340 | 103 | |
50966bfa PY |
104 | SSL_CIPHER_get_id() returns the OpenSSL-specific ID of the given cipher B<c>. That ID is |
105 | not the same as the IANA-specific ID. | |
106 | ||
107 | SSL_CIPHER_get_protocol_id() returns the two-byte ID used in the TLS protocol of the given | |
108 | cipher B<c>. | |
22d1a340 | 109 | |
baf245ec RS |
110 | SSL_CIPHER_description() returns a textual description of the cipher used |
111 | into the buffer B<buf> of length B<len> provided. If B<buf> is provided, it | |
112 | must be at least 128 bytes, otherwise a buffer will be allocated using | |
113 | OPENSSL_malloc(). If the provided buffer is too small, or the allocation fails, | |
114 | B<NULL> is returned. | |
615513ba | 115 | |
baf245ec RS |
116 | The string returned by SSL_CIPHER_description() consists of several fields |
117 | separated by whitespace: | |
803e4e93 LJ |
118 | |
119 | =over 4 | |
120 | ||
121 | =item <ciphername> | |
122 | ||
123 | Textual representation of the cipher name. | |
124 | ||
125 | =item <protocol version> | |
126 | ||
baf245ec | 127 | Protocol version, such as B<TLSv1.2>, when the cipher was first defined. |
803e4e93 LJ |
128 | |
129 | =item Kx=<key exchange> | |
130 | ||
baf245ec | 131 | Key exchange method such as B<RSA>, B<ECDHE>, etc. |
803e4e93 LJ |
132 | |
133 | =item Au=<authentication> | |
134 | ||
baf245ec | 135 | Authentication method such as B<RSA>, B<None>, etc.. None is the |
803e4e93 LJ |
136 | representation of anonymous ciphers. |
137 | ||
52d160d8 | 138 | =item Enc=<symmetric encryption method> |
803e4e93 | 139 | |
baf245ec | 140 | Encryption method, with number of secret bits, such as B<AESGCM(128)>. |
803e4e93 LJ |
141 | |
142 | =item Mac=<message authentication code> | |
143 | ||
baf245ec | 144 | Message digest, such as B<SHA256>. |
803e4e93 LJ |
145 | |
146 | =back | |
147 | ||
b1e21f8f LJ |
148 | Some examples for the output of SSL_CIPHER_description(): |
149 | ||
baf245ec RS |
150 | ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD |
151 | RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 | |
615513ba | 152 | |
1f13ad31 PY |
153 | =head1 RETURN VALUES |
154 | ||
155 | SSL_CIPHER_get_name(), SSL_CIPHER_standard_name(), OPENSSL_cipher_name(), | |
156 | SSL_CIPHER_get_version() and SSL_CIPHER_description() return the corresponding | |
157 | value in a null-terminated string for a specific cipher or "(NONE)" | |
158 | if the cipher is not found. | |
159 | ||
160 | SSL_CIPHER_get_bits() returns a positive integer representing the number of | |
161 | secret bits or 0 if an error occurred. | |
162 | ||
163 | SSL_CIPHER_get_cipher_nid(), SSL_CIPHER_get_digest_nid(), | |
164 | SSL_CIPHER_get_kx_nid() and SSL_CIPHER_get_auth_nid() return the NID value or | |
165 | B<NID_undef> if an error occurred. | |
166 | ||
167 | SSL_CIPHER_get_handshake_digest() returns a valid B<EVP_MD> structure or NULL | |
168 | if an error occurred. | |
169 | ||
170 | SSL_CIPHER_is_aead() returns 1 if the cipher is AEAD or 0 otherwise. | |
171 | ||
172 | SSL_CIPHER_find() returns a valid B<SSL_CIPHER> structure or NULL if an error | |
173 | occurred. | |
174 | ||
175 | SSL_CIPHER_get_id() returns a 4-byte integer representing the OpenSSL-specific ID. | |
176 | ||
177 | SSL_CIPHER_get_protocol_id() returns a 2-byte integer representing the TLS | |
178 | protocol-specific ID. | |
179 | ||
baf245ec | 180 | =head1 HISTORY |
803e4e93 | 181 | |
baf245ec | 182 | SSL_CIPHER_get_version() was updated to always return the correct protocol |
9c39fa1e | 183 | string in OpenSSL 1.1.0. |
615513ba | 184 | |
baf245ec | 185 | SSL_CIPHER_description() was changed to return B<NULL> on error, |
9c39fa1e MC |
186 | rather than a fixed string, in OpenSSL 1.1.0. |
187 | ||
188 | SSL_CIPHER_get_handshake_digest() was added in OpenSSL 1.1.1. | |
615513ba | 189 | |
bbb4ceb8 PY |
190 | SSL_CIPHER_standard_name() was globally available in OpenSSL 1.1.1. Before |
191 | OpenSSL 1.1.1, tracing (B<enable-ssl-trace> argument to Configure) was | |
192 | required to enable this function. | |
193 | ||
194 | OPENSSL_cipher_name() was added in OpenSSL 1.1.1. | |
195 | ||
615513ba RL |
196 | =head1 SEE ALSO |
197 | ||
b97fdb57 | 198 | L<ssl(7)>, L<SSL_get_current_cipher(3)>, |
9b86974e | 199 | L<SSL_get_ciphers(3)>, L<ciphers(1)> |
615513ba | 200 | |
e2f92610 RS |
201 | =head1 COPYRIGHT |
202 | ||
61f805c1 | 203 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
204 | |
205 | Licensed under the OpenSSL license (the "License"). You may not use | |
206 | this file except in compliance with the License. You can obtain a copy | |
207 | in the file LICENSE in the source distribution or at | |
208 | L<https://www.openssl.org/source/license.html>. | |
209 | ||
210 | =cut |