← Back to branch summary

~ubuntu-branches/ubuntu/precise/openssl098/precise

« back to all changes in this revision

Viewing changes to doc/ssl/SSL_alert_type_string.pod

  • Committer: Bazaar Package Importer
  • Author(s): Kurt Roeckx
  • Date: 2011-03-23 19:50:31 UTC
  • Revision ID: james.westby@ubuntu.com-20110323195031-6h9crj4bymhhr8b8
Tags: upstream-0.9.8o
Import upstream version 0.9.8o

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/ssl/SSL_alert_type_string.pod
 
1
=pod
 
2
 
 
3
=head1 NAME
 
4
 
 
5
SSL_alert_type_string, SSL_alert_type_string_long, SSL_alert_desc_string, SSL_alert_desc_string_long - get textual description of alert information
 
6
 
 
7
=head1 SYNOPSIS
 
8
 
 
9
 #include <openssl/ssl.h>
 
10
 
 
11
 const char *SSL_alert_type_string(int value);
 
12
 const char *SSL_alert_type_string_long(int value);
 
13
 
 
14
 const char *SSL_alert_desc_string(int value);
 
15
 const char *SSL_alert_desc_string_long(int value);
 
16
 
 
17
=head1 DESCRIPTION
 
18
 
 
19
SSL_alert_type_string() returns a one letter string indicating the
 
20
type of the alert specified by B<value>.
 
21
 
 
22
SSL_alert_type_string_long() returns a string indicating the type of the alert
 
23
specified by B<value>.
 
24
 
 
25
SSL_alert_desc_string() returns a two letter string as a short form
 
26
describing the reason of the alert specified by B<value>.
 
27
 
 
28
SSL_alert_desc_string_long() returns a string describing the reason
 
29
of the alert specified by B<value>.
 
30
 
 
31
=head1 NOTES
 
32
 
 
33
When one side of an SSL/TLS communication wants to inform the peer about
 
34
a special situation, it sends an alert. The alert is sent as a special message
 
35
and does not influence the normal data stream (unless its contents results
 
36
in the communication being canceled).
 
37
 
 
38
A warning alert is sent, when a non-fatal error condition occurs. The
 
39
"close notify" alert is sent as a warning alert. Other examples for
 
40
non-fatal errors are certificate errors ("certificate expired",
 
41
"unsupported certificate"), for which a warning alert may be sent.
 
42
(The sending party may however decide to send a fatal error.) The
 
43
receiving side may cancel the connection on reception of a warning
 
44
alert on it discretion.
 
45
 
 
46
Several alert messages must be sent as fatal alert messages as specified
 
47
by the TLS RFC. A fatal alert always leads to a connection abort.
 
48
 
 
49
=head1 RETURN VALUES
 
50
 
 
51
The following strings can occur for SSL_alert_type_string() or
 
52
SSL_alert_type_string_long():
 
53
 
 
54
=over 4
 
55
 
 
56
=item "W"/"warning"
 
57
 
 
58
=item "F"/"fatal"
 
59
 
 
60
=item "U"/"unknown"
 
61
 
 
62
This indicates that no support is available for this alert type.
 
63
Probably B<value> does not contain a correct alert message.
 
64
 
 
65
=back
 
66
 
 
67
The following strings can occur for SSL_alert_desc_string() or
 
68
SSL_alert_desc_string_long():
 
69
 
 
70
=over 4
 
71
 
 
72
=item "CN"/"close notify"
 
73
 
 
74
The connection shall be closed. This is a warning alert.
 
75
 
 
76
=item "UM"/"unexpected message"
 
77
 
 
78
An inappropriate message was received. This alert is always fatal
 
79
and should never be observed in communication between proper
 
80
implementations.
 
81
 
 
82
=item "BM"/"bad record mac"
 
83
 
 
84
This alert is returned if a record is received with an incorrect
 
85
MAC. This message is always fatal.
 
86
 
 
87
=item "DF"/"decompression failure"
 
88
 
 
89
The decompression function received improper input (e.g. data
 
90
that would expand to excessive length). This message is always
 
91
fatal.
 
92
 
 
93
=item "HF"/"handshake failure"
 
94
 
 
95
Reception of a handshake_failure alert message indicates that the
 
96
sender was unable to negotiate an acceptable set of security
 
97
parameters given the options available. This is a fatal error.
 
98
 
 
99
=item "NC"/"no certificate"
 
100
 
 
101
A client, that was asked to send a certificate, does not send a certificate
 
102
(SSLv3 only).
 
103
 
 
104
=item "BC"/"bad certificate"
 
105
 
 
106
A certificate was corrupt, contained signatures that did not
 
107
verify correctly, etc
 
108
 
 
109
=item "UC"/"unsupported certificate"
 
110
 
 
111
A certificate was of an unsupported type.
 
112
 
 
113
=item "CR"/"certificate revoked"
 
114
 
 
115
A certificate was revoked by its signer.
 
116
 
 
117
=item "CE"/"certificate expired"
 
118
 
 
119
A certificate has expired or is not currently valid.
 
120
 
 
121
=item "CU"/"certificate unknown"
 
122
 
 
123
Some other (unspecified) issue arose in processing the
 
124
certificate, rendering it unacceptable.
 
125
 
 
126
=item "IP"/"illegal parameter"
 
127
 
 
128
A field in the handshake was out of range or inconsistent with
 
129
other fields. This is always fatal.
 
130
 
 
131
=item "DC"/"decryption failed"
 
132
 
 
133
A TLSCiphertext decrypted in an invalid way: either it wasn't an
 
134
even multiple of the block length or its padding values, when
 
135
checked, weren't correct. This message is always fatal.
 
136
 
 
137
=item "RO"/"record overflow"
 
138
 
 
139
A TLSCiphertext record was received which had a length more than
 
140
2^14+2048 bytes, or a record decrypted to a TLSCompressed record
 
141
with more than 2^14+1024 bytes. This message is always fatal.
 
142
 
 
143
=item "CA"/"unknown CA"
 
144
 
 
145
A valid certificate chain or partial chain was received, but the
 
146
certificate was not accepted because the CA certificate could not
 
147
be located or couldn't be matched with a known, trusted CA.  This
 
148
message is always fatal.
 
149
 
 
150
=item "AD"/"access denied"
 
151
 
 
152
A valid certificate was received, but when access control was
 
153
applied, the sender decided not to proceed with negotiation.
 
154
This message is always fatal.
 
155
 
 
156
=item "DE"/"decode error"
 
157
 
 
158
A message could not be decoded because some field was out of the
 
159
specified range or the length of the message was incorrect. This
 
160
message is always fatal.
 
161
 
 
162
=item "CY"/"decrypt error"
 
163
 
 
164
A handshake cryptographic operation failed, including being
 
165
unable to correctly verify a signature, decrypt a key exchange,
 
166
or validate a finished message.
 
167
 
 
168
=item "ER"/"export restriction"
 
169
 
 
170
A negotiation not in compliance with export restrictions was
 
171
detected; for example, attempting to transfer a 1024 bit
 
172
ephemeral RSA key for the RSA_EXPORT handshake method. This
 
173
message is always fatal.
 
174
 
 
175
=item "PV"/"protocol version"
 
176
 
 
177
The protocol version the client has attempted to negotiate is
 
178
recognized, but not supported. (For example, old protocol
 
179
versions might be avoided for security reasons). This message is
 
180
always fatal.
 
181
 
 
182
=item "IS"/"insufficient security"
 
183
 
 
184
Returned instead of handshake_failure when a negotiation has
 
185
failed specifically because the server requires ciphers more
 
186
secure than those supported by the client. This message is always
 
187
fatal.
 
188
 
 
189
=item "IE"/"internal error"
 
190
 
 
191
An internal error unrelated to the peer or the correctness of the
 
192
protocol makes it impossible to continue (such as a memory
 
193
allocation failure). This message is always fatal.
 
194
 
 
195
=item "US"/"user canceled"
 
196
 
 
197
This handshake is being canceled for some reason unrelated to a
 
198
protocol failure. If the user cancels an operation after the
 
199
handshake is complete, just closing the connection by sending a
 
200
close_notify is more appropriate. This alert should be followed
 
201
by a close_notify. This message is generally a warning.
 
202
 
 
203
=item "NR"/"no renegotiation"
 
204
 
 
205
Sent by the client in response to a hello request or by the
 
206
server in response to a client hello after initial handshaking.
 
207
Either of these would normally lead to renegotiation; when that
 
208
is not appropriate, the recipient should respond with this alert;
 
209
at that point, the original requester can decide whether to
 
210
proceed with the connection. One case where this would be
 
211
appropriate would be where a server has spawned a process to
 
212
satisfy a request; the process might receive security parameters
 
213
(key length, authentication, etc.) at startup and it might be
 
214
difficult to communicate changes to these parameters after that
 
215
point. This message is always a warning.
 
216
 
 
217
=item "UK"/"unknown"
 
218
 
 
219
This indicates that no description is available for this alert type.
 
220
Probably B<value> does not contain a correct alert message.
 
221
 
 
222
=back
 
223
 
 
224
=head1 SEE ALSO
 
225
 
 
226
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_info_callback(3)|SSL_CTX_set_info_callback(3)>
 
227
 
 
228
=cut