| blob | c7d50a7944d4a4c858df238bffd95a03c65c68f0 |
1 .\" $NetBSD: SSL_CIPHER_get_name.3,v 1.14 2015/06/12 17:01:14 christos Exp $
2 .\"
3 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
4 .\"
5 .\" Standard preamble:
6 .\" ========================================================================
7 .de Sp \" Vertical space (when we can't use .PP)
8 .if t .sp .5v
9 .if n .sp
10 ..
11 .de Vb \" Begin verbatim text
12 .ft CW
13 .nf
14 .ne \\$1
15 ..
16 .de Ve \" End verbatim text
17 .ft R
18 .fi
19 ..
20 .\" Set up some character translations and predefined strings. \*(-- will
21 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
22 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
23 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
24 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
25 .\" nothing in troff, for use with C<>.
26 .tr \(*W-
27 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
28 .ie n \{\
29 . ds -- \(*W-
30 . ds PI pi
31 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
32 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
33 . ds L" ""
34 . ds R" ""
35 . ds C` ""
36 . ds C' ""
37 'br\}
38 .el\{\
39 . ds -- \|\(em\|
40 . ds PI \(*p
41 . ds L" ``
42 . ds R" ''
43 . ds C`
44 . ds C'
45 'br\}
46 .\"
47 .\" Escape single quotes in literal strings from groff's Unicode transform.
48 .ie \n(.g .ds Aq \(aq
49 .el .ds Aq '
50 .\"
51 .\" If the F register is turned on, we'll generate index entries on stderr for
52 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
53 .\" entries marked with X<> in POD. Of course, you'll have to process the
54 .\" output yourself in some meaningful fashion.
55 .\"
56 .\" Avoid warning from groff about undefined register 'F'.
57 .de IX
58 ..
59 .nr rF 0
60 .if \n(.g .if rF .nr rF 1
61 .if (\n(rF:(\n(.g==0)) \{
62 . if \nF \{
63 . de IX
64 . tm Index:\\$1\t\\n%\t"\\$2"
65 ..
66 . if !\nF==2 \{
67 . nr % 0
68 . nr F 2
69 . \}
70 . \}
71 .\}
72 .rr rF
73 .\"
74 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
75 .\" Fear. Run. Save yourself. No user-serviceable parts.
76 . \" fudge factors for nroff and troff
77 .if n \{\
78 . ds #H 0
79 . ds #V .8m
80 . ds #F .3m
81 . ds #[ \f1
82 . ds #] \fP
83 .\}
84 .if t \{\
85 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
86 . ds #V .6m
87 . ds #F 0
88 . ds #[ \&
89 . ds #] \&
90 .\}
91 . \" simple accents for nroff and troff
92 .if n \{\
93 . ds ' \&
94 . ds ` \&
95 . ds ^ \&
96 . ds , \&
97 . ds ~ ~
98 . ds /
99 .\}
100 .if t \{\
101 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
102 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
103 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
104 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
105 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
106 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
107 .\}
108 . \" troff and (daisy-wheel) nroff accents
109 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
110 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
111 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
112 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
113 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
114 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
115 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
116 .ds ae a\h'-(\w'a'u*4/10)'e
117 .ds Ae A\h'-(\w'A'u*4/10)'E
118 . \" corrections for vroff
119 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
120 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
121 . \" for low resolution devices (crt and lpr)
122 .if \n(.H>23 .if \n(.V>19 \
123 \{\
124 . ds : e
125 . ds 8 ss
126 . ds o a
127 . ds d- d\h'-1'\(ga
128 . ds D- D\h'-1'\(hy
129 . ds th \o'bp'
130 . ds Th \o'LP'
131 . ds ae ae
132 . ds Ae AE
133 .\}
134 .rm #[ #] #H #V #F C
135 .\" ========================================================================
136 .\"
137 .IX Title "SSL_CIPHER_get_name 3"
138 .TH SSL_CIPHER_get_name 3 "2014-08-10" "1.0.1n" "OpenSSL"
139 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
140 .\" way too many mistakes in technical documents.
141 .if n .ad l
142 .nh
143 .SH "NAME"
144 SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_description \- get SSL_CIPHER properties
145 .SH "LIBRARY"
146 libcrypto, -lcrypto
147 .SH "SYNOPSIS"
148 .IX Header "SYNOPSIS"
149 .Vb 1
150 \& #include <openssl/ssl.h>
151 \&
152 \& const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
153 \& int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
154 \& char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
155 \& char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
156 .Ve
157 .SH "DESCRIPTION"
158 .IX Header "DESCRIPTION"
159 \&\fISSL_CIPHER_get_name()\fR returns a pointer to the name of \fBcipher\fR. If the
160 argument is the \s-1NULL\s0 pointer, a pointer to the constant value \*(L"\s-1NONE\*(R"\s0 is
161 returned.
162 .PP
163 \&\fISSL_CIPHER_get_bits()\fR returns the number of secret bits used for \fBcipher\fR. If
164 \&\fBalg_bits\fR is not \s-1NULL,\s0 it contains the number of bits processed by the
165 chosen algorithm. If \fBcipher\fR is \s-1NULL, 0\s0 is returned.
166 .PP
167 \&\fISSL_CIPHER_get_version()\fR returns string which indicates the \s-1SSL/TLS\s0 protocol
168 version that first defined the cipher.
169 This is currently \fBSSLv2\fR or \fBTLSv1/SSLv3\fR.
170 In some cases it should possibly return \*(L"TLSv1.2\*(R" but does not;
171 use \fISSL_CIPHER_description()\fR instead.
172 If \fBcipher\fR is \s-1NULL, \*(L"\s0(\s-1NONE\s0)\*(R" is returned.
173 .PP
174 \&\fISSL_CIPHER_description()\fR returns a textual description of the cipher used
175 into the buffer \fBbuf\fR of length \fBlen\fR provided. \fBlen\fR must be at least
176 128 bytes, otherwise a pointer to the string \*(L"Buffer too small\*(R" is
177 returned. If \fBbuf\fR is \s-1NULL,\s0 a buffer of 128 bytes is allocated using
178 \&\fIOPENSSL_malloc()\fR. If the allocation fails, a pointer to the string
179 \&\*(L"OPENSSL_malloc Error\*(R" is returned.
180 .SH "NOTES"
181 .IX Header "NOTES"
182 The number of bits processed can be different from the secret bits. An
183 export cipher like e.g. \s-1EXP\-RC4\-MD5\s0 has only 40 secret bits. The algorithm
184 does use the full 128 bits (which would be returned for \fBalg_bits\fR), of
185 which however 88bits are fixed. The search space is hence only 40 bits.
186 .PP
187 The string returned by \fISSL_CIPHER_description()\fR in case of success consists
188 of cleartext information separated by one or more blanks in the following
189 sequence:
190 .IP "<ciphername>" 4
191 .IX Item "<ciphername>"
192 Textual representation of the cipher name.
193 .IP "<protocol version>" 4
194 .IX Item "<protocol version>"
195 Protocol version: \fBSSLv2\fR, \fBSSLv3\fR, \fBTLSv1.2\fR. The TLSv1.0 ciphers are
196 flagged with SSLv3. No new ciphers were added by TLSv1.1.
197 .IP "Kx=<key exchange>" 4
198 .IX Item "Kx=<key exchange>"
199 Key exchange method: \fB\s-1RSA\s0\fR (for export ciphers as \fB\s-1RSA\s0(512)\fR or
200 \&\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),
201 \&\fB\s-1DH/RSA\s0\fR, \fB\s-1DH/DSS\s0\fR, \fBFortezza\fR.
202 .IP "Au=<authentication>" 4
203 .IX Item "Au=<authentication>"
204 Authentication method: \fB\s-1RSA\s0\fR, \fB\s-1DSS\s0\fR, \fB\s-1DH\s0\fR, \fBNone\fR. None is the
205 representation of anonymous ciphers.
206 .IP "Enc=<symmetric encryption method>" 4
207 .IX Item "Enc=<symmetric encryption method>"
208 Encryption method with number of secret bits: \fB\s-1DES\s0(40)\fR, \fB\s-1DES\s0(56)\fR,
209 \&\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,
210 \&\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.
211 .IP "Mac=<message authentication code>" 4
212 .IX Item "Mac=<message authentication code>"
213 Message digest: \fB\s-1MD5\s0\fR, \fB\s-1SHA1\s0\fR.
214 .IP "<export flag>" 4
215 .IX Item "<export flag>"
216 If the cipher is flagged exportable with respect to old \s-1US\s0 crypto
217 regulations, the word "\fBexport\fR" is printed.
218 .SH "EXAMPLES"
219 .IX Header "EXAMPLES"
220 Some examples for the output of \fISSL_CIPHER_description()\fR:
221 .PP
222 .Vb 4
223 \& EDH\-RSA\-DES\-CBC3\-SHA SSLv3 Kx=DH Au=RSA Enc=3DES(168) Mac=SHA1
224 \& EDH\-DSS\-DES\-CBC3\-SHA SSLv3 Kx=DH Au=DSS Enc=3DES(168) Mac=SHA1
225 \& RC4\-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
226 \& EXP\-RC4\-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
227 .Ve
228 .PP
229 A comp[lete list can be retrieved by invoking the following command:
230 .PP
231 .Vb 1
232 \& openssl ciphers \-v ALL
233 .Ve
234 .SH "BUGS"
235 .IX Header "BUGS"
236 If \fISSL_CIPHER_description()\fR is called with \fBcipher\fR being \s-1NULL,\s0 the
237 library crashes.
238 .PP
239 If \fISSL_CIPHER_description()\fR cannot handle a built-in cipher, the according
240 description of the cipher property is \fBunknown\fR. This case should not
241 occur.
242 .SH "RETURN VALUES"
243 .IX Header "RETURN VALUES"
244 See \s-1DESCRIPTION\s0
245 .SH "SEE ALSO"
246 .IX Header "SEE ALSO"
247 \&\fIssl\fR\|(3), \fISSL_get_current_cipher\fR\|(3),
248 \&\fISSL_get_ciphers\fR\|(3), \fIopenssl_ciphers\fR\|(1)