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