doc/man3/SSL_CIPHER_get_name.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CIPHER_get_name,
   6 SSL_CIPHER_standard_name,
   7 OPENSSL_cipher_name,
   8 SSL_CIPHER_get_bits,
   9 SSL_CIPHER_get_version,
  10 SSL_CIPHER_description,
  11 SSL_CIPHER_get_cipher_nid,
  12 SSL_CIPHER_get_digest_nid,
  13 SSL_CIPHER_get_handshake_digest,
  14 SSL_CIPHER_get_kx_nid,
  15 SSL_CIPHER_get_auth_nid,
  16 SSL_CIPHER_is_aead,
  17 SSL_CIPHER_find,
  18 SSL_CIPHER_get_id
  19 - get SSL_CIPHER properties
  20
  21 =head1 SYNOPSIS
  22
  23  #include <openssl/ssl.h>
  24
  25  const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
  26  const char *SSL_CIPHER_standard_name(const SSL_CIPHER *cipher);
  27  const char *OPENSSL_cipher_name(const char *stdname);
  28  int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
  29  char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
  30  char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
  31  int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
  32  int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
  33  const EVP_MD *SSL_CIPHER_get_handshake_digest(const SSL_CIPHER *c);
  34  int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
  35  int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
  36  int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
  37  const SSL_CIPHER *SSL_CIPHER_find(SSL *ssl, const unsigned char *ptr);
  38  uint32_t SSL_CIPHER_get_id(const SSL_CIPHER *c);
  39
  40 =head1 DESCRIPTION
  41
  42 SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
  43 B<cipher> is NULL, it returns "(NONE)".
  44
  45 SSL_CIPHER_standard_name() returns a pointer to the standard RFC name of
  46 B<cipher>. If the B<cipher> is NULL, it returns "(NONE)". If the B<cipher>
  47 has no standard name, it returns B<NULL>. If B<cipher> was defined in both
  48 SSLv3 and TLS, it returns the TLS name.
  49
  50 OPENSSL_cipher_name() returns a pointer to the OpenSSL name of B<stdname>.
  51 If the B<stdname> is NULL, or B<stdname> has no corresponding OpenSSL name,
  52 it returns "(NONE)". Where both exist, B<stdname> should be the TLS name rather
  53 than the SSLv3 name.
  54
  55 SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
  56 If B<cipher> is NULL, 0 is returned.
  57
  58 SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
  59 version that first defined the cipher.  It returns "(NONE)" if B<cipher> is NULL.
  60
  61 SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
  62 If there is no cipher (e.g. for cipher suites with no encryption) then
  63 B<NID_undef> is returned.
  64
  65 SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
  66 used by B<c> during record encryption/decryption. If there is no digest (e.g.
  67 for AEAD cipher suites) then B<NID_undef> is returned.
  68
  69 SSL_CIPHER_get_handshake_digest() returns an EVP_MD for the digest used during
  70 the SSL/TLS handshake when using the SSL_CIPHER B<c>. Note that this may be
  71 different to the digest used to calculate the MAC for encrypted records.
  72
  73 SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
  74 used by B<c>. If there is no key exchange, then B<NID_undef> is returned.
  75 If any appropriate key exchange algorithm can be used (as in the case of TLS 1.3
  76 cipher suites) B<NID_kx_any> is returned. Examples (not comprehensive):
  77
  78  NID_kx_rsa
  79  NID_kx_ecdhe
  80  NID_kx_dhe
  81  NID_kx_psk
  82
  83 SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
  84 used by B<c>. If there is no authentication, then B<NID_undef> is returned.
  85 If any appropriate authentication algorithm can be used (as in the case of
  86 TLS 1.3 cipher suites) B<NID_auth_any> is returned. Examples (not comprehensive):
  87
  88  NID_auth_rsa
  89  NID_auth_ecdsa
  90  NID_auth_psk
  91
  92 SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
  93 ChaCha20/Poly1305), and 0 if it is not AEAD.
  94
  95 SSL_CIPHER_find() returns a B<SSL_CIPHER> structure which has the cipher ID stored
  96 in B<ptr>. The B<ptr> parameter is a two element array of B<char>, which stores the
  97 two-byte TLS cipher ID (as allocated by IANA) in network byte order. This parameter
  98 is usually retrieved from a TLS packet by using functions like L<SSL_early_get0_ciphers(3)>.
  99 SSL_CIPHER_find() returns NULL if an error occurs or the indicated cipher is not found.
 100
 101 SSL_CIPHER_get_id() returns the ID of the given cipher B<c>. The ID here is an
 102 OpenSSL-specific concept, which stores a prefix of 0x0300 in the higher two bytes,
 103 and the IANA-specified chipher suite ID in the lower two bytes. For instance,
 104 TLS_RSA_WITH_NULL_MD5 has IANA ID "0x00, 0x01", but the SSL_CIPHER_get_id()
 105 function will return an ID with value 0x03000001.
 106
 107 SSL_CIPHER_description() returns a textual description of the cipher used
 108 into the buffer B<buf> of length B<len> provided.  If B<buf> is provided, it
 109 must be at least 128 bytes, otherwise a buffer will be allocated using
 110 OPENSSL_malloc().  If the provided buffer is too small, or the allocation fails,
 111 B<NULL> is returned.
 112
 113 The string returned by SSL_CIPHER_description() consists of several fields
 114 separated by whitespace:
 115
 116 =over 4
 117
 118 =item <ciphername>
 119
 120 Textual representation of the cipher name.
 121
 122 =item <protocol version>
 123
 124 Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
 125
 126 =item Kx=<key exchange>
 127
 128 Key exchange method such as B<RSA>, B<ECDHE>, etc.
 129
 130 =item Au=<authentication>
 131
 132 Authentication method such as B<RSA>, B<None>, etc.. None is the
 133 representation of anonymous ciphers.
 134
 135 =item Enc=<symmetric encryption method>
 136
 137 Encryption method, with number of secret bits, such as B<AESGCM(128)>.
 138
 139 =item Mac=<message authentication code>
 140
 141 Message digest, such as B<SHA256>.
 142
 143 =back
 144
 145 Some examples for the output of SSL_CIPHER_description():
 146
 147  ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  Enc=AESGCM(256) Mac=AEAD
 148  RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK   Au=RSA  Enc=AES(256)  Mac=SHA384
 149
 150 =head1 HISTORY
 151
 152 SSL_CIPHER_get_version() was updated to always return the correct protocol
 153 string in OpenSSL 1.1.0.
 154
 155 SSL_CIPHER_description() was changed to return B<NULL> on error,
 156 rather than a fixed string, in OpenSSL 1.1.0.
 157
 158 SSL_CIPHER_get_handshake_digest() was added in OpenSSL 1.1.1.
 159
 160 SSL_CIPHER_standard_name() was globally available in OpenSSL 1.1.1. Before
 161 OpenSSL 1.1.1, tracing (B<enable-ssl-trace> argument to Configure) was
 162 required to enable this function.
 163
 164 OPENSSL_cipher_name() was added in OpenSSL 1.1.1.
 165
 166 =head1 SEE ALSO
 167
 168 L<ssl(7)>, L<SSL_get_current_cipher(3)>,
 169 L<SSL_get_ciphers(3)>, L<ciphers(1)>
 170
 171 =head1 COPYRIGHT
 172
 173 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 174
 175 Licensed under the OpenSSL license (the "License").  You may not use
 176 this file except in compliance with the License.  You can obtain a copy
 177 in the file LICENSE in the source distribution or at
 178 L<https://www.openssl.org/source/license.html>.
 179
 180 =cut