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 strict;
11 use IO::Socket::SSL;
12 my $client = IO::Socket::SSL->new("www.example.com:https")
14 || warn "I encountered a problem: ".IO::Socket::SSL::errstr();
15 $client->verify_hostname( 'www.example.com','http' )
16 || die "hostname verification failed";
17 print $client "GET / HTTP/1.0\r\n\r\n";
19 print <$client>;
20
22 This module is a true drop-in replacement for IO::Socket::INET that
23 uses SSL to encrypt data before it is transferred to a remote server or
24 client. IO::Socket::SSL supports all the extra features that one
25 needs to write a full-featured SSL client or server application:
26 multiple SSL contexts, cipher selection, certificate verification, and
27 SSL version selection. As an extra bonus, it works perfectly with
28 mod_perl.
29 If you have never used SSL before, you should read the appendix
31 labelled 'Using SSL' before attempting to use this module.
32 If you have used this module before, read on, as versions 0.93 and
34 above have several changes from the previous IO::Socket::SSL versions
35 (especially see the note about return values).
36 If you are using non-blocking sockets read on, as version 0.98 added
38 better support for non-blocking.
39 If you are trying to use it with threads see the BUGS section.
41
43 IO::Socket::SSL inherits its methods from IO::Socket::INET, overriding
44 them as necessary. If there is an SSL error, the method or operation
45 will return an empty list (false in all contexts). The methods
46 that have changed from the perspective of the user are re-documented
47 here:
48 new(...)
50 Creates a new IO::Socket::SSL object. You may use all the friendly
51 options that came bundled with IO::Socket::INET, plus (optionally)
52 the ones that follow:
53 SSL_version
55 Sets the version of the SSL protocol used to transmit data.
56 'SSLv23' uses a handshake compatible with SSL2.0, SSL3.0, and
57 TLS1.x, while 'SSLv2', 'SSLv3', 'TLSv1', 'TLSv1_1', or 'TLSv1_2'
58 restrict handshake and protocol to the specified version. All
59 values are case-insensitive. Instead of 'TLSv1_1' and 'TLSv1_2'
60 one can also use 'TLSv11' and 'TLSv12'. Support for 'TLSv1_1'
61 and 'TLSv1_2' requires recent versions of Net::SSLeay and
62 openssl.
63 SSL_cipher_list
65 If this option is set the cipher list for the connection will be
66 set to the given value, e.g. something like 'ALL:!LOW:!EXP:!ADH'.
67 Look into the OpenSSL documentation
68 (<http://www.openssl.org/docs/apps/ciphers.html#CIPHER_STRINGS>)
69 for more details. If this option is not used the openssl builtin
70 default is used which is suitable for most cases.
71 SSL_use_cert
73 If this is set, it forces IO::Socket::SSL to use a certificate
74 and key, even if you are setting up an SSL client. If this is
75 set to 0 (the default), then you will only need a certificate and
76 key if you are setting up a server.
77 SSL_use_cert will implicitly be set if SSL_server is set. For
79 convinience it is also set if it was not given but a cert was
80 given for use (SSL_cert_file or similar).
81 SSL_server
83 Use this, if the socket should be used as a server. If this is
84 not explicitly set it is assumed, if Listen with given when
85 creating the socket.
86 SSL_key_file
88 If your RSA private key is not in default place
89 (certs/server-key.pem for servers, certs/client-key.pem for
90 clients), then this is the option that you would use to specify a
91 different location. Keys should be PEM formatted, and if they
92 are encrypted, you will be prompted to enter a password before
93 the socket is formed (unless you specified the SSL_passwd_cb
94 option).
95 SSL_key
97 This is an EVP_PKEY* and can be used instead of SSL_key_file.
98 Useful if you don't have your key in a file but create it
99 dynamically or get it from a string (see openssl
100 PEM_read_bio_PrivateKey etc for getting a EVP_PKEY* from a
101 string).
102 SSL_cert_file
104 If your SSL certificate is not in the default place
105 (certs/server-cert.pem for servers, certs/client-cert.pem for
106 clients), then you should use this option to specify the location
107 of your certificate. Note that a key and certificate are only
108 required for an SSL server, so you do not need to bother with
109 these trifling options should you be setting up an
110 unauthenticated client.
111 SSL_cert
113 This is an X509* or an array of X509*. The first X509* is the
114 internal representation of the certificate while the following
115 ones are extra certificates. Useful if you create your
116 certificate dynamically (like in a SSL intercepting proxy) or get
117 it from a string (see openssl PEM_read_bio_X509 etc for getting a
118 X509* from a string).
119 SSL_dh_file
121 If you want Diffie-Hellman key exchange you need to supply a
122 suitable file here or use the SSL_dh parameter. See dhparam
123 command in openssl for more information. To create a server
124 which provides perfect forward secrecy you need to either give
125 the DH parameters or (better, because faster) the ECDH curve.
126 SSL_dh
128 Like SSL_dh_file, but instead of giving a file you use a
129 preloaded or generated DH*.
130 SSL_ecdh_curve
132 If you want Elliptic Curve Diffie-Hellmann key exchange you need
133 to supply the OID or NID of a suitable curve (like 'prime256v1')
134 here. To create a server which provides perfect forward secrecy
135 you need to either give the DH parameters or (better, because
136 faster) the ECDH curve.
137 SSL_passwd_cb
139 If your private key is encrypted, you might not want the default
140 password prompt from Net::SSLeay. This option takes a reference
141 to a subroutine that should return the password required to
142 decrypt your private key.
143 SSL_ca_file
145 If you want to verify that the peer certificate has been signed
146 by a reputable certificate authority, then you should use this
147 option to locate the file containing the certificate(s) of the
148 reputable certificate authorities if it is not already in the
149 file certs/my-ca.pem.
150 SSL_ca_path
152 If you are unusually friendly with the OpenSSL documentation, you
153 might have set yourself up a directory containing several trusted
154 certificates as separate files as well as an index of the
155 certificates. If you want to use that directory for validation
156 purposes, and that directory is not ca/, then use this option to
157 point IO::Socket::SSL to the right place to look.
158 SSL_verify_mode
160 This option sets the verification mode for the peer certificate.
161 The default (0x00) does no authentication. You may combine
162 0x01 (verify peer), 0x02 (fail verification if no peer
163 certificate exists; ignored for clients), and 0x04 (verify client
164 once) to change the default. See OpenSSL man page for
165 SSL_CTX_set_verify for more information.
166 SSL_verify_callback
168 If you want to verify certificates yourself, you can pass a sub
169 reference along with this parameter to do so. When the callback
170 is called, it will be passed: 1) a true/false value that
171 indicates what OpenSSL thinks of the certificate, 2) a C-style
172 memory address of the certificate store, 3) a string containing
173 the certificate's issuer attributes and owner attributes, and 4)
174 a string containing any errors encountered (0 if no errors). The
175 function should return 1 or 0, depending on whether it thinks the
176 certificate is valid or invalid. The default is to let OpenSSL
177 do all of the busy work.
178 SSL_verifycn_scheme
180 Set the scheme used to automatically verify the hostname of the
181 peer. See the information about the verification schemes in
182 verify_hostname. The default is undef, e.g. to not automatically
183 verify the hostname.
184 SSL_verifycn_name
186 Set the name which is used in verification of hostname. If
187 SSL_verifycn_scheme is set and no SSL_verifycn_name is given it
188 will try to use the PeerHost and PeerAddr settings and fail if no
189 name caan be determined.
190 Using PeerHost or PeerAddr works only if you create the
192 connection directly with "IO::Socket::SSL->new", if an
193 IO::Socket::INET object is upgraded with start_SSL the name has
194 to be given in SSL_verifycn_name.
195 SSL_check_crl
197 If you want to verify that the peer certificate has not been
198 revoked by the signing authority, set this value to true. OpenSSL
199 will search for the CRL in your SSL_ca_path, or use the file
200 specified by SSL_crl_file. See the Net::SSLeay documentation for
201 more details. Note that this functionality appears to be broken
202 with OpenSSL < v0.9.7b, so its use with lower versions will
203 result in an error.
204 SSL_crl_file
206 If you want to specify the CRL file to be used, set this value to
207 the pathname to be used. This must be used in addition to
208 setting SSL_check_crl.
209 SSL_reuse_ctx
211 If you have already set the above options (SSL_version through
212 SSL_check_crl; this does not include SSL_cipher_list yet) for a
213 previous instance of IO::Socket::SSL, then you can reuse the SSL
214 context of that instance by passing it as the value for the
215 SSL_reuse_ctx parameter. You may also create a new instance of
216 the IO::Socket::SSL::SSL_Context class, using any context options
217 that you desire without specifying connection options, and pass
218 that here instead.
219 If you use this option, all other context-related options that
221 you pass in the same call to new() will be ignored unless the
222 context supplied was invalid. Note that, contrary to versions of
223 IO::Socket::SSL below v0.90, a global SSL context will not be
224 implicitly used unless you use the set_default_context()
225 function.
226 SSL_session_cache_size
228 If you make repeated connections to the same host/port and the
229 SSL renegotiation time is an issue, you can turn on client-side
230 session caching with this option by specifying a positive cache
231 size. For successive connections, pass the SSL_reuse_ctx option
232 to the new() calls (or use set_default_context()) to make use of
233 the cached sessions. The session cache size refers to the number
234 of unique host/port pairs that can be stored at one time; the
235 oldest sessions in the cache will be removed if new ones are
236 added.
237 SSL_session_cache
239 Specifies session cache object which should be used instead of
240 creating a new. Overrules SSL_session_cache_size. This option
241 is useful if you want to reuse the cache, but not the rest of the
242 context.
243 A session cache object can be created using
245 "IO::Socket::SSL::Session_Cache->new( cachesize )".
246 Use set_default_session_cache() to set a global cache object.
248 SSL_error_trap
250 When using the accept() or connect() methods, it may be the case
251 that the actual socket connection works but the SSL negotiation
252 fails, as in the case of an HTTP client connecting to an HTTPS
253 server. Passing a subroutine ref attached to this parameter
254 allows you to gain control of the orphaned socket instead of
255 having it be closed forcibly. The subroutine, if called, will be
256 passed two parameters: a reference to the socket on which the SSL
257 negotiation failed and and the full text of the error message.
258 close(...)
260 There are a number of nasty traps that lie in wait if you are not
261 careful about using close(). The first of these will bite you if
262 you have been using shutdown() on your sockets. Since the SSL
263 protocol mandates that a SSL "close notify" message be sent before
264 the socket is closed, a shutdown() that closes the socket's write
265 channel will cause the close() call to hang. For a similar reason,
266 if you try to close a copy of a socket (as in a forking server) you
267 will affect the original socket as well. To get around these
268 problems, call close with an object-oriented syntax (e.g.
269 $socket->close(SSL_no_shutdown => 1)) and one or more of the
270 following parameters:
271 SSL_no_shutdown
273 If set to a true value, this option will make close() not use the
274 SSL_shutdown() call on the socket in question so that the close
275 operation can complete without problems if you have used
276 shutdown() or are working on a copy of a socket.
277 SSL_fast_shutdown
279 If set to true only a unidirectional shutdown will be done, e.g.
280 only the close_notify (see SSL_shutdown(3)) will be called.
281 Otherwise a bidrectional shutdown will be done. If used within
282 close() it defaults to true, if used within stop_SSL() it
283 defaults to false.
284 SSL_ctx_free
286 If you want to make sure that the SSL context of the socket is
287 destroyed when you close it, set this option to a true value.
288 peek(...)
290 This function has exactly the same syntax as sysread(), and
291 performs nearly the same task (reading data from the socket) but
292 will not advance the read position so that successive calls to
293 peek() with the same arguments will return the same results. This
294 function requires OpenSSL 0.9.6a or later to work.
295 pending()
297 This function will let you know how many bytes of data are
298 immediately ready for reading from the socket. This is especially
299 handy if you are doing reads on a blocking socket or just want to
300 know if new data has been sent over the socket.
301 get_cipher()
303 Returns the string form of the cipher that the IO::Socket::SSL
304 object is using.
305 dump_peer_certificate()
307 Returns a parsable string with select fields from the peer SSL
308 certificate. This method directly returns the result of the
309 dump_peer_certificate() method of Net::SSLeay.
310 peer_certificate($field)
312 If a peer certificate exists, this function can retrieve values
313 from it. If no field is given the internal representation of
314 certificate from Net::SSLeay is returned. The following fields can
315 be queried:
316 authority (alias issuer)
318 The certificate authority which signed the certificate.
319 owner (alias subject)
321 The owner of the certificate.
322 commonName (alias cn) - only for Net::SSLeay version >=1.30
324 The common name, usually the server name for SSL
325 certificates.
326 subjectAltNames - only for Net::SSLeay version >=1.33
328 Alternative names for the subject, usually different names
329 for the same server, like example.org, example.com,
330 *.example.com.
331 It returns a list of (typ,value) with typ GEN_DNS,
333 GEN_IPADD etc (these constants are exported from
334 IO::Socket::SSL). See
335 Net::SSLeay::X509_get_subjectAltNames.
336 verify_hostname($hostname,$scheme)
338 This verifies the given hostname against the peer certificate using
339 the given scheme. Hostname is usually what you specify within the
340 PeerAddr.
341 Verification of hostname against a certificate is different between
343 various applications and RFCs. Some scheme allow wildcards for
344 hostnames, some only in subjectAltNames, and even their different
345 wildcard schemes are possible.
346 To ease the verification the following schemes are predefined:
348 ldap (rfc4513), pop3,imap,acap (rfc2995), nntp (rfc4642)
350 Simple wildcards in subjectAltNames are possible, e.g.
351 *.example.org matches www.example.org but not
352 lala.www.example.org. If nothing from subjectAltNames match
353 it checks against the common name, but there are no
354 wildcards allowed.
355 http (rfc2818), alias is www
357 Extended wildcards in subjectAltNames are possible, e.g.
358 *.example.org or even www*.example.org. Wildcards in the
359 common name are not allowed. The common name will be only
360 checked if no names are given in subjectAltNames.
361 smtp (rfc3207)
363 This RFC doesn't say much useful about the verification so
364 it just assumes that subjectAltNames are possible, but no
365 wildcards are possible anywhere.
366 The scheme can be given either by specifying the name for one of
368 the above predefined schemes, by using a callback (see below) or by
369 using a hash which can have the following keys and values:
370 check_cn: 0|'always'|'when_only'
372 Determines if the common name gets checked. If 'always' it
373 will always be checked (like in ldap), if 'when_only' it
374 will only be checked if no names are given in
375 subjectAltNames (like in http), for any other values the
376 common name will not be checked.
377 wildcards_in_alt: 0|'leftmost'|'anywhere'
379 Determines if and where wildcards in subjectAltNames are
380 possible. If 'leftmost' only cases like *.example.org will
381 be possible (like in ldap), for 'anywhere' www*.example.org
382 is possible too (like http), dangerous things like but
383 www.*.org or even '*' will not be allowed.
384 wildcards_in_cn: 0|'leftmost'|'anywhere'
386 Similar to wildcards_in_alt, but checks the common name.
387 There is no predefined scheme which allows wildcards in
388 common names.
389 If you give a subroutine for verification it will be called with
391 the arguments ($hostname,$commonName,@subjectAltNames), where
392 hostname is the name given for verification, commonName is the
393 result from peer_certificate('cn') and subjectAltNames is the
394 result from peer_certificate('subjectAltNames').
395 errstr()
397 Returns the last error (in string form) that occurred. If you do
398 not have a real object to perform this method on, call
399 IO::Socket::SSL::errstr() instead.
400 For read and write errors on non-blocking sockets, this method may
402 include the string "SSL wants a read first!" or "SSL wants a write
403 first!" meaning that the other side is expecting to read from or
404 write to the socket and wants to be satisfied before you get to do
405 anything. But with version 0.98 you are better comparing the global
406 exported variable $SSL_ERROR against the exported symbols
407 SSL_WANT_READ and SSL_WANT_WRITE.
408 opened()
410 This returns false if the socket could not be opened, 1 if the
411 socket could be opened and the SSL handshake was successful done
412 and -1 if the underlying IO::Handle is open, but the SSL handshake
413 failed.
414 IO::Socket::SSL->start_SSL($socket, ... )
416 This will convert a glob reference or a socket that you provide to
417 an IO::Socket::SSL object. You may also pass parameters to
418 specify context or connection options as with a call to new(). If
419 you are using this function on an accept()ed socket, you must set
420 the parameter "SSL_server" to 1, i.e.
421 IO::Socket::SSL->start_SSL($socket, SSL_server => 1). If you have
422 a class that inherits from IO::Socket::SSL and you want the $socket
423 to be blessed into your own class instead, use
424 MyClass->start_SSL($socket) to achieve the desired effect.
425 Note that if start_SSL() fails in SSL negotiation, $socket will
427 remain blessed in its original class. For non-blocking sockets
428 you better just upgrade the socket to IO::Socket::SSL and call
429 accept_SSL or connect_SSL and the upgraded object. To just upgrade
430 the socket set SSL_startHandshake explicitly to 0. If you call
431 start_SSL w/o this parameter it will revert to blocking behavior
432 for accept_SSL and connect_SSL.
433 If given the parameter "Timeout" it will stop if after the timeout
435 no SSL connection was established. This parameter is only used for
436 blocking sockets, if it is not given the default Timeout from the
437 underlying IO::Socket will be used.
438 stop_SSL(...)
440 This is the opposite of start_SSL(), e.g. it will shutdown the SSL
441 connection and return to the class before start_SSL(). It gets the
442 same arguments as close(), in fact close() calls stop_SSL() (but
443 without downgrading the class).
444 Will return true if it suceeded and undef if failed. This might be
446 the case for non-blocking sockets. In this case $! is set to EAGAIN
447 and the ssl error to SSL_WANT_READ or SSL_WANT_WRITE. In this case
448 the call should be retried again with the same arguments once the
449 socket is ready is until it succeeds.
450 IO::Socket::SSL->new_from_fd($fd, ...)
452 This will convert a socket identified via a file descriptor into an
453 SSL socket. Note that the argument list does not include a "MODE"
454 argument; if you supply one, it will be thoughtfully ignored (for
455 compatibility with IO::Socket::INET). Instead, a mode of '+<' is
456 assumed, and the file descriptor passed must be able to handle such
457 I/O because the initial SSL handshake requires bidirectional
458 communication.
459 IO::Socket::SSL::set_default_context(...)
461 You may use this to make IO::Socket::SSL automatically re-use a
462 given context (unless specifically overridden in a call to new()).
463 It accepts one argument, which should be either an IO::Socket::SSL
464 object or an IO::Socket::SSL::SSL_Context object. See the
465 SSL_reuse_ctx option of new() for more details. Note that this
466 sets the default context globally, so use with caution (esp. in
467 mod_perl scripts).
468 IO::Socket::SSL::set_default_session_cache(...)
470 You may use this to make IO::Socket::SSL automatically re-use a
471 given session cache (unless specifically overridden in a call to
472 new()). It accepts one argument, which should be an
473 IO::Socket::SSL::Session_Cache object or similar (e.g something
474 which implements get_session and add_session like
475 IO::Socket::SSL::Session_Cache does). See the SSL_session_cache
476 option of new() for more details. Note that this sets the default
477 cache globally, so use with caution.
478 IO::Socket::SSL::set_ctx_defaults(%args)
480 With this function one can set defaults for all SSL_* parameter
481 used for creation of the context, like the SSL_verify* parameter.
482 mode - set default SSL_verify_mode
484 callback - set default SSL_verify_callback
485 scheme - set default SSL_verifycn_scheme
486 name - set default SSL_verifycn_name
487 If not given and scheme is hash reference with key callback
488 it will be set to 'unknown'
489 The following methods are unsupported (not to mention futile!) and
491 IO::Socket::SSL will emit a large CROAK() if you are silly enough to
492 use them:
493 truncate
495 stat
496 ungetc
497 setbuf
498 setvbuf
499 fdopen
500 send/recv
501 Note that send() and recv() cannot be reliably trapped by a tied
502 filehandle (such as that used by IO::Socket::SSL) and so may send
503 unencrypted data over the socket. Object-oriented calls to these
504 functions will fail, telling you to use the print/printf/syswrite
505 and read/sysread families instead.
506
508 Support for IPv6 with IO::Socket::SSL is expected to work and basic
509 testing is done. If IO::Socket::INET6 is available it will
510 automatically use it instead of IO::Socket::INET4.
511 Please be aware of the associated problems: If you give a name as a
513 host and the host resolves to both IPv6 and IPv4 it will try IPv6 first
514 and if there is no IPv6 connectivity it will fail.
515 To avoid these problems you can either force IPv4 by specifying and
517 AF_INET as the Domain (this is per socket) or load IO::Socket::SSL with
518 the option 'inet4' (This is a global setting, e.g. affects all
519 IO::Socket::SSL objects in the program).
520
522 A few changes have gone into IO::Socket::SSL v0.93 and later with
523 respect to return values. The behavior on success remains unchanged,
524 but for all functions, the return value on error is now an empty
525 list. Therefore, the return value will be false in all contexts, but
526 those who have been using the return values as arguments to subroutines
527 (like "mysub(IO::Socket::SSL(...)-"new, ...)>) may run into problems.
528 The moral of the story: always check the return values of these
529 functions before using them in any way that you consider meaningful.
530
532 If you are having problems using IO::Socket::SSL despite the fact that
533 can recite backwards the section of this documentation labelled 'Using
534 SSL', you should try enabling debugging. To specify the debug level,
535 pass 'debug#' (where # is a number from 0 to 3) to IO::Socket::SSL when
536 calling it. The debug level will also be propagated to
537 Net::SSLeay::trace, see also Net::SSLeay:
538 use IO::Socket::SSL qw(debug0);
540 No debugging (default).
541 use IO::Socket::SSL qw(debug1);
543 Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.
544 use IO::Socket::SSL qw(debug2);
546 Print also information about call flow from IO::Socket::SSL and
547 progress information from Net::SSLeay.
548 use IO::Socket::SSL qw(debug3);
550 Print also some data dumps from IO::Socket::SSL and from
551 Net::SSLeay.
552
554 See the 'example' directory.
555
557 IO::Socket::SSL is not threadsafe. This is because IO::Socket::SSL is
558 based on Net::SSLeay which uses a global object to access some of the
559 API of openssl and is therefore not threadsafe. It might probably work
560 if you don't use SSL_verify_callback and SSL_password_cb.
561 IO::Socket::SSL does not work together with
563 Storable::fd_retrieve/fd_store. See BUGS file for more information and
564 how to work around the problem.
565 Non-blocking and timeouts (which are based on non-blocking) are not
567 supported on Win32, because the underlying IO::Socket::INET does not
568 support non-blocking on this platform.
569
571 IO::Socket::SSL uses Net::SSLeay as the shiny interface to OpenSSL,
572 which is the shiny interface to the ugliness of SSL. As a result, you
573 will need both Net::SSLeay and OpenSSL on your computer before using
574 this module.
575 If you have Scalar::Util (standard with Perl 5.8.0 and above) or
577 WeakRef, IO::Socket::SSL sockets will auto-close when they go out of
578 scope, just like IO::Socket::INET sockets. If you do not have one
579 of these modules, then IO::Socket::SSL sockets will stay open until the
580 program ends or you explicitly close them. This is due to the fact
581 that a circular reference is required to make IO::Socket::SSL sockets
582 act simultaneously like objects and glob references.
583
585 The following functions are deprecated and are only retained for
586 compatibility:
587 context_init()
589 use the SSL_reuse_ctx option if you want to re-use a context
590 socketToSSL() and socket_to_SSL()
592 use IO::Socket::SSL->start_SSL() instead
593 get_peer_certificate()
595 use the peer_certificate() function instead. Used to return
596 X509_Certificate with methods subject_name and issuer_name. Now
597 simply returns $self which has these methods (although depreceated).
598 issuer_name()
600 use peer_certificate( 'issuer' ) instead
601 subject_name()
603 use peer_certificate( 'subject' ) instead
604 The following classes have been removed:
606 SSL_SSL
608 (not that you should have been directly accessing this anyway):
609 X509_Certificate
611 (but get_peer_certificate() will still Do The Right Thing)
612
614 IO::Socket::INET, IO::Socket::INET6, Net::SSLeay.
615
617 Steffen Ullrich, <steffen at genua.de> is the current maintainer.
618 Peter Behroozi, <behrooz at fas.harvard.edu> (Note the lack of an "i"
620 at the end of "behrooz")
621 Marko Asplund, <marko.asplund at kronodoc.fi>, was the original author
623 of IO::Socket::SSL.
624 Patches incorporated from various people, see file Changes.
626
628 Working support for non-blocking was added by Steffen Ullrich.
629 The rewrite of this module is Copyright (C) 2002-2005 Peter Behroozi.
631 The original versions of this module are Copyright (C) 1999-2002 Marko
633 Asplund.
634 This module is free software; you can redistribute it and/or modify it
636 under the same terms as Perl itself.
637
639 If you are unfamiliar with the way OpenSSL works, good references may
640 be found in both the book "Network Security with OpenSSL" (Oreilly &
641 Assoc.) and the web site
642 <http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/>. Read on for a
643 quick overview.
644 The Long of It (Detail)
646 The usual reason for using SSL is to keep your data safe. This means
647 that not only do you have to encrypt the data while it is being
648 transported over a network, but you also have to make sure that the
649 right person gets the data. To accomplish this with SSL, you have to
650 use certificates. A certificate closely resembles a Government-issued
651 ID (at least in places where you can trust them). The ID contains
652 some sort of identifying information such as a name and address, and is
653 usually stamped with a seal of Government Approval. Theoretically,
654 this means that you may trust the information on the card and do
655 business with the owner of the card. The same ideas apply to SSL
656 certificates, which have some identifying information and are "stamped"
657 [most people refer to this as signing instead] by someone (a
658 Certificate Authority) who you trust will adequately verify the
659 identifying information. In this case, because of some clever number
660 theory, it is extremely difficult to falsify the stamping
661 process. Another useful consequence of number theory is that the
662 certificate is linked to the encryption process, so you may encrypt
663 data (using information on the certificate) that only the certificate
664 owner can decrypt.
665 What does this mean for you? It means that at least one person in the
667 party has to have an ID to get drinks :-). Seriously, it means that
668 one of the people communicating has to have a certificate to ensure
669 that your data is safe. For client/server interactions, the server
670 must always have a certificate. If the server wants to verify that
671 the client is safe, then the client must also have a personal
672 certificate. To verify that a certificate is safe, one compares the
673 stamped "seal" [commonly called an encrypted digest/hash/signature] on
674 the certificate with the official "seal" of the Certificate Authority
675 to make sure that they are the same. To do this, you will need the
676 [unfortunately named] certificate of the Certificate Authority. With
677 all these in hand, you can set up a SSL connection and be reasonably
678 confident that no-one is reading your data.
679 The Short of It (Summary)
681 For servers, you will need to generate a cryptographic private key and
682 a certificate request. You will need to send the certificate request
683 to a Certificate Authority to get a real certificate back, after which
684 you can start serving people. For clients, you will not need anything
685 unless the server wants validation, in which case you will also need a
686 private key and a real certificate. For more information about how
687 to get these, see <http://www.modssl.org/docs/2.8/ssl_faq.html#ToC24>.
688perl v5.10.1 2016-11-18 SSL(3)