xref: /openbsd-src/lib/libssl/man/SSL_CIPHER_get_name.3 (revision bf08afbe4137b3e1a86218881f96ef9d07b8f07e) 
1.\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.17 2024/07/16 10:19:38 tb 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 16 2024 $
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_handshake_digest ,
65.Nm SSL_CIPHER_get_kx_nid ,
66.Nm SSL_CIPHER_get_auth_nid ,
67.Nm SSL_CIPHER_is_aead ,
68.Nm SSL_CIPHER_find ,
69.Nm SSL_CIPHER_get_id ,
70.Nm SSL_CIPHER_description
71.Nd get SSL_CIPHER properties
72.Sh SYNOPSIS
73.In openssl/ssl.h
74.Ft const char *
75.Fn SSL_CIPHER_get_name "const SSL_CIPHER *cipher"
76.Ft int
77.Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits"
78.Ft const char *
79.Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher"
80.Ft int
81.Fn SSL_CIPHER_get_cipher_nid "const SSL_CIPHER *cipher"
82.Ft int
83.Fn SSL_CIPHER_get_digest_nid "const SSL_CIPHER *cipher"
84.Ft "const EVP_MD *"
85.Fn SSL_CIPHER_get_handshake_digest "const SSL_CIPHER *cipher"
86.Ft int
87.Fn SSL_CIPHER_get_kx_nid "const SSL_CIPHER *cipher"
88.Ft int
89.Fn SSL_CIPHER_get_auth_nid "const SSL_CIPHER *cipher"
90.Ft int
91.Fn SSL_CIPHER_is_aead "const SSL_CIPHER *cipher"
92.Ft const SSL_CIPHER *
93.Fn SSL_CIPHER_find "SSL *ssl" "const unsigned char *ptr"
94.Ft unsigned long
95.Fn SSL_CIPHER_get_id "const SSL_CIPHER *cipher"
96.Ft char *
97.Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size"
98.Sh DESCRIPTION
99.Fn SSL_CIPHER_get_name
100returns a pointer to the name of
101.Fa cipher .
102.Pp
103.Fn SSL_CIPHER_get_bits
104returns the number of secret bits used for
105.Fa cipher .
106If
107.Fa alg_bits
108is not
109.Dv NULL ,
110the number of bits processed by the chosen algorithm is stored into it.
111.Pp
112.Fn SSL_CIPHER_get_version
113returns a string which indicates the SSL/TLS protocol version that first
114defined the cipher.
115This is currently
116.Qq TLSv1/SSLv3 .
117In some cases it should possibly return
118.Qq TLSv1.2
119but the function does not; use
120.Fn SSL_CIPHER_description
121instead.
122.Pp
123.Fn SSL_CIPHER_get_cipher_nid
124returns the cipher NID corresponding to the
125.Fa cipher .
126If there is no cipher (e.g. for cipher suites with no encryption), then
127.Dv NID_undef
128is returned.
129.Pp
130.Fn SSL_CIPHER_get_digest_nid
131returns the digest NID corresponding to the MAC used by the
132.Fa cipher
133during record encryption/decryption.
134If there is no digest (e.g. for AEAD cipher suites), then
135.Dv NID_undef
136is returned.
137.Pp
138.Fn SSL_CIPHER_get_handshake_digest
139returns the
140.Vt EVP_MD
141object representing the digest used during a TLS handshake with the cipher
142.Fa c ,
143which may be different to the digest used in the message authentication code
144for encrypted records.
145.Pp
146.Fn SSL_CIPHER_get_kx_nid
147returns the key exchange NID corresponding to the method used by the
148.Fa cipher .
149If there is no key exchange, then
150.Dv NID_undef
151is returned.
152Examples of possible return values include
153.Dv NID_kx_rsa ,
154.Dv NID_kx_dhe ,
155and
156.Dv NID_kx_ecdhe .
157.Pp
158.Fn SSL_CIPHER_get_auth_nid
159returns the authentication NID corresponding to the method used by the
160.Fa cipher .
161If there is no authentication,
162.Dv NID_undef
163is returned.
164Examples of possible return values include
165.Dv NID_auth_rsa
166and
167.Dv NID_auth_ecdsa .
168.Pp
169.Fn SSL_CIPHER_is_aead
170returns 1 if the
171.Fa cipher
172is AEAD (e.g. GCM or ChaCha20/Poly1305), or 0 if it is not AEAD.
173.Pp
174.Fn SSL_CIPHER_find
175returns a pointer to a
176.Vt SSL_CIPHER
177structure which has the cipher ID specified in
178.Fa ptr .
179The
180.Fa ptr
181parameter is an array of length two which stores the two-byte
182TLS cipher ID (as allocated by IANA) in network byte order.
183.Fa SSL_CIPHER_find
184returns
185.Dv NULL
186if an error occurs or the indicated cipher is not found.
187.Pp
188.Fn SSL_CIPHER_get_id
189returns the ID of the given
190.Fa cipher ,
191which must not be
192.Dv NULL .
193The ID here is an OpenSSL-specific concept, which stores a prefix
194of 0x0300 in the higher two bytes and the IANA-specified cipher
195suite ID in the lower two bytes.
196For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so
197.Fn SSL_CIPHER_get_id
198returns 0x03000001.
199.Pp
200.Fn SSL_CIPHER_description
201copies a textual description of
202.Fa cipher
203into the buffer
204.Fa buf ,
205which must be at least
206.Fa size
207bytes long.
208The
209.Fa cipher
210argument must not be a
211.Dv NULL
212pointer.
213If
214.Fa buf
215is
216.Dv NULL ,
217a buffer is allocated using
218.Xr asprintf 3 ;
219that buffer should be freed using the
220.Xr free 3
221function.
222If
223.Fa len
224is too small to hold the description, a pointer to the static string
225.Qq Buffer too small
226is returned.
227If memory allocation fails, which can happen even if a
228.Fa buf
229of sufficient size is provided, a pointer to the static string
230.Qq OPENSSL_malloc Error
231is returned and the content of
232.Fa buf
233remains unchanged.
234.Pp
235The string returned by
236.Fn SSL_CIPHER_description
237consists of several fields separated by whitespace:
238.Bl -tag -width Ds
239.It Aq Ar ciphername
240Textual representation of the cipher name.
241.It Aq Ar protocol version
242Protocol version:
243.Sy SSLv3 ,
244.Sy TLSv1.2 ,
245or
246.Sy TLSv1.3 .
247The TLSv1.0 ciphers are flagged with SSLv3.
248No new ciphers were added by TLSv1.1.
249.It Kx= Ns Aq Ar key exchange
250Key exchange method:
251.Sy DH ,
252.Sy ECDH ,
253.Sy GOST ,
254.Sy RSA ,
255or
256.Sy TLSv1.3 .
257.It Au= Ns Aq Ar authentication
258Authentication method:
259.Sy ECDSA ,
260.Sy GOST01 ,
261.Sy RSA ,
262.Sy TLSv1.3 ,
263or
264.Sy None .
265.Sy None
266is the representation of anonymous ciphers.
267.It Enc= Ns Aq Ar symmetric encryption method
268Encryption method with number of secret bits:
269.Sy 3DES(168) ,
270.Sy RC4(128) ,
271.Sy AES(128) ,
272.Sy AES(256) ,
273.Sy AESGCM(128) ,
274.Sy AESGCM(256) ,
275.Sy Camellia(128) ,
276.Sy Camellia(256) ,
277.Sy ChaCha20-Poly1305 ,
278.Sy GOST-28178-89-CNT ,
279or
280.Sy None .
281.It Mac= Ns Aq Ar message authentication code
282Message digest:
283.Sy MD5 ,
284.Sy SHA1 ,
285.Sy SHA256 ,
286.Sy SHA384 ,
287.Sy AEAD ,
288.Sy GOST94 ,
289.Sy GOST89IMIT ,
290or
291.Sy STREEBOG256 .
292.El
293.Sh RETURN VALUES
294.Fn SSL_CIPHER_get_name
295returns an internal pointer to a NUL-terminated string.
296.Fn SSL_CIPHER_get_version
297returns a pointer to a static NUL-terminated string.
298If
299.Fa cipher
300is a
301.Dv NULL
302pointer, both functions return a pointer to the static string
303.Qq Pq NONE .
304.Pp
305.Fn SSL_CIPHER_get_bits
306returns a positive integer representing the number of secret bits
307or 0 if
308.Fa cipher
309is a
310.Dv NULL
311pointer.
312.Pp
313.Fn SSL_CIPHER_get_cipher_nid ,
314.Fn SSL_CIPHER_get_digest_nid ,
315.Fn SSL_CIPHER_get_kx_nid ,
316and
317.Fn SSL_CIPHER_get_auth_nid
318return an NID constant or
319.Dv NID_undef
320if an error occurred.
321.Fn SSL_CIPHER_get_handshake_digest
322returns a valid
323.Vt EVP_MD
324object or
325.Dv NULL
326if an error occurred.
327.Pp
328.Fn SSL_CIPHER_is_aead
329returns 1 if the
330.Fa cipher
331is AEAD or 0 otherwise.
332.Pp
333.Fn SSL_CIPHER_find
334returns a pointer to a valid
335.Vt SSL_CIPHER
336structure or
337.Dv NULL
338if an error occurred.
339.Pp
340.Fn SSL_CIPHER_get_id
341returns a 32-bit unsigned integer.
342.Pp
343.Fn SSL_CIPHER_description
344returns
345.Fa buf
346or a newly allocated string on success or a pointer to a static
347string on error.
348.Sh EXAMPLES
349An example for the output of
350.Fn SSL_CIPHER_description :
351.Bd -literal
352ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
353.Ed
354.Pp
355A complete list can be retrieved by invoking the following command:
356.Pp
357.Dl $ openssl ciphers -v ALL:COMPLEMENTOFALL
358.Sh SEE ALSO
359.Xr openssl 1 ,
360.Xr ssl 3 ,
361.Xr SSL_get_ciphers 3 ,
362.Xr SSL_get_current_cipher 3
363.Sh HISTORY
364.Fn SSL_CIPHER_description
365first appeared in SSLeay 0.8.0.
366.Fn SSL_CIPHER_get_name ,
367.Fn SSL_CIPHER_get_bits ,
368and
369.Fn SSL_CIPHER_get_version
370first appeared in SSLeay 0.8.1.
371These functions have been available since
372.Ox 2.4 .
373.Pp
374.Fn SSL_CIPHER_get_id
375first appeared in OpenSSL 1.0.1 and has been available since
376.Ox 5.3 .
377.Pp
378.Fn SSL_CIPHER_get_cipher_nid ,
379.Fn SSL_CIPHER_get_digest_nid ,
380.Fn SSL_CIPHER_get_kx_nid ,
381.Fn SSL_CIPHER_get_auth_nid ,
382and
383.Fn SSL_CIPHER_is_aead
384first appeared in OpenSSL 1.1.0 and have been available since
385.Ox 6.3 .
386.Fn SSL_CIPHER_find
387first appeared in OpenSSL 1.1.0 and has been available since
388.Ox 7.0 .
389.Fn SSL_CIPHER_get_handshake_digest
390first appeared in OpenSSL 1.1.1 and has been available since
391.Ox 7.6 .
392.Sh BUGS
393If
394.Fn SSL_CIPHER_description
395cannot handle a built-in cipher,
396the according description of the cipher property is
397.Qq unknown .
398This case should not occur.
399