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