1.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.14 2022/07/17 08:51:07 jsg Exp $
2.\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
4.\"
5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>,
6.\" Dr. Stephen Henson <steve@openssl.org>, Todd Short <tshort@akamai.com>,
7.\" and Paul Yang <yang.yang@baishancloud.com>.
8.\" Copyright (c) 2000, 2005, 2009, 2013, 2014, 2015, 2016, 2017
9.\" The OpenSSL Project.  All rights reserved.
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\"
15.\" 1. Redistributions of source code must retain the above copyright
16.\"    notice, this list of conditions and the following disclaimer.
17.\"
18.\" 2. Redistributions in binary form must reproduce the above copyright
19.\"    notice, this list of conditions and the following disclaimer in
20.\"    the documentation and/or other materials provided with the
21.\"    distribution.
22.\"
23.\" 3. All advertising materials mentioning features or use of this
24.\"    software must display the following acknowledgment:
25.\"    "This product includes software developed by the OpenSSL Project
26.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
27.\"
28.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
29.\"    endorse or promote products derived from this software without
30.\"    prior written permission. For written permission, please contact
31.\"    openssl-core@openssl.org.
32.\"
33.\" 5. Products derived from this software may not be called "OpenSSL"
34.\"    nor may "OpenSSL" appear in their names without prior written
35.\"    permission of the OpenSSL Project.
36.\"
37.\" 6. Redistributions of any form whatsoever must retain the following
38.\"    acknowledgment:
39.\"    "This product includes software developed by the OpenSSL Project
40.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
41.\"
42.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
43.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
45.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
46.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
47.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
48.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
49.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
51.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
53.\" OF THE POSSIBILITY OF SUCH DAMAGE.
54.\"
55.Dd $Mdocdate: July 17 2022 $
56.Dt SSL_CIPHER_GET_NAME 3
57.Os
58.Sh NAME
59.Nm SSL_CIPHER_get_name ,
60.Nm SSL_CIPHER_get_bits ,
61.Nm SSL_CIPHER_get_version ,
62.Nm SSL_CIPHER_get_cipher_nid ,
63.Nm SSL_CIPHER_get_digest_nid ,
64.Nm SSL_CIPHER_get_kx_nid ,
65.Nm SSL_CIPHER_get_auth_nid ,
66.Nm SSL_CIPHER_is_aead ,
67.Nm SSL_CIPHER_find ,
68.Nm SSL_CIPHER_get_id ,
69.Nm SSL_CIPHER_description
70.Nd get SSL_CIPHER properties
71.Sh SYNOPSIS
72.In openssl/ssl.h
73.Ft const char *
74.Fn SSL_CIPHER_get_name "const SSL_CIPHER *cipher"
75.Ft int
76.Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits"
77.Ft const char *
78.Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher"
79.Ft int
80.Fn SSL_CIPHER_get_cipher_nid "const SSL_CIPHER *cipher"
81.Ft int
82.Fn SSL_CIPHER_get_digest_nid "const SSL_CIPHER *cipher"
83.Ft int
84.Fn SSL_CIPHER_get_kx_nid "const SSL_CIPHER *cipher"
85.Ft int
86.Fn SSL_CIPHER_get_auth_nid "const SSL_CIPHER *cipher"
87.Ft int
88.Fn SSL_CIPHER_is_aead "const SSL_CIPHER *cipher"
89.Ft const SSL_CIPHER *
90.Fn SSL_CIPHER_find "SSL *ssl" "const unsigned char *ptr"
91.Ft unsigned long
92.Fn SSL_CIPHER_get_id "const SSL_CIPHER *cipher"
93.Ft char *
94.Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size"
95.Sh DESCRIPTION
96.Fn SSL_CIPHER_get_name
97returns a pointer to the name of
98.Fa cipher .
99.Pp
100.Fn SSL_CIPHER_get_bits
101returns the number of secret bits used for
102.Fa cipher .
103If
104.Fa alg_bits
105is not
106.Dv NULL ,
107the number of bits processed by the chosen algorithm is stored into it.
108.Pp
109.Fn SSL_CIPHER_get_version
110returns a string which indicates the SSL/TLS protocol version that first
111defined the cipher.
112This is currently
113.Qq TLSv1/SSLv3 .
114In some cases it should possibly return
115.Qq TLSv1.2
116but the function does not; use
117.Fn SSL_CIPHER_description
118instead.
119.Pp
120.Fn SSL_CIPHER_get_cipher_nid
121returns the cipher NID corresponding to the
122.Fa cipher .
123If there is no cipher (e.g. for cipher suites with no encryption), then
124.Dv NID_undef
125is returned.
126.Pp
127.Fn SSL_CIPHER_get_digest_nid
128returns the digest NID corresponding to the MAC used by the
129.Fa cipher
130during record encryption/decryption.
131If there is no digest (e.g. for AEAD cipher suites), then
132.Dv NID_undef
133is returned.
134.Pp
135.Fn SSL_CIPHER_get_kx_nid
136returns the key exchange NID corresponding to the method used by the
137.Fa cipher .
138If there is no key exchange, then
139.Dv NID_undef
140is returned.
141Examples of possible return values include
142.Dv NID_kx_rsa ,
143.Dv NID_kx_dhe ,
144and
145.Dv NID_kx_ecdhe .
146.Pp
147.Fn SSL_CIPHER_get_auth_nid
148returns the authentication NID corresponding to the method used by the
149.Fa cipher .
150If there is no authentication,
151.Dv NID_undef
152is returned.
153Examples of possible return values include
154.Dv NID_auth_rsa
155and
156.Dv NID_auth_ecdsa .
157.Pp
158.Fn SSL_CIPHER_is_aead
159returns 1 if the
160.Fa cipher
161is AEAD (e.g. GCM or ChaCha20/Poly1305), or 0 if it is not AEAD.
162.Pp
163.Fn SSL_CIPHER_find
164returns a pointer to a
165.Vt SSL_CIPHER
166structure which has the cipher ID specified in
167.Fa ptr .
168The
169.Fa ptr
170parameter is an array of length two which stores the two-byte
171TLS cipher ID (as allocated by IANA) in network byte order.
172.Fa SSL_CIPHER_find
173returns
174.Dv NULL
175if an error occurs or the indicated cipher is not found.
176.Pp
177.Fn SSL_CIPHER_get_id
178returns the ID of the given
179.Fa cipher ,
180which must not be
181.Dv NULL .
182The ID here is an OpenSSL-specific concept, which stores a prefix
183of 0x0300 in the higher two bytes and the IANA-specified cipher
184suite ID in the lower two bytes.
185For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so
186.Fn SSL_CIPHER_get_id
187returns 0x03000001.
188.Pp
189.Fn SSL_CIPHER_description
190copies a textual description of
191.Fa cipher
192into the buffer
193.Fa buf ,
194which must be at least
195.Fa size
196bytes long.
197The
198.Fa cipher
199argument must not be a
200.Dv NULL
201pointer.
202If
203.Fa buf
204is
205.Dv NULL ,
206a buffer is allocated using
207.Xr asprintf 3 ;
208that buffer should be freed using the
209.Xr free 3
210function.
211If
212.Fa len
213is too small to hold the description, a pointer to the static string
214.Qq Buffer too small
215is returned.
216If memory allocation fails, which can happen even if a
217.Fa buf
218of sufficient size is provided, a pointer to the static string
219.Qq OPENSSL_malloc Error
220is returned and the content of
221.Fa buf
222remains unchanged.
223.Pp
224The string returned by
225.Fn SSL_CIPHER_description
226consists of several fields separated by whitespace:
227.Bl -tag -width Ds
228.It Aq Ar ciphername
229Textual representation of the cipher name.
230.It Aq Ar protocol version
231Protocol version:
232.Sy SSLv3 ,
233.Sy TLSv1.2 ,
234or
235.Sy TLSv1.3 .
236The TLSv1.0 ciphers are flagged with SSLv3.
237No new ciphers were added by TLSv1.1.
238.It Kx= Ns Aq Ar key exchange
239Key exchange method:
240.Sy DH ,
241.Sy ECDH ,
242.Sy GOST ,
243.Sy RSA ,
244or
245.Sy TLSv1.3 .
246.It Au= Ns Aq Ar authentication
247Authentication method:
248.Sy ECDSA ,
249.Sy GOST01 ,
250.Sy RSA ,
251.Sy TLSv1.3 ,
252or
253.Sy None .
254.Sy None
255is the representation of anonymous ciphers.
256.It Enc= Ns Aq Ar symmetric encryption method
257Encryption method with number of secret bits:
258.Sy 3DES(168) ,
259.Sy RC4(128) ,
260.Sy AES(128) ,
261.Sy AES(256) ,
262.Sy AESGCM(128) ,
263.Sy AESGCM(256) ,
264.Sy Camellia(128) ,
265.Sy Camellia(256) ,
266.Sy ChaCha20-Poly1305 ,
267.Sy GOST-28178-89-CNT ,
268or
269.Sy None .
270.It Mac= Ns Aq Ar message authentication code
271Message digest:
272.Sy MD5 ,
273.Sy SHA1 ,
274.Sy SHA256 ,
275.Sy SHA384 ,
276.Sy AEAD ,
277.Sy GOST94 ,
278.Sy GOST89IMIT ,
279or
280.Sy STREEBOG256 .
281.El
282.Sh RETURN VALUES
283.Fn SSL_CIPHER_get_name
284returns an internal pointer to a NUL-terminated string.
285.Fn SSL_CIPHER_get_version
286returns a pointer to a static NUL-terminated string.
287If
288.Fa cipher
289is a
290.Dv NULL
291pointer, both functions return a pointer to the static string
292.Qq Pq NONE .
293.Pp
294.Fn SSL_CIPHER_get_bits
295returns a positive integer representing the number of secret bits
296or 0 if
297.Fa cipher
298is a
299.Dv NULL
300pointer.
301.Pp
302.Fn SSL_CIPHER_get_cipher_nid ,
303.Fn SSL_CIPHER_get_digest_nid ,
304.Fn SSL_CIPHER_get_kx_nid ,
305and
306.Fn SSL_CIPHER_get_auth_nid
307return an NID constant or
308.Dv NID_undef
309if an error occurred.
310.Pp
311.Fn SSL_CIPHER_is_aead
312returns 1 if the
313.Fa cipher
314is AEAD or 0 otherwise.
315.Pp
316.Fn SSL_CIPHER_find
317returns a pointer to a valid
318.Vt SSL_CIPHER
319structure or
320.Dv NULL
321if an error occurred.
322.Pp
323.Fn SSL_CIPHER_get_id
324returns a 32-bit unsigned integer.
325.Pp
326.Fn SSL_CIPHER_description
327returns
328.Fa buf
329or a newly allocated string on success or a pointer to a static
330string on error.
331.Sh EXAMPLES
332An example for the output of
333.Fn SSL_CIPHER_description :
334.Bd -literal
335ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
336.Ed
337.Pp
338A complete list can be retrieved by invoking the following command:
339.Pp
340.Dl $ openssl ciphers -v ALL:COMPLEMENTOFALL
341.Sh SEE ALSO
342.Xr openssl 1 ,
343.Xr ssl 3 ,
344.Xr SSL_get_ciphers 3 ,
345.Xr SSL_get_current_cipher 3
346.Sh HISTORY
347.Fn SSL_CIPHER_description
348first appeared in SSLeay 0.8.0.
349.Fn SSL_CIPHER_get_name ,
350.Fn SSL_CIPHER_get_bits ,
351and
352.Fn SSL_CIPHER_get_version
353first appeared in SSLeay 0.8.1.
354These functions have been available since
355.Ox 2.4 .
356.Pp
357.Fn SSL_CIPHER_get_id
358first appeared in OpenSSL 1.0.1 and has been available since
359.Ox 5.3 .
360.Pp
361.Fn SSL_CIPHER_get_cipher_nid ,
362.Fn SSL_CIPHER_get_digest_nid ,
363.Fn SSL_CIPHER_get_kx_nid ,
364.Fn SSL_CIPHER_get_auth_nid ,
365and
366.Fn SSL_CIPHER_is_aead
367first appeared in OpenSSL 1.1.0 and have been available since
368.Ox 6.3 .
369.Fn SSL_CIPHER_find
370first appeared in OpenSSL 1.1.0 and has been available since
371.Ox 7.0 .
372.Sh BUGS
373If
374.Fn SSL_CIPHER_description
375cannot handle a built-in cipher,
376the according description of the cipher property is
377.Qq unknown .
378This case should not occur.
379