secure/lib/libcrypto/man/man3/SSL_CIPHER_get_name.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CIPHER_GET_NAME 3"
 136 .TH SSL_CIPHER_GET_NAME 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
 149 \& const char *SSL_CIPHER_standard_name(const SSL_CIPHER *cipher);
 150 \& const char *OPENSSL_cipher_name(const char *stdname);
 151 \& int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
 152 \& char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
 153 \& char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
 154 \& int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
 155 \& int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
 156 \& const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c);
 157 \& int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
 158 \& int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
 159 \& int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
 160 \& const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr);
 161 \& uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c);
 162 \& uint32_t SSL_CIPHER_get_protocol_id(const SSL_CIPHER *c);
 163 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 \&\fBSSL_CIPHER_get_name()\fR returns a pointer to the name of \fBcipher\fR. If the
 167 \&\fBcipher\fR is \s-1NULL,\s0 it returns \*(L"(\s-1NONE\s0)\*(R".
 168 .PP
 169 \&\fBSSL_CIPHER_standard_name()\fR returns a pointer to the standard \s-1RFC\s0 name of
 170 \&\fBcipher\fR. If the \fBcipher\fR is \s-1NULL,\s0 it returns \*(L"(\s-1NONE\s0)\*(R". If the \fBcipher\fR
 171 has no standard name, it returns \fB\s-1NULL\s0\fR. If \fBcipher\fR was defined in both
 172 SSLv3 and \s-1TLS,\s0 it returns the \s-1TLS\s0 name.
 173 .PP
 174 \&\fBOPENSSL_cipher_name()\fR returns a pointer to the OpenSSL name of \fBstdname\fR.
 175 If the \fBstdname\fR is \s-1NULL,\s0 or \fBstdname\fR has no corresponding OpenSSL name,
 176 it returns \*(L"(\s-1NONE\s0)\*(R". Where both exist, \fBstdname\fR should be the \s-1TLS\s0 name rather
 177 than the SSLv3 name.
 178 .PP
 179 \&\fBSSL_CIPHER_get_bits()\fR returns the number of secret bits used for \fBcipher\fR.
 180 If \fBcipher\fR is \s-1NULL, 0\s0 is returned.
 181 .PP
 182 \&\fBSSL_CIPHER_get_version()\fR returns string which indicates the \s-1SSL/TLS\s0 protocol
 183 version that first defined the cipher.  It returns \*(L"(\s-1NONE\s0)\*(R" if \fBcipher\fR is \s-1NULL.\s0
 184 .PP
 185 \&\fBSSL_CIPHER_get_cipher_nid()\fR returns the cipher \s-1NID\s0 corresponding to \fBc\fR.
 186 If there is no cipher (e.g. for cipher suites with no encryption) then
 187 \&\fBNID_undef\fR is returned.
 188 .PP
 189 \&\fBSSL_CIPHER_get_digest_nid()\fR returns the digest \s-1NID\s0 corresponding to the \s-1MAC\s0
 190 used by \fBc\fR during record encryption/decryption. If there is no digest (e.g.
 191 for \s-1AEAD\s0 cipher suites) then \fBNID_undef\fR is returned.
 192 .PP
 193 \&\fBSSL_CIPHER_get_handshake_digest()\fR returns an \s-1EVP_MD\s0 for the digest used during
 194 the \s-1SSL/TLS\s0 handshake when using the \s-1SSL_CIPHER\s0 \fBc\fR. Note that this may be
 195 different to the digest used to calculate the \s-1MAC\s0 for encrypted records.
 196 .PP
 197 \&\fBSSL_CIPHER_get_kx_nid()\fR returns the key exchange \s-1NID\s0 corresponding to the method
 198 used by \fBc\fR. If there is no key exchange, then \fBNID_undef\fR is returned.
 199 If any appropriate key exchange algorithm can be used (as in the case of \s-1TLS 1.3\s0
 200 cipher suites) \fBNID_kx_any\fR is returned. Examples (not comprehensive):
 201 .PP
 202 .Vb 4
 203 \& NID_kx_rsa
 204 \& NID_kx_ecdhe
 205 \& NID_kx_dhe
 206 \& NID_kx_psk
 207 .Ve
 208 .PP
 209 \&\fBSSL_CIPHER_get_auth_nid()\fR returns the authentication \s-1NID\s0 corresponding to the method
 210 used by \fBc\fR. If there is no authentication, then \fBNID_undef\fR is returned.
 211 If any appropriate authentication algorithm can be used (as in the case of
 212 \&\s-1TLS 1.3\s0 cipher suites) \fBNID_auth_any\fR is returned. Examples (not comprehensive):
 213 .PP
 214 .Vb 3
 215 \& NID_auth_rsa
 216 \& NID_auth_ecdsa
 217 \& NID_auth_psk
 218 .Ve
 219 .PP
 220 \&\fBSSL_CIPHER_is_aead()\fR returns 1 if the cipher \fBc\fR is \s-1AEAD\s0 (e.g. \s-1GCM\s0 or
 221 ChaCha20/Poly1305), and 0 if it is not \s-1AEAD.\s0
 222 .PP
 223 \&\fBSSL_CIPHER_find()\fR returns a \fB\s-1SSL_CIPHER\s0\fR structure which has the cipher \s-1ID\s0 stored
 224 in \fBptr\fR. The \fBptr\fR parameter is a two element array of \fBchar\fR, which stores the
 225 two-byte \s-1TLS\s0 cipher \s-1ID\s0 (as allocated by \s-1IANA\s0) in network byte order. This parameter
 226 is usually retrieved from a \s-1TLS\s0 packet by using functions like
 227 \&\fBSSL_client_hello_get0_ciphers\fR\|(3).  \fBSSL_CIPHER_find()\fR returns \s-1NULL\s0 if an
 228 error occurs or the indicated cipher is not found.
 229 .PP
 230 \&\fBSSL_CIPHER_get_id()\fR returns the OpenSSL-specific \s-1ID\s0 of the given cipher \fBc\fR. That \s-1ID\s0 is
 231 not the same as the IANA-specific \s-1ID.\s0
 232 .PP
 233 \&\fBSSL_CIPHER_get_protocol_id()\fR returns the two-byte \s-1ID\s0 used in the \s-1TLS\s0 protocol of the given
 234 cipher \fBc\fR.
 235 .PP
 236 \&\fBSSL_CIPHER_description()\fR returns a textual description of the cipher used
 237 into the buffer \fBbuf\fR of length \fBlen\fR provided.  If \fBbuf\fR is provided, it
 238 must be at least 128 bytes, otherwise a buffer will be allocated using
 239 \&\fBOPENSSL_malloc()\fR.  If the provided buffer is too small, or the allocation fails,
 240 \&\fB\s-1NULL\s0\fR is returned.
 241 .PP
 242 The string returned by \fBSSL_CIPHER_description()\fR consists of several fields
 243 separated by whitespace:
 244 .IP "<ciphername>" 4
 245 .IX Item "<ciphername>"
 246 Textual representation of the cipher name.
 247 .IP "<protocol version>" 4
 248 .IX Item "<protocol version>"
 249 The minimum protocol version that the ciphersuite supports, such as \fBTLSv1.2\fR.
 250 Note that this is not always the same as the protocol version in which the
 251 ciphersuite was first defined because some ciphersuites are backwards compatible
 252 with earlier protocol versions.
 253 .IP "Kx=<key exchange>" 4
 254 .IX Item "Kx=<key exchange>"
 255 Key exchange method such as \fB\s-1RSA\s0\fR, \fB\s-1ECDHE\s0\fR, etc.
 256 .IP "Au=<authentication>" 4
 257 .IX Item "Au=<authentication>"
 258 Authentication method such as \fB\s-1RSA\s0\fR, \fBNone\fR, etc.. None is the
 259 representation of anonymous ciphers.
 260 .IP "Enc=<symmetric encryption method>" 4
 261 .IX Item "Enc=<symmetric encryption method>"
 262 Encryption method, with number of secret bits, such as \fB\s-1AESGCM\s0(128)\fR.
 263 .IP "Mac=<message authentication code>" 4
 264 .IX Item "Mac=<message authentication code>"
 265 Message digest, such as \fB\s-1SHA256\s0\fR.
 266 .PP
 267 Some examples for the output of \fBSSL_CIPHER_description()\fR:
 268 .PP
 269 .Vb 2
 270 \& ECDHE\-RSA\-AES256\-GCM\-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  Enc=AESGCM(256) Mac=AEAD
 271 \& RSA\-PSK\-AES256\-CBC\-SHA384 TLSv1.0 Kx=RSAPSK   Au=RSA  Enc=AES(256)  Mac=SHA384
 272 .Ve
 273 .SH "RETURN VALUES"
 274 .IX Header "RETURN VALUES"
 275 \&\fBSSL_CIPHER_get_name()\fR, \fBSSL_CIPHER_standard_name()\fR, \fBOPENSSL_cipher_name()\fR,
 276 \&\fBSSL_CIPHER_get_version()\fR and \fBSSL_CIPHER_description()\fR return the corresponding
 277 value in a null-terminated string for a specific cipher or \*(L"(\s-1NONE\s0)\*(R"
 278 if the cipher is not found.
 279 .PP
 280 \&\fBSSL_CIPHER_get_bits()\fR returns a positive integer representing the number of
 281 secret bits or 0 if an error occurred.
 282 .PP
 283 \&\fBSSL_CIPHER_get_cipher_nid()\fR, \fBSSL_CIPHER_get_digest_nid()\fR,
 284 \&\fBSSL_CIPHER_get_kx_nid()\fR and \fBSSL_CIPHER_get_auth_nid()\fR return the \s-1NID\s0 value or
 285 \&\fBNID_undef\fR if an error occurred.
 286 .PP
 287 \&\fBSSL_CIPHER_get_handshake_digest()\fR returns a valid \fB\s-1EVP_MD\s0\fR structure or \s-1NULL\s0
 288 if an error occurred.
 289 .PP
 290 \&\fBSSL_CIPHER_is_aead()\fR returns 1 if the cipher is \s-1AEAD\s0 or 0 otherwise.
 291 .PP
 292 \&\fBSSL_CIPHER_find()\fR returns a valid \fB\s-1SSL_CIPHER\s0\fR structure or \s-1NULL\s0 if an error
 293 occurred.
 294 .PP
 295 \&\fBSSL_CIPHER_get_id()\fR returns a 4\-byte integer representing the OpenSSL-specific \s-1ID.\s0
 296 .PP
 297 \&\fBSSL_CIPHER_get_protocol_id()\fR returns a 2\-byte integer representing the \s-1TLS\s0
 298 protocol-specific \s-1ID.\s0
 299 .SH "SEE ALSO"
 300 .IX Header "SEE ALSO"
 301 \&\fBssl\fR\|(7), \fBSSL_get_current_cipher\fR\|(3),
 302 \&\fBSSL_get_ciphers\fR\|(3), \fBciphers\fR\|(1)
 303 .SH "HISTORY"
 304 .IX Header "HISTORY"
 305 The \fBSSL_CIPHER_get_version()\fR function was updated to always return the
 306 correct protocol string in OpenSSL 1.1.0.
 307 .PP
 308 The \fBSSL_CIPHER_description()\fR function was changed to return \fB\s-1NULL\s0\fR on error,
 309 rather than a fixed string, in OpenSSL 1.1.0.
 310 .PP
 311 The \fBSSL_CIPHER_get_handshake_digest()\fR function was added in OpenSSL 1.1.1.
 312 .PP
 313 The \fBSSL_CIPHER_standard_name()\fR function was globally available in OpenSSL 1.1.1.
 314  Before OpenSSL 1.1.1, tracing (\fBenable-ssl-trace\fR argument to Configure) was
 315 required to enable this function.
 316 .PP
 317 The \fBOPENSSL_cipher_name()\fR function was added in OpenSSL 1.1.1.
 318 .SH "COPYRIGHT"
 319 .IX Header "COPYRIGHT"
 320 Copyright 2000\-2019 The OpenSSL Project Authors. All Rights Reserved.
 321 .PP
 322 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 323 this file except in compliance with the License.  You can obtain a copy
 324 in the file \s-1LICENSE\s0 in the source distribution or at
 325 <https://www.openssl.org/source/license.html>.