1Net::SSLeay(3) User Contributed Perl Documentation Net::SSLeay(3)
2
6 Net::SSLeay - Perl bindings for OpenSSL and LibreSSL
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 This module provides Perl bindings for libssl (an SSL/TLS API) and
41 libcrypto (a cryptography API).
42
44 Net::SSLeay supports the following libssl implementations:
45 • Any stable release of OpenSSL <https://www.openssl.org> in the
47 0.9.8 - 3.0 branches, except for OpenSSL 0.9.8 - 0.9.8b.
48 • Any stable release of LibreSSL <https://www.libressl.org> in the
50 2.0 - 3.4 series, except for LibreSSL 3.2.2 and 3.2.3.
51 Net::SSLeay may not function as expected with releases other than the
53 ones listed above due to libssl API incompatibilities, or, in the case
54 of LibreSSL, because of deviations from the libssl API.
55 Net::SSLeay is only as secure as the underlying libssl implementation
57 you use. Although Net::SSLeay maintains compatibility with old
58 versions of OpenSSL and LibreSSL, it is strongly recommended that you
59 use a version of OpenSSL or LibreSSL that is supported by the
60 OpenSSL/LibreSSL developers and/or your operating system vendor. Many
61 unsupported versions of OpenSSL and LibreSSL are known to contain
62 severe security vulnerabilities. Refer to the OpenSSL Release Strategy
63 <https://www.openssl.org/policies/releasestrat.html> and LibreSSL
64 Support Schedule <https://www.libressl.org/releases.html> for
65 information on which versions are currently supported.
66 The libssl API has changed significantly since OpenSSL 0.9.8: hundreds
68 of functions have been added, deprecated or removed in the intervening
69 versions. Although this documentation lists all of the functions and
70 constants that Net::SSLeay may expose, they will not be available for
71 use if they are missing from the underlying libssl implementation.
72 Refer to the compatibility notes in this documentation, as well as the
73 OpenSSL/LibreSSL manual pages, for information on which
74 OpenSSL/LibreSSL versions support each function or constant. At run-
75 time, you can check whether a function or constant is exposed before
76 calling it using the following convention:
77 if ( defined &Net::SSLeay::libssl_function ) {
79 # libssl_function() (or SSL_libssl_function()) is available
80 Net::SSLeay::libssl_function(...);
81 }
82
84 Net::SSLeay module basically comprise of:
85 • High level functions for accessing web servers (by using
87 HTTP/HTTPS)
88 • Low level API (mostly mapped 1:1 to openssl's C functions)
90 • Convenience functions (related to low level API but with more perl
92 friendly interface)
93 There is also a related module called Net::SSLeay::Handle included in
95 this distribution that you might want to use instead. It has its own
96 pod documentation.
97 High level functions for accessing web servers
99 This module offers some high level convenience functions for accessing
100 web pages on SSL servers (for symmetry, the same API is offered for
101 accessing http servers, too), an sslcat() function for writing your own
102 clients, and finally access to the SSL api of the SSLeay/OpenSSL
103 package so you can write servers or clients for more complicated
104 applications.
105 For high level functions it is most convenient to import them into your
107 main namespace as indicated in the synopsis.
108 Basic set of functions
110 • get_https
112 • post_https
114 • put_https
116 • head_https
118 • do_https
120 • sslcat
122 • https_cat
124 • make_form
126 • make_headers
128 Case 1 (in SYNOPSIS) demonstrates the typical invocation of get_https()
130 to fetch an HTML page from secure server. The first argument provides
131 the hostname or IP in dotted decimal notation of the remote server to
132 contact. The second argument is the TCP port at the remote end (your
133 own port is picked arbitrarily from high numbered ports as usual for
134 TCP). The third argument is the URL of the page without the host name
135 part. If in doubt consult the HTTP specifications at
136 <http://www.w3c.org>.
137 Case 2 (in SYNOPSIS) demonstrates full fledged use of get_https(). As
139 can be seen, get_https() parses the response and response headers and
140 returns them as a list, which can be captured in a hash for later
141 reference. Also a fourth argument to get_https() is used to insert some
142 additional headers in the request. make_headers() is a function that
143 will convert a list or hash to such headers. By default get_https()
144 supplies "Host" (to make virtual hosting easy) and "Accept" (reportedly
145 needed by IIS) headers.
146 Case 2b (in SYNOPSIS) demonstrates how to get a password protected
148 page. Refer to the HTTP protocol specifications for further details
149 (e.g. RFC-2617).
150 Case 3 (in SYNOPSIS) invokes post_https() to submit a HTML/CGI form to
152 a secure server. The first four arguments are equal to get_https()
153 (note that the empty string ('') is passed as header argument). The
154 fifth argument is the contents of the form formatted according to CGI
155 specification. Do not post UTF-8 data as content: use utf8::downgrade
156 first. In this case the helper function make_https() is used to do the
157 formatting, but you could pass any string. post_https() automatically
158 adds "Content-Type" and "Content-Length" headers to the request.
159 Case 4 (in SYNOPSIS) shows the fundamental sslcat() function (inspired
161 in spirit by the "netcat" utility :-). It's your swiss army knife that
162 allows you to easily contact servers, send some data, and then get the
163 response. You are responsible for formatting the data and parsing the
164 response - sslcat() is just a transport.
165 Case 5 (in SYNOPSIS) is a full invocation of sslcat() which allows the
167 return of errors as well as the server (peer) certificate.
168 The $trace global variable can be used to control the verbosity of the
170 high level functions. Level 0 guarantees silence, level 1 (the default)
171 only emits error messages.
172 Alternate versions of high-level API
174 • get_https3
176 • post_https3
178 • put_https3
180 • get_https4
182 • post_https4
184 • put_https4
186 The above mentioned functions actually return the response headers as a
188 list, which only gets converted to hash upon assignment (this
189 assignment looses information if the same header occurs twice, as may
190 be the case with cookies). There are also other variants of the
191 functions that return unprocessed headers and that return a reference
192 to a hash.
193 ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
195 for ($i = 0; $i < $#headers; $i+=2) {
196 print "$headers[$i] = " . $headers[$i+1] . "\n";
197 }
198 ($page, $response, $headers, $server_cert)
200 = get_https3('www.bacus.pt', 443, '/');
201 print "$headers\n";
202 ($page, $response, $headers_ref)
204 = get_https4('www.bacus.pt', 443, '/');
205 for $k (sort keys %{$headers_ref}) {
206 for $v (@{$$headers_ref{$k}}) {
207 print "$k = $v\n";
208 }
209 }
210 All of the above code fragments accomplish the same thing: display all
212 values of all headers. The API functions ending in "3" return the
213 headers simply as a scalar string and it is up to the application to
214 split them up. The functions ending in "4" return a reference to a hash
215 of arrays (see perlref and perllol if you are not familiar with complex
216 perl data structures). To access a single value of such a header hash
217 you would do something like
218 print $$headers_ref{COOKIE}[0];
220 Variants 3 and 4 also allow you to discover the server certificate in
222 case you would like to store or display it, e.g.
223 ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
225 if (!defined($server_cert) || ($server_cert == 0)) {
226 warn "Subject Name: undefined, Issuer Name: undefined";
227 } else {
228 warn 'Subject Name: '
229 . Net::SSLeay::X509_NAME_oneline(
230 Net::SSLeay::X509_get_subject_name($server_cert))
231 . 'Issuer Name: '
232 . Net::SSLeay::X509_NAME_oneline(
233 Net::SSLeay::X509_get_issuer_name($server_cert));
234 }
235 Beware that this method only allows after the fact verification of the
237 certificate: by the time get_https3() has returned the https request
238 has already been sent to the server, whether you decide to trust it or
239 not. To do the verification correctly you must either employ the
240 OpenSSL certificate verification framework or use the lower level API
241 to first connect and verify the certificate and only then send the http
242 data. See the implementation of ds_https3() for guidance on how to do
243 this.
244 Using client certificates
246 Secure web communications are encrypted using symmetric crypto keys
248 exchanged using encryption based on the certificate of the server.
249 Therefore in all SSL connections the server must have a certificate.
250 This serves both to authenticate the server to the clients and to
251 perform the key exchange.
252 Sometimes it is necessary to authenticate the client as well. Two
254 options are available: HTTP basic authentication and a client side
255 certificate. The basic authentication over HTTPS is actually quite safe
256 because HTTPS guarantees that the password will not travel in the
257 clear. Never-the-less, problems like easily guessable passwords remain.
258 The client certificate method involves authentication of the client at
259 the SSL level using a certificate. For this to work, both the client
260 and the server have certificates (which typically are different) and
261 private keys.
262 The API functions outlined above accept additional arguments that allow
264 one to supply the client side certificate and key files. The format of
265 these files is the same as used for server certificates and the caveat
266 about encrypting private keys applies.
267 ($page, $result, %headers) = # 2c
269 = get_https('www.bacus.pt', 443, '/protected.html',
270 make_headers(Authorization =>
271 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
272 '', $mime_type6, $path_to_crt7, $path_to_key8);
273 ($page, $response, %reply_headers)
275 = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
276 make_headers('Authorization' =>
277 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
278 make_form(OK => '1', name => 'Sampo'),
279 $mime_type6, $path_to_crt7, $path_to_key8);
280 Case 2c (in SYNOPSIS) demonstrates getting a password protected page
282 that also requires a client certificate, i.e. it is possible to use
283 both authentication methods simultaneously.
284 Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
286 requires both password authentication and a client certificate, just
287 like in case 2c.
288 Note: The client will not send a certificate unless the server requests
290 one. This is typically achieved by setting the verify mode to
291 "VERIFY_PEER" on the server:
292 Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
294 See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
296 description.
297 Working through a web proxy
299 • set_proxy
301 "Net::SSLeay" can use a web proxy to make its connections. You need to
303 first set the proxy host and port using set_proxy() and then just use
304 the normal API functions, e.g:
305 Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
307 ($page) = get_https('www.bacus.pt', 443, '/');
308 If your proxy requires authentication, you can supply a username and
310 password as well
311 Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
313 ($page, $result, %headers) =
314 = get_https('www.bacus.pt', 443, '/protected.html',
315 make_headers(Authorization =>
316 'Basic ' . MIME::Base64::encode("susie:pass",''))
317 );
318 This example demonstrates the case where we authenticate to the proxy
320 as "joe" and to the final web server as "susie". Proxy authentication
321 requires the "MIME::Base64" module to work.
322 HTTP (without S) API
324 • get_http
326 • post_http
328 • tcpcat
330 • get_httpx
332 • post_httpx
334 • tcpxcat
336 Over the years it has become clear that it would be convenient to use
338 the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
339 (see "LWP" for the heavy-weight object-oriented approach). In fact it
340 would be nice to be able to flip https on and off on the fly. Thus
341 regular HTTP support was evolved.
342 use Net::SSLeay qw(get_http post_http tcpcat
344 get_httpx post_httpx tcpxcat
345 make_headers make_form);
346 ($page, $result, %headers)
348 = get_http('www.bacus.pt', 443, '/protected.html',
349 make_headers(Authorization =>
350 'Basic ' . MIME::Base64::encode("$user:$pass",''))
351 );
352 ($page, $response, %reply_headers)
354 = post_http('www.bacus.pt', 443, '/foo.cgi', '',
355 make_form(OK => '1',
356 name => 'Sampo'
357 ));
358 ($reply, $err) = tcpcat($host, $port, $request);
360 ($page, $result, %headers)
362 = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
363 make_headers(Authorization =>
364 'Basic ' . MIME::Base64::encode("$user:$pass",''))
365 );
366 ($page, $response, %reply_headers)
368 = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
369 make_form(OK => '1', name => 'Sampo' ));
370 ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
372 As can be seen, the "x" family of APIs takes as the first argument a
374 flag which indicates whether SSL is used or not.
375 Certificate verification and Certificate Revocation Lists (CRLs)
377 OpenSSL supports the ability to verify peer certificates. It can also
378 optionally check the peer certificate against a Certificate Revocation
379 List (CRL) from the certificates issuer. A CRL is a file, created by
380 the certificate issuer that lists all the certificates that it
381 previously signed, but which it now revokes. CRLs are in PEM format.
382 You can enable "Net::SSLeay CRL" checking like this:
384 &Net::SSLeay::X509_STORE_set_flags
386 (&Net::SSLeay::CTX_get_cert_store($ssl),
387 &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
388 After setting this flag, if OpenSSL checks a peer's certificate, then
390 it will attempt to find a CRL for the issuer. It does this by looking
391 for a specially named file in the search directory specified by
392 CTX_load_verify_locations. CRL files are named with the hash of the
393 issuer's subject name, followed by ".r0", ".r1" etc. For example
394 "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
395 issuer, and then check for a revocation of the peer certificate in all
396 of them. (You can also force it to look in a specific named CRL file.,
397 see below). You can find out the hash of the issuer subject name in a
398 CRL with
399 openssl crl -in crl.pem -hash -noout
401 If the peer certificate does not pass the revocation list, or if no CRL
403 is found, then the handshaking fails with an error.
404 You can also force OpenSSL to look for CRLs in one or more arbitrarily
406 named files.
407 my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
409 my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
410 if ($crl) {
411 Net::SSLeay::X509_STORE_add_crl(
412 Net::SSLeay::CTX_get_cert_store($ssl, $crl)
413 );
414 } else {
415 error reading CRL....
416 }
417 Usually the URLs where you can download the CRLs is contained in the
419 certificate itself and you can extract them with
420 my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
422 But there is no automatic downloading of the CRLs and often these CRLs
424 are too huge to just download them to verify a single certificate.
425 Also, these CRLs are often in DER format which you need to convert to
426 PEM before you can use it:
427 openssl crl -in crl.der -inform der -out crl.pem
429 So as an alternative for faster and timely revocation checks you better
431 use the Online Status Revocation Protocol (OCSP).
432 Certificate verification and Online Status Revocation Protocol (OCSP)
434 While checking for revoked certificates is possible and fast with
435 Certificate Revocation Lists, you need to download the complete and
436 often huge list before you can verify a single certificate.
437 A faster way is to ask the CA to check the revocation of just a single
439 or a few certificates using OCSP. Basically you generate for each
440 certificate an OCSP_CERTID based on the certificate itself and its
441 issuer, put the ids togetether into an OCSP_REQUEST and send the
442 request to the URL given in the certificate.
443 As a result you get back an OCSP_RESPONSE and need to check the status
445 of the response, check that it is valid (e.g. signed by the CA) and
446 finally extract the information about each OCSP_CERTID to find out if
447 the certificate is still valid or got revoked.
448 With Net::SSLeay this can be done like this:
450 # get id(s) for given certs, like from get_peer_certificate
452 # or get_peer_cert_chain. This will croak if
453 # - one tries to make an OCSP_CERTID for a self-signed certificate
454 # - the issuer of the certificate cannot be found in the SSL objects
455 # store, nor in the current certificate chain
456 my $cert = Net::SSLeay::get_peer_certificate($ssl);
457 my $id = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) };
458 die "failed to make OCSP_CERTID: $@" if $@;
459 # create OCSP_REQUEST from id(s)
461 # Multiple can be put into the same request, if the same OCSP responder
462 # is responsible for them.
463 my $req = Net::SSLeay::OCSP_ids2req($id);
464 # determine URI of OCSP responder
466 my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
467 # Send stringified OCSP_REQUEST with POST to $uri.
469 # We can ignore certificate verification for https, because the OCSP
470 # response itself is signed.
471 my $ua = HTTP::Tiny->new(verify_SSL => 0);
472 my $res = $ua->request( 'POST',$uri, {
473 headers => { 'Content-type' => 'application/ocsp-request' },
474 content => Net::SSLeay::i2d_OCSP_REQUEST($req)
475 });
476 my $content = $res && $res->{success} && $res->{content}
477 or die "query failed";
478 # Extract OCSP_RESPONSE.
480 # this will croak if the string is not an OCSP_RESPONSE
481 my $resp = eval { Net::SSLeay::d2i_OCSP_RESPONSE($content) };
482 # Check status of response.
484 my $status = Net::SSLeay::OCSP_response_status($resp);
485 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL())
486 die "OCSP response failed: ".
487 Net::SSLeay::OCSP_response_status_str($status);
488 }
489 # Verify signature of response and if nonce matches request.
491 # This will croak if there is a nonce in the response, but it does not match
492 # the request. It will return false if the signature could not be verified,
493 # in which case details can be retrieved with Net::SSLeay::ERR_get_error.
494 # It will not complain if the response does not contain a nonce, which is
495 # usually the case with pre-signed responses.
496 if ( ! eval { Net::SSLeay::OCSP_response_verify($ssl,$resp,$req) }) {
497 die "OCSP response verification failed";
498 }
499 # Extract information from OCSP_RESPONSE for each of the ids.
501 # If called in scalar context it will return the time (as time_t), when the
503 # next update is due (minimum of all successful responses inside $resp). It
504 # will croak on the following problems:
505 # - response is expired or not yet valid
506 # - no response for given OCSP_CERTID
507 # - certificate status is not good (e.g. revoked or unknown)
508 if ( my $nextupd = eval { Net::SSLeay::OCSP_response_results($resp,$id) }) {
509 warn "certificate is valid, next update in ".
510 ($nextupd-time())." seconds\n";
511 } else {
512 die "certificate is not valid: $@";
513 }
514 # But in array context it will return detailed information about each given
516 # OCSP_CERTID instead croaking on errors:
517 # if no @ids are given it will return information about all single responses
518 # in the OCSP_RESPONSE
519 my @results = Net::SSLeay::OCSP_response_results($resp,@ids);
520 for my $r (@results) {
521 print Dumper($r);
522 # @results are in the same order as the @ids and contain:
523 # $r->[0] - OCSP_CERTID
524 # $r->[1] - undef if no error (certificate good) OR error message as string
525 # $r->[2] - hash with details:
526 # thisUpdate - time_t of this single response
527 # nextUpdate - time_t when update is expected
528 # statusType - integer:
529 # V_OCSP_CERTSTATUS_GOOD(0)
530 # V_OCSP_CERTSTATUS_REVOKED(1)
531 # V_OCSP_CERTSTATUS_UNKNOWN(2)
532 # revocationTime - time_t (only if revoked)
533 # revocationReason - integer (only if revoked)
534 # revocationReason_str - reason as string (only if revoked)
535 }
536 To further speed up certificate revocation checking one can use a TLS
538 extension to instruct the server to staple the OCSP response:
539 # set TLS extension before doing SSL_connect
541 Net::SSLeay::set_tlsext_status_type($ssl,
542 Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
543 # setup callback to verify OCSP response
545 my $cert_valid = undef;
546 Net::SSLeay::CTX_set_tlsext_status_cb($context,sub {
547 my ($ssl,$resp) = @_;
548 if (!$resp) {
549 # Lots of servers don't return an OCSP response.
550 # In this case we must check the OCSP status outside the SSL
551 # handshake.
552 warn "server did not return stapled OCSP response\n";
553 return 1;
554 }
555 # verify status
556 my $status = Net::SSLeay::OCSP_response_status($resp);
557 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL()) {
558 warn "OCSP response failure: $status\n";
559 return 1;
560 }
561 # verify signature - we have no OCSP_REQUEST here to check nonce
562 if (!eval { Net::SSLeay::OCSP_response_verify($ssl,$resp) }) {
563 warn "OCSP response verify failed\n";
564 return 1;
565 }
566 # check if the certificate is valid
567 # we should check here against the peer_certificate
568 my $cert = Net::SSLeay::get_peer_certificate();
569 my $certid = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) } or do {
570 warn "cannot get certid from cert: $@";
571 $cert_valid = -1;
572 return 1;
573 };
574 if ( $nextupd = eval {
576 Net::SSLeay::OCSP_response_results($resp,$certid) }) {
577 warn "certificate not revoked\n";
578 $cert_valid = 1;
579 } else {
580 warn "certificate not valid: $@";
581 $cert_valid = 0;
582 }
583 });
584 # do SSL handshake here
586 ....
587 # check if certificate revocation was checked already
588 if ( ! defined $cert_valid) {
589 # check revocation outside of SSL handshake by asking OCSP responder
590 ...
591 } elsif ( ! $cert_valid ) {
592 die "certificate not valid - closing SSL connection";
593 } elsif ( $cert_valid<0 ) {
594 die "cannot verify certificate revocation - self-signed ?";
595 } else {
596 # everything fine
597 ...
598 }
599 Using Net::SSLeay in multi-threaded applications
601 IMPORTANT: versions 1.42 or earlier are not thread-safe!
602 Net::SSLeay module implements all necessary stuff to be ready for
604 multi-threaded environment - it requires openssl-0.9.7 or newer. The
605 implementation fully follows thread safety related requirements of
606 openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
607 If you are about to use Net::SSLeay (or any other module based on
609 Net::SSLeay) in multi-threaded perl application it is recommended to
610 follow this best-practice:
611 Initialization
613 Load and initialize Net::SSLeay module in the main thread:
615 use threads;
617 use Net::SSLeay;
618 Net::SSLeay::load_error_strings();
620 Net::SSLeay::SSLeay_add_ssl_algorithms();
621 Net::SSLeay::randomize();
622 sub do_master_job {
624 #... call whatever from Net::SSLeay
625 }
626 sub do_worker_job {
628 #... call whatever from Net::SSLeay
629 }
630 #start threads
632 my $master = threads->new(\&do_master_job, 'param1', 'param2');
633 my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
634 #waiting for all threads to finish
636 $_->join() for (threads->list);
637 NOTE: Openssl's "int SSL_library_init(void)" function (which is also
639 aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
640 and "add_ssl_algorithms") is not re-entrant and multiple calls can
641 cause a crash in threaded application. Net::SSLeay implements flags
642 preventing repeated calls to this function, therefore even multiple
643 initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
644 without trouble.
645 Using callbacks
647 Do not use callbacks across threads (the module blocks cross-thread
649 callback operations and throws a warning). Always do the callback
650 setup, callback use and callback destruction within the same thread.
651 Using openssl elements
653 All openssl elements (X509, SSL_CTX, ...) can be directly passed
655 between threads.
656 use threads;
658 use Net::SSLeay;
659 Net::SSLeay::load_error_strings();
661 Net::SSLeay::SSLeay_add_ssl_algorithms();
662 Net::SSLeay::randomize();
663 sub do_job {
665 my $context = shift;
666 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
667 #...
668 }
669 my $c = Net::SSLeay::CTX_new();
671 threads->create(\&do_job, $c);
672 Or:
674 use threads;
676 use Net::SSLeay;
677 my $context; #does not need to be 'shared'
679 Net::SSLeay::load_error_strings();
681 Net::SSLeay::SSLeay_add_ssl_algorithms();
682 Net::SSLeay::randomize();
683 sub do_job {
685 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
686 #...
687 }
688 $context = Net::SSLeay::CTX_new();
690 threads->create(\&do_job);
691 Using other perl modules based on Net::SSLeay
693 It should be fine to use any other module based on Net::SSLeay (like
695 IO::Socket::SSL) in multi-threaded applications. It is generally
696 recommended to do any global initialization of such a module in the
697 main thread before calling "threads->new(..)" or "threads->create(..)"
698 but it might differ module by module.
699 To be safe you can load and init Net::SSLeay explicitly in the main
701 thread:
702 use Net::SSLeay;
704 use Other::SSLeay::Based::Module;
705 Net::SSLeay::load_error_strings();
707 Net::SSLeay::SSLeay_add_ssl_algorithms();
708 Net::SSLeay::randomize();
709 Or even safer:
711 use Net::SSLeay;
713 use Other::SSLeay::Based::Module;
714 BEGIN {
716 Net::SSLeay::load_error_strings();
717 Net::SSLeay::SSLeay_add_ssl_algorithms();
718 Net::SSLeay::randomize();
719 }
720 Combining Net::SSLeay with other modules linked with openssl
722 BEWARE: This might be a big trouble! This is not guaranteed be thread-
724 safe!
725 There are many other (XS) modules linked directly to openssl library
727 (like Crypt::SSLeay).
728 As it is expected that also "another" module will call
730 "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
731 multiple openssl initialization by Net::SSLeay and "another" module.
732 As you can expect Net::SSLeay is not able to avoid multiple
734 initialization of openssl library called by "another" module, thus you
735 have to handle this on your own (in some cases it might not be possible
736 at all to avoid this).
737 Threading with get_https and friends
739 The convenience functions get_https, post_https etc all initialize the
741 SSL library by calling Net::SSLeay::initialize which does the
742 conventional library initialization:
743 Net::SSLeay::load_error_strings();
745 Net::SSLeay::SSLeay_add_ssl_algorithms();
746 Net::SSLeay::randomize();
747 Net::SSLeay::initialize initializes the SSL library at most once. You
749 can override the Net::SSLeay::initialize function if you desire some
750 other type of initialization behaviour by get_https and friends. You
751 can call Net::SSLeay::initialize from your own code if you desire this
752 conventional library initialization.
753 Convenience routines
755 To be used with Low level API
756 Net::SSLeay::randomize($rn_seed_file,$additional_seed);
758 Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
759 $cert = Net::SSLeay::dump_peer_certificate($ssl);
760 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
761 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
762 $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
764 $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
765 Net::SSLeay::ssl_write_CRLF($ssl, $message);
766 • randomize
768 seeds the openssl PRNG with "/dev/urandom" (see the top of
770 "SSLeay.pm" for how to change or configure this) and optionally
771 with user provided data. It is very important to properly seed your
772 random numbers, so do not forget to call this. The high level API
773 functions automatically call randomize() so it is not needed with
774 them. See also caveats.
775 • set_cert_and_key
777 takes two file names as arguments and sets the certificate and
779 private key to those. This can be used to set either server
780 certificates or client certificates.
781 • dump_peer_certificate
783 allows you to get a plaintext description of the certificate the
785 peer (usually the server) presented to us.
786 • ssl_read_all
788 see ssl_write_all (below)
790 • ssl_write_all
792 ssl_read_all() and ssl_write_all() provide true blocking semantics
794 for these operations (see limitation, below, for explanation).
795 These are much preferred to the low level API equivalents (which
796 implement BSD blocking semantics). The message argument to
797 ssl_write_all() can be a reference. This is helpful to avoid
798 unnecessary copying when writing something big, e.g:
799 $data = 'A' x 1000000000;
801 Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
802 • ssl_read_CRLF
804 uses ssl_read_all() to read in a line terminated with a carriage
806 return followed by a linefeed (CRLF). The CRLF is included in the
807 returned scalar.
808 • ssl_read_until
810 uses ssl_read_all() to read from the SSL input stream until it
812 encounters a programmer specified delimiter. If the delimiter is
813 undefined, $/ is used. If $/ is undefined, "\n" is used. One can
814 optionally set a maximum length of bytes to read from the SSL input
815 stream.
816 • ssl_write_CRLF
818 writes $message and appends CRLF to the SSL output stream.
820 Initialization
822 In order to use the low level API you should start your programs with
823 the following incantation:
824 use Net::SSLeay qw(die_now die_if_ssl_error);
826 Net::SSLeay::load_error_strings();
827 Net::SSLeay::SSLeay_add_ssl_algorithms(); # Important!
828 Net::SSLeay::ENGINE_load_builtin_engines(); # If you want built-in engines
829 Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
830 Net::SSLeay::randomize();
831 Error handling functions
833 I can not emphasize the need to check for error enough. Use these
834 functions even in the most simple programs, they will reduce debugging
835 time greatly. Do not ask questions on the mailing list without having
836 first sprinkled these in your code.
837 • die_now
839 • die_if_ssl_error
841 die_now() and die_if_ssl_error() are used to conveniently print the
843 SSLeay error stack when something goes wrong:
844 Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
846 Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
849 • print_errs
851 You can also use Net::SSLeay::print_errs() to dump the error stack
853 without exiting the program. As can be seen, your code becomes much
854 more readable if you import the error reporting functions into your
855 main name space.
856 Sockets
858 Perl uses file handles for all I/O. While SSLeay has a quite flexible
859 BIO mechanism and perl has an evolved PerlIO mechanism, this module
860 still sticks to using file descriptors. Thus to attach SSLeay to a
861 socket you should use fileno() to extract the underlying file
862 descriptor:
863 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
865 You should also set $| to 1 to eliminate STDIO buffering so you do not
867 get confused if you use perl I/O functions to manipulate your socket
868 handle.
869 If you need to select(2) on the socket, go right ahead, but be warned
871 that OpenSSL does some internal buffering so SSL_read does not always
872 return data even if the socket selected for reading (just keep on
873 selecting and trying to read). "Net::SSLeay" is no different from the C
874 language OpenSSL in this respect.
875 Callbacks
877 You can establish a per-context verify callback function something like
878 this:
879 sub verify {
881 my ($ok, $x509_store_ctx) = @_;
882 print "Verifying certificate...\n";
883 ...
884 return $ok;
885 }
886 It is used like this:
888 Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
890 Per-context callbacks for decrypting private keys are implemented.
892 Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
894 Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
895 Net::SSLeay::FILETYPE_PEM)
896 or die "Error reading private key";
897 Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
898 If Hello Extensions are supported by your OpenSSL, a session secret
900 callback can be set up to be called when a session secret is set by
901 openssl.
902 Establish it like this:
904 Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb, $somedata);
906 It will be called like this:
908 sub session_secret_cb
910 {
911 my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
912 }
913 No other callbacks are implemented. You do not need to use any callback
915 for simple (i.e. normal) cases where the SSLeay built-in verify
916 mechanism satisfies your needs.
917 It is required to reset these callbacks to undef immediately after use
919 to prevent memory leaks, thread safety problems and crashes on exit
920 that can occur if different threads set different callbacks.
921 If you want to use callback stuff, see examples/callback.pl! It's the
923 only one I am able to make work reliably.
924 Low level API
926 In addition to the high level functions outlined above, this module
927 contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
928 API.
929 See the "*.h" headers from OpenSSL C distribution for a list of low
931 level SSLeay functions to call (check SSLeay.xs to see if some function
932 has been implemented). The module strips the initial "SSL_" off of the
933 SSLeay names. Generally you should use "Net::SSLeay::" in its place.
934 Note that some functions are prefixed with "P_" - these are very close
936 to the original API however contain some kind of a wrapper making its
937 interface more perl friendly.
938 For example:
940 In C:
942 #include <ssl.h>
944 err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
946 &your_call_back_here);
947 In Perl:
949 use Net::SSLeay;
951 $err = Net::SSLeay::set_verify ($ssl,
953 Net::SSLeay::VERIFY_CLIENT_ONCE,
954 \&your_call_back_here);
955 If the function does not start with "SSL_" you should use the full
957 function name, e.g.:
958 $err = Net::SSLeay::ERR_get_error;
960 The following new functions behave in perlish way:
962 $got = Net::SSLeay::read($ssl);
964 # Performs SSL_read, but returns $got
965 # resized according to data received.
966 # Returns undef on failure.
967 Net::SSLeay::write($ssl, $foo) || die;
969 # Performs SSL_write, but automatically
970 # figures out the size of $foo
971 Low level API: Version and library information related functions
973 • OpenSSL_version_num and SSLeay
975 COMPATIBILITY: SSLeay() is not available in Net-SSLeay-1.42 and
977 before. SSLeay() was made an alias of OpenSSL_version_num() in
978 OpenSSL 1.1.0 and LibreSSL 2.7.0.
979 COMPATIBILITY: OpenSSL_version_num() requires at least
981 Net-SSLeay-1.82 with OpenSSL 1.1.0, or Net-SSLeay-1.88 with
982 LibreSSL 2.7.0.
983 Both functions return OPENSSL_VERSION_NUMBER constant (numeric) as
985 defined by the underlying OpenSSL or LibreSSL library.
986 my $ver_number = Net::SSLeay::SSLeay();
988 or
989 my $ver_number = Net::SSLeay::OpenSSL_version_num();
990 # returns: OPENSSL_VERSION_NUMBER constant
991 OpenSSL version numbering is:
993 # 0x00903100 => openssl-0.9.3
995 # 0x00904100 => openssl-0.9.4
996 # 0x00905100 => openssl-0.9.5
997 # 0x0090600f => openssl-0.9.6
998 # 0x0090601f => openssl-0.9.6a
999 # ...
1000 # 0x009060df => openssl-0.9.6m
1001 # 0x0090700f => openssl-0.9.7
1002 # 0x0090701f => openssl-0.9.7a
1003 # ...
1004 # 0x009070df => openssl-0.9.7m
1005 # 0x0090800f => openssl-0.9.8
1006 # 0x0090801f => openssl-0.9.8a
1007 # ...
1008 # 0x0090821f => openssl-0.9.8zh
1009 # 0x1000000f => openssl-1.0.0
1010 # ...
1011 # 0x1000014f => openssl-1.0.0t
1012 # 0x1000100f => openssl-1.0.1
1013 # ...
1014 # 0x1000115f => openssl-1.0.1u
1015 # 0x1000200f => openssl-1.0.2
1016 # ...
1017 # 0x1000215f => openssl-1.0.2u
1018 # 0x1010000f => openssl-1.1.0
1019 # ...
1020 # 0x101000cf => openssl-1.1.0l
1021 # 0x1010100f => openssl-1.1.1
1022 # ...
1023 # 0x101010df => openssl-1.1.1m
1024 # 0x30000000 => openssl-3.0.0
1025 # 0x30000010 => openssl-3.0.1
1026 Note that OpenSSL 3.0.0 and later do not set the status nibble in the
1028 least significant octet to f.
1029 LibreSSL returns 0x20000000 always:
1031 # 0x20000000 => libressl-2.2.1
1033 # ...
1034 # 0x20000000 => libressl-3.4.2
1035 You can use the version number like this when you know that the
1037 underlying library is OpenSSL:
1038 if (Net::SSLeay::SSLeay() < 0x0090800f) {
1040 die "You need OpenSSL 0.9.8 or higher";
1041 }
1042 LibresSSL 2.2.2 and later define constant LIBRESSL_VERSION_NUMBER
1044 that gives the LibreSSL version number. The format is the same that
1045 OpenSSL uses with OPENSSL_VERSION_NUMBER. You can do this if you
1046 need to check that the underlying library is LibreSSL and it's
1047 recent enough:
1048 if (Net::SSLeay::SSLeay() != 0x20000000 ||
1050 Net::SSLeay::LIBRESSL_VERSION_NUMBER() < 0x3040200f) {
1051 die "You need LibreSSL. Version 3.4.2 or higher";
1052 }
1053 Check openssl doc
1055 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version_num.html>
1056 See OpenSSL 1.1.1 and earlier documentation for the details of
1058 status nibble and the format interpretation.
1059 • SSLeay_version
1061 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
1063 Returns different strings depending on $type.
1065 my $ver_string = Net::SSLeay::SSLeay_version($type);
1067 # $type
1068 # SSLEAY_VERSION - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
1069 # SSLEAY_CFLAGS - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
1070 # SSLEAY_BUILT_ON - e.g. 'built on: Fri May 6 00:00:46 GMT 2011'
1071 # SSLEAY_PLATFORM - e.g. 'platform: mingw'
1072 # SSLEAY_DIR - e.g. 'OPENSSLDIR: "z:/...."'
1073 #
1074 # returns: string
1075 Net::SSLeay::SSLeay_version();
1077 #is equivalent to
1078 Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
1079 OpenSSL 1.1.0 changed SSLeay_version() to an alias of
1081 OpenSSL_version(). To ensure correct functionality with LibreSSL,
1082 use SSLEAY_* constants with SSLeay_version() and OPENSSL_*
1083 constants with OpenSSL_version().
1084 Check openssl doc
1086 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1087 OpenSSL website no longer has a manual page for SSLeay_version().
1089 • OpenSSL_version
1091 COMPATIBILITY: requires at least Net-SSLeay-1.82 with OpenSSL
1093 1.1.0, or Net-SSLeay-1.88 with LibreSSL 2.7.0.
1094 Returns different strings depending on $t. Available $t constants
1096 depend on the library version.
1097 my $ver_string = Net::SSLeay::OpenSSL_version($t);
1099 # $t
1100 # OPENSSL_VERSION - e.g. 'OpenSSL 1.1.0g 2 Nov 2017'
1101 # OPENSSL_CFLAGS - e.g. 'compiler: cc -DDSO_DLFCN -DHAVE_DLFCN_H .....'
1102 # OPENSSL_BUILT_ON - e.g. 'built on: reproducible build, date unspecified'
1103 # OPENSSL_PLATFORM - e.g. 'platform: darwin64-x86_64-cc'
1104 # OPENSSL_DIR - e.g. 'OPENSSLDIR: "/opt/openssl-1.1.0g"'
1105 # OPENSSL_ENGINES_DIR - e.g. 'ENGINESDIR: "/opt/openssl-1.1.0g/lib/engines-1.1"'
1106 #
1107 # returns: string
1108 Net::SSLeay::OpenSSL_version();
1110 #is equivalent to
1111 Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1112 Check openssl doc
1114 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1115 • OPENSSL_info
1117 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1119 requires at least OpenSSL 3.0.0-alpha1
1120 Returns different strings depending on $t. Available $t constants
1122 depend on the library version.
1123 my $info_string = Net::SSLeay::OPENSSL_info($t);
1125 # $t
1126 # OPENSSL_INFO_CONFIG_DIR - e.g. '/opt/openssl-3.0.1'
1127 # OPENSSL_INFO_...
1128 #
1129 # returns: string
1130 Check openssl doc
1132 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_info.html>
1133 • OPENSSL_version_major, OPENSSL_version_minor and
1135 OPENSSL_version_patch
1136 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1138 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1139 Return constants OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR and
1141 OPENSSL_VERSION_PATCH, respectively.
1142 my $major = Net::SSLeay::OPENSSL_version_major();
1144 my $minor = Net::SSLeay::OPENSSL_version_minor();
1145 my $patch = Net::SSLeay::OPENSSL_version_patch();
1146 #
1147 # return: integer
1148 For example with OpenSSL 3.0.1, $major is 3, $minor is 0 and $patch
1150 is 1.
1151 Note: the constants record Net::SSLeay compile time values whereas
1153 the three functions return values from the library. Typically these
1154 are the same, but they can be different if the library version is
1155 updated but Net::SSLeay is not re-compiled. See the OpenSSL and
1156 LibreSSL API/ABI compatibility statements for more information.
1157 Check openssl doc
1159 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_major.html>
1160 • OPENSSL_version_pre_release
1162 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1164 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1165 Return constant string defined by C macro
1167 OPENSSL_VERSION_PRE_RELEASE.
1168 my $pre_release = Net::SSLeay::OPENSSL_version_pre_release();
1170 #
1171 # returns: string
1172 For example: "-alpha3" or "" for a release version.
1174 When the macro is not defined, an empty string is returned instead.
1176 Check openssl doc
1178 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_pre_release.html>
1179 • OPENSSL_version_build_metadata()
1181 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1183 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1184 Return constant string defined by C macro
1186 OPENSSL_VERSION_BUILD_METADATA.
1187 my $metadata = Net::SSLeay::OPENSSL_version_build_metadata();
1189 #
1190 # returns: string
1191 For example: "+fips" or "".
1193 When the macro is not defined, an empty string is returned instead.
1195 Check openssl doc
1197 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_build_metadata.html>
1198 Low level API: Initialization related functions
1200 • library_init
1202 Initialize SSL library by registering algorithms.
1204 my $rv = Net::SSLeay::library_init();
1206 Check openssl doc
1208 <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1209 While the original function from OpenSSL always returns 1,
1211 Net::SSLeay adds a wrapper around it to make sure that the OpenSSL
1212 function is only called once. Thus the function will return 1 if
1213 initialization was done and 0 if not, i.e. if initialization was
1214 done already before.
1215 • add_ssl_algorithms
1217 The alias for "library_init"
1219 Net::SSLeay::add_ssl_algorithms();
1221 • OpenSSL_add_ssl_algorithms
1223 The alias for "library_init"
1225 Net::SSLeay::OpenSSL_add_ssl_algorithms();
1227 • SSLeay_add_ssl_algorithms
1229 The alias for "library_init"
1231 Net::SSLeay::SSLeay_add_ssl_algorithms();
1233 • load_error_strings
1235 Registers the error strings for all libcrypto + libssl related
1237 functions.
1238 Net::SSLeay::load_error_strings();
1240 #
1241 # returns: no return value
1242 Check openssl doc
1244 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1245 • ERR_load_crypto_strings
1247 Registers the error strings for all libcrypto functions. No need to
1249 call this function if you have already called "load_error_strings".
1250 Net::SSLeay::ERR_load_crypto_strings();
1252 #
1253 # returns: no return value
1254 Check openssl doc
1256 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1257 • ERR_load_RAND_strings
1259 Registers the error strings for RAND related functions. No need to
1261 call this function if you have already called "load_error_strings".
1262 Net::SSLeay::ERR_load_RAND_strings();
1264 #
1265 # returns: no return value
1266 • ERR_load_SSL_strings
1268 Registers the error strings for SSL related functions. No need to
1270 call this function if you have already called "load_error_strings".
1271 Net::SSLeay::ERR_load_SSL_strings();
1273 #
1274 # returns: no return value
1275 • OpenSSL_add_all_algorithms
1277 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1279 Add algorithms to internal table.
1281 Net::SSLeay::OpenSSL_add_all_algorithms();
1283 #
1284 # returns: no return value
1285 Check openssl doc
1287 <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1288 • OPENSSL_add_all_algorithms_conf
1290 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1292 Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1294 config file
1295 Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1297 #
1298 # returns: no return value
1299 • OPENSSL_add_all_algorithms_noconf
1301 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1303 Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1305 config file
1306 Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1308 #
1309 # returns: no return value
1310 Low level API: ERR_* and SSL_alert_* related functions
1312 NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1314 from their names.
1315 • ERR_clear_error
1317 Clear the error queue.
1319 Net::SSLeay::ERR_clear_error();
1321 #
1322 # returns: no return value
1323 Check openssl doc
1325 <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1326 • ERR_error_string
1328 Generates a human-readable string representing the error code
1330 $error.
1331 my $rv = Net::SSLeay::ERR_error_string($error);
1333 # $error - (unsigned integer) error code
1334 #
1335 # returns: string
1336 Check openssl doc
1338 <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1339 • ERR_get_error
1341 Returns the earliest error code from the thread's error queue and
1343 removes the entry. This function can be called repeatedly until
1344 there are no more error codes to return.
1345 my $rv = Net::SSLeay::ERR_get_error();
1347 #
1348 # returns: (unsigned integer) error code
1349 Check openssl doc
1351 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1352 • ERR_peek_error
1354 Returns the earliest error code from the thread's error queue
1356 without modifying it.
1357 my $rv = Net::SSLeay::ERR_peek_error();
1359 #
1360 # returns: (unsigned integer) error code
1361 Check openssl doc
1363 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1364 • ERR_put_error
1366 Adds an error code to the thread's error queue. It signals that the
1368 error of $reason code reason occurred in function $func of library
1369 $lib, in line number $line of $file.
1370 Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
1372 # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
1373 # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
1374 # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
1375 # $file - (string) file name
1376 # $line - (integer) line number in $file
1377 #
1378 # returns: no return value
1379 Check openssl doc
1381 <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
1382 <http://www.openssl.org/docs/crypto/err.html>
1383 • alert_desc_string
1385 Returns a two letter string as a short form describing the reason
1387 of the alert specified by value.
1388 my $rv = Net::SSLeay::alert_desc_string($value);
1390 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1391 #
1392 # returns: description string (2 letters)
1393 Check openssl doc
1395 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1396 • alert_desc_string_long
1398 Returns a string describing the reason of the alert specified by
1400 value.
1401 my $rv = Net::SSLeay::alert_desc_string_long($value);
1403 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1404 #
1405 # returns: description string
1406 Check openssl doc
1408 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1409 • alert_type_string
1411 Returns a one letter string indicating the type of the alert
1413 specified by value.
1414 my $rv = Net::SSLeay::alert_type_string($value);
1416 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1417 #
1418 # returns: string (1 letter)
1419 Check openssl doc
1421 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1422 • alert_type_string_long
1424 Returns a string indicating the type of the alert specified by
1426 value.
1427 my $rv = Net::SSLeay::alert_type_string_long($value);
1429 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1430 #
1431 # returns: string
1432 Check openssl doc
1434 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1435 Low level API: SSL_METHOD_* related functions
1437 • SSLv23_method, SSLv23_server_method and SSLv23_client_method
1439 COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1441 Returns SSL_METHOD structure corresponding to general-purpose
1443 version-flexible TLS method, the return value can be later used as
1444 a param of "CTX_new_with_method".
1445 NOTE: Consider using TLS_method, TLS_server_method or
1447 TLS_client_method with new code.
1448 my $rv = Net::SSLeay::SSLv2_method();
1450 #
1451 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1452 • SSLv2_method
1454 Returns SSL_METHOD structure corresponding to SSLv2 method, the
1456 return value can be later used as a param of "CTX_new_with_method".
1457 Only available where supported by the underlying openssl.
1458 my $rv = Net::SSLeay::SSLv2_method();
1460 #
1461 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1462 • SSLv3_method
1464 Returns SSL_METHOD structure corresponding to SSLv3 method, the
1466 return value can be later used as a param of "CTX_new_with_method".
1467 my $rv = Net::SSLeay::SSLv3_method();
1469 #
1470 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1471 Check openssl doc
1473 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1474 • TLSv1_method, TLSv1_server_method and TLSv1_client_method
1476 COMPATIBILITY: Server and client methods not available in
1478 Net-SSLeay-1.82 and before.
1479 Returns SSL_METHOD structure corresponding to TLSv1 method, the
1481 return value can be later used as a param of "CTX_new_with_method".
1482 my $rv = Net::SSLeay::TLSv1_method();
1484 #
1485 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1486 Check openssl doc
1488 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1489 • TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1491 COMPATIBILITY: Server and client methods not available in
1493 Net-SSLeay-1.82 and before.
1494 Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1496 return value can be later used as a param of "CTX_new_with_method".
1497 Only available where supported by the underlying openssl.
1498 my $rv = Net::SSLeay::TLSv1_1_method();
1500 #
1501 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1502 Check openssl doc
1504 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1505 • TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1507 COMPATIBILITY: Server and client methods not available in
1509 Net-SSLeay-1.82 and before.
1510 Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1512 return value can be later used as a param of "CTX_new_with_method".
1513 Only available where supported by the underlying openssl.
1514 my $rv = Net::SSLeay::TLSv1_2_method();
1516 #
1517 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1518 Check openssl doc
1520 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1521 • TLS_method, TLS_server_method and TLS_client_method
1523 COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1525 Returns SSL_METHOD structure corresponding to general-purpose
1527 version-flexible TLS method, the return value can be later used as
1528 a param of "CTX_new_with_method". Only available where supported by
1529 the underlying openssl.
1530 my $rv = Net::SSLeay::TLS_method();
1532 #
1533 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1534 Check openssl doc
1536 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1537 Low level API: ENGINE_* related functions
1539 • ENGINE_load_builtin_engines
1541 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1543 loading support.
1544 Load all bundled ENGINEs into memory and make them visible.
1546 Net::SSLeay::ENGINE_load_builtin_engines();
1548 #
1549 # returns: no return value
1550 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1552 • ENGINE_register_all_complete
1554 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1556 loading support.
1557 Register all loaded ENGINEs for every algorithm they collectively
1559 implement.
1560 Net::SSLeay::ENGINE_register_all_complete();
1562 #
1563 # returns: no return value
1564 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1566 • ENGINE_set_default
1568 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1570 loading support.
1571 Set default engine to $e + set its flags to $flags.
1573 my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1575 # $e - value corresponding to openssl's ENGINE structure
1576 # $flags - (integer) engine flags
1577 # flags value can be made by bitwise "OR"ing:
1578 # 0x0001 - ENGINE_METHOD_RSA
1579 # 0x0002 - ENGINE_METHOD_DSA
1580 # 0x0004 - ENGINE_METHOD_DH
1581 # 0x0008 - ENGINE_METHOD_RAND
1582 # 0x0010 - ENGINE_METHOD_ECDH
1583 # 0x0020 - ENGINE_METHOD_ECDSA
1584 # 0x0040 - ENGINE_METHOD_CIPHERS
1585 # 0x0080 - ENGINE_METHOD_DIGESTS
1586 # 0x0100 - ENGINE_METHOD_STORE
1587 # 0x0200 - ENGINE_METHOD_PKEY_METHS
1588 # 0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1589 # Obvious all-or-nothing cases:
1590 # 0xFFFF - ENGINE_METHOD_ALL
1591 # 0x0000 - ENGINE_METHOD_NONE
1592 #
1593 # returns: 1 on success, 0 on failure
1594 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1596 • ENGINE_by_id
1598 Get ENGINE by its identification $id.
1600 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1602 loading support.
1603 my $rv = Net::SSLeay::ENGINE_by_id($id);
1605 # $id - (string) engine identification e.g. "dynamic"
1606 #
1607 # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1608 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1610 Low level API: EVP_PKEY_* related functions
1612 • EVP_PKEY_copy_parameters
1614 Copies the parameters from key $from to key $to.
1616 my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1618 # $to - value corresponding to openssl's EVP_PKEY structure
1619 # $from - value corresponding to openssl's EVP_PKEY structure
1620 #
1621 # returns: 1 on success, 0 on failure
1622 Check openssl doc
1624 <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1625 • EVP_PKEY_new
1627 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1629 Creates a new EVP_PKEY structure.
1631 my $rv = Net::SSLeay::EVP_PKEY_new();
1633 #
1634 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1635 Check openssl doc
1637 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1638 • EVP_PKEY_free
1640 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1642 Free an allocated EVP_PKEY structure.
1644 Net::SSLeay::EVP_PKEY_free($pkey);
1646 # $pkey - value corresponding to openssl's EVP_PKEY structure
1647 #
1648 # returns: no return value
1649 Check openssl doc
1651 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1652 • EVP_PKEY_assign_RSA
1654 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1656 Set the key referenced by $pkey to $key
1658 NOTE: No reference counter will be increased, i.e. $key will be
1660 freed if $pkey is freed.
1661 my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1663 # $pkey - value corresponding to openssl's EVP_PKEY structure
1664 # $key - value corresponding to openssl's RSA structure
1665 #
1666 # returns: 1 on success, 0 on failure
1667 Check openssl doc
1669 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1670 • EVP_PKEY_assign_EC_KEY
1672 COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1674 Set the key referenced by $pkey to $key
1676 NOTE: No reference counter will be increased, i.e. $key will be
1678 freed if $pkey is freed.
1679 my $rv = Net::SSLeay::EVP_PKEY_assign_EC_KEY($pkey, $key);
1681 # $pkey - value corresponding to openssl's EVP_PKEY structure
1682 # $key - value corresponding to openssl's EC_KEY structure
1683 #
1684 # returns: 1 on success, 0 on failure
1685 Check openssl doc
1687 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1688 • EVP_PKEY_bits
1690 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1692 Returns the size of the key $pkey in bits.
1694 my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1696 # $pkey - value corresponding to openssl's EVP_PKEY structure
1697 #
1698 # returns: size in bits
1699 • EVP_PKEY_size
1701 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1703 Returns the maximum size of a signature in bytes. The actual
1705 signature may be smaller.
1706 my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1708 # $pkey - value corresponding to openssl's EVP_PKEY structure
1709 #
1710 # returns: the maximum size in bytes
1711 Check openssl doc
1713 <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1714 • EVP_PKEY_id
1716 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1718 requires at least openssl-1.0.0
1719 Returns $pkey type (integer value of corresponding NID).
1721 my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1723 # $pkey - value corresponding to openssl's EVP_PKEY structure
1724 #
1725 # returns: (integer) key type
1726 Example:
1728 my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1730 my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1731 print Net::SSLeay::OBJ_nid2sn($type); #prints e.g. 'rsaEncryption'
1732 Low level API: PEM_* related functions
1734 Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1736 • PEM_read_bio_X509
1738 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1740 Loads PEM formatted X509 certificate via given BIO structure.
1742 my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1744 # $bio - value corresponding to openssl's BIO structure
1745 #
1746 # returns: value corresponding to openssl's X509 structure (0 on failure)
1747 Example:
1749 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1751 my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1752 Net::SSLeay::BIO_free($bio);
1753 • PEM_read_bio_X509_REQ
1755 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1757 Loads PEM formatted X509_REQ object via given BIO structure.
1759 my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1761 # $bio - value corresponding to openssl's BIO structure
1762 #
1763 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1764 Example:
1766 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1768 my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1769 Net::SSLeay::BIO_free($bio);
1770 • PEM_read_bio_DHparams
1772 Reads DH structure from BIO.
1774 my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1776 # $bio - value corresponding to openssl's BIO structure
1777 #
1778 # returns: value corresponding to openssl's DH structure (0 on failure)
1779 • PEM_read_bio_X509_CRL
1781 Reads X509_CRL structure from BIO.
1783 my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1785 # $bio - value corresponding to openssl's BIO structure
1786 #
1787 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1788 • PEM_read_bio_PrivateKey
1790 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1792 Loads PEM formatted private key via given BIO structure.
1794 my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1796 # $bio - value corresponding to openssl's BIO structure
1797 # $cb - reference to perl callback function
1798 # $data - data that will be passed to callback function (see examples below)
1799 #
1800 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1801 Example:
1803 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1805 my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1806 Net::SSLeay::BIO_free($bio);
1807 To use password you have the following options:
1809 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1811 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1812 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1813 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, ""); # use empty password
1814 Callback function signature:
1816 sub callback_func {
1818 my ($max_passwd_size, $rwflag, $data) = @_;
1819 # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1820 # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1821 # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1822 return "secret";
1824 }
1825 • PEM_X509_INFO_read_bio
1827 Reads a BIO containing a PEM formatted file into a
1829 STACK_OF(X509_INFO) structure.
1830 my $rv = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1832 # $bio - value corresponding to openssl's BIO structure
1833 #
1834 # returns: value corresponding to openssl's STACK_OF(X509_INFO) structure.
1835 Example:
1837 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1839 my $sk_x509_info = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1840 Net::SSLeay::BIO_free($bio);
1841 • PEM_get_string_X509
1843 NOTE: Does not exactly correspond to any low level API function
1845 Converts/exports X509 certificate to string (PEM format).
1847 Net::SSLeay::PEM_get_string_X509($x509);
1849 # $x509 - value corresponding to openssl's X509 structure
1850 #
1851 # returns: string with $x509 in PEM format
1852 • PEM_get_string_PrivateKey
1854 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1856 Converts public key $pk into PEM formatted string (optionally
1858 protected with password).
1859 my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1861 # $pk - value corresponding to openssl's EVP_PKEY structure
1862 # $passwd - [optional] (string) password to use for key encryption
1863 # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1864 #
1865 # returns: PEM formatted string
1866 Examples:
1868 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1870 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1871 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1872 • PEM_get_string_X509_CRL
1874 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1876 Converts X509_CRL object $x509_crl into PEM formatted string.
1878 Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1880 # $x509_crl - value corresponding to openssl's X509_CRL structure
1881 #
1882 # returns: no return value
1883 • PEM_get_string_X509_REQ
1885 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1887 Converts X509_REQ object $x509_crl into PEM formatted string.
1889 Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1891 # $x509_req - value corresponding to openssl's X509_REQ structure
1892 #
1893 # returns: no return value
1894 Low level API: d2i_* (DER format) related functions
1896 • d2i_X509_bio
1898 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1900 Loads DER formatted X509 certificate via given BIO structure.
1902 my $rv = Net::SSLeay::d2i_X509_bio($bp);
1904 # $bp - value corresponding to openssl's BIO structure
1905 #
1906 # returns: value corresponding to openssl's X509 structure (0 on failure)
1907 Example:
1909 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1911 my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1912 Net::SSLeay::BIO_free($bio);
1913 Check openssl doc
1915 <http://www.openssl.org/docs/crypto/d2i_X509.html>
1916 • d2i_X509_CRL_bio
1918 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1920 Loads DER formatted X509_CRL object via given BIO structure.
1922 my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1924 # $bp - value corresponding to openssl's BIO structure
1925 #
1926 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1927 Example:
1929 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1931 my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1932 Net::SSLeay::BIO_free($bio);
1933 • d2i_X509_REQ_bio
1935 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1937 Loads DER formatted X509_REQ object via given BIO structure.
1939 my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1941 # $bp - value corresponding to openssl's BIO structure
1942 #
1943 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1944 Example:
1946 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1948 my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1949 Net::SSLeay::BIO_free($bio);
1950 Low level API: PKCS12 related functions
1952 • P_PKCS12_load_file
1954 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1956 Loads X509 certificate + private key + certificates of CA chain (if
1958 present in PKCS12 file).
1959 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1961 # $filename - name of PKCS12 file
1962 # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1963 # $password - [optional] password for private key
1964 #
1965 # returns: triplet ($privkey, $cert, @cachain)
1966 # $privkey - value corresponding to openssl's EVP_PKEY structure
1967 # $cert - value corresponding to openssl's X509 structure
1968 # @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1969 IMPORTANT NOTE: after you do the job you need to call X509_free()
1971 on $privkey + all members of @cachain and EVP_PKEY_free() on
1972 $privkey.
1973 Examples:
1975 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1977 #or
1978 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1979 #or
1980 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1981 #or
1982 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1983 #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1985 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1986 NOTE With some combinations of Windows, perl, compiler and compiler
1988 options, you may see a runtime error "no OPENSSL_Applink", when
1989 calling Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more
1990 details.
1991 Low level API: SESSION_* related functions
1993 • d2i_SSL_SESSION
1995 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1997 Transforms the binary ASN1 representation string of an SSL/TLS
1999 session into an SSL_SESSION object.
2000 my $ses = Net::SSLeay::d2i_SSL_SESSION($data);
2002 # $data - the session as ASN1 representation string
2003 #
2004 # returns: $ses - the new SSL_SESSION
2005 Check openssl doc
2007 <https://www.openssl.org/docs/ssl/i2d_SSL_SESSION.html>
2008 • i2d_SSL_SESSION
2010 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
2012 Transforms the SSL_SESSION object in into the ASN1 representation
2014 and returns it as string.
2015 my $data = Net::SSLeay::i2d_SSL_SESSION($ses);
2017 # $ses - value corresponding to openssl's SSL_SESSION structure
2018 #
2019 # returns: $data - session as string
2020 Check openssl doc
2022 <https://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
2023 • SESSION_new
2025 Creates a new SSL_SESSION structure.
2027 my $rv = Net::SSLeay::SESSION_new();
2029 #
2030 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
2031 • SESSION_free
2033 Free an allocated SSL_SESSION structure.
2035 Net::SSLeay::SESSION_free($ses);
2037 # $ses - value corresponding to openssl's SSL_SESSION structure
2038 #
2039 # returns: no return value
2040 Check openssl doc
2042 <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
2043 • SESSION_up_ref
2045 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2047 requires at least OpenSSL 1.1.0-pre4 or LibreSSL 2.7.0
2048 Increases the reference counter on a SSL_SESSION structure.
2050 Net::SSLeay::SESSION_up_ref($ses);
2052 # $ses - value corresponding to openssl's SSL_SESSION structure
2053 #
2054 # returns: 1 on success else 0
2055 Check openssl doc
2057 <https://www.openssl.org/docs/ssl/SSL_SESSION_up_ref.html>
2058 • SESSION_dup
2060 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2062 requires at least OpenSSL 1.1.1, not in LibreSSL
2063 Duplicates a SSL_SESSION structure.
2065 Net::SSLeay::SESSION_dup($ses);
2067 # $ses - value corresponding to openssl's SSL_SESSION structure
2068 #
2069 # returns: the duplicated session
2070 Check openssl doc
2072 <https://www.openssl.org/docs/ssl/SSL_SESSION_dup.html>
2073 • SESSION_is_resumable
2075 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2077 requires at least OpenSSL 1.1.1, not in LibreSSL
2078 Determine whether an SSL_SESSION object can be used for resumption.
2080 Net::SSLeay::SESSION_is_resumable($ses);
2082 # $ses - value corresponding to openssl's SSL_SESSION structure
2083 #
2084 # returns: (integer) 1 if it can or 0 if not
2085 Check openssl doc
2087 <https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html>
2088 • SESSION_cmp
2090 Compare two SSL_SESSION structures.
2092 my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
2094 # $sesa - value corresponding to openssl's SSL_SESSION structure
2095 # $sesb - value corresponding to openssl's SSL_SESSION structure
2096 #
2097 # returns: 0 if the two structures are the same
2098 NOTE: Not available in openssl 1.0 or later
2100 • SESSION_get_app_data
2102 Can be used to get application defined value/data.
2104 my $rv = Net::SSLeay::SESSION_get_app_data($ses);
2106 # $ses - value corresponding to openssl's SSL_SESSION structure
2107 #
2108 # returns: string/buffer/pointer ???
2109 • SESSION_set_app_data
2111 Can be used to set some application defined value/data.
2113 my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
2115 # $s - value corresponding to openssl's SSL_SESSION structure
2116 # $a - (string/buffer/pointer ???) data
2117 #
2118 # returns: ???
2119 • SESSION_get_ex_data
2121 Is used to retrieve the information for $idx from session $ses.
2123 my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
2125 # $ses - value corresponding to openssl's SSL_SESSION structure
2126 # $idx - (integer) index for application specific data
2127 #
2128 # returns: pointer to ???
2129 Check openssl doc
2131 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2132 • SESSION_set_ex_data
2134 Is used to store application data at arg for idx into the session
2136 object.
2137 my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
2139 # $ss - value corresponding to openssl's SSL_SESSION structure
2140 # $idx - (integer) ???
2141 # $data - (pointer) ???
2142 #
2143 # returns: 1 on success, 0 on failure
2144 Check openssl doc
2146 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2147 • SESSION_get_ex_new_index
2149 Is used to register a new index for application specific data.
2151 my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2153 # $argl - (long) ???
2154 # $argp - (pointer) ???
2155 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2156 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2157 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2158 #
2159 # returns: (integer) ???
2160 Check openssl doc
2162 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2163 • SESSION_get_master_key
2165 NOTE: Does not exactly correspond to any low level API function
2167 Returns 'master_key' value from SSL_SESSION structure $s
2169 Net::SSLeay::SESSION_get_master_key($s);
2171 # $s - value corresponding to openssl's SSL_SESSION structure
2172 #
2173 # returns: master key (binary data)
2174 • SESSION_set_master_key
2176 Sets 'master_key' value for SSL_SESSION structure $s
2178 Net::SSLeay::SESSION_set_master_key($s, $key);
2180 # $s - value corresponding to openssl's SSL_SESSION structure
2181 # $key - master key (binary data)
2182 #
2183 # returns: no return value
2184 Not available with OpenSSL 1.1 and later. Code that previously
2186 used
2187 SESSION_set_master_key must now set $secret in the
2188 session_secret
2189 callback set with SSL_set_session_secret_cb.
2190 • SESSION_get_time
2192 Returns the time at which the session s was established. The time
2194 is given in seconds since 1.1.1970.
2195 my $rv = Net::SSLeay::SESSION_get_time($s);
2197 # $s - value corresponding to openssl's SSL_SESSION structure
2198 #
2199 # returns: timestamp (seconds since 1.1.1970)
2200 Check openssl doc
2202 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2203 • get_time
2205 Technically the same functionality as "SESSION_get_time".
2207 my $rv = Net::SSLeay::get_time($s);
2209 • SESSION_get_timeout
2211 Returns the timeout value set for session $s in seconds.
2213 my $rv = Net::SSLeay::SESSION_get_timeout($s);
2215 # $s - value corresponding to openssl's SSL_SESSION structure
2216 #
2217 # returns: timeout (in seconds)
2218 Check openssl doc
2220 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2221 • get_timeout
2223 Technically the same functionality as "SESSION_get_timeout".
2225 my $rv = Net::SSLeay::get_timeout($s);
2227 • SESSION_print
2229 NOTE: Does not exactly correspond to any low level API function
2231 Prints session details (e.g. protocol version, cipher, session-id
2233 ...) to BIO.
2234 my $rv = Net::SSLeay::SESSION_print($fp, $ses);
2236 # $fp - value corresponding to openssl's BIO structure
2237 # $ses - value corresponding to openssl's SSL_SESSION structure
2238 #
2239 # returns: 1 on success, 0 on failure
2240 You have to use necessary BIO functions like this:
2242 # let us have $ssl corresponding to openssl's SSL structure
2244 my $ses = Net::SSLeay::get_session($ssl);
2245 my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
2246 Net::SSLeay::SESSION_print($bio, $ses);
2247 print Net::SSLeay::BIO_read($bio);
2248 • SESSION_print_fp
2250 Prints session details (e.g. protocol version, cipher, session-id
2252 ...) to file handle.
2253 my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
2255 # $fp - perl file handle
2256 # $ses - value corresponding to openssl's SSL_SESSION structure
2257 #
2258 # returns: 1 on success, 0 on failure
2259 Example:
2261 # let us have $ssl corresponding to openssl's SSL structure
2263 my $ses = Net::SSLeay::get_session($ssl);
2264 open my $fh, ">", "output.txt";
2265 Net::SSLeay::SESSION_print_fp($fh,$ses);
2266 • SESSION_set_time
2268 Replaces the creation time of the session s with the chosen value
2270 $t (seconds since 1.1.1970).
2271 my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
2273 # $ses - value corresponding to openssl's SSL_SESSION structure
2274 # $t - time value
2275 #
2276 # returns: 1 on success
2277 Check openssl doc
2279 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2280 • set_time
2282 Technically the same functionality as "SESSION_set_time".
2284 my $rv = Net::SSLeay::set_time($ses, $t);
2286 • SESSION_set_timeout
2288 Sets the timeout value for session s in seconds to $t.
2290 my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
2292 # $s - value corresponding to openssl's SSL_SESSION structure
2293 # $t - timeout (in seconds)
2294 #
2295 # returns: 1 on success
2296 Check openssl doc
2298 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2299 • set_timeout
2301 Technically the same functionality as "SESSION_set_timeout".
2303 my $rv = Net::SSLeay::set_timeout($ses, $t);
2305 Low level API: SSL_CTX_* related functions
2307 NOTE: Please note that the function described in this chapter have
2309 "SSL_" part stripped from their original openssl names.
2310 • CTX_add_client_CA
2312 Adds the CA name extracted from $cacert to the list of CAs sent to
2314 the client when requesting a client certificate for $ctx.
2315 my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
2317 # $ctx - value corresponding to openssl's SSL_CTX structure
2318 # $cacert - value corresponding to openssl's X509 structure
2319 #
2320 # returns: 1 on success, 0 on failure
2321 Check openssl doc
2323 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2324 • CTX_add_extra_chain_cert
2326 Adds the certificate $x509 to the certificate chain presented
2328 together with the certificate. Several certificates can be added
2329 one after the other.
2330 my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
2332 # $ctx - value corresponding to openssl's SSL_CTX structure
2333 # $x509 - value corresponding to openssl's X509 structure
2334 #
2335 # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
2336 Check openssl doc
2338 <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2339 • CTX_add_session
2341 Adds the session $ses to the context $ctx.
2343 my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
2345 # $ctx - value corresponding to openssl's SSL_CTX structure
2346 # $ses - value corresponding to openssl's SSL_SESSION structure
2347 #
2348 # returns: 1 on success, 0 on failure
2349 Check openssl doc
2351 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2352 • CTX_callback_ctrl
2354 ??? (more info needed)
2356 my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
2358 # $ctx - value corresponding to openssl's SSL_CTX structure
2359 # $cmd - (integer) command id
2360 # $fp - (function pointer) ???
2361 #
2362 # returns: ???
2363 Check openssl doc
2365 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2366 • CTX_check_private_key
2368 Checks the consistency of a private key with the corresponding
2370 certificate loaded into $ctx.
2371 my $rv = Net::SSLeay::CTX_check_private_key($ctx);
2373 # $ctx - value corresponding to openssl's SSL_CTX structure
2374 #
2375 # returns: 1 on success, otherwise check out the error stack to find out the reason
2376 Check openssl doc
2378 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2379 • CTX_ctrl
2381 Internal handling function for SSL_CTX objects.
2383 BEWARE: openssl doc says: This function should never be called
2385 directly!
2386 my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
2388 # $ctx - value corresponding to openssl's SSL_CTX structure
2389 # $cmd - (integer) command id
2390 # $larg - (integer) long ???
2391 # $parg - (string/pointer) ???
2392 #
2393 # returns: (long) result of given command ???
2394 #valid $cmd values
2396 1 - SSL_CTRL_NEED_TMP_RSA
2397 2 - SSL_CTRL_SET_TMP_RSA
2398 3 - SSL_CTRL_SET_TMP_DH
2399 4 - SSL_CTRL_SET_TMP_ECDH
2400 5 - SSL_CTRL_SET_TMP_RSA_CB
2401 6 - SSL_CTRL_SET_TMP_DH_CB
2402 7 - SSL_CTRL_SET_TMP_ECDH_CB
2403 8 - SSL_CTRL_GET_SESSION_REUSED
2404 9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
2405 10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
2406 11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
2407 12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
2408 13 - SSL_CTRL_GET_FLAGS
2409 14 - SSL_CTRL_EXTRA_CHAIN_CERT
2410 15 - SSL_CTRL_SET_MSG_CALLBACK
2411 16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
2412 17 - SSL_CTRL_SET_MTU
2413 20 - SSL_CTRL_SESS_NUMBER
2414 21 - SSL_CTRL_SESS_CONNECT
2415 22 - SSL_CTRL_SESS_CONNECT_GOOD
2416 23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
2417 24 - SSL_CTRL_SESS_ACCEPT
2418 25 - SSL_CTRL_SESS_ACCEPT_GOOD
2419 26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
2420 27 - SSL_CTRL_SESS_HIT
2421 28 - SSL_CTRL_SESS_CB_HIT
2422 29 - SSL_CTRL_SESS_MISSES
2423 30 - SSL_CTRL_SESS_TIMEOUTS
2424 31 - SSL_CTRL_SESS_CACHE_FULL
2425 32 - SSL_CTRL_OPTIONS
2426 33 - SSL_CTRL_MODE
2427 40 - SSL_CTRL_GET_READ_AHEAD
2428 41 - SSL_CTRL_SET_READ_AHEAD
2429 42 - SSL_CTRL_SET_SESS_CACHE_SIZE
2430 43 - SSL_CTRL_GET_SESS_CACHE_SIZE
2431 44 - SSL_CTRL_SET_SESS_CACHE_MODE
2432 45 - SSL_CTRL_GET_SESS_CACHE_MODE
2433 50 - SSL_CTRL_GET_MAX_CERT_LIST
2434 51 - SSL_CTRL_SET_MAX_CERT_LIST
2435 52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
2436 53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
2437 54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
2438 55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
2439 56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
2440 57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
2441 58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
2442 59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
2443 60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
2444 61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
2445 62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
2446 63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
2447 64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
2448 65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
2449 66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
2450 67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
2451 68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
2452 69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
2453 70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
2454 71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
2455 72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
2456 73 - DTLS_CTRL_GET_TIMEOUT
2457 74 - DTLS_CTRL_HANDLE_TIMEOUT
2458 75 - DTLS_CTRL_LISTEN
2459 76 - SSL_CTRL_GET_RI_SUPPORT
2460 77 - SSL_CTRL_CLEAR_OPTIONS
2461 78 - SSL_CTRL_CLEAR_MODE
2462 82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2464 83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2465 88 - SSL_CTRL_CHAIN
2467 89 - SSL_CTRL_CHAIN_CERT
2468 90 - SSL_CTRL_GET_CURVES
2470 91 - SSL_CTRL_SET_CURVES
2471 92 - SSL_CTRL_SET_CURVES_LIST
2472 93 - SSL_CTRL_GET_SHARED_CURVE
2473 94 - SSL_CTRL_SET_ECDH_AUTO
2474 97 - SSL_CTRL_SET_SIGALGS
2475 98 - SSL_CTRL_SET_SIGALGS_LIST
2476 99 - SSL_CTRL_CERT_FLAGS
2477 100 - SSL_CTRL_CLEAR_CERT_FLAGS
2478 101 - SSL_CTRL_SET_CLIENT_SIGALGS
2479 102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
2480 103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
2481 104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
2482 105 - SSL_CTRL_BUILD_CERT_CHAIN
2483 106 - SSL_CTRL_SET_VERIFY_CERT_STORE
2484 107 - SSL_CTRL_SET_CHAIN_CERT_STORE
2485 108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
2486 109 - SSL_CTRL_GET_SERVER_TMP_KEY
2487 110 - SSL_CTRL_GET_RAW_CIPHERLIST
2488 111 - SSL_CTRL_GET_EC_POINT_FORMATS
2489 112 - SSL_CTRL_GET_TLSA_RECORD
2490 113 - SSL_CTRL_SET_TLSA_RECORD
2491 114 - SSL_CTRL_PULL_TLSA_RECORD
2492 Check openssl doc
2494 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2495 • CTX_flush_sessions
2497 Causes a run through the session cache of $ctx to remove sessions
2499 expired at time $tm.
2500 Net::SSLeay::CTX_flush_sessions($ctx, $tm);
2502 # $ctx - value corresponding to openssl's SSL_CTX structure
2503 # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
2504 #
2505 # returns: no return value
2506 Check openssl doc
2508 <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2509 • CTX_free
2511 Free an allocated SSL_CTX object.
2513 Net::SSLeay::CTX_free($ctx);
2515 # $ctx - value corresponding to openssl's SSL_CTX structure
2516 #
2517 # returns: no return value
2518 Check openssl doc
2520 <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2521 • CTX_get_app_data
2523 Can be used to get application defined value/data.
2525 my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2527 # $ctx - value corresponding to openssl's SSL_CTX structure
2528 #
2529 # returns: string/buffer/pointer ???
2530 • CTX_set_app_data
2532 Can be used to set some application defined value/data.
2534 my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2536 # $ctx - value corresponding to openssl's SSL_CTX structure
2537 # $arg - (string/buffer/pointer ???) data
2538 #
2539 # returns: ???
2540 • CTX_get0_param
2542 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2544 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
2545 Returns the current verification parameters.
2547 my $vpm = Net::SSLeay::CTX_get0_param($ctx);
2549 # $ctx - value corresponding to openssl's SSL_CTX structure
2550 #
2551 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
2552 Check openssl doc
2554 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2555 • CTX_get_cert_store
2557 Returns the current certificate verification storage.
2559 my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2561 # $ctx - value corresponding to openssl's SSL_CTX structure
2562 #
2563 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2564 Check openssl doc
2566 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2567 • CTX_get_client_CA_list
2569 Returns the list of client CAs explicitly set for $ctx using
2571 "CTX_set_client_CA_list".
2572 my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2574 # $ctx - value corresponding to openssl's SSL_CTX structure
2575 #
2576 # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2577 Check openssl doc
2579 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2580 • CTX_get_ex_data
2582 Is used to retrieve the information for index $idx from $ctx.
2584 my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2586 # $ssl - value corresponding to openssl's SSL_CTX structure
2587 # $idx - (integer) index for application specific data
2588 #
2589 # returns: pointer to ???
2590 Check openssl doc
2592 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2593 • CTX_get_ex_new_index
2595 Is used to register a new index for application specific data.
2597 my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2599 # $argl - (long) ???
2600 # $argp - (pointer) ???
2601 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2602 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2603 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2604 #
2605 # returns: (integer) ???
2606 Check openssl doc
2608 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2609 • CTX_get_mode
2611 Returns the mode set for ctx.
2613 my $rv = Net::SSLeay::CTX_get_mode($ctx);
2615 # $ctx - value corresponding to openssl's SSL_CTX structure
2616 #
2617 # returns: mode (bitmask)
2618 #to decode the return value (bitmask) use:
2620 0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2621 0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2622 0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2623 0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2624 0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2625 (note: some of the bits might not be supported by older openssl versions)
2626 Check openssl doc
2628 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2629 • CTX_set_mode
2631 Adds the mode set via bitmask in $mode to $ctx. Options already set
2633 before are not cleared.
2634 my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2636 # $ctx - value corresponding to openssl's SSL_CTX structure
2637 # $mode - mode bitmask
2638 #
2639 # returns: the new mode bitmask after adding $mode
2640 For bitmask details see "CTX_get_mode" (above).
2642 Check openssl doc
2644 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2645 • CTX_get_options
2647 Returns the options (bitmask) set for $ctx.
2649 my $rv = Net::SSLeay::CTX_get_options($ctx);
2651 # $ctx - value corresponding to openssl's SSL_CTX structure
2652 #
2653 # returns: options (bitmask)
2654 BEWARE: The available constants and their values in bitmask depend
2656 on the TLS library. For example, SSL_OP_NO_TLSv1_3 became available
2657 much later than SSL_OP_NO_COMPRESS which is already deprecated by
2658 some libraries. Also, some previously used option values have been
2659 recycled and are now used for newer options. See the list of
2660 constants in this document for options Net::SSLeay currently
2661 supports.
2662 You are strongly encouraged to check your TLS library if you need
2664 to use numeric values directly. The following is a sample of
2665 historic values. It may not be correct anymore.
2666 #to decode the return value (bitmask) use:
2668 0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2669 0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2670 0x00004000 corresponds to SSL_OP_NO_TICKET
2671 0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2672 0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2673 0x04000000 corresponds to SSL_OP_NO_TLSv1
2674 Check openssl doc
2676 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_options.html>
2677 • CTX_set_options
2679 Adds the options set via bitmask in $options to ctx. Options
2681 already set before are not cleared.
2682 Net::SSLeay::CTX_set_options($ctx, $options);
2684 # $ctx - value corresponding to openssl's SSL_CTX structure
2685 # $options - options bitmask
2686 #
2687 # returns: the new options bitmask after adding $options
2688 For bitmask details see "CTX_get_options" (above).
2690 Check openssl doc
2692 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html>
2693 • CTX_get_quiet_shutdown
2695 Returns the 'quiet shutdown' setting of $ctx.
2697 my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2699 # $ctx - value corresponding to openssl's SSL_CTX structure
2700 #
2701 # returns: (integer) the current setting
2702 Check openssl doc
2704 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2705 • CTX_get_read_ahead
2707 my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2709 # $ctx - value corresponding to openssl's SSL_CTX structure
2710 #
2711 # returns: (integer) read_ahead value
2712 • CTX_get_session_cache_mode
2714 Returns the currently used cache mode (bitmask).
2716 my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2718 # $ctx - value corresponding to openssl's SSL_CTX structure
2719 #
2720 # returns: mode (bitmask)
2721 BEWARE: SESS_CACHE_OFF and other constants are not available in
2723 Net-SSLeay-1.82 and before. If the constants are not available,
2724 the following values have historically been correct. You are
2725 strongly encouraged to check your TLS library for the current
2726 values.
2727 #to decode the return value (bitmask) use:
2729 0x0000 corresponds to SSL_SESS_CACHE_OFF
2730 0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2731 0x0002 corresponds to SSL_SESS_CACHE_SERVER
2732 0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2733 0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2734 0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2735 (note: some of the bits might not be supported by older openssl versions)
2736 Check openssl doc
2738 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2739 • CTX_set_session_cache_mode
2741 Enables/disables session caching by setting the operational mode
2743 for $ctx to $mode.
2744 my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2746 # $ctx - value corresponding to openssl's SSL_CTX structure
2747 # $mode - mode (bitmask)
2748 #
2749 # returns: previously set cache mode
2750 For bitmask details see "CTX_get_session_cache_mode" (above).
2752 Check openssl doc
2754 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2755 • CTX_get_timeout
2757 Returns the currently set timeout value for $ctx.
2759 my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2761 # $ctx - value corresponding to openssl's SSL_CTX structure
2762 #
2763 # returns: timeout in seconds
2764 Check openssl doc
2766 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2767 • CTX_get_verify_depth
2769 Returns the verification depth limit currently set in $ctx. If no
2771 limit has been explicitly set, -1 is returned and the default value
2772 will be used.
2773 my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2775 # $ctx - value corresponding to openssl's SSL_CTX structure
2776 #
2777 # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2778 Check openssl doc
2780 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2781 • CTX_get_verify_mode
2783 Returns the verification mode (bitmask) currently set in $ctx.
2785 my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2787 # $ctx - value corresponding to openssl's SSL_CTX structure
2788 #
2789 # returns: mode (bitmask)
2790 For bitmask details see "CTX_set_verify".
2792 Check openssl doc
2794 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_verify_mode.html>
2795 • CTX_set_verify
2797 Sets the verification flags for $ctx to be $mode and specifies the
2799 verify_callback function to be used.
2800 Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2802 # $ctx - value corresponding to openssl's SSL_CTX structure
2803 # $mode - mode (bitmask), see OpenSSL manual
2804 # $callback - [optional] reference to perl callback function
2805 #
2806 # returns: no return value
2807 Check openssl doc
2809 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html>
2810 • CTX_set_post_handshake_auth
2812 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2814 requires at least OpenSSL 1.1.1, not in LibreSSL
2815 Enable the Post-Handshake Authentication extension to be added to
2817 the ClientHello such that post-handshake authentication can be
2818 requested by the server.
2819 Net::SSLeay::CTX_set_posthandshake_auth($ctx, $val);
2821 # $ctx - value corresponding to openssl's SSL_CTX structure
2822 # $val - 0 then the extension is not sent, otherwise it is
2823 #
2824 # returns: no return value
2825 Check openssl doc
2827 https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth
2828 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth.html>
2829 • CTX_load_verify_locations
2831 Specifies the locations for $ctx, at which CA certificates for
2833 verification purposes are located. The certificates available via
2834 $CAfile and $CApath are trusted.
2835 my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2837 # $ctx - value corresponding to openssl's SSL_CTX structure
2838 # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2839 # $CApath - (string) directory containing CA certificates in PEM format (or '')
2840 #
2841 # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2842 Check openssl doc
2844 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2845 • CTX_need_tmp_RSA
2847 Return the result of
2849 "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2850 my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2852 # $ctx - value corresponding to openssl's SSL_CTX structure
2853 #
2854 # returns: result of SSL_CTRL_NEED_TMP_RSA command
2855 Not available with OpenSSL 1.1 and later.
2857 • CTX_new
2859 The same as "CTX_v23_new"
2861 my $rv = Net::SSLeay::CTX_new();
2863 #
2864 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2865 Check openssl doc
2867 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2868 Not available with OpenSSL 1.1 and later.
2870 • CTX_v2_new
2872 Creates a new SSL_CTX object - based on SSLv2_method() - as
2874 framework to establish TLS/SSL enabled connections.
2875 my $rv = Net::SSLeay::CTX_v2_new();
2877 #
2878 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2879 • CTX_v23_new
2881 Creates a new SSL_CTX object - based on SSLv23_method() - as
2883 framework to establish TLS/SSL enabled connections.
2884 my $rv = Net::SSLeay::CTX_v23_new();
2886 #
2887 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2888 • CTX_v3_new
2890 Creates a new SSL_CTX object - based on SSLv3_method() - as
2892 framework to establish TLS/SSL enabled connections.
2893 my $rv = Net::SSLeay::CTX_v3_new();
2895 #
2896 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2897 • CTX_tlsv1_new
2899 Creates a new SSL_CTX object - based on TLSv1_method() - as
2901 framework to establish TLS/SSL enabled connections.
2902 my $rv = Net::SSLeay::CTX_tlsv1_new();
2904 #
2905 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2906 • CTX_tlsv1_1_new
2908 Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2910 framework to establish TLS/SSL enabled connections. Only available
2911 where supported by the underlying openssl.
2912 my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2914 #
2915 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2916 • CTX_tlsv1_2_new
2918 Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2920 framework to establish TLS/SSL enabled connections. Only available
2921 where supported by the underlying openssl.
2922 my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2924 #
2925 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2926 • CTX_new_with_method
2928 Creates a new SSL_CTX object based on $meth method
2930 my $rv = Net::SSLeay::CTX_new_with_method($meth);
2932 # $meth - value corresponding to openssl's SSL_METHOD structure
2933 #
2934 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2935 #example
2937 my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2938 Check openssl doc
2940 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2941 • CTX_set_min_proto_version, CTX_set_max_proto_version,
2943 set_min_proto_version and set_max_proto_version,
2944 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2946 requires at least OpenSSL 1.1.0-pre2 or LibreSSL 2.6.0
2947 Set the minimum and maximum supported protocol for $ctx or $ssl.
2949 my $rv = Net::SSLeay::CTX_set_min_proto_version($ctx, $version)
2951 # $ctx - value corresponding to openssl's SSL_CTX structure
2952 # $version - (integer) constat version value or 0 for automatic lowest or highest value
2953 #
2954 # returns: 1 on success, 0 on failure
2955 #example: allow only TLS 1.2 for a SSL_CTX
2957 my $rv_min = Net::SSLeay::CTX_set_min_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2958 my $rv_max = Net::SSLeay::CTX_set_max_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2959 #example: allow only TLS 1.1 for a SSL
2961 my $rv_min = Net::SSLeay::set_min_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2962 my $rv_max = Net::SSLeay::set_max_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2963 Check openssl doc
2965 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2966 • CTX_get_min_proto_version, CTX_get_max_proto_version,
2968 get_min_proto_version and get_max_proto_version,
2969 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2971 requires at least OpenSSL 1.1.0g
2972 Get the minimum and maximum supported protocol for $ctx or $ssl.
2974 my $version = Net::SSLeay::CTX_get_min_proto_version($ctx)
2976 # $ctx - value corresponding to openssl's SSL_CTX structure
2977 #
2978 # returns: 0 automatic lowest or highest value, configured value otherwise
2979 Check openssl doc
2981 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2982 • CTX_remove_session
2984 Removes the session $ses from the context $ctx.
2986 my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2988 # $ctx - value corresponding to openssl's SSL_CTX structure
2989 # $ses - value corresponding to openssl's SSL_SESSION structure
2990 #
2991 # returns: 1 on success, 0 on failure
2992 Check openssl doc
2994 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2995 • CTX_sess_accept
2997 my $rv = Net::SSLeay::CTX_sess_accept($ctx);
2999 # $ctx - value corresponding to openssl's SSL_CTX structure
3000 #
3001 # returns: number of started SSL/TLS handshakes in server mode
3002 Check openssl doc
3004 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3005 • CTX_sess_accept_good
3007 my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
3009 # $ctx - value corresponding to openssl's SSL_CTX structure
3010 #
3011 # returns: number of successfully established SSL/TLS sessions in server mode
3012 Check openssl doc
3014 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3015 • CTX_sess_accept_renegotiate
3017 my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
3019 # $ctx - value corresponding to openssl's SSL_CTX structure
3020 #
3021 # returns: number of start renegotiations in server mode
3022 Check openssl doc
3024 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3025 • CTX_sess_cache_full
3027 my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
3029 # $ctx - value corresponding to openssl's SSL_CTX structure
3030 #
3031 # returns: number of sessions that were removed because the maximum session cache size was exceeded
3032 Check openssl doc
3034 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3035 • CTX_sess_cb_hits
3037 my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
3039 # $ctx - value corresponding to openssl's SSL_CTX structure
3040 #
3041 # returns: number of successfully retrieved sessions from the external session cache in server mode
3042 Check openssl doc
3044 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3045 • CTX_sess_connect
3047 my $rv = Net::SSLeay::CTX_sess_connect($ctx);
3049 # $ctx - value corresponding to openssl's SSL_CTX structure
3050 #
3051 # returns: number of started SSL/TLS handshakes in client mode
3052 Check openssl doc
3054 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3055 • CTX_sess_connect_good
3057 my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
3059 # $ctx - value corresponding to openssl's SSL_CTX structure
3060 #
3061 # returns: number of successfully established SSL/TLS sessions in client mode
3062 Check openssl doc
3064 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3065 • CTX_sess_connect_renegotiate
3067 my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
3069 # $ctx - value corresponding to openssl's SSL_CTX structure
3070 #
3071 # returns: number of start renegotiations in client mode
3072 Check openssl doc
3074 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3075 • CTX_sess_get_cache_size
3077 Returns the currently valid session cache size.
3079 my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
3081 # $ctx - value corresponding to openssl's SSL_CTX structure
3082 #
3083 # returns: current size
3084 Check openssl doc
3086 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3087 • CTX_sess_hits
3089 my $rv = Net::SSLeay::CTX_sess_hits($ctx);
3091 # $ctx - value corresponding to openssl's SSL_CTX structure
3092 #
3093 # returns: number of successfully reused sessions
3094 Check openssl doc
3096 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3097 • CTX_sess_misses
3099 my $rv = Net::SSLeay::CTX_sess_misses($ctx);
3101 # $ctx - value corresponding to openssl's SSL_CTX structure
3102 #
3103 # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
3104 Check openssl doc
3106 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3107 • CTX_sess_number
3109 my $rv = Net::SSLeay::CTX_sess_number($ctx);
3111 # $ctx - value corresponding to openssl's SSL_CTX structure
3112 #
3113 # returns: current number of sessions in the internal session cache
3114 Check openssl doc
3116 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3117 • CTX_sess_set_cache_size
3119 Sets the size of the internal session cache of context $ctx to
3121 $size.
3122 Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
3124 # $ctx - value corresponding to openssl's SSL_CTX structure
3125 # $size - cache size (0 = unlimited)
3126 #
3127 # returns: previously valid size
3128 Check openssl doc
3130 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3131 • CTX_sess_timeouts
3133 Returns the number of sessions proposed by clients and either found
3135 in the internal or external session cache in server mode, but that
3136 were invalid due to timeout. These sessions are not included in the
3137 SSL_CTX_sess_hits count.
3138 my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
3140 # $ctx - value corresponding to openssl's SSL_CTX structure
3141 #
3142 # returns: number of sessions
3143 Check openssl doc
3145 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3146 • CTX_sess_set_new_cb
3148 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3150 Sets the callback function, which is automatically called whenever
3152 a new session was negotiated.
3153 Net::SSLeay::CTX_sess_set_new_cb($ctx, $func);
3155 # $ctx - value corresponding to openssl's SSL_CTX structure
3156 # $func - perl reference to callback function
3157 #
3158 # returns: no return value
3159 Check openssl doc
3161 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html>
3162 • CTX_sess_set_remove_cb
3164 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3166 Sets the callback function, which is automatically called whenever
3168 a session is removed by the SSL engine.
3169 Net::SSLeay::CTX_sess_set_remove_cb($ctx, $func);
3171 # $ctx - value corresponding to openssl's SSL_CTX structure
3172 # $func - perl reference to callback function
3173 #
3174 # returns: no return value
3175 Check openssl doc
3177 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_remove_cb.html>
3178 • CTX_sessions
3180 Returns a pointer to the lhash databases containing the internal
3182 session cache for ctx.
3183 my $rv = Net::SSLeay::CTX_sessions($ctx);
3185 # $ctx - value corresponding to openssl's SSL_CTX structure
3186 #
3187 # returns: value corresponding to openssl's LHASH structure (0 on failure)
3188 Check openssl doc
3190 <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
3191 • CTX_set1_param
3193 COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
3195 Applies X509 verification parameters $vpm on $ctx
3197 my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
3199 # $ctx - value corresponding to openssl's SSL_CTX structure
3200 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
3201 #
3202 # returns: 1 on success, 0 on failure
3203 Check openssl doc
3205 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3206 • CTX_set_cert_store
3208 Sets/replaces the certificate verification storage of $ctx to/with
3210 $store.
3211 Net::SSLeay::CTX_set_cert_store($ctx, $store);
3213 # $ctx - value corresponding to openssl's SSL_CTX structure
3214 # $store - value corresponding to openssl's X509_STORE structure
3215 #
3216 # returns: no return value
3217 Check openssl doc
3219 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
3220 • CTX_set_cert_verify_callback
3222 Sets the verification callback function for $ctx. SSL objects that
3224 are created from $ctx inherit the setting valid at the time when
3225 Net::SSLeay::new($ctx) is called.
3226 Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
3228 # $ctx - value corresponding to openssl's SSL_CTX structure
3229 # $func - perl reference to callback function
3230 # $data - [optional] data that will be passed to callback function when invoked
3231 #
3232 # returns: no return value
3233 Check openssl doc
3235 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
3236 • CTX_set_cipher_list
3238 Sets the list of available ciphers for $ctx using the control
3240 string $str. The list of ciphers is inherited by all ssl objects
3241 created from $ctx.
3242 my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
3244 # $s - value corresponding to openssl's SSL_CTX structure
3245 # $str - (string) cipher list e.g. '3DES:+RSA'
3246 #
3247 # returns: 1 if any cipher could be selected and 0 on complete failure
3248 The format of $str is described in
3250 <https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html>
3251 Check openssl doc
3253 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html>
3254 • CTX_set_ciphersuites
3256 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3258 requires at least OpenSSL 1.1.1, not in LibreSSL
3259 Configure the available TLSv1.3 ciphersuites.
3261 my $rv = Net::SSLeay::CTX_set_ciphersuites($ctx, $str);
3263 # $ctx - value corresponding to openssl's SSL_CTX structure
3264 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
3265 #
3266 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
3267 Check openssl doc
3269 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html>
3270 • CTX_set_client_CA_list
3272 Sets the list of CAs sent to the client when requesting a client
3274 certificate for $ctx.
3275 Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
3277 # $ctx - value corresponding to openssl's SSL_CTX structure
3278 # $list - value corresponding to openssl's X509_NAME_STACK structure
3279 #
3280 # returns: no return value
3281 Check openssl doc
3283 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3284 • CTX_set_default_passwd_cb
3286 Sets the default password callback called when loading/storing a
3288 PEM certificate with encryption.
3289 Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
3291 # $ctx - value corresponding to openssl's SSL_CTX structure
3292 # $func - perl reference to callback function
3293 #
3294 # returns: no return value
3295 Check openssl doc
3297 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3298 • CTX_set_default_passwd_cb_userdata
3300 Sets a pointer to userdata which will be provided to the password
3302 callback on invocation.
3303 Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
3305 # $ctx - value corresponding to openssl's SSL_CTX structure
3306 # $userdata - data that will be passed to callback function when invoked
3307 #
3308 # returns: no return value
3309 Check openssl doc
3311 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3312 • CTX_set_default_verify_paths
3314 ??? (more info needed)
3316 my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
3318 # $ctx - value corresponding to openssl's SSL_CTX structure
3319 #
3320 # returns: 1 on success, 0 on failure
3321 • CTX_set_ex_data
3323 Is used to store application data at $data for $idx into the $ctx
3325 object.
3326 my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
3328 # $ssl - value corresponding to openssl's SSL_CTX structure
3329 # $idx - (integer) ???
3330 # $data - (pointer) ???
3331 #
3332 # returns: 1 on success, 0 on failure
3333 Check openssl doc
3335 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3336 • CTX_set_purpose
3338 my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
3340 # $s - value corresponding to openssl's SSL_CTX structure
3341 # $purpose - (integer) purpose identifier
3342 #
3343 # returns: 1 on success, 0 on failure
3344 #avainable purpose identifier
3346 1 - X509_PURPOSE_SSL_CLIENT
3347 2 - X509_PURPOSE_SSL_SERVER
3348 3 - X509_PURPOSE_NS_SSL_SERVER
3349 4 - X509_PURPOSE_SMIME_SIGN
3350 5 - X509_PURPOSE_SMIME_ENCRYPT
3351 6 - X509_PURPOSE_CRL_SIGN
3352 7 - X509_PURPOSE_ANY
3353 8 - X509_PURPOSE_OCSP_HELPER
3354 9 - X509_PURPOSE_TIMESTAMP_SIGN
3355 #or use corresponding constants
3357 $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3358 ...
3359 $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3360 • CTX_set_quiet_shutdown
3362 Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
3364 created from $ctx inherit the mode valid at the time
3365 Net::SSLeay::new($ctx) is called.
3366 Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
3368 # $ctx - value corresponding to openssl's SSL_CTX structure
3369 # $mode - 0 or 1
3370 #
3371 # returns: no return value
3372 Check openssl doc
3374 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3375 • CTX_set_read_ahead
3377 my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
3379 # $ctx - value corresponding to openssl's SSL_CTX structure
3380 # $val - read_ahead value to be set
3381 #
3382 # returns: the original read_ahead value
3383 • CTX_set_session_id_context
3385 Sets the context $sid_ctx of length $sid_ctx_len within which a
3387 session can be reused for the $ctx object.
3388 my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
3390 # $ctx - value corresponding to openssl's SSL_CTX structure
3391 # $sid_ctx - data buffer
3392 # $sid_ctx_len - length of data in $sid_ctx
3393 #
3394 # returns: 1 on success, 0 on failure (the error is logged to the error stack)
3395 Check openssl doc
3397 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3398 • CTX_set_ssl_version
3400 Sets a new default TLS/SSL method for SSL objects newly created
3402 from this $ctx. SSL objects already created with
3403 Net::SSLeay::new($ctx) are not affected, except when
3404 Net::SSLeay:clear($ssl) is being called.
3405 my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
3407 # $ctx - value corresponding to openssl's SSL_CTX structure
3408 # $meth - value corresponding to openssl's SSL_METHOD structure
3409 #
3410 # returns: 1 on success, 0 on failure
3411 Check openssl doc
3413 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3414 • CTX_set_timeout
3416 Sets the timeout for newly created sessions for $ctx to $t. The
3418 timeout value $t must be given in seconds.
3419 my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
3421 # $ctx - value corresponding to openssl's SSL_CTX structure
3422 # $t - timeout in seconds
3423 #
3424 # returns: previously set timeout value
3425 Check openssl doc
3427 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3428 • CTX_set_tmp_dh
3430 Sets DH parameters to be used to be $dh. The key is inherited by
3432 all ssl objects created from $ctx.
3433 my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
3435 # $ctx - value corresponding to openssl's SSL_CTX structure
3436 # $dh - value corresponding to openssl's DH structure
3437 #
3438 # returns: 1 on success, 0 on failure
3439 Check openssl doc
3441 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3442 • CTX_set_tmp_dh_callback
3444 Sets the callback function for $ctx to be used when a DH parameters
3446 are required to $tmp_dh_callback.
3447 Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
3449 # $ctx - value corresponding to openssl's SSL_CTX structure
3450 # tmp_dh_callback - (function pointer) ???
3451 #
3452 # returns: no return value
3453 Check openssl doc
3455 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3456 • CTX_set_tmp_rsa
3458 Sets the temporary/ephemeral RSA key to be used to be $rsa.
3460 my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
3462 # $ctx - value corresponding to openssl's SSL_CTX structure
3463 # $rsa - value corresponding to openssl's RSA structure
3464 #
3465 # returns: 1 on success, 0 on failure
3466 Check openssl doc
3468 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3469 Not available with OpenSSL 1.1 and later.
3471 • CTX_set_tmp_rsa_callback
3473 Sets the callback function for ctx to be used when a
3475 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3476 ??? (does this function really work?)
3478 Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
3480 # $ctx - value corresponding to openssl's SSL_CTX structure
3481 # $tmp_rsa_callback - (function pointer) ???
3482 #
3483 # returns: no return value
3484 Check openssl doc
3486 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3487 Not available with OpenSSL 1.1 and later.
3489 • CTX_set_trust
3491 my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
3493 # $s - value corresponding to openssl's SSL_CTX structure
3494 # $trust - (integer) trust identifier
3495 #
3496 # returns: the original value
3497 #available trust identifiers
3499 1 - X509_TRUST_COMPAT
3500 2 - X509_TRUST_SSL_CLIENT
3501 3 - X509_TRUST_SSL_SERVER
3502 4 - X509_TRUST_EMAIL
3503 5 - X509_TRUST_OBJECT_SIGN
3504 6 - X509_TRUST_OCSP_SIGN
3505 7 - X509_TRUST_OCSP_REQUEST
3506 8 - X509_TRUST_TSA
3507 #or use corresponding constants
3509 $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3510 ...
3511 $trust = &Net::SSLeay::X509_TRUST_TSA;
3512 • CTX_set_verify_depth
3514 Sets the maximum depth for the certificate chain verification that
3516 shall be allowed for ctx.
3517 Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
3519 # $ctx - value corresponding to openssl's SSL_CTX structure
3520 # $depth - max. depth
3521 #
3522 # returns: no return value
3523 Check openssl doc
3525 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3526 • CTX_use_PKCS12_file
3528 Adds the certificate and private key from PKCS12 file $p12filename
3530 to $ctx.
3531 my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
3533 # $ctx - value corresponding to openssl's SSL_CTX structure
3534 # $p12filename - (string) filename
3535 # $password - (string) password to decrypt private key
3536 #
3537 # returns: 1 on success, 0 on failure
3538 • CTX_use_PrivateKey
3540 Adds the private key $pkey to $ctx.
3542 my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
3544 # $ctx - value corresponding to openssl's SSL_CTX structure
3545 # $pkey - value corresponding to openssl's EVP_PKEY structure
3546 #
3547 # returns: 1 on success, otherwise check out the error stack to find out the reason
3548 Check openssl doc
3550 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3551 • CTX_use_PrivateKey_file
3553 Adds the first private key found in $file to $ctx.
3555 my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
3557 # $ctx - value corresponding to openssl's SSL_CTX structure
3558 # $file - (string) file name
3559 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3560 #
3561 # returns: 1 on success, otherwise check out the error stack to find out the reason
3562 Check openssl doc
3564 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3565 • CTX_use_RSAPrivateKey
3567 Adds the RSA private key $rsa to $ctx.
3569 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
3571 # $ctx - value corresponding to openssl's SSL_CTX structure
3572 # $rsa - value corresponding to openssl's RSA structure
3573 #
3574 # returns: 1 on success, otherwise check out the error stack to find out the reason
3575 Check openssl doc
3577 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3578 • CTX_use_RSAPrivateKey_file
3580 Adds the first RSA private key found in $file to $ctx.
3582 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
3584 # $ctx - value corresponding to openssl's SSL_CTX structure
3585 # $file - (string) file name
3586 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3587 #
3588 # returns: 1 on success, otherwise check out the error stack to find out the reason
3589 • CTX_use_certificate
3591 Loads the certificate $x into $ctx
3593 my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
3595 # $ctx - value corresponding to openssl's SSL_CTX structure
3596 # $x - value corresponding to openssl's X509 structure
3597 #
3598 # returns: 1 on success, otherwise check out the error stack to find out the reason
3599 Check openssl doc
3601 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3602 • CTX_use_certificate_chain_file
3604 Loads a certificate chain from $file into $ctx. The certificates
3606 must be in PEM format and must be sorted starting with the
3607 subject's certificate (actual client or server certificate),
3608 followed by intermediate CA certificates if applicable, and ending
3609 at the highest level (root) CA.
3610 my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
3612 # $ctx - value corresponding to openssl's SSL_CTX structure
3613 # $file - (string) file name
3614 #
3615 # returns: 1 on success, otherwise check out the error stack to find out the reason
3616 Check openssl doc
3618 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3619 • CTX_use_certificate_file
3621 Loads the first certificate stored in $file into $ctx.
3623 my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
3625 # $ctx - value corresponding to openssl's SSL_CTX structure
3626 # $file - (string) file name
3627 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3628 #
3629 # returns: 1 on success, otherwise check out the error stack to find out the reason
3630 Check openssl doc
3632 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3633 • CTX_get_security_level
3635 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3637 requires at least OpenSSL 1.1.0, not in LibreSSL
3638 Returns the security level associated with $ctx.
3640 my $level = Net::SSLeay::CTX_get_security_level($ctx);
3642 # $ctx - value corresponding to openssl's SSL_CTX structure
3643 #
3644 # returns: (integer) current security level
3645 Check openssl doc
3647 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html>
3648 • CTX_set_security_level
3650 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3652 requires at least OpenSSL 1.1.0, not in LibreSSL
3653 Sets the security level associated with $ctx to $level.
3655 Net::SSLeay::CTX_set_security_level($ctx, $level);
3657 # $ssl - value corresponding to openssl's SSL_CTX structure
3658 # $level - new security level
3659 #
3660 # returns: no return value
3661 Check openssl doc
3663 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html>
3664 • CTX_set_num_tickets
3666 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3668 requires at least OpenSSL 1.1.1, not in LibreSSL
3669 Set number of TLSv1.3 session tickets that will be sent to a
3671 client.
3672 my $rv = Net::SSLeay::CTX_set_num_tickets($ctx, $number_of_tickets);
3674 # $ctx - value corresponding to openssl's SSL_CTX structure
3675 # $number_of_tickets - number of tickets to send
3676 #
3677 # returns: 1 on success, 0 on failure
3678 Set to zero if you do not no want to support a session resumption.
3680 Check openssl doc
3682 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html>
3683 • CTX_get_num_tickets
3685 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3687 requires at least OpenSSL 1.1.1, not in LibreSSL
3688 Get number of TLSv1.3 session tickets that will be sent to a
3690 client.
3691 my $number_of_tickets = Net::SSLeay::CTX_get_num_tickets($ctx);
3693 # $ctx - value corresponding to openssl's SSL_CTX structure
3694 #
3695 # returns: (integer) number of tickets to send
3696 Check openssl doc
3698 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_num_tickets.html>
3699 • CTX_set_keylog_callback
3701 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3703 requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3704 Set the TLS key logging callback.
3706 Net::SSLeay::CTX_set_keylog_callback($ctx, $cb);
3708 # $ctx - value corresponding to openssl's SSL_CTX structure
3709 # $cb - reference to a perl callback function
3710 #
3711 # returns: no return value
3712 The callback function will be called like this:
3714 keylog_cb_func($ssl, $line);
3716 # $ssl - value corresponding to OpenSSL's SSL object associated with the connection
3717 # $line - a string containing the key material in the format used by NSS for its SSLKEYLOGFILE debugging output
3718 Check openssl doc
3720 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_keylog_callback.html>
3721 • CTX_get_keylog_callback
3723 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3725 requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3726 Retrieve the previously set TLS key logging callback.
3728 my $cb = Net::SSLeay::CTX_get_keylog_callback($ctx);
3730 # $ctx - value corresponding to openssl's SSL_CTX structure
3731 #
3732 # returns: a reference to a perl callback function or undef if no callback is set
3733 Check openssl doc
3735 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_keylog_callback.html>
3736 Low level API: SSL_* related functions
3738 NOTE: Please note that the function described in this chapter have
3740 "SSL_" part stripped from their original openssl names.
3741 • new
3743 Creates a new SSL structure which is needed to hold the data for a
3745 TLS/SSL connection. The new structure inherits the settings of the
3746 underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3747 options, verification settings, timeout settings.
3748 my $rv = Net::SSLeay::new($ctx);
3750 # $ctx - value corresponding to openssl's SSL_CTX structure
3751 #
3752 # returns: value corresponding to openssl's SSL structure (0 on failure)
3753 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3755 • accept
3757 Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3759 communication channel must already have been set and assigned to
3760 the ssl by setting an underlying BIO.
3761 my $rv = Net::SSLeay::accept($ssl);
3763 # $ssl - value corresponding to openssl's SSL structure
3764 #
3765 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3766 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3768 • add_client_CA
3770 Adds the CA name extracted from cacert to the list of CAs sent to
3772 the client when requesting a client certificate for the chosen ssl,
3773 overriding the setting valid for ssl's SSL_CTX object.
3774 my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3776 # $ssl - value corresponding to openssl's SSL structure
3777 # $x - value corresponding to openssl's X509 structure
3778 #
3779 # returns: 1 on success, 0 on failure
3780 Check openssl doc
3782 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3783 • callback_ctrl
3785 ??? (more info needed)
3787 my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3789 # $ssl - value corresponding to openssl's SSL structure
3790 # $cmd - (integer) command id
3791 # $fp - (function pointer) ???
3792 #
3793 # returns: ???
3794 Check openssl doc
3796 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3797 • check_private_key
3799 Checks the consistency of a private key with the corresponding
3801 certificate loaded into $ssl
3802 my $rv = Net::SSLeay::check_private_key($ssl);
3804 # $ssl - value corresponding to openssl's SSL structure
3805 #
3806 # returns: 1 on success, otherwise check out the error stack to find out the reason
3807 Check openssl doc
3809 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3810 • clear
3812 Reset SSL object to allow another connection.
3814 Net::SSLeay::clear($ssl);
3816 # $ssl - value corresponding to openssl's SSL structure
3817 #
3818 # returns: no return value
3819 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3821 • connect
3823 Initiate the TLS/SSL handshake with an TLS/SSL server.
3825 my $rv = Net::SSLeay::connect($ssl);
3827 # $ssl - value corresponding to openssl's SSL structure
3828 #
3829 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3830 Check openssl doc
3832 <http://www.openssl.org/docs/ssl/SSL_connect.html>
3833 • copy_session_id
3835 Copies the session structure fro $from to $to (+ also the private
3837 key and certificate associated with $from).
3838 Net::SSLeay::copy_session_id($to, $from);
3840 # $to - value corresponding to openssl's SSL structure
3841 # $from - value corresponding to openssl's SSL structure
3842 #
3843 # returns: no return value
3844 • ctrl
3846 Internal handling function for SSL objects.
3848 BEWARE: openssl doc says: This function should never be called
3850 directly!
3851 my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3853 # $ssl - value corresponding to openssl's SSL structure
3854 # $cmd - (integer) command id
3855 # $larg - (integer) long ???
3856 # $parg - (string/pointer) ???
3857 #
3858 # returns: (long) result of given command ???
3859 For more details about valid $cmd values check "CTX_ctrl".
3861 Check openssl doc
3863 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3864 • do_handshake
3866 Will wait for a SSL/TLS handshake to take place. If the connection
3868 is in client mode, the handshake will be started. The handshake
3869 routines may have to be explicitly set in advance using either
3870 SSL_set_connect_state or SSL_set_accept_state(3).
3871 my $rv = Net::SSLeay::do_handshake($ssl);
3873 # $ssl - value corresponding to openssl's SSL structure
3874 #
3875 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3876 Check openssl doc
3878 <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3879 • dup
3881 Returns a duplicate of $ssl.
3883 my $rv = Net::SSLeay::dup($ssl);
3885 # $ssl - value corresponding to openssl's SSL structure
3886 #
3887 # returns: value corresponding to openssl's SSL structure (0 on failure)
3888 • free
3890 Free an allocated SSL structure.
3892 Net::SSLeay::free($ssl);
3894 # $ssl - value corresponding to openssl's SSL structure
3895 #
3896 # returns: no return value
3897 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3899 • get0_param
3901 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
3903 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
3904 Returns the current verification parameters.
3906 my $vpm = Net::SSLeay::get0_param($ssl);
3908 # $ssl - value corresponding to openssl's SSL structure
3909 #
3910 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
3911 Check openssl doc
3913 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3914 • get_SSL_CTX
3916 Returns a pointer to the SSL_CTX object, from which $ssl was
3918 created with Net::SSLeay::new.
3919 my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3921 # $ssl - value corresponding to openssl's SSL structure
3922 #
3923 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3924 Check openssl doc
3926 <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3927 • set_SSL_CTX
3929 COMPATIBILITY: requires at least OpenSSL 0.9.8f
3931 Sets the SSL_CTX the corresponds to an SSL session.
3933 my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3935 # $ssl - value corresponding to openssl's SSL structure
3936 # $ssl_ctx - Change the ssl object to the given ssl_ctx
3937 #
3938 # returns - the ssl_ctx
3939 • get_app_data
3941 Can be used to get application defined value/data.
3943 my $rv = Net::SSLeay::get_app_data($ssl);
3945 # $ssl - value corresponding to openssl's SSL structure
3946 #
3947 # returns: string/buffer/pointer ???
3948 • set_app_data
3950 Can be used to set some application defined value/data.
3952 my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3954 # $ssl - value corresponding to openssl's SSL structure
3955 # $arg - (string/buffer/pointer ???) data
3956 #
3957 # returns: ???
3958 • get_certificate
3960 Gets X509 certificate from an established SSL connection.
3962 my $rv = Net::SSLeay::get_certificate($ssl);
3964 # $ssl - value corresponding to openssl's SSL structure
3965 #
3966 # returns: value corresponding to openssl's X509 structure (0 on failure)
3967 • get_cipher
3969 Obtains the name of the currently used cipher.
3971 my $rv = Net::SSLeay::get_cipher($ssl);
3973 # $ssl - value corresponding to openssl's SSL structure
3974 #
3975 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3976 Check openssl doc
3978 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3979 • get_cipher_bits
3981 Obtain the number of secret/algorithm bits used.
3983 my $rv = Net::SSLeay::get_cipher_bits($ssl);
3985 # $ssl - value corresponding to openssl's SSL structure
3986 #
3987 # returns: number of secret bits used by current cipher
3988 Check openssl doc
3990 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3991 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3992 • get_ciphers
3994 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
3996 Returns a list of SSL_CIPHER structures available for $ssl sorted
3998 by preference
3999 my @ciphers = Net::SSLeay::get_ciphers($ssl);
4001 # $ssl - value corresponding to openssl's SSL structure
4002 #
4003 # returns: (list) SSL_CIPHER structures or nothing when $ssl is undefined or no ciphers are available
4004 Example:
4006 my @ciphers = Net::SSLeay::get_ciphers($ssl);
4008 foreach my $c (@ciphers) {
4009 print Net::SSLeay::CIPHER_get_name($c) . "\n";
4010 }
4011 Check openssl doc
4013 <https://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
4014 • get_cipher_list
4016 Returns the name (string) of the SSL_CIPHER listed for $ssl with
4018 priority $n.
4019 my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
4021 # $ssl - value corresponding to openssl's SSL structure
4022 # $n - (integer) priority
4023 #
4024 # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or undef in case of error
4025 Call Net::SSLeay::get_cipher_list with priority starting from 0 to
4027 obtain the sorted list of available ciphers, until undef is
4028 returned:
4029 my $priority = 0;
4031 while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
4032 print "cipher[$priority] = $c\n";
4033 $priority++;
4034 }
4035 Check openssl doc
4037 <https://www.openssl.org/docs/ssl/SSL_get_cipher_list.html>
4038 • get_client_CA_list
4040 Returns the list of client CAs explicitly set for $ssl using
4042 "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
4043 "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
4044 In client mode, returns the list of client CAs sent from the
4046 server, if any.
4047 my $rv = Net::SSLeay::get_client_CA_list($ssl);
4049 # $ssl - value corresponding to openssl's SSL structure
4050 #
4051 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4052 Check openssl doc
4054 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
4055 • get_current_cipher
4057 Returns the cipher actually used.
4059 my $rv = Net::SSLeay::get_current_cipher($ssl);
4061 # $ssl - value corresponding to openssl's SSL structure
4062 #
4063 # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
4064 Check openssl doc
4066 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
4067 • get_default_timeout
4069 Returns the default timeout value assigned to SSL_SESSION objects
4071 negotiated for the protocol valid for $ssl.
4072 my $rv = Net::SSLeay::get_default_timeout($ssl);
4074 # $ssl - value corresponding to openssl's SSL structure
4075 #
4076 # returns: (long) timeout in seconds
4077 Check openssl doc
4079 <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
4080 • get_error
4082 Returns a result code for a preceding call to "connect", "accept",
4084 "do_handshake", "read", "peek" or "write" on $ssl.
4085 my $rv = Net::SSLeay::get_error($ssl, $ret);
4087 # $ssl - value corresponding to openssl's SSL structure
4088 # $ret - return value of preceding TLS/SSL I/O operation
4089 #
4090 # returns: result code, which is one of the following values:
4091 # 0 - SSL_ERROR_NONE
4092 # 1 - SSL_ERROR_SSL
4093 # 2 - SSL_ERROR_WANT_READ
4094 # 3 - SSL_ERROR_WANT_WRITE
4095 # 4 - SSL_ERROR_WANT_X509_LOOKUP
4096 # 5 - SSL_ERROR_SYSCALL
4097 # 6 - SSL_ERROR_ZERO_RETURN
4098 # 7 - SSL_ERROR_WANT_CONNECT
4099 # 8 - SSL_ERROR_WANT_ACCEPT
4100 Check openssl doc
4102 <http://www.openssl.org/docs/ssl/SSL_get_error.html>
4103 • get_ex_data
4105 Is used to retrieve the information for $idx from $ssl.
4107 my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
4109 # $ssl - value corresponding to openssl's SSL structure
4110 # $idx - (integer) index for application specific data
4111 #
4112 # returns: pointer to ???
4113 Check openssl doc
4115 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4116 • set_ex_data
4118 Is used to store application data at $data for $idx into the $ssl
4120 object.
4121 my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
4123 # $ssl - value corresponding to openssl's SSL structure
4124 # $idx - (integer) ???
4125 # $data - (pointer) ???
4126 #
4127 # returns: 1 on success, 0 on failure
4128 Check openssl doc
4130 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4131 • get_ex_new_index
4133 Is used to register a new index for application specific data.
4135 my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
4137 # $argl - (long) ???
4138 # $argp - (pointer) ???
4139 # $new_func - function pointer ??? (CRYPTO_EX_new *)
4140 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
4141 # $free_func - function pointer ??? (CRYPTO_EX_free *)
4142 #
4143 # returns: (integer) ???
4144 Check openssl doc
4146 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4147 • get_fd
4149 Returns the file descriptor which is linked to $ssl.
4151 my $rv = Net::SSLeay::get_fd($ssl);
4153 # $ssl - value corresponding to openssl's SSL structure
4154 #
4155 # returns: file descriptor (>=0) or -1 on failure
4156 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
4158 • get_finished
4160 Obtains the latest 'Finished' message sent to the peer. Return
4162 value is zero if there's been no Finished message yet. Default
4163 count is 2*EVP_MAX_MD_SIZE that is long enough for all possible
4164 Finish messages. If you supply a non-default count, the resulting
4165 return value may be longer than returned buf's length.
4166 my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
4168 # $ssl - value corresponding to openssl's SSL structure
4169 # $buf - buffer where the returned data will be stored
4170 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
4171 #
4172 # returns: length of latest Finished message
4173 • get_peer_finished
4175 Obtains the latest 'Finished' message expected from the peer.
4177 Parameters and return value are similar to get_finished().
4178 my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
4180 # $ssl - value corresponding to openssl's SSL structure
4181 # $buf - buffer where the returned data will be stored
4182 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
4183 #
4184 # returns: length of latest Finished message
4185 • get_keyblock_size
4187 Gets the length of the TLS keyblock.
4189 NOTE: Does not exactly correspond to any low level API function.
4191 my $rv = Net::SSLeay::get_keyblock_size($ssl);
4193 # $ssl - value corresponding to openssl's SSL structure
4194 #
4195 # returns: keyblock size, -1 on error
4196 • get_mode
4198 Returns the mode (bitmask) set for $ssl.
4200 my $rv = Net::SSLeay::get_mode($ssl);
4202 # $ssl - value corresponding to openssl's SSL structure
4203 #
4204 # returns: mode (bitmask)
4205 To decode the return value (bitmask) see documentation for
4207 "CTX_get_mode".
4208 Check openssl doc
4210 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4211 • set_mode
4213 Adds the mode set via bitmask in $mode to $ssl. Options already set
4215 before are not cleared.
4216 my $rv = Net::SSLeay::set_mode($ssl, $mode);
4218 # $ssl - value corresponding to openssl's SSL structure
4219 # $mode - mode (bitmask)
4220 #
4221 # returns: the new mode bitmask after adding $mode
4222 For $mode bitmask details see "CTX_get_mode".
4224 Check openssl doc
4226 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4227 • get_options
4229 Returns the options (bitmask) set for $ssl.
4231 my $rv = Net::SSLeay::get_options($ssl);
4233 # $ssl - value corresponding to openssl's SSL structure
4234 #
4235 # returns: options (bitmask)
4236 To decode the return value (bitmask) see documentation for
4238 "CTX_get_options".
4239 Check openssl doc
4241 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4242 • set_options
4244 Adds the options set via bitmask in $options to $ssl. Options
4246 already set before are not cleared!
4247 Net::SSLeay::set_options($ssl, $options);
4249 # $ssl - value corresponding to openssl's SSL structure
4250 # $options - options (bitmask)
4251 #
4252 # returns: the new options bitmask after adding $options
4253 For $options bitmask details see "CTX_get_options".
4255 Check openssl doc
4257 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4258 • get_peer_certificate
4260 Get the X509 certificate of the peer.
4262 my $rv = Net::SSLeay::get_peer_certificate($ssl);
4264 # $ssl - value corresponding to openssl's SSL structure
4265 #
4266 # returns: value corresponding to openssl's X509 structure (0 on failure)
4267 Check openssl doc
4269 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4270 • get_peer_cert_chain
4272 Get the certificate chain of the peer as an array of X509
4274 structures.
4275 my @rv = Net::SSLeay::get_peer_cert_chain($ssl);
4277 # $ssl - value corresponding to openssl's SSL structure
4278 #
4279 # returns: list of X509 structures
4280 Check openssl doc
4282 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4283 • get_quiet_shutdown
4285 Returns the 'quiet shutdown' setting of ssl.
4287 my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
4289 # $ssl - value corresponding to openssl's SSL structure
4290 #
4291 # returns: (integer) current 'quiet shutdown' value
4292 Check openssl doc
4294 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4295 • get_rbio
4297 Get 'read' BIO linked to an SSL object $ssl.
4299 my $rv = Net::SSLeay::get_rbio($ssl);
4301 # $ssl - value corresponding to openssl's SSL structure
4302 #
4303 # returns: value corresponding to openssl's BIO structure (0 on failure)
4304 Check openssl doc
4306 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4307 • get_read_ahead
4309 my $rv = Net::SSLeay::get_read_ahead($ssl);
4311 # $ssl - value corresponding to openssl's SSL structure
4312 #
4313 # returns: (integer) read_ahead value
4314 • set_read_ahead
4316 Net::SSLeay::set_read_ahead($ssl, $val);
4318 # $ssl - value corresponding to openssl's SSL structure
4319 # $val - read_ahead value to be set
4320 #
4321 # returns: the original read_ahead value
4322 • get_security_level
4324 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4326 requires at least OpenSSL 1.1.0, not in LibreSSL
4327 Returns the security level associated with $ssl.
4329 my $level = Net::SSLeay::get_security_level($ssl);
4331 # $ssl - value corresponding to openssl's SSL structure
4332 #
4333 # returns: (integer) current security level
4334 Check openssl doc
4336 <https://www.openssl.org/docs/manmaster/man3/SSL_get_security_level.html>
4337 • set_security_level
4339 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4341 requires at least OpenSSL 1.1.0, not in LibreSSL
4342 Sets the security level associated with $ssl to $level.
4344 Net::SSLeay::set_security_level($ssl, $level);
4346 # $ssl - value corresponding to openssl's SSL structure
4347 # $level - new security level
4348 #
4349 # returns: no return value
4350 Check openssl doc
4352 <https://www.openssl.org/docs/manmaster/man3/SSL_set_security_level.html>
4353 • set_num_tickets
4355 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4357 requires at least OpenSSL 1.1.1, not in LibreSSL
4358 Set number of TLSv1.3 session tickets that will be sent to a
4360 client.
4361 my $rv = Net::SSLeay::set_num_tickets($ssl, $number_of_tickets);
4363 # $ssl - value corresponding to openssl's SSL structure
4364 # $number_of_tickets - number of tickets to send
4365 #
4366 # returns: 1 on success, 0 on failure
4367 Set to zero if you do not no want to support a session resumption.
4369 Check openssl doc
4371 <https://www.openssl.org/docs/manmaster/man3/SSL_set_num_tickets.html>
4372 • get_num_tickets
4374 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4376 requires at least OpenSSL 1.1.1, not in LibreSSL
4377 Get number of TLSv1.3 session tickets that will be sent to a
4379 client.
4380 my $number_of_tickets = Net::SSLeay::get_num_tickets($ctx);
4382 # $ctx - value corresponding to openssl's SSL structure
4383 #
4384 # returns: number of tickets to send
4385 Check openssl doc
4387 <https://www.openssl.org/docs/manmaster/man3/SSL_get_num_tickets.html>
4388 • get_server_random
4390 Returns internal SSLv3 server_random value.
4392 Net::SSLeay::get_server_random($ssl);
4394 # $ssl - value corresponding to openssl's SSL structure
4395 #
4396 # returns: server_random value (binary data)
4397 • get_client_random
4399 NOTE: Does not exactly correspond to any low level API function
4401 Returns internal SSLv3 client_random value.
4403 Net::SSLeay::get_client_random($ssl);
4405 # $ssl - value corresponding to openssl's SSL structure
4406 #
4407 # returns: client_random value (binary data)
4408 • export_keying_material
4410 Returns keying material based on the string $label and optional
4412 $context. Note that with TLSv1.2 and lower, empty context (empty
4413 string) and undefined context (no value or 'undef') will return
4414 different values.
4415 my $out = Net::SSLeay::export_keying_material($ssl, $olen, $label, $context);
4417 # $ssl - value corresponding to openssl's SSL structure
4418 # $olen - number of bytes to return
4419 # $label - application specific label
4420 # $context - [optional] context - default is undef for no context
4421 #
4422 # returns: keying material (binary data) or undef on error
4423 Check openssl doc
4425 <https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html>
4426 • get_session
4428 Retrieve TLS/SSL session data used in $ssl. The reference count of
4430 the SSL_SESSION is NOT incremented.
4431 my $rv = Net::SSLeay::get_session($ssl);
4433 # $ssl - value corresponding to openssl's SSL structure
4434 #
4435 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4436 Check openssl doc
4438 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4439 • SSL_get0_session
4441 The alias for "get_session" (note that the name is
4443 "SSL_get0_session" NOT "get0_session").
4444 my $rv = Net::SSLeay::SSL_get0_session();
4446 • get1_session
4448 Returns a pointer to the SSL_SESSION actually used in $ssl. The
4450 reference count of the SSL_SESSION is incremented by 1.
4451 my $rv = Net::SSLeay::get1_session($ssl);
4453 # $ssl - value corresponding to openssl's SSL structure
4454 #
4455 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4456 Check openssl doc
4458 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4459 • get_shared_ciphers
4461 Returns string with a list (colon ':' separated) of ciphers shared
4463 between client and server within SSL session $ssl.
4464 my $rv = Net::SSLeay::get_shared_ciphers()
4466 #
4467 # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
4468 • get_shutdown
4470 Returns the shutdown mode of $ssl.
4472 my $rv = Net::SSLeay::get_shutdown($ssl);
4474 # $ssl - value corresponding to openssl's SSL structure
4475 #
4476 # returns: shutdown mode (bitmask) of ssl
4477 #to decode the return value (bitmask) use:
4479 0 - No shutdown setting, yet
4480 1 - SSL_SENT_SHUTDOWN
4481 2 - SSL_RECEIVED_SHUTDOWN
4482 Check openssl doc
4484 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4485 • get_ssl_method
4487 Returns a function pointer to the TLS/SSL method set in $ssl.
4489 my $rv = Net::SSLeay::get_ssl_method($ssl);
4491 # $ssl - value corresponding to openssl's SSL structure
4492 #
4493 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
4494 Check openssl doc
4496 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4497 • in_init, in_before, is_init_finished, in_connect_init,
4499 in_accept_init
4500 COMPATIBILITY: not available in Net-SSLeay-1.85 and before.
4502 Retrieve information about the handshake state machine. All
4504 functions take $ssl as the only argument and return 0 or 1. These
4505 functions are recommended over get_state() and state().
4506 my $rv = Net::SSLeay::is_init_finished($ssl);
4508 # $ssl - value corresponding to openssl's SSL structure
4509 #
4510 # returns: All functions return 1 or 0
4511 Check openssl doc https://www.openssl.org/docs/ssl/SSL_in_init.html
4513 <http://www.openssl.org/docs/ssl/SSL_in_init.html>
4514 • get_state
4516 COMPATIBILITY: OpenSSL 1.1.0 and later use different constants
4518 which are not made available. Use is_init_finished() and related
4519 functions instead.
4520 Returns the SSL connection state.
4522 my $rv = Net::SSLeay::get_state($ssl);
4524 # $ssl - value corresponding to openssl's SSL structure
4525 #
4526 # returns: (integer) state value
4527 # to decode the returned state check:
4528 # SSL_ST_* constants in openssl/ssl.h
4529 # SSL2_ST_* constants in openssl/ssl2.h
4530 # SSL23_ST_* constants in openssl/ssl23.h
4531 # SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
4532 • state
4534 Exactly the same as "get_state".
4536 my $rv = Net::SSLeay::state($ssl);
4538 • set_state
4540 Sets the SSL connection state.
4542 Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4544 Not available with OpenSSL 1.1 and later.
4546 • get_verify_depth
4548 Returns the verification depth limit currently set in $ssl.
4550 my $rv = Net::SSLeay::get_verify_depth($ssl);
4552 # $ssl - value corresponding to openssl's SSL structure
4553 #
4554 # returns: current depth or -1 if no limit has been explicitly set
4555 Check openssl doc
4557 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4558 • set_verify_depth
4560 Sets the maximum depth for the certificate chain verification that
4562 shall be allowed for $ssl.
4563 Net::SSLeay::set_verify_depth($ssl, $depth);
4565 # $ssl - value corresponding to openssl's SSL structure
4566 # $depth - (integer) depth
4567 #
4568 # returns: no return value
4569 Check openssl doc
4571 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4572 • get_verify_mode
4574 Returns the verification mode (bitmask) currently set in $ssl.
4576 my $rv = Net::SSLeay::get_verify_mode($ssl);
4578 # $ssl - value corresponding to openssl's SSL structure
4579 #
4580 # returns: mode (bitmask)
4581 To decode the return value (bitmask) see documentation for
4583 "CTX_get_verify_mode".
4584 Check openssl doc
4586 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4587 • set_verify
4589 Sets the verification flags for $ssl to be $mode and specifies the
4591 $verify_callback function to be used.
4592 Net::SSLeay::set_verify($ssl, $mode, $callback);
4594 # $ssl - value corresponding to openssl's SSL structure
4595 # $mode - mode (bitmask)
4596 # $callback - [optional] reference to perl callback function
4597 #
4598 # returns: no return value
4599 For $mode bitmask details see "CTX_get_verify_mode".
4601 Check openssl doc
4603 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4604 • set_post_handshake_auth
4606 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4608 requires at least OpenSSL 1.1.1, not in LibreSSL
4609 Enable the Post-Handshake Authentication extension to be added to
4611 the ClientHello such that post-handshake authentication can be
4612 requested by the server.
4613 Net::SSLeay::set_posthandshake_auth($ssl, $val);
4615 # $ssl - value corresponding to openssl's SSL structure
4616 # $val - 0 then the extension is not sent, otherwise it is
4617 #
4618 # returns: no return value
4619 Check openssl doc
4621 https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth
4622 <https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth.html>
4623 • verify_client_post_handshake
4625 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4627 requires at least OpenSSL 1.1.1, not in LibreSSL
4628 verify_client_post_handshake causes a CertificateRequest message to
4630 be sent by a server on the given ssl connection.
4631 my $rv = Net::SSLeay::verify_client_post_handshake($ssl);
4633 # $ssl - value corresponding to openssl's SSL structure
4634 #
4635 # returns: 1 if the request succeeded, and 0 if the request failed. The error stack can be examined to determine the failure reason.
4636 Check openssl doc
4638 <https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html>
4639 • get_verify_result
4641 Returns the result of the verification of the X509 certificate
4643 presented by the peer, if any.
4644 my $rv = Net::SSLeay::get_verify_result($ssl);
4646 # $ssl - value corresponding to openssl's SSL structure
4647 #
4648 # returns: (integer)
4649 # 0 - X509_V_OK: ok
4650 # 2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
4651 # 3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
4652 # 4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
4653 # 5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
4654 # 6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
4655 # 7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
4656 # 8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
4657 # 9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
4658 # 10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
4659 # 11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
4660 # 12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
4661 # 13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
4662 # 14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
4663 # 15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
4664 # 16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
4665 # 17 - X509_V_ERR_OUT_OF_MEM: out of memory
4666 # 18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
4667 # 19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
4668 # 20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
4669 # 21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
4670 # 22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
4671 # 23 - X509_V_ERR_CERT_REVOKED: certificate revoked
4672 # 24 - X509_V_ERR_INVALID_CA: invalid CA certificate
4673 # 25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
4674 # 26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
4675 # 27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
4676 # 28 - X509_V_ERR_CERT_REJECTED: certificate rejected
4677 # 29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
4678 # 30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
4679 # 31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
4680 # 32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
4681 # 50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
4682 Check openssl doc
4684 <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4685 • set_verify_result
4687 Override result of peer certificate verification.
4689 Net::SSLeay::set_verify_result($ssl, $v);
4691 # $ssl - value corresponding to openssl's SSL structure
4692 # $v - (integer) result value
4693 #
4694 # returns: no return value
4695 For more info about valid return values see "get_verify_result"
4697 Check openssl doc
4699 <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4700 • get_wbio
4702 Get 'write' BIO linked to an SSL object $ssl.
4704 my $rv = Net::SSLeay::get_wbio($ssl);
4706 # $ssl - value corresponding to openssl's SSL structure
4707 #
4708 # returns: value corresponding to openssl's BIO structure (0 on failure)
4709 Check openssl doc
4711 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4712 • load_client_CA_file
4714 Load X509 certificates from file (PEM formatted).
4716 my $rv = Net::SSLeay::load_client_CA_file($file);
4718 # $file - (string) file name
4719 #
4720 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4721 Check openssl doc
4723 <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4724 • clear_num_renegotiations
4726 Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4728 my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4730 # $ssl - value corresponding to openssl's SSL structure
4731 #
4732 # returns: command result
4733 • need_tmp_RSA
4735 Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4737 my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4739 # $ssl - value corresponding to openssl's SSL structure
4740 #
4741 # returns: command result
4742 Not available with OpenSSL 1.1 and later.
4744 • num_renegotiations
4746 Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4748 my $rv = Net::SSLeay::num_renegotiations($ssl);
4750 # $ssl - value corresponding to openssl's SSL structure
4751 #
4752 # returns: command result
4753 • total_renegotiations
4755 Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4757 my $rv = Net::SSLeay::total_renegotiations($ssl);
4759 # $ssl - value corresponding to openssl's SSL structure
4760 #
4761 # returns: command result
4762 • peek
4764 Copies $max bytes from the specified $ssl into the returned value.
4766 In contrast to the Net::SSLeay::read() function, the data in the
4767 SSL buffer is unmodified after the SSL_peek() operation.
4768 Net::SSLeay::peek($ssl, $max);
4770 # $ssl - value corresponding to openssl's SSL structure
4771 # $max - [optional] max bytes to peek (integer) - default is 32768
4772 #
4773 # in scalar context: data read from the TLS/SSL connection, undef on error
4774 # in list context: two-item array consisting of data read (undef on error),
4775 # and return code from SSL_peek().
4776 • peek_ex
4778 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4780 requires at least OpenSSL 1.1.1, not in LibreSSL
4781 Copies $max bytes from the specified $ssl into the returned value.
4783 In contrast to the Net::SSLeay::read_ex() function, the data in the
4784 SSL buffer is unmodified after the SSL_peek_ex() operation.
4785 my($got, $rv) = Net::SSLeay::peek_ex($ssl, $max);
4787 # $ssl - value corresponding to openssl's SSL structure
4788 # $max - [optional] max bytes to peek (integer) - default is 32768
4789 #
4790 # returns a list: two-item list consisting of data read (undef on error),
4791 # and return code from SSL_peek_ex().
4792 Check openssl doc
4794 <https://www.openssl.org/docs/manmaster/man3/SSL_peek_ex.html>
4795 • pending
4797 Obtain number of readable bytes buffered in $ssl object.
4799 my $rv = Net::SSLeay::pending($ssl);
4801 # $ssl - value corresponding to openssl's SSL structure
4802 #
4803 # returns: the number of bytes pending
4804 Check openssl doc
4806 <http://www.openssl.org/docs/ssl/SSL_pending.html>
4807 • has_pending
4809 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4811 requires at least OpenSSL 1.1.0, not in LibreSSL
4812 Returns 1 if $ssl has buffered data (whether processed or
4814 unprocessed) and 0 otherwise.
4815 my $rv = Net::SSLeay::has_pending($ssl);
4817 # $ssl - value corresponding to openssl's SSL structure
4818 #
4819 # returns: (integer) 1 or 0
4820 Check openssl doc
4822 <https://www.openssl.org/docs/manmaster/man3/SSL_has_pending.html>
4823 • read
4825 Tries to read $max bytes from the specified $ssl.
4827 my $got = Net::SSLeay::read($ssl, $max);
4829 my($got, $rv) = Net::SSLeay::read($ssl, $max);
4830 # $ssl - value corresponding to openssl's SSL structure
4831 # $max - [optional] max bytes to read (integer) - default is 32768
4832 #
4833 # returns:
4834 # in scalar context: data read from the TLS/SSL connection, undef on error
4835 # in list context: two-item array consisting of data read (undef on error),
4836 # and return code from SSL_read().
4837 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4839 • read_ex
4841 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4843 requires at least OpenSSL 1.1.1, not in LibreSSL
4844 Tries to read $max bytes from the specified $ssl.
4846 my($got, $rv) = Net::SSLeay::read_ex($ssl, $max);
4848 # $ssl - value corresponding to openssl's SSL structure
4849 # $max - [optional] max bytes to read (integer) - default is 32768
4850 #
4851 # returns a list: two-item list consisting of data read (undef on error),
4852 # and return code from SSL_read_ex().
4853 Check openssl doc
4855 <https://www.openssl.org/docs/manmaster/man3/SSL_read_ex.html>
4856 • renegotiate
4858 Turn on flags for renegotiation so that renegotiation will happen
4860 my $rv = Net::SSLeay::renegotiate($ssl);
4862 # $ssl - value corresponding to openssl's SSL structure
4863 #
4864 # returns: 1 on success, 0 on failure
4865 • rstate_string
4867 Returns a 2 letter string indicating the current read state of the
4869 SSL object $ssl.
4870 my $rv = Net::SSLeay::rstate_string($ssl);
4872 # $ssl - value corresponding to openssl's SSL structure
4873 #
4874 # returns: 2-letter string
4875 Check openssl doc
4877 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4878 • rstate_string_long
4880 Returns a string indicating the current read state of the SSL
4882 object ssl.
4883 my $rv = Net::SSLeay::rstate_string_long($ssl);
4885 # $ssl - value corresponding to openssl's SSL structure
4886 #
4887 # returns: string with current state
4888 Check openssl doc
4890 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4891 • session_reused
4893 Query whether a reused session was negotiated during handshake.
4895 my $rv = Net::SSLeay::session_reused($ssl);
4897 # $ssl - value corresponding to openssl's SSL structure
4898 #
4899 # returns: 0 - new session was negotiated; 1 - session was reused.
4900 Check openssl doc
4902 <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4903 • set1_param
4905 COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
4907 Applies X509 verification parameters $vpm on $ssl
4909 my $rv = Net::SSLeay::set1_param($ssl, $vpm);
4911 # $ssl - value corresponding to openssl's SSL structure
4912 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
4913 #
4914 # returns: 1 on success, 0 on failure
4915 • set_accept_state
4917 Sets $ssl to work in server mode.
4919 Net::SSLeay::set_accept_state($ssl);
4921 # $ssl - value corresponding to openssl's SSL structure
4922 #
4923 # returns: no return value
4924 Check openssl doc
4926 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4927 • set_bio
4929 Connects the BIOs $rbio and $wbio for the read and write operations
4931 of the TLS/SSL (encrypted) side of $ssl.
4932 Net::SSLeay::set_bio($ssl, $rbio, $wbio);
4934 # $ssl - value corresponding to openssl's SSL structure
4935 # $rbio - value corresponding to openssl's BIO structure
4936 # $wbio - value corresponding to openssl's BIO structure
4937 #
4938 # returns: no return value
4939 Check openssl doc
4941 <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4942 • set_cipher_list
4944 Sets the list of ciphers only for ssl.
4946 my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
4948 # $ssl - value corresponding to openssl's SSL structure
4949 # $str - (string) cipher list e.g. '3DES:+RSA'
4950 #
4951 # returns: 1 if any cipher could be selected and 0 on complete failure
4952 Check openssl doc
4954 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4955 • set_ciphersuites
4957 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4959 requires at least OpenSSL 1.1.1, not in LibreSSL
4960 Configure the available TLSv1.3 ciphersuites.
4962 my $rv = Net::SSLeay::set_ciphersuites($ssl, $str);
4964 # $ssl - value corresponding to openssl's SSL structure
4965 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
4966 #
4967 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
4968 Check openssl doc
4970 <https://www.openssl.org/docs/manmaster/man3/SSL_set_ciphersuites.html>
4971 • set_client_CA_list
4973 Sets the list of CAs sent to the client when requesting a client
4975 certificate for the chosen $ssl, overriding the setting valid for
4976 $ssl's SSL_CTX object.
4977 my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
4979 # $ssl - value corresponding to openssl's SSL structure
4980 # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
4981 #
4982 # returns: no return value
4983 Check openssl doc
4985 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4986 • set_connect_state
4988 Sets $ssl to work in client mode.
4990 Net::SSLeay::set_connect_state($ssl);
4992 # $ssl - value corresponding to openssl's SSL structure
4993 #
4994 # returns: no return value
4995 Check openssl doc
4997 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4998 • set_fd
5000 Sets the file descriptor $fd as the input/output facility for the
5002 TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
5003 file descriptor of a network connection.
5004 my $rv = Net::SSLeay::set_fd($ssl, $fd);
5006 # $ssl - value corresponding to openssl's SSL structure
5007 # $fd - (integer) file handle (got via perl's fileno)
5008 #
5009 # returns: 1 on success, 0 on failure
5010 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5012 • set_psk_client_callback
5014 Sets the psk client callback.
5016 Net::SSLeay::set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
5018 # $ssl - value corresponding to openssl's SSL structure
5019 # $hint - PSK identity hint send by the server
5020 # $identity - PSK identity
5021 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
5022 #
5023 # returns: no return value
5024 Check openssl doc
5026 <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
5027 • set_rfd
5029 Sets the file descriptor $fd as the input (read) facility for the
5031 TLS/SSL (encrypted) side of $ssl.
5032 my $rv = Net::SSLeay::set_rfd($ssl, $fd);
5034 # $ssl - value corresponding to openssl's SSL structure
5035 # $fd - (integer) file handle (got via perl's fileno)
5036 #
5037 # returns: 1 on success, 0 on failure
5038 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5040 • set_wfd
5042 my $rv = Net::SSLeay::set_wfd($ssl, $fd);
5044 # $ssl - value corresponding to openssl's SSL structure
5045 # $fd - (integer) file handle (got via perl's fileno)
5046 #
5047 # returns: 1 on success, 0 on failure
5048 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5050 • set_info_callback
5052 Sets the callback function, that can be used to obtain state
5054 information for $ssl during connection setup and use. When
5055 callback is undef, the callback setting currently valid for ctx is
5056 used.
5057 Net::SSLeay::set_info_callback($ssl, $cb, [$data]);
5059 # $ssl - value corresponding to openssl's SSL structure
5060 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
5061 #
5062 # returns: no return value
5063 Check openssl doc
5065 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5066 • CTX_set_info_callback
5068 Sets the callback function on ctx, that can be used to obtain state
5070 information during ssl connection setup and use. When callback is
5071 undef, an existing callback will be disabled.
5072 Net::SSLeay::CTX_set_info_callback($ssl, $cb, [$data]);
5074 # $ssl - value corresponding to openssl's SSL structure
5075 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
5076 #
5077 # returns: no return value
5078 Check openssl doc
5080 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5081 • set_msg_callback
5083 Sets the callback function, that can be used to obtain protocol
5085 messages information for $ssl during connection setup and use.
5086 When callback is undef, the callback setting currently valid for
5087 ctx is used. Note that set_msg_callback_arg is not provided as
5088 there is no need to explicitly set $arg, this is handled by
5089 set_msg_callback.
5090 Net::SSLeay::set_msg_callback($ssl, $cb, [$arg]);
5092 # $ssl - value corresponding to openssl's SSL structure
5093 # $cb - sub { my ($write_p,$version,$content_type,$buf,$len,$ssl,$arg) = @_; ... }
5094 #
5095 # returns: no return value
5096 Check openssl doc
5098 <http://www.openssl.org/docs/manmaster/man3/SSL_set_msg_callback.html>
5099 • CTX_set_msg_callback
5101 Sets the callback function on ctx, that can be used to obtain
5103 protocol messages information for ssl connection setup and use.
5104 When callback is undef, the existing callback will be disabled.
5105 Note that CTX_set_msg_callback_arg is not provided as there is no
5106 need to explicitly set $arg, this is handled by
5107 CTX_set_msg_callback.
5108 Net::SSLeay::CTX_set_msg_callback($ssl, $cb, [$arg]);
5110 # $ssl - value corresponding to openssl's SSL structure
5111 # $cb - sub { my ($write_p,$version,$content_type,$buf,$len,$ssl,$arg) = @_; ... }
5112 #
5113 # returns: no return value
5114 Check openssl doc
5116 <http://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_msg_callback.html>
5117 • set_pref_cipher
5119 Sets the list of available ciphers for $ssl using the control
5121 string $str.
5122 my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
5124 # $ssl - value corresponding to openssl's SSL structure
5125 # $str - (string) cipher list e.g. '3DES:+RSA'
5126 #
5127 # returns: 1 if any cipher could be selected and 0 on complete failure
5128 Check openssl doc
5130 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
5131 • CTX_set_psk_client_callback
5133 Sets the psk client callback.
5135 Net::SSLeay::CTX_set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
5137 # $ssl - value corresponding to openssl's SSL structure
5138 # $hint - PSK identity hint send by the server
5139 # $identity - PSK identity
5140 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
5141 #
5142 # returns: no return value
5143 Check openssl doc
5145 <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
5146 • set_purpose
5148 my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
5150 # $ssl - value corresponding to openssl's SSL structure
5151 # $purpose - (integer) purpose identifier
5152 #
5153 # returns: 1 on success, 0 on failure
5154 For more info about available $purpose identifiers see
5156 "CTX_set_purpose".
5157 • set_quiet_shutdown
5159 Sets the 'quiet shutdown' flag for $ssl to be $mode.
5161 Net::SSLeay::set_quiet_shutdown($ssl, $mode);
5163 # $ssl - value corresponding to openssl's SSL structure
5164 # $mode - 0 or 1
5165 #
5166 # returns: no return value
5167 Check openssl doc
5169 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
5170 • set_session
5172 Set a TLS/SSL session to be used during TLS/SSL connect.
5174 my $rv = Net::SSLeay::set_session($to, $ses);
5176 # $to - value corresponding to openssl's SSL structure
5177 # $ses - value corresponding to openssl's SSL_SESSION structure
5178 #
5179 # returns: 1 on success, 0 on failure
5180 Check openssl doc
5182 <http://www.openssl.org/docs/ssl/SSL_set_session.html>
5183 • set_session_id_context
5185 Sets the context $sid_ctx of length $sid_ctx_len within which a
5187 session can be reused for the $ssl object.
5188 my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
5190 # $ssl - value corresponding to openssl's SSL structure
5191 # $sid_ctx - data buffer
5192 # $sid_ctx_len - length of data in $sid_ctx
5193 #
5194 # returns: 1 on success, 0 on failure
5195 Check openssl doc
5197 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
5198 • set_session_secret_cb
5200 Setup pre-shared secret session resumption function.
5202 Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
5204 # $ssl - value corresponding to openssl's SSL structure
5205 # $func - perl reference to callback function
5206 # $data - [optional] data that will be passed to callback function when invoked
5207 #
5208 # returns: no return value
5209 The callback function will be called like:
5211 callback_function($secret, $ciphers, $pref_cipher, $data);
5213 # $secret is the current master session key, usually all 0s at the beginning of a session
5214 # $ciphers is ref to an array of peer cipher names
5215 # $pref_cipher is a ref to an index into the list of cipher names of
5216 # the preferred cipher. Set it if you want to specify a preferred cipher
5217 # $data is the data passed to set_session_secret_cb
5218 The callback function should return 1 if it likes the suggested
5220 cipher (or has selected an alternative by setting pref_cipher),
5221 else it should return 0 (in which case OpenSSL will select its own
5222 preferred cipher).
5223 With OpenSSL 1.1 and later, callback_function can change the master
5225 key for the session by altering $secret and returning 1.
5226 • CTX_set_tlsext_ticket_getkey_cb
5228 Setup encryption for TLS session tickets (stateless session reuse).
5230 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($ctx, $func, $data);
5232 # $ctx - value corresponding to openssl's SSL_CTX structure
5233 # $func - perl reference to callback function
5234 # $data - [optional] data that will be passed to callback function when invoked
5235 #
5236 # returns: no return value
5237 The callback function will be called like:
5239 getkey($data,[$key_name]) -> ($key,$current_key_name)
5241 # $data is the data passed to set_session_secret_cb
5242 # $key_name is the name of the key OpenSSL has extracted from the session ticket
5243 # $key is the requested key for ticket encryption + HMAC
5244 # $current_key_name is the name for the currently valid key
5245 OpenSSL will call the function without a key name if it generates a
5247 new ticket. It then needs the callback to return the
5248 encryption+HMAC key and an identifier (key name) for this key.
5249 When OpenSSL gets a session ticket from the client it extracts the
5251 key name and calls the callback with this name as argument. It then
5252 expects the callback to return the encryption+HMAC key matching the
5253 requested key name and and also the key name which should be used
5254 at the moment. If the requested key name and the returned key name
5255 differ it means that this session ticket was created with an
5256 expired key and need to be renewed. In this case OpenSSL will call
5257 the callback again with no key name to create a new session ticket
5258 based on the old one.
5259 The key must be at least 32 byte of random data which can be
5261 created with RAND_bytes. Internally the first 16 byte are used as
5262 key in AES-128 encryption while the next 16 byte are used for the
5263 SHA-256 HMAC. The key name are binary data and must be exactly 16
5264 byte long.
5265 Example:
5267 Net::SSLeay::RAND_bytes(my $oldkey,32);
5269 Net::SSLeay::RAND_bytes(my $newkey,32);
5270 my $oldkey_name = pack("a16",'oldsecret');
5271 my $newkey_name = pack("a16",'newsecret');
5272 my @keys = (
5274 [ $newkey_name, $newkey ], # current active key
5275 [ $oldkey_name, $oldkey ], # already expired
5276 );
5277 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
5279 my ($mykeys,$name) = @_;
5280 # return (current_key, current_key_name) if no name given
5282 return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
5283 # return (matching_key, current_key_name) if we find a key matching
5285 # the given name
5286 for(my $i = 0; $i<@$mykeys; $i++) {
5287 next if $name ne $mykeys->[$i][0];
5288 return ($mykeys->[$i][1],$mykeys->[0][0]);
5289 }
5290 # no matching key found
5292 return;
5293 },\@keys);
5294 This function is based on the OpenSSL function
5296 SSL_CTX_set_tlsext_ticket_key_cb but provides a simpler to use
5297 interface. For more information see
5298 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tlsext_ticket_key_cb.html>
5299 • set_session_ticket_ext_cb
5301 Setup callback for TLS session tickets (stateless session reuse).
5303 Net::SSLeay::set_session_ticket_ext_cb($ssl, $func, $data);
5305 # $ssl - value corresponding to openssl's SSL structure
5306 # $func - perl reference to callback function
5307 # $data - [optional] data that will be passed to callback function when invoked
5308 #
5309 # returns: no return value
5310 The callback function will be called like:
5312 getticket($ssl,$ticket,$data) -> $return_value
5314 # $ssl is a value corresponding to openssl's SSL structure
5315 # $ticket is a value of received TLS session ticket (can also be empty)
5316 # $data is the data passed to set_session_ticket_ext_cb
5317 # $return_value is either 0 (failure) or 1 (success)
5318 This function is based on the OpenSSL function
5320 SSL_set_session_ticket_ext_cb.
5321 • set_session_ticket_ext
5323 Set TLS session ticket (stateless session reuse).
5325 Net::SSLeay::set_session_ticket_ext($ssl, $ticket);
5327 # $ssl - value corresponding to openssl's SSL structure
5328 # $ticket - is a value of TLS session ticket which client will send (can also be empty string)
5329 #
5330 # returns: no return value
5331 The callback function will be called like:
5333 getticket($ssl,$ticket,$data) -> $return_value
5335 # $ssl is a value corresponding to openssl's SSL structure
5336 # $ticket is a value of received TLS session ticket (can also be empty)
5337 # $data is the data passed to set_session_ticket_ext_cb
5338 # $return_value is either 0 (failure) or 1 (success)
5339 This function is based on the OpenSSL function
5341 SSL_set_session_ticket_ext_cb.
5342 • set_shutdown
5344 Sets the shutdown state of $ssl to $mode.
5346 Net::SSLeay::set_shutdown($ssl, $mode);
5348 # $ssl - value corresponding to openssl's SSL structure
5349 # $mode - (integer) shutdown mode:
5350 # 0 - No shutdown
5351 # 1 - SSL_SENT_SHUTDOWN
5352 # 2 - SSL_RECEIVED_SHUTDOWN
5353 # 3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
5354 #
5355 # returns: no return value
5356 Check openssl doc
5358 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
5359 • set_ssl_method
5361 Sets a new TLS/SSL method for a particular $ssl object.
5363 my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
5365 # $ssl - value corresponding to openssl's SSL structure
5366 # $method - value corresponding to openssl's SSL_METHOD structure
5367 #
5368 # returns: 1 on success, 0 on failure
5369 Check openssl doc
5371 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
5372 • set_tmp_dh
5374 Sets DH parameters to be used to be $dh.
5376 my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
5378 # $ssl - value corresponding to openssl's SSL structure
5379 # $dh - value corresponding to openssl's DH structure
5380 #
5381 # returns: 1 on success, 0 on failure
5382 Check openssl doc
5384 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5385 • set_tmp_dh_callback
5387 Sets the callback function for $ssl to be used when a DH parameters
5389 are required to $dh_cb.
5390 ??? (does this function really work?)
5392 Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
5394 # $ssl - value corresponding to openssl's SSL structure
5395 # $dh_cb - pointer to function ???
5396 #
5397 # returns: no return value
5398 Check openssl doc
5400 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5401 • set_tmp_rsa
5403 Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
5405 my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
5407 # $ssl - value corresponding to openssl's SSL structure
5408 # $rsa - value corresponding to openssl's RSA structure
5409 #
5410 # returns: 1 on success, 0 on failure
5411 Example:
5413 $rsakey = Net::SSLeay::RSA_generate_key();
5415 Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
5416 Net::SSLeay::RSA_free($rsakey);
5417 Check openssl doc
5419 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5420 • set_tmp_rsa_callback
5422 Sets the callback function for $ssl to be used when a
5424 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
5425 ??? (does this function really work?)
5427 Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
5429 # $ssl - value corresponding to openssl's SSL structure
5430 # $tmp_rsa_callback - (function pointer) ???
5431 #
5432 # returns: no return value
5433 Check openssl doc
5435 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5436 • set_trust
5438 my $rv = Net::SSLeay::set_trust($ssl, $trust);
5440 # $ssl - value corresponding to openssl's SSL structure
5441 # $trust - (integer) trust identifier
5442 #
5443 # returns: the original value
5444 For more details about $trust values see "CTX_set_trust".
5446 • shutdown
5448 Shuts down an active TLS/SSL connection. It sends the 'close
5450 notify' shutdown alert to the peer.
5451 my $rv = Net::SSLeay::shutdown($ssl);
5453 # $ssl - value corresponding to openssl's SSL structure
5454 #
5455 # returns: 1 - shutdown was successfully completed
5456 # 0 - shutdown is not yet finished,
5457 # -1 - shutdown was not successful
5458 Check openssl doc
5460 <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
5461 • state_string
5463 Returns a 6 letter string indicating the current state of the SSL
5465 object $ssl.
5466 my $rv = Net::SSLeay::state_string($ssl);
5468 # $ssl - value corresponding to openssl's SSL structure
5469 #
5470 # returns: 6-letter string
5471 Check openssl doc
5473 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5474 • state_string_long
5476 Returns a string indicating the current state of the SSL object
5478 $ssl.
5479 my $rv = Net::SSLeay::state_string_long($ssl);
5481 # $ssl - value corresponding to openssl's SSL structure
5482 #
5483 # returns: state strings
5484 Check openssl doc
5486 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5487 • set_default_passwd_cb
5489 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5491 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5492 Sets the default password callback called when loading/storing a
5494 PEM certificate with encryption for $ssl.
5495 Net::SSLeay::set_default_passwd_cb($ssl, $func);
5497 # $ssl - value corresponding to openssl's SSL structure
5498 # $func - perl reference to callback function
5499 #
5500 # returns: no return value
5501 Check openssl doc
5503 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5504 • set_default_passwd_cb_userdata
5506 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5508 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5509 Sets a pointer to userdata which will be provided to the password
5511 callback of $ssl on invocation.
5512 Net::SSLeay::set_default_passwd_cb_userdata($ssl, $userdata);
5514 # $ssl - value corresponding to openssl's SSL structure
5515 # $userdata - data that will be passed to callback function when invoked
5516 #
5517 # returns: no return value
5518 Check openssl doc
5520 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5521 • use_PrivateKey
5523 Adds $pkey as private key to $ssl.
5525 my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
5527 # $ssl - value corresponding to openssl's SSL structure
5528 # $pkey - value corresponding to openssl's EVP_PKEY structure
5529 #
5530 # returns: 1 on success, otherwise check out the error stack to find out the reason
5531 Check openssl doc
5533 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5534 • use_PrivateKey_ASN1
5536 Adds the private key of type $pk stored in $data to $ssl.
5538 my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
5540 # $pk - (integer) key type, NID of corresponding algorithm
5541 # $ssl - value corresponding to openssl's SSL structure
5542 # $data - key data (binary)
5543 # $len - length of $data
5544 #
5545 # returns: 1 on success, otherwise check out the error stack to find out the reason
5546 Check openssl doc
5548 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5549 • use_PrivateKey_file
5551 Adds the first private key found in $file to $ssl.
5553 my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
5555 # $ssl - value corresponding to openssl's SSL structure
5556 # $file - (string) file name
5557 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5558 #
5559 # returns: 1 on success, otherwise check out the error stack to find out the reason
5560 Check openssl doc
5562 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5563 • use_RSAPrivateKey
5565 Adds $rsa as RSA private key to $ssl.
5567 my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
5569 # $ssl - value corresponding to openssl's SSL structure
5570 # $rsa - value corresponding to openssl's RSA structure
5571 #
5572 # returns: 1 on success, otherwise check out the error stack to find out the reason
5573 Check openssl doc
5575 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5576 • use_RSAPrivateKey_ASN1
5578 Adds RSA private key stored in $data to $ssl.
5580 my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
5582 # $ssl - value corresponding to openssl's SSL structure
5583 # $data - key data (binary)
5584 # $len - length of $data
5585 #
5586 # returns: 1 on success, otherwise check out the error stack to find out the reason
5587 Check openssl doc
5589 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5590 • use_RSAPrivateKey_file
5592 Adds the first RSA private key found in $file to $ssl.
5594 my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
5596 # $ssl - value corresponding to openssl's SSL structure
5597 # $file - (string) file name
5598 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5599 #
5600 # returns: 1 on success, otherwise check out the error stack to find out the reason
5601 Check openssl doc
5603 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5604 • use_certificate
5606 Loads the certificate $x into $ssl.
5608 my $rv = Net::SSLeay::use_certificate($ssl, $x);
5610 # $ssl - value corresponding to openssl's SSL structure
5611 # $x - value corresponding to openssl's X509 structure
5612 #
5613 # returns: 1 on success, otherwise check out the error stack to find out the reason
5614 Check openssl doc
5616 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5617 • use_certificate_ASN1
5619 Loads the ASN1 encoded certificate from $data to $ssl.
5621 my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
5623 # $ssl - value corresponding to openssl's SSL structure
5624 # $data - certificate data (binary)
5625 # $len - length of $data
5626 #
5627 # returns: 1 on success, otherwise check out the error stack to find out the reason
5628 Check openssl doc
5630 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5631 • use_certificate_chain_file
5633 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5635 requires at least OpenSSL 1.1.0
5636 Loads a certificate chain from $file into $ssl. The certificates
5638 must be in PEM format and must be sorted starting with the
5639 subject's certificate (actual client or server certificate),
5640 followed by intermediate CA certificates if applicable, and ending
5641 at the highest level (root) CA.
5642 my $rv = Net::SSLeay::use_certificate_chain_file($ssl, $file);
5644 # $ssl - value corresponding to openssl's SSL structure
5645 # $file - (string) file name
5646 #
5647 # returns: 1 on success, otherwise check out the error stack to find out the reason
5648 Check openssl doc
5650 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5651 • use_certificate_file
5653 Loads the first certificate stored in $file into $ssl.
5655 my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
5657 # $ssl - value corresponding to openssl's SSL structure
5658 # $file - (string) file name
5659 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5660 #
5661 # returns: 1 on success, otherwise check out the error stack to find out the reason
5662 Check openssl doc
5664 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5665 • get_version
5667 Returns SSL/TLS protocol name
5669 my $rv = Net::SSLeay::get_version($ssl);
5671 # $ssl - value corresponding to openssl's SSL structure
5672 #
5673 # returns: (string) protocol name, see OpenSSL manual for the full list
5674 # TLSv1
5675 # TLSv1.3
5676 Check openssl doc
5678 <https://www.openssl.org/docs/manmaster/man3/SSL_get_version.html>
5679 • version
5681 Returns SSL/TLS protocol version
5683 my $rv = Net::SSLeay::version($ssl);
5685 # $ssl - value corresponding to openssl's SSL structure
5686 #
5687 # returns: (integer) protocol version, see OpenSSL manual for the full list
5688 # 0x0301 - TLS1_VERSION (TLSv1)
5689 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5690 Check openssl doc
5692 <https://www.openssl.org/docs/manmaster/man3/SSL_version.html>
5693 • client_version
5695 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5697 requires at least OpenSSL 1.1.0, not in LibreSSL
5698 Returns TLS protocol version used by the client when initiating the
5700 connection
5701 my $rv = Net::SSLeay::client_version($ssl);
5703 # $ssl - value corresponding to openssl's SSL structure
5704 #
5705 # returns: (integer) protocol version, see OpenSSL manual for the full list
5706 # 0x0301 - TLS1_VERSION (TLSv1)
5707 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5708 Check openssl doc
5710 <https://www.openssl.org/docs/manmaster/man3/SSL_client_version.html>
5711 • is_dtls
5713 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5715 requires at least OpenSSL 1.1.0, not in LibreSSL
5716 my $rv = Net::SSLeay::is_dtls($ssl);
5718 # $ssl - value corresponding to openssl's SSL structure
5719 #
5720 # returns: (integer) zero or one
5721 # 0 - connection is not using DTLS
5722 # 1 - connection is using DTLS
5723 Check openssl doc
5725 <https://www.openssl.org/docs/manmaster/man3/SSL_is_dtls.html>
5726 • want
5728 Returns state information for the SSL object $ssl.
5730 my $rv = Net::SSLeay::want($ssl);
5732 # $ssl - value corresponding to openssl's SSL structure
5733 #
5734 # returns: state
5735 # 1 - SSL_NOTHING
5736 # 2 - SSL_WRITING
5737 # 3 - SSL_READING
5738 # 4 - SSL_X509_LOOKUP
5739 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5741 • write
5743 Writes data from the buffer $data into the specified $ssl
5745 connection.
5746 my $rv = Net::SSLeay::write($ssl, $data);
5748 # $ssl - value corresponding to openssl's SSL structure
5749 # $data - data to be written
5750 #
5751 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5752 # 0 - write not successful, probably the underlying connection was closed
5753 # <0 - error
5754 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5756 • write_ex
5758 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5760 requires at least OpenSSL 1.1.1, not in LibreSSL
5761 Writes data from the buffer $data into the specified $ssl
5763 connection.
5764 my ($len, $rv) = Net::SSLeay::write_ex($ssl, $data);
5766 # $ssl - value corresponding to openssl's SSL structure
5767 # $data - data to be written
5768 #
5769 # returns a list: two-item list consisting of number of bytes written,
5770 # and return code from SSL_write_ex()
5771 Check openssl doc
5773 <https://www.openssl.org/docs/manmaster/man3/SSL_write_ex.html>
5774 • write_partial
5776 NOTE: Does not exactly correspond to any low level API function
5778 Writes a fragment of data in $data from the buffer $data into the
5780 specified $ssl connection. This is a non-blocking function like
5781 Net::SSLeay::write().
5782 my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
5784 # $ssl - value corresponding to openssl's SSL structure
5785 # $from - (integer) offset from the beginning of $data
5786 # $count - (integer) length of data to be written
5787 # $data - data buffer
5788 #
5789 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5790 # 0 - write not successful, probably the underlying connection was closed
5791 # <0 - error
5792 • set_tlsext_host_name
5794 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5796 requires at least openssl-0.9.8f
5797 Sets TLS servername extension on SLL object $ssl to value $name.
5799 my $rv = set_tlsext_host_name($ssl, $name);
5801 # $ssl - value corresponding to openssl's SSL structure
5802 # $name - (string) name to be set
5803 #
5804 # returns: 1 on success, 0 on failure
5805 Low level API: RAND_* related functions
5807 Check openssl doc related to RAND stuff
5809 <http://www.openssl.org/docs/crypto/rand.html>
5810 • RAND_add
5812 Mixes the $num bytes at $buf into the PRNG state.
5814 Net::SSLeay::RAND_add($buf, $num, $entropy);
5816 # $buf - buffer with data to be mixed into the PRNG state
5817 # $num - number of bytes in $buf
5818 # $entropy - estimate of how much randomness is contained in $buf (in bytes)
5819 #
5820 # returns: no return value
5821 Check openssl doc
5823 <http://www.openssl.org/docs/crypto/RAND_add.html>
5824 • RAND_seed
5826 Equivalent to "RAND_add" when $num == $entropy.
5828 Net::SSLeay::RAND_seed($buf); # Perlishly figures out buf size
5830 # $buf - buffer with data to be mixed into the PRNG state
5831 # $num - number of bytes in $buf
5832 #
5833 # returns: no return value
5834 Check openssl doc
5836 <http://www.openssl.org/docs/crypto/RAND_add.html>
5837 • RAND_status
5839 Gives PRNG status (seeded enough or not).
5841 my $rv = Net::SSLeay::RAND_status();
5843 #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5844 Check openssl doc
5846 <http://www.openssl.org/docs/crypto/RAND_add.html>
5847 • RAND_bytes
5849 Puts $num cryptographically strong pseudo-random bytes into $buf.
5851 my $rv = Net::SSLeay::RAND_bytes($buf, $num);
5853 # $buf - buffer where the random data will be stored
5854 # $num - the size (in bytes) of requested random data
5855 #
5856 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5857 Check openssl doc
5859 <http://www.openssl.org/docs/manmaster/man3/RAND_bytes.html>
5860 • RAND_priv_bytes
5862 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5864 requires at least OpenSSL 1.1.1, not in LibreSSL
5865 Puts $num cryptographically strong pseudo-random bytes into $buf.
5867 my $rv = Net::SSLeay::RAND_priv_bytes($buf, $num);
5869 # $buf - buffer where the random data will be stored
5870 # $num - the size (in bytes) of requested random data
5871 #
5872 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5873 RAND_priv_bytes has the same semantics as RAND_bytes, but see see
5875 the documentation for more information.
5876 Check openssl doc
5878 <http://www.openssl.org/docs/manmaster/man3/RAND_priv_bytes.html>
5879 • RAND_pseudo_bytes
5881 Puts $num pseudo-random (not necessarily unpredictable) bytes into
5883 $buf.
5884 my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
5886 # $buf - buffer where the random data will be stored
5887 # $num - the size (in bytes) of requested random data
5888 #
5889 # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
5890 Check openssl doc
5892 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5893 • RAND_cleanup
5895 Erase the PRNG state.
5897 Net::SSLeay::RAND_cleanup();
5899 # no args, no return value
5900 Check openssl doc
5902 <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5903 • RAND_egd_bytes
5905 Queries the entropy gathering daemon EGD on socket $path for $bytes
5907 bytes.
5908 my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
5910 # $path - path to a socket of entropy gathering daemon EGD
5911 # $bytes - number of bytes we want from EGD
5912 #
5913 # returns: the number of bytes read from the daemon on success, and -1 on failure
5914 Check openssl doc
5916 <http://www.openssl.org/docs/crypto/RAND_egd.html>
5917 • RAND_file_name
5919 Generates a default path for the random seed file.
5921 my $file = Net::SSLeay::RAND_file_name($num);
5923 # $num - maximum size of returned file name
5924 #
5925 # returns: string with file name on success, '' (empty string) or undef on failure
5926 LibreSSL and OpenSSL 1.1.0a and later return undef when, for
5928 example, $num is not large enough to hold the filename.
5929 Check openssl doc
5931 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5932 • RAND_load_file
5934 COMPATIBILITY: Is no longer functional on LibreSSL
5936 Reads $max_bytes of bytes from $file_name and adds them to the
5938 PRNG.
5939 my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
5941 # $file_name - the name of file
5942 # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
5943 #
5944 # returns: the number of bytes read
5945 Check openssl doc
5947 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5948 • RAND_write_file
5950 Writes 1024 random bytes to $file_name which can be used to
5952 initialize the PRNG by calling "RAND_load_file" in a later session.
5953 my $rv = Net::SSLeay::RAND_write_file($file_name);
5955 # $file_name - the name of file
5956 #
5957 # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
5958 Check openssl doc
5960 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5961 • RAND_poll
5963 Collects some entropy from operating system and adds it to the
5965 PRNG.
5966 my $rv = Net::SSLeay::RAND_poll();
5968 # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5969 Low level API: OBJ_* related functions
5971 • OBJ_cmp
5973 Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5975 my $rv = Net::SSLeay::OBJ_cmp($a, $b);
5977 # $a - value corresponding to openssl's ASN1_OBJECT structure
5978 # $b - value corresponding to openssl's ASN1_OBJECT structure
5979 #
5980 # returns: if the two are identical 0 is returned
5981 Check openssl doc
5983 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5984 • OBJ_dup
5986 Returns a copy/duplicate of $o.
5988 my $rv = Net::SSLeay::OBJ_dup($o);
5990 # $o - value corresponding to openssl's ASN1_OBJECT structure
5991 #
5992 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5993 Check openssl doc
5995 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5996 • OBJ_nid2ln
5998 Returns long name for given NID $n.
6000 my $rv = Net::SSLeay::OBJ_nid2ln($n);
6002 # $n - (integer) NID
6003 #
6004 # returns: (string) long name e.g. 'commonName'
6005 Check openssl doc
6007 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6008 • OBJ_ln2nid
6010 Returns NID corresponding to given long name $n.
6012 my $rv = Net::SSLeay::OBJ_ln2nid($s);
6014 # $s - (string) long name e.g. 'commonName'
6015 #
6016 # returns: (integer) NID
6017 • OBJ_nid2sn
6019 Returns short name for given NID $n.
6021 my $rv = Net::SSLeay::OBJ_nid2sn($n);
6023 # $n - (integer) NID
6024 #
6025 # returns: (string) short name e.g. 'CN'
6026 Example:
6028 print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
6030 • OBJ_sn2nid
6032 Returns NID corresponding to given short name $s.
6034 my $rv = Net::SSLeay::OBJ_sn2nid($s);
6036 # $s - (string) short name e.g. 'CN'
6037 #
6038 # returns: (integer) NID
6039 Example:
6041 print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
6043 print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
6044 • OBJ_nid2obj
6046 Returns ASN1_OBJECT for given NID $n.
6048 my $rv = Net::SSLeay::OBJ_nid2obj($n);
6050 # $n - (integer) NID
6051 #
6052 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6053 Check openssl doc
6055 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6056 • OBJ_obj2nid
6058 Returns NID corresponding to given ASN1_OBJECT $o.
6060 my $rv = Net::SSLeay::OBJ_obj2nid($o);
6062 # $o - value corresponding to openssl's ASN1_OBJECT structure
6063 #
6064 # returns: (integer) NID
6065 Check openssl doc
6067 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6068 • OBJ_txt2obj
6070 Converts the text string s into an ASN1_OBJECT structure. If
6072 $no_name is 0 then long names (e.g. 'commonName') and short names
6073 (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
6074 '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
6075 my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
6077 # $s - text string to be converted
6078 # $no_name - (integer) 0 or 1
6079 #
6080 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6081 Check openssl doc
6083 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6084 • OBJ_obj2txt
6086 Converts the ASN1_OBJECT a into a textual representation.
6088 Net::SSLeay::OBJ_obj2txt($a, $no_name);
6090 # $a - value corresponding to openssl's ASN1_OBJECT structure
6091 # $no_name - (integer) 0 or 1
6092 #
6093 # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
6094 Check openssl doc
6096 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6097 • OBJ_txt2nid
6099 Returns NID corresponding to text string $s which can be a long
6101 name, a short name or the numerical representation of an object.
6102 my $rv = Net::SSLeay::OBJ_txt2nid($s);
6104 # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
6105 #
6106 # returns: (integer) NID
6107 Example:
6109 my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
6111 Net::SSLeay::OBJ_nid2sn($n);
6112 Check openssl doc
6114 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6115 Low level API: ASN1_INTEGER_* related functions
6117 • ASN1_INTEGER_new
6119 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6121 Creates a new ASN1_INTEGER structure.
6123 my $rv = Net::SSLeay::ASN1_INTEGER_new();
6125 #
6126 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6127 • ASN1_INTEGER_free
6129 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6131 Free an allocated ASN1_INTEGER structure.
6133 Net::SSLeay::ASN1_INTEGER_free($i);
6135 # $i - value corresponding to openssl's ASN1_INTEGER structure
6136 #
6137 # returns: no return value
6138 • ASN1_INTEGER_get
6140 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6142 Returns integer value of given ASN1_INTEGER object.
6144 BEWARE: If the value stored in ASN1_INTEGER is greater than max.
6146 integer that can be stored in 'long' type (usually 32bit but may
6147 vary according to platform) then this function will return -1. For
6148 getting large ASN1_INTEGER values consider using
6149 "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
6150 my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
6152 # $a - value corresponding to openssl's ASN1_INTEGER structure
6153 #
6154 # returns: integer value of ASN1_INTEGER object in $a
6155 • ASN1_INTEGER_set
6157 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6159 Sets value of given ASN1_INTEGER object to value $val
6161 BEWARE: $val has max. limit (= max. integer that can be stored in
6163 'long' type). For setting large ASN1_INTEGER values consider using
6164 "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
6165 my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
6167 # $i - value corresponding to openssl's ASN1_INTEGER structure
6168 # $val - integer value
6169 #
6170 # returns: 1 on success, 0 on failure
6171 • P_ASN1_INTEGER_get_dec
6173 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6175 Returns string with decimal representation of integer value of
6177 given ASN1_INTEGER object.
6178 Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
6180 # $i - value corresponding to openssl's ASN1_INTEGER structure
6181 #
6182 # returns: string with decimal representation
6183 • P_ASN1_INTEGER_get_hex
6185 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6187 Returns string with hexadecimal representation of integer value of
6189 given ASN1_INTEGER object.
6190 Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
6192 # $i - value corresponding to openssl's ASN1_INTEGER structure
6193 #
6194 # returns: string with hexadecimal representation
6195 • P_ASN1_INTEGER_set_dec
6197 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6199 Sets value of given ASN1_INTEGER object to value $val (decimal
6201 string, suitable for large integers)
6202 Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
6204 # $i - value corresponding to openssl's ASN1_INTEGER structure
6205 # $str - string with decimal representation
6206 #
6207 # returns: 1 on success, 0 on failure
6208 • P_ASN1_INTEGER_set_hex
6210 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6212 Sets value of given ASN1_INTEGER object to value $val (hexadecimal
6214 string, suitable for large integers)
6215 Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
6217 # $i - value corresponding to openssl's ASN1_INTEGER structure
6218 # $str - string with hexadecimal representation
6219 #
6220 # returns: 1 on success, 0 on failure
6221 Low level API: ASN1_STRING_* related functions
6223 • P_ASN1_STRING_get
6225 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6227 Returns string value of given ASN1_STRING object.
6229 Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
6231 # $s - value corresponding to openssl's ASN1_STRING structure
6232 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
6233 #
6234 # returns: string
6235 $string = Net::SSLeay::P_ASN1_STRING_get($s);
6237 #is the same as:
6238 $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
6239 Low level API: ASN1_TIME_* related functions
6241 • ASN1_TIME_new
6243 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6245 my $time = ASN1_TIME_new();
6247 # returns: value corresponding to openssl's ASN1_TIME structure
6248 • ASN1_TIME_free
6250 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6252 ASN1_TIME_free($time);
6254 # $time - value corresponding to openssl's ASN1_TIME structure
6255 • ASN1_TIME_set
6257 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6259 ASN1_TIME_set($time, $t);
6261 # $time - value corresponding to openssl's ASN1_TIME structure
6262 # $t - time value in seconds since 1.1.1970
6263 BEWARE: It is platform dependent how this function will handle
6265 dates after 2038. Although perl's integer is large enough the
6266 internal implementation of this function is dependent on the size
6267 of time_t structure (32bit time_t has problem with 2038).
6268 If you want to safely set date and time after 2038 use function
6270 "P_ASN1_TIME_set_isotime".
6271 • P_ASN1_TIME_get_isotime
6273 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6275 requires at least openssl-0.9.7e
6276 NOTE: Does not exactly correspond to any low level API function
6278 Gives ISO-8601 string representation of ASN1_TIME structure.
6280 my $datetime_string = P_ASN1_TIME_get_isotime($time);
6282 # $time - value corresponding to openssl's ASN1_TIME structure
6283 #
6284 # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
6285 The output format is compatible with module
6287 DateTime::Format::RFC3339
6288 • P_ASN1_TIME_set_isotime
6290 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6292 requires at least openssl-0.9.7e
6293 NOTE: Does not exactly correspond to any low level API function
6295 Sets time and date value of ANS1_time structure.
6297 my $rv = P_ASN1_TIME_set_isotime($time, $string);
6299 # $time - value corresponding to openssl's ASN1_TIME structure
6300 # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
6301 #
6302 # returns: 1 on success, 0 on failure
6303 The $string parameter has to be in full form like
6305 "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
6306 "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
6307 "2012-03-22" are not supported.
6308 • P_ASN1_TIME_put2string
6310 COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
6312 bugs with openssl-0.9.8i
6313 NOTE: Does not exactly correspond to any low level API function
6315 Gives string representation of ASN1_TIME structure.
6317 my $str = P_ASN1_TIME_put2string($time);
6319 # $time - value corresponding to openssl's ASN1_TIME structure
6320 #
6321 # returns: datetime string like 'May 16 20:39:37 2033 GMT'
6322 • P_ASN1_UTCTIME_put2string
6324 NOTE: deprecated function, only for backward compatibility, just an
6326 alias for "P_ASN1_TIME_put2string"
6327 Low level API: X509_* related functions
6329 • X509_new
6331 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6333 Allocates and initializes a X509 structure.
6335 my $rv = Net::SSLeay::X509_new();
6337 #
6338 # returns: value corresponding to openssl's X509 structure (0 on failure)
6339 Check openssl doc
6341 <http://www.openssl.org/docs/crypto/X509_new.html>
6342 • X509_free
6344 Frees up the X509 structure.
6346 Net::SSLeay::X509_free($a);
6348 # $a - value corresponding to openssl's X509 structure
6349 #
6350 # returns: no return value
6351 Check openssl doc
6353 <http://www.openssl.org/docs/crypto/X509_new.html>
6354 • X509_check_host
6356 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6358 requires at least OpenSSL 1.0.2.
6359 X509_CHECK_FLAG_NEVER_CHECK_SUBJECT requires OpenSSL 1.1.0.
6360 Checks if the certificate Subject Alternative Name (SAN) or Subject
6362 CommonName (CN) matches the specified host name.
6363 my $rv = Net::SSLeay::X509_check_host($cert, $name, $flags, $peername);
6365 # $cert - value corresponding to openssl's X509 structure
6366 # $name - host name to check
6367 # $flags (optional, default: 0) - can be the bitwise OR of:
6368 # &Net::SSLeay::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
6369 # &Net::SSLeay::X509_CHECK_FLAG_NO_WILDCARDS
6370 # &Net::SSLeay::X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
6371 # &Net::SSLeay::X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
6372 # &Net::SSLeay::X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
6373 # &Net::SSLeay::X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
6374 # $peername (optional) - If not omitted and $host matches $cert,
6375 # a copy of the matching SAN or CN from
6376 # the peer certificate is stored in $peername.
6377 #
6378 # returns:
6379 # 1 for a successful match
6380 # 0 for a failed match
6381 # -1 for an internal error
6382 # -2 if the input is malformed
6383 Check openssl doc
6385 <https://www.openssl.org/docs/crypto/X509_check_host.html>.
6386 • X509_check_email
6388 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6390 requires at least OpenSSL 1.0.2.
6391 Checks if the certificate matches the specified email address.
6393 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6395 # $cert - value corresponding to openssl's X509 structure
6396 # $address - email address to check
6397 # $flags (optional, default: 0) - see X509_check_host()
6398 #
6399 # returns: see X509_check_host()
6400 Check openssl doc
6402 <https://www.openssl.org/docs/crypto/X509_check_email.html>.
6403 • X509_check_ip
6405 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6407 requires at least OpenSSL 1.0.2.
6408 Checks if the certificate matches the specified IPv4 or IPv6
6410 address.
6411 my $rv = Net::SSLeay::X509_check_ip($cert, $address, $flags);
6413 # $cert - value corresponding to openssl's X509 structure
6414 # $address - IP address to check in binary format, in network byte order
6415 # $flags (optional, default: 0) - see X509_check_host()
6416 #
6417 # returns: see X509_check_host()
6418 Check openssl doc
6420 <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
6421 • X509_check_ip_asc
6423 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6425 requires at least OpenSSL 1.0.2.
6426 Checks if the certificate matches the specified IPv4 or IPv6
6428 address.
6429 my $rv = Net::SSLeay::X509_check_ip_asc($cert, $address, $flags);
6431 # $cert - value corresponding to openssl's X509 structure
6432 # $address - IP address to check in text representation
6433 # $flags (optional, default: 0) - see X509_check_host()
6434 #
6435 # returns: see X509_check_host()
6436 Check openssl doc
6438 <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
6439 • X509_certificate_type
6441 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6443 Returns bitmask with type of certificate $x.
6445 my $rv = Net::SSLeay::X509_certificate_type($x);
6447 # $x - value corresponding to openssl's X509 structure
6448 #
6449 # returns: (integer) bitmask with certificate type
6450 #to decode bitmask returned by this function use these constants:
6452 &Net::SSLeay::EVP_PKS_DSA
6453 &Net::SSLeay::EVP_PKS_EC
6454 &Net::SSLeay::EVP_PKS_RSA
6455 &Net::SSLeay::EVP_PKT_ENC
6456 &Net::SSLeay::EVP_PKT_EXCH
6457 &Net::SSLeay::EVP_PKT_EXP
6458 &Net::SSLeay::EVP_PKT_SIGN
6459 &Net::SSLeay::EVP_PK_DH
6460 &Net::SSLeay::EVP_PK_DSA
6461 &Net::SSLeay::EVP_PK_EC
6462 &Net::SSLeay::EVP_PK_RSA
6463 • X509_digest
6465 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6467 Computes digest/fingerprint of X509 $data using $type hash
6469 function.
6470 my $digest_value = Net::SSLeay::X509_digest($data, $type);
6472 # $data - value corresponding to openssl's X509 structure
6473 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6474 #
6475 # returns: hash value (binary)
6476 #to get printable (hex) value of digest use:
6478 print unpack('H*', $digest_value);
6479 • X509_issuer_and_serial_hash
6481 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6483 Sort of a checksum of issuer name and serial number of X509
6485 certificate $x. The result is not a full hash (e.g. sha-1), it is
6486 kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
6487 The resulting value might differ across different openssl versions
6488 for the same X509 certificate.
6489 my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
6491 # $x - value corresponding to openssl's X509 structure
6492 #
6493 # returns: number representing checksum
6494 • X509_issuer_name_hash
6496 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6498 Sort of a checksum of issuer name of X509 certificate $x. The
6500 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6501 truncated to the size of 'unsigned long' (32 bits). The resulting
6502 value might differ across different openssl versions for the same
6503 X509 certificate.
6504 my $rv = Net::SSLeay::X509_issuer_name_hash($x);
6506 # $x - value corresponding to openssl's X509 structure
6507 #
6508 # returns: number representing checksum
6509 • X509_subject_name_hash
6511 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6513 Sort of a checksum of subject name of X509 certificate $x. The
6515 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6516 truncated to the size of 'unsigned long' (32 bits). The resulting
6517 value might differ across different openssl versions for the same
6518 X509 certificate.
6519 my $rv = Net::SSLeay::X509_subject_name_hash($x);
6521 # $x - value corresponding to openssl's X509 structure
6522 #
6523 # returns: number representing checksum
6524 • X509_pubkey_digest
6526 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6528 requires at least openssl-0.9.7
6529 Computes digest/fingerprint of public key from X509 certificate
6531 $data using $type hash function.
6532 my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
6534 # $data - value corresponding to openssl's X509 structure
6535 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6536 #
6537 # returns: hash value (binary)
6538 #to get printable (hex) value of digest use:
6540 print unpack('H*', $digest_value);
6541 • X509_set_issuer_name
6543 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6545 Sets issuer of X509 certificate $x to $name.
6547 my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
6549 # $x - value corresponding to openssl's X509 structure
6550 # $name - value corresponding to openssl's X509_NAME structure
6551 #
6552 # returns: 1 on success, 0 on failure
6553 • X509_set_pubkey
6555 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6557 Sets public key of X509 certificate $x to $pkey.
6559 my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
6561 # $x - value corresponding to openssl's X509 structure
6562 # $pkey - value corresponding to openssl's EVP_PKEY structure
6563 #
6564 # returns: 1 on success, 0 on failure
6565 • X509_set_serialNumber
6567 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6569 Sets serial number of X509 certificate $x to $serial.
6571 my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
6573 # $x - value corresponding to openssl's X509 structure
6574 # $serial - value corresponding to openssl's ASN1_INTEGER structure
6575 #
6576 # returns: 1 on success, 0 on failure
6577 #to create $serial value use one of these:
6579 $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
6580 $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
6581 $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
6582 • X509_set_subject_name
6584 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6586 Sets subject of X509 certificate $x to $name.
6588 my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
6590 # $x - value corresponding to openssl's X509 structure
6591 # $name - value corresponding to openssl's X509_NAME structure
6592 #
6593 # returns: 1 on success, 0 on failure
6594 • X509_set_version
6596 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6598 Set 'version' value for X509 certificate $ to $version.
6600 my $rv = Net::SSLeay::X509_set_version($x, $version);
6602 # $x - value corresponding to openssl's X509 structure
6603 # $version - (integer) version number
6604 #
6605 # returns: 1 on success, 0 on failure
6606 • X509_sign
6608 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6610 Sign X509 certificate $x with private key $pkey (using digest
6612 algorithm $md).
6613 my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
6615 # $x - value corresponding to openssl's X509 structure
6616 # $pkey - value corresponding to openssl's EVP_PKEY structure
6617 # $md - value corresponding to openssl's EVP_MD structure
6618 #
6619 # returns: 1 on success, 0 on failure
6620 • X509_verify
6622 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6624 Verifies X509 object $a using public key $r (pubkey of issuing CA).
6626 my $rv = Net::SSLeay::X509_verify($x, $r);
6628 # $x - value corresponding to openssl's X509 structure
6629 # $r - value corresponding to openssl's EVP_PKEY structure
6630 #
6631 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6632 • X509_get_ext_count
6634 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6636 Returns the total number of extensions in X509 object $x.
6638 my $rv = Net::SSLeay::X509_get_ext_count($x);
6640 # $x - value corresponding to openssl's X509 structure
6641 #
6642 # returns: count of extensions
6643 • X509_get_pubkey
6645 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6647 Returns public key corresponding to given X509 object $x.
6649 my $rv = Net::SSLeay::X509_get_pubkey($x);
6651 # $x - value corresponding to openssl's X509 structure
6652 #
6653 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6654 NOTE: This method returns only the public key's key bits, without
6656 the algorithm or parameters. Use X509_get_X509_PUBKEY() to return
6657 the full public key (SPKI) instead.
6658 • X509_get_X509_PUBKEY
6660 COMPATIBILITY: not available in Net-SSLeay-1.72 and before
6662 Returns the full public key (SPKI) of given X509 certificate $x.
6664 Net::SSLeay::X509_get_X509_PUBKEY($x);
6666 # $x - value corresponding to openssl's X509 structure
6667 #
6668 # returns: public key data in DER format (binary)
6669 • X509_get_serialNumber
6671 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6673 Returns serial number of X509 certificate $x.
6675 my $rv = Net::SSLeay::X509_get_serialNumber($x);
6677 # $x - value corresponding to openssl's X509 structure
6678 #
6679 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6680 See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
6682 "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
6683 • X509_get0_serialNumber
6685 COMPATIBILITY: available in Net-SSLeay-1.86 onwards
6687 X509_get0_serialNumber() is the same as X509_get_serialNumber()
6689 except it accepts a const parameter and returns a const result.
6690 • X509_get_version
6692 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6694 Returns 'version' value of given X509 certificate $x.
6696 my $rv = Net::SSLeay::X509_get_version($x);
6698 # $x - value corresponding to openssl's X509 structure
6699 #
6700 # returns: (integer) version
6701 • X509_get_ext
6703 Returns X509_EXTENSION from $x509 based on given position/index.
6705 my $rv = Net::SSLeay::X509_get_ext($x509, $index);
6707 # $x509 - value corresponding to openssl's X509 structure
6708 # $index - (integer) position/index of extension within $x509
6709 #
6710 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6711 • X509_get_ext_by_NID
6713 Returns X509_EXTENSION from $x509 based on given NID.
6715 my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
6717 # $x509 - value corresponding to openssl's X509 structure
6718 # $nid - (integer) NID value
6719 # $loc - (integer) position to start lookup at
6720 #
6721 # returns: position/index of extension, negative value on error
6722 # call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
6723 • X509_get_fingerprint
6725 Returns fingerprint of certificate $cert.
6727 NOTE: Does not exactly correspond to any low level API function.
6729 The implementation is based on openssl's X509_digest().
6730 Net::SSLeay::X509_get_fingerprint($x509, $type);
6732 # $x509 - value corresponding to openssl's X509 structure
6733 # $type - (string) digest type, currently supported values:
6734 # "md5"
6735 # "sha1"
6736 # "sha256"
6737 # "ripemd160"
6738 #
6739 # returns: certificate digest - hexadecimal string (NOT binary data!)
6740 • X509_get_issuer_name
6742 Return an X509_NAME object representing the issuer of the
6744 certificate $cert.
6745 my $rv = Net::SSLeay::X509_get_issuer_name($cert);
6747 # $cert - value corresponding to openssl's X509 structure
6748 #
6749 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6750 • X509_get_notAfter
6752 Return an object giving the time after which the certificate $cert
6754 is not valid.
6755 my $rv = Net::SSLeay::X509_get_notAfter($cert);
6757 # $cert - value corresponding to openssl's X509 structure
6758 #
6759 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6760 To get human readable/printable form the return value you can use:
6762 my $time = Net::SSLeay::X509_get_notAfter($cert);
6764 print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6765 • X509_get_notBefore
6767 Return an object giving the time before which the certificate $cert
6769 is not valid
6770 my $rv = Net::SSLeay::X509_get_notBefore($cert);
6772 # $cert - value corresponding to openssl's X509 structure
6773 #
6774 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6775 To get human readable/printable form the return value you can use:
6777 my $time = Net::SSLeay::X509_get_notBefore($cert);
6779 print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6780 • X509_get_subjectAltNames
6782 NOTE: Does not exactly correspond to any low level API function.
6784 Returns the list of alternative subject names from X509 certificate
6786 $cert.
6787 my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
6789 # $cert - value corresponding to openssl's X509 structure
6790 #
6791 # returns: list containing pairs - name_type (integer), name_value (string)
6792 # where name_type can be:
6793 # 0 - GEN_OTHERNAME
6794 # 1 - GEN_EMAIL
6795 # 2 - GEN_DNS
6796 # 3 - GEN_X400
6797 # 4 - GEN_DIRNAME
6798 # 5 - GEN_EDIPARTY
6799 # 6 - GEN_URI
6800 # 7 - GEN_IPADD
6801 # 8 - GEN_RID
6802 Note: type 7 - GEN_IPADD contains the IP address as a packed binary
6804 address. GEN_RID is available in Net-SSLeay-1.90 and later. Maximum
6805 length for returned RID string is currently 2500. Invalid and
6806 overly long RID values are skipped and not returned. GEN_X400 and
6807 GEN_EDIPARTY are not supported and will not be returned even when
6808 present in the certificate.
6809 • X509_get_subject_name
6811 Returns the subject of the certificate $cert.
6813 my $rv = Net::SSLeay::X509_get_subject_name($cert);
6815 # $cert - value corresponding to openssl's X509 structure
6816 #
6817 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6818 • X509_gmtime_adj
6820 Adjust th ASN1_TIME object to the timestamp (in GMT).
6822 my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
6824 # $s - value corresponding to openssl's ASN1_TIME structure
6825 # $adj - timestamp (seconds since 1.1.1970)
6826 #
6827 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6828 BEWARE: this function may fail for dates after 2038 as it is
6830 dependent on time_t size on your system (32bit time_t does not work
6831 after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
6832 • X509_load_cert_crl_file
6834 Takes PEM file and loads all X509 certificates and X509 CRLs from
6836 that file into X509_LOOKUP structure.
6837 my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
6839 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6840 # $file - (string) file name
6841 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6842 # if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
6843 #
6844 # returns: 1 on success, 0 on failure
6845 • X509_load_cert_file
6847 Loads/adds X509 certificate from $file to X509_LOOKUP structure
6849 my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
6851 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6852 # $file - (string) file name
6853 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6854 #
6855 # returns: 1 on success, 0 on failure
6856 • X509_load_crl_file
6858 Loads/adds X509 CRL from $file to X509_LOOKUP structure
6860 my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
6862 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6863 # $file - (string) file name
6864 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6865 #
6866 # returns: 1 on success, 0 on failure
6867 • X509_policy_level_get0_node
6869 ??? (more info needed)
6871 my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
6873 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6874 # $i - (integer) index/position
6875 #
6876 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6877 • X509_policy_level_node_count
6879 ??? (more info needed)
6881 my $rv = Net::SSLeay::X509_policy_level_node_count($level);
6883 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6884 #
6885 # returns: (integer) node count
6886 • X509_policy_node_get0_parent
6888 ??? (more info needed)
6890 my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
6892 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6893 #
6894 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6895 • X509_policy_node_get0_policy
6897 ??? (more info needed)
6899 my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
6901 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6902 #
6903 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6904 • X509_policy_node_get0_qualifiers
6906 ??? (more info needed)
6908 my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
6910 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6911 #
6912 # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
6913 • X509_policy_tree_free
6915 ??? (more info needed)
6917 Net::SSLeay::X509_policy_tree_free($tree);
6919 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6920 #
6921 # returns: no return value
6922 • X509_policy_tree_get0_level
6924 ??? (more info needed)
6926 my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
6928 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6929 # $i - (integer) level index
6930 #
6931 # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
6932 • X509_policy_tree_get0_policies
6934 ??? (more info needed)
6936 my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
6938 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6939 #
6940 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6941 • X509_policy_tree_get0_user_policies
6943 ??? (more info needed)
6945 my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
6947 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6948 #
6949 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6950 • X509_policy_tree_level_count
6952 ??? (more info needed)
6954 my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
6956 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6957 #
6958 # returns: (integer) count
6959 • X509_verify_cert_error_string
6961 Returns a human readable error string for verification error $n.
6963 my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6965 # $n - (long) numeric error code
6966 #
6967 # returns: error string
6968 Check openssl doc
6970 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6971 • P_X509_add_extensions
6973 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6975 Adds one or more X509 extensions to X509 object $x.
6977 my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
6979 # $x - value corresponding to openssl's X509 structure
6980 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
6981 # $nid - NID identifying extension to be set
6982 # $value - extension value
6983 #
6984 # returns: 1 on success, 0 on failure
6985 You can set more extensions at once:
6987 my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
6989 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6990 &Net::SSLeay::NID_subject_key_identifier => 'hash',
6991 &Net::SSLeay::NID_authority_key_identifier => 'keyid',
6992 &Net::SSLeay::NID_authority_key_identifier => 'issuer',
6993 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6994 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6995 &Net::SSLeay::NID_netscape_cert_type => 'server',
6996 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
6997 );
6998 • P_X509_copy_extensions
7000 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7002 Copies X509 extensions from X509_REQ object to X509 object - handy
7004 when you need to turn X509_REQ into X509 certificate.
7005 Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
7007 # $x509_req - value corresponding to openssl's X509_REQ structure
7008 # $x509 - value corresponding to openssl's X509 structure
7009 # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
7010 #
7011 # returns: 1 on success, 0 on failure
7012 • P_X509_get_crl_distribution_points
7014 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7016 requires at least openssl-0.9.7
7017 Get the list of CRL distribution points from X509 certificate.
7019 my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
7021 # $x509 - value corresponding to openssl's X509 structure
7022 #
7023 # returns: list of distribution points (usually URLs)
7024 • P_X509_get_ext_key_usage
7026 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7028 requires at least openssl-0.9.7
7029 Gets the list of extended key usage of given X509 certificate
7031 $cert.
7032 my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
7034 # $cert - value corresponding to openssl's X509 structure
7035 # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
7036 #
7037 # returns: list of values
7038 Examples:
7040 my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
7042 # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
7043 my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
7045 # returns for example: (129, 130)
7046 my @extkeyusage_sn = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
7048 # returns for example: ("serverAuth", "clientAuth")
7049 my @extkeyusage_ln = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
7051 # returns for example: ("TLS Web Server Authentication", "TLS Web Client Authentication")
7052 • P_X509_get_key_usage
7054 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7056 Gets the list of key usage of given X509 certificate $cert.
7058 my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
7060 # $cert - value corresponding to openssl's X509 structure
7061 #
7062 # returns: list of key usage values which can be none, one or more from the following list:
7063 # "digitalSignature"
7064 # "nonRepudiation"
7065 # "keyEncipherment"
7066 # "dataEncipherment"
7067 # "keyAgreement"
7068 # "keyCertSign"
7069 # "cRLSign"
7070 # "encipherOnly"
7071 # "decipherOnly"
7072 • P_X509_get_netscape_cert_type
7074 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7076 Gets the list of Netscape cert types of given X509 certificate
7078 $cert.
7079 Net::SSLeay::P_X509_get_netscape_cert_type($cert);
7081 # $cert - value corresponding to openssl's X509 structure
7082 #
7083 # returns: list of Netscape type values which can be none, one or more from the following list:
7084 # "client"
7085 # "server"
7086 # "email"
7087 # "objsign"
7088 # "reserved"
7089 # "sslCA"
7090 # "emailCA"
7091 # "objCA"
7092 • P_X509_get_pubkey_alg
7094 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7096 Returns ASN1_OBJECT corresponding to X509 certificate public key
7098 algorithm.
7099 my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
7101 # $x - value corresponding to openssl's X509 structure
7102 #
7103 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7104 To get textual representation use:
7106 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
7108 # returns for example: "rsaEncryption"
7109 • P_X509_get_signature_alg
7111 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7113 Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
7115 my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
7117 # $x - value corresponding to openssl's X509 structure
7118 #
7119 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7120 To get textual representation use:
7122 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
7124 # returns for example: "sha1WithRSAEncryption"
7125 • sk_X509_new_null
7127 Returns a new, empty, STACK_OF(X509) structure.
7129 my $rv = Net::SSLeay::sk_X509_new_null();
7131 #
7132 # returns: value corresponding to openssl's STACK_OF(X509) structure
7133 • sk_X509_push
7135 Pushes an X509 structure onto a STACK_OF(X509) structure.
7137 my $rv = Net::SSLeay::sk_X509_push($sk_x509, $x509);
7139 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7140 # $x509 - value corresponding to openssl's X509 structure
7141 #
7142 # returns: total number of elements after the operation, 0 on failure
7143 • sk_X509_pop
7145 Pops an single X509 structure from a STACK_OF(X509) structure.
7147 my $x509 = NetSSLeay::sk_X509_pop($sk_x509)
7149 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7150 #
7151 # returns: a pointer to an X509 structure, undef on failure
7152 Check openssl doc
7154 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_pop.html>
7155 • sk_X509_shift
7157 Shifts an single X509 structure onto a STACK_OF(X509) structure.
7159 my $x509 = NetSSLeay::sk_X509_shift($sk_x509, $x509)
7161 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7162 # $x509 - value corresponding to openssl's X509 structure
7163 #
7164 # returns: a pointer to an X509 structure, undef on failure
7165 Check openssl doc
7167 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_shift.html>
7168 • sk_X509_unshift
7170 Unshifts an single X509 structure from a STACK_OF(X509) structure.
7172 my $rv = NetSSLeay::sk_X509_unshift($sk_x509)
7174 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7175 #
7176 # returns: total number of elements after the operation, 0 on failure
7177 Check openssl doc
7179 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_unshift.html>
7180 • sk_X509_insert
7182 Inserts a single X509 structure into a STACK_OF(X509) at the
7184 specified index.
7185 my $rv = Net::SSLeay::sk_X509_insert($sk_x509, $x509, index);
7187 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7188 # $x509 - value corresponding to openssl's X509 structure
7189 # index - integer - 0 based index
7190 #
7191 # returns: total number of elements after the operation, 0 on failure
7192 Check openssl doc
7194 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_insert.html>
7195 • sk_X509_delete
7197 Delete a single X509 structure from a STACK_OF(X509) at the
7199 specified index.
7200 my $x509 = Net::SSLeay::sk_X509_delete($sk_x509, index);
7202 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7203 # index - integer - 0 based index
7204 #
7205 # returns: a pointer to an X509 structure, undef on failure
7206 Check openssl doc
7208 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_delete.html>
7209 • sk_X509_value
7211 Return a single X509 structure from a STACK_OF(X509) at the
7213 specified index.
7214 my $x509 = Net::SSLeay::sk_X509_value($sk_x509, index)
7216 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7217 # index - integer - 0 based index
7218 #
7219 # returns: a pointer to an X509 structure, undef on failure
7220 Check openssl doc
7222 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_value.html>
7223 • sk_X509_num
7225 Return the number of X509 elements in a STACK_OF(X509).
7227 my $num = Net::SSLeay::sk_X509_num($sk_x509);
7229 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7230 #
7231 # returns: the number of elements in the stack, -1 if the passed stack is NULL
7232 Check openssl doc
7234 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_num.html>
7235 Low level API: X509_REQ_* related functions
7237 • X509_REQ_new
7239 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7241 Creates a new X509_REQ structure.
7243 my $rv = Net::SSLeay::X509_REQ_new();
7245 #
7246 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
7247 • X509_REQ_free
7249 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7251 Free an allocated X509_REQ structure.
7253 Net::SSLeay::X509_REQ_free($x);
7255 # $x - value corresponding to openssl's X509_REQ structure
7256 #
7257 # returns: no return value
7258 • X509_REQ_add1_attr_by_NID
7260 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7262 Adds an attribute whose name is defined by a NID $nid. The field
7264 value to be added is in $bytes.
7265 my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
7267 # $req - value corresponding to openssl's X509_REQ structure
7268 # $nid - (integer) NID value
7269 # $type - (integer) type of data in $bytes (see below)
7270 # $bytes - data to be set
7271 #
7272 # returns: 1 on success, 0 on failure
7273 # values for $type - use constants:
7275 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7276 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7277 • X509_REQ_digest
7279 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7281 Computes digest/fingerprint of X509_REQ $data using $type hash
7283 function.
7284 my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
7286 # $data - value corresponding to openssl's X509_REQ structure
7287 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7288 #
7289 # returns: hash value (binary)
7290 #to get printable (hex) value of digest use:
7292 print unpack('H*', $digest_value);
7293 • X509_REQ_get_attr_by_NID
7295 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7297 Retrieve the next index matching $nid after $lastpos ($lastpos
7299 should initially be set to -1).
7300 my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
7302 # $req - value corresponding to openssl's X509_REQ structure
7303 # $nid - (integer) NID value
7304 # $lastpos - [optional] (integer) index where to start search (default -1)
7305 #
7306 # returns: index (-1 if there are no more entries)
7307 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7309 e.g.
7310 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
7312 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
7313 • X509_REQ_get_attr_by_OBJ
7315 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7317 Retrieve the next index matching $obj after $lastpos ($lastpos
7319 should initially be set to -1).
7320 my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
7322 # $req - value corresponding to openssl's X509_REQ structure
7323 # $obj - value corresponding to openssl's ASN1_OBJECT structure
7324 # $lastpos - [optional] (integer) index where to start search (default -1)
7325 #
7326 # returns: index (-1 if there are no more entries)
7327 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7329 e.g.
7330 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
7332 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
7333 • X509_REQ_get_attr_count
7335 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7337 Returns the total number of attributes in $req.
7339 my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
7341 # $req - value corresponding to openssl's X509_REQ structure
7342 #
7343 # returns: (integer) items count
7344 • X509_REQ_get_pubkey
7346 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7348 Returns public key corresponding to given X509_REQ object $x.
7350 my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
7352 # $x - value corresponding to openssl's X509_REQ structure
7353 #
7354 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
7355 • X509_REQ_get_subject_name
7357 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7359 Returns X509_NAME object corresponding to subject name of given
7361 X509_REQ object $x.
7362 my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
7364 # $x - value corresponding to openssl's X509_REQ structure
7365 #
7366 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7367 • X509_REQ_get_version
7369 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7371 Returns 'version' value for given X509_REQ object $x.
7373 my $rv = Net::SSLeay::X509_REQ_get_version($x);
7375 # $x - value corresponding to openssl's X509_REQ structure
7376 #
7377 # returns: (integer) version e.g. 0 = "version 1"
7378 • X509_REQ_set_pubkey
7380 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7382 Sets public key of given X509_REQ object $x to $pkey.
7384 my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
7386 # $x - value corresponding to openssl's X509_REQ structure
7387 # $pkey - value corresponding to openssl's EVP_PKEY structure
7388 #
7389 # returns: 1 on success, 0 on failure
7390 • X509_REQ_set_subject_name
7392 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7394 Sets subject name of given X509_REQ object $x to X509_NAME object
7396 $name.
7397 my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
7399 # $x - value corresponding to openssl's X509_REQ structure
7400 # $name - value corresponding to openssl's X509_NAME structure
7401 #
7402 # returns: 1 on success, 0 on failure
7403 • X509_REQ_set_version
7405 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7407 Sets 'version' of given X509_REQ object $x to $version.
7409 my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
7411 # $x - value corresponding to openssl's X509_REQ structure
7412 # $version - (integer) e.g. 0 = "version 1"
7413 #
7414 # returns: 1 on success, 0 on failure
7415 • X509_REQ_sign
7417 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7419 Sign X509_REQ object $x with private key $pk (using digest
7421 algorithm $md).
7422 my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
7424 # $x - value corresponding to openssl's X509_REQ structure
7425 # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
7426 # $md - value corresponding to openssl's EVP_MD structure
7427 #
7428 # returns: 1 on success, 0 on failure
7429 • X509_REQ_verify
7431 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7433 Verifies X509_REQ object $x using public key $r (pubkey of
7435 requesting party).
7436 my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
7438 # $x - value corresponding to openssl's X509_REQ structure
7439 # $r - value corresponding to openssl's EVP_PKEY structure
7440 #
7441 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7442 • P_X509_REQ_add_extensions
7444 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7446 Adds one or more X509 extensions to X509_REQ object $x.
7448 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
7450 # $x - value corresponding to openssl's X509_REQ structure
7451 # $nid - NID identifying extension to be set
7452 # $value - extension value
7453 #
7454 # returns: 1 on success, 0 on failure
7455 You can set more extensions at once:
7457 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
7459 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
7460 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
7461 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
7462 &Net::SSLeay::NID_netscape_cert_type => 'server',
7463 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
7464 &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
7465 );
7466 • P_X509_REQ_get_attr
7468 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7470 requires at least openssl-0.9.7
7471 Returns attribute value for X509_REQ's attribute at index $n.
7473 Net::SSLeay::P_X509_REQ_get_attr($req, $n);
7475 # $req - value corresponding to openssl's X509_REQ structure
7476 # $n - (integer) attribute index
7477 #
7478 # returns: value corresponding to openssl's ASN1_STRING structure
7479 Low level API: X509_CRL_* related functions
7481 • X509_CRL_new
7483 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7485 Creates a new X509_CRL structure.
7487 my $rv = Net::SSLeay::X509_CRL_new();
7489 #
7490 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
7491 • X509_CRL_free
7493 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7495 Free an allocated X509_CRL structure.
7497 Net::SSLeay::X509_CRL_free($x);
7499 # $x - value corresponding to openssl's X509_CRL structure
7500 #
7501 # returns: no return value
7502 • X509_CRL_digest
7504 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7506 Computes digest/fingerprint of X509_CRL $data using $type hash
7508 function.
7509 my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
7511 # $data - value corresponding to openssl's X509_CRL structure
7512 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7513 #
7514 # returns: hash value (binary)
7515 Example:
7517 my $x509_crl
7519 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7520 my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
7521 #to get printable (hex) value of digest use:
7522 print "digest=", unpack('H*', $digest_value), "\n";
7523 • X509_CRL_get_ext
7525 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7527 Returns X509_EXTENSION from $x509 based on given position/index.
7529 my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
7531 # $x509 - value corresponding to openssl's X509_CRL structure
7532 # $index - (integer) position/index of extension within $x509
7533 #
7534 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
7535 • X509_CRL_get_ext_by_NID
7537 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7539 Returns X509_EXTENSION from $x509 based on given NID.
7541 my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
7543 # $x509 - value corresponding to openssl's X509_CRL structure
7544 # $nid - (integer) NID value
7545 # $loc - (integer) position to start lookup at
7546 #
7547 # returns: position/index of extension, negative value on error
7548 # call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
7549 • X509_CRL_get_ext_count
7551 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7553 Returns the total number of extensions in X509_CRL object $x.
7555 my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
7557 # $x - value corresponding to openssl's X509_CRL structure
7558 #
7559 # returns: count of extensions
7560 • X509_CRL_get_issuer
7562 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7564 Returns X509_NAME object corresponding to the issuer of X509_CRL
7566 $x.
7567 my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
7569 # $x - value corresponding to openssl's X509_CRL structure
7570 #
7571 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7572 See other "X509_NAME_*" functions to get more info from X509_NAME
7574 structure.
7575 • X509_CRL_get_lastUpdate
7577 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7579 Returns 'lastUpdate' date-time value of X509_CRL object $x.
7581 my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
7583 # $x - value corresponding to openssl's X509_CRL structure
7584 #
7585 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7586 • X509_CRL_get_nextUpdate
7588 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7590 Returns 'nextUpdate' date-time value of X509_CRL object $x.
7592 my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
7594 # $x - value corresponding to openssl's X509_CRL structure
7595 #
7596 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7597 • X509_CRL_get_version
7599 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7601 Returns 'version' value of given X509_CRL structure $x.
7603 my $rv = Net::SSLeay::X509_CRL_get_version($x);
7605 # $x - value corresponding to openssl's X509_CRL structure
7606 #
7607 # returns: (integer) version
7608 • X509_CRL_set_issuer_name
7610 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7612 requires at least openssl-0.9.7
7613 Sets the issuer of X509_CRL object $x to X509_NAME object $name.
7615 my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
7617 # $x - value corresponding to openssl's X509_CRL structure
7618 # $name - value corresponding to openssl's X509_NAME structure
7619 #
7620 # returns: 1 on success, 0 on failure
7621 • X509_CRL_set_lastUpdate
7623 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7625 requires at least openssl-0.9.7
7626 Sets 'lastUpdate' value of X509_CRL object $x to $tm.
7628 my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
7630 # $x - value corresponding to openssl's X509_CRL structure
7631 # $tm - value corresponding to openssl's ASN1_TIME structure
7632 #
7633 # returns: 1 on success, 0 on failure
7634 • X509_CRL_set_nextUpdate
7636 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7638 requires at least openssl-0.9.7
7639 Sets 'nextUpdate' value of X509_CRL object $x to $tm.
7641 my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
7643 # $x - value corresponding to openssl's X509_CRL structure
7644 # $tm - value corresponding to openssl's ASN1_TIME structure
7645 #
7646 # returns: 1 on success, 0 on failure
7647 • X509_CRL_set_version
7649 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7651 requires at least openssl-0.9.7
7652 Sets 'version' value of given X509_CRL structure $x to $version.
7654 my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
7656 # $x - value corresponding to openssl's X509_CRL structure
7657 # $version - (integer) version number (1 = version 2 CRL)
7658 #
7659 # returns: 1 on success, 0 on failure
7660 Note that if you want to use any X509_CRL extension you need to set
7662 "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
7663 • X509_CRL_sign
7665 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7667 Sign X509_CRL object $x with private key $pkey (using digest
7669 algorithm $md).
7670 my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
7672 # $x - value corresponding to openssl's X509_CRL structure
7673 # $pkey - value corresponding to openssl's EVP_PKEY structure
7674 # $md - value corresponding to openssl's EVP_MD structure
7675 #
7676 # returns: 1 on success, 0 on failure
7677 • X509_CRL_sort
7679 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7681 requires at least openssl-0.9.7
7682 Sorts the data of X509_CRL object so it will be written in serial
7684 number order.
7685 my $rv = Net::SSLeay::X509_CRL_sort($x);
7687 # $x - value corresponding to openssl's X509_CRL structure
7688 #
7689 # returns: 1 on success, 0 on failure
7690 • X509_CRL_verify
7692 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7694 Verifies X509_CRL object $a using public key $r (pubkey of issuing
7696 CA).
7697 my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
7699 # $a - value corresponding to openssl's X509_CRL structure
7700 # $r - value corresponding to openssl's EVP_PKEY structure
7701 #
7702 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7703 • P_X509_CRL_add_revoked_serial_hex
7705 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7707 requires at least openssl-0.9.7
7708 Adds given serial number $serial_hex to X509_CRL object $crl.
7710 Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
7712 # $crl - value corresponding to openssl's X509_CRL structure
7713 # $serial_hex - string (hexadecimal) representation of serial number
7714 # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
7715 # $reason_code - [optional] (integer) reason code (see below) - default 0
7716 # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
7717 #
7718 # returns: no return value
7719 reason codes:
7721 0 - unspecified
7722 1 - keyCompromise
7723 2 - CACompromise
7724 3 - affiliationChanged
7725 4 - superseded
7726 5 - cessationOfOperation
7727 6 - certificateHold
7728 7 - removeFromCRL
7729 • P_X509_CRL_get_serial
7731 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7733 requires at least openssl-0.9.7
7734 Returns serial number of X509_CRL object.
7736 my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
7738 # $crl - value corresponding to openssl's X509_CRL structure
7739 #
7740 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
7741 • P_X509_CRL_set_serial
7743 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7745 requires at least openssl-0.9.7
7746 Sets serial number of X509_CRL object to $crl_number.
7748 my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
7750 # $crl - value corresponding to openssl's X509_CRL structure
7751 # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
7752 #
7753 # returns: 1 on success, 0 on failure
7754 • P_X509_CRL_add_extensions
7756 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
7758 Adds one or more X509 extensions to X509 CRL object $x.
7760 my $rv = Net::SSLeay::P_X509_CRL_add_extensions($x, $ca_cert, $nid, $value);
7762 # $x - value corresponding to openssl's X509 CRL structure
7763 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
7764 # $nid - NID identifying extension to be set
7765 # $value - extension value
7766 #
7767 # returns: 1 on success, 0 on failure
7768 For more details see "P_X509_add_extensions".
7770 Low level API: X509_EXTENSION_* related functions
7772 • X509_EXTENSION_get_critical
7774 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7776 Returns 'critical' flag of given X509_EXTENSION object $ex.
7778 my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
7780 # $ex - value corresponding to openssl's X509_EXTENSION structure
7781 #
7782 # returns: (integer) 1 - critical, 0 - noncritical
7783 • X509_EXTENSION_get_data
7785 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7787 Returns value (raw data) of X509_EXTENSION object $ne.
7789 my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
7791 # $ne - value corresponding to openssl's X509_EXTENSION structure
7792 #
7793 # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
7794 Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
7796 into perl scalar variable.
7797 • X509_EXTENSION_get_object
7799 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7801 Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
7803 my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
7805 # $ex - value corresponding to openssl's X509_EXTENSION structure
7806 #
7807 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7808 • X509V3_EXT_print
7810 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7812 Returns string representation of given X509_EXTENSION object $ext.
7814 Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
7816 # $ext - value corresponding to openssl's X509_EXTENSION structure
7817 # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
7818 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7819 #
7820 # returns: no return value
7821 • X509V3_EXT_d2i
7823 Parses an extension and returns its internal structure.
7825 my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
7827 # $ext - value corresponding to openssl's X509_EXTENSION structure
7828 #
7829 # returns: pointer ???
7830 Low level API: X509_NAME_* related functions
7832 • X509_NAME_ENTRY_get_data
7834 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7836 Retrieves the field value of $ne in and ASN1_STRING structure.
7838 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
7840 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7841 #
7842 # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
7843 Check openssl doc
7845 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7846 • X509_NAME_ENTRY_get_object
7848 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7850 Retrieves the field name of $ne in and ASN1_OBJECT structure.
7852 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
7854 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7855 #
7856 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7857 Check openssl doc
7859 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7860 • X509_NAME_new
7862 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7864 requires at least openssl-0.9.5
7865 Creates a new X509_NAME structure. Adds a field whose name is
7867 defined by a string $field. The field value to be added is in
7868 $bytes.
7869 my $rv = Net::SSLeay::X509_NAME_new();
7871 #
7872 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7873 • X509_NAME_hash
7875 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7877 requires at least openssl-0.9.5
7878 Sort of a checksum of issuer name $name. The result is not a full
7880 hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
7881 'unsigned long' (32 bits). The resulting value might differ across
7882 different openssl versions for the same X509 certificate.
7883 my $rv = Net::SSLeay::X509_NAME_hash($name);
7885 # $name - value corresponding to openssl's X509_NAME structure
7886 #
7887 # returns: number representing checksum
7888 • X509_NAME_add_entry_by_txt
7890 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7892 requires at least openssl-0.9.5
7893 Adds a field whose name is defined by a string $field. The field
7895 value to be added is in $bytes.
7896 my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
7898 # $name - value corresponding to openssl's X509_NAME structure
7899 # $field - (string) field definition (name) - e.g. "organizationName"
7900 # $type - (integer) type of data in $bytes (see below)
7901 # $bytes - data to be set
7902 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7903 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7904 #
7905 # returns: 1 on success, 0 on failure
7906 # values for $type - use constants:
7908 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7909 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7910 Unicode note: when passing non-ascii (unicode) string in $bytes do
7912 not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
7913 the perl $string via "$bytes = encode('utf-8', $string)".
7914 Check openssl doc
7916 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7917 • X509_NAME_add_entry_by_NID
7919 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7921 requires at least openssl-0.9.5
7922 Adds a field whose name is defined by a NID $nid. The field value
7924 to be added is in $bytes.
7925 my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
7927 # $name - value corresponding to openssl's X509_NAME structure
7928 # $nid - (integer) field definition - NID value
7929 # $type - (integer) type of data in $bytes (see below)
7930 # $bytes - data to be set
7931 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7932 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7933 #
7934 # returns: 1 on success, 0 on failure
7935 Check openssl doc
7937 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7938 • X509_NAME_add_entry_by_OBJ
7940 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7942 requires at least openssl-0.9.5
7943 Adds a field whose name is defined by a object (OID) $obj . The
7945 field value to be added is in $bytes.
7946 my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
7948 # $name - value corresponding to openssl's X509_NAME structure
7949 # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
7950 # $type - (integer) type of data in $bytes (see below)
7951 # $bytes - data to be set
7952 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7953 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7954 #
7955 # returns: 1 on success, 0 on failure
7956 Check openssl doc
7958 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7959 • X509_NAME_cmp
7961 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7963 Compares two X509_NAME obejcts.
7965 my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
7967 # $a - value corresponding to openssl's X509_NAME structure
7968 # $b - value corresponding to openssl's X509_NAME structure
7969 #
7970 # returns: 0 if $a matches $b; non zero otherwise
7971 • X509_NAME_digest
7973 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7975 Computes digest/fingerprint of X509_NAME $data using $type hash
7977 function.
7978 my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
7980 # $data - value corresponding to openssl's X509_NAME structure
7981 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7982 #
7983 # returns: hash value (binary)
7984 #to get printable (hex) value of digest use:
7986 print unpack('H*', $digest_value);
7987 • X509_NAME_entry_count
7989 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7991 Returns the total number of entries in $name.
7993 my $rv = Net::SSLeay::X509_NAME_entry_count($name);
7995 # $name - value corresponding to openssl's X509_NAME structure
7996 #
7997 # returns: (integer) entries count
7998 Check openssl doc
8000 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8001 • X509_NAME_get_entry
8003 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8005 Retrieves the X509_NAME_ENTRY from $name corresponding to index
8007 $loc. Acceptable values for $loc run from 0 to
8008 "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
8009 is an internal pointer which must not be freed.
8010 my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
8012 # $name - value corresponding to openssl's X509_NAME structure
8013 # $loc - (integer) index of wanted entry
8014 #
8015 # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
8016 Check openssl doc
8018 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8019 • X509_NAME_print_ex
8021 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8023 Returns a string with human readable version of $name.
8025 Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
8027 # $name - value corresponding to openssl's X509_NAME structure
8028 # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
8029 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
8030 #
8031 # returns: string representation of $name
8032 #available conversion flags - use constants:
8034 &Net::SSLeay::XN_FLAG_COMPAT
8035 &Net::SSLeay::XN_FLAG_DN_REV
8036 &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
8037 &Net::SSLeay::XN_FLAG_FN_ALIGN
8038 &Net::SSLeay::XN_FLAG_FN_LN
8039 &Net::SSLeay::XN_FLAG_FN_MASK
8040 &Net::SSLeay::XN_FLAG_FN_NONE
8041 &Net::SSLeay::XN_FLAG_FN_OID
8042 &Net::SSLeay::XN_FLAG_FN_SN
8043 &Net::SSLeay::XN_FLAG_MULTILINE
8044 &Net::SSLeay::XN_FLAG_ONELINE
8045 &Net::SSLeay::XN_FLAG_RFC2253
8046 &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
8047 &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
8048 &Net::SSLeay::XN_FLAG_SEP_MASK
8049 &Net::SSLeay::XN_FLAG_SEP_MULTILINE
8050 &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
8051 &Net::SSLeay::XN_FLAG_SPC_EQ
8052 Most likely you will be fine with default:
8054 Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
8056 Or you might want RFC2253-like output without utf8 chars escaping:
8058 use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
8060 my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
8061 my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
8062 Check openssl doc
8064 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8065 • X509_NAME_get_text_by_NID
8067 Retrieves the text from the first entry in name which matches $nid,
8069 if no such entry exists -1 is returned.
8070 openssl note: this is a legacy function which has various
8072 limitations which makes it of minimal use in practice. It can only
8073 find the first matching entry and will copy the contents of the
8074 field verbatim: this can be highly confusing if the target is a
8075 multicharacter string type like a BMPString or a UTF8String.
8076 Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
8078 # $name - value corresponding to openssl's X509_NAME structure
8079 # $nid - NID value (integer)
8080 #
8081 # returns: text value
8082 Check openssl doc
8084 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8085 • X509_NAME_oneline
8087 Return an ASCII version of $name.
8089 Net::SSLeay::X509_NAME_oneline($name);
8091 # $name - value corresponding to openssl's X509_NAME structure
8092 #
8093 # returns: (string) ASCII version of $name
8094 Check openssl doc
8096 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8097 • sk_X509_NAME_free
8099 Free an allocated STACK_OF(X509_NAME) structure.
8101 Net::SSLeay::sk_X509_NAME_free($sk);
8103 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8104 #
8105 # returns: no return value
8106 • sk_X509_NAME_num
8108 Return number of items in STACK_OF(X509_NAME)
8110 my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
8112 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8113 #
8114 # returns: number of items
8115 • sk_X509_NAME_value
8117 Returns X509_NAME from position $index in STACK_OF(X509_NAME)
8119 my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
8121 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8122 # $i - (integer) index/position
8123 #
8124 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
8125 • add_file_cert_subjects_to_stack
8127 Add a file of certs to a stack. All certs in $file that are not
8129 already in the $stackCAs will be added.
8130 my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
8132 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
8133 # $file - (string) filename
8134 #
8135 # returns: 1 on success, 0 on failure
8136 • add_dir_cert_subjects_to_stack
8138 Add a directory of certs to a stack. All certs in $dir that are not
8140 already in the $stackCAs will be added.
8141 my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
8143 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
8144 # $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.
8145 #
8146 # returns: 1 on success, 0 on failure
8147 Low level API: X509_STORE_* related functions
8149 • X509_STORE_CTX_new
8151 returns a newly initialised X509_STORE_CTX structure.
8153 • X509_STORE_CTX_init
8155 X509_STORE_CTX_init() sets up an X509_STORE_CTX for a subsequent
8157 verification operation. It must be called before each call to
8158 X509_verify_cert().
8159 my $rv = Net::SSLeay::X509_STORE_CTX_init($x509_store_ctx, $x509_store, $x509, $chain);
8161 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure (required)
8162 # $x509_store - value corresponding to openssl's X509_STORE structure (optional)
8163 # $x509 - value corresponding to openssl's X509 structure (optional)
8164 # $chain - value corresponding to openssl's STACK_OF(X509) structure (optional)
8165 #
8166 # returns: 1 on success, 0 on failure
8167 #
8168 # Note: returns nothing with Net::SSLeay 1.90 and earlier.
8169 Check openssl doc
8171 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_init.html>
8172 • X509_STORE_CTX_free
8174 Frees an X509_STORE_CTX structure.
8176 Net::SSLeay::X509_STORE_CTX_free($x509_store_ctx);
8178 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
8180 structure
8181 • X509_verify_cert
8183 The X509_verify_cert() function attempts to discover and validate a
8185 certificate chain based on parameters in ctx. A complete
8186 description of the process is contained in the verify(1) manual
8187 page.
8188 If this function returns 0, use X509_STORE_CTX_get_error to get
8190 additional error information.
8191 my $rv = Net::SSLeay::X509_verify_cert($x509_store_ctx);
8193 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8194 #
8195 # returns: 1 if a complete chain can be built and validated, otherwise 0
8196 Check openssl doc
8198 <https://www.openssl.org/docs/manmaster/man3/X509_verify_cert.html>
8199 • X509_STORE_CTX_get_current_cert
8201 Returns the certificate in ctx which caused the error or 0 if no
8203 certificate is relevant.
8204 my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
8206 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8207 #
8208 # returns: value corresponding to openssl's X509 structure (0 on failure)
8209 Check openssl doc
8211 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8212 • X509_STORE_CTX_get0_cert
8214 COMPATIBILITY: not available in Net-SSLeay-1.88 and before;
8216 requires at least OpenSSL 1.1.0pre6 or LibreSSL 2.7.0
8217 Returns an internal pointer to the certificate being verified by
8219 the ctx.
8220 my $x509 = Net::SSLeay::X509_STORE_CTX_get0_cert($x509_store_ctx);
8222 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8223 #
8224 # returns: value corresponding to openssl's X509 structure
8225 Check openssl doc
8227 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get0_cert.html>
8228 • X509_STORE_CTX_get1_chain
8230 Returns a returns a complete validate chain if a previous call to
8232 X509_verify_cert() is successful.
8233 my $rv = Net::SSLeay::X509_STORE_CTX_get1_chain($x509_store_ctx);
8235 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8236 #
8237 # returns: value corresponding to openssl's STACK_OF(X509) structure
8238 Check openssl doc
8240 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get1_chain.html>
8241 • X509_STORE_CTX_get_error
8243 Returns the error code of $ctx.
8245 my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
8247 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8248 #
8249 # returns: (integer) error code
8250 For more info about erro code values check function
8252 "get_verify_result".
8253 Check openssl doc
8255 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8256 • X509_STORE_CTX_get_error_depth
8258 Returns the depth of the error. This is a non-negative integer
8260 representing where in the certificate chain the error occurred. If
8261 it is zero it occurred in the end entity certificate, one if it is
8262 the certificate which signed the end entity certificate and so on.
8263 my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
8265 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8266 #
8267 # returns: (integer) depth
8268 Check openssl doc
8270 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8271 • X509_STORE_CTX_get_ex_data
8273 Is used to retrieve the information for $idx from $x509_store_ctx.
8275 my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
8277 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8278 # $idx - (integer) index for application specific data
8279 #
8280 # returns: pointer to ???
8281 • X509_STORE_CTX_set_ex_data
8283 Is used to store application data at arg for idx into
8285 $x509_store_ctx.
8286 my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
8288 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8289 # $idx - (integer) ???
8290 # $data - (pointer) ???
8291 #
8292 # returns: 1 on success, 0 on failure
8293 • X509_STORE_CTX_set_cert
8295 Sets the certificate to be verified in $x509_store_ctx to $x.
8297 Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
8299 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8300 # $x - value corresponding to openssl's X509 structure
8301 #
8302 # returns: no return value
8303 Check openssl doc
8305 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
8306 • X509_STORE_new
8308 Returns a newly initialized X509_STORE structure.
8310 my $rv = Net::SSLeay::X509_STORE_new();
8312 #
8313 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
8314 • X509_STORE_free
8316 Frees an X509_STORE structure
8318 Net::SSLeay::X509_STORE_free($x509_store);
8320 # $x509_store - value corresponding to openssl's X509_STORE structure
8321 • X509_STORE_add_lookup
8323 Adds a lookup to an X509_STORE for a given lookup method.
8325 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir;
8327 my $rv = Net::SSLeay::X509_STORE_add_lookup($x509_store, $method);
8328 # $method - value corresponding to openssl's X509_LOOKUP_METHOD structure
8329 # $x509_store - value corresponding to openssl's X509_STORE structure
8330 #
8331 # returns: value corresponding to openssl's X509_LOOKUP structure
8332 Check openssl doc
8334 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_add_lookup.html>
8335 • X509_STORE_CTX_set_error
8337 Sets the error code of $ctx to $s. For example it might be used in
8339 a verification callback to set an error based on additional checks.
8340 Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
8342 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8343 # $s - (integer) error id
8344 #
8345 # returns: no return value
8346 Check openssl doc
8348 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8349 • X509_STORE_add_cert
8351 Adds X509 certificate $x into the X509_STORE $store.
8353 my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
8355 # $store - value corresponding to openssl's X509_STORE structure
8356 # $x - value corresponding to openssl's X509 structure
8357 #
8358 # returns: 1 on success, 0 on failure
8359 • X509_STORE_add_crl
8361 Adds X509 CRL $x into the X509_STORE $store.
8363 my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
8365 # $store - value corresponding to openssl's X509_STORE structure
8366 # $x - value corresponding to openssl's X509_CRL structure
8367 #
8368 # returns: 1 on success, 0 on failure
8369 • X509_STORE_set1_param
8371 ??? (more info needed)
8373 my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
8375 # $store - value corresponding to openssl's X509_STORE structure
8376 # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
8377 #
8378 # returns: 1 on success, 0 on failure
8379 • X509_LOOKUP_hash_dir
8381 Returns an X509_LOOKUP structure that instructs an X509_STORE to
8383 load files from a directory containing certificates with filenames
8384 in the format hash.N or crls with filenames in the format hash.rN
8385 my $rv = Net::SSLeay::X509_LOOKUP_hash_dir();
8387 #
8388 # returns: value corresponding to openssl's X509_LOOKUP_METHOD structure, with the hashed directory method
8389 Check openssl doc
8391 <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
8392 • X509_LOOKUP_add_dir
8394 Add a directory to an X509_LOOKUP structure, usually obtained from
8396 X509_STORE_add_lookup.
8397 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir;
8399 my $lookup = Net::SSLeay::X509_STORE_add_lookup($x509_store, $method);
8400 my $type = &Net::SSLeay::X509_FILETYPE_PEM;
8401 Net::SSLeay::X509_LOOKUP_add_dir($lookup, $dir, $type);
8402 # $lookup - value corresponding to openssl's X509_LOOKUP structure
8403 # $dir - string path to a directory
8404 # $type - constant corresponding to the type of file in the directory - can be X509_FILETYPE_PEM, X509_FILETYPE_DEFAULT, or X509_FILETYPE_ASN1
8405 • X509_STORE_set_flags
8407 Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
8409 # $ctx - value corresponding to openssl's X509_STORE structure
8410 # $flags - (unsigned long) flags to be set (bitmask)
8411 #
8412 # returns: no return value
8413 #to create $flags value use corresponding constants like
8415 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8416 For more details about $flags bitmask see
8418 "X509_VERIFY_PARAM_set_flags".
8419 • X509_STORE_set_purpose
8421 Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
8423 # $ctx - value corresponding to openssl's X509_STORE structure
8424 # $purpose - (integer) purpose identifier
8425 #
8426 # returns: no return value
8427 For more details about $purpose identifier check "CTX_set_purpose".
8429 • X509_STORE_set_trust
8431 Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
8433 # $ctx - value corresponding to openssl's X509_STORE structure
8434 # $trust - (integer) trust identifier
8435 #
8436 # returns: no return value
8437 For more details about $trust identifier check "CTX_set_trust".
8439 Low Level API: X509_INFO related functions
8441 • sk_X509_INFO_num
8443 Returns the number of values in a STACK_OF(X509_INFO) structure.
8445 my $rv = Net::SSLeay::sk_X509_INFO_num($sk_x509_info);
8447 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8448 #
8449 # returns: number of values in $sk_X509_info
8450 • sk_X509_INFO_value
8452 Returns the value of a STACK_OF(X509_INFO) structure at a given
8454 index.
8455 my $rv = Net::SSLeay::sk_X509_INFO_value($sk_x509_info, $index);
8457 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8458 # $index - index into the stack
8459 #
8460 # returns: value corresponding to openssl's X509_INFO structure at the given index
8461 • P_X509_INFO_get_x509
8463 Returns the X509 structure stored in an X509_INFO structure.
8465 my $rv = Net::SSLeay::P_X509_INFO_get_x509($x509_info);
8467 # $x509_info - value corresponding to openssl's X509_INFO structure
8468 #
8469 # returns: value corresponding to openssl's X509 structure
8470 Low level API: X509_VERIFY_PARAM_* related functions
8472 • X509_VERIFY_PARAM_add0_policy
8474 Enables policy checking (it is disabled by default) and adds
8476 $policy to the acceptable policy set.
8477 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
8479 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8480 # $policy - value corresponding to openssl's ASN1_OBJECT structure
8481 #
8482 # returns: 1 on success, 0 on failure
8483 Check openssl doc
8485 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8486 • X509_VERIFY_PARAM_add0_table
8488 ??? (more info needed)
8490 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
8492 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8493 #
8494 # returns: 1 on success, 0 on failure
8495 • X509_VERIFY_PARAM_add1_host
8497 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8499 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8500 Adds an additional reference identifier that can match the peer's
8502 certificate.
8503 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add1_host($param, $name);
8505 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8506 # $name - (string) name to be set
8507 #
8508 # returns: 1 on success, 0 on failure
8509 See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
8511 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8512 wildcard matching.
8513 Check openssl doc
8515 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8516 • X509_VERIFY_PARAM_clear_flags
8518 Clears the flags $flags in param.
8520 my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
8522 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8523 # $flags - (unsigned long) flags to be set (bitmask)
8524 #
8525 # returns: 1 on success, 0 on failure
8526 For more details about $flags bitmask see
8528 "X509_VERIFY_PARAM_set_flags".
8529 Check openssl doc
8531 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8532 • X509_VERIFY_PARAM_free
8534 Frees up the X509_VERIFY_PARAM structure.
8536 Net::SSLeay::X509_VERIFY_PARAM_free($param);
8538 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8539 #
8540 # returns: no return value
8541 • X509_VERIFY_PARAM_get0_peername
8543 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8545 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8546 Returns the DNS hostname or subject CommonName from the peer
8548 certificate that matched one of the reference identifiers.
8549 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get0_peername($param);
8551 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8552 #
8553 # returns: (string) name e.g. '*.example.com' or undef
8554 Check openssl doc
8556 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8557 • X509_VERIFY_PARAM_get_depth
8559 Returns the current verification depth.
8561 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
8563 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8564 #
8565 # returns: (ineger) depth
8566 Check openssl doc
8568 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8569 • X509_VERIFY_PARAM_get_flags
8571 Returns the current verification flags.
8573 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
8575 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8576 #
8577 # returns: (unsigned long) flags to be set (bitmask)
8578 For more details about returned flags bitmask see
8580 "X509_VERIFY_PARAM_set_flags".
8581 Check openssl doc
8583 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8584 • X509_VERIFY_PARAM_set_flags
8586 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
8588 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8589 # $flags - (unsigned long) flags to be set (bitmask)
8590 #
8591 # returns: 1 on success, 0 on failure
8592 #to create $flags value use corresponding constants like
8594 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8595 For more details about $flags bitmask, see the OpenSSL docs below.
8597 Check openssl doc
8599 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8600 • X509_VERIFY_PARAM_inherit
8602 ??? (more info needed)
8604 my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
8606 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8607 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8608 #
8609 # returns: 1 on success, 0 on failure
8610 • X509_VERIFY_PARAM_lookup
8612 Finds X509_VERIFY_PARAM by name.
8614 my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
8616 # $name - (string) name we want to find
8617 #
8618 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8619 • X509_VERIFY_PARAM_new
8621 Creates a new X509_VERIFY_PARAM structure.
8623 my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
8625 #
8626 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8627 • X509_VERIFY_PARAM_set1
8629 Sets the name of X509_VERIFY_PARAM structure $to to the same value
8631 as the name of X509_VERIFY_PARAM structure $from.
8632 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
8634 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8635 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8636 #
8637 # returns: 1 on success, 0 on failure
8638 • X509_VERIFY_PARAM_set1_email
8640 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8642 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8643 Sets the expected RFC822 email address to email.
8645 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_email($param, $email);
8647 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8648 # $email - (string) email to be set
8649 #
8650 # returns: 1 on success, 0 on failure
8651 Check openssl doc
8653 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8654 • X509_VERIFY_PARAM_set1_host
8656 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8658 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8659 Sets the expected DNS hostname to name clearing any previously
8661 specified host name or names.
8662 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_host($param, $name);
8664 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8665 # $name - (string) name to be set
8666 #
8667 # returns: 1 on success, 0 on failure
8668 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8670 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8671 wildcard matching.
8672 Check openssl doc
8674 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8675 • X509_VERIFY_PARAM_set1_ip
8677 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8679 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8680 Sets the expected IP address to ip.
8682 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_ip($param, $ip);
8684 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8685 # $ip - (binary) 4 octet IPv4 or 16 octet IPv6 address
8686 #
8687 # returns: 1 on success, 0 on failure
8688 Check openssl doc
8690 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8691 • X509_VERIFY_PARAM_set1_ip_asc
8693 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8695 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8696 Sets the expected IP address to ipasc.
8698 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_asc($param, $ipasc);
8700 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8701 # $ip - (string) IPv4 or IPv6 address
8702 #
8703 # returns: 1 on success, 0 on failure
8704 Check openssl doc
8706 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8707 • X509_VERIFY_PARAM_set1_name
8709 Sets the name of X509_VERIFY_PARAM structure $param to $name.
8711 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
8713 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8714 # $name - (string) name to be set
8715 #
8716 # returns: 1 on success, 0 on failure
8717 • X509_VERIFY_PARAM_set1_policies
8719 Enables policy checking (it is disabled by default) and sets the
8721 acceptable policy set to policies. Any existing policy set is
8722 cleared. The policies parameter can be 0 to clear an existing
8723 policy set.
8724 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
8726 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8727 # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
8728 #
8729 # returns: 1 on success, 0 on failure
8730 Check openssl doc
8732 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8733 • X509_VERIFY_PARAM_set_depth
8735 Sets the maximum verification depth to depth. That is the maximum
8737 number of untrusted CA certificates that can appear in a chain.
8738 Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
8740 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8741 # $depth - (integer) depth to be set
8742 #
8743 # returns: no return value
8744 Check openssl doc
8746 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8747 • X509_VERIFY_PARAM_set_hostflags
8749 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8751 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8752 Net::SSLeay::X509_VERIFY_PARAM_set_hostflags($param, $flags);
8754 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8755 # $flags - (unsigned int) flags to be set (bitmask)
8756 #
8757 # returns: no return value
8758 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8760 "X509_VERIFY_PARAM_set1_host" for more information. The flags for
8761 controlling wildcard checks and other features are defined in
8762 OpenSSL docs.
8763 Check openssl doc
8765 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8766 • X509_VERIFY_PARAM_set_purpose
8768 Sets the verification purpose in $param to $purpose. This
8770 determines the acceptable purpose of the certificate chain, for
8771 example SSL client or SSL server.
8772 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
8774 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8775 # $purpose - (integer) purpose identifier
8776 #
8777 # returns: 1 on success, 0 on failure
8778 For more details about $purpose identifier check "CTX_set_purpose".
8780 Check openssl doc
8782 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8783 • X509_VERIFY_PARAM_set_time
8785 Sets the verification time in $param to $t. Normally the current
8787 time is used.
8788 Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
8790 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8791 # $t - (time_t) time in seconds since 1.1.1970
8792 #
8793 # returns: no return value
8794 Check openssl doc
8796 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8797 • X509_VERIFY_PARAM_set_trust
8799 Sets the trust setting in $param to $trust.
8801 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
8803 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8804 # $trust - (integer) trust identifier
8805 #
8806 # returns: 1 on success, 0 on failure
8807 For more details about $trust identifier check "CTX_set_trust".
8809 Check openssl doc
8811 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8812 • X509_VERIFY_PARAM_table_cleanup
8814 ??? (more info needed)
8816 Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
8818 #
8819 # returns: no return value
8820 Low level API: Cipher (EVP_CIPHER_*) related functions
8822 • EVP_get_cipherbyname
8824 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8826 Returns an EVP_CIPHER structure when passed a cipher name.
8828 my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
8830 # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
8831 #
8832 # returns: value corresponding to openssl's EVP_CIPHER structure
8833 Check openssl doc
8835 <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
8836 Low level API: Digest (EVP_MD_*) related functions
8838 • OpenSSL_add_all_digests
8840 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8842 Net::SSLeay::OpenSSL_add_all_digests();
8844 # no args, no return value
8845 http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
8847 • P_EVP_MD_list_all
8849 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8851 requires at least openssl-1.0.0
8852 NOTE: Does not exactly correspond to any low level API function
8854 my $rv = Net::SSLeay::P_EVP_MD_list_all();
8856 #
8857 # returns: arrayref - list of available digest names
8858 The returned digest names correspond to values expected by
8860 "EVP_get_digestbyname".
8861 Note that some of the digests are available by default and some
8863 only after calling "OpenSSL_add_all_digests".
8864 • EVP_get_digestbyname
8866 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8868 my $rv = Net::SSLeay::EVP_get_digestbyname($name);
8870 # $name - string with digest name
8871 #
8872 # returns: value corresponding to openssl's EVP_MD structure
8873 The $name param can be:
8875 md2
8877 md4
8878 md5
8879 mdc2
8880 ripemd160
8881 sha
8882 sha1
8883 sha224
8884 sha256
8885 sha512
8886 whirlpool
8887 Or better check the supported digests by calling
8889 "P_EVP_MD_list_all".
8890 • EVP_MD_type
8892 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8894 my $rv = Net::SSLeay::EVP_MD_type($md);
8896 # $md - value corresponding to openssl's EVP_MD structure
8897 #
8898 # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
8899 • EVP_MD_size
8901 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8903 my $rv = Net::SSLeay::EVP_MD_size($md);
8905 # $md - value corresponding to openssl's EVP_MD structure
8906 #
8907 # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
8908 • EVP_MD_CTX_md
8910 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8912 requires at least openssl-0.9.7
8913 Net::SSLeay::EVP_MD_CTX_md($ctx);
8915 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8916 #
8917 # returns: value corresponding to openssl's EVP_MD structure
8918 • EVP_MD_CTX_create
8920 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8922 requires at least openssl-0.9.7
8923 Allocates, initializes and returns a digest context.
8925 my $rv = Net::SSLeay::EVP_MD_CTX_create();
8927 #
8928 # returns: value corresponding to openssl's EVP_MD_CTX structure
8929 The complete idea behind EVP_MD_CTX looks like this example:
8931 Net::SSLeay::OpenSSL_add_all_digests();
8933 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
8935 my $ctx = Net::SSLeay::EVP_MD_CTX_create();
8936 Net::SSLeay::EVP_DigestInit($ctx, $md);
8937 while(my $chunk = get_piece_of_data()) {
8939 Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
8940 }
8941 my $result = Net::SSLeay::EVP_DigestFinal($ctx);
8943 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8944 print "digest=", unpack('H*', $result), "\n"; #print hex value
8946 • EVP_DigestInit_ex
8948 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8950 requires at least openssl-0.9.7
8951 Sets up digest context $ctx to use a digest $type from ENGINE
8953 $impl, $ctx must be initialized before calling this function, type
8954 will typically be supplied by a function such as
8955 "EVP_get_digestbyname". If $impl is 0 then the default
8956 implementation of digest $type is used.
8957 my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
8959 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8960 # $type - value corresponding to openssl's EVP_MD structure
8961 # $impl - value corresponding to openssl's ENGINE structure
8962 #
8963 # returns: 1 for success and 0 for failure
8964 • EVP_DigestInit
8966 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8968 requires at least openssl-0.9.7
8969 Behaves in the same way as "EVP_DigestInit_ex" except the passed
8971 context $ctx does not have to be initialized, and it always uses
8972 the default digest implementation.
8973 my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
8975 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8976 # $type - value corresponding to openssl's EVP_MD structure
8977 #
8978 # returns: 1 for success and 0 for failure
8979 • EVP_MD_CTX_destroy
8981 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8983 requires at least openssl-0.9.7
8984 Cleans up digest context $ctx and frees up the space allocated to
8986 it, it should be called only on a context created using
8987 "EVP_MD_CTX_create".
8988 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8990 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8991 #
8992 # returns: no return value
8993 • EVP_DigestUpdate
8995 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8997 requires at least openssl-0.9.7
8998 my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
9000 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9001 # $data - data to be hashed
9002 #
9003 # returns: 1 for success and 0 for failure
9004 • EVP_DigestFinal_ex
9006 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9008 requires at least openssl-0.9.7
9009 Retrieves the digest value from $ctx. After calling
9011 "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
9012 be made, but "EVP_DigestInit_ex" can be called to initialize a new
9013 digest operation.
9014 my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
9016 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9017 #
9018 # returns: hash value (binary)
9019 #to get printable (hex) value of digest use:
9021 print unpack('H*', $digest_value);
9022 • EVP_DigestFinal
9024 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9026 requires at least openssl-0.9.7
9027 Similar to "EVP_DigestFinal_ex" except the digest context ctx is
9029 automatically cleaned up.
9030 my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
9032 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9033 #
9034 # returns: hash value (binary)
9035 #to get printable (hex) value of digest use:
9037 print unpack('H*', $digest_value);
9038 • MD2
9040 COMPATIBILITY: no supported by default in openssl-1.0.0
9042 Computes MD2 from given $data (all data needs to be loaded into
9044 memory)
9045 my $digest = Net::SSLeay::MD2($data);
9047 print "digest(hexadecimal)=", unpack('H*', $digest);
9048 • MD4
9050 Computes MD4 from given $data (all data needs to be loaded into
9052 memory)
9053 my $digest = Net::SSLeay::MD4($data);
9055 print "digest(hexadecimal)=", unpack('H*', $digest);
9056 • MD5
9058 Computes MD5 from given $data (all data needs to be loaded into
9060 memory)
9061 my $digest = Net::SSLeay::MD5($data);
9063 print "digest(hexadecimal)=", unpack('H*', $digest);
9064 • RIPEMD160
9066 Computes RIPEMD160 from given $data (all data needs to be loaded
9068 into memory)
9069 my $digest = Net::SSLeay::RIPEMD160($data);
9071 print "digest(hexadecimal)=", unpack('H*', $digest);
9072 • SHA1
9074 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9076 Computes SHA1 from given $data (all data needs to be loaded into
9078 memory)
9079 my $digest = Net::SSLeay::SHA1($data);
9081 print "digest(hexadecimal)=", unpack('H*', $digest);
9082 • SHA256
9084 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9086 requires at least openssl-0.9.8
9087 Computes SHA256 from given $data (all data needs to be loaded into
9089 memory)
9090 my $digest = Net::SSLeay::SHA256($data);
9092 print "digest(hexadecimal)=", unpack('H*', $digest);
9093 • SHA512
9095 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9097 requires at least openssl-0.9.8
9098 Computes SHA512 from given $data (all data needs to be loaded into
9100 memory)
9101 my $digest = Net::SSLeay::SHA512($data);
9103 print "digest(hexadecimal)=", unpack('H*', $digest);
9104 • EVP_Digest
9106 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9108 requires at least openssl-0.9.7
9109 Computes "any" digest from given $data (all data needs to be loaded
9111 into memory)
9112 my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
9114 my $digest = Net::SSLeay::EVP_Digest($data, $md);
9115 print "digest(hexadecimal)=", unpack('H*', $digest);
9116 • EVP_sha1
9118 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9120 my $md = Net::SSLeay::EVP_sha1();
9122 #
9123 # returns: value corresponding to openssl's EVP_MD structure
9124 • EVP_sha256
9126 COMPATIBILITY: requires at least openssl-0.9.8
9128 my $md = Net::SSLeay::EVP_sha256();
9130 #
9131 # returns: value corresponding to openssl's EVP_MD structure
9132 • EVP_sha512
9134 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9136 requires at least openssl-0.9.8
9137 my $md = Net::SSLeay::EVP_sha512();
9139 #
9140 # returns: value corresponding to openssl's EVP_MD structure
9141 • EVP_add_digest
9143 my $rv = Net::SSLeay::EVP_add_digest($digest);
9145 # $digest - value corresponding to openssl's EVP_MD structure
9146 #
9147 # returns: 1 on success, 0 otherwise
9148 Low level API: CIPHER_* related functions
9150 • CIPHER_get_name
9152 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9154 Returns name of the cipher used.
9156 my $rv = Net::SSLeay::CIPHER_get_name($cipher);
9158 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9159 #
9160 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA', '(NONE)' if $cipher is undefined.
9161 Check openssl doc
9163 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
9164 Example:
9166 my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
9168 my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
9169 • CIPHER_description
9171 COMPATIBILITY: doesn't work correctly in Net-SSLeay-1.88 and before
9173 Returns a textual description of the cipher used.
9175 my $rv = Net::SSLeay::CIPHER_description($cipher);
9177 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9178 #
9179 # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
9180 Check openssl doc
9182 <https://www.openssl.org/docs/ssl/SSL_CIPHER_description.html>
9183 • CIPHER_get_bits
9185 COMPATIBILITY: $alg_bits doesn't work correctly in Net-SSLeay-1.88
9187 and before
9188 Returns the number of secret bits used for cipher.
9190 my $rv = Net::SSLeay::CIPHER_get_bits($cipher, $alg_bits);
9192 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9193 # $alg_bits - [optional] empty scalar for storing additional return value
9194 #
9195 # returns: (integer) number of secret bits, 0 on error
9196 # (integer) in $alg_bits for bits processed by the chosen algorithm
9197 Check openssl doc
9199 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_bits.html>
9200 Example:
9202 # bits and alg_bits are not equal for e.g., TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
9204 # RFC 8422 name TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
9205 my $alg_bits;
9206 my $bits = Net::SSLeay::CIPHER_get_bits($cipher, $alg_bits);
9207 #my $bits = Net::SSLeay::CIPHER_get_bits($cipher);
9208 print "bits: $bits, alg_bits: $alg_bits\n";
9209 • CIPHER_get_version
9211 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
9213 Returns version of SSL/TLS protocol that first defined the cipher
9215 my $rv = Net::SSLeay::CIPHER_get_version($cipher);
9217 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9218 #
9219 # returns: (string) cipher name e.g. 'TLSv1/SSLv3' with some libraries, 'TLSv1.0' or 'TLSv1.3', '(NONE)' if $cipher is undefined.
9220 Check openssl doc
9222 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_version.html>
9223 Low level API: RSA_* related functions
9225 • RSA_generate_key
9227 Generates a key pair and returns it in a newly allocated RSA
9229 structure. The pseudo-random number generator must be seeded prior
9230 to calling RSA_generate_key.
9231 my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
9233 # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
9234 # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
9235 # $perl_cb - [optional] reference to perl callback function
9236 # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
9237 #
9238 # returns: value corresponding to openssl's RSA structure (0 on failure)
9239 Check openssl doc
9241 <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
9242 • RSA_free
9244 Frees the RSA structure and its components. The key is erased
9246 before the memory is returned to the system.
9247 Net::SSLeay::RSA_free($r);
9249 # $r - value corresponding to openssl's RSA structure
9250 #
9251 # returns: no return value
9252 Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
9254 • RSA_get_key_parameters
9256 Returns a list of pointers to BIGNUMs representing the parameters
9258 of the key in this order: (n, e, d, p, q, dmp1, dmq1, iqmp)
9259 Caution: returned list consists of SV pointers to BIGNUMs, which
9261 would need to be blessed as Crypt::OpenSSL::Bignum for further use
9262 my (@params) = RSA_get_key_parameters($r);
9264 Low level API: BIO_* related functions
9266 • BIO_eof
9268 Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
9270 varies according to the BIO type.
9271 my $rv = Net::SSLeay::BIO_eof($s);
9273 # $s - value corresponding to openssl's BIO structure
9274 #
9275 # returns: 1 if EOF has been reached 0 otherwise
9276 Check openssl doc
9278 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9279 • BIO_f_ssl
9281 Returns the SSL BIO method. This is a filter BIO which is a wrapper
9283 round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
9284 my $rv = Net::SSLeay::BIO_f_ssl();
9286 #
9287 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9288 Check openssl doc
9290 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9291 • BIO_free
9293 Frees up a single BIO.
9295 my $rv = Net::SSLeay::BIO_free($bio;);
9297 # $bio; - value corresponding to openssl's BIO structure
9298 #
9299 # returns: 1 on success, 0 on failure
9300 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9302 • BIO_new
9304 Returns a new BIO using method $type
9306 my $rv = Net::SSLeay::BIO_new($type);
9308 # $type - value corresponding to openssl's BIO_METHOD structure
9309 #
9310 # returns: value corresponding to openssl's BIO structure (0 on failure)
9311 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9313 • BIO_new_buffer_ssl_connect
9315 Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
9317 (using ctx) and a connect BIO.
9318 my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
9320 # $ctx - value corresponding to openssl's SSL_CTX structure
9321 #
9322 # returns: value corresponding to openssl's BIO structure (0 on failure)
9323 Check openssl doc
9325 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9326 • BIO_new_file
9328 Creates a new file BIO with mode $mode the meaning of mode is the
9330 same as the stdio function fopen(). The BIO_CLOSE flag is set on
9331 the returned BIO.
9332 my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
9334 # $filename - (string) filename
9335 # $mode - (string) opening mode (as mode by stdio function fopen)
9336 #
9337 # returns: value corresponding to openssl's BIO structure (0 on failure)
9338 Check openssl doc
9340 <http://www.openssl.org/docs/crypto/BIO_s_file.html>
9341 • BIO_new_ssl
9343 Allocates an SSL BIO using SSL_CTX ctx and using client mode if
9345 client is non zero.
9346 my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
9348 # $ctx - value corresponding to openssl's SSL_CTX structure
9349 # $client - (integer) 0 or 1 - indicates ssl client mode
9350 #
9351 # returns: value corresponding to openssl's BIO structure (0 on failure)
9352 Check openssl doc
9354 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9355 • BIO_new_ssl_connect
9357 Creates a new BIO chain consisting of an SSL BIO (using ctx)
9359 followed by a connect BIO.
9360 my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
9362 # $ctx - value corresponding to openssl's SSL_CTX structure
9363 #
9364 # returns: value corresponding to openssl's BIO structure (0 on failure)
9365 Check openssl doc
9367 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9368 • BIO_pending
9370 Return the number of pending characters in the BIOs read buffers.
9372 my $rv = Net::SSLeay::BIO_pending($s);
9374 # $s - value corresponding to openssl's BIO structure
9375 #
9376 # returns: the amount of pending data
9377 Check openssl doc
9379 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9380 • BIO_wpending
9382 Return the number of pending characters in the BIOs write buffers.
9384 my $rv = Net::SSLeay::BIO_wpending($s);
9386 # $s - value corresponding to openssl's BIO structure
9387 #
9388 # returns: the amount of pending data
9389 Check openssl doc
9391 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9392 • BIO_read
9394 Read the underlying descriptor.
9396 Net::SSLeay::BIO_read($s, $max);
9398 # $s - value corresponding to openssl's BIO structure
9399 # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
9400 #
9401 # returns: data
9402 Check openssl doc
9404 <http://www.openssl.org/docs/crypto/BIO_read.html>
9405 • BIO_write
9407 Attempts to write data from $buffer to BIO $b.
9409 my $rv = Net::SSLeay::BIO_write($b, $buffer);
9411 # $b - value corresponding to openssl's BIO structure
9412 # $buffer - data
9413 #
9414 # returns: amount of data successfully written
9415 # or that no data was successfully read or written if the result is 0 or -1
9416 # or -2 when the operation is not implemented in the specific BIO type
9417 Check openssl doc
9419 <http://www.openssl.org/docs/crypto/BIO_read.html>
9420 • BIO_s_mem
9422 Return the memory BIO method function.
9424 my $rv = Net::SSLeay::BIO_s_mem();
9426 #
9427 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9428 Check openssl doc
9430 <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
9431 • BIO_ssl_copy_session_id
9433 Copies an SSL session id between BIO chains from and to. It does
9435 this by locating the SSL BIOs in each chain and calling
9436 SSL_copy_session_id() on the internal SSL pointer.
9437 my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
9439 # $to - value corresponding to openssl's BIO structure
9440 # $from - value corresponding to openssl's BIO structure
9441 #
9442 # returns: 1 on success, 0 on failure
9443 Check openssl doc
9445 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9446 • BIO_ssl_shutdown
9448 Closes down an SSL connection on BIO chain bio. It does this by
9450 locating the SSL BIO in the chain and calling SSL_shutdown() on its
9451 internal SSL pointer.
9452 Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
9454 # $ssl_bio - value corresponding to openssl's BIO structure
9455 #
9456 # returns: no return value
9457 Check openssl doc
9459 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9460 Low level API: Server side Server Name Indication (SNI) support
9462 • set_tlsext_host_name
9464 TBA
9466 • get_servername
9468 TBA
9470 • get_servername_type
9472 TBA
9474 • CTX_set_tlsext_servername_callback
9476 COMPATIBILITY: requires at least OpenSSL 0.9.8f
9478 This function is used in a server to support Server side Server
9480 Name Indication (SNI).
9481 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
9483 # $ctx - SSL context
9484 # $code - reference to a subroutine that will be called when a new connection is being initiated
9485 #
9486 # returns: no return value
9487 On the client side: use set_tlsext_host_name($ssl, $servername)
9489 before initiating the SSL connection.
9490 On the server side: Set up an additional SSL_CTX() for each
9492 different certificate;
9493 Add a servername callback to each SSL_CTX() using
9495 CTX_set_tlsext_servername_callback();
9496 The callback function is required to retrieve the client-supplied
9498 servername with get_servername(ssl). Figure out the right SSL_CTX
9499 to go with that host name, then switch the SSL object to that
9500 SSL_CTX with set_SSL_CTX().
9501 Example:
9503 # set callback
9505 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
9506 sub {
9507 my $ssl = shift;
9508 my $h = Net::SSLeay::get_servername($ssl);
9509 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9510 } );
9511 More complete example:
9513 # ... initialize Net::SSLeay
9515 my %hostnames = (
9517 'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
9518 'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
9519 );
9520 # create a new context for each certificate/key pair
9522 for my $name (keys %hostnames) {
9523 $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
9524 Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
9525 Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
9526 $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
9527 }
9528 # create default context
9530 my $ctx = Net::SSLeay::CTX_new or die;
9531 Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
9532 Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
9533 # set callback
9535 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
9536 my $ssl = shift;
9537 my $h = Net::SSLeay::get_servername($ssl);
9538 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9539 } );
9540 # ... later
9542 $s = Net::SSLeay::new($ctx);
9544 Net::SSLeay::set_fd($s, fileno($accepted_socket));
9545 Net::SSLeay::accept($s);
9546 Low level API: NPN (next protocol negotiation) related functions
9548 NPN is being replaced with ALPN, a more recent TLS extension for
9550 application protocol negotiation that's in process of being adopted by
9551 IETF. Please look below for APLN API description.
9552 Simple approach for using NPN support looks like this:
9554 ### client side
9556 use Net::SSLeay;
9557 use IO::Socket::INET;
9558 Net::SSLeay::initialize();
9560 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9561 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9562 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9563 Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
9564 my $ssl = Net::SSLeay::new($ctx) or die;
9565 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9566 Net::SSLeay::connect($ssl);
9567 warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
9569 warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
9570 ### server side
9572 use Net::SSLeay;
9573 use IO::Socket::INET;
9574 Net::SSLeay::initialize();
9576 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9577 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9578 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9579 Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
9580 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9581 while (1) {
9583 my $ssl = Net::SSLeay::new($ctx);
9584 warn("server:waiting for incoming connection...\n");
9585 my $fd = $sock->accept();
9586 Net::SSLeay::set_fd($ssl, $fd->fileno);
9587 Net::SSLeay::accept($ssl);
9588 warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
9589 my $got = Net::SSLeay::read($ssl);
9590 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9591 Net::SSLeay::free($ssl);
9592 $fd->close();
9593 }
9594 # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
9595 Please note that the selection (negotiation) is performed by client
9597 side, the server side simply advertise the list of supported protocols.
9598 Advanced approach allows you to implement your own negotiation
9600 algorithm.
9601 #see below documentation for:
9603 Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9604 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9605 Detection of NPN support (works even in older Net::SSLeay versions):
9607 use Net::SSLeay;
9609 if (exists &Net::SSLeay::P_next_proto_negotiated) {
9611 # do NPN stuff
9612 }
9613 • CTX_set_next_proto_select_cb
9615 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9617 requires at least openssl-1.0.1
9618 NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
9620 connection.
9621 Simple usage - in this case a "common" negotiation algorithm (as
9623 implemented by openssl's function SSL_select_next_proto) is used.
9624 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
9626 # $ctx - value corresponding to openssl's SSL_CTX structure
9627 # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
9628 #
9629 # returns: 0 on success, 1 on failure
9630 Advanced usage (you probably do not need this):
9632 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9634 # $ctx - value corresponding to openssl's SSL_CTX structure
9635 # $perl_callback_function - reference to perl function
9636 # $callback_data - [optional] data to passed to callback function when invoked
9637 #
9638 # returns: 0 on success, 1 on failure
9639 # where callback function looks like
9641 sub npn_advertised_cb_invoke {
9642 my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
9643 my $status;
9644 # ...
9645 $status = 1; #status can be:
9646 # 0 - OPENSSL_NPN_UNSUPPORTED
9647 # 1 - OPENSSL_NPN_NEGOTIATED
9648 # 2 - OPENSSL_NPN_NO_OVERLAP
9649 return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
9650 }
9651 To undefine/clear this callback use:
9653 Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
9655 • CTX_set_next_protos_advertised_cb
9657 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9659 requires at least openssl-1.0.1
9660 NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
9662 connection.
9663 Simple usage:
9665 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
9667 # $ctx - value corresponding to openssl's SSL_CTX structure
9668 # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
9669 #
9670 # returns: 0 on success, 1 on failure
9671 Advanced usage (you probably do not need this):
9673 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9675 # $ctx - value corresponding to openssl's SSL_CTX structure
9676 # $perl_callback_function - reference to perl function
9677 # $callback_data - [optional] data to passed to callback function when invoked
9678 #
9679 # returns: 0 on success, 1 on failure
9680 # where callback function looks like
9682 sub npn_advertised_cb_invoke {
9683 my ($ssl, $callback_data) = @_;
9684 # ...
9685 return ['http1.1','spdy/2']; # the callback has to return arrayref
9686 }
9687 To undefine/clear this callback use:
9689 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
9691 • P_next_proto_negotiated
9693 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9695 requires at least openssl-1.0.1
9696 Returns the name of negotiated protocol for given SSL connection
9698 $ssl.
9699 $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
9701 # $ssl - value corresponding to openssl's SSL structure
9702 #
9703 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9704 • P_next_proto_last_status
9706 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9708 requires at least openssl-1.0.1
9709 Returns the result of the last negotiation for given SSL connection
9711 $ssl.
9712 $rv = Net::SSLeay::P_next_proto_last_status($ssl)
9714 # $ssl - value corresponding to openssl's SSL structure
9715 #
9716 # returns: (integer) negotiation status
9717 # 0 - OPENSSL_NPN_UNSUPPORTED
9718 # 1 - OPENSSL_NPN_NEGOTIATED
9719 # 2 - OPENSSL_NPN_NO_OVERLAP
9720 Low level API: ALPN (application layer protocol negotiation) related
9722 functions
9723 Application protocol can be negotiated via two different mechanisms
9725 employing two different TLS extensions: NPN (obsolete) and ALPN
9726 (recommended).
9727 The API is rather similar, with slight differences reflecting protocol
9729 specifics. In particular, with ALPN the protocol negotiation takes
9730 place on server, while with NPN the client implements the protocol
9731 negotiation logic.
9732 With ALPN, the most basic implementation looks like this:
9734 ### client side
9736 use Net::SSLeay;
9737 use IO::Socket::INET;
9738 Net::SSLeay::initialize();
9740 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9741 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9742 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9743 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9744 my $ssl = Net::SSLeay::new($ctx) or die;
9745 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9746 Net::SSLeay::connect($ssl);
9747 warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
9749 ### server side
9751 use Net::SSLeay;
9752 use IO::Socket::INET;
9753 Net::SSLeay::initialize();
9755 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9756 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9757 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9758 Net::SSLeay::CTX_set_alpn_select_cb($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9759 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9760 while (1) {
9762 my $ssl = Net::SSLeay::new($ctx);
9763 warn("server:waiting for incoming connection...\n");
9764 my $fd = $sock->accept();
9765 Net::SSLeay::set_fd($ssl, $fd->fileno);
9766 Net::SSLeay::accept($ssl);
9767 warn "server:selected=",Net::SSLeay::P_alpn_selected($ssl),"\n";
9768 my $got = Net::SSLeay::read($ssl);
9769 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9770 Net::SSLeay::free($ssl);
9771 $fd->close();
9772 }
9773 # check with: openssl s_client -connect localhost:5443 -alpn spdy/3,http/1.1
9774 Advanced approach allows you to implement your own negotiation
9776 algorithm.
9777 #see below documentation for:
9779 Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9780 Detection of ALPN support (works even in older Net::SSLeay versions):
9782 use Net::SSLeay;
9784 if (exists &Net::SSLeay::P_alpn_selected) {
9786 # do ALPN stuff
9787 }
9788 • CTX_set_alpn_select_cb
9790 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9792 requires at least openssl-1.0.2
9793 NOTE: You need CTX_set_alpn_select_cb on server side of TLS
9795 connection.
9796 Simple usage - in this case a "common" negotiation algorithm (as
9798 implemented by openssl's function SSL_select_next_proto) is used.
9799 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $arrayref);
9801 # $ctx - value corresponding to openssl's SSL_CTX structure
9802 # $arrayref - list of accepted protocols - e.g. ['http/2.0', 'http/1.1', 'spdy/3']
9803 #
9804 # returns: 0 on success, 1 on failure
9805 Advanced usage (you probably do not need this):
9807 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9809 # $ctx - value corresponding to openssl's SSL_CTX structure
9810 # $perl_callback_function - reference to perl function
9811 # $callback_data - [optional] data to passed to callback function when invoked
9812 #
9813 # returns: 0 on success, 1 on failure
9814 # where callback function looks like
9816 sub alpn_select_cb_invoke {
9817 my ($ssl, $arrayref_proto_list_advertised_by_client, $callback_data) = @_;
9818 # ...
9819 if ($negotiated) {
9820 return 'http/2.0';
9821 } else {
9822 return undef;
9823 }
9824 }
9825 To undefine/clear this callback use:
9827 Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
9829 • set_alpn_protos
9831 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9833 requires at least openssl-1.0.2
9834 NOTE: You need set_alpn_protos on client side of TLS connection.
9836 This adds list of supported application layer protocols to
9838 ClientHello message sent by a client. It advertises the
9839 enumeration of supported protocols:
9840 Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
9842 # returns 0 on success
9843 • CTX_set_alpn_protos
9845 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9847 requires at least openssl-1.0.2
9848 NOTE: You need CTX_set_alpn_protos on client side of TLS
9850 connection.
9851 This adds list of supported application layer protocols to
9853 ClientHello message sent by a client. It advertises the
9854 enumeration of supported protocols:
9855 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9857 # returns 0 on success
9858 • P_alpn_selected
9860 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9862 requires at least openssl-1.0.2
9863 Returns the name of negotiated protocol for given TLS connection
9865 $ssl.
9866 $rv = Net::SSLeay::P_alpn_selected($ssl)
9868 # $ssl - value corresponding to openssl's SSL structure
9869 #
9870 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9871 Low level API: DANE Support
9873 OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
9875 Authentication of Named Entities (DANE) Transport Layer Association
9876 within OpenSSL
9877 • SSL_get_tlsa_record_byname
9879 COMPATIBILITY: DELETED from net-ssleay, since it is not supported
9881 by OpenSSL
9882 In order to facilitate DANE there is additional interface,
9884 SSL_get_tlsa_record_byname, accepting hostname, port and socket
9885 type that returns packed TLSA record. In order to make it even
9886 easier there is additional SSL_ctrl function that calls
9887 SSL_get_tlsa_record_byname for you. Latter is recommended for
9888 programmers that wish to maintain broader binary compatibility,
9889 e.g. make application work with both 1.0.2 and prior version (in
9890 which case call to SSL_ctrl with new code returning error would
9891 have to be ignored when running with prior version).
9892 Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
9894 Low level API: Other functions
9896 • COMP_add_compression_method
9898 Adds the compression method cm with the identifier id to the list
9900 of available compression methods. This list is globally maintained
9901 for all SSL operations within this application. It cannot be set
9902 for specific SSL_CTX or SSL objects.
9903 my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
9905 # $id - (integer) compression method id
9906 # 0 to 63: methods defined by the IETF
9907 # 64 to 192: external party methods assigned by IANA
9908 # 193 to 255: reserved for private use
9909 #
9910 # $cm - value corresponding to openssl's COMP_METHOD structure
9911 #
9912 # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
9913 Check openssl doc
9915 <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
9916 • DH_free
9918 Frees the DH structure and its components. The values are erased
9920 before the memory is returned to the system.
9921 Net::SSLeay::DH_free($dh);
9923 # $dh - value corresponding to openssl's DH structure
9924 #
9925 # returns: no return value
9926 Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
9928 • FIPS_mode_set
9930 Enable or disable FIPS mode in a FIPS capable OpenSSL.
9932 Net::SSLeay:: FIPS_mode_set($enable);
9934 # $enable - (integer) 1 to enable, 0 to disable
9935 Low level API: EC related functions
9937 • CTX_set_tmp_ecdh
9939 TBA
9941 • EC_KEY_free
9943 TBA
9945 • EC_KEY_new_by_curve_name
9947 TBA
9949 • EC_KEY_generate_key
9951 Generates a EC key and returns it in a newly allocated EC_KEY
9953 structure. The EC key then can be used to create a PKEY which can
9954 be used in calls like X509_set_pubkey.
9955 my $key = Net::SSLeay::EVP_PKEY_new();
9957 my $ec = Net::SSLeay::EC_KEY_generate_key($curve);
9958 Net::SSLeay::EVP_PKEY_assign_EC_KEY($key,$ec);
9959 # $curve - curve name like 'secp521r1' or the matching Id (integer) of the curve
9961 #
9962 # returns: value corresponding to openssl's EC_KEY structure (0 on failure)
9963 This function has no equivalent in OpenSSL but combines multiple
9965 OpenSSL functions for an easier interface.
9966 • CTX_set_ecdh_auto, set_ecdh_auto
9968 These functions enable or disable the automatic curve selection on
9970 the server side by calling SSL_CTX_set_ecdh_auto or
9971 SSL_set_ecdh_auto respectively. If enabled the highest preference
9972 curve is automatically used for ECDH temporary keys used during key
9973 exchange. This function is no longer available for OpenSSL 1.1.0
9974 or higher.
9975 Net::SSLeay::CTX_set_ecdh_auto($ctx,1);
9977 Net::SSLeay::set_ecdh_auto($ssl,1);
9978 • CTX_set1_curves_list, set1_curves_list
9980 These functions set the supported curves (in order of preference)
9982 by calling SSL_CTX_set1_curves_list or SSL_set1_curves_list
9983 respectively. For a TLS client these curves are offered to the
9984 server in the supported curves extension while on the server side
9985 these are used to determine the shared curve. These functions are
9986 only available since OpenSSL 1.1.0.
9987 Net::SSLeay::CTX_set1_curves_list($ctx,"P-521:P-384:P-256");
9989 Net::SSLeay::set1_curves_list($ssl,"P-521:P-384:P-256");
9990 • CTX_set1_groups_list, set1_groups_list
9992 These functions set the supported groups (in order of preference)
9994 by calling SSL_CTX_set1_groups_list or SSL_set1_groups_list
9995 respectively. This is practically the same as CTX_set1_curves_list
9996 and set1_curves_list except that all DH groups can be given as
9997 supported by TLS 1.3. These functions are only available since
9998 OpenSSL 1.1.1.
9999 Net::SSLeay::CTX_set1_groups_list($ctx,"P-521:P-384:P-256");
10001 Net::SSLeay::set1_groups_list($ssl,"P-521:P-384:P-256");
10002 Low level API: OSSL_LIB_CTX and OSSL_PROVIDER related functions
10004 • OSSL_LIB_CTX_get0_global_default
10006 Returns a concrete (non NULL) reference to the global default
10008 library context.
10009 my $libctx = Net::SSLeay::OSSL_LIB_CTX_get0_global_default();
10011 # returns: a value corresponding to OSSL_LIB_CTX structure or false on failure
10012 Typically it's simpler to use undef with functions that take an
10014 OSSL_LIB_CTX argument when global default library context is
10015 needed.
10016 Check openssl doc
10018 <https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX_get0_global_default.html>
10019 • OSSL_PROVIDER_load
10021 Loads and initializes a provider
10023 my $provider = Net::SSLeay::OSSL_PROVIDER_load($libctx, $name);
10025 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10026 # $name - (string) provider name, e.g., 'legacy'
10027 #
10028 # returns: a value corresponding to OSSL_PROVIDER or false on failure
10029 Using undef loads the provider within the global default library
10031 context.
10032 my $provider = Net::SSLeay::OSSL_PROVIDER_load(undef, 'legacy');
10034 Check openssl doc
10036 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_load.html>
10037 • OSSL_PROVIDER_try_load
10039 Loads and initializes a provider similar to OSSL_PROVIDER_load with
10041 additional fallback control.
10042 my $provider = Net::SSLeay::OSSL_PROVIDER_try_load($libctx, $name, $retain_fallbacks);
10044 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10045 # $name - (string) provider name, e.g., 'legacy'
10046 # $retain_fallbacks - (integer) 0 or 1
10047 #
10048 # returns: a value corresponding to OSSL_PROVIDER or false on failure
10049 Check openssl doc
10051 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_try_load.html>
10052 • OSSL_PROVIDER_unload
10054 Unloads the given provider.
10056 my $rv = Net::SSLeay::OSSL_PROVIDER_unload($provider);
10058 # $provider - a value corresponding to OSSL_PROVIDER
10059 #
10060 # returns: (integer) 1 on success, 0 on error
10061 Check openssl doc
10063 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_unload.html>
10064 • OSSL_PROVIDER_available
10066 Checks if a named provider is available for use.
10068 my $rv = Net::SSLeay::OSSL_PROVIDER_available($libctx, $name);
10070 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10071 # $name - (string) provider name, e.g., 'legacy'
10072 #
10073 # returns: (integer) 1 if the named provider is available, otherwise 0.
10074 Check openssl doc
10076 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_available.html>
10077 • OSSL_PROVIDER_do_all
10079 Iterates over all loaded providers. A callback is called for each
10081 provider.
10082 my $rv = Net::SSLeay::OSSL_PROVIDER_do_all($libctx, $cb, $cbdata);
10084 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10085 # $cb - reference to a perl callback function
10086 $ $cbdata - data that will be passed to callback function
10087 #
10088 # returns: (integer) 1 if all callbacks returned 1, 0 the first time a callback returns 0.
10089 Example:
10091 sub do_all_cb {
10093 my ($provider, $cbdata) = @_;
10094 my $name = Net::SSLeay::OSSL_PROVIDER_get0_name($provider);
10096 print "Callback for provider: '$name', cbdata: '$cbdata'\n";
10097 return 1;
10098 }
10099 my $data_for_cb = 'Hello';
10100 # Triggers default provider automatic loading.
10102 Net::SSLeay::OSSL_PROVIDER_available(undef, 'default') || die 'default provider not available';
10103 Net::SSLeay::OSSL_PROVIDER_load(undef, 'legacy') || die 'load legacy';
10104 Net::SSLeay::OSSL_PROVIDER_load(undef, 'null') || die 'load null';
10105 Net::SSLeay::OSSL_PROVIDER_do_all(undef, \&do_all_cb, $data_for_cb) || die 'a callback failed';
10106 Check openssl doc
10108 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_do_all.html>
10109 • OSSL_PROVIDER_get0_name
10111 Returns the name of the given provider.
10113 my $name = Net::SSLeay::OSSL_PROVIDER_get0_name($provider);
10115 # $provider - a value corresponding to OSSL_PROVIDER
10116 #
10117 # returns: (string) provider name, e.g., 'legacy'
10118 Check openssl doc
10120 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_get0_name.html>
10121 • OSSL_PROVIDER_self_test
10123 Runs the provider's self tests.
10125 my $rv = Net::SSLeay::OSSL_PROVIDER_self_test($provider);
10127 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10128 # $provider - a value corresponding to OSSL_PROVIDER
10129 #
10130 # returns: (integer) returns 1 if the self tests pass, 0 on error
10131 Check openssl doc
10133 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_self_test.html>
10134 Constants
10136 There are many openssl constants available in Net::SSLeay. You can use
10137 them like this:
10138 use Net::SSLeay;
10140 print &Net::SSLeay::NID_commonName;
10141 #or
10142 print Net::SSLeay::NID_commonName();
10143 Or you can import them and use:
10145 use Net::SSLeay qw/NID_commonName/;
10147 print &NID_commonName;
10148 #or
10149 print NID_commonName();
10150 #or
10151 print NID_commonName;
10152 The constants names are derived from openssl constants, however
10154 constants starting with "SSL_" prefix have name with "SSL_" part
10155 stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
10156 "Net::SSleay::OP_ALL"
10157 The list of all available constant names:
10159 ASN1_STRFLGS_ESC_CTRL OPENSSL_VERSION_STRING
10161 ASN1_STRFLGS_ESC_MSB OP_ALL
10162 ASN1_STRFLGS_ESC_QUOTE OP_ALLOW_NO_DHE_KEX
10163 ASN1_STRFLGS_RFC2253 OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
10164 CB_ACCEPT_EXIT OP_CIPHER_SERVER_PREFERENCE
10165 CB_ACCEPT_LOOP OP_CISCO_ANYCONNECT
10166 CB_ALERT OP_COOKIE_EXCHANGE
10167 CB_CONNECT_EXIT OP_CRYPTOPRO_TLSEXT_BUG
10168 CB_CONNECT_LOOP OP_DONT_INSERT_EMPTY_FRAGMENTS
10169 CB_EXIT OP_ENABLE_MIDDLEBOX_COMPAT
10170 CB_HANDSHAKE_DONE OP_EPHEMERAL_RSA
10171 CB_HANDSHAKE_START OP_LEGACY_SERVER_CONNECT
10172 CB_LOOP OP_MICROSOFT_BIG_SSLV3_BUFFER
10173 CB_READ OP_MICROSOFT_SESS_ID_BUG
10174 CB_READ_ALERT OP_MSIE_SSLV2_RSA_PADDING
10175 CB_WRITE OP_NETSCAPE_CA_DN_BUG
10176 CB_WRITE_ALERT OP_NETSCAPE_CHALLENGE_BUG
10177 ERROR_NONE OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
10178 ERROR_SSL OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
10179 ERROR_SYSCALL OP_NON_EXPORT_FIRST
10180 ERROR_WANT_ACCEPT OP_NO_ANTI_REPLAY
10181 ERROR_WANT_CONNECT OP_NO_CLIENT_RENEGOTIATION
10182 ERROR_WANT_READ OP_NO_COMPRESSION
10183 ERROR_WANT_WRITE OP_NO_ENCRYPT_THEN_MAC
10184 ERROR_WANT_X509_LOOKUP OP_NO_QUERY_MTU
10185 ERROR_ZERO_RETURN OP_NO_RENEGOTIATION
10186 EVP_PKS_DSA OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
10187 EVP_PKS_EC OP_NO_SSL_MASK
10188 EVP_PKS_RSA OP_NO_SSLv2
10189 EVP_PKT_ENC OP_NO_SSLv3
10190 EVP_PKT_EXCH OP_NO_TICKET
10191 EVP_PKT_EXP OP_NO_TLSv1
10192 EVP_PKT_SIGN OP_NO_TLSv1_1
10193 EVP_PK_DH OP_NO_TLSv1_2
10194 EVP_PK_DSA OP_NO_TLSv1_3
10195 EVP_PK_EC OP_PKCS1_CHECK_1
10196 EVP_PK_RSA OP_PKCS1_CHECK_2
10197 FILETYPE_ASN1 OP_PRIORITIZE_CHACHA
10198 FILETYPE_PEM OP_SAFARI_ECDHE_ECDSA_BUG
10199 F_CLIENT_CERTIFICATE OP_SINGLE_DH_USE
10200 F_CLIENT_HELLO OP_SINGLE_ECDH_USE
10201 F_CLIENT_MASTER_KEY OP_SSLEAY_080_CLIENT_DH_BUG
10202 F_D2I_SSL_SESSION OP_SSLREF2_REUSE_CERT_TYPE_BUG
10203 F_GET_CLIENT_FINISHED OP_TLSEXT_PADDING
10204 F_GET_CLIENT_HELLO OP_TLS_BLOCK_PADDING_BUG
10205 F_GET_CLIENT_MASTER_KEY OP_TLS_D5_BUG
10206 F_GET_SERVER_FINISHED OP_TLS_ROLLBACK_BUG
10207 F_GET_SERVER_HELLO READING
10208 F_GET_SERVER_VERIFY RECEIVED_SHUTDOWN
10209 F_I2D_SSL_SESSION RSA_3
10210 F_READ_N RSA_F4
10211 F_REQUEST_CERTIFICATE R_BAD_AUTHENTICATION_TYPE
10212 F_SERVER_HELLO R_BAD_CHECKSUM
10213 F_SSL_CERT_NEW R_BAD_MAC_DECODE
10214 F_SSL_GET_NEW_SESSION R_BAD_RESPONSE_ARGUMENT
10215 F_SSL_NEW R_BAD_SSL_FILETYPE
10216 F_SSL_READ R_BAD_SSL_SESSION_ID_LENGTH
10217 F_SSL_RSA_PRIVATE_DECRYPT R_BAD_STATE
10218 F_SSL_RSA_PUBLIC_ENCRYPT R_BAD_WRITE_RETRY
10219 F_SSL_SESSION_NEW R_CHALLENGE_IS_DIFFERENT
10220 F_SSL_SESSION_PRINT_FP R_CIPHER_TABLE_SRC_ERROR
10221 F_SSL_SET_FD R_INVALID_CHALLENGE_LENGTH
10222 F_SSL_SET_RFD R_NO_CERTIFICATE_SET
10223 F_SSL_SET_WFD R_NO_CERTIFICATE_SPECIFIED
10224 F_SSL_USE_CERTIFICATE R_NO_CIPHER_LIST
10225 F_SSL_USE_CERTIFICATE_ASN1 R_NO_CIPHER_MATCH
10226 F_SSL_USE_CERTIFICATE_FILE R_NO_PRIVATEKEY
10227 F_SSL_USE_PRIVATEKEY R_NO_PUBLICKEY
10228 F_SSL_USE_PRIVATEKEY_ASN1 R_NULL_SSL_CTX
10229 F_SSL_USE_PRIVATEKEY_FILE R_PEER_DID_NOT_RETURN_A_CERTIFICATE
10230 F_SSL_USE_RSAPRIVATEKEY R_PEER_ERROR
10231 F_SSL_USE_RSAPRIVATEKEY_ASN1 R_PEER_ERROR_CERTIFICATE
10232 F_SSL_USE_RSAPRIVATEKEY_FILE R_PEER_ERROR_NO_CIPHER
10233 F_WRITE_PENDING R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE
10234 GEN_DIRNAME R_PUBLIC_KEY_ENCRYPT_ERROR
10235 GEN_DNS R_PUBLIC_KEY_IS_NOT_RSA
10236 GEN_EDIPARTY R_READ_WRONG_PACKET_TYPE
10237 GEN_EMAIL R_SHORT_READ
10238 GEN_IPADD R_SSL_SESSION_ID_IS_DIFFERENT
10239 GEN_OTHERNAME R_UNABLE_TO_EXTRACT_PUBLIC_KEY
10240 GEN_RID R_UNKNOWN_REMOTE_ERROR_TYPE
10241 GEN_URI R_UNKNOWN_STATE
10242 GEN_X400 R_X509_LIB
10243 LIBRESSL_VERSION_NUMBER SENT_SHUTDOWN
10244 MBSTRING_ASC SESSION_ASN1_VERSION
10245 MBSTRING_BMP SESS_CACHE_BOTH
10246 MBSTRING_FLAG SESS_CACHE_CLIENT
10247 MBSTRING_UNIV SESS_CACHE_NO_AUTO_CLEAR
10248 MBSTRING_UTF8 SESS_CACHE_NO_INTERNAL
10249 MIN_RSA_MODULUS_LENGTH_IN_BYTES SESS_CACHE_NO_INTERNAL_LOOKUP
10250 MODE_ACCEPT_MOVING_WRITE_BUFFER SESS_CACHE_NO_INTERNAL_STORE
10251 MODE_AUTO_RETRY SESS_CACHE_OFF
10252 MODE_ENABLE_PARTIAL_WRITE SESS_CACHE_SERVER
10253 MODE_RELEASE_BUFFERS SSL2_MT_CLIENT_CERTIFICATE
10254 NID_OCSP_sign SSL2_MT_CLIENT_FINISHED
10255 NID_SMIMECapabilities SSL2_MT_CLIENT_HELLO
10256 NID_X500 SSL2_MT_CLIENT_MASTER_KEY
10257 NID_X509 SSL2_MT_ERROR
10258 NID_ad_OCSP SSL2_MT_REQUEST_CERTIFICATE
10259 NID_ad_ca_issuers SSL2_MT_SERVER_FINISHED
10260 NID_algorithm SSL2_MT_SERVER_HELLO
10261 NID_authority_key_identifier SSL2_MT_SERVER_VERIFY
10262 NID_basic_constraints SSL2_VERSION
10263 NID_bf_cbc SSL3_MT_CCS
10264 NID_bf_cfb64 SSL3_MT_CERTIFICATE
10265 NID_bf_ecb SSL3_MT_CERTIFICATE_REQUEST
10266 NID_bf_ofb64 SSL3_MT_CERTIFICATE_STATUS
10267 NID_cast5_cbc SSL3_MT_CERTIFICATE_URL
10268 NID_cast5_cfb64 SSL3_MT_CERTIFICATE_VERIFY
10269 NID_cast5_ecb SSL3_MT_CHANGE_CIPHER_SPEC
10270 NID_cast5_ofb64 SSL3_MT_CLIENT_HELLO
10271 NID_certBag SSL3_MT_CLIENT_KEY_EXCHANGE
10272 NID_certificate_policies SSL3_MT_ENCRYPTED_EXTENSIONS
10273 NID_client_auth SSL3_MT_END_OF_EARLY_DATA
10274 NID_code_sign SSL3_MT_FINISHED
10275 NID_commonName SSL3_MT_HELLO_REQUEST
10276 NID_countryName SSL3_MT_KEY_UPDATE
10277 NID_crlBag SSL3_MT_MESSAGE_HASH
10278 NID_crl_distribution_points SSL3_MT_NEWSESSION_TICKET
10279 NID_crl_number SSL3_MT_NEXT_PROTO
10280 NID_crl_reason SSL3_MT_SERVER_DONE
10281 NID_delta_crl SSL3_MT_SERVER_HELLO
10282 NID_des_cbc SSL3_MT_SERVER_KEY_EXCHANGE
10283 NID_des_cfb64 SSL3_MT_SUPPLEMENTAL_DATA
10284 NID_des_ecb SSL3_RT_ALERT
10285 NID_des_ede SSL3_RT_APPLICATION_DATA
10286 NID_des_ede3 SSL3_RT_CHANGE_CIPHER_SPEC
10287 NID_des_ede3_cbc SSL3_RT_HANDSHAKE
10288 NID_des_ede3_cfb64 SSL3_RT_HEADER
10289 NID_des_ede3_ofb64 SSL3_RT_INNER_CONTENT_TYPE
10290 NID_des_ede_cbc SSL3_VERSION
10291 NID_des_ede_cfb64 SSLEAY_BUILT_ON
10292 NID_des_ede_ofb64 SSLEAY_CFLAGS
10293 NID_des_ofb64 SSLEAY_DIR
10294 NID_description SSLEAY_PLATFORM
10295 NID_desx_cbc SSLEAY_VERSION
10296 NID_dhKeyAgreement ST_ACCEPT
10297 NID_dnQualifier ST_BEFORE
10298 NID_dsa ST_CONNECT
10299 NID_dsaWithSHA ST_INIT
10300 NID_dsaWithSHA1 ST_OK
10301 NID_dsaWithSHA1_2 ST_READ_BODY
10302 NID_dsa_2 ST_READ_HEADER
10303 NID_email_protect TLS1_1_VERSION
10304 NID_ext_key_usage TLS1_2_VERSION
10305 NID_ext_req TLS1_3_VERSION
10306 NID_friendlyName TLS1_VERSION
10307 NID_givenName TLSEXT_STATUSTYPE_ocsp
10308 NID_hmacWithSHA1 VERIFY_CLIENT_ONCE
10309 NID_id_ad VERIFY_FAIL_IF_NO_PEER_CERT
10310 NID_id_ce VERIFY_NONE
10311 NID_id_kp VERIFY_PEER
10312 NID_id_pbkdf2 VERIFY_POST_HANDSHAKE
10313 NID_id_pe V_OCSP_CERTSTATUS_GOOD
10314 NID_id_pkix V_OCSP_CERTSTATUS_REVOKED
10315 NID_id_qt_cps V_OCSP_CERTSTATUS_UNKNOWN
10316 NID_id_qt_unotice WRITING
10317 NID_idea_cbc X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
10318 NID_idea_cfb64 X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
10319 NID_idea_ecb X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
10320 NID_idea_ofb64 X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
10321 NID_info_access X509_CHECK_FLAG_NO_WILDCARDS
10322 NID_initials X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
10323 NID_invalidity_date X509_FILETYPE_ASN1
10324 NID_issuer_alt_name X509_FILETYPE_DEFAULT
10325 NID_keyBag X509_FILETYPE_PEM
10326 NID_key_usage X509_LOOKUP
10327 NID_localKeyID X509_PURPOSE_ANY
10328 NID_localityName X509_PURPOSE_CRL_SIGN
10329 NID_md2 X509_PURPOSE_NS_SSL_SERVER
10330 NID_md2WithRSAEncryption X509_PURPOSE_OCSP_HELPER
10331 NID_md5 X509_PURPOSE_SMIME_ENCRYPT
10332 NID_md5WithRSA X509_PURPOSE_SMIME_SIGN
10333 NID_md5WithRSAEncryption X509_PURPOSE_SSL_CLIENT
10334 NID_md5_sha1 X509_PURPOSE_SSL_SERVER
10335 NID_mdc2 X509_PURPOSE_TIMESTAMP_SIGN
10336 NID_mdc2WithRSA X509_TRUST_COMPAT
10337 NID_ms_code_com X509_TRUST_EMAIL
10338 NID_ms_code_ind X509_TRUST_OBJECT_SIGN
10339 NID_ms_ctl_sign X509_TRUST_OCSP_REQUEST
10340 NID_ms_efs X509_TRUST_OCSP_SIGN
10341 NID_ms_ext_req X509_TRUST_SSL_CLIENT
10342 NID_ms_sgc X509_TRUST_SSL_SERVER
10343 NID_name X509_TRUST_TSA
10344 NID_netscape X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH
10345 NID_netscape_base_url X509_V_ERR_AKID_SKID_MISMATCH
10346 NID_netscape_ca_policy_url X509_V_ERR_APPLICATION_VERIFICATION
10347 NID_netscape_ca_revocation_url X509_V_ERR_CA_KEY_TOO_SMALL
10348 NID_netscape_cert_extension X509_V_ERR_CA_MD_TOO_WEAK
10349 NID_netscape_cert_sequence X509_V_ERR_CERT_CHAIN_TOO_LONG
10350 NID_netscape_cert_type X509_V_ERR_CERT_HAS_EXPIRED
10351 NID_netscape_comment X509_V_ERR_CERT_NOT_YET_VALID
10352 NID_netscape_data_type X509_V_ERR_CERT_REJECTED
10353 NID_netscape_renewal_url X509_V_ERR_CERT_REVOKED
10354 NID_netscape_revocation_url X509_V_ERR_CERT_SIGNATURE_FAILURE
10355 NID_netscape_ssl_server_name X509_V_ERR_CERT_UNTRUSTED
10356 NID_ns_sgc X509_V_ERR_CRL_HAS_EXPIRED
10357 NID_organizationName X509_V_ERR_CRL_NOT_YET_VALID
10358 NID_organizationalUnitName X509_V_ERR_CRL_PATH_VALIDATION_ERROR
10359 NID_pbeWithMD2AndDES_CBC X509_V_ERR_CRL_SIGNATURE_FAILURE
10360 NID_pbeWithMD2AndRC2_CBC X509_V_ERR_DANE_NO_MATCH
10361 NID_pbeWithMD5AndCast5_CBC X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
10362 NID_pbeWithMD5AndDES_CBC X509_V_ERR_DIFFERENT_CRL_SCOPE
10363 NID_pbeWithMD5AndRC2_CBC X509_V_ERR_EE_KEY_TOO_SMALL
10364 NID_pbeWithSHA1AndDES_CBC X509_V_ERR_EMAIL_MISMATCH
10365 NID_pbeWithSHA1AndRC2_CBC X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD
10366 NID_pbe_WithSHA1And128BitRC2_CBC X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD
10367 NID_pbe_WithSHA1And128BitRC4 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD
10368 NID_pbe_WithSHA1And2_Key_TripleDES_CBC X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD
10369 NID_pbe_WithSHA1And3_Key_TripleDES_CBC X509_V_ERR_EXCLUDED_VIOLATION
10370 NID_pbe_WithSHA1And40BitRC2_CBC X509_V_ERR_HOSTNAME_MISMATCH
10371 NID_pbe_WithSHA1And40BitRC4 X509_V_ERR_INVALID_CA
10372 NID_pbes2 X509_V_ERR_INVALID_CALL
10373 NID_pbmac1 X509_V_ERR_INVALID_EXTENSION
10374 NID_pkcs X509_V_ERR_INVALID_NON_CA
10375 NID_pkcs3 X509_V_ERR_INVALID_POLICY_EXTENSION
10376 NID_pkcs7 X509_V_ERR_INVALID_PURPOSE
10377 NID_pkcs7_data X509_V_ERR_IP_ADDRESS_MISMATCH
10378 NID_pkcs7_digest X509_V_ERR_KEYUSAGE_NO_CERTSIGN
10379 NID_pkcs7_encrypted X509_V_ERR_KEYUSAGE_NO_CRL_SIGN
10380 NID_pkcs7_enveloped X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE
10381 NID_pkcs7_signed X509_V_ERR_NO_EXPLICIT_POLICY
10382 NID_pkcs7_signedAndEnveloped X509_V_ERR_NO_VALID_SCTS
10383 NID_pkcs8ShroudedKeyBag X509_V_ERR_OCSP_CERT_UNKNOWN
10384 NID_pkcs9 X509_V_ERR_OCSP_VERIFY_FAILED
10385 NID_pkcs9_challengePassword X509_V_ERR_OCSP_VERIFY_NEEDED
10386 NID_pkcs9_contentType X509_V_ERR_OUT_OF_MEM
10387 NID_pkcs9_countersignature X509_V_ERR_PATH_LENGTH_EXCEEDED
10388 NID_pkcs9_emailAddress X509_V_ERR_PATH_LOOP
10389 NID_pkcs9_extCertAttributes X509_V_ERR_PERMITTED_VIOLATION
10390 NID_pkcs9_messageDigest X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED
10391 NID_pkcs9_signingTime X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED
10392 NID_pkcs9_unstructuredAddress X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION
10393 NID_pkcs9_unstructuredName X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN
10394 NID_private_key_usage_period X509_V_ERR_STORE_LOOKUP
10395 NID_rc2_40_cbc X509_V_ERR_SUBJECT_ISSUER_MISMATCH
10396 NID_rc2_64_cbc X509_V_ERR_SUBTREE_MINMAX
10397 NID_rc2_cbc X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256
10398 NID_rc2_cfb64 X509_V_ERR_SUITE_B_INVALID_ALGORITHM
10399 NID_rc2_ecb X509_V_ERR_SUITE_B_INVALID_CURVE
10400 NID_rc2_ofb64 X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM
10401 NID_rc4 X509_V_ERR_SUITE_B_INVALID_VERSION
10402 NID_rc4_40 X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED
10403 NID_rc5_cbc X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY
10404 NID_rc5_cfb64 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE
10405 NID_rc5_ecb X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE
10406 NID_rc5_ofb64 X509_V_ERR_UNABLE_TO_GET_CRL
10407 NID_ripemd160 X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER
10408 NID_ripemd160WithRSA X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT
10409 NID_rle_compression X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
10410 NID_rsa X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE
10411 NID_rsaEncryption X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION
10412 NID_rsadsi X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION
10413 NID_safeContentsBag X509_V_ERR_UNNESTED_RESOURCE
10414 NID_sdsiCertificate X509_V_ERR_UNSPECIFIED
10415 NID_secretBag X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX
10416 NID_serialNumber X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE
10417 NID_server_auth X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE
10418 NID_sha X509_V_ERR_UNSUPPORTED_NAME_SYNTAX
10419 NID_sha1 X509_V_FLAG_ALLOW_PROXY_CERTS
10420 NID_sha1WithRSA X509_V_FLAG_CB_ISSUER_CHECK
10421 NID_sha1WithRSAEncryption X509_V_FLAG_CHECK_SS_SIGNATURE
10422 NID_shaWithRSAEncryption X509_V_FLAG_CRL_CHECK
10423 NID_stateOrProvinceName X509_V_FLAG_CRL_CHECK_ALL
10424 NID_subject_alt_name X509_V_FLAG_EXPLICIT_POLICY
10425 NID_subject_key_identifier X509_V_FLAG_EXTENDED_CRL_SUPPORT
10426 NID_surname X509_V_FLAG_IGNORE_CRITICAL
10427 NID_sxnet X509_V_FLAG_INHIBIT_ANY
10428 NID_time_stamp X509_V_FLAG_INHIBIT_MAP
10429 NID_title X509_V_FLAG_LEGACY_VERIFY
10430 NID_undef X509_V_FLAG_NOTIFY_POLICY
10431 NID_uniqueIdentifier X509_V_FLAG_NO_ALT_CHAINS
10432 NID_x509Certificate X509_V_FLAG_NO_CHECK_TIME
10433 NID_x509Crl X509_V_FLAG_PARTIAL_CHAIN
10434 NID_zlib_compression X509_V_FLAG_POLICY_CHECK
10435 NOTHING X509_V_FLAG_POLICY_MASK
10436 OCSP_RESPONSE_STATUS_INTERNALERROR X509_V_FLAG_SUITEB_128_LOS
10437 OCSP_RESPONSE_STATUS_MALFORMEDREQUEST X509_V_FLAG_SUITEB_128_LOS_ONLY
10438 OCSP_RESPONSE_STATUS_SIGREQUIRED X509_V_FLAG_SUITEB_192_LOS
10439 OCSP_RESPONSE_STATUS_SUCCESSFUL X509_V_FLAG_TRUSTED_FIRST
10440 OCSP_RESPONSE_STATUS_TRYLATER X509_V_FLAG_USE_CHECK_TIME
10441 OCSP_RESPONSE_STATUS_UNAUTHORIZED X509_V_FLAG_USE_DELTAS
10442 OPENSSL_BUILT_ON X509_V_FLAG_X509_STRICT
10443 OPENSSL_CFLAGS X509_V_OK
10444 OPENSSL_CPU_INFO XN_FLAG_COMPAT
10445 OPENSSL_DIR XN_FLAG_DN_REV
10446 OPENSSL_ENGINES_DIR XN_FLAG_DUMP_UNKNOWN_FIELDS
10447 OPENSSL_FULL_VERSION_STRING XN_FLAG_FN_ALIGN
10448 OPENSSL_INFO_CONFIG_DIR XN_FLAG_FN_LN
10449 OPENSSL_INFO_CPU_SETTINGS XN_FLAG_FN_MASK
10450 OPENSSL_INFO_DIR_FILENAME_SEPARATOR XN_FLAG_FN_NONE
10451 OPENSSL_INFO_DSO_EXTENSION XN_FLAG_FN_OID
10452 OPENSSL_INFO_ENGINES_DIR XN_FLAG_FN_SN
10453 OPENSSL_INFO_LIST_SEPARATOR XN_FLAG_MULTILINE
10454 OPENSSL_INFO_MODULES_DIR XN_FLAG_ONELINE
10455 OPENSSL_INFO_SEED_SOURCE XN_FLAG_RFC2253
10456 OPENSSL_MODULES_DIR XN_FLAG_SEP_COMMA_PLUS
10457 OPENSSL_PLATFORM XN_FLAG_SEP_CPLUS_SPC
10458 OPENSSL_VERSION XN_FLAG_SEP_MASK
10459 OPENSSL_VERSION_MAJOR XN_FLAG_SEP_MULTILINE
10460 OPENSSL_VERSION_MINOR XN_FLAG_SEP_SPLUS_SPC
10461 OPENSSL_VERSION_NUMBER XN_FLAG_SPC_EQ
10462 OPENSSL_VERSION_PATCH
10463 INTERNAL ONLY functions (do not use these)
10465 The following functions are not intended for use from outside of
10466 Net::SSLeay module. They might be removed, renamed or changed without
10467 prior notice in future version.
10468 Simply DO NOT USE THEM!
10470 • hello
10472 • blength
10474 • constant
10476
10478 One very good example to look at is the implementation of sslcat() in
10479 the "SSLeay.pm" file.
10480 The following is a simple SSLeay client (with too little error checking
10482 :-(
10483 #!/usr/bin/perl
10485 use Socket;
10486 use Net::SSLeay qw(die_now die_if_ssl_error) ;
10487 Net::SSLeay::load_error_strings();
10488 Net::SSLeay::SSLeay_add_ssl_algorithms();
10489 Net::SSLeay::randomize();
10490 ($dest_serv, $port, $msg) = @ARGV; # Read command line
10492 $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
10493 $dest_ip = gethostbyname ($dest_serv);
10494 $dest_serv_params = sockaddr_in($port, $dest_ip);
10495 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
10497 connect (S, $dest_serv_params) or die "connect: $!";
10498 select (S); $| = 1; select (STDOUT); # Eliminate STDIO buffering
10499 # The network connection is now open, lets fire up SSL
10501 $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
10503 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10504 or die_if_ssl_error("ssl ctx set options");
10505 $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
10506 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
10507 $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
10508 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10509 # Exchange data
10511 $res = Net::SSLeay::write($ssl, $msg); # Perl knows how long $msg is
10513 die_if_ssl_error("ssl write");
10514 CORE::shutdown S, 1; # Half close --> No more output, sends EOF to server
10515 $got = Net::SSLeay::read($ssl); # Perl returns undef on failure
10516 die_if_ssl_error("ssl read");
10517 print $got;
10518 Net::SSLeay::free ($ssl); # Tear down connection
10520 Net::SSLeay::CTX_free ($ctx);
10521 close S;
10522 The following is a simple SSLeay echo server (non forking):
10524 #!/usr/bin/perl -w
10526 use Socket;
10527 use Net::SSLeay qw(die_now die_if_ssl_error);
10528 Net::SSLeay::load_error_strings();
10529 Net::SSLeay::SSLeay_add_ssl_algorithms();
10530 Net::SSLeay::randomize();
10531 $our_ip = "\0\0\0\0"; # Bind to all interfaces
10533 $port = 1235;
10534 $sockaddr_template = 'S n a4 x8';
10535 $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
10536 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
10538 bind (S, $our_serv_params) or die "bind: $!";
10539 listen (S, 5) or die "listen: $!";
10540 $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
10541 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10542 or die_if_ssl_error("ssl ctx set options");
10543 # Following will ask password unless private key is not encrypted
10545 Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
10546 &Net::SSLeay::FILETYPE_PEM);
10547 die_if_ssl_error("private key");
10548 Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
10549 &Net::SSLeay::FILETYPE_PEM);
10550 die_if_ssl_error("certificate");
10551 while (1) {
10553 print "Accepting connections...\n";
10554 ($addr = accept (NS, S)) or die "accept: $!";
10555 select (NS); $| = 1; select (STDOUT); # Piping hot!
10556 ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
10558 @inetaddr = unpack('C4',$client_ip);
10559 print "$af connection from " .
10560 join ('.', @inetaddr) . ":$client_port\n";
10561 # We now have a network connection, lets fire up SSLeay...
10563 $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
10565 Net::SSLeay::set_fd($ssl, fileno(NS));
10566 $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
10568 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10569 # Connected. Exchange some data.
10571 $got = Net::SSLeay::read($ssl); # Returns undef on fail
10573 die_if_ssl_error("ssl read");
10574 print "Got `$got' (" . length ($got) . " chars)\n";
10575 Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
10577 die_if_ssl_error("ssl write");
10578 Net::SSLeay::free ($ssl); # Tear down connection
10580 close NS;
10581 }
10582 Yet another echo server. This one runs from "/etc/inetd.conf" so it
10584 avoids all the socket code overhead. Only caveat is opening an rsa key
10585 file - it had better be without any encryption or else it will not know
10586 where to ask for the password. Note how "STDIN" and "STDOUT" are wired
10587 to SSL.
10588 #!/usr/bin/perl
10590 # /etc/inetd.conf
10591 # ssltst stream tcp nowait root /path/to/server.pl server.pl
10592 # /etc/services
10593 # ssltst 1234/tcp
10594 use Net::SSLeay qw(die_now die_if_ssl_error);
10596 Net::SSLeay::load_error_strings();
10597 Net::SSLeay::SSLeay_add_ssl_algorithms();
10598 Net::SSLeay::randomize();
10599 chdir '/key/dir' or die "chdir: $!";
10601 $| = 1; # Piping hot!
10602 open LOG, ">>/dev/console" or die "Can't open log file $!";
10603 select LOG; print "server.pl started\n";
10604 $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
10606 $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
10607 Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
10608 and die_if_ssl_error("ssl set options");
10609 # We get already open network connection from inetd, now we just
10611 # need to attach SSLeay to STDIN and STDOUT
10612 Net::SSLeay::set_rfd($ssl, fileno(STDIN));
10613 Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
10614 Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
10616 Net::SSLeay::FILETYPE_PEM);
10617 die_if_ssl_error("private key");
10618 Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
10619 Net::SSLeay::FILETYPE_PEM);
10620 die_if_ssl_error("certificate");
10621 Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
10623 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10624 $got = Net::SSLeay::read($ssl);
10626 die_if_ssl_error("ssl read");
10627 print "Got `$got' (" . length ($got) . " chars)\n";
10628 Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
10630 die_if_ssl_error("ssl write");
10631 Net::SSLeay::free ($ssl); # Tear down the connection
10633 Net::SSLeay::CTX_free ($ctx);
10634 close LOG;
10635 There are also a number of example/test programs in the examples
10637 directory:
10638 sslecho.pl - A simple server, not unlike the one above
10640 minicli.pl - Implements a client using low level SSLeay routines
10641 sslcat.pl - Demonstrates using high level sslcat utility function
10642 get_page.pl - Is a utility for getting html pages from secure servers
10643 callback.pl - Demonstrates certificate verification and callback usage
10644 stdio_bulk.pl - Does SSL over Unix pipes
10645 ssl-inetd-serv.pl - SSL server that can be invoked from inetd.conf
10646 httpd-proxy-snif.pl - Utility that allows you to see how a browser
10647 sends https request to given server and what reply
10648 it gets back (very educative :-)
10649 makecert.pl - Creates a self signed cert (does not use this module)
10650
10652 See README and README.* in the distribution directory for installation
10653 guidance on a variety of platforms.
10654
10656 Net::SSLeay::read() uses an internal buffer of 32KB, thus no single
10657 read will return more. In practice one read returns much less, usually
10658 as much as fits in one network packet. To work around this, you should
10659 use a loop like this:
10660 $reply = '';
10662 while ($got = Net::SSLeay::read($ssl)) {
10663 last if print_errs('SSL_read');
10664 $reply .= $got;
10665 }
10666 Although there is no built-in limit in Net::SSLeay::write(), the
10668 network packet size limitation applies here as well, thus use:
10669 $written = 0;
10671 while ($written < length($message)) {
10673 $written += Net::SSLeay::write($ssl, substr($message, $written));
10674 last if print_errs('SSL_write');
10675 }
10676 Or alternatively you can just use the following convenience functions:
10678 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
10680 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
10681
10683 LibreSSL versions in the 3.1 - 3.3 series contain a TLS 1.3
10684 implementation that is not fully compatible with the libssl API, but is
10685 still advertised during protocol auto-negotiation. If you encounter
10686 problems or unexpected behaviour with SSL or SSL_CTX objects whose
10687 protocol version was automatically negotiated and libssl is provided by
10688 any of these versions of LibreSSL, it could be because the peers
10689 negotiated to use TLS 1.3 - try setting the maximum protocol version to
10690 TLS 1.2 (via Net::SSLeay::set_max_proto_version() or
10691 Net::SSLeay::CTX_set_max_proto_version()) before establishing the
10692 connection. The first stable LibreSSL version with a fully libssl-
10693 compatible TLS 1.3 implementation is 3.4.1.
10694 An OpenSSL bug CVE-2015-0290 "OpenSSL Multiblock Corrupted Pointer
10696 Issue" can cause POST requests of over 90kB to fail or crash. This bug
10697 is reported to be fixed in OpenSSL 1.0.2a.
10698 Autoloader emits a
10700 Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
10702 warning if die_if_ssl_error is made autoloadable. If you figure out
10704 why, drop me a line.
10705 Callback set using SSL_set_verify() does not appear to work. This may
10707 well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
10708 using SSL_CTX_set_verify() instead and do not be surprised if even this
10709 stops working in future versions.
10710 Callback and certificate verification stuff is generally too little
10712 tested.
10713 Random numbers are not initialized randomly enough, especially if you
10715 do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
10716 platforms - but it's been suggested that cryptorand daemon from the
10717 SUNski package solves this). In this case you should investigate third
10718 party software that can emulate these devices, e.g. by way of a named
10719 pipe to some program.
10720 Another gotcha with random number initialization is randomness
10722 depletion. This phenomenon, which has been extensively discussed in
10723 OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
10724 to block if you use "/dev/random" or to operate insecurely if you use
10725 "/dev/urandom". What happens is that when too much randomness is drawn
10726 from the operating system's randomness pool then randomness can
10727 temporarily be unavailable. "/dev/random" solves this problem by
10728 waiting until enough randomness can be gathered - and this can take a
10729 long time since blocking reduces activity in the machine and less
10730 activity provides less random events: a vicious circle. "/dev/urandom"
10731 solves this dilemma more pragmatically by simply returning predictable
10732 "random" numbers. Some" /dev/urandom" emulation software however
10733 actually seems to implement "/dev/random" semantics. Caveat emptor.
10734 I've been pointed to two such daemons by Mik Firestone
10736 <mik@@speed.stdio._com> who has used them on Solaris 8:
10737 1. Entropy Gathering Daemon (EGD) at
10739 <http://www.lothar.com/tech/crypto/>
10740 2. Pseudo-random number generating daemon (PRNGD) at
10742 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10743 If you are using the low level API functions to communicate with other
10745 SSL implementations, you would do well to call
10746 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10748 or die_if_ssl_error("ssl ctx set options");
10749 to cope with some well know bugs in some other SSL implementations. The
10751 high level API functions always set all known compatibility options.
10752 Sometimes sslcat() (and the high level HTTPS functions that build on
10754 it) is too fast in signaling the EOF to legacy HTTPS servers. This
10755 causes the server to return empty page. To work around this problem you
10756 can set the global variable
10757 $Net::SSLeay::slowly = 1; # Add sleep so broken servers can keep up
10759 HTTP/1.1 is not supported. Specifically this module does not know to
10761 issue or serve multiple http requests per connection. This is a serious
10762 shortcoming, but using the SSL session cache on your server helps to
10763 alleviate the CPU load somewhat.
10764 As of version 1.09 many newer OpenSSL auxiliary functions were added
10766 (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
10767 Unfortunately I have not had any opportunity to test these. Some of
10768 them are trivial enough that I believe they "just work", but others
10769 have rather complex interfaces with function pointers and all. In these
10770 cases you should proceed wit great caution.
10771 This module defaults to using OpenSSL automatic protocol negotiation
10773 code for automatically detecting the version of the SSL/TLS protocol
10774 that the other end talks. With most web servers this works just fine,
10775 but once in a while I get complaints from people that the module does
10776 not work with some web servers. Usually this can be solved by
10777 explicitly setting the protocol version, e.g.
10778 $Net::SSLeay::ssl_version = 2; # Insist on SSLv2
10780 $Net::SSLeay::ssl_version = 3; # Insist on SSLv3
10781 $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
10782 $Net::SSLeay::ssl_version = 11; # Insist on TLSv1.1
10783 $Net::SSLeay::ssl_version = 12; # Insist on TLSv1.2
10784 $Net::SSLeay::ssl_version = 13; # Insist on TLSv1.3
10785 Although the autonegotiation is nice to have, the SSL standards do not
10787 formally specify any such mechanism. Most of the world has accepted the
10788 SSLeay/OpenSSL way of doing it as the de facto standard. But for the
10789 few that think differently, you have to explicitly speak the correct
10790 version. This is not really a bug, but rather a deficiency in the
10791 standards. If a site refuses to respond or sends back some nonsensical
10792 error codes (at the SSL handshake level), try this option before
10793 mailing me.
10794 On some systems, OpenSSL may be compiled without support for SSLv2. If
10796 this is the case, Net::SSLeay will warn if ssl_version has been set to
10797 2.
10798 The high level API returns the certificate of the peer, thus allowing
10800 one to check what certificate was supplied. However, you will only be
10801 able to check the certificate after the fact, i.e. you already sent
10802 your form data by the time you find out that you did not trust them,
10803 oops.
10804 So, while being able to know the certificate after the fact is surely
10806 useful, the security minded would still choose to do the connection and
10807 certificate verification first and only then exchange data with the
10808 site. Currently none of the high level API functions do this, thus you
10809 would have to program it using the low level API. A good place to start
10810 is to see how the Net::SSLeay::http_cat() function is implemented.
10811 The high level API functions use a global file handle "SSLCAT_S"
10813 internally. This really should not be a problem because there is no way
10814 to interleave the high level API functions, unless you use threads (but
10815 threads are not very well supported in perl anyway). However, you may
10816 run into problems if you call undocumented internal functions in an
10817 interleaved fashion. The best solution is to "require Net::SSLeay" in
10818 one thread after all the threads have been created.
10819
10821 Random number generator not seeded!!!
10822 (W) This warning indicates that randomize() was not able to read
10823 "/dev/random" or "/dev/urandom", possibly because your system does
10824 not have them or they are differently named. You can still use SSL,
10825 but the encryption will not be as strong.
10826 open_tcp_connection: destination host not found:`server' (port 123)
10828 ($!)
10829 Name lookup for host named "server" failed.
10830 open_tcp_connection: failed `server', 123 ($!)
10832 The name was resolved, but establishing the TCP connection failed.
10833 msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
10835 proto
10836 SSLeay error string. The first number (123) is the PID, the second
10837 number (1) indicates the position of the error message in SSLeay
10838 error stack. You often see a pile of these messages as errors
10839 cascade.
10840 msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
10842 The same as above, but you didn't call load_error_strings() so
10843 SSLeay couldn't verbosely explain the error. You can still find out
10844 what it means with this command:
10845 /usr/local/ssl/bin/ssleay errstr 02001002
10847 Password is being asked for private key
10849 This is normal behaviour if your private key is encrypted. Either
10850 you have to supply the password or you have to use an unencrypted
10851 private key. Scan OpenSSL.org for the FAQ that explains how to do
10852 this (or just study examples/makecert.pl which is used during "make
10853 test" to do just that).
10854
10856 You can mitigate some of the security vulnerabilities that might be
10857 present in your SSL/TLS application:
10858 BEAST Attack
10860 http://blogs.cisco.com/security/beat-the-beast-with-tls/
10861 https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
10862 http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
10863 The BEAST attack relies on a weakness in the way CBC mode is used in
10865 SSL/TLS. In OpenSSL versions 0.9.6d and later, the protocol-level
10866 mitigation is enabled by default, thus making it not vulnerable to the
10867 BEAST attack.
10868 Solutions:
10870 • Compile with OpenSSL versions 0.9.6d or later, which enables
10872 SSL_OP_ALL by default
10873 • Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
10875 enabled by default)
10876 • Don't support SSLv2, SSLv3
10878 • Actively control the ciphers your server supports with
10880 set_cipher_list:
10881 Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
10883 Session Resumption
10885 http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
10886 The SSL Labs vulnerability test on your SSL server might report in red:
10888 Session resumption No (IDs assigned but not accepted)
10890 This report is not really bug or a vulnerability, since the server will
10892 not accept session resumption requests. However, you can prevent this
10893 noise in the report by disabling the session cache altogether:
10894 Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx,
10895 Net::SSLeay::SESS_CACHE_OFF()); Use 0 if you don't have SESS_CACHE_OFF
10896 constant.
10897 Secure Renegotiation and DoS Attack
10899 https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
10900 This is not a "security flaw," it is more of a DoS vulnerability.
10902 Solutions:
10904 • Do not support SSLv2
10906 • Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
10908 • Compile with OpenSSL 0.9.8m or later
10910
10912 If you encounter a problem with this module that you believe is a bug,
10913 please create a new issue <https://github.com/radiator-software/p5-net-
10914 ssleay/issues/new> in the Net-SSLeay GitHub repository. Please make
10915 sure your bug report includes the following information:
10916 • the code you are trying to run;
10918 • your operating system name and version;
10920 • the output of "perl -V";
10922 • the version of OpenSSL or LibreSSL you are using.
10924
10926 Originally written by Sampo Kellomäki.
10927 Maintained by Florian Ragwitz between November 2005 and January 2010.
10929 Maintained by Mike McCauley between November 2005 and June 2018.
10931 Maintained by Chris Novakovic, Tuure Vartiainen and Heikki Vatiainen
10933 since June 2018.
10934
10936 Copyright (c) 1996-2003 Sampo Kellomäki <sampo@iki.fi>
10937 Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
10939 Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
10941 Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
10943 Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
10945 Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
10947 All rights reserved.
10949
10951 This module is released under the terms of the Artistic License 2.0.
10952 For details, see the "LICENSE" file distributed with Net-SSLeay's
10953 source code.
10954
10956 Net::SSLeay::Handle - File handle interface
10957 ./examples - Example servers and a clients
10958 <http://www.openssl.org/> - OpenSSL source, documentation, etc
10959 openssl-users-request@openssl.org - General OpenSSL mailing list
10960 <http://www.ietf.org/rfc/rfc2246.txt> - TLS 1.0 specification
10961 <http://www.w3c.org> - HTTP specifications
10962 <http://www.ietf.org/rfc/rfc2617.txt> - How to send password
10963 <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
10964 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10965 - pseudo-random number generating daemon (PRNGD)
10966 perl(1)
10967 perlref(1)
10968 perllol(1)
10969 perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
10970perl v5.36.0 2023-01-20 Net::SSLeay(3)