lib/libssl/man/SSL_CIPHER_get_name.3

   1 .\" $OpenBSD: SSL_CIPHER_get_name.3,v 1.8 2018/03/24 00:55:37 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: March 24 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 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
  94 returns a pointer to the name of
  95 .Fa cipher .
  96 .Pp
  97 .Fn SSL_CIPHER_get_bits
  98 returns the number of secret bits used for
  99 .Fa cipher .
 100 If
 101 .Fa alg_bits
 102 is not
 103 .Dv NULL ,
 104 the number of bits processed by the chosen algorithm is stored into it.
 105 .Pp
 106 .Fn SSL_CIPHER_get_version
 107 returns a string which indicates the SSL/TLS protocol version that first
 108 defined the cipher.
 109 This is currently
 110 .Qq TLSv1/SSLv3 .
 111 In some cases it should possibly return
 112 .Qq TLSv1.2
 113 but the function does not; use
 114 .Fn SSL_CIPHER_description
 115 instead.
 116 .Pp
 117 .Fn SSL_CIPHER_get_cipher_nid
 118 returns the cipher NID corresponding to the
 119 .Fa cipher .
 120 If there is no cipher (e.g. for cipher suites with no encryption), then
 121 .Dv NID_undef
 122 is returned.
 123 .Pp
 124 .Fn SSL_CIPHER_get_digest_nid
 125 returns the digest NID corresponding to the MAC used by the
 126 .Fa cipher
 127 during record encryption/decryption.
 128 If there is no digest (e.g. for AEAD cipher suites), then
 129 .Dv NID_undef
 130 is returned.
 131 .Pp
 132 .Fn SSL_CIPHER_get_kx_nid
 133 returns the key exchange NID corresponding to the method used by the
 134 .Fa cipher .
 135 If there is no key exchange, then
 136 .Dv NID_undef
 137 is returned.
 138 Examples of possible return values include
 139 .Dv NID_kx_rsa ,
 140 .Dv NID_kx_dhe ,
 141 and
 142 .Dv NID_kx_ecdhe .
 143 .Pp
 144 .Fn SSL_CIPHER_get_auth_nid
 145 returns the authentication NID corresponding to the method used by the
 146 .Fa cipher .
 147 If there is no authentication,
 148 .Dv NID_undef
 149 is returned.
 150 Examples of possible return values include
 151 .Dv NID_auth_rsa
 152 and
 153 .Dv NID_auth_ecdsa .
 154 .Pp
 155 .Fn SSL_CIPHER_is_aead
 156 returns 1 if the
 157 .Fa cipher
 158 is AEAD (e.g. GCM or ChaCha20/Poly1305), or 0 if it is not AEAD.
 159 .Pp
 160 .Fn SSL_CIPHER_get_id
 161 returns the ID of the given
 162 .Fa cipher ,
 163 which must not be
 164 .Dv NULL .
 165 The ID here is an OpenSSL-specific concept, which stores a prefix
 166 of 0x0300 in the higher two bytes and the IANA-specified chipher
 167 suite ID in the lower two bytes.
 168 For instance, TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", so
 169 .Fn SSL_CIPHER_get_id
 170 returns 0x03000001.
 171 .Pp
 172 .Fn SSL_CIPHER_description
 173 copies a textual description of
 174 .Fa cipher
 175 into the buffer
 176 .Fa buf ,
 177 which must be at least
 178 .Fa size
 179 bytes long.
 180 The
 181 .Fa cipher
 182 argument must not be a
 183 .Dv NULL
 184 pointer.
 185 If
 186 .Fa buf
 187 is
 188 .Dv NULL ,
 189 a buffer is allocated using
 190 .Xr asprintf 3 ;
 191 that buffer should be freed using the
 192 .Xr free 3
 193 function.
 194 If
 195 .Fa len
 196 is too small to hold the description, a pointer to the static string
 197 .Qq Buffer too small
 198 is returned.
 199 If memory allocation fails, which can happen even if a
 200 .Fa buf
 201 of sufficient size is provided, a pointer to the static string
 202 .Qq OPENSSL_malloc Error
 203 is returned and the content of
 204 .Fa buf
 205 remains unchanged.
 206 .Pp
 207 The string returned by
 208 .Fn SSL_CIPHER_description
 209 consists of several fields separated by whitespace:
 210 .Bl -tag -width Ds
 211 .It Aq Ar ciphername
 212 Textual representation of the cipher name.
 213 .It Aq Ar protocol version
 214 Protocol version:
 215 .Sy SSLv3
 216 or
 217 .Sy TLSv1.2 .
 218 The TLSv1.0 ciphers are flagged with SSLv3.
 219 No new ciphers were added by TLSv1.1.
 220 .It Kx= Ns Aq Ar key exchange
 221 Key exchange method:
 222 .Sy DH ,
 223 .Sy ECDH ,
 224 .Sy GOST ,
 225 or
 226 .Sy RSA .
 227 .It Au= Ns Aq Ar authentication
 228 Authentication method:
 229 .Sy DSS ,
 230 .Sy ECDSA ,
 231 .Sy GOST01 ,
 232 .Sy RSA ,
 233 or
 234 .Sy None .
 235 .Sy None
 236 is the representation of anonymous ciphers.
 237 .It Enc= Ns Aq Ar symmetric encryption method
 238 Encryption 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 ,
 253 or
 254 .Sy None .
 255 .It Mac= Ns Aq Ar message authentication code
 256 Message 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
 269 returns an internal pointer to a NUL-terminated string.
 270 .Fn SSL_CIPHER_get_version
 271 returns a pointer to a static NUL-terminated string.
 272 If
 273 .Fa cipher
 274 is a
 275 .Dv NULL
 276 pointer, both functions return a pointer to the static string
 277 .Qq Pq NONE .
 278 .Pp
 279 .Fn SSL_CIPHER_get_bits
 280 returns a positive integer representing the number of secret bits
 281 or 0 if
 282 .Fa cipher
 283 is a
 284 .Dv NULL
 285 pointer.
 286 .Pp
 287 .Fn SSL_CIPHER_get_cipher_nid ,
 288 .Fn SSL_CIPHER_get_digest_nid ,
 289 .Fn SSL_CIPHER_get_kx_nid ,
 290 and
 291 .Fn SSL_CIPHER_get_auth_nid
 292 return an NID constant or
 293 .Dv NID_undef
 294 if an error occurred.
 295 .Pp
 296 .Fn SSL_CIPHER_is_aead
 297 returns 1 if the
 298 .Fa cipher
 299 is AEAD or 0 otherwise.
 300 .Pp
 301 .Fn SSL_CIPHER_get_id
 302 returns a 32-bit unsigned integer.
 303 .Pp
 304 .Fn SSL_CIPHER_description
 305 returns
 306 .Fa buf
 307 or a newly allocated string on success or a pointer to a static
 308 string on error.
 309 .Sh EXAMPLES
 310 An example for the output of
 311 .Fn SSL_CIPHER_description :
 312 .Bd -literal
 313 ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
 314 .Ed
 315 .Pp
 316 A 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_get_name ,
 326 .Fn SSL_CIPHER_get_bits ,
 327 .Fn SSL_CIPHER_get_version ,
 328 and
 329 .Fn SSL_CIPHER_description
 330 appeared before SSLeay 0.8 and have been available since
 331 .Ox 2.4 .
 332 .Pp
 333 .Fn SSL_CIPHER_get_id
 334 first appeared in OpenSSL 1.0.1 and has been available since
 335 .Ox 5.3 .
 336 .Pp
 337 .Fn SSL_CIPHER_get_cipher_nid ,
 338 .Fn SSL_CIPHER_get_digest_nid ,
 339 .Fn SSL_CIPHER_get_kx_nid ,
 340 .Fn SSL_CIPHER_get_auth_nid ,
 341 and
 342 .Fn SSL_CIPHER_is_aead
 343 first appeared in OpenSSL 1.1.0 and have been available since
 344 .Ox 6.3 .
 345 .Sh BUGS
 346 If
 347 .Fn SSL_CIPHER_description
 348 cannot handle a built-in cipher,
 349 the according description of the cipher property is
 350 .Qq unknown .
 351 This case should not occur.