1Net::SSLeay(3) User Contributed Perl Documentation Net::SSLeay(3)
2
6 Net::SSLeay - Perl extension for using OpenSSL
7
9 use Net::SSLeay qw(get_https post_https sslcat make_headers make_form);
10 ($page) = get_https('www.bacus.pt', 443, '/'); # Case 1
12 ($page, $response, %reply_headers)
14 = get_https('www.bacus.pt', 443, '/', # Case 2
15 make_headers(User-Agent => 'Cryptozilla/5.0b1',
16 Referer => 'https://www.bacus.pt'
17 ));
18 ($page, $result, %headers) = # Case 2b
20 = get_https('www.bacus.pt', 443, '/protected.html',
21 make_headers(Authorization =>
22 'Basic ' . MIME::Base64::encode("$user:$pass",''))
23 );
24 ($page, $response, %reply_headers)
26 = post_https('www.bacus.pt', 443, '/foo.cgi', '', # Case 3
27 make_form(OK => '1',
28 name => 'Sampo'
29 ));
30 $reply = sslcat($host, $port, $request); # Case 4
32 ($reply, $err, $server_cert) = sslcat($host, $port, $request); # Case 5
34 $Net::SSLeay::trace = 2; # 0=no debugging, 1=ciphers, 2=trace, 3=dump data
36 Net::SSLeay::initialize(); # Initialize ssl library once
38
40 Net::SSLeay module contains perl bindings to openssl
41 (<http://www.openssl.org>) library.
42 COMPATIBILITY NOTE: Net::SSLeay cannot be built with pre-0.9.3 openssl.
44 It is strongly recommended to use at least 0.9.7 (as older versions are
45 not tested during development). Some low level API functions may be
46 available with certain openssl versions.
47 Net::SSLeay module basically comprise of:
49 · High level functions for accessing web servers (by using
51 HTTP/HTTPS)
52 · Low level API (mostly mapped 1:1 to openssl's C functions)
54 · Convenience functions (related to low level API but with more perl
56 friendly interface)
57 There is also a related module called Net::SSLeay::Handle included in
59 this distribution that you might want to use instead. It has its own
60 pod documentation.
61 High level functions for accessing web servers
63 This module offers some high level convenience functions for accessing
64 web pages on SSL servers (for symmetry, the same API is offered for
65 accessing http servers, too), an "sslcat()" function for writing your
66 own clients, and finally access to the SSL api of the SSLeay/OpenSSL
67 package so you can write servers or clients for more complicated
68 applications.
69 For high level functions it is most convenient to import them into your
71 main namespace as indicated in the synopsis.
72 Basic set of functions
74 · get_https
76 · post_https
78 · put_https
80 · head_https
82 · do_https
84 · sslcat
86 · https_cat
88 · make_form
90 · make_headers
92 Case 1 (in SYNOPSIS) demonstrates the typical invocation of get_https()
94 to fetch an HTML page from secure server. The first argument provides
95 the hostname or IP in dotted decimal notation of the remote server to
96 contact. The second argument is the TCP port at the remote end (your
97 own port is picked arbitrarily from high numbered ports as usual for
98 TCP). The third argument is the URL of the page without the host name
99 part. If in doubt consult the HTTP specifications at
100 <http://www.w3c.org>.
101 Case 2 (in SYNOPSIS) demonstrates full fledged use of "get_https()". As
103 can be seen, "get_https()" parses the response and response headers and
104 returns them as a list, which can be captured in a hash for later
105 reference. Also a fourth argument to "get_https()" is used to insert
106 some additional headers in the request. "make_headers()" is a function
107 that will convert a list or hash to such headers. By default
108 "get_https()" supplies "Host" (to make virtual hosting easy) and
109 "Accept" (reportedly needed by IIS) headers.
110 Case 2b (in SYNOPSIS) demonstrates how to get a password protected
112 page. Refer to the HTTP protocol specifications for further details
113 (e.g. RFC-2617).
114 Case 3 (in SYNOPSIS) invokes "post_https()" to submit a HTML/CGI form
116 to a secure server. The first four arguments are equal to "get_https()"
117 (note that the empty string ('') is passed as header argument). The
118 fifth argument is the contents of the form formatted according to CGI
119 specification. Do not post UTF-8 data as content: use utf8::downgrade
120 first. In this case the helper function "make_https()" is used to do
121 the formatting, but you could pass any string. "post_https()"
122 automatically adds "Content-Type" and "Content-Length" headers to the
123 request.
124 Case 4 (in SYNOPSIS) shows the fundamental "sslcat()" function
126 (inspired in spirit by the "netcat" utility :-). It's your swiss army
127 knife that allows you to easily contact servers, send some data, and
128 then get the response. You are responsible for formatting the data and
129 parsing the response - "sslcat()" is just a transport.
130 Case 5 (in SYNOPSIS) is a full invocation of "sslcat()" which allows
132 the return of errors as well as the server (peer) certificate.
133 The $trace global variable can be used to control the verbosity of the
135 high level functions. Level 0 guarantees silence, level 1 (the default)
136 only emits error messages.
137 Alternate versions of high-level API
139 · get_https3
141 · post_https3
143 · put_https3
145 · get_https4
147 · post_https4
149 · put_https4
151 The above mentioned functions actually return the response headers as a
153 list, which only gets converted to hash upon assignment (this
154 assignment looses information if the same header occurs twice, as may
155 be the case with cookies). There are also other variants of the
156 functions that return unprocessed headers and that return a reference
157 to a hash.
158 ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
160 for ($i = 0; $i < $#headers; $i+=2) {
161 print "$headers[$i] = " . $headers[$i+1] . "\n";
162 }
163 ($page, $response, $headers, $server_cert)
165 = get_https3('www.bacus.pt', 443, '/');
166 print "$headers\n";
167 ($page, $response, $headers_ref)
169 = get_https4('www.bacus.pt', 443, '/');
170 for $k (sort keys %{$headers_ref}) {
171 for $v (@{$$headers_ref{$k}}) {
172 print "$k = $v\n";
173 }
174 }
175 All of the above code fragments accomplish the same thing: display all
177 values of all headers. The API functions ending in "3" return the
178 headers simply as a scalar string and it is up to the application to
179 split them up. The functions ending in "4" return a reference to a hash
180 of arrays (see perlref and perllol if you are not familiar with complex
181 perl data structures). To access a single value of such a header hash
182 you would do something like
183 print $$headers_ref{COOKIE}[0];
185 Variants 3 and 4 also allow you to discover the server certificate in
187 case you would like to store or display it, e.g.
188 ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
190 if (!defined($server_cert) || ($server_cert == 0)) {
191 warn "Subject Name: undefined, Issuer Name: undefined";
192 } else {
193 warn 'Subject Name: '
194 . Net::SSLeay::X509_NAME_oneline(
195 Net::SSLeay::X509_get_subject_name($server_cert))
196 . 'Issuer Name: '
197 . Net::SSLeay::X509_NAME_oneline(
198 Net::SSLeay::X509_get_issuer_name($server_cert));
199 }
200 Beware that this method only allows after the fact verification of the
202 certificate: by the time "get_https3()" has returned the https request
203 has already been sent to the server, whether you decide to trust it or
204 not. To do the verification correctly you must either employ the
205 OpenSSL certificate verification framework or use the lower level API
206 to first connect and verify the certificate and only then send the http
207 data. See the implementation of "ds_https3()" for guidance on how to do
208 this.
209 Using client certificates
211 Secure web communications are encrypted using symmetric crypto keys
213 exchanged using encryption based on the certificate of the server.
214 Therefore in all SSL connections the server must have a certificate.
215 This serves both to authenticate the server to the clients and to
216 perform the key exchange.
217 Sometimes it is necessary to authenticate the client as well. Two
219 options are available: HTTP basic authentication and a client side
220 certificate. The basic authentication over HTTPS is actually quite safe
221 because HTTPS guarantees that the password will not travel in the
222 clear. Never-the-less, problems like easily guessable passwords remain.
223 The client certificate method involves authentication of the client at
224 the SSL level using a certificate. For this to work, both the client
225 and the server have certificates (which typically are different) and
226 private keys.
227 The API functions outlined above accept additional arguments that allow
229 one to supply the client side certificate and key files. The format of
230 these files is the same as used for server certificates and the caveat
231 about encrypting private keys applies.
232 ($page, $result, %headers) = # 2c
234 = get_https('www.bacus.pt', 443, '/protected.html',
235 make_headers(Authorization =>
236 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
237 '', $mime_type6, $path_to_crt7, $path_to_key8);
238 ($page, $response, %reply_headers)
240 = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
241 make_headers('Authorization' =>
242 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
243 make_form(OK => '1', name => 'Sampo'),
244 $mime_type6, $path_to_crt7, $path_to_key8);
245 Case 2c (in SYNOPSIS) demonstrates getting a password protected page
247 that also requires a client certificate, i.e. it is possible to use
248 both authentication methods simultaneously.
249 Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
251 requires both password authentication and a client certificate, just
252 like in case 2c.
253 Note: The client will not send a certificate unless the server requests
255 one. This is typically achieved by setting the verify mode to
256 "VERIFY_PEER" on the server:
257 Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
259 See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
261 description.
262 Working through a web proxy
264 · set_proxy
266 "Net::SSLeay" can use a web proxy to make its connections. You need to
268 first set the proxy host and port using "set_proxy()" and then just use
269 the normal API functions, e.g:
270 Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
272 ($page) = get_https('www.bacus.pt', 443, '/');
273 If your proxy requires authentication, you can supply a username and
275 password as well
276 Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
278 ($page, $result, %headers) =
279 = get_https('www.bacus.pt', 443, '/protected.html',
280 make_headers(Authorization =>
281 'Basic ' . MIME::Base64::encode("susie:pass",''))
282 );
283 This example demonstrates the case where we authenticate to the proxy
285 as "joe" and to the final web server as "susie". Proxy authentication
286 requires the "MIME::Base64" module to work.
287 HTTP (without S) API
289 · get_http
291 · post_http
293 · tcpcat
295 · get_httpx
297 · post_httpx
299 · tcpxcat
301 Over the years it has become clear that it would be convenient to use
303 the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
304 (see "LWP" for the heavy-weight object-oriented approach). In fact it
305 would be nice to be able to flip https on and off on the fly. Thus
306 regular HTTP support was evolved.
307 use Net::SSLeay qw(get_http post_http tcpcat
309 get_httpx post_httpx tcpxcat
310 make_headers make_form);
311 ($page, $result, %headers)
313 = get_http('www.bacus.pt', 443, '/protected.html',
314 make_headers(Authorization =>
315 'Basic ' . MIME::Base64::encode("$user:$pass",''))
316 );
317 ($page, $response, %reply_headers)
319 = post_http('www.bacus.pt', 443, '/foo.cgi', '',
320 make_form(OK => '1',
321 name => 'Sampo'
322 ));
323 ($reply, $err) = tcpcat($host, $port, $request);
325 ($page, $result, %headers)
327 = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
328 make_headers(Authorization =>
329 'Basic ' . MIME::Base64::encode("$user:$pass",''))
330 );
331 ($page, $response, %reply_headers)
333 = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
334 make_form(OK => '1', name => 'Sampo' ));
335 ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
337 As can be seen, the "x" family of APIs takes as the first argument a
339 flag which indicates whether SSL is used or not.
340 Certificate verification and Certificate Revocation Lists (CRLs)
342 OpenSSL supports the ability to verify peer certificates. It can also
343 optionally check the peer certificate against a Certificate Revocation
344 List (CRL) from the certificates issuer. A CRL is a file, created by
345 the certificate issuer that lists all the certificates that it
346 previously signed, but which it now revokes. CRLs are in PEM format.
347 You can enable "Net::SSLeay CRL" checking like this:
349 &Net::SSLeay::X509_STORE_set_flags
351 (&Net::SSLeay::CTX_get_cert_store($ssl),
352 &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
353 After setting this flag, if OpenSSL checks a peer's certificate, then
355 it will attempt to find a CRL for the issuer. It does this by looking
356 for a specially named file in the search directory specified by
357 CTX_load_verify_locations. CRL files are named with the hash of the
358 issuer's subject name, followed by ".r0", ".r1" etc. For example
359 "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
360 issuer, and then check for a revocation of the peer certificate in all
361 of them. (You can also force it to look in a specific named CRL file.,
362 see below). You can find out the hash of the issuer subject name in a
363 CRL with
364 openssl crl -in crl.pem -hash -noout
366 If the peer certificate does not pass the revocation list, or if no CRL
368 is found, then the handshaking fails with an error.
369 You can also force OpenSSL to look for CRLs in one or more arbitrarily
371 named files.
372 my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
374 my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
375 if ($crl) {
376 Net::SSLeay::X509_STORE_add_crl(
377 Net::SSLeay::CTX_get_cert_store($ssl, $crl)
378 );
379 } else {
380 error reading CRL....
381 }
382 Using Net::SSLeay in multi-threaded applications
384 IMPORTANT: versions 1.42 or earlier are not thread-safe!
385 Net::SSLeay module implements all necessary stuff to be ready for
387 multi-threaded environment - it requires openssl-0.9.7 or newer. The
388 implementation fully follows thread safety related requirements of
389 openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
390 If you are about to use Net::SSLeay (or any other module based on
392 Net::SSLeay) in multi-threaded perl application it is recommended to
393 follow this best-practice:
394 Initialization
396 Load and initialize Net::SSLeay module in the main thread:
398 use threads;
400 use Net::SSLeay;
401 Net::SSLeay::load_error_strings();
403 Net::SSLeay::SSLeay_add_ssl_algorithms();
404 Net::SSLeay::randomize();
405 sub do_master_job {
407 #... call whatever from Net::SSLeay
408 }
409 sub do_worker_job {
411 #... call whatever from Net::SSLeay
412 }
413 #start threads
415 my $master = threads->new(\&do_master_job, 'param1', 'param2');
416 my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
417 #waiting for all threads to finish
419 $_->join() for (threads->list);
420 NOTE: Openssl's "int SSL_library_init(void)" function (which is also
422 aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
423 and "add_ssl_algorithms") is not re-entrant and multiple calls can
424 cause a crash in threaded application. Net::SSLeay implements flags
425 preventing repeated calls to this function, therefore even multiple
426 initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
427 without trouble.
428 Using callbacks
430 Do not use callbacks across threads (the module blocks cross-thread
432 callback operations and throws a warning). Allways do the callback
433 setup, callback use and callback destruction within the same thread.
434 Using openssl elements
436 All openssl elements (X509, SSL_CTX, ...) can be directly passed
438 between threads.
439 use threads;
441 use Net::SSLeay;
442 Net::SSLeay::load_error_strings();
444 Net::SSLeay::SSLeay_add_ssl_algorithms();
445 Net::SSLeay::randomize();
446 sub do_job {
448 my $context = shift;
449 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
450 #...
451 }
452 my $c = Net::SSLeay::CTX_new();
454 threads->create(\&do_job, $c);
455 Or:
457 use threads;
459 use Net::SSLeay;
460 my $context; #does not need to be 'shared'
462 Net::SSLeay::load_error_strings();
464 Net::SSLeay::SSLeay_add_ssl_algorithms();
465 Net::SSLeay::randomize();
466 sub do_job {
468 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
469 #...
470 }
471 $context = Net::SSLeay::CTX_new();
473 threads->create(\&do_job);
474 Using other perl modules based on Net::SSLeay
476 It should be fine to use any other module based on Net::SSLeay (like
478 IO::Socket::SSL) in multi-threaded applications. It is generally
479 recommended to do any global initialization of such a module in the
480 main thread before calling "threads->new(..)" or "threads->create(..)"
481 but it might differ module by module.
482 To be play safe you can load and init Net::SSLeay explicitly in the
484 main thread:
485 use Net::SSLeay;
487 use Other::SSLeay::Based::Module;
488 Net::SSLeay::load_error_strings();
490 Net::SSLeay::SSLeay_add_ssl_algorithms();
491 Net::SSLeay::randomize();Net::SSLeay::initialize();
492 Net::SSLeay::initialize();
493 Or even safer:
495 use Net::SSLeay;
497 use Other::SSLeay::Based::Module;
498 BEGIN {
500 Net::SSLeay::load_error_strings();
501 Net::SSLeay::SSLeay_add_ssl_algorithms();
502 Net::SSLeay::randomize();Net::SSLeay::initialize();
503 }
504 Combining Net::SSLeay with other modules linked with openssl
506 BEWARE: This might be a big trouble! This is not guaranteed be thread-
508 safe!
509 There are many other (XS) modules linked directly to openssl library
511 (like Crypt::SSLeay).
512 As it is expected that also "another" module will call
514 "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
515 multiple openssl initialization by Net::SSLeay and "another" module.
516 As you can expect Net::SSLeay is not able to avoid multiple
518 initialization of openssl library called by "another" module, thus you
519 have to handle this on your own (in some cases it might not be possible
520 at all to avoid this).
521 Threading with get_https and friends
523 The convenience functions get_https, post_https etc all initialize the
525 SSL library by calling Net::SSLeay::initialize which does the
526 conventional library initialization:
527 Net::SSLeay::load_error_strings();
529 Net::SSLeay::SSLeay_add_ssl_algorithms();
530 Net::SSLeay::randomize();
531 Net::SSLeay::initialize initializes the SSL library at most once. You
533 can override the Net::SSLeay::initialize function if you desire some
534 other type of initialization behaviour by get_https and friends. You
535 can call Net::SSLeay::initialize from your own code if you desire this
536 conventional library initialization.
537 Convenience routines
539 To be used with Low level API
540 Net::SSLeay::randomize($rn_seed_file,$additional_seed);
542 Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
543 $cert = Net::SSLeay::dump_peer_certificate($ssl);
544 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
545 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
546 $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
548 $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
549 Net::SSLeay::ssl_write_CRLF($ssl, $message);
550 · randomize
552 seeds the openssl PRNG with "/dev/urandom" (see the top of
554 "SSLeay.pm" for how to change or configure this) and optionally
555 with user provided data. It is very important to properly seed your
556 random numbers, so do not forget to call this. The high level API
557 functions automatically call "randomize()" so it is not needed with
558 them. See also caveats.
559 · set_cert_and_key
561 takes two file names as arguments and sets the certificate and
563 private key to those. This can be used to set either server
564 certificates or client certificates.
565 · dump_peer_certificate
567 allows you to get a plaintext description of the certificate the
569 peer (usually the server) presented to us.
570 · ssl_read_all
572 see ssl_write_all (below)
574 · ssl_write_all
576 "ssl_read_all()" and "ssl_write_all()" provide true blocking
578 semantics for these operations (see limitation, below, for
579 explanation). These are much preferred to the low level API
580 equivalents (which implement BSD blocking semantics). The message
581 argument to "ssl_write_all()" can be a reference. This is helpful
582 to avoid unnecessary copying when writing something big, e.g:
583 $data = 'A' x 1000000000;
585 Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
586 · ssl_read_CRLF
588 uses "ssl_read_all()" to read in a line terminated with a carriage
590 return followed by a linefeed (CRLF). The CRLF is included in the
591 returned scalar.
592 · ssl_read_until
594 uses "ssl_read_all()" to read from the SSL input stream until it
596 encounters a programmer specified delimiter. If the delimiter is
597 undefined, $/ is used. If $/ is undefined, "\n" is used. One can
598 optionally set a maximum length of bytes to read from the SSL input
599 stream.
600 · ssl_write_CRLF
602 writes $message and appends CRLF to the SSL output stream.
604 Initialization
606 In order to use the low level API you should start your programs with
607 the following incantation:
608 use Net::SSLeay qw(die_now die_if_ssl_error);
610 Net::SSLeay::load_error_strings();
611 Net::SSLeay::SSLeay_add_ssl_algorithms(); # Important!
612 Net::SSLeay::ENGINE_load_builtin_engines(); # If you want built-in engines
613 Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
614 Net::SSLeay::randomize();
615 Error handling functions
617 I can not emphasize the need to check for error enough. Use these
618 functions even in the most simple programs, they will reduce debugging
619 time greatly. Do not ask questions on the mailing list without having
620 first sprinkled these in your code.
621 · die_now
623 · die_if_ssl_error
625 "die_now()" and "die_if_ssl_error()" are used to conveniently print
627 the SSLeay error stack when something goes wrong:
628 Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
630 Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
633 · print_errs
635 You can also use "Net::SSLeay::print_errs()" to dump the error
637 stack without exiting the program. As can be seen, your code
638 becomes much more readable if you import the error reporting
639 functions into your main name space.
640 Sockets
642 Perl uses file handles for all I/O. While SSLeay has a quite flexible
643 BIO mechanism and perl has an evolved PerlIO mechanism, this module
644 still sticks to using file descriptors. Thus to attach SSLeay to a
645 socket you should use "fileno()" to extract the underlying file
646 descriptor:
647 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
649 You should also set $| to 1 to eliminate STDIO buffering so you do not
651 get confused if you use perl I/O functions to manipulate your socket
652 handle.
653 If you need to select(2) on the socket, go right ahead, but be warned
655 that OpenSSL does some internal buffering so SSL_read does not always
656 return data even if the socket selected for reading (just keep on
657 selecting and trying to read). "Net::SSLeay" is no different from the C
658 language OpenSSL in this respect.
659 Callbacks
661 You can establish a per-context verify callback function something like
662 this:
663 sub verify {
665 my ($ok, $x509_store_ctx) = @_;
666 print "Verifying certificate...\n";
667 ...
668 return $ok;
669 }
670 It is used like this:
672 Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
674 Per-context callbacks for decrypting private keys are implemented.
676 Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
678 Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
679 Net::SSLeay::FILETYPE_PEM)
680 or die "Error reading private key";
681 Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
682 If Hello Extensions are supported by your OpenSSL, a session secret
684 callback can be set up to be called when a session secret is set by
685 openssl.
686 Establish it like this:
688 Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb,
689 $somedata);
690 It will be called like this:
692 sub session_secret_cb
694 {
695 my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
696 }
697 No other callbacks are implemented. You do not need to use any callback
699 for simple (i.e. normal) cases where the SSLeay built-in verify
700 mechanism satisfies your needs.
701 It is required to reset these callbacks to undef immediately after use
703 to prevent memory leaks, thread safety problems and crashes on exit
704 that can occur if different threads set different callbacks.
705 If you want to use callback stuff, see examples/callback.pl! It's the
707 only one I am able to make work reliably.
708 Low level API
710 In addition to the high level functions outlined above, this module
711 contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
712 API.
713 See the "*.h" headers from OpenSSL C distribution for a list of low
715 level SSLeay functions to call (check SSLeay.xs to see if some function
716 has been implemented). The module strips the initial "SSL_" off of the
717 SSLeay names. Generally you should use "Net::SSLeay::" in its place.
718 Note that some functions are prefixed with "P_" - these are very close
720 to the original API however contain some kind of a wrapper making its
721 interface more perl friendly.
722 For example:
724 In C:
726 #include <ssl.h>
728 err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
730 &your_call_back_here);
731 In Perl:
733 use Net::SSLeay;
735 $err = Net::SSLeay::set_verify ($ssl,
737 Net::SSLeay::VERIFY_CLIENT_ONCE,
738 \&your_call_back_here);
739 If the function does not start with "SSL_" you should use the full
741 function name, e.g.:
742 $err = Net::SSLeay::ERR_get_error;
744 The following new functions behave in perlish way:
746 $got = Net::SSLeay::read($ssl);
748 # Performs SSL_read, but returns $got
749 # resized according to data received.
750 # Returns undef on failure.
751 Net::SSLeay::write($ssl, $foo) || die;
753 # Performs SSL_write, but automatically
754 # figures out the size of $foo
755 Low level API: Version related functions
757 · SSLeay
759 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
761 Gives version number (numeric) of underlaying openssl library.
763 my $ver_number = Net::SSLeay::SSLeay();
765 # returns: the number identifying the openssl release
766 #
767 # 0x00903100 => openssl-0.9.3
768 # 0x00904100 => openssl-0.9.4
769 # 0x00905100 => openssl-0.9.5
770 # 0x0090600f => openssl-0.9.6
771 # 0x0090601f => openssl-0.9.6a
772 # 0x0090602f => openssl-0.9.6b
773 # ...
774 # 0x009060df => openssl-0.9.6m
775 # 0x0090700f => openssl-0.9.7
776 # 0x0090701f => openssl-0.9.7a
777 # 0x0090702f => openssl-0.9.7b
778 # ...
779 # 0x009070df => openssl-0.9.7m
780 # 0x0090800f => openssl-0.9.8
781 # 0x0090801f => openssl-0.9.8a
782 # 0x0090802f => openssl-0.9.8b
783 # ...
784 # 0x0090814f => openssl-0.9.8t
785 # 0x1000000f => openssl-1.0.0
786 # 0x1000004f => openssl-1.0.0d
787 # 0x1000007f => openssl-1.0.0g
788 You can use it like this:
790 if (Net::SSLeay::SSLeay() < 0x0090800f) {
792 die "you need openssl-0.9.8 or higher";
793 }
794 · SSLeay_version
796 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
798 Gives version number (string) of underlaying openssl library.
800 my $ver_string = Net::SSLeay::SSLeay_version($type);
802 # $type
803 # 0 (=SSLEAY_VERSION) - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
804 # 2 (=SSLEAY_CFLAGS) - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
805 # 3 (=SSLEAY_BUILT_ON)- e.g. 'built on: Fri May 6 00:00:46 GMT 2011'
806 # 4 (=SSLEAY_PLATFORM)- e.g. 'platform: mingw'
807 #
808 # returns: string
809 Net::SSLeay::SSLeay_version();
811 #is equivalent to
812 Net::SSLeay::SSLeay_version(0);
813 Check openssl doc
815 <http://www.openssl.org/docs/crypto/SSLeay_version.html>
816 Low level API: Initialization related functions
818 · library_init
820 Initialize SSL library by registering algorithms.
822 my $rv = Net::SSLeay::library_init();
824 #
825 # returns: always 1
826 Check openssl doc
828 <http://www.openssl.org/docs/ssl/SSL_library_init.html>
829 · add_ssl_algorithms
831 The alias for "library_init"
833 Net::SSLeay::add_ssl_algorithms();
835 · OpenSSL_add_ssl_algorithms
837 The alias for "library_init"
839 Net::SSLeay::OpenSSL_add_ssl_algorithms();
841 · SSLeay_add_ssl_algorithms
843 The alias for "library_init"
845 Net::SSLeay::SSLeay_add_ssl_algorithms();
847 · load_error_strings
849 Registers the error strings for all libcrypto + libssl related
851 functions.
852 Net::SSLeay::load_error_strings();
854 #
855 # returns: no return value
856 Check openssl doc
858 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
859 · ERR_load_crypto_strings
861 Registers the error strings for all libcrypto functions. No need to
863 call this function if you have already called "load_error_strings".
864 Net::SSLeay::ERR_load_crypto_strings();
866 #
867 # returns: no return value
868 Check openssl doc
870 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
871 · ERR_load_RAND_strings
873 Registers the error strings for RAND related functions. No need to
875 call this function if you have already called "load_error_strings".
876 Net::SSLeay::ERR_load_RAND_strings();
878 #
879 # returns: no return value
880 · ERR_load_SSL_strings
882 Registers the error strings for SSL related functions. No need to
884 call this function if you have already called "load_error_strings".
885 Net::SSLeay::ERR_load_SSL_strings();
887 #
888 # returns: no return value
889 · OpenSSL_add_all_algorithms
891 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
893 Add algorithms to internal table.
895 Net::SSLeay::OpenSSL_add_all_algorithms();
897 #
898 # returns: no return value
899 Check openssl doc
901 <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
902 · OPENSSL_add_all_algorithms_conf
904 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
906 Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
908 config file
909 Net::SSLeay::OPENSSL_add_all_algorithms_conf();
911 #
912 # returns: no return value
913 · OPENSSL_add_all_algorithms_noconf
915 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
917 Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
919 config file
920 Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
922 #
923 # returns: no return value
924 Low level API: ERR_* and SSL_alert_* related functions
926 NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
928 from their names.
929 · ERR_clear_error
931 Clear the error queue.
933 Net::SSLeay::ERR_clear_error();
935 #
936 # returns: no return value
937 Check openssl doc
939 <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
940 · ERR_error_string
942 Generates a human-readable string representing the error code
944 $error.
945 my $rv = Net::SSLeay::ERR_error_string($error);
947 # $error - (unsigned integer) error code
948 #
949 # returns: string
950 Check openssl doc
952 <http://www.openssl.org/docs/crypto/ERR_error_string.html>
953 · ERR_get_error
955 Returns the earliest error code from the thread's error queue and
957 removes the entry. This function can be called repeatedly until
958 there are no more error codes to return.
959 my $rv = Net::SSLeay::ERR_get_error();
961 #
962 # returns: (unsigned integer) error code
963 Check openssl doc
965 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
966 · ERR_peek_error
968 Returns the earliest error code from the thread's error queue
970 without modifying it.
971 my $rv = Net::SSLeay::ERR_peek_error();
973 #
974 # returns: (unsigned integer) error code
975 Check openssl doc
977 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
978 · ERR_put_error
980 Adds an error code to the thread's error queue. It signals that the
982 error of $reason code reason occurred in function $func of library
983 $lib, in line number $line of $file.
984 Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
986 # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
987 # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
988 # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
989 # $file - (string) file name
990 # $line - (integer) line number in $file
991 #
992 # returns: no return value
993 Check openssl doc
995 <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
996 <http://www.openssl.org/docs/crypto/err.html>
997 · alert_desc_string
999 Returns a two letter string as a short form describing the reason
1001 of the alert specified by value.
1002 my $rv = Net::SSLeay::alert_desc_string($value);
1004 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1005 #
1006 # returns: description string (2 letters)
1007 Check openssl doc
1009 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1010 · alert_desc_string_long
1012 Returns a string describing the reason of the alert specified by
1014 value.
1015 my $rv = Net::SSLeay::alert_desc_string_long($value);
1017 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1018 #
1019 # returns: description string
1020 Check openssl doc
1022 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1023 · alert_type_string
1025 Returns a one letter string indicating the type of the alert
1027 specified by value.
1028 my $rv = Net::SSLeay::alert_type_string($value);
1030 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1031 #
1032 # returns: string (1 letter)
1033 Check openssl doc
1035 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1036 · alert_type_string_long
1038 Returns a string indicating the type of the alert specified by
1040 value.
1041 my $rv = Net::SSLeay::alert_type_string_long($value);
1043 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1044 #
1045 # returns: string
1046 Check openssl doc
1048 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1049 Low level API: SSL_METHOD_* related functions
1051 · SSLv2_method
1053 Returns SSL_METHOD structure corresponding to SSLv2 method, the
1055 return value can be later used as a param of "CTX_new_with_method".
1056 Only available where suported by the underlying openssl.
1057 my $rv = Net::SSLeay::SSLv2_method();
1059 #
1060 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1061 · SSLv3_method
1063 Returns SSL_METHOD structure corresponding to SSLv3 method, the
1065 return value can be later used as a param of "CTX_new_with_method".
1066 my $rv = Net::SSLeay::SSLv3_method();
1068 #
1069 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1070 Check openssl doc
1072 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1073 · TLSv1_method
1075 Returns SSL_METHOD structure corresponding to TLSv1 method, the
1077 return value can be later used as a param of "CTX_new_with_method".
1078 my $rv = Net::SSLeay::TLSv1_method();
1080 #
1081 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1082 Check openssl doc
1084 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1085 · TLSv1_1_method
1087 Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1089 return value can be later used as a param of "CTX_new_with_method".
1090 Only available where supported by the underlying openssl.
1091 my $rv = Net::SSLeay::TLSv1__1method();
1093 #
1094 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1095 Check openssl doc
1097 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1098 · TLSv1_2_method
1100 Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1102 return value can be later used as a param of "CTX_new_with_method".
1103 Only available where supported by the underlying openssl.
1104 my $rv = Net::SSLeay::TLSv1_2_method();
1106 #
1107 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1108 Check openssl doc
1110 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1111 Low level API: ENGINE_* related functions
1113 · ENGINE_load_builtin_engines
1115 Load all bundled ENGINEs into memory and make them visible.
1117 Net::SSLeay::ENGINE_load_builtin_engines();
1119 #
1120 # returns: no return value
1121 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1123 · ENGINE_register_all_complete
1125 Register all loaded ENGINEs for every algorithm they collectively
1127 implement.
1128 Net::SSLeay::ENGINE_register_all_complete();
1130 #
1131 # returns: no return value
1132 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1134 · ENGINE_set_default
1136 Set default engine to $e + set its flags to $flags.
1138 my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1140 # $e - value corresponding to openssl's ENGINE structure
1141 # $flags - (integer) engine flags
1142 # flags value can be made by bitwise "OR"ing:
1143 # 0x0001 - ENGINE_METHOD_RSA
1144 # 0x0002 - ENGINE_METHOD_DSA
1145 # 0x0004 - ENGINE_METHOD_DH
1146 # 0x0008 - ENGINE_METHOD_RAND
1147 # 0x0010 - ENGINE_METHOD_ECDH
1148 # 0x0020 - ENGINE_METHOD_ECDSA
1149 # 0x0040 - ENGINE_METHOD_CIPHERS
1150 # 0x0080 - ENGINE_METHOD_DIGESTS
1151 # 0x0100 - ENGINE_METHOD_STORE
1152 # 0x0200 - ENGINE_METHOD_PKEY_METHS
1153 # 0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1154 # Obvious all-or-nothing cases:
1155 # 0xFFFF - ENGINE_METHOD_ALL
1156 # 0x0000 - ENGINE_METHOD_NONE
1157 #
1158 # returns: 1 on success, 0 on failure
1159 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1161 · ENGINE_by_id
1163 Get ENGINE by its identification $id.
1165 my $rv = Net::SSLeay::ENGINE_by_id($id);
1167 # $id - (string) engine identification e.g. "dynamic"
1168 #
1169 # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1170 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1172 Low level API: EVP_PKEY_* related functions
1174 · EVP_PKEY_copy_parameters
1176 Copies the parameters from key $from to key $to.
1178 my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1180 # $to - value corresponding to openssl's EVP_PKEY structure
1181 # $from - value corresponding to openssl's EVP_PKEY structure
1182 #
1183 # returns: 1 on success, 0 on failure
1184 Check openssl doc
1186 <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1187 · EVP_PKEY_new
1189 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1191 Creates a new EVP_PKEY structure.
1193 my $rv = Net::SSLeay::EVP_PKEY_new();
1195 #
1196 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1197 Check openssl doc
1199 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1200 · EVP_PKEY_free
1202 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1204 Free an allocated EVP_PKEY structure.
1206 Net::SSLeay::EVP_PKEY_free($pkey);
1208 # $pkey - value corresponding to openssl's EVP_PKEY structure
1209 #
1210 # returns: no return value
1211 Check openssl doc
1213 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1214 · EVP_PKEY_assign_RSA
1216 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1218 Set the key referenced by $pkey to $key
1220 NOTE: In accordance with the OpenSSL naming convention the $key
1222 assigned to the $pkey using the "1" functions must be freed as well
1223 as $pkey.
1224 my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1226 # $pkey - value corresponding to openssl's EVP_PKEY structure
1227 # $key - value corresponding to openssl's RSA structure
1228 #
1229 # returns: 1 on success, 0 on failure
1230 Check openssl doc
1232 <http://www.openssl.org/docs/crypto/EVP_PKEY_set1_RSA.html>
1233 · EVP_PKEY_bits
1235 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1237 Returns the size of the key $pkey in bits.
1239 my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1241 # $pkey - value corresponding to openssl's EVP_PKEY structure
1242 #
1243 # returns: size in bits
1244 · EVP_PKEY_size
1246 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1248 Returns the maximum size of a signature in bytes. The actual
1250 signature may be smaller.
1251 my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1253 # $pkey - value corresponding to openssl's EVP_PKEY structure
1254 #
1255 # returns: the maximum size in bytes
1256 Check openssl doc
1258 <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1259 · EVP_PKEY_id
1261 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1263 requires at least openssl-1.0.0
1264 Returns $pkey type (integer value of corresponding NID).
1266 my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1268 # $pkey - value corresponding to openssl's EVP_PKEY structure
1269 #
1270 # returns: (integer) key type
1271 Example:
1273 my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1275 my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1276 print Net::SSLeay::OBJ_nid2sn($type); #prints e.g. 'rsaEncryption'
1277 Low level API: PEM_* related functions
1279 Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1281 · PEM_read_bio_X509
1283 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1285 Loads PEM formated X509 certificate via given BIO structure.
1287 my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1289 # $bio - value corresponding to openssl's BIO structure
1290 #
1291 # returns: value corresponding to openssl's X509 structure (0 on failure)
1292 Example:
1294 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1296 my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1297 Net::SSLeay::BIO_free($bio);
1298 · PEM_read_bio_X509_REQ
1300 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1302 Loads PEM formated X509_REQ object via given BIO structure.
1304 my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1306 # $bio - value corresponding to openssl's BIO structure
1307 #
1308 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1309 Example:
1311 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1313 my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1314 Net::SSLeay::BIO_free($bio);
1315 · PEM_read_bio_DHparams
1317 Reads DH structure from BIO.
1319 my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1321 # $bio - value corresponding to openssl's BIO structure
1322 #
1323 # returns: value corresponding to openssl's DH structure (0 on failure)
1324 · PEM_read_bio_X509_CRL
1326 Reads X509_CRL structure from BIO.
1328 my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1330 # $bio - value corresponding to openssl's BIO structure
1331 #
1332 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1333 · PEM_read_bio_PrivateKey
1335 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1337 Loads PEM formated private key via given BIO structure.
1339 my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1341 # $bio - value corresponding to openssl's BIO structure
1342 # $cb - reference to perl callback function
1343 # $data - data that will be passed to callback function (see examples below)
1344 #
1345 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1346 Example:
1348 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1350 my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1351 Net::SSLeay::BIO_free($bio);
1352 To use password you have the following options:
1354 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1356 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1357 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1358 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, ""); # use empty password
1359 Callback function signature:
1361 sub callback_func {
1363 my ($max_passwd_size, $rwflag, $data) = @_;
1364 # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1365 # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1366 # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1367 return "secret";
1369 }
1370 · PEM_get_string_X509
1372 NOTE: Does not exactly correspond to any low level API function
1374 Converts/exports X509 certificate to string (PEM format).
1376 Net::SSLeay::PEM_get_string_X509($x509);
1378 # $x509 - value corresponding to openssl's X509 structure
1379 #
1380 # returns: string with $x509 in PEM format
1381 · PEM_get_string_PrivateKey
1383 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1385 Converts public key $pk into PEM formated string (optionally
1387 protected with password).
1388 my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1390 # $pk - value corresponding to openssl's EVP_PKEY structure
1391 # $passwd - [optional] (string) password to use for key encryption
1392 # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1393 #
1394 # returns: PEM formated string
1395 Examples:
1397 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1399 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1400 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1401 · PEM_get_string_X509_CRL
1403 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1405 Converts X509_CRL object $x509_crl into PEM formated string.
1407 Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1409 # $x509_crl - value corresponding to openssl's X509_CRL structure
1410 #
1411 # returns: no return value
1412 · PEM_get_string_X509_REQ
1414 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1416 Converts X509_REQ object $x509_crl into PEM formated string.
1418 Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1420 # $x509_req - value corresponding to openssl's X509_REQ structure
1421 #
1422 # returns: no return value
1423 Low level API: d2i_* (DER format) related functions
1425 · d2i_X509_bio
1427 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1429 Loads DER formated X509 certificate via given BIO structure.
1431 my $rv = Net::SSLeay::d2i_X509_bio($bp);
1433 # $bp - value corresponding to openssl's BIO structure
1434 #
1435 # returns: value corresponding to openssl's X509 structure (0 on failure)
1436 Example:
1438 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1440 my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1441 Net::SSLeay::BIO_free($bio);
1442 Check openssl doc
1444 <http://www.openssl.org/docs/crypto/d2i_X509.html>
1445 · d2i_X509_CRL_bio
1447 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1449 Loads DER formated X509_CRL object via given BIO structure.
1451 my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1453 # $bp - value corresponding to openssl's BIO structure
1454 #
1455 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1456 Example:
1458 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1460 my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1461 Net::SSLeay::BIO_free($bio);
1462 · d2i_X509_REQ_bio
1464 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1466 Loads DER formated X509_REQ object via given BIO structure.
1468 my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1470 # $bp - value corresponding to openssl's BIO structure
1471 #
1472 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1473 Example:
1475 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1477 my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1478 Net::SSLeay::BIO_free($bio);
1479 Low level API: PKCS12 related functions
1481 · P_PKCS12_load_file
1483 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1485 Loads X509 certificate + private key + certificates of CA chain (if
1487 present in PKCS12 file).
1488 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1490 # $filename - name of PKCS12 file
1491 # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1492 # $password - [optional] password for private key
1493 #
1494 # returns: triplet ($privkey, $cert, @cachain)
1495 # $privkey - value corresponding to openssl's EVP_PKEY structure
1496 # $cert - value corresponding to openssl's X509 structure
1497 # @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1498 IMPORTANT NOTE: after you do the job you need to call X509_free()
1500 on $privkey + all members of @cachain and EVP_PKEY_free() on
1501 $privkey.
1502 Examples:
1504 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1506 #or
1507 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1508 #or
1509 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1510 #or
1511 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1512 #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1514 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1515 Low level API: SESSION_* related functions
1517 · d2i_SSL_SESSION
1519 Transforms the external ASN1 representation of an SSL/TLS session,
1521 stored as binary data at location pp with length length, into an
1522 SSL_SESSION object.
1523 ??? (does this function really work?)
1525 my $rv = Net::SSLeay::d2i_SSL_SESSION($a, $pp, $length);
1527 # $a - value corresponding to openssl's SSL_SESSION structure
1528 # $pp - pointer/buffer ???
1529 # $length - ???
1530 #
1531 # returns: ???
1532 Check openssl doc
1534 <http://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1535 · i2d_SSL_SESSION
1537 Transforms the SSL_SESSION object in into the ASN1 representation
1539 and stores it into the memory location pointed to by pp. The length
1540 of the resulting ASN1 representation is returned.
1541 ??? (does this function really work?)
1543 my $rv = Net::SSLeay::i2d_SSL_SESSION($in, $pp);
1545 # $in - value corresponding to openssl's SSL_SESSION structure
1546 # $pp - pointer/data ???
1547 #
1548 # returns: 1 on success, 0
1549 Check openssl doc
1551 <http://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1552 · SESSION_new
1554 Creates a new SSL_SESSION structure.
1556 my $rv = Net::SSLeay::SESSION_new();
1558 #
1559 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
1560 · SESSION_free
1562 Free an allocated SSL_SESSION structure.
1564 Net::SSLeay::SESSION_free($ses);
1566 # $ses - value corresponding to openssl's SSL_SESSION structure
1567 #
1568 # returns: no return value
1569 Check openssl doc
1571 <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
1572 · SESSION_cmp
1574 Compare two SSL_SESSION structures.
1576 my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
1578 # $sesa - value corresponding to openssl's SSL_SESSION structure
1579 # $sesb - value corresponding to openssl's SSL_SESSION structure
1580 #
1581 # returns: 0 if the two structures are the same
1582 NOTE: Not available in openssl 1.0 or later
1584 · SESSION_get_app_data
1586 Can be used to get application defined value/data.
1588 my $rv = Net::SSLeay::SESSION_get_app_data($ses);
1590 # $ses - value corresponding to openssl's SSL_SESSION structure
1591 #
1592 # returns: string/buffer/pointer ???
1593 · SESSION_set_app_data
1595 Can be used to set some application defined value/data.
1597 my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
1599 # $s - value corresponding to openssl's SSL_SESSION structure
1600 # $a - (string/buffer/pointer ???) data
1601 #
1602 # returns: ???
1603 · SESSION_get_ex_data
1605 Is used to retrieve the information for $idx from session $ses.
1607 my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
1609 # $ses - value corresponding to openssl's SSL_SESSION structure
1610 # $idx - (integer) index for application specific data
1611 #
1612 # returns: pointer to ???
1613 Check openssl doc
1615 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1616 · SESSION_set_ex_data
1618 Is used to store application data at arg for idx into the session
1620 object.
1621 my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
1623 # $ss - value corresponding to openssl's SSL_SESSION structure
1624 # $idx - (integer) ???
1625 # $data - (pointer) ???
1626 #
1627 # returns: 1 on success, 0 on failure
1628 Check openssl doc
1630 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1631 · SESSION_get_ex_new_index
1633 Is used to register a new index for application specific data.
1635 my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
1637 # $argl - (long) ???
1638 # $argp - (pointer) ???
1639 # $new_func - function pointer ??? (CRYPTO_EX_new *)
1640 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
1641 # $free_func - function pointer ??? (CRYPTO_EX_free *)
1642 #
1643 # returns: (integer) ???
1644 Check openssl doc
1646 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1647 · SESSION_get_master_key
1649 NOTE: Does not exactly correspond to any low level API function
1651 Returns 'master_key' value from SSL_SESSION structure $s
1653 Net::SSLeay::SESSION_get_master_key($s);
1655 # $s - value corresponding to openssl's SSL_SESSION structure
1656 #
1657 # returns: master key (binary data)
1658 · SESSION_set_master_key
1660 Sets 'master_key' value for SSL_SESSION structure $s
1662 Net::SSLeay::SESSION_set_master_key($s, $key);
1664 # $s - value corresponding to openssl's SSL_SESSION structure
1665 # $key - master key (binary data)
1666 #
1667 # returns: no return value
1668 · SESSION_get_time
1670 Returns the time at which the session s was established. The time
1672 is given in seconds since 1.1.1970.
1673 my $rv = Net::SSLeay::SESSION_get_time($s);
1675 # $s - value corresponding to openssl's SSL_SESSION structure
1676 #
1677 # returns: timestamp (seconds since 1.1.1970)
1678 Check openssl doc
1680 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1681 · get_time
1683 Technically the same functionality as "SESSION_get_time".
1685 my $rv = Net::SSLeay::get_time($s);
1687 · SESSION_get_timeout
1689 Returns the timeout value set for session $s in seconds.
1691 my $rv = Net::SSLeay::SESSION_get_timeout($s);
1693 # $s - value corresponding to openssl's SSL_SESSION structure
1694 #
1695 # returns: timeout (in seconds)
1696 Check openssl doc
1698 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1699 · get_timeout
1701 Technically the same functionality as "SESSION_get_timeout".
1703 my $rv = Net::SSLeay::get_timeout($s);
1705 · SESSION_print
1707 NOTE: Does not exactly correspond to any low level API function
1709 Prints session details (e.g. protocol version, ciprher, session-id
1711 ...) to BIO.
1712 my $rv = Net::SSLeay::SESSION_print($fp, $ses);
1714 # $fp - value corresponding to openssl's BIO structure
1715 # $ses - value corresponding to openssl's SSL_SESSION structure
1716 #
1717 # returns: 1 on success, 0 on failure
1718 You have to use necessary BIO functions like this:
1720 # let us have $ssl corresponding to openssl's SSL structure
1722 my $ses = Net::SSLeay::get_session($ssl);
1723 my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
1724 Net::SSLeay::SESSION_print($bio, $ses);
1725 print Net::SSLeay::BIO_read($bio);
1726 · SESSION_print_fp
1728 Prints session details (e.g. protocol version, ciprher, session-id
1730 ...) to file handle.
1731 my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
1733 # $fp - perl file handle
1734 # $ses - value corresponding to openssl's SSL_SESSION structure
1735 #
1736 # returns: 1 on success, 0 on failure
1737 Example:
1739 # let us have $ssl corresponding to openssl's SSL structure
1741 my $ses = Net::SSLeay::get_session($ssl);
1742 open my $fh, ">", "output.txt";
1743 Net::SSLeay::SESSION_print_fp($fh,$ses);
1744 · SESSION_set_time
1746 Replaces the creation time of the session s with the chosen value
1748 $t (seconds since 1.1.1970).
1749 my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
1751 # $ses - value corresponding to openssl's SSL_SESSION structure
1752 # $t - time value
1753 #
1754 # returns: 1 on success
1755 Check openssl doc
1757 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1758 · set_time
1760 Technically the same functionality as "SESSION_set_time".
1762 my $rv = Net::SSLeay::set_time($ses, $t);
1764 · SESSION_set_timeout
1766 Sets the timeout value for session s in seconds to $t.
1768 my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
1770 # $s - value corresponding to openssl's SSL_SESSION structure
1771 # $t - timeout (in seconds)
1772 #
1773 # returns: 1 on success
1774 Check openssl doc
1776 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1777 · set_timeout
1779 Technically the same functionality as "SESSION_set_timeout".
1781 my $rv = Net::SSLeay::set_timeout($ses, $t);
1783 Low level API: SSL_CTX_* related functions
1785 NOTE: Please note that the function described in this chapter have
1787 "SSL_" part stripped from their original openssl names.
1788 · CTX_add_client_CA
1790 Adds the CA name extracted from $cacert to the list of CAs sent to
1792 the client when requesting a client certificate for $ctx.
1793 my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
1795 # $ctx - value corresponding to openssl's SSL_CTX structure
1796 # $cacert - value corresponding to openssl's X509 structure
1797 #
1798 # returns: 1 on success, 0 on failure
1799 Check openssl doc
1801 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
1802 · CTX_add_extra_chain_cert
1804 Adds the certificate $x509 to the certificate chain presented
1806 together with the certificate. Several certificates can be added
1807 one after the other.
1808 my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
1810 # $ctx - value corresponding to openssl's SSL_CTX structure
1811 # $x509 - value corresponding to openssl's X509 structure
1812 #
1813 # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
1814 Check openssl doc
1816 <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
1817 · CTX_add_session
1819 Adds the session $ses to the context $ctx.
1821 my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
1823 # $ctx - value corresponding to openssl's SSL_CTX structure
1824 # $ses - value corresponding to openssl's SSL_SESSION structure
1825 #
1826 # returns: 1 on success, 0 on failure
1827 Check openssl doc
1829 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
1830 · CTX_callback_ctrl
1832 ??? (more info needed)
1834 my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
1836 # $ctx - value corresponding to openssl's SSL_CTX structure
1837 # $cmd - (integer) command id
1838 # $fp - (function pointer) ???
1839 #
1840 # returns: ???
1841 Check openssl doc
1843 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
1844 · CTX_check_private_key
1846 Checks the consistency of a private key with the corresponding
1848 certificate loaded into $ctx.
1849 my $rv = Net::SSLeay::CTX_check_private_key($ctx);
1851 # $ctx - value corresponding to openssl's SSL_CTX structure
1852 #
1853 # returns: 1 on success, otherwise check out the error stack to find out the reason
1854 Check openssl doc
1856 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
1857 · CTX_ctrl
1859 Internal handling function for SSL_CTX objects.
1861 BEWARE: openssl doc says: This function should never be called
1863 directly!
1864 my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
1866 # $ctx - value corresponding to openssl's SSL_CTX structure
1867 # $cmd - (integer) command id
1868 # $larg - (integer) long ???
1869 # $parg - (string/pointer) ???
1870 #
1871 # returns: (long) result of given command ???
1872 #valid $cmd values
1874 1 - SSL_CTRL_NEED_TMP_RSA
1875 2 - SSL_CTRL_SET_TMP_RSA
1876 3 - SSL_CTRL_SET_TMP_DH
1877 4 - SSL_CTRL_SET_TMP_ECDH
1878 5 - SSL_CTRL_SET_TMP_RSA_CB
1879 6 - SSL_CTRL_SET_TMP_DH_CB
1880 7 - SSL_CTRL_SET_TMP_ECDH_CB
1881 8 - SSL_CTRL_GET_SESSION_REUSED
1882 9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
1883 10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
1884 11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
1885 12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
1886 13 - SSL_CTRL_GET_FLAGS
1887 14 - SSL_CTRL_EXTRA_CHAIN_CERT
1888 15 - SSL_CTRL_SET_MSG_CALLBACK
1889 16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
1890 17 - SSL_CTRL_SET_MTU
1891 20 - SSL_CTRL_SESS_NUMBER
1892 21 - SSL_CTRL_SESS_CONNECT
1893 22 - SSL_CTRL_SESS_CONNECT_GOOD
1894 23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
1895 24 - SSL_CTRL_SESS_ACCEPT
1896 25 - SSL_CTRL_SESS_ACCEPT_GOOD
1897 26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
1898 27 - SSL_CTRL_SESS_HIT
1899 28 - SSL_CTRL_SESS_CB_HIT
1900 29 - SSL_CTRL_SESS_MISSES
1901 30 - SSL_CTRL_SESS_TIMEOUTS
1902 31 - SSL_CTRL_SESS_CACHE_FULL
1903 32 - SSL_CTRL_OPTIONS
1904 33 - SSL_CTRL_MODE
1905 40 - SSL_CTRL_GET_READ_AHEAD
1906 41 - SSL_CTRL_SET_READ_AHEAD
1907 42 - SSL_CTRL_SET_SESS_CACHE_SIZE
1908 43 - SSL_CTRL_GET_SESS_CACHE_SIZE
1909 44 - SSL_CTRL_SET_SESS_CACHE_MODE
1910 45 - SSL_CTRL_GET_SESS_CACHE_MODE
1911 50 - SSL_CTRL_GET_MAX_CERT_LIST
1912 51 - SSL_CTRL_SET_MAX_CERT_LIST
1913 52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
1914 53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
1915 54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
1916 55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
1917 56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
1918 57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
1919 58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
1920 59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
1921 60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
1922 61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
1923 62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
1924 63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
1925 64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
1926 65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
1927 66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
1928 67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
1929 68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
1930 69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
1931 70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
1932 71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
1933 72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
1934 73 - DTLS_CTRL_GET_TIMEOUT
1935 74 - DTLS_CTRL_HANDLE_TIMEOUT
1936 75 - DTLS_CTRL_LISTEN
1937 76 - SSL_CTRL_GET_RI_SUPPORT
1938 77 - SSL_CTRL_CLEAR_OPTIONS
1939 78 - SSL_CTRL_CLEAR_MODE
1940 82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
1942 83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
1943 88 - SSL_CTRL_CHAIN
1945 89 - SSL_CTRL_CHAIN_CERT
1946 90 - SSL_CTRL_GET_CURVES
1948 91 - SSL_CTRL_SET_CURVES
1949 92 - SSL_CTRL_SET_CURVES_LIST
1950 93 - SSL_CTRL_GET_SHARED_CURVE
1951 94 - SSL_CTRL_SET_ECDH_AUTO
1952 97 - SSL_CTRL_SET_SIGALGS
1953 98 - SSL_CTRL_SET_SIGALGS_LIST
1954 99 - SSL_CTRL_CERT_FLAGS
1955 100 - SSL_CTRL_CLEAR_CERT_FLAGS
1956 101 - SSL_CTRL_SET_CLIENT_SIGALGS
1957 102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
1958 103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
1959 104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
1960 105 - SSL_CTRL_BUILD_CERT_CHAIN
1961 106 - SSL_CTRL_SET_VERIFY_CERT_STORE
1962 107 - SSL_CTRL_SET_CHAIN_CERT_STORE
1963 108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
1964 109 - SSL_CTRL_GET_SERVER_TMP_KEY
1965 110 - SSL_CTRL_GET_RAW_CIPHERLIST
1966 111 - SSL_CTRL_GET_EC_POINT_FORMATS
1967 112 - SSL_CTRL_GET_TLSA_RECORD
1968 113 - SSL_CTRL_SET_TLSA_RECORD
1969 114 - SSL_CTRL_PULL_TLSA_RECORD
1970 Check openssl doc
1972 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
1973 · CTX_flush_sessions
1975 Causes a run through the session cache of $ctx to remove sessions
1977 expired at time $tm.
1978 Net::SSLeay::CTX_flush_sessions($ctx, $tm);
1980 # $ctx - value corresponding to openssl's SSL_CTX structure
1981 # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
1982 #
1983 # returns: no return value
1984 Check openssl doc
1986 <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
1987 · CTX_free
1989 Free an allocated SSL_CTX object.
1991 Net::SSLeay::CTX_free($ctx);
1993 # $ctx - value corresponding to openssl's SSL_CTX structure
1994 #
1995 # returns: no return value
1996 Check openssl doc
1998 <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
1999 · CTX_get_app_data
2001 Can be used to get application defined value/data.
2003 my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2005 # $ctx - value corresponding to openssl's SSL_CTX structure
2006 #
2007 # returns: string/buffer/pointer ???
2008 · CTX_set_app_data
2010 Can be used to set some application defined value/data.
2012 my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2014 # $ctx - value corresponding to openssl's SSL_CTX structure
2015 # $arg - (string/buffer/pointer ???) data
2016 #
2017 # returns: ???
2018 · CTX_get_cert_store
2020 Returns the current certificate verification storage.
2022 my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2024 # $ctx - value corresponding to openssl's SSL_CTX structure
2025 #
2026 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2027 Check openssl doc
2029 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2030 · CTX_get_client_CA_list
2032 Returns the list of client CAs explicitly set for $ctx using
2034 "CTX_set_client_CA_list".
2035 my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2037 # $ctx - value corresponding to openssl's SSL_CTX structure
2038 #
2039 # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2040 Check openssl doc
2042 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2043 · CTX_get_ex_data
2045 Is used to retrieve the information for index $idx from $ctx.
2047 my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2049 # $ssl - value corresponding to openssl's SSL_CTX structure
2050 # $idx - (integer) index for application specific data
2051 #
2052 # returns: pointer to ???
2053 Check openssl doc
2055 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2056 · CTX_get_ex_new_index
2058 Is used to register a new index for application specific data.
2060 my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2062 # $argl - (long) ???
2063 # $argp - (pointer) ???
2064 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2065 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2066 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2067 #
2068 # returns: (integer) ???
2069 Check openssl doc
2071 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2072 · CTX_get_mode
2074 Returns the mode set for ctx.
2076 my $rv = Net::SSLeay::CTX_get_mode($ctx);
2078 # $ctx - value corresponding to openssl's SSL_CTX structure
2079 #
2080 # returns: mode (bitmask)
2081 #to decode the return value (bitmask) use:
2083 0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2084 0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2085 0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2086 0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2087 0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2088 (note: some of the bits might not be supported by older openssl versions)
2089 Check openssl doc
2091 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2092 · CTX_set_mode
2094 Adds the mode set via bitmask in $mode to $ctx. Options already set
2096 before are not cleared.
2097 my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2099 # $ctx - value corresponding to openssl's SSL_CTX structure
2100 # $mode - mode bitmask
2101 #
2102 # returns: the new mode bitmask after adding $mode
2103 For bitmask details see "CTX_get_mode" (above).
2105 Check openssl doc
2107 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2108 · CTX_get_options
2110 Returns the options (bitmask) set for $ctx.
2112 my $rv = Net::SSLeay::CTX_get_options($ctx);
2114 # $ctx - value corresponding to openssl's SSL_CTX structure
2115 #
2116 # returns: options (bitmask)
2117 #to decode the return value (bitmask) use:
2119 0x00000001 corresponds to SSL_OP_MICROSOFT_SESS_ID_BUG
2120 0x00000002 corresponds to SSL_OP_NETSCAPE_CHALLENGE_BUG
2121 0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2122 0x00000008 corresponds to SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
2123 0x00000010 corresponds to SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG
2124 0x00000020 corresponds to SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER
2125 0x00000040 corresponds to SSL_OP_MSIE_SSLV2_RSA_PADDING
2126 0x00000080 corresponds to SSL_OP_SSLEAY_080_CLIENT_DH_BUG
2127 0x00000100 corresponds to SSL_OP_TLS_D5_BUG
2128 0x00000200 corresponds to SSL_OP_TLS_BLOCK_PADDING_BUG
2129 0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2130 0x80000FFF corresponds to SSL_OP_ALL
2131 0x00001000 corresponds to SSL_OP_NO_QUERY_MTU
2132 0x00002000 corresponds to SSL_OP_COOKIE_EXCHANGE
2133 0x00004000 corresponds to SSL_OP_NO_TICKET
2134 0x00008000 corresponds to SSL_OP_CISCO_ANYCONNECT
2135 0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2136 0x00020000 corresponds to SSL_OP_NO_COMPRESSION
2137 0x00040000 corresponds to SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
2138 0x00080000 corresponds to SSL_OP_SINGLE_ECDH_USE
2139 0x00100000 corresponds to SSL_OP_SINGLE_DH_USE
2140 0x00200000 corresponds to SSL_OP_EPHEMERAL_RSA
2141 0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2142 0x00800000 corresponds to SSL_OP_TLS_ROLLBACK_BUG
2143 0x01000000 corresponds to SSL_OP_NO_SSLv2
2144 0x02000000 corresponds to SSL_OP_NO_SSLv3
2145 0x04000000 corresponds to SSL_OP_NO_TLSv1
2146 0x08000000 corresponds to SSL_OP_PKCS1_CHECK_1
2147 0x10000000 corresponds to SSL_OP_PKCS1_CHECK_2
2148 0x20000000 corresponds to SSL_OP_NETSCAPE_CA_DN_BUG
2149 0x40000000 corresponds to SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
2150 0x80000000 corresponds to SSL_OP_CRYPTOPRO_TLSEXT_BUG
2151 (note: some of the bits might not be supported by older openssl versions)
2152 Check openssl doc
2154 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
2155 · CTX_set_options
2157 Adds the options set via bitmask in $options to ctx. Options
2159 already set before are not cleared.
2160 Net::SSLeay::CTX_set_options($ctx, $options);
2162 # $ctx - value corresponding to openssl's SSL_CTX structure
2163 # $options - options bitmask
2164 #
2165 # returns: the new options bitmask after adding $options
2166 For bitmask details see "CTX_get_options" (above).
2168 Check openssl doc
2170 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
2171 · CTX_get_quiet_shutdown
2173 Returns the 'quiet shutdown' setting of $ctx.
2175 my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2177 # $ctx - value corresponding to openssl's SSL_CTX structure
2178 #
2179 # returns: (integer) the current setting
2180 Check openssl doc
2182 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2183 · CTX_get_read_ahead
2185 my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2187 # $ctx - value corresponding to openssl's SSL_CTX structure
2188 #
2189 # returns: (integer) read_ahead value
2190 · CTX_get_session_cache_mode
2192 Returns the currently used cache mode (bitmask).
2194 my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2196 # $ctx - value corresponding to openssl's SSL_CTX structure
2197 #
2198 # returns: mode (bitmask)
2199 #to decode the return value (bitmask) use:
2201 0x0000 corresponds to SSL_SESS_CACHE_OFF
2202 0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2203 0x0002 corresponds to SSL_SESS_CACHE_SERVER
2204 0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2205 0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2206 0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2207 (note: some of the bits might not be supported by older openssl versions)
2208 Check openssl doc
2210 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2211 · CTX_set_session_cache_mode
2213 Enables/disables session caching by setting the operational mode
2215 for $ctx to $mode.
2216 my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2218 # $ctx - value corresponding to openssl's SSL_CTX structure
2219 # $mode - mode (bitmask)
2220 #
2221 # returns: previously set cache mode
2222 For bitmask details see "CTX_get_session_cache_mode" (above).
2224 Check openssl doc
2226 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2227 · CTX_get_timeout
2229 Returns the currently set timeout value for $ctx.
2231 my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2233 # $ctx - value corresponding to openssl's SSL_CTX structure
2234 #
2235 # returns: timeout in seconds
2236 Check openssl doc
2238 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2239 · CTX_get_verify_depth
2241 Returns the verification depth limit currently set in $ctx. If no
2243 limit has been explicitly set, -1 is returned and the default value
2244 will be used.",
2245 my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2247 # $ctx - value corresponding to openssl's SSL_CTX structure
2248 #
2249 # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2250 Check openssl doc
2252 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2253 · CTX_get_verify_mode
2255 Returns the verification mode (bitmask) currently set in $ctx.
2257 my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2259 # $ctx - value corresponding to openssl's SSL_CTX structure
2260 #
2261 # returns: mode (bitmask)
2262 #to decode the return value (bitmask) use:
2264 0x00 corresponds to SSL_VERIFY_NONE
2265 0x01 corresponds to SSL_VERIFY_PEER
2266 0x02 corresponds to SSL_VERIFY_FAIL_IF_NO_PEER_CERT
2267 0x04 corresponds to SSL_VERIFY_CLIENT_ONCE
2268 (note: some of the bits might not be supported by older openssl versions)
2269 Check openssl doc
2271 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2272 · CTX_set_verify
2274 Sets the verification flags for $ctx to be $mode and specifies the
2276 verify_callback function to be used.
2277 Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2279 # $ctx - value corresponding to openssl's SSL_CTX structure
2280 # $mode - mode (bitmask)
2281 # $callback - [optional] reference to perl callback function
2282 #
2283 # returns: no return value
2284 For bitmask details see "CTX_get_verify_mode" (above).
2286 Check openssl doc
2288 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
2289 · CTX_load_verify_locations
2291 Specifies the locations for $ctx, at which CA certificates for
2293 verification purposes are located. The certificates available via
2294 $CAfile and $CApath are trusted.
2295 my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2297 # $ctx - value corresponding to openssl's SSL_CTX structure
2298 # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2299 # $CApath - (string) directory containing CA certificates in PEM format (or '')
2300 #
2301 # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2302 Check openssl doc
2304 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2305 · CTX_need_tmp_RSA
2307 Return the result of
2309 "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2310 my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2312 # $ctx - value corresponding to openssl's SSL_CTX structure
2313 #
2314 # returns: result of SSL_CTRL_NEED_TMP_RSA command
2315 · CTX_new
2317 The same as "CTX_v23_new"
2319 my $rv = Net::SSLeay::CTX_new();
2321 #
2322 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2323 Check openssl doc
2325 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2326 · CTX_v2_new
2328 Creates a new SSL_CTX object - based on SSLv2_method() - as
2330 framework to establish TLS/SSL enabled connections.
2331 my $rv = Net::SSLeay::CTX_v2_new();
2333 #
2334 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2335 · CTX_v23_new
2337 Creates a new SSL_CTX object - based on SSLv23_method() - as
2339 framework to establish TLS/SSL enabled connections.
2340 my $rv = Net::SSLeay::CTX_v23_new();
2342 #
2343 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2344 · CTX_v3_new
2346 Creates a new SSL_CTX object - based on SSLv3_method() - as
2348 framework to establish TLS/SSL enabled connections.
2349 my $rv = Net::SSLeay::CTX_v3_new();
2351 #
2352 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2353 · CTX_tlsv1_new
2355 Creates a new SSL_CTX object - based on TLSv1_method() - as
2357 framework to establish TLS/SSL enabled connections.
2358 my $rv = Net::SSLeay::CTX_tlsv1_new();
2360 #
2361 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2362 · CTX_tlsv1_1_new
2364 Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2366 framework to establish TLS/SSL enabled connections. Only available
2367 where supported by the underlying openssl.
2368 my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2370 #
2371 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2372 · CTX_tlsv1_2_new
2374 Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2376 framework to establish TLS/SSL enabled connections. Only available
2377 where supported by the underlying openssl.
2378 my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2380 #
2381 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2382 · CTX_new_with_method
2384 Creates a new SSL_CTX object based on $meth method
2386 my $rv = Net::SSLeay::CTX_new_with_method($meth);
2388 # $meth - value corresponding to openssl's SSL_METHOD structure
2389 #
2390 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2391 #example
2393 my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2394 Check openssl doc
2396 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2397 · CTX_remove_session
2399 Removes the session $ses from the context $ctx.
2401 my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2403 # $ctx - value corresponding to openssl's SSL_CTX structure
2404 # $ses - value corresponding to openssl's SSL_SESSION structure
2405 #
2406 # returns: 1 on success, 0 on failure
2407 Check openssl doc
2409 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2410 · CTX_sess_accept
2412 my $rv = Net::SSLeay::CTX_sess_accept($ctx);
2414 # $ctx - value corresponding to openssl's SSL_CTX structure
2415 #
2416 # returns: number of started SSL/TLS handshakes in server mode
2417 Check openssl doc
2419 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2420 · CTX_sess_accept_good
2422 my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
2424 # $ctx - value corresponding to openssl's SSL_CTX structure
2425 #
2426 # returns: number of successfully established SSL/TLS sessions in server mode
2427 Check openssl doc
2429 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2430 · CTX_sess_accept_renegotiate
2432 my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
2434 # $ctx - value corresponding to openssl's SSL_CTX structure
2435 #
2436 # returns: number of start renegotiations in server mode
2437 Check openssl doc
2439 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2440 · CTX_sess_cache_full
2442 my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
2444 # $ctx - value corresponding to openssl's SSL_CTX structure
2445 #
2446 # returns: number of sessions that were removed because the maximum session cache size was exceeded
2447 Check openssl doc
2449 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2450 · CTX_sess_cb_hits
2452 my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
2454 # $ctx - value corresponding to openssl's SSL_CTX structure
2455 #
2456 # returns: number of successfully retrieved sessions from the external session cache in server mode
2457 Check openssl doc
2459 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2460 · CTX_sess_connect
2462 my $rv = Net::SSLeay::CTX_sess_connect($ctx);
2464 # $ctx - value corresponding to openssl's SSL_CTX structure
2465 #
2466 # returns: number of started SSL/TLS handshakes in client mode
2467 Check openssl doc
2469 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2470 · CTX_sess_connect_good
2472 my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
2474 # $ctx - value corresponding to openssl's SSL_CTX structure
2475 #
2476 # returns: number of successfully established SSL/TLS sessions in client mode
2477 Check openssl doc
2479 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2480 · CTX_sess_connect_renegotiate
2482 my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
2484 # $ctx - value corresponding to openssl's SSL_CTX structure
2485 #
2486 # returns: number of start renegotiations in client mode
2487 Check openssl doc
2489 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2490 · CTX_sess_get_cache_size
2492 Returns the currently valid session cache size.
2494 my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
2496 # $ctx - value corresponding to openssl's SSL_CTX structure
2497 #
2498 # returns: current size
2499 Check openssl doc
2501 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2502 · CTX_sess_hits
2504 my $rv = Net::SSLeay::CTX_sess_hits($ctx);
2506 # $ctx - value corresponding to openssl's SSL_CTX structure
2507 #
2508 # returns: number of successfully reused sessions
2509 Check openssl doc
2511 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2512 · CTX_sess_misses
2514 my $rv = Net::SSLeay::CTX_sess_misses($ctx);
2516 # $ctx - value corresponding to openssl's SSL_CTX structure
2517 #
2518 # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
2519 Check openssl doc
2521 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2522 · CTX_sess_number
2524 my $rv = Net::SSLeay::CTX_sess_number($ctx);
2526 # $ctx - value corresponding to openssl's SSL_CTX structure
2527 #
2528 # returns: current number of sessions in the internal session cache
2529 Check openssl doc
2531 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2532 · CTX_sess_set_cache_size
2534 Sets the size of the internal session cache of context $ctx to
2536 $size.
2537 Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
2539 # $ctx - value corresponding to openssl's SSL_CTX structure
2540 # $size - cache size (0 = unlimited)
2541 #
2542 # returns: previously valid size
2543 Check openssl doc
2545 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2546 · CTX_sess_timeouts
2548 Returns the number of sessions proposed by clients and either found
2550 in the internal or external session cache in server mode, but that
2551 were invalid due to timeout. These sessions are not included in the
2552 SSL_CTX_sess_hits count.
2553 my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
2555 # $ctx - value corresponding to openssl's SSL_CTX structure
2556 #
2557 # returns: number of sessions
2558 Check openssl doc
2560 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2561 · CTX_sessions
2563 Returns a pointer to the lhash databases containing the internal
2565 session cache for ctx.
2566 my $rv = Net::SSLeay::CTX_sessions($ctx);
2568 # $ctx - value corresponding to openssl's SSL_CTX structure
2569 #
2570 # returns: value corresponding to openssl's LHASH structure (0 on failure)
2571 Check openssl doc
2573 <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
2574 · CTX_set1_param
2576 Applies X509 verification parameters $vpm on $ctx
2578 my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
2580 # $ctx - value corresponding to openssl's SSL_CTX structure
2581 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
2582 #
2583 # returns: 1 on success, 0 on failure
2584 · CTX_set_cert_store
2586 Sets/replaces the certificate verification storage of $ctx to/with
2588 $store.
2589 Net::SSLeay::CTX_set_cert_store($ctx, $store);
2591 # $ctx - value corresponding to openssl's SSL_CTX structure
2592 # $store - value corresponding to openssl's X509_STORE structure
2593 #
2594 # returns: no return value
2595 Check openssl doc
2597 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2598 · CTX_set_cert_verify_callback
2600 Sets the verification callback function for $ctx. SSL objects that
2602 are created from $ctx inherit the setting valid at the time when
2603 "Net::SSLeay::new($ctx)" is called.
2604 Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
2606 # $ctx - value corresponding to openssl's SSL_CTX structure
2607 # $func - perl reference to callback function
2608 # $data - [optional] data that will be passed to callback function when invoked
2609 #
2610 # returns: no return value
2611 Check openssl doc
2613 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
2614 · CTX_set_cipher_list
2616 Sets the list of available ciphers for $ctx using the control
2618 string $str. The list of ciphers is inherited by all ssl objects
2619 created from $ctx.
2620 my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
2622 # $s - value corresponding to openssl's SSL_CTX structure
2623 # $str - (string) cipher list e.g. '3DES:+RSA'
2624 #
2625 # returns: 1 if any cipher could be selected and 0 on complete failure
2626 The format of $str is described in
2628 <http://www.openssl.org/docs/apps/ciphers.html>
2629 Check openssl doc
2631 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
2632 · CTX_set_client_CA_list
2634 Sets the list of CAs sent to the client when requesting a client
2636 certificate for $ctx.
2637 Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
2639 # $ctx - value corresponding to openssl's SSL_CTX structure
2640 # $list - value corresponding to openssl's X509_NAME_STACK structure
2641 #
2642 # returns: no return value
2643 Check openssl doc
2645 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2646 · CTX_set_default_passwd_cb
2648 Sets the default password callback called when loading/storing a
2650 PEM certificate with encryption.
2651 Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
2653 # $ctx - value corresponding to openssl's SSL_CTX structure
2654 # $func - perl reference to callback function
2655 #
2656 # returns: no return value
2657 Check openssl doc
2659 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
2660 · CTX_set_default_passwd_cb_userdata
2662 Sets a pointer to userdata which will be provided to the password
2664 callback on invocation.
2665 Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
2667 # $ctx - value corresponding to openssl's SSL_CTX structure
2668 # $userdata - data that will be passed to callback function when invoked
2669 #
2670 # returns: no return value
2671 Check openssl doc
2673 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
2674 · CTX_set_default_verify_paths
2676 ??? (more info needed)
2678 my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
2680 # $ctx - value corresponding to openssl's SSL_CTX structure
2681 #
2682 # returns: 1 on success, 0 on failure
2683 · CTX_set_ex_data
2685 Is used to store application data at $data for $idx into the $ctx
2687 object.
2688 my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
2690 # $ssl - value corresponding to openssl's SSL_CTX structure
2691 # $idx - (integer) ???
2692 # $data - (pointer) ???
2693 #
2694 # returns: 1 on success, 0 on failure
2695 Check openssl doc
2697 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2698 · CTX_set_purpose
2700 my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
2702 # $s - value corresponding to openssl's SSL_CTX structure
2703 # $purpose - (integer) purpose identifier
2704 #
2705 # returns: 1 on success, 0 on failure
2706 #avainable purpose identifier
2708 1 - X509_PURPOSE_SSL_CLIENT
2709 2 - X509_PURPOSE_SSL_SERVER
2710 3 - X509_PURPOSE_NS_SSL_SERVER
2711 4 - X509_PURPOSE_SMIME_SIGN
2712 5 - X509_PURPOSE_SMIME_ENCRYPT
2713 6 - X509_PURPOSE_CRL_SIGN
2714 7 - X509_PURPOSE_ANY
2715 8 - X509_PURPOSE_OCSP_HELPER
2716 9 - X509_PURPOSE_TIMESTAMP_SIGN
2717 #or use corresponding constants
2719 $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
2720 ...
2721 $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
2722 · CTX_set_quiet_shutdown
2724 Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
2726 created from $ctx inherit the mode valid at the time
2727 "Net::SSLeay::new($ctx)" is called.
2728 Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
2730 # $ctx - value corresponding to openssl's SSL_CTX structure
2731 # $mode - 0 or 1
2732 #
2733 # returns: no return value
2734 Check openssl doc
2736 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2737 · CTX_set_read_ahead
2739 my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
2741 # $ctx - value corresponding to openssl's SSL_CTX structure
2742 # $val - read_ahead value to be set
2743 #
2744 # returns: the original read_ahead value
2745 · CTX_set_session_id_context
2747 Sets the context $sid_ctx of length $sid_ctx_len within which a
2749 session can be reused for the $ctx object.
2750 my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
2752 # $ctx - value corresponding to openssl's SSL_CTX structure
2753 # $sid_ctx - data buffer
2754 # $sid_ctx_len - length of data in $sid_ctx
2755 #
2756 # returns: 1 on success, 0 on failure (the error is logged to the error stack)
2757 Check openssl doc
2759 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
2760 · CTX_set_ssl_version
2762 Sets a new default TLS/SSL method for SSL objects newly created
2764 from this $ctx. SSL objects already created with
2765 "Net::SSLeay::new($ctx)" are not affected, except when
2766 "Net::SSLeay:clear($ssl)" is being called.
2767 my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
2769 # $ctx - value corresponding to openssl's SSL_CTX structure
2770 # $meth - value corresponding to openssl's SSL_METHOD structure
2771 #
2772 # returns: 1 on success, 0 on failure
2773 Check openssl doc
2775 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
2776 · CTX_set_timeout
2778 Sets the timeout for newly created sessions for $ctx to $t. The
2780 timeout value $t must be given in seconds.
2781 my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
2783 # $ctx - value corresponding to openssl's SSL_CTX structure
2784 # $t - timeout in seconds
2785 #
2786 # returns: previously set timeout value
2787 Check openssl doc
2789 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2790 · CTX_set_tmp_dh
2792 Sets DH parameters to be used to be $dh. The key is inherited by
2794 all ssl objects created from $ctx.
2795 my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
2797 # $ctx - value corresponding to openssl's SSL_CTX structure
2798 # $dh - value corresponding to openssl's DH structure
2799 #
2800 # returns: 1 on success, 0 on failure
2801 Check openssl doc
2803 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
2804 · CTX_set_tmp_dh_callback
2806 Sets the callback function for $ctx to be used when a DH parameters
2808 are required to $tmp_dh_callback.
2809 Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
2811 # $ctx - value corresponding to openssl's SSL_CTX structure
2812 # tmp_dh_callback - (function pointer) ???
2813 #
2814 # returns: no return value
2815 Check openssl doc
2817 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
2818 · CTX_set_tmp_rsa
2820 Sets the temporary/ephemeral RSA key to be used to be $rsa.
2822 my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
2824 # $ctx - value corresponding to openssl's SSL_CTX structure
2825 # $rsa - value corresponding to openssl's RSA structure
2826 #
2827 # returns: 1 on success, 0 on failure
2828 Check openssl doc
2830 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
2831 · CTX_set_tmp_rsa_callback
2833 Sets the callback function for ctx to be used when a
2835 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
2836 ??? (does this function really work?)
2838 Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
2840 # $ctx - value corresponding to openssl's SSL_CTX structure
2841 # $tmp_rsa_callback - (function pointer) ???
2842 #
2843 # returns: no return value
2844 Check openssl doc
2846 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
2847 · CTX_set_trust
2849 my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
2851 # $s - value corresponding to openssl's SSL_CTX structure
2852 # $trust - (integer) trust identifier
2853 #
2854 # returns: the original value
2855 #available trust identifiers
2857 1 - X509_TRUST_COMPAT
2858 2 - X509_TRUST_SSL_CLIENT
2859 3 - X509_TRUST_SSL_SERVER
2860 4 - X509_TRUST_EMAIL
2861 5 - X509_TRUST_OBJECT_SIGN
2862 6 - X509_TRUST_OCSP_SIGN
2863 7 - X509_TRUST_OCSP_REQUEST
2864 8 - X509_TRUST_TSA
2865 #or use corresponding constants
2867 $trust = &Net::SSLeay::X509_TRUST_COMPAT;
2868 ...
2869 $trust = &Net::SSLeay::X509_TRUST_TSA;
2870 · CTX_set_verify_depth
2872 Sets the maximum depth for the certificate chain verification that
2874 shall be allowed for ctx.
2875 Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
2877 # $ctx - value corresponding to openssl's SSL_CTX structure
2878 # $depth - max. depth
2879 #
2880 # returns: no return value
2881 Check openssl doc
2883 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
2884 · CTX_use_PKCS12_file
2886 Adds the certificate and private key from PKCS12 file $p12filename
2888 to $ctx.
2889 my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
2891 # $ctx - value corresponding to openssl's SSL_CTX structure
2892 # $p12filename - (string) filename
2893 # $password - (string) password to decrypt private key
2894 #
2895 # returns: 1 on success, 0 on failure
2896 · CTX_use_PrivateKey
2898 Adds the private key $pkey to $ctx.
2900 my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
2902 # $ctx - value corresponding to openssl's SSL_CTX structure
2903 # $pkey - value corresponding to openssl's EVP_PKEY structure
2904 #
2905 # returns: 1 on success, otherwise check out the error stack to find out the reason
2906 Check openssl doc
2908 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2909 · CTX_use_PrivateKey_file
2911 Adds the first private key found in $file to $ctx.
2913 my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
2915 # $ctx - value corresponding to openssl's SSL_CTX structure
2916 # $file - (string) file name
2917 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
2918 #
2919 # returns: 1 on success, otherwise check out the error stack to find out the reason
2920 Check openssl doc
2922 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2923 · CTX_use_RSAPrivateKey
2925 Adds the RSA private key $rsa to $ctx.
2927 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
2929 # $ctx - value corresponding to openssl's SSL_CTX structure
2930 # $rsa - value corresponding to openssl's RSA structure
2931 #
2932 # returns: 1 on success, otherwise check out the error stack to find out the reason
2933 Check openssl doc
2935 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2936 · CTX_use_RSAPrivateKey_file
2938 Adds the first RSA private key found in $file to $ctx.
2940 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
2942 # $ctx - value corresponding to openssl's SSL_CTX structure
2943 # $file - (string) file name
2944 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
2945 #
2946 # returns: 1 on success, otherwise check out the error stack to find out the reason
2947 · CTX_use_certificate
2949 Loads the certificate $x into $ctx
2951 my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
2953 # $ctx - value corresponding to openssl's SSL_CTX structure
2954 # $x - value corresponding to openssl's X509 structure
2955 #
2956 # returns: 1 on success, otherwise check out the error stack to find out the reason
2957 Check openssl doc
2959 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2960 · CTX_use_certificate_chain_file
2962 Loads a certificate chain from $file into $ctx. The certificates
2964 must be in PEM format and must be sorted starting with the
2965 subject's certificate (actual client or server certificate),
2966 followed by intermediate CA certificates if applicable, and ending
2967 at the highest level (root) CA.
2968 my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
2970 # $ctx - value corresponding to openssl's SSL_CTX structure
2971 # $file - (string) file name
2972 #
2973 # returns: 1 on success, otherwise check out the error stack to find out the reason
2974 Check openssl doc
2976 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2977 · CTX_use_certificate_file
2979 Loads the first certificate stored in $file into $ctx.
2981 my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
2983 # $ctx - value corresponding to openssl's SSL_CTX structure
2984 # $file - (string) file name
2985 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
2986 #
2987 # returns: 1 on success, otherwise check out the error stack to find out the reason
2988 Check openssl doc
2990 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2991 Low level API: SSL_* related functions
2993 NOTE: Please note that the function described in this chapter have
2995 "SSL_" part stripped from their original openssl names.
2996 · new
2998 Creates a new SSL structure which is needed to hold the data for a
3000 TLS/SSL connection. The new structure inherits the settings of the
3001 underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3002 options, verification settings, timeout settings.
3003 my $rv = Net::SSLeay::new($ctx);
3005 # $ctx - value corresponding to openssl's SSL_CTX structure
3006 #
3007 # returns: value corresponding to openssl's SSL structure (0 on failure)
3008 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3010 · accept
3012 Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3014 communication channel must already have been set and assigned to
3015 the ssl by setting an underlying BIO.
3016 my $rv = Net::SSLeay::accept($ssl);
3018 # $ssl - value corresponding to openssl's SSL structure
3019 #
3020 # returns: 1 = success, 0 = handshake not successfull, <0 = fatal error during handshake
3021 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3023 · add_client_CA
3025 Adds the CA name extracted from cacert to the list of CAs sent to
3027 the client when requesting a client certificate for the chosen ssl,
3028 overriding the setting valid for ssl's SSL_CTX object.
3029 my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3031 # $ssl - value corresponding to openssl's SSL structure
3032 # $x - value corresponding to openssl's X509 structure
3033 #
3034 # returns: 1 on success, 0 on failure
3035 Check openssl doc
3037 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3038 · callback_ctrl
3040 ??? (more info needed)
3042 my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3044 # $ssl - value corresponding to openssl's SSL structure
3045 # $cmd - (integer) command id
3046 # $fp - (function pointer) ???
3047 #
3048 # returns: ???
3049 Check openssl doc
3051 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3052 · check_private_key
3054 Checks the consistency of a private key with the corresponding
3056 certificate loaded into $ssl
3057 my $rv = Net::SSLeay::check_private_key($ssl);
3059 # $ssl - value corresponding to openssl's SSL structure
3060 #
3061 # returns: 1 on success, otherwise check out the error stack to find out the reason
3062 Check openssl doc
3064 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3065 · clear
3067 Reset SSL object to allow another connection.
3069 Net::SSLeay::clear($ssl);
3071 # $ssl - value corresponding to openssl's SSL structure
3072 #
3073 # returns: no return value
3074 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3076 · connect
3078 Initiate the TLS/SSL handshake with an TLS/SSL server.
3080 my $rv = Net::SSLeay::connect($ssl);
3082 # $ssl - value corresponding to openssl's SSL structure
3083 #
3084 # returns: 1 = success, 0 = handshake not successfull, <0 = fatal error during handshake
3085 Check openssl doc
3087 <http://www.openssl.org/docs/ssl/SSL_connect.html>
3088 · copy_session_id
3090 Copies the session structure fro $from to $to (+ also the private
3092 key and certificate associated with $from).
3093 Net::SSLeay::copy_session_id($to, $from);
3095 # $to - value corresponding to openssl's SSL structure
3096 # $from - value corresponding to openssl's SSL structure
3097 #
3098 # returns: no return value
3099 · ctrl
3101 Internal handling function for SSL objects.
3103 BEWARE: openssl doc says: This function should never be called
3105 directly!
3106 my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3108 # $ssl - value corresponding to openssl's SSL structure
3109 # $cmd - (integer) command id
3110 # $larg - (integer) long ???
3111 # $parg - (string/pointer) ???
3112 #
3113 # returns: (long) result of given command ???
3114 For more details about valid $cmd values check "CTX_ctrl".
3116 Check openssl doc
3118 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3119 · do_handshake
3121 Will wait for a SSL/TLS handshake to take place. If the connection
3123 is in client mode, the handshake will be started. The handshake
3124 routines may have to be explicitly set in advance using either
3125 SSL_set_connect_state or SSL_set_accept_state(3).
3126 my $rv = Net::SSLeay::do_handshake($ssl);
3128 # $ssl - value corresponding to openssl's SSL structure
3129 #
3130 # returns: 1 = success, 0 = handshake not successfull, <0 = fatal error during handshake
3131 Check openssl doc
3133 <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3134 · dup
3136 Returns a duplicate of $ssl.
3138 my $rv = Net::SSLeay::dup($ssl);
3140 # $ssl - value corresponding to openssl's SSL structure
3141 #
3142 # returns: value corresponding to openssl's SSL structure (0 on failure)
3143 · free
3145 Free an allocated SSL structure.
3147 Net::SSLeay::free($ssl);
3149 # $ssl - value corresponding to openssl's SSL structure
3150 #
3151 # returns: no return value
3152 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3154 · get_SSL_CTX
3156 Returns a pointer to the SSL_CTX object, from which $ssl was
3158 created with Net::SSLeay::new.
3159 my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3161 # $ssl - value corresponding to openssl's SSL structure
3162 #
3163 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3164 Check openssl doc
3166 <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3167 · set_SSL_CTX
3169 Sets the SSL_CTX the corresponds to an SSL session.
3171 my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3173 # $ssl - value corresponding to openssl's SSL structure
3174 # $ssl_ctx - Change the ssl object to the given ssl_ctx
3175 #
3176 # returns - the ssl_ctx
3177 · get_app_data
3179 Can be used to get application defined value/data.
3181 my $rv = Net::SSLeay::get_app_data($ssl);
3183 # $ssl - value corresponding to openssl's SSL structure
3184 #
3185 # returns: string/buffer/pointer ???
3186 · set_app_data
3188 Can be used to set some application defined value/data.
3190 my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3192 # $ssl - value corresponding to openssl's SSL structure
3193 # $arg - (string/buffer/pointer ???) data
3194 #
3195 # returns: ???
3196 · get_certificate
3198 Gets X509 certificate from an established SSL connection.
3200 my $rv = Net::SSLeay::get_certificate($ssl);
3202 # $ssl - value corresponding to openssl's SSL structure
3203 #
3204 # returns: value corresponding to openssl's X509 structure (0 on failure)
3205 · get_cipher
3207 Obtains the name of the currently used cipher.
3209 my $rv = Net::SSLeay::get_cipher($ssl);
3211 # $ssl - value corresponding to openssl's SSL structure
3212 #
3213 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3214 Check openssl doc
3216 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3217 · get_cipher_bits
3219 Obtain the number of secret/algorithm bits used.
3221 my $rv = Net::SSLeay::get_cipher_bits($ssl);
3223 # $ssl - value corresponding to openssl's SSL structure
3224 #
3225 # returns: number of secret bits used by current cipher
3226 Check openssl doc
3228 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3229 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3230 · get_cipher_list
3232 Returns the name (string) of the SSL_CIPHER listed for $ssl with
3234 priority $n.
3235 my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
3237 # $ssl - value corresponding to openssl's SSL structure
3238 # $n - (integer) priority
3239 #
3240 # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or '' in case of error
3241 Call Net::SSLeay::get_cipher_list with priority starting from 0 to
3243 obtain the sorted list of available ciphers, until '' is returned:
3244 my $priority = 0;
3246 while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
3247 print "cipher[$priority] = $c\n";
3248 $priority++;
3249 }
3250 Check openssl doc
3252 <http://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
3253 · get_client_CA_list
3255 Returns the list of client CAs explicitly set for $ssl using
3257 "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
3258 "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
3259 In client mode, returns the list of client CAs sent from the
3261 server, if any.
3262 my $rv = Net::SSLeay::get_client_CA_list($ssl);
3264 # $ssl - value corresponding to openssl's SSL structure
3265 #
3266 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
3267 Check openssl doc
3269 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
3270 · get_current_cipher
3272 Returns the cipher actually used.
3274 my $rv = Net::SSLeay::get_current_cipher($ssl);
3276 # $ssl - value corresponding to openssl's SSL structure
3277 #
3278 # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
3279 Check openssl doc
3281 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3282 · get_default_timeout
3284 Returns the default timeout value assigned to SSL_SESSION objects
3286 negotiated for the protocol valid for $ssl.
3287 my $rv = Net::SSLeay::get_default_timeout($ssl);
3289 # $ssl - value corresponding to openssl's SSL structure
3290 #
3291 # returns: (long) timeout in seconds
3292 Check openssl doc
3294 <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
3295 · get_error
3297 Returns a result code for a preceding call to "connect", "accept",
3299 "do_handshake", "read", "peek" or "write" on $ssl.
3300 my $rv = Net::SSLeay::get_error($ssl, $ret);
3302 # $ssl - value corresponding to openssl's SSL structure
3303 # $ret - return value of preceding TLS/SSL I/O operation
3304 #
3305 # returns: result code, which is one of the following values:
3306 # 0 - SSL_ERROR_NONE
3307 # 1 - SSL_ERROR_SSL
3308 # 2 - SSL_ERROR_WANT_READ
3309 # 3 - SSL_ERROR_WANT_WRITE
3310 # 4 - SSL_ERROR_WANT_X509_LOOKUP
3311 # 5 - SSL_ERROR_SYSCALL
3312 # 6 - SSL_ERROR_ZERO_RETURN
3313 # 7 - SSL_ERROR_WANT_CONNECT
3314 # 8 - SSL_ERROR_WANT_ACCEPT
3315 Check openssl doc
3317 <http://www.openssl.org/docs/ssl/SSL_get_error.html>
3318 · get_ex_data
3320 Is used to retrieve the information for $idx from $ssl.
3322 my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
3324 # $ssl - value corresponding to openssl's SSL structure
3325 # $idx - (integer) index for application specific data
3326 #
3327 # returns: pointer to ???
3328 Check openssl doc
3330 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3331 · set_ex_data
3333 Is used to store application data at $data for $idx into the $ssl
3335 object.
3336 my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
3338 # $ssl - value corresponding to openssl's SSL structure
3339 # $idx - (integer) ???
3340 # $data - (pointer) ???
3341 #
3342 # returns: 1 on success, 0 on failure
3343 Check openssl doc
3345 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3346 · get_ex_new_index
3348 Is used to register a new index for application specific data.
3350 my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
3352 # $argl - (long) ???
3353 # $argp - (pointer) ???
3354 # $new_func - function pointer ??? (CRYPTO_EX_new *)
3355 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
3356 # $free_func - function pointer ??? (CRYPTO_EX_free *)
3357 #
3358 # returns: (integer) ???
3359 Check openssl doc
3361 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3362 · get_fd
3364 Returns the file descriptor which is linked to $ssl.
3366 my $rv = Net::SSLeay::get_fd($ssl);
3368 # $ssl - value corresponding to openssl's SSL structure
3369 #
3370 # returns: file descriptor (>=0) or -1 on failure
3371 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
3373 · get_finished
3375 Obtains the latest 'Finished' message sent to the peer.
3377 ??? (does this function really work?)
3379 my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
3381 # $ssl - value corresponding to openssl's SSL structure
3382 # $buf - buffer where the returned data will be stored (pointer ???, pre-allocated ???)
3383 # $count - max. size of return data
3384 #
3385 # returns: actual size of the returned data in $buf
3386 · get_peer_finished
3388 Obtains the latest 'Finished' message expected from the peer.
3390 ??? (does this function really work?)
3392 my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
3394 # $ssl - value corresponding to openssl's SSL structure
3395 # $buf - buffer where the returned data will be stored (pointer ???, pre-allocated ???)
3396 # $count - max. size of the return data
3397 #
3398 # returns: actual size of the returned data in $buf
3399 · get_keyblock_size
3401 NOTE: Does not exactly correspond to any low level API function.
3403 ??? (more info needed)
3405 my $rv = Net::SSLeay::get_keyblock_size($ssl);
3407 # $ssl - value corresponding to openssl's SSL structure
3408 #
3409 # returns: keyblock size, -1 on error
3410 · get_mode
3412 Returns the mode (bitmask) set for $ssl.
3414 my $rv = Net::SSLeay::get_mode($ssl);
3416 # $ssl - value corresponding to openssl's SSL structure
3417 #
3418 # returns: mode (bitmask)
3419 To decode the return value (bitmask) see documentation for
3421 "CTX_get_mode".
3422 Check openssl doc
3424 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3425 · set_mode
3427 Adds the mode set via bitmask in $mode to $ssl. Options already set
3429 before are not cleared.
3430 my $rv = Net::SSLeay::set_mode($ssl, $mode);
3432 # $ssl - value corresponding to openssl's SSL structure
3433 # $mode - mode (bitmask)
3434 #
3435 # returns: the new mode bitmask after adding $mode
3436 For $mode bitmask details see "CTX_get_mode".
3438 Check openssl doc
3440 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3441 · get_options
3443 Returns the options (bitmask) set for $ssl.
3445 my $rv = Net::SSLeay::get_options($ssl);
3447 # $ssl - value corresponding to openssl's SSL structure
3448 #
3449 # returns: options (bitmask)
3450 To decode the return value (bitmask) see documentation for
3452 "CTX_get_options".
3453 Check openssl doc
3455 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
3456 · set_options
3458 Adds the options set via bitmask in $options to $ssl. Options
3460 already set before are not cleared!
3461 Net::SSLeay::set_options($ssl, $options);
3463 # $ssl - value corresponding to openssl's SSL structure
3464 # $options - options (bitmask)
3465 #
3466 # returns: the new options bitmask after adding $options
3467 For $options bitmask details see "CTX_get_options".
3469 Check openssl doc
3471 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
3472 · get_peer_certificate
3474 Get the X509 certificate of the peer.
3476 my $rv = Net::SSLeay::get_peer_certificate($ssl);
3478 # $ssl - value corresponding to openssl's SSL structure
3479 #
3480 # returns: value corresponding to openssl's X509 structure (0 on failure)
3481 Check openssl doc
3483 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
3484 · get_quiet_shutdown
3486 Returns the 'quiet shutdown' setting of ssl.
3488 my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
3490 # $ssl - value corresponding to openssl's SSL structure
3491 #
3492 # returns: (integer) current 'quiet shutdown' value
3493 Check openssl doc
3495 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3496 · get_rbio
3498 Get 'read' BIO linked to an SSL object $ssl.
3500 my $rv = Net::SSLeay::get_rbio($ssl);
3502 # $ssl - value corresponding to openssl's SSL structure
3503 #
3504 # returns: value corresponding to openssl's BIO structure (0 on failure)
3505 Check openssl doc
3507 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
3508 · get_read_ahead
3510 my $rv = Net::SSLeay::get_read_ahead($ssl);
3512 # $ssl - value corresponding to openssl's SSL structure
3513 #
3514 # returns: (integer) read_ahead value
3515 · set_read_ahead
3517 Net::SSLeay::set_read_ahead($ssl, $val);
3519 # $ssl - value corresponding to openssl's SSL structure
3520 # $val - read_ahead value to be set
3521 #
3522 # returns: the original read_ahead value
3523 · get_server_random
3525 Returns internal SSLv3 server_random value.
3527 Net::SSLeay::get_server_random($ssl);
3529 # $ssl - value corresponding to openssl's SSL structure
3530 #
3531 # returns: server_random value (binary data)
3532 · get_client_random
3534 NOTE: Does not exactly correspond to any low level API function
3536 Returns internal SSLv3 client_random value.
3538 Net::SSLeay::get_client_random($ssl);
3540 # $ssl - value corresponding to openssl's SSL structure
3541 #
3542 # returns: client_random value (binary data)
3543 · export_keying_material
3545 Returns a buffer of $req_len bytes of keying material based on the
3547 constant string $label using the masterkey and client and server
3548 random strings as described in draft-ietf-pppext-eap-ttls-01.txt
3549 and See rfc2716 If p is present, it will be concatenated before
3550 generating the keying material Returns undef on error
3551 my $out = Net::SSLeay::export_keying_material($ssl, $req_len, $label, $p);
3553 · get_session
3555 Retrieve TLS/SSL session data used in $ssl. The reference count of
3557 the SSL_SESSION is NOT incremented.
3558 my $rv = Net::SSLeay::get_session($ssl);
3560 # $ssl - value corresponding to openssl's SSL structure
3561 #
3562 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
3563 Check openssl doc
3565 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
3566 · SSL_get0_session
3568 The alias for "get_session" (note that the name is
3570 "SSL_get0_session" NOT "get0_session").
3571 my $rv = Net::SSLeay::SSL_get0_session();
3573 · get1_session
3575 Returns a pointer to the SSL_SESSION actually used in $ssl. The
3577 reference count of the SSL_SESSION is incremented by 1.
3578 my $rv = Net::SSLeay::get1_session($ssl);
3580 # $ssl - value corresponding to openssl's SSL structure
3581 #
3582 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
3583 Check openssl doc
3585 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
3586 · get_shared_ciphers
3588 Returns string with a list (colon ':' separated) of ciphers shared
3590 between client and server within SSL session $ssl.
3591 my $rv = Net::SSLeay::get_shared_ciphers()
3593 #
3594 # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
3595 · get_shutdown
3597 Returns the shutdown mode of $ssl.
3599 my $rv = Net::SSLeay::get_shutdown($ssl);
3601 # $ssl - value corresponding to openssl's SSL structure
3602 #
3603 # returns: shutdown mode (bitmask) of ssl
3604 #to decode the return value (bitmask) use:
3606 0 - No shutdown setting, yet
3607 1 - SSL_SENT_SHUTDOWN
3608 2 - SSL_RECEIVED_SHUTDOWN
3609 Check openssl doc
3611 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
3612 · get_ssl_method
3614 Returns a function pointer to the TLS/SSL method set in $ssl.
3616 my $rv = Net::SSLeay::get_ssl_method($ssl);
3618 # $ssl - value corresponding to openssl's SSL structure
3619 #
3620 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
3621 Check openssl doc
3623 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3624 · get_state
3626 Returns the SSL connection state.
3628 my $rv = Net::SSLeay::get_state($ssl);
3630 # $ssl - value corresponding to openssl's SSL structure
3631 #
3632 # returns: (integer) state value
3633 # to decode the returned state check:
3634 # SSL_ST_* constants in openssl/ssl.h
3635 # SSL2_ST_* constants in openssl/ssl2.h
3636 # SSL23_ST_* constants in openssl/ssl23.h
3637 # SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
3638 · state
3640 Exactly the same as "get_state".
3642 my $rv = Net::SSLeay::state($ssl);
3644 · get_verify_depth
3646 Returns the verification depth limit currently set in $ssl.
3648 my $rv = Net::SSLeay::get_verify_depth($ssl);
3650 # $ssl - value corresponding to openssl's SSL structure
3651 #
3652 # returns: current depth or -1 if no limit has been explicitly set
3653 Check openssl doc
3655 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
3656 · set_verify_depth
3658 Sets the maximum depth for the certificate chain verification that
3660 shall be allowed for $ssl.
3661 Net::SSLeay::set_verify_depth($ssl, $depth);
3663 # $ssl - value corresponding to openssl's SSL structure
3664 # $depth - (integer) depth
3665 #
3666 # returns: no return value
3667 Check openssl doc
3669 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3670 · get_verify_mode
3672 Returns the verification mode (bitmask) currently set in $ssl.
3674 my $rv = Net::SSLeay::get_verify_mode($ssl);
3676 # $ssl - value corresponding to openssl's SSL structure
3677 #
3678 # returns: mode (bitmask)
3679 To decode the return value (bitmask) see documentation for
3681 "CTX_get_verify_mode".
3682 Check openssl doc
3684 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
3685 · set_verify
3687 Sets the verification flags for $ssl to be $mode and specifies the
3689 $verify_callback function to be used.
3690 Net::SSLeay::set_verify($ssl, $mode, $callback);
3692 # $ssl - value corresponding to openssl's SSL structure
3693 # $mode - mode (bitmask)
3694 # $callback - [optional] reference to perl callback function
3695 #
3696 # returns: no return value
3697 For $mode bitmask details see "CTX_get_verify_mode".
3699 Check openssl doc
3701 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3702 · get_verify_result
3704 Returns the result of the verification of the X509 certificate
3706 presented by the peer, if any.
3707 my $rv = Net::SSLeay::get_verify_result($ssl);
3709 # $ssl - value corresponding to openssl's SSL structure
3710 #
3711 # returns: (integer)
3712 # 0 - X509_V_OK: ok
3713 # 2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
3714 # 3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
3715 # 4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
3716 # 5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
3717 # 6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
3718 # 7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
3719 # 8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
3720 # 9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
3721 # 10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
3722 # 11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
3723 # 12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
3724 # 13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
3725 # 14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
3726 # 15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
3727 # 16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
3728 # 17 - X509_V_ERR_OUT_OF_MEM: out of memory
3729 # 18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
3730 # 19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
3731 # 20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
3732 # 21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
3733 # 22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
3734 # 23 - X509_V_ERR_CERT_REVOKED: certificate revoked
3735 # 24 - X509_V_ERR_INVALID_CA: invalid CA certificate
3736 # 25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
3737 # 26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
3738 # 27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
3739 # 28 - X509_V_ERR_CERT_REJECTED: certificate rejected
3740 # 29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
3741 # 30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
3742 # 31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
3743 # 32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
3744 # 50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
3745 Check openssl doc
3747 <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
3748 · set_verify_result
3750 Override result of peer certificate verification.
3752 Net::SSLeay::set_verify_result($ssl, $v);
3754 # $ssl - value corresponding to openssl's SSL structure
3755 # $v - (integer) result value
3756 #
3757 # returns: no return value
3758 For more info about valid return values see "get_verify_result"
3760 Check openssl doc
3762 <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
3763 · get_wbio
3765 Get 'write' BIO linked to an SSL object $ssl.
3767 my $rv = Net::SSLeay::get_wbio($ssl);
3769 # $ssl - value corresponding to openssl's SSL structure
3770 #
3771 # returns: value corresponding to openssl's BIO structure (0 on failure)
3772 Check openssl doc
3774 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
3775 · load_client_CA_file
3777 Load X509 certificates from file (PEM formated).
3779 my $rv = Net::SSLeay::load_client_CA_file($file);
3781 # $file - (string) file name
3782 #
3783 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
3784 Check openssl doc
3786 <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
3787 · clear_num_renegotiations
3789 Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
3791 my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
3793 # $ssl - value corresponding to openssl's SSL structure
3794 #
3795 # returns: command result
3796 · need_tmp_RSA
3798 Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
3800 my $rv = Net::SSLeay::need_tmp_RSA($ssl);
3802 # $ssl - value corresponding to openssl's SSL structure
3803 #
3804 # returns: command result
3805 · num_renegotiations
3807 Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
3809 my $rv = Net::SSLeay::num_renegotiations($ssl);
3811 # $ssl - value corresponding to openssl's SSL structure
3812 #
3813 # returns: command result
3814 · total_renegotiations
3816 Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
3818 my $rv = Net::SSLeay::total_renegotiations($ssl);
3820 # $ssl - value corresponding to openssl's SSL structure
3821 #
3822 # returns: command result
3823 · peek
3825 Copies $max bytes from the specified $ssl into the returned value.
3827 In constrast to the "Net::SSLeay::read()" function, the data in the
3828 SSL buffer is unmodified after the SSL_peek() operation.
3829 Net::SSLeay::peek($ssl, $max);
3831 # $ssl - value corresponding to openssl's SSL structure
3832 # $max - [optional] max bytes to peek (integer) - default is 32768
3833 #
3834 # returns: read data, undef on error
3835 · pending
3837 Obtain number of readable bytes buffered in $ssl object.
3839 my $rv = Net::SSLeay::pending($ssl);
3841 # $ssl - value corresponding to openssl's SSL structure
3842 #
3843 # returns: the number of bytes pending
3844 Check openssl doc
3846 <http://www.openssl.org/docs/ssl/SSL_pending.html>
3847 · read
3849 Tries to read $max bytes from the specified $ssl.
3851 my $got = Net::SSLeay::read($ssl, $max);
3853 my($got, $rv) = Net::SSLeay::read($ssl, $max);
3854 # $ssl - value corresponding to openssl's SSL structure
3855 # $max - [optional] max bytes to read (integer) - default is 32768
3856 #
3857 # returns:
3858 # in scalar context: data read from the TLS/SSL connection, undef on error
3859 # in list context: two-item array consisting of data read (undef on error),
3860 # and return code from SSL_read().
3861 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
3863 · renegotiate
3865 Turn on flags for renegotiation so that renegotiation will happen
3867 my $rv = Net::SSLeay::renegotiate($ssl);
3869 # $ssl - value corresponding to openssl's SSL structure
3870 #
3871 # returns: 1 on success, 0 on failure
3872 · rstate_string
3874 Returns a 2 letter string indicating the current read state of the
3876 SSL object $ssl.
3877 my $rv = Net::SSLeay::rstate_string($ssl);
3879 # $ssl - value corresponding to openssl's SSL structure
3880 #
3881 # returns: 2-letter string
3882 Check openssl doc
3884 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
3885 · rstate_string_long
3887 Returns a string indicating the current read state of the SSL
3889 object ssl.
3890 my $rv = Net::SSLeay::rstate_string_long($ssl);
3892 # $ssl - value corresponding to openssl's SSL structure
3893 #
3894 # returns: string with current state
3895 Check openssl doc
3897 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
3898 · session_reused
3900 Query whether a reused session was negotiated during handshake.
3902 my $rv = Net::SSLeay::session_reused($ssl);
3904 # $ssl - value corresponding to openssl's SSL structure
3905 #
3906 # returns: 0 - new session was negotiated; 1 - session was reused.
3907 Check openssl doc
3909 <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
3910 · set1_param
3912 Applies X509 verification parameters $vpm on $ssl
3914 my $rv = Net::SSLeay::set1_param($ssl, $vpm);
3916 # $ssl - value corresponding to openssl's SSL structure
3917 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
3918 #
3919 # returns: 1 on success, 0 on failure
3920 · set_accept_state
3922 Sets $ssl to work in server mode.
3924 Net::SSLeay::set_accept_state($ssl);
3926 # $ssl - value corresponding to openssl's SSL structure
3927 #
3928 # returns: no return value
3929 Check openssl doc
3931 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
3932 · set_bio
3934 Connects the BIOs $rbio and $wbio for the read and write operations
3936 of the TLS/SSL (encrypted) side of $ssl.
3937 Net::SSLeay::set_bio($ssl, $rbio, $wbio);
3939 # $ssl - value corresponding to openssl's SSL structure
3940 # $rbio - value corresponding to openssl's BIO structure
3941 # $wbio - value corresponding to openssl's BIO structure
3942 #
3943 # returns: no return value
3944 Check openssl doc
3946 <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
3947 · set_cipher_list
3949 Sets the list of ciphers only for ssl.
3951 my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
3953 # $ssl - value corresponding to openssl's SSL structure
3954 # $str - (string) cipher list e.g. '3DES:+RSA'
3955 #
3956 # returns: 1 if any cipher could be selected and 0 on complete failure
3957 Check openssl doc
3959 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
3960 · set_client_CA_list
3962 Sets the list of CAs sent to the client when requesting a client
3964 certificate for the chosen $ssl, overriding the setting valid for
3965 $ssl's SSL_CTX object.
3966 my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
3968 # $ssl - value corresponding to openssl's SSL structure
3969 # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
3970 #
3971 # returns: no return value
3972 Check openssl doc
3974 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3975 · set_connect_state
3977 Sets $ssl to work in client mode.
3979 Net::SSLeay::set_connect_state($ssl);
3981 # $ssl - value corresponding to openssl's SSL structure
3982 #
3983 # returns: no return value
3984 Check openssl doc
3986 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
3987 · set_fd
3989 Sets the file descriptor $fd as the input/output facility for the
3991 TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
3992 file descriptor of a network connection.
3993 my $rv = Net::SSLeay::set_fd($ssl, $fd);
3995 # $ssl - value corresponding to openssl's SSL structure
3996 # $fd - (integer) file handle (got via perl's fileno)
3997 #
3998 # returns: 1 on success, 0 on failure
3999 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4001 · set_rfd
4003 Sets the file descriptor $fd as the input (read) facility for the
4005 TLS/SSL (encrypted) side of $ssl.
4006 my $rv = Net::SSLeay::set_rfd($ssl, $fd);
4008 # $ssl - value corresponding to openssl's SSL structure
4009 # $fd - (integer) file handle (got via perl's fileno)
4010 #
4011 # returns: 1 on success, 0 on failure
4012 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4014 · set_wfd
4016 my $rv = Net::SSLeay::set_wfd($ssl, $fd);
4018 # $ssl - value corresponding to openssl's SSL structure
4019 # $fd - (integer) file handle (got via perl's fileno)
4020 #
4021 # returns: 1 on success, 0 on failure
4022 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4024 · set_info_callback
4026 Sets the callback function, that can be used to obtain state
4028 information for $ssl during connection setup and use. When
4029 callback is 0 (NULL), the callback setting currently valid for ctx
4030 is used.
4031 ??? (does this function really work?)
4033 Net::SSLeay::set_info_callback($ssl, $cb);
4035 # $ssl - value corresponding to openssl's SSL structure
4036 # $cb - pointer to function ???
4037 #
4038 # returns: no return value
4039 Check openssl doc
4041 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4042 · set_pref_cipher
4044 Sets the list of available ciphers for $ssl using the control
4046 string $str.
4047 my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
4049 # $ssl - value corresponding to openssl's SSL structure
4050 # $str - (string) cipher list e.g. '3DES:+RSA'
4051 #
4052 # returns: 1 if any cipher could be selected and 0 on complete failure
4053 Check openssl doc
4055 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4056 · set_purpose
4058 my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
4060 # $ssl - value corresponding to openssl's SSL structure
4061 # $purpose - (integer) purpose identifier
4062 #
4063 # returns: 1 on success, 0 on failure
4064 For more info about available $purpose identifiers see
4066 "CTX_set_purpose".
4067 · set_quiet_shutdown
4069 Sets the 'quiet shutdown' flag for $ssl to be $mode.
4071 Net::SSLeay::set_quiet_shutdown($ssl, $mode);
4073 # $ssl - value corresponding to openssl's SSL structure
4074 # $mode - 0 or 1
4075 #
4076 # returns: no return value
4077 Check openssl doc
4079 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4080 · set_session
4082 Set a TLS/SSL session to be used during TLS/SSL connect.
4084 my $rv = Net::SSLeay::set_session($to, $ses);
4086 # $to - value corresponding to openssl's SSL structure
4087 # $ses - value corresponding to openssl's SSL_SESSION structure
4088 #
4089 # returns: 1 on success, 0 on failure
4090 Check openssl doc
4092 <http://www.openssl.org/docs/ssl/SSL_set_session.html>
4093 · set_session_id_context
4095 Sets the context $sid_ctx of length $sid_ctx_len within which a
4097 session can be reused for the $ssl object.
4098 my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
4100 # $ssl - value corresponding to openssl's SSL structure
4101 # $sid_ctx - data buffer
4102 # $sid_ctx_len - length of data in $sid_ctx
4103 #
4104 # returns: 1 on success, 0 on failure
4105 Check openssl doc
4107 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
4108 · set_session_secret_cb
4110 Setup pre-shared secret session resumption function.
4112 Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
4114 # $ssl - value corresponding to openssl's SSL structure
4115 # $func - perl reference to callback function
4116 # $data - [optional] data that will be passed to callback function when invoked
4117 #
4118 # returns: no return value
4119 · set_shutdown
4121 Sets the shutdown state of $ssl to $mode.
4123 Net::SSLeay::set_shutdown($ssl, $mode);
4125 # $ssl - value corresponding to openssl's SSL structure
4126 # $mode - (integer) shutdown mode:
4127 # 0 - No shutdown
4128 # 1 - SSL_SENT_SHUTDOWN
4129 # 2 - SSL_RECEIVED_SHUTDOWN
4130 # 3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
4131 #
4132 # returns: no return value
4133 Check openssl doc
4135 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4136 · set_ssl_method
4138 Sets a new TLS/SSL method for a particular $ssl object.
4140 my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
4142 # $ssl - value corresponding to openssl's SSL structure
4143 # $method - value corresponding to openssl's SSL_METHOD structure
4144 #
4145 # returns: 1 on success, 0 on failure
4146 Check openssl doc
4148 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4149 · set_tmp_dh
4151 Sets DH parameters to be used to be $dh.
4153 my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
4155 # $ssl - value corresponding to openssl's SSL structure
4156 # $dh - value corresponding to openssl's DH structure
4157 #
4158 # returns: 1 on success, 0 on failure
4159 Check openssl doc
4161 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
4162 · set_tmp_dh_callback
4164 Sets the callback function for $ssl to be used when a DH parameters
4166 are required to $dh_cb.
4167 ??? (does this function really work?)
4169 Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
4171 # $ssl - value corresponding to openssl's SSL structure
4172 # $dh_cb - pointer to function ???
4173 #
4174 # returns: no return value
4175 Check openssl doc
4177 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
4178 · set_tmp_rsa
4180 Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
4182 my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
4184 # $ssl - value corresponding to openssl's SSL structure
4185 # $rsa - value corresponding to openssl's RSA structure
4186 #
4187 # returns: 1 on success, 0 on failure
4188 Example:
4190 $rsakey = Net::SSLeay::RSA_generate_key();
4192 Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
4193 Net::SSLeay::RSA_free($rsakey);
4194 Check openssl doc
4196 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
4197 · set_tmp_rsa_callback
4199 Sets the callback function for $ssl to be used when a
4201 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
4202 ??? (does this function really work?)
4204 Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
4206 # $ssl - value corresponding to openssl's SSL structure
4207 # $tmp_rsa_callback - (function pointer) ???
4208 #
4209 # returns: no return value
4210 Check openssl doc
4212 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
4213 · set_trust
4215 my $rv = Net::SSLeay::set_trust($ssl, $trust);
4217 # $ssl - value corresponding to openssl's SSL structure
4218 # $trust - (integer) trust identifier
4219 #
4220 # returns: the original value
4221 For more details about $trust values see "CTX_set_trust".
4223 · shutdown
4225 Shuts down an active TLS/SSL connection. It sends the 'close
4227 notify' shutdown alert to the peer.
4228 my $rv = Net::SSLeay::shutdown($ssl);
4230 # $ssl - value corresponding to openssl's SSL structure
4231 #
4232 # returns: 1 - shutdown was successfully completed
4233 # 0 - shutdown is not yet finished,
4234 # -1 - shutdown was not successful
4235 Check openssl doc
4237 <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
4238 · state_string
4240 Returns a 6 letter string indicating the current state of the SSL
4242 object $ssl.
4243 my $rv = Net::SSLeay::state_string($ssl);
4245 # $ssl - value corresponding to openssl's SSL structure
4246 #
4247 # returns: 6-letter string
4248 Check openssl doc
4250 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
4251 · state_string_long
4253 Returns a string indicating the current state of the SSL object
4255 $ssl.
4256 my $rv = Net::SSLeay::state_string_long($ssl);
4258 # $ssl - value corresponding to openssl's SSL structure
4259 #
4260 # returns: state strings
4261 Check openssl doc
4263 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
4264 · use_PrivateKey
4266 Adds $pkey as private key to $ssl.
4268 my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
4270 # $ssl - value corresponding to openssl's SSL structure
4271 # $pkey - value corresponding to openssl's EVP_PKEY structure
4272 #
4273 # returns: 1 on success, otherwise check out the error stack to find out the reason
4274 Check openssl doc
4276 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4277 · use_PrivateKey_ASN1
4279 Adds the private key of type $pk stored in $data to $ssl.
4281 my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
4283 # $pk - (integer) key type, NID of corresponding algorithm
4284 # $ssl - value corresponding to openssl's SSL structure
4285 # $data - key data (binary)
4286 # $len - length of $data
4287 #
4288 # returns: 1 on success, otherwise check out the error stack to find out the reason
4289 Check openssl doc
4291 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4292 · use_PrivateKey_file
4294 Adds the first private key found in $file to $ssl.
4296 my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
4298 # $ssl - value corresponding to openssl's SSL structure
4299 # $file - (string) file name
4300 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
4301 #
4302 # returns: 1 on success, otherwise check out the error stack to find out the reason
4303 Check openssl doc
4305 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4306 · use_RSAPrivateKey
4308 Adds $rsa as RSA private key to $ssl.
4310 my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
4312 # $ssl - value corresponding to openssl's SSL structure
4313 # $rsa - value corresponding to openssl's RSA structure
4314 #
4315 # returns: 1 on success, otherwise check out the error stack to find out the reason
4316 Check openssl doc
4318 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4319 · use_RSAPrivateKey_ASN1
4321 Adds RSA private key stored in $data to $ssl.
4323 my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
4325 # $ssl - value corresponding to openssl's SSL structure
4326 # $data - key data (binary)
4327 # $len - length of $data
4328 #
4329 # returns: 1 on success, otherwise check out the error stack to find out the reason
4330 Check openssl doc
4332 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4333 · use_RSAPrivateKey_file
4335 Adds the first RSA private key found in $file to $ssl.
4337 my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
4339 # $ssl - value corresponding to openssl's SSL structure
4340 # $file - (string) file name
4341 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
4342 #
4343 # returns: 1 on success, otherwise check out the error stack to find out the reason
4344 Check openssl doc
4346 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4347 · use_certificate
4349 Loads the certificate $x into $ssl.
4351 my $rv = Net::SSLeay::use_certificate($ssl, $x);
4353 # $ssl - value corresponding to openssl's SSL structure
4354 # $x - value corresponding to openssl's X509 structure
4355 #
4356 # returns: 1 on success, otherwise check out the error stack to find out the reason
4357 Check openssl doc
4359 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4360 · use_certificate_ASN1
4362 Loads the ASN1 encoded certificate from $data to $ssl.
4364 my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
4366 # $ssl - value corresponding to openssl's SSL structure
4367 # $data - certificate data (binary)
4368 # $len - length of $data
4369 #
4370 # returns: 1 on success, otherwise check out the error stack to find out the reason
4371 Check openssl doc
4373 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4374 · use_certificate_file
4376 Loads the first certificate stored in $file into $ssl.
4378 my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
4380 # $ssl - value corresponding to openssl's SSL structure
4381 # $file - (string) file name
4382 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
4383 #
4384 # returns: 1 on success, otherwise check out the error stack to find out the reason
4385 Check openssl doc
4387 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4388 · version
4390 Returns SSL/TLS protocol version
4392 my $rv = Net::SSLeay::version($ssl);
4394 # $ssl - value corresponding to openssl's SSL structure
4395 #
4396 # returns: (integer) protocol version
4397 # 0x0002 - SSL2_VERSION (SSLv2)
4398 # 0x0300 - SSL3_VERSION (SSLv3)
4399 # 0x0301 - TLS1_VERSION (TLSv1)
4400 # 0xFEFF - DTLS1_VERSION (DTLSv1)
4401 · want
4403 Returns state information for the SSL object $ssl.
4405 my $rv = Net::SSLeay::want($ssl);
4407 # $ssl - value corresponding to openssl's SSL structure
4408 #
4409 # returns: state
4410 # 1 - SSL_NOTHING
4411 # 2 - SSL_WRITING
4412 # 3 - SSL_READING
4413 # 4 - SSL_X509_LOOKUP
4414 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
4416 · write
4418 Writes data from the buffer $data into the specified $ssl
4420 connection.
4421 my $rv = Net::SSLeay::write($ssl, $data);
4423 # $ssl - value corresponding to openssl's SSL structure
4424 # $data - data to be written
4425 #
4426 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
4427 # 0 - write not successful, probably the underlying connection was closed
4428 # <0 - error
4429 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
4431 · write_partial
4433 NOTE: Does not exactly correspond to any low level API function
4435 Writes a fragment of data data from the buffer $data into the
4437 specified $ssl connection.
4438 my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
4440 # $ssl - value corresponding to openssl's SSL structure
4441 # $from - (integer) offset from the beginning of $data
4442 # $count - (integer) length of data to be written
4443 # $data - data buffer
4444 #
4445 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
4446 # 0 - write not successful, probably the underlying connection was closed
4447 # <0 - error
4448 · set_tlsext_host_name
4450 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
4452 requires at least openssl-0.9.8f
4453 Sets TLS servername extension on SLL object $ssl to value $name.
4455 my $rv = set_tlsext_host_name($ssl, $name);
4457 # $ssl - value corresponding to openssl's SSL structure
4458 # $name - (string) name to be set
4459 #
4460 # returns: 1 on success, 0 on failure
4461 Low level API: RAND_* related functions
4463 Check openssl doc related to RAND stuff
4465 <http://www.openssl.org/docs/crypto/rand.html>
4466 · RAND_add
4468 Mixes the $num bytes at $buf into the PRNG state.
4470 Net::SSLeay::RAND_add($buf, $num, $entropy);
4472 # $buf - buffer with data to be mixed into the PRNG state
4473 # $num - number of bytes in $buf
4474 # $entropy - estimate of how much randomness is contained in $buf (in bytes)
4475 #
4476 # returns: no return value
4477 Check openssl doc
4479 <http://www.openssl.org/docs/crypto/RAND_add.html>
4480 · RAND_seed
4482 Equivalent to "RAND_add" when $num == $entropy.
4484 Net::SSLeay::RAND_seed($buf); # Perlishly figures out buf size
4486 # $buf - buffer with data to be mixed into the PRNG state
4487 # $num - number of bytes in $buf
4488 #
4489 # returns: no return value
4490 Check openssl doc
4492 <http://www.openssl.org/docs/crypto/RAND_add.html>
4493 · RAND_status
4495 Gives PRNG status (seeded enough or not).
4497 my $rv = Net::SSLeay::RAND_status();
4499 #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
4500 Check openssl doc
4502 <http://www.openssl.org/docs/crypto/RAND_add.html>
4503 · RAND_bytes
4505 Puts $num cryptographically strong pseudo-random bytes into $buf.
4507 my $rv = Net::SSLeay::RAND_bytes($buf, $num);
4509 # $buf - buffer where the random data will be stored
4510 # $num - the size (in bytes) of requested random data
4511 #
4512 # returns: 1 on success, 0 otherwise
4513 Check openssl doc
4515 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
4516 · RAND_pseudo_bytes
4518 Puts $num pseudo-random (not necessarily unpredictable) bytes into
4520 $buf.
4521 my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
4523 # $buf - buffer where the random data will be stored
4524 # $num - the size (in bytes) of requested random data
4525 #
4526 # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
4527 Check openssl doc
4529 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
4530 · RAND_cleanup
4532 Erase the PRNG state.
4534 Net::SSLeay::RAND_cleanup();
4536 # no args, no return value
4537 Check openssl doc
4539 <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
4540 · RAND_egd
4542 Queries the entropy gathering daemon EGD on socket $path for 255
4544 bytes.
4545 my $rv = Net::SSLeay::RAND_egd($path);
4547 # $path - path to a socket of entropy gathering daemon EGD
4548 #
4549 # returns: the number of bytes read from the daemon on success, and -1 on failure
4550 Check openssl doc
4552 <http://www.openssl.org/docs/crypto/RAND_egd.html>
4553 · RAND_egd_bytes
4555 Queries the entropy gathering daemon EGD on socket $path for $bytes
4557 bytes.
4558 my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
4560 # $path - path to a socket of entropy gathering daemon EGD
4561 # $bytes - number of bytes we want from EGD
4562 #
4563 # returns: the number of bytes read from the daemon on success, and -1 on failure
4564 Check openssl doc
4566 <http://www.openssl.org/docs/crypto/RAND_egd.html>
4567 · RAND_file_name
4569 Generates a default path for the random seed file.
4571 my $file = Net::SSLeay::RAND_file_name($num);
4573 # $num - maximum size of returned file name
4574 #
4575 # returns: string with file name on success, '' (empty string) on failure
4576 Check openssl doc
4578 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
4579 · RAND_load_file
4581 Reads $max_bytes of bytes from $file_name and adds them to the
4583 PRNG.
4584 my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
4586 # $file_name - the name of file
4587 # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
4588 #
4589 # returns: the number of bytes read
4590 Check openssl doc
4592 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
4593 · RAND_write_file
4595 Writes 1024 random bytes to $file_name which can be used to
4597 initialize the PRNG by calling "RAND_load_file" in a later session.
4598 my $rv = Net::SSLeay::RAND_write_file($file_name);
4600 # $file_name - the name of file
4601 #
4602 # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
4603 Check openssl doc
4605 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
4606 · RAND_poll
4608 Collects some entropy from operating system and adds it to the
4610 PRNG.
4611 my $rv = Net::SSLeay::RAND_poll();
4613 # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
4614 Low level API: OBJ_* related functions
4616 · OBJ_cmp
4618 Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
4620 my $rv = Net::SSLeay::OBJ_cmp($a, $b);
4622 # $a - value corresponding to openssl's ASN1_OBJECT structure
4623 # $b - value corresponding to openssl's ASN1_OBJECT structure
4624 #
4625 # returns: if the two are identical 0 is returned
4626 Check openssl doc
4628 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4629 · OBJ_dup
4631 Returns a copy/duplicate of $o.
4633 my $rv = Net::SSLeay::OBJ_dup($o);
4635 # $o - value corresponding to openssl's ASN1_OBJECT structure
4636 #
4637 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
4638 Check openssl doc
4640 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4641 · OBJ_nid2ln
4643 Returns long name for given NID $n.
4645 my $rv = Net::SSLeay::OBJ_nid2ln($n);
4647 # $n - (integer) NID
4648 #
4649 # returns: (string) long name e.g. 'commonName'
4650 Check openssl doc
4652 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4653 · OBJ_ln2nid
4655 Returns NID corresponding to given long name $n.
4657 my $rv = Net::SSLeay::OBJ_ln2nid($s);
4659 # $s - (string) long name e.g. 'commonName'
4660 #
4661 # returns: (integer) NID
4662 · OBJ_nid2sn
4664 Returns short name for given NID $n.
4666 my $rv = Net::SSLeay::OBJ_nid2sn($n);
4668 # $n - (integer) NID
4669 #
4670 # returns: (string) short name e.g. 'CN'
4671 Example:
4673 print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
4675 · OBJ_sn2nid
4677 Returns NID corresponding to given short name $s.
4679 my $rv = Net::SSLeay::OBJ_sn2nid($s);
4681 # $s - (string) short name e.g. 'CN'
4682 #
4683 # returns: (integer) NID
4684 Example:
4686 print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
4688 print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
4689 · OBJ_nid2obj
4691 Returns ASN1_OBJECT for given NID $n.
4693 my $rv = Net::SSLeay::OBJ_nid2obj($n);
4695 # $n - (integer) NID
4696 #
4697 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
4698 Check openssl doc
4700 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4701 · OBJ_obj2nid
4703 Returns NID corresponding to given ASN1_OBJECT $o.
4705 my $rv = Net::SSLeay::OBJ_obj2nid($o);
4707 # $o - value corresponding to openssl's ASN1_OBJECT structure
4708 #
4709 # returns: (integer) NID
4710 Check openssl doc
4712 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4713 · OBJ_txt2obj
4715 Converts the text string s into an ASN1_OBJECT structure. If
4717 $no_name is 0 then long names (e.g. 'commonName') and short names
4718 (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
4719 '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
4720 my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
4722 # $s - text string to be converted
4723 # $no_name - (integer) 0 or 1
4724 #
4725 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
4726 Check openssl doc
4728 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4729 · OBJ_obj2txt
4731 Converts the ASN1_OBJECT a into a textual representation.
4733 Net::SSLeay::OBJ_obj2txt($a, $no_name);
4735 # $a - value corresponding to openssl's ASN1_OBJECT structure
4736 # $no_name - (integer) 0 or 1
4737 #
4738 # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
4739 Check openssl doc
4741 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4742 · OBJ_txt2nid
4744 Returns NID corresponding to text string $s which can be a long
4746 name, a short name or the numerical respresentation of an object.
4747 my $rv = Net::SSLeay::OBJ_txt2nid($s);
4749 # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
4750 #
4751 # returns: (integer) NID
4752 Example:
4754 my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
4756 Net::SSLeay::OBJ_nid2sn($n);
4757 Check openssl doc
4759 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
4760 Low level API: ASN1_INTEGER_* related functions
4762 · ASN1_INTEGER_new
4764 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4766 Creates a new ASN1_INTEGER structure.
4768 my $rv = Net::SSLeay::ASN1_INTEGER_new();
4770 #
4771 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
4772 · ASN1_INTEGER_free
4774 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4776 Free an allocated ASN1_INTEGER structure.
4778 Net::SSLeay::ASN1_INTEGER_free($i);
4780 # $i - value corresponding to openssl's ASN1_INTEGER structure
4781 #
4782 # returns: no return value
4783 · ASN1_INTEGER_get
4785 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4787 Returns integer value of given ASN1_INTEGER object.
4789 BEWARE: If the value stored in ASN1_INTEGER is greater than max.
4791 integer that can be stored in 'long' type (usually 32bit but may
4792 vary according to platform) then this function will return -1. For
4793 getting large ASN1_INTEGER values consider using
4794 "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
4795 my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
4797 # $a - value corresponding to openssl's ASN1_INTEGER structure
4798 #
4799 # returns: integer value of ASN1_INTEGER object in $a
4800 · ASN1_INTEGER_set
4802 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4804 Sets value of given ASN1_INTEGER object to value $val
4806 BEWARE: $val has max. limit (= max. integer that can be stored in
4808 'long' type). For setting large ASN1_INTEGER values consider using
4809 "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
4810 my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
4812 # $i - value corresponding to openssl's ASN1_INTEGER structure
4813 # $val - integer value
4814 #
4815 # returns: 1 on success, 0 on failure
4816 · P_ASN1_INTEGER_get_dec
4818 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4820 Returns string with decimal representation of integer value of
4822 given ASN1_INTEGER object.
4823 Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
4825 # $i - value corresponding to openssl's ASN1_INTEGER structure
4826 #
4827 # returns: string with decimal representation
4828 · P_ASN1_INTEGER_get_hex
4830 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4832 Returns string with hexadecimal representation of integer value of
4834 given ASN1_INTEGER object.
4835 Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
4837 # $i - value corresponding to openssl's ASN1_INTEGER structure
4838 #
4839 # returns: string with hexadecimal representation
4840 · P_ASN1_INTEGER_set_dec
4842 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4844 Sets value of given ASN1_INTEGER object to value $val (decimal
4846 string, suitable for large integers)
4847 Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
4849 # $i - value corresponding to openssl's ASN1_INTEGER structure
4850 # $str - string with decimal representation
4851 #
4852 # returns: 1 on success, 0 on failure
4853 · P_ASN1_INTEGER_set_hex
4855 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4857 Sets value of given ASN1_INTEGER object to value $val (hexadecimal
4859 string, suitable for large integers)
4860 Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
4862 # $i - value corresponding to openssl's ASN1_INTEGER structure
4863 # $str - string with hexadecimal representation
4864 #
4865 # returns: 1 on success, 0 on failure
4866 Low level API: ASN1_STRING_* related functions
4868 · P_ASN1_STRING_get
4870 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4872 Returns string value of given ASN1_STRING object.
4874 Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
4876 # $s - value corresponding to openssl's ASN1_STRING structure
4877 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
4878 #
4879 # returns: string
4880 $string = Net::SSLeay::P_ASN1_STRING_get($s);
4882 #is the same as:
4883 $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
4884 Low level API: ASN1_TIME_* related functions
4886 · ASN1_TIME_new
4888 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
4890 my $time = ASN1_TIME_new();
4892 # returns: value corresponding to openssl's ASN1_TIME structure
4893 · ASN1_TIME_free
4895 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
4897 ASN1_TIME_free($time);
4899 # $time - value corresponding to openssl's ASN1_TIME structure
4900 · ASN1_TIME_set
4902 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
4904 ASN1_TIME_set($time, $t);
4906 # $time - value corresponding to openssl's ASN1_TIME structure
4907 # $t - time value in seconds since 1.1.1970
4908 BEWARE: It is platform dependent how this function will handle
4910 dates after 2038. Although perl's integer is large enough the
4911 internal implementation of this function is dependent on the size
4912 of time_t structure (32bit time_t has problem with 2038).
4913 If you want to safely set date and time after 2038 use function
4915 "P_ASN1_TIME_set_isotime".
4916 · P_ASN1_TIME_get_isotime
4918 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
4920 requires at least openssl-0.9.7e
4921 NOTE: Does not exactly correspond to any low level API function
4923 Gives ISO-8601 string representation of ASN1_TIME structure.
4925 my $datetime_string = P_ASN1_TIME_get_isotime($time);
4927 # $time - value corresponding to openssl's ASN1_TIME structure
4928 #
4929 # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
4930 The output format is compatible with module
4932 DateTime::Format::RFC3339
4933 · P_ASN1_TIME_set_isotime
4935 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
4937 requires at least openssl-0.9.7e
4938 NOTE: Does not exactly correspond to any low level API function
4940 Sets time and date value of ANS1_time structure.
4942 my $rv = P_ASN1_TIME_set_isotime($time, $string);
4944 # $time - value corresponding to openssl's ASN1_TIME structure
4945 # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
4946 #
4947 # returns: 1 on success, 0 on failure
4948 The $string parameter has to be in full form like
4950 "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
4951 "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
4952 "2012-03-22" are not supported.
4953 · P_ASN1_TIME_put2string
4955 COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
4957 bugs with openssl-0.9.8i
4958 NOTE: Does not exactly correspond to any low level API function
4960 Gives string representation of ASN1_TIME structure.
4962 my $str = P_ASN1_TIME_put2string($time);
4964 # $time - value corresponding to openssl's ASN1_TIME structure
4965 #
4966 # returns: datetime string like 'May 16 20:39:37 2033 GMT'
4967 · P_ASN1_UTCTIME_put2string
4969 NOTE: deprecated function, only for backward compatibility, just an
4971 alias for "P_ASN1_TIME_put2string"
4972 Low level API: X509_* related functions
4974 · X509_new
4976 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
4978 Allocates and initializes a X509 structure.
4980 my $rv = Net::SSLeay::X509_new();
4982 #
4983 # returns: value corresponding to openssl's X509 structure (0 on failure)
4984 Check openssl doc
4986 <http://www.openssl.org/docs/crypto/X509_new.html>
4987 · X509_free
4989 Frees up the X509 structure.
4991 Net::SSLeay::X509_free($a);
4993 # $a - value corresponding to openssl's X509 structure
4994 #
4995 # returns: no return value
4996 Check openssl doc
4998 <http://www.openssl.org/docs/crypto/X509_new.html>
4999 · X509_certificate_type
5001 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5003 Returns bitmask with type of certificate $x.
5005 my $rv = Net::SSLeay::X509_certificate_type($x);
5007 # $x - value corresponding to openssl's X509 structure
5008 #
5009 # returns: (integer) bitmask with certificate type
5010 #to decode bitmask returned by this function use these constants:
5012 &Net::SSLeay::EVP_PKS_DSA
5013 &Net::SSLeay::EVP_PKS_EC
5014 &Net::SSLeay::EVP_PKS_RSA
5015 &Net::SSLeay::EVP_PKT_ENC
5016 &Net::SSLeay::EVP_PKT_EXCH
5017 &Net::SSLeay::EVP_PKT_EXP
5018 &Net::SSLeay::EVP_PKT_SIGN
5019 &Net::SSLeay::EVP_PK_DH
5020 &Net::SSLeay::EVP_PK_DSA
5021 &Net::SSLeay::EVP_PK_EC
5022 &Net::SSLeay::EVP_PK_RSA
5023 · X509_digest
5025 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5027 Computes digest/fingerprint of X509 $data using $type hash
5029 function.
5030 my $digest_value = Net::SSLeay::X509_digest($data, $type);
5032 # $data - value corresponding to openssl's X509 structure
5033 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5034 #
5035 # returns: hash value (binary)
5036 #to get printable (hex) value of digest use:
5038 print unpack('H*', $digest_value);
5039 · X509_issuer_and_serial_hash
5041 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5043 Sort of a checksum of issuer name and serial number of X509
5045 certificate $x. The result is not a full hash (e.g. sha-1), it is
5046 kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
5047 The resulting value might differ across different openssl versions
5048 for the same X509 certificate.
5049 my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
5051 # $x - value corresponding to openssl's X509 structure
5052 #
5053 # returns: number representing checksum
5054 · X509_issuer_name_hash
5056 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5058 Sort of a checksum of issuer name of X509 certificate $x. The
5060 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
5061 truncated to the size of 'unsigned long' (32 bits). The resulting
5062 value might differ across different openssl versions for the same
5063 X509 certificate.
5064 my $rv = Net::SSLeay::X509_issuer_name_hash($x);
5066 # $x - value corresponding to openssl's X509 structure
5067 #
5068 # returns: number representing checksum
5069 · X509_subject_name_hash
5071 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5073 Sort of a checksum of subject name of X509 certificate $x. The
5075 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
5076 truncated to the size of 'unsigned long' (32 bits). The resulting
5077 value might differ across different openssl versions for the same
5078 X509 certificate.
5079 my $rv = Net::SSLeay::X509_subject_name_hash($x);
5081 # $x - value corresponding to openssl's X509 structure
5082 #
5083 # returns: number representing checksum
5084 · X509_pubkey_digest
5086 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5088 requires at least openssl-0.9.7
5089 Computes digest/fingerprint of public key from X509 certificate
5091 $data using $type hash function.
5092 my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
5094 # $data - value corresponding to openssl's X509 structure
5095 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5096 #
5097 # returns: hash value (binary)
5098 #to get printable (hex) value of digest use:
5100 print unpack('H*', $digest_value);
5101 · X509_set_issuer_name
5103 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5105 Sets issuer of X509 certificate $x to $name.
5107 my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
5109 # $x - value corresponding to openssl's X509 structure
5110 # $name - value corresponding to openssl's X509_NAME structure
5111 #
5112 # returns: 1 on success, 0 on failure
5113 · X509_set_pubkey
5115 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5117 Sets public key of X509 certificate $x to $pkey.
5119 my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
5121 # $x - value corresponding to openssl's X509 structure
5122 # $pkey - value corresponding to openssl's EVP_PKEY structure
5123 #
5124 # returns: 1 on success, 0 on failure
5125 · X509_set_serialNumber
5127 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5129 Sets serial number of X509 certificate $x to $serial.
5131 my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
5133 # $x - value corresponding to openssl's X509 structure
5134 # $serial - value corresponding to openssl's ASN1_INTEGER structure
5135 #
5136 # returns: 1 on success, 0 on failure
5137 #to create $serial value use one of these:
5139 $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
5140 $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
5141 $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
5142 · X509_set_subject_name
5144 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5146 Sets subject of X509 certificate $x to $name.
5148 my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
5150 # $x - value corresponding to openssl's X509 structure
5151 # $name - value corresponding to openssl's X509_NAME structure
5152 #
5153 # returns: 1 on success, 0 on failure
5154 · X509_set_version
5156 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5158 Set 'version' value for X509 certificate $ to $version.
5160 my $rv = Net::SSLeay::X509_set_version($x, $version);
5162 # $x - value corresponding to openssl's X509 structure
5163 # $version - (integer) version number
5164 #
5165 # returns: 1 on success, 0 on failure
5166 · X509_sign
5168 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5170 Sign X509 certificate $x with private key $pkey (using digest
5172 algorithm $md).
5173 my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
5175 # $x - value corresponding to openssl's X509 structure
5176 # $pkey - value corresponding to openssl's EVP_PKEY structure
5177 # $md - value corresponding to openssl's EVP_MD structure
5178 #
5179 # returns: 1 on success, 0 on failure
5180 · X509_verify
5182 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5184 Verifies X509 object $a using public key $r (pubkey of issuing CA).
5186 my $rv = Net::SSLeay::X509_verify($x, $r);
5188 # $x - value corresponding to openssl's X509 structure
5189 # $r - value corresponding to openssl's EVP_PKEY structure
5190 #
5191 # returns: 0 - verify failure, 1 - verify OK, <0 - error
5192 · X509_get_ext_count
5194 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5196 Returns the total number of extensions in X509 object $x.
5198 my $rv = Net::SSLeay::X509_get_ext_count($x);
5200 # $x - value corresponding to openssl's X509 structure
5201 #
5202 # returns: count of extensions
5203 · X509_get_pubkey
5205 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5207 Returns public key corresponding to given X509 object $x.
5209 my $rv = Net::SSLeay::X509_get_pubkey($x);
5211 # $x - value corresponding to openssl's X509 structure
5212 #
5213 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
5214 · X509_get_serialNumber
5216 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5218 Returns serial number of X509 certificate $x.
5220 my $rv = Net::SSLeay::X509_get_serialNumber($x);
5222 # $x - value corresponding to openssl's X509 structure
5223 #
5224 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
5225 See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
5227 "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
5228 · X509_get_version
5230 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5232 Returns 'version' value of given X509 certificate $x.
5234 my $rv = Net::SSLeay::X509_get_version($x);
5236 # $x - value corresponding to openssl's X509 structure
5237 #
5238 # returns: (integer) version
5239 · X509_get_ext
5241 Returns X509_EXTENSION from $x509 based on given position/index.
5243 my $rv = Net::SSLeay::X509_get_ext($x509, $index);
5245 # $x509 - value corresponding to openssl's X509 structure
5246 # $index - (integer) position/index of extension within $x509
5247 #
5248 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
5249 · X509_get_ext_by_NID
5251 Returns X509_EXTENSION from $x509 based on given NID.
5253 my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
5255 # $x509 - value corresponding to openssl's X509 structure
5256 # $nid - (integer) NID value
5257 # $loc - (integer) position to start lookup at
5258 #
5259 # returns: position/index of extension, negative value on error
5260 # call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
5261 · X509_get_fingerprint
5263 Returns fingerprint of certificate $cert.
5265 NOTE: Does not exactly correspond to any low level API function.
5267 The implementation is basen on openssl's "X509_digest()".
5268 Net::SSLeay::X509_get_fingerprint($x509, $type);
5270 # $x509 - value corresponding to openssl's X509 structure
5271 # $type - (string) digest type, currently supported values:
5272 # "md5"
5273 # "sha1"
5274 # "sha256"
5275 # "ripemd160"
5276 #
5277 # returns: certificate digest - hexadecimal string (NOT binary data!)
5278 · X509_get_issuer_name
5280 Return an X509_NAME object representing the issuer of the
5282 certificate $cert.
5283 my $rv = Net::SSLeay::X509_get_issuer_name($cert);
5285 # $cert - value corresponding to openssl's X509 structure
5286 #
5287 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
5288 · X509_get_notAfter
5290 Return an object giving the time after which the certificate $cert
5292 is not valid.
5293 my $rv = Net::SSLeay::X509_get_notAfter($cert);
5295 # $cert - value corresponding to openssl's X509 structure
5296 #
5297 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
5298 To get human readable/printable form the return value you can use:
5300 my $time = Net::SSLeay::X509_get_notAfter($cert);
5302 print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
5303 · X509_get_notBefore
5305 Return an object giving the time before which the certificate $cert
5307 is not valid
5308 my $rv = Net::SSLeay::X509_get_notBefore($cert);
5310 # $cert - value corresponding to openssl's X509 structure
5311 #
5312 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
5313 To get human readable/printable form the return value you can use:
5315 my $time = Net::SSLeay::X509_get_notBefore($cert);
5317 print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
5318 · X509_get_subjectAltNames
5320 NOTE: Does not exactly correspond to any low level API function.
5322 Returns the list of alternative subject names from X509 certificate
5324 $cert.
5325 my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
5327 # $cert - value corresponding to openssl's X509 structure
5328 #
5329 # returns: list containing pairs - name_type (integer), name_value (string)
5330 # where name_type can be:
5331 # 0 - GEN_OTHERNAME
5332 # 1 - GEN_EMAIL
5333 # 2 - GEN_DNS
5334 # 3 - GEN_X400
5335 # 4 - GEN_DIRNAME
5336 # 5 - GEN_EDIPARTY
5337 # 6 - GEN_URI
5338 # 7 - GEN_IPADD
5339 # 8 - GEN_RID
5340 · X509_get_subject_name
5342 Returns the subject of the certificate $cert.
5344 my $rv = Net::SSLeay::X509_get_subject_name($cert);
5346 # $cert - value corresponding to openssl's X509 structure
5347 #
5348 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
5349 · X509_gmtime_adj
5351 Adjust th ASN1_TIME object to the timestamp (in GMT).
5353 my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
5355 # $s - value corresponding to openssl's ASN1_TIME structure
5356 # $adj - timestamp (seconds since 1.1.1970)
5357 #
5358 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
5359 BEWARE: this function may fail for dates after 2038 as it is
5361 dependent on time_t size on your system (32bit time_t does not work
5362 after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
5363 · X509_load_cert_crl_file
5365 Takes PEM file and loads all X509 certificates and X509 CRLs from
5367 that file into X509_LOOKUP structure.
5368 my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
5370 # $ctx - value corresponding to openssl's X509_LOOKUP structure
5371 # $file - (string) file name
5372 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5373 # if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
5374 #
5375 # returns: 1 on success, 0 on failure
5376 · X509_load_cert_file
5378 Loads/adds X509 certificate from $file to X509_LOOKUP structure
5380 my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
5382 # $ctx - value corresponding to openssl's X509_LOOKUP structure
5383 # $file - (string) file name
5384 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5385 #
5386 # returns: 1 on success, 0 on failure
5387 · X509_load_crl_file
5389 Loads/adds X509 CRL from $file to X509_LOOKUP structure
5391 my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
5393 # $ctx - value corresponding to openssl's X509_LOOKUP structure
5394 # $file - (string) file name
5395 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5396 #
5397 # returns: 1 on success, 0 on failure
5398 · X509_policy_level_get0_node
5400 ??? (more info needed)
5402 my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
5404 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
5405 # $i - (integer) index/position
5406 #
5407 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
5408 · X509_policy_level_node_count
5410 ??? (more info needed)
5412 my $rv = Net::SSLeay::X509_policy_level_node_count($level);
5414 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
5415 #
5416 # returns: (integer) node count
5417 · X509_policy_node_get0_parent
5419 ??? (more info needed)
5421 my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
5423 # $node - value corresponding to openssl's X509_POLICY_NODE structure
5424 #
5425 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
5426 · X509_policy_node_get0_policy
5428 ??? (more info needed)
5430 my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
5432 # $node - value corresponding to openssl's X509_POLICY_NODE structure
5433 #
5434 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5435 · X509_policy_node_get0_qualifiers
5437 ??? (more info needed)
5439 my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
5441 # $node - value corresponding to openssl's X509_POLICY_NODE structure
5442 #
5443 # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
5444 · X509_policy_tree_free
5446 ??? (more info needed)
5448 Net::SSLeay::X509_policy_tree_free($tree);
5450 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
5451 #
5452 # returns: no return value
5453 · X509_policy_tree_get0_level
5455 ??? (more info needed)
5457 my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
5459 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
5460 # $i - (integer) level index
5461 #
5462 # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
5463 · X509_policy_tree_get0_policies
5465 ??? (more info needed)
5467 my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
5469 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
5470 #
5471 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
5472 · X509_policy_tree_get0_user_policies
5474 ??? (more info needed)
5476 my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
5478 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
5479 #
5480 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
5481 · X509_policy_tree_level_count
5483 ??? (more info needed)
5485 my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
5487 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
5488 #
5489 # returns: (integer) count
5490 · X509_verify_cert_error_string
5492 Returns a human readable error string for verification error $n.
5494 my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
5496 # $n - (long) numeric error code
5497 #
5498 # returns: error string
5499 Check openssl doc
5501 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
5502 · P_X509_add_extensions
5504 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5506 Adds one or more X509 extensions to X509 object $x.
5508 my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
5510 # $x - value corresponding to openssl's X509 structure
5511 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
5512 # $nid - NID identifying extension to be set
5513 # $value - extension value
5514 #
5515 # returns: 1 on success, 0 on failure
5516 You can set more extensions at once:
5518 my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
5520 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
5521 &Net::SSLeay::NID_subject_key_identifier => 'hash',
5522 &Net::SSLeay::NID_authority_key_identifier => 'keyid',
5523 &Net::SSLeay::NID_authority_key_identifier => 'issuer',
5524 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
5525 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
5526 &Net::SSLeay::NID_netscape_cert_type => 'server',
5527 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
5528 );
5529 · P_X509_copy_extensions
5531 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5533 Copies X509 extensions from X509_REQ object to X509 object - handy
5535 when you need to turn X509_REQ into X509 certificate.
5536 Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
5538 # $x509_req - value corresponding to openssl's X509_REQ structure
5539 # $x509 - value corresponding to openssl's X509 structure
5540 # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
5541 #
5542 # returns: 1 on success, 0 on failure
5543 · P_X509_get_crl_distribution_points
5545 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5547 requires at least openssl-0.9.7
5548 Get the list of CRL distribution points from X509 certificate.
5550 my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
5552 # $x509 - value corresponding to openssl's X509 structure
5553 #
5554 # returns: list of distribution points (usually URLs)
5555 · P_X509_get_ext_key_usage
5557 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5559 requires at least openssl-0.9.7
5560 Gets the list of extended key usage of given X509 certificate
5562 $cert.
5563 my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
5565 # $cert - value corresponding to openssl's X509 structure
5566 # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
5567 #
5568 # returns: list of values
5569 Examples:
5571 my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
5573 # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
5574 my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
5576 # returns for example: (129, 130)
5577 my @extkeyusage_sn = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
5579 # returns for example: ("serverAuth", "clientAuth")
5580 my @extkeyusage_ln = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
5582 # returns for example: ("TLS Web Server Authentication", "TLS Web Client Authentication")
5583 · P_X509_get_key_usage
5585 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5587 Gets the list of key usage of given X509 certificate $cert.
5589 my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
5591 # $cert - value corresponding to openssl's X509 structure
5592 #
5593 # returns: list of key usage values which can be none, one or more from the following list:
5594 # "digitalSignature"
5595 # "nonRepudiation"
5596 # "keyEncipherment"
5597 # "dataEncipherment"
5598 # "keyAgreement"
5599 # "keyCertSign"
5600 # "cRLSign"
5601 # "encipherOnly"
5602 # "decipherOnly"
5603 · P_X509_get_netscape_cert_type
5605 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5607 Gets the list of Netscape cert types of given X509 certificate
5609 $cert.
5610 Net::SSLeay::P_X509_get_netscape_cert_type($cert);
5612 # $cert - value corresponding to openssl's X509 structure
5613 #
5614 # returns: list of Netscape type values which can be none, one or more from the following list:
5615 # "client"
5616 # "server"
5617 # "email"
5618 # "objsign"
5619 # "reserved"
5620 # "sslCA"
5621 # "emailCA"
5622 # "objCA"
5623 · P_X509_get_pubkey_alg
5625 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5627 Returns ASN1_OBJECT corresponding to X509 certificate public key
5629 algorithm.
5630 my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
5632 # $x - value corresponding to openssl's X509 structure
5633 #
5634 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5635 To get textual representation use:
5637 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
5639 # returns for example: "rsaEncryption"
5640 · P_X509_get_signature_alg
5642 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5644 Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
5646 my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
5648 # $x - value corresponding to openssl's X509 structure
5649 #
5650 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5651 To get textual representation use:
5653 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
5655 # returns for example: "sha1WithRSAEncryption"
5656 Low level API: X509_REQ_* related functions
5658 · X509_REQ_new
5660 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5662 Creates a new X509_REQ structure.
5664 my $rv = Net::SSLeay::X509_REQ_new();
5666 #
5667 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
5668 · X509_REQ_free
5670 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5672 Free an allocated X509_REQ structure.
5674 Net::SSLeay::X509_REQ_free($x);
5676 # $x - value corresponding to openssl's X509_REQ structure
5677 #
5678 # returns: no return value
5679 · X509_REQ_add1_attr_by_NID
5681 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5683 Adds an attribute whose name is defined by a NID $nid. The field
5685 value to be added is in $bytes.
5686 my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
5688 # $req - value corresponding to openssl's X509_REQ structure
5689 # $nid - (integer) NID value
5690 # $type - (integer) type of data in $bytes (see below)
5691 # $bytes - data to be set
5692 #
5693 # returns: 1 on success, 0 on failure
5694 # values for $type - use constants:
5696 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
5697 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
5698 · X509_REQ_digest
5700 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5702 Computes digest/fingerprint of X509_REQ $data using $type hash
5704 function.
5705 my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
5707 # $data - value corresponding to openssl's X509_REQ structure
5708 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5709 #
5710 # returns: hash value (binary)
5711 #to get printable (hex) value of digest use:
5713 print unpack('H*', $digest_value);
5714 · X509_REQ_get_attr_by_NID
5716 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5718 Retrieve the next index matching $nid after $lastpos ($lastpos
5720 should initially be set to -1).
5721 my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
5723 # $req - value corresponding to openssl's X509_REQ structure
5724 # $nid - (integer) NID value
5725 # $lastpos - [optional] (integer) index where to start search (default -1)
5726 #
5727 # returns: index (-1 if there are no more entries)
5728 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
5730 e.g.
5731 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
5733 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
5734 · X509_REQ_get_attr_by_OBJ
5736 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5738 Retrieve the next index matching $obj after $lastpos ($lastpos
5740 should initially be set to -1).
5741 my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
5743 # $req - value corresponding to openssl's X509_REQ structure
5744 # $obj - value corresponding to openssl's ASN1_OBJECT structure
5745 # $lastpos - [optional] (integer) index where to start search (default -1)
5746 #
5747 # returns: index (-1 if there are no more entries)
5748 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
5750 e.g.
5751 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
5753 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
5754 · X509_REQ_get_attr_count
5756 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5758 Returns the total number of attributes in $req.
5760 my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
5762 # $req - value corresponding to openssl's X509_REQ structure
5763 #
5764 # returns: (integer) items count
5765 · X509_REQ_get_pubkey
5767 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5769 Returns public key corresponding to given X509_REQ object $x.
5771 my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
5773 # $x - value corresponding to openssl's X509_REQ structure
5774 #
5775 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
5776 · X509_REQ_get_subject_name
5778 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5780 Returns X509_NAME object corresponding to subject name of given
5782 X509_REQ object $x.
5783 my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
5785 # $x - value corresponding to openssl's X509_REQ structure
5786 #
5787 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
5788 · X509_REQ_get_version
5790 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5792 Returns 'version' value for given X509_REQ object $x.
5794 my $rv = Net::SSLeay::X509_REQ_get_version($x);
5796 # $x - value corresponding to openssl's X509_REQ structure
5797 #
5798 # returns: (integer) version e.g. 0 = "version 1"
5799 · X509_REQ_set_pubkey
5801 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5803 Sets public key of given X509_REQ object $x to $pkey.
5805 my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
5807 # $x - value corresponding to openssl's X509_REQ structure
5808 # $pkey - value corresponding to openssl's EVP_PKEY structure
5809 #
5810 # returns: 1 on success, 0 on failure
5811 · X509_REQ_set_subject_name
5813 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5815 Sets subject name of given X509_REQ object $x to X509_NAME object
5817 $name.
5818 my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
5820 # $x - value corresponding to openssl's X509_REQ structure
5821 # $name - value corresponding to openssl's X509_NAME structure
5822 #
5823 # returns: 1 on success, 0 on failure
5824 · X509_REQ_set_version
5826 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5828 Sets 'version' of given X509_REQ object $x to $version.
5830 my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
5832 # $x - value corresponding to openssl's X509_REQ structure
5833 # $version - (integer) e.g. 0 = "version 1"
5834 #
5835 # returns: 1 on success, 0 on failure
5836 · X509_REQ_sign
5838 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5840 Sign X509_REQ object $x with private key $pk (using digest
5842 algorithm $md).
5843 my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
5845 # $x - value corresponding to openssl's X509_REQ structure
5846 # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
5847 # $md - value corresponding to openssl's EVP_MD structure
5848 #
5849 # returns: 1 on success, 0 on failure
5850 · X509_REQ_verify
5852 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5854 Verifies X509_REQ object $x using public key $r (pubkey of
5856 requesting party).
5857 my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
5859 # $x - value corresponding to openssl's X509_REQ structure
5860 # $r - value corresponding to openssl's EVP_PKEY structure
5861 #
5862 # returns: 0 - verify failure, 1 - verify OK, <0 - error
5863 · P_X509_REQ_add_extensions
5865 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5867 Adds one or more X509 extensions to X509_REQ object $x.
5869 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
5871 # $x - value corresponding to openssl's X509_REQ structure
5872 # $nid - NID identifying extension to be set
5873 # $value - extension value
5874 #
5875 # returns: 1 on success, 0 on failure
5876 You can set more extensions at once:
5878 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
5880 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
5881 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
5882 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
5883 &Net::SSLeay::NID_netscape_cert_type => 'server',
5884 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
5885 &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
5886 );
5887 · P_X509_REQ_get_attr
5889 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5891 requires at least openssl-0.9.7
5892 Returns attribute value for X509_REQ's attribute at index $n.
5894 Net::SSLeay::P_X509_REQ_get_attr($req, $n);
5896 # $req - value corresponding to openssl's X509_REQ structure
5897 # $n - (integer) attribute index
5898 #
5899 # returns: value corresponding to openssl's ASN1_STRING structure
5900 Low level API: X509_CRL_* related functions
5902 · X509_CRL_new
5904 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5906 Creates a new X509_CRL structure.
5908 my $rv = Net::SSLeay::X509_CRL_new();
5910 #
5911 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
5912 · X509_CRL_free
5914 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5916 Free an allocated X509_CRL structure.
5918 Net::SSLeay::X509_CRL_free($x);
5920 # $x - value corresponding to openssl's X509_CRL structure
5921 #
5922 # returns: no return value
5923 · X509_CRL_digest
5925 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5927 Computes digest/fingerprint of X509_CRL $data using $type hash
5929 function.
5930 my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
5932 # $data - value corresponding to openssl's X509_CRL structure
5933 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5934 #
5935 # returns: hash value (binary)
5936 Example:
5938 my $x509_crl
5940 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
5941 my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
5942 #to get printable (hex) value of digest use:
5943 print "digest=", unpack('H*', $digest_value), "\n";
5944 · X509_CRL_get_ext
5946 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
5948 Returns X509_EXTENSION from $x509 based on given position/index.
5950 my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
5952 # $x509 - value corresponding to openssl's X509_CRL structure
5953 # $index - (integer) position/index of extension within $x509
5954 #
5955 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
5956 · X509_CRL_get_ext_by_NID
5958 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
5960 Returns X509_EXTENSION from $x509 based on given NID.
5962 my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
5964 # $x509 - value corresponding to openssl's X509_CRL structure
5965 # $nid - (integer) NID value
5966 # $loc - (integer) position to start lookup at
5967 #
5968 # returns: position/index of extension, negative value on error
5969 # call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
5970 · X509_CRL_get_ext_count
5972 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
5974 Returns the total number of extensions in X509_CRL object $x.
5976 my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
5978 # $x - value corresponding to openssl's X509_CRL structure
5979 #
5980 # returns: count of extensions
5981 · X509_CRL_get_issuer
5983 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5985 Returns X509_NAME object corresponding to the issuer of X509_CRL
5987 $x.
5988 my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
5990 # $x - value corresponding to openssl's X509_CRL structure
5991 #
5992 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
5993 See other "X509_NAME_*" functions to get more info from X509_NAME
5995 structure.
5996 · X509_CRL_get_lastUpdate
5998 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6000 Returns 'lastUpdate' date-time value of X509_CRL object $x.
6002 my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
6004 # $x - value corresponding to openssl's X509_CRL structure
6005 #
6006 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6007 · X509_CRL_get_nextUpdate
6009 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6011 Returns 'nextUpdate' date-time value of X509_CRL object $x.
6013 my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
6015 # $x - value corresponding to openssl's X509_CRL structure
6016 #
6017 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6018 · X509_CRL_get_version
6020 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6022 Returns 'version' value of given X509_CRL structure $x.
6024 my $rv = Net::SSLeay::X509_CRL_get_version($x);
6026 # $x - value corresponding to openssl's X509_CRL structure
6027 #
6028 # returns: (integer) version
6029 · X509_CRL_set_issuer_name
6031 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6033 requires at least openssl-0.9.7
6034 Sets the issuer of X509_CRL object $x to X509_NAME object $name.
6036 my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
6038 # $x - value corresponding to openssl's X509_CRL structure
6039 # $name - value corresponding to openssl's X509_NAME structure
6040 #
6041 # returns: 1 on success, 0 on failure
6042 · X509_CRL_set_lastUpdate
6044 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6046 requires at least openssl-0.9.7
6047 Sets 'lastUpdate' value of X509_CRL object $x to $tm.
6049 my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
6051 # $x - value corresponding to openssl's X509_CRL structure
6052 # $tm - value corresponding to openssl's ASN1_TIME structure
6053 #
6054 # returns: 1 on success, 0 on failure
6055 · X509_CRL_set_nextUpdate
6057 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6059 requires at least openssl-0.9.7
6060 Sets 'nextUpdate' value of X509_CRL object $x to $tm.
6062 my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
6064 # $x - value corresponding to openssl's X509_CRL structure
6065 # $tm - value corresponding to openssl's ASN1_TIME structure
6066 #
6067 # returns: 1 on success, 0 on failure
6068 · X509_CRL_set_version
6070 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6072 requires at least openssl-0.9.7
6073 Sets 'version' value of given X509_CRL structure $x to $version.
6075 my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
6077 # $x - value corresponding to openssl's X509_CRL structure
6078 # $version - (integer) version number (1 = version 2 CRL)
6079 #
6080 # returns: 1 on success, 0 on failure
6081 Note that if you want to use any X509_CRL extension you need to set
6083 "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
6084 · X509_CRL_sign
6086 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6088 Sign X509_CRL object $x with private key $pkey (using digest
6090 algorithm $md).
6091 my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
6093 # $x - value corresponding to openssl's X509_CRL structure
6094 # $pkey - value corresponding to openssl's EVP_PKEY structure
6095 # $md - value corresponding to openssl's EVP_MD structure
6096 #
6097 # returns: 1 on success, 0 on failure
6098 · X509_CRL_sort
6100 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6102 requires at least openssl-0.9.7
6103 Sorts the data of X509_CRL object so it will be written in serial
6105 number order.
6106 my $rv = Net::SSLeay::X509_CRL_sort($x);
6108 # $x - value corresponding to openssl's X509_CRL structure
6109 #
6110 # returns: 1 on success, 0 on failure
6111 · X509_CRL_verify
6113 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6115 Verifies X509_CRL object $a using public key $r (pubkey of issuing
6117 CA).
6118 my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
6120 # $a - value corresponding to openssl's X509_CRL structure
6121 # $r - value corresponding to openssl's EVP_PKEY structure
6122 #
6123 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6124 · P_X509_CRL_add_revoked_serial_hex
6126 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6128 requires at least openssl-0.9.7
6129 Adds given serian number $serial_hex to X509_CRL object $crl.
6131 Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
6133 # $crl - value corresponding to openssl's X509_CRL structure
6134 # $serial_hex - string (hexadecimal) representation of serial number
6135 # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
6136 # $reason_code - [optional] (integer) reason code (see below) - default 0
6137 # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
6138 #
6139 # returns: no return value
6140 reason codes:
6142 0 - unspecified
6143 1 - keyCompromise
6144 2 - CACompromise
6145 3 - affiliationChanged
6146 4 - superseded
6147 5 - cessationOfOperation
6148 6 - certificateHold
6149 7 - removeFromCRL
6150 · P_X509_CRL_get_serial
6152 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6154 requires at least openssl-0.9.7
6155 Returns serial number of X509_CRL object.
6157 my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
6159 # $crl - value corresponding to openssl's X509_CRL structure
6160 #
6161 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6162 · P_X509_CRL_set_serial
6164 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6166 requires at least openssl-0.9.7
6167 Sets serial number of X509_CRL object to $crl_number.
6169 my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
6171 # $crl - value corresponding to openssl's X509_CRL structure
6172 # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
6173 #
6174 # returns: 1 on success, 0 on failure
6175 Low level API: X509_EXTENSION_* related functions
6177 · X509_EXTENSION_get_critical
6179 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6181 Returns 'critical' flag of given X509_EXTENSION object $ex.
6183 my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
6185 # $ex - value corresponding to openssl's X509_EXTENSION structure
6186 #
6187 # returns: (integer) 1 - critical, 0 - noncritical
6188 · X509_EXTENSION_get_data
6190 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6192 Returns value (raw data) of X509_EXTENSION object $ne.
6194 my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
6196 # $ne - value corresponding to openssl's X509_EXTENSION structure
6197 #
6198 # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
6199 Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
6201 into perl scalar variable.
6202 · X509_EXTENSION_get_object
6204 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6206 Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
6208 my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
6210 # $ex - value corresponding to openssl's X509_EXTENSION structure
6211 #
6212 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6213 · X509V3_EXT_print
6215 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6217 Returns string representation of given X509_EXTENSION object $ext.
6219 Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
6221 # $ext - value corresponding to openssl's X509_EXTENSION structure
6222 # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
6223 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
6224 #
6225 # returns: no return value
6226 · X509V3_EXT_d2i
6228 Parses an extension and returns its internal structure.
6230 my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
6232 # $ext - value corresponding to openssl's X509_EXTENSION structure
6233 #
6234 # returns: pointer ???
6235 Low level API: X509_NAME_* related functions
6237 · X509_NAME_ENTRY_get_data
6239 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6241 Retrieves the field value of $ne in and ASN1_STRING structure.
6243 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
6245 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
6246 #
6247 # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
6248 Check openssl doc
6250 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
6251 · X509_NAME_ENTRY_get_object
6253 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6255 Retrieves the field name of $ne in and ASN1_OBJECT structure.
6257 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
6259 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
6260 #
6261 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6262 Check openssl doc
6264 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
6265 · X509_NAME_new
6267 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6269 requires at least openssl-0.9.5
6270 Creates a new X509_NAME structure. Adds a field whose name is
6272 defined by a string $field. The field value to be added is in
6273 $bytes.
6274 my $rv = Net::SSLeay::X509_NAME_new();
6276 #
6277 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6278 · X509_NAME_hash
6280 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6282 requires at least openssl-0.9.5
6283 Sort of a checksum of issuer name $name. The result is not a full
6285 hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
6286 'unsigned long' (32 bits). The resulting value might differ across
6287 different openssl versions for the same X509 certificate.
6288 my $rv = Net::SSLeay::X509_NAME_hash($name);
6290 # $name - value corresponding to openssl's X509_NAME structure
6291 #
6292 # returns: number representing checksum
6293 · X509_NAME_add_entry_by_txt
6295 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6297 requires at least openssl-0.9.5
6298 Adds a field whose name is defined by a string $field. The field
6300 value to be added is in $bytes.
6301 my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
6303 # $name - value corresponding to openssl's X509_NAME structure
6304 # $field - (string) field definition (name) - e.g. "organizationName"
6305 # $type - (integer) type of data in $bytes (see below)
6306 # $bytes - data to be set
6307 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
6308 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
6309 #
6310 # returns: 1 on success, 0 on failure
6311 # values for $type - use constants:
6313 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
6314 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
6315 Unicode note: when passing non-ascii (unicode) string in $bytes do
6317 not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
6318 the perl $string via "$bytes = encode('utf-8', $string)".
6319 Check openssl doc
6321 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
6322 · X509_NAME_add_entry_by_NID
6324 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6326 requires at least openssl-0.9.5
6327 Adds a field whose name is defined by a NID $nid. The field value
6329 to be added is in $bytes.
6330 my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
6332 # $name - value corresponding to openssl's X509_NAME structure
6333 # $nid - (integer) field definition - NID value
6334 # $type - (integer) type of data in $bytes (see below)
6335 # $bytes - data to be set
6336 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
6337 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
6338 #
6339 # returns: 1 on success, 0 on failure
6340 Check openssl doc
6342 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
6343 · X509_NAME_add_entry_by_OBJ
6345 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6347 requires at least openssl-0.9.5
6348 Adds a field whose name is defined by a object (OID) $obj . The
6350 field value to be added is in $bytes.
6351 my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
6353 # $name - value corresponding to openssl's X509_NAME structure
6354 # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
6355 # $type - (integer) type of data in $bytes (see below)
6356 # $bytes - data to be set
6357 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
6358 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
6359 #
6360 # returns: 1 on success, 0 on failure
6361 Check openssl doc
6363 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
6364 · X509_NAME_cmp
6366 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6368 Compares two X509_NAME obejcts.
6370 my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
6372 # $a - value corresponding to openssl's X509_NAME structure
6373 # $b - value corresponding to openssl's X509_NAME structure
6374 #
6375 # returns: 0 if $a matches $b; non zero otherwise
6376 · X509_NAME_digest
6378 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6380 Computes digest/fingerprint of X509_NAME $data using $type hash
6382 function.
6383 my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
6385 # $data - value corresponding to openssl's X509_NAME structure
6386 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6387 #
6388 # returns: hash value (binary)
6389 #to get printable (hex) value of digest use:
6391 print unpack('H*', $digest_value);
6392 · X509_NAME_entry_count
6394 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6396 Returns the total number of entries in $name.
6398 my $rv = Net::SSLeay::X509_NAME_entry_count($name);
6400 # $name - value corresponding to openssl's X509_NAME structure
6401 #
6402 # returns: (integer) entries count
6403 Check openssl doc
6405 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
6406 · X509_NAME_get_entry
6408 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6410 Retrieves the X509_NAME_ENTRY from $name corresponding to index
6412 $loc. Acceptable values for $loc run from 0 to
6413 "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
6414 is an internal pointer which must not be freed.
6415 my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
6417 # $name - value corresponding to openssl's X509_NAME structure
6418 # $loc - (integer) index of wanted entry
6419 #
6420 # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
6421 Check openssl doc
6423 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
6424 · X509_NAME_print_ex
6426 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6428 Returns a string with human readable version of $name.
6430 Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
6432 # $name - value corresponding to openssl's X509_NAME structure
6433 # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
6434 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
6435 #
6436 # returns: string representation of $name
6437 #available conversion flags - use constants:
6439 &Net::SSLeay::XN_FLAG_COMPAT
6440 &Net::SSLeay::XN_FLAG_DN_REV
6441 &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
6442 &Net::SSLeay::XN_FLAG_FN_ALIGN
6443 &Net::SSLeay::XN_FLAG_FN_LN
6444 &Net::SSLeay::XN_FLAG_FN_MASK
6445 &Net::SSLeay::XN_FLAG_FN_NONE
6446 &Net::SSLeay::XN_FLAG_FN_OID
6447 &Net::SSLeay::XN_FLAG_FN_SN
6448 &Net::SSLeay::XN_FLAG_MULTILINE
6449 &Net::SSLeay::XN_FLAG_ONELINE
6450 &Net::SSLeay::XN_FLAG_RFC2253
6451 &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
6452 &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
6453 &Net::SSLeay::XN_FLAG_SEP_MASK
6454 &Net::SSLeay::XN_FLAG_SEP_MULTILINE
6455 &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
6456 &Net::SSLeay::XN_FLAG_SPC_EQ
6457 Most likely you will be fine with default:
6459 Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
6461 Or you might want RFC2253-like output without utf8 chars escaping:
6463 use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
6465 my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
6466 my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
6467 Check openssl doc
6469 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
6470 · X509_NAME_get_text_by_NID
6472 Retrieves the text from the first entry in name which matches $nid,
6474 if no such entry exists -1 is returned.
6475 openssl note: this is a legacy function which has various
6477 limitations which makes it of minimal use in practice. It can only
6478 find the first matching entry and will copy the contents of the
6479 field verbatim: this can be highly confusing if the target is a
6480 muticharacter string type like a BMPString or a UTF8String.
6481 Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
6483 # $name - value corresponding to openssl's X509_NAME structure
6484 # $nid - NID value (integer)
6485 #
6486 # returns: text value
6487 Check openssl doc
6489 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
6490 · X509_NAME_oneline
6492 Return an ASCII version of $name.
6494 Net::SSLeay::X509_NAME_oneline($name);
6496 # $name - value corresponding to openssl's X509_NAME structure
6497 #
6498 # returns: (string) ASCII version of $name
6499 Check openssl doc
6501 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
6502 · sk_X509_NAME_free
6504 Free an allocated STACK_OF(X509_NAME) structure.
6506 Net::SSLeay::sk_X509_NAME_free($sk);
6508 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
6509 #
6510 # returns: no return value
6511 · sk_X509_NAME_num
6513 Return number of items in STACK_OF(X509_NAME)
6515 my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
6517 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
6518 #
6519 # returns: number of items
6520 · sk_X509_NAME_value
6522 Returns X509_NAME from position $index in STACK_OF(X509_NAME)
6524 my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
6526 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
6527 # $i - (integer) index/position
6528 #
6529 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6530 · add_file_cert_subjects_to_stack
6532 Add a file of certs to a stack. All certs in $file that are not
6534 already in the $stackCAs will be added.
6535 my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
6537 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
6538 # $file - (string) filename
6539 #
6540 # returns: 1 on success, 0 on failure
6541 · add_dir_cert_subjects_to_stack
6543 Add a directory of certs to a stack. All certs in $dir that are not
6545 already in the $stackCAs will be added.
6546 my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
6548 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
6549 # $dir - (string) the directory to append from. All files in this directory will be examined as potential certs. Any that are acceptable to SSL_add_dir_cert_subjects_to_stack() that are not already in the stack will be included.
6550 #
6551 # returns: 1 on success, 0 on failure
6552 Low level API: X509_STORE_* related functions
6554 · X509_STORE_CTX_get_current_cert
6556 Returns the certificate in ctx which caused the error or 0 if no
6558 certificate is relevant.
6559 my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
6561 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6562 #
6563 # returns: value corresponding to openssl's X509 structure (0 on failure)
6564 Check openssl doc
6566 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6567 · X509_STORE_CTX_get_error
6569 Returns the error code of $ctx.
6571 my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
6573 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6574 #
6575 # returns: (integer) error code
6576 For more info about erro code values check function
6578 "get_verify_result".
6579 Check openssl doc
6581 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6582 · X509_STORE_CTX_get_error_depth
6584 Returns the depth of the error. This is a non-negative integer
6586 representing where in the certificate chain the error occurred. If
6587 it is zero it occurred in the end entity certificate, one if it is
6588 the certificate which signed the end entity certificate and so on.
6589 my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
6591 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6592 #
6593 # returns: (integer) depth
6594 Check openssl doc
6596 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6597 · X509_STORE_CTX_get_ex_data
6599 Is used to retrieve the information for $idx from $x509_store_ctx.
6601 my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
6603 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6604 # $idx - (integer) index for application specific data
6605 #
6606 # returns: pointer to ???
6607 · X509_STORE_CTX_set_ex_data
6609 Is used to store application data at arg for idx into
6611 $x509_store_ctx.
6612 my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
6614 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6615 # $idx - (integer) ???
6616 # $data - (pointer) ???
6617 #
6618 # returns: 1 on success, 0 on failure
6619 · X509_STORE_CTX_set_cert
6621 Sets the certificate to be vertified in $x509_store_ctx to $x.
6623 Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
6625 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6626 # $x - value corresponding to openssl's X509 structure
6627 #
6628 # returns: no return value
6629 Check openssl doc
6631 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
6632 · X509_STORE_CTX_set_error
6634 Sets the error code of $ctx to $s. For example it might be used in
6636 a verification callback to set an error based on additional checks.
6637 Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
6639 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
6640 # $s - (integer) error id
6641 #
6642 # returns: no return value
6643 Check openssl doc
6645 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6646 · X509_STORE_add_cert
6648 Adds X509 certificate $x into the X509_STORE $store.
6650 my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
6652 # $store - value corresponding to openssl's X509_STORE structure
6653 # $x - value corresponding to openssl's X509 structure
6654 #
6655 # returns: 1 on success, 0 on failure
6656 · X509_STORE_add_crl
6658 Adds X509 CRL $x into the X509_STORE $store.
6660 my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
6662 # $store - value corresponding to openssl's X509_STORE structure
6663 # $x - value corresponding to openssl's X509_CRL structure
6664 #
6665 # returns: 1 on success, 0 on failure
6666 · X509_STORE_set1_param
6668 ??? (more info needed)
6670 my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
6672 # $store - value corresponding to openssl's X509_STORE structure
6673 # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
6674 #
6675 # returns: 1 on success, 0 on failure
6676 · X509_STORE_set_flags
6678 Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
6680 # $ctx - value corresponding to openssl's X509_STORE structure
6681 # $flags - (unsigned long) flags to be set (bitmask)
6682 #
6683 # returns: no return value
6684 #to create $flags value use:
6686 0x0001 - X509_V_FLAG_CB_ISSUER_CHECK - Send issuer+subject checks to verify_cb
6687 0x0002 - X509_V_FLAG_USE_CHECK_TIME - Use check time instead of current time
6688 0x0004 - X509_V_FLAG_CRL_CHECK - Lookup CRLs
6689 0x0008 - X509_V_FLAG_CRL_CHECK_ALL - Lookup CRLs for whole chain
6690 0x0010 - X509_V_FLAG_IGNORE_CRITICAL - Ignore unhandled critical extensions
6691 0x0020 - X509_V_FLAG_X509_STRICT - Disable workarounds for broken certificates
6692 0x0040 - X509_V_FLAG_ALLOW_PROXY_CERTS - Enable proxy certificate validation
6693 0x0080 - X509_V_FLAG_POLICY_CHECK - Enable policy checking
6694 0x0100 - X509_V_FLAG_EXPLICIT_POLICY - Policy variable require-explicit-policy
6695 0x0200 - X509_V_FLAG_INHIBIT_ANY - Policy variable inhibit-any-policy
6696 0x0400 - X509_V_FLAG_INHIBIT_MAP - Policy variable inhibit-policy-mapping
6697 0x0800 - X509_V_FLAG_NOTIFY_POLICY - Notify callback that policy is OK
6698 0x1000 - X509_V_FLAG_EXTENDED_CRL_SUPPORT - Extended CRL features such as indirect CRLs, alternate CRL signing keys
6699 0x2000 - X509_V_FLAG_USE_DELTAS - Delta CRL support
6700 0x4000 - X509_V_FLAG_CHECK_SS_SIGNATURE - Check selfsigned CA signature
6701 #or use corresponding constants like
6703 $flags = &Net::SSLeay::X509_V_FLAG_CB_ISSUER_CHECK;
6704 ...
6705 $flags = &Net::SSLeay::X509_V_FLAG_CHECK_SS_SIGNATURE;
6706 · X509_STORE_set_purpose
6708 Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
6710 # $ctx - value corresponding to openssl's X509_STORE structure
6711 # $purpose - (integer) purpose identifier
6712 #
6713 # returns: no return value
6714 For more details about $purpose identifier check "CTX_set_purpose".
6716 · X509_STORE_set_trust
6718 Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
6720 # $ctx - value corresponding to openssl's X509_STORE structure
6721 # $trust - (integer) trust identifier
6722 #
6723 # returns: no return value
6724 For more details about $trust identifier check "CTX_set_trust".
6726 Low level API: X509_VERIFY_PARAM_* related functions
6728 · X509_VERIFY_PARAM_add0_policy
6730 Enables policy checking (it is disabled by default) and adds
6732 $policy to the acceptable policy set.
6733 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
6735 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6736 # $policy - value corresponding to openssl's ASN1_OBJECT structure
6737 #
6738 # returns: 1 on success, 0 on failure
6739 Check openssl doc
6741 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6742 · X509_VERIFY_PARAM_add0_table
6744 ??? (more info needed)
6746 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
6748 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6749 #
6750 # returns: 1 on success, 0 on failure
6751 · X509_VERIFY_PARAM_clear_flags
6753 Clears the flags $flags in param.
6755 my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
6757 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6758 # $flags - (unsigned long) flags to be set (bitmask)
6759 #
6760 # returns: 1 on success, 0 on failure
6761 For more details about $flags bitmask see "X509_STORE_set_flags".
6763 Check openssl doc
6765 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6766 · X509_VERIFY_PARAM_free
6768 Frees up the X509_VERIFY_PARAM structure.
6770 Net::SSLeay::X509_VERIFY_PARAM_free($param);
6772 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6773 #
6774 # returns: no return value
6775 · X509_VERIFY_PARAM_get_depth
6777 Returns the current verification depth.
6779 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
6781 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6782 #
6783 # returns: (ineger) depth
6784 Check openssl doc
6786 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6787 · X509_VERIFY_PARAM_get_flags
6789 Returns the current verification flags.
6791 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
6793 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6794 #
6795 # returns: (unsigned long) flags to be set (bitmask)
6796 For more details about returned flags bitmask see
6798 "X509_STORE_set_flags".
6799 Check openssl doc
6801 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6802 · X509_VERIFY_PARAM_set_flags
6804 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
6806 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6807 # $flags - (unsigned long) flags to be set (bitmask)
6808 #
6809 # returns: 1 on success, 0 on failure
6810 For more details about $flags bitmask see "X509_STORE_set_flags".
6812 Check openssl doc
6814 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6815 · X509_VERIFY_PARAM_inherit
6817 ??? (more info needed)
6819 my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
6821 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
6822 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
6823 #
6824 # returns: 1 on success, 0 on failure
6825 · X509_VERIFY_PARAM_lookup
6827 Finds X509_VERIFY_PARAM by name.
6829 my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
6831 # $name - (string) name we want to find
6832 #
6833 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
6834 · X509_VERIFY_PARAM_new
6836 Creates a new X509_VERIFY_PARAM structure.
6838 my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
6840 #
6841 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
6842 · X509_VERIFY_PARAM_set1
6844 Sets the name of X509_VERIFY_PARAM structure $to to the same value
6846 as the name of X509_VERIFY_PARAM structure $from.
6847 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
6849 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
6850 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
6851 #
6852 # returns: 1 on success, 0 on failure
6853 · X509_VERIFY_PARAM_set1_name
6855 Sets the name of X509_VERIFY_PARAM structure $param to $name.
6857 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
6859 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6860 # $name - (string) name to be set
6861 #
6862 # returns: 1 on success, 0 on failure
6863 · X509_VERIFY_PARAM_set1_policies
6865 Enables policy checking (it is disabled by default) and sets the
6867 acceptable policy set to policies. Any existing policy set is
6868 cleared. The policies parameter can be 0 to clear an existing
6869 policy set.
6870 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
6872 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6873 # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
6874 #
6875 # returns: 1 on success, 0 on failure
6876 Check openssl doc
6878 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6879 · X509_VERIFY_PARAM_set_depth
6881 Sets the maximum verification depth to depth. That is the maximum
6883 number of untrusted CA certificates that can appear in a chain.
6884 Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
6886 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6887 # $depth - (integer) depth to be set
6888 #
6889 # returns: no return value
6890 Check openssl doc
6892 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6893 · X509_VERIFY_PARAM_set_purpose
6895 Sets the verification purpose in $param to $purpose. This
6897 determines the acceptable purpose of the certificate chain, for
6898 example SSL client or SSL server.
6899 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
6901 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6902 # $purpose - (integer) purpose identifier
6903 #
6904 # returns: 1 on success, 0 on failure
6905 For more details about $purpose identifier check "CTX_set_purpose".
6907 Check openssl doc
6909 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6910 · X509_VERIFY_PARAM_set_time
6912 Sets the verification time in $param to $t. Normally the current
6914 time is used.
6915 Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
6917 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6918 # $t - (time_t) time in seconds since 1.1.1970
6919 #
6920 # returns: no return value
6921 Check openssl doc
6923 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6924 · X509_VERIFY_PARAM_set_trust
6926 Sets the trust setting in $param to $trust.
6928 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
6930 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
6931 # $trust - (integer) trust identifier
6932 #
6933 # returns: 1 on success, 0 on failure
6934 For more details about $trust identifier check "CTX_set_trust".
6936 Check openssl doc
6938 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
6939 · X509_VERIFY_PARAM_table_cleanup
6941 ??? (more info needed)
6943 Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
6945 #
6946 # returns: no return value
6947 Low level API: Cipher (EVP_CIPHER_*) related functions
6949 · EVP_get_cipherbyname
6951 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6953 Returns an EVP_CIPHER structure when passed a cipher name.
6955 my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
6957 # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
6958 #
6959 # returns: value corresponding to openssl's EVP_CIPHER structure
6960 Check openssl doc
6962 <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
6963 Low level API: Digest (EVP_MD_*) related functions
6965 · OpenSSL_add_all_digests
6967 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6969 Net::SSLeay::OpenSSL_add_all_digests();
6971 # no args, no return value
6972 http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
6974 · P_EVP_MD_list_all
6976 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6978 requires at least openssl-1.0.0
6979 NOTE: Does not exactly correspond to any low level API function
6981 my $rv = Net::SSLeay::P_EVP_MD_list_all();
6983 #
6984 # returns: arrayref - list of available digest names
6985 The returned digest names correspond to values expected by
6987 "EVP_get_digestbyname".
6988 Note that some of the digets are available by default and some only
6990 after calling "OpenSSL_add_all_digests".
6991 · EVP_get_digestbyname
6993 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6995 my $rv = Net::SSLeay::EVP_get_digestbyname($name);
6997 # $name - string with digest name
6998 #
6999 # returns: value corresponding to openssl's EVP_MD structure
7000 The $name param can be:
7002 md2
7004 md4
7005 md5
7006 mdc2
7007 ripemd160
7008 sha
7009 sha1
7010 sha224
7011 sha256
7012 sha512
7013 whirlpool
7014 Or better check the supported digests by calling
7016 "P_EVP_MD_list_all".
7017 · EVP_MD_type
7019 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7021 my $rv = Net::SSLeay::EVP_MD_type($md);
7023 # $md - value corresponding to openssl's EVP_MD structure
7024 #
7025 # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
7026 · EVP_MD_size
7028 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7030 my $rv = Net::SSLeay::EVP_MD_size($md);
7032 # $md - value corresponding to openssl's EVP_MD structure
7033 #
7034 # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
7035 · EVP_MD_CTX_md
7037 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7039 requires at least openssl-0.9.7
7040 Net::SSLeay::EVP_MD_CTX_md($ctx);
7042 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7043 #
7044 # returns: value corresponding to openssl's EVP_MD structure
7045 · EVP_MD_CTX_create
7047 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7049 requires at least openssl-0.9.7
7050 Allocates, initializes and returns a digest context.
7052 my $rv = Net::SSLeay::EVP_MD_CTX_create();
7054 #
7055 # returns: value corresponding to openssl's EVP_MD_CTX structure
7056 The complete idea behind EVP_MD_CTX looks like this example:
7058 Net::SSLeay::OpenSSL_add_all_digests();
7060 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7062 my $ctx = Net::SSLeay::EVP_MD_CTX_create();
7063 Net::SSLeay::EVP_DigestInit($ctx, $md);
7064 while(my $chunk = get_piece_of_data()) {
7066 Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
7067 }
7068 my $result = Net::SSLeay::EVP_DigestFinal($ctx);
7070 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
7071 print "digest=", unpack('H*', $result), "\n"; #print hex value
7073 · EVP_DigestInit_ex
7075 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7077 requires at least openssl-0.9.7
7078 Sets up digest context $ctx to use a digest $type from ENGINE
7080 $impl, $ctx must be initialized before calling this function, type
7081 will typically be supplied by a function such as
7082 "EVP_get_digestbyname". If $impl is 0 then the default
7083 implementation of digest $type is used.
7084 my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
7086 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7087 # $type - value corresponding to openssl's EVP_MD structure
7088 # $impl - value corresponding to openssl's ENGINE structure
7089 #
7090 # returns: 1 for success and 0 for failure
7091 · EVP_DigestInit
7093 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7095 requires at least openssl-0.9.7
7096 Behaves in the same way as "EVP_DigestInit_ex" except the passed
7098 context $ctx does not have to be initialized, and it always uses
7099 the default digest implementation.
7100 my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
7102 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7103 # $type - value corresponding to openssl's EVP_MD structure
7104 #
7105 # returns: 1 for success and 0 for failure
7106 · EVP_MD_CTX_destroy
7108 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7110 requires at least openssl-0.9.7
7111 Cleans up digest context $ctx and frees up the space allocated to
7113 it, it should be called only on a context created using
7114 "EVP_MD_CTX_create".
7115 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
7117 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7118 #
7119 # returns: no return value
7120 · EVP_DigestUpdate
7122 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7124 requires at least openssl-0.9.7
7125 my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
7127 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7128 # $data - data to be hashed
7129 #
7130 # returns: 1 for success and 0 for failure
7131 · EVP_DigestFinal_ex
7133 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7135 requires at least openssl-0.9.7
7136 Retrieves the digest value from $ctx. After calling
7138 "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
7139 be made, but "EVP_DigestInit_ex" can be called to initialize a new
7140 digest operation.
7141 my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
7143 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7144 #
7145 # returns: hash value (binary)
7146 #to get printable (hex) value of digest use:
7148 print unpack('H*', $digest_value);
7149 · EVP_DigestFinal
7151 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7153 requires at least openssl-0.9.7
7154 Similar to "EVP_DigestFinal_ex" except the digest context ctx is
7156 automatically cleaned up.
7157 my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
7159 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7160 #
7161 # returns: hash value (binary)
7162 #to get printable (hex) value of digest use:
7164 print unpack('H*', $digest_value);
7165 · MD2
7167 COMPATIBILITY: no supported by default in openssl-1.0.0
7169 Computes MD2 from given $data (all data needs to be loaded into
7171 memory)
7172 my $digest = Net::SSLeay::MD2($data);
7174 print "digest(hexadecimal)=", unpack('H*', $digest);
7175 · MD4
7177 Computes MD4 from given $data (all data needs to be loaded into
7179 memory)
7180 my $digest = Net::SSLeay::MD4($data);
7182 print "digest(hexadecimal)=", unpack('H*', $digest);
7183 · MD5
7185 Computes MD5 from given $data (all data needs to be loaded into
7187 memory)
7188 my $digest = Net::SSLeay::MD5($data);
7190 print "digest(hexadecimal)=", unpack('H*', $digest);
7191 · RIPEMD160
7193 Computes RIPEMD160 from given $data (all data needs to be loaded
7195 into memory)
7196 my $digest = Net::SSLeay::RIPEMD160($data);
7198 print "digest(hexadecimal)=", unpack('H*', $digest);
7199 · SHA1
7201 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7203 Computes SHA1 from given $data (all data needs to be loaded into
7205 memory)
7206 my $digest = Net::SSLeay::SHA1($data);
7208 print "digest(hexadecimal)=", unpack('H*', $digest);
7209 · SHA256
7211 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7213 requires at least openssl-0.9.8
7214 Computes SHA256 from given $data (all data needs to be loaded into
7216 memory)
7217 my $digest = Net::SSLeay::SHA256($data);
7219 print "digest(hexadecimal)=", unpack('H*', $digest);
7220 · SHA512
7222 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7224 requires at least openssl-0.9.8
7225 Computes SHA512 from given $data (all data needs to be loaded into
7227 memory)
7228 my $digest = Net::SSLeay::SHA512($data);
7230 print "digest(hexadecimal)=", unpack('H*', $digest);
7231 · EVP_Digest
7233 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7235 requires at least openssl-0.9.7
7236 Computes "any" digest from given $data (all data needs to be loaded
7238 into memory)
7239 my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
7241 my $digest = Net::SSLeay::EVP_Digest($data, $md);
7242 print "digest(hexadecimal)=", unpack('H*', $digest);
7243 · EVP_sha1
7245 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7247 my $md = Net::SSLeay::EVP_sha1();
7249 #
7250 # returns: value corresponding to openssl's EVP_MD structure
7251 · EVP_sha256
7253 COMPATIBILITY: requires at least openssl-0.9.8
7255 my $md = Net::SSLeay::EVP_sha256();
7257 #
7258 # returns: value corresponding to openssl's EVP_MD structure
7259 · EVP_sha512
7261 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7263 requires at least openssl-0.9.8
7264 my $md = Net::SSLeay::EVP_sha512();
7266 #
7267 # returns: value corresponding to openssl's EVP_MD structure
7268 · EVP_add_digest
7270 my $rv = Net::SSLeay::EVP_add_digest($digest);
7272 # $digest - value corresponding to openssl's EVP_MD structure
7273 #
7274 # returns: 1 on success, 0 otherwise
7275 Low level API: CIPHER_* related functions
7277 · CIPHER_get_name
7279 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7281 Returns name of the cipher used.
7283 my $rv = Net::SSLeay::CIPHER_description($cipher);
7285 # $cipher - value corresponding to openssl's SSL_CIPHER structure
7286 #
7287 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA'
7288 Check openssl doc
7290 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
7291 Example:
7293 my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
7295 my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
7296 · CIPHER_description
7298 Returns a textual description of the cipher used.
7300 ??? (does this function really work?)
7302 my $rv = Net::SSLeay::CIPHER_description($cipher, $buf, $size);
7304 # $cipher - value corresponding to openssl's SSL_CIPHER structure
7305 # $bufer - (string/buffer) ???
7306 # $size - (integer) ???
7307 #
7308 # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
7309 Check openssl doc
7311 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
7312 · CIPHER_get_bits
7314 Returns the number of secret bits used for cipher.
7316 my $rv = Net::SSLeay::CIPHER_get_bits($c);
7318 # $c - value corresponding to openssl's SSL_CIPHER structure
7319 #
7320 # returns: (integert) number of secret bits, 0 on error
7321 Check openssl doc
7323 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
7324 Low level API: RSA_* related functions
7326 · RSA_generate_key
7328 Generates a key pair and returns it in a newly allocated RSA
7330 structure. The pseudo-random number generator must be seeded prior
7331 to calling RSA_generate_key.
7332 my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
7334 # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
7335 # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
7336 # $perl_cb - [optional] reference to perl callback function
7337 # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
7338 #
7339 # returns: value corresponding to openssl's RSA structure (0 on failure)
7340 Check openssl doc
7342 <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
7343 · RSA_free
7345 Frees the RSA structure and its components. The key is erased
7347 before the memory is returned to the system.
7348 Net::SSLeay::RSA_free($r);
7350 # $r - value corresponding to openssl's RSA structure
7351 #
7352 # returns: no return value
7353 Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
7355 Low level API: BIO_* related functions
7357 · BIO_eof
7359 Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
7361 varies according to the BIO type.
7362 my $rv = Net::SSLeay::BIO_eof($s);
7364 # $s - value corresponding to openssl's BIO structure
7365 #
7366 # returns: 1 if EOF has been reached 0 otherwise
7367 Check openssl doc
7369 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
7370 · BIO_f_ssl
7372 Returns the SSL BIO method. This is a filter BIO which is a wrapper
7374 round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
7375 my $rv = Net::SSLeay::BIO_f_ssl();
7377 #
7378 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
7379 Check openssl doc
7381 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7382 · BIO_free
7384 Frees up a single BIO.
7386 my $rv = Net::SSLeay::BIO_free($bio;);
7388 # $bio; - value corresponding to openssl's BIO structure
7389 #
7390 # returns: 1 on success, 0 on failure
7391 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
7393 · BIO_new
7395 Returns a new BIO using method $type
7397 my $rv = Net::SSLeay::BIO_new($type);
7399 # $type - value corresponding to openssl's BIO_METHOD structure
7400 #
7401 # returns: value corresponding to openssl's BIO structure (0 on failure)
7402 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
7404 · BIO_new_buffer_ssl_connect
7406 Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
7408 (using ctx) and a connect BIO.
7409 my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
7411 # $ctx - value corresponding to openssl's SSL_CTX structure
7412 #
7413 # returns: value corresponding to openssl's BIO structure (0 on failure)
7414 Check openssl doc
7416 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7417 · BIO_new_file
7419 Creates a new file BIO with mode mode the meaning of mode is the
7421 same as the stdio function fopen(). The BIO_CLOSE flag is set on
7422 the returned BIO.
7423 my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
7425 # $filename - (string) filename
7426 # $mode - (string) opening mode (as mode by stdio function fopen)
7427 #
7428 # returns: value corresponding to openssl's BIO structure (0 on failure)
7429 Check openssl doc
7431 <http://www.openssl.org/docs/crypto/BIO_s_file.html>
7432 · BIO_new_ssl
7434 Allocates an SSL BIO using SSL_CTX ctx and using client mode if
7436 client is non zero.
7437 my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
7439 # $ctx - value corresponding to openssl's SSL_CTX structure
7440 # $client - (integer) 0 or 1 - indicates ssl client mode
7441 #
7442 # returns: value corresponding to openssl's BIO structure (0 on failure)
7443 Check openssl doc
7445 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7446 · BIO_new_ssl_connect
7448 Creates a new BIO chain consisting of an SSL BIO (using ctx)
7450 followed by a connect BIO.
7451 my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
7453 # $ctx - value corresponding to openssl's SSL_CTX structure
7454 #
7455 # returns: value corresponding to openssl's BIO structure (0 on failure)
7456 Check openssl doc
7458 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7459 · BIO_pending
7461 Return the number of pending characters in the BIOs read buffers.
7463 my $rv = Net::SSLeay::BIO_pending($s);
7465 # $s - value corresponding to openssl's BIO structure
7466 #
7467 # returns: the amount of pending data
7468 Check openssl doc
7470 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
7471 · BIO_wpending
7473 Return the number of pending characters in the BIOs write buffers.
7475 my $rv = Net::SSLeay::BIO_wpending($s);
7477 # $s - value corresponding to openssl's BIO structure
7478 #
7479 # returns: the amount of pending data
7480 Check openssl doc
7482 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
7483 · BIO_read
7485 Read the underlying descriptor.
7487 Net::SSLeay::BIO_read($s, $max);
7489 # $s - value corresponding to openssl's BIO structure
7490 # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
7491 #
7492 # returns: data
7493 Check openssl doc
7495 <http://www.openssl.org/docs/crypto/BIO_read.html>
7496 · BIO_write
7498 Attempts to write data from $buffer to BIO $b.
7500 my $rv = Net::SSLeay::BIO_write($b, $buffer);
7502 # $b - value corresponding to openssl's BIO structure
7503 # $buffer - data
7504 #
7505 # returns: amount of data successfully written
7506 # or that no data was successfully read or written if the result is 0 or -1
7507 # or -2 when the operation is not implemented in the specific BIO type
7508 Check openssl doc
7510 <http://www.openssl.org/docs/crypto/BIO_read.html>
7511 · BIO_s_mem
7513 Return the memory BIO method function.
7515 my $rv = Net::SSLeay::BIO_s_mem();
7517 #
7518 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
7519 Check openssl doc
7521 <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
7522 · BIO_ssl_copy_session_id
7524 Copies an SSL session id between BIO chains from and to. It does
7526 this by locating the SSL BIOs in each chain and calling
7527 SSL_copy_session_id() on the internal SSL pointer.
7528 my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
7530 # $to - value corresponding to openssl's BIO structure
7531 # $from - value corresponding to openssl's BIO structure
7532 #
7533 # returns: 1 on success, 0 on failure
7534 Check openssl doc
7536 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7537 · BIO_ssl_shutdown
7539 Closes down an SSL connection on BIO chain bio. It does this by
7541 locating the SSL BIO in the chain and calling SSL_shutdown() on its
7542 internal SSL pointer.
7543 Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
7545 # $ssl_bio - value corresponding to openssl's BIO structure
7546 #
7547 # returns: no return value
7548 Check openssl doc
7550 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
7551 Low level API: Server side Server Name Indication (SNI) support
7553 · set_tlsext_host_name
7555 TBA
7557 · get_servername
7559 TBA
7561 · get_servername_type
7563 TBA
7565 · CTX_set_tlsext_servername_callback
7567 COMPATIBILITY: requires at least OpenSSL 0.9.8f
7569 This function is used in a server to support Server side Server
7571 Name Indication (SNI).
7572 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
7574 # $ctx - SSL context
7575 # $code - reference to a subroutine that will be called when a new connection is being initiated
7576 #
7577 # returns: no return value
7578 On the client side:
7579 use set_tlsext_host_name($ssl, $servername) before initiating the SSL connection.
7580 On the server side: Set up an additional SSL_CTX() for each
7582 different certificate;
7583 Add a servername callback to each SSL_CTX() using
7585 CTX_set_tlsext_servername_callback();
7586 The callback function is required to retrieve the client-supplied
7588 servername with get_servername(ssl). Figure out the right SSL_CTX
7589 to go with that host name, then switch the SSL object to that
7590 SSL_CTX with set_SSL_CTX().
7591 Example:
7593 # set callback
7595 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
7596 sub {
7597 my $ssl = shift;
7598 my $h = Net::SSLeay::get_servername($ssl);
7599 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
7600 } );
7601 More complete example:
7603 # ... initialize Net::SSLeay
7605 my %hostnames = (
7607 'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
7608 'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
7609 );
7610 # create a new context for each certificate/key pair
7612 for my $name (keys %hostnames) {
7613 $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
7614 Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
7615 Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
7616 $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
7617 }
7618 # create default context
7620 my $ctx = Net::SSLeay::CTX_new or die;
7621 Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
7622 Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
7623 # set callback
7625 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
7626 my $ssl = shift;
7627 my $h = Net::SSLeay::get_servername($ssl);
7628 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
7629 } );
7630 # ... later
7632 $s = Net::SSLeay::new($ctx);
7634 Net::SSLeay::set_fd($s, fileno($accepted_socket));
7635 Net::SSLeay::accept($s);
7636 Low level API: NPN (next protocol negotiation) related functions
7638 Simple approach for using NPN support looks like this:
7640 ### client side
7642 use Net::SSLeay;
7643 use IO::Socket::INET;
7644 Net::SSLeay::initialize();
7646 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
7647 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
7648 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
7649 Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
7650 my $ssl = Net::SSLeay::new($ctx) or die;
7651 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
7652 Net::SSLeay::connect($ssl);
7653 warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
7655 warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
7656 ### server side
7658 use Net::SSLeay;
7659 use IO::Socket::INET;
7660 Net::SSLeay::initialize();
7662 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
7663 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
7664 Net::SSLeay::set_cert_and_key($ctx, "t/data/cert.pem", "t/data/key.pem");
7665 Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
7666 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
7667 while (1) {
7669 my $ssl = Net::SSLeay::new($ctx);
7670 warn("server:waiting for incoming connection...\n");
7671 my $fd = $sock->accept();
7672 Net::SSLeay::set_fd($ssl, $fd->fileno);
7673 Net::SSLeay::accept($ssl);
7674 warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
7675 my $got = Net::SSLeay::read($ssl);
7676 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
7677 Net::SSLeay::free($ssl);
7678 $fd->close();
7679 }
7680 # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
7681 Please note that the selection (negotiation) is performed by client
7683 side, the server side simply advertise the list of supported protocols.
7684 Advanced approach allows you to implement your own negotiation
7686 algorithm.
7687 #see below documentation for:
7689 Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
7690 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
7691 Detection of NPN support (works even in older Net::SSLeay versions):
7693 use Net::SSLeay;
7695 if (exists &Net::SSLeay::P_next_proto_negotiated) {
7697 # do NPN stuff
7698 }
7699 · CTX_set_next_proto_select_cb
7701 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7703 requires at least openssl-1.0.1
7704 NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
7706 connection.
7707 Simple usage - in this case a "common" negotiation algorithm (as
7709 implemented by openssl's function SSL_select_next_proto) is used.
7710 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
7712 # $ctx - value corresponding to openssl's SSL_CTX structure
7713 # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
7714 #
7715 # returns: 0 on success, 1 on failure
7716 Advanced usage (you probably do not need this):
7718 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
7720 # $ctx - value corresponding to openssl's SSL_CTX structure
7721 # $perl_callback_function - reference to perl function
7722 # $callback_data - [optional] data to passed to callback function when invoked
7723 #
7724 # returns: 0 on success, 1 on failure
7725 # where callback function looks like
7727 sub npn_advertised_cb_invoke {
7728 my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
7729 my $status;
7730 # ...
7731 $status = 1; #status can be:
7732 # 0 - OPENSSL_NPN_UNSUPPORTED
7733 # 1 - OPENSSL_NPN_NEGOTIATED
7734 # 2 - OPENSSL_NPN_NO_OVERLAP
7735 return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
7736 }
7737 To undefine/clear this callback use:
7739 Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
7741 · CTX_set_next_protos_advertised_cb
7743 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7745 requires at least openssl-1.0.1
7746 NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
7748 connection.
7749 Simple usage:
7751 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
7753 # $ctx - value corresponding to openssl's SSL_CTX structure
7754 # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
7755 #
7756 # returns: 0 on success, 1 on failure
7757 Advanced usage (you probably do not need this):
7759 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
7761 # $ctx - value corresponding to openssl's SSL_CTX structure
7762 # $perl_callback_function - reference to perl function
7763 # $callback_data - [optional] data to passed to callback function when invoked
7764 #
7765 # returns: 0 on success, 1 on failure
7766 # where callback function looks like
7768 sub npn_advertised_cb_invoke {
7769 my ($ssl, $callback_data) = @_;
7770 # ...
7771 return ['http1.1','spdy/2']; # the callback has to return arrayref
7772 }
7773 To undefine/clear this callback use:
7775 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
7777 · P_next_proto_negotiated
7779 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7781 requires at least openssl-1.0.1
7782 Returns the name of negotiated protocol for given SSL connection
7784 $ssl.
7785 $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
7787 # $ssl - value corresponding to openssl's SSL structure
7788 #
7789 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
7790 · P_next_proto_last_status
7792 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7794 requires at least openssl-1.0.1
7795 Returns the result of the last negotiation for given SSL connection
7797 $ssl.
7798 $rv = Net::SSLeay::P_next_proto_last_status($ssl)
7800 # $ssl - value corresponding to openssl's SSL structure
7801 #
7802 # returns: (integer) negotiation status
7803 # 0 - OPENSSL_NPN_UNSUPPORTED
7804 # 1 - OPENSSL_NPN_NEGOTIATED
7805 # 2 - OPENSSL_NPN_NO_OVERLAP
7806 Low level API: DANE Support
7808 OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
7810 Authentication of Named Entities (DANE) Transport Layer Association
7811 within OpenSSL
7812 · SSL_get_tlsa_record_byname
7814 COMPATIBILITY: Requires at least openssl-1.0.2
7816 In order to facilitate DANE there is additional interface,
7818 SSL_get_tlsa_record_byname, accepting hostname, port and socket
7819 type that returns packed TLSA record. In order to make it even
7820 easier there is additional SSL_ctrl function that calls
7821 SSL_get_tlsa_record_byname for you. Latter is recommended for
7822 programmers that wish to maintain broader binary compatibility,
7823 e.g. make application work with both 1.0.2 and prior version (in
7824 which case call to SSL_ctrl with new code returning error would
7825 have to be ignored when running with prior version).
7826 Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
7828 Low level API: Other functions
7830 · COMP_add_compression_method
7832 Adds the compression method cm with the identifier id to the list
7834 of available compression methods. This list is globally maintained
7835 for all SSL operations within this application. It cannot be set
7836 for specific SSL_CTX or SSL objects.
7837 my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
7839 # $id - (integer) compression method id
7840 # 0 to 63: methods defined by the IETF
7841 # 64 to 192: external party methods assigned by IANA
7842 # 193 to 255: reserved for private use
7843 #
7844 # $cm - value corresponding to openssl's COMP_METHOD structure
7845 #
7846 # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
7847 Check openssl doc
7849 <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
7850 · DH_free
7852 Frees the DH structure and its components. The values are erased
7854 before the memory is returned to the system.
7855 Net::SSLeay::DH_free($dh);
7857 # $dh - value corresponding to openssl's DH structure
7858 #
7859 # returns: no return value
7860 Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
7862 · FIPS_mode_set
7864 Enable or disable FIPS mode in a FIPS capable OpenSSL.
7866 Net::SSLeay:: FIPS_mode_set($enable);
7868 # $enable - (integer) 1 to enable, 0 to disable
7869 Low level API: EC related functions
7871 · CTX_set_tmp_ecdh
7873 TBA
7875 · EC_KEY_free
7877 TBA
7879 · EC_KEY_new_by_curve_name
7881 TBA
7883 Constants
7885 There are many openssl constants available in Net::SSLeay. You can use
7886 them like this:
7887 use Net::SSLeay;
7889 print &Net::SSLeay::NID_commonName;
7890 #or
7891 print Net::SSLeay::NID_commonName();
7892 Or you can import them and use:
7894 use Net::SSLeay qw/NID_commonName/;
7896 print &NID_commonName;
7897 #or
7898 print NID_commonName();
7899 #or
7900 print NID_commonName;
7901 The constants names are derived from openssl constants, however
7903 constants starting with "SSL_" prefix have name with "SSL_" part
7904 stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
7905 "Net::SSleay::OP_ALL"
7906 The list of all available constant names:
7908 ASN1_STRFLGS_ESC_CTRL NID_ext_req OP_CISCO_ANYCONNECT
7910 ASN1_STRFLGS_ESC_MSB NID_friendlyName OP_COOKIE_EXCHANGE
7911 ASN1_STRFLGS_ESC_QUOTE NID_givenName OP_CRYPTOPRO_TLSEXT_BUG
7912 ASN1_STRFLGS_RFC2253 NID_hmacWithSHA1 OP_DONT_INSERT_EMPTY_FRAGMENTS
7913 CB_ACCEPT_EXIT NID_id_ad OP_EPHEMERAL_RSA
7914 CB_ACCEPT_LOOP NID_id_ce OP_LEGACY_SERVER_CONNECT
7915 CB_CONNECT_EXIT NID_id_kp OP_MICROSOFT_BIG_SSLV3_BUFFER
7916 CB_CONNECT_LOOP NID_id_pbkdf2 OP_MICROSOFT_SESS_ID_BUG
7917 ERROR_NONE NID_id_pe OP_MSIE_SSLV2_RSA_PADDING
7918 ERROR_SSL NID_id_pkix OP_NETSCAPE_CA_DN_BUG
7919 ERROR_SYSCALL NID_id_qt_cps OP_NETSCAPE_CHALLENGE_BUG
7920 ERROR_WANT_ACCEPT NID_id_qt_unotice OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
7921 ERROR_WANT_CONNECT NID_idea_cbc OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
7922 ERROR_WANT_READ NID_idea_cfb64 OP_NON_EXPORT_FIRST
7923 ERROR_WANT_WRITE NID_idea_ecb OP_NO_COMPRESSION
7924 ERROR_WANT_X509_LOOKUP NID_idea_ofb64 OP_NO_QUERY_MTU
7925 ERROR_ZERO_RETURN NID_info_access OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
7926 EVP_PKS_DSA NID_initials OP_NO_SSLv2
7927 EVP_PKS_EC NID_invalidity_date OP_NO_SSLv3
7928 EVP_PKS_RSA NID_issuer_alt_name OP_NO_TICKET
7929 EVP_PKT_ENC NID_keyBag OP_NO_TLSv1
7930 EVP_PKT_EXCH NID_key_usage OP_NO_TLSv1_1
7931 EVP_PKT_EXP NID_localKeyID OP_NO_TLSv1_2
7932 EVP_PKT_SIGN NID_localityName OP_PKCS1_CHECK_1
7933 EVP_PK_DH NID_md2 OP_PKCS1_CHECK_2
7934 EVP_PK_DSA NID_md2WithRSAEncryption OP_SINGLE_DH_USE
7935 EVP_PK_EC NID_md5 OP_SINGLE_ECDH_USE
7936 EVP_PK_RSA NID_md5WithRSA OP_SSLEAY_080_CLIENT_DH_BUG
7937 FILETYPE_ASN1 NID_md5WithRSAEncryption OP_SSLREF2_REUSE_CERT_TYPE_BUG
7938 FILETYPE_PEM NID_md5_sha1 OP_TLS_BLOCK_PADDING_BUG
7939 F_CLIENT_CERTIFICATE NID_mdc2 OP_TLS_D5_BUG
7940 F_CLIENT_HELLO NID_mdc2WithRSA OP_TLS_ROLLBACK_BUG
7941 F_CLIENT_MASTER_KEY NID_ms_code_com READING
7942 F_D2I_SSL_SESSION NID_ms_code_ind RECEIVED_SHUTDOWN
7943 F_GET_CLIENT_FINISHED NID_ms_ctl_sign RSA_3
7944 F_GET_CLIENT_HELLO NID_ms_efs RSA_F4
7945 F_GET_CLIENT_MASTER_KEY NID_ms_ext_req R_BAD_AUTHENTICATION_TYPE
7946 F_GET_SERVER_FINISHED NID_ms_sgc R_BAD_CHECKSUM
7947 F_GET_SERVER_HELLO NID_name R_BAD_MAC_DECODE
7948 F_GET_SERVER_VERIFY NID_netscape R_BAD_RESPONSE_ARGUMENT
7949 F_I2D_SSL_SESSION NID_netscape_base_url R_BAD_SSL_FILETYPE
7950 F_READ_N NID_netscape_ca_policy_url R_BAD_SSL_SESSION_ID_LENGTH
7951 F_REQUEST_CERTIFICATE NID_netscape_ca_revocation_url R_BAD_STATE
7952 F_SERVER_HELLO NID_netscape_cert_extension R_BAD_WRITE_RETRY
7953 F_SSL_CERT_NEW NID_netscape_cert_sequence R_CHALLENGE_IS_DIFFERENT
7954 F_SSL_GET_NEW_SESSION NID_netscape_cert_type R_CIPHER_TABLE_SRC_ERROR
7955 F_SSL_NEW NID_netscape_comment R_INVALID_CHALLENGE_LENGTH
7956 F_SSL_READ NID_netscape_data_type R_NO_CERTIFICATE_SET
7957 F_SSL_RSA_PRIVATE_DECRYPT NID_netscape_renewal_url R_NO_CERTIFICATE_SPECIFIED
7958 F_SSL_RSA_PUBLIC_ENCRYPT NID_netscape_revocation_url R_NO_CIPHER_LIST
7959 F_SSL_SESSION_NEW NID_netscape_ssl_server_name R_NO_CIPHER_MATCH
7960 F_SSL_SESSION_PRINT_FP NID_ns_sgc R_NO_PRIVATEKEY
7961 F_SSL_SET_FD NID_organizationName R_NO_PUBLICKEY
7962 F_SSL_SET_RFD NID_organizationalUnitName R_NULL_SSL_CTX
7963 F_SSL_SET_WFD NID_pbeWithMD2AndDES_CBC R_PEER_DID_NOT_RETURN_A_CERTIFICATE
7964 F_SSL_USE_CERTIFICATE NID_pbeWithMD2AndRC2_CBC R_PEER_ERROR
7965 F_SSL_USE_CERTIFICATE_ASN1 NID_pbeWithMD5AndCast5_CBC R_PEER_ERROR_CERTIFICATE
7966 F_SSL_USE_CERTIFICATE_FILE NID_pbeWithMD5AndDES_CBC R_PEER_ERROR_NO_CIPHER
7967 F_SSL_USE_PRIVATEKEY NID_pbeWithMD5AndRC2_CBC R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE
7968 F_SSL_USE_PRIVATEKEY_ASN1 NID_pbeWithSHA1AndDES_CBC R_PUBLIC_KEY_ENCRYPT_ERROR
7969 F_SSL_USE_PRIVATEKEY_FILE NID_pbeWithSHA1AndRC2_CBC R_PUBLIC_KEY_IS_NOT_RSA
7970 F_SSL_USE_RSAPRIVATEKEY NID_pbe_WithSHA1And128BitRC2_CBC R_READ_WRONG_PACKET_TYPE
7971 F_SSL_USE_RSAPRIVATEKEY_ASN1 NID_pbe_WithSHA1And128BitRC4 R_SHORT_READ
7972 F_SSL_USE_RSAPRIVATEKEY_FILE NID_pbe_WithSHA1And2_Key_TripleDES_CBC R_SSL_SESSION_ID_IS_DIFFERENT
7973 F_WRITE_PENDING NID_pbe_WithSHA1And3_Key_TripleDES_CBC R_UNABLE_TO_EXTRACT_PUBLIC_KEY
7974 GEN_DIRNAME NID_pbe_WithSHA1And40BitRC2_CBC R_UNKNOWN_REMOTE_ERROR_TYPE
7975 GEN_DNS NID_pbe_WithSHA1And40BitRC4 R_UNKNOWN_STATE
7976 GEN_EDIPARTY NID_pbes2 R_X509_LIB
7977 GEN_EMAIL NID_pbmac1 SENT_SHUTDOWN
7978 GEN_IPADD NID_pkcs SESSION_ASN1_VERSION
7979 GEN_OTHERNAME NID_pkcs3 ST_ACCEPT
7980 GEN_RID NID_pkcs7 ST_BEFORE
7981 GEN_URI NID_pkcs7_data ST_CONNECT
7982 GEN_X400 NID_pkcs7_digest ST_INIT
7983 MBSTRING_ASC NID_pkcs7_encrypted ST_OK
7984 MBSTRING_BMP NID_pkcs7_enveloped ST_READ_BODY
7985 MBSTRING_FLAG NID_pkcs7_signed ST_READ_HEADER
7986 MBSTRING_UNIV NID_pkcs7_signedAndEnveloped VERIFY_CLIENT_ONCE
7987 MBSTRING_UTF8 NID_pkcs8ShroudedKeyBag VERIFY_FAIL_IF_NO_PEER_CERT
7988 MIN_RSA_MODULUS_LENGTH_IN_BYTES NID_pkcs9 VERIFY_NONE
7989 MODE_ACCEPT_MOVING_WRITE_BUFFER NID_pkcs9_challengePassword VERIFY_PEER
7990 MODE_AUTO_RETRY NID_pkcs9_contentType WRITING
7991 MODE_ENABLE_PARTIAL_WRITE NID_pkcs9_countersignature X509_LOOKUP
7992 MODE_RELEASE_BUFFERS NID_pkcs9_emailAddress X509_PURPOSE_ANY
7993 NID_OCSP_sign NID_pkcs9_extCertAttributes X509_PURPOSE_CRL_SIGN
7994 NID_SMIMECapabilities NID_pkcs9_messageDigest X509_PURPOSE_NS_SSL_SERVER
7995 NID_X500 NID_pkcs9_signingTime X509_PURPOSE_OCSP_HELPER
7996 NID_X509 NID_pkcs9_unstructuredAddress X509_PURPOSE_SMIME_ENCRYPT
7997 NID_ad_OCSP NID_pkcs9_unstructuredName X509_PURPOSE_SMIME_SIGN
7998 NID_ad_ca_issuers NID_private_key_usage_period X509_PURPOSE_SSL_CLIENT
7999 NID_algorithm NID_rc2_40_cbc X509_PURPOSE_SSL_SERVER
8000 NID_authority_key_identifier NID_rc2_64_cbc X509_PURPOSE_TIMESTAMP_SIGN
8001 NID_basic_constraints NID_rc2_cbc X509_TRUST_COMPAT
8002 NID_bf_cbc NID_rc2_cfb64 X509_TRUST_EMAIL
8003 NID_bf_cfb64 NID_rc2_ecb X509_TRUST_OBJECT_SIGN
8004 NID_bf_ecb NID_rc2_ofb64 X509_TRUST_OCSP_REQUEST
8005 NID_bf_ofb64 NID_rc4 X509_TRUST_OCSP_SIGN
8006 NID_cast5_cbc NID_rc4_40 X509_TRUST_SSL_CLIENT
8007 NID_cast5_cfb64 NID_rc5_cbc X509_TRUST_SSL_SERVER
8008 NID_cast5_ecb NID_rc5_cfb64 X509_TRUST_TSA
8009 NID_cast5_ofb64 NID_rc5_ecb X509_V_FLAG_ALLOW_PROXY_CERTS
8010 NID_certBag NID_rc5_ofb64 X509_V_FLAG_CB_ISSUER_CHECK
8011 NID_certificate_policies NID_ripemd160 X509_V_FLAG_CHECK_SS_SIGNATURE
8012 NID_client_auth NID_ripemd160WithRSA X509_V_FLAG_CRL_CHECK
8013 NID_code_sign NID_rle_compression X509_V_FLAG_CRL_CHECK_ALL
8014 NID_commonName NID_rsa X509_V_FLAG_EXPLICIT_POLICY
8015 NID_countryName NID_rsaEncryption X509_V_FLAG_EXTENDED_CRL_SUPPORT
8016 NID_crlBag NID_rsadsi X509_V_FLAG_IGNORE_CRITICAL
8017 NID_crl_distribution_points NID_safeContentsBag X509_V_FLAG_INHIBIT_ANY
8018 NID_crl_number NID_sdsiCertificate X509_V_FLAG_INHIBIT_MAP
8019 NID_crl_reason NID_secretBag X509_V_FLAG_NOTIFY_POLICY
8020 NID_delta_crl NID_serialNumber X509_V_FLAG_POLICY_CHECK
8021 NID_des_cbc NID_server_auth X509_V_FLAG_POLICY_MASK
8022 NID_des_cfb64 NID_sha X509_V_FLAG_USE_CHECK_TIME
8023 NID_des_ecb NID_sha1 X509_V_FLAG_USE_DELTAS
8024 NID_des_ede NID_sha1WithRSA X509_V_FLAG_X509_STRICT
8025 NID_des_ede3 NID_sha1WithRSAEncryption X509_V_OK
8026 NID_des_ede3_cbc NID_shaWithRSAEncryption XN_FLAG_COMPAT
8027 NID_des_ede3_cfb64 NID_stateOrProvinceName XN_FLAG_DN_REV
8028 NID_des_ede3_ofb64 NID_subject_alt_name XN_FLAG_DUMP_UNKNOWN_FIELDS
8029 NID_des_ede_cbc NID_subject_key_identifier XN_FLAG_FN_ALIGN
8030 NID_des_ede_cfb64 NID_surname XN_FLAG_FN_LN
8031 NID_des_ede_ofb64 NID_sxnet XN_FLAG_FN_MASK
8032 NID_des_ofb64 NID_time_stamp XN_FLAG_FN_NONE
8033 NID_description NID_title XN_FLAG_FN_OID
8034 NID_desx_cbc NID_undef XN_FLAG_FN_SN
8035 NID_dhKeyAgreement NID_uniqueIdentifier XN_FLAG_MULTILINE
8036 NID_dnQualifier NID_x509Certificate XN_FLAG_ONELINE
8037 NID_dsa NID_x509Crl XN_FLAG_RFC2253
8038 NID_dsaWithSHA NID_zlib_compression XN_FLAG_SEP_COMMA_PLUS
8039 NID_dsaWithSHA1 NOTHING XN_FLAG_SEP_CPLUS_SPC
8040 NID_dsaWithSHA1_2 OPENSSL_VERSION_NUMBER XN_FLAG_SEP_MASK
8041 NID_dsa_2 OP_ALL XN_FLAG_SEP_MULTILINE
8042 NID_email_protect OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION XN_FLAG_SEP_SPLUS_SPC
8043 NID_ext_key_usage OP_CIPHER_SERVER_PREFERENCE XN_FLAG_SPC_EQ
8044 INTERNAL ONLY functions (do not use these)
8046 The following functions are not intended for use from outside of
8047 Net::SSLeay module. They might be removed, renamed or changed without
8048 prior notice in future version.
8049 Simply DO NOT USE THEM!
8051 · hello
8053 · blength
8055 · constant
8057
8059 One very good example to look at is the implementation of "sslcat()" in
8060 the "SSLeay.pm" file.
8061 The following is a simple SSLeay client (with too little error checking
8063 :-(
8064 #!/usr/bin/perl
8066 use Socket;
8067 use Net::SSLeay qw(die_now die_if_ssl_error) ;
8068 Net::SSLeay::load_error_strings();
8069 Net::SSLeay::SSLeay_add_ssl_algorithms();
8070 Net::SSLeay::randomize();
8071 ($dest_serv, $port, $msg) = @ARGV; # Read command line
8073 $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
8074 $dest_ip = gethostbyname ($dest_serv);
8075 $dest_serv_params = sockaddr_in($port, $dest_ip);
8076 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
8078 connect (S, $dest_serv_params) or die "connect: $!";
8079 select (S); $| = 1; select (STDOUT); # Eliminate STDIO buffering
8080 # The network connection is now open, lets fire up SSL
8082 $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
8084 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
8085 or die_if_ssl_error("ssl ctx set options");
8086 $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
8087 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
8088 $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
8089 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
8090 # Exchange data
8092 $res = Net::SSLeay::write($ssl, $msg); # Perl knows how long $msg is
8094 die_if_ssl_error("ssl write");
8095 CORE::shutdown S, 1; # Half close --> No more output, sends EOF to server
8096 $got = Net::SSLeay::read($ssl); # Perl returns undef on failure
8097 die_if_ssl_error("ssl read");
8098 print $got;
8099 Net::SSLeay::free ($ssl); # Tear down connection
8101 Net::SSLeay::CTX_free ($ctx);
8102 close S;
8103 The following is a simple SSLeay echo server (non forking):
8105 #!/usr/bin/perl -w
8107 use Socket;
8108 use Net::SSLeay qw(die_now die_if_ssl_error);
8109 Net::SSLeay::load_error_strings();
8110 Net::SSLeay::SSLeay_add_ssl_algorithms();
8111 Net::SSLeay::randomize();
8112 $our_ip = "\0\0\0\0"; # Bind to all interfaces
8114 $port = 1235;
8115 $sockaddr_template = 'S n a4 x8';
8116 $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
8117 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
8119 bind (S, $our_serv_params) or die "bind: $!";
8120 listen (S, 5) or die "listen: $!";
8121 $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
8122 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
8123 or die_if_ssl_error("ssl ctx set options");
8124 # Following will ask password unless private key is not encrypted
8126 Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
8127 &Net::SSLeay::FILETYPE_PEM);
8128 die_if_ssl_error("private key");
8129 Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
8130 &Net::SSLeay::FILETYPE_PEM);
8131 die_if_ssl_error("certificate");
8132 while (1) {
8134 print "Accepting connections...\n";
8135 ($addr = accept (NS, S)) or die "accept: $!";
8136 select (NS); $| = 1; select (STDOUT); # Piping hot!
8137 ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
8139 @inetaddr = unpack('C4',$client_ip);
8140 print "$af connection from " .
8141 join ('.', @inetaddr) . ":$client_port\n";
8142 # We now have a network connection, lets fire up SSLeay...
8144 $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
8146 Net::SSLeay::set_fd($ssl, fileno(NS));
8147 $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
8149 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
8150 # Connected. Exchange some data.
8152 $got = Net::SSLeay::read($ssl); # Returns undef on fail
8154 die_if_ssl_error("ssl read");
8155 print "Got `$got' (" . length ($got) . " chars)\n";
8156 Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
8158 die_if_ssl_error("ssl write");
8159 Net::SSLeay::free ($ssl); # Tear down connection
8161 close NS;
8162 }
8163 Yet another echo server. This one runs from "/etc/inetd.conf" so it
8165 avoids all the socket code overhead. Only caveat is opening an rsa key
8166 file - it had better be without any encryption or else it will not know
8167 where to ask for the password. Note how "STDIN" and "STDOUT" are wired
8168 to SSL.
8169 #!/usr/bin/perl
8171 # /etc/inetd.conf
8172 # ssltst stream tcp nowait root /path/to/server.pl server.pl
8173 # /etc/services
8174 # ssltst 1234/tcp
8175 use Net::SSLeay qw(die_now die_if_ssl_error);
8177 Net::SSLeay::load_error_strings();
8178 Net::SSLeay::SSLeay_add_ssl_algorithms();
8179 Net::SSLeay::randomize();
8180 chdir '/key/dir' or die "chdir: $!";
8182 $| = 1; # Piping hot!
8183 open LOG, ">>/dev/console" or die "Can't open log file $!";
8184 select LOG; print "server.pl started\n";
8185 $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
8187 $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
8188 Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
8189 and die_if_ssl_error("ssl set options");
8190 # We get already open network connection from inetd, now we just
8192 # need to attach SSLeay to STDIN and STDOUT
8193 Net::SSLeay::set_rfd($ssl, fileno(STDIN));
8194 Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
8195 Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
8197 Net::SSLeay::FILETYPE_PEM);
8198 die_if_ssl_error("private key");
8199 Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
8200 Net::SSLeay::FILETYPE_PEM);
8201 die_if_ssl_error("certificate");
8202 Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
8204 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
8205 $got = Net::SSLeay::read($ssl);
8207 die_if_ssl_error("ssl read");
8208 print "Got `$got' (" . length ($got) . " chars)\n";
8209 Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
8211 die_if_ssl_error("ssl write");
8212 Net::SSLeay::free ($ssl); # Tear down the connection
8214 Net::SSLeay::CTX_free ($ctx);
8215 close LOG;
8216 There are also a number of example/test programs in the examples
8218 directory:
8219 sslecho.pl - A simple server, not unlike the one above
8221 minicli.pl - Implements a client using low level SSLeay routines
8222 sslcat.pl - Demonstrates using high level sslcat utility function
8223 get_page.pl - Is a utility for getting html pages from secure servers
8224 callback.pl - Demonstrates certificate verification and callback usage
8225 stdio_bulk.pl - Does SSL over Unix pipes
8226 ssl-inetd-serv.pl - SSL server that can be invoked from inetd.conf
8227 httpd-proxy-snif.pl - Utility that allows you to see how a browser
8228 sends https request to given server and what reply
8229 it gets back (very educative :-)
8230 makecert.pl - Creates a self signed cert (does not use this module)
8231
8233 "Net::SSLeay::read()" uses an internal buffer of 32KB, thus no single
8234 read will return more. In practice one read returns much less, usually
8235 as much as fits in one network packet. To work around this, you should
8236 use a loop like this:
8237 $reply = '';
8239 while ($got = Net::SSLeay::read($ssl)) {
8240 last if print_errs('SSL_read');
8241 $reply .= $got;
8242 }
8243 Although there is no built-in limit in "Net::SSLeay::write()", the
8245 network packet size limitation applies here as well, thus use:
8246 $written = 0;
8248 while ($written < length($message)) {
8250 $written += Net::SSLeay::write($ssl, substr($message, $written));
8251 last if print_errs('SSL_write');
8252 }
8253 Or alternatively you can just use the following convenience functions:
8255 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
8257 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
8258
8260 Autoloader emits a
8261 Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
8263 warning if die_if_ssl_error is made autoloadable. If you figure out
8265 why, drop me a line.
8266 Callback set using "SSL_set_verify()" does not appear to work. This may
8268 well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
8269 using "SSL_CTX_set_verify()" instead and do not be surprised if even
8270 this stops working in future versions.
8271 Callback and certificate verification stuff is generally too little
8273 tested.
8274 Random numbers are not initialized randomly enough, especially if you
8276 do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
8277 platforms - but it's been suggested that cryptorand daemon from the
8278 SUNski package solves this). In this case you should investigate third
8279 party software that can emulate these devices, e.g. by way of a named
8280 pipe to some program.
8281 Another gotcha with random number initialization is randomness
8283 depletion. This phenomenon, which has been extensively discussed in
8284 OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
8285 to block if you use "/dev/random" or to operate insecurely if you use
8286 "/dev/urandom". What happens is that when too much randomness is drawn
8287 from the operating system's randomness pool then randomness can
8288 temporarily be unavailable. "/dev/random" solves this problem by
8289 waiting until enough randomness can be gathered - and this can take a
8290 long time since blocking reduces activity in the machine and less
8291 activity provides less random events: a vicious circle. "/dev/urandom"
8292 solves this dilemma more pragmatically by simply returning predictable
8293 "random" numbers. Some" /dev/urandom" emulation software however
8294 actually seems to implement "/dev/random" semantics. Caveat emptor.
8295 I've been pointed to two such daemons by Mik Firestone
8297 <mik@@speed.stdio._com> who has used them on Solaris 8:
8298 1. Entropy Gathering Daemon (EGD) at
8300 <http://www.lothar.com/tech/crypto/>
8301 2. Pseudo-random number generating daemon (PRNGD) at
8303 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
8304 If you are using the low level API functions to communicate with other
8306 SSL implementations, you would do well to call
8307 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
8309 or die_if_ssl_error("ssl ctx set options");
8310 to cope with some well know bugs in some other SSL implementations. The
8312 high level API functions always set all known compatibility options.
8313 Sometimes "sslcat()" (and the high level HTTPS functions that build on
8315 it) is too fast in signaling the EOF to legacy HTTPS servers. This
8316 causes the server to return empty page. To work around this problem you
8317 can set the global variable
8318 $Net::SSLeay::slowly = 1; # Add sleep so broken servers can keep up
8320 HTTP/1.1 is not supported. Specifically this module does not know to
8322 issue or serve multiple http requests per connection. This is a serious
8323 shortcoming, but using the SSL session cache on your server helps to
8324 alleviate the CPU load somewhat.
8325 As of version 1.09 many newer OpenSSL auxiliary functions were added
8327 (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
8328 Unfortunately I have not had any opportunity to test these. Some of
8329 them are trivial enough that I believe they "just work", but others
8330 have rather complex interfaces with function pointers and all. In these
8331 cases you should proceed wit great caution.
8332 This module defaults to using OpenSSL automatic protocol negotiation
8334 code for automatically detecting the version of the SSL protocol that
8335 the other end talks. With most web servers this works just fine, but
8336 once in a while I get complaints from people that the module does not
8337 work with some web servers. Usually this can be solved by explicitly
8338 setting the protocol version, e.g.
8339 $Net::SSLeay::ssl_version = 2; # Insist on SSLv2
8341 $Net::SSLeay::ssl_version = 3; # Insist on SSLv3
8342 $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
8343 Although the autonegotiation is nice to have, the SSL standards do not
8345 formally specify any such mechanism. Most of the world has accepted the
8346 SSLeay/OpenSSL way of doing it as the de facto standard. But for the
8347 few that think differently, you have to explicitly speak the correct
8348 version. This is not really a bug, but rather a deficiency in the
8349 standards. If a site refuses to respond or sends back some nonsensical
8350 error codes (at the SSL handshake level), try this option before
8351 mailing me.
8352 On some systems, OpenSSL may be compiled without support for SSLv2. If
8354 this is the case, Net::SSLeay will warn if ssl_version has been set to
8355 2.
8356 The high level API returns the certificate of the peer, thus allowing
8358 one to check what certificate was supplied. However, you will only be
8359 able to check the certificate after the fact, i.e. you already sent
8360 your form data by the time you find out that you did not trust them,
8361 oops.
8362 So, while being able to know the certificate after the fact is surely
8364 useful, the security minded would still choose to do the connection and
8365 certificate verification first and only then exchange data with the
8366 site. Currently none of the high level API functions do this, thus you
8367 would have to program it using the low level API. A good place to start
8368 is to see how the "Net::SSLeay::http_cat()" function is implemented.
8369 The high level API functions use a global file handle "SSLCAT_S"
8371 internally. This really should not be a problem because there is no way
8372 to interleave the high level API functions, unless you use threads (but
8373 threads are not very well supported in perl anyway (as of version
8374 5.6.1). However, you may run into problems if you call undocumented
8375 internal functions in an interleaved fashion. The best solution is to
8376 "require Net::SSLeay" in one thread after all the threads have been
8377 created.
8378
8380 Random number generator not seeded!!!
8381 (W) This warning indicates that "randomize()" was not able to read
8382 "/dev/random" or "/dev/urandom", possibly because your system does
8383 not have them or they are differently named. You can still use SSL,
8384 but the encryption will not be as strong.
8385 open_tcp_connection: destination host not found:`server' (port 123)
8387 ($!)
8388 Name lookup for host named "server" failed.
8389 open_tcp_connection: failed `server', 123 ($!)
8391 The name was resolved, but establishing the TCP connection failed.
8392 msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
8394 proto
8395 SSLeay error string. The first number (123) is the PID, the second
8396 number (1) indicates the position of the error message in SSLeay
8397 error stack. You often see a pile of these messages as errors
8398 cascade.
8399 msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
8401 The same as above, but you didn't call load_error_strings() so
8402 SSLeay couldn't verbosely explain the error. You can still find out
8403 what it means with this command:
8404 /usr/local/ssl/bin/ssleay errstr 02001002
8406 Password is being asked for private key
8408 This is normal behaviour if your private key is encrypted. Either
8409 you have to supply the password or you have to use an unencrypted
8410 private key. Scan OpenSSL.org for the FAQ that explains how to do
8411 this (or just study examples/makecert.pl which is used during "make
8412 test" to do just that).
8413
8415 You can mitigate some of the security vulnerabilites that might be
8416 present in your SSL/TLS application:
8417 BEAST Attack
8419 http://blogs.cisco.com/security/beat-the-beast-with-tls/
8420 https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
8421 http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
8422 The BEAST attack relies on a weakness in the way CBC mode is used in
8424 SSL/TLS. In OpenSSL versions 0.9.6d and later, the protocol-level
8425 mitigation is enabled by default, thus making it not vulnerable to the
8426 BEAST attack.
8427 Solutions:
8429 · Compile with OpenSSL versions 0.9.6d or later, which enables
8431 SSL_OP_ALL by default
8432 · Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
8434 enabled by default)
8435 · Dont support SSLv2, SSLv3
8437 · Actively control the ciphers your server supports with
8439 set_cipher_list:
8440 Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
8442 Session Resumption
8444 http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
8445 The SSL Labs vulnerability test on your SSL server might report in red:
8447 Session resumption No (IDs assigned but not accepted)
8449 This report is not really bug or a vulnerability, since the server will
8451 not accept session resumption requests. However, you can prevent this
8452 noise in the report by disabling the session cache altogether:
8453 Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx, 0);
8454 Secure Renegotiation and DoS Attack
8456 https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
8457 This is not a "security flaw," it is more of a DoS vulnerability.
8459 Solutions:
8461 · Do not support SSLv2
8463 · Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
8465 · Compile with OpenSSL 0.9.8m or later
8467
8469 Please report any bugs or feature requests to "bug-Net-SSLeay at
8470 rt.cpan.org", or through the web interface at
8471 <http://rt.cpan.org/Public/Dist/Display.html?Name=Net-SSLeay>. I will
8472 be notified, and then you'll automatically be notified of progress on
8473 your bug as I make changes.
8474 Subversion access to the latest source code etc can be obtained at
8476 <http://alioth.debian.org/projects/net-ssleay>
8477 The developer mailing list (for people interested in contributing to
8479 the source code) can be found at
8480 <http://lists.alioth.debian.org/mailman/listinfo/net-ssleay-devel>
8481 You can find documentation for this module with the "perldoc" command.
8483 perldoc Net::SSLeay
8485 You can also look for information at:
8487 · AnnoCPAN: Annotated CPAN documentation
8489 <http://annocpan.org/dist/Net-SSLeay>
8491 · CPAN Ratings
8493 <http://cpanratings.perl.org/d/Net-SSLeay>
8495 · Search CPAN
8497 <http://search.cpan.org/dist/Net-SSLeay>
8499 Commercial support for Net::SSLeay may be obtained from
8501 Symlabs (netssleay@symlabs.com)
8503 Tel: +351-214.222.630
8504 Fax: +351-214.222.637
8505
8507 Maintained by Mike McCauley and Florian Ragwitz since November 2005
8508 Originally written by Sampo Kellomaeki <sampo@symlabs.com>
8510
8512 Copyright (c) 1996-2003 Sampo Kellomaeki <sampo@symlabs.com>
8513 Copyright (C) 2005-2006 Florian Ragwitz <rafl@debian.org>
8515 Copyright (C) 2005 Mike McCauley <mikem@airspayce.com>
8517 All Rights Reserved.
8519 Distribution and use of this module is under the same terms as the
8521 OpenSSL package itself (i.e. free, but mandatory attribution; NO
8522 WARRANTY). Please consult LICENSE file in the root of the OpenSSL
8523 distribution.
8524 While the source distribution of this perl module does not contain
8526 Eric's or OpenSSL's code, if you use this module you will use OpenSSL
8527 library. Please give Eric and OpenSSL team credit (as required by their
8528 licenses).
8529 And remember, you, and nobody else but you, are responsible for
8531 auditing this module and OpenSSL library for security problems,
8532 backdoors, and general suitability for your application.
8533
8535 Net::SSLeay::Handle - File handle interface
8536 ./examples - Example servers and a clients
8537 <http://www.openssl.org/> - OpenSSL source, documentation, etc
8538 openssl-users-request@openssl.org - General OpenSSL mailing list
8539 <http://www.ietf.org/rfc/rfc2246.txt> - TLS 1.0 specification
8540 <http://www.w3c.org> - HTTP specifications
8541 <http://www.ietf.org/rfc/rfc2617.txt> - How to send password
8542 <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
8543 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
8544 - pseudo-random number generating daemon (PRNGD)
8545 perl(1)
8546 perlref(1)
8547 perllol(1)
8548 perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
8549perl v5.16.3 2017-08-02 Net::SSLeay(3)