lib/libssl/man/SSL_CIPHER_get_name.3

   1 .\"     $OpenBSD: SSL_CIPHER_get_name.3,v 1.2 2016/11/29 19:18:52 schwarze Exp $
   2 .\"     OpenSSL 45f55f6a Nov 30 15:35:22 2014 +0100
   3 .\"
   4 .\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>.
   5 .\" Copyright (c) 2000, 2001, 2005, 2009, 2013, 2014 The OpenSSL Project.
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: November 29 2016 $
  53 .Dt SSL_CIPHER_GET_NAME 3
  54 .Os
  55 .Sh NAME
  56 .Nm SSL_CIPHER_get_name ,
  57 .Nm SSL_CIPHER_get_bits ,
  58 .Nm SSL_CIPHER_get_version ,
  59 .Nm SSL_CIPHER_description
  60 .Nd get SSL_CIPHER properties
  61 .Sh SYNOPSIS
  62 .In openssl/ssl.h
  63 .Ft const char *
  64 .Fn SSL_CIPHER_get_name "const SSL_CIPHER *cipher"
  65 .Ft int
  66 .Fn SSL_CIPHER_get_bits "const SSL_CIPHER *cipher" "int *alg_bits"
  67 .Ft char *
  68 .Fn SSL_CIPHER_get_version "const SSL_CIPHER *cipher"
  69 .Ft char *
  70 .Fn SSL_CIPHER_description "const SSL_CIPHER *cipher" "char *buf" "int size"
  71 .Sh DESCRIPTION
  72 .Fn SSL_CIPHER_get_name
  73 returns a pointer to the name of
  74 .Fa cipher .
  75 If the
  76 .Fa cipher
  77 is
  78 .Dv NULL ,
  79 it returns
  80 .Qq (NONE) .
  81 .Pp
  82 .Fn SSL_CIPHER_get_bits
  83 returns the number of secret bits used for
  84 .Fa cipher .
  85 If
  86 .Fa alg_bits
  87 is not
  88 .Dv NULL ,
  89 it contains the number of bits processed by the
  90 chosen algorithm.
  91 If
  92 .Fa cipher
  93 is
  94 .Dv NULL ,
  95 0 is returned.
  96 .Pp
  97 .Fn SSL_CIPHER_get_version
  98 returns a string which indicates the SSL/TLS protocol version that first
  99 defined the cipher.
 100 This is currently
 101 .Qq TLSv1/SSLv3 .
 102 In some cases it should possibly return
 103 .Qq TLSv1.2
 104 but the function does not; use
 105 .Xr SSL_CIPHER_description 3
 106 instead.
 107 If
 108 .Fa cipher
 109 is
 110 .Dv NULL ,
 111 .Qq (NONE)
 112 is returned.
 113 .Pp
 114 .Fn SSL_CIPHER_description
 115 returns a textual description of the cipher used into the buffer
 116 .Fa buf
 117 of length
 118 .Fa len
 119 provided.
 120 If
 121 .Fa buf
 122 is
 123 .Dv NULL ,
 124 a buffer is allocated using
 125 .Xr asprintf 3 ;
 126 that buffer should be freed using the
 127 .Xr free 3
 128 function.
 129 If
 130 .Fa len
 131 is too small, or if
 132 .Fa buf
 133 is
 134 .Dv NULL
 135 and the allocation fails, a pointer to the string
 136 .Qq Buffer too small
 137 is returned.
 138 .Pp
 139 The string returned by
 140 .Fn SSL_CIPHER_description
 141 consists of several fields separated by whitespace:
 142 .Bl -tag -width Ds
 143 .It Aq Ar ciphername
 144 Textual representation of the cipher name.
 145 .It Aq Ar protocol version
 146 Protocol version:
 147 .Sy SSLv3
 148 or
 149 .Sy TLSv1.2 .
 150 The TLSv1.0 ciphers are flagged with SSLv3.
 151 No new ciphers were added by TLSv1.1.
 152 .It Kx= Ns Aq Ar key exchange
 153 Key exchange method:
 154 .Sy DH ,
 155 .Sy ECDH ,
 156 .Sy GOST ,
 157 or
 158 .Sy RSA .
 159 .It Au= Ns Aq Ar authentication
 160 Authentication method:
 161 .Sy DSS ,
 162 .Sy ECDSA ,
 163 .Sy GOST01 ,
 164 .Sy RSA ,
 165 or
 166 .Sy None .
 167 .Sy None
 168 is the representation of anonymous ciphers.
 169 .It Enc= Ns Aq Ar symmetric encryption method
 170 Encryption method with number of secret bits:
 171 .Sy DES(56) ,
 172 .Sy 3DES(168) ,
 173 .Sy RC4(64) ,
 174 .Sy RC4(128) ,
 175 .Sy IDEA(128) ,
 176 .Sy AES(128) ,
 177 .Sy AES(256) ,
 178 .Sy AESCGM(128) ,
 179 .Sy AESCGM(256) ,
 180 .Sy Camellia(128) ,
 181 .Sy Camellia(256) ,
 182 .Sy ChaCha20-Poly1305 ,
 183 .Sy ChaCha20-Poly1305-Old ,
 184 .Sy GOST-28178-89-CNT ,
 185 or
 186 .Sy None .
 187 .It Mac= Ns Aq Ar message authentication code
 188 Message digest:
 189 .Sy MD5 ,
 190 .Sy SHA1 ,
 191 .Sy SHA256 ,
 192 .Sy SHA384 ,
 193 .Sy AEAD ,
 194 .Sy GOST94 ,
 195 .Sy GOST89IMIT ,
 196 .Sy STREEBOG256 ,
 197 .Sy STREEBOG512 .
 198 .El
 199 .Sh EXAMPLES
 200 An example for the output of
 201 .Fn SSL_CIPHER_description :
 202 .Bd -literal
 203 ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH Au=RSA Enc=AESGCM(256) Mac=AEAD
 204 .Ed
 205 .Pp
 206 A complete list can be retrieved by invoking the following command:
 207 .Pp
 208 .Dl $ openssl ciphers -v ALL
 209 .Sh SEE ALSO
 210 .Xr openssl 1 ,
 211 .Xr ssl 3 ,
 212 .Xr SSL_get_ciphers 3 ,
 213 .Xr SSL_get_current_cipher 3
 214 .Sh BUGS
 215 If
 216 .Fn SSL_CIPHER_description
 217 is called with
 218 .Fa cipher
 219 being
 220 .Dv NULL ,
 221 the library crashes.
 222 .Pp
 223 If
 224 .Fn SSL_CIPHER_description
 225 cannot handle a built-in cipher,
 226 the according description of the cipher property is
 227 .Qq unknown .
 228 This case should not occur.