doc/ssl/SSL_CIPHER_get_name.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description - get SSL_CIPHER properties
   6
   7 =head1 SYNOPSIS
   8
   9  #include <openssl/ssl.h>
  10
  11  const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
  12  int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
  13  char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
  14  char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
  15  int SSL_CIPHER_get_cipher_nid(const SSL_CIPHER *c);
  16  int SSL_CIPHER_get_digest_nid(const SSL_CIPHER *c);
  17  int SSL_CIPHER_get_kx_nid(const SSL_CIPHER *c);
  18  int SSL_CIPHER_get_auth_nid(const SSL_CIPHER *c);
  19  int SSL_CIPHER_is_aead(const SSL_CIPHER *c);
  20
  21 =head1 DESCRIPTION
  22
  23 SSL_CIPHER_get_name() returns a pointer to the name of B<cipher>. If the
  24 B<cipher> is NULL, it returns "(NONE)".
  25
  26 SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>.
  27 If B<cipher> is NULL, 0 is returned.
  28
  29 SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
  30 version that first defined the cipher.  It returns "(NONE)" if B<cipher> is NULL.
  31
  32 SSL_CIPHER_get_cipher_nid() returns the cipher NID corresponding to B<c>.
  33 If there is no cipher (e.g. for ciphersuites with no encryption) then
  34 B<NID_undef> is returned.
  35
  36 SSL_CIPHER_get_digest_nid() returns the digest NID corresponding to the MAC
  37 used by B<c>. If there is no digest (e.g. for AEAD ciphersuites) then
  38 B<NID_undef> is returned.
  39
  40 SSL_CIPHER_get_kx_nid() returns the key exchange NID corresponding to the method
  41 used by B<c>. If there is no key exchange, then B<NID_undef> is returned. Examples (not comprehensive):
  42
  43  NID_kx_rsa
  44  NID_kx_ecdhe
  45  NID_kx_dhe
  46  NID_kx_psk
  47
  48 SSL_CIPHER_get_auth_nid() returns the authentication NID corresponding to the method
  49 used by B<c>. If there is no authentication, then B<NID_undef> is returned.
  50 Examples (not comprehensive):
  51
  52  NID_auth_rsa
  53  NID_auth_ecdsa
  54  NID_auth_psk
  55
  56 SSL_CIPHER_is_aead() returns 1 if the cipher B<c> is AEAD (e.g. GCM or
  57 ChaCha20/Poly1305), and 0 if it is not AEAD.
  58
  59 SSL_CIPHER_description() returns a textual description of the cipher used
  60 into the buffer B<buf> of length B<len> provided.  If B<buf> is provided, it
  61 must be at least 128 bytes, otherwise a buffer will be allocated using
  62 OPENSSL_malloc().  If the provided buffer is too small, or the allocation fails,
  63 B<NULL> is returned.
  64
  65 The string returned by SSL_CIPHER_description() consists of several fields
  66 separated by whitespace:
  67
  68 =over 4
  69
  70 =item <ciphername>
  71
  72 Textual representation of the cipher name.
  73
  74 =item <protocol version>
  75
  76 Protocol version, such as B<TLSv1.2>, when the cipher was first defined.
  77
  78 =item Kx=<key exchange>
  79
  80 Key exchange method such as B<RSA>, B<ECDHE>, etc.
  81
  82 =item Au=<authentication>
  83
  84 Authentication method such as B<RSA>, B<None>, etc.. None is the
  85 representation of anonymous ciphers.
  86
  87 =item Enc=<symmetric encryption method>
  88
  89 Encryption method, with number of secret bits, such as B<AESGCM(128)>.
  90
  91 =item Mac=<message authentication code>
  92
  93 Message digest, such as B<SHA256>.
  94
  95 =back
  96
  97 Some examples for the output of SSL_CIPHER_description():
  98
  99  ECDHE-RSA-AES256-GCM-SHA256 TLSv1.2 Kx=ECDH     Au=RSA  Enc=AESGCM(256) Mac=AEAD
 100  RSA-PSK-AES256-CBC-SHA384 TLSv1.0 Kx=RSAPSK   Au=RSA  Enc=AES(256)  Mac=SHA384
 101
 102 =head1 HISTORY
 103
 104 SSL_CIPHER_get_version() was updated to always return the correct protocol
 105 string in OpenSSL 1.1.
 106
 107 SSL_CIPHER_description() was changed to return B<NULL> on error,
 108 rather than a fixed string, in OpenSSL 1.1
 109
 110 =head1 SEE ALSO
 111
 112 L<ssl(3)>, L<SSL_get_current_cipher(3)>,
 113 L<SSL_get_ciphers(3)>, L<ciphers(1)>
 114
 115 =cut
 116
 117 =head1 COPYRIGHT
 118
 119 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
 120
 121 Licensed under the OpenSSL license (the "License").  You may not use
 122 this file except in compliance with the License.  You can obtain a copy
 123 in the file LICENSE in the source distribution or at
 124 L<https://www.openssl.org/source/license.html>.
 125
 126 =cut