secure/lib/libssl/man/SSL_CIPHER_get_name.3

   1 .\" Automatically generated by Pod::Man 4.07 (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 "2017-01-26" "1.0.2k" "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_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description \- 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 \& int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
 146 \& char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
 147 \& char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 \&\fISSL_CIPHER_get_name()\fR returns a pointer to the name of \fBcipher\fR. If the
 152 argument is the \s-1NULL\s0 pointer, a pointer to the constant value \*(L"\s-1NONE\*(R"\s0 is
 153 returned.
 154 .PP
 155 \&\fISSL_CIPHER_get_bits()\fR returns the number of secret bits used for \fBcipher\fR. If
 156 \&\fBalg_bits\fR is not \s-1NULL,\s0 it contains the number of bits processed by the
 157 chosen algorithm. If \fBcipher\fR is \s-1NULL, 0\s0 is returned.
 158 .PP
 159 \&\fISSL_CIPHER_get_version()\fR returns string which indicates the \s-1SSL/TLS\s0 protocol
 160 version that first defined the cipher.
 161 This is currently \fBSSLv2\fR or \fBTLSv1/SSLv3\fR.
 162 In some cases it should possibly return \*(L"TLSv1.2\*(R" but does not;
 163 use \fISSL_CIPHER_description()\fR instead.
 164 If \fBcipher\fR is \s-1NULL, \*(L"\s0(\s-1NONE\s0)\*(R" is returned.
 165 .PP
 166 \&\fISSL_CIPHER_description()\fR returns a textual description of the cipher used
 167 into the buffer \fBbuf\fR of length \fBlen\fR provided. \fBlen\fR must be at least
 168 128 bytes, otherwise a pointer to the string \*(L"Buffer too small\*(R" is
 169 returned. If \fBbuf\fR is \s-1NULL,\s0 a buffer of 128 bytes is allocated using
 170 \&\fIOPENSSL_malloc()\fR. If the allocation fails, a pointer to the string
 171 \&\*(L"OPENSSL_malloc Error\*(R" is returned.
 172 .SH "NOTES"
 173 .IX Header "NOTES"
 174 The number of bits processed can be different from the secret bits. An
 175 export cipher like e.g. \s-1EXP\-RC4\-MD5\s0 has only 40 secret bits. The algorithm
 176 does use the full 128 bits (which would be returned for \fBalg_bits\fR), of
 177 which however 88bits are fixed. The search space is hence only 40 bits.
 178 .PP
 179 The string returned by \fISSL_CIPHER_description()\fR in case of success consists
 180 of cleartext information separated by one or more blanks in the following
 181 sequence:
 182 .IP "<ciphername>" 4
 183 .IX Item "<ciphername>"
 184 Textual representation of the cipher name.
 185 .IP "<protocol version>" 4
 186 .IX Item "<protocol version>"
 187 Protocol version: \fBSSLv2\fR, \fBSSLv3\fR, \fBTLSv1.2\fR. The TLSv1.0 ciphers are
 188 flagged with SSLv3. No new ciphers were added by TLSv1.1.
 189 .IP "Kx=<key exchange>" 4
 190 .IX Item "Kx=<key exchange>"
 191 Key exchange method: \fB\s-1RSA\s0\fR (for export ciphers as \fB\s-1RSA\s0(512)\fR or
 192 \&\fB\s-1RSA\s0(1024)\fR), \fB\s-1DH\s0\fR (for export ciphers as \fB\s-1DH\s0(512)\fR or \fB\s-1DH\s0(1024)\fR),
 193 \&\fB\s-1DH/RSA\s0\fR, \fB\s-1DH/DSS\s0\fR, \fBFortezza\fR.
 194 .IP "Au=<authentication>" 4
 195 .IX Item "Au=<authentication>"
 196 Authentication method: \fB\s-1RSA\s0\fR, \fB\s-1DSS\s0\fR, \fB\s-1DH\s0\fR, \fBNone\fR. None is the
 197 representation of anonymous ciphers.
 198 .IP "Enc=<symmetric encryption method>" 4
 199 .IX Item "Enc=<symmetric encryption method>"
 200 Encryption method with number of secret bits: \fB\s-1DES\s0(40)\fR, \fB\s-1DES\s0(56)\fR,
 201 \&\fB3DES(168)\fR, \fB\s-1RC4\s0(40)\fR, \fB\s-1RC4\s0(56)\fR, \fB\s-1RC4\s0(64)\fR, \fB\s-1RC4\s0(128)\fR,
 202 \&\fB\s-1RC2\s0(40)\fR, \fB\s-1RC2\s0(56)\fR, \fB\s-1RC2\s0(128)\fR, \fB\s-1IDEA\s0(128)\fR, \fBFortezza\fR, \fBNone\fR.
 203 .IP "Mac=<message authentication code>" 4
 204 .IX Item "Mac=<message authentication code>"
 205 Message digest: \fB\s-1MD5\s0\fR, \fB\s-1SHA1\s0\fR.
 206 .IP "<export flag>" 4
 207 .IX Item "<export flag>"
 208 If the cipher is flagged exportable with respect to old \s-1US\s0 crypto
 209 regulations, the word "\fBexport\fR" is printed.
 210 .SH "EXAMPLES"
 211 .IX Header "EXAMPLES"
 212 Some examples for the output of \fISSL_CIPHER_description()\fR:
 213 .PP
 214 .Vb 4
 215 \& EDH\-RSA\-DES\-CBC3\-SHA    SSLv3 Kx=DH       Au=RSA  Enc=3DES(168) Mac=SHA1
 216 \& EDH\-DSS\-DES\-CBC3\-SHA    SSLv3 Kx=DH       Au=DSS  Enc=3DES(168) Mac=SHA1
 217 \& RC4\-MD5                 SSLv3 Kx=RSA      Au=RSA  Enc=RC4(128)  Mac=MD5
 218 \& EXP\-RC4\-MD5             SSLv3 Kx=RSA(512) Au=RSA  Enc=RC4(40)   Mac=MD5  export
 219 .Ve
 220 .PP
 221 A comp[lete list can be retrieved by invoking the following command:
 222 .PP
 223 .Vb 1
 224 \& openssl ciphers \-v ALL
 225 .Ve
 226 .SH "BUGS"
 227 .IX Header "BUGS"
 228 If \fISSL_CIPHER_description()\fR is called with \fBcipher\fR being \s-1NULL,\s0 the
 229 library crashes.
 230 .PP
 231 If \fISSL_CIPHER_description()\fR cannot handle a built-in cipher, the according
 232 description of the cipher property is \fBunknown\fR. This case should not
 233 occur.
 234 .PP
 235 The standard terminology for ephemeral Diffie-Hellman schemes is \s-1DHE
 236 \&\s0(finite field) or \s-1ECDHE \s0(elliptic curve).  This version of OpenSSL
 237 idiosyncratically reports these schemes as \s-1EDH\s0 and \s-1EECDH,\s0 even though
 238 it also accepts the standard terminology.
 239 .PP
 240 It is recommended to use the standard terminology (\s-1DHE\s0 and \s-1ECDHE\s0)
 241 during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of
 242 configuration.  OpenSSL versions after 1.0.2 will report the standard
 243 terms via SSL_CIPHER_get_name and SSL_CIPHER_description.
 244 .SH "RETURN VALUES"
 245 .IX Header "RETURN VALUES"
 246 See \s-1DESCRIPTION\s0
 247 .SH "SEE ALSO"
 248 .IX Header "SEE ALSO"
 249 \&\fIssl\fR\|(3), \fISSL_get_current_cipher\fR\|(3),
 250 \&\fISSL_get_ciphers\fR\|(3), \fIciphers\fR\|(1),
 251 \&\fISSL_CTX_set_cipher_list\fR\|(3)