]>
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 | ||
69539990 MC |
127 | The minimum protocol version that the ciphersuite supports, such as B<TLSv1.2>. |
128 | Note that this is not always the same as the protocol version in which the | |
129 | ciphersuite was first defined because some ciphersuites are backwards compatible | |
130 | with earlier protocol versions. | |
803e4e93 LJ |
131 | |
132 | =item Kx=<key exchange> | |
133 | ||
baf245ec | 134 | Key exchange method such as B<RSA>, B<ECDHE>, etc. |
803e4e93 LJ |
135 | |
136 | =item Au=<authentication> | |
137 | ||
baf245ec | 138 | Authentication method such as B<RSA>, B<None>, etc.. None is the |
803e4e93 LJ |
139 | representation of anonymous ciphers. |
140 | ||
52d160d8 | 141 | =item Enc=<symmetric encryption method> |
803e4e93 | 142 | |
baf245ec | 143 | Encryption method, with number of secret bits, such as B<AESGCM(128)>. |
803e4e93 LJ |
144 | |
145 | =item Mac=<message authentication code> | |
146 | ||
baf245ec | 147 | Message digest, such as B<SHA256>. |
803e4e93 LJ |
148 | |
149 | =back | |
150 | ||
b1e21f8f LJ |
151 | Some examples for the output of SSL_CIPHER_description(): |
152 | ||
baf245ec RS |
153 | ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD |
154 | RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK Au=RSA Enc=AES(256) Mac=SHA384 | |
615513ba | 155 | |
1f13ad31 PY |
156 | =head1 RETURN VALUES |
157 | ||
158 | SSL_CIPHER_get_name(), SSL_CIPHER_standard_name(), OPENSSL_cipher_name(), | |
159 | SSL_CIPHER_get_version() and SSL_CIPHER_description() return the corresponding | |
160 | value in a null-terminated string for a specific cipher or "(NONE)" | |
161 | if the cipher is not found. | |
162 | ||
163 | SSL_CIPHER_get_bits() returns a positive integer representing the number of | |
164 | secret bits or 0 if an error occurred. | |
165 | ||
166 | SSL_CIPHER_get_cipher_nid(), SSL_CIPHER_get_digest_nid(), | |
167 | SSL_CIPHER_get_kx_nid() and SSL_CIPHER_get_auth_nid() return the NID value or | |
168 | B<NID_undef> if an error occurred. | |
169 | ||
170 | SSL_CIPHER_get_handshake_digest() returns a valid B<EVP_MD> structure or NULL | |
171 | if an error occurred. | |
172 | ||
173 | SSL_CIPHER_is_aead() returns 1 if the cipher is AEAD or 0 otherwise. | |
174 | ||
175 | SSL_CIPHER_find() returns a valid B<SSL_CIPHER> structure or NULL if an error | |
176 | occurred. | |
177 | ||
178 | SSL_CIPHER_get_id() returns a 4-byte integer representing the OpenSSL-specific ID. | |
179 | ||
180 | SSL_CIPHER_get_protocol_id() returns a 2-byte integer representing the TLS | |
181 | protocol-specific ID. | |
182 | ||
b5c4bbbe JL |
183 | =head1 SEE ALSO |
184 | ||
185 | L<ssl(7)>, L<SSL_get_current_cipher(3)>, | |
1903a9b7 | 186 | L<SSL_get_ciphers(3)>, L<openssl-ciphers(1)> |
b5c4bbbe | 187 | |
baf245ec | 188 | =head1 HISTORY |
803e4e93 | 189 | |
fc5ecadd DMSP |
190 | The SSL_CIPHER_get_version() function was updated to always return the |
191 | correct protocol string in OpenSSL 1.1.0. | |
615513ba | 192 | |
fc5ecadd | 193 | The SSL_CIPHER_description() function was changed to return B<NULL> on error, |
9c39fa1e MC |
194 | rather than a fixed string, in OpenSSL 1.1.0. |
195 | ||
fc5ecadd | 196 | The SSL_CIPHER_get_handshake_digest() function was added in OpenSSL 1.1.1. |
615513ba | 197 | |
fc5ecadd DMSP |
198 | The SSL_CIPHER_standard_name() function was globally available in OpenSSL 1.1.1. |
199 | Before OpenSSL 1.1.1, tracing (B<enable-ssl-trace> argument to Configure) was | |
bbb4ceb8 PY |
200 | required to enable this function. |
201 | ||
fc5ecadd | 202 | The OPENSSL_cipher_name() function was added in OpenSSL 1.1.1. |
bbb4ceb8 | 203 | |
e2f92610 RS |
204 | =head1 COPYRIGHT |
205 | ||
b5c4bbbe | 206 | Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 207 | |
4746f25a | 208 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
209 | this file except in compliance with the License. You can obtain a copy |
210 | in the file LICENSE in the source distribution or at | |
211 | L<https://www.openssl.org/source/license.html>. | |
212 | ||
213 | =cut |