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 It is compatible with OpenSSL 1.0 and 1.1. Some functions are not
49 available under OpenSSL 1.1.
50 Net::SSLeay module basically comprise of:
52 · High level functions for accessing web servers (by using
54 HTTP/HTTPS)
55 · Low level API (mostly mapped 1:1 to openssl's C functions)
57 · Convenience functions (related to low level API but with more perl
59 friendly interface)
60 There is also a related module called Net::SSLeay::Handle included in
62 this distribution that you might want to use instead. It has its own
63 pod documentation.
64 High level functions for accessing web servers
66 This module offers some high level convenience functions for accessing
67 web pages on SSL servers (for symmetry, the same API is offered for
68 accessing http servers, too), an "sslcat()" function for writing your
69 own clients, and finally access to the SSL api of the SSLeay/OpenSSL
70 package so you can write servers or clients for more complicated
71 applications.
72 For high level functions it is most convenient to import them into your
74 main namespace as indicated in the synopsis.
75 Basic set of functions
77 · get_https
79 · post_https
81 · put_https
83 · head_https
85 · do_https
87 · sslcat
89 · https_cat
91 · make_form
93 · make_headers
95 Case 1 (in SYNOPSIS) demonstrates the typical invocation of get_https()
97 to fetch an HTML page from secure server. The first argument provides
98 the hostname or IP in dotted decimal notation of the remote server to
99 contact. The second argument is the TCP port at the remote end (your
100 own port is picked arbitrarily from high numbered ports as usual for
101 TCP). The third argument is the URL of the page without the host name
102 part. If in doubt consult the HTTP specifications at
103 <http://www.w3c.org>.
104 Case 2 (in SYNOPSIS) demonstrates full fledged use of "get_https()". As
106 can be seen, "get_https()" parses the response and response headers and
107 returns them as a list, which can be captured in a hash for later
108 reference. Also a fourth argument to "get_https()" is used to insert
109 some additional headers in the request. "make_headers()" is a function
110 that will convert a list or hash to such headers. By default
111 "get_https()" supplies "Host" (to make virtual hosting easy) and
112 "Accept" (reportedly needed by IIS) headers.
113 Case 2b (in SYNOPSIS) demonstrates how to get a password protected
115 page. Refer to the HTTP protocol specifications for further details
116 (e.g. RFC-2617).
117 Case 3 (in SYNOPSIS) invokes "post_https()" to submit a HTML/CGI form
119 to a secure server. The first four arguments are equal to "get_https()"
120 (note that the empty string ('') is passed as header argument). The
121 fifth argument is the contents of the form formatted according to CGI
122 specification. Do not post UTF-8 data as content: use utf8::downgrade
123 first. In this case the helper function "make_https()" is used to do
124 the formatting, but you could pass any string. "post_https()"
125 automatically adds "Content-Type" and "Content-Length" headers to the
126 request.
127 Case 4 (in SYNOPSIS) shows the fundamental "sslcat()" function
129 (inspired in spirit by the "netcat" utility :-). It's your swiss army
130 knife that allows you to easily contact servers, send some data, and
131 then get the response. You are responsible for formatting the data and
132 parsing the response - "sslcat()" is just a transport.
133 Case 5 (in SYNOPSIS) is a full invocation of "sslcat()" which allows
135 the return of errors as well as the server (peer) certificate.
136 The $trace global variable can be used to control the verbosity of the
138 high level functions. Level 0 guarantees silence, level 1 (the default)
139 only emits error messages.
140 Alternate versions of high-level API
142 · get_https3
144 · post_https3
146 · put_https3
148 · get_https4
150 · post_https4
152 · put_https4
154 The above mentioned functions actually return the response headers as a
156 list, which only gets converted to hash upon assignment (this
157 assignment looses information if the same header occurs twice, as may
158 be the case with cookies). There are also other variants of the
159 functions that return unprocessed headers and that return a reference
160 to a hash.
161 ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
163 for ($i = 0; $i < $#headers; $i+=2) {
164 print "$headers[$i] = " . $headers[$i+1] . "\n";
165 }
166 ($page, $response, $headers, $server_cert)
168 = get_https3('www.bacus.pt', 443, '/');
169 print "$headers\n";
170 ($page, $response, $headers_ref)
172 = get_https4('www.bacus.pt', 443, '/');
173 for $k (sort keys %{$headers_ref}) {
174 for $v (@{$$headers_ref{$k}}) {
175 print "$k = $v\n";
176 }
177 }
178 All of the above code fragments accomplish the same thing: display all
180 values of all headers. The API functions ending in "3" return the
181 headers simply as a scalar string and it is up to the application to
182 split them up. The functions ending in "4" return a reference to a hash
183 of arrays (see perlref and perllol if you are not familiar with complex
184 perl data structures). To access a single value of such a header hash
185 you would do something like
186 print $$headers_ref{COOKIE}[0];
188 Variants 3 and 4 also allow you to discover the server certificate in
190 case you would like to store or display it, e.g.
191 ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
193 if (!defined($server_cert) || ($server_cert == 0)) {
194 warn "Subject Name: undefined, Issuer Name: undefined";
195 } else {
196 warn 'Subject Name: '
197 . Net::SSLeay::X509_NAME_oneline(
198 Net::SSLeay::X509_get_subject_name($server_cert))
199 . 'Issuer Name: '
200 . Net::SSLeay::X509_NAME_oneline(
201 Net::SSLeay::X509_get_issuer_name($server_cert));
202 }
203 Beware that this method only allows after the fact verification of the
205 certificate: by the time "get_https3()" has returned the https request
206 has already been sent to the server, whether you decide to trust it or
207 not. To do the verification correctly you must either employ the
208 OpenSSL certificate verification framework or use the lower level API
209 to first connect and verify the certificate and only then send the http
210 data. See the implementation of "ds_https3()" for guidance on how to do
211 this.
212 Using client certificates
214 Secure web communications are encrypted using symmetric crypto keys
216 exchanged using encryption based on the certificate of the server.
217 Therefore in all SSL connections the server must have a certificate.
218 This serves both to authenticate the server to the clients and to
219 perform the key exchange.
220 Sometimes it is necessary to authenticate the client as well. Two
222 options are available: HTTP basic authentication and a client side
223 certificate. The basic authentication over HTTPS is actually quite safe
224 because HTTPS guarantees that the password will not travel in the
225 clear. Never-the-less, problems like easily guessable passwords remain.
226 The client certificate method involves authentication of the client at
227 the SSL level using a certificate. For this to work, both the client
228 and the server have certificates (which typically are different) and
229 private keys.
230 The API functions outlined above accept additional arguments that allow
232 one to supply the client side certificate and key files. The format of
233 these files is the same as used for server certificates and the caveat
234 about encrypting private keys applies.
235 ($page, $result, %headers) = # 2c
237 = get_https('www.bacus.pt', 443, '/protected.html',
238 make_headers(Authorization =>
239 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
240 '', $mime_type6, $path_to_crt7, $path_to_key8);
241 ($page, $response, %reply_headers)
243 = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
244 make_headers('Authorization' =>
245 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
246 make_form(OK => '1', name => 'Sampo'),
247 $mime_type6, $path_to_crt7, $path_to_key8);
248 Case 2c (in SYNOPSIS) demonstrates getting a password protected page
250 that also requires a client certificate, i.e. it is possible to use
251 both authentication methods simultaneously.
252 Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
254 requires both password authentication and a client certificate, just
255 like in case 2c.
256 Note: The client will not send a certificate unless the server requests
258 one. This is typically achieved by setting the verify mode to
259 "VERIFY_PEER" on the server:
260 Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
262 See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
264 description.
265 Working through a web proxy
267 · set_proxy
269 "Net::SSLeay" can use a web proxy to make its connections. You need to
271 first set the proxy host and port using "set_proxy()" and then just use
272 the normal API functions, e.g:
273 Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
275 ($page) = get_https('www.bacus.pt', 443, '/');
276 If your proxy requires authentication, you can supply a username and
278 password as well
279 Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
281 ($page, $result, %headers) =
282 = get_https('www.bacus.pt', 443, '/protected.html',
283 make_headers(Authorization =>
284 'Basic ' . MIME::Base64::encode("susie:pass",''))
285 );
286 This example demonstrates the case where we authenticate to the proxy
288 as "joe" and to the final web server as "susie". Proxy authentication
289 requires the "MIME::Base64" module to work.
290 HTTP (without S) API
292 · get_http
294 · post_http
296 · tcpcat
298 · get_httpx
300 · post_httpx
302 · tcpxcat
304 Over the years it has become clear that it would be convenient to use
306 the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
307 (see "LWP" for the heavy-weight object-oriented approach). In fact it
308 would be nice to be able to flip https on and off on the fly. Thus
309 regular HTTP support was evolved.
310 use Net::SSLeay qw(get_http post_http tcpcat
312 get_httpx post_httpx tcpxcat
313 make_headers make_form);
314 ($page, $result, %headers)
316 = get_http('www.bacus.pt', 443, '/protected.html',
317 make_headers(Authorization =>
318 'Basic ' . MIME::Base64::encode("$user:$pass",''))
319 );
320 ($page, $response, %reply_headers)
322 = post_http('www.bacus.pt', 443, '/foo.cgi', '',
323 make_form(OK => '1',
324 name => 'Sampo'
325 ));
326 ($reply, $err) = tcpcat($host, $port, $request);
328 ($page, $result, %headers)
330 = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
331 make_headers(Authorization =>
332 'Basic ' . MIME::Base64::encode("$user:$pass",''))
333 );
334 ($page, $response, %reply_headers)
336 = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
337 make_form(OK => '1', name => 'Sampo' ));
338 ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
340 As can be seen, the "x" family of APIs takes as the first argument a
342 flag which indicates whether SSL is used or not.
343 Certificate verification and Certificate Revocation Lists (CRLs)
345 OpenSSL supports the ability to verify peer certificates. It can also
346 optionally check the peer certificate against a Certificate Revocation
347 List (CRL) from the certificates issuer. A CRL is a file, created by
348 the certificate issuer that lists all the certificates that it
349 previously signed, but which it now revokes. CRLs are in PEM format.
350 You can enable "Net::SSLeay CRL" checking like this:
352 &Net::SSLeay::X509_STORE_set_flags
354 (&Net::SSLeay::CTX_get_cert_store($ssl),
355 &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
356 After setting this flag, if OpenSSL checks a peer's certificate, then
358 it will attempt to find a CRL for the issuer. It does this by looking
359 for a specially named file in the search directory specified by
360 CTX_load_verify_locations. CRL files are named with the hash of the
361 issuer's subject name, followed by ".r0", ".r1" etc. For example
362 "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
363 issuer, and then check for a revocation of the peer certificate in all
364 of them. (You can also force it to look in a specific named CRL file.,
365 see below). You can find out the hash of the issuer subject name in a
366 CRL with
367 openssl crl -in crl.pem -hash -noout
369 If the peer certificate does not pass the revocation list, or if no CRL
371 is found, then the handshaking fails with an error.
372 You can also force OpenSSL to look for CRLs in one or more arbitrarily
374 named files.
375 my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
377 my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
378 if ($crl) {
379 Net::SSLeay::X509_STORE_add_crl(
380 Net::SSLeay::CTX_get_cert_store($ssl, $crl)
381 );
382 } else {
383 error reading CRL....
384 }
385 Usually the URLs where you can download the CRLs is contained in the
387 certificate itself and you can extract them with
388 my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
390 But there is no automatic downloading of the CRLs and often these CRLs
392 are too huge to just download them to verify a single certificate.
393 Also, these CRLs are often in DER format which you need to convert to
394 PEM before you can use it:
395 openssl crl -in crl.der -inform der -out crl.pem
397 So as an alternative for faster and timely revocation checks you better
399 use the Online Status Revocation Protocol (OCSP).
400 Certificate verification and Online Status Revocation Protocol (OCSP)
402 While checking for revoked certificates is possible and fast with
403 Certificate Revocation Lists, you need to download the complete and
404 often huge list before you can verify a single certificate.
405 A faster way is to ask the CA to check the revocation of just a single
407 or a few certificates using OCSP. Basically you generate for each
408 certificate an OCSP_CERTID based on the certificate itself and its
409 issuer, put the ids togetether into an OCSP_REQUEST and send the
410 request to the URL given in the certificate.
411 As a result you get back an OCSP_RESPONSE and need to check the status
413 of the response, check that it is valid (e.g. signed by the CA) and
414 finally extract the information about each OCSP_CERTID to find out if
415 the certificate is still valid or got revoked.
416 With Net::SSLeay this can be done like this:
418 # get id(s) for given certs, like from get_peer_certificate
420 # or get_peer_cert_chain. This will croak if
421 # - one tries to make an OCSP_CERTID for a self-signed certificate
422 # - the issuer of the certificate cannot be found in the SSL objects
423 # store, nor in the current certificate chain
424 my $cert = Net::SSLeay::get_peer_certificate($ssl);
425 my $id = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) };
426 die "failed to make OCSP_CERTID: $@" if $@;
427 # create OCSP_REQUEST from id(s)
429 # Multiple can be put into the same request, if the same OCSP responder
430 # is responsible for them.
431 my $req = Net::SSLeay::OCSP_ids2req($id);
432 # determine URI of OCSP responder
434 my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
435 # Send stringified OCSP_REQUEST with POST to $uri.
437 # We can ignore certificate verification for https, because the OCSP
438 # response itself is signed.
439 my $ua = HTTP::Tiny->new(verify_SSL => 0);
440 my $res = $ua->request( 'POST',$uri, {
441 headers => { 'Content-type' => 'application/ocsp-request' },
442 content => Net::SSLeay::i2d_OCSP_REQUEST($req)
443 });
444 my $content = $res && $res->{success} && $res->{content}
445 or die "query failed";
446 # Extract OCSP_RESPONSE.
448 # this will croak if the string is not an OCSP_RESPONSE
449 my $resp = eval { Net::SSLeay::d2i_OCSP_RESPONSE($content) };
450 # Check status of response.
452 my $status = Net::SSLeay::OCSP_response_status($resp);
453 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL())
454 die "OCSP response failed: ".
455 Net::SSLeay::OCSP_response_status_str($status);
456 }
457 # Verify signature of response and if nonce matches request.
459 # This will croak if there is a nonce in the response, but it does not match
460 # the request. It will return false if the signature could not be verified,
461 # in which case details can be retrieved with Net::SSLeay::ERR_get_error.
462 # It will not complain if the response does not contain a nonce, which is
463 # usually the case with pre-signed responses.
464 if ( ! eval { Net::SSLeay::OCSP_response_verify($ssl,$resp,$req) }) {
465 die "OCSP response verification failed";
466 }
467 # Extract information from OCSP_RESPONSE for each of the ids.
469 # If called in scalar context it will return the time (as time_t), when the
471 # next update is due (minimum of all successful responses inside $resp). It
472 # will croak on the following problems:
473 # - response is expired or not yet valid
474 # - no response for given OCSP_CERTID
475 # - certificate status is not good (e.g. revoked or unknown)
476 if ( my $nextupd = eval { Net::SSLeay::OCSP_response_results($resp,$id) }) {
477 warn "certificate is valid, next update in ".
478 ($nextupd-time())." seconds\n";
479 } else {
480 die "certificate is not valid: $@";
481 }
482 # But in array context it will return detailed information about each given
484 # OCSP_CERTID instead croaking on errors:
485 # if no @ids are given it will return information about all single responses
486 # in the OCSP_RESPONSE
487 my @results = Net::SSLeay::OCSP_response_results($resp,@ids);
488 for my $r (@results) {
489 print Dumper($r);
490 # @results are in the same order as the @ids and contain:
491 # $r->[0] - OCSP_CERTID
492 # $r->[1] - undef if no error (certificate good) OR error message as string
493 # $r->[2] - hash with details:
494 # thisUpdate - time_t of this single response
495 # nextUpdate - time_t when update is expected
496 # statusType - integer:
497 # V_OCSP_CERTSTATUS_GOOD(0)
498 # V_OCSP_CERTSTATUS_REVOKED(1)
499 # V_OCSP_CERTSTATUS_UNKNOWN(2)
500 # revocationTime - time_t (only if revoked)
501 # revocationReason - integer (only if revoked)
502 # revocationReason_str - reason as string (only if revoked)
503 }
504 To further speed up certificate revocation checking one can use a TLS
506 extension to instruct the server to staple the OCSP response:
507 # set TLS extension before doing SSL_connect
509 Net::SSLeay::set_tlsext_status_type($ssl,
510 Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
511 # setup callback to verify OCSP response
513 my $cert_valid = undef;
514 Net::SSLeay::CTX_set_tlsext_status_cb($context,sub {
515 my ($ssl,$resp) = @_;
516 if (!$resp) {
517 # Lots of servers don't return an OCSP response.
518 # In this case we must check the OCSP status outside the SSL
519 # handshake.
520 warn "server did not return stapled OCSP response\n";
521 return 1;
522 }
523 # verify status
524 my $status = Net::SSLeay::OCSP_response_status($resp);
525 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL()) {
526 warn "OCSP response failure: $status\n";
527 return 1;
528 }
529 # verify signature - we have no OCSP_REQUEST here to check nonce
530 if (!eval { Net::SSLeay::OCSP_response_verify($ssl,$resp) }) {
531 warn "OCSP response verify failed\n";
532 return 1;
533 }
534 # check if the certificate is valid
535 # we should check here against the peer_certificate
536 my $cert = Net::SSLeay::get_peer_certificate();
537 my $certid = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) } or do {
538 warn "cannot get certid from cert: $@";
539 $cert_valid = -1;
540 return 1;
541 };
542 if ( $nextupd = eval {
544 Net::SSLeay::OCSP_response_results($resp,$certid) }) {
545 warn "certificate not revoked\n";
546 $cert_valid = 1;
547 } else {
548 warn "certificate not valid: $@";
549 $cert_valid = 0;
550 }
551 });
552 # do SSL handshake here
554 ....
555 # check if certificate revocation was checked already
556 if ( ! defined $cert_valid) {
557 # check revocation outside of SSL handshake by asking OCSP responder
558 ...
559 } elsif ( ! $cert_valid ) {
560 die "certificate not valid - closing SSL connection";
561 } elsif ( $cert_valid<0 ) {
562 die "cannot verify certificate revocation - self-signed ?";
563 } else {
564 # everything fine
565 ...
566 }
567 Using Net::SSLeay in multi-threaded applications
569 IMPORTANT: versions 1.42 or earlier are not thread-safe!
570 Net::SSLeay module implements all necessary stuff to be ready for
572 multi-threaded environment - it requires openssl-0.9.7 or newer. The
573 implementation fully follows thread safety related requirements of
574 openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
575 If you are about to use Net::SSLeay (or any other module based on
577 Net::SSLeay) in multi-threaded perl application it is recommended to
578 follow this best-practice:
579 Initialization
581 Load and initialize Net::SSLeay module in the main thread:
583 use threads;
585 use Net::SSLeay;
586 Net::SSLeay::load_error_strings();
588 Net::SSLeay::SSLeay_add_ssl_algorithms();
589 Net::SSLeay::randomize();
590 sub do_master_job {
592 #... call whatever from Net::SSLeay
593 }
594 sub do_worker_job {
596 #... call whatever from Net::SSLeay
597 }
598 #start threads
600 my $master = threads->new(\&do_master_job, 'param1', 'param2');
601 my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
602 #waiting for all threads to finish
604 $_->join() for (threads->list);
605 NOTE: Openssl's "int SSL_library_init(void)" function (which is also
607 aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
608 and "add_ssl_algorithms") is not re-entrant and multiple calls can
609 cause a crash in threaded application. Net::SSLeay implements flags
610 preventing repeated calls to this function, therefore even multiple
611 initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
612 without trouble.
613 Using callbacks
615 Do not use callbacks across threads (the module blocks cross-thread
617 callback operations and throws a warning). Always do the callback
618 setup, callback use and callback destruction within the same thread.
619 Using openssl elements
621 All openssl elements (X509, SSL_CTX, ...) can be directly passed
623 between threads.
624 use threads;
626 use Net::SSLeay;
627 Net::SSLeay::load_error_strings();
629 Net::SSLeay::SSLeay_add_ssl_algorithms();
630 Net::SSLeay::randomize();
631 sub do_job {
633 my $context = shift;
634 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
635 #...
636 }
637 my $c = Net::SSLeay::CTX_new();
639 threads->create(\&do_job, $c);
640 Or:
642 use threads;
644 use Net::SSLeay;
645 my $context; #does not need to be 'shared'
647 Net::SSLeay::load_error_strings();
649 Net::SSLeay::SSLeay_add_ssl_algorithms();
650 Net::SSLeay::randomize();
651 sub do_job {
653 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
654 #...
655 }
656 $context = Net::SSLeay::CTX_new();
658 threads->create(\&do_job);
659 Using other perl modules based on Net::SSLeay
661 It should be fine to use any other module based on Net::SSLeay (like
663 IO::Socket::SSL) in multi-threaded applications. It is generally
664 recommended to do any global initialization of such a module in the
665 main thread before calling "threads->new(..)" or "threads->create(..)"
666 but it might differ module by module.
667 To be safe you can load and init Net::SSLeay explicitly in the main
669 thread:
670 use Net::SSLeay;
672 use Other::SSLeay::Based::Module;
673 Net::SSLeay::load_error_strings();
675 Net::SSLeay::SSLeay_add_ssl_algorithms();
676 Net::SSLeay::randomize();
677 Or even safer:
679 use Net::SSLeay;
681 use Other::SSLeay::Based::Module;
682 BEGIN {
684 Net::SSLeay::load_error_strings();
685 Net::SSLeay::SSLeay_add_ssl_algorithms();
686 Net::SSLeay::randomize();
687 }
688 Combining Net::SSLeay with other modules linked with openssl
690 BEWARE: This might be a big trouble! This is not guaranteed be thread-
692 safe!
693 There are many other (XS) modules linked directly to openssl library
695 (like Crypt::SSLeay).
696 As it is expected that also "another" module will call
698 "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
699 multiple openssl initialization by Net::SSLeay and "another" module.
700 As you can expect Net::SSLeay is not able to avoid multiple
702 initialization of openssl library called by "another" module, thus you
703 have to handle this on your own (in some cases it might not be possible
704 at all to avoid this).
705 Threading with get_https and friends
707 The convenience functions get_https, post_https etc all initialize the
709 SSL library by calling Net::SSLeay::initialize which does the
710 conventional library initialization:
711 Net::SSLeay::load_error_strings();
713 Net::SSLeay::SSLeay_add_ssl_algorithms();
714 Net::SSLeay::randomize();
715 Net::SSLeay::initialize initializes the SSL library at most once. You
717 can override the Net::SSLeay::initialize function if you desire some
718 other type of initialization behaviour by get_https and friends. You
719 can call Net::SSLeay::initialize from your own code if you desire this
720 conventional library initialization.
721 Convenience routines
723 To be used with Low level API
724 Net::SSLeay::randomize($rn_seed_file,$additional_seed);
726 Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
727 $cert = Net::SSLeay::dump_peer_certificate($ssl);
728 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
729 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
730 $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
732 $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
733 Net::SSLeay::ssl_write_CRLF($ssl, $message);
734 · randomize
736 seeds the openssl PRNG with "/dev/urandom" (see the top of
738 "SSLeay.pm" for how to change or configure this) and optionally
739 with user provided data. It is very important to properly seed your
740 random numbers, so do not forget to call this. The high level API
741 functions automatically call "randomize()" so it is not needed with
742 them. See also caveats.
743 · set_cert_and_key
745 takes two file names as arguments and sets the certificate and
747 private key to those. This can be used to set either server
748 certificates or client certificates.
749 · dump_peer_certificate
751 allows you to get a plaintext description of the certificate the
753 peer (usually the server) presented to us.
754 · ssl_read_all
756 see ssl_write_all (below)
758 · ssl_write_all
760 "ssl_read_all()" and "ssl_write_all()" provide true blocking
762 semantics for these operations (see limitation, below, for
763 explanation). These are much preferred to the low level API
764 equivalents (which implement BSD blocking semantics). The message
765 argument to "ssl_write_all()" can be a reference. This is helpful
766 to avoid unnecessary copying when writing something big, e.g:
767 $data = 'A' x 1000000000;
769 Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
770 · ssl_read_CRLF
772 uses "ssl_read_all()" to read in a line terminated with a carriage
774 return followed by a linefeed (CRLF). The CRLF is included in the
775 returned scalar.
776 · ssl_read_until
778 uses "ssl_read_all()" to read from the SSL input stream until it
780 encounters a programmer specified delimiter. If the delimiter is
781 undefined, $/ is used. If $/ is undefined, "\n" is used. One can
782 optionally set a maximum length of bytes to read from the SSL input
783 stream.
784 · ssl_write_CRLF
786 writes $message and appends CRLF to the SSL output stream.
788 Initialization
790 In order to use the low level API you should start your programs with
791 the following incantation:
792 use Net::SSLeay qw(die_now die_if_ssl_error);
794 Net::SSLeay::load_error_strings();
795 Net::SSLeay::SSLeay_add_ssl_algorithms(); # Important!
796 Net::SSLeay::ENGINE_load_builtin_engines(); # If you want built-in engines
797 Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
798 Net::SSLeay::randomize();
799 Error handling functions
801 I can not emphasize the need to check for error enough. Use these
802 functions even in the most simple programs, they will reduce debugging
803 time greatly. Do not ask questions on the mailing list without having
804 first sprinkled these in your code.
805 · die_now
807 · die_if_ssl_error
809 "die_now()" and "die_if_ssl_error()" are used to conveniently print
811 the SSLeay error stack when something goes wrong:
812 Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
814 Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
817 · print_errs
819 You can also use "Net::SSLeay::print_errs()" to dump the error
821 stack without exiting the program. As can be seen, your code
822 becomes much more readable if you import the error reporting
823 functions into your main name space.
824 Sockets
826 Perl uses file handles for all I/O. While SSLeay has a quite flexible
827 BIO mechanism and perl has an evolved PerlIO mechanism, this module
828 still sticks to using file descriptors. Thus to attach SSLeay to a
829 socket you should use "fileno()" to extract the underlying file
830 descriptor:
831 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
833 You should also set $| to 1 to eliminate STDIO buffering so you do not
835 get confused if you use perl I/O functions to manipulate your socket
836 handle.
837 If you need to select(2) on the socket, go right ahead, but be warned
839 that OpenSSL does some internal buffering so SSL_read does not always
840 return data even if the socket selected for reading (just keep on
841 selecting and trying to read). "Net::SSLeay" is no different from the C
842 language OpenSSL in this respect.
843 Callbacks
845 You can establish a per-context verify callback function something like
846 this:
847 sub verify {
849 my ($ok, $x509_store_ctx) = @_;
850 print "Verifying certificate...\n";
851 ...
852 return $ok;
853 }
854 It is used like this:
856 Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
858 Per-context callbacks for decrypting private keys are implemented.
860 Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
862 Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
863 Net::SSLeay::FILETYPE_PEM)
864 or die "Error reading private key";
865 Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
866 If Hello Extensions are supported by your OpenSSL, a session secret
868 callback can be set up to be called when a session secret is set by
869 openssl.
870 Establish it like this:
872 Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb,
873 $somedata);
874 It will be called like this:
876 sub session_secret_cb
878 {
879 my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
880 }
881 No other callbacks are implemented. You do not need to use any callback
883 for simple (i.e. normal) cases where the SSLeay built-in verify
884 mechanism satisfies your needs.
885 It is required to reset these callbacks to undef immediately after use
887 to prevent memory leaks, thread safety problems and crashes on exit
888 that can occur if different threads set different callbacks.
889 If you want to use callback stuff, see examples/callback.pl! It's the
891 only one I am able to make work reliably.
892 Low level API
894 In addition to the high level functions outlined above, this module
895 contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
896 API.
897 See the "*.h" headers from OpenSSL C distribution for a list of low
899 level SSLeay functions to call (check SSLeay.xs to see if some function
900 has been implemented). The module strips the initial "SSL_" off of the
901 SSLeay names. Generally you should use "Net::SSLeay::" in its place.
902 Note that some functions are prefixed with "P_" - these are very close
904 to the original API however contain some kind of a wrapper making its
905 interface more perl friendly.
906 For example:
908 In C:
910 #include <ssl.h>
912 err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
914 &your_call_back_here);
915 In Perl:
917 use Net::SSLeay;
919 $err = Net::SSLeay::set_verify ($ssl,
921 Net::SSLeay::VERIFY_CLIENT_ONCE,
922 \&your_call_back_here);
923 If the function does not start with "SSL_" you should use the full
925 function name, e.g.:
926 $err = Net::SSLeay::ERR_get_error;
928 The following new functions behave in perlish way:
930 $got = Net::SSLeay::read($ssl);
932 # Performs SSL_read, but returns $got
933 # resized according to data received.
934 # Returns undef on failure.
935 Net::SSLeay::write($ssl, $foo) || die;
937 # Performs SSL_write, but automatically
938 # figures out the size of $foo
939 Low level API: Version related functions
941 · SSLeay
943 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
945 Gives version number (numeric) of underlaying openssl library.
947 my $ver_number = Net::SSLeay::SSLeay();
949 # returns: the number identifying the openssl release
950 #
951 # 0x00903100 => openssl-0.9.3
952 # 0x00904100 => openssl-0.9.4
953 # 0x00905100 => openssl-0.9.5
954 # 0x0090600f => openssl-0.9.6
955 # 0x0090601f => openssl-0.9.6a
956 # 0x0090602f => openssl-0.9.6b
957 # ...
958 # 0x009060df => openssl-0.9.6m
959 # 0x0090700f => openssl-0.9.7
960 # 0x0090701f => openssl-0.9.7a
961 # 0x0090702f => openssl-0.9.7b
962 # ...
963 # 0x009070df => openssl-0.9.7m
964 # 0x0090800f => openssl-0.9.8
965 # 0x0090801f => openssl-0.9.8a
966 # 0x0090802f => openssl-0.9.8b
967 # ...
968 # 0x0090814f => openssl-0.9.8t
969 # 0x1000000f => openssl-1.0.0
970 # 0x1000004f => openssl-1.0.0d
971 # 0x1000007f => openssl-1.0.0g
972 You can use it like this:
974 if (Net::SSLeay::SSLeay() < 0x0090800f) {
976 die "you need openssl-0.9.8 or higher";
977 }
978 · SSLeay_version
980 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
982 Gives version number (string) of underlaying openssl library.
984 my $ver_string = Net::SSLeay::SSLeay_version($type);
986 # $type
987 # SSLEAY_VERSION - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
988 # SSLEAY_CFLAGS - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
989 # SSLEAY_BUILT_ON - e.g. 'built on: Fri May 6 00:00:46 GMT 2011'
990 # SSLEAY_PLATFORM - e.g. 'platform: mingw'
991 # SSLEAY_DIR - e.g. 'OPENSSLDIR: "z:/...."'
992 #
993 # returns: string
994 Net::SSLeay::SSLeay_version();
996 #is equivalent to
997 Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
998 Check openssl doc
1000 <https://www.openssl.org/docs/man1.0.2/crypto/SSLeay_version.html>
1001 · OpenSSL_version_num
1003 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1005 requires at least OpenSSL 1.1.0
1006 Gives version number (numeric) of underlaying openssl library. See
1008 "SSLeay" for interpreting the result.
1009 my $ver_number = Net::SSLeay::OpenSSL_version_num();
1011 # returns: the number identifying the openssl release
1012 · OpenSSL_version
1014 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1016 requires at least OpenSSL 1.1.0
1017 Gives version number (string) of underlaying openssl library.
1019 my $ver_string = Net::SSLeay::OpenSSL_version($t);
1021 # $t
1022 # OPENSSL_VERSION - e.g. 'OpenSSL 1.1.0g 2 Nov 2017'
1023 # OPENSSL_CFLAGS - e.g. 'compiler: cc -DDSO_DLFCN -DHAVE_DLFCN_H .....'
1024 # OPENSSL_BUILT_ON - e.g. 'built on: reproducible build, date unspecified'
1025 # OPENSSL_PLATFORM - e.g. 'platform: darwin64-x86_64-cc'
1026 # OPENSSL_DIR - e.g. 'OPENSSLDIR: "/opt/openssl-1.1.0g"'
1027 # OPENSSL_ENGINES_DIR - e.g. 'ENGINESDIR: "/opt/openssl-1.1.0g/lib/engines-1.1"'
1028 #
1029 # returns: string
1030 Net::SSLeay::OpenSSL_version();
1032 #is equivalent to
1033 Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1034 Check openssl doc
1036 <https://www.openssl.org/docs/crypto/OpenSSL_version.html>
1037 Low level API: Initialization related functions
1039 · library_init
1041 Initialize SSL library by registering algorithms.
1043 my $rv = Net::SSLeay::library_init();
1045 Check openssl doc
1047 <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1048 While the original function from OpenSSL always returns 1,
1050 Net::SSLeay adds a wrapper around it to make sure that the OpenSSL
1051 function is only called once. Thus the function will return 1 if
1052 initialization was done and 0 if not, i.e. if initialization was
1053 done already before.
1054 · add_ssl_algorithms
1056 The alias for "library_init"
1058 Net::SSLeay::add_ssl_algorithms();
1060 · OpenSSL_add_ssl_algorithms
1062 The alias for "library_init"
1064 Net::SSLeay::OpenSSL_add_ssl_algorithms();
1066 · SSLeay_add_ssl_algorithms
1068 The alias for "library_init"
1070 Net::SSLeay::SSLeay_add_ssl_algorithms();
1072 · load_error_strings
1074 Registers the error strings for all libcrypto + libssl related
1076 functions.
1077 Net::SSLeay::load_error_strings();
1079 #
1080 # returns: no return value
1081 Check openssl doc
1083 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1084 · ERR_load_crypto_strings
1086 Registers the error strings for all libcrypto functions. No need to
1088 call this function if you have already called "load_error_strings".
1089 Net::SSLeay::ERR_load_crypto_strings();
1091 #
1092 # returns: no return value
1093 Check openssl doc
1095 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1096 · ERR_load_RAND_strings
1098 Registers the error strings for RAND related functions. No need to
1100 call this function if you have already called "load_error_strings".
1101 Net::SSLeay::ERR_load_RAND_strings();
1103 #
1104 # returns: no return value
1105 · ERR_load_SSL_strings
1107 Registers the error strings for SSL related functions. No need to
1109 call this function if you have already called "load_error_strings".
1110 Net::SSLeay::ERR_load_SSL_strings();
1112 #
1113 # returns: no return value
1114 · OpenSSL_add_all_algorithms
1116 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1118 Add algorithms to internal table.
1120 Net::SSLeay::OpenSSL_add_all_algorithms();
1122 #
1123 # returns: no return value
1124 Check openssl doc
1126 <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1127 · OPENSSL_add_all_algorithms_conf
1129 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1131 Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1133 config file
1134 Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1136 #
1137 # returns: no return value
1138 · OPENSSL_add_all_algorithms_noconf
1140 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1142 Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1144 config file
1145 Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1147 #
1148 # returns: no return value
1149 Low level API: ERR_* and SSL_alert_* related functions
1151 NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1153 from their names.
1154 · ERR_clear_error
1156 Clear the error queue.
1158 Net::SSLeay::ERR_clear_error();
1160 #
1161 # returns: no return value
1162 Check openssl doc
1164 <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1165 · ERR_error_string
1167 Generates a human-readable string representing the error code
1169 $error.
1170 my $rv = Net::SSLeay::ERR_error_string($error);
1172 # $error - (unsigned integer) error code
1173 #
1174 # returns: string
1175 Check openssl doc
1177 <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1178 · ERR_get_error
1180 Returns the earliest error code from the thread's error queue and
1182 removes the entry. This function can be called repeatedly until
1183 there are no more error codes to return.
1184 my $rv = Net::SSLeay::ERR_get_error();
1186 #
1187 # returns: (unsigned integer) error code
1188 Check openssl doc
1190 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1191 · ERR_peek_error
1193 Returns the earliest error code from the thread's error queue
1195 without modifying it.
1196 my $rv = Net::SSLeay::ERR_peek_error();
1198 #
1199 # returns: (unsigned integer) error code
1200 Check openssl doc
1202 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1203 · ERR_put_error
1205 Adds an error code to the thread's error queue. It signals that the
1207 error of $reason code reason occurred in function $func of library
1208 $lib, in line number $line of $file.
1209 Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
1211 # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
1212 # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
1213 # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
1214 # $file - (string) file name
1215 # $line - (integer) line number in $file
1216 #
1217 # returns: no return value
1218 Check openssl doc
1220 <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
1221 <http://www.openssl.org/docs/crypto/err.html>
1222 · alert_desc_string
1224 Returns a two letter string as a short form describing the reason
1226 of the alert specified by value.
1227 my $rv = Net::SSLeay::alert_desc_string($value);
1229 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1230 #
1231 # returns: description string (2 letters)
1232 Check openssl doc
1234 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1235 · alert_desc_string_long
1237 Returns a string describing the reason of the alert specified by
1239 value.
1240 my $rv = Net::SSLeay::alert_desc_string_long($value);
1242 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1243 #
1244 # returns: description string
1245 Check openssl doc
1247 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1248 · alert_type_string
1250 Returns a one letter string indicating the type of the alert
1252 specified by value.
1253 my $rv = Net::SSLeay::alert_type_string($value);
1255 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1256 #
1257 # returns: string (1 letter)
1258 Check openssl doc
1260 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1261 · alert_type_string_long
1263 Returns a string indicating the type of the alert specified by
1265 value.
1266 my $rv = Net::SSLeay::alert_type_string_long($value);
1268 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1269 #
1270 # returns: string
1271 Check openssl doc
1273 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1274 Low level API: SSL_METHOD_* related functions
1276 · SSLv23_method, SSLv23_server_method and SSLv23_client_method
1278 COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1280 Returns SSL_METHOD structure corresponding to general-purpose
1282 version-flexible TLS method, the return value can be later used as
1283 a param of "CTX_new_with_method".
1284 NOTE: Consider using TLS_method, TLS_server_method or
1286 TLS_client_method with new code.
1287 my $rv = Net::SSLeay::SSLv2_method();
1289 #
1290 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1291 · SSLv2_method
1293 Returns SSL_METHOD structure corresponding to SSLv2 method, the
1295 return value can be later used as a param of "CTX_new_with_method".
1296 Only available where supported by the underlying openssl.
1297 my $rv = Net::SSLeay::SSLv2_method();
1299 #
1300 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1301 · SSLv3_method
1303 Returns SSL_METHOD structure corresponding to SSLv3 method, the
1305 return value can be later used as a param of "CTX_new_with_method".
1306 my $rv = Net::SSLeay::SSLv3_method();
1308 #
1309 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1310 Check openssl doc
1312 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1313 · TLSv1_method, TLSv1_server_method and TLSv1_client_method
1315 COMPATIBILITY: Server and client methods not available in
1317 Net-SSLeay-1.82 and before.
1318 Returns SSL_METHOD structure corresponding to TLSv1 method, the
1320 return value can be later used as a param of "CTX_new_with_method".
1321 my $rv = Net::SSLeay::TLSv1_method();
1323 #
1324 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1325 Check openssl doc
1327 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1328 · TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1330 COMPATIBILITY: Server and client methods not available in
1332 Net-SSLeay-1.82 and before.
1333 Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1335 return value can be later used as a param of "CTX_new_with_method".
1336 Only available where supported by the underlying openssl.
1337 my $rv = Net::SSLeay::TLSv1_1_method();
1339 #
1340 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1341 Check openssl doc
1343 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1344 · TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1346 COMPATIBILITY: Server and client methods not available in
1348 Net-SSLeay-1.82 and before.
1349 Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1351 return value can be later used as a param of "CTX_new_with_method".
1352 Only available where supported by the underlying openssl.
1353 my $rv = Net::SSLeay::TLSv1_2_method();
1355 #
1356 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1357 Check openssl doc
1359 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1360 · TLS_method, TLS_server_method and TLS_client_method
1362 COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1364 Returns SSL_METHOD structure corresponding to general-purpose
1366 version-flexible TLS method, the return value can be later used as
1367 a param of "CTX_new_with_method". Only available where supported by
1368 the underlying openssl.
1369 my $rv = Net::SSLeay::TLS_method();
1371 #
1372 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1373 Check openssl doc
1375 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1376 Low level API: ENGINE_* related functions
1378 · ENGINE_load_builtin_engines
1380 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1382 loading support.
1383 Load all bundled ENGINEs into memory and make them visible.
1385 Net::SSLeay::ENGINE_load_builtin_engines();
1387 #
1388 # returns: no return value
1389 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1391 · ENGINE_register_all_complete
1393 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1395 loading support.
1396 Register all loaded ENGINEs for every algorithm they collectively
1398 implement.
1399 Net::SSLeay::ENGINE_register_all_complete();
1401 #
1402 # returns: no return value
1403 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1405 · ENGINE_set_default
1407 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1409 loading support.
1410 Set default engine to $e + set its flags to $flags.
1412 my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1414 # $e - value corresponding to openssl's ENGINE structure
1415 # $flags - (integer) engine flags
1416 # flags value can be made by bitwise "OR"ing:
1417 # 0x0001 - ENGINE_METHOD_RSA
1418 # 0x0002 - ENGINE_METHOD_DSA
1419 # 0x0004 - ENGINE_METHOD_DH
1420 # 0x0008 - ENGINE_METHOD_RAND
1421 # 0x0010 - ENGINE_METHOD_ECDH
1422 # 0x0020 - ENGINE_METHOD_ECDSA
1423 # 0x0040 - ENGINE_METHOD_CIPHERS
1424 # 0x0080 - ENGINE_METHOD_DIGESTS
1425 # 0x0100 - ENGINE_METHOD_STORE
1426 # 0x0200 - ENGINE_METHOD_PKEY_METHS
1427 # 0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1428 # Obvious all-or-nothing cases:
1429 # 0xFFFF - ENGINE_METHOD_ALL
1430 # 0x0000 - ENGINE_METHOD_NONE
1431 #
1432 # returns: 1 on success, 0 on failure
1433 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1435 · ENGINE_by_id
1437 Get ENGINE by its identification $id.
1439 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1441 loading support.
1442 my $rv = Net::SSLeay::ENGINE_by_id($id);
1444 # $id - (string) engine identification e.g. "dynamic"
1445 #
1446 # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1447 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1449 Low level API: EVP_PKEY_* related functions
1451 · EVP_PKEY_copy_parameters
1453 Copies the parameters from key $from to key $to.
1455 my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1457 # $to - value corresponding to openssl's EVP_PKEY structure
1458 # $from - value corresponding to openssl's EVP_PKEY structure
1459 #
1460 # returns: 1 on success, 0 on failure
1461 Check openssl doc
1463 <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1464 · EVP_PKEY_new
1466 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1468 Creates a new EVP_PKEY structure.
1470 my $rv = Net::SSLeay::EVP_PKEY_new();
1472 #
1473 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1474 Check openssl doc
1476 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1477 · EVP_PKEY_free
1479 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1481 Free an allocated EVP_PKEY structure.
1483 Net::SSLeay::EVP_PKEY_free($pkey);
1485 # $pkey - value corresponding to openssl's EVP_PKEY structure
1486 #
1487 # returns: no return value
1488 Check openssl doc
1490 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1491 · EVP_PKEY_assign_RSA
1493 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1495 Set the key referenced by $pkey to $key
1497 NOTE: No reference counter will be increased, i.e. $key will be
1499 freed if $pkey is freed.
1500 my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1502 # $pkey - value corresponding to openssl's EVP_PKEY structure
1503 # $key - value corresponding to openssl's RSA structure
1504 #
1505 # returns: 1 on success, 0 on failure
1506 Check openssl doc
1508 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1509 · EVP_PKEY_assign_EC_KEY
1511 COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1513 Set the key referenced by $pkey to $key
1515 NOTE: No reference counter will be increased, i.e. $key will be
1517 freed if $pkey is freed.
1518 my $rv = Net::SSLeay::EVP_PKEY_assign_EC_KEY($pkey, $key);
1520 # $pkey - value corresponding to openssl's EVP_PKEY structure
1521 # $key - value corresponding to openssl's EC_KEY structure
1522 #
1523 # returns: 1 on success, 0 on failure
1524 Check openssl doc
1526 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1527 · EVP_PKEY_bits
1529 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1531 Returns the size of the key $pkey in bits.
1533 my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1535 # $pkey - value corresponding to openssl's EVP_PKEY structure
1536 #
1537 # returns: size in bits
1538 · EVP_PKEY_size
1540 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1542 Returns the maximum size of a signature in bytes. The actual
1544 signature may be smaller.
1545 my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1547 # $pkey - value corresponding to openssl's EVP_PKEY structure
1548 #
1549 # returns: the maximum size in bytes
1550 Check openssl doc
1552 <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1553 · EVP_PKEY_id
1555 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1557 requires at least openssl-1.0.0
1558 Returns $pkey type (integer value of corresponding NID).
1560 my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1562 # $pkey - value corresponding to openssl's EVP_PKEY structure
1563 #
1564 # returns: (integer) key type
1565 Example:
1567 my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1569 my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1570 print Net::SSLeay::OBJ_nid2sn($type); #prints e.g. 'rsaEncryption'
1571 Low level API: PEM_* related functions
1573 Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1575 · PEM_read_bio_X509
1577 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1579 Loads PEM formatted X509 certificate via given BIO structure.
1581 my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1583 # $bio - value corresponding to openssl's BIO structure
1584 #
1585 # returns: value corresponding to openssl's X509 structure (0 on failure)
1586 Example:
1588 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1590 my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1591 Net::SSLeay::BIO_free($bio);
1592 · PEM_read_bio_X509_REQ
1594 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1596 Loads PEM formatted X509_REQ object via given BIO structure.
1598 my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1600 # $bio - value corresponding to openssl's BIO structure
1601 #
1602 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1603 Example:
1605 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1607 my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1608 Net::SSLeay::BIO_free($bio);
1609 · PEM_read_bio_DHparams
1611 Reads DH structure from BIO.
1613 my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1615 # $bio - value corresponding to openssl's BIO structure
1616 #
1617 # returns: value corresponding to openssl's DH structure (0 on failure)
1618 · PEM_read_bio_X509_CRL
1620 Reads X509_CRL structure from BIO.
1622 my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1624 # $bio - value corresponding to openssl's BIO structure
1625 #
1626 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1627 · PEM_read_bio_PrivateKey
1629 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1631 Loads PEM formatted private key via given BIO structure.
1633 my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1635 # $bio - value corresponding to openssl's BIO structure
1636 # $cb - reference to perl callback function
1637 # $data - data that will be passed to callback function (see examples below)
1638 #
1639 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1640 Example:
1642 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1644 my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1645 Net::SSLeay::BIO_free($bio);
1646 To use password you have the following options:
1648 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1650 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1651 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1652 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, ""); # use empty password
1653 Callback function signature:
1655 sub callback_func {
1657 my ($max_passwd_size, $rwflag, $data) = @_;
1658 # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1659 # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1660 # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1661 return "secret";
1663 }
1664 · PEM_X509_INFO_read_bio
1666 Reads a BIO containing a PEM formatted file into a
1668 STACK_OF(X509_INFO) structure.
1669 my $rv = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1671 # $bio - value corresponding to openssl's BIO structure
1672 #
1673 # returns: value corresponding to openssl's STACK_OF(X509_INFO) structure.
1674 Example:
1676 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1678 my $sk_x509_info = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1679 Net::SSLeay::BIO_free($bio);
1680 · PEM_get_string_X509
1682 NOTE: Does not exactly correspond to any low level API function
1684 Converts/exports X509 certificate to string (PEM format).
1686 Net::SSLeay::PEM_get_string_X509($x509);
1688 # $x509 - value corresponding to openssl's X509 structure
1689 #
1690 # returns: string with $x509 in PEM format
1691 · PEM_get_string_PrivateKey
1693 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1695 Converts public key $pk into PEM formatted string (optionally
1697 protected with password).
1698 my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1700 # $pk - value corresponding to openssl's EVP_PKEY structure
1701 # $passwd - [optional] (string) password to use for key encryption
1702 # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1703 #
1704 # returns: PEM formatted string
1705 Examples:
1707 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1709 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1710 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1711 · PEM_get_string_X509_CRL
1713 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1715 Converts X509_CRL object $x509_crl into PEM formatted string.
1717 Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1719 # $x509_crl - value corresponding to openssl's X509_CRL structure
1720 #
1721 # returns: no return value
1722 · PEM_get_string_X509_REQ
1724 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1726 Converts X509_REQ object $x509_crl into PEM formatted string.
1728 Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1730 # $x509_req - value corresponding to openssl's X509_REQ structure
1731 #
1732 # returns: no return value
1733 Low level API: d2i_* (DER format) related functions
1735 · d2i_X509_bio
1737 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1739 Loads DER formatted X509 certificate via given BIO structure.
1741 my $rv = Net::SSLeay::d2i_X509_bio($bp);
1743 # $bp - value corresponding to openssl's BIO structure
1744 #
1745 # returns: value corresponding to openssl's X509 structure (0 on failure)
1746 Example:
1748 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1750 my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1751 Net::SSLeay::BIO_free($bio);
1752 Check openssl doc
1754 <http://www.openssl.org/docs/crypto/d2i_X509.html>
1755 · d2i_X509_CRL_bio
1757 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1759 Loads DER formatted X509_CRL object via given BIO structure.
1761 my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1763 # $bp - value corresponding to openssl's BIO structure
1764 #
1765 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1766 Example:
1768 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1770 my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1771 Net::SSLeay::BIO_free($bio);
1772 · d2i_X509_REQ_bio
1774 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1776 Loads DER formatted X509_REQ object via given BIO structure.
1778 my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1780 # $bp - value corresponding to openssl's BIO structure
1781 #
1782 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1783 Example:
1785 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1787 my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1788 Net::SSLeay::BIO_free($bio);
1789 Low level API: PKCS12 related functions
1791 · P_PKCS12_load_file
1793 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1795 Loads X509 certificate + private key + certificates of CA chain (if
1797 present in PKCS12 file).
1798 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1800 # $filename - name of PKCS12 file
1801 # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1802 # $password - [optional] password for private key
1803 #
1804 # returns: triplet ($privkey, $cert, @cachain)
1805 # $privkey - value corresponding to openssl's EVP_PKEY structure
1806 # $cert - value corresponding to openssl's X509 structure
1807 # @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1808 IMPORTANT NOTE: after you do the job you need to call X509_free()
1810 on $privkey + all members of @cachain and EVP_PKEY_free() on
1811 $privkey.
1812 Examples:
1814 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1816 #or
1817 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1818 #or
1819 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1820 #or
1821 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1822 #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1824 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1825 NOTE With some combinations of Windows, perl, compiler and compiler
1827 options, you may see a runtime error "no OPENSSL_Applink", when
1828 calling Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more
1829 details.
1830 Low level API: SESSION_* related functions
1832 · d2i_SSL_SESSION
1834 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1836 Transforms the binary ASN1 representation string of an SSL/TLS
1838 session into an SSL_SESSION object.
1839 my $ses = Net::SSLeay::d2i_SSL_SESSION($data);
1841 # $data - the session as ASN1 representation string
1842 #
1843 # returns: $ses - the new SSL_SESSION
1844 Check openssl doc
1846 <https://www.openssl.org/docs/ssl/i2d_SSL_SESSION.html>
1847 · i2d_SSL_SESSION
1849 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1851 Transforms the SSL_SESSION object in into the ASN1 representation
1853 and returns it as string.
1854 my $data = Net::SSLeay::i2d_SSL_SESSION($ses);
1856 # $ses - value corresponding to openssl's SSL_SESSION structure
1857 #
1858 # returns: $data - session as string
1859 Check openssl doc
1861 <https://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1862 · SESSION_new
1864 Creates a new SSL_SESSION structure.
1866 my $rv = Net::SSLeay::SESSION_new();
1868 #
1869 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
1870 · SESSION_free
1872 Free an allocated SSL_SESSION structure.
1874 Net::SSLeay::SESSION_free($ses);
1876 # $ses - value corresponding to openssl's SSL_SESSION structure
1877 #
1878 # returns: no return value
1879 Check openssl doc
1881 <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
1882 · SESSION_up_ref
1884 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1886 requires at least OpenSSL 1.1.0 or LibreSSL 2.7.0
1887 Increases the reference counter on a SSL_SESSION structure.
1889 Net::SSLeay::SESSION_up_ref($ses);
1891 # $ses - value corresponding to openssl's SSL_SESSION structure
1892 #
1893 # returns: 1 on success else 0
1894 Check openssl doc
1896 <https://www.openssl.org/docs/ssl/SSL_SESSION_up_ref.html>
1897 · SESSION_dup
1899 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1901 requires at least OpenSSL 1.1.1, not in LibreSSL
1902 Duplicates a SSL_SESSION structure.
1904 Net::SSLeay::SESSION_dup($ses);
1906 # $ses - value corresponding to openssl's SSL_SESSION structure
1907 #
1908 # returns: the duplicated session
1909 Check openssl doc
1911 <https://www.openssl.org/docs/ssl/SSL_SESSION_dup.html>
1912 · SESSION_is_resumable
1914 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1916 requires at least OpenSSL 1.1.1, not in LibreSSL
1917 Determine whether an SSL_SESSION object can be used for resumption.
1919 Net::SSLeay::SESSION_is_resumable($ses);
1921 # $ses - value corresponding to openssl's SSL_SESSION structure
1922 #
1923 # returns: (integer) 1 if it can or 0 if not
1924 Check openssl doc
1926 <https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html>
1927 · SESSION_cmp
1929 Compare two SSL_SESSION structures.
1931 my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
1933 # $sesa - value corresponding to openssl's SSL_SESSION structure
1934 # $sesb - value corresponding to openssl's SSL_SESSION structure
1935 #
1936 # returns: 0 if the two structures are the same
1937 NOTE: Not available in openssl 1.0 or later
1939 · SESSION_get_app_data
1941 Can be used to get application defined value/data.
1943 my $rv = Net::SSLeay::SESSION_get_app_data($ses);
1945 # $ses - value corresponding to openssl's SSL_SESSION structure
1946 #
1947 # returns: string/buffer/pointer ???
1948 · SESSION_set_app_data
1950 Can be used to set some application defined value/data.
1952 my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
1954 # $s - value corresponding to openssl's SSL_SESSION structure
1955 # $a - (string/buffer/pointer ???) data
1956 #
1957 # returns: ???
1958 · SESSION_get_ex_data
1960 Is used to retrieve the information for $idx from session $ses.
1962 my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
1964 # $ses - value corresponding to openssl's SSL_SESSION structure
1965 # $idx - (integer) index for application specific data
1966 #
1967 # returns: pointer to ???
1968 Check openssl doc
1970 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1971 · SESSION_set_ex_data
1973 Is used to store application data at arg for idx into the session
1975 object.
1976 my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
1978 # $ss - value corresponding to openssl's SSL_SESSION structure
1979 # $idx - (integer) ???
1980 # $data - (pointer) ???
1981 #
1982 # returns: 1 on success, 0 on failure
1983 Check openssl doc
1985 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1986 · SESSION_get_ex_new_index
1988 Is used to register a new index for application specific data.
1990 my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
1992 # $argl - (long) ???
1993 # $argp - (pointer) ???
1994 # $new_func - function pointer ??? (CRYPTO_EX_new *)
1995 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
1996 # $free_func - function pointer ??? (CRYPTO_EX_free *)
1997 #
1998 # returns: (integer) ???
1999 Check openssl doc
2001 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2002 · SESSION_get_master_key
2004 NOTE: Does not exactly correspond to any low level API function
2006 Returns 'master_key' value from SSL_SESSION structure $s
2008 Net::SSLeay::SESSION_get_master_key($s);
2010 # $s - value corresponding to openssl's SSL_SESSION structure
2011 #
2012 # returns: master key (binary data)
2013 · SESSION_set_master_key
2015 Sets 'master_key' value for SSL_SESSION structure $s
2017 Net::SSLeay::SESSION_set_master_key($s, $key);
2019 # $s - value corresponding to openssl's SSL_SESSION structure
2020 # $key - master key (binary data)
2021 #
2022 # returns: no return value
2023 Not available with OpenSSL 1.1 and later. Code that previously
2025 used
2026 SESSION_set_master_key must now set $secret in the
2027 session_secret
2028 callback set with SSL_set_session_secret_cb.
2029 · SESSION_get_time
2031 Returns the time at which the session s was established. The time
2033 is given in seconds since 1.1.1970.
2034 my $rv = Net::SSLeay::SESSION_get_time($s);
2036 # $s - value corresponding to openssl's SSL_SESSION structure
2037 #
2038 # returns: timestamp (seconds since 1.1.1970)
2039 Check openssl doc
2041 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2042 · get_time
2044 Technically the same functionality as "SESSION_get_time".
2046 my $rv = Net::SSLeay::get_time($s);
2048 · SESSION_get_timeout
2050 Returns the timeout value set for session $s in seconds.
2052 my $rv = Net::SSLeay::SESSION_get_timeout($s);
2054 # $s - value corresponding to openssl's SSL_SESSION structure
2055 #
2056 # returns: timeout (in seconds)
2057 Check openssl doc
2059 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2060 · get_timeout
2062 Technically the same functionality as "SESSION_get_timeout".
2064 my $rv = Net::SSLeay::get_timeout($s);
2066 · SESSION_print
2068 NOTE: Does not exactly correspond to any low level API function
2070 Prints session details (e.g. protocol version, cipher, session-id
2072 ...) to BIO.
2073 my $rv = Net::SSLeay::SESSION_print($fp, $ses);
2075 # $fp - value corresponding to openssl's BIO structure
2076 # $ses - value corresponding to openssl's SSL_SESSION structure
2077 #
2078 # returns: 1 on success, 0 on failure
2079 You have to use necessary BIO functions like this:
2081 # let us have $ssl corresponding to openssl's SSL structure
2083 my $ses = Net::SSLeay::get_session($ssl);
2084 my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
2085 Net::SSLeay::SESSION_print($bio, $ses);
2086 print Net::SSLeay::BIO_read($bio);
2087 · SESSION_print_fp
2089 Prints session details (e.g. protocol version, cipher, session-id
2091 ...) to file handle.
2092 my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
2094 # $fp - perl file handle
2095 # $ses - value corresponding to openssl's SSL_SESSION structure
2096 #
2097 # returns: 1 on success, 0 on failure
2098 Example:
2100 # let us have $ssl corresponding to openssl's SSL structure
2102 my $ses = Net::SSLeay::get_session($ssl);
2103 open my $fh, ">", "output.txt";
2104 Net::SSLeay::SESSION_print_fp($fh,$ses);
2105 · SESSION_set_time
2107 Replaces the creation time of the session s with the chosen value
2109 $t (seconds since 1.1.1970).
2110 my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
2112 # $ses - value corresponding to openssl's SSL_SESSION structure
2113 # $t - time value
2114 #
2115 # returns: 1 on success
2116 Check openssl doc
2118 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2119 · set_time
2121 Technically the same functionality as "SESSION_set_time".
2123 my $rv = Net::SSLeay::set_time($ses, $t);
2125 · SESSION_set_timeout
2127 Sets the timeout value for session s in seconds to $t.
2129 my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
2131 # $s - value corresponding to openssl's SSL_SESSION structure
2132 # $t - timeout (in seconds)
2133 #
2134 # returns: 1 on success
2135 Check openssl doc
2137 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2138 · set_timeout
2140 Technically the same functionality as "SESSION_set_timeout".
2142 my $rv = Net::SSLeay::set_timeout($ses, $t);
2144 Low level API: SSL_CTX_* related functions
2146 NOTE: Please note that the function described in this chapter have
2148 "SSL_" part stripped from their original openssl names.
2149 · CTX_add_client_CA
2151 Adds the CA name extracted from $cacert to the list of CAs sent to
2153 the client when requesting a client certificate for $ctx.
2154 my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
2156 # $ctx - value corresponding to openssl's SSL_CTX structure
2157 # $cacert - value corresponding to openssl's X509 structure
2158 #
2159 # returns: 1 on success, 0 on failure
2160 Check openssl doc
2162 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2163 · CTX_add_extra_chain_cert
2165 Adds the certificate $x509 to the certificate chain presented
2167 together with the certificate. Several certificates can be added
2168 one after the other.
2169 my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
2171 # $ctx - value corresponding to openssl's SSL_CTX structure
2172 # $x509 - value corresponding to openssl's X509 structure
2173 #
2174 # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
2175 Check openssl doc
2177 <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2178 · CTX_add_session
2180 Adds the session $ses to the context $ctx.
2182 my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
2184 # $ctx - value corresponding to openssl's SSL_CTX structure
2185 # $ses - value corresponding to openssl's SSL_SESSION structure
2186 #
2187 # returns: 1 on success, 0 on failure
2188 Check openssl doc
2190 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2191 · CTX_callback_ctrl
2193 ??? (more info needed)
2195 my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
2197 # $ctx - value corresponding to openssl's SSL_CTX structure
2198 # $cmd - (integer) command id
2199 # $fp - (function pointer) ???
2200 #
2201 # returns: ???
2202 Check openssl doc
2204 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2205 · CTX_check_private_key
2207 Checks the consistency of a private key with the corresponding
2209 certificate loaded into $ctx.
2210 my $rv = Net::SSLeay::CTX_check_private_key($ctx);
2212 # $ctx - value corresponding to openssl's SSL_CTX structure
2213 #
2214 # returns: 1 on success, otherwise check out the error stack to find out the reason
2215 Check openssl doc
2217 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2218 · CTX_ctrl
2220 Internal handling function for SSL_CTX objects.
2222 BEWARE: openssl doc says: This function should never be called
2224 directly!
2225 my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
2227 # $ctx - value corresponding to openssl's SSL_CTX structure
2228 # $cmd - (integer) command id
2229 # $larg - (integer) long ???
2230 # $parg - (string/pointer) ???
2231 #
2232 # returns: (long) result of given command ???
2233 #valid $cmd values
2235 1 - SSL_CTRL_NEED_TMP_RSA
2236 2 - SSL_CTRL_SET_TMP_RSA
2237 3 - SSL_CTRL_SET_TMP_DH
2238 4 - SSL_CTRL_SET_TMP_ECDH
2239 5 - SSL_CTRL_SET_TMP_RSA_CB
2240 6 - SSL_CTRL_SET_TMP_DH_CB
2241 7 - SSL_CTRL_SET_TMP_ECDH_CB
2242 8 - SSL_CTRL_GET_SESSION_REUSED
2243 9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
2244 10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
2245 11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
2246 12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
2247 13 - SSL_CTRL_GET_FLAGS
2248 14 - SSL_CTRL_EXTRA_CHAIN_CERT
2249 15 - SSL_CTRL_SET_MSG_CALLBACK
2250 16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
2251 17 - SSL_CTRL_SET_MTU
2252 20 - SSL_CTRL_SESS_NUMBER
2253 21 - SSL_CTRL_SESS_CONNECT
2254 22 - SSL_CTRL_SESS_CONNECT_GOOD
2255 23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
2256 24 - SSL_CTRL_SESS_ACCEPT
2257 25 - SSL_CTRL_SESS_ACCEPT_GOOD
2258 26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
2259 27 - SSL_CTRL_SESS_HIT
2260 28 - SSL_CTRL_SESS_CB_HIT
2261 29 - SSL_CTRL_SESS_MISSES
2262 30 - SSL_CTRL_SESS_TIMEOUTS
2263 31 - SSL_CTRL_SESS_CACHE_FULL
2264 32 - SSL_CTRL_OPTIONS
2265 33 - SSL_CTRL_MODE
2266 40 - SSL_CTRL_GET_READ_AHEAD
2267 41 - SSL_CTRL_SET_READ_AHEAD
2268 42 - SSL_CTRL_SET_SESS_CACHE_SIZE
2269 43 - SSL_CTRL_GET_SESS_CACHE_SIZE
2270 44 - SSL_CTRL_SET_SESS_CACHE_MODE
2271 45 - SSL_CTRL_GET_SESS_CACHE_MODE
2272 50 - SSL_CTRL_GET_MAX_CERT_LIST
2273 51 - SSL_CTRL_SET_MAX_CERT_LIST
2274 52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
2275 53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
2276 54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
2277 55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
2278 56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
2279 57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
2280 58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
2281 59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
2282 60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
2283 61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
2284 62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
2285 63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
2286 64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
2287 65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
2288 66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
2289 67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
2290 68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
2291 69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
2292 70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
2293 71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
2294 72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
2295 73 - DTLS_CTRL_GET_TIMEOUT
2296 74 - DTLS_CTRL_HANDLE_TIMEOUT
2297 75 - DTLS_CTRL_LISTEN
2298 76 - SSL_CTRL_GET_RI_SUPPORT
2299 77 - SSL_CTRL_CLEAR_OPTIONS
2300 78 - SSL_CTRL_CLEAR_MODE
2301 82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2303 83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2304 88 - SSL_CTRL_CHAIN
2306 89 - SSL_CTRL_CHAIN_CERT
2307 90 - SSL_CTRL_GET_CURVES
2309 91 - SSL_CTRL_SET_CURVES
2310 92 - SSL_CTRL_SET_CURVES_LIST
2311 93 - SSL_CTRL_GET_SHARED_CURVE
2312 94 - SSL_CTRL_SET_ECDH_AUTO
2313 97 - SSL_CTRL_SET_SIGALGS
2314 98 - SSL_CTRL_SET_SIGALGS_LIST
2315 99 - SSL_CTRL_CERT_FLAGS
2316 100 - SSL_CTRL_CLEAR_CERT_FLAGS
2317 101 - SSL_CTRL_SET_CLIENT_SIGALGS
2318 102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
2319 103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
2320 104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
2321 105 - SSL_CTRL_BUILD_CERT_CHAIN
2322 106 - SSL_CTRL_SET_VERIFY_CERT_STORE
2323 107 - SSL_CTRL_SET_CHAIN_CERT_STORE
2324 108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
2325 109 - SSL_CTRL_GET_SERVER_TMP_KEY
2326 110 - SSL_CTRL_GET_RAW_CIPHERLIST
2327 111 - SSL_CTRL_GET_EC_POINT_FORMATS
2328 112 - SSL_CTRL_GET_TLSA_RECORD
2329 113 - SSL_CTRL_SET_TLSA_RECORD
2330 114 - SSL_CTRL_PULL_TLSA_RECORD
2331 Check openssl doc
2333 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2334 · CTX_flush_sessions
2336 Causes a run through the session cache of $ctx to remove sessions
2338 expired at time $tm.
2339 Net::SSLeay::CTX_flush_sessions($ctx, $tm);
2341 # $ctx - value corresponding to openssl's SSL_CTX structure
2342 # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
2343 #
2344 # returns: no return value
2345 Check openssl doc
2347 <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2348 · CTX_free
2350 Free an allocated SSL_CTX object.
2352 Net::SSLeay::CTX_free($ctx);
2354 # $ctx - value corresponding to openssl's SSL_CTX structure
2355 #
2356 # returns: no return value
2357 Check openssl doc
2359 <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2360 · CTX_get_app_data
2362 Can be used to get application defined value/data.
2364 my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2366 # $ctx - value corresponding to openssl's SSL_CTX structure
2367 #
2368 # returns: string/buffer/pointer ???
2369 · CTX_set_app_data
2371 Can be used to set some application defined value/data.
2373 my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2375 # $ctx - value corresponding to openssl's SSL_CTX structure
2376 # $arg - (string/buffer/pointer ???) data
2377 #
2378 # returns: ???
2379 · CTX_get0_param
2381 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2383 requires at least OpenSSL 1.0.2
2384 Returns the current verification parameters.
2386 my $vpm = Net::SSLeay::CTX_get0_param($ctx);
2388 # $ctx - value corresponding to openssl's SSL_CTX structure
2389 #
2390 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
2391 Check openssl doc
2393 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2394 · CTX_get_cert_store
2396 Returns the current certificate verification storage.
2398 my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2400 # $ctx - value corresponding to openssl's SSL_CTX structure
2401 #
2402 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2403 Check openssl doc
2405 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2406 · CTX_get_client_CA_list
2408 Returns the list of client CAs explicitly set for $ctx using
2410 "CTX_set_client_CA_list".
2411 my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2413 # $ctx - value corresponding to openssl's SSL_CTX structure
2414 #
2415 # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2416 Check openssl doc
2418 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2419 · CTX_get_ex_data
2421 Is used to retrieve the information for index $idx from $ctx.
2423 my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2425 # $ssl - value corresponding to openssl's SSL_CTX structure
2426 # $idx - (integer) index for application specific data
2427 #
2428 # returns: pointer to ???
2429 Check openssl doc
2431 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2432 · CTX_get_ex_new_index
2434 Is used to register a new index for application specific data.
2436 my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2438 # $argl - (long) ???
2439 # $argp - (pointer) ???
2440 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2441 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2442 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2443 #
2444 # returns: (integer) ???
2445 Check openssl doc
2447 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2448 · CTX_get_mode
2450 Returns the mode set for ctx.
2452 my $rv = Net::SSLeay::CTX_get_mode($ctx);
2454 # $ctx - value corresponding to openssl's SSL_CTX structure
2455 #
2456 # returns: mode (bitmask)
2457 #to decode the return value (bitmask) use:
2459 0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2460 0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2461 0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2462 0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2463 0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2464 (note: some of the bits might not be supported by older openssl versions)
2465 Check openssl doc
2467 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2468 · CTX_set_mode
2470 Adds the mode set via bitmask in $mode to $ctx. Options already set
2472 before are not cleared.
2473 my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2475 # $ctx - value corresponding to openssl's SSL_CTX structure
2476 # $mode - mode bitmask
2477 #
2478 # returns: the new mode bitmask after adding $mode
2479 For bitmask details see "CTX_get_mode" (above).
2481 Check openssl doc
2483 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2484 · CTX_get_options
2486 Returns the options (bitmask) set for $ctx.
2488 my $rv = Net::SSLeay::CTX_get_options($ctx);
2490 # $ctx - value corresponding to openssl's SSL_CTX structure
2491 #
2492 # returns: options (bitmask)
2493 BEWARE: The available constants and their values in bitmask depend
2495 on the TLS library. For example, SSL_OP_NO_TLSv1_3 became available
2496 much later than SSL_OP_NO_COMPRESS which is already deprecated by
2497 some libraries. Also, some previously used option values have been
2498 recycled and are now used for newer options. See the list of
2499 constants in this document for options Net::SSLeay currently
2500 supports.
2501 You are strongly encouraged to check your TLS library if you need
2503 to use numeric values directly. The following is a sample of
2504 historic values. It may not be correct anymore.
2505 #to decode the return value (bitmask) use:
2507 0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2508 0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2509 0x00004000 corresponds to SSL_OP_NO_TICKET
2510 0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2511 0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2512 0x04000000 corresponds to SSL_OP_NO_TLSv1
2513 Check openssl doc
2515 <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2516 · CTX_set_options
2518 Adds the options set via bitmask in $options to ctx. Options
2520 already set before are not cleared.
2521 Net::SSLeay::CTX_set_options($ctx, $options);
2523 # $ctx - value corresponding to openssl's SSL_CTX structure
2524 # $options - options bitmask
2525 #
2526 # returns: the new options bitmask after adding $options
2527 For bitmask details see "CTX_get_options" (above).
2529 Check openssl doc
2531 <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2532 · CTX_get_quiet_shutdown
2534 Returns the 'quiet shutdown' setting of $ctx.
2536 my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2538 # $ctx - value corresponding to openssl's SSL_CTX structure
2539 #
2540 # returns: (integer) the current setting
2541 Check openssl doc
2543 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2544 · CTX_get_read_ahead
2546 my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2548 # $ctx - value corresponding to openssl's SSL_CTX structure
2549 #
2550 # returns: (integer) read_ahead value
2551 · CTX_get_session_cache_mode
2553 Returns the currently used cache mode (bitmask).
2555 my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2557 # $ctx - value corresponding to openssl's SSL_CTX structure
2558 #
2559 # returns: mode (bitmask)
2560 BEWARE: SESS_CACHE_OFF and other constants are not available in
2562 Net-SSLeay-1.82 and before. If the constants are not available,
2563 the following values have historically been correct. You are
2564 strongly encouraged to check your TLS library for the current
2565 values.
2566 #to decode the return value (bitmask) use:
2568 0x0000 corresponds to SSL_SESS_CACHE_OFF
2569 0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2570 0x0002 corresponds to SSL_SESS_CACHE_SERVER
2571 0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2572 0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2573 0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2574 (note: some of the bits might not be supported by older openssl versions)
2575 Check openssl doc
2577 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2578 · CTX_set_session_cache_mode
2580 Enables/disables session caching by setting the operational mode
2582 for $ctx to $mode.
2583 my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2585 # $ctx - value corresponding to openssl's SSL_CTX structure
2586 # $mode - mode (bitmask)
2587 #
2588 # returns: previously set cache mode
2589 For bitmask details see "CTX_get_session_cache_mode" (above).
2591 Check openssl doc
2593 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2594 · CTX_get_timeout
2596 Returns the currently set timeout value for $ctx.
2598 my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2600 # $ctx - value corresponding to openssl's SSL_CTX structure
2601 #
2602 # returns: timeout in seconds
2603 Check openssl doc
2605 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2606 · CTX_get_verify_depth
2608 Returns the verification depth limit currently set in $ctx. If no
2610 limit has been explicitly set, -1 is returned and the default value
2611 will be used.",
2612 my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2614 # $ctx - value corresponding to openssl's SSL_CTX structure
2615 #
2616 # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2617 Check openssl doc
2619 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2620 · CTX_get_verify_mode
2622 Returns the verification mode (bitmask) currently set in $ctx.
2624 my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2626 # $ctx - value corresponding to openssl's SSL_CTX structure
2627 #
2628 # returns: mode (bitmask)
2629 For bitmask details see "CTX_set_verify".
2631 Check openssl doc
2633 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_verify_mode.html>
2634 · CTX_set_verify
2636 Sets the verification flags for $ctx to be $mode and specifies the
2638 verify_callback function to be used.
2639 Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2641 # $ctx - value corresponding to openssl's SSL_CTX structure
2642 # $mode - mode (bitmask), see OpenSSL manual
2643 # $callback - [optional] reference to perl callback function
2644 #
2645 # returns: no return value
2646 Check openssl doc
2648 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html>
2649 · CTX_set_post_handshake_auth
2651 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2653 requires at least OpenSSL 1.1.1, not in LibreSSL
2654 Enable the Post-Handshake Authentication extension to be added to
2656 the ClientHello such that post-handshake authentication can be
2657 requested by the server.
2658 Net::SSLeay::CTX_set_posthandshake_auth($ctx, $val);
2660 # $ctx - value corresponding to openssl's SSL_CTX structure
2661 # $val - 0 then the extension is not sent, otherwise it is
2662 #
2663 # returns: no return value
2664 Check openssl doc
2666 https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth
2667 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth.html>
2668 · CTX_load_verify_locations
2670 Specifies the locations for $ctx, at which CA certificates for
2672 verification purposes are located. The certificates available via
2673 $CAfile and $CApath are trusted.
2674 my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2676 # $ctx - value corresponding to openssl's SSL_CTX structure
2677 # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2678 # $CApath - (string) directory containing CA certificates in PEM format (or '')
2679 #
2680 # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2681 Check openssl doc
2683 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2684 · CTX_need_tmp_RSA
2686 Return the result of
2688 "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2689 my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2691 # $ctx - value corresponding to openssl's SSL_CTX structure
2692 #
2693 # returns: result of SSL_CTRL_NEED_TMP_RSA command
2694 Not available with OpenSSL 1.1 and later.
2696 · CTX_new
2698 The same as "CTX_v23_new"
2700 my $rv = Net::SSLeay::CTX_new();
2702 #
2703 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2704 Check openssl doc
2706 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2707 Not available with OpenSSL 1.1 and later.
2709 · CTX_v2_new
2711 Creates a new SSL_CTX object - based on SSLv2_method() - as
2713 framework to establish TLS/SSL enabled connections.
2714 my $rv = Net::SSLeay::CTX_v2_new();
2716 #
2717 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2718 · CTX_v23_new
2720 Creates a new SSL_CTX object - based on SSLv23_method() - as
2722 framework to establish TLS/SSL enabled connections.
2723 my $rv = Net::SSLeay::CTX_v23_new();
2725 #
2726 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2727 · CTX_v3_new
2729 Creates a new SSL_CTX object - based on SSLv3_method() - as
2731 framework to establish TLS/SSL enabled connections.
2732 my $rv = Net::SSLeay::CTX_v3_new();
2734 #
2735 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2736 · CTX_tlsv1_new
2738 Creates a new SSL_CTX object - based on TLSv1_method() - as
2740 framework to establish TLS/SSL enabled connections.
2741 my $rv = Net::SSLeay::CTX_tlsv1_new();
2743 #
2744 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2745 · CTX_tlsv1_1_new
2747 Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2749 framework to establish TLS/SSL enabled connections. Only available
2750 where supported by the underlying openssl.
2751 my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2753 #
2754 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2755 · CTX_tlsv1_2_new
2757 Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2759 framework to establish TLS/SSL enabled connections. Only available
2760 where supported by the underlying openssl.
2761 my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2763 #
2764 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2765 · CTX_new_with_method
2767 Creates a new SSL_CTX object based on $meth method
2769 my $rv = Net::SSLeay::CTX_new_with_method($meth);
2771 # $meth - value corresponding to openssl's SSL_METHOD structure
2772 #
2773 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2774 #example
2776 my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2777 Check openssl doc
2779 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2780 · CTX_set_min_proto_version, CTX_set_max_proto_version,
2782 set_min_proto_version and set_max_proto_version,
2783 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2785 requires at least OpenSSL 1.1.0 or LibreSSL 2.6.0
2786 Set the minimum and maximum supported protocol for $ctx or $ssl.
2788 my $rv = Net::SSLeay::CTX_set_min_proto_version($ctx, $version)
2790 # $ctx - value corresponding to openssl's SSL_CTX structure
2791 # $version - (integer) constat version value or 0 for automatic lowest or highest value
2792 #
2793 # returns: 1 on success, 0 on failure
2794 #example: allow only TLS 1.2 for a SSL_CTX
2796 my $rv_min = Net::SSLeay::CTX_set_min_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2797 my $rv_max = Net::SSLeay::CTX_set_max_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2798 #example: allow only TLS 1.1 for a SSL
2800 my $rv_min = Net::SSLeay::set_min_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2801 my $rv_max = Net::SSLeay::set_max_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2802 Check openssl doc
2804 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2805 · CTX_get_min_proto_version, CTX_get_max_proto_version,
2807 get_min_proto_version and get_max_proto_version,
2808 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2810 requires at least OpenSSL 1.1.0g
2811 Get the minimum and maximum supported protocol for $ctx or $ssl.
2813 my $version = Net::SSLeay::CTX_get_min_proto_version($ctx)
2815 # $ctx - value corresponding to openssl's SSL_CTX structure
2816 #
2817 # returns: 0 automatic lowest or highest value, configured value otherwise
2818 Check openssl doc
2820 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2821 · CTX_remove_session
2823 Removes the session $ses from the context $ctx.
2825 my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2827 # $ctx - value corresponding to openssl's SSL_CTX structure
2828 # $ses - value corresponding to openssl's SSL_SESSION structure
2829 #
2830 # returns: 1 on success, 0 on failure
2831 Check openssl doc
2833 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2834 · CTX_sess_accept
2836 my $rv = Net::SSLeay::CTX_sess_accept($ctx);
2838 # $ctx - value corresponding to openssl's SSL_CTX structure
2839 #
2840 # returns: number of started SSL/TLS handshakes in server mode
2841 Check openssl doc
2843 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2844 · CTX_sess_accept_good
2846 my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
2848 # $ctx - value corresponding to openssl's SSL_CTX structure
2849 #
2850 # returns: number of successfully established SSL/TLS sessions in server mode
2851 Check openssl doc
2853 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2854 · CTX_sess_accept_renegotiate
2856 my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
2858 # $ctx - value corresponding to openssl's SSL_CTX structure
2859 #
2860 # returns: number of start renegotiations in server mode
2861 Check openssl doc
2863 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2864 · CTX_sess_cache_full
2866 my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
2868 # $ctx - value corresponding to openssl's SSL_CTX structure
2869 #
2870 # returns: number of sessions that were removed because the maximum session cache size was exceeded
2871 Check openssl doc
2873 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2874 · CTX_sess_cb_hits
2876 my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
2878 # $ctx - value corresponding to openssl's SSL_CTX structure
2879 #
2880 # returns: number of successfully retrieved sessions from the external session cache in server mode
2881 Check openssl doc
2883 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2884 · CTX_sess_connect
2886 my $rv = Net::SSLeay::CTX_sess_connect($ctx);
2888 # $ctx - value corresponding to openssl's SSL_CTX structure
2889 #
2890 # returns: number of started SSL/TLS handshakes in client mode
2891 Check openssl doc
2893 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2894 · CTX_sess_connect_good
2896 my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
2898 # $ctx - value corresponding to openssl's SSL_CTX structure
2899 #
2900 # returns: number of successfully established SSL/TLS sessions in client mode
2901 Check openssl doc
2903 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2904 · CTX_sess_connect_renegotiate
2906 my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
2908 # $ctx - value corresponding to openssl's SSL_CTX structure
2909 #
2910 # returns: number of start renegotiations in client mode
2911 Check openssl doc
2913 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2914 · CTX_sess_get_cache_size
2916 Returns the currently valid session cache size.
2918 my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
2920 # $ctx - value corresponding to openssl's SSL_CTX structure
2921 #
2922 # returns: current size
2923 Check openssl doc
2925 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2926 · CTX_sess_hits
2928 my $rv = Net::SSLeay::CTX_sess_hits($ctx);
2930 # $ctx - value corresponding to openssl's SSL_CTX structure
2931 #
2932 # returns: number of successfully reused sessions
2933 Check openssl doc
2935 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2936 · CTX_sess_misses
2938 my $rv = Net::SSLeay::CTX_sess_misses($ctx);
2940 # $ctx - value corresponding to openssl's SSL_CTX structure
2941 #
2942 # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
2943 Check openssl doc
2945 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2946 · CTX_sess_number
2948 my $rv = Net::SSLeay::CTX_sess_number($ctx);
2950 # $ctx - value corresponding to openssl's SSL_CTX structure
2951 #
2952 # returns: current number of sessions in the internal session cache
2953 Check openssl doc
2955 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2956 · CTX_sess_set_cache_size
2958 Sets the size of the internal session cache of context $ctx to
2960 $size.
2961 Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
2963 # $ctx - value corresponding to openssl's SSL_CTX structure
2964 # $size - cache size (0 = unlimited)
2965 #
2966 # returns: previously valid size
2967 Check openssl doc
2969 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2970 · CTX_sess_timeouts
2972 Returns the number of sessions proposed by clients and either found
2974 in the internal or external session cache in server mode, but that
2975 were invalid due to timeout. These sessions are not included in the
2976 SSL_CTX_sess_hits count.
2977 my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
2979 # $ctx - value corresponding to openssl's SSL_CTX structure
2980 #
2981 # returns: number of sessions
2982 Check openssl doc
2984 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2985 · CTX_sess_set_new_cb
2987 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
2989 Sets the callback function, which is automatically called whenever
2991 a new session was negotiated.
2992 Net::SSLeay::CTX_sess_set_new_cb($ctx, $func);
2994 # $ctx - value corresponding to openssl's SSL_CTX structure
2995 # $func - perl reference to callback function
2996 #
2997 # returns: no return value
2998 Check openssl doc
3000 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html>
3001 · CTX_sess_set_remove_cb
3003 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3005 Sets the callback function, which is automatically called whenever
3007 a session is removed by the SSL engine.
3008 Net::SSLeay::CTX_sess_set_remove_cb($ctx, $func);
3010 # $ctx - value corresponding to openssl's SSL_CTX structure
3011 # $func - perl reference to callback function
3012 #
3013 # returns: no return value
3014 Check openssl doc
3016 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_remove_cb.html>
3017 · CTX_sessions
3019 Returns a pointer to the lhash databases containing the internal
3021 session cache for ctx.
3022 my $rv = Net::SSLeay::CTX_sessions($ctx);
3024 # $ctx - value corresponding to openssl's SSL_CTX structure
3025 #
3026 # returns: value corresponding to openssl's LHASH structure (0 on failure)
3027 Check openssl doc
3029 <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
3030 · CTX_set1_param
3032 Applies X509 verification parameters $vpm on $ctx
3034 my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
3036 # $ctx - value corresponding to openssl's SSL_CTX structure
3037 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
3038 #
3039 # returns: 1 on success, 0 on failure
3040 Check openssl doc
3042 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3043 · CTX_set_cert_store
3045 Sets/replaces the certificate verification storage of $ctx to/with
3047 $store.
3048 Net::SSLeay::CTX_set_cert_store($ctx, $store);
3050 # $ctx - value corresponding to openssl's SSL_CTX structure
3051 # $store - value corresponding to openssl's X509_STORE structure
3052 #
3053 # returns: no return value
3054 Check openssl doc
3056 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
3057 · CTX_set_cert_verify_callback
3059 Sets the verification callback function for $ctx. SSL objects that
3061 are created from $ctx inherit the setting valid at the time when
3062 "Net::SSLeay::new($ctx)" is called.
3063 Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
3065 # $ctx - value corresponding to openssl's SSL_CTX structure
3066 # $func - perl reference to callback function
3067 # $data - [optional] data that will be passed to callback function when invoked
3068 #
3069 # returns: no return value
3070 Check openssl doc
3072 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
3073 · CTX_set_cipher_list
3075 Sets the list of available ciphers for $ctx using the control
3077 string $str. The list of ciphers is inherited by all ssl objects
3078 created from $ctx.
3079 my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
3081 # $s - value corresponding to openssl's SSL_CTX structure
3082 # $str - (string) cipher list e.g. '3DES:+RSA'
3083 #
3084 # returns: 1 if any cipher could be selected and 0 on complete failure
3085 The format of $str is described in
3087 <http://www.openssl.org/docs/apps/ciphers.html>
3088 Check openssl doc
3090 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
3091 · CTX_set_ciphersuites
3093 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3095 requires at least OpenSSL 1.1.1, not in LibreSSL
3096 Configure the available TLSv1.3 ciphersuites.
3098 my $rv = Net::SSLeay::CTX_set_ciphersuites($ctx, $str);
3100 # $ctx - value corresponding to openssl's SSL_CTX structure
3101 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
3102 #
3103 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
3104 Check openssl doc
3106 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html>
3107 · CTX_set_client_CA_list
3109 Sets the list of CAs sent to the client when requesting a client
3111 certificate for $ctx.
3112 Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
3114 # $ctx - value corresponding to openssl's SSL_CTX structure
3115 # $list - value corresponding to openssl's X509_NAME_STACK structure
3116 #
3117 # returns: no return value
3118 Check openssl doc
3120 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3121 · CTX_set_default_passwd_cb
3123 Sets the default password callback called when loading/storing a
3125 PEM certificate with encryption.
3126 Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
3128 # $ctx - value corresponding to openssl's SSL_CTX structure
3129 # $func - perl reference to callback function
3130 #
3131 # returns: no return value
3132 Check openssl doc
3134 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3135 · CTX_set_default_passwd_cb_userdata
3137 Sets a pointer to userdata which will be provided to the password
3139 callback on invocation.
3140 Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
3142 # $ctx - value corresponding to openssl's SSL_CTX structure
3143 # $userdata - data that will be passed to callback function when invoked
3144 #
3145 # returns: no return value
3146 Check openssl doc
3148 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3149 · CTX_set_default_verify_paths
3151 ??? (more info needed)
3153 my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
3155 # $ctx - value corresponding to openssl's SSL_CTX structure
3156 #
3157 # returns: 1 on success, 0 on failure
3158 · CTX_set_ex_data
3160 Is used to store application data at $data for $idx into the $ctx
3162 object.
3163 my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
3165 # $ssl - value corresponding to openssl's SSL_CTX structure
3166 # $idx - (integer) ???
3167 # $data - (pointer) ???
3168 #
3169 # returns: 1 on success, 0 on failure
3170 Check openssl doc
3172 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3173 · CTX_set_purpose
3175 my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
3177 # $s - value corresponding to openssl's SSL_CTX structure
3178 # $purpose - (integer) purpose identifier
3179 #
3180 # returns: 1 on success, 0 on failure
3181 #avainable purpose identifier
3183 1 - X509_PURPOSE_SSL_CLIENT
3184 2 - X509_PURPOSE_SSL_SERVER
3185 3 - X509_PURPOSE_NS_SSL_SERVER
3186 4 - X509_PURPOSE_SMIME_SIGN
3187 5 - X509_PURPOSE_SMIME_ENCRYPT
3188 6 - X509_PURPOSE_CRL_SIGN
3189 7 - X509_PURPOSE_ANY
3190 8 - X509_PURPOSE_OCSP_HELPER
3191 9 - X509_PURPOSE_TIMESTAMP_SIGN
3192 #or use corresponding constants
3194 $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3195 ...
3196 $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3197 · CTX_set_quiet_shutdown
3199 Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
3201 created from $ctx inherit the mode valid at the time
3202 "Net::SSLeay::new($ctx)" is called.
3203 Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
3205 # $ctx - value corresponding to openssl's SSL_CTX structure
3206 # $mode - 0 or 1
3207 #
3208 # returns: no return value
3209 Check openssl doc
3211 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3212 · CTX_set_read_ahead
3214 my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
3216 # $ctx - value corresponding to openssl's SSL_CTX structure
3217 # $val - read_ahead value to be set
3218 #
3219 # returns: the original read_ahead value
3220 · CTX_set_session_id_context
3222 Sets the context $sid_ctx of length $sid_ctx_len within which a
3224 session can be reused for the $ctx object.
3225 my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
3227 # $ctx - value corresponding to openssl's SSL_CTX structure
3228 # $sid_ctx - data buffer
3229 # $sid_ctx_len - length of data in $sid_ctx
3230 #
3231 # returns: 1 on success, 0 on failure (the error is logged to the error stack)
3232 Check openssl doc
3234 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3235 · CTX_set_ssl_version
3237 Sets a new default TLS/SSL method for SSL objects newly created
3239 from this $ctx. SSL objects already created with
3240 "Net::SSLeay::new($ctx)" are not affected, except when
3241 "Net::SSLeay:clear($ssl)" is being called.
3242 my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
3244 # $ctx - value corresponding to openssl's SSL_CTX structure
3245 # $meth - value corresponding to openssl's SSL_METHOD structure
3246 #
3247 # returns: 1 on success, 0 on failure
3248 Check openssl doc
3250 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3251 · CTX_set_timeout
3253 Sets the timeout for newly created sessions for $ctx to $t. The
3255 timeout value $t must be given in seconds.
3256 my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
3258 # $ctx - value corresponding to openssl's SSL_CTX structure
3259 # $t - timeout in seconds
3260 #
3261 # returns: previously set timeout value
3262 Check openssl doc
3264 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3265 · CTX_set_tmp_dh
3267 Sets DH parameters to be used to be $dh. The key is inherited by
3269 all ssl objects created from $ctx.
3270 my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
3272 # $ctx - value corresponding to openssl's SSL_CTX structure
3273 # $dh - value corresponding to openssl's DH structure
3274 #
3275 # returns: 1 on success, 0 on failure
3276 Check openssl doc
3278 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3279 · CTX_set_tmp_dh_callback
3281 Sets the callback function for $ctx to be used when a DH parameters
3283 are required to $tmp_dh_callback.
3284 Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
3286 # $ctx - value corresponding to openssl's SSL_CTX structure
3287 # tmp_dh_callback - (function pointer) ???
3288 #
3289 # returns: no return value
3290 Check openssl doc
3292 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3293 · CTX_set_tmp_rsa
3295 Sets the temporary/ephemeral RSA key to be used to be $rsa.
3297 my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
3299 # $ctx - value corresponding to openssl's SSL_CTX structure
3300 # $rsa - value corresponding to openssl's RSA structure
3301 #
3302 # returns: 1 on success, 0 on failure
3303 Check openssl doc
3305 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3306 Not available with OpenSSL 1.1 and later.
3308 · CTX_set_tmp_rsa_callback
3310 Sets the callback function for ctx to be used when a
3312 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3313 ??? (does this function really work?)
3315 Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
3317 # $ctx - value corresponding to openssl's SSL_CTX structure
3318 # $tmp_rsa_callback - (function pointer) ???
3319 #
3320 # returns: no return value
3321 Check openssl doc
3323 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3324 Not available with OpenSSL 1.1 and later.
3326 · CTX_set_trust
3328 my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
3330 # $s - value corresponding to openssl's SSL_CTX structure
3331 # $trust - (integer) trust identifier
3332 #
3333 # returns: the original value
3334 #available trust identifiers
3336 1 - X509_TRUST_COMPAT
3337 2 - X509_TRUST_SSL_CLIENT
3338 3 - X509_TRUST_SSL_SERVER
3339 4 - X509_TRUST_EMAIL
3340 5 - X509_TRUST_OBJECT_SIGN
3341 6 - X509_TRUST_OCSP_SIGN
3342 7 - X509_TRUST_OCSP_REQUEST
3343 8 - X509_TRUST_TSA
3344 #or use corresponding constants
3346 $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3347 ...
3348 $trust = &Net::SSLeay::X509_TRUST_TSA;
3349 · CTX_set_verify_depth
3351 Sets the maximum depth for the certificate chain verification that
3353 shall be allowed for ctx.
3354 Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
3356 # $ctx - value corresponding to openssl's SSL_CTX structure
3357 # $depth - max. depth
3358 #
3359 # returns: no return value
3360 Check openssl doc
3362 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3363 · CTX_use_PKCS12_file
3365 Adds the certificate and private key from PKCS12 file $p12filename
3367 to $ctx.
3368 my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
3370 # $ctx - value corresponding to openssl's SSL_CTX structure
3371 # $p12filename - (string) filename
3372 # $password - (string) password to decrypt private key
3373 #
3374 # returns: 1 on success, 0 on failure
3375 · CTX_use_PrivateKey
3377 Adds the private key $pkey to $ctx.
3379 my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
3381 # $ctx - value corresponding to openssl's SSL_CTX structure
3382 # $pkey - value corresponding to openssl's EVP_PKEY structure
3383 #
3384 # returns: 1 on success, otherwise check out the error stack to find out the reason
3385 Check openssl doc
3387 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3388 · CTX_use_PrivateKey_file
3390 Adds the first private key found in $file to $ctx.
3392 my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
3394 # $ctx - value corresponding to openssl's SSL_CTX structure
3395 # $file - (string) file name
3396 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3397 #
3398 # returns: 1 on success, otherwise check out the error stack to find out the reason
3399 Check openssl doc
3401 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3402 · CTX_use_RSAPrivateKey
3404 Adds the RSA private key $rsa to $ctx.
3406 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
3408 # $ctx - value corresponding to openssl's SSL_CTX structure
3409 # $rsa - value corresponding to openssl's RSA structure
3410 #
3411 # returns: 1 on success, otherwise check out the error stack to find out the reason
3412 Check openssl doc
3414 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3415 · CTX_use_RSAPrivateKey_file
3417 Adds the first RSA private key found in $file to $ctx.
3419 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
3421 # $ctx - value corresponding to openssl's SSL_CTX structure
3422 # $file - (string) file name
3423 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3424 #
3425 # returns: 1 on success, otherwise check out the error stack to find out the reason
3426 · CTX_use_certificate
3428 Loads the certificate $x into $ctx
3430 my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
3432 # $ctx - value corresponding to openssl's SSL_CTX structure
3433 # $x - value corresponding to openssl's X509 structure
3434 #
3435 # returns: 1 on success, otherwise check out the error stack to find out the reason
3436 Check openssl doc
3438 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3439 · CTX_use_certificate_chain_file
3441 Loads a certificate chain from $file into $ctx. The certificates
3443 must be in PEM format and must be sorted starting with the
3444 subject's certificate (actual client or server certificate),
3445 followed by intermediate CA certificates if applicable, and ending
3446 at the highest level (root) CA.
3447 my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
3449 # $ctx - value corresponding to openssl's SSL_CTX structure
3450 # $file - (string) file name
3451 #
3452 # returns: 1 on success, otherwise check out the error stack to find out the reason
3453 Check openssl doc
3455 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3456 · CTX_use_certificate_file
3458 Loads the first certificate stored in $file into $ctx.
3460 my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
3462 # $ctx - value corresponding to openssl's SSL_CTX structure
3463 # $file - (string) file name
3464 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3465 #
3466 # returns: 1 on success, otherwise check out the error stack to find out the reason
3467 Check openssl doc
3469 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3470 · CTX_get_security_level
3472 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3474 requires at least OpenSSL 1.1.0, not in LibreSSL
3475 Returns the security level associated with $ctx.
3477 my $level = Net::SSLeay::CTX_get_security_level($ctx);
3479 # $ctx - value corresponding to openssl's SSL_CTX structure
3480 #
3481 # returns: (integer) current security level
3482 Check openssl doc
3484 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html>
3485 · CTX_set_security_level
3487 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3489 requires at least OpenSSL 1.1.0, not in LibreSSL
3490 Sets the security level associated with $ctx to $level.
3492 Net::SSLeay::CTX_set_security_level($ctx, $level);
3494 # $ssl - value corresponding to openssl's SSL_CTX structure
3495 # $level - new security level
3496 #
3497 # returns: no return value
3498 Check openssl doc
3500 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html>
3501 · CTX_set_num_tickets
3503 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3505 requires at least OpenSSL 1.1.1, not in LibreSSL
3506 Set number of TLSv1.3 session tickets that will be sent to a
3508 client.
3509 my $rv = Net::SSLeay::CTX_set_num_tickets($ctx, $number_of_tickets);
3511 # $ctx - value corresponding to openssl's SSL_CTX structure
3512 # $number_of_tickets - number of tickets to send
3513 #
3514 # returns: 1 on success, 0 on failure
3515 Set to zero if you do not no want to support a session resumption.
3517 Check openssl doc
3519 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html>
3520 · CTX_get_num_tickets
3522 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3524 requires at least OpenSSL 1.1.1, not in LibreSSL
3525 Get number of TLSv1.3 session tickets that will be sent to a
3527 client.
3528 my $number_of_tickets = Net::SSLeay::CTX_get_num_tickets($ctx);
3530 # $ctx - value corresponding to openssl's SSL_CTX structure
3531 #
3532 # returns: (integer) number of tickets to send
3533 Check openssl doc
3535 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_num_tickets.html>
3536 Low level API: SSL_* related functions
3538 NOTE: Please note that the function described in this chapter have
3540 "SSL_" part stripped from their original openssl names.
3541 · new
3543 Creates a new SSL structure which is needed to hold the data for a
3545 TLS/SSL connection. The new structure inherits the settings of the
3546 underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3547 options, verification settings, timeout settings.
3548 my $rv = Net::SSLeay::new($ctx);
3550 # $ctx - value corresponding to openssl's SSL_CTX structure
3551 #
3552 # returns: value corresponding to openssl's SSL structure (0 on failure)
3553 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3555 · accept
3557 Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3559 communication channel must already have been set and assigned to
3560 the ssl by setting an underlying BIO.
3561 my $rv = Net::SSLeay::accept($ssl);
3563 # $ssl - value corresponding to openssl's SSL structure
3564 #
3565 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3566 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3568 · add_client_CA
3570 Adds the CA name extracted from cacert to the list of CAs sent to
3572 the client when requesting a client certificate for the chosen ssl,
3573 overriding the setting valid for ssl's SSL_CTX object.
3574 my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3576 # $ssl - value corresponding to openssl's SSL structure
3577 # $x - value corresponding to openssl's X509 structure
3578 #
3579 # returns: 1 on success, 0 on failure
3580 Check openssl doc
3582 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3583 · callback_ctrl
3585 ??? (more info needed)
3587 my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3589 # $ssl - value corresponding to openssl's SSL structure
3590 # $cmd - (integer) command id
3591 # $fp - (function pointer) ???
3592 #
3593 # returns: ???
3594 Check openssl doc
3596 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3597 · check_private_key
3599 Checks the consistency of a private key with the corresponding
3601 certificate loaded into $ssl
3602 my $rv = Net::SSLeay::check_private_key($ssl);
3604 # $ssl - value corresponding to openssl's SSL structure
3605 #
3606 # returns: 1 on success, otherwise check out the error stack to find out the reason
3607 Check openssl doc
3609 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3610 · clear
3612 Reset SSL object to allow another connection.
3614 Net::SSLeay::clear($ssl);
3616 # $ssl - value corresponding to openssl's SSL structure
3617 #
3618 # returns: no return value
3619 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3621 · connect
3623 Initiate the TLS/SSL handshake with an TLS/SSL server.
3625 my $rv = Net::SSLeay::connect($ssl);
3627 # $ssl - value corresponding to openssl's SSL structure
3628 #
3629 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3630 Check openssl doc
3632 <http://www.openssl.org/docs/ssl/SSL_connect.html>
3633 · copy_session_id
3635 Copies the session structure fro $from to $to (+ also the private
3637 key and certificate associated with $from).
3638 Net::SSLeay::copy_session_id($to, $from);
3640 # $to - value corresponding to openssl's SSL structure
3641 # $from - value corresponding to openssl's SSL structure
3642 #
3643 # returns: no return value
3644 · ctrl
3646 Internal handling function for SSL objects.
3648 BEWARE: openssl doc says: This function should never be called
3650 directly!
3651 my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3653 # $ssl - value corresponding to openssl's SSL structure
3654 # $cmd - (integer) command id
3655 # $larg - (integer) long ???
3656 # $parg - (string/pointer) ???
3657 #
3658 # returns: (long) result of given command ???
3659 For more details about valid $cmd values check "CTX_ctrl".
3661 Check openssl doc
3663 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3664 · do_handshake
3666 Will wait for a SSL/TLS handshake to take place. If the connection
3668 is in client mode, the handshake will be started. The handshake
3669 routines may have to be explicitly set in advance using either
3670 SSL_set_connect_state or SSL_set_accept_state(3).
3671 my $rv = Net::SSLeay::do_handshake($ssl);
3673 # $ssl - value corresponding to openssl's SSL structure
3674 #
3675 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3676 Check openssl doc
3678 <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3679 · dup
3681 Returns a duplicate of $ssl.
3683 my $rv = Net::SSLeay::dup($ssl);
3685 # $ssl - value corresponding to openssl's SSL structure
3686 #
3687 # returns: value corresponding to openssl's SSL structure (0 on failure)
3688 · free
3690 Free an allocated SSL structure.
3692 Net::SSLeay::free($ssl);
3694 # $ssl - value corresponding to openssl's SSL structure
3695 #
3696 # returns: no return value
3697 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3699 · get0_param
3701 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
3703 requires at least OpenSSL 1.0.2
3704 Returns the current verification parameters.
3706 my $vpm = Net::SSLeay::get0_param($ssl);
3708 # $ssl - value corresponding to openssl's SSL structure
3709 #
3710 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
3711 Check openssl doc
3713 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3714 · get_SSL_CTX
3716 Returns a pointer to the SSL_CTX object, from which $ssl was
3718 created with Net::SSLeay::new.
3719 my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3721 # $ssl - value corresponding to openssl's SSL structure
3722 #
3723 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3724 Check openssl doc
3726 <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3727 · set_SSL_CTX
3729 Sets the SSL_CTX the corresponds to an SSL session.
3731 my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3733 # $ssl - value corresponding to openssl's SSL structure
3734 # $ssl_ctx - Change the ssl object to the given ssl_ctx
3735 #
3736 # returns - the ssl_ctx
3737 · get_app_data
3739 Can be used to get application defined value/data.
3741 my $rv = Net::SSLeay::get_app_data($ssl);
3743 # $ssl - value corresponding to openssl's SSL structure
3744 #
3745 # returns: string/buffer/pointer ???
3746 · set_app_data
3748 Can be used to set some application defined value/data.
3750 my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3752 # $ssl - value corresponding to openssl's SSL structure
3753 # $arg - (string/buffer/pointer ???) data
3754 #
3755 # returns: ???
3756 · get_certificate
3758 Gets X509 certificate from an established SSL connection.
3760 my $rv = Net::SSLeay::get_certificate($ssl);
3762 # $ssl - value corresponding to openssl's SSL structure
3763 #
3764 # returns: value corresponding to openssl's X509 structure (0 on failure)
3765 · get_cipher
3767 Obtains the name of the currently used cipher.
3769 my $rv = Net::SSLeay::get_cipher($ssl);
3771 # $ssl - value corresponding to openssl's SSL structure
3772 #
3773 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3774 Check openssl doc
3776 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3777 · get_cipher_bits
3779 Obtain the number of secret/algorithm bits used.
3781 my $rv = Net::SSLeay::get_cipher_bits($ssl);
3783 # $ssl - value corresponding to openssl's SSL structure
3784 #
3785 # returns: number of secret bits used by current cipher
3786 Check openssl doc
3788 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3789 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3790 · get_cipher_list
3792 Returns the name (string) of the SSL_CIPHER listed for $ssl with
3794 priority $n.
3795 my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
3797 # $ssl - value corresponding to openssl's SSL structure
3798 # $n - (integer) priority
3799 #
3800 # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or '' in case of error
3801 Call Net::SSLeay::get_cipher_list with priority starting from 0 to
3803 obtain the sorted list of available ciphers, until '' is returned:
3804 my $priority = 0;
3806 while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
3807 print "cipher[$priority] = $c\n";
3808 $priority++;
3809 }
3810 Check openssl doc
3812 <http://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
3813 · get_client_CA_list
3815 Returns the list of client CAs explicitly set for $ssl using
3817 "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
3818 "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
3819 In client mode, returns the list of client CAs sent from the
3821 server, if any.
3822 my $rv = Net::SSLeay::get_client_CA_list($ssl);
3824 # $ssl - value corresponding to openssl's SSL structure
3825 #
3826 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
3827 Check openssl doc
3829 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
3830 · get_current_cipher
3832 Returns the cipher actually used.
3834 my $rv = Net::SSLeay::get_current_cipher($ssl);
3836 # $ssl - value corresponding to openssl's SSL structure
3837 #
3838 # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
3839 Check openssl doc
3841 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3842 · get_default_timeout
3844 Returns the default timeout value assigned to SSL_SESSION objects
3846 negotiated for the protocol valid for $ssl.
3847 my $rv = Net::SSLeay::get_default_timeout($ssl);
3849 # $ssl - value corresponding to openssl's SSL structure
3850 #
3851 # returns: (long) timeout in seconds
3852 Check openssl doc
3854 <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
3855 · get_error
3857 Returns a result code for a preceding call to "connect", "accept",
3859 "do_handshake", "read", "peek" or "write" on $ssl.
3860 my $rv = Net::SSLeay::get_error($ssl, $ret);
3862 # $ssl - value corresponding to openssl's SSL structure
3863 # $ret - return value of preceding TLS/SSL I/O operation
3864 #
3865 # returns: result code, which is one of the following values:
3866 # 0 - SSL_ERROR_NONE
3867 # 1 - SSL_ERROR_SSL
3868 # 2 - SSL_ERROR_WANT_READ
3869 # 3 - SSL_ERROR_WANT_WRITE
3870 # 4 - SSL_ERROR_WANT_X509_LOOKUP
3871 # 5 - SSL_ERROR_SYSCALL
3872 # 6 - SSL_ERROR_ZERO_RETURN
3873 # 7 - SSL_ERROR_WANT_CONNECT
3874 # 8 - SSL_ERROR_WANT_ACCEPT
3875 Check openssl doc
3877 <http://www.openssl.org/docs/ssl/SSL_get_error.html>
3878 · get_ex_data
3880 Is used to retrieve the information for $idx from $ssl.
3882 my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
3884 # $ssl - value corresponding to openssl's SSL structure
3885 # $idx - (integer) index for application specific data
3886 #
3887 # returns: pointer to ???
3888 Check openssl doc
3890 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3891 · set_ex_data
3893 Is used to store application data at $data for $idx into the $ssl
3895 object.
3896 my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
3898 # $ssl - value corresponding to openssl's SSL structure
3899 # $idx - (integer) ???
3900 # $data - (pointer) ???
3901 #
3902 # returns: 1 on success, 0 on failure
3903 Check openssl doc
3905 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3906 · get_ex_new_index
3908 Is used to register a new index for application specific data.
3910 my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
3912 # $argl - (long) ???
3913 # $argp - (pointer) ???
3914 # $new_func - function pointer ??? (CRYPTO_EX_new *)
3915 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
3916 # $free_func - function pointer ??? (CRYPTO_EX_free *)
3917 #
3918 # returns: (integer) ???
3919 Check openssl doc
3921 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3922 · get_fd
3924 Returns the file descriptor which is linked to $ssl.
3926 my $rv = Net::SSLeay::get_fd($ssl);
3928 # $ssl - value corresponding to openssl's SSL structure
3929 #
3930 # returns: file descriptor (>=0) or -1 on failure
3931 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
3933 · get_finished
3935 Obtains the latest 'Finished' message sent to the peer. Return
3937 value is zero if there's been no Finished message yet. Default
3938 count is 2*EVP_MAX_MD_SIZE that is long enough for all possible
3939 Finish messages. If you supply a non-default count, the resulting
3940 return value may be longer than returned buf's length.
3941 my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
3943 # $ssl - value corresponding to openssl's SSL structure
3944 # $buf - buffer where the returned data will be stored
3945 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3946 #
3947 # returns: length of latest Finished message
3948 · get_peer_finished
3950 Obtains the latest 'Finished' message expected from the peer.
3952 Parameters and return value are similar to get_finished().
3953 my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
3955 # $ssl - value corresponding to openssl's SSL structure
3956 # $buf - buffer where the returned data will be stored
3957 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3958 #
3959 # returns: length of latest Finished message
3960 · get_keyblock_size
3962 Gets the length of the TLS keyblock.
3964 NOTE: Does not exactly correspond to any low level API function.
3966 my $rv = Net::SSLeay::get_keyblock_size($ssl);
3968 # $ssl - value corresponding to openssl's SSL structure
3969 #
3970 # returns: keyblock size, -1 on error
3971 · get_mode
3973 Returns the mode (bitmask) set for $ssl.
3975 my $rv = Net::SSLeay::get_mode($ssl);
3977 # $ssl - value corresponding to openssl's SSL structure
3978 #
3979 # returns: mode (bitmask)
3980 To decode the return value (bitmask) see documentation for
3982 "CTX_get_mode".
3983 Check openssl doc
3985 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3986 · set_mode
3988 Adds the mode set via bitmask in $mode to $ssl. Options already set
3990 before are not cleared.
3991 my $rv = Net::SSLeay::set_mode($ssl, $mode);
3993 # $ssl - value corresponding to openssl's SSL structure
3994 # $mode - mode (bitmask)
3995 #
3996 # returns: the new mode bitmask after adding $mode
3997 For $mode bitmask details see "CTX_get_mode".
3999 Check openssl doc
4001 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4002 · get_options
4004 Returns the options (bitmask) set for $ssl.
4006 my $rv = Net::SSLeay::get_options($ssl);
4008 # $ssl - value corresponding to openssl's SSL structure
4009 #
4010 # returns: options (bitmask)
4011 To decode the return value (bitmask) see documentation for
4013 "CTX_get_options".
4014 Check openssl doc
4016 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4017 · set_options
4019 Adds the options set via bitmask in $options to $ssl. Options
4021 already set before are not cleared!
4022 Net::SSLeay::set_options($ssl, $options);
4024 # $ssl - value corresponding to openssl's SSL structure
4025 # $options - options (bitmask)
4026 #
4027 # returns: the new options bitmask after adding $options
4028 For $options bitmask details see "CTX_get_options".
4030 Check openssl doc
4032 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4033 · get_peer_certificate
4035 Get the X509 certificate of the peer.
4037 my $rv = Net::SSLeay::get_peer_certificate($ssl);
4039 # $ssl - value corresponding to openssl's SSL structure
4040 #
4041 # returns: value corresponding to openssl's X509 structure (0 on failure)
4042 Check openssl doc
4044 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4045 · get_peer_cert_chain
4047 Get the certificate chain of the peer as an array of X509
4049 structures.
4050 my @rv = Net::SSLeay::get_peer_cert_chain($ssl);
4052 # $ssl - value corresponding to openssl's SSL structure
4053 #
4054 # returns: list of X509 structures
4055 Check openssl doc
4057 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4058 · get_quiet_shutdown
4060 Returns the 'quiet shutdown' setting of ssl.
4062 my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
4064 # $ssl - value corresponding to openssl's SSL structure
4065 #
4066 # returns: (integer) current 'quiet shutdown' value
4067 Check openssl doc
4069 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4070 · get_rbio
4072 Get 'read' BIO linked to an SSL object $ssl.
4074 my $rv = Net::SSLeay::get_rbio($ssl);
4076 # $ssl - value corresponding to openssl's SSL structure
4077 #
4078 # returns: value corresponding to openssl's BIO structure (0 on failure)
4079 Check openssl doc
4081 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4082 · get_read_ahead
4084 my $rv = Net::SSLeay::get_read_ahead($ssl);
4086 # $ssl - value corresponding to openssl's SSL structure
4087 #
4088 # returns: (integer) read_ahead value
4089 · set_read_ahead
4091 Net::SSLeay::set_read_ahead($ssl, $val);
4093 # $ssl - value corresponding to openssl's SSL structure
4094 # $val - read_ahead value to be set
4095 #
4096 # returns: the original read_ahead value
4097 · get_security_level
4099 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4101 requires at least OpenSSL 1.1.0, not in LibreSSL
4102 Returns the security level associated with $ssl.
4104 my $level = Net::SSLeay::get_security_level($ssl);
4106 # $ssl - value corresponding to openssl's SSL structure
4107 #
4108 # returns: (integer) current security level
4109 Check openssl doc
4111 <https://www.openssl.org/docs/manmaster/man3/SSL_get_security_level.html>
4112 · set_security_level
4114 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4116 requires at least OpenSSL 1.1.0, not in LibreSSL
4117 Sets the security level associated with $ssl to $level.
4119 Net::SSLeay::set_security_level($ssl, $level);
4121 # $ssl - value corresponding to openssl's SSL structure
4122 # $level - new security level
4123 #
4124 # returns: no return value
4125 Check openssl doc
4127 <https://www.openssl.org/docs/manmaster/man3/SSL_set_security_level.html>
4128 · set_num_tickets
4130 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4132 requires at least OpenSSL 1.1.1, not in LibreSSL
4133 Set number of TLSv1.3 session tickets that will be sent to a
4135 client.
4136 my $rv = Net::SSLeay::set_num_tickets($ssl, $number_of_tickets);
4138 # $ssl - value corresponding to openssl's SSL structure
4139 # $number_of_tickets - number of tickets to send
4140 #
4141 # returns: 1 on success, 0 on failure
4142 Set to zero if you do not no want to support a session resumption.
4144 Check openssl doc
4146 <https://www.openssl.org/docs/manmaster/man3/SSL_set_num_tickets.html>
4147 · get_num_tickets
4149 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4151 requires at least OpenSSL 1.1.1, not in LibreSSL
4152 Get number of TLSv1.3 session tickets that will be sent to a
4154 client.
4155 my $number_of_tickets = Net::SSLeay::get_num_tickets($ctx);
4157 # $ctx - value corresponding to openssl's SSL structure
4158 #
4159 # returns: number of tickets to send
4160 Check openssl doc
4162 <https://www.openssl.org/docs/manmaster/man3/SSL_get_num_tickets.html>
4163 · get_server_random
4165 Returns internal SSLv3 server_random value.
4167 Net::SSLeay::get_server_random($ssl);
4169 # $ssl - value corresponding to openssl's SSL structure
4170 #
4171 # returns: server_random value (binary data)
4172 · get_client_random
4174 NOTE: Does not exactly correspond to any low level API function
4176 Returns internal SSLv3 client_random value.
4178 Net::SSLeay::get_client_random($ssl);
4180 # $ssl - value corresponding to openssl's SSL structure
4181 #
4182 # returns: client_random value (binary data)
4183 · export_keying_material
4185 Returns keying material based on the string $label and optional
4187 $context. Note that with TLSv1.2 and lower, empty context (empty
4188 string) and undefined context (no value or 'undef') will return
4189 different values.
4190 my $out = Net::SSLeay::export_keying_material($ssl, $olen, $label, $context);
4192 # $ssl - value corresponding to openssl's SSL structure
4193 # $olen - number of bytes to return
4194 # $label - application specific label
4195 # $context - [optional] context - default is undef for no context
4196 #
4197 # returns: keying material (binary data) or undef on error
4198 Check openssl doc
4200 <https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html>
4201 · get_session
4203 Retrieve TLS/SSL session data used in $ssl. The reference count of
4205 the SSL_SESSION is NOT incremented.
4206 my $rv = Net::SSLeay::get_session($ssl);
4208 # $ssl - value corresponding to openssl's SSL structure
4209 #
4210 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4211 Check openssl doc
4213 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4214 · SSL_get0_session
4216 The alias for "get_session" (note that the name is
4218 "SSL_get0_session" NOT "get0_session").
4219 my $rv = Net::SSLeay::SSL_get0_session();
4221 · get1_session
4223 Returns a pointer to the SSL_SESSION actually used in $ssl. The
4225 reference count of the SSL_SESSION is incremented by 1.
4226 my $rv = Net::SSLeay::get1_session($ssl);
4228 # $ssl - value corresponding to openssl's SSL structure
4229 #
4230 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4231 Check openssl doc
4233 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4234 · get_shared_ciphers
4236 Returns string with a list (colon ':' separated) of ciphers shared
4238 between client and server within SSL session $ssl.
4239 my $rv = Net::SSLeay::get_shared_ciphers()
4241 #
4242 # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
4243 · get_shutdown
4245 Returns the shutdown mode of $ssl.
4247 my $rv = Net::SSLeay::get_shutdown($ssl);
4249 # $ssl - value corresponding to openssl's SSL structure
4250 #
4251 # returns: shutdown mode (bitmask) of ssl
4252 #to decode the return value (bitmask) use:
4254 0 - No shutdown setting, yet
4255 1 - SSL_SENT_SHUTDOWN
4256 2 - SSL_RECEIVED_SHUTDOWN
4257 Check openssl doc
4259 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4260 · get_ssl_method
4262 Returns a function pointer to the TLS/SSL method set in $ssl.
4264 my $rv = Net::SSLeay::get_ssl_method($ssl);
4266 # $ssl - value corresponding to openssl's SSL structure
4267 #
4268 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
4269 Check openssl doc
4271 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4272 · in_init, in_before, is_init_finished, in_connect_init,
4274 in_accept_init
4275 COMPATIBILITY: not available in Net-SSLeay-1.85 and before.
4277 Retrieve information about the handshake state machine. All
4279 functions take $ssl as the only argument and return 0 or 1. These
4280 functions are recommended over get_state() and state().
4281 my $rv = Net::SSLeay::is_init_finished($ssl);
4283 # $ssl - value corresponding to openssl's SSL structure
4284 #
4285 # returns: All functions return 1 or 0
4286 Check openssl doc https://www.openssl.org/docs/ssl/SSL_in_init.html
4288 <http://www.openssl.org/docs/ssl/SSL_in_init.html>
4289 · get_state
4291 COMPATIBILITY: OpenSSL 1.1.0 and later use different constants
4293 which are not made available. Use is_init_finished() and related
4294 functions instead.
4295 Returns the SSL connection state.
4297 my $rv = Net::SSLeay::get_state($ssl);
4299 # $ssl - value corresponding to openssl's SSL structure
4300 #
4301 # returns: (integer) state value
4302 # to decode the returned state check:
4303 # SSL_ST_* constants in openssl/ssl.h
4304 # SSL2_ST_* constants in openssl/ssl2.h
4305 # SSL23_ST_* constants in openssl/ssl23.h
4306 # SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
4307 · state
4309 Exactly the same as "get_state".
4311 my $rv = Net::SSLeay::state($ssl);
4313 · set_state
4315 Sets the SSL connection state.
4317 Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4319 Not available with OpenSSL 1.1 and later.
4321 · get_verify_depth
4323 Returns the verification depth limit currently set in $ssl.
4325 my $rv = Net::SSLeay::get_verify_depth($ssl);
4327 # $ssl - value corresponding to openssl's SSL structure
4328 #
4329 # returns: current depth or -1 if no limit has been explicitly set
4330 Check openssl doc
4332 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4333 · set_verify_depth
4335 Sets the maximum depth for the certificate chain verification that
4337 shall be allowed for $ssl.
4338 Net::SSLeay::set_verify_depth($ssl, $depth);
4340 # $ssl - value corresponding to openssl's SSL structure
4341 # $depth - (integer) depth
4342 #
4343 # returns: no return value
4344 Check openssl doc
4346 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4347 · get_verify_mode
4349 Returns the verification mode (bitmask) currently set in $ssl.
4351 my $rv = Net::SSLeay::get_verify_mode($ssl);
4353 # $ssl - value corresponding to openssl's SSL structure
4354 #
4355 # returns: mode (bitmask)
4356 To decode the return value (bitmask) see documentation for
4358 "CTX_get_verify_mode".
4359 Check openssl doc
4361 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4362 · set_verify
4364 Sets the verification flags for $ssl to be $mode and specifies the
4366 $verify_callback function to be used.
4367 Net::SSLeay::set_verify($ssl, $mode, $callback);
4369 # $ssl - value corresponding to openssl's SSL structure
4370 # $mode - mode (bitmask)
4371 # $callback - [optional] reference to perl callback function
4372 #
4373 # returns: no return value
4374 For $mode bitmask details see "CTX_get_verify_mode".
4376 Check openssl doc
4378 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4379 · set_post_handshake_auth
4381 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4383 requires at least OpenSSL 1.1.1, not in LibreSSL
4384 Enable the Post-Handshake Authentication extension to be added to
4386 the ClientHello such that post-handshake authentication can be
4387 requested by the server.
4388 Net::SSLeay::set_posthandshake_auth($ssl, $val);
4390 # $ssl - value corresponding to openssl's SSL structure
4391 # $val - 0 then the extension is not sent, otherwise it is
4392 #
4393 # returns: no return value
4394 Check openssl doc
4396 https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth
4397 <https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth.html>
4398 · verify_client_post_handshake
4400 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4402 requires at least OpenSSL 1.1.1, not in LibreSSL
4403 verify_client_post_handshake causes a CertificateRequest message to
4405 be sent by a server on the given ssl connection.
4406 my $rv = Net::SSLeay::verify_client_post_handshake($ssl);
4408 # $ssl - value corresponding to openssl's SSL structure
4409 #
4410 # returns: 1 if the request succeeded, and 0 if the request failed. The error stack can be examined to determine the failure reason.
4411 Check openssl doc
4413 <https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html>
4414 · get_verify_result
4416 Returns the result of the verification of the X509 certificate
4418 presented by the peer, if any.
4419 my $rv = Net::SSLeay::get_verify_result($ssl);
4421 # $ssl - value corresponding to openssl's SSL structure
4422 #
4423 # returns: (integer)
4424 # 0 - X509_V_OK: ok
4425 # 2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
4426 # 3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
4427 # 4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
4428 # 5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
4429 # 6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
4430 # 7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
4431 # 8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
4432 # 9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
4433 # 10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
4434 # 11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
4435 # 12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
4436 # 13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
4437 # 14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
4438 # 15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
4439 # 16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
4440 # 17 - X509_V_ERR_OUT_OF_MEM: out of memory
4441 # 18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
4442 # 19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
4443 # 20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
4444 # 21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
4445 # 22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
4446 # 23 - X509_V_ERR_CERT_REVOKED: certificate revoked
4447 # 24 - X509_V_ERR_INVALID_CA: invalid CA certificate
4448 # 25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
4449 # 26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
4450 # 27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
4451 # 28 - X509_V_ERR_CERT_REJECTED: certificate rejected
4452 # 29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
4453 # 30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
4454 # 31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
4455 # 32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
4456 # 50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
4457 Check openssl doc
4459 <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4460 · set_verify_result
4462 Override result of peer certificate verification.
4464 Net::SSLeay::set_verify_result($ssl, $v);
4466 # $ssl - value corresponding to openssl's SSL structure
4467 # $v - (integer) result value
4468 #
4469 # returns: no return value
4470 For more info about valid return values see "get_verify_result"
4472 Check openssl doc
4474 <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4475 · get_wbio
4477 Get 'write' BIO linked to an SSL object $ssl.
4479 my $rv = Net::SSLeay::get_wbio($ssl);
4481 # $ssl - value corresponding to openssl's SSL structure
4482 #
4483 # returns: value corresponding to openssl's BIO structure (0 on failure)
4484 Check openssl doc
4486 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4487 · load_client_CA_file
4489 Load X509 certificates from file (PEM formatted).
4491 my $rv = Net::SSLeay::load_client_CA_file($file);
4493 # $file - (string) file name
4494 #
4495 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4496 Check openssl doc
4498 <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4499 · clear_num_renegotiations
4501 Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4503 my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4505 # $ssl - value corresponding to openssl's SSL structure
4506 #
4507 # returns: command result
4508 · need_tmp_RSA
4510 Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4512 my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4514 # $ssl - value corresponding to openssl's SSL structure
4515 #
4516 # returns: command result
4517 Not available with OpenSSL 1.1 and later.
4519 · num_renegotiations
4521 Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4523 my $rv = Net::SSLeay::num_renegotiations($ssl);
4525 # $ssl - value corresponding to openssl's SSL structure
4526 #
4527 # returns: command result
4528 · total_renegotiations
4530 Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4532 my $rv = Net::SSLeay::total_renegotiations($ssl);
4534 # $ssl - value corresponding to openssl's SSL structure
4535 #
4536 # returns: command result
4537 · peek
4539 Copies $max bytes from the specified $ssl into the returned value.
4541 In contrast to the "Net::SSLeay::read()" function, the data in the
4542 SSL buffer is unmodified after the SSL_peek() operation.
4543 Net::SSLeay::peek($ssl, $max);
4545 # $ssl - value corresponding to openssl's SSL structure
4546 # $max - [optional] max bytes to peek (integer) - default is 32768
4547 #
4548 # in scalar context: data read from the TLS/SSL connection, undef on error
4549 # in list context: two-item array consisting of data read (undef on error),
4550 # and return code from SSL_peek().
4551 · peek_ex
4553 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4555 requires at least OpenSSL 1.1.1, not in LibreSSL
4556 Copies $max bytes from the specified $ssl into the returned value.
4558 In contrast to the "Net::SSLeay::read_ex()" function, the data in
4559 the SSL buffer is unmodified after the SSL_peek_ex() operation.
4560 my($got, $rv) = Net::SSLeay::peek_ex($ssl, $max);
4562 # $ssl - value corresponding to openssl's SSL structure
4563 # $max - [optional] max bytes to peek (integer) - default is 32768
4564 #
4565 # returns a list: two-item list consisting of data read (undef on error),
4566 # and return code from SSL_peek_ex().
4567 Check openssl doc
4569 <https://www.openssl.org/docs/manmaster/man3/SSL_peek_ex.html>
4570 · pending
4572 Obtain number of readable bytes buffered in $ssl object.
4574 my $rv = Net::SSLeay::pending($ssl);
4576 # $ssl - value corresponding to openssl's SSL structure
4577 #
4578 # returns: the number of bytes pending
4579 Check openssl doc
4581 <http://www.openssl.org/docs/ssl/SSL_pending.html>
4582 · has_pending
4584 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4586 requires at least OpenSSL 1.1.0, not in LibreSSL
4587 Returns 1 if $ssl has buffered data (whether processed or
4589 unprocessed) and 0 otherwise.
4590 my $rv = Net::SSLeay::has_pending($ssl);
4592 # $ssl - value corresponding to openssl's SSL structure
4593 #
4594 # returns: (integer) 1 or 0
4595 Check openssl doc
4597 <https://www.openssl.org/docs/manmaster/man3/SSL_has_pending.html>
4598 · read
4600 Tries to read $max bytes from the specified $ssl.
4602 my $got = Net::SSLeay::read($ssl, $max);
4604 my($got, $rv) = Net::SSLeay::read($ssl, $max);
4605 # $ssl - value corresponding to openssl's SSL structure
4606 # $max - [optional] max bytes to read (integer) - default is 32768
4607 #
4608 # returns:
4609 # in scalar context: data read from the TLS/SSL connection, undef on error
4610 # in list context: two-item array consisting of data read (undef on error),
4611 # and return code from SSL_read().
4612 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4614 · read_ex
4616 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4618 requires at least OpenSSL 1.1.1, not in LibreSSL
4619 Tries to read $max bytes from the specified $ssl.
4621 my($got, $rv) = Net::SSLeay::read_ex($ssl, $max);
4623 # $ssl - value corresponding to openssl's SSL structure
4624 # $max - [optional] max bytes to read (integer) - default is 32768
4625 #
4626 # returns a list: two-item list consisting of data read (undef on error),
4627 # and return code from SSL_read_ex().
4628 Check openssl doc
4630 <https://www.openssl.org/docs/manmaster/man3/SSL_read_ex.html>
4631 · renegotiate
4633 Turn on flags for renegotiation so that renegotiation will happen
4635 my $rv = Net::SSLeay::renegotiate($ssl);
4637 # $ssl - value corresponding to openssl's SSL structure
4638 #
4639 # returns: 1 on success, 0 on failure
4640 · rstate_string
4642 Returns a 2 letter string indicating the current read state of the
4644 SSL object $ssl.
4645 my $rv = Net::SSLeay::rstate_string($ssl);
4647 # $ssl - value corresponding to openssl's SSL structure
4648 #
4649 # returns: 2-letter string
4650 Check openssl doc
4652 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4653 · rstate_string_long
4655 Returns a string indicating the current read state of the SSL
4657 object ssl.
4658 my $rv = Net::SSLeay::rstate_string_long($ssl);
4660 # $ssl - value corresponding to openssl's SSL structure
4661 #
4662 # returns: string with current state
4663 Check openssl doc
4665 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4666 · session_reused
4668 Query whether a reused session was negotiated during handshake.
4670 my $rv = Net::SSLeay::session_reused($ssl);
4672 # $ssl - value corresponding to openssl's SSL structure
4673 #
4674 # returns: 0 - new session was negotiated; 1 - session was reused.
4675 Check openssl doc
4677 <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4678 · set1_param
4680 Applies X509 verification parameters $vpm on $ssl
4682 my $rv = Net::SSLeay::set1_param($ssl, $vpm);
4684 # $ssl - value corresponding to openssl's SSL structure
4685 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
4686 #
4687 # returns: 1 on success, 0 on failure
4688 · set_accept_state
4690 Sets $ssl to work in server mode.
4692 Net::SSLeay::set_accept_state($ssl);
4694 # $ssl - value corresponding to openssl's SSL structure
4695 #
4696 # returns: no return value
4697 Check openssl doc
4699 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4700 · set_bio
4702 Connects the BIOs $rbio and $wbio for the read and write operations
4704 of the TLS/SSL (encrypted) side of $ssl.
4705 Net::SSLeay::set_bio($ssl, $rbio, $wbio);
4707 # $ssl - value corresponding to openssl's SSL structure
4708 # $rbio - value corresponding to openssl's BIO structure
4709 # $wbio - value corresponding to openssl's BIO structure
4710 #
4711 # returns: no return value
4712 Check openssl doc
4714 <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4715 · set_cipher_list
4717 Sets the list of ciphers only for ssl.
4719 my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
4721 # $ssl - value corresponding to openssl's SSL structure
4722 # $str - (string) cipher list e.g. '3DES:+RSA'
4723 #
4724 # returns: 1 if any cipher could be selected and 0 on complete failure
4725 Check openssl doc
4727 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4728 · set_ciphersuites
4730 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4732 requires at least OpenSSL 1.1.1, not in LibreSSL
4733 Configure the available TLSv1.3 ciphersuites.
4735 my $rv = Net::SSLeay::set_ciphersuites($ssl, $str);
4737 # $ssl - value corresponding to openssl's SSL structure
4738 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
4739 #
4740 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
4741 Check openssl doc
4743 <https://www.openssl.org/docs/manmaster/man3/SSL_set_ciphersuites.html>
4744 · set_client_CA_list
4746 Sets the list of CAs sent to the client when requesting a client
4748 certificate for the chosen $ssl, overriding the setting valid for
4749 $ssl's SSL_CTX object.
4750 my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
4752 # $ssl - value corresponding to openssl's SSL structure
4753 # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
4754 #
4755 # returns: no return value
4756 Check openssl doc
4758 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4759 · set_connect_state
4761 Sets $ssl to work in client mode.
4763 Net::SSLeay::set_connect_state($ssl);
4765 # $ssl - value corresponding to openssl's SSL structure
4766 #
4767 # returns: no return value
4768 Check openssl doc
4770 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4771 · set_fd
4773 Sets the file descriptor $fd as the input/output facility for the
4775 TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
4776 file descriptor of a network connection.
4777 my $rv = Net::SSLeay::set_fd($ssl, $fd);
4779 # $ssl - value corresponding to openssl's SSL structure
4780 # $fd - (integer) file handle (got via perl's fileno)
4781 #
4782 # returns: 1 on success, 0 on failure
4783 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4785 · set_psk_client_callback
4787 Sets the psk client callback.
4789 Net::SSLeay::set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4791 # $ssl - value corresponding to openssl's SSL structure
4792 # $hint - PSK identity hint send by the server
4793 # $identity - PSK identity
4794 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4795 #
4796 # returns: no return value
4797 Check openssl doc
4799 <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
4800 · set_rfd
4802 Sets the file descriptor $fd as the input (read) facility for the
4804 TLS/SSL (encrypted) side of $ssl.
4805 my $rv = Net::SSLeay::set_rfd($ssl, $fd);
4807 # $ssl - value corresponding to openssl's SSL structure
4808 # $fd - (integer) file handle (got via perl's fileno)
4809 #
4810 # returns: 1 on success, 0 on failure
4811 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4813 · set_wfd
4815 my $rv = Net::SSLeay::set_wfd($ssl, $fd);
4817 # $ssl - value corresponding to openssl's SSL structure
4818 # $fd - (integer) file handle (got via perl's fileno)
4819 #
4820 # returns: 1 on success, 0 on failure
4821 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4823 · set_info_callback
4825 Sets the callback function, that can be used to obtain state
4827 information for $ssl during connection setup and use. When
4828 callback is undef, the callback setting currently valid for ctx is
4829 used.
4830 Net::SSLeay::set_info_callback($ssl, $cb, [$data]);
4832 # $ssl - value corresponding to openssl's SSL structure
4833 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4834 #
4835 # returns: no return value
4836 Check openssl doc
4838 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4839 · CTX_set_info_callback
4841 Sets the callback function on ctx, that can be used to obtain state
4843 information during ssl connection setup and use. When callback is
4844 undef, an existing callback will be disabled.
4845 Net::SSLeay::CTX_set_info_callback($ssl, $cb, [$data]);
4847 # $ssl - value corresponding to openssl's SSL structure
4848 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4849 #
4850 # returns: no return value
4851 Check openssl doc
4853 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4854 · set_pref_cipher
4856 Sets the list of available ciphers for $ssl using the control
4858 string $str.
4859 my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
4861 # $ssl - value corresponding to openssl's SSL structure
4862 # $str - (string) cipher list e.g. '3DES:+RSA'
4863 #
4864 # returns: 1 if any cipher could be selected and 0 on complete failure
4865 Check openssl doc
4867 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4868 · CTX_set_psk_client_callback
4870 Sets the psk client callback.
4872 Net::SSLeay::CTX_set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4874 # $ssl - value corresponding to openssl's SSL structure
4875 # $hint - PSK identity hint send by the server
4876 # $identity - PSK identity
4877 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4878 #
4879 # returns: no return value
4880 Check openssl doc
4882 <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
4883 · set_purpose
4885 my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
4887 # $ssl - value corresponding to openssl's SSL structure
4888 # $purpose - (integer) purpose identifier
4889 #
4890 # returns: 1 on success, 0 on failure
4891 For more info about available $purpose identifiers see
4893 "CTX_set_purpose".
4894 · set_quiet_shutdown
4896 Sets the 'quiet shutdown' flag for $ssl to be $mode.
4898 Net::SSLeay::set_quiet_shutdown($ssl, $mode);
4900 # $ssl - value corresponding to openssl's SSL structure
4901 # $mode - 0 or 1
4902 #
4903 # returns: no return value
4904 Check openssl doc
4906 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4907 · set_session
4909 Set a TLS/SSL session to be used during TLS/SSL connect.
4911 my $rv = Net::SSLeay::set_session($to, $ses);
4913 # $to - value corresponding to openssl's SSL structure
4914 # $ses - value corresponding to openssl's SSL_SESSION structure
4915 #
4916 # returns: 1 on success, 0 on failure
4917 Check openssl doc
4919 <http://www.openssl.org/docs/ssl/SSL_set_session.html>
4920 · set_session_id_context
4922 Sets the context $sid_ctx of length $sid_ctx_len within which a
4924 session can be reused for the $ssl object.
4925 my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
4927 # $ssl - value corresponding to openssl's SSL structure
4928 # $sid_ctx - data buffer
4929 # $sid_ctx_len - length of data in $sid_ctx
4930 #
4931 # returns: 1 on success, 0 on failure
4932 Check openssl doc
4934 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
4935 · set_session_secret_cb
4937 Setup pre-shared secret session resumption function.
4939 Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
4941 # $ssl - value corresponding to openssl's SSL structure
4942 # $func - perl reference to callback function
4943 # $data - [optional] data that will be passed to callback function when invoked
4944 #
4945 # returns: no return value
4946 The callback function will be called like:
4948 callback_function($secret, $ciphers, $pref_cipher, $data);
4949 # $secret is the current master session key, usually all 0s at the
4951 beginning of a session # $ciphers is ref to an array of peer cipher
4952 names # $pref_cipher is a ref to an index into the list of cipher
4953 names of # the preferred cipher. Set it if you want to specify a
4954 preferred cipher # $data is the data passed to
4955 set_session_secret_cb
4956 The callback function should return 1 if it likes the suggested
4958 cipher (or has selected an alternative by setting pref_cipher),
4959 else it should return 0 (in which case OpenSSL will select its own
4960 preferred cipher).
4961 With OpenSSL 1.1 and later, callback_function can change the master
4963 key for the session by altering $secret and returning 1.
4964 · CTX_set_tlsext_ticket_getkey_cb
4966 Setup encryption for TLS session tickets (stateless session reuse).
4968 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($ctx, $func, $data);
4970 # $ctx - value corresponding to openssl's SSL_CTX structure
4971 # $func - perl reference to callback function
4972 # $data - [optional] data that will be passed to callback function when invoked
4973 #
4974 # returns: no return value
4975 The callback function will be called like:
4977 getkey($data,[$key_name]) -> ($key,$current_key_name)
4978 # $data is the data passed to set_session_secret_cb # $key_name is
4980 the name of the key OpenSSL has extracted from the session ticket #
4981 $key is the requested key for ticket encryption + HMAC #
4982 $current_key_name is the name for the currently valid key
4983 OpenSSL will call the function without a key name if it generates a
4985 new ticket. It then needs the callback to return the
4986 encryption+HMAC key and an identifier (key name) for this key.
4987 When OpenSSL gets a session ticket from the client it extracts the
4989 key name and calls the callback with this name as argument. It then
4990 expects the callback to return the encryption+HMAC key matching the
4991 requested key name and and also the key name which should be used
4992 at the moment. If the requested key name and the returned key name
4993 differ it means that this session ticket was created with an
4994 expired key and need to be renewed. In this case OpenSSL will call
4995 the callback again with no key name to create a new session ticket
4996 based on the old one.
4997 The key must be at least 32 byte of random data which can be
4999 created with RAND_bytes. Internally the first 16 byte are used as
5000 key in AES-128 encryption while the next 16 byte are used for the
5001 SHA-256 HMAC. The key name are binary data and must be exactly 16
5002 byte long.
5003 Example:
5005 Net::SSLeay::RAND_bytes(my $oldkey,32);
5007 Net::SSLeay::RAND_bytes(my $newkey,32);
5008 my $oldkey_name = pack("a16",'oldsecret');
5009 my $newkey_name = pack("a16",'newsecret');
5010 my @keys = (
5012 [ $newkey_name, $newkey ], # current active key
5013 [ $oldkey_name, $oldkey ], # already expired
5014 );
5015 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
5017 my ($mykeys,$name) = @_;
5018 # return (current_key, current_key_name) if no name given
5020 return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
5021 # return (matching_key, current_key_name) if we find a key matching
5023 # the given name
5024 for(my $i = 0; $i<@$mykeys; $i++) {
5025 next if $name ne $mykeys->[$i][0];
5026 return ($mykeys->[$i][1],$mykeys->[0][0]);
5027 }
5028 # no matching key found
5030 return;
5031 },\@keys);
5032 This function is based on the OpenSSL function
5034 SSL_CTX_set_tlsext_ticket_key_cb but provides a simpler to use
5035 interface. For more information see
5036 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tlsext_ticket_key_cb.html>
5037 · set_session_ticket_ext_cb
5039 Setup callback for TLS session tickets (stateless session reuse).
5041 Net::SSLeay::set_session_ticket_ext_cb($ssl, $func, $data);
5043 # $ssl - value corresponding to openssl's SSL structure
5044 # $func - perl reference to callback function
5045 # $data - [optional] data that will be passed to callback function when invoked
5046 #
5047 # returns: no return value
5048 The callback function will be called like:
5050 getticket($ssl,$ticket,$data) -> $return_value
5051 # $ssl is a value corresponding to openssl's SSL structure #
5053 $ticket is a value of received TLS session ticket (can also be
5054 empty) # $data is the data passed to set_session_ticket_ext_cb #
5055 $return_value is either 0 (failure) or 1 (success)
5056 This function is based on the OpenSSL function
5058 SSL_set_session_ticket_ext_cb.
5059 · set_session_ticket_ext
5061 Set TLS session ticket (stateless session reuse).
5063 Net::SSLeay::set_session_ticket_ext($ssl, $ticket);
5065 # $ssl - value corresponding to openssl's SSL structure
5066 # $ticket - is a value of TLS session ticket which client will send (can also be empty string)
5067 #
5068 # returns: no return value
5069 The callback function will be called like:
5071 getticket($ssl,$ticket,$data) -> $return_value
5072 # $ssl is a value corresponding to openssl's SSL structure #
5074 $ticket is a value of received TLS session ticket (can also be
5075 empty) # $data is the data passed to set_session_ticket_ext_cb #
5076 $return_value is either 0 (failure) or 1 (success)
5077 This function is based on the OpenSSL function
5079 SSL_set_session_ticket_ext_cb.
5080 · set_shutdown
5082 Sets the shutdown state of $ssl to $mode.
5084 Net::SSLeay::set_shutdown($ssl, $mode);
5086 # $ssl - value corresponding to openssl's SSL structure
5087 # $mode - (integer) shutdown mode:
5088 # 0 - No shutdown
5089 # 1 - SSL_SENT_SHUTDOWN
5090 # 2 - SSL_RECEIVED_SHUTDOWN
5091 # 3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
5092 #
5093 # returns: no return value
5094 Check openssl doc
5096 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
5097 · set_ssl_method
5099 Sets a new TLS/SSL method for a particular $ssl object.
5101 my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
5103 # $ssl - value corresponding to openssl's SSL structure
5104 # $method - value corresponding to openssl's SSL_METHOD structure
5105 #
5106 # returns: 1 on success, 0 on failure
5107 Check openssl doc
5109 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
5110 · set_tmp_dh
5112 Sets DH parameters to be used to be $dh.
5114 my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
5116 # $ssl - value corresponding to openssl's SSL structure
5117 # $dh - value corresponding to openssl's DH structure
5118 #
5119 # returns: 1 on success, 0 on failure
5120 Check openssl doc
5122 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5123 · set_tmp_dh_callback
5125 Sets the callback function for $ssl to be used when a DH parameters
5127 are required to $dh_cb.
5128 ??? (does this function really work?)
5130 Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
5132 # $ssl - value corresponding to openssl's SSL structure
5133 # $dh_cb - pointer to function ???
5134 #
5135 # returns: no return value
5136 Check openssl doc
5138 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5139 · set_tmp_rsa
5141 Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
5143 my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
5145 # $ssl - value corresponding to openssl's SSL structure
5146 # $rsa - value corresponding to openssl's RSA structure
5147 #
5148 # returns: 1 on success, 0 on failure
5149 Example:
5151 $rsakey = Net::SSLeay::RSA_generate_key();
5153 Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
5154 Net::SSLeay::RSA_free($rsakey);
5155 Check openssl doc
5157 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5158 · set_tmp_rsa_callback
5160 Sets the callback function for $ssl to be used when a
5162 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
5163 ??? (does this function really work?)
5165 Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
5167 # $ssl - value corresponding to openssl's SSL structure
5168 # $tmp_rsa_callback - (function pointer) ???
5169 #
5170 # returns: no return value
5171 Check openssl doc
5173 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5174 · set_trust
5176 my $rv = Net::SSLeay::set_trust($ssl, $trust);
5178 # $ssl - value corresponding to openssl's SSL structure
5179 # $trust - (integer) trust identifier
5180 #
5181 # returns: the original value
5182 For more details about $trust values see "CTX_set_trust".
5184 · shutdown
5186 Shuts down an active TLS/SSL connection. It sends the 'close
5188 notify' shutdown alert to the peer.
5189 my $rv = Net::SSLeay::shutdown($ssl);
5191 # $ssl - value corresponding to openssl's SSL structure
5192 #
5193 # returns: 1 - shutdown was successfully completed
5194 # 0 - shutdown is not yet finished,
5195 # -1 - shutdown was not successful
5196 Check openssl doc
5198 <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
5199 · state_string
5201 Returns a 6 letter string indicating the current state of the SSL
5203 object $ssl.
5204 my $rv = Net::SSLeay::state_string($ssl);
5206 # $ssl - value corresponding to openssl's SSL structure
5207 #
5208 # returns: 6-letter string
5209 Check openssl doc
5211 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5212 · state_string_long
5214 Returns a string indicating the current state of the SSL object
5216 $ssl.
5217 my $rv = Net::SSLeay::state_string_long($ssl);
5219 # $ssl - value corresponding to openssl's SSL structure
5220 #
5221 # returns: state strings
5222 Check openssl doc
5224 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5225 · set_default_passwd_cb
5227 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5229 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5230 Sets the default password callback called when loading/storing a
5232 PEM certificate with encryption for $ssl.
5233 Net::SSLeay::set_default_passwd_cb($ssl, $func);
5235 # $ssl - value corresponding to openssl's SSL structure
5236 # $func - perl reference to callback function
5237 #
5238 # returns: no return value
5239 Check openssl doc
5241 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5242 · set_default_passwd_cb_userdata
5244 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5246 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5247 Sets a pointer to userdata which will be provided to the password
5249 callback of $ssl on invocation.
5250 Net::SSLeay::set_default_passwd_cb_userdata($ssl, $userdata);
5252 # $ssl - value corresponding to openssl's SSL structure
5253 # $userdata - data that will be passed to callback function when invoked
5254 #
5255 # returns: no return value
5256 Check openssl doc
5258 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5259 · use_PrivateKey
5261 Adds $pkey as private key to $ssl.
5263 my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
5265 # $ssl - value corresponding to openssl's SSL structure
5266 # $pkey - value corresponding to openssl's EVP_PKEY structure
5267 #
5268 # returns: 1 on success, otherwise check out the error stack to find out the reason
5269 Check openssl doc
5271 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5272 · use_PrivateKey_ASN1
5274 Adds the private key of type $pk stored in $data to $ssl.
5276 my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
5278 # $pk - (integer) key type, NID of corresponding algorithm
5279 # $ssl - value corresponding to openssl's SSL structure
5280 # $data - key data (binary)
5281 # $len - length of $data
5282 #
5283 # returns: 1 on success, otherwise check out the error stack to find out the reason
5284 Check openssl doc
5286 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5287 · use_PrivateKey_file
5289 Adds the first private key found in $file to $ssl.
5291 my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
5293 # $ssl - value corresponding to openssl's SSL structure
5294 # $file - (string) file name
5295 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5296 #
5297 # returns: 1 on success, otherwise check out the error stack to find out the reason
5298 Check openssl doc
5300 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5301 · use_RSAPrivateKey
5303 Adds $rsa as RSA private key to $ssl.
5305 my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
5307 # $ssl - value corresponding to openssl's SSL structure
5308 # $rsa - value corresponding to openssl's RSA structure
5309 #
5310 # returns: 1 on success, otherwise check out the error stack to find out the reason
5311 Check openssl doc
5313 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5314 · use_RSAPrivateKey_ASN1
5316 Adds RSA private key stored in $data to $ssl.
5318 my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
5320 # $ssl - value corresponding to openssl's SSL structure
5321 # $data - key data (binary)
5322 # $len - length of $data
5323 #
5324 # returns: 1 on success, otherwise check out the error stack to find out the reason
5325 Check openssl doc
5327 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5328 · use_RSAPrivateKey_file
5330 Adds the first RSA private key found in $file to $ssl.
5332 my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
5334 # $ssl - value corresponding to openssl's SSL structure
5335 # $file - (string) file name
5336 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5337 #
5338 # returns: 1 on success, otherwise check out the error stack to find out the reason
5339 Check openssl doc
5341 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5342 · use_certificate
5344 Loads the certificate $x into $ssl.
5346 my $rv = Net::SSLeay::use_certificate($ssl, $x);
5348 # $ssl - value corresponding to openssl's SSL structure
5349 # $x - value corresponding to openssl's X509 structure
5350 #
5351 # returns: 1 on success, otherwise check out the error stack to find out the reason
5352 Check openssl doc
5354 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5355 · use_certificate_ASN1
5357 Loads the ASN1 encoded certificate from $data to $ssl.
5359 my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
5361 # $ssl - value corresponding to openssl's SSL structure
5362 # $data - certificate data (binary)
5363 # $len - length of $data
5364 #
5365 # returns: 1 on success, otherwise check out the error stack to find out the reason
5366 Check openssl doc
5368 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5369 · use_certificate_chain_file
5371 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5373 requires at least OpenSSL 1.1.0
5374 Loads a certificate chain from $file into $ssl. The certificates
5376 must be in PEM format and must be sorted starting with the
5377 subject's certificate (actual client or server certificate),
5378 followed by intermediate CA certificates if applicable, and ending
5379 at the highest level (root) CA.
5380 my $rv = Net::SSLeay::use_certificate_chain_file($ssl, $file);
5382 # $ssl - value corresponding to openssl's SSL structure
5383 # $file - (string) file name
5384 #
5385 # returns: 1 on success, otherwise check out the error stack to find out the reason
5386 Check openssl doc
5388 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5389 · use_certificate_file
5391 Loads the first certificate stored in $file into $ssl.
5393 my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
5395 # $ssl - value corresponding to openssl's SSL structure
5396 # $file - (string) file name
5397 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5398 #
5399 # returns: 1 on success, otherwise check out the error stack to find out the reason
5400 Check openssl doc
5402 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5403 · get_version
5405 Returns SSL/TLS protocol name
5407 my $rv = Net::SSLeay::get_version($ssl);
5409 # $ssl - value corresponding to openssl's SSL structure
5410 #
5411 # returns: (string) protocol name, see OpenSSL manual for the full list
5412 # TLSv1
5413 # TLSv1.3
5414 Check openssl doc
5416 <https://www.openssl.org/docs/manmaster/man3/SSL_get_version.html>
5417 · version
5419 Returns SSL/TLS protocol version
5421 my $rv = Net::SSLeay::version($ssl);
5423 # $ssl - value corresponding to openssl's SSL structure
5424 #
5425 # returns: (integer) protocol version, see OpenSSL manual for the full list
5426 # 0x0301 - TLS1_VERSION (TLSv1)
5427 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5428 Check openssl doc
5430 <https://www.openssl.org/docs/manmaster/man3/SSL_version.html>
5431 · client_version
5433 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5435 requires at least OpenSSL 1.1.0, not in LibreSSL
5436 Returns TLS protocol version used by the client when initiating the
5438 connection
5439 my $rv = Net::SSLeay::client_version($ssl);
5441 # $ssl - value corresponding to openssl's SSL structure
5442 #
5443 # returns: (integer) protocol version, see OpenSSL manual for the full list
5444 # 0x0301 - TLS1_VERSION (TLSv1)
5445 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5446 Check openssl doc
5448 <https://www.openssl.org/docs/manmaster/man3/SSL_client_version.html>
5449 · is_dtls
5451 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5453 requires at least OpenSSL 1.1.0, not in LibreSSL
5454 my $rv = Net::SSLeay::is_dtls($ssl);
5456 # $ssl - value corresponding to openssl's SSL structure
5457 #
5458 # returns: (integer) zero or one
5459 # 0 - connection is not using DTLS
5460 # 1 - connection is using DTLS
5461 Check openssl doc
5463 <https://www.openssl.org/docs/manmaster/man3/SSL_is_dtls.html>
5464 · want
5466 Returns state information for the SSL object $ssl.
5468 my $rv = Net::SSLeay::want($ssl);
5470 # $ssl - value corresponding to openssl's SSL structure
5471 #
5472 # returns: state
5473 # 1 - SSL_NOTHING
5474 # 2 - SSL_WRITING
5475 # 3 - SSL_READING
5476 # 4 - SSL_X509_LOOKUP
5477 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5479 · write
5481 Writes data from the buffer $data into the specified $ssl
5483 connection.
5484 my $rv = Net::SSLeay::write($ssl, $data);
5486 # $ssl - value corresponding to openssl's SSL structure
5487 # $data - data to be written
5488 #
5489 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5490 # 0 - write not successful, probably the underlying connection was closed
5491 # <0 - error
5492 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5494 · write_ex
5496 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5498 requires at least OpenSSL 1.1.1, not in LibreSSL
5499 Writes data from the buffer $data into the specified $ssl
5501 connection.
5502 my ($len, $rv) = Net::SSLeay::write_ex($ssl, $data);
5504 # $ssl - value corresponding to openssl's SSL structure
5505 # $data - data to be written
5506 #
5507 # returns a list: two-item list consisting of number of bytes written,
5508 # and return code from SSL_write_ex()
5509 Check openssl doc
5511 <https://www.openssl.org/docs/manmaster/man3/SSL_write_ex.html>
5512 · write_partial
5514 NOTE: Does not exactly correspond to any low level API function
5516 Writes a fragment of data in $data from the buffer $data into the
5518 specified $ssl connection. This is a non-blocking function like
5519 Net::SSLeay::write().
5520 my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
5522 # $ssl - value corresponding to openssl's SSL structure
5523 # $from - (integer) offset from the beginning of $data
5524 # $count - (integer) length of data to be written
5525 # $data - data buffer
5526 #
5527 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5528 # 0 - write not successful, probably the underlying connection was closed
5529 # <0 - error
5530 · set_tlsext_host_name
5532 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5534 requires at least openssl-0.9.8f
5535 Sets TLS servername extension on SLL object $ssl to value $name.
5537 my $rv = set_tlsext_host_name($ssl, $name);
5539 # $ssl - value corresponding to openssl's SSL structure
5540 # $name - (string) name to be set
5541 #
5542 # returns: 1 on success, 0 on failure
5543 Low level API: RAND_* related functions
5545 Check openssl doc related to RAND stuff
5547 <http://www.openssl.org/docs/crypto/rand.html>
5548 · RAND_add
5550 Mixes the $num bytes at $buf into the PRNG state.
5552 Net::SSLeay::RAND_add($buf, $num, $entropy);
5554 # $buf - buffer with data to be mixed into the PRNG state
5555 # $num - number of bytes in $buf
5556 # $entropy - estimate of how much randomness is contained in $buf (in bytes)
5557 #
5558 # returns: no return value
5559 Check openssl doc
5561 <http://www.openssl.org/docs/crypto/RAND_add.html>
5562 · RAND_seed
5564 Equivalent to "RAND_add" when $num == $entropy.
5566 Net::SSLeay::RAND_seed($buf); # Perlishly figures out buf size
5568 # $buf - buffer with data to be mixed into the PRNG state
5569 # $num - number of bytes in $buf
5570 #
5571 # returns: no return value
5572 Check openssl doc
5574 <http://www.openssl.org/docs/crypto/RAND_add.html>
5575 · RAND_status
5577 Gives PRNG status (seeded enough or not).
5579 my $rv = Net::SSLeay::RAND_status();
5581 #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5582 Check openssl doc
5584 <http://www.openssl.org/docs/crypto/RAND_add.html>
5585 · RAND_bytes
5587 Puts $num cryptographically strong pseudo-random bytes into $buf.
5589 my $rv = Net::SSLeay::RAND_bytes($buf, $num);
5591 # $buf - buffer where the random data will be stored
5592 # $num - the size (in bytes) of requested random data
5593 #
5594 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5595 Check openssl doc
5597 <http://www.openssl.org/docs/manmaster/man3/RAND_bytes.html>
5598 · RAND_priv_bytes
5600 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5602 requires at least OpenSSL 1.1.1, not in LibreSSL
5603 Puts $num cryptographically strong pseudo-random bytes into $buf.
5605 my $rv = Net::SSLeay::RAND_priv_bytes($buf, $num);
5607 # $buf - buffer where the random data will be stored
5608 # $num - the size (in bytes) of requested random data
5609 #
5610 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5611 RAND_priv_bytes has the same semantics as RAND_bytes, but see see
5613 the documentation for more information.
5614 Check openssl doc
5616 <http://www.openssl.org/docs/manmaster/man3/RAND_priv_bytes.html>
5617 · RAND_pseudo_bytes
5619 Puts $num pseudo-random (not necessarily unpredictable) bytes into
5621 $buf.
5622 my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
5624 # $buf - buffer where the random data will be stored
5625 # $num - the size (in bytes) of requested random data
5626 #
5627 # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
5628 Check openssl doc
5630 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5631 · RAND_cleanup
5633 Erase the PRNG state.
5635 Net::SSLeay::RAND_cleanup();
5637 # no args, no return value
5638 Check openssl doc
5640 <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5641 · RAND_egd_bytes
5643 Queries the entropy gathering daemon EGD on socket $path for $bytes
5645 bytes.
5646 my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
5648 # $path - path to a socket of entropy gathering daemon EGD
5649 # $bytes - number of bytes we want from EGD
5650 #
5651 # returns: the number of bytes read from the daemon on success, and -1 on failure
5652 Check openssl doc
5654 <http://www.openssl.org/docs/crypto/RAND_egd.html>
5655 · RAND_file_name
5657 Generates a default path for the random seed file.
5659 my $file = Net::SSLeay::RAND_file_name($num);
5661 # $num - maximum size of returned file name
5662 #
5663 # returns: string with file name on success, '' (empty string) on failure
5664 Check openssl doc
5666 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5667 · RAND_load_file
5669 COMPATIBILITY: Is no longer functional on LibreSSL
5671 Reads $max_bytes of bytes from $file_name and adds them to the
5673 PRNG.
5674 my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
5676 # $file_name - the name of file
5677 # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
5678 #
5679 # returns: the number of bytes read
5680 Check openssl doc
5682 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5683 · RAND_write_file
5685 Writes 1024 random bytes to $file_name which can be used to
5687 initialize the PRNG by calling "RAND_load_file" in a later session.
5688 my $rv = Net::SSLeay::RAND_write_file($file_name);
5690 # $file_name - the name of file
5691 #
5692 # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
5693 Check openssl doc
5695 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5696 · RAND_poll
5698 Collects some entropy from operating system and adds it to the
5700 PRNG.
5701 my $rv = Net::SSLeay::RAND_poll();
5703 # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5704 Low level API: OBJ_* related functions
5706 · OBJ_cmp
5708 Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5710 my $rv = Net::SSLeay::OBJ_cmp($a, $b);
5712 # $a - value corresponding to openssl's ASN1_OBJECT structure
5713 # $b - value corresponding to openssl's ASN1_OBJECT structure
5714 #
5715 # returns: if the two are identical 0 is returned
5716 Check openssl doc
5718 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5719 · OBJ_dup
5721 Returns a copy/duplicate of $o.
5723 my $rv = Net::SSLeay::OBJ_dup($o);
5725 # $o - value corresponding to openssl's ASN1_OBJECT structure
5726 #
5727 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5728 Check openssl doc
5730 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5731 · OBJ_nid2ln
5733 Returns long name for given NID $n.
5735 my $rv = Net::SSLeay::OBJ_nid2ln($n);
5737 # $n - (integer) NID
5738 #
5739 # returns: (string) long name e.g. 'commonName'
5740 Check openssl doc
5742 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5743 · OBJ_ln2nid
5745 Returns NID corresponding to given long name $n.
5747 my $rv = Net::SSLeay::OBJ_ln2nid($s);
5749 # $s - (string) long name e.g. 'commonName'
5750 #
5751 # returns: (integer) NID
5752 · OBJ_nid2sn
5754 Returns short name for given NID $n.
5756 my $rv = Net::SSLeay::OBJ_nid2sn($n);
5758 # $n - (integer) NID
5759 #
5760 # returns: (string) short name e.g. 'CN'
5761 Example:
5763 print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
5765 · OBJ_sn2nid
5767 Returns NID corresponding to given short name $s.
5769 my $rv = Net::SSLeay::OBJ_sn2nid($s);
5771 # $s - (string) short name e.g. 'CN'
5772 #
5773 # returns: (integer) NID
5774 Example:
5776 print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
5778 print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
5779 · OBJ_nid2obj
5781 Returns ASN1_OBJECT for given NID $n.
5783 my $rv = Net::SSLeay::OBJ_nid2obj($n);
5785 # $n - (integer) NID
5786 #
5787 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5788 Check openssl doc
5790 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5791 · OBJ_obj2nid
5793 Returns NID corresponding to given ASN1_OBJECT $o.
5795 my $rv = Net::SSLeay::OBJ_obj2nid($o);
5797 # $o - value corresponding to openssl's ASN1_OBJECT structure
5798 #
5799 # returns: (integer) NID
5800 Check openssl doc
5802 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5803 · OBJ_txt2obj
5805 Converts the text string s into an ASN1_OBJECT structure. If
5807 $no_name is 0 then long names (e.g. 'commonName') and short names
5808 (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
5809 '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
5810 my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
5812 # $s - text string to be converted
5813 # $no_name - (integer) 0 or 1
5814 #
5815 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5816 Check openssl doc
5818 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5819 · OBJ_obj2txt
5821 Converts the ASN1_OBJECT a into a textual representation.
5823 Net::SSLeay::OBJ_obj2txt($a, $no_name);
5825 # $a - value corresponding to openssl's ASN1_OBJECT structure
5826 # $no_name - (integer) 0 or 1
5827 #
5828 # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
5829 Check openssl doc
5831 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5832 · OBJ_txt2nid
5834 Returns NID corresponding to text string $s which can be a long
5836 name, a short name or the numerical representation of an object.
5837 my $rv = Net::SSLeay::OBJ_txt2nid($s);
5839 # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
5840 #
5841 # returns: (integer) NID
5842 Example:
5844 my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
5846 Net::SSLeay::OBJ_nid2sn($n);
5847 Check openssl doc
5849 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5850 Low level API: ASN1_INTEGER_* related functions
5852 · ASN1_INTEGER_new
5854 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5856 Creates a new ASN1_INTEGER structure.
5858 my $rv = Net::SSLeay::ASN1_INTEGER_new();
5860 #
5861 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
5862 · ASN1_INTEGER_free
5864 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5866 Free an allocated ASN1_INTEGER structure.
5868 Net::SSLeay::ASN1_INTEGER_free($i);
5870 # $i - value corresponding to openssl's ASN1_INTEGER structure
5871 #
5872 # returns: no return value
5873 · ASN1_INTEGER_get
5875 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5877 Returns integer value of given ASN1_INTEGER object.
5879 BEWARE: If the value stored in ASN1_INTEGER is greater than max.
5881 integer that can be stored in 'long' type (usually 32bit but may
5882 vary according to platform) then this function will return -1. For
5883 getting large ASN1_INTEGER values consider using
5884 "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
5885 my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
5887 # $a - value corresponding to openssl's ASN1_INTEGER structure
5888 #
5889 # returns: integer value of ASN1_INTEGER object in $a
5890 · ASN1_INTEGER_set
5892 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5894 Sets value of given ASN1_INTEGER object to value $val
5896 BEWARE: $val has max. limit (= max. integer that can be stored in
5898 'long' type). For setting large ASN1_INTEGER values consider using
5899 "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
5900 my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
5902 # $i - value corresponding to openssl's ASN1_INTEGER structure
5903 # $val - integer value
5904 #
5905 # returns: 1 on success, 0 on failure
5906 · P_ASN1_INTEGER_get_dec
5908 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5910 Returns string with decimal representation of integer value of
5912 given ASN1_INTEGER object.
5913 Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
5915 # $i - value corresponding to openssl's ASN1_INTEGER structure
5916 #
5917 # returns: string with decimal representation
5918 · P_ASN1_INTEGER_get_hex
5920 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5922 Returns string with hexadecimal representation of integer value of
5924 given ASN1_INTEGER object.
5925 Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
5927 # $i - value corresponding to openssl's ASN1_INTEGER structure
5928 #
5929 # returns: string with hexadecimal representation
5930 · P_ASN1_INTEGER_set_dec
5932 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5934 Sets value of given ASN1_INTEGER object to value $val (decimal
5936 string, suitable for large integers)
5937 Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
5939 # $i - value corresponding to openssl's ASN1_INTEGER structure
5940 # $str - string with decimal representation
5941 #
5942 # returns: 1 on success, 0 on failure
5943 · P_ASN1_INTEGER_set_hex
5945 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5947 Sets value of given ASN1_INTEGER object to value $val (hexadecimal
5949 string, suitable for large integers)
5950 Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
5952 # $i - value corresponding to openssl's ASN1_INTEGER structure
5953 # $str - string with hexadecimal representation
5954 #
5955 # returns: 1 on success, 0 on failure
5956 Low level API: ASN1_STRING_* related functions
5958 · P_ASN1_STRING_get
5960 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5962 Returns string value of given ASN1_STRING object.
5964 Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
5966 # $s - value corresponding to openssl's ASN1_STRING structure
5967 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
5968 #
5969 # returns: string
5970 $string = Net::SSLeay::P_ASN1_STRING_get($s);
5972 #is the same as:
5973 $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
5974 Low level API: ASN1_TIME_* related functions
5976 · ASN1_TIME_new
5978 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5980 my $time = ASN1_TIME_new();
5982 # returns: value corresponding to openssl's ASN1_TIME structure
5983 · ASN1_TIME_free
5985 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5987 ASN1_TIME_free($time);
5989 # $time - value corresponding to openssl's ASN1_TIME structure
5990 · ASN1_TIME_set
5992 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5994 ASN1_TIME_set($time, $t);
5996 # $time - value corresponding to openssl's ASN1_TIME structure
5997 # $t - time value in seconds since 1.1.1970
5998 BEWARE: It is platform dependent how this function will handle
6000 dates after 2038. Although perl's integer is large enough the
6001 internal implementation of this function is dependent on the size
6002 of time_t structure (32bit time_t has problem with 2038).
6003 If you want to safely set date and time after 2038 use function
6005 "P_ASN1_TIME_set_isotime".
6006 · P_ASN1_TIME_get_isotime
6008 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6010 requires at least openssl-0.9.7e
6011 NOTE: Does not exactly correspond to any low level API function
6013 Gives ISO-8601 string representation of ASN1_TIME structure.
6015 my $datetime_string = P_ASN1_TIME_get_isotime($time);
6017 # $time - value corresponding to openssl's ASN1_TIME structure
6018 #
6019 # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
6020 The output format is compatible with module
6022 DateTime::Format::RFC3339
6023 · P_ASN1_TIME_set_isotime
6025 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6027 requires at least openssl-0.9.7e
6028 NOTE: Does not exactly correspond to any low level API function
6030 Sets time and date value of ANS1_time structure.
6032 my $rv = P_ASN1_TIME_set_isotime($time, $string);
6034 # $time - value corresponding to openssl's ASN1_TIME structure
6035 # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
6036 #
6037 # returns: 1 on success, 0 on failure
6038 The $string parameter has to be in full form like
6040 "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
6041 "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
6042 "2012-03-22" are not supported.
6043 · P_ASN1_TIME_put2string
6045 COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
6047 bugs with openssl-0.9.8i
6048 NOTE: Does not exactly correspond to any low level API function
6050 Gives string representation of ASN1_TIME structure.
6052 my $str = P_ASN1_TIME_put2string($time);
6054 # $time - value corresponding to openssl's ASN1_TIME structure
6055 #
6056 # returns: datetime string like 'May 16 20:39:37 2033 GMT'
6057 · P_ASN1_UTCTIME_put2string
6059 NOTE: deprecated function, only for backward compatibility, just an
6061 alias for "P_ASN1_TIME_put2string"
6062 Low level API: X509_* related functions
6064 · X509_new
6066 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6068 Allocates and initializes a X509 structure.
6070 my $rv = Net::SSLeay::X509_new();
6072 #
6073 # returns: value corresponding to openssl's X509 structure (0 on failure)
6074 Check openssl doc
6076 <http://www.openssl.org/docs/crypto/X509_new.html>
6077 · X509_free
6079 Frees up the X509 structure.
6081 Net::SSLeay::X509_free($a);
6083 # $a - value corresponding to openssl's X509 structure
6084 #
6085 # returns: no return value
6086 Check openssl doc
6088 <http://www.openssl.org/docs/crypto/X509_new.html>
6089 · X509_check_host
6091 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6093 requires at least OpenSSL 1.0.2.
6094 X509_CHECK_FLAG_NEVER_CHECK_SUBJECT requires OpenSSL 1.1.0.
6095 Checks f the certificate Subject Alternative Name (SAN) or Subject
6097 CommonName (CN) matches the specified host name.
6098 my $rv = Net::SSLeay::X509_check_host($cert, $name, $flags, $peername);
6100 # $cert - value corresponding to openssl's X509 structure
6101 # $name - host name to check
6102 # $flags (optional, default: 0) - can be the bitwise OR of:
6103 # &Net::SSLeay::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
6104 # &Net::SSLeay::X509_CHECK_FLAG_NO_WILDCARDS
6105 # &Net::SSLeay::X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
6106 # &Net::SSLeay::X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
6107 # &Net::SSLeay::X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
6108 # &Net::SSLeay::X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
6109 # $peername (optional) - If not omitted and $host matches $cert,
6110 # a copy of the matching SAN or CN from
6111 # the peer certificate is stored in $peername.
6112 #
6113 # returns:
6114 # 1 for a successful match
6115 # 0 for a failed match
6116 # -1 for an internal error
6117 # -2 if the input is malformed
6118 Check openssl doc
6120 <https://www.openssl.org/docs/crypto/X509_check_host.html>.
6121 · X509_check_email
6123 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6125 requires at least OpenSSL 1.0.2.
6126 Checks if the certificate matches the specified email address.
6128 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6130 # $cert - value corresponding to openssl's X509 structure
6131 # $address - email address to check
6132 # $flags (optional, default: 0) - see X509_check_host()
6133 #
6134 # returns: see X509_check_host()
6135 Check openssl doc
6137 <https://www.openssl.org/docs/crypto/X509_check_email.html>.
6138 · X509_check_ip
6140 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6142 requires at least OpenSSL 1.0.2.
6143 Checks if the certificate matches the specified IPv4 or IPv6
6145 address.
6146 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6148 # $cert - value corresponding to openssl's X509 structure
6149 # $address - IP address to check in binary format, in network byte order
6150 # $flags (optional, default: 0) - see X509_check_host()
6151 #
6152 # returns: see X509_check_host()
6153 Check openssl doc
6155 <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
6156 · X509_check_ip_asc
6158 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6160 requires at least OpenSSL 1.0.2.
6161 Checks if the certificate matches the specified IPv4 or IPv6
6163 address.
6164 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6166 # $cert - value corresponding to openssl's X509 structure
6167 # $address - IP address to check in text representation
6168 # $flags (optional, default: 0) - see X509_check_host()
6169 #
6170 # returns: see X509_check_host()
6171 Check openssl doc
6173 <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
6174 · X509_certificate_type
6176 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6178 Returns bitmask with type of certificate $x.
6180 my $rv = Net::SSLeay::X509_certificate_type($x);
6182 # $x - value corresponding to openssl's X509 structure
6183 #
6184 # returns: (integer) bitmask with certificate type
6185 #to decode bitmask returned by this function use these constants:
6187 &Net::SSLeay::EVP_PKS_DSA
6188 &Net::SSLeay::EVP_PKS_EC
6189 &Net::SSLeay::EVP_PKS_RSA
6190 &Net::SSLeay::EVP_PKT_ENC
6191 &Net::SSLeay::EVP_PKT_EXCH
6192 &Net::SSLeay::EVP_PKT_EXP
6193 &Net::SSLeay::EVP_PKT_SIGN
6194 &Net::SSLeay::EVP_PK_DH
6195 &Net::SSLeay::EVP_PK_DSA
6196 &Net::SSLeay::EVP_PK_EC
6197 &Net::SSLeay::EVP_PK_RSA
6198 · X509_digest
6200 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6202 Computes digest/fingerprint of X509 $data using $type hash
6204 function.
6205 my $digest_value = Net::SSLeay::X509_digest($data, $type);
6207 # $data - value corresponding to openssl's X509 structure
6208 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6209 #
6210 # returns: hash value (binary)
6211 #to get printable (hex) value of digest use:
6213 print unpack('H*', $digest_value);
6214 · X509_issuer_and_serial_hash
6216 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6218 Sort of a checksum of issuer name and serial number of X509
6220 certificate $x. The result is not a full hash (e.g. sha-1), it is
6221 kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
6222 The resulting value might differ across different openssl versions
6223 for the same X509 certificate.
6224 my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
6226 # $x - value corresponding to openssl's X509 structure
6227 #
6228 # returns: number representing checksum
6229 · X509_issuer_name_hash
6231 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6233 Sort of a checksum of issuer name of X509 certificate $x. The
6235 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6236 truncated to the size of 'unsigned long' (32 bits). The resulting
6237 value might differ across different openssl versions for the same
6238 X509 certificate.
6239 my $rv = Net::SSLeay::X509_issuer_name_hash($x);
6241 # $x - value corresponding to openssl's X509 structure
6242 #
6243 # returns: number representing checksum
6244 · X509_subject_name_hash
6246 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6248 Sort of a checksum of subject name of X509 certificate $x. The
6250 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6251 truncated to the size of 'unsigned long' (32 bits). The resulting
6252 value might differ across different openssl versions for the same
6253 X509 certificate.
6254 my $rv = Net::SSLeay::X509_subject_name_hash($x);
6256 # $x - value corresponding to openssl's X509 structure
6257 #
6258 # returns: number representing checksum
6259 · X509_pubkey_digest
6261 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6263 requires at least openssl-0.9.7
6264 Computes digest/fingerprint of public key from X509 certificate
6266 $data using $type hash function.
6267 my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
6269 # $data - value corresponding to openssl's X509 structure
6270 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6271 #
6272 # returns: hash value (binary)
6273 #to get printable (hex) value of digest use:
6275 print unpack('H*', $digest_value);
6276 · X509_set_issuer_name
6278 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6280 Sets issuer of X509 certificate $x to $name.
6282 my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
6284 # $x - value corresponding to openssl's X509 structure
6285 # $name - value corresponding to openssl's X509_NAME structure
6286 #
6287 # returns: 1 on success, 0 on failure
6288 · X509_set_pubkey
6290 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6292 Sets public key of X509 certificate $x to $pkey.
6294 my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
6296 # $x - value corresponding to openssl's X509 structure
6297 # $pkey - value corresponding to openssl's EVP_PKEY structure
6298 #
6299 # returns: 1 on success, 0 on failure
6300 · X509_set_serialNumber
6302 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6304 Sets serial number of X509 certificate $x to $serial.
6306 my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
6308 # $x - value corresponding to openssl's X509 structure
6309 # $serial - value corresponding to openssl's ASN1_INTEGER structure
6310 #
6311 # returns: 1 on success, 0 on failure
6312 #to create $serial value use one of these:
6314 $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
6315 $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
6316 $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
6317 · X509_set_subject_name
6319 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6321 Sets subject of X509 certificate $x to $name.
6323 my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
6325 # $x - value corresponding to openssl's X509 structure
6326 # $name - value corresponding to openssl's X509_NAME structure
6327 #
6328 # returns: 1 on success, 0 on failure
6329 · X509_set_version
6331 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6333 Set 'version' value for X509 certificate $ to $version.
6335 my $rv = Net::SSLeay::X509_set_version($x, $version);
6337 # $x - value corresponding to openssl's X509 structure
6338 # $version - (integer) version number
6339 #
6340 # returns: 1 on success, 0 on failure
6341 · X509_sign
6343 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6345 Sign X509 certificate $x with private key $pkey (using digest
6347 algorithm $md).
6348 my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
6350 # $x - value corresponding to openssl's X509 structure
6351 # $pkey - value corresponding to openssl's EVP_PKEY structure
6352 # $md - value corresponding to openssl's EVP_MD structure
6353 #
6354 # returns: 1 on success, 0 on failure
6355 · X509_verify
6357 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6359 Verifies X509 object $a using public key $r (pubkey of issuing CA).
6361 my $rv = Net::SSLeay::X509_verify($x, $r);
6363 # $x - value corresponding to openssl's X509 structure
6364 # $r - value corresponding to openssl's EVP_PKEY structure
6365 #
6366 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6367 · X509_get_ext_count
6369 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6371 Returns the total number of extensions in X509 object $x.
6373 my $rv = Net::SSLeay::X509_get_ext_count($x);
6375 # $x - value corresponding to openssl's X509 structure
6376 #
6377 # returns: count of extensions
6378 · X509_get_pubkey
6380 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6382 Returns public key corresponding to given X509 object $x.
6384 my $rv = Net::SSLeay::X509_get_pubkey($x);
6386 # $x - value corresponding to openssl's X509 structure
6387 #
6388 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6389 NOTE: This method returns only the public key's key bits, without
6391 the algorithm or parameters. Use "X509_get_X509_PUBKEY()" to
6392 return the full public key (SPKI) instead.
6393 · X509_get_X509_PUBKEY
6395 COMPATIBILITY: not available in Net-SSLeay-1.72 and before
6397 Returns the full public key (SPKI) of given X509 certificate $x.
6399 Net::SSLeay::X509_get_X509_PUBKEY($x);
6401 # $x - value corresponding to openssl's X509 structure
6402 #
6403 # returns: public key data in DER format (binary)
6404 · X509_get_serialNumber
6406 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6408 Returns serial number of X509 certificate $x.
6410 my $rv = Net::SSLeay::X509_get_serialNumber($x);
6412 # $x - value corresponding to openssl's X509 structure
6413 #
6414 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6415 See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
6417 "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
6418 · X509_get0_serialNumber
6420 COMPATIBILITY: available in Net-SSLeay-1.86 onwards
6422 X509_get0_serialNumber() is the same as X509_get_serialNumber()
6424 except it accepts a const parameter and returns a const result.
6425 · X509_get_version
6427 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6429 Returns 'version' value of given X509 certificate $x.
6431 my $rv = Net::SSLeay::X509_get_version($x);
6433 # $x - value corresponding to openssl's X509 structure
6434 #
6435 # returns: (integer) version
6436 · X509_get_ext
6438 Returns X509_EXTENSION from $x509 based on given position/index.
6440 my $rv = Net::SSLeay::X509_get_ext($x509, $index);
6442 # $x509 - value corresponding to openssl's X509 structure
6443 # $index - (integer) position/index of extension within $x509
6444 #
6445 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6446 · X509_get_ext_by_NID
6448 Returns X509_EXTENSION from $x509 based on given NID.
6450 my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
6452 # $x509 - value corresponding to openssl's X509 structure
6453 # $nid - (integer) NID value
6454 # $loc - (integer) position to start lookup at
6455 #
6456 # returns: position/index of extension, negative value on error
6457 # call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
6458 · X509_get_fingerprint
6460 Returns fingerprint of certificate $cert.
6462 NOTE: Does not exactly correspond to any low level API function.
6464 The implementation is basen on openssl's "X509_digest()".
6465 Net::SSLeay::X509_get_fingerprint($x509, $type);
6467 # $x509 - value corresponding to openssl's X509 structure
6468 # $type - (string) digest type, currently supported values:
6469 # "md5"
6470 # "sha1"
6471 # "sha256"
6472 # "ripemd160"
6473 #
6474 # returns: certificate digest - hexadecimal string (NOT binary data!)
6475 · X509_get_issuer_name
6477 Return an X509_NAME object representing the issuer of the
6479 certificate $cert.
6480 my $rv = Net::SSLeay::X509_get_issuer_name($cert);
6482 # $cert - value corresponding to openssl's X509 structure
6483 #
6484 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6485 · X509_get_notAfter
6487 Return an object giving the time after which the certificate $cert
6489 is not valid.
6490 my $rv = Net::SSLeay::X509_get_notAfter($cert);
6492 # $cert - value corresponding to openssl's X509 structure
6493 #
6494 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6495 To get human readable/printable form the return value you can use:
6497 my $time = Net::SSLeay::X509_get_notAfter($cert);
6499 print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6500 · X509_get_notBefore
6502 Return an object giving the time before which the certificate $cert
6504 is not valid
6505 my $rv = Net::SSLeay::X509_get_notBefore($cert);
6507 # $cert - value corresponding to openssl's X509 structure
6508 #
6509 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6510 To get human readable/printable form the return value you can use:
6512 my $time = Net::SSLeay::X509_get_notBefore($cert);
6514 print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6515 · X509_get_subjectAltNames
6517 NOTE: Does not exactly correspond to any low level API function.
6519 Returns the list of alternative subject names from X509 certificate
6521 $cert.
6522 my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
6524 # $cert - value corresponding to openssl's X509 structure
6525 #
6526 # returns: list containing pairs - name_type (integer), name_value (string)
6527 # where name_type can be:
6528 # 0 - GEN_OTHERNAME
6529 # 1 - GEN_EMAIL
6530 # 2 - GEN_DNS
6531 # 3 - GEN_X400
6532 # 4 - GEN_DIRNAME
6533 # 5 - GEN_EDIPARTY
6534 # 6 - GEN_URI
6535 # 7 - GEN_IPADD
6536 # 8 - GEN_RID
6537 Note: type 7 - GEN_IPADD contains the IP address as a packed binary
6539 address.
6540 · X509_get_subject_name
6542 Returns the subject of the certificate $cert.
6544 my $rv = Net::SSLeay::X509_get_subject_name($cert);
6546 # $cert - value corresponding to openssl's X509 structure
6547 #
6548 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6549 · X509_gmtime_adj
6551 Adjust th ASN1_TIME object to the timestamp (in GMT).
6553 my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
6555 # $s - value corresponding to openssl's ASN1_TIME structure
6556 # $adj - timestamp (seconds since 1.1.1970)
6557 #
6558 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6559 BEWARE: this function may fail for dates after 2038 as it is
6561 dependent on time_t size on your system (32bit time_t does not work
6562 after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
6563 · X509_load_cert_crl_file
6565 Takes PEM file and loads all X509 certificates and X509 CRLs from
6567 that file into X509_LOOKUP structure.
6568 my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
6570 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6571 # $file - (string) file name
6572 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6573 # if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
6574 #
6575 # returns: 1 on success, 0 on failure
6576 · X509_load_cert_file
6578 Loads/adds X509 certificate from $file to X509_LOOKUP structure
6580 my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
6582 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6583 # $file - (string) file name
6584 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6585 #
6586 # returns: 1 on success, 0 on failure
6587 · X509_load_crl_file
6589 Loads/adds X509 CRL from $file to X509_LOOKUP structure
6591 my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
6593 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6594 # $file - (string) file name
6595 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6596 #
6597 # returns: 1 on success, 0 on failure
6598 · X509_policy_level_get0_node
6600 ??? (more info needed)
6602 my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
6604 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6605 # $i - (integer) index/position
6606 #
6607 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6608 · X509_policy_level_node_count
6610 ??? (more info needed)
6612 my $rv = Net::SSLeay::X509_policy_level_node_count($level);
6614 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6615 #
6616 # returns: (integer) node count
6617 · X509_policy_node_get0_parent
6619 ??? (more info needed)
6621 my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
6623 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6624 #
6625 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6626 · X509_policy_node_get0_policy
6628 ??? (more info needed)
6630 my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
6632 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6633 #
6634 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6635 · X509_policy_node_get0_qualifiers
6637 ??? (more info needed)
6639 my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
6641 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6642 #
6643 # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
6644 · X509_policy_tree_free
6646 ??? (more info needed)
6648 Net::SSLeay::X509_policy_tree_free($tree);
6650 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6651 #
6652 # returns: no return value
6653 · X509_policy_tree_get0_level
6655 ??? (more info needed)
6657 my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
6659 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6660 # $i - (integer) level index
6661 #
6662 # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
6663 · X509_policy_tree_get0_policies
6665 ??? (more info needed)
6667 my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
6669 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6670 #
6671 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6672 · X509_policy_tree_get0_user_policies
6674 ??? (more info needed)
6676 my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
6678 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6679 #
6680 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6681 · X509_policy_tree_level_count
6683 ??? (more info needed)
6685 my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
6687 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6688 #
6689 # returns: (integer) count
6690 · X509_verify_cert_error_string
6692 Returns a human readable error string for verification error $n.
6694 my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6696 # $n - (long) numeric error code
6697 #
6698 # returns: error string
6699 Check openssl doc
6701 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6702 · P_X509_add_extensions
6704 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6706 Adds one or more X509 extensions to X509 object $x.
6708 my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
6710 # $x - value corresponding to openssl's X509 structure
6711 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
6712 # $nid - NID identifying extension to be set
6713 # $value - extension value
6714 #
6715 # returns: 1 on success, 0 on failure
6716 You can set more extensions at once:
6718 my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
6720 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6721 &Net::SSLeay::NID_subject_key_identifier => 'hash',
6722 &Net::SSLeay::NID_authority_key_identifier => 'keyid',
6723 &Net::SSLeay::NID_authority_key_identifier => 'issuer',
6724 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6725 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6726 &Net::SSLeay::NID_netscape_cert_type => 'server',
6727 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
6728 );
6729 · P_X509_copy_extensions
6731 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6733 Copies X509 extensions from X509_REQ object to X509 object - handy
6735 when you need to turn X509_REQ into X509 certificate.
6736 Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
6738 # $x509_req - value corresponding to openssl's X509_REQ structure
6739 # $x509 - value corresponding to openssl's X509 structure
6740 # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
6741 #
6742 # returns: 1 on success, 0 on failure
6743 · P_X509_get_crl_distribution_points
6745 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6747 requires at least openssl-0.9.7
6748 Get the list of CRL distribution points from X509 certificate.
6750 my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
6752 # $x509 - value corresponding to openssl's X509 structure
6753 #
6754 # returns: list of distribution points (usually URLs)
6755 · P_X509_get_ext_key_usage
6757 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6759 requires at least openssl-0.9.7
6760 Gets the list of extended key usage of given X509 certificate
6762 $cert.
6763 my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
6765 # $cert - value corresponding to openssl's X509 structure
6766 # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
6767 #
6768 # returns: list of values
6769 Examples:
6771 my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
6773 # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
6774 my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
6776 # returns for example: (129, 130)
6777 my @extkeyusage_sn = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
6779 # returns for example: ("serverAuth", "clientAuth")
6780 my @extkeyusage_ln = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
6782 # returns for example: ("TLS Web Server Authentication", "TLS Web Client Authentication")
6783 · P_X509_get_key_usage
6785 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6787 Gets the list of key usage of given X509 certificate $cert.
6789 my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
6791 # $cert - value corresponding to openssl's X509 structure
6792 #
6793 # returns: list of key usage values which can be none, one or more from the following list:
6794 # "digitalSignature"
6795 # "nonRepudiation"
6796 # "keyEncipherment"
6797 # "dataEncipherment"
6798 # "keyAgreement"
6799 # "keyCertSign"
6800 # "cRLSign"
6801 # "encipherOnly"
6802 # "decipherOnly"
6803 · P_X509_get_netscape_cert_type
6805 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6807 Gets the list of Netscape cert types of given X509 certificate
6809 $cert.
6810 Net::SSLeay::P_X509_get_netscape_cert_type($cert);
6812 # $cert - value corresponding to openssl's X509 structure
6813 #
6814 # returns: list of Netscape type values which can be none, one or more from the following list:
6815 # "client"
6816 # "server"
6817 # "email"
6818 # "objsign"
6819 # "reserved"
6820 # "sslCA"
6821 # "emailCA"
6822 # "objCA"
6823 · P_X509_get_pubkey_alg
6825 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6827 Returns ASN1_OBJECT corresponding to X509 certificate public key
6829 algorithm.
6830 my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
6832 # $x - value corresponding to openssl's X509 structure
6833 #
6834 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6835 To get textual representation use:
6837 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
6839 # returns for example: "rsaEncryption"
6840 · P_X509_get_signature_alg
6842 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6844 Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
6846 my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
6848 # $x - value corresponding to openssl's X509 structure
6849 #
6850 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6851 To get textual representation use:
6853 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
6855 # returns for example: "sha1WithRSAEncryption"
6856 · sk_X509_new_null
6858 Returns a new, empty, STACK_OF(X509) structure.
6860 my $rv = Net::SSLeay::sk_X509_new_null();
6862 #
6863 # returns: value corresponding to openssl's STACK_OF(X509) structure
6864 · sk_X509_push
6866 Pushes an X509 structure onto a STACK_OF(X509) structure.
6868 my $rv = Net::SSLeay::sk_X509_push($sk_x509, $x509);
6870 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
6871 # $x509 - value corresponding to openssl's X509 structure
6872 #
6873 # returns: 1 if successful, 0 if unsuccessful
6874 Low level API: X509_REQ_* related functions
6876 · X509_REQ_new
6878 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6880 Creates a new X509_REQ structure.
6882 my $rv = Net::SSLeay::X509_REQ_new();
6884 #
6885 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
6886 · X509_REQ_free
6888 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6890 Free an allocated X509_REQ structure.
6892 Net::SSLeay::X509_REQ_free($x);
6894 # $x - value corresponding to openssl's X509_REQ structure
6895 #
6896 # returns: no return value
6897 · X509_REQ_add1_attr_by_NID
6899 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6901 Adds an attribute whose name is defined by a NID $nid. The field
6903 value to be added is in $bytes.
6904 my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
6906 # $req - value corresponding to openssl's X509_REQ structure
6907 # $nid - (integer) NID value
6908 # $type - (integer) type of data in $bytes (see below)
6909 # $bytes - data to be set
6910 #
6911 # returns: 1 on success, 0 on failure
6912 # values for $type - use constants:
6914 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
6915 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
6916 · X509_REQ_digest
6918 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6920 Computes digest/fingerprint of X509_REQ $data using $type hash
6922 function.
6923 my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
6925 # $data - value corresponding to openssl's X509_REQ structure
6926 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6927 #
6928 # returns: hash value (binary)
6929 #to get printable (hex) value of digest use:
6931 print unpack('H*', $digest_value);
6932 · X509_REQ_get_attr_by_NID
6934 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6936 Retrieve the next index matching $nid after $lastpos ($lastpos
6938 should initially be set to -1).
6939 my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
6941 # $req - value corresponding to openssl's X509_REQ structure
6942 # $nid - (integer) NID value
6943 # $lastpos - [optional] (integer) index where to start search (default -1)
6944 #
6945 # returns: index (-1 if there are no more entries)
6946 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6948 e.g.
6949 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6951 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6952 · X509_REQ_get_attr_by_OBJ
6954 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6956 Retrieve the next index matching $obj after $lastpos ($lastpos
6958 should initially be set to -1).
6959 my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
6961 # $req - value corresponding to openssl's X509_REQ structure
6962 # $obj - value corresponding to openssl's ASN1_OBJECT structure
6963 # $lastpos - [optional] (integer) index where to start search (default -1)
6964 #
6965 # returns: index (-1 if there are no more entries)
6966 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6968 e.g.
6969 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6971 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6972 · X509_REQ_get_attr_count
6974 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6976 Returns the total number of attributes in $req.
6978 my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
6980 # $req - value corresponding to openssl's X509_REQ structure
6981 #
6982 # returns: (integer) items count
6983 · X509_REQ_get_pubkey
6985 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6987 Returns public key corresponding to given X509_REQ object $x.
6989 my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
6991 # $x - value corresponding to openssl's X509_REQ structure
6992 #
6993 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6994 · X509_REQ_get_subject_name
6996 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6998 Returns X509_NAME object corresponding to subject name of given
7000 X509_REQ object $x.
7001 my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
7003 # $x - value corresponding to openssl's X509_REQ structure
7004 #
7005 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7006 · X509_REQ_get_version
7008 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7010 Returns 'version' value for given X509_REQ object $x.
7012 my $rv = Net::SSLeay::X509_REQ_get_version($x);
7014 # $x - value corresponding to openssl's X509_REQ structure
7015 #
7016 # returns: (integer) version e.g. 0 = "version 1"
7017 · X509_REQ_set_pubkey
7019 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7021 Sets public key of given X509_REQ object $x to $pkey.
7023 my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
7025 # $x - value corresponding to openssl's X509_REQ structure
7026 # $pkey - value corresponding to openssl's EVP_PKEY structure
7027 #
7028 # returns: 1 on success, 0 on failure
7029 · X509_REQ_set_subject_name
7031 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7033 Sets subject name of given X509_REQ object $x to X509_NAME object
7035 $name.
7036 my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
7038 # $x - value corresponding to openssl's X509_REQ structure
7039 # $name - value corresponding to openssl's X509_NAME structure
7040 #
7041 # returns: 1 on success, 0 on failure
7042 · X509_REQ_set_version
7044 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7046 Sets 'version' of given X509_REQ object $x to $version.
7048 my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
7050 # $x - value corresponding to openssl's X509_REQ structure
7051 # $version - (integer) e.g. 0 = "version 1"
7052 #
7053 # returns: 1 on success, 0 on failure
7054 · X509_REQ_sign
7056 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7058 Sign X509_REQ object $x with private key $pk (using digest
7060 algorithm $md).
7061 my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
7063 # $x - value corresponding to openssl's X509_REQ structure
7064 # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
7065 # $md - value corresponding to openssl's EVP_MD structure
7066 #
7067 # returns: 1 on success, 0 on failure
7068 · X509_REQ_verify
7070 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7072 Verifies X509_REQ object $x using public key $r (pubkey of
7074 requesting party).
7075 my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
7077 # $x - value corresponding to openssl's X509_REQ structure
7078 # $r - value corresponding to openssl's EVP_PKEY structure
7079 #
7080 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7081 · P_X509_REQ_add_extensions
7083 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7085 Adds one or more X509 extensions to X509_REQ object $x.
7087 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
7089 # $x - value corresponding to openssl's X509_REQ structure
7090 # $nid - NID identifying extension to be set
7091 # $value - extension value
7092 #
7093 # returns: 1 on success, 0 on failure
7094 You can set more extensions at once:
7096 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
7098 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
7099 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
7100 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
7101 &Net::SSLeay::NID_netscape_cert_type => 'server',
7102 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
7103 &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
7104 );
7105 · P_X509_REQ_get_attr
7107 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7109 requires at least openssl-0.9.7
7110 Returns attribute value for X509_REQ's attribute at index $n.
7112 Net::SSLeay::P_X509_REQ_get_attr($req, $n);
7114 # $req - value corresponding to openssl's X509_REQ structure
7115 # $n - (integer) attribute index
7116 #
7117 # returns: value corresponding to openssl's ASN1_STRING structure
7118 Low level API: X509_CRL_* related functions
7120 · X509_CRL_new
7122 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7124 Creates a new X509_CRL structure.
7126 my $rv = Net::SSLeay::X509_CRL_new();
7128 #
7129 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
7130 · X509_CRL_free
7132 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7134 Free an allocated X509_CRL structure.
7136 Net::SSLeay::X509_CRL_free($x);
7138 # $x - value corresponding to openssl's X509_CRL structure
7139 #
7140 # returns: no return value
7141 · X509_CRL_digest
7143 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7145 Computes digest/fingerprint of X509_CRL $data using $type hash
7147 function.
7148 my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
7150 # $data - value corresponding to openssl's X509_CRL structure
7151 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7152 #
7153 # returns: hash value (binary)
7154 Example:
7156 my $x509_crl
7158 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7159 my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
7160 #to get printable (hex) value of digest use:
7161 print "digest=", unpack('H*', $digest_value), "\n";
7162 · X509_CRL_get_ext
7164 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7166 Returns X509_EXTENSION from $x509 based on given position/index.
7168 my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
7170 # $x509 - value corresponding to openssl's X509_CRL structure
7171 # $index - (integer) position/index of extension within $x509
7172 #
7173 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
7174 · X509_CRL_get_ext_by_NID
7176 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7178 Returns X509_EXTENSION from $x509 based on given NID.
7180 my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
7182 # $x509 - value corresponding to openssl's X509_CRL structure
7183 # $nid - (integer) NID value
7184 # $loc - (integer) position to start lookup at
7185 #
7186 # returns: position/index of extension, negative value on error
7187 # call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
7188 · X509_CRL_get_ext_count
7190 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7192 Returns the total number of extensions in X509_CRL object $x.
7194 my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
7196 # $x - value corresponding to openssl's X509_CRL structure
7197 #
7198 # returns: count of extensions
7199 · X509_CRL_get_issuer
7201 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7203 Returns X509_NAME object corresponding to the issuer of X509_CRL
7205 $x.
7206 my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
7208 # $x - value corresponding to openssl's X509_CRL structure
7209 #
7210 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7211 See other "X509_NAME_*" functions to get more info from X509_NAME
7213 structure.
7214 · X509_CRL_get_lastUpdate
7216 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7218 Returns 'lastUpdate' date-time value of X509_CRL object $x.
7220 my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
7222 # $x - value corresponding to openssl's X509_CRL structure
7223 #
7224 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7225 · X509_CRL_get_nextUpdate
7227 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7229 Returns 'nextUpdate' date-time value of X509_CRL object $x.
7231 my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
7233 # $x - value corresponding to openssl's X509_CRL structure
7234 #
7235 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7236 · X509_CRL_get_version
7238 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7240 Returns 'version' value of given X509_CRL structure $x.
7242 my $rv = Net::SSLeay::X509_CRL_get_version($x);
7244 # $x - value corresponding to openssl's X509_CRL structure
7245 #
7246 # returns: (integer) version
7247 · X509_CRL_set_issuer_name
7249 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7251 requires at least openssl-0.9.7
7252 Sets the issuer of X509_CRL object $x to X509_NAME object $name.
7254 my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
7256 # $x - value corresponding to openssl's X509_CRL structure
7257 # $name - value corresponding to openssl's X509_NAME structure
7258 #
7259 # returns: 1 on success, 0 on failure
7260 · X509_CRL_set_lastUpdate
7262 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7264 requires at least openssl-0.9.7
7265 Sets 'lastUpdate' value of X509_CRL object $x to $tm.
7267 my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
7269 # $x - value corresponding to openssl's X509_CRL structure
7270 # $tm - value corresponding to openssl's ASN1_TIME structure
7271 #
7272 # returns: 1 on success, 0 on failure
7273 · X509_CRL_set_nextUpdate
7275 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7277 requires at least openssl-0.9.7
7278 Sets 'nextUpdate' value of X509_CRL object $x to $tm.
7280 my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
7282 # $x - value corresponding to openssl's X509_CRL structure
7283 # $tm - value corresponding to openssl's ASN1_TIME structure
7284 #
7285 # returns: 1 on success, 0 on failure
7286 · X509_CRL_set_version
7288 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7290 requires at least openssl-0.9.7
7291 Sets 'version' value of given X509_CRL structure $x to $version.
7293 my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
7295 # $x - value corresponding to openssl's X509_CRL structure
7296 # $version - (integer) version number (1 = version 2 CRL)
7297 #
7298 # returns: 1 on success, 0 on failure
7299 Note that if you want to use any X509_CRL extension you need to set
7301 "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
7302 · X509_CRL_sign
7304 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7306 Sign X509_CRL object $x with private key $pkey (using digest
7308 algorithm $md).
7309 my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
7311 # $x - value corresponding to openssl's X509_CRL structure
7312 # $pkey - value corresponding to openssl's EVP_PKEY structure
7313 # $md - value corresponding to openssl's EVP_MD structure
7314 #
7315 # returns: 1 on success, 0 on failure
7316 · X509_CRL_sort
7318 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7320 requires at least openssl-0.9.7
7321 Sorts the data of X509_CRL object so it will be written in serial
7323 number order.
7324 my $rv = Net::SSLeay::X509_CRL_sort($x);
7326 # $x - value corresponding to openssl's X509_CRL structure
7327 #
7328 # returns: 1 on success, 0 on failure
7329 · X509_CRL_verify
7331 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7333 Verifies X509_CRL object $a using public key $r (pubkey of issuing
7335 CA).
7336 my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
7338 # $a - value corresponding to openssl's X509_CRL structure
7339 # $r - value corresponding to openssl's EVP_PKEY structure
7340 #
7341 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7342 · P_X509_CRL_add_revoked_serial_hex
7344 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7346 requires at least openssl-0.9.7
7347 Adds given serial number $serial_hex to X509_CRL object $crl.
7349 Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
7351 # $crl - value corresponding to openssl's X509_CRL structure
7352 # $serial_hex - string (hexadecimal) representation of serial number
7353 # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
7354 # $reason_code - [optional] (integer) reason code (see below) - default 0
7355 # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
7356 #
7357 # returns: no return value
7358 reason codes:
7360 0 - unspecified
7361 1 - keyCompromise
7362 2 - CACompromise
7363 3 - affiliationChanged
7364 4 - superseded
7365 5 - cessationOfOperation
7366 6 - certificateHold
7367 7 - removeFromCRL
7368 · P_X509_CRL_get_serial
7370 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7372 requires at least openssl-0.9.7
7373 Returns serial number of X509_CRL object.
7375 my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
7377 # $crl - value corresponding to openssl's X509_CRL structure
7378 #
7379 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
7380 · P_X509_CRL_set_serial
7382 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7384 requires at least openssl-0.9.7
7385 Sets serial number of X509_CRL object to $crl_number.
7387 my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
7389 # $crl - value corresponding to openssl's X509_CRL structure
7390 # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
7391 #
7392 # returns: 1 on success, 0 on failure
7393 Low level API: X509_EXTENSION_* related functions
7395 · X509_EXTENSION_get_critical
7397 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7399 Returns 'critical' flag of given X509_EXTENSION object $ex.
7401 my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
7403 # $ex - value corresponding to openssl's X509_EXTENSION structure
7404 #
7405 # returns: (integer) 1 - critical, 0 - noncritical
7406 · X509_EXTENSION_get_data
7408 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7410 Returns value (raw data) of X509_EXTENSION object $ne.
7412 my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
7414 # $ne - value corresponding to openssl's X509_EXTENSION structure
7415 #
7416 # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
7417 Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
7419 into perl scalar variable.
7420 · X509_EXTENSION_get_object
7422 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7424 Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
7426 my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
7428 # $ex - value corresponding to openssl's X509_EXTENSION structure
7429 #
7430 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7431 · X509V3_EXT_print
7433 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7435 Returns string representation of given X509_EXTENSION object $ext.
7437 Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
7439 # $ext - value corresponding to openssl's X509_EXTENSION structure
7440 # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
7441 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7442 #
7443 # returns: no return value
7444 · X509V3_EXT_d2i
7446 Parses an extension and returns its internal structure.
7448 my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
7450 # $ext - value corresponding to openssl's X509_EXTENSION structure
7451 #
7452 # returns: pointer ???
7453 Low level API: X509_NAME_* related functions
7455 · X509_NAME_ENTRY_get_data
7457 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7459 Retrieves the field value of $ne in and ASN1_STRING structure.
7461 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
7463 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7464 #
7465 # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
7466 Check openssl doc
7468 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7469 · X509_NAME_ENTRY_get_object
7471 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7473 Retrieves the field name of $ne in and ASN1_OBJECT structure.
7475 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
7477 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7478 #
7479 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7480 Check openssl doc
7482 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7483 · X509_NAME_new
7485 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7487 requires at least openssl-0.9.5
7488 Creates a new X509_NAME structure. Adds a field whose name is
7490 defined by a string $field. The field value to be added is in
7491 $bytes.
7492 my $rv = Net::SSLeay::X509_NAME_new();
7494 #
7495 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7496 · X509_NAME_hash
7498 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7500 requires at least openssl-0.9.5
7501 Sort of a checksum of issuer name $name. The result is not a full
7503 hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
7504 'unsigned long' (32 bits). The resulting value might differ across
7505 different openssl versions for the same X509 certificate.
7506 my $rv = Net::SSLeay::X509_NAME_hash($name);
7508 # $name - value corresponding to openssl's X509_NAME structure
7509 #
7510 # returns: number representing checksum
7511 · X509_NAME_add_entry_by_txt
7513 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7515 requires at least openssl-0.9.5
7516 Adds a field whose name is defined by a string $field. The field
7518 value to be added is in $bytes.
7519 my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
7521 # $name - value corresponding to openssl's X509_NAME structure
7522 # $field - (string) field definition (name) - e.g. "organizationName"
7523 # $type - (integer) type of data in $bytes (see below)
7524 # $bytes - data to be set
7525 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7526 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7527 #
7528 # returns: 1 on success, 0 on failure
7529 # values for $type - use constants:
7531 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7532 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7533 Unicode note: when passing non-ascii (unicode) string in $bytes do
7535 not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
7536 the perl $string via "$bytes = encode('utf-8', $string)".
7537 Check openssl doc
7539 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7540 · X509_NAME_add_entry_by_NID
7542 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7544 requires at least openssl-0.9.5
7545 Adds a field whose name is defined by a NID $nid. The field value
7547 to be added is in $bytes.
7548 my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
7550 # $name - value corresponding to openssl's X509_NAME structure
7551 # $nid - (integer) field definition - NID value
7552 # $type - (integer) type of data in $bytes (see below)
7553 # $bytes - data to be set
7554 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7555 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7556 #
7557 # returns: 1 on success, 0 on failure
7558 Check openssl doc
7560 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7561 · X509_NAME_add_entry_by_OBJ
7563 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7565 requires at least openssl-0.9.5
7566 Adds a field whose name is defined by a object (OID) $obj . The
7568 field value to be added is in $bytes.
7569 my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
7571 # $name - value corresponding to openssl's X509_NAME structure
7572 # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
7573 # $type - (integer) type of data in $bytes (see below)
7574 # $bytes - data to be set
7575 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7576 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7577 #
7578 # returns: 1 on success, 0 on failure
7579 Check openssl doc
7581 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7582 · X509_NAME_cmp
7584 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7586 Compares two X509_NAME obejcts.
7588 my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
7590 # $a - value corresponding to openssl's X509_NAME structure
7591 # $b - value corresponding to openssl's X509_NAME structure
7592 #
7593 # returns: 0 if $a matches $b; non zero otherwise
7594 · X509_NAME_digest
7596 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7598 Computes digest/fingerprint of X509_NAME $data using $type hash
7600 function.
7601 my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
7603 # $data - value corresponding to openssl's X509_NAME structure
7604 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7605 #
7606 # returns: hash value (binary)
7607 #to get printable (hex) value of digest use:
7609 print unpack('H*', $digest_value);
7610 · X509_NAME_entry_count
7612 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7614 Returns the total number of entries in $name.
7616 my $rv = Net::SSLeay::X509_NAME_entry_count($name);
7618 # $name - value corresponding to openssl's X509_NAME structure
7619 #
7620 # returns: (integer) entries count
7621 Check openssl doc
7623 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7624 · X509_NAME_get_entry
7626 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7628 Retrieves the X509_NAME_ENTRY from $name corresponding to index
7630 $loc. Acceptable values for $loc run from 0 to
7631 "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
7632 is an internal pointer which must not be freed.
7633 my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
7635 # $name - value corresponding to openssl's X509_NAME structure
7636 # $loc - (integer) index of wanted entry
7637 #
7638 # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
7639 Check openssl doc
7641 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7642 · X509_NAME_print_ex
7644 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7646 Returns a string with human readable version of $name.
7648 Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
7650 # $name - value corresponding to openssl's X509_NAME structure
7651 # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
7652 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7653 #
7654 # returns: string representation of $name
7655 #available conversion flags - use constants:
7657 &Net::SSLeay::XN_FLAG_COMPAT
7658 &Net::SSLeay::XN_FLAG_DN_REV
7659 &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
7660 &Net::SSLeay::XN_FLAG_FN_ALIGN
7661 &Net::SSLeay::XN_FLAG_FN_LN
7662 &Net::SSLeay::XN_FLAG_FN_MASK
7663 &Net::SSLeay::XN_FLAG_FN_NONE
7664 &Net::SSLeay::XN_FLAG_FN_OID
7665 &Net::SSLeay::XN_FLAG_FN_SN
7666 &Net::SSLeay::XN_FLAG_MULTILINE
7667 &Net::SSLeay::XN_FLAG_ONELINE
7668 &Net::SSLeay::XN_FLAG_RFC2253
7669 &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
7670 &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
7671 &Net::SSLeay::XN_FLAG_SEP_MASK
7672 &Net::SSLeay::XN_FLAG_SEP_MULTILINE
7673 &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
7674 &Net::SSLeay::XN_FLAG_SPC_EQ
7675 Most likely you will be fine with default:
7677 Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
7679 Or you might want RFC2253-like output without utf8 chars escaping:
7681 use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
7683 my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
7684 my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
7685 Check openssl doc
7687 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7688 · X509_NAME_get_text_by_NID
7690 Retrieves the text from the first entry in name which matches $nid,
7692 if no such entry exists -1 is returned.
7693 openssl note: this is a legacy function which has various
7695 limitations which makes it of minimal use in practice. It can only
7696 find the first matching entry and will copy the contents of the
7697 field verbatim: this can be highly confusing if the target is a
7698 multicharacter string type like a BMPString or a UTF8String.
7699 Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
7701 # $name - value corresponding to openssl's X509_NAME structure
7702 # $nid - NID value (integer)
7703 #
7704 # returns: text value
7705 Check openssl doc
7707 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7708 · X509_NAME_oneline
7710 Return an ASCII version of $name.
7712 Net::SSLeay::X509_NAME_oneline($name);
7714 # $name - value corresponding to openssl's X509_NAME structure
7715 #
7716 # returns: (string) ASCII version of $name
7717 Check openssl doc
7719 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7720 · sk_X509_NAME_free
7722 Free an allocated STACK_OF(X509_NAME) structure.
7724 Net::SSLeay::sk_X509_NAME_free($sk);
7726 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7727 #
7728 # returns: no return value
7729 · sk_X509_NAME_num
7731 Return number of items in STACK_OF(X509_NAME)
7733 my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
7735 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7736 #
7737 # returns: number of items
7738 · sk_X509_NAME_value
7740 Returns X509_NAME from position $index in STACK_OF(X509_NAME)
7742 my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
7744 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7745 # $i - (integer) index/position
7746 #
7747 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7748 · add_file_cert_subjects_to_stack
7750 Add a file of certs to a stack. All certs in $file that are not
7752 already in the $stackCAs will be added.
7753 my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
7755 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7756 # $file - (string) filename
7757 #
7758 # returns: 1 on success, 0 on failure
7759 · add_dir_cert_subjects_to_stack
7761 Add a directory of certs to a stack. All certs in $dir that are not
7763 already in the $stackCAs will be added.
7764 my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
7766 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7767 # $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.
7768 #
7769 # returns: 1 on success, 0 on failure
7770 Low level API: X509_STORE_* related functions
7772 · X509_STORE_CTX_new
7774 returns a newly initialised X509_STORE_CTX structure.
7776 · X509_STORE_CTX_init
7778 X509_STORE_CTX_init() sets up an X509_STORE_CTX for a subsequent
7780 verification operation. It must be called before each call to
7781 X509_verify_cert().
7782 Net::SSLeay::X509_STORE_CTX_init($x509_store_ctx, $x509_store,
7784 $x509, $chain);
7785 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7787 structure (required) # $x509_store - value corresponding to
7788 openssl's X509_STORE structure (optional) # $x509 - value
7789 corresponding to openssl's X509 structure (optional) # $chain -
7790 value corresponding to openssl's STACK_OF(X509) structure
7791 (optional)
7792 Check openssl doc
7794 <https://www.openssl.org/docs/man1.0.2/crypto/X509_STORE_CTX_init.html>
7795 · X509_STORE_CTX_free
7797 Frees an X509_STORE_CTX structure.
7799 Net::SSLeay::X509_STORE_CTX_free($x509_store_ctx);
7801 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7803 structure
7804 · X509_verify_cert
7806 The X509_verify_cert() function attempts to discover and validate a
7808 certificate chain based on parameters in ctx. A complete
7809 description of the process is contained in the verify(1) manual
7810 page.
7811 If this function returns 0, use X509_STORE_CTX_get_error to get
7813 additional error information.
7814 my $rv = Net::SSLeay::X509_verify_cert($x509_store_ctx); #
7816 $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7817 structure # # returns: 1 if a complete chain can be built and
7818 validated, otherwise 0
7819 Check openssl doc
7821 <https://www.openssl.org/docs/manmaster/man3/X509_verify_cert.html>
7822 · X509_STORE_CTX_get_current_cert
7824 Returns the certificate in ctx which caused the error or 0 if no
7826 certificate is relevant.
7827 my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
7829 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7830 #
7831 # returns: value corresponding to openssl's X509 structure (0 on failure)
7832 Check openssl doc
7834 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7835 · X509_STORE_CTX_get_error
7837 Returns the error code of $ctx.
7839 my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
7841 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7842 #
7843 # returns: (integer) error code
7844 For more info about erro code values check function
7846 "get_verify_result".
7847 Check openssl doc
7849 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7850 · X509_STORE_CTX_get_error_depth
7852 Returns the depth of the error. This is a non-negative integer
7854 representing where in the certificate chain the error occurred. If
7855 it is zero it occurred in the end entity certificate, one if it is
7856 the certificate which signed the end entity certificate and so on.
7857 my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
7859 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7860 #
7861 # returns: (integer) depth
7862 Check openssl doc
7864 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7865 · X509_STORE_CTX_get_ex_data
7867 Is used to retrieve the information for $idx from $x509_store_ctx.
7869 my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
7871 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7872 # $idx - (integer) index for application specific data
7873 #
7874 # returns: pointer to ???
7875 · X509_STORE_CTX_set_ex_data
7877 Is used to store application data at arg for idx into
7879 $x509_store_ctx.
7880 my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
7882 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7883 # $idx - (integer) ???
7884 # $data - (pointer) ???
7885 #
7886 # returns: 1 on success, 0 on failure
7887 · X509_STORE_CTX_set_cert
7889 Sets the certificate to be verified in $x509_store_ctx to $x.
7891 Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
7893 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7894 # $x - value corresponding to openssl's X509 structure
7895 #
7896 # returns: no return value
7897 Check openssl doc
7899 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
7900 · X509_STORE_new
7902 Returns a newly initialized X509_STORE structure.
7904 my $rv = Net::SSLeay::X509_STORE_new(); # # returns: value
7906 corresponding to openssl's X509_STORE structure (0 on failure)
7907 · X509_STORE_free
7909 Frees an X509_STORE structure
7911 Net::SSLeay::X509_STORE_free($x509_store); # $x509_store - value
7913 corresponding to openssl's X509_STORE structure
7914 · X509_STORE_add_lookup
7916 Adds a lookup to an X509_STORE for a given lookup method.
7918 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir; my $rv =
7920 Net::SSLeay::X509_STORE_add_lookup($x509_store, $method); # $method
7921 - value corresponding to openssl's X509_LOOKUP_METHOD structure #
7922 $x509_store - value corresponding to openssl's X509_STORE structure
7923 # # returns: value corresponding to openssl's X509_LOOKUP structure
7924 Check openssl doc
7926 <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
7927 · X509_STORE_CTX_set_error
7929 Sets the error code of $ctx to $s. For example it might be used in
7931 a verification callback to set an error based on additional checks.
7932 Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
7934 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7935 # $s - (integer) error id
7936 #
7937 # returns: no return value
7938 Check openssl doc
7940 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7941 · X509_STORE_add_cert
7943 Adds X509 certificate $x into the X509_STORE $store.
7945 my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
7947 # $store - value corresponding to openssl's X509_STORE structure
7948 # $x - value corresponding to openssl's X509 structure
7949 #
7950 # returns: 1 on success, 0 on failure
7951 · X509_STORE_add_crl
7953 Adds X509 CRL $x into the X509_STORE $store.
7955 my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
7957 # $store - value corresponding to openssl's X509_STORE structure
7958 # $x - value corresponding to openssl's X509_CRL structure
7959 #
7960 # returns: 1 on success, 0 on failure
7961 · X509_STORE_set1_param
7963 ??? (more info needed)
7965 my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
7967 # $store - value corresponding to openssl's X509_STORE structure
7968 # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
7969 #
7970 # returns: 1 on success, 0 on failure
7971 · X509_LOOKUP_hash_dir
7973 Returns an X509_LOOKUP structure that instructs an X509_STORE to
7975 load files from a directory containing certificates with filenames
7976 in the format hash.N or crls with filenames in the format hash.rN
7977 my $rv = Net::SSLeay::X509_LOOKUP_hash_dir(); # # returns: value
7979 corresponding to openssl's X509_LOOKUP_METHOD structure, with the
7980 hashed directory method
7981 Check openssl doc
7983 <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
7984 · X509_LOOKUP_add_dir
7986 Add a directory to an X509_LOOKUP structure, usually obtained from
7988 X509_STORE_add_lookup.
7989 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir; my $lookup =
7991 Net::SSLeay::X509_STORE_add_lookup($x509_store, $method); my $type
7992 = &Net::SSLeay::X509_FILETYPE_PEM;
7993 Net::SSLeay::X509_LOOKUP_add_dir($lookup, $dir, $type); # $lookup -
7994 value corresponding to openssl's X509_LOOKUP structure # $dir -
7995 string path to a directory s# $type - constant corresponding to the
7996 type of file in the directory - can be X509_FILETYPE_PEM,
7997 X509_FILETYPE_DEFAULT, or X509_FILETYPE_ASN1
7998 · X509_STORE_set_flags
8000 Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
8002 # $ctx - value corresponding to openssl's X509_STORE structure
8003 # $flags - (unsigned long) flags to be set (bitmask)
8004 #
8005 # returns: no return value
8006 #to create $flags value use corresponding constants like
8008 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8009 For more details about $flags bitmask see
8011 "X509_VERIFY_PARAM_set_flags".
8012 · X509_STORE_set_purpose
8014 Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
8016 # $ctx - value corresponding to openssl's X509_STORE structure
8017 # $purpose - (integer) purpose identifier
8018 #
8019 # returns: no return value
8020 For more details about $purpose identifier check "CTX_set_purpose".
8022 · X509_STORE_set_trust
8024 Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
8026 # $ctx - value corresponding to openssl's X509_STORE structure
8027 # $trust - (integer) trust identifier
8028 #
8029 # returns: no return value
8030 For more details about $trust identifier check "CTX_set_trust".
8032 Low Level API: X509_INFO related functions
8034 · sk_X509_INFO_num
8036 Returns the number of values in a STACK_OF(X509_INFO) structure.
8038 my $rv = Net::SSLeay::sk_X509_INFO_num($sk_x509_info);
8040 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8041 #
8042 # returns: number of values in $sk_X509_info
8043 · sk_X509_INFO_value
8045 Returns the value of a STACK_OF(X509_INFO) structure at a given
8047 index.
8048 my $rv = Net::SSLeay::sk_X509_INFO_value($sk_x509_info, $index);
8050 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8051 # $index - index into the stack
8052 #
8053 # returns: value corresponding to openssl's X509_INFO structure at the given index
8054 · P_X509_INFO_get_x509
8056 Returns the X509 structure stored in an X509_INFO structure.
8058 my $rv = Net::SSLeay::P_X509_INFO_get_x509($x509_info);
8060 # $x509_info - value corresponding to openssl's X509_INFO structure
8061 #
8062 # returns: value corresponding to openssl's X509 structure
8063 Low level API: X509_VERIFY_PARAM_* related functions
8065 · X509_VERIFY_PARAM_add0_policy
8067 Enables policy checking (it is disabled by default) and adds
8069 $policy to the acceptable policy set.
8070 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
8072 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8073 # $policy - value corresponding to openssl's ASN1_OBJECT structure
8074 #
8075 # returns: 1 on success, 0 on failure
8076 Check openssl doc
8078 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8079 · X509_VERIFY_PARAM_add0_table
8081 ??? (more info needed)
8083 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
8085 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8086 #
8087 # returns: 1 on success, 0 on failure
8088 · X509_VERIFY_PARAM_add1_host
8090 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8092 requires at least OpenSSL 1.0.2
8093 Adds an additional reference identifier that can match the peer's
8095 certificate.
8096 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add1_host($param, $name);
8098 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8099 # $name - (string) name to be set
8100 #
8101 # returns: 1 on success, 0 on failure
8102 See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
8104 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8105 wildcard matching.
8106 Check openssl doc
8108 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8109 · X509_VERIFY_PARAM_clear_flags
8111 Clears the flags $flags in param.
8113 my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
8115 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8116 # $flags - (unsigned long) flags to be set (bitmask)
8117 #
8118 # returns: 1 on success, 0 on failure
8119 For more details about $flags bitmask see
8121 "X509_VERIFY_PARAM_set_flags".
8122 Check openssl doc
8124 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8125 · X509_VERIFY_PARAM_free
8127 Frees up the X509_VERIFY_PARAM structure.
8129 Net::SSLeay::X509_VERIFY_PARAM_free($param);
8131 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8132 #
8133 # returns: no return value
8134 · X509_VERIFY_PARAM_get0_peername
8136 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8138 requires at least OpenSSL 1.0.2
8139 Returns the DNS hostname or subject CommonName from the peer
8141 certificate that matched one of the reference identifiers.
8142 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get0_peername($param);
8144 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8145 #
8146 # returns: (string) name e.g. '*.example.com' or undef
8147 Check openssl doc
8149 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8150 · X509_VERIFY_PARAM_get_depth
8152 Returns the current verification depth.
8154 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
8156 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8157 #
8158 # returns: (ineger) depth
8159 Check openssl doc
8161 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8162 · X509_VERIFY_PARAM_get_flags
8164 Returns the current verification flags.
8166 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
8168 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8169 #
8170 # returns: (unsigned long) flags to be set (bitmask)
8171 For more details about returned flags bitmask see
8173 "X509_VERIFY_PARAM_set_flags".
8174 Check openssl doc
8176 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8177 · X509_VERIFY_PARAM_set_flags
8179 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
8181 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8182 # $flags - (unsigned long) flags to be set (bitmask)
8183 #
8184 # returns: 1 on success, 0 on failure
8185 #to create $flags value use corresponding constants like
8187 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8188 For more details about $flags bitmask, see the OpenSSL docs below.
8190 Check openssl doc
8192 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8193 · X509_VERIFY_PARAM_inherit
8195 ??? (more info needed)
8197 my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
8199 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8200 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8201 #
8202 # returns: 1 on success, 0 on failure
8203 · X509_VERIFY_PARAM_lookup
8205 Finds X509_VERIFY_PARAM by name.
8207 my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
8209 # $name - (string) name we want to find
8210 #
8211 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8212 · X509_VERIFY_PARAM_new
8214 Creates a new X509_VERIFY_PARAM structure.
8216 my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
8218 #
8219 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8220 · X509_VERIFY_PARAM_set1
8222 Sets the name of X509_VERIFY_PARAM structure $to to the same value
8224 as the name of X509_VERIFY_PARAM structure $from.
8225 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
8227 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8228 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8229 #
8230 # returns: 1 on success, 0 on failure
8231 · X509_VERIFY_PARAM_set1_email
8233 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8235 requires at least OpenSSL 1.0.2
8236 Sets the expected RFC822 email address to email.
8238 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_email($param, $email);
8240 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8241 # $email - (string) email to be set
8242 #
8243 # returns: 1 on success, 0 on failure
8244 Check openssl doc
8246 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8247 · X509_VERIFY_PARAM_set1_host
8249 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8251 requires at least OpenSSL 1.0.2
8252 Sets the expected DNS hostname to name clearing any previously
8254 specified host name or names.
8255 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_host($param, $name);
8257 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8258 # $name - (string) name to be set
8259 #
8260 # returns: 1 on success, 0 on failure
8261 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8263 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8264 wildcard matching.
8265 Check openssl doc
8267 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8268 · X509_VERIFY_PARAM_set1_ip
8270 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8272 requires at least OpenSSL 1.0.2
8273 Sets the expected IP address to ip.
8275 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_ip($param, $ip);
8277 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8278 # $ip - (binary) 4 octet IPv4 or 16 octet IPv6 address
8279 #
8280 # returns: 1 on success, 0 on failure
8281 Check openssl doc
8283 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8284 · X509_VERIFY_PARAM_set1_ip_asc
8286 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8288 requires at least OpenSSL 1.0.2
8289 Sets the expected IP address to ipasc.
8291 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_asc($param, $ipasc);
8293 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8294 # $ip - (string) IPv4 or IPv6 address
8295 #
8296 # returns: 1 on success, 0 on failure
8297 Check openssl doc
8299 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8300 · X509_VERIFY_PARAM_set1_name
8302 Sets the name of X509_VERIFY_PARAM structure $param to $name.
8304 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
8306 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8307 # $name - (string) name to be set
8308 #
8309 # returns: 1 on success, 0 on failure
8310 · X509_VERIFY_PARAM_set1_policies
8312 Enables policy checking (it is disabled by default) and sets the
8314 acceptable policy set to policies. Any existing policy set is
8315 cleared. The policies parameter can be 0 to clear an existing
8316 policy set.
8317 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
8319 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8320 # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
8321 #
8322 # returns: 1 on success, 0 on failure
8323 Check openssl doc
8325 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8326 · X509_VERIFY_PARAM_set_depth
8328 Sets the maximum verification depth to depth. That is the maximum
8330 number of untrusted CA certificates that can appear in a chain.
8331 Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
8333 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8334 # $depth - (integer) depth to be set
8335 #
8336 # returns: no return value
8337 Check openssl doc
8339 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8340 · X509_VERIFY_PARAM_set_hostflags
8342 Net::SSLeay::X509_VERIFY_PARAM_set_hostflags($param, $flags);
8344 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8345 # $flags - (unsigned int) flags to be set (bitmask)
8346 #
8347 # returns: no return value
8348 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8350 "X509_VERIFY_PARAM_set1_host" for more information. The flags for
8351 controlling wildcard checks and other features are defined in
8352 OpenSSL docs.
8353 Check openssl doc
8355 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8356 · X509_VERIFY_PARAM_set_purpose
8358 Sets the verification purpose in $param to $purpose. This
8360 determines the acceptable purpose of the certificate chain, for
8361 example SSL client or SSL server.
8362 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
8364 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8365 # $purpose - (integer) purpose identifier
8366 #
8367 # returns: 1 on success, 0 on failure
8368 For more details about $purpose identifier check "CTX_set_purpose".
8370 Check openssl doc
8372 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8373 · X509_VERIFY_PARAM_set_time
8375 Sets the verification time in $param to $t. Normally the current
8377 time is used.
8378 Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
8380 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8381 # $t - (time_t) time in seconds since 1.1.1970
8382 #
8383 # returns: no return value
8384 Check openssl doc
8386 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8387 · X509_VERIFY_PARAM_set_trust
8389 Sets the trust setting in $param to $trust.
8391 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
8393 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8394 # $trust - (integer) trust identifier
8395 #
8396 # returns: 1 on success, 0 on failure
8397 For more details about $trust identifier check "CTX_set_trust".
8399 Check openssl doc
8401 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8402 · X509_VERIFY_PARAM_table_cleanup
8404 ??? (more info needed)
8406 Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
8408 #
8409 # returns: no return value
8410 Low level API: Cipher (EVP_CIPHER_*) related functions
8412 · EVP_get_cipherbyname
8414 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8416 Returns an EVP_CIPHER structure when passed a cipher name.
8418 my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
8420 # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
8421 #
8422 # returns: value corresponding to openssl's EVP_CIPHER structure
8423 Check openssl doc
8425 <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
8426 Low level API: Digest (EVP_MD_*) related functions
8428 · OpenSSL_add_all_digests
8430 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8432 Net::SSLeay::OpenSSL_add_all_digests();
8434 # no args, no return value
8435 http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
8437 · P_EVP_MD_list_all
8439 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8441 requires at least openssl-1.0.0
8442 NOTE: Does not exactly correspond to any low level API function
8444 my $rv = Net::SSLeay::P_EVP_MD_list_all();
8446 #
8447 # returns: arrayref - list of available digest names
8448 The returned digest names correspond to values expected by
8450 "EVP_get_digestbyname".
8451 Note that some of the digests are available by default and some
8453 only after calling "OpenSSL_add_all_digests".
8454 · EVP_get_digestbyname
8456 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8458 my $rv = Net::SSLeay::EVP_get_digestbyname($name);
8460 # $name - string with digest name
8461 #
8462 # returns: value corresponding to openssl's EVP_MD structure
8463 The $name param can be:
8465 md2
8467 md4
8468 md5
8469 mdc2
8470 ripemd160
8471 sha
8472 sha1
8473 sha224
8474 sha256
8475 sha512
8476 whirlpool
8477 Or better check the supported digests by calling
8479 "P_EVP_MD_list_all".
8480 · EVP_MD_type
8482 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8484 my $rv = Net::SSLeay::EVP_MD_type($md);
8486 # $md - value corresponding to openssl's EVP_MD structure
8487 #
8488 # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
8489 · EVP_MD_size
8491 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8493 my $rv = Net::SSLeay::EVP_MD_size($md);
8495 # $md - value corresponding to openssl's EVP_MD structure
8496 #
8497 # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
8498 · EVP_MD_CTX_md
8500 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8502 requires at least openssl-0.9.7
8503 Net::SSLeay::EVP_MD_CTX_md($ctx);
8505 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8506 #
8507 # returns: value corresponding to openssl's EVP_MD structure
8508 · EVP_MD_CTX_create
8510 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8512 requires at least openssl-0.9.7
8513 Allocates, initializes and returns a digest context.
8515 my $rv = Net::SSLeay::EVP_MD_CTX_create();
8517 #
8518 # returns: value corresponding to openssl's EVP_MD_CTX structure
8519 The complete idea behind EVP_MD_CTX looks like this example:
8521 Net::SSLeay::OpenSSL_add_all_digests();
8523 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
8525 my $ctx = Net::SSLeay::EVP_MD_CTX_create();
8526 Net::SSLeay::EVP_DigestInit($ctx, $md);
8527 while(my $chunk = get_piece_of_data()) {
8529 Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
8530 }
8531 my $result = Net::SSLeay::EVP_DigestFinal($ctx);
8533 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8534 print "digest=", unpack('H*', $result), "\n"; #print hex value
8536 · EVP_DigestInit_ex
8538 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8540 requires at least openssl-0.9.7
8541 Sets up digest context $ctx to use a digest $type from ENGINE
8543 $impl, $ctx must be initialized before calling this function, type
8544 will typically be supplied by a function such as
8545 "EVP_get_digestbyname". If $impl is 0 then the default
8546 implementation of digest $type is used.
8547 my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
8549 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8550 # $type - value corresponding to openssl's EVP_MD structure
8551 # $impl - value corresponding to openssl's ENGINE structure
8552 #
8553 # returns: 1 for success and 0 for failure
8554 · EVP_DigestInit
8556 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8558 requires at least openssl-0.9.7
8559 Behaves in the same way as "EVP_DigestInit_ex" except the passed
8561 context $ctx does not have to be initialized, and it always uses
8562 the default digest implementation.
8563 my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
8565 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8566 # $type - value corresponding to openssl's EVP_MD structure
8567 #
8568 # returns: 1 for success and 0 for failure
8569 · EVP_MD_CTX_destroy
8571 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8573 requires at least openssl-0.9.7
8574 Cleans up digest context $ctx and frees up the space allocated to
8576 it, it should be called only on a context created using
8577 "EVP_MD_CTX_create".
8578 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8580 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8581 #
8582 # returns: no return value
8583 · EVP_DigestUpdate
8585 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8587 requires at least openssl-0.9.7
8588 my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
8590 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8591 # $data - data to be hashed
8592 #
8593 # returns: 1 for success and 0 for failure
8594 · EVP_DigestFinal_ex
8596 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8598 requires at least openssl-0.9.7
8599 Retrieves the digest value from $ctx. After calling
8601 "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
8602 be made, but "EVP_DigestInit_ex" can be called to initialize a new
8603 digest operation.
8604 my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
8606 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8607 #
8608 # returns: hash value (binary)
8609 #to get printable (hex) value of digest use:
8611 print unpack('H*', $digest_value);
8612 · EVP_DigestFinal
8614 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8616 requires at least openssl-0.9.7
8617 Similar to "EVP_DigestFinal_ex" except the digest context ctx is
8619 automatically cleaned up.
8620 my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
8622 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8623 #
8624 # returns: hash value (binary)
8625 #to get printable (hex) value of digest use:
8627 print unpack('H*', $digest_value);
8628 · MD2
8630 COMPATIBILITY: no supported by default in openssl-1.0.0
8632 Computes MD2 from given $data (all data needs to be loaded into
8634 memory)
8635 my $digest = Net::SSLeay::MD2($data);
8637 print "digest(hexadecimal)=", unpack('H*', $digest);
8638 · MD4
8640 Computes MD4 from given $data (all data needs to be loaded into
8642 memory)
8643 my $digest = Net::SSLeay::MD4($data);
8645 print "digest(hexadecimal)=", unpack('H*', $digest);
8646 · MD5
8648 Computes MD5 from given $data (all data needs to be loaded into
8650 memory)
8651 my $digest = Net::SSLeay::MD5($data);
8653 print "digest(hexadecimal)=", unpack('H*', $digest);
8654 · RIPEMD160
8656 Computes RIPEMD160 from given $data (all data needs to be loaded
8658 into memory)
8659 my $digest = Net::SSLeay::RIPEMD160($data);
8661 print "digest(hexadecimal)=", unpack('H*', $digest);
8662 · SHA1
8664 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8666 Computes SHA1 from given $data (all data needs to be loaded into
8668 memory)
8669 my $digest = Net::SSLeay::SHA1($data);
8671 print "digest(hexadecimal)=", unpack('H*', $digest);
8672 · SHA256
8674 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8676 requires at least openssl-0.9.8
8677 Computes SHA256 from given $data (all data needs to be loaded into
8679 memory)
8680 my $digest = Net::SSLeay::SHA256($data);
8682 print "digest(hexadecimal)=", unpack('H*', $digest);
8683 · SHA512
8685 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8687 requires at least openssl-0.9.8
8688 Computes SHA512 from given $data (all data needs to be loaded into
8690 memory)
8691 my $digest = Net::SSLeay::SHA512($data);
8693 print "digest(hexadecimal)=", unpack('H*', $digest);
8694 · EVP_Digest
8696 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8698 requires at least openssl-0.9.7
8699 Computes "any" digest from given $data (all data needs to be loaded
8701 into memory)
8702 my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
8704 my $digest = Net::SSLeay::EVP_Digest($data, $md);
8705 print "digest(hexadecimal)=", unpack('H*', $digest);
8706 · EVP_sha1
8708 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8710 my $md = Net::SSLeay::EVP_sha1();
8712 #
8713 # returns: value corresponding to openssl's EVP_MD structure
8714 · EVP_sha256
8716 COMPATIBILITY: requires at least openssl-0.9.8
8718 my $md = Net::SSLeay::EVP_sha256();
8720 #
8721 # returns: value corresponding to openssl's EVP_MD structure
8722 · EVP_sha512
8724 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8726 requires at least openssl-0.9.8
8727 my $md = Net::SSLeay::EVP_sha512();
8729 #
8730 # returns: value corresponding to openssl's EVP_MD structure
8731 · EVP_add_digest
8733 my $rv = Net::SSLeay::EVP_add_digest($digest);
8735 # $digest - value corresponding to openssl's EVP_MD structure
8736 #
8737 # returns: 1 on success, 0 otherwise
8738 Low level API: CIPHER_* related functions
8740 · CIPHER_get_name
8742 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8744 Returns name of the cipher used.
8746 my $rv = Net::SSLeay::CIPHER_description($cipher);
8748 # $cipher - value corresponding to openssl's SSL_CIPHER structure
8749 #
8750 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA'
8751 Check openssl doc
8753 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8754 Example:
8756 my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
8758 my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
8759 · CIPHER_description
8761 Returns a textual description of the cipher used.
8763 ??? (does this function really work?)
8765 my $rv = Net::SSLeay::CIPHER_description($cipher, $buf, $size);
8767 # $cipher - value corresponding to openssl's SSL_CIPHER structure
8768 # $bufer - (string/buffer) ???
8769 # $size - (integer) ???
8770 #
8771 # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
8772 Check openssl doc
8774 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8775 · CIPHER_get_bits
8777 Returns the number of secret bits used for cipher.
8779 my $rv = Net::SSLeay::CIPHER_get_bits($c);
8781 # $c - value corresponding to openssl's SSL_CIPHER structure
8782 #
8783 # returns: (integert) number of secret bits, 0 on error
8784 Check openssl doc
8786 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8787 Low level API: RSA_* related functions
8789 · RSA_generate_key
8791 Generates a key pair and returns it in a newly allocated RSA
8793 structure. The pseudo-random number generator must be seeded prior
8794 to calling RSA_generate_key.
8795 my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
8797 # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
8798 # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
8799 # $perl_cb - [optional] reference to perl callback function
8800 # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
8801 #
8802 # returns: value corresponding to openssl's RSA structure (0 on failure)
8803 Check openssl doc
8805 <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
8806 · RSA_free
8808 Frees the RSA structure and its components. The key is erased
8810 before the memory is returned to the system.
8811 Net::SSLeay::RSA_free($r);
8813 # $r - value corresponding to openssl's RSA structure
8814 #
8815 # returns: no return value
8816 Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
8818 · RSA_get_key_parameters
8820 Returns a list of pointers to BIGNUMs representing the parameters
8822 of the key in this order: (n, e, d, p, q, dmp1, dmq1, iqmp)
8823 Caution: returned list consists of SV pointers to BIGNUMs, which
8824 would need to be blessed as Crypt::OpenSSL::Bignum for further use
8825 my (@params) = RSA_get_key_parameters($r);
8827 Low level API: BIO_* related functions
8829 · BIO_eof
8831 Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
8833 varies according to the BIO type.
8834 my $rv = Net::SSLeay::BIO_eof($s);
8836 # $s - value corresponding to openssl's BIO structure
8837 #
8838 # returns: 1 if EOF has been reached 0 otherwise
8839 Check openssl doc
8841 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8842 · BIO_f_ssl
8844 Returns the SSL BIO method. This is a filter BIO which is a wrapper
8846 round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
8847 my $rv = Net::SSLeay::BIO_f_ssl();
8849 #
8850 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8851 Check openssl doc
8853 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8854 · BIO_free
8856 Frees up a single BIO.
8858 my $rv = Net::SSLeay::BIO_free($bio;);
8860 # $bio; - value corresponding to openssl's BIO structure
8861 #
8862 # returns: 1 on success, 0 on failure
8863 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8865 · BIO_new
8867 Returns a new BIO using method $type
8869 my $rv = Net::SSLeay::BIO_new($type);
8871 # $type - value corresponding to openssl's BIO_METHOD structure
8872 #
8873 # returns: value corresponding to openssl's BIO structure (0 on failure)
8874 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8876 · BIO_new_buffer_ssl_connect
8878 Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
8880 (using ctx) and a connect BIO.
8881 my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
8883 # $ctx - value corresponding to openssl's SSL_CTX structure
8884 #
8885 # returns: value corresponding to openssl's BIO structure (0 on failure)
8886 Check openssl doc
8888 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8889 · BIO_new_file
8891 Creates a new file BIO with mode $mode the meaning of mode is the
8893 same as the stdio function fopen(). The BIO_CLOSE flag is set on
8894 the returned BIO.
8895 my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
8897 # $filename - (string) filename
8898 # $mode - (string) opening mode (as mode by stdio function fopen)
8899 #
8900 # returns: value corresponding to openssl's BIO structure (0 on failure)
8901 Check openssl doc
8903 <http://www.openssl.org/docs/crypto/BIO_s_file.html>
8904 · BIO_new_ssl
8906 Allocates an SSL BIO using SSL_CTX ctx and using client mode if
8908 client is non zero.
8909 my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
8911 # $ctx - value corresponding to openssl's SSL_CTX structure
8912 # $client - (integer) 0 or 1 - indicates ssl client mode
8913 #
8914 # returns: value corresponding to openssl's BIO structure (0 on failure)
8915 Check openssl doc
8917 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8918 · BIO_new_ssl_connect
8920 Creates a new BIO chain consisting of an SSL BIO (using ctx)
8922 followed by a connect BIO.
8923 my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
8925 # $ctx - value corresponding to openssl's SSL_CTX structure
8926 #
8927 # returns: value corresponding to openssl's BIO structure (0 on failure)
8928 Check openssl doc
8930 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8931 · BIO_pending
8933 Return the number of pending characters in the BIOs read buffers.
8935 my $rv = Net::SSLeay::BIO_pending($s);
8937 # $s - value corresponding to openssl's BIO structure
8938 #
8939 # returns: the amount of pending data
8940 Check openssl doc
8942 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8943 · BIO_wpending
8945 Return the number of pending characters in the BIOs write buffers.
8947 my $rv = Net::SSLeay::BIO_wpending($s);
8949 # $s - value corresponding to openssl's BIO structure
8950 #
8951 # returns: the amount of pending data
8952 Check openssl doc
8954 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8955 · BIO_read
8957 Read the underlying descriptor.
8959 Net::SSLeay::BIO_read($s, $max);
8961 # $s - value corresponding to openssl's BIO structure
8962 # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
8963 #
8964 # returns: data
8965 Check openssl doc
8967 <http://www.openssl.org/docs/crypto/BIO_read.html>
8968 · BIO_write
8970 Attempts to write data from $buffer to BIO $b.
8972 my $rv = Net::SSLeay::BIO_write($b, $buffer);
8974 # $b - value corresponding to openssl's BIO structure
8975 # $buffer - data
8976 #
8977 # returns: amount of data successfully written
8978 # or that no data was successfully read or written if the result is 0 or -1
8979 # or -2 when the operation is not implemented in the specific BIO type
8980 Check openssl doc
8982 <http://www.openssl.org/docs/crypto/BIO_read.html>
8983 · BIO_s_mem
8985 Return the memory BIO method function.
8987 my $rv = Net::SSLeay::BIO_s_mem();
8989 #
8990 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8991 Check openssl doc
8993 <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
8994 · BIO_ssl_copy_session_id
8996 Copies an SSL session id between BIO chains from and to. It does
8998 this by locating the SSL BIOs in each chain and calling
8999 SSL_copy_session_id() on the internal SSL pointer.
9000 my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
9002 # $to - value corresponding to openssl's BIO structure
9003 # $from - value corresponding to openssl's BIO structure
9004 #
9005 # returns: 1 on success, 0 on failure
9006 Check openssl doc
9008 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9009 · BIO_ssl_shutdown
9011 Closes down an SSL connection on BIO chain bio. It does this by
9013 locating the SSL BIO in the chain and calling SSL_shutdown() on its
9014 internal SSL pointer.
9015 Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
9017 # $ssl_bio - value corresponding to openssl's BIO structure
9018 #
9019 # returns: no return value
9020 Check openssl doc
9022 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9023 Low level API: Server side Server Name Indication (SNI) support
9025 · set_tlsext_host_name
9027 TBA
9029 · get_servername
9031 TBA
9033 · get_servername_type
9035 TBA
9037 · CTX_set_tlsext_servername_callback
9039 COMPATIBILITY: requires at least OpenSSL 0.9.8f
9041 This function is used in a server to support Server side Server
9043 Name Indication (SNI).
9044 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
9046 # $ctx - SSL context
9047 # $code - reference to a subroutine that will be called when a new connection is being initiated
9048 #
9049 # returns: no return value
9050 On the client side:
9051 use set_tlsext_host_name($ssl, $servername) before initiating the SSL connection.
9052 On the server side: Set up an additional SSL_CTX() for each
9054 different certificate;
9055 Add a servername callback to each SSL_CTX() using
9057 CTX_set_tlsext_servername_callback();
9058 The callback function is required to retrieve the client-supplied
9060 servername with get_servername(ssl). Figure out the right SSL_CTX
9061 to go with that host name, then switch the SSL object to that
9062 SSL_CTX with set_SSL_CTX().
9063 Example:
9065 # set callback
9067 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
9068 sub {
9069 my $ssl = shift;
9070 my $h = Net::SSLeay::get_servername($ssl);
9071 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9072 } );
9073 More complete example:
9075 # ... initialize Net::SSLeay
9077 my %hostnames = (
9079 'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
9080 'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
9081 );
9082 # create a new context for each certificate/key pair
9084 for my $name (keys %hostnames) {
9085 $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
9086 Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
9087 Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
9088 $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
9089 }
9090 # create default context
9092 my $ctx = Net::SSLeay::CTX_new or die;
9093 Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
9094 Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
9095 # set callback
9097 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
9098 my $ssl = shift;
9099 my $h = Net::SSLeay::get_servername($ssl);
9100 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9101 } );
9102 # ... later
9104 $s = Net::SSLeay::new($ctx);
9106 Net::SSLeay::set_fd($s, fileno($accepted_socket));
9107 Net::SSLeay::accept($s);
9108 Low level API: NPN (next protocol negotiation) related functions
9110 NPN is being replaced with ALPN, a more recent TLS extension for
9112 application protocol negotiation that's in process of being adopted by
9113 IETF. Please look below for APLN API description.
9114 Simple approach for using NPN support looks like this:
9116 ### client side
9118 use Net::SSLeay;
9119 use IO::Socket::INET;
9120 Net::SSLeay::initialize();
9122 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9123 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9124 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9125 Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
9126 my $ssl = Net::SSLeay::new($ctx) or die;
9127 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9128 Net::SSLeay::connect($ssl);
9129 warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
9131 warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
9132 ### server side
9134 use Net::SSLeay;
9135 use IO::Socket::INET;
9136 Net::SSLeay::initialize();
9138 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9139 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9140 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9141 Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
9142 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9143 while (1) {
9145 my $ssl = Net::SSLeay::new($ctx);
9146 warn("server:waiting for incoming connection...\n");
9147 my $fd = $sock->accept();
9148 Net::SSLeay::set_fd($ssl, $fd->fileno);
9149 Net::SSLeay::accept($ssl);
9150 warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
9151 my $got = Net::SSLeay::read($ssl);
9152 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9153 Net::SSLeay::free($ssl);
9154 $fd->close();
9155 }
9156 # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
9157 Please note that the selection (negotiation) is performed by client
9159 side, the server side simply advertise the list of supported protocols.
9160 Advanced approach allows you to implement your own negotiation
9162 algorithm.
9163 #see below documentation for:
9165 Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9166 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9167 Detection of NPN support (works even in older Net::SSLeay versions):
9169 use Net::SSLeay;
9171 if (exists &Net::SSLeay::P_next_proto_negotiated) {
9173 # do NPN stuff
9174 }
9175 · CTX_set_next_proto_select_cb
9177 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9179 requires at least openssl-1.0.1
9180 NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
9182 connection.
9183 Simple usage - in this case a "common" negotiation algorithm (as
9185 implemented by openssl's function SSL_select_next_proto) is used.
9186 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
9188 # $ctx - value corresponding to openssl's SSL_CTX structure
9189 # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
9190 #
9191 # returns: 0 on success, 1 on failure
9192 Advanced usage (you probably do not need this):
9194 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9196 # $ctx - value corresponding to openssl's SSL_CTX structure
9197 # $perl_callback_function - reference to perl function
9198 # $callback_data - [optional] data to passed to callback function when invoked
9199 #
9200 # returns: 0 on success, 1 on failure
9201 # where callback function looks like
9203 sub npn_advertised_cb_invoke {
9204 my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
9205 my $status;
9206 # ...
9207 $status = 1; #status can be:
9208 # 0 - OPENSSL_NPN_UNSUPPORTED
9209 # 1 - OPENSSL_NPN_NEGOTIATED
9210 # 2 - OPENSSL_NPN_NO_OVERLAP
9211 return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
9212 }
9213 To undefine/clear this callback use:
9215 Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
9217 · CTX_set_next_protos_advertised_cb
9219 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9221 requires at least openssl-1.0.1
9222 NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
9224 connection.
9225 Simple usage:
9227 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
9229 # $ctx - value corresponding to openssl's SSL_CTX structure
9230 # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
9231 #
9232 # returns: 0 on success, 1 on failure
9233 Advanced usage (you probably do not need this):
9235 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9237 # $ctx - value corresponding to openssl's SSL_CTX structure
9238 # $perl_callback_function - reference to perl function
9239 # $callback_data - [optional] data to passed to callback function when invoked
9240 #
9241 # returns: 0 on success, 1 on failure
9242 # where callback function looks like
9244 sub npn_advertised_cb_invoke {
9245 my ($ssl, $callback_data) = @_;
9246 # ...
9247 return ['http1.1','spdy/2']; # the callback has to return arrayref
9248 }
9249 To undefine/clear this callback use:
9251 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
9253 · P_next_proto_negotiated
9255 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9257 requires at least openssl-1.0.1
9258 Returns the name of negotiated protocol for given SSL connection
9260 $ssl.
9261 $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
9263 # $ssl - value corresponding to openssl's SSL structure
9264 #
9265 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9266 · P_next_proto_last_status
9268 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9270 requires at least openssl-1.0.1
9271 Returns the result of the last negotiation for given SSL connection
9273 $ssl.
9274 $rv = Net::SSLeay::P_next_proto_last_status($ssl)
9276 # $ssl - value corresponding to openssl's SSL structure
9277 #
9278 # returns: (integer) negotiation status
9279 # 0 - OPENSSL_NPN_UNSUPPORTED
9280 # 1 - OPENSSL_NPN_NEGOTIATED
9281 # 2 - OPENSSL_NPN_NO_OVERLAP
9282 Low level API: ALPN (application layer protocol negotiation) related
9284 functions
9285 Application protocol can be negotiated via two different mechanisms
9287 employing two different TLS extensions: NPN (obsolete) and ALPN
9288 (recommended).
9289 The API is rather similar, with slight differences reflecting protocol
9291 specifics. In particular, with ALPN the protocol negotiation takes
9292 place on server, while with NPN the client implements the protocol
9293 negotiation logic.
9294 With ALPN, the most basic implementation looks like this:
9296 ### client side
9298 use Net::SSLeay;
9299 use IO::Socket::INET;
9300 Net::SSLeay::initialize();
9302 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9303 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9304 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9305 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9306 my $ssl = Net::SSLeay::new($ctx) or die;
9307 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9308 Net::SSLeay::connect($ssl);
9309 warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
9311 ### server side
9313 use Net::SSLeay;
9314 use IO::Socket::INET;
9315 Net::SSLeay::initialize();
9317 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9318 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9319 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9320 Net::SSLeay::CTX_set_alpn_select_cb($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9321 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9322 while (1) {
9324 my $ssl = Net::SSLeay::new($ctx);
9325 warn("server:waiting for incoming connection...\n");
9326 my $fd = $sock->accept();
9327 Net::SSLeay::set_fd($ssl, $fd->fileno);
9328 Net::SSLeay::accept($ssl);
9329 warn "server:selected=",Net::SSLeay::P_alpn_selected($ssl),"\n";
9330 my $got = Net::SSLeay::read($ssl);
9331 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9332 Net::SSLeay::free($ssl);
9333 $fd->close();
9334 }
9335 # check with: openssl s_client -connect localhost:5443 -alpn spdy/3,http/1.1
9336 Advanced approach allows you to implement your own negotiation
9338 algorithm.
9339 #see below documentation for:
9341 Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9342 Detection of ALPN support (works even in older Net::SSLeay versions):
9344 use Net::SSLeay;
9346 if (exists &Net::SSLeay::P_alpn_selected) {
9348 # do ALPN stuff
9349 }
9350 · CTX_set_alpn_select_cb
9352 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9354 requires at least openssl-1.0.2
9355 NOTE: You need CTX_set_alpn_select_cb on server side of TLS
9357 connection.
9358 Simple usage - in this case a "common" negotiation algorithm (as
9360 implemented by openssl's function SSL_select_next_proto) is used.
9361 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $arrayref);
9363 # $ctx - value corresponding to openssl's SSL_CTX structure
9364 # $arrayref - list of accepted protocols - e.g. ['http/2.0', 'http/1.1', 'spdy/3']
9365 #
9366 # returns: 0 on success, 1 on failure
9367 Advanced usage (you probably do not need this):
9369 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9371 # $ctx - value corresponding to openssl's SSL_CTX structure
9372 # $perl_callback_function - reference to perl function
9373 # $callback_data - [optional] data to passed to callback function when invoked
9374 #
9375 # returns: 0 on success, 1 on failure
9376 # where callback function looks like
9378 sub alpn_select_cb_invoke {
9379 my ($ssl, $arrayref_proto_list_advertised_by_client, $callback_data) = @_;
9380 # ...
9381 if ($negotiated) {
9382 return 'http/2.0';
9383 } else {
9384 return undef;
9385 }
9386 }
9387 To undefine/clear this callback use:
9389 Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
9391 · set_alpn_protos
9393 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9395 requires at least openssl-1.0.2
9396 NOTE: You need set_alpn_protos on client side of TLS connection.
9398 This adds list of supported application layer protocols to
9400 ClientHello message sent by a client. It advertises the
9401 enumeration of supported protocols:
9402 Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
9404 # returns 0 on success
9405 · CTX_set_alpn_protos
9407 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9409 requires at least openssl-1.0.2
9410 NOTE: You need CTX_set_alpn_protos on client side of TLS
9412 connection.
9413 This adds list of supported application layer protocols to
9415 ClientHello message sent by a client. It advertises the
9416 enumeration of supported protocols:
9417 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9419 # returns 0 on success
9420 · P_alpn_selected
9422 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9424 requires at least openssl-1.0.2
9425 Returns the name of negotiated protocol for given TLS connection
9427 $ssl.
9428 $rv = Net::SSLeay::P_alpn_selected($ssl)
9430 # $ssl - value corresponding to openssl's SSL structure
9431 #
9432 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9433 Low level API: DANE Support
9435 OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
9437 Authentication of Named Entities (DANE) Transport Layer Association
9438 within OpenSSL
9439 · SSL_get_tlsa_record_byname
9441 COMPATIBILITY: DELETED from net-ssleay, since it is not supported
9443 by OpenSSL
9444 In order to facilitate DANE there is additional interface,
9446 SSL_get_tlsa_record_byname, accepting hostname, port and socket
9447 type that returns packed TLSA record. In order to make it even
9448 easier there is additional SSL_ctrl function that calls
9449 SSL_get_tlsa_record_byname for you. Latter is recommended for
9450 programmers that wish to maintain broader binary compatibility,
9451 e.g. make application work with both 1.0.2 and prior version (in
9452 which case call to SSL_ctrl with new code returning error would
9453 have to be ignored when running with prior version).
9454 Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
9456 Low level API: Other functions
9458 · COMP_add_compression_method
9460 Adds the compression method cm with the identifier id to the list
9462 of available compression methods. This list is globally maintained
9463 for all SSL operations within this application. It cannot be set
9464 for specific SSL_CTX or SSL objects.
9465 my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
9467 # $id - (integer) compression method id
9468 # 0 to 63: methods defined by the IETF
9469 # 64 to 192: external party methods assigned by IANA
9470 # 193 to 255: reserved for private use
9471 #
9472 # $cm - value corresponding to openssl's COMP_METHOD structure
9473 #
9474 # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
9475 Check openssl doc
9477 <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
9478 · DH_free
9480 Frees the DH structure and its components. The values are erased
9482 before the memory is returned to the system.
9483 Net::SSLeay::DH_free($dh);
9485 # $dh - value corresponding to openssl's DH structure
9486 #
9487 # returns: no return value
9488 Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
9490 · FIPS_mode_set
9492 Enable or disable FIPS mode in a FIPS capable OpenSSL.
9494 Net::SSLeay:: FIPS_mode_set($enable);
9496 # $enable - (integer) 1 to enable, 0 to disable
9497 Low level API: EC related functions
9499 · CTX_set_tmp_ecdh
9501 TBA
9503 · EC_KEY_free
9505 TBA
9507 · EC_KEY_new_by_curve_name
9509 TBA
9511 · EC_KEY_generate_key
9513 Generates a EC key and returns it in a newly allocated EC_KEY
9515 structure. The EC key then can be used to create a PKEY which can
9516 be used in calls like X509_set_pubkey.
9517 my $key = Net::SSLeay::EVP_PKEY_new();
9519 my $ec = Net::SSLeay::EC_KEY_generate_key($curve);
9520 Net::SSLeay::EVP_PKEY_assign_EC_KEY($key,$ec);
9521 # $curve - curve name like 'secp521r1' or the matching Id (integer) of the curve
9523 #
9524 # returns: value corresponding to openssl's EC_KEY structure (0 on failure)
9525 This function has no equivalent in OpenSSL but combines multiple
9527 OpenSSL functions for an easier interface.
9528 · CTX_set_ecdh_auto, set_ecdh_auto
9530 These functions enable or disable the automatic curve selection on
9532 the server side by calling SSL_CTX_set_ecdh_auto or
9533 SSL_set_ecdh_auto respectively. If enabled the highest preference
9534 curve is automatically used for ECDH temporary keys used during key
9535 exchange. This function is no longer available for OpenSSL 1.1.0
9536 or higher.
9537 Net::SSLeay::CTX_set_ecdh_auto($ctx,1);
9539 Net::SSLeay::set_ecdh_auto($ssl,1);
9540 · CTX_set1_curves_list, set1_curves_list
9542 These functions set the supported curves (in order of preference)
9544 by calling SSL_CTX_set1_curves_list or SSL_set1_curves_list
9545 respectively. For a TLS client these curves are offered to the
9546 server in the supported curves extension while on the server side
9547 these are used to determine the shared curve. These functions are
9548 only available since OpenSSL 1.1.0.
9549 Net::SSLeay::CTX_set1_curves_list($ctx,"P-521:P-384:P-256");
9551 Net::SSLeay::set1_curves_list($ssl,"P-521:P-384:P-256");
9552 · CTX_set1_groups_list, set1_groups_list
9554 These functions set the supported groups (in order of preference)
9556 by calling SSL_CTX_set1_groups_list or SSL_set1_groups_list
9557 respectively. This is practically the same as CTX_set1_curves_list
9558 and set1_curves_list except that all DH groups can be given as
9559 supported by TLS 1.3. These functions are only available since
9560 OpenSSL 1.1.1.
9561 Net::SSLeay::CTX_set1_groups_list($ctx,"P-521:P-384:P-256");
9563 Net::SSLeay::set1_groups_list($ssl,"P-521:P-384:P-256");
9564 Constants
9566 There are many openssl constants available in Net::SSLeay. You can use
9567 them like this:
9568 use Net::SSLeay;
9570 print &Net::SSLeay::NID_commonName;
9571 #or
9572 print Net::SSLeay::NID_commonName();
9573 Or you can import them and use:
9575 use Net::SSLeay qw/NID_commonName/;
9577 print &NID_commonName;
9578 #or
9579 print NID_commonName();
9580 #or
9581 print NID_commonName;
9582 The constants names are derived from openssl constants, however
9584 constants starting with "SSL_" prefix have name with "SSL_" part
9585 stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
9586 "Net::SSleay::OP_ALL"
9587 The list of all available constant names:
9589 ASN1_STRFLGS_ESC_CTRL NID_netscape R_UNKNOWN_REMOTE_ERROR_TYPE
9591 ASN1_STRFLGS_ESC_MSB NID_netscape_base_url R_UNKNOWN_STATE
9592 ASN1_STRFLGS_ESC_QUOTE NID_netscape_ca_policy_url R_X509_LIB
9593 ASN1_STRFLGS_RFC2253 NID_netscape_ca_revocation_url SENT_SHUTDOWN
9594 CB_ACCEPT_EXIT NID_netscape_cert_extension SESSION_ASN1_VERSION
9595 CB_ACCEPT_LOOP NID_netscape_cert_sequence SESS_CACHE_BOTH
9596 CB_ALERT NID_netscape_cert_type SESS_CACHE_CLIENT
9597 CB_CONNECT_EXIT NID_netscape_comment SESS_CACHE_NO_AUTO_CLEAR
9598 CB_CONNECT_LOOP NID_netscape_data_type SESS_CACHE_NO_INTERNAL
9599 CB_EXIT NID_netscape_renewal_url SESS_CACHE_NO_INTERNAL_LOOKUP
9600 CB_HANDSHAKE_DONE NID_netscape_revocation_url SESS_CACHE_NO_INTERNAL_STORE
9601 CB_HANDSHAKE_START NID_netscape_ssl_server_name SESS_CACHE_OFF
9602 CB_LOOP NID_ns_sgc SESS_CACHE_SERVER
9603 CB_READ NID_organizationName SSL3_VERSION
9604 CB_READ_ALERT NID_organizationalUnitName SSLEAY_BUILT_ON
9605 CB_WRITE NID_pbeWithMD2AndDES_CBC SSLEAY_CFLAGS
9606 CB_WRITE_ALERT NID_pbeWithMD2AndRC2_CBC SSLEAY_DIR
9607 ERROR_NONE NID_pbeWithMD5AndCast5_CBC SSLEAY_PLATFORM
9608 ERROR_SSL NID_pbeWithMD5AndDES_CBC SSLEAY_VERSION
9609 ERROR_SYSCALL NID_pbeWithMD5AndRC2_CBC ST_ACCEPT
9610 ERROR_WANT_ACCEPT NID_pbeWithSHA1AndDES_CBC ST_BEFORE
9611 ERROR_WANT_CONNECT NID_pbeWithSHA1AndRC2_CBC ST_CONNECT
9612 ERROR_WANT_READ NID_pbe_WithSHA1And128BitRC2_CBC ST_INIT
9613 ERROR_WANT_WRITE NID_pbe_WithSHA1And128BitRC4 ST_OK
9614 ERROR_WANT_X509_LOOKUP NID_pbe_WithSHA1And2_Key_TripleDES_CBC ST_READ_BODY
9615 ERROR_ZERO_RETURN NID_pbe_WithSHA1And3_Key_TripleDES_CBC ST_READ_HEADER
9616 EVP_PKS_DSA NID_pbe_WithSHA1And40BitRC2_CBC TLS1_1_VERSION
9617 EVP_PKS_EC NID_pbe_WithSHA1And40BitRC4 TLS1_2_VERSION
9618 EVP_PKS_RSA NID_pbes2 TLS1_3_VERSION
9619 EVP_PKT_ENC NID_pbmac1 TLS1_VERSION
9620 EVP_PKT_EXCH NID_pkcs TLSEXT_STATUSTYPE_ocsp
9621 EVP_PKT_EXP NID_pkcs3 VERIFY_CLIENT_ONCE
9622 EVP_PKT_SIGN NID_pkcs7 VERIFY_FAIL_IF_NO_PEER_CERT
9623 EVP_PK_DH NID_pkcs7_data VERIFY_NONE
9624 EVP_PK_DSA NID_pkcs7_digest VERIFY_PEER
9625 EVP_PK_EC NID_pkcs7_encrypted VERIFY_POST_HANDSHAKE
9626 EVP_PK_RSA NID_pkcs7_enveloped V_OCSP_CERTSTATUS_GOOD
9627 FILETYPE_ASN1 NID_pkcs7_signed V_OCSP_CERTSTATUS_REVOKED
9628 FILETYPE_PEM NID_pkcs7_signedAndEnveloped V_OCSP_CERTSTATUS_UNKNOWN
9629 F_CLIENT_CERTIFICATE NID_pkcs8ShroudedKeyBag WRITING
9630 F_CLIENT_HELLO NID_pkcs9 X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
9631 F_CLIENT_MASTER_KEY NID_pkcs9_challengePassword X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
9632 F_D2I_SSL_SESSION NID_pkcs9_contentType X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
9633 F_GET_CLIENT_FINISHED NID_pkcs9_countersignature X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
9634 F_GET_CLIENT_HELLO NID_pkcs9_emailAddress X509_CHECK_FLAG_NO_WILDCARDS
9635 F_GET_CLIENT_MASTER_KEY NID_pkcs9_extCertAttributes X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
9636 F_GET_SERVER_FINISHED NID_pkcs9_messageDigest X509_FILETYPE_ASN1
9637 F_GET_SERVER_HELLO NID_pkcs9_signingTime X509_FILETYPE_DEFAULT
9638 F_GET_SERVER_VERIFY NID_pkcs9_unstructuredAddress X509_FILETYPE_PEM
9639 F_I2D_SSL_SESSION NID_pkcs9_unstructuredName X509_LOOKUP
9640 F_READ_N NID_private_key_usage_period X509_PURPOSE_ANY
9641 F_REQUEST_CERTIFICATE NID_rc2_40_cbc X509_PURPOSE_CRL_SIGN
9642 F_SERVER_HELLO NID_rc2_64_cbc X509_PURPOSE_NS_SSL_SERVER
9643 F_SSL_CERT_NEW NID_rc2_cbc X509_PURPOSE_OCSP_HELPER
9644 F_SSL_GET_NEW_SESSION NID_rc2_cfb64 X509_PURPOSE_SMIME_ENCRYPT
9645 F_SSL_NEW NID_rc2_ecb X509_PURPOSE_SMIME_SIGN
9646 F_SSL_READ NID_rc2_ofb64 X509_PURPOSE_SSL_CLIENT
9647 F_SSL_RSA_PRIVATE_DECRYPT NID_rc4 X509_PURPOSE_SSL_SERVER
9648 F_SSL_RSA_PUBLIC_ENCRYPT NID_rc4_40 X509_PURPOSE_TIMESTAMP_SIGN
9649 F_SSL_SESSION_NEW NID_rc5_cbc X509_TRUST_COMPAT
9650 F_SSL_SESSION_PRINT_FP NID_rc5_cfb64 X509_TRUST_EMAIL
9651 F_SSL_SET_FD NID_rc5_ecb X509_TRUST_OBJECT_SIGN
9652 F_SSL_SET_RFD NID_rc5_ofb64 X509_TRUST_OCSP_REQUEST
9653 F_SSL_SET_WFD NID_ripemd160 X509_TRUST_OCSP_SIGN
9654 F_SSL_USE_CERTIFICATE NID_ripemd160WithRSA X509_TRUST_SSL_CLIENT
9655 F_SSL_USE_CERTIFICATE_ASN1 NID_rle_compression X509_TRUST_SSL_SERVER
9656 F_SSL_USE_CERTIFICATE_FILE NID_rsa X509_TRUST_TSA
9657 F_SSL_USE_PRIVATEKEY NID_rsaEncryption X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH
9658 F_SSL_USE_PRIVATEKEY_ASN1 NID_rsadsi X509_V_ERR_AKID_SKID_MISMATCH
9659 F_SSL_USE_PRIVATEKEY_FILE NID_safeContentsBag X509_V_ERR_APPLICATION_VERIFICATION
9660 F_SSL_USE_RSAPRIVATEKEY NID_sdsiCertificate X509_V_ERR_CA_KEY_TOO_SMALL
9661 F_SSL_USE_RSAPRIVATEKEY_ASN1 NID_secretBag X509_V_ERR_CA_MD_TOO_WEAK
9662 F_SSL_USE_RSAPRIVATEKEY_FILE NID_serialNumber X509_V_ERR_CERT_CHAIN_TOO_LONG
9663 F_WRITE_PENDING NID_server_auth X509_V_ERR_CERT_HAS_EXPIRED
9664 GEN_DIRNAME NID_sha X509_V_ERR_CERT_NOT_YET_VALID
9665 GEN_DNS NID_sha1 X509_V_ERR_CERT_REJECTED
9666 GEN_EDIPARTY NID_sha1WithRSA X509_V_ERR_CERT_REVOKED
9667 GEN_EMAIL NID_sha1WithRSAEncryption X509_V_ERR_CERT_SIGNATURE_FAILURE
9668 GEN_IPADD NID_shaWithRSAEncryption X509_V_ERR_CERT_UNTRUSTED
9669 GEN_OTHERNAME NID_stateOrProvinceName X509_V_ERR_CRL_HAS_EXPIRED
9670 GEN_RID NID_subject_alt_name X509_V_ERR_CRL_NOT_YET_VALID
9671 GEN_URI NID_subject_key_identifier X509_V_ERR_CRL_PATH_VALIDATION_ERROR
9672 GEN_X400 NID_surname X509_V_ERR_CRL_SIGNATURE_FAILURE
9673 LIBRESSL_VERSION_NUMBER NID_sxnet X509_V_ERR_DANE_NO_MATCH
9674 MBSTRING_ASC NID_time_stamp X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
9675 MBSTRING_BMP NID_title X509_V_ERR_DIFFERENT_CRL_SCOPE
9676 MBSTRING_FLAG NID_undef X509_V_ERR_EE_KEY_TOO_SMALL
9677 MBSTRING_UNIV NID_uniqueIdentifier X509_V_ERR_EMAIL_MISMATCH
9678 MBSTRING_UTF8 NID_x509Certificate X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD
9679 MIN_RSA_MODULUS_LENGTH_IN_BYTES NID_x509Crl X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD
9680 MODE_ACCEPT_MOVING_WRITE_BUFFER NID_zlib_compression X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD
9681 MODE_AUTO_RETRY NOTHING X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD
9682 MODE_ENABLE_PARTIAL_WRITE OCSP_RESPONSE_STATUS_INTERNALERROR X509_V_ERR_EXCLUDED_VIOLATION
9683 MODE_RELEASE_BUFFERS OCSP_RESPONSE_STATUS_MALFORMEDREQUEST X509_V_ERR_HOSTNAME_MISMATCH
9684 NID_OCSP_sign OCSP_RESPONSE_STATUS_SIGREQUIRED X509_V_ERR_INVALID_CA
9685 NID_SMIMECapabilities OCSP_RESPONSE_STATUS_SUCCESSFUL X509_V_ERR_INVALID_CALL
9686 NID_X500 OCSP_RESPONSE_STATUS_TRYLATER X509_V_ERR_INVALID_EXTENSION
9687 NID_X509 OCSP_RESPONSE_STATUS_UNAUTHORIZED X509_V_ERR_INVALID_NON_CA
9688 NID_ad_OCSP OPENSSL_BUILT_ON X509_V_ERR_INVALID_POLICY_EXTENSION
9689 NID_ad_ca_issuers OPENSSL_CFLAGS X509_V_ERR_INVALID_PURPOSE
9690 NID_algorithm OPENSSL_DIR X509_V_ERR_IP_ADDRESS_MISMATCH
9691 NID_authority_key_identifier OPENSSL_ENGINES_DIR X509_V_ERR_KEYUSAGE_NO_CERTSIGN
9692 NID_basic_constraints OPENSSL_PLATFORM X509_V_ERR_KEYUSAGE_NO_CRL_SIGN
9693 NID_bf_cbc OPENSSL_VERSION X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE
9694 NID_bf_cfb64 OPENSSL_VERSION_NUMBER X509_V_ERR_NO_EXPLICIT_POLICY
9695 NID_bf_ecb OP_ALL X509_V_ERR_NO_VALID_SCTS
9696 NID_bf_ofb64 OP_ALLOW_NO_DHE_KEX X509_V_ERR_OCSP_CERT_UNKNOWN
9697 NID_cast5_cbc OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION X509_V_ERR_OCSP_VERIFY_FAILED
9698 NID_cast5_cfb64 OP_CIPHER_SERVER_PREFERENCE X509_V_ERR_OCSP_VERIFY_NEEDED
9699 NID_cast5_ecb OP_CISCO_ANYCONNECT X509_V_ERR_OUT_OF_MEM
9700 NID_cast5_ofb64 OP_COOKIE_EXCHANGE X509_V_ERR_PATH_LENGTH_EXCEEDED
9701 NID_certBag OP_CRYPTOPRO_TLSEXT_BUG X509_V_ERR_PATH_LOOP
9702 NID_certificate_policies OP_DONT_INSERT_EMPTY_FRAGMENTS X509_V_ERR_PERMITTED_VIOLATION
9703 NID_client_auth OP_ENABLE_MIDDLEBOX_COMPAT X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED
9704 NID_code_sign OP_EPHEMERAL_RSA X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED
9705 NID_commonName OP_LEGACY_SERVER_CONNECT X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION
9706 NID_countryName OP_MICROSOFT_BIG_SSLV3_BUFFER X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN
9707 NID_crlBag OP_MICROSOFT_SESS_ID_BUG X509_V_ERR_STORE_LOOKUP
9708 NID_crl_distribution_points OP_MSIE_SSLV2_RSA_PADDING X509_V_ERR_SUBJECT_ISSUER_MISMATCH
9709 NID_crl_number OP_NETSCAPE_CA_DN_BUG X509_V_ERR_SUBTREE_MINMAX
9710 NID_crl_reason OP_NETSCAPE_CHALLENGE_BUG X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256
9711 NID_delta_crl OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG X509_V_ERR_SUITE_B_INVALID_ALGORITHM
9712 NID_des_cbc OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG X509_V_ERR_SUITE_B_INVALID_CURVE
9713 NID_des_cfb64 OP_NON_EXPORT_FIRST X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM
9714 NID_des_ecb OP_NO_ANTI_REPLAY X509_V_ERR_SUITE_B_INVALID_VERSION
9715 NID_des_ede OP_NO_CLIENT_RENEGOTIATION X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED
9716 NID_des_ede3 OP_NO_COMPRESSION X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY
9717 NID_des_ede3_cbc OP_NO_ENCRYPT_THEN_MAC X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE
9718 NID_des_ede3_cfb64 OP_NO_QUERY_MTU X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE
9719 NID_des_ede3_ofb64 OP_NO_RENEGOTIATION X509_V_ERR_UNABLE_TO_GET_CRL
9720 NID_des_ede_cbc OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER
9721 NID_des_ede_cfb64 OP_NO_SSL_MASK X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT
9722 NID_des_ede_ofb64 OP_NO_SSLv2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
9723 NID_des_ofb64 OP_NO_SSLv3 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE
9724 NID_description OP_NO_TICKET X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION
9725 NID_desx_cbc OP_NO_TLSv1 X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION
9726 NID_dhKeyAgreement OP_NO_TLSv1_1 X509_V_ERR_UNNESTED_RESOURCE
9727 NID_dnQualifier OP_NO_TLSv1_2 X509_V_ERR_UNSPECIFIED
9728 NID_dsa OP_NO_TLSv1_3 X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX
9729 NID_dsaWithSHA OP_PKCS1_CHECK_1 X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE
9730 NID_dsaWithSHA1 OP_PKCS1_CHECK_2 X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE
9731 NID_dsaWithSHA1_2 OP_PRIORITIZE_CHACHA X509_V_ERR_UNSUPPORTED_NAME_SYNTAX
9732 NID_dsa_2 OP_SAFARI_ECDHE_ECDSA_BUG X509_V_FLAG_ALLOW_PROXY_CERTS
9733 NID_email_protect OP_SINGLE_DH_USE X509_V_FLAG_CB_ISSUER_CHECK
9734 NID_ext_key_usage OP_SINGLE_ECDH_USE X509_V_FLAG_CHECK_SS_SIGNATURE
9735 NID_ext_req OP_SSLEAY_080_CLIENT_DH_BUG X509_V_FLAG_CRL_CHECK
9736 NID_friendlyName OP_SSLREF2_REUSE_CERT_TYPE_BUG X509_V_FLAG_CRL_CHECK_ALL
9737 NID_givenName OP_TLSEXT_PADDING X509_V_FLAG_EXPLICIT_POLICY
9738 NID_hmacWithSHA1 OP_TLS_BLOCK_PADDING_BUG X509_V_FLAG_EXTENDED_CRL_SUPPORT
9739 NID_id_ad OP_TLS_D5_BUG X509_V_FLAG_IGNORE_CRITICAL
9740 NID_id_ce OP_TLS_ROLLBACK_BUG X509_V_FLAG_INHIBIT_ANY
9741 NID_id_kp READING X509_V_FLAG_INHIBIT_MAP
9742 NID_id_pbkdf2 RECEIVED_SHUTDOWN X509_V_FLAG_NOTIFY_POLICY
9743 NID_id_pe RSA_3 X509_V_FLAG_NO_ALT_CHAINS
9744 NID_id_pkix RSA_F4 X509_V_FLAG_NO_CHECK_TIME
9745 NID_id_qt_cps R_BAD_AUTHENTICATION_TYPE X509_V_FLAG_PARTIAL_CHAIN
9746 NID_id_qt_unotice R_BAD_CHECKSUM X509_V_FLAG_POLICY_CHECK
9747 NID_idea_cbc R_BAD_MAC_DECODE X509_V_FLAG_POLICY_MASK
9748 NID_idea_cfb64 R_BAD_RESPONSE_ARGUMENT X509_V_FLAG_SUITEB_128_LOS
9749 NID_idea_ecb R_BAD_SSL_FILETYPE X509_V_FLAG_SUITEB_128_LOS_ONLY
9750 NID_idea_ofb64 R_BAD_SSL_SESSION_ID_LENGTH X509_V_FLAG_SUITEB_192_LOS
9751 NID_info_access R_BAD_STATE X509_V_FLAG_TRUSTED_FIRST
9752 NID_initials R_BAD_WRITE_RETRY X509_V_FLAG_USE_CHECK_TIME
9753 NID_invalidity_date R_CHALLENGE_IS_DIFFERENT X509_V_FLAG_USE_DELTAS
9754 NID_issuer_alt_name R_CIPHER_TABLE_SRC_ERROR X509_V_FLAG_X509_STRICT
9755 NID_keyBag R_INVALID_CHALLENGE_LENGTH X509_V_OK
9756 NID_key_usage R_NO_CERTIFICATE_SET XN_FLAG_COMPAT
9757 NID_localKeyID R_NO_CERTIFICATE_SPECIFIED XN_FLAG_DN_REV
9758 NID_localityName R_NO_CIPHER_LIST XN_FLAG_DUMP_UNKNOWN_FIELDS
9759 NID_md2 R_NO_CIPHER_MATCH XN_FLAG_FN_ALIGN
9760 NID_md2WithRSAEncryption R_NO_PRIVATEKEY XN_FLAG_FN_LN
9761 NID_md5 R_NO_PUBLICKEY XN_FLAG_FN_MASK
9762 NID_md5WithRSA R_NULL_SSL_CTX XN_FLAG_FN_NONE
9763 NID_md5WithRSAEncryption R_PEER_DID_NOT_RETURN_A_CERTIFICATE XN_FLAG_FN_OID
9764 NID_md5_sha1 R_PEER_ERROR XN_FLAG_FN_SN
9765 NID_mdc2 R_PEER_ERROR_CERTIFICATE XN_FLAG_MULTILINE
9766 NID_mdc2WithRSA R_PEER_ERROR_NO_CIPHER XN_FLAG_ONELINE
9767 NID_ms_code_com R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE XN_FLAG_RFC2253
9768 NID_ms_code_ind R_PUBLIC_KEY_ENCRYPT_ERROR XN_FLAG_SEP_COMMA_PLUS
9769 NID_ms_ctl_sign R_PUBLIC_KEY_IS_NOT_RSA XN_FLAG_SEP_CPLUS_SPC
9770 NID_ms_efs R_READ_WRONG_PACKET_TYPE XN_FLAG_SEP_MASK
9771 NID_ms_ext_req R_SHORT_READ XN_FLAG_SEP_MULTILINE
9772 NID_ms_sgc R_SSL_SESSION_ID_IS_DIFFERENT XN_FLAG_SEP_SPLUS_SPC
9773 NID_name R_UNABLE_TO_EXTRACT_PUBLIC_KEY XN_FLAG_SPC_EQ
9774 INTERNAL ONLY functions (do not use these)
9776 The following functions are not intended for use from outside of
9777 Net::SSLeay module. They might be removed, renamed or changed without
9778 prior notice in future version.
9779 Simply DO NOT USE THEM!
9781 · hello
9783 · blength
9785 · constant
9787
9789 One very good example to look at is the implementation of "sslcat()" in
9790 the "SSLeay.pm" file.
9791 The following is a simple SSLeay client (with too little error checking
9793 :-(
9794 #!/usr/bin/perl
9796 use Socket;
9797 use Net::SSLeay qw(die_now die_if_ssl_error) ;
9798 Net::SSLeay::load_error_strings();
9799 Net::SSLeay::SSLeay_add_ssl_algorithms();
9800 Net::SSLeay::randomize();
9801 ($dest_serv, $port, $msg) = @ARGV; # Read command line
9803 $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
9804 $dest_ip = gethostbyname ($dest_serv);
9805 $dest_serv_params = sockaddr_in($port, $dest_ip);
9806 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
9808 connect (S, $dest_serv_params) or die "connect: $!";
9809 select (S); $| = 1; select (STDOUT); # Eliminate STDIO buffering
9810 # The network connection is now open, lets fire up SSL
9812 $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
9814 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9815 or die_if_ssl_error("ssl ctx set options");
9816 $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
9817 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
9818 $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
9819 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9820 # Exchange data
9822 $res = Net::SSLeay::write($ssl, $msg); # Perl knows how long $msg is
9824 die_if_ssl_error("ssl write");
9825 CORE::shutdown S, 1; # Half close --> No more output, sends EOF to server
9826 $got = Net::SSLeay::read($ssl); # Perl returns undef on failure
9827 die_if_ssl_error("ssl read");
9828 print $got;
9829 Net::SSLeay::free ($ssl); # Tear down connection
9831 Net::SSLeay::CTX_free ($ctx);
9832 close S;
9833 The following is a simple SSLeay echo server (non forking):
9835 #!/usr/bin/perl -w
9837 use Socket;
9838 use Net::SSLeay qw(die_now die_if_ssl_error);
9839 Net::SSLeay::load_error_strings();
9840 Net::SSLeay::SSLeay_add_ssl_algorithms();
9841 Net::SSLeay::randomize();
9842 $our_ip = "\0\0\0\0"; # Bind to all interfaces
9844 $port = 1235;
9845 $sockaddr_template = 'S n a4 x8';
9846 $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
9847 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
9849 bind (S, $our_serv_params) or die "bind: $!";
9850 listen (S, 5) or die "listen: $!";
9851 $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
9852 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9853 or die_if_ssl_error("ssl ctx set options");
9854 # Following will ask password unless private key is not encrypted
9856 Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
9857 &Net::SSLeay::FILETYPE_PEM);
9858 die_if_ssl_error("private key");
9859 Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
9860 &Net::SSLeay::FILETYPE_PEM);
9861 die_if_ssl_error("certificate");
9862 while (1) {
9864 print "Accepting connections...\n";
9865 ($addr = accept (NS, S)) or die "accept: $!";
9866 select (NS); $| = 1; select (STDOUT); # Piping hot!
9867 ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
9869 @inetaddr = unpack('C4',$client_ip);
9870 print "$af connection from " .
9871 join ('.', @inetaddr) . ":$client_port\n";
9872 # We now have a network connection, lets fire up SSLeay...
9874 $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
9876 Net::SSLeay::set_fd($ssl, fileno(NS));
9877 $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
9879 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9880 # Connected. Exchange some data.
9882 $got = Net::SSLeay::read($ssl); # Returns undef on fail
9884 die_if_ssl_error("ssl read");
9885 print "Got `$got' (" . length ($got) . " chars)\n";
9886 Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
9888 die_if_ssl_error("ssl write");
9889 Net::SSLeay::free ($ssl); # Tear down connection
9891 close NS;
9892 }
9893 Yet another echo server. This one runs from "/etc/inetd.conf" so it
9895 avoids all the socket code overhead. Only caveat is opening an rsa key
9896 file - it had better be without any encryption or else it will not know
9897 where to ask for the password. Note how "STDIN" and "STDOUT" are wired
9898 to SSL.
9899 #!/usr/bin/perl
9901 # /etc/inetd.conf
9902 # ssltst stream tcp nowait root /path/to/server.pl server.pl
9903 # /etc/services
9904 # ssltst 1234/tcp
9905 use Net::SSLeay qw(die_now die_if_ssl_error);
9907 Net::SSLeay::load_error_strings();
9908 Net::SSLeay::SSLeay_add_ssl_algorithms();
9909 Net::SSLeay::randomize();
9910 chdir '/key/dir' or die "chdir: $!";
9912 $| = 1; # Piping hot!
9913 open LOG, ">>/dev/console" or die "Can't open log file $!";
9914 select LOG; print "server.pl started\n";
9915 $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
9917 $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
9918 Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
9919 and die_if_ssl_error("ssl set options");
9920 # We get already open network connection from inetd, now we just
9922 # need to attach SSLeay to STDIN and STDOUT
9923 Net::SSLeay::set_rfd($ssl, fileno(STDIN));
9924 Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
9925 Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
9927 Net::SSLeay::FILETYPE_PEM);
9928 die_if_ssl_error("private key");
9929 Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
9930 Net::SSLeay::FILETYPE_PEM);
9931 die_if_ssl_error("certificate");
9932 Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
9934 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9935 $got = Net::SSLeay::read($ssl);
9937 die_if_ssl_error("ssl read");
9938 print "Got `$got' (" . length ($got) . " chars)\n";
9939 Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
9941 die_if_ssl_error("ssl write");
9942 Net::SSLeay::free ($ssl); # Tear down the connection
9944 Net::SSLeay::CTX_free ($ctx);
9945 close LOG;
9946 There are also a number of example/test programs in the examples
9948 directory:
9949 sslecho.pl - A simple server, not unlike the one above
9951 minicli.pl - Implements a client using low level SSLeay routines
9952 sslcat.pl - Demonstrates using high level sslcat utility function
9953 get_page.pl - Is a utility for getting html pages from secure servers
9954 callback.pl - Demonstrates certificate verification and callback usage
9955 stdio_bulk.pl - Does SSL over Unix pipes
9956 ssl-inetd-serv.pl - SSL server that can be invoked from inetd.conf
9957 httpd-proxy-snif.pl - Utility that allows you to see how a browser
9958 sends https request to given server and what reply
9959 it gets back (very educative :-)
9960 makecert.pl - Creates a self signed cert (does not use this module)
9961
9963 See README and README.* in the distribution directory for installation
9964 guidance on a variety of platforms.
9965
9967 "Net::SSLeay::read()" uses an internal buffer of 32KB, thus no single
9968 read will return more. In practice one read returns much less, usually
9969 as much as fits in one network packet. To work around this, you should
9970 use a loop like this:
9971 $reply = '';
9973 while ($got = Net::SSLeay::read($ssl)) {
9974 last if print_errs('SSL_read');
9975 $reply .= $got;
9976 }
9977 Although there is no built-in limit in "Net::SSLeay::write()", the
9979 network packet size limitation applies here as well, thus use:
9980 $written = 0;
9982 while ($written < length($message)) {
9984 $written += Net::SSLeay::write($ssl, substr($message, $written));
9985 last if print_errs('SSL_write');
9986 }
9987 Or alternatively you can just use the following convenience functions:
9989 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
9991 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
9992
9994 An OpenSSL bug CVE-2015-0290 "OpenSSL Multiblock Corrupted Pointer
9995 Issue" can cause POST requests of over 90kB to fail or crash. This bug
9996 is reported to be fixed in OpenSSL 1.0.2a.
9997 Autoloader emits a
9999 Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
10001 warning if die_if_ssl_error is made autoloadable. If you figure out
10003 why, drop me a line.
10004 Callback set using "SSL_set_verify()" does not appear to work. This may
10006 well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
10007 using "SSL_CTX_set_verify()" instead and do not be surprised if even
10008 this stops working in future versions.
10009 Callback and certificate verification stuff is generally too little
10011 tested.
10012 Random numbers are not initialized randomly enough, especially if you
10014 do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
10015 platforms - but it's been suggested that cryptorand daemon from the
10016 SUNski package solves this). In this case you should investigate third
10017 party software that can emulate these devices, e.g. by way of a named
10018 pipe to some program.
10019 Another gotcha with random number initialization is randomness
10021 depletion. This phenomenon, which has been extensively discussed in
10022 OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
10023 to block if you use "/dev/random" or to operate insecurely if you use
10024 "/dev/urandom". What happens is that when too much randomness is drawn
10025 from the operating system's randomness pool then randomness can
10026 temporarily be unavailable. "/dev/random" solves this problem by
10027 waiting until enough randomness can be gathered - and this can take a
10028 long time since blocking reduces activity in the machine and less
10029 activity provides less random events: a vicious circle. "/dev/urandom"
10030 solves this dilemma more pragmatically by simply returning predictable
10031 "random" numbers. Some" /dev/urandom" emulation software however
10032 actually seems to implement "/dev/random" semantics. Caveat emptor.
10033 I've been pointed to two such daemons by Mik Firestone
10035 <mik@@speed.stdio._com> who has used them on Solaris 8:
10036 1. Entropy Gathering Daemon (EGD) at
10038 <http://www.lothar.com/tech/crypto/>
10039 2. Pseudo-random number generating daemon (PRNGD) at
10041 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10042 If you are using the low level API functions to communicate with other
10044 SSL implementations, you would do well to call
10045 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10047 or die_if_ssl_error("ssl ctx set options");
10048 to cope with some well know bugs in some other SSL implementations. The
10050 high level API functions always set all known compatibility options.
10051 Sometimes "sslcat()" (and the high level HTTPS functions that build on
10053 it) is too fast in signaling the EOF to legacy HTTPS servers. This
10054 causes the server to return empty page. To work around this problem you
10055 can set the global variable
10056 $Net::SSLeay::slowly = 1; # Add sleep so broken servers can keep up
10058 HTTP/1.1 is not supported. Specifically this module does not know to
10060 issue or serve multiple http requests per connection. This is a serious
10061 shortcoming, but using the SSL session cache on your server helps to
10062 alleviate the CPU load somewhat.
10063 As of version 1.09 many newer OpenSSL auxiliary functions were added
10065 (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
10066 Unfortunately I have not had any opportunity to test these. Some of
10067 them are trivial enough that I believe they "just work", but others
10068 have rather complex interfaces with function pointers and all. In these
10069 cases you should proceed wit great caution.
10070 This module defaults to using OpenSSL automatic protocol negotiation
10072 code for automatically detecting the version of the SSL/TLS protocol
10073 that the other end talks. With most web servers this works just fine,
10074 but once in a while I get complaints from people that the module does
10075 not work with some web servers. Usually this can be solved by
10076 explicitly setting the protocol version, e.g.
10077 $Net::SSLeay::ssl_version = 2; # Insist on SSLv2
10079 $Net::SSLeay::ssl_version = 3; # Insist on SSLv3
10080 $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
10081 $Net::SSLeay::ssl_version = 11; # Insist on TLSv1.1
10082 $Net::SSLeay::ssl_version = 12; # Insist on TLSv1.2
10083 $Net::SSLeay::ssl_version = 13; # Insist on TLSv1.3
10084 Although the autonegotiation is nice to have, the SSL standards do not
10086 formally specify any such mechanism. Most of the world has accepted the
10087 SSLeay/OpenSSL way of doing it as the de facto standard. But for the
10088 few that think differently, you have to explicitly speak the correct
10089 version. This is not really a bug, but rather a deficiency in the
10090 standards. If a site refuses to respond or sends back some nonsensical
10091 error codes (at the SSL handshake level), try this option before
10092 mailing me.
10093 On some systems, OpenSSL may be compiled without support for SSLv2. If
10095 this is the case, Net::SSLeay will warn if ssl_version has been set to
10096 2.
10097 The high level API returns the certificate of the peer, thus allowing
10099 one to check what certificate was supplied. However, you will only be
10100 able to check the certificate after the fact, i.e. you already sent
10101 your form data by the time you find out that you did not trust them,
10102 oops.
10103 So, while being able to know the certificate after the fact is surely
10105 useful, the security minded would still choose to do the connection and
10106 certificate verification first and only then exchange data with the
10107 site. Currently none of the high level API functions do this, thus you
10108 would have to program it using the low level API. A good place to start
10109 is to see how the "Net::SSLeay::http_cat()" function is implemented.
10110 The high level API functions use a global file handle "SSLCAT_S"
10112 internally. This really should not be a problem because there is no way
10113 to interleave the high level API functions, unless you use threads (but
10114 threads are not very well supported in perl anyway). However, you may
10115 run into problems if you call undocumented internal functions in an
10116 interleaved fashion. The best solution is to "require Net::SSLeay" in
10117 one thread after all the threads have been created.
10118
10120 Random number generator not seeded!!!
10121 (W) This warning indicates that "randomize()" was not able to read
10122 "/dev/random" or "/dev/urandom", possibly because your system does
10123 not have them or they are differently named. You can still use SSL,
10124 but the encryption will not be as strong.
10125 open_tcp_connection: destination host not found:`server' (port 123)
10127 ($!)
10128 Name lookup for host named "server" failed.
10129 open_tcp_connection: failed `server', 123 ($!)
10131 The name was resolved, but establishing the TCP connection failed.
10132 msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
10134 proto
10135 SSLeay error string. The first number (123) is the PID, the second
10136 number (1) indicates the position of the error message in SSLeay
10137 error stack. You often see a pile of these messages as errors
10138 cascade.
10139 msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
10141 The same as above, but you didn't call load_error_strings() so
10142 SSLeay couldn't verbosely explain the error. You can still find out
10143 what it means with this command:
10144 /usr/local/ssl/bin/ssleay errstr 02001002
10146 Password is being asked for private key
10148 This is normal behaviour if your private key is encrypted. Either
10149 you have to supply the password or you have to use an unencrypted
10150 private key. Scan OpenSSL.org for the FAQ that explains how to do
10151 this (or just study examples/makecert.pl which is used during "make
10152 test" to do just that).
10153
10155 You can mitigate some of the security vulnerabilities that might be
10156 present in your SSL/TLS application:
10157 BEAST Attack
10159 http://blogs.cisco.com/security/beat-the-beast-with-tls/
10160 https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
10161 http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
10162 The BEAST attack relies on a weakness in the way CBC mode is used in
10164 SSL/TLS. In OpenSSL versions 0.9.6d and later, the protocol-level
10165 mitigation is enabled by default, thus making it not vulnerable to the
10166 BEAST attack.
10167 Solutions:
10169 · Compile with OpenSSL versions 0.9.6d or later, which enables
10171 SSL_OP_ALL by default
10172 · Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
10174 enabled by default)
10175 · Don't support SSLv2, SSLv3
10177 · Actively control the ciphers your server supports with
10179 set_cipher_list:
10180 Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
10182 Session Resumption
10184 http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
10185 The SSL Labs vulnerability test on your SSL server might report in red:
10187 Session resumption No (IDs assigned but not accepted)
10189 This report is not really bug or a vulnerability, since the server will
10191 not accept session resumption requests. However, you can prevent this
10192 noise in the report by disabling the session cache altogether:
10193 Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx,
10194 Net::SSLeay::SESS_CACHE_OFF()); Use 0 if you don't have SESS_CACHE_OFF
10195 constant.
10196 Secure Renegotiation and DoS Attack
10198 https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
10199 This is not a "security flaw," it is more of a DoS vulnerability.
10201 Solutions:
10203 · Do not support SSLv2
10205 · Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
10207 · Compile with OpenSSL 0.9.8m or later
10209
10211 If you encounter a problem with this module that you believe is a bug,
10212 please report it in one of the following ways:
10213 · create a new issue <https://github.com/radiator-software/p5-net-
10215 ssleay/issues/new> under the Net-SSLeay GitHub project at
10216 <https://github.com/radiator-software/p5-net-ssleay>;
10217 · open a ticket <https://rt.cpan.org/Ticket/Create.html?Queue=Net-
10219 SSLeay> using the CPAN RT bug tracker's web interface at
10220 <https://rt.cpan.org/Dist/Display.html?Queue=Net-SSLeay>;
10221 · send an email to the CPAN RT bug tracker at
10223 bug-Net-SSLeay@rt.cpan.org <mailto:bug-Net-SSLeay@rt.cpan.org>.
10224 Please make sure your bug report includes the following information:
10226 · the code you are trying to run;
10228 · your operating system name and version;
10230 · the output of "perl -V";
10232 · the version of OpenSSL or LibreSSL you are using.
10234
10236 Originally written by Sampo Kellomäki.
10237 Maintained by Florian Ragwitz between November 2005 and January 2010.
10239 Maintained by Mike McCauley between November 2005 and June 2018.
10241 Maintained by Chris Novakovic, Tuure Vartiainen and Heikki Vatiainen
10243 since June 2018.
10244
10246 Copyright (c) 1996-2003 Sampo Kellomäki <sampo@iki.fi>
10247 Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
10249 Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
10251 Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
10253 Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
10255 Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
10257 All rights reserved.
10259
10261 This module is released under the terms of the Artistic License 2.0.
10262 For details, see the "LICENSE" file distributed with Net-SSLeay's
10263 source code.
10264
10266 Net::SSLeay::Handle - File handle interface
10267 ./examples - Example servers and a clients
10268 <http://www.openssl.org/> - OpenSSL source, documentation, etc
10269 openssl-users-request@openssl.org - General OpenSSL mailing list
10270 <http://www.ietf.org/rfc/rfc2246.txt> - TLS 1.0 specification
10271 <http://www.w3c.org> - HTTP specifications
10272 <http://www.ietf.org/rfc/rfc2617.txt> - How to send password
10273 <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
10274 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10275 - pseudo-random number generating daemon (PRNGD)
10276 perl(1)
10277 perlref(1)
10278 perllol(1)
10279 perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
10280perl v5.30.1 2020-02-05 Net::SSLeay(3)