secure/lib/libcrypto/man/SSL_CIPHER_get_name.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CIPHER_GET_NAME 3"
 132 .TH SSL_CIPHER_GET_NAME 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_CIPHER_get_name, SSL_CIPHER_standard_name, OPENSSL_cipher_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description, SSL_CIPHER_get_cipher_nid, SSL_CIPHER_get_digest_nid, SSL_CIPHER_get_handshake_digest, SSL_CIPHER_get_kx_nid, SSL_CIPHER_get_auth_nid, SSL_CIPHER_is_aead, SSL_CIPHER_find, SSL_CIPHER_get_id, SSL_CIPHER_get_protocol_id \&\- get SSL_CIPHER properties
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
 145 \& const char *SSL_CIPHER_standard_name(const SSL_CIPHER *cipher);
 146 \& const char *OPENSSL_cipher_name(const char *stdname);
 147 \& int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
 148 \& char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
 149 \& char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
 150 \& int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
 151 \& int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
 152 \& const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c);
 153 \& int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
 154 \& int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
 155 \& int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
 156 \& const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr);
 157 \& uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c);
 158 \& uint32_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c);
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 \&\fISSL_CIPHER_get_name()\fR returns a pointer to the name of \fBcipher\fR. If the
 163 \&\fBcipher\fR is \s-1NULL,\s0 it returns \*(L"(\s-1NONE\s0)\*(R".
 164 .PP
 165 \&\fISSL_CIPHER_standard_name()\fR returns a pointer to the standard \s-1RFC\s0 name of
 166 \&\fBcipher\fR. If the \fBcipher\fR is \s-1NULL,\s0 it returns \*(L"(\s-1NONE\s0)\*(R". If the \fBcipher\fR
 167 has no standard name, it returns \fB\s-1NULL\s0\fR. If \fBcipher\fR was defined in both
 168 SSLv3 and \s-1TLS,\s0 it returns the \s-1TLS\s0 name.
 169 .PP
 170 \&\fIOPENSSL_cipher_name()\fR returns a pointer to the OpenSSL name of \fBstdname\fR.
 171 If the \fBstdname\fR is \s-1NULL,\s0 or \fBstdname\fR has no corresponding OpenSSL name,
 172 it returns \*(L"(\s-1NONE\s0)\*(R". Where both exist, \fBstdname\fR should be the \s-1TLS\s0 name rather
 173 than the SSLv3 name.
 174 .PP
 175 \&\fISSL_CIPHER_get_bits()\fR returns the number of secret bits used for \fBcipher\fR.
 176 If \fBcipher\fR is \s-1NULL, 0\s0 is returned.
 177 .PP
 178 \&\fISSL_CIPHER_get_version()\fR returns string which indicates the \s-1SSL/TLS\s0 protocol
 179 version that first defined the cipher.  It returns \*(L"(\s-1NONE\s0)\*(R" if \fBcipher\fR is \s-1NULL.\s0
 180 .PP
 181 \&\fISSL_CIPHER_get_cipher_nid()\fR returns the cipher \s-1NID\s0 corresponding to \fBc\fR.
 182 If there is no cipher (e.g. for cipher suites with no encryption) then
 183 \&\fBNID_undef\fR is returned.
 184 .PP
 185 \&\fISSL_CIPHER_get_digest_nid()\fR returns the digest \s-1NID\s0 corresponding to the \s-1MAC\s0
 186 used by \fBc\fR during record encryption/decryption. If there is no digest (e.g.
 187 for \s-1AEAD\s0 cipher suites) then \fBNID_undef\fR is returned.
 188 .PP
 189 \&\fISSL_CIPHER_get_handshake_digest()\fR returns an \s-1EVP_MD\s0 for the digest used during
 190 the \s-1SSL/TLS\s0 handshake when using the \s-1SSL_CIPHER\s0 \fBc\fR. Note that this may be
 191 different to the digest used to calculate the \s-1MAC\s0 for encrypted records.
 192 .PP
 193 \&\fISSL_CIPHER_get_kx_nid()\fR returns the key exchange \s-1NID\s0 corresponding to the method
 194 used by \fBc\fR. If there is no key exchange, then \fBNID_undef\fR is returned.
 195 If any appropriate key exchange algorithm can be used (as in the case of \s-1TLS 1.3\s0
 196 cipher suites) \fBNID_kx_any\fR is returned. Examples (not comprehensive):
 197 .PP
 198 .Vb 4
 199 \& NID_kx_rsa
 200 \& NID_kx_ecdhe
 201 \& NID_kx_dhe
 202 \& NID_kx_psk
 203 .Ve
 204 .PP
 205 \&\fISSL_CIPHER_get_auth_nid()\fR returns the authentication \s-1NID\s0 corresponding to the method
 206 used by \fBc\fR. If there is no authentication, then \fBNID_undef\fR is returned.
 207 If any appropriate authentication algorithm can be used (as in the case of
 208 \&\s-1TLS 1.3\s0 cipher suites) \fBNID_auth_any\fR is returned. Examples (not comprehensive):
 209 .PP
 210 .Vb 3
 211 \& NID_auth_rsa
 212 \& NID_auth_ecdsa
 213 \& NID_auth_psk
 214 .Ve
 215 .PP
 216 \&\fISSL_CIPHER_is_aead()\fR returns 1 if the cipher \fBc\fR is \s-1AEAD\s0 (e.g. \s-1GCM\s0 or
 217 ChaCha20/Poly1305), and 0 if it is not \s-1AEAD.\s0
 218 .PP
 219 \&\fISSL_CIPHER_find()\fR returns a \fB\s-1SSL_CIPHER\s0\fR structure which has the cipher \s-1ID\s0 stored
 220 in \fBptr\fR. The \fBptr\fR parameter is a two element array of \fBchar\fR, which stores the
 221 two-byte \s-1TLS\s0 cipher \s-1ID\s0 (as allocated by \s-1IANA\s0) in network byte order. This parameter
 222 is usually retrieved from a \s-1TLS\s0 packet by using functions like
 223 \&\fISSL_client_hello_get0_ciphers\fR\|(3).  \fISSL_CIPHER_find()\fR returns \s-1NULL\s0 if an
 224 error occurs or the indicated cipher is not found.
 225 .PP
 226 \&\fISSL_CIPHER_get_id()\fR returns the OpenSSL-specific \s-1ID\s0 of the given cipher \fBc\fR. That \s-1ID\s0 is
 227 not the same as the IANA-specific \s-1ID.\s0
 228 .PP
 229 \&\fISSL_CIPHER_get_protocol_id()\fR returns the two-byte \s-1ID\s0 used in the \s-1TLS\s0 protocol of the given
 230 cipher \fBc\fR.
 231 .PP
 232 \&\fISSL_CIPHER_description()\fR returns a textual description of the cipher used
 233 into the buffer \fBbuf\fR of length \fBlen\fR provided.  If \fBbuf\fR is provided, it
 234 must be at least 128 bytes, otherwise a buffer will be allocated using
 235 \&\fIOPENSSL_malloc()\fR.  If the provided buffer is too small, or the allocation fails,
 236 \&\fB\s-1NULL\s0\fR is returned.
 237 .PP
 238 The string returned by \fISSL_CIPHER_description()\fR consists of several fields
 239 separated by whitespace:
 240 .IP "<ciphername>" 4
 241 .IX Item "<ciphername>"
 242 Textual representation of the cipher name.
 243 .IP "<protocol version>" 4
 244 .IX Item "<protocol version>"
 245 Protocol version, such as \fBTLSv1.2\fR, when the cipher was first defined.
 246 .IP "Kx=<key exchange>" 4
 247 .IX Item "Kx=<key exchange>"
 248 Key exchange method such as \fB\s-1RSA\s0\fR, \fB\s-1ECDHE\s0\fR, etc.
 249 .IP "Au=<authentication>" 4
 250 .IX Item "Au=<authentication>"
 251 Authentication method such as \fB\s-1RSA\s0\fR, \fBNone\fR, etc.. None is the
 252 representation of anonymous ciphers.
 253 .IP "Enc=<symmetric encryption method>" 4
 254 .IX Item "Enc=<symmetric encryption method>"
 255 Encryption method, with number of secret bits, such as \fB\s-1AESGCM\s0(128)\fR.
 256 .IP "Mac=<message authentication code>" 4
 257 .IX Item "Mac=<message authentication code>"
 258 Message digest, such as \fB\s-1SHA256\s0\fR.
 259 .PP
 260 Some examples for the output of \fISSL_CIPHER_description()\fR:
 261 .PP
 262 .Vb 2
 263 \& ECDHE\-RSA\-AES256\-GCM\-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  Enc=AESGCM(256) Mac=AEAD
 264 \& RSA\-PSK\-AES256\-CBC\-SHA384 TLSv1.0 Kx=RSAPSK   Au=RSA  Enc=AES(256)  Mac=SHA384
 265 .Ve
 266 .SH "RETURN VALUES"
 267 .IX Header "RETURN VALUES"
 268 \&\fISSL_CIPHER_get_name()\fR, \fISSL_CIPHER_standard_name()\fR, \fIOPENSSL_cipher_name()\fR,
 269 \&\fISSL_CIPHER_get_version()\fR and \fISSL_CIPHER_description()\fR return the corresponding
 270 value in a null-terminated string for a specific cipher or \*(L"(\s-1NONE\s0)\*(R"
 271 if the cipher is not found.
 272 .PP
 273 \&\fISSL_CIPHER_get_bits()\fR returns a positive integer representing the number of
 274 secret bits or 0 if an error occurred.
 275 .PP
 276 \&\fISSL_CIPHER_get_cipher_nid()\fR, \fISSL_CIPHER_get_digest_nid()\fR,
 277 \&\fISSL_CIPHER_get_kx_nid()\fR and \fISSL_CIPHER_get_auth_nid()\fR return the \s-1NID\s0 value or
 278 \&\fBNID_undef\fR if an error occurred.
 279 .PP
 280 \&\fISSL_CIPHER_get_handshake_digest()\fR returns a valid \fB\s-1EVP_MD\s0\fR structure or \s-1NULL\s0
 281 if an error occurred.
 282 .PP
 283 \&\fISSL_CIPHER_is_aead()\fR returns 1 if the cipher is \s-1AEAD\s0 or 0 otherwise.
 284 .PP
 285 \&\fISSL_CIPHER_find()\fR returns a valid \fB\s-1SSL_CIPHER\s0\fR structure or \s-1NULL\s0 if an error
 286 occurred.
 287 .PP
 288 \&\fISSL_CIPHER_get_id()\fR returns a 4\-byte integer representing the OpenSSL-specific \s-1ID.\s0
 289 .PP
 290 \&\fISSL_CIPHER_get_protocol_id()\fR returns a 2\-byte integer representing the \s-1TLS\s0
 291 protocol-specific \s-1ID.\s0
 292 .SH "HISTORY"
 293 .IX Header "HISTORY"
 294 \&\fISSL_CIPHER_get_version()\fR was updated to always return the correct protocol
 295 string in OpenSSL 1.1.0.
 296 .PP
 297 \&\fISSL_CIPHER_description()\fR was changed to return \fB\s-1NULL\s0\fR on error,
 298 rather than a fixed string, in OpenSSL 1.1.0.
 299 .PP
 300 \&\fISSL_CIPHER_get_handshake_digest()\fR was added in OpenSSL 1.1.1.
 301 .PP
 302 \&\fISSL_CIPHER_standard_name()\fR was globally available in OpenSSL 1.1.1. Before
 303 OpenSSL 1.1.1, tracing (\fBenable-ssl-trace\fR argument to Configure) was
 304 required to enable this function.
 305 .PP
 306 \&\fIOPENSSL_cipher_name()\fR was added in OpenSSL 1.1.1.
 307 .SH "SEE ALSO"
 308 .IX Header "SEE ALSO"
 309 \&\fIssl\fR\|(7), \fISSL_get_current_cipher\fR\|(3),
 310 \&\fISSL_get_ciphers\fR\|(3), \fIciphers\fR\|(1)
 311 .SH "COPYRIGHT"
 312 .IX Header "COPYRIGHT"
 313 Copyright 2000\-2018 The OpenSSL Project Authors. All Rights Reserved.
 314 .PP
 315 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 316 this file except in compliance with the License.  You can obtain a copy
 317 in the file \s-1LICENSE\s0 in the source distribution or at
 318 <https://www.openssl.org/source/license.html>.