doc/man3/SSL_CIPHER_get_name.pod

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