| blob | b141d9c5d11897f9e6ed256ab7c1bc6a2d3e8f88 |
1 .\" Automatically generated by Pod::Man 2.28 (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 "2016-05-03" "1.0.2h" "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 .PP
239 The standard terminology for ephemeral Diffie-Hellman schemes is \s-1DHE
240 \&\s0(finite field) or \s-1ECDHE \s0(elliptic curve). This version of OpenSSL
241 idiosyncratically reports these schemes as \s-1EDH\s0 and \s-1EECDH,\s0 even though
242 it also accepts the standard terminology.
243 .PP
244 It is recommended to use the standard terminology (\s-1DHE\s0 and \s-1ECDHE\s0)
245 during configuration (e.g. via SSL_CTX_set_cipher_list) for clarity of
246 configuration. OpenSSL versions after 1.0.2 will report the standard
247 terms via SSL_CIPHER_get_name and SSL_CIPHER_description.
248 .SH "RETURN VALUES"
249 .IX Header "RETURN VALUES"
250 See \s-1DESCRIPTION\s0
251 .SH "SEE ALSO"
252 .IX Header "SEE ALSO"
253 \&\fIssl\fR\|(3), \fISSL_get_current_cipher\fR\|(3),
254 \&\fISSL_get_ciphers\fR\|(3), \fIciphers\fR\|(1),
255 \&\fISSL_CTX_set_cipher_list\fR\|(3)