1SSL(3) User Contributed Perl Documentation SSL(3)
2
6 IO::Socket::SSL -- Nearly transparent SSL encapsulation for
7 IO::Socket::INET.
8
10 use IO::Socket::SSL;
11 my $client = IO::Socket::SSL->new("www.example.com:https");
13 if ($client) {
15 print $client "GET / HTTP/1.0\r\n\r\n";
16 print <$client>;
17 close $client;
18 } else {
19 warn "I encountered a problem: ",
20 IO::Socket::SSL::errstr();
21 }
22
24 This module is a true drop-in replacement for IO::Socket::INET that
25 uses SSL to encrypt data before it is transferred to a remote server or
26 client. IO::Socket::SSL supports all the extra features that one needs
27 to write a full-featured SSL client or server application: multiple SSL
28 contexts, cipher selection, certificate verification, and SSL version
29 selection. As an extra bonus, it works perfectly with mod_perl.
30 If you have never used SSL before, you should read the appendix
32 labelled 'Using SSL' before attempting to use this module.
33 If you have used this module before, read on, as versions 0.93 and
35 above have several changes from the previous IO::Socket::SSL versions
36 (especially see the note about return values).
37 If you are using non-blocking sockets read on, as version 0.98 added
39 better support for non-blocking.
40
42 IO::Socket::SSL inherits its methods from IO::Socket::INET, overriding
43 them as necessary. If there is an SSL error, the method or operation
44 will return an empty list (false in all contexts). The methods that
45 have changed from the perspective of the user are re-documented here:
46 new(...)
48 Creates a new IO::Socket::SSL object. You may use all the friendly
49 options that came bundled with IO::Socket::INET, plus (optionally)
50 the ones that follow:
51 SSL_version
53 Sets the version of the SSL protocol used to transmit data. The
54 default is SSLv2/3, which auto-negotiates between SSLv2 and
55 SSLv3. You may specify 'SSLv2', 'SSLv3', or 'TLSv1' (case-insen‐
56 sitive) if you do not want this behavior.
57 SSL_cipher_list
59 If this option is set the cipher list for the connection will be
60 set to the given value, e.g. something like 'ALL:!LOW:!EXP:!ADH'.
61 Look into the OpenSSL documentation
62 (<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>)
63 for more details. If this option is not used the openssl builtin
64 default is used which is suitable for most cases.
65 SSL_use_cert
67 If this is set, it forces IO::Socket::SSL to use a certificate
68 and key, even if you are setting up an SSL client. If this is
69 set to 0 (the default), then you will only need a certificate and
70 key if you are setting up a server.
71 SSL_key_file
73 If your RSA private key is not in default place
74 (certs/server-key.pem for servers, certs/client-key.pem for
75 clients), then this is the option that you would use to specify a
76 different location. Keys should be PEM formatted, and if they
77 are encrypted, you will be prompted to enter a password before
78 the socket is formed (unless you specified the SSL_passwd_cb
79 option).
80 SSL_key
82 This is an EVP_PKEY* and can be used instead of SSL_key_file.
83 Useful if you don't have your key in a file but create it dynami‐
84 cally or get it from a string (see openssl PEM_read_bio_Pri‐
85 vateKey etc for getting a EVP_PKEY* from a string).
86 SSL_cert_file
88 If your SSL certificate is not in the default place
89 (certs/server-cert.pem for servers, certs/client-cert.pem for
90 clients), then you should use this option to specify the location
91 of your certificate. Note that a key and certificate are only
92 required for an SSL server, so you do not need to bother with
93 these trifling options should you be setting up an unauthenti‐
94 cated client.
95 SSL_cert
97 This is an X509* or an array of X509*. The first X509* is the
98 internal representation of the certificate while the following
99 ones are extra certificates. Useful if you create your certifi‐
100 cate dynamically (like in a SSL intercepting proxy) or get it
101 from a string (see openssl PEM_read_bio_X509 etc for getting a
102 X509* from a string).
103 SSL_dh_file
105 If you want Diffie-Hellman key exchange you need to supply a
106 suitable file here or use the SSL_dh parameter. See dhparam com‐
107 mand in openssl for more information.
108 SSL_dh
110 Like SSL_dh_file, but instead of giving a file you use a pre‐
111 loaded or generated DH*.
112 SSL_passwd_cb
114 If your private key is encrypted, you might not want the default
115 password prompt from Net::SSLeay. This option takes a reference
116 to a subroutine that should return the password required to
117 decrypt your private key.
118 SSL_ca_file
120 If you want to verify that the peer certificate has been signed
121 by a reputable certificate authority, then you should use this
122 option to locate the file containing the certificate(s) of the
123 reputable certificate authorities if it is not already in the
124 file certs/my-ca.pem.
125 SSL_ca_path
127 If you are unusually friendly with the OpenSSL documentation, you
128 might have set yourself up a directory containing several trusted
129 certificates as separate files as well as an index of the cer‐
130 tificates. If you want to use that directory for validation pur‐
131 poses, and that directory is not ca/, then use this option to
132 point IO::Socket::SSL to the right place to look.
133 SSL_verify_mode
135 This option sets the verification mode for the peer certificate.
136 The default (0x00) does no authentication. You may combine 0x01
137 (verify peer), 0x02 (fail verification if no peer certificate
138 exists; ignored for clients), and 0x04 (verify client once) to
139 change the default.
140 SSL_verify_callback
142 If you want to verify certificates yourself, you can pass a sub
143 reference along with this parameter to do so. When the callback
144 is called, it will be passed: 1) a true/false value that indi‐
145 cates what OpenSSL thinks of the certificate, 2) a C-style memory
146 address of the certificate store, 3) a string containing the cer‐
147 tificate's issuer attributes and owner attributes, and 4) a
148 string containing any errors encountered (0 if no errors). The
149 function should return 1 or 0, depending on whether it thinks the
150 certificate is valid or invalid. The default is to let OpenSSL
151 do all of the busy work.
152 SSL_check_crl
154 If you want to verify that the peer certificate has not been
155 revoked by the signing authority, set this value to true.
156 OpenSSL will search for the CRL in your SSL_ca_path. See the
157 Net::SSLeay documentation for more details. Note that this func‐
158 tionality appears to be broken with OpenSSL < v0.9.7b, so its use
159 with lower versions will result in an error.
160 SSL_reuse_ctx
162 If you have already set the above options (SSL_version through
163 SSL_check_crl; this does not include SSL_cipher_list yet) for a
164 previous instance of IO::Socket::SSL, then you can reuse the SSL
165 context of that instance by passing it as the value for the
166 SSL_reuse_ctx parameter. You may also create a new instance of
167 the IO::Socket::SSL::SSL_Context class, using any context options
168 that you desire without specifying connection options, and pass
169 that here instead.
170 If you use this option, all other context-related options that
172 you pass in the same call to new() will be ignored unless the
173 context supplied was invalid. Note that, contrary to versions of
174 IO::Socket::SSL below v0.90, a global SSL context will not be
175 implicitly used unless you use the set_default_context() func‐
176 tion.
177 SSL_session_cache_size
179 If you make repeated connections to the same host/port and the
180 SSL renegotiation time is an issue, you can turn on client-side
181 session caching with this option by specifying a positive cache
182 size. For successive connections, pass the SSL_reuse_ctx option
183 to the new() calls (or use set_default_context()) to make use of
184 the cached sessions. The session cache size refers to the number
185 of unique host/port pairs that can be stored at one time; the
186 oldest sessions in the cache will be removed if new ones are
187 added.
188 SSL_error_trap
190 When using the accept() or connect() methods, it may be the case
191 that the actual socket connection works but the SSL negotiation
192 fails, as in the case of an HTTP client connecting to an HTTPS
193 server. Passing a subroutine ref attached to this parameter
194 allows you to gain control of the orphaned socket instead of hav‐
195 ing it be closed forcibly. The subroutine, if called, will be
196 passed two parameters: a reference to the socket on which the SSL
197 negotiation failed and and the full text of the error message.
198 close(...)
200 There are a number of nasty traps that lie in wait if you are not
201 careful about using close(). The first of these will bite you if
202 you have been using shutdown() on your sockets. Since the SSL pro‐
203 tocol mandates that a SSL "close notify" message be sent before the
204 socket is closed, a shutdown() that closes the socket's write chan‐
205 nel will cause the close() call to hang. For a similar reason, if
206 you try to close a copy of a socket (as in a forking server) you
207 will affect the original socket as well. To get around these prob‐
208 lems, call close with an object-oriented syntax (e.g.
209 $socket->close(SSL_no_shutdown => 1)) and one or more of the fol‐
210 lowing parameters:
211 SSL_no_shutdown
213 If set to a true value, this option will make close() not use the
214 SSL_shutdown() call on the socket in question so that the close
215 operation can complete without problems if you have used shut‐
216 down() or are working on a copy of a socket.
217 SSL_ctx_free
219 If you want to make sure that the SSL context of the socket is
220 destroyed when you close it, set this option to a true value.
221 peek(...)
223 This function has exactly the same syntax as sysread(), and per‐
224 forms nearly the same task (reading data from the socket) but will
225 not advance the read position so that successive calls to peek()
226 with the same arguments will return the same results. This func‐
227 tion requires OpenSSL 0.9.6a or later to work.
228 pending()
230 This function will let you know how many bytes of data are immedi‐
231 ately ready for reading from the socket. This is especially handy
232 if you are doing reads on a blocking socket or just want to know if
233 new data has been sent over the socket.
234 get_cipher()
236 Returns the string form of the cipher that the IO::Socket::SSL
237 object is using.
238 dump_peer_certificate()
240 Returns a parsable string with select fields from the peer SSL cer‐
241 tificate. This method directly returns the result of the
242 dump_peer_certificate() method of Net::SSLeay.
243 peer_certificate($field)
245 If a peer certificate exists, this function can retrieve values
246 from it. Right now, the only fields it can return are "authority"
247 and "owner" (or "issuer" and "subject" if you want to use OpenSSL
248 names), corresponding to the certificate authority that signed the
249 peer certificate and the owner of the peer certificate. This func‐
250 tion returns a string with all the information about the particular
251 field in one parsable line. If no field is given it returns the
252 full certificate (x509).
253 errstr()
255 Returns the last error (in string form) that occurred. If you do
256 not have a real object to perform this method on, call
257 IO::Socket::SSL::errstr() instead.
258 For read and write errors on non-blocking sockets, this method may
260 include the string "SSL wants a read first!" or "SSL wants a write
261 first!" meaning that the other side is expecting to read from or
262 write to the socket and wants to be satisfied before you get to do
263 anything. But with version 0.98 you are better comparing the global
264 exported variable $SSL_ERROR against the exported symbols
265 SSL_WANT_READ and SSL_WANT_WRITE.
266 IO::Socket::SSL->start_SSL($socket, ... )
268 This will convert a glob reference or a socket that you provide to
269 an IO::Socket::SSL object. You may also pass parameters to specify
270 context or connection options as with a call to new(). If you are
271 using this function on an accept()ed socket, you must set the
272 parameter "SSL_server" to 1, i.e.
273 IO::Socket::SSL->start_SSL($socket, SSL_server => 1). If you have
274 a class that inherits from IO::Socket::SSL and you want the $socket
275 to be blessed into your own class instead, use
276 MyClass->start_SSL($socket) to achieve the desired effect.
277 Note that if start_SSL() fails in SSL negotiation, $socket will
279 remain blessed in its original class. For non-blocking sockets you
280 better just upgrade the socket to IO::Socket::SSL and call
281 accept_SSL or connect_SSL and the upgraded object. To just upgrade
282 the socket set SSL_startHandshake explicitly to 0. If you call
283 start_SSL w/o this parameter it will revert to blocking behavior
284 for accept_SSL and connect_SSL.
285 IO::Socket::SSL->new_from_fd($fd, ...)
287 This will convert a socket identified via a file descriptor into an
288 SSL socket. Note that the argument list does not include a "MODE"
289 argument; if you supply one, it will be thoughtfully ignored (for
290 compatibility with IO::Socket::INET). Instead, a mode of '+<' is
291 assumed, and the file descriptor passed must be able to handle such
292 I/O because the initial SSL handshake requires bidirectional commu‐
293 nication.
294 IO::Socket::SSL::set_default_context(...)
296 You may use this to make IO::Socket::SSL automatically re-use a
297 given context (unless specifically overridden in a call to new()).
298 It accepts one argument, which should be either an IO::Socket::SSL
299 object or an IO::Socket::SSL::SSL_Context object. See the SSL_re‐
300 use_ctx option of new() for more details. Note that this sets the
301 default context globally, so use with caution (esp. in mod_perl
302 scripts).
303 The following methods are unsupported (not to mention futile!) and
305 IO::Socket::SSL will emit a large CROAK() if you are silly enough to
306 use them:
307 truncate
309 stat
310 ungetc
311 setbuf
312 setvbuf
313 fdopen
314 send/recv
315 Note that send() and recv() cannot be reliably trapped by a tied
316 filehandle (such as that used by IO::Socket::SSL) and so may send
317 unencrypted data over the socket. Object-oriented calls to these
318 functions will fail, telling you to use the print/printf/syswrite
319 and read/sysread families instead.
320
322 A few changes have gone into IO::Socket::SSL v0.93 and later with
323 respect to return values. The behavior on success remains unchanged,
324 but for all functions, the return value on error is now an empty list.
325 Therefore, the return value will be false in all contexts, but those
326 who have been using the return values as arguments to subroutines (like
327 "mysub(IO::Socket::SSL(...)-"new, ...)>) may run into problems. The
328 moral of the story: always check the return values of these functions
329 before using them in any way that you consider meaningful.
330
332 Support for IPv6 with IO::Socket::SSL is expected to work, but is
333 experimental, as none of the author's machines use IPv6 and hence he
334 cannot test IO::Socket::SSL with them. However, a few brave people
335 have used it without incident, so if you wish to make IO::Socket::SSL
336 IPv6 aware, pass the 'inet6' option to IO::Socket::SSL when calling it
337 (i.e. "use IO::Socket::SSL qw(inet6);"). You will need
338 IO::Socket::INET6 and Socket6 to use this option, and you will also
339 need to write "use Socket6;" before using IO::Socket::SSL. If you
340 absolutely do not want to use this (or want a quick change back to
341 IPv4), pass the 'inet4' option instead.
342 Currently, there is no support for using IPv4 and IPv6 simultaneously
344 in a single program, but it is planned for a future release.
345
347 If you are having problems using IO::Socket::SSL despite the fact that
348 can recite backwards the section of this documentation labelled 'Using
349 SSL', you should try enabling debugging. To specify the debug level,
350 pass 'debug#' (where # is a number from 0 to 4) to IO::Socket::SSL when
351 calling it:
352 use IO::Socket::SSL qw(debug0);
354 #No debugging (default).
355 use IO::Socket::SSL qw(debug1);
357 #Only print out errors.
358 use IO::Socket::SSL qw(debug2);
360 #Print out errors and cipher negotiation.
361 use IO::Socket::SSL qw(debug3);
363 #Print out progress, ciphers, and errors.
364 use IO::Socket::SSL qw(debug4);
366 #Print out everything, including data.
367 You can also set $IO::Socket::SSL::DEBUG to 0-4, but that's a bit of a
369 mouthful, isn't it?
370
372 See the 'example' directory.
373
375 IO::Socket::SSL is not threadsafe. This is because IO::Socket::SSL is
376 based on Net::SSLeay which uses a global object to access some of the
377 API of openssl and is therefore not threadsafe.
378 IO::Socket::SSL does not work together with
380 Storable::fd_retrieve/fd_store. See BUGS file for more information and
381 how to work around the problem.
382
384 IO::Socket::SSL uses Net::SSLeay as the shiny interface to OpenSSL,
385 which is the shiny interface to the ugliness of SSL. As a result, you
386 will need both Net::SSLeay and OpenSSL on your computer before using
387 this module.
388 If you have Scalar::Util (standard with Perl 5.8.0 and above) or
390 WeakRef, IO::Socket::SSL sockets will auto-close when they go out of
391 scope, just like IO::Socket::INET sockets. If you do not have one of
392 these modules, then IO::Socket::SSL sockets will stay open until the
393 program ends or you explicitly close them. This is due to the fact
394 that a circular reference is required to make IO::Socket::SSL sockets
395 act simultaneously like objects and glob references.
396
398 The following functions are deprecated and are only retained for com‐
399 patibility:
400 context_init()
402 use the SSL_reuse_ctx option if you want to re-use a context
403 socketToSSL() and socket_to_SSL()
405 use IO::Socket::SSL->start_SSL() instead
406 get_peer_certificate()
408 use the peer_certificate() function instead. Used to return
409 X509_Certificate with methods subject_name and issuer_name. Now sim‐
410 ply returns $self which has these methods (although depreceated).
411 issuer_name()
413 use peer_certificate( 'issuer' ) instead
414 subject_name()
416 use peer_certificate( 'subject' ) instead
417 The following classes have been removed:
419 SSL_SSL
421 (not that you should have been directly accessing this anyway):
422 X509_Certificate
424 (but get_peer_certificate() will still Do The Right Thing)
425
427 IO::Socket::INET, IO::Socket::INET6, Net::SSLeay.
428
430 Steffen Ullrich, <steffen at genua.de> is the current maintainer.
431 Peter Behroozi, <behrooz at fas.harvard.edu> (Note the lack of an "i"
433 at the end of "behrooz")
434 Marko Asplund, <marko.asplund at kronodoc.fi>, was the original author
436 of IO::Socket::SSL.
437 Patches incorporated from various people, see file Changes.
439
441 Working support for non-blocking was added by Steffen Ullrich.
442 The rewrite of this module is Copyright (C) 2002-2005 Peter Behroozi.
444 The original versions of this module are Copyright (C) 1999-2002 Marko
446 Asplund.
447 This module is free software; you can redistribute it and/or modify it
449 under the same terms as Perl itself.
450
452 If you are unfamiliar with the way OpenSSL works, good references may
453 be found in both the book "Network Security with OpenSSL" (Oreilly &
454 Assoc.) and the web site <http://www.tldp.org/HOWTO/SSL-Certifi‐
455 cates-HOWTO/>. Read on for a quick overview.
456 The Long of It (Detail)
458 The usual reason for using SSL is to keep your data safe. This means
460 that not only do you have to encrypt the data while it is being trans‐
461 ported over a network, but you also have to make sure that the right
462 person gets the data. To accomplish this with SSL, you have to use
463 certificates. A certificate closely resembles a Government-issued ID
464 (at least in places where you can trust them). The ID contains some
465 sort of identifying information such as a name and address, and is usu‐
466 ally stamped with a seal of Government Approval. Theoretically, this
467 means that you may trust the information on the card and do business
468 with the owner of the card. The same ideas apply to SSL certificates,
469 which have some identifying information and are "stamped" [most people
470 refer to this as signing instead] by someone (a Certificate Authority)
471 who you trust will adequately verify the identifying information. In
472 this case, because of some clever number theory, it is extremely diffi‐
473 cult to falsify the stamping process. Another useful consequence of
474 number theory is that the certificate is linked to the encryption
475 process, so you may encrypt data (using information on the certificate)
476 that only the certificate owner can decrypt.
477 What does this mean for you? It means that at least one person in the
479 party has to have an ID to get drinks :-). Seriously, it means that
480 one of the people communicating has to have a certificate to ensure
481 that your data is safe. For client/server interactions, the server
482 must always have a certificate. If the server wants to verify that the
483 client is safe, then the client must also have a personal certificate.
484 To verify that a certificate is safe, one compares the stamped "seal"
485 [commonly called an encrypted digest/hash/signature] on the certificate
486 with the official "seal" of the Certificate Authority to make sure that
487 they are the same. To do this, you will need the [unfortunately named]
488 certificate of the Certificate Authority. With all these in hand, you
489 can set up a SSL connection and be reasonably confident that no-one is
490 reading your data.
491 The Short of It (Summary)
493 For servers, you will need to generate a cryptographic private key and
495 a certificate request. You will need to send the certificate request
496 to a Certificate Authority to get a real certificate back, after which
497 you can start serving people. For clients, you will not need anything
498 unless the server wants validation, in which case you will also need a
499 private key and a real certificate. For more information about how to
500 get these, see <http://www.modssl.org/docs/2.8/ssl_faq.html#ToC24>.
501perl v5.8.8 2006-12-02 SSL(3)