secure/lib/libssl/man/SSL_CIPHER_get_name.3

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