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
102 own 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
142 some additional headers in the request. "make_headers()" is a function
143 that will convert a list or hash to such headers. By default
144 "get_https()" supplies "Host" (to make virtual hosting easy) and
145 "Accept" (reportedly 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
152 to 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
157 the formatting, but you could pass any string. "post_https()"
158 automatically adds "Content-Type" and "Content-Length" headers to the
159 request.
160 Case 4 (in SYNOPSIS) shows the fundamental "sslcat()" function
162 (inspired in spirit by the "netcat" utility :-). It's your swiss army
163 knife that allows you to easily contact servers, send some data, and
164 then get the response. You are responsible for formatting the data and
165 parsing the response - "sslcat()" is just a transport.
166 Case 5 (in SYNOPSIS) is a full invocation of "sslcat()" which allows
168 the return of errors as well as the server (peer) certificate.
169 The $trace global variable can be used to control the verbosity of the
171 high level functions. Level 0 guarantees silence, level 1 (the default)
172 only emits error messages.
173 Alternate versions of high-level API
175 • get_https3
177 • post_https3
179 • put_https3
181 • get_https4
183 • post_https4
185 • put_https4
187 The above mentioned functions actually return the response headers as a
189 list, which only gets converted to hash upon assignment (this
190 assignment looses information if the same header occurs twice, as may
191 be the case with cookies). There are also other variants of the
192 functions that return unprocessed headers and that return a reference
193 to a hash.
194 ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
196 for ($i = 0; $i < $#headers; $i+=2) {
197 print "$headers[$i] = " . $headers[$i+1] . "\n";
198 }
199 ($page, $response, $headers, $server_cert)
201 = get_https3('www.bacus.pt', 443, '/');
202 print "$headers\n";
203 ($page, $response, $headers_ref)
205 = get_https4('www.bacus.pt', 443, '/');
206 for $k (sort keys %{$headers_ref}) {
207 for $v (@{$$headers_ref{$k}}) {
208 print "$k = $v\n";
209 }
210 }
211 All of the above code fragments accomplish the same thing: display all
213 values of all headers. The API functions ending in "3" return the
214 headers simply as a scalar string and it is up to the application to
215 split them up. The functions ending in "4" return a reference to a hash
216 of arrays (see perlref and perllol if you are not familiar with complex
217 perl data structures). To access a single value of such a header hash
218 you would do something like
219 print $$headers_ref{COOKIE}[0];
221 Variants 3 and 4 also allow you to discover the server certificate in
223 case you would like to store or display it, e.g.
224 ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
226 if (!defined($server_cert) || ($server_cert == 0)) {
227 warn "Subject Name: undefined, Issuer Name: undefined";
228 } else {
229 warn 'Subject Name: '
230 . Net::SSLeay::X509_NAME_oneline(
231 Net::SSLeay::X509_get_subject_name($server_cert))
232 . 'Issuer Name: '
233 . Net::SSLeay::X509_NAME_oneline(
234 Net::SSLeay::X509_get_issuer_name($server_cert));
235 }
236 Beware that this method only allows after the fact verification of the
238 certificate: by the time "get_https3()" has returned the https request
239 has already been sent to the server, whether you decide to trust it or
240 not. To do the verification correctly you must either employ the
241 OpenSSL certificate verification framework or use the lower level API
242 to first connect and verify the certificate and only then send the http
243 data. See the implementation of "ds_https3()" for guidance on how to do
244 this.
245 Using client certificates
247 Secure web communications are encrypted using symmetric crypto keys
249 exchanged using encryption based on the certificate of the server.
250 Therefore in all SSL connections the server must have a certificate.
251 This serves both to authenticate the server to the clients and to
252 perform the key exchange.
253 Sometimes it is necessary to authenticate the client as well. Two
255 options are available: HTTP basic authentication and a client side
256 certificate. The basic authentication over HTTPS is actually quite safe
257 because HTTPS guarantees that the password will not travel in the
258 clear. Never-the-less, problems like easily guessable passwords remain.
259 The client certificate method involves authentication of the client at
260 the SSL level using a certificate. For this to work, both the client
261 and the server have certificates (which typically are different) and
262 private keys.
263 The API functions outlined above accept additional arguments that allow
265 one to supply the client side certificate and key files. The format of
266 these files is the same as used for server certificates and the caveat
267 about encrypting private keys applies.
268 ($page, $result, %headers) = # 2c
270 = get_https('www.bacus.pt', 443, '/protected.html',
271 make_headers(Authorization =>
272 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
273 '', $mime_type6, $path_to_crt7, $path_to_key8);
274 ($page, $response, %reply_headers)
276 = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
277 make_headers('Authorization' =>
278 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
279 make_form(OK => '1', name => 'Sampo'),
280 $mime_type6, $path_to_crt7, $path_to_key8);
281 Case 2c (in SYNOPSIS) demonstrates getting a password protected page
283 that also requires a client certificate, i.e. it is possible to use
284 both authentication methods simultaneously.
285 Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
287 requires both password authentication and a client certificate, just
288 like in case 2c.
289 Note: The client will not send a certificate unless the server requests
291 one. This is typically achieved by setting the verify mode to
292 "VERIFY_PEER" on the server:
293 Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
295 See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
297 description.
298 Working through a web proxy
300 • set_proxy
302 "Net::SSLeay" can use a web proxy to make its connections. You need to
304 first set the proxy host and port using "set_proxy()" and then just use
305 the normal API functions, e.g:
306 Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
308 ($page) = get_https('www.bacus.pt', 443, '/');
309 If your proxy requires authentication, you can supply a username and
311 password as well
312 Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
314 ($page, $result, %headers) =
315 = get_https('www.bacus.pt', 443, '/protected.html',
316 make_headers(Authorization =>
317 'Basic ' . MIME::Base64::encode("susie:pass",''))
318 );
319 This example demonstrates the case where we authenticate to the proxy
321 as "joe" and to the final web server as "susie". Proxy authentication
322 requires the "MIME::Base64" module to work.
323 HTTP (without S) API
325 • get_http
327 • post_http
329 • tcpcat
331 • get_httpx
333 • post_httpx
335 • tcpxcat
337 Over the years it has become clear that it would be convenient to use
339 the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
340 (see "LWP" for the heavy-weight object-oriented approach). In fact it
341 would be nice to be able to flip https on and off on the fly. Thus
342 regular HTTP support was evolved.
343 use Net::SSLeay qw(get_http post_http tcpcat
345 get_httpx post_httpx tcpxcat
346 make_headers make_form);
347 ($page, $result, %headers)
349 = get_http('www.bacus.pt', 443, '/protected.html',
350 make_headers(Authorization =>
351 'Basic ' . MIME::Base64::encode("$user:$pass",''))
352 );
353 ($page, $response, %reply_headers)
355 = post_http('www.bacus.pt', 443, '/foo.cgi', '',
356 make_form(OK => '1',
357 name => 'Sampo'
358 ));
359 ($reply, $err) = tcpcat($host, $port, $request);
361 ($page, $result, %headers)
363 = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
364 make_headers(Authorization =>
365 'Basic ' . MIME::Base64::encode("$user:$pass",''))
366 );
367 ($page, $response, %reply_headers)
369 = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
370 make_form(OK => '1', name => 'Sampo' ));
371 ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
373 As can be seen, the "x" family of APIs takes as the first argument a
375 flag which indicates whether SSL is used or not.
376 Certificate verification and Certificate Revocation Lists (CRLs)
378 OpenSSL supports the ability to verify peer certificates. It can also
379 optionally check the peer certificate against a Certificate Revocation
380 List (CRL) from the certificates issuer. A CRL is a file, created by
381 the certificate issuer that lists all the certificates that it
382 previously signed, but which it now revokes. CRLs are in PEM format.
383 You can enable "Net::SSLeay CRL" checking like this:
385 &Net::SSLeay::X509_STORE_set_flags
387 (&Net::SSLeay::CTX_get_cert_store($ssl),
388 &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
389 After setting this flag, if OpenSSL checks a peer's certificate, then
391 it will attempt to find a CRL for the issuer. It does this by looking
392 for a specially named file in the search directory specified by
393 CTX_load_verify_locations. CRL files are named with the hash of the
394 issuer's subject name, followed by ".r0", ".r1" etc. For example
395 "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
396 issuer, and then check for a revocation of the peer certificate in all
397 of them. (You can also force it to look in a specific named CRL file.,
398 see below). You can find out the hash of the issuer subject name in a
399 CRL with
400 openssl crl -in crl.pem -hash -noout
402 If the peer certificate does not pass the revocation list, or if no CRL
404 is found, then the handshaking fails with an error.
405 You can also force OpenSSL to look for CRLs in one or more arbitrarily
407 named files.
408 my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
410 my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
411 if ($crl) {
412 Net::SSLeay::X509_STORE_add_crl(
413 Net::SSLeay::CTX_get_cert_store($ssl, $crl)
414 );
415 } else {
416 error reading CRL....
417 }
418 Usually the URLs where you can download the CRLs is contained in the
420 certificate itself and you can extract them with
421 my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
423 But there is no automatic downloading of the CRLs and often these CRLs
425 are too huge to just download them to verify a single certificate.
426 Also, these CRLs are often in DER format which you need to convert to
427 PEM before you can use it:
428 openssl crl -in crl.der -inform der -out crl.pem
430 So as an alternative for faster and timely revocation checks you better
432 use the Online Status Revocation Protocol (OCSP).
433 Certificate verification and Online Status Revocation Protocol (OCSP)
435 While checking for revoked certificates is possible and fast with
436 Certificate Revocation Lists, you need to download the complete and
437 often huge list before you can verify a single certificate.
438 A faster way is to ask the CA to check the revocation of just a single
440 or a few certificates using OCSP. Basically you generate for each
441 certificate an OCSP_CERTID based on the certificate itself and its
442 issuer, put the ids togetether into an OCSP_REQUEST and send the
443 request to the URL given in the certificate.
444 As a result you get back an OCSP_RESPONSE and need to check the status
446 of the response, check that it is valid (e.g. signed by the CA) and
447 finally extract the information about each OCSP_CERTID to find out if
448 the certificate is still valid or got revoked.
449 With Net::SSLeay this can be done like this:
451 # get id(s) for given certs, like from get_peer_certificate
453 # or get_peer_cert_chain. This will croak if
454 # - one tries to make an OCSP_CERTID for a self-signed certificate
455 # - the issuer of the certificate cannot be found in the SSL objects
456 # store, nor in the current certificate chain
457 my $cert = Net::SSLeay::get_peer_certificate($ssl);
458 my $id = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) };
459 die "failed to make OCSP_CERTID: $@" if $@;
460 # create OCSP_REQUEST from id(s)
462 # Multiple can be put into the same request, if the same OCSP responder
463 # is responsible for them.
464 my $req = Net::SSLeay::OCSP_ids2req($id);
465 # determine URI of OCSP responder
467 my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
468 # Send stringified OCSP_REQUEST with POST to $uri.
470 # We can ignore certificate verification for https, because the OCSP
471 # response itself is signed.
472 my $ua = HTTP::Tiny->new(verify_SSL => 0);
473 my $res = $ua->request( 'POST',$uri, {
474 headers => { 'Content-type' => 'application/ocsp-request' },
475 content => Net::SSLeay::i2d_OCSP_REQUEST($req)
476 });
477 my $content = $res && $res->{success} && $res->{content}
478 or die "query failed";
479 # Extract OCSP_RESPONSE.
481 # this will croak if the string is not an OCSP_RESPONSE
482 my $resp = eval { Net::SSLeay::d2i_OCSP_RESPONSE($content) };
483 # Check status of response.
485 my $status = Net::SSLeay::OCSP_response_status($resp);
486 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL())
487 die "OCSP response failed: ".
488 Net::SSLeay::OCSP_response_status_str($status);
489 }
490 # Verify signature of response and if nonce matches request.
492 # This will croak if there is a nonce in the response, but it does not match
493 # the request. It will return false if the signature could not be verified,
494 # in which case details can be retrieved with Net::SSLeay::ERR_get_error.
495 # It will not complain if the response does not contain a nonce, which is
496 # usually the case with pre-signed responses.
497 if ( ! eval { Net::SSLeay::OCSP_response_verify($ssl,$resp,$req) }) {
498 die "OCSP response verification failed";
499 }
500 # Extract information from OCSP_RESPONSE for each of the ids.
502 # If called in scalar context it will return the time (as time_t), when the
504 # next update is due (minimum of all successful responses inside $resp). It
505 # will croak on the following problems:
506 # - response is expired or not yet valid
507 # - no response for given OCSP_CERTID
508 # - certificate status is not good (e.g. revoked or unknown)
509 if ( my $nextupd = eval { Net::SSLeay::OCSP_response_results($resp,$id) }) {
510 warn "certificate is valid, next update in ".
511 ($nextupd-time())." seconds\n";
512 } else {
513 die "certificate is not valid: $@";
514 }
515 # But in array context it will return detailed information about each given
517 # OCSP_CERTID instead croaking on errors:
518 # if no @ids are given it will return information about all single responses
519 # in the OCSP_RESPONSE
520 my @results = Net::SSLeay::OCSP_response_results($resp,@ids);
521 for my $r (@results) {
522 print Dumper($r);
523 # @results are in the same order as the @ids and contain:
524 # $r->[0] - OCSP_CERTID
525 # $r->[1] - undef if no error (certificate good) OR error message as string
526 # $r->[2] - hash with details:
527 # thisUpdate - time_t of this single response
528 # nextUpdate - time_t when update is expected
529 # statusType - integer:
530 # V_OCSP_CERTSTATUS_GOOD(0)
531 # V_OCSP_CERTSTATUS_REVOKED(1)
532 # V_OCSP_CERTSTATUS_UNKNOWN(2)
533 # revocationTime - time_t (only if revoked)
534 # revocationReason - integer (only if revoked)
535 # revocationReason_str - reason as string (only if revoked)
536 }
537 To further speed up certificate revocation checking one can use a TLS
539 extension to instruct the server to staple the OCSP response:
540 # set TLS extension before doing SSL_connect
542 Net::SSLeay::set_tlsext_status_type($ssl,
543 Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
544 # setup callback to verify OCSP response
546 my $cert_valid = undef;
547 Net::SSLeay::CTX_set_tlsext_status_cb($context,sub {
548 my ($ssl,$resp) = @_;
549 if (!$resp) {
550 # Lots of servers don't return an OCSP response.
551 # In this case we must check the OCSP status outside the SSL
552 # handshake.
553 warn "server did not return stapled OCSP response\n";
554 return 1;
555 }
556 # verify status
557 my $status = Net::SSLeay::OCSP_response_status($resp);
558 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL()) {
559 warn "OCSP response failure: $status\n";
560 return 1;
561 }
562 # verify signature - we have no OCSP_REQUEST here to check nonce
563 if (!eval { Net::SSLeay::OCSP_response_verify($ssl,$resp) }) {
564 warn "OCSP response verify failed\n";
565 return 1;
566 }
567 # check if the certificate is valid
568 # we should check here against the peer_certificate
569 my $cert = Net::SSLeay::get_peer_certificate();
570 my $certid = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) } or do {
571 warn "cannot get certid from cert: $@";
572 $cert_valid = -1;
573 return 1;
574 };
575 if ( $nextupd = eval {
577 Net::SSLeay::OCSP_response_results($resp,$certid) }) {
578 warn "certificate not revoked\n";
579 $cert_valid = 1;
580 } else {
581 warn "certificate not valid: $@";
582 $cert_valid = 0;
583 }
584 });
585 # do SSL handshake here
587 ....
588 # check if certificate revocation was checked already
589 if ( ! defined $cert_valid) {
590 # check revocation outside of SSL handshake by asking OCSP responder
591 ...
592 } elsif ( ! $cert_valid ) {
593 die "certificate not valid - closing SSL connection";
594 } elsif ( $cert_valid<0 ) {
595 die "cannot verify certificate revocation - self-signed ?";
596 } else {
597 # everything fine
598 ...
599 }
600 Using Net::SSLeay in multi-threaded applications
602 IMPORTANT: versions 1.42 or earlier are not thread-safe!
603 Net::SSLeay module implements all necessary stuff to be ready for
605 multi-threaded environment - it requires openssl-0.9.7 or newer. The
606 implementation fully follows thread safety related requirements of
607 openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
608 If you are about to use Net::SSLeay (or any other module based on
610 Net::SSLeay) in multi-threaded perl application it is recommended to
611 follow this best-practice:
612 Initialization
614 Load and initialize Net::SSLeay module in the main thread:
616 use threads;
618 use Net::SSLeay;
619 Net::SSLeay::load_error_strings();
621 Net::SSLeay::SSLeay_add_ssl_algorithms();
622 Net::SSLeay::randomize();
623 sub do_master_job {
625 #... call whatever from Net::SSLeay
626 }
627 sub do_worker_job {
629 #... call whatever from Net::SSLeay
630 }
631 #start threads
633 my $master = threads->new(\&do_master_job, 'param1', 'param2');
634 my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
635 #waiting for all threads to finish
637 $_->join() for (threads->list);
638 NOTE: Openssl's "int SSL_library_init(void)" function (which is also
640 aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
641 and "add_ssl_algorithms") is not re-entrant and multiple calls can
642 cause a crash in threaded application. Net::SSLeay implements flags
643 preventing repeated calls to this function, therefore even multiple
644 initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
645 without trouble.
646 Using callbacks
648 Do not use callbacks across threads (the module blocks cross-thread
650 callback operations and throws a warning). Always do the callback
651 setup, callback use and callback destruction within the same thread.
652 Using openssl elements
654 All openssl elements (X509, SSL_CTX, ...) can be directly passed
656 between threads.
657 use threads;
659 use Net::SSLeay;
660 Net::SSLeay::load_error_strings();
662 Net::SSLeay::SSLeay_add_ssl_algorithms();
663 Net::SSLeay::randomize();
664 sub do_job {
666 my $context = shift;
667 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
668 #...
669 }
670 my $c = Net::SSLeay::CTX_new();
672 threads->create(\&do_job, $c);
673 Or:
675 use threads;
677 use Net::SSLeay;
678 my $context; #does not need to be 'shared'
680 Net::SSLeay::load_error_strings();
682 Net::SSLeay::SSLeay_add_ssl_algorithms();
683 Net::SSLeay::randomize();
684 sub do_job {
686 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
687 #...
688 }
689 $context = Net::SSLeay::CTX_new();
691 threads->create(\&do_job);
692 Using other perl modules based on Net::SSLeay
694 It should be fine to use any other module based on Net::SSLeay (like
696 IO::Socket::SSL) in multi-threaded applications. It is generally
697 recommended to do any global initialization of such a module in the
698 main thread before calling "threads->new(..)" or "threads->create(..)"
699 but it might differ module by module.
700 To be safe you can load and init Net::SSLeay explicitly in the main
702 thread:
703 use Net::SSLeay;
705 use Other::SSLeay::Based::Module;
706 Net::SSLeay::load_error_strings();
708 Net::SSLeay::SSLeay_add_ssl_algorithms();
709 Net::SSLeay::randomize();
710 Or even safer:
712 use Net::SSLeay;
714 use Other::SSLeay::Based::Module;
715 BEGIN {
717 Net::SSLeay::load_error_strings();
718 Net::SSLeay::SSLeay_add_ssl_algorithms();
719 Net::SSLeay::randomize();
720 }
721 Combining Net::SSLeay with other modules linked with openssl
723 BEWARE: This might be a big trouble! This is not guaranteed be thread-
725 safe!
726 There are many other (XS) modules linked directly to openssl library
728 (like Crypt::SSLeay).
729 As it is expected that also "another" module will call
731 "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
732 multiple openssl initialization by Net::SSLeay and "another" module.
733 As you can expect Net::SSLeay is not able to avoid multiple
735 initialization of openssl library called by "another" module, thus you
736 have to handle this on your own (in some cases it might not be possible
737 at all to avoid this).
738 Threading with get_https and friends
740 The convenience functions get_https, post_https etc all initialize the
742 SSL library by calling Net::SSLeay::initialize which does the
743 conventional library initialization:
744 Net::SSLeay::load_error_strings();
746 Net::SSLeay::SSLeay_add_ssl_algorithms();
747 Net::SSLeay::randomize();
748 Net::SSLeay::initialize initializes the SSL library at most once. You
750 can override the Net::SSLeay::initialize function if you desire some
751 other type of initialization behaviour by get_https and friends. You
752 can call Net::SSLeay::initialize from your own code if you desire this
753 conventional library initialization.
754 Convenience routines
756 To be used with Low level API
757 Net::SSLeay::randomize($rn_seed_file,$additional_seed);
759 Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
760 $cert = Net::SSLeay::dump_peer_certificate($ssl);
761 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
762 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
763 $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
765 $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
766 Net::SSLeay::ssl_write_CRLF($ssl, $message);
767 • randomize
769 seeds the openssl PRNG with "/dev/urandom" (see the top of
771 "SSLeay.pm" for how to change or configure this) and optionally
772 with user provided data. It is very important to properly seed your
773 random numbers, so do not forget to call this. The high level API
774 functions automatically call "randomize()" so it is not needed with
775 them. See also caveats.
776 • set_cert_and_key
778 takes two file names as arguments and sets the certificate and
780 private key to those. This can be used to set either server
781 certificates or client certificates.
782 • dump_peer_certificate
784 allows you to get a plaintext description of the certificate the
786 peer (usually the server) presented to us.
787 • ssl_read_all
789 see ssl_write_all (below)
791 • ssl_write_all
793 "ssl_read_all()" and "ssl_write_all()" provide true blocking
795 semantics for these operations (see limitation, below, for
796 explanation). These are much preferred to the low level API
797 equivalents (which implement BSD blocking semantics). The message
798 argument to "ssl_write_all()" can be a reference. This is helpful
799 to avoid unnecessary copying when writing something big, e.g:
800 $data = 'A' x 1000000000;
802 Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
803 • ssl_read_CRLF
805 uses "ssl_read_all()" to read in a line terminated with a carriage
807 return followed by a linefeed (CRLF). The CRLF is included in the
808 returned scalar.
809 • ssl_read_until
811 uses "ssl_read_all()" to read from the SSL input stream until it
813 encounters a programmer specified delimiter. If the delimiter is
814 undefined, $/ is used. If $/ is undefined, "\n" is used. One can
815 optionally set a maximum length of bytes to read from the SSL input
816 stream.
817 • ssl_write_CRLF
819 writes $message and appends CRLF to the SSL output stream.
821 Initialization
823 In order to use the low level API you should start your programs with
824 the following incantation:
825 use Net::SSLeay qw(die_now die_if_ssl_error);
827 Net::SSLeay::load_error_strings();
828 Net::SSLeay::SSLeay_add_ssl_algorithms(); # Important!
829 Net::SSLeay::ENGINE_load_builtin_engines(); # If you want built-in engines
830 Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
831 Net::SSLeay::randomize();
832 Error handling functions
834 I can not emphasize the need to check for error enough. Use these
835 functions even in the most simple programs, they will reduce debugging
836 time greatly. Do not ask questions on the mailing list without having
837 first sprinkled these in your code.
838 • die_now
840 • die_if_ssl_error
842 "die_now()" and "die_if_ssl_error()" are used to conveniently print
844 the SSLeay error stack when something goes wrong:
845 Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
847 Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
850 • print_errs
852 You can also use "Net::SSLeay::print_errs()" to dump the error
854 stack without exiting the program. As can be seen, your code
855 becomes much more readable if you import the error reporting
856 functions into your main name space.
857 Sockets
859 Perl uses file handles for all I/O. While SSLeay has a quite flexible
860 BIO mechanism and perl has an evolved PerlIO mechanism, this module
861 still sticks to using file descriptors. Thus to attach SSLeay to a
862 socket you should use "fileno()" to extract the underlying file
863 descriptor:
864 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
866 You should also set $| to 1 to eliminate STDIO buffering so you do not
868 get confused if you use perl I/O functions to manipulate your socket
869 handle.
870 If you need to select(2) on the socket, go right ahead, but be warned
872 that OpenSSL does some internal buffering so SSL_read does not always
873 return data even if the socket selected for reading (just keep on
874 selecting and trying to read). "Net::SSLeay" is no different from the C
875 language OpenSSL in this respect.
876 Callbacks
878 You can establish a per-context verify callback function something like
879 this:
880 sub verify {
882 my ($ok, $x509_store_ctx) = @_;
883 print "Verifying certificate...\n";
884 ...
885 return $ok;
886 }
887 It is used like this:
889 Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
891 Per-context callbacks for decrypting private keys are implemented.
893 Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
895 Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
896 Net::SSLeay::FILETYPE_PEM)
897 or die "Error reading private key";
898 Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
899 If Hello Extensions are supported by your OpenSSL, a session secret
901 callback can be set up to be called when a session secret is set by
902 openssl.
903 Establish it like this:
905 Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb, $somedata);
907 It will be called like this:
909 sub session_secret_cb
911 {
912 my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
913 }
914 No other callbacks are implemented. You do not need to use any callback
916 for simple (i.e. normal) cases where the SSLeay built-in verify
917 mechanism satisfies your needs.
918 It is required to reset these callbacks to undef immediately after use
920 to prevent memory leaks, thread safety problems and crashes on exit
921 that can occur if different threads set different callbacks.
922 If you want to use callback stuff, see examples/callback.pl! It's the
924 only one I am able to make work reliably.
925 Low level API
927 In addition to the high level functions outlined above, this module
928 contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
929 API.
930 See the "*.h" headers from OpenSSL C distribution for a list of low
932 level SSLeay functions to call (check SSLeay.xs to see if some function
933 has been implemented). The module strips the initial "SSL_" off of the
934 SSLeay names. Generally you should use "Net::SSLeay::" in its place.
935 Note that some functions are prefixed with "P_" - these are very close
937 to the original API however contain some kind of a wrapper making its
938 interface more perl friendly.
939 For example:
941 In C:
943 #include <ssl.h>
945 err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
947 &your_call_back_here);
948 In Perl:
950 use Net::SSLeay;
952 $err = Net::SSLeay::set_verify ($ssl,
954 Net::SSLeay::VERIFY_CLIENT_ONCE,
955 \&your_call_back_here);
956 If the function does not start with "SSL_" you should use the full
958 function name, e.g.:
959 $err = Net::SSLeay::ERR_get_error;
961 The following new functions behave in perlish way:
963 $got = Net::SSLeay::read($ssl);
965 # Performs SSL_read, but returns $got
966 # resized according to data received.
967 # Returns undef on failure.
968 Net::SSLeay::write($ssl, $foo) || die;
970 # Performs SSL_write, but automatically
971 # figures out the size of $foo
972 Low level API: Version and library information related functions
974 • OpenSSL_version_num and SSLeay
976 COMPATIBILITY: SSLeay() is not available in Net-SSLeay-1.42 and
978 before. SSLeay() was made an alias of OpenSSL_version_num() in
979 OpenSSL 1.1.0 and LibreSSL 2.7.0.
980 COMPATIBILITY: OpenSSL_version_num() requires at least
982 Net-SSLeay-1.82 with OpenSSL 1.1.0, or Net-SSLeay-1.88 with
983 LibreSSL 2.7.0.
984 Both functions return OPENSSL_VERSION_NUMBER constant (numeric) as
986 defined by the underlying OpenSSL or LibreSSL library.
987 my $ver_number = Net::SSLeay::SSLeay();
989 or
990 my $ver_number = Net::SSLeay::OpenSSL_version_num();
991 # returns: OPENSSL_VERSION_NUMBER constant
992 OpenSSL version numbering is:
994 # 0x00903100 => openssl-0.9.3
996 # 0x00904100 => openssl-0.9.4
997 # 0x00905100 => openssl-0.9.5
998 # 0x0090600f => openssl-0.9.6
999 # 0x0090601f => openssl-0.9.6a
1000 # ...
1001 # 0x009060df => openssl-0.9.6m
1002 # 0x0090700f => openssl-0.9.7
1003 # 0x0090701f => openssl-0.9.7a
1004 # ...
1005 # 0x009070df => openssl-0.9.7m
1006 # 0x0090800f => openssl-0.9.8
1007 # 0x0090801f => openssl-0.9.8a
1008 # ...
1009 # 0x0090821f => openssl-0.9.8zh
1010 # 0x1000000f => openssl-1.0.0
1011 # ...
1012 # 0x1000014f => openssl-1.0.0t
1013 # 0x1000100f => openssl-1.0.1
1014 # ...
1015 # 0x1000115f => openssl-1.0.1u
1016 # 0x1000200f => openssl-1.0.2
1017 # ...
1018 # 0x1000215f => openssl-1.0.2u
1019 # 0x1010000f => openssl-1.1.0
1020 # ...
1021 # 0x101000cf => openssl-1.1.0l
1022 # 0x1010100f => openssl-1.1.1
1023 # ...
1024 # 0x101010df => openssl-1.1.1m
1025 # 0x30000000 => openssl-3.0.0
1026 # 0x30000010 => openssl-3.0.1
1027 Note that OpenSSL 3.0.0 and later do not set the status nibble in the
1029 least significant octet to f.
1030 LibreSSL returns 0x20000000 always:
1032 # 0x20000000 => libressl-2.2.1
1034 # ...
1035 # 0x20000000 => libressl-3.4.2
1036 You can use the version number like this when you know that the
1038 underlying library is OpenSSL:
1039 if (Net::SSLeay::SSLeay() < 0x0090800f) {
1041 die "You need OpenSSL 0.9.8 or higher";
1042 }
1043 LibresSSL 2.2.2 and later define constant LIBRESSL_VERSION_NUMBER
1045 that gives the LibreSSL version number. The format is the same that
1046 OpenSSL uses with OPENSSL_VERSION_NUMBER. You can do this if you
1047 need to check that the underlying library is LibreSSL and it's
1048 recent enough:
1049 if (Net::SSLeay::SSLeay() != 0x20000000 ||
1051 Net::SSLeay::LIBRESSL_VERSION_NUMBER() < 0x3040200f) {
1052 die "You need LibreSSL. Version 3.4.2 or higher";
1053 }
1054 Check openssl doc
1056 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version_num.html>
1057 See OpenSSL 1.1.1 and earlier documentation for the details of
1059 status nibble and the format interpretation.
1060 • SSLeay_version
1062 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
1064 Returns different strings depending on $type.
1066 my $ver_string = Net::SSLeay::SSLeay_version($type);
1068 # $type
1069 # SSLEAY_VERSION - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
1070 # SSLEAY_CFLAGS - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
1071 # SSLEAY_BUILT_ON - e.g. 'built on: Fri May 6 00:00:46 GMT 2011'
1072 # SSLEAY_PLATFORM - e.g. 'platform: mingw'
1073 # SSLEAY_DIR - e.g. 'OPENSSLDIR: "z:/...."'
1074 #
1075 # returns: string
1076 Net::SSLeay::SSLeay_version();
1078 #is equivalent to
1079 Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
1080 OpenSSL 1.1.0 changed SSLeay_version() to an alias of
1082 OpenSSL_version(). To ensure correct functionality with LibreSSL,
1083 use SSLEAY_* constants with SSLeay_version() and OPENSSL_*
1084 constants with OpenSSL_version().
1085 Check openssl doc
1087 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1088 OpenSSL website no longer has a manual page for SSLeay_version().
1090 • OpenSSL_version
1092 COMPATIBILITY: requires at least Net-SSLeay-1.82 with OpenSSL
1094 1.1.0, or Net-SSLeay-1.88 with LibreSSL 2.7.0.
1095 Returns different strings depending on $t. Available $t constants
1097 depend on the library version.
1098 my $ver_string = Net::SSLeay::OpenSSL_version($t);
1100 # $t
1101 # OPENSSL_VERSION - e.g. 'OpenSSL 1.1.0g 2 Nov 2017'
1102 # OPENSSL_CFLAGS - e.g. 'compiler: cc -DDSO_DLFCN -DHAVE_DLFCN_H .....'
1103 # OPENSSL_BUILT_ON - e.g. 'built on: reproducible build, date unspecified'
1104 # OPENSSL_PLATFORM - e.g. 'platform: darwin64-x86_64-cc'
1105 # OPENSSL_DIR - e.g. 'OPENSSLDIR: "/opt/openssl-1.1.0g"'
1106 # OPENSSL_ENGINES_DIR - e.g. 'ENGINESDIR: "/opt/openssl-1.1.0g/lib/engines-1.1"'
1107 #
1108 # returns: string
1109 Net::SSLeay::OpenSSL_version();
1111 #is equivalent to
1112 Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1113 Check openssl doc
1115 <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1116 • OPENSSL_info
1118 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1120 requires at least OpenSSL 3.0.0-alpha1
1121 Returns different strings depending on $t. Available $t constants
1123 depend on the library version.
1124 my $info_string = Net::SSLeay::OPENSSL_info($t);
1126 # $t
1127 # OPENSSL_INFO_CONFIG_DIR - e.g. '/opt/openssl-3.0.1'
1128 # OPENSSL_INFO_...
1129 #
1130 # returns: string
1131 Check openssl doc
1133 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_info.html>
1134 • OPENSSL_version_major, OPENSSL_version_minor and
1136 OPENSSL_version_patch
1137 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1139 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1140 Return constants OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR and
1142 OPENSSL_VERSION_PATCH, respectively.
1143 my $major = Net::SSLeay::OPENSSL_version_major();
1145 my $minor = Net::SSLeay::OPENSSL_version_minor();
1146 my $patch = Net::SSLeay::OPENSSL_version_patch();
1147 #
1148 # return: integer
1149 For example with OpenSSL 3.0.1, $major is 3, $minor is 0 and $patch
1151 is 1.
1152 Note: the constants record Net::SSLeay compile time values whereas
1154 the three functions return values from the library. Typically these
1155 are the same, but they can be different if the library version is
1156 updated but Net::SSLeay is not re-compiled. See the OpenSSL and
1157 LibreSSL API/ABI compatibility statements for more information.
1158 Check openssl doc
1160 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_major.html>
1161 • OPENSSL_version_pre_release
1163 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1165 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1166 Return constant string defined by C macro
1168 OPENSSL_VERSION_PRE_RELEASE.
1169 my $pre_release = Net::SSLeay::OPENSSL_version_pre_release();
1171 #
1172 # returns: string
1173 For example: "-alpha3" or "" for a release version.
1175 When the macro is not defined, an empty string is returned instead.
1177 Check openssl doc
1179 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_pre_release.html>
1180 • OPENSSL_version_build_metadata()
1182 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1184 requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1185 Return constant string defined by C macro
1187 OPENSSL_VERSION_BUILD_METADATA.
1188 my $metadata = Net::SSLeay::OPENSSL_version_build_metadata();
1190 #
1191 # returns: string
1192 For example: "+fips" or "".
1194 When the macro is not defined, an empty string is returned instead.
1196 Check openssl doc
1198 <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_build_metadata.html>
1199 Low level API: Initialization related functions
1201 • library_init
1203 Initialize SSL library by registering algorithms.
1205 my $rv = Net::SSLeay::library_init();
1207 Check openssl doc
1209 <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1210 While the original function from OpenSSL always returns 1,
1212 Net::SSLeay adds a wrapper around it to make sure that the OpenSSL
1213 function is only called once. Thus the function will return 1 if
1214 initialization was done and 0 if not, i.e. if initialization was
1215 done already before.
1216 • add_ssl_algorithms
1218 The alias for "library_init"
1220 Net::SSLeay::add_ssl_algorithms();
1222 • OpenSSL_add_ssl_algorithms
1224 The alias for "library_init"
1226 Net::SSLeay::OpenSSL_add_ssl_algorithms();
1228 • SSLeay_add_ssl_algorithms
1230 The alias for "library_init"
1232 Net::SSLeay::SSLeay_add_ssl_algorithms();
1234 • load_error_strings
1236 Registers the error strings for all libcrypto + libssl related
1238 functions.
1239 Net::SSLeay::load_error_strings();
1241 #
1242 # returns: no return value
1243 Check openssl doc
1245 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1246 • ERR_load_crypto_strings
1248 Registers the error strings for all libcrypto functions. No need to
1250 call this function if you have already called "load_error_strings".
1251 Net::SSLeay::ERR_load_crypto_strings();
1253 #
1254 # returns: no return value
1255 Check openssl doc
1257 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1258 • ERR_load_RAND_strings
1260 Registers the error strings for RAND related functions. No need to
1262 call this function if you have already called "load_error_strings".
1263 Net::SSLeay::ERR_load_RAND_strings();
1265 #
1266 # returns: no return value
1267 • ERR_load_SSL_strings
1269 Registers the error strings for SSL related functions. No need to
1271 call this function if you have already called "load_error_strings".
1272 Net::SSLeay::ERR_load_SSL_strings();
1274 #
1275 # returns: no return value
1276 • OpenSSL_add_all_algorithms
1278 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1280 Add algorithms to internal table.
1282 Net::SSLeay::OpenSSL_add_all_algorithms();
1284 #
1285 # returns: no return value
1286 Check openssl doc
1288 <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1289 • OPENSSL_add_all_algorithms_conf
1291 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1293 Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1295 config file
1296 Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1298 #
1299 # returns: no return value
1300 • OPENSSL_add_all_algorithms_noconf
1302 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1304 Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1306 config file
1307 Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1309 #
1310 # returns: no return value
1311 Low level API: ERR_* and SSL_alert_* related functions
1313 NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1315 from their names.
1316 • ERR_clear_error
1318 Clear the error queue.
1320 Net::SSLeay::ERR_clear_error();
1322 #
1323 # returns: no return value
1324 Check openssl doc
1326 <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1327 • ERR_error_string
1329 Generates a human-readable string representing the error code
1331 $error.
1332 my $rv = Net::SSLeay::ERR_error_string($error);
1334 # $error - (unsigned integer) error code
1335 #
1336 # returns: string
1337 Check openssl doc
1339 <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1340 • ERR_get_error
1342 Returns the earliest error code from the thread's error queue and
1344 removes the entry. This function can be called repeatedly until
1345 there are no more error codes to return.
1346 my $rv = Net::SSLeay::ERR_get_error();
1348 #
1349 # returns: (unsigned integer) error code
1350 Check openssl doc
1352 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1353 • ERR_peek_error
1355 Returns the earliest error code from the thread's error queue
1357 without modifying it.
1358 my $rv = Net::SSLeay::ERR_peek_error();
1360 #
1361 # returns: (unsigned integer) error code
1362 Check openssl doc
1364 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1365 • ERR_put_error
1367 Adds an error code to the thread's error queue. It signals that the
1369 error of $reason code reason occurred in function $func of library
1370 $lib, in line number $line of $file.
1371 Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
1373 # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
1374 # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
1375 # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
1376 # $file - (string) file name
1377 # $line - (integer) line number in $file
1378 #
1379 # returns: no return value
1380 Check openssl doc
1382 <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
1383 <http://www.openssl.org/docs/crypto/err.html>
1384 • alert_desc_string
1386 Returns a two letter string as a short form describing the reason
1388 of the alert specified by value.
1389 my $rv = Net::SSLeay::alert_desc_string($value);
1391 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1392 #
1393 # returns: description string (2 letters)
1394 Check openssl doc
1396 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1397 • alert_desc_string_long
1399 Returns a string describing the reason of the alert specified by
1401 value.
1402 my $rv = Net::SSLeay::alert_desc_string_long($value);
1404 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1405 #
1406 # returns: description string
1407 Check openssl doc
1409 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1410 • alert_type_string
1412 Returns a one letter string indicating the type of the alert
1414 specified by value.
1415 my $rv = Net::SSLeay::alert_type_string($value);
1417 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1418 #
1419 # returns: string (1 letter)
1420 Check openssl doc
1422 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1423 • alert_type_string_long
1425 Returns a string indicating the type of the alert specified by
1427 value.
1428 my $rv = Net::SSLeay::alert_type_string_long($value);
1430 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1431 #
1432 # returns: string
1433 Check openssl doc
1435 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1436 Low level API: SSL_METHOD_* related functions
1438 • SSLv23_method, SSLv23_server_method and SSLv23_client_method
1440 COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1442 Returns SSL_METHOD structure corresponding to general-purpose
1444 version-flexible TLS method, the return value can be later used as
1445 a param of "CTX_new_with_method".
1446 NOTE: Consider using TLS_method, TLS_server_method or
1448 TLS_client_method with new code.
1449 my $rv = Net::SSLeay::SSLv2_method();
1451 #
1452 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1453 • SSLv2_method
1455 Returns SSL_METHOD structure corresponding to SSLv2 method, the
1457 return value can be later used as a param of "CTX_new_with_method".
1458 Only available where supported by the underlying openssl.
1459 my $rv = Net::SSLeay::SSLv2_method();
1461 #
1462 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1463 • SSLv3_method
1465 Returns SSL_METHOD structure corresponding to SSLv3 method, the
1467 return value can be later used as a param of "CTX_new_with_method".
1468 my $rv = Net::SSLeay::SSLv3_method();
1470 #
1471 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1472 Check openssl doc
1474 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1475 • TLSv1_method, TLSv1_server_method and TLSv1_client_method
1477 COMPATIBILITY: Server and client methods not available in
1479 Net-SSLeay-1.82 and before.
1480 Returns SSL_METHOD structure corresponding to TLSv1 method, the
1482 return value can be later used as a param of "CTX_new_with_method".
1483 my $rv = Net::SSLeay::TLSv1_method();
1485 #
1486 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1487 Check openssl doc
1489 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1490 • TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1492 COMPATIBILITY: Server and client methods not available in
1494 Net-SSLeay-1.82 and before.
1495 Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1497 return value can be later used as a param of "CTX_new_with_method".
1498 Only available where supported by the underlying openssl.
1499 my $rv = Net::SSLeay::TLSv1_1_method();
1501 #
1502 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1503 Check openssl doc
1505 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1506 • TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1508 COMPATIBILITY: Server and client methods not available in
1510 Net-SSLeay-1.82 and before.
1511 Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1513 return value can be later used as a param of "CTX_new_with_method".
1514 Only available where supported by the underlying openssl.
1515 my $rv = Net::SSLeay::TLSv1_2_method();
1517 #
1518 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1519 Check openssl doc
1521 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1522 • TLS_method, TLS_server_method and TLS_client_method
1524 COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1526 Returns SSL_METHOD structure corresponding to general-purpose
1528 version-flexible TLS method, the return value can be later used as
1529 a param of "CTX_new_with_method". Only available where supported by
1530 the underlying openssl.
1531 my $rv = Net::SSLeay::TLS_method();
1533 #
1534 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1535 Check openssl doc
1537 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1538 Low level API: ENGINE_* related functions
1540 • ENGINE_load_builtin_engines
1542 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1544 loading support.
1545 Load all bundled ENGINEs into memory and make them visible.
1547 Net::SSLeay::ENGINE_load_builtin_engines();
1549 #
1550 # returns: no return value
1551 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1553 • ENGINE_register_all_complete
1555 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1557 loading support.
1558 Register all loaded ENGINEs for every algorithm they collectively
1560 implement.
1561 Net::SSLeay::ENGINE_register_all_complete();
1563 #
1564 # returns: no return value
1565 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1567 • ENGINE_set_default
1569 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1571 loading support.
1572 Set default engine to $e + set its flags to $flags.
1574 my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1576 # $e - value corresponding to openssl's ENGINE structure
1577 # $flags - (integer) engine flags
1578 # flags value can be made by bitwise "OR"ing:
1579 # 0x0001 - ENGINE_METHOD_RSA
1580 # 0x0002 - ENGINE_METHOD_DSA
1581 # 0x0004 - ENGINE_METHOD_DH
1582 # 0x0008 - ENGINE_METHOD_RAND
1583 # 0x0010 - ENGINE_METHOD_ECDH
1584 # 0x0020 - ENGINE_METHOD_ECDSA
1585 # 0x0040 - ENGINE_METHOD_CIPHERS
1586 # 0x0080 - ENGINE_METHOD_DIGESTS
1587 # 0x0100 - ENGINE_METHOD_STORE
1588 # 0x0200 - ENGINE_METHOD_PKEY_METHS
1589 # 0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1590 # Obvious all-or-nothing cases:
1591 # 0xFFFF - ENGINE_METHOD_ALL
1592 # 0x0000 - ENGINE_METHOD_NONE
1593 #
1594 # returns: 1 on success, 0 on failure
1595 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1597 • ENGINE_by_id
1599 Get ENGINE by its identification $id.
1601 COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1603 loading support.
1604 my $rv = Net::SSLeay::ENGINE_by_id($id);
1606 # $id - (string) engine identification e.g. "dynamic"
1607 #
1608 # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1609 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1611 Low level API: EVP_PKEY_* related functions
1613 • EVP_PKEY_copy_parameters
1615 Copies the parameters from key $from to key $to.
1617 my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1619 # $to - value corresponding to openssl's EVP_PKEY structure
1620 # $from - value corresponding to openssl's EVP_PKEY structure
1621 #
1622 # returns: 1 on success, 0 on failure
1623 Check openssl doc
1625 <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1626 • EVP_PKEY_new
1628 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1630 Creates a new EVP_PKEY structure.
1632 my $rv = Net::SSLeay::EVP_PKEY_new();
1634 #
1635 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1636 Check openssl doc
1638 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1639 • EVP_PKEY_free
1641 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1643 Free an allocated EVP_PKEY structure.
1645 Net::SSLeay::EVP_PKEY_free($pkey);
1647 # $pkey - value corresponding to openssl's EVP_PKEY structure
1648 #
1649 # returns: no return value
1650 Check openssl doc
1652 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1653 • EVP_PKEY_assign_RSA
1655 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1657 Set the key referenced by $pkey to $key
1659 NOTE: No reference counter will be increased, i.e. $key will be
1661 freed if $pkey is freed.
1662 my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1664 # $pkey - value corresponding to openssl's EVP_PKEY structure
1665 # $key - value corresponding to openssl's RSA structure
1666 #
1667 # returns: 1 on success, 0 on failure
1668 Check openssl doc
1670 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1671 • EVP_PKEY_assign_EC_KEY
1673 COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1675 Set the key referenced by $pkey to $key
1677 NOTE: No reference counter will be increased, i.e. $key will be
1679 freed if $pkey is freed.
1680 my $rv = Net::SSLeay::EVP_PKEY_assign_EC_KEY($pkey, $key);
1682 # $pkey - value corresponding to openssl's EVP_PKEY structure
1683 # $key - value corresponding to openssl's EC_KEY structure
1684 #
1685 # returns: 1 on success, 0 on failure
1686 Check openssl doc
1688 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1689 • EVP_PKEY_bits
1691 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1693 Returns the size of the key $pkey in bits.
1695 my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1697 # $pkey - value corresponding to openssl's EVP_PKEY structure
1698 #
1699 # returns: size in bits
1700 • EVP_PKEY_size
1702 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1704 Returns the maximum size of a signature in bytes. The actual
1706 signature may be smaller.
1707 my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1709 # $pkey - value corresponding to openssl's EVP_PKEY structure
1710 #
1711 # returns: the maximum size in bytes
1712 Check openssl doc
1714 <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1715 • EVP_PKEY_id
1717 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1719 requires at least openssl-1.0.0
1720 Returns $pkey type (integer value of corresponding NID).
1722 my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1724 # $pkey - value corresponding to openssl's EVP_PKEY structure
1725 #
1726 # returns: (integer) key type
1727 Example:
1729 my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1731 my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1732 print Net::SSLeay::OBJ_nid2sn($type); #prints e.g. 'rsaEncryption'
1733 Low level API: PEM_* related functions
1735 Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1737 • PEM_read_bio_X509
1739 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1741 Loads PEM formatted X509 certificate via given BIO structure.
1743 my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1745 # $bio - value corresponding to openssl's BIO structure
1746 #
1747 # returns: value corresponding to openssl's X509 structure (0 on failure)
1748 Example:
1750 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1752 my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1753 Net::SSLeay::BIO_free($bio);
1754 • PEM_read_bio_X509_REQ
1756 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1758 Loads PEM formatted X509_REQ object via given BIO structure.
1760 my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1762 # $bio - value corresponding to openssl's BIO structure
1763 #
1764 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1765 Example:
1767 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1769 my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1770 Net::SSLeay::BIO_free($bio);
1771 • PEM_read_bio_DHparams
1773 Reads DH structure from BIO.
1775 my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1777 # $bio - value corresponding to openssl's BIO structure
1778 #
1779 # returns: value corresponding to openssl's DH structure (0 on failure)
1780 • PEM_read_bio_X509_CRL
1782 Reads X509_CRL structure from BIO.
1784 my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1786 # $bio - value corresponding to openssl's BIO structure
1787 #
1788 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1789 • PEM_read_bio_PrivateKey
1791 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1793 Loads PEM formatted private key via given BIO structure.
1795 my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1797 # $bio - value corresponding to openssl's BIO structure
1798 # $cb - reference to perl callback function
1799 # $data - data that will be passed to callback function (see examples below)
1800 #
1801 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1802 Example:
1804 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1806 my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1807 Net::SSLeay::BIO_free($bio);
1808 To use password you have the following options:
1810 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1812 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1813 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1814 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, ""); # use empty password
1815 Callback function signature:
1817 sub callback_func {
1819 my ($max_passwd_size, $rwflag, $data) = @_;
1820 # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1821 # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1822 # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1823 return "secret";
1825 }
1826 • PEM_X509_INFO_read_bio
1828 Reads a BIO containing a PEM formatted file into a
1830 STACK_OF(X509_INFO) structure.
1831 my $rv = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1833 # $bio - value corresponding to openssl's BIO structure
1834 #
1835 # returns: value corresponding to openssl's STACK_OF(X509_INFO) structure.
1836 Example:
1838 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1840 my $sk_x509_info = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1841 Net::SSLeay::BIO_free($bio);
1842 • PEM_get_string_X509
1844 NOTE: Does not exactly correspond to any low level API function
1846 Converts/exports X509 certificate to string (PEM format).
1848 Net::SSLeay::PEM_get_string_X509($x509);
1850 # $x509 - value corresponding to openssl's X509 structure
1851 #
1852 # returns: string with $x509 in PEM format
1853 • PEM_get_string_PrivateKey
1855 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1857 Converts public key $pk into PEM formatted string (optionally
1859 protected with password).
1860 my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1862 # $pk - value corresponding to openssl's EVP_PKEY structure
1863 # $passwd - [optional] (string) password to use for key encryption
1864 # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1865 #
1866 # returns: PEM formatted string
1867 Examples:
1869 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1871 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1872 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1873 • PEM_get_string_X509_CRL
1875 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1877 Converts X509_CRL object $x509_crl into PEM formatted string.
1879 Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1881 # $x509_crl - value corresponding to openssl's X509_CRL structure
1882 #
1883 # returns: no return value
1884 • PEM_get_string_X509_REQ
1886 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1888 Converts X509_REQ object $x509_crl into PEM formatted string.
1890 Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1892 # $x509_req - value corresponding to openssl's X509_REQ structure
1893 #
1894 # returns: no return value
1895 Low level API: d2i_* (DER format) related functions
1897 • d2i_X509_bio
1899 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1901 Loads DER formatted X509 certificate via given BIO structure.
1903 my $rv = Net::SSLeay::d2i_X509_bio($bp);
1905 # $bp - value corresponding to openssl's BIO structure
1906 #
1907 # returns: value corresponding to openssl's X509 structure (0 on failure)
1908 Example:
1910 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1912 my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1913 Net::SSLeay::BIO_free($bio);
1914 Check openssl doc
1916 <http://www.openssl.org/docs/crypto/d2i_X509.html>
1917 • d2i_X509_CRL_bio
1919 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1921 Loads DER formatted X509_CRL object via given BIO structure.
1923 my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1925 # $bp - value corresponding to openssl's BIO structure
1926 #
1927 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1928 Example:
1930 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1932 my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1933 Net::SSLeay::BIO_free($bio);
1934 • d2i_X509_REQ_bio
1936 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1938 Loads DER formatted X509_REQ object via given BIO structure.
1940 my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1942 # $bp - value corresponding to openssl's BIO structure
1943 #
1944 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1945 Example:
1947 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1949 my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1950 Net::SSLeay::BIO_free($bio);
1951 Low level API: PKCS12 related functions
1953 • P_PKCS12_load_file
1955 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1957 Loads X509 certificate + private key + certificates of CA chain (if
1959 present in PKCS12 file).
1960 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1962 # $filename - name of PKCS12 file
1963 # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1964 # $password - [optional] password for private key
1965 #
1966 # returns: triplet ($privkey, $cert, @cachain)
1967 # $privkey - value corresponding to openssl's EVP_PKEY structure
1968 # $cert - value corresponding to openssl's X509 structure
1969 # @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1970 IMPORTANT NOTE: after you do the job you need to call X509_free()
1972 on $privkey + all members of @cachain and EVP_PKEY_free() on
1973 $privkey.
1974 Examples:
1976 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1978 #or
1979 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1980 #or
1981 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1982 #or
1983 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1984 #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1986 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1987 NOTE With some combinations of Windows, perl, compiler and compiler
1989 options, you may see a runtime error "no OPENSSL_Applink", when
1990 calling Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more
1991 details.
1992 Low level API: SESSION_* related functions
1994 • d2i_SSL_SESSION
1996 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1998 Transforms the binary ASN1 representation string of an SSL/TLS
2000 session into an SSL_SESSION object.
2001 my $ses = Net::SSLeay::d2i_SSL_SESSION($data);
2003 # $data - the session as ASN1 representation string
2004 #
2005 # returns: $ses - the new SSL_SESSION
2006 Check openssl doc
2008 <https://www.openssl.org/docs/ssl/i2d_SSL_SESSION.html>
2009 • i2d_SSL_SESSION
2011 COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
2013 Transforms the SSL_SESSION object in into the ASN1 representation
2015 and returns it as string.
2016 my $data = Net::SSLeay::i2d_SSL_SESSION($ses);
2018 # $ses - value corresponding to openssl's SSL_SESSION structure
2019 #
2020 # returns: $data - session as string
2021 Check openssl doc
2023 <https://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
2024 • SESSION_new
2026 Creates a new SSL_SESSION structure.
2028 my $rv = Net::SSLeay::SESSION_new();
2030 #
2031 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
2032 • SESSION_free
2034 Free an allocated SSL_SESSION structure.
2036 Net::SSLeay::SESSION_free($ses);
2038 # $ses - value corresponding to openssl's SSL_SESSION structure
2039 #
2040 # returns: no return value
2041 Check openssl doc
2043 <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
2044 • SESSION_up_ref
2046 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2048 requires at least OpenSSL 1.1.0-pre4 or LibreSSL 2.7.0
2049 Increases the reference counter on a SSL_SESSION structure.
2051 Net::SSLeay::SESSION_up_ref($ses);
2053 # $ses - value corresponding to openssl's SSL_SESSION structure
2054 #
2055 # returns: 1 on success else 0
2056 Check openssl doc
2058 <https://www.openssl.org/docs/ssl/SSL_SESSION_up_ref.html>
2059 • SESSION_dup
2061 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2063 requires at least OpenSSL 1.1.1, not in LibreSSL
2064 Duplicates a SSL_SESSION structure.
2066 Net::SSLeay::SESSION_dup($ses);
2068 # $ses - value corresponding to openssl's SSL_SESSION structure
2069 #
2070 # returns: the duplicated session
2071 Check openssl doc
2073 <https://www.openssl.org/docs/ssl/SSL_SESSION_dup.html>
2074 • SESSION_is_resumable
2076 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2078 requires at least OpenSSL 1.1.1, not in LibreSSL
2079 Determine whether an SSL_SESSION object can be used for resumption.
2081 Net::SSLeay::SESSION_is_resumable($ses);
2083 # $ses - value corresponding to openssl's SSL_SESSION structure
2084 #
2085 # returns: (integer) 1 if it can or 0 if not
2086 Check openssl doc
2088 <https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html>
2089 • SESSION_cmp
2091 Compare two SSL_SESSION structures.
2093 my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
2095 # $sesa - value corresponding to openssl's SSL_SESSION structure
2096 # $sesb - value corresponding to openssl's SSL_SESSION structure
2097 #
2098 # returns: 0 if the two structures are the same
2099 NOTE: Not available in openssl 1.0 or later
2101 • SESSION_get_app_data
2103 Can be used to get application defined value/data.
2105 my $rv = Net::SSLeay::SESSION_get_app_data($ses);
2107 # $ses - value corresponding to openssl's SSL_SESSION structure
2108 #
2109 # returns: string/buffer/pointer ???
2110 • SESSION_set_app_data
2112 Can be used to set some application defined value/data.
2114 my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
2116 # $s - value corresponding to openssl's SSL_SESSION structure
2117 # $a - (string/buffer/pointer ???) data
2118 #
2119 # returns: ???
2120 • SESSION_get_ex_data
2122 Is used to retrieve the information for $idx from session $ses.
2124 my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
2126 # $ses - value corresponding to openssl's SSL_SESSION structure
2127 # $idx - (integer) index for application specific data
2128 #
2129 # returns: pointer to ???
2130 Check openssl doc
2132 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2133 • SESSION_set_ex_data
2135 Is used to store application data at arg for idx into the session
2137 object.
2138 my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
2140 # $ss - value corresponding to openssl's SSL_SESSION structure
2141 # $idx - (integer) ???
2142 # $data - (pointer) ???
2143 #
2144 # returns: 1 on success, 0 on failure
2145 Check openssl doc
2147 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2148 • SESSION_get_ex_new_index
2150 Is used to register a new index for application specific data.
2152 my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2154 # $argl - (long) ???
2155 # $argp - (pointer) ???
2156 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2157 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2158 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2159 #
2160 # returns: (integer) ???
2161 Check openssl doc
2163 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2164 • SESSION_get_master_key
2166 NOTE: Does not exactly correspond to any low level API function
2168 Returns 'master_key' value from SSL_SESSION structure $s
2170 Net::SSLeay::SESSION_get_master_key($s);
2172 # $s - value corresponding to openssl's SSL_SESSION structure
2173 #
2174 # returns: master key (binary data)
2175 • SESSION_set_master_key
2177 Sets 'master_key' value for SSL_SESSION structure $s
2179 Net::SSLeay::SESSION_set_master_key($s, $key);
2181 # $s - value corresponding to openssl's SSL_SESSION structure
2182 # $key - master key (binary data)
2183 #
2184 # returns: no return value
2185 Not available with OpenSSL 1.1 and later. Code that previously
2187 used
2188 SESSION_set_master_key must now set $secret in the
2189 session_secret
2190 callback set with SSL_set_session_secret_cb.
2191 • SESSION_get_time
2193 Returns the time at which the session s was established. The time
2195 is given in seconds since 1.1.1970.
2196 my $rv = Net::SSLeay::SESSION_get_time($s);
2198 # $s - value corresponding to openssl's SSL_SESSION structure
2199 #
2200 # returns: timestamp (seconds since 1.1.1970)
2201 Check openssl doc
2203 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2204 • get_time
2206 Technically the same functionality as "SESSION_get_time".
2208 my $rv = Net::SSLeay::get_time($s);
2210 • SESSION_get_timeout
2212 Returns the timeout value set for session $s in seconds.
2214 my $rv = Net::SSLeay::SESSION_get_timeout($s);
2216 # $s - value corresponding to openssl's SSL_SESSION structure
2217 #
2218 # returns: timeout (in seconds)
2219 Check openssl doc
2221 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2222 • get_timeout
2224 Technically the same functionality as "SESSION_get_timeout".
2226 my $rv = Net::SSLeay::get_timeout($s);
2228 • SESSION_print
2230 NOTE: Does not exactly correspond to any low level API function
2232 Prints session details (e.g. protocol version, cipher, session-id
2234 ...) to BIO.
2235 my $rv = Net::SSLeay::SESSION_print($fp, $ses);
2237 # $fp - value corresponding to openssl's BIO structure
2238 # $ses - value corresponding to openssl's SSL_SESSION structure
2239 #
2240 # returns: 1 on success, 0 on failure
2241 You have to use necessary BIO functions like this:
2243 # let us have $ssl corresponding to openssl's SSL structure
2245 my $ses = Net::SSLeay::get_session($ssl);
2246 my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
2247 Net::SSLeay::SESSION_print($bio, $ses);
2248 print Net::SSLeay::BIO_read($bio);
2249 • SESSION_print_fp
2251 Prints session details (e.g. protocol version, cipher, session-id
2253 ...) to file handle.
2254 my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
2256 # $fp - perl file handle
2257 # $ses - value corresponding to openssl's SSL_SESSION structure
2258 #
2259 # returns: 1 on success, 0 on failure
2260 Example:
2262 # let us have $ssl corresponding to openssl's SSL structure
2264 my $ses = Net::SSLeay::get_session($ssl);
2265 open my $fh, ">", "output.txt";
2266 Net::SSLeay::SESSION_print_fp($fh,$ses);
2267 • SESSION_set_time
2269 Replaces the creation time of the session s with the chosen value
2271 $t (seconds since 1.1.1970).
2272 my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
2274 # $ses - value corresponding to openssl's SSL_SESSION structure
2275 # $t - time value
2276 #
2277 # returns: 1 on success
2278 Check openssl doc
2280 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2281 • set_time
2283 Technically the same functionality as "SESSION_set_time".
2285 my $rv = Net::SSLeay::set_time($ses, $t);
2287 • SESSION_set_timeout
2289 Sets the timeout value for session s in seconds to $t.
2291 my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
2293 # $s - value corresponding to openssl's SSL_SESSION structure
2294 # $t - timeout (in seconds)
2295 #
2296 # returns: 1 on success
2297 Check openssl doc
2299 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2300 • set_timeout
2302 Technically the same functionality as "SESSION_set_timeout".
2304 my $rv = Net::SSLeay::set_timeout($ses, $t);
2306 Low level API: SSL_CTX_* related functions
2308 NOTE: Please note that the function described in this chapter have
2310 "SSL_" part stripped from their original openssl names.
2311 • CTX_add_client_CA
2313 Adds the CA name extracted from $cacert to the list of CAs sent to
2315 the client when requesting a client certificate for $ctx.
2316 my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
2318 # $ctx - value corresponding to openssl's SSL_CTX structure
2319 # $cacert - value corresponding to openssl's X509 structure
2320 #
2321 # returns: 1 on success, 0 on failure
2322 Check openssl doc
2324 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2325 • CTX_add_extra_chain_cert
2327 Adds the certificate $x509 to the certificate chain presented
2329 together with the certificate. Several certificates can be added
2330 one after the other.
2331 my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
2333 # $ctx - value corresponding to openssl's SSL_CTX structure
2334 # $x509 - value corresponding to openssl's X509 structure
2335 #
2336 # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
2337 Check openssl doc
2339 <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2340 • CTX_add_session
2342 Adds the session $ses to the context $ctx.
2344 my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
2346 # $ctx - value corresponding to openssl's SSL_CTX structure
2347 # $ses - value corresponding to openssl's SSL_SESSION structure
2348 #
2349 # returns: 1 on success, 0 on failure
2350 Check openssl doc
2352 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2353 • CTX_callback_ctrl
2355 ??? (more info needed)
2357 my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
2359 # $ctx - value corresponding to openssl's SSL_CTX structure
2360 # $cmd - (integer) command id
2361 # $fp - (function pointer) ???
2362 #
2363 # returns: ???
2364 Check openssl doc
2366 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2367 • CTX_check_private_key
2369 Checks the consistency of a private key with the corresponding
2371 certificate loaded into $ctx.
2372 my $rv = Net::SSLeay::CTX_check_private_key($ctx);
2374 # $ctx - value corresponding to openssl's SSL_CTX structure
2375 #
2376 # returns: 1 on success, otherwise check out the error stack to find out the reason
2377 Check openssl doc
2379 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2380 • CTX_ctrl
2382 Internal handling function for SSL_CTX objects.
2384 BEWARE: openssl doc says: This function should never be called
2386 directly!
2387 my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
2389 # $ctx - value corresponding to openssl's SSL_CTX structure
2390 # $cmd - (integer) command id
2391 # $larg - (integer) long ???
2392 # $parg - (string/pointer) ???
2393 #
2394 # returns: (long) result of given command ???
2395 #valid $cmd values
2397 1 - SSL_CTRL_NEED_TMP_RSA
2398 2 - SSL_CTRL_SET_TMP_RSA
2399 3 - SSL_CTRL_SET_TMP_DH
2400 4 - SSL_CTRL_SET_TMP_ECDH
2401 5 - SSL_CTRL_SET_TMP_RSA_CB
2402 6 - SSL_CTRL_SET_TMP_DH_CB
2403 7 - SSL_CTRL_SET_TMP_ECDH_CB
2404 8 - SSL_CTRL_GET_SESSION_REUSED
2405 9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
2406 10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
2407 11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
2408 12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
2409 13 - SSL_CTRL_GET_FLAGS
2410 14 - SSL_CTRL_EXTRA_CHAIN_CERT
2411 15 - SSL_CTRL_SET_MSG_CALLBACK
2412 16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
2413 17 - SSL_CTRL_SET_MTU
2414 20 - SSL_CTRL_SESS_NUMBER
2415 21 - SSL_CTRL_SESS_CONNECT
2416 22 - SSL_CTRL_SESS_CONNECT_GOOD
2417 23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
2418 24 - SSL_CTRL_SESS_ACCEPT
2419 25 - SSL_CTRL_SESS_ACCEPT_GOOD
2420 26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
2421 27 - SSL_CTRL_SESS_HIT
2422 28 - SSL_CTRL_SESS_CB_HIT
2423 29 - SSL_CTRL_SESS_MISSES
2424 30 - SSL_CTRL_SESS_TIMEOUTS
2425 31 - SSL_CTRL_SESS_CACHE_FULL
2426 32 - SSL_CTRL_OPTIONS
2427 33 - SSL_CTRL_MODE
2428 40 - SSL_CTRL_GET_READ_AHEAD
2429 41 - SSL_CTRL_SET_READ_AHEAD
2430 42 - SSL_CTRL_SET_SESS_CACHE_SIZE
2431 43 - SSL_CTRL_GET_SESS_CACHE_SIZE
2432 44 - SSL_CTRL_SET_SESS_CACHE_MODE
2433 45 - SSL_CTRL_GET_SESS_CACHE_MODE
2434 50 - SSL_CTRL_GET_MAX_CERT_LIST
2435 51 - SSL_CTRL_SET_MAX_CERT_LIST
2436 52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
2437 53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
2438 54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
2439 55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
2440 56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
2441 57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
2442 58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
2443 59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
2444 60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
2445 61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
2446 62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
2447 63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
2448 64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
2449 65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
2450 66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
2451 67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
2452 68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
2453 69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
2454 70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
2455 71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
2456 72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
2457 73 - DTLS_CTRL_GET_TIMEOUT
2458 74 - DTLS_CTRL_HANDLE_TIMEOUT
2459 75 - DTLS_CTRL_LISTEN
2460 76 - SSL_CTRL_GET_RI_SUPPORT
2461 77 - SSL_CTRL_CLEAR_OPTIONS
2462 78 - SSL_CTRL_CLEAR_MODE
2463 82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2465 83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2466 88 - SSL_CTRL_CHAIN
2468 89 - SSL_CTRL_CHAIN_CERT
2469 90 - SSL_CTRL_GET_CURVES
2471 91 - SSL_CTRL_SET_CURVES
2472 92 - SSL_CTRL_SET_CURVES_LIST
2473 93 - SSL_CTRL_GET_SHARED_CURVE
2474 94 - SSL_CTRL_SET_ECDH_AUTO
2475 97 - SSL_CTRL_SET_SIGALGS
2476 98 - SSL_CTRL_SET_SIGALGS_LIST
2477 99 - SSL_CTRL_CERT_FLAGS
2478 100 - SSL_CTRL_CLEAR_CERT_FLAGS
2479 101 - SSL_CTRL_SET_CLIENT_SIGALGS
2480 102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
2481 103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
2482 104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
2483 105 - SSL_CTRL_BUILD_CERT_CHAIN
2484 106 - SSL_CTRL_SET_VERIFY_CERT_STORE
2485 107 - SSL_CTRL_SET_CHAIN_CERT_STORE
2486 108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
2487 109 - SSL_CTRL_GET_SERVER_TMP_KEY
2488 110 - SSL_CTRL_GET_RAW_CIPHERLIST
2489 111 - SSL_CTRL_GET_EC_POINT_FORMATS
2490 112 - SSL_CTRL_GET_TLSA_RECORD
2491 113 - SSL_CTRL_SET_TLSA_RECORD
2492 114 - SSL_CTRL_PULL_TLSA_RECORD
2493 Check openssl doc
2495 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2496 • CTX_flush_sessions
2498 Causes a run through the session cache of $ctx to remove sessions
2500 expired at time $tm.
2501 Net::SSLeay::CTX_flush_sessions($ctx, $tm);
2503 # $ctx - value corresponding to openssl's SSL_CTX structure
2504 # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
2505 #
2506 # returns: no return value
2507 Check openssl doc
2509 <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2510 • CTX_free
2512 Free an allocated SSL_CTX object.
2514 Net::SSLeay::CTX_free($ctx);
2516 # $ctx - value corresponding to openssl's SSL_CTX structure
2517 #
2518 # returns: no return value
2519 Check openssl doc
2521 <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2522 • CTX_get_app_data
2524 Can be used to get application defined value/data.
2526 my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2528 # $ctx - value corresponding to openssl's SSL_CTX structure
2529 #
2530 # returns: string/buffer/pointer ???
2531 • CTX_set_app_data
2533 Can be used to set some application defined value/data.
2535 my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2537 # $ctx - value corresponding to openssl's SSL_CTX structure
2538 # $arg - (string/buffer/pointer ???) data
2539 #
2540 # returns: ???
2541 • CTX_get0_param
2543 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2545 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
2546 Returns the current verification parameters.
2548 my $vpm = Net::SSLeay::CTX_get0_param($ctx);
2550 # $ctx - value corresponding to openssl's SSL_CTX structure
2551 #
2552 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
2553 Check openssl doc
2555 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2556 • CTX_get_cert_store
2558 Returns the current certificate verification storage.
2560 my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2562 # $ctx - value corresponding to openssl's SSL_CTX structure
2563 #
2564 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2565 Check openssl doc
2567 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2568 • CTX_get_client_CA_list
2570 Returns the list of client CAs explicitly set for $ctx using
2572 "CTX_set_client_CA_list".
2573 my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2575 # $ctx - value corresponding to openssl's SSL_CTX structure
2576 #
2577 # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2578 Check openssl doc
2580 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2581 • CTX_get_ex_data
2583 Is used to retrieve the information for index $idx from $ctx.
2585 my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2587 # $ssl - value corresponding to openssl's SSL_CTX structure
2588 # $idx - (integer) index for application specific data
2589 #
2590 # returns: pointer to ???
2591 Check openssl doc
2593 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2594 • CTX_get_ex_new_index
2596 Is used to register a new index for application specific data.
2598 my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2600 # $argl - (long) ???
2601 # $argp - (pointer) ???
2602 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2603 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2604 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2605 #
2606 # returns: (integer) ???
2607 Check openssl doc
2609 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2610 • CTX_get_mode
2612 Returns the mode set for ctx.
2614 my $rv = Net::SSLeay::CTX_get_mode($ctx);
2616 # $ctx - value corresponding to openssl's SSL_CTX structure
2617 #
2618 # returns: mode (bitmask)
2619 #to decode the return value (bitmask) use:
2621 0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2622 0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2623 0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2624 0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2625 0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2626 (note: some of the bits might not be supported by older openssl versions)
2627 Check openssl doc
2629 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2630 • CTX_set_mode
2632 Adds the mode set via bitmask in $mode to $ctx. Options already set
2634 before are not cleared.
2635 my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2637 # $ctx - value corresponding to openssl's SSL_CTX structure
2638 # $mode - mode bitmask
2639 #
2640 # returns: the new mode bitmask after adding $mode
2641 For bitmask details see "CTX_get_mode" (above).
2643 Check openssl doc
2645 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2646 • CTX_get_options
2648 Returns the options (bitmask) set for $ctx.
2650 my $rv = Net::SSLeay::CTX_get_options($ctx);
2652 # $ctx - value corresponding to openssl's SSL_CTX structure
2653 #
2654 # returns: options (bitmask)
2655 BEWARE: The available constants and their values in bitmask depend
2657 on the TLS library. For example, SSL_OP_NO_TLSv1_3 became available
2658 much later than SSL_OP_NO_COMPRESS which is already deprecated by
2659 some libraries. Also, some previously used option values have been
2660 recycled and are now used for newer options. See the list of
2661 constants in this document for options Net::SSLeay currently
2662 supports.
2663 You are strongly encouraged to check your TLS library if you need
2665 to use numeric values directly. The following is a sample of
2666 historic values. It may not be correct anymore.
2667 #to decode the return value (bitmask) use:
2669 0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2670 0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2671 0x00004000 corresponds to SSL_OP_NO_TICKET
2672 0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2673 0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2674 0x04000000 corresponds to SSL_OP_NO_TLSv1
2675 Check openssl doc
2677 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_options.html>
2678 • CTX_set_options
2680 Adds the options set via bitmask in $options to ctx. Options
2682 already set before are not cleared.
2683 Net::SSLeay::CTX_set_options($ctx, $options);
2685 # $ctx - value corresponding to openssl's SSL_CTX structure
2686 # $options - options bitmask
2687 #
2688 # returns: the new options bitmask after adding $options
2689 For bitmask details see "CTX_get_options" (above).
2691 Check openssl doc
2693 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html>
2694 • CTX_get_quiet_shutdown
2696 Returns the 'quiet shutdown' setting of $ctx.
2698 my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2700 # $ctx - value corresponding to openssl's SSL_CTX structure
2701 #
2702 # returns: (integer) the current setting
2703 Check openssl doc
2705 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2706 • CTX_get_read_ahead
2708 my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2710 # $ctx - value corresponding to openssl's SSL_CTX structure
2711 #
2712 # returns: (integer) read_ahead value
2713 • CTX_get_session_cache_mode
2715 Returns the currently used cache mode (bitmask).
2717 my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2719 # $ctx - value corresponding to openssl's SSL_CTX structure
2720 #
2721 # returns: mode (bitmask)
2722 BEWARE: SESS_CACHE_OFF and other constants are not available in
2724 Net-SSLeay-1.82 and before. If the constants are not available,
2725 the following values have historically been correct. You are
2726 strongly encouraged to check your TLS library for the current
2727 values.
2728 #to decode the return value (bitmask) use:
2730 0x0000 corresponds to SSL_SESS_CACHE_OFF
2731 0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2732 0x0002 corresponds to SSL_SESS_CACHE_SERVER
2733 0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2734 0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2735 0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2736 (note: some of the bits might not be supported by older openssl versions)
2737 Check openssl doc
2739 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2740 • CTX_set_session_cache_mode
2742 Enables/disables session caching by setting the operational mode
2744 for $ctx to $mode.
2745 my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2747 # $ctx - value corresponding to openssl's SSL_CTX structure
2748 # $mode - mode (bitmask)
2749 #
2750 # returns: previously set cache mode
2751 For bitmask details see "CTX_get_session_cache_mode" (above).
2753 Check openssl doc
2755 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2756 • CTX_get_timeout
2758 Returns the currently set timeout value for $ctx.
2760 my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2762 # $ctx - value corresponding to openssl's SSL_CTX structure
2763 #
2764 # returns: timeout in seconds
2765 Check openssl doc
2767 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2768 • CTX_get_verify_depth
2770 Returns the verification depth limit currently set in $ctx. If no
2772 limit has been explicitly set, -1 is returned and the default value
2773 will be used.
2774 my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2776 # $ctx - value corresponding to openssl's SSL_CTX structure
2777 #
2778 # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2779 Check openssl doc
2781 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2782 • CTX_get_verify_mode
2784 Returns the verification mode (bitmask) currently set in $ctx.
2786 my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2788 # $ctx - value corresponding to openssl's SSL_CTX structure
2789 #
2790 # returns: mode (bitmask)
2791 For bitmask details see "CTX_set_verify".
2793 Check openssl doc
2795 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_verify_mode.html>
2796 • CTX_set_verify
2798 Sets the verification flags for $ctx to be $mode and specifies the
2800 verify_callback function to be used.
2801 Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2803 # $ctx - value corresponding to openssl's SSL_CTX structure
2804 # $mode - mode (bitmask), see OpenSSL manual
2805 # $callback - [optional] reference to perl callback function
2806 #
2807 # returns: no return value
2808 Check openssl doc
2810 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html>
2811 • CTX_set_post_handshake_auth
2813 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2815 requires at least OpenSSL 1.1.1, not in LibreSSL
2816 Enable the Post-Handshake Authentication extension to be added to
2818 the ClientHello such that post-handshake authentication can be
2819 requested by the server.
2820 Net::SSLeay::CTX_set_posthandshake_auth($ctx, $val);
2822 # $ctx - value corresponding to openssl's SSL_CTX structure
2823 # $val - 0 then the extension is not sent, otherwise it is
2824 #
2825 # returns: no return value
2826 Check openssl doc
2828 https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth
2829 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth.html>
2830 • CTX_load_verify_locations
2832 Specifies the locations for $ctx, at which CA certificates for
2834 verification purposes are located. The certificates available via
2835 $CAfile and $CApath are trusted.
2836 my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2838 # $ctx - value corresponding to openssl's SSL_CTX structure
2839 # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2840 # $CApath - (string) directory containing CA certificates in PEM format (or '')
2841 #
2842 # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2843 Check openssl doc
2845 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2846 • CTX_need_tmp_RSA
2848 Return the result of
2850 "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2851 my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2853 # $ctx - value corresponding to openssl's SSL_CTX structure
2854 #
2855 # returns: result of SSL_CTRL_NEED_TMP_RSA command
2856 Not available with OpenSSL 1.1 and later.
2858 • CTX_new
2860 The same as "CTX_v23_new"
2862 my $rv = Net::SSLeay::CTX_new();
2864 #
2865 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2866 Check openssl doc
2868 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2869 Not available with OpenSSL 1.1 and later.
2871 • CTX_v2_new
2873 Creates a new SSL_CTX object - based on SSLv2_method() - as
2875 framework to establish TLS/SSL enabled connections.
2876 my $rv = Net::SSLeay::CTX_v2_new();
2878 #
2879 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2880 • CTX_v23_new
2882 Creates a new SSL_CTX object - based on SSLv23_method() - as
2884 framework to establish TLS/SSL enabled connections.
2885 my $rv = Net::SSLeay::CTX_v23_new();
2887 #
2888 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2889 • CTX_v3_new
2891 Creates a new SSL_CTX object - based on SSLv3_method() - as
2893 framework to establish TLS/SSL enabled connections.
2894 my $rv = Net::SSLeay::CTX_v3_new();
2896 #
2897 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2898 • CTX_tlsv1_new
2900 Creates a new SSL_CTX object - based on TLSv1_method() - as
2902 framework to establish TLS/SSL enabled connections.
2903 my $rv = Net::SSLeay::CTX_tlsv1_new();
2905 #
2906 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2907 • CTX_tlsv1_1_new
2909 Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2911 framework to establish TLS/SSL enabled connections. Only available
2912 where supported by the underlying openssl.
2913 my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2915 #
2916 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2917 • CTX_tlsv1_2_new
2919 Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2921 framework to establish TLS/SSL enabled connections. Only available
2922 where supported by the underlying openssl.
2923 my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2925 #
2926 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2927 • CTX_new_with_method
2929 Creates a new SSL_CTX object based on $meth method
2931 my $rv = Net::SSLeay::CTX_new_with_method($meth);
2933 # $meth - value corresponding to openssl's SSL_METHOD structure
2934 #
2935 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2936 #example
2938 my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2939 Check openssl doc
2941 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2942 • CTX_set_min_proto_version, CTX_set_max_proto_version,
2944 set_min_proto_version and set_max_proto_version,
2945 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2947 requires at least OpenSSL 1.1.0-pre2 or LibreSSL 2.6.0
2948 Set the minimum and maximum supported protocol for $ctx or $ssl.
2950 my $rv = Net::SSLeay::CTX_set_min_proto_version($ctx, $version)
2952 # $ctx - value corresponding to openssl's SSL_CTX structure
2953 # $version - (integer) constat version value or 0 for automatic lowest or highest value
2954 #
2955 # returns: 1 on success, 0 on failure
2956 #example: allow only TLS 1.2 for a SSL_CTX
2958 my $rv_min = Net::SSLeay::CTX_set_min_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2959 my $rv_max = Net::SSLeay::CTX_set_max_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2960 #example: allow only TLS 1.1 for a SSL
2962 my $rv_min = Net::SSLeay::set_min_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2963 my $rv_max = Net::SSLeay::set_max_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2964 Check openssl doc
2966 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2967 • CTX_get_min_proto_version, CTX_get_max_proto_version,
2969 get_min_proto_version and get_max_proto_version,
2970 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2972 requires at least OpenSSL 1.1.0g
2973 Get the minimum and maximum supported protocol for $ctx or $ssl.
2975 my $version = Net::SSLeay::CTX_get_min_proto_version($ctx)
2977 # $ctx - value corresponding to openssl's SSL_CTX structure
2978 #
2979 # returns: 0 automatic lowest or highest value, configured value otherwise
2980 Check openssl doc
2982 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2983 • CTX_remove_session
2985 Removes the session $ses from the context $ctx.
2987 my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2989 # $ctx - value corresponding to openssl's SSL_CTX structure
2990 # $ses - value corresponding to openssl's SSL_SESSION structure
2991 #
2992 # returns: 1 on success, 0 on failure
2993 Check openssl doc
2995 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2996 • CTX_sess_accept
2998 my $rv = Net::SSLeay::CTX_sess_accept($ctx);
3000 # $ctx - value corresponding to openssl's SSL_CTX structure
3001 #
3002 # returns: number of started SSL/TLS handshakes in server mode
3003 Check openssl doc
3005 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3006 • CTX_sess_accept_good
3008 my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
3010 # $ctx - value corresponding to openssl's SSL_CTX structure
3011 #
3012 # returns: number of successfully established SSL/TLS sessions in server mode
3013 Check openssl doc
3015 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3016 • CTX_sess_accept_renegotiate
3018 my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
3020 # $ctx - value corresponding to openssl's SSL_CTX structure
3021 #
3022 # returns: number of start renegotiations in server mode
3023 Check openssl doc
3025 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3026 • CTX_sess_cache_full
3028 my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
3030 # $ctx - value corresponding to openssl's SSL_CTX structure
3031 #
3032 # returns: number of sessions that were removed because the maximum session cache size was exceeded
3033 Check openssl doc
3035 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3036 • CTX_sess_cb_hits
3038 my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
3040 # $ctx - value corresponding to openssl's SSL_CTX structure
3041 #
3042 # returns: number of successfully retrieved sessions from the external session cache in server mode
3043 Check openssl doc
3045 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3046 • CTX_sess_connect
3048 my $rv = Net::SSLeay::CTX_sess_connect($ctx);
3050 # $ctx - value corresponding to openssl's SSL_CTX structure
3051 #
3052 # returns: number of started SSL/TLS handshakes in client mode
3053 Check openssl doc
3055 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3056 • CTX_sess_connect_good
3058 my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
3060 # $ctx - value corresponding to openssl's SSL_CTX structure
3061 #
3062 # returns: number of successfully established SSL/TLS sessions in client mode
3063 Check openssl doc
3065 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3066 • CTX_sess_connect_renegotiate
3068 my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
3070 # $ctx - value corresponding to openssl's SSL_CTX structure
3071 #
3072 # returns: number of start renegotiations in client mode
3073 Check openssl doc
3075 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3076 • CTX_sess_get_cache_size
3078 Returns the currently valid session cache size.
3080 my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
3082 # $ctx - value corresponding to openssl's SSL_CTX structure
3083 #
3084 # returns: current size
3085 Check openssl doc
3087 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3088 • CTX_sess_hits
3090 my $rv = Net::SSLeay::CTX_sess_hits($ctx);
3092 # $ctx - value corresponding to openssl's SSL_CTX structure
3093 #
3094 # returns: number of successfully reused sessions
3095 Check openssl doc
3097 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3098 • CTX_sess_misses
3100 my $rv = Net::SSLeay::CTX_sess_misses($ctx);
3102 # $ctx - value corresponding to openssl's SSL_CTX structure
3103 #
3104 # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
3105 Check openssl doc
3107 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3108 • CTX_sess_number
3110 my $rv = Net::SSLeay::CTX_sess_number($ctx);
3112 # $ctx - value corresponding to openssl's SSL_CTX structure
3113 #
3114 # returns: current number of sessions in the internal session cache
3115 Check openssl doc
3117 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3118 • CTX_sess_set_cache_size
3120 Sets the size of the internal session cache of context $ctx to
3122 $size.
3123 Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
3125 # $ctx - value corresponding to openssl's SSL_CTX structure
3126 # $size - cache size (0 = unlimited)
3127 #
3128 # returns: previously valid size
3129 Check openssl doc
3131 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3132 • CTX_sess_timeouts
3134 Returns the number of sessions proposed by clients and either found
3136 in the internal or external session cache in server mode, but that
3137 were invalid due to timeout. These sessions are not included in the
3138 SSL_CTX_sess_hits count.
3139 my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
3141 # $ctx - value corresponding to openssl's SSL_CTX structure
3142 #
3143 # returns: number of sessions
3144 Check openssl doc
3146 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3147 • CTX_sess_set_new_cb
3149 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3151 Sets the callback function, which is automatically called whenever
3153 a new session was negotiated.
3154 Net::SSLeay::CTX_sess_set_new_cb($ctx, $func);
3156 # $ctx - value corresponding to openssl's SSL_CTX structure
3157 # $func - perl reference to callback function
3158 #
3159 # returns: no return value
3160 Check openssl doc
3162 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html>
3163 • CTX_sess_set_remove_cb
3165 COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3167 Sets the callback function, which is automatically called whenever
3169 a session is removed by the SSL engine.
3170 Net::SSLeay::CTX_sess_set_remove_cb($ctx, $func);
3172 # $ctx - value corresponding to openssl's SSL_CTX structure
3173 # $func - perl reference to callback function
3174 #
3175 # returns: no return value
3176 Check openssl doc
3178 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_remove_cb.html>
3179 • CTX_sessions
3181 Returns a pointer to the lhash databases containing the internal
3183 session cache for ctx.
3184 my $rv = Net::SSLeay::CTX_sessions($ctx);
3186 # $ctx - value corresponding to openssl's SSL_CTX structure
3187 #
3188 # returns: value corresponding to openssl's LHASH structure (0 on failure)
3189 Check openssl doc
3191 <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
3192 • CTX_set1_param
3194 COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
3196 Applies X509 verification parameters $vpm on $ctx
3198 my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
3200 # $ctx - value corresponding to openssl's SSL_CTX structure
3201 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
3202 #
3203 # returns: 1 on success, 0 on failure
3204 Check openssl doc
3206 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3207 • CTX_set_cert_store
3209 Sets/replaces the certificate verification storage of $ctx to/with
3211 $store.
3212 Net::SSLeay::CTX_set_cert_store($ctx, $store);
3214 # $ctx - value corresponding to openssl's SSL_CTX structure
3215 # $store - value corresponding to openssl's X509_STORE structure
3216 #
3217 # returns: no return value
3218 Check openssl doc
3220 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
3221 • CTX_set_cert_verify_callback
3223 Sets the verification callback function for $ctx. SSL objects that
3225 are created from $ctx inherit the setting valid at the time when
3226 "Net::SSLeay::new($ctx)" is called.
3227 Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
3229 # $ctx - value corresponding to openssl's SSL_CTX structure
3230 # $func - perl reference to callback function
3231 # $data - [optional] data that will be passed to callback function when invoked
3232 #
3233 # returns: no return value
3234 Check openssl doc
3236 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
3237 • CTX_set_cipher_list
3239 Sets the list of available ciphers for $ctx using the control
3241 string $str. The list of ciphers is inherited by all ssl objects
3242 created from $ctx.
3243 my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
3245 # $s - value corresponding to openssl's SSL_CTX structure
3246 # $str - (string) cipher list e.g. '3DES:+RSA'
3247 #
3248 # returns: 1 if any cipher could be selected and 0 on complete failure
3249 The format of $str is described in
3251 <https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html>
3252 Check openssl doc
3254 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html>
3255 • CTX_set_ciphersuites
3257 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3259 requires at least OpenSSL 1.1.1, not in LibreSSL
3260 Configure the available TLSv1.3 ciphersuites.
3262 my $rv = Net::SSLeay::CTX_set_ciphersuites($ctx, $str);
3264 # $ctx - value corresponding to openssl's SSL_CTX structure
3265 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
3266 #
3267 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
3268 Check openssl doc
3270 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html>
3271 • CTX_set_client_CA_list
3273 Sets the list of CAs sent to the client when requesting a client
3275 certificate for $ctx.
3276 Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
3278 # $ctx - value corresponding to openssl's SSL_CTX structure
3279 # $list - value corresponding to openssl's X509_NAME_STACK structure
3280 #
3281 # returns: no return value
3282 Check openssl doc
3284 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3285 • CTX_set_default_passwd_cb
3287 Sets the default password callback called when loading/storing a
3289 PEM certificate with encryption.
3290 Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
3292 # $ctx - value corresponding to openssl's SSL_CTX structure
3293 # $func - perl reference to callback function
3294 #
3295 # returns: no return value
3296 Check openssl doc
3298 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3299 • CTX_set_default_passwd_cb_userdata
3301 Sets a pointer to userdata which will be provided to the password
3303 callback on invocation.
3304 Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
3306 # $ctx - value corresponding to openssl's SSL_CTX structure
3307 # $userdata - data that will be passed to callback function when invoked
3308 #
3309 # returns: no return value
3310 Check openssl doc
3312 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3313 • CTX_set_default_verify_paths
3315 ??? (more info needed)
3317 my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
3319 # $ctx - value corresponding to openssl's SSL_CTX structure
3320 #
3321 # returns: 1 on success, 0 on failure
3322 • CTX_set_ex_data
3324 Is used to store application data at $data for $idx into the $ctx
3326 object.
3327 my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
3329 # $ssl - value corresponding to openssl's SSL_CTX structure
3330 # $idx - (integer) ???
3331 # $data - (pointer) ???
3332 #
3333 # returns: 1 on success, 0 on failure
3334 Check openssl doc
3336 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3337 • CTX_set_purpose
3339 my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
3341 # $s - value corresponding to openssl's SSL_CTX structure
3342 # $purpose - (integer) purpose identifier
3343 #
3344 # returns: 1 on success, 0 on failure
3345 #avainable purpose identifier
3347 1 - X509_PURPOSE_SSL_CLIENT
3348 2 - X509_PURPOSE_SSL_SERVER
3349 3 - X509_PURPOSE_NS_SSL_SERVER
3350 4 - X509_PURPOSE_SMIME_SIGN
3351 5 - X509_PURPOSE_SMIME_ENCRYPT
3352 6 - X509_PURPOSE_CRL_SIGN
3353 7 - X509_PURPOSE_ANY
3354 8 - X509_PURPOSE_OCSP_HELPER
3355 9 - X509_PURPOSE_TIMESTAMP_SIGN
3356 #or use corresponding constants
3358 $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3359 ...
3360 $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3361 • CTX_set_quiet_shutdown
3363 Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
3365 created from $ctx inherit the mode valid at the time
3366 "Net::SSLeay::new($ctx)" is called.
3367 Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
3369 # $ctx - value corresponding to openssl's SSL_CTX structure
3370 # $mode - 0 or 1
3371 #
3372 # returns: no return value
3373 Check openssl doc
3375 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3376 • CTX_set_read_ahead
3378 my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
3380 # $ctx - value corresponding to openssl's SSL_CTX structure
3381 # $val - read_ahead value to be set
3382 #
3383 # returns: the original read_ahead value
3384 • CTX_set_session_id_context
3386 Sets the context $sid_ctx of length $sid_ctx_len within which a
3388 session can be reused for the $ctx object.
3389 my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
3391 # $ctx - value corresponding to openssl's SSL_CTX structure
3392 # $sid_ctx - data buffer
3393 # $sid_ctx_len - length of data in $sid_ctx
3394 #
3395 # returns: 1 on success, 0 on failure (the error is logged to the error stack)
3396 Check openssl doc
3398 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3399 • CTX_set_ssl_version
3401 Sets a new default TLS/SSL method for SSL objects newly created
3403 from this $ctx. SSL objects already created with
3404 "Net::SSLeay::new($ctx)" are not affected, except when
3405 "Net::SSLeay:clear($ssl)" is being called.
3406 my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
3408 # $ctx - value corresponding to openssl's SSL_CTX structure
3409 # $meth - value corresponding to openssl's SSL_METHOD structure
3410 #
3411 # returns: 1 on success, 0 on failure
3412 Check openssl doc
3414 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3415 • CTX_set_timeout
3417 Sets the timeout for newly created sessions for $ctx to $t. The
3419 timeout value $t must be given in seconds.
3420 my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
3422 # $ctx - value corresponding to openssl's SSL_CTX structure
3423 # $t - timeout in seconds
3424 #
3425 # returns: previously set timeout value
3426 Check openssl doc
3428 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3429 • CTX_set_tmp_dh
3431 Sets DH parameters to be used to be $dh. The key is inherited by
3433 all ssl objects created from $ctx.
3434 my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
3436 # $ctx - value corresponding to openssl's SSL_CTX structure
3437 # $dh - value corresponding to openssl's DH structure
3438 #
3439 # returns: 1 on success, 0 on failure
3440 Check openssl doc
3442 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3443 • CTX_set_tmp_dh_callback
3445 Sets the callback function for $ctx to be used when a DH parameters
3447 are required to $tmp_dh_callback.
3448 Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
3450 # $ctx - value corresponding to openssl's SSL_CTX structure
3451 # tmp_dh_callback - (function pointer) ???
3452 #
3453 # returns: no return value
3454 Check openssl doc
3456 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3457 • CTX_set_tmp_rsa
3459 Sets the temporary/ephemeral RSA key to be used to be $rsa.
3461 my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
3463 # $ctx - value corresponding to openssl's SSL_CTX structure
3464 # $rsa - value corresponding to openssl's RSA structure
3465 #
3466 # returns: 1 on success, 0 on failure
3467 Check openssl doc
3469 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3470 Not available with OpenSSL 1.1 and later.
3472 • CTX_set_tmp_rsa_callback
3474 Sets the callback function for ctx to be used when a
3476 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3477 ??? (does this function really work?)
3479 Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
3481 # $ctx - value corresponding to openssl's SSL_CTX structure
3482 # $tmp_rsa_callback - (function pointer) ???
3483 #
3484 # returns: no return value
3485 Check openssl doc
3487 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3488 Not available with OpenSSL 1.1 and later.
3490 • CTX_set_trust
3492 my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
3494 # $s - value corresponding to openssl's SSL_CTX structure
3495 # $trust - (integer) trust identifier
3496 #
3497 # returns: the original value
3498 #available trust identifiers
3500 1 - X509_TRUST_COMPAT
3501 2 - X509_TRUST_SSL_CLIENT
3502 3 - X509_TRUST_SSL_SERVER
3503 4 - X509_TRUST_EMAIL
3504 5 - X509_TRUST_OBJECT_SIGN
3505 6 - X509_TRUST_OCSP_SIGN
3506 7 - X509_TRUST_OCSP_REQUEST
3507 8 - X509_TRUST_TSA
3508 #or use corresponding constants
3510 $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3511 ...
3512 $trust = &Net::SSLeay::X509_TRUST_TSA;
3513 • CTX_set_verify_depth
3515 Sets the maximum depth for the certificate chain verification that
3517 shall be allowed for ctx.
3518 Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
3520 # $ctx - value corresponding to openssl's SSL_CTX structure
3521 # $depth - max. depth
3522 #
3523 # returns: no return value
3524 Check openssl doc
3526 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3527 • CTX_use_PKCS12_file
3529 Adds the certificate and private key from PKCS12 file $p12filename
3531 to $ctx.
3532 my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
3534 # $ctx - value corresponding to openssl's SSL_CTX structure
3535 # $p12filename - (string) filename
3536 # $password - (string) password to decrypt private key
3537 #
3538 # returns: 1 on success, 0 on failure
3539 • CTX_use_PrivateKey
3541 Adds the private key $pkey to $ctx.
3543 my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
3545 # $ctx - value corresponding to openssl's SSL_CTX structure
3546 # $pkey - value corresponding to openssl's EVP_PKEY structure
3547 #
3548 # returns: 1 on success, otherwise check out the error stack to find out the reason
3549 Check openssl doc
3551 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3552 • CTX_use_PrivateKey_file
3554 Adds the first private key found in $file to $ctx.
3556 my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
3558 # $ctx - value corresponding to openssl's SSL_CTX structure
3559 # $file - (string) file name
3560 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3561 #
3562 # returns: 1 on success, otherwise check out the error stack to find out the reason
3563 Check openssl doc
3565 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3566 • CTX_use_RSAPrivateKey
3568 Adds the RSA private key $rsa to $ctx.
3570 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
3572 # $ctx - value corresponding to openssl's SSL_CTX structure
3573 # $rsa - value corresponding to openssl's RSA structure
3574 #
3575 # returns: 1 on success, otherwise check out the error stack to find out the reason
3576 Check openssl doc
3578 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3579 • CTX_use_RSAPrivateKey_file
3581 Adds the first RSA private key found in $file to $ctx.
3583 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
3585 # $ctx - value corresponding to openssl's SSL_CTX structure
3586 # $file - (string) file name
3587 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3588 #
3589 # returns: 1 on success, otherwise check out the error stack to find out the reason
3590 • CTX_use_certificate
3592 Loads the certificate $x into $ctx
3594 my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
3596 # $ctx - value corresponding to openssl's SSL_CTX structure
3597 # $x - value corresponding to openssl's X509 structure
3598 #
3599 # returns: 1 on success, otherwise check out the error stack to find out the reason
3600 Check openssl doc
3602 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3603 • CTX_use_certificate_chain_file
3605 Loads a certificate chain from $file into $ctx. The certificates
3607 must be in PEM format and must be sorted starting with the
3608 subject's certificate (actual client or server certificate),
3609 followed by intermediate CA certificates if applicable, and ending
3610 at the highest level (root) CA.
3611 my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
3613 # $ctx - value corresponding to openssl's SSL_CTX structure
3614 # $file - (string) file name
3615 #
3616 # returns: 1 on success, otherwise check out the error stack to find out the reason
3617 Check openssl doc
3619 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3620 • CTX_use_certificate_file
3622 Loads the first certificate stored in $file into $ctx.
3624 my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
3626 # $ctx - value corresponding to openssl's SSL_CTX structure
3627 # $file - (string) file name
3628 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3629 #
3630 # returns: 1 on success, otherwise check out the error stack to find out the reason
3631 Check openssl doc
3633 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3634 • CTX_get_security_level
3636 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3638 requires at least OpenSSL 1.1.0, not in LibreSSL
3639 Returns the security level associated with $ctx.
3641 my $level = Net::SSLeay::CTX_get_security_level($ctx);
3643 # $ctx - value corresponding to openssl's SSL_CTX structure
3644 #
3645 # returns: (integer) current security level
3646 Check openssl doc
3648 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html>
3649 • CTX_set_security_level
3651 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3653 requires at least OpenSSL 1.1.0, not in LibreSSL
3654 Sets the security level associated with $ctx to $level.
3656 Net::SSLeay::CTX_set_security_level($ctx, $level);
3658 # $ssl - value corresponding to openssl's SSL_CTX structure
3659 # $level - new security level
3660 #
3661 # returns: no return value
3662 Check openssl doc
3664 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html>
3665 • CTX_set_num_tickets
3667 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3669 requires at least OpenSSL 1.1.1, not in LibreSSL
3670 Set number of TLSv1.3 session tickets that will be sent to a
3672 client.
3673 my $rv = Net::SSLeay::CTX_set_num_tickets($ctx, $number_of_tickets);
3675 # $ctx - value corresponding to openssl's SSL_CTX structure
3676 # $number_of_tickets - number of tickets to send
3677 #
3678 # returns: 1 on success, 0 on failure
3679 Set to zero if you do not no want to support a session resumption.
3681 Check openssl doc
3683 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html>
3684 • CTX_get_num_tickets
3686 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3688 requires at least OpenSSL 1.1.1, not in LibreSSL
3689 Get number of TLSv1.3 session tickets that will be sent to a
3691 client.
3692 my $number_of_tickets = Net::SSLeay::CTX_get_num_tickets($ctx);
3694 # $ctx - value corresponding to openssl's SSL_CTX structure
3695 #
3696 # returns: (integer) number of tickets to send
3697 Check openssl doc
3699 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_num_tickets.html>
3700 • CTX_set_keylog_callback
3702 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3704 requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3705 Set the TLS key logging callback.
3707 Net::SSLeay::CTX_set_keylog_callback($ctx, $cb);
3709 # $ctx - value corresponding to openssl's SSL_CTX structure
3710 # $cb - reference to a perl callback function
3711 #
3712 # returns: no return value
3713 The callback function will be called like this:
3715 keylog_cb_func($ssl, $line);
3717 # $ssl - value corresponding to OpenSSL's SSL object associated with the connection
3718 # $line - a string containing the key material in the format used by NSS for its SSLKEYLOGFILE debugging output
3719 Check openssl doc
3721 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_keylog_callback.html>
3722 • CTX_get_keylog_callback
3724 COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3726 requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3727 Retrieve the previously set TLS key logging callback.
3729 my $cb = Net::SSLeay::CTX_get_keylog_callback($ctx);
3731 # $ctx - value corresponding to openssl's SSL_CTX structure
3732 #
3733 # returns: a reference to a perl callback function or undef if no callback is set
3734 Check openssl doc
3736 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_keylog_callback.html>
3737 Low level API: SSL_* related functions
3739 NOTE: Please note that the function described in this chapter have
3741 "SSL_" part stripped from their original openssl names.
3742 • new
3744 Creates a new SSL structure which is needed to hold the data for a
3746 TLS/SSL connection. The new structure inherits the settings of the
3747 underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3748 options, verification settings, timeout settings.
3749 my $rv = Net::SSLeay::new($ctx);
3751 # $ctx - value corresponding to openssl's SSL_CTX structure
3752 #
3753 # returns: value corresponding to openssl's SSL structure (0 on failure)
3754 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3756 • accept
3758 Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3760 communication channel must already have been set and assigned to
3761 the ssl by setting an underlying BIO.
3762 my $rv = Net::SSLeay::accept($ssl);
3764 # $ssl - value corresponding to openssl's SSL structure
3765 #
3766 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3767 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3769 • add_client_CA
3771 Adds the CA name extracted from cacert to the list of CAs sent to
3773 the client when requesting a client certificate for the chosen ssl,
3774 overriding the setting valid for ssl's SSL_CTX object.
3775 my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3777 # $ssl - value corresponding to openssl's SSL structure
3778 # $x - value corresponding to openssl's X509 structure
3779 #
3780 # returns: 1 on success, 0 on failure
3781 Check openssl doc
3783 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3784 • callback_ctrl
3786 ??? (more info needed)
3788 my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3790 # $ssl - value corresponding to openssl's SSL structure
3791 # $cmd - (integer) command id
3792 # $fp - (function pointer) ???
3793 #
3794 # returns: ???
3795 Check openssl doc
3797 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3798 • check_private_key
3800 Checks the consistency of a private key with the corresponding
3802 certificate loaded into $ssl
3803 my $rv = Net::SSLeay::check_private_key($ssl);
3805 # $ssl - value corresponding to openssl's SSL structure
3806 #
3807 # returns: 1 on success, otherwise check out the error stack to find out the reason
3808 Check openssl doc
3810 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3811 • clear
3813 Reset SSL object to allow another connection.
3815 Net::SSLeay::clear($ssl);
3817 # $ssl - value corresponding to openssl's SSL structure
3818 #
3819 # returns: no return value
3820 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3822 • connect
3824 Initiate the TLS/SSL handshake with an TLS/SSL server.
3826 my $rv = Net::SSLeay::connect($ssl);
3828 # $ssl - value corresponding to openssl's SSL structure
3829 #
3830 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3831 Check openssl doc
3833 <http://www.openssl.org/docs/ssl/SSL_connect.html>
3834 • copy_session_id
3836 Copies the session structure fro $from to $to (+ also the private
3838 key and certificate associated with $from).
3839 Net::SSLeay::copy_session_id($to, $from);
3841 # $to - value corresponding to openssl's SSL structure
3842 # $from - value corresponding to openssl's SSL structure
3843 #
3844 # returns: no return value
3845 • ctrl
3847 Internal handling function for SSL objects.
3849 BEWARE: openssl doc says: This function should never be called
3851 directly!
3852 my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3854 # $ssl - value corresponding to openssl's SSL structure
3855 # $cmd - (integer) command id
3856 # $larg - (integer) long ???
3857 # $parg - (string/pointer) ???
3858 #
3859 # returns: (long) result of given command ???
3860 For more details about valid $cmd values check "CTX_ctrl".
3862 Check openssl doc
3864 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3865 • do_handshake
3867 Will wait for a SSL/TLS handshake to take place. If the connection
3869 is in client mode, the handshake will be started. The handshake
3870 routines may have to be explicitly set in advance using either
3871 SSL_set_connect_state or SSL_set_accept_state(3).
3872 my $rv = Net::SSLeay::do_handshake($ssl);
3874 # $ssl - value corresponding to openssl's SSL structure
3875 #
3876 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3877 Check openssl doc
3879 <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3880 • dup
3882 Returns a duplicate of $ssl.
3884 my $rv = Net::SSLeay::dup($ssl);
3886 # $ssl - value corresponding to openssl's SSL structure
3887 #
3888 # returns: value corresponding to openssl's SSL structure (0 on failure)
3889 • free
3891 Free an allocated SSL structure.
3893 Net::SSLeay::free($ssl);
3895 # $ssl - value corresponding to openssl's SSL structure
3896 #
3897 # returns: no return value
3898 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3900 • get0_param
3902 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
3904 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
3905 Returns the current verification parameters.
3907 my $vpm = Net::SSLeay::get0_param($ssl);
3909 # $ssl - value corresponding to openssl's SSL structure
3910 #
3911 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
3912 Check openssl doc
3914 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3915 • get_SSL_CTX
3917 Returns a pointer to the SSL_CTX object, from which $ssl was
3919 created with Net::SSLeay::new.
3920 my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3922 # $ssl - value corresponding to openssl's SSL structure
3923 #
3924 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3925 Check openssl doc
3927 <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3928 • set_SSL_CTX
3930 COMPATIBILITY: requires at least OpenSSL 0.9.8f
3932 Sets the SSL_CTX the corresponds to an SSL session.
3934 my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3936 # $ssl - value corresponding to openssl's SSL structure
3937 # $ssl_ctx - Change the ssl object to the given ssl_ctx
3938 #
3939 # returns - the ssl_ctx
3940 • get_app_data
3942 Can be used to get application defined value/data.
3944 my $rv = Net::SSLeay::get_app_data($ssl);
3946 # $ssl - value corresponding to openssl's SSL structure
3947 #
3948 # returns: string/buffer/pointer ???
3949 • set_app_data
3951 Can be used to set some application defined value/data.
3953 my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3955 # $ssl - value corresponding to openssl's SSL structure
3956 # $arg - (string/buffer/pointer ???) data
3957 #
3958 # returns: ???
3959 • get_certificate
3961 Gets X509 certificate from an established SSL connection.
3963 my $rv = Net::SSLeay::get_certificate($ssl);
3965 # $ssl - value corresponding to openssl's SSL structure
3966 #
3967 # returns: value corresponding to openssl's X509 structure (0 on failure)
3968 • get_cipher
3970 Obtains the name of the currently used cipher.
3972 my $rv = Net::SSLeay::get_cipher($ssl);
3974 # $ssl - value corresponding to openssl's SSL structure
3975 #
3976 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3977 Check openssl doc
3979 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3980 • get_cipher_bits
3982 Obtain the number of secret/algorithm bits used.
3984 my $rv = Net::SSLeay::get_cipher_bits($ssl);
3986 # $ssl - value corresponding to openssl's SSL structure
3987 #
3988 # returns: number of secret bits used by current cipher
3989 Check openssl doc
3991 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3992 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3993 • get_ciphers
3995 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
3997 Returns a list of SSL_CIPHER structures available for $ssl sorted
3999 by preference
4000 my @ciphers = Net::SSLeay::get_ciphers($ssl);
4002 # $ssl - value corresponding to openssl's SSL structure
4003 #
4004 # returns: (list) SSL_CIPHER structures or nothing when $ssl is undefined or no ciphers are available
4005 Example:
4007 my @ciphers = Net::SSLeay::get_ciphers($ssl);
4009 foreach my $c (@ciphers) {
4010 print Net::SSLeay::CIPHER_get_name($c) . "\n";
4011 }
4012 Check openssl doc
4014 <https://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
4015 • get_cipher_list
4017 Returns the name (string) of the SSL_CIPHER listed for $ssl with
4019 priority $n.
4020 my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
4022 # $ssl - value corresponding to openssl's SSL structure
4023 # $n - (integer) priority
4024 #
4025 # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or undef in case of error
4026 Call Net::SSLeay::get_cipher_list with priority starting from 0 to
4028 obtain the sorted list of available ciphers, until undef is
4029 returned:
4030 my $priority = 0;
4032 while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
4033 print "cipher[$priority] = $c\n";
4034 $priority++;
4035 }
4036 Check openssl doc
4038 <https://www.openssl.org/docs/ssl/SSL_get_cipher_list.html>
4039 • get_client_CA_list
4041 Returns the list of client CAs explicitly set for $ssl using
4043 "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
4044 "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
4045 In client mode, returns the list of client CAs sent from the
4047 server, if any.
4048 my $rv = Net::SSLeay::get_client_CA_list($ssl);
4050 # $ssl - value corresponding to openssl's SSL structure
4051 #
4052 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4053 Check openssl doc
4055 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
4056 • get_current_cipher
4058 Returns the cipher actually used.
4060 my $rv = Net::SSLeay::get_current_cipher($ssl);
4062 # $ssl - value corresponding to openssl's SSL structure
4063 #
4064 # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
4065 Check openssl doc
4067 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
4068 • get_default_timeout
4070 Returns the default timeout value assigned to SSL_SESSION objects
4072 negotiated for the protocol valid for $ssl.
4073 my $rv = Net::SSLeay::get_default_timeout($ssl);
4075 # $ssl - value corresponding to openssl's SSL structure
4076 #
4077 # returns: (long) timeout in seconds
4078 Check openssl doc
4080 <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
4081 • get_error
4083 Returns a result code for a preceding call to "connect", "accept",
4085 "do_handshake", "read", "peek" or "write" on $ssl.
4086 my $rv = Net::SSLeay::get_error($ssl, $ret);
4088 # $ssl - value corresponding to openssl's SSL structure
4089 # $ret - return value of preceding TLS/SSL I/O operation
4090 #
4091 # returns: result code, which is one of the following values:
4092 # 0 - SSL_ERROR_NONE
4093 # 1 - SSL_ERROR_SSL
4094 # 2 - SSL_ERROR_WANT_READ
4095 # 3 - SSL_ERROR_WANT_WRITE
4096 # 4 - SSL_ERROR_WANT_X509_LOOKUP
4097 # 5 - SSL_ERROR_SYSCALL
4098 # 6 - SSL_ERROR_ZERO_RETURN
4099 # 7 - SSL_ERROR_WANT_CONNECT
4100 # 8 - SSL_ERROR_WANT_ACCEPT
4101 Check openssl doc
4103 <http://www.openssl.org/docs/ssl/SSL_get_error.html>
4104 • get_ex_data
4106 Is used to retrieve the information for $idx from $ssl.
4108 my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
4110 # $ssl - value corresponding to openssl's SSL structure
4111 # $idx - (integer) index for application specific data
4112 #
4113 # returns: pointer to ???
4114 Check openssl doc
4116 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4117 • set_ex_data
4119 Is used to store application data at $data for $idx into the $ssl
4121 object.
4122 my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
4124 # $ssl - value corresponding to openssl's SSL structure
4125 # $idx - (integer) ???
4126 # $data - (pointer) ???
4127 #
4128 # returns: 1 on success, 0 on failure
4129 Check openssl doc
4131 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4132 • get_ex_new_index
4134 Is used to register a new index for application specific data.
4136 my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
4138 # $argl - (long) ???
4139 # $argp - (pointer) ???
4140 # $new_func - function pointer ??? (CRYPTO_EX_new *)
4141 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
4142 # $free_func - function pointer ??? (CRYPTO_EX_free *)
4143 #
4144 # returns: (integer) ???
4145 Check openssl doc
4147 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4148 • get_fd
4150 Returns the file descriptor which is linked to $ssl.
4152 my $rv = Net::SSLeay::get_fd($ssl);
4154 # $ssl - value corresponding to openssl's SSL structure
4155 #
4156 # returns: file descriptor (>=0) or -1 on failure
4157 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
4159 • get_finished
4161 Obtains the latest 'Finished' message sent to the peer. Return
4163 value is zero if there's been no Finished message yet. Default
4164 count is 2*EVP_MAX_MD_SIZE that is long enough for all possible
4165 Finish messages. If you supply a non-default count, the resulting
4166 return value may be longer than returned buf's length.
4167 my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
4169 # $ssl - value corresponding to openssl's SSL structure
4170 # $buf - buffer where the returned data will be stored
4171 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
4172 #
4173 # returns: length of latest Finished message
4174 • get_peer_finished
4176 Obtains the latest 'Finished' message expected from the peer.
4178 Parameters and return value are similar to get_finished().
4179 my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
4181 # $ssl - value corresponding to openssl's SSL structure
4182 # $buf - buffer where the returned data will be stored
4183 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
4184 #
4185 # returns: length of latest Finished message
4186 • get_keyblock_size
4188 Gets the length of the TLS keyblock.
4190 NOTE: Does not exactly correspond to any low level API function.
4192 my $rv = Net::SSLeay::get_keyblock_size($ssl);
4194 # $ssl - value corresponding to openssl's SSL structure
4195 #
4196 # returns: keyblock size, -1 on error
4197 • get_mode
4199 Returns the mode (bitmask) set for $ssl.
4201 my $rv = Net::SSLeay::get_mode($ssl);
4203 # $ssl - value corresponding to openssl's SSL structure
4204 #
4205 # returns: mode (bitmask)
4206 To decode the return value (bitmask) see documentation for
4208 "CTX_get_mode".
4209 Check openssl doc
4211 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4212 • set_mode
4214 Adds the mode set via bitmask in $mode to $ssl. Options already set
4216 before are not cleared.
4217 my $rv = Net::SSLeay::set_mode($ssl, $mode);
4219 # $ssl - value corresponding to openssl's SSL structure
4220 # $mode - mode (bitmask)
4221 #
4222 # returns: the new mode bitmask after adding $mode
4223 For $mode bitmask details see "CTX_get_mode".
4225 Check openssl doc
4227 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4228 • get_options
4230 Returns the options (bitmask) set for $ssl.
4232 my $rv = Net::SSLeay::get_options($ssl);
4234 # $ssl - value corresponding to openssl's SSL structure
4235 #
4236 # returns: options (bitmask)
4237 To decode the return value (bitmask) see documentation for
4239 "CTX_get_options".
4240 Check openssl doc
4242 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4243 • set_options
4245 Adds the options set via bitmask in $options to $ssl. Options
4247 already set before are not cleared!
4248 Net::SSLeay::set_options($ssl, $options);
4250 # $ssl - value corresponding to openssl's SSL structure
4251 # $options - options (bitmask)
4252 #
4253 # returns: the new options bitmask after adding $options
4254 For $options bitmask details see "CTX_get_options".
4256 Check openssl doc
4258 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4259 • get_peer_certificate
4261 Get the X509 certificate of the peer.
4263 my $rv = Net::SSLeay::get_peer_certificate($ssl);
4265 # $ssl - value corresponding to openssl's SSL structure
4266 #
4267 # returns: value corresponding to openssl's X509 structure (0 on failure)
4268 Check openssl doc
4270 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4271 • get_peer_cert_chain
4273 Get the certificate chain of the peer as an array of X509
4275 structures.
4276 my @rv = Net::SSLeay::get_peer_cert_chain($ssl);
4278 # $ssl - value corresponding to openssl's SSL structure
4279 #
4280 # returns: list of X509 structures
4281 Check openssl doc
4283 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4284 • get_quiet_shutdown
4286 Returns the 'quiet shutdown' setting of ssl.
4288 my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
4290 # $ssl - value corresponding to openssl's SSL structure
4291 #
4292 # returns: (integer) current 'quiet shutdown' value
4293 Check openssl doc
4295 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4296 • get_rbio
4298 Get 'read' BIO linked to an SSL object $ssl.
4300 my $rv = Net::SSLeay::get_rbio($ssl);
4302 # $ssl - value corresponding to openssl's SSL structure
4303 #
4304 # returns: value corresponding to openssl's BIO structure (0 on failure)
4305 Check openssl doc
4307 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4308 • get_read_ahead
4310 my $rv = Net::SSLeay::get_read_ahead($ssl);
4312 # $ssl - value corresponding to openssl's SSL structure
4313 #
4314 # returns: (integer) read_ahead value
4315 • set_read_ahead
4317 Net::SSLeay::set_read_ahead($ssl, $val);
4319 # $ssl - value corresponding to openssl's SSL structure
4320 # $val - read_ahead value to be set
4321 #
4322 # returns: the original read_ahead value
4323 • get_security_level
4325 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4327 requires at least OpenSSL 1.1.0, not in LibreSSL
4328 Returns the security level associated with $ssl.
4330 my $level = Net::SSLeay::get_security_level($ssl);
4332 # $ssl - value corresponding to openssl's SSL structure
4333 #
4334 # returns: (integer) current security level
4335 Check openssl doc
4337 <https://www.openssl.org/docs/manmaster/man3/SSL_get_security_level.html>
4338 • set_security_level
4340 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4342 requires at least OpenSSL 1.1.0, not in LibreSSL
4343 Sets the security level associated with $ssl to $level.
4345 Net::SSLeay::set_security_level($ssl, $level);
4347 # $ssl - value corresponding to openssl's SSL structure
4348 # $level - new security level
4349 #
4350 # returns: no return value
4351 Check openssl doc
4353 <https://www.openssl.org/docs/manmaster/man3/SSL_set_security_level.html>
4354 • set_num_tickets
4356 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4358 requires at least OpenSSL 1.1.1, not in LibreSSL
4359 Set number of TLSv1.3 session tickets that will be sent to a
4361 client.
4362 my $rv = Net::SSLeay::set_num_tickets($ssl, $number_of_tickets);
4364 # $ssl - value corresponding to openssl's SSL structure
4365 # $number_of_tickets - number of tickets to send
4366 #
4367 # returns: 1 on success, 0 on failure
4368 Set to zero if you do not no want to support a session resumption.
4370 Check openssl doc
4372 <https://www.openssl.org/docs/manmaster/man3/SSL_set_num_tickets.html>
4373 • get_num_tickets
4375 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4377 requires at least OpenSSL 1.1.1, not in LibreSSL
4378 Get number of TLSv1.3 session tickets that will be sent to a
4380 client.
4381 my $number_of_tickets = Net::SSLeay::get_num_tickets($ctx);
4383 # $ctx - value corresponding to openssl's SSL structure
4384 #
4385 # returns: number of tickets to send
4386 Check openssl doc
4388 <https://www.openssl.org/docs/manmaster/man3/SSL_get_num_tickets.html>
4389 • get_server_random
4391 Returns internal SSLv3 server_random value.
4393 Net::SSLeay::get_server_random($ssl);
4395 # $ssl - value corresponding to openssl's SSL structure
4396 #
4397 # returns: server_random value (binary data)
4398 • get_client_random
4400 NOTE: Does not exactly correspond to any low level API function
4402 Returns internal SSLv3 client_random value.
4404 Net::SSLeay::get_client_random($ssl);
4406 # $ssl - value corresponding to openssl's SSL structure
4407 #
4408 # returns: client_random value (binary data)
4409 • export_keying_material
4411 Returns keying material based on the string $label and optional
4413 $context. Note that with TLSv1.2 and lower, empty context (empty
4414 string) and undefined context (no value or 'undef') will return
4415 different values.
4416 my $out = Net::SSLeay::export_keying_material($ssl, $olen, $label, $context);
4418 # $ssl - value corresponding to openssl's SSL structure
4419 # $olen - number of bytes to return
4420 # $label - application specific label
4421 # $context - [optional] context - default is undef for no context
4422 #
4423 # returns: keying material (binary data) or undef on error
4424 Check openssl doc
4426 <https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html>
4427 • get_session
4429 Retrieve TLS/SSL session data used in $ssl. The reference count of
4431 the SSL_SESSION is NOT incremented.
4432 my $rv = Net::SSLeay::get_session($ssl);
4434 # $ssl - value corresponding to openssl's SSL structure
4435 #
4436 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4437 Check openssl doc
4439 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4440 • SSL_get0_session
4442 The alias for "get_session" (note that the name is
4444 "SSL_get0_session" NOT "get0_session").
4445 my $rv = Net::SSLeay::SSL_get0_session();
4447 • get1_session
4449 Returns a pointer to the SSL_SESSION actually used in $ssl. The
4451 reference count of the SSL_SESSION is incremented by 1.
4452 my $rv = Net::SSLeay::get1_session($ssl);
4454 # $ssl - value corresponding to openssl's SSL structure
4455 #
4456 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4457 Check openssl doc
4459 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4460 • get_shared_ciphers
4462 Returns string with a list (colon ':' separated) of ciphers shared
4464 between client and server within SSL session $ssl.
4465 my $rv = Net::SSLeay::get_shared_ciphers()
4467 #
4468 # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
4469 • get_shutdown
4471 Returns the shutdown mode of $ssl.
4473 my $rv = Net::SSLeay::get_shutdown($ssl);
4475 # $ssl - value corresponding to openssl's SSL structure
4476 #
4477 # returns: shutdown mode (bitmask) of ssl
4478 #to decode the return value (bitmask) use:
4480 0 - No shutdown setting, yet
4481 1 - SSL_SENT_SHUTDOWN
4482 2 - SSL_RECEIVED_SHUTDOWN
4483 Check openssl doc
4485 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4486 • get_ssl_method
4488 Returns a function pointer to the TLS/SSL method set in $ssl.
4490 my $rv = Net::SSLeay::get_ssl_method($ssl);
4492 # $ssl - value corresponding to openssl's SSL structure
4493 #
4494 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
4495 Check openssl doc
4497 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4498 • in_init, in_before, is_init_finished, in_connect_init,
4500 in_accept_init
4501 COMPATIBILITY: not available in Net-SSLeay-1.85 and before.
4503 Retrieve information about the handshake state machine. All
4505 functions take $ssl as the only argument and return 0 or 1. These
4506 functions are recommended over get_state() and state().
4507 my $rv = Net::SSLeay::is_init_finished($ssl);
4509 # $ssl - value corresponding to openssl's SSL structure
4510 #
4511 # returns: All functions return 1 or 0
4512 Check openssl doc https://www.openssl.org/docs/ssl/SSL_in_init.html
4514 <http://www.openssl.org/docs/ssl/SSL_in_init.html>
4515 • get_state
4517 COMPATIBILITY: OpenSSL 1.1.0 and later use different constants
4519 which are not made available. Use is_init_finished() and related
4520 functions instead.
4521 Returns the SSL connection state.
4523 my $rv = Net::SSLeay::get_state($ssl);
4525 # $ssl - value corresponding to openssl's SSL structure
4526 #
4527 # returns: (integer) state value
4528 # to decode the returned state check:
4529 # SSL_ST_* constants in openssl/ssl.h
4530 # SSL2_ST_* constants in openssl/ssl2.h
4531 # SSL23_ST_* constants in openssl/ssl23.h
4532 # SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
4533 • state
4535 Exactly the same as "get_state".
4537 my $rv = Net::SSLeay::state($ssl);
4539 • set_state
4541 Sets the SSL connection state.
4543 Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4545 Not available with OpenSSL 1.1 and later.
4547 • get_verify_depth
4549 Returns the verification depth limit currently set in $ssl.
4551 my $rv = Net::SSLeay::get_verify_depth($ssl);
4553 # $ssl - value corresponding to openssl's SSL structure
4554 #
4555 # returns: current depth or -1 if no limit has been explicitly set
4556 Check openssl doc
4558 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4559 • set_verify_depth
4561 Sets the maximum depth for the certificate chain verification that
4563 shall be allowed for $ssl.
4564 Net::SSLeay::set_verify_depth($ssl, $depth);
4566 # $ssl - value corresponding to openssl's SSL structure
4567 # $depth - (integer) depth
4568 #
4569 # returns: no return value
4570 Check openssl doc
4572 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4573 • get_verify_mode
4575 Returns the verification mode (bitmask) currently set in $ssl.
4577 my $rv = Net::SSLeay::get_verify_mode($ssl);
4579 # $ssl - value corresponding to openssl's SSL structure
4580 #
4581 # returns: mode (bitmask)
4582 To decode the return value (bitmask) see documentation for
4584 "CTX_get_verify_mode".
4585 Check openssl doc
4587 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4588 • set_verify
4590 Sets the verification flags for $ssl to be $mode and specifies the
4592 $verify_callback function to be used.
4593 Net::SSLeay::set_verify($ssl, $mode, $callback);
4595 # $ssl - value corresponding to openssl's SSL structure
4596 # $mode - mode (bitmask)
4597 # $callback - [optional] reference to perl callback function
4598 #
4599 # returns: no return value
4600 For $mode bitmask details see "CTX_get_verify_mode".
4602 Check openssl doc
4604 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4605 • set_post_handshake_auth
4607 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4609 requires at least OpenSSL 1.1.1, not in LibreSSL
4610 Enable the Post-Handshake Authentication extension to be added to
4612 the ClientHello such that post-handshake authentication can be
4613 requested by the server.
4614 Net::SSLeay::set_posthandshake_auth($ssl, $val);
4616 # $ssl - value corresponding to openssl's SSL structure
4617 # $val - 0 then the extension is not sent, otherwise it is
4618 #
4619 # returns: no return value
4620 Check openssl doc
4622 https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth
4623 <https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth.html>
4624 • verify_client_post_handshake
4626 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4628 requires at least OpenSSL 1.1.1, not in LibreSSL
4629 verify_client_post_handshake causes a CertificateRequest message to
4631 be sent by a server on the given ssl connection.
4632 my $rv = Net::SSLeay::verify_client_post_handshake($ssl);
4634 # $ssl - value corresponding to openssl's SSL structure
4635 #
4636 # returns: 1 if the request succeeded, and 0 if the request failed. The error stack can be examined to determine the failure reason.
4637 Check openssl doc
4639 <https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html>
4640 • get_verify_result
4642 Returns the result of the verification of the X509 certificate
4644 presented by the peer, if any.
4645 my $rv = Net::SSLeay::get_verify_result($ssl);
4647 # $ssl - value corresponding to openssl's SSL structure
4648 #
4649 # returns: (integer)
4650 # 0 - X509_V_OK: ok
4651 # 2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
4652 # 3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
4653 # 4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
4654 # 5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
4655 # 6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
4656 # 7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
4657 # 8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
4658 # 9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
4659 # 10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
4660 # 11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
4661 # 12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
4662 # 13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
4663 # 14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
4664 # 15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
4665 # 16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
4666 # 17 - X509_V_ERR_OUT_OF_MEM: out of memory
4667 # 18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
4668 # 19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
4669 # 20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
4670 # 21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
4671 # 22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
4672 # 23 - X509_V_ERR_CERT_REVOKED: certificate revoked
4673 # 24 - X509_V_ERR_INVALID_CA: invalid CA certificate
4674 # 25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
4675 # 26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
4676 # 27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
4677 # 28 - X509_V_ERR_CERT_REJECTED: certificate rejected
4678 # 29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
4679 # 30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
4680 # 31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
4681 # 32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
4682 # 50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
4683 Check openssl doc
4685 <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4686 • set_verify_result
4688 Override result of peer certificate verification.
4690 Net::SSLeay::set_verify_result($ssl, $v);
4692 # $ssl - value corresponding to openssl's SSL structure
4693 # $v - (integer) result value
4694 #
4695 # returns: no return value
4696 For more info about valid return values see "get_verify_result"
4698 Check openssl doc
4700 <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4701 • get_wbio
4703 Get 'write' BIO linked to an SSL object $ssl.
4705 my $rv = Net::SSLeay::get_wbio($ssl);
4707 # $ssl - value corresponding to openssl's SSL structure
4708 #
4709 # returns: value corresponding to openssl's BIO structure (0 on failure)
4710 Check openssl doc
4712 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4713 • load_client_CA_file
4715 Load X509 certificates from file (PEM formatted).
4717 my $rv = Net::SSLeay::load_client_CA_file($file);
4719 # $file - (string) file name
4720 #
4721 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4722 Check openssl doc
4724 <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4725 • clear_num_renegotiations
4727 Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4729 my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4731 # $ssl - value corresponding to openssl's SSL structure
4732 #
4733 # returns: command result
4734 • need_tmp_RSA
4736 Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4738 my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4740 # $ssl - value corresponding to openssl's SSL structure
4741 #
4742 # returns: command result
4743 Not available with OpenSSL 1.1 and later.
4745 • num_renegotiations
4747 Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4749 my $rv = Net::SSLeay::num_renegotiations($ssl);
4751 # $ssl - value corresponding to openssl's SSL structure
4752 #
4753 # returns: command result
4754 • total_renegotiations
4756 Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4758 my $rv = Net::SSLeay::total_renegotiations($ssl);
4760 # $ssl - value corresponding to openssl's SSL structure
4761 #
4762 # returns: command result
4763 • peek
4765 Copies $max bytes from the specified $ssl into the returned value.
4767 In contrast to the "Net::SSLeay::read()" function, the data in the
4768 SSL buffer is unmodified after the SSL_peek() operation.
4769 Net::SSLeay::peek($ssl, $max);
4771 # $ssl - value corresponding to openssl's SSL structure
4772 # $max - [optional] max bytes to peek (integer) - default is 32768
4773 #
4774 # in scalar context: data read from the TLS/SSL connection, undef on error
4775 # in list context: two-item array consisting of data read (undef on error),
4776 # and return code from SSL_peek().
4777 • peek_ex
4779 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4781 requires at least OpenSSL 1.1.1, not in LibreSSL
4782 Copies $max bytes from the specified $ssl into the returned value.
4784 In contrast to the "Net::SSLeay::read_ex()" function, the data in
4785 the SSL buffer is unmodified after the SSL_peek_ex() operation.
4786 my($got, $rv) = Net::SSLeay::peek_ex($ssl, $max);
4788 # $ssl - value corresponding to openssl's SSL structure
4789 # $max - [optional] max bytes to peek (integer) - default is 32768
4790 #
4791 # returns a list: two-item list consisting of data read (undef on error),
4792 # and return code from SSL_peek_ex().
4793 Check openssl doc
4795 <https://www.openssl.org/docs/manmaster/man3/SSL_peek_ex.html>
4796 • pending
4798 Obtain number of readable bytes buffered in $ssl object.
4800 my $rv = Net::SSLeay::pending($ssl);
4802 # $ssl - value corresponding to openssl's SSL structure
4803 #
4804 # returns: the number of bytes pending
4805 Check openssl doc
4807 <http://www.openssl.org/docs/ssl/SSL_pending.html>
4808 • has_pending
4810 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4812 requires at least OpenSSL 1.1.0, not in LibreSSL
4813 Returns 1 if $ssl has buffered data (whether processed or
4815 unprocessed) and 0 otherwise.
4816 my $rv = Net::SSLeay::has_pending($ssl);
4818 # $ssl - value corresponding to openssl's SSL structure
4819 #
4820 # returns: (integer) 1 or 0
4821 Check openssl doc
4823 <https://www.openssl.org/docs/manmaster/man3/SSL_has_pending.html>
4824 • read
4826 Tries to read $max bytes from the specified $ssl.
4828 my $got = Net::SSLeay::read($ssl, $max);
4830 my($got, $rv) = Net::SSLeay::read($ssl, $max);
4831 # $ssl - value corresponding to openssl's SSL structure
4832 # $max - [optional] max bytes to read (integer) - default is 32768
4833 #
4834 # returns:
4835 # in scalar context: data read from the TLS/SSL connection, undef on error
4836 # in list context: two-item array consisting of data read (undef on error),
4837 # and return code from SSL_read().
4838 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4840 • read_ex
4842 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4844 requires at least OpenSSL 1.1.1, not in LibreSSL
4845 Tries to read $max bytes from the specified $ssl.
4847 my($got, $rv) = Net::SSLeay::read_ex($ssl, $max);
4849 # $ssl - value corresponding to openssl's SSL structure
4850 # $max - [optional] max bytes to read (integer) - default is 32768
4851 #
4852 # returns a list: two-item list consisting of data read (undef on error),
4853 # and return code from SSL_read_ex().
4854 Check openssl doc
4856 <https://www.openssl.org/docs/manmaster/man3/SSL_read_ex.html>
4857 • renegotiate
4859 Turn on flags for renegotiation so that renegotiation will happen
4861 my $rv = Net::SSLeay::renegotiate($ssl);
4863 # $ssl - value corresponding to openssl's SSL structure
4864 #
4865 # returns: 1 on success, 0 on failure
4866 • rstate_string
4868 Returns a 2 letter string indicating the current read state of the
4870 SSL object $ssl.
4871 my $rv = Net::SSLeay::rstate_string($ssl);
4873 # $ssl - value corresponding to openssl's SSL structure
4874 #
4875 # returns: 2-letter string
4876 Check openssl doc
4878 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4879 • rstate_string_long
4881 Returns a string indicating the current read state of the SSL
4883 object ssl.
4884 my $rv = Net::SSLeay::rstate_string_long($ssl);
4886 # $ssl - value corresponding to openssl's SSL structure
4887 #
4888 # returns: string with current state
4889 Check openssl doc
4891 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4892 • session_reused
4894 Query whether a reused session was negotiated during handshake.
4896 my $rv = Net::SSLeay::session_reused($ssl);
4898 # $ssl - value corresponding to openssl's SSL structure
4899 #
4900 # returns: 0 - new session was negotiated; 1 - session was reused.
4901 Check openssl doc
4903 <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4904 • set1_param
4906 COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
4908 Applies X509 verification parameters $vpm on $ssl
4910 my $rv = Net::SSLeay::set1_param($ssl, $vpm);
4912 # $ssl - value corresponding to openssl's SSL structure
4913 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
4914 #
4915 # returns: 1 on success, 0 on failure
4916 • set_accept_state
4918 Sets $ssl to work in server mode.
4920 Net::SSLeay::set_accept_state($ssl);
4922 # $ssl - value corresponding to openssl's SSL structure
4923 #
4924 # returns: no return value
4925 Check openssl doc
4927 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4928 • set_bio
4930 Connects the BIOs $rbio and $wbio for the read and write operations
4932 of the TLS/SSL (encrypted) side of $ssl.
4933 Net::SSLeay::set_bio($ssl, $rbio, $wbio);
4935 # $ssl - value corresponding to openssl's SSL structure
4936 # $rbio - value corresponding to openssl's BIO structure
4937 # $wbio - value corresponding to openssl's BIO structure
4938 #
4939 # returns: no return value
4940 Check openssl doc
4942 <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4943 • set_cipher_list
4945 Sets the list of ciphers only for ssl.
4947 my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
4949 # $ssl - value corresponding to openssl's SSL structure
4950 # $str - (string) cipher list e.g. '3DES:+RSA'
4951 #
4952 # returns: 1 if any cipher could be selected and 0 on complete failure
4953 Check openssl doc
4955 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4956 • set_ciphersuites
4958 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4960 requires at least OpenSSL 1.1.1, not in LibreSSL
4961 Configure the available TLSv1.3 ciphersuites.
4963 my $rv = Net::SSLeay::set_ciphersuites($ssl, $str);
4965 # $ssl - value corresponding to openssl's SSL structure
4966 # $str - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
4967 #
4968 # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
4969 Check openssl doc
4971 <https://www.openssl.org/docs/manmaster/man3/SSL_set_ciphersuites.html>
4972 • set_client_CA_list
4974 Sets the list of CAs sent to the client when requesting a client
4976 certificate for the chosen $ssl, overriding the setting valid for
4977 $ssl's SSL_CTX object.
4978 my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
4980 # $ssl - value corresponding to openssl's SSL structure
4981 # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
4982 #
4983 # returns: no return value
4984 Check openssl doc
4986 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4987 • set_connect_state
4989 Sets $ssl to work in client mode.
4991 Net::SSLeay::set_connect_state($ssl);
4993 # $ssl - value corresponding to openssl's SSL structure
4994 #
4995 # returns: no return value
4996 Check openssl doc
4998 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4999 • set_fd
5001 Sets the file descriptor $fd as the input/output facility for the
5003 TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
5004 file descriptor of a network connection.
5005 my $rv = Net::SSLeay::set_fd($ssl, $fd);
5007 # $ssl - value corresponding to openssl's SSL structure
5008 # $fd - (integer) file handle (got via perl's fileno)
5009 #
5010 # returns: 1 on success, 0 on failure
5011 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5013 • set_psk_client_callback
5015 Sets the psk client callback.
5017 Net::SSLeay::set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
5019 # $ssl - value corresponding to openssl's SSL structure
5020 # $hint - PSK identity hint send by the server
5021 # $identity - PSK identity
5022 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
5023 #
5024 # returns: no return value
5025 Check openssl doc
5027 <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
5028 • set_rfd
5030 Sets the file descriptor $fd as the input (read) facility for the
5032 TLS/SSL (encrypted) side of $ssl.
5033 my $rv = Net::SSLeay::set_rfd($ssl, $fd);
5035 # $ssl - value corresponding to openssl's SSL structure
5036 # $fd - (integer) file handle (got via perl's fileno)
5037 #
5038 # returns: 1 on success, 0 on failure
5039 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5041 • set_wfd
5043 my $rv = Net::SSLeay::set_wfd($ssl, $fd);
5045 # $ssl - value corresponding to openssl's SSL structure
5046 # $fd - (integer) file handle (got via perl's fileno)
5047 #
5048 # returns: 1 on success, 0 on failure
5049 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5051 • set_info_callback
5053 Sets the callback function, that can be used to obtain state
5055 information for $ssl during connection setup and use. When
5056 callback is undef, the callback setting currently valid for ctx is
5057 used.
5058 Net::SSLeay::set_info_callback($ssl, $cb, [$data]);
5060 # $ssl - value corresponding to openssl's SSL structure
5061 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
5062 #
5063 # returns: no return value
5064 Check openssl doc
5066 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5067 • CTX_set_info_callback
5069 Sets the callback function on ctx, that can be used to obtain state
5071 information during ssl connection setup and use. When callback is
5072 undef, an existing callback will be disabled.
5073 Net::SSLeay::CTX_set_info_callback($ssl, $cb, [$data]);
5075 # $ssl - value corresponding to openssl's SSL structure
5076 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
5077 #
5078 # returns: no return value
5079 Check openssl doc
5081 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5082 • set_msg_callback
5084 Sets the callback function, that can be used to obtain protocol
5086 messages information for $ssl during connection setup and use.
5087 When callback is undef, the callback setting currently valid for
5088 ctx is used. Note that set_msg_callback_arg is not provided as
5089 there is no need to explicitly set $arg, this is handled by
5090 set_msg_callback.
5091 Net::SSLeay::set_msg_callback($ssl, $cb, [$arg]);
5093 # $ssl - value corresponding to openssl's SSL structure
5094 # $cb - sub { my ($write_p,$version,$content_type,$buf,$len,$ssl,$arg) = @_; ... }
5095 #
5096 # returns: no return value
5097 Check openssl doc
5099 <http://www.openssl.org/docs/manmaster/man3/SSL_set_msg_callback.html>
5100 • CTX_set_msg_callback
5102 Sets the callback function on ctx, that can be used to obtain
5104 protocol messages information for ssl connection setup and use.
5105 When callback is undef, the existing callback will be disabled.
5106 Note that CTX_set_msg_callback_arg is not provided as there is no
5107 need to explicitly set $arg, this is handled by
5108 CTX_set_msg_callback.
5109 Net::SSLeay::CTX_set_msg_callback($ssl, $cb, [$arg]);
5111 # $ssl - value corresponding to openssl's SSL structure
5112 # $cb - sub { my ($write_p,$version,$content_type,$buf,$len,$ssl,$arg) = @_; ... }
5113 #
5114 # returns: no return value
5115 Check openssl doc
5117 <http://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_msg_callback.html>
5118 • set_pref_cipher
5120 Sets the list of available ciphers for $ssl using the control
5122 string $str.
5123 my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
5125 # $ssl - value corresponding to openssl's SSL structure
5126 # $str - (string) cipher list e.g. '3DES:+RSA'
5127 #
5128 # returns: 1 if any cipher could be selected and 0 on complete failure
5129 Check openssl doc
5131 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
5132 • CTX_set_psk_client_callback
5134 Sets the psk client callback.
5136 Net::SSLeay::CTX_set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
5138 # $ssl - value corresponding to openssl's SSL structure
5139 # $hint - PSK identity hint send by the server
5140 # $identity - PSK identity
5141 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
5142 #
5143 # returns: no return value
5144 Check openssl doc
5146 <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
5147 • set_purpose
5149 my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
5151 # $ssl - value corresponding to openssl's SSL structure
5152 # $purpose - (integer) purpose identifier
5153 #
5154 # returns: 1 on success, 0 on failure
5155 For more info about available $purpose identifiers see
5157 "CTX_set_purpose".
5158 • set_quiet_shutdown
5160 Sets the 'quiet shutdown' flag for $ssl to be $mode.
5162 Net::SSLeay::set_quiet_shutdown($ssl, $mode);
5164 # $ssl - value corresponding to openssl's SSL structure
5165 # $mode - 0 or 1
5166 #
5167 # returns: no return value
5168 Check openssl doc
5170 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
5171 • set_session
5173 Set a TLS/SSL session to be used during TLS/SSL connect.
5175 my $rv = Net::SSLeay::set_session($to, $ses);
5177 # $to - value corresponding to openssl's SSL structure
5178 # $ses - value corresponding to openssl's SSL_SESSION structure
5179 #
5180 # returns: 1 on success, 0 on failure
5181 Check openssl doc
5183 <http://www.openssl.org/docs/ssl/SSL_set_session.html>
5184 • set_session_id_context
5186 Sets the context $sid_ctx of length $sid_ctx_len within which a
5188 session can be reused for the $ssl object.
5189 my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
5191 # $ssl - value corresponding to openssl's SSL structure
5192 # $sid_ctx - data buffer
5193 # $sid_ctx_len - length of data in $sid_ctx
5194 #
5195 # returns: 1 on success, 0 on failure
5196 Check openssl doc
5198 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
5199 • set_session_secret_cb
5201 Setup pre-shared secret session resumption function.
5203 Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
5205 # $ssl - value corresponding to openssl's SSL structure
5206 # $func - perl reference to callback function
5207 # $data - [optional] data that will be passed to callback function when invoked
5208 #
5209 # returns: no return value
5210 The callback function will be called like:
5212 callback_function($secret, $ciphers, $pref_cipher, $data);
5214 # $secret is the current master session key, usually all 0s at the beginning of a session
5215 # $ciphers is ref to an array of peer cipher names
5216 # $pref_cipher is a ref to an index into the list of cipher names of
5217 # the preferred cipher. Set it if you want to specify a preferred cipher
5218 # $data is the data passed to set_session_secret_cb
5219 The callback function should return 1 if it likes the suggested
5221 cipher (or has selected an alternative by setting pref_cipher),
5222 else it should return 0 (in which case OpenSSL will select its own
5223 preferred cipher).
5224 With OpenSSL 1.1 and later, callback_function can change the master
5226 key for the session by altering $secret and returning 1.
5227 • CTX_set_tlsext_ticket_getkey_cb
5229 Setup encryption for TLS session tickets (stateless session reuse).
5231 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($ctx, $func, $data);
5233 # $ctx - value corresponding to openssl's SSL_CTX structure
5234 # $func - perl reference to callback function
5235 # $data - [optional] data that will be passed to callback function when invoked
5236 #
5237 # returns: no return value
5238 The callback function will be called like:
5240 getkey($data,[$key_name]) -> ($key,$current_key_name)
5242 # $data is the data passed to set_session_secret_cb
5243 # $key_name is the name of the key OpenSSL has extracted from the session ticket
5244 # $key is the requested key for ticket encryption + HMAC
5245 # $current_key_name is the name for the currently valid key
5246 OpenSSL will call the function without a key name if it generates a
5248 new ticket. It then needs the callback to return the
5249 encryption+HMAC key and an identifier (key name) for this key.
5250 When OpenSSL gets a session ticket from the client it extracts the
5252 key name and calls the callback with this name as argument. It then
5253 expects the callback to return the encryption+HMAC key matching the
5254 requested key name and and also the key name which should be used
5255 at the moment. If the requested key name and the returned key name
5256 differ it means that this session ticket was created with an
5257 expired key and need to be renewed. In this case OpenSSL will call
5258 the callback again with no key name to create a new session ticket
5259 based on the old one.
5260 The key must be at least 32 byte of random data which can be
5262 created with RAND_bytes. Internally the first 16 byte are used as
5263 key in AES-128 encryption while the next 16 byte are used for the
5264 SHA-256 HMAC. The key name are binary data and must be exactly 16
5265 byte long.
5266 Example:
5268 Net::SSLeay::RAND_bytes(my $oldkey,32);
5270 Net::SSLeay::RAND_bytes(my $newkey,32);
5271 my $oldkey_name = pack("a16",'oldsecret');
5272 my $newkey_name = pack("a16",'newsecret');
5273 my @keys = (
5275 [ $newkey_name, $newkey ], # current active key
5276 [ $oldkey_name, $oldkey ], # already expired
5277 );
5278 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
5280 my ($mykeys,$name) = @_;
5281 # return (current_key, current_key_name) if no name given
5283 return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
5284 # return (matching_key, current_key_name) if we find a key matching
5286 # the given name
5287 for(my $i = 0; $i<@$mykeys; $i++) {
5288 next if $name ne $mykeys->[$i][0];
5289 return ($mykeys->[$i][1],$mykeys->[0][0]);
5290 }
5291 # no matching key found
5293 return;
5294 },\@keys);
5295 This function is based on the OpenSSL function
5297 SSL_CTX_set_tlsext_ticket_key_cb but provides a simpler to use
5298 interface. For more information see
5299 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tlsext_ticket_key_cb.html>
5300 • set_session_ticket_ext_cb
5302 Setup callback for TLS session tickets (stateless session reuse).
5304 Net::SSLeay::set_session_ticket_ext_cb($ssl, $func, $data);
5306 # $ssl - value corresponding to openssl's SSL structure
5307 # $func - perl reference to callback function
5308 # $data - [optional] data that will be passed to callback function when invoked
5309 #
5310 # returns: no return value
5311 The callback function will be called like:
5313 getticket($ssl,$ticket,$data) -> $return_value
5315 # $ssl is a value corresponding to openssl's SSL structure
5316 # $ticket is a value of received TLS session ticket (can also be empty)
5317 # $data is the data passed to set_session_ticket_ext_cb
5318 # $return_value is either 0 (failure) or 1 (success)
5319 This function is based on the OpenSSL function
5321 SSL_set_session_ticket_ext_cb.
5322 • set_session_ticket_ext
5324 Set TLS session ticket (stateless session reuse).
5326 Net::SSLeay::set_session_ticket_ext($ssl, $ticket);
5328 # $ssl - value corresponding to openssl's SSL structure
5329 # $ticket - is a value of TLS session ticket which client will send (can also be empty string)
5330 #
5331 # returns: no return value
5332 The callback function will be called like:
5334 getticket($ssl,$ticket,$data) -> $return_value
5336 # $ssl is a value corresponding to openssl's SSL structure
5337 # $ticket is a value of received TLS session ticket (can also be empty)
5338 # $data is the data passed to set_session_ticket_ext_cb
5339 # $return_value is either 0 (failure) or 1 (success)
5340 This function is based on the OpenSSL function
5342 SSL_set_session_ticket_ext_cb.
5343 • set_shutdown
5345 Sets the shutdown state of $ssl to $mode.
5347 Net::SSLeay::set_shutdown($ssl, $mode);
5349 # $ssl - value corresponding to openssl's SSL structure
5350 # $mode - (integer) shutdown mode:
5351 # 0 - No shutdown
5352 # 1 - SSL_SENT_SHUTDOWN
5353 # 2 - SSL_RECEIVED_SHUTDOWN
5354 # 3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
5355 #
5356 # returns: no return value
5357 Check openssl doc
5359 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
5360 • set_ssl_method
5362 Sets a new TLS/SSL method for a particular $ssl object.
5364 my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
5366 # $ssl - value corresponding to openssl's SSL structure
5367 # $method - value corresponding to openssl's SSL_METHOD structure
5368 #
5369 # returns: 1 on success, 0 on failure
5370 Check openssl doc
5372 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
5373 • set_tmp_dh
5375 Sets DH parameters to be used to be $dh.
5377 my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
5379 # $ssl - value corresponding to openssl's SSL structure
5380 # $dh - value corresponding to openssl's DH structure
5381 #
5382 # returns: 1 on success, 0 on failure
5383 Check openssl doc
5385 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5386 • set_tmp_dh_callback
5388 Sets the callback function for $ssl to be used when a DH parameters
5390 are required to $dh_cb.
5391 ??? (does this function really work?)
5393 Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
5395 # $ssl - value corresponding to openssl's SSL structure
5396 # $dh_cb - pointer to function ???
5397 #
5398 # returns: no return value
5399 Check openssl doc
5401 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5402 • set_tmp_rsa
5404 Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
5406 my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
5408 # $ssl - value corresponding to openssl's SSL structure
5409 # $rsa - value corresponding to openssl's RSA structure
5410 #
5411 # returns: 1 on success, 0 on failure
5412 Example:
5414 $rsakey = Net::SSLeay::RSA_generate_key();
5416 Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
5417 Net::SSLeay::RSA_free($rsakey);
5418 Check openssl doc
5420 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5421 • set_tmp_rsa_callback
5423 Sets the callback function for $ssl to be used when a
5425 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
5426 ??? (does this function really work?)
5428 Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
5430 # $ssl - value corresponding to openssl's SSL structure
5431 # $tmp_rsa_callback - (function pointer) ???
5432 #
5433 # returns: no return value
5434 Check openssl doc
5436 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5437 • set_trust
5439 my $rv = Net::SSLeay::set_trust($ssl, $trust);
5441 # $ssl - value corresponding to openssl's SSL structure
5442 # $trust - (integer) trust identifier
5443 #
5444 # returns: the original value
5445 For more details about $trust values see "CTX_set_trust".
5447 • shutdown
5449 Shuts down an active TLS/SSL connection. It sends the 'close
5451 notify' shutdown alert to the peer.
5452 my $rv = Net::SSLeay::shutdown($ssl);
5454 # $ssl - value corresponding to openssl's SSL structure
5455 #
5456 # returns: 1 - shutdown was successfully completed
5457 # 0 - shutdown is not yet finished,
5458 # -1 - shutdown was not successful
5459 Check openssl doc
5461 <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
5462 • state_string
5464 Returns a 6 letter string indicating the current state of the SSL
5466 object $ssl.
5467 my $rv = Net::SSLeay::state_string($ssl);
5469 # $ssl - value corresponding to openssl's SSL structure
5470 #
5471 # returns: 6-letter string
5472 Check openssl doc
5474 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5475 • state_string_long
5477 Returns a string indicating the current state of the SSL object
5479 $ssl.
5480 my $rv = Net::SSLeay::state_string_long($ssl);
5482 # $ssl - value corresponding to openssl's SSL structure
5483 #
5484 # returns: state strings
5485 Check openssl doc
5487 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5488 • set_default_passwd_cb
5490 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5492 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5493 Sets the default password callback called when loading/storing a
5495 PEM certificate with encryption for $ssl.
5496 Net::SSLeay::set_default_passwd_cb($ssl, $func);
5498 # $ssl - value corresponding to openssl's SSL structure
5499 # $func - perl reference to callback function
5500 #
5501 # returns: no return value
5502 Check openssl doc
5504 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5505 • set_default_passwd_cb_userdata
5507 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5509 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5510 Sets a pointer to userdata which will be provided to the password
5512 callback of $ssl on invocation.
5513 Net::SSLeay::set_default_passwd_cb_userdata($ssl, $userdata);
5515 # $ssl - value corresponding to openssl's SSL structure
5516 # $userdata - data that will be passed to callback function when invoked
5517 #
5518 # returns: no return value
5519 Check openssl doc
5521 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5522 • use_PrivateKey
5524 Adds $pkey as private key to $ssl.
5526 my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
5528 # $ssl - value corresponding to openssl's SSL structure
5529 # $pkey - value corresponding to openssl's EVP_PKEY structure
5530 #
5531 # returns: 1 on success, otherwise check out the error stack to find out the reason
5532 Check openssl doc
5534 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5535 • use_PrivateKey_ASN1
5537 Adds the private key of type $pk stored in $data to $ssl.
5539 my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
5541 # $pk - (integer) key type, NID of corresponding algorithm
5542 # $ssl - value corresponding to openssl's SSL structure
5543 # $data - key data (binary)
5544 # $len - length of $data
5545 #
5546 # returns: 1 on success, otherwise check out the error stack to find out the reason
5547 Check openssl doc
5549 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5550 • use_PrivateKey_file
5552 Adds the first private key found in $file to $ssl.
5554 my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
5556 # $ssl - value corresponding to openssl's SSL structure
5557 # $file - (string) file name
5558 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5559 #
5560 # returns: 1 on success, otherwise check out the error stack to find out the reason
5561 Check openssl doc
5563 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5564 • use_RSAPrivateKey
5566 Adds $rsa as RSA private key to $ssl.
5568 my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
5570 # $ssl - value corresponding to openssl's SSL structure
5571 # $rsa - value corresponding to openssl's RSA structure
5572 #
5573 # returns: 1 on success, otherwise check out the error stack to find out the reason
5574 Check openssl doc
5576 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5577 • use_RSAPrivateKey_ASN1
5579 Adds RSA private key stored in $data to $ssl.
5581 my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
5583 # $ssl - value corresponding to openssl's SSL structure
5584 # $data - key data (binary)
5585 # $len - length of $data
5586 #
5587 # returns: 1 on success, otherwise check out the error stack to find out the reason
5588 Check openssl doc
5590 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5591 • use_RSAPrivateKey_file
5593 Adds the first RSA private key found in $file to $ssl.
5595 my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
5597 # $ssl - value corresponding to openssl's SSL structure
5598 # $file - (string) file name
5599 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5600 #
5601 # returns: 1 on success, otherwise check out the error stack to find out the reason
5602 Check openssl doc
5604 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5605 • use_certificate
5607 Loads the certificate $x into $ssl.
5609 my $rv = Net::SSLeay::use_certificate($ssl, $x);
5611 # $ssl - value corresponding to openssl's SSL structure
5612 # $x - value corresponding to openssl's X509 structure
5613 #
5614 # returns: 1 on success, otherwise check out the error stack to find out the reason
5615 Check openssl doc
5617 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5618 • use_certificate_ASN1
5620 Loads the ASN1 encoded certificate from $data to $ssl.
5622 my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
5624 # $ssl - value corresponding to openssl's SSL structure
5625 # $data - certificate data (binary)
5626 # $len - length of $data
5627 #
5628 # returns: 1 on success, otherwise check out the error stack to find out the reason
5629 Check openssl doc
5631 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5632 • use_certificate_chain_file
5634 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5636 requires at least OpenSSL 1.1.0
5637 Loads a certificate chain from $file into $ssl. The certificates
5639 must be in PEM format and must be sorted starting with the
5640 subject's certificate (actual client or server certificate),
5641 followed by intermediate CA certificates if applicable, and ending
5642 at the highest level (root) CA.
5643 my $rv = Net::SSLeay::use_certificate_chain_file($ssl, $file);
5645 # $ssl - value corresponding to openssl's SSL structure
5646 # $file - (string) file name
5647 #
5648 # returns: 1 on success, otherwise check out the error stack to find out the reason
5649 Check openssl doc
5651 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5652 • use_certificate_file
5654 Loads the first certificate stored in $file into $ssl.
5656 my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
5658 # $ssl - value corresponding to openssl's SSL structure
5659 # $file - (string) file name
5660 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5661 #
5662 # returns: 1 on success, otherwise check out the error stack to find out the reason
5663 Check openssl doc
5665 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5666 • get_version
5668 Returns SSL/TLS protocol name
5670 my $rv = Net::SSLeay::get_version($ssl);
5672 # $ssl - value corresponding to openssl's SSL structure
5673 #
5674 # returns: (string) protocol name, see OpenSSL manual for the full list
5675 # TLSv1
5676 # TLSv1.3
5677 Check openssl doc
5679 <https://www.openssl.org/docs/manmaster/man3/SSL_get_version.html>
5680 • version
5682 Returns SSL/TLS protocol version
5684 my $rv = Net::SSLeay::version($ssl);
5686 # $ssl - value corresponding to openssl's SSL structure
5687 #
5688 # returns: (integer) protocol version, see OpenSSL manual for the full list
5689 # 0x0301 - TLS1_VERSION (TLSv1)
5690 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5691 Check openssl doc
5693 <https://www.openssl.org/docs/manmaster/man3/SSL_version.html>
5694 • client_version
5696 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5698 requires at least OpenSSL 1.1.0, not in LibreSSL
5699 Returns TLS protocol version used by the client when initiating the
5701 connection
5702 my $rv = Net::SSLeay::client_version($ssl);
5704 # $ssl - value corresponding to openssl's SSL structure
5705 #
5706 # returns: (integer) protocol version, see OpenSSL manual for the full list
5707 # 0x0301 - TLS1_VERSION (TLSv1)
5708 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5709 Check openssl doc
5711 <https://www.openssl.org/docs/manmaster/man3/SSL_client_version.html>
5712 • is_dtls
5714 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5716 requires at least OpenSSL 1.1.0, not in LibreSSL
5717 my $rv = Net::SSLeay::is_dtls($ssl);
5719 # $ssl - value corresponding to openssl's SSL structure
5720 #
5721 # returns: (integer) zero or one
5722 # 0 - connection is not using DTLS
5723 # 1 - connection is using DTLS
5724 Check openssl doc
5726 <https://www.openssl.org/docs/manmaster/man3/SSL_is_dtls.html>
5727 • want
5729 Returns state information for the SSL object $ssl.
5731 my $rv = Net::SSLeay::want($ssl);
5733 # $ssl - value corresponding to openssl's SSL structure
5734 #
5735 # returns: state
5736 # 1 - SSL_NOTHING
5737 # 2 - SSL_WRITING
5738 # 3 - SSL_READING
5739 # 4 - SSL_X509_LOOKUP
5740 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5742 • write
5744 Writes data from the buffer $data into the specified $ssl
5746 connection.
5747 my $rv = Net::SSLeay::write($ssl, $data);
5749 # $ssl - value corresponding to openssl's SSL structure
5750 # $data - data to be written
5751 #
5752 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5753 # 0 - write not successful, probably the underlying connection was closed
5754 # <0 - error
5755 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5757 • write_ex
5759 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5761 requires at least OpenSSL 1.1.1, not in LibreSSL
5762 Writes data from the buffer $data into the specified $ssl
5764 connection.
5765 my ($len, $rv) = Net::SSLeay::write_ex($ssl, $data);
5767 # $ssl - value corresponding to openssl's SSL structure
5768 # $data - data to be written
5769 #
5770 # returns a list: two-item list consisting of number of bytes written,
5771 # and return code from SSL_write_ex()
5772 Check openssl doc
5774 <https://www.openssl.org/docs/manmaster/man3/SSL_write_ex.html>
5775 • write_partial
5777 NOTE: Does not exactly correspond to any low level API function
5779 Writes a fragment of data in $data from the buffer $data into the
5781 specified $ssl connection. This is a non-blocking function like
5782 Net::SSLeay::write().
5783 my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
5785 # $ssl - value corresponding to openssl's SSL structure
5786 # $from - (integer) offset from the beginning of $data
5787 # $count - (integer) length of data to be written
5788 # $data - data buffer
5789 #
5790 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5791 # 0 - write not successful, probably the underlying connection was closed
5792 # <0 - error
5793 • set_tlsext_host_name
5795 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5797 requires at least openssl-0.9.8f
5798 Sets TLS servername extension on SLL object $ssl to value $name.
5800 my $rv = set_tlsext_host_name($ssl, $name);
5802 # $ssl - value corresponding to openssl's SSL structure
5803 # $name - (string) name to be set
5804 #
5805 # returns: 1 on success, 0 on failure
5806 Low level API: RAND_* related functions
5808 Check openssl doc related to RAND stuff
5810 <http://www.openssl.org/docs/crypto/rand.html>
5811 • RAND_add
5813 Mixes the $num bytes at $buf into the PRNG state.
5815 Net::SSLeay::RAND_add($buf, $num, $entropy);
5817 # $buf - buffer with data to be mixed into the PRNG state
5818 # $num - number of bytes in $buf
5819 # $entropy - estimate of how much randomness is contained in $buf (in bytes)
5820 #
5821 # returns: no return value
5822 Check openssl doc
5824 <http://www.openssl.org/docs/crypto/RAND_add.html>
5825 • RAND_seed
5827 Equivalent to "RAND_add" when $num == $entropy.
5829 Net::SSLeay::RAND_seed($buf); # Perlishly figures out buf size
5831 # $buf - buffer with data to be mixed into the PRNG state
5832 # $num - number of bytes in $buf
5833 #
5834 # returns: no return value
5835 Check openssl doc
5837 <http://www.openssl.org/docs/crypto/RAND_add.html>
5838 • RAND_status
5840 Gives PRNG status (seeded enough or not).
5842 my $rv = Net::SSLeay::RAND_status();
5844 #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5845 Check openssl doc
5847 <http://www.openssl.org/docs/crypto/RAND_add.html>
5848 • RAND_bytes
5850 Puts $num cryptographically strong pseudo-random bytes into $buf.
5852 my $rv = Net::SSLeay::RAND_bytes($buf, $num);
5854 # $buf - buffer where the random data will be stored
5855 # $num - the size (in bytes) of requested random data
5856 #
5857 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5858 Check openssl doc
5860 <http://www.openssl.org/docs/manmaster/man3/RAND_bytes.html>
5861 • RAND_priv_bytes
5863 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5865 requires at least OpenSSL 1.1.1, not in LibreSSL
5866 Puts $num cryptographically strong pseudo-random bytes into $buf.
5868 my $rv = Net::SSLeay::RAND_priv_bytes($buf, $num);
5870 # $buf - buffer where the random data will be stored
5871 # $num - the size (in bytes) of requested random data
5872 #
5873 # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5874 RAND_priv_bytes has the same semantics as RAND_bytes, but see see
5876 the documentation for more information.
5877 Check openssl doc
5879 <http://www.openssl.org/docs/manmaster/man3/RAND_priv_bytes.html>
5880 • RAND_pseudo_bytes
5882 Puts $num pseudo-random (not necessarily unpredictable) bytes into
5884 $buf.
5885 my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
5887 # $buf - buffer where the random data will be stored
5888 # $num - the size (in bytes) of requested random data
5889 #
5890 # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
5891 Check openssl doc
5893 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5894 • RAND_cleanup
5896 Erase the PRNG state.
5898 Net::SSLeay::RAND_cleanup();
5900 # no args, no return value
5901 Check openssl doc
5903 <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5904 • RAND_egd_bytes
5906 Queries the entropy gathering daemon EGD on socket $path for $bytes
5908 bytes.
5909 my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
5911 # $path - path to a socket of entropy gathering daemon EGD
5912 # $bytes - number of bytes we want from EGD
5913 #
5914 # returns: the number of bytes read from the daemon on success, and -1 on failure
5915 Check openssl doc
5917 <http://www.openssl.org/docs/crypto/RAND_egd.html>
5918 • RAND_file_name
5920 Generates a default path for the random seed file.
5922 my $file = Net::SSLeay::RAND_file_name($num);
5924 # $num - maximum size of returned file name
5925 #
5926 # returns: string with file name on success, '' (empty string) or undef on failure
5927 LibreSSL and OpenSSL 1.1.0a and later return undef when, for
5929 example, $num is not large enough to hold the filename.
5930 Check openssl doc
5932 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5933 • RAND_load_file
5935 COMPATIBILITY: Is no longer functional on LibreSSL
5937 Reads $max_bytes of bytes from $file_name and adds them to the
5939 PRNG.
5940 my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
5942 # $file_name - the name of file
5943 # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
5944 #
5945 # returns: the number of bytes read
5946 Check openssl doc
5948 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5949 • RAND_write_file
5951 Writes 1024 random bytes to $file_name which can be used to
5953 initialize the PRNG by calling "RAND_load_file" in a later session.
5954 my $rv = Net::SSLeay::RAND_write_file($file_name);
5956 # $file_name - the name of file
5957 #
5958 # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
5959 Check openssl doc
5961 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5962 • RAND_poll
5964 Collects some entropy from operating system and adds it to the
5966 PRNG.
5967 my $rv = Net::SSLeay::RAND_poll();
5969 # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5970 Low level API: OBJ_* related functions
5972 • OBJ_cmp
5974 Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5976 my $rv = Net::SSLeay::OBJ_cmp($a, $b);
5978 # $a - value corresponding to openssl's ASN1_OBJECT structure
5979 # $b - value corresponding to openssl's ASN1_OBJECT structure
5980 #
5981 # returns: if the two are identical 0 is returned
5982 Check openssl doc
5984 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5985 • OBJ_dup
5987 Returns a copy/duplicate of $o.
5989 my $rv = Net::SSLeay::OBJ_dup($o);
5991 # $o - value corresponding to openssl's ASN1_OBJECT structure
5992 #
5993 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5994 Check openssl doc
5996 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5997 • OBJ_nid2ln
5999 Returns long name for given NID $n.
6001 my $rv = Net::SSLeay::OBJ_nid2ln($n);
6003 # $n - (integer) NID
6004 #
6005 # returns: (string) long name e.g. 'commonName'
6006 Check openssl doc
6008 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6009 • OBJ_ln2nid
6011 Returns NID corresponding to given long name $n.
6013 my $rv = Net::SSLeay::OBJ_ln2nid($s);
6015 # $s - (string) long name e.g. 'commonName'
6016 #
6017 # returns: (integer) NID
6018 • OBJ_nid2sn
6020 Returns short name for given NID $n.
6022 my $rv = Net::SSLeay::OBJ_nid2sn($n);
6024 # $n - (integer) NID
6025 #
6026 # returns: (string) short name e.g. 'CN'
6027 Example:
6029 print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
6031 • OBJ_sn2nid
6033 Returns NID corresponding to given short name $s.
6035 my $rv = Net::SSLeay::OBJ_sn2nid($s);
6037 # $s - (string) short name e.g. 'CN'
6038 #
6039 # returns: (integer) NID
6040 Example:
6042 print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
6044 print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
6045 • OBJ_nid2obj
6047 Returns ASN1_OBJECT for given NID $n.
6049 my $rv = Net::SSLeay::OBJ_nid2obj($n);
6051 # $n - (integer) NID
6052 #
6053 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6054 Check openssl doc
6056 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6057 • OBJ_obj2nid
6059 Returns NID corresponding to given ASN1_OBJECT $o.
6061 my $rv = Net::SSLeay::OBJ_obj2nid($o);
6063 # $o - value corresponding to openssl's ASN1_OBJECT structure
6064 #
6065 # returns: (integer) NID
6066 Check openssl doc
6068 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6069 • OBJ_txt2obj
6071 Converts the text string s into an ASN1_OBJECT structure. If
6073 $no_name is 0 then long names (e.g. 'commonName') and short names
6074 (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
6075 '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
6076 my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
6078 # $s - text string to be converted
6079 # $no_name - (integer) 0 or 1
6080 #
6081 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6082 Check openssl doc
6084 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6085 • OBJ_obj2txt
6087 Converts the ASN1_OBJECT a into a textual representation.
6089 Net::SSLeay::OBJ_obj2txt($a, $no_name);
6091 # $a - value corresponding to openssl's ASN1_OBJECT structure
6092 # $no_name - (integer) 0 or 1
6093 #
6094 # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
6095 Check openssl doc
6097 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6098 • OBJ_txt2nid
6100 Returns NID corresponding to text string $s which can be a long
6102 name, a short name or the numerical representation of an object.
6103 my $rv = Net::SSLeay::OBJ_txt2nid($s);
6105 # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
6106 #
6107 # returns: (integer) NID
6108 Example:
6110 my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
6112 Net::SSLeay::OBJ_nid2sn($n);
6113 Check openssl doc
6115 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6116 Low level API: ASN1_INTEGER_* related functions
6118 • ASN1_INTEGER_new
6120 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6122 Creates a new ASN1_INTEGER structure.
6124 my $rv = Net::SSLeay::ASN1_INTEGER_new();
6126 #
6127 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6128 • ASN1_INTEGER_free
6130 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6132 Free an allocated ASN1_INTEGER structure.
6134 Net::SSLeay::ASN1_INTEGER_free($i);
6136 # $i - value corresponding to openssl's ASN1_INTEGER structure
6137 #
6138 # returns: no return value
6139 • ASN1_INTEGER_get
6141 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6143 Returns integer value of given ASN1_INTEGER object.
6145 BEWARE: If the value stored in ASN1_INTEGER is greater than max.
6147 integer that can be stored in 'long' type (usually 32bit but may
6148 vary according to platform) then this function will return -1. For
6149 getting large ASN1_INTEGER values consider using
6150 "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
6151 my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
6153 # $a - value corresponding to openssl's ASN1_INTEGER structure
6154 #
6155 # returns: integer value of ASN1_INTEGER object in $a
6156 • ASN1_INTEGER_set
6158 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6160 Sets value of given ASN1_INTEGER object to value $val
6162 BEWARE: $val has max. limit (= max. integer that can be stored in
6164 'long' type). For setting large ASN1_INTEGER values consider using
6165 "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
6166 my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
6168 # $i - value corresponding to openssl's ASN1_INTEGER structure
6169 # $val - integer value
6170 #
6171 # returns: 1 on success, 0 on failure
6172 • P_ASN1_INTEGER_get_dec
6174 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6176 Returns string with decimal representation of integer value of
6178 given ASN1_INTEGER object.
6179 Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
6181 # $i - value corresponding to openssl's ASN1_INTEGER structure
6182 #
6183 # returns: string with decimal representation
6184 • P_ASN1_INTEGER_get_hex
6186 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6188 Returns string with hexadecimal representation of integer value of
6190 given ASN1_INTEGER object.
6191 Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
6193 # $i - value corresponding to openssl's ASN1_INTEGER structure
6194 #
6195 # returns: string with hexadecimal representation
6196 • P_ASN1_INTEGER_set_dec
6198 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6200 Sets value of given ASN1_INTEGER object to value $val (decimal
6202 string, suitable for large integers)
6203 Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
6205 # $i - value corresponding to openssl's ASN1_INTEGER structure
6206 # $str - string with decimal representation
6207 #
6208 # returns: 1 on success, 0 on failure
6209 • P_ASN1_INTEGER_set_hex
6211 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6213 Sets value of given ASN1_INTEGER object to value $val (hexadecimal
6215 string, suitable for large integers)
6216 Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
6218 # $i - value corresponding to openssl's ASN1_INTEGER structure
6219 # $str - string with hexadecimal representation
6220 #
6221 # returns: 1 on success, 0 on failure
6222 Low level API: ASN1_STRING_* related functions
6224 • P_ASN1_STRING_get
6226 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6228 Returns string value of given ASN1_STRING object.
6230 Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
6232 # $s - value corresponding to openssl's ASN1_STRING structure
6233 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
6234 #
6235 # returns: string
6236 $string = Net::SSLeay::P_ASN1_STRING_get($s);
6238 #is the same as:
6239 $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
6240 Low level API: ASN1_TIME_* related functions
6242 • ASN1_TIME_new
6244 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6246 my $time = ASN1_TIME_new();
6248 # returns: value corresponding to openssl's ASN1_TIME structure
6249 • ASN1_TIME_free
6251 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6253 ASN1_TIME_free($time);
6255 # $time - value corresponding to openssl's ASN1_TIME structure
6256 • ASN1_TIME_set
6258 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6260 ASN1_TIME_set($time, $t);
6262 # $time - value corresponding to openssl's ASN1_TIME structure
6263 # $t - time value in seconds since 1.1.1970
6264 BEWARE: It is platform dependent how this function will handle
6266 dates after 2038. Although perl's integer is large enough the
6267 internal implementation of this function is dependent on the size
6268 of time_t structure (32bit time_t has problem with 2038).
6269 If you want to safely set date and time after 2038 use function
6271 "P_ASN1_TIME_set_isotime".
6272 • P_ASN1_TIME_get_isotime
6274 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6276 requires at least openssl-0.9.7e
6277 NOTE: Does not exactly correspond to any low level API function
6279 Gives ISO-8601 string representation of ASN1_TIME structure.
6281 my $datetime_string = P_ASN1_TIME_get_isotime($time);
6283 # $time - value corresponding to openssl's ASN1_TIME structure
6284 #
6285 # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
6286 The output format is compatible with module
6288 DateTime::Format::RFC3339
6289 • P_ASN1_TIME_set_isotime
6291 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6293 requires at least openssl-0.9.7e
6294 NOTE: Does not exactly correspond to any low level API function
6296 Sets time and date value of ANS1_time structure.
6298 my $rv = P_ASN1_TIME_set_isotime($time, $string);
6300 # $time - value corresponding to openssl's ASN1_TIME structure
6301 # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
6302 #
6303 # returns: 1 on success, 0 on failure
6304 The $string parameter has to be in full form like
6306 "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
6307 "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
6308 "2012-03-22" are not supported.
6309 • P_ASN1_TIME_put2string
6311 COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
6313 bugs with openssl-0.9.8i
6314 NOTE: Does not exactly correspond to any low level API function
6316 Gives string representation of ASN1_TIME structure.
6318 my $str = P_ASN1_TIME_put2string($time);
6320 # $time - value corresponding to openssl's ASN1_TIME structure
6321 #
6322 # returns: datetime string like 'May 16 20:39:37 2033 GMT'
6323 • P_ASN1_UTCTIME_put2string
6325 NOTE: deprecated function, only for backward compatibility, just an
6327 alias for "P_ASN1_TIME_put2string"
6328 Low level API: X509_* related functions
6330 • X509_new
6332 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6334 Allocates and initializes a X509 structure.
6336 my $rv = Net::SSLeay::X509_new();
6338 #
6339 # returns: value corresponding to openssl's X509 structure (0 on failure)
6340 Check openssl doc
6342 <http://www.openssl.org/docs/crypto/X509_new.html>
6343 • X509_free
6345 Frees up the X509 structure.
6347 Net::SSLeay::X509_free($a);
6349 # $a - value corresponding to openssl's X509 structure
6350 #
6351 # returns: no return value
6352 Check openssl doc
6354 <http://www.openssl.org/docs/crypto/X509_new.html>
6355 • X509_check_host
6357 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6359 requires at least OpenSSL 1.0.2.
6360 X509_CHECK_FLAG_NEVER_CHECK_SUBJECT requires OpenSSL 1.1.0.
6361 Checks if the certificate Subject Alternative Name (SAN) or Subject
6363 CommonName (CN) matches the specified host name.
6364 my $rv = Net::SSLeay::X509_check_host($cert, $name, $flags, $peername);
6366 # $cert - value corresponding to openssl's X509 structure
6367 # $name - host name to check
6368 # $flags (optional, default: 0) - can be the bitwise OR of:
6369 # &Net::SSLeay::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
6370 # &Net::SSLeay::X509_CHECK_FLAG_NO_WILDCARDS
6371 # &Net::SSLeay::X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
6372 # &Net::SSLeay::X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
6373 # &Net::SSLeay::X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
6374 # &Net::SSLeay::X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
6375 # $peername (optional) - If not omitted and $host matches $cert,
6376 # a copy of the matching SAN or CN from
6377 # the peer certificate is stored in $peername.
6378 #
6379 # returns:
6380 # 1 for a successful match
6381 # 0 for a failed match
6382 # -1 for an internal error
6383 # -2 if the input is malformed
6384 Check openssl doc
6386 <https://www.openssl.org/docs/crypto/X509_check_host.html>.
6387 • X509_check_email
6389 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6391 requires at least OpenSSL 1.0.2.
6392 Checks if the certificate matches the specified email address.
6394 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6396 # $cert - value corresponding to openssl's X509 structure
6397 # $address - email address to check
6398 # $flags (optional, default: 0) - see X509_check_host()
6399 #
6400 # returns: see X509_check_host()
6401 Check openssl doc
6403 <https://www.openssl.org/docs/crypto/X509_check_email.html>.
6404 • X509_check_ip
6406 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6408 requires at least OpenSSL 1.0.2.
6409 Checks if the certificate matches the specified IPv4 or IPv6
6411 address.
6412 my $rv = Net::SSLeay::X509_check_ip($cert, $address, $flags);
6414 # $cert - value corresponding to openssl's X509 structure
6415 # $address - IP address to check in binary format, in network byte order
6416 # $flags (optional, default: 0) - see X509_check_host()
6417 #
6418 # returns: see X509_check_host()
6419 Check openssl doc
6421 <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
6422 • X509_check_ip_asc
6424 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6426 requires at least OpenSSL 1.0.2.
6427 Checks if the certificate matches the specified IPv4 or IPv6
6429 address.
6430 my $rv = Net::SSLeay::X509_check_ip_asc($cert, $address, $flags);
6432 # $cert - value corresponding to openssl's X509 structure
6433 # $address - IP address to check in text representation
6434 # $flags (optional, default: 0) - see X509_check_host()
6435 #
6436 # returns: see X509_check_host()
6437 Check openssl doc
6439 <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
6440 • X509_certificate_type
6442 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6444 Returns bitmask with type of certificate $x.
6446 my $rv = Net::SSLeay::X509_certificate_type($x);
6448 # $x - value corresponding to openssl's X509 structure
6449 #
6450 # returns: (integer) bitmask with certificate type
6451 #to decode bitmask returned by this function use these constants:
6453 &Net::SSLeay::EVP_PKS_DSA
6454 &Net::SSLeay::EVP_PKS_EC
6455 &Net::SSLeay::EVP_PKS_RSA
6456 &Net::SSLeay::EVP_PKT_ENC
6457 &Net::SSLeay::EVP_PKT_EXCH
6458 &Net::SSLeay::EVP_PKT_EXP
6459 &Net::SSLeay::EVP_PKT_SIGN
6460 &Net::SSLeay::EVP_PK_DH
6461 &Net::SSLeay::EVP_PK_DSA
6462 &Net::SSLeay::EVP_PK_EC
6463 &Net::SSLeay::EVP_PK_RSA
6464 • X509_digest
6466 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6468 Computes digest/fingerprint of X509 $data using $type hash
6470 function.
6471 my $digest_value = Net::SSLeay::X509_digest($data, $type);
6473 # $data - value corresponding to openssl's X509 structure
6474 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6475 #
6476 # returns: hash value (binary)
6477 #to get printable (hex) value of digest use:
6479 print unpack('H*', $digest_value);
6480 • X509_issuer_and_serial_hash
6482 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6484 Sort of a checksum of issuer name and serial number of X509
6486 certificate $x. The result is not a full hash (e.g. sha-1), it is
6487 kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
6488 The resulting value might differ across different openssl versions
6489 for the same X509 certificate.
6490 my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
6492 # $x - value corresponding to openssl's X509 structure
6493 #
6494 # returns: number representing checksum
6495 • X509_issuer_name_hash
6497 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6499 Sort of a checksum of issuer name of X509 certificate $x. The
6501 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6502 truncated to the size of 'unsigned long' (32 bits). The resulting
6503 value might differ across different openssl versions for the same
6504 X509 certificate.
6505 my $rv = Net::SSLeay::X509_issuer_name_hash($x);
6507 # $x - value corresponding to openssl's X509 structure
6508 #
6509 # returns: number representing checksum
6510 • X509_subject_name_hash
6512 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6514 Sort of a checksum of subject name of X509 certificate $x. The
6516 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6517 truncated to the size of 'unsigned long' (32 bits). The resulting
6518 value might differ across different openssl versions for the same
6519 X509 certificate.
6520 my $rv = Net::SSLeay::X509_subject_name_hash($x);
6522 # $x - value corresponding to openssl's X509 structure
6523 #
6524 # returns: number representing checksum
6525 • X509_pubkey_digest
6527 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6529 requires at least openssl-0.9.7
6530 Computes digest/fingerprint of public key from X509 certificate
6532 $data using $type hash function.
6533 my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
6535 # $data - value corresponding to openssl's X509 structure
6536 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6537 #
6538 # returns: hash value (binary)
6539 #to get printable (hex) value of digest use:
6541 print unpack('H*', $digest_value);
6542 • X509_set_issuer_name
6544 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6546 Sets issuer of X509 certificate $x to $name.
6548 my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
6550 # $x - value corresponding to openssl's X509 structure
6551 # $name - value corresponding to openssl's X509_NAME structure
6552 #
6553 # returns: 1 on success, 0 on failure
6554 • X509_set_pubkey
6556 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6558 Sets public key of X509 certificate $x to $pkey.
6560 my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
6562 # $x - value corresponding to openssl's X509 structure
6563 # $pkey - value corresponding to openssl's EVP_PKEY structure
6564 #
6565 # returns: 1 on success, 0 on failure
6566 • X509_set_serialNumber
6568 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6570 Sets serial number of X509 certificate $x to $serial.
6572 my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
6574 # $x - value corresponding to openssl's X509 structure
6575 # $serial - value corresponding to openssl's ASN1_INTEGER structure
6576 #
6577 # returns: 1 on success, 0 on failure
6578 #to create $serial value use one of these:
6580 $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
6581 $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
6582 $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
6583 • X509_set_subject_name
6585 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6587 Sets subject of X509 certificate $x to $name.
6589 my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
6591 # $x - value corresponding to openssl's X509 structure
6592 # $name - value corresponding to openssl's X509_NAME structure
6593 #
6594 # returns: 1 on success, 0 on failure
6595 • X509_set_version
6597 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6599 Set 'version' value for X509 certificate $ to $version.
6601 my $rv = Net::SSLeay::X509_set_version($x, $version);
6603 # $x - value corresponding to openssl's X509 structure
6604 # $version - (integer) version number
6605 #
6606 # returns: 1 on success, 0 on failure
6607 • X509_sign
6609 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6611 Sign X509 certificate $x with private key $pkey (using digest
6613 algorithm $md).
6614 my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
6616 # $x - value corresponding to openssl's X509 structure
6617 # $pkey - value corresponding to openssl's EVP_PKEY structure
6618 # $md - value corresponding to openssl's EVP_MD structure
6619 #
6620 # returns: 1 on success, 0 on failure
6621 • X509_verify
6623 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6625 Verifies X509 object $a using public key $r (pubkey of issuing CA).
6627 my $rv = Net::SSLeay::X509_verify($x, $r);
6629 # $x - value corresponding to openssl's X509 structure
6630 # $r - value corresponding to openssl's EVP_PKEY structure
6631 #
6632 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6633 • X509_get_ext_count
6635 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6637 Returns the total number of extensions in X509 object $x.
6639 my $rv = Net::SSLeay::X509_get_ext_count($x);
6641 # $x - value corresponding to openssl's X509 structure
6642 #
6643 # returns: count of extensions
6644 • X509_get_pubkey
6646 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6648 Returns public key corresponding to given X509 object $x.
6650 my $rv = Net::SSLeay::X509_get_pubkey($x);
6652 # $x - value corresponding to openssl's X509 structure
6653 #
6654 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6655 NOTE: This method returns only the public key's key bits, without
6657 the algorithm or parameters. Use "X509_get_X509_PUBKEY()" to
6658 return the full public key (SPKI) instead.
6659 • X509_get_X509_PUBKEY
6661 COMPATIBILITY: not available in Net-SSLeay-1.72 and before
6663 Returns the full public key (SPKI) of given X509 certificate $x.
6665 Net::SSLeay::X509_get_X509_PUBKEY($x);
6667 # $x - value corresponding to openssl's X509 structure
6668 #
6669 # returns: public key data in DER format (binary)
6670 • X509_get_serialNumber
6672 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6674 Returns serial number of X509 certificate $x.
6676 my $rv = Net::SSLeay::X509_get_serialNumber($x);
6678 # $x - value corresponding to openssl's X509 structure
6679 #
6680 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6681 See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
6683 "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
6684 • X509_get0_serialNumber
6686 COMPATIBILITY: available in Net-SSLeay-1.86 onwards
6688 X509_get0_serialNumber() is the same as X509_get_serialNumber()
6690 except it accepts a const parameter and returns a const result.
6691 • X509_get_version
6693 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6695 Returns 'version' value of given X509 certificate $x.
6697 my $rv = Net::SSLeay::X509_get_version($x);
6699 # $x - value corresponding to openssl's X509 structure
6700 #
6701 # returns: (integer) version
6702 • X509_get_ext
6704 Returns X509_EXTENSION from $x509 based on given position/index.
6706 my $rv = Net::SSLeay::X509_get_ext($x509, $index);
6708 # $x509 - value corresponding to openssl's X509 structure
6709 # $index - (integer) position/index of extension within $x509
6710 #
6711 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6712 • X509_get_ext_by_NID
6714 Returns X509_EXTENSION from $x509 based on given NID.
6716 my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
6718 # $x509 - value corresponding to openssl's X509 structure
6719 # $nid - (integer) NID value
6720 # $loc - (integer) position to start lookup at
6721 #
6722 # returns: position/index of extension, negative value on error
6723 # call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
6724 • X509_get_fingerprint
6726 Returns fingerprint of certificate $cert.
6728 NOTE: Does not exactly correspond to any low level API function.
6730 The implementation is based on openssl's "X509_digest()".
6731 Net::SSLeay::X509_get_fingerprint($x509, $type);
6733 # $x509 - value corresponding to openssl's X509 structure
6734 # $type - (string) digest type, currently supported values:
6735 # "md5"
6736 # "sha1"
6737 # "sha256"
6738 # "ripemd160"
6739 #
6740 # returns: certificate digest - hexadecimal string (NOT binary data!)
6741 • X509_get_issuer_name
6743 Return an X509_NAME object representing the issuer of the
6745 certificate $cert.
6746 my $rv = Net::SSLeay::X509_get_issuer_name($cert);
6748 # $cert - value corresponding to openssl's X509 structure
6749 #
6750 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6751 • X509_get_notAfter
6753 Return an object giving the time after which the certificate $cert
6755 is not valid.
6756 my $rv = Net::SSLeay::X509_get_notAfter($cert);
6758 # $cert - value corresponding to openssl's X509 structure
6759 #
6760 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6761 To get human readable/printable form the return value you can use:
6763 my $time = Net::SSLeay::X509_get_notAfter($cert);
6765 print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6766 • X509_get_notBefore
6768 Return an object giving the time before which the certificate $cert
6770 is not valid
6771 my $rv = Net::SSLeay::X509_get_notBefore($cert);
6773 # $cert - value corresponding to openssl's X509 structure
6774 #
6775 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6776 To get human readable/printable form the return value you can use:
6778 my $time = Net::SSLeay::X509_get_notBefore($cert);
6780 print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6781 • X509_get_subjectAltNames
6783 NOTE: Does not exactly correspond to any low level API function.
6785 Returns the list of alternative subject names from X509 certificate
6787 $cert.
6788 my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
6790 # $cert - value corresponding to openssl's X509 structure
6791 #
6792 # returns: list containing pairs - name_type (integer), name_value (string)
6793 # where name_type can be:
6794 # 0 - GEN_OTHERNAME
6795 # 1 - GEN_EMAIL
6796 # 2 - GEN_DNS
6797 # 3 - GEN_X400
6798 # 4 - GEN_DIRNAME
6799 # 5 - GEN_EDIPARTY
6800 # 6 - GEN_URI
6801 # 7 - GEN_IPADD
6802 # 8 - GEN_RID
6803 Note: type 7 - GEN_IPADD contains the IP address as a packed binary
6805 address. GEN_RID is available in Net-SSLeay-1.90 and later. Maximum
6806 length for returned RID string is currently 2500. Invalid and
6807 overly long RID values are skipped and not returned. GEN_X400 and
6808 GEN_EDIPARTY are not supported and will not be returned even when
6809 present in the certificate.
6810 • X509_get_subject_name
6812 Returns the subject of the certificate $cert.
6814 my $rv = Net::SSLeay::X509_get_subject_name($cert);
6816 # $cert - value corresponding to openssl's X509 structure
6817 #
6818 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6819 • X509_gmtime_adj
6821 Adjust th ASN1_TIME object to the timestamp (in GMT).
6823 my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
6825 # $s - value corresponding to openssl's ASN1_TIME structure
6826 # $adj - timestamp (seconds since 1.1.1970)
6827 #
6828 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6829 BEWARE: this function may fail for dates after 2038 as it is
6831 dependent on time_t size on your system (32bit time_t does not work
6832 after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
6833 • X509_load_cert_crl_file
6835 Takes PEM file and loads all X509 certificates and X509 CRLs from
6837 that file into X509_LOOKUP structure.
6838 my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
6840 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6841 # $file - (string) file name
6842 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6843 # if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
6844 #
6845 # returns: 1 on success, 0 on failure
6846 • X509_load_cert_file
6848 Loads/adds X509 certificate from $file to X509_LOOKUP structure
6850 my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
6852 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6853 # $file - (string) file name
6854 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6855 #
6856 # returns: 1 on success, 0 on failure
6857 • X509_load_crl_file
6859 Loads/adds X509 CRL from $file to X509_LOOKUP structure
6861 my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
6863 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6864 # $file - (string) file name
6865 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6866 #
6867 # returns: 1 on success, 0 on failure
6868 • X509_policy_level_get0_node
6870 ??? (more info needed)
6872 my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
6874 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6875 # $i - (integer) index/position
6876 #
6877 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6878 • X509_policy_level_node_count
6880 ??? (more info needed)
6882 my $rv = Net::SSLeay::X509_policy_level_node_count($level);
6884 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6885 #
6886 # returns: (integer) node count
6887 • X509_policy_node_get0_parent
6889 ??? (more info needed)
6891 my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
6893 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6894 #
6895 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6896 • X509_policy_node_get0_policy
6898 ??? (more info needed)
6900 my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
6902 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6903 #
6904 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6905 • X509_policy_node_get0_qualifiers
6907 ??? (more info needed)
6909 my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
6911 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6912 #
6913 # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
6914 • X509_policy_tree_free
6916 ??? (more info needed)
6918 Net::SSLeay::X509_policy_tree_free($tree);
6920 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6921 #
6922 # returns: no return value
6923 • X509_policy_tree_get0_level
6925 ??? (more info needed)
6927 my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
6929 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6930 # $i - (integer) level index
6931 #
6932 # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
6933 • X509_policy_tree_get0_policies
6935 ??? (more info needed)
6937 my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
6939 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6940 #
6941 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6942 • X509_policy_tree_get0_user_policies
6944 ??? (more info needed)
6946 my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
6948 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6949 #
6950 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6951 • X509_policy_tree_level_count
6953 ??? (more info needed)
6955 my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
6957 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6958 #
6959 # returns: (integer) count
6960 • X509_verify_cert_error_string
6962 Returns a human readable error string for verification error $n.
6964 my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6966 # $n - (long) numeric error code
6967 #
6968 # returns: error string
6969 Check openssl doc
6971 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6972 • P_X509_add_extensions
6974 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6976 Adds one or more X509 extensions to X509 object $x.
6978 my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
6980 # $x - value corresponding to openssl's X509 structure
6981 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
6982 # $nid - NID identifying extension to be set
6983 # $value - extension value
6984 #
6985 # returns: 1 on success, 0 on failure
6986 You can set more extensions at once:
6988 my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
6990 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6991 &Net::SSLeay::NID_subject_key_identifier => 'hash',
6992 &Net::SSLeay::NID_authority_key_identifier => 'keyid',
6993 &Net::SSLeay::NID_authority_key_identifier => 'issuer',
6994 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6995 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6996 &Net::SSLeay::NID_netscape_cert_type => 'server',
6997 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
6998 );
6999 • P_X509_copy_extensions
7001 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7003 Copies X509 extensions from X509_REQ object to X509 object - handy
7005 when you need to turn X509_REQ into X509 certificate.
7006 Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
7008 # $x509_req - value corresponding to openssl's X509_REQ structure
7009 # $x509 - value corresponding to openssl's X509 structure
7010 # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
7011 #
7012 # returns: 1 on success, 0 on failure
7013 • P_X509_get_crl_distribution_points
7015 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7017 requires at least openssl-0.9.7
7018 Get the list of CRL distribution points from X509 certificate.
7020 my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
7022 # $x509 - value corresponding to openssl's X509 structure
7023 #
7024 # returns: list of distribution points (usually URLs)
7025 • P_X509_get_ext_key_usage
7027 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7029 requires at least openssl-0.9.7
7030 Gets the list of extended key usage of given X509 certificate
7032 $cert.
7033 my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
7035 # $cert - value corresponding to openssl's X509 structure
7036 # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
7037 #
7038 # returns: list of values
7039 Examples:
7041 my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
7043 # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
7044 my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
7046 # returns for example: (129, 130)
7047 my @extkeyusage_sn = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
7049 # returns for example: ("serverAuth", "clientAuth")
7050 my @extkeyusage_ln = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
7052 # returns for example: ("TLS Web Server Authentication", "TLS Web Client Authentication")
7053 • P_X509_get_key_usage
7055 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7057 Gets the list of key usage of given X509 certificate $cert.
7059 my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
7061 # $cert - value corresponding to openssl's X509 structure
7062 #
7063 # returns: list of key usage values which can be none, one or more from the following list:
7064 # "digitalSignature"
7065 # "nonRepudiation"
7066 # "keyEncipherment"
7067 # "dataEncipherment"
7068 # "keyAgreement"
7069 # "keyCertSign"
7070 # "cRLSign"
7071 # "encipherOnly"
7072 # "decipherOnly"
7073 • P_X509_get_netscape_cert_type
7075 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7077 Gets the list of Netscape cert types of given X509 certificate
7079 $cert.
7080 Net::SSLeay::P_X509_get_netscape_cert_type($cert);
7082 # $cert - value corresponding to openssl's X509 structure
7083 #
7084 # returns: list of Netscape type values which can be none, one or more from the following list:
7085 # "client"
7086 # "server"
7087 # "email"
7088 # "objsign"
7089 # "reserved"
7090 # "sslCA"
7091 # "emailCA"
7092 # "objCA"
7093 • P_X509_get_pubkey_alg
7095 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7097 Returns ASN1_OBJECT corresponding to X509 certificate public key
7099 algorithm.
7100 my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
7102 # $x - value corresponding to openssl's X509 structure
7103 #
7104 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7105 To get textual representation use:
7107 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
7109 # returns for example: "rsaEncryption"
7110 • P_X509_get_signature_alg
7112 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7114 Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
7116 my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
7118 # $x - value corresponding to openssl's X509 structure
7119 #
7120 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7121 To get textual representation use:
7123 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
7125 # returns for example: "sha1WithRSAEncryption"
7126 • sk_X509_new_null
7128 Returns a new, empty, STACK_OF(X509) structure.
7130 my $rv = Net::SSLeay::sk_X509_new_null();
7132 #
7133 # returns: value corresponding to openssl's STACK_OF(X509) structure
7134 • sk_X509_push
7136 Pushes an X509 structure onto a STACK_OF(X509) structure.
7138 my $rv = Net::SSLeay::sk_X509_push($sk_x509, $x509);
7140 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7141 # $x509 - value corresponding to openssl's X509 structure
7142 #
7143 # returns: total number of elements after the operation, 0 on failure
7144 • sk_X509_pop
7146 Pops an single X509 structure from a STACK_OF(X509) structure.
7148 my $x509 = NetSSLeay::sk_X509_pop($sk_x509)
7150 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7151 #
7152 # returns: a pointer to an X509 structure, undef on failure
7153 Check openssl doc
7155 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_pop.html>
7156 • sk_X509_shift
7158 Shifts an single X509 structure onto a STACK_OF(X509) structure.
7160 my $x509 = NetSSLeay::sk_X509_shift($sk_x509, $x509)
7162 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7163 # $x509 - value corresponding to openssl's X509 structure
7164 #
7165 # returns: a pointer to an X509 structure, undef on failure
7166 Check openssl doc
7168 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_shift.html>
7169 • sk_X509_unshift
7171 Unshifts an single X509 structure from a STACK_OF(X509) structure.
7173 my $rv = NetSSLeay::sk_X509_unshift($sk_x509)
7175 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7176 #
7177 # returns: total number of elements after the operation, 0 on failure
7178 Check openssl doc
7180 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_unshift.html>
7181 • sk_X509_insert
7183 Inserts a single X509 structure into a STACK_OF(X509) at the
7185 specified index.
7186 my $rv = Net::SSLeay::sk_X509_insert($sk_x509, $x509, index);
7188 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7189 # $x509 - value corresponding to openssl's X509 structure
7190 # index - integer - 0 based index
7191 #
7192 # returns: total number of elements after the operation, 0 on failure
7193 Check openssl doc
7195 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_insert.html>
7196 • sk_X509_delete
7198 Delete a single X509 structure from a STACK_OF(X509) at the
7200 specified index.
7201 my $x509 = Net::SSLeay::sk_X509_delete($sk_x509, index);
7203 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7204 # index - integer - 0 based index
7205 #
7206 # returns: a pointer to an X509 structure, undef on failure
7207 Check openssl doc
7209 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_delete.html>
7210 • sk_X509_value
7212 Return a single X509 structure from a STACK_OF(X509) at the
7214 specified index.
7215 my $x509 = Net::SSLeay::sk_X509_value($sk_x509, index)
7217 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7218 # index - integer - 0 based index
7219 #
7220 # returns: a pointer to an X509 structure, undef on failure
7221 Check openssl doc
7223 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_value.html>
7224 • sk_X509_num
7226 Return the number of X509 elements in a STACK_OF(X509).
7228 my $num = Net::SSLeay::sk_X509_num($sk_x509);
7230 # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
7231 #
7232 # returns: the number of elements in the stack, -1 if the passed stack is NULL
7233 Check openssl doc
7235 <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_num.html>
7236 Low level API: X509_REQ_* related functions
7238 • X509_REQ_new
7240 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7242 Creates a new X509_REQ structure.
7244 my $rv = Net::SSLeay::X509_REQ_new();
7246 #
7247 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
7248 • X509_REQ_free
7250 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7252 Free an allocated X509_REQ structure.
7254 Net::SSLeay::X509_REQ_free($x);
7256 # $x - value corresponding to openssl's X509_REQ structure
7257 #
7258 # returns: no return value
7259 • X509_REQ_add1_attr_by_NID
7261 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7263 Adds an attribute whose name is defined by a NID $nid. The field
7265 value to be added is in $bytes.
7266 my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
7268 # $req - value corresponding to openssl's X509_REQ structure
7269 # $nid - (integer) NID value
7270 # $type - (integer) type of data in $bytes (see below)
7271 # $bytes - data to be set
7272 #
7273 # returns: 1 on success, 0 on failure
7274 # values for $type - use constants:
7276 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7277 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7278 • X509_REQ_digest
7280 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7282 Computes digest/fingerprint of X509_REQ $data using $type hash
7284 function.
7285 my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
7287 # $data - value corresponding to openssl's X509_REQ structure
7288 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7289 #
7290 # returns: hash value (binary)
7291 #to get printable (hex) value of digest use:
7293 print unpack('H*', $digest_value);
7294 • X509_REQ_get_attr_by_NID
7296 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7298 Retrieve the next index matching $nid after $lastpos ($lastpos
7300 should initially be set to -1).
7301 my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
7303 # $req - value corresponding to openssl's X509_REQ structure
7304 # $nid - (integer) NID value
7305 # $lastpos - [optional] (integer) index where to start search (default -1)
7306 #
7307 # returns: index (-1 if there are no more entries)
7308 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7310 e.g.
7311 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
7313 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
7314 • X509_REQ_get_attr_by_OBJ
7316 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7318 Retrieve the next index matching $obj after $lastpos ($lastpos
7320 should initially be set to -1).
7321 my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
7323 # $req - value corresponding to openssl's X509_REQ structure
7324 # $obj - value corresponding to openssl's ASN1_OBJECT structure
7325 # $lastpos - [optional] (integer) index where to start search (default -1)
7326 #
7327 # returns: index (-1 if there are no more entries)
7328 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7330 e.g.
7331 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
7333 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
7334 • X509_REQ_get_attr_count
7336 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7338 Returns the total number of attributes in $req.
7340 my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
7342 # $req - value corresponding to openssl's X509_REQ structure
7343 #
7344 # returns: (integer) items count
7345 • X509_REQ_get_pubkey
7347 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7349 Returns public key corresponding to given X509_REQ object $x.
7351 my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
7353 # $x - value corresponding to openssl's X509_REQ structure
7354 #
7355 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
7356 • X509_REQ_get_subject_name
7358 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7360 Returns X509_NAME object corresponding to subject name of given
7362 X509_REQ object $x.
7363 my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
7365 # $x - value corresponding to openssl's X509_REQ structure
7366 #
7367 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7368 • X509_REQ_get_version
7370 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7372 Returns 'version' value for given X509_REQ object $x.
7374 my $rv = Net::SSLeay::X509_REQ_get_version($x);
7376 # $x - value corresponding to openssl's X509_REQ structure
7377 #
7378 # returns: (integer) version e.g. 0 = "version 1"
7379 • X509_REQ_set_pubkey
7381 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7383 Sets public key of given X509_REQ object $x to $pkey.
7385 my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
7387 # $x - value corresponding to openssl's X509_REQ structure
7388 # $pkey - value corresponding to openssl's EVP_PKEY structure
7389 #
7390 # returns: 1 on success, 0 on failure
7391 • X509_REQ_set_subject_name
7393 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7395 Sets subject name of given X509_REQ object $x to X509_NAME object
7397 $name.
7398 my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
7400 # $x - value corresponding to openssl's X509_REQ structure
7401 # $name - value corresponding to openssl's X509_NAME structure
7402 #
7403 # returns: 1 on success, 0 on failure
7404 • X509_REQ_set_version
7406 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7408 Sets 'version' of given X509_REQ object $x to $version.
7410 my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
7412 # $x - value corresponding to openssl's X509_REQ structure
7413 # $version - (integer) e.g. 0 = "version 1"
7414 #
7415 # returns: 1 on success, 0 on failure
7416 • X509_REQ_sign
7418 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7420 Sign X509_REQ object $x with private key $pk (using digest
7422 algorithm $md).
7423 my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
7425 # $x - value corresponding to openssl's X509_REQ structure
7426 # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
7427 # $md - value corresponding to openssl's EVP_MD structure
7428 #
7429 # returns: 1 on success, 0 on failure
7430 • X509_REQ_verify
7432 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7434 Verifies X509_REQ object $x using public key $r (pubkey of
7436 requesting party).
7437 my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
7439 # $x - value corresponding to openssl's X509_REQ structure
7440 # $r - value corresponding to openssl's EVP_PKEY structure
7441 #
7442 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7443 • P_X509_REQ_add_extensions
7445 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7447 Adds one or more X509 extensions to X509_REQ object $x.
7449 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
7451 # $x - value corresponding to openssl's X509_REQ structure
7452 # $nid - NID identifying extension to be set
7453 # $value - extension value
7454 #
7455 # returns: 1 on success, 0 on failure
7456 You can set more extensions at once:
7458 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
7460 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
7461 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
7462 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
7463 &Net::SSLeay::NID_netscape_cert_type => 'server',
7464 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
7465 &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
7466 );
7467 • P_X509_REQ_get_attr
7469 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7471 requires at least openssl-0.9.7
7472 Returns attribute value for X509_REQ's attribute at index $n.
7474 Net::SSLeay::P_X509_REQ_get_attr($req, $n);
7476 # $req - value corresponding to openssl's X509_REQ structure
7477 # $n - (integer) attribute index
7478 #
7479 # returns: value corresponding to openssl's ASN1_STRING structure
7480 Low level API: X509_CRL_* related functions
7482 • X509_CRL_new
7484 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7486 Creates a new X509_CRL structure.
7488 my $rv = Net::SSLeay::X509_CRL_new();
7490 #
7491 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
7492 • X509_CRL_free
7494 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7496 Free an allocated X509_CRL structure.
7498 Net::SSLeay::X509_CRL_free($x);
7500 # $x - value corresponding to openssl's X509_CRL structure
7501 #
7502 # returns: no return value
7503 • X509_CRL_digest
7505 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7507 Computes digest/fingerprint of X509_CRL $data using $type hash
7509 function.
7510 my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
7512 # $data - value corresponding to openssl's X509_CRL structure
7513 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7514 #
7515 # returns: hash value (binary)
7516 Example:
7518 my $x509_crl
7520 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7521 my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
7522 #to get printable (hex) value of digest use:
7523 print "digest=", unpack('H*', $digest_value), "\n";
7524 • X509_CRL_get_ext
7526 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7528 Returns X509_EXTENSION from $x509 based on given position/index.
7530 my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
7532 # $x509 - value corresponding to openssl's X509_CRL structure
7533 # $index - (integer) position/index of extension within $x509
7534 #
7535 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
7536 • X509_CRL_get_ext_by_NID
7538 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7540 Returns X509_EXTENSION from $x509 based on given NID.
7542 my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
7544 # $x509 - value corresponding to openssl's X509_CRL structure
7545 # $nid - (integer) NID value
7546 # $loc - (integer) position to start lookup at
7547 #
7548 # returns: position/index of extension, negative value on error
7549 # call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
7550 • X509_CRL_get_ext_count
7552 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7554 Returns the total number of extensions in X509_CRL object $x.
7556 my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
7558 # $x - value corresponding to openssl's X509_CRL structure
7559 #
7560 # returns: count of extensions
7561 • X509_CRL_get_issuer
7563 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7565 Returns X509_NAME object corresponding to the issuer of X509_CRL
7567 $x.
7568 my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
7570 # $x - value corresponding to openssl's X509_CRL structure
7571 #
7572 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7573 See other "X509_NAME_*" functions to get more info from X509_NAME
7575 structure.
7576 • X509_CRL_get_lastUpdate
7578 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7580 Returns 'lastUpdate' date-time value of X509_CRL object $x.
7582 my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
7584 # $x - value corresponding to openssl's X509_CRL structure
7585 #
7586 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7587 • X509_CRL_get_nextUpdate
7589 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7591 Returns 'nextUpdate' date-time value of X509_CRL object $x.
7593 my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
7595 # $x - value corresponding to openssl's X509_CRL structure
7596 #
7597 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7598 • X509_CRL_get_version
7600 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7602 Returns 'version' value of given X509_CRL structure $x.
7604 my $rv = Net::SSLeay::X509_CRL_get_version($x);
7606 # $x - value corresponding to openssl's X509_CRL structure
7607 #
7608 # returns: (integer) version
7609 • X509_CRL_set_issuer_name
7611 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7613 requires at least openssl-0.9.7
7614 Sets the issuer of X509_CRL object $x to X509_NAME object $name.
7616 my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
7618 # $x - value corresponding to openssl's X509_CRL structure
7619 # $name - value corresponding to openssl's X509_NAME structure
7620 #
7621 # returns: 1 on success, 0 on failure
7622 • X509_CRL_set_lastUpdate
7624 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7626 requires at least openssl-0.9.7
7627 Sets 'lastUpdate' value of X509_CRL object $x to $tm.
7629 my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
7631 # $x - value corresponding to openssl's X509_CRL structure
7632 # $tm - value corresponding to openssl's ASN1_TIME structure
7633 #
7634 # returns: 1 on success, 0 on failure
7635 • X509_CRL_set_nextUpdate
7637 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7639 requires at least openssl-0.9.7
7640 Sets 'nextUpdate' value of X509_CRL object $x to $tm.
7642 my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
7644 # $x - value corresponding to openssl's X509_CRL structure
7645 # $tm - value corresponding to openssl's ASN1_TIME structure
7646 #
7647 # returns: 1 on success, 0 on failure
7648 • X509_CRL_set_version
7650 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7652 requires at least openssl-0.9.7
7653 Sets 'version' value of given X509_CRL structure $x to $version.
7655 my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
7657 # $x - value corresponding to openssl's X509_CRL structure
7658 # $version - (integer) version number (1 = version 2 CRL)
7659 #
7660 # returns: 1 on success, 0 on failure
7661 Note that if you want to use any X509_CRL extension you need to set
7663 "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
7664 • X509_CRL_sign
7666 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7668 Sign X509_CRL object $x with private key $pkey (using digest
7670 algorithm $md).
7671 my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
7673 # $x - value corresponding to openssl's X509_CRL structure
7674 # $pkey - value corresponding to openssl's EVP_PKEY structure
7675 # $md - value corresponding to openssl's EVP_MD structure
7676 #
7677 # returns: 1 on success, 0 on failure
7678 • X509_CRL_sort
7680 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7682 requires at least openssl-0.9.7
7683 Sorts the data of X509_CRL object so it will be written in serial
7685 number order.
7686 my $rv = Net::SSLeay::X509_CRL_sort($x);
7688 # $x - value corresponding to openssl's X509_CRL structure
7689 #
7690 # returns: 1 on success, 0 on failure
7691 • X509_CRL_verify
7693 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7695 Verifies X509_CRL object $a using public key $r (pubkey of issuing
7697 CA).
7698 my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
7700 # $a - value corresponding to openssl's X509_CRL structure
7701 # $r - value corresponding to openssl's EVP_PKEY structure
7702 #
7703 # returns: 0 - verify failure, 1 - verify OK, <0 - error
7704 • P_X509_CRL_add_revoked_serial_hex
7706 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7708 requires at least openssl-0.9.7
7709 Adds given serial number $serial_hex to X509_CRL object $crl.
7711 Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
7713 # $crl - value corresponding to openssl's X509_CRL structure
7714 # $serial_hex - string (hexadecimal) representation of serial number
7715 # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
7716 # $reason_code - [optional] (integer) reason code (see below) - default 0
7717 # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
7718 #
7719 # returns: no return value
7720 reason codes:
7722 0 - unspecified
7723 1 - keyCompromise
7724 2 - CACompromise
7725 3 - affiliationChanged
7726 4 - superseded
7727 5 - cessationOfOperation
7728 6 - certificateHold
7729 7 - removeFromCRL
7730 • P_X509_CRL_get_serial
7732 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7734 requires at least openssl-0.9.7
7735 Returns serial number of X509_CRL object.
7737 my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
7739 # $crl - value corresponding to openssl's X509_CRL structure
7740 #
7741 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
7742 • P_X509_CRL_set_serial
7744 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7746 requires at least openssl-0.9.7
7747 Sets serial number of X509_CRL object to $crl_number.
7749 my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
7751 # $crl - value corresponding to openssl's X509_CRL structure
7752 # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
7753 #
7754 # returns: 1 on success, 0 on failure
7755 • P_X509_CRL_add_extensions
7757 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
7759 Adds one or more X509 extensions to X509 CRL object $x.
7761 my $rv = Net::SSLeay::P_X509_CRL_add_extensions($x, $ca_cert, $nid, $value);
7763 # $x - value corresponding to openssl's X509 CRL structure
7764 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
7765 # $nid - NID identifying extension to be set
7766 # $value - extension value
7767 #
7768 # returns: 1 on success, 0 on failure
7769 For more details see "P_X509_add_extensions".
7771 Low level API: X509_EXTENSION_* related functions
7773 • X509_EXTENSION_get_critical
7775 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7777 Returns 'critical' flag of given X509_EXTENSION object $ex.
7779 my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
7781 # $ex - value corresponding to openssl's X509_EXTENSION structure
7782 #
7783 # returns: (integer) 1 - critical, 0 - noncritical
7784 • X509_EXTENSION_get_data
7786 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7788 Returns value (raw data) of X509_EXTENSION object $ne.
7790 my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
7792 # $ne - value corresponding to openssl's X509_EXTENSION structure
7793 #
7794 # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
7795 Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
7797 into perl scalar variable.
7798 • X509_EXTENSION_get_object
7800 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7802 Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
7804 my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
7806 # $ex - value corresponding to openssl's X509_EXTENSION structure
7807 #
7808 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7809 • X509V3_EXT_print
7811 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7813 Returns string representation of given X509_EXTENSION object $ext.
7815 Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
7817 # $ext - value corresponding to openssl's X509_EXTENSION structure
7818 # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
7819 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7820 #
7821 # returns: no return value
7822 • X509V3_EXT_d2i
7824 Parses an extension and returns its internal structure.
7826 my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
7828 # $ext - value corresponding to openssl's X509_EXTENSION structure
7829 #
7830 # returns: pointer ???
7831 Low level API: X509_NAME_* related functions
7833 • X509_NAME_ENTRY_get_data
7835 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7837 Retrieves the field value of $ne in and ASN1_STRING structure.
7839 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
7841 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7842 #
7843 # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
7844 Check openssl doc
7846 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7847 • X509_NAME_ENTRY_get_object
7849 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7851 Retrieves the field name of $ne in and ASN1_OBJECT structure.
7853 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
7855 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7856 #
7857 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7858 Check openssl doc
7860 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7861 • X509_NAME_new
7863 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7865 requires at least openssl-0.9.5
7866 Creates a new X509_NAME structure. Adds a field whose name is
7868 defined by a string $field. The field value to be added is in
7869 $bytes.
7870 my $rv = Net::SSLeay::X509_NAME_new();
7872 #
7873 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7874 • X509_NAME_hash
7876 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7878 requires at least openssl-0.9.5
7879 Sort of a checksum of issuer name $name. The result is not a full
7881 hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
7882 'unsigned long' (32 bits). The resulting value might differ across
7883 different openssl versions for the same X509 certificate.
7884 my $rv = Net::SSLeay::X509_NAME_hash($name);
7886 # $name - value corresponding to openssl's X509_NAME structure
7887 #
7888 # returns: number representing checksum
7889 • X509_NAME_add_entry_by_txt
7891 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7893 requires at least openssl-0.9.5
7894 Adds a field whose name is defined by a string $field. The field
7896 value to be added is in $bytes.
7897 my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
7899 # $name - value corresponding to openssl's X509_NAME structure
7900 # $field - (string) field definition (name) - e.g. "organizationName"
7901 # $type - (integer) type of data in $bytes (see below)
7902 # $bytes - data to be set
7903 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7904 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7905 #
7906 # returns: 1 on success, 0 on failure
7907 # values for $type - use constants:
7909 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7910 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7911 Unicode note: when passing non-ascii (unicode) string in $bytes do
7913 not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
7914 the perl $string via "$bytes = encode('utf-8', $string)".
7915 Check openssl doc
7917 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7918 • X509_NAME_add_entry_by_NID
7920 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7922 requires at least openssl-0.9.5
7923 Adds a field whose name is defined by a NID $nid. The field value
7925 to be added is in $bytes.
7926 my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
7928 # $name - value corresponding to openssl's X509_NAME structure
7929 # $nid - (integer) field definition - NID value
7930 # $type - (integer) type of data in $bytes (see below)
7931 # $bytes - data to be set
7932 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7933 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7934 #
7935 # returns: 1 on success, 0 on failure
7936 Check openssl doc
7938 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7939 • X509_NAME_add_entry_by_OBJ
7941 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7943 requires at least openssl-0.9.5
7944 Adds a field whose name is defined by a object (OID) $obj . The
7946 field value to be added is in $bytes.
7947 my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
7949 # $name - value corresponding to openssl's X509_NAME structure
7950 # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
7951 # $type - (integer) type of data in $bytes (see below)
7952 # $bytes - data to be set
7953 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7954 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7955 #
7956 # returns: 1 on success, 0 on failure
7957 Check openssl doc
7959 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7960 • X509_NAME_cmp
7962 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7964 Compares two X509_NAME obejcts.
7966 my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
7968 # $a - value corresponding to openssl's X509_NAME structure
7969 # $b - value corresponding to openssl's X509_NAME structure
7970 #
7971 # returns: 0 if $a matches $b; non zero otherwise
7972 • X509_NAME_digest
7974 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7976 Computes digest/fingerprint of X509_NAME $data using $type hash
7978 function.
7979 my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
7981 # $data - value corresponding to openssl's X509_NAME structure
7982 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7983 #
7984 # returns: hash value (binary)
7985 #to get printable (hex) value of digest use:
7987 print unpack('H*', $digest_value);
7988 • X509_NAME_entry_count
7990 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7992 Returns the total number of entries in $name.
7994 my $rv = Net::SSLeay::X509_NAME_entry_count($name);
7996 # $name - value corresponding to openssl's X509_NAME structure
7997 #
7998 # returns: (integer) entries count
7999 Check openssl doc
8001 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8002 • X509_NAME_get_entry
8004 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8006 Retrieves the X509_NAME_ENTRY from $name corresponding to index
8008 $loc. Acceptable values for $loc run from 0 to
8009 "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
8010 is an internal pointer which must not be freed.
8011 my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
8013 # $name - value corresponding to openssl's X509_NAME structure
8014 # $loc - (integer) index of wanted entry
8015 #
8016 # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
8017 Check openssl doc
8019 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8020 • X509_NAME_print_ex
8022 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8024 Returns a string with human readable version of $name.
8026 Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
8028 # $name - value corresponding to openssl's X509_NAME structure
8029 # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
8030 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
8031 #
8032 # returns: string representation of $name
8033 #available conversion flags - use constants:
8035 &Net::SSLeay::XN_FLAG_COMPAT
8036 &Net::SSLeay::XN_FLAG_DN_REV
8037 &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
8038 &Net::SSLeay::XN_FLAG_FN_ALIGN
8039 &Net::SSLeay::XN_FLAG_FN_LN
8040 &Net::SSLeay::XN_FLAG_FN_MASK
8041 &Net::SSLeay::XN_FLAG_FN_NONE
8042 &Net::SSLeay::XN_FLAG_FN_OID
8043 &Net::SSLeay::XN_FLAG_FN_SN
8044 &Net::SSLeay::XN_FLAG_MULTILINE
8045 &Net::SSLeay::XN_FLAG_ONELINE
8046 &Net::SSLeay::XN_FLAG_RFC2253
8047 &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
8048 &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
8049 &Net::SSLeay::XN_FLAG_SEP_MASK
8050 &Net::SSLeay::XN_FLAG_SEP_MULTILINE
8051 &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
8052 &Net::SSLeay::XN_FLAG_SPC_EQ
8053 Most likely you will be fine with default:
8055 Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
8057 Or you might want RFC2253-like output without utf8 chars escaping:
8059 use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
8061 my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
8062 my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
8063 Check openssl doc
8065 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8066 • X509_NAME_get_text_by_NID
8068 Retrieves the text from the first entry in name which matches $nid,
8070 if no such entry exists -1 is returned.
8071 openssl note: this is a legacy function which has various
8073 limitations which makes it of minimal use in practice. It can only
8074 find the first matching entry and will copy the contents of the
8075 field verbatim: this can be highly confusing if the target is a
8076 multicharacter string type like a BMPString or a UTF8String.
8077 Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
8079 # $name - value corresponding to openssl's X509_NAME structure
8080 # $nid - NID value (integer)
8081 #
8082 # returns: text value
8083 Check openssl doc
8085 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8086 • X509_NAME_oneline
8088 Return an ASCII version of $name.
8090 Net::SSLeay::X509_NAME_oneline($name);
8092 # $name - value corresponding to openssl's X509_NAME structure
8093 #
8094 # returns: (string) ASCII version of $name
8095 Check openssl doc
8097 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8098 • sk_X509_NAME_free
8100 Free an allocated STACK_OF(X509_NAME) structure.
8102 Net::SSLeay::sk_X509_NAME_free($sk);
8104 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8105 #
8106 # returns: no return value
8107 • sk_X509_NAME_num
8109 Return number of items in STACK_OF(X509_NAME)
8111 my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
8113 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8114 #
8115 # returns: number of items
8116 • sk_X509_NAME_value
8118 Returns X509_NAME from position $index in STACK_OF(X509_NAME)
8120 my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
8122 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
8123 # $i - (integer) index/position
8124 #
8125 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
8126 • add_file_cert_subjects_to_stack
8128 Add a file of certs to a stack. All certs in $file that are not
8130 already in the $stackCAs will be added.
8131 my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
8133 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
8134 # $file - (string) filename
8135 #
8136 # returns: 1 on success, 0 on failure
8137 • add_dir_cert_subjects_to_stack
8139 Add a directory of certs to a stack. All certs in $dir that are not
8141 already in the $stackCAs will be added.
8142 my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
8144 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
8145 # $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.
8146 #
8147 # returns: 1 on success, 0 on failure
8148 Low level API: X509_STORE_* related functions
8150 • X509_STORE_CTX_new
8152 returns a newly initialised X509_STORE_CTX structure.
8154 • X509_STORE_CTX_init
8156 X509_STORE_CTX_init() sets up an X509_STORE_CTX for a subsequent
8158 verification operation. It must be called before each call to
8159 X509_verify_cert().
8160 my $rv = Net::SSLeay::X509_STORE_CTX_init($x509_store_ctx, $x509_store, $x509, $chain);
8162 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure (required)
8163 # $x509_store - value corresponding to openssl's X509_STORE structure (optional)
8164 # $x509 - value corresponding to openssl's X509 structure (optional)
8165 # $chain - value corresponding to openssl's STACK_OF(X509) structure (optional)
8166 #
8167 # returns: 1 on success, 0 on failure
8168 #
8169 # Note: returns nothing with Net::SSLeay 1.90 and earlier.
8170 Check openssl doc
8172 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_init.html>
8173 • X509_STORE_CTX_free
8175 Frees an X509_STORE_CTX structure.
8177 Net::SSLeay::X509_STORE_CTX_free($x509_store_ctx);
8179 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
8181 structure
8182 • X509_verify_cert
8184 The X509_verify_cert() function attempts to discover and validate a
8186 certificate chain based on parameters in ctx. A complete
8187 description of the process is contained in the verify(1) manual
8188 page.
8189 If this function returns 0, use X509_STORE_CTX_get_error to get
8191 additional error information.
8192 my $rv = Net::SSLeay::X509_verify_cert($x509_store_ctx);
8194 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8195 #
8196 # returns: 1 if a complete chain can be built and validated, otherwise 0
8197 Check openssl doc
8199 <https://www.openssl.org/docs/manmaster/man3/X509_verify_cert.html>
8200 • X509_STORE_CTX_get_current_cert
8202 Returns the certificate in ctx which caused the error or 0 if no
8204 certificate is relevant.
8205 my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
8207 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8208 #
8209 # returns: value corresponding to openssl's X509 structure (0 on failure)
8210 Check openssl doc
8212 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8213 • X509_STORE_CTX_get0_cert
8215 COMPATIBILITY: not available in Net-SSLeay-1.88 and before;
8217 requires at least OpenSSL 1.1.0pre6 or LibreSSL 2.7.0
8218 Returns an internal pointer to the certificate being verified by
8220 the ctx.
8221 my $x509 = Net::SSLeay::X509_STORE_CTX_get0_cert($x509_store_ctx);
8223 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8224 #
8225 # returns: value corresponding to openssl's X509 structure
8226 Check openssl doc
8228 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get0_cert.html>
8229 • X509_STORE_CTX_get1_chain
8231 Returns a returns a complete validate chain if a previous call to
8233 X509_verify_cert() is successful.
8234 my $rv = Net::SSLeay::X509_STORE_CTX_get1_chain($x509_store_ctx);
8236 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8237 #
8238 # returns: value corresponding to openssl's STACK_OF(X509) structure
8239 Check openssl doc
8241 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get1_chain.html>
8242 • X509_STORE_CTX_get_error
8244 Returns the error code of $ctx.
8246 my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
8248 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8249 #
8250 # returns: (integer) error code
8251 For more info about erro code values check function
8253 "get_verify_result".
8254 Check openssl doc
8256 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8257 • X509_STORE_CTX_get_error_depth
8259 Returns the depth of the error. This is a non-negative integer
8261 representing where in the certificate chain the error occurred. If
8262 it is zero it occurred in the end entity certificate, one if it is
8263 the certificate which signed the end entity certificate and so on.
8264 my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
8266 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8267 #
8268 # returns: (integer) depth
8269 Check openssl doc
8271 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8272 • X509_STORE_CTX_get_ex_data
8274 Is used to retrieve the information for $idx from $x509_store_ctx.
8276 my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
8278 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8279 # $idx - (integer) index for application specific data
8280 #
8281 # returns: pointer to ???
8282 • X509_STORE_CTX_set_ex_data
8284 Is used to store application data at arg for idx into
8286 $x509_store_ctx.
8287 my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
8289 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8290 # $idx - (integer) ???
8291 # $data - (pointer) ???
8292 #
8293 # returns: 1 on success, 0 on failure
8294 • X509_STORE_CTX_set_cert
8296 Sets the certificate to be verified in $x509_store_ctx to $x.
8298 Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
8300 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8301 # $x - value corresponding to openssl's X509 structure
8302 #
8303 # returns: no return value
8304 Check openssl doc
8306 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
8307 • X509_STORE_new
8309 Returns a newly initialized X509_STORE structure.
8311 my $rv = Net::SSLeay::X509_STORE_new();
8313 #
8314 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
8315 • X509_STORE_free
8317 Frees an X509_STORE structure
8319 Net::SSLeay::X509_STORE_free($x509_store);
8321 # $x509_store - value corresponding to openssl's X509_STORE structure
8322 • X509_STORE_add_lookup
8324 Adds a lookup to an X509_STORE for a given lookup method.
8326 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir;
8328 my $rv = Net::SSLeay::X509_STORE_add_lookup($x509_store, $method);
8329 # $method - value corresponding to openssl's X509_LOOKUP_METHOD structure
8330 # $x509_store - value corresponding to openssl's X509_STORE structure
8331 #
8332 # returns: value corresponding to openssl's X509_LOOKUP structure
8333 Check openssl doc
8335 <https://www.openssl.org/docs/manmaster/man3/X509_STORE_add_lookup.html>
8336 • X509_STORE_CTX_set_error
8338 Sets the error code of $ctx to $s. For example it might be used in
8340 a verification callback to set an error based on additional checks.
8341 Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
8343 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
8344 # $s - (integer) error id
8345 #
8346 # returns: no return value
8347 Check openssl doc
8349 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8350 • X509_STORE_add_cert
8352 Adds X509 certificate $x into the X509_STORE $store.
8354 my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
8356 # $store - value corresponding to openssl's X509_STORE structure
8357 # $x - value corresponding to openssl's X509 structure
8358 #
8359 # returns: 1 on success, 0 on failure
8360 • X509_STORE_add_crl
8362 Adds X509 CRL $x into the X509_STORE $store.
8364 my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
8366 # $store - value corresponding to openssl's X509_STORE structure
8367 # $x - value corresponding to openssl's X509_CRL structure
8368 #
8369 # returns: 1 on success, 0 on failure
8370 • X509_STORE_set1_param
8372 ??? (more info needed)
8374 my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
8376 # $store - value corresponding to openssl's X509_STORE structure
8377 # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
8378 #
8379 # returns: 1 on success, 0 on failure
8380 • X509_LOOKUP_hash_dir
8382 Returns an X509_LOOKUP structure that instructs an X509_STORE to
8384 load files from a directory containing certificates with filenames
8385 in the format hash.N or crls with filenames in the format hash.rN
8386 my $rv = Net::SSLeay::X509_LOOKUP_hash_dir();
8388 #
8389 # returns: value corresponding to openssl's X509_LOOKUP_METHOD structure, with the hashed directory method
8390 Check openssl doc
8392 <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
8393 • X509_LOOKUP_add_dir
8395 Add a directory to an X509_LOOKUP structure, usually obtained from
8397 X509_STORE_add_lookup.
8398 my $method = &Net::SSLeay::X509_LOOKUP_hash_dir;
8400 my $lookup = Net::SSLeay::X509_STORE_add_lookup($x509_store, $method);
8401 my $type = &Net::SSLeay::X509_FILETYPE_PEM;
8402 Net::SSLeay::X509_LOOKUP_add_dir($lookup, $dir, $type);
8403 # $lookup - value corresponding to openssl's X509_LOOKUP structure
8404 # $dir - string path to a directory
8405 # $type - constant corresponding to the type of file in the directory - can be X509_FILETYPE_PEM, X509_FILETYPE_DEFAULT, or X509_FILETYPE_ASN1
8406 • X509_STORE_set_flags
8408 Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
8410 # $ctx - value corresponding to openssl's X509_STORE structure
8411 # $flags - (unsigned long) flags to be set (bitmask)
8412 #
8413 # returns: no return value
8414 #to create $flags value use corresponding constants like
8416 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8417 For more details about $flags bitmask see
8419 "X509_VERIFY_PARAM_set_flags".
8420 • X509_STORE_set_purpose
8422 Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
8424 # $ctx - value corresponding to openssl's X509_STORE structure
8425 # $purpose - (integer) purpose identifier
8426 #
8427 # returns: no return value
8428 For more details about $purpose identifier check "CTX_set_purpose".
8430 • X509_STORE_set_trust
8432 Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
8434 # $ctx - value corresponding to openssl's X509_STORE structure
8435 # $trust - (integer) trust identifier
8436 #
8437 # returns: no return value
8438 For more details about $trust identifier check "CTX_set_trust".
8440 Low Level API: X509_INFO related functions
8442 • sk_X509_INFO_num
8444 Returns the number of values in a STACK_OF(X509_INFO) structure.
8446 my $rv = Net::SSLeay::sk_X509_INFO_num($sk_x509_info);
8448 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8449 #
8450 # returns: number of values in $sk_X509_info
8451 • sk_X509_INFO_value
8453 Returns the value of a STACK_OF(X509_INFO) structure at a given
8455 index.
8456 my $rv = Net::SSLeay::sk_X509_INFO_value($sk_x509_info, $index);
8458 # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8459 # $index - index into the stack
8460 #
8461 # returns: value corresponding to openssl's X509_INFO structure at the given index
8462 • P_X509_INFO_get_x509
8464 Returns the X509 structure stored in an X509_INFO structure.
8466 my $rv = Net::SSLeay::P_X509_INFO_get_x509($x509_info);
8468 # $x509_info - value corresponding to openssl's X509_INFO structure
8469 #
8470 # returns: value corresponding to openssl's X509 structure
8471 Low level API: X509_VERIFY_PARAM_* related functions
8473 • X509_VERIFY_PARAM_add0_policy
8475 Enables policy checking (it is disabled by default) and adds
8477 $policy to the acceptable policy set.
8478 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
8480 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8481 # $policy - value corresponding to openssl's ASN1_OBJECT structure
8482 #
8483 # returns: 1 on success, 0 on failure
8484 Check openssl doc
8486 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8487 • X509_VERIFY_PARAM_add0_table
8489 ??? (more info needed)
8491 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
8493 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8494 #
8495 # returns: 1 on success, 0 on failure
8496 • X509_VERIFY_PARAM_add1_host
8498 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8500 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8501 Adds an additional reference identifier that can match the peer's
8503 certificate.
8504 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add1_host($param, $name);
8506 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8507 # $name - (string) name to be set
8508 #
8509 # returns: 1 on success, 0 on failure
8510 See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
8512 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8513 wildcard matching.
8514 Check openssl doc
8516 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8517 • X509_VERIFY_PARAM_clear_flags
8519 Clears the flags $flags in param.
8521 my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
8523 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8524 # $flags - (unsigned long) flags to be set (bitmask)
8525 #
8526 # returns: 1 on success, 0 on failure
8527 For more details about $flags bitmask see
8529 "X509_VERIFY_PARAM_set_flags".
8530 Check openssl doc
8532 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8533 • X509_VERIFY_PARAM_free
8535 Frees up the X509_VERIFY_PARAM structure.
8537 Net::SSLeay::X509_VERIFY_PARAM_free($param);
8539 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8540 #
8541 # returns: no return value
8542 • X509_VERIFY_PARAM_get0_peername
8544 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8546 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8547 Returns the DNS hostname or subject CommonName from the peer
8549 certificate that matched one of the reference identifiers.
8550 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get0_peername($param);
8552 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8553 #
8554 # returns: (string) name e.g. '*.example.com' or undef
8555 Check openssl doc
8557 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8558 • X509_VERIFY_PARAM_get_depth
8560 Returns the current verification depth.
8562 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
8564 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8565 #
8566 # returns: (ineger) depth
8567 Check openssl doc
8569 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8570 • X509_VERIFY_PARAM_get_flags
8572 Returns the current verification flags.
8574 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
8576 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8577 #
8578 # returns: (unsigned long) flags to be set (bitmask)
8579 For more details about returned flags bitmask see
8581 "X509_VERIFY_PARAM_set_flags".
8582 Check openssl doc
8584 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8585 • X509_VERIFY_PARAM_set_flags
8587 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
8589 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8590 # $flags - (unsigned long) flags to be set (bitmask)
8591 #
8592 # returns: 1 on success, 0 on failure
8593 #to create $flags value use corresponding constants like
8595 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8596 For more details about $flags bitmask, see the OpenSSL docs below.
8598 Check openssl doc
8600 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8601 • X509_VERIFY_PARAM_inherit
8603 ??? (more info needed)
8605 my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
8607 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8608 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8609 #
8610 # returns: 1 on success, 0 on failure
8611 • X509_VERIFY_PARAM_lookup
8613 Finds X509_VERIFY_PARAM by name.
8615 my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
8617 # $name - (string) name we want to find
8618 #
8619 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8620 • X509_VERIFY_PARAM_new
8622 Creates a new X509_VERIFY_PARAM structure.
8624 my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
8626 #
8627 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8628 • X509_VERIFY_PARAM_set1
8630 Sets the name of X509_VERIFY_PARAM structure $to to the same value
8632 as the name of X509_VERIFY_PARAM structure $from.
8633 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
8635 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8636 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8637 #
8638 # returns: 1 on success, 0 on failure
8639 • X509_VERIFY_PARAM_set1_email
8641 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8643 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8644 Sets the expected RFC822 email address to email.
8646 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_email($param, $email);
8648 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8649 # $email - (string) email to be set
8650 #
8651 # returns: 1 on success, 0 on failure
8652 Check openssl doc
8654 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8655 • X509_VERIFY_PARAM_set1_host
8657 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8659 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8660 Sets the expected DNS hostname to name clearing any previously
8662 specified host name or names.
8663 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_host($param, $name);
8665 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8666 # $name - (string) name to be set
8667 #
8668 # returns: 1 on success, 0 on failure
8669 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8671 "X509_VERIFY_PARAM_set_hostflags" for more information, including
8672 wildcard matching.
8673 Check openssl doc
8675 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8676 • X509_VERIFY_PARAM_set1_ip
8678 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8680 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8681 Sets the expected IP address to ip.
8683 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_ip($param, $ip);
8685 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8686 # $ip - (binary) 4 octet IPv4 or 16 octet IPv6 address
8687 #
8688 # returns: 1 on success, 0 on failure
8689 Check openssl doc
8691 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8692 • X509_VERIFY_PARAM_set1_ip_asc
8694 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8696 requires at least OpenSSL 1.0.2-beta1 or LibreSSL 2.7.0
8697 Sets the expected IP address to ipasc.
8699 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_asc($param, $ipasc);
8701 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8702 # $ip - (string) IPv4 or IPv6 address
8703 #
8704 # returns: 1 on success, 0 on failure
8705 Check openssl doc
8707 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8708 • X509_VERIFY_PARAM_set1_name
8710 Sets the name of X509_VERIFY_PARAM structure $param to $name.
8712 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
8714 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8715 # $name - (string) name to be set
8716 #
8717 # returns: 1 on success, 0 on failure
8718 • X509_VERIFY_PARAM_set1_policies
8720 Enables policy checking (it is disabled by default) and sets the
8722 acceptable policy set to policies. Any existing policy set is
8723 cleared. The policies parameter can be 0 to clear an existing
8724 policy set.
8725 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
8727 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8728 # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
8729 #
8730 # returns: 1 on success, 0 on failure
8731 Check openssl doc
8733 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8734 • X509_VERIFY_PARAM_set_depth
8736 Sets the maximum verification depth to depth. That is the maximum
8738 number of untrusted CA certificates that can appear in a chain.
8739 Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
8741 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8742 # $depth - (integer) depth to be set
8743 #
8744 # returns: no return value
8745 Check openssl doc
8747 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8748 • X509_VERIFY_PARAM_set_hostflags
8750 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8752 requires at least OpenSSL 1.0.2-beta2 or LibreSSL 2.7.0
8753 Net::SSLeay::X509_VERIFY_PARAM_set_hostflags($param, $flags);
8755 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8756 # $flags - (unsigned int) flags to be set (bitmask)
8757 #
8758 # returns: no return value
8759 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8761 "X509_VERIFY_PARAM_set1_host" for more information. The flags for
8762 controlling wildcard checks and other features are defined in
8763 OpenSSL docs.
8764 Check openssl doc
8766 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8767 • X509_VERIFY_PARAM_set_purpose
8769 Sets the verification purpose in $param to $purpose. This
8771 determines the acceptable purpose of the certificate chain, for
8772 example SSL client or SSL server.
8773 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
8775 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8776 # $purpose - (integer) purpose identifier
8777 #
8778 # returns: 1 on success, 0 on failure
8779 For more details about $purpose identifier check "CTX_set_purpose".
8781 Check openssl doc
8783 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8784 • X509_VERIFY_PARAM_set_time
8786 Sets the verification time in $param to $t. Normally the current
8788 time is used.
8789 Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
8791 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8792 # $t - (time_t) time in seconds since 1.1.1970
8793 #
8794 # returns: no return value
8795 Check openssl doc
8797 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8798 • X509_VERIFY_PARAM_set_trust
8800 Sets the trust setting in $param to $trust.
8802 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
8804 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8805 # $trust - (integer) trust identifier
8806 #
8807 # returns: 1 on success, 0 on failure
8808 For more details about $trust identifier check "CTX_set_trust".
8810 Check openssl doc
8812 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8813 • X509_VERIFY_PARAM_table_cleanup
8815 ??? (more info needed)
8817 Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
8819 #
8820 # returns: no return value
8821 Low level API: Cipher (EVP_CIPHER_*) related functions
8823 • EVP_get_cipherbyname
8825 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8827 Returns an EVP_CIPHER structure when passed a cipher name.
8829 my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
8831 # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
8832 #
8833 # returns: value corresponding to openssl's EVP_CIPHER structure
8834 Check openssl doc
8836 <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
8837 Low level API: Digest (EVP_MD_*) related functions
8839 • OpenSSL_add_all_digests
8841 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8843 Net::SSLeay::OpenSSL_add_all_digests();
8845 # no args, no return value
8846 http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
8848 • P_EVP_MD_list_all
8850 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8852 requires at least openssl-1.0.0
8853 NOTE: Does not exactly correspond to any low level API function
8855 my $rv = Net::SSLeay::P_EVP_MD_list_all();
8857 #
8858 # returns: arrayref - list of available digest names
8859 The returned digest names correspond to values expected by
8861 "EVP_get_digestbyname".
8862 Note that some of the digests are available by default and some
8864 only after calling "OpenSSL_add_all_digests".
8865 • EVP_get_digestbyname
8867 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8869 my $rv = Net::SSLeay::EVP_get_digestbyname($name);
8871 # $name - string with digest name
8872 #
8873 # returns: value corresponding to openssl's EVP_MD structure
8874 The $name param can be:
8876 md2
8878 md4
8879 md5
8880 mdc2
8881 ripemd160
8882 sha
8883 sha1
8884 sha224
8885 sha256
8886 sha512
8887 whirlpool
8888 Or better check the supported digests by calling
8890 "P_EVP_MD_list_all".
8891 • EVP_MD_type
8893 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8895 my $rv = Net::SSLeay::EVP_MD_type($md);
8897 # $md - value corresponding to openssl's EVP_MD structure
8898 #
8899 # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
8900 • EVP_MD_size
8902 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8904 my $rv = Net::SSLeay::EVP_MD_size($md);
8906 # $md - value corresponding to openssl's EVP_MD structure
8907 #
8908 # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
8909 • EVP_MD_CTX_md
8911 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8913 requires at least openssl-0.9.7
8914 Net::SSLeay::EVP_MD_CTX_md($ctx);
8916 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8917 #
8918 # returns: value corresponding to openssl's EVP_MD structure
8919 • EVP_MD_CTX_create
8921 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8923 requires at least openssl-0.9.7
8924 Allocates, initializes and returns a digest context.
8926 my $rv = Net::SSLeay::EVP_MD_CTX_create();
8928 #
8929 # returns: value corresponding to openssl's EVP_MD_CTX structure
8930 The complete idea behind EVP_MD_CTX looks like this example:
8932 Net::SSLeay::OpenSSL_add_all_digests();
8934 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
8936 my $ctx = Net::SSLeay::EVP_MD_CTX_create();
8937 Net::SSLeay::EVP_DigestInit($ctx, $md);
8938 while(my $chunk = get_piece_of_data()) {
8940 Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
8941 }
8942 my $result = Net::SSLeay::EVP_DigestFinal($ctx);
8944 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8945 print "digest=", unpack('H*', $result), "\n"; #print hex value
8947 • EVP_DigestInit_ex
8949 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8951 requires at least openssl-0.9.7
8952 Sets up digest context $ctx to use a digest $type from ENGINE
8954 $impl, $ctx must be initialized before calling this function, type
8955 will typically be supplied by a function such as
8956 "EVP_get_digestbyname". If $impl is 0 then the default
8957 implementation of digest $type is used.
8958 my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
8960 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8961 # $type - value corresponding to openssl's EVP_MD structure
8962 # $impl - value corresponding to openssl's ENGINE structure
8963 #
8964 # returns: 1 for success and 0 for failure
8965 • EVP_DigestInit
8967 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8969 requires at least openssl-0.9.7
8970 Behaves in the same way as "EVP_DigestInit_ex" except the passed
8972 context $ctx does not have to be initialized, and it always uses
8973 the default digest implementation.
8974 my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
8976 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8977 # $type - value corresponding to openssl's EVP_MD structure
8978 #
8979 # returns: 1 for success and 0 for failure
8980 • EVP_MD_CTX_destroy
8982 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8984 requires at least openssl-0.9.7
8985 Cleans up digest context $ctx and frees up the space allocated to
8987 it, it should be called only on a context created using
8988 "EVP_MD_CTX_create".
8989 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8991 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8992 #
8993 # returns: no return value
8994 • EVP_DigestUpdate
8996 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8998 requires at least openssl-0.9.7
8999 my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
9001 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9002 # $data - data to be hashed
9003 #
9004 # returns: 1 for success and 0 for failure
9005 • EVP_DigestFinal_ex
9007 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9009 requires at least openssl-0.9.7
9010 Retrieves the digest value from $ctx. After calling
9012 "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
9013 be made, but "EVP_DigestInit_ex" can be called to initialize a new
9014 digest operation.
9015 my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
9017 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9018 #
9019 # returns: hash value (binary)
9020 #to get printable (hex) value of digest use:
9022 print unpack('H*', $digest_value);
9023 • EVP_DigestFinal
9025 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9027 requires at least openssl-0.9.7
9028 Similar to "EVP_DigestFinal_ex" except the digest context ctx is
9030 automatically cleaned up.
9031 my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
9033 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
9034 #
9035 # returns: hash value (binary)
9036 #to get printable (hex) value of digest use:
9038 print unpack('H*', $digest_value);
9039 • MD2
9041 COMPATIBILITY: no supported by default in openssl-1.0.0
9043 Computes MD2 from given $data (all data needs to be loaded into
9045 memory)
9046 my $digest = Net::SSLeay::MD2($data);
9048 print "digest(hexadecimal)=", unpack('H*', $digest);
9049 • MD4
9051 Computes MD4 from given $data (all data needs to be loaded into
9053 memory)
9054 my $digest = Net::SSLeay::MD4($data);
9056 print "digest(hexadecimal)=", unpack('H*', $digest);
9057 • MD5
9059 Computes MD5 from given $data (all data needs to be loaded into
9061 memory)
9062 my $digest = Net::SSLeay::MD5($data);
9064 print "digest(hexadecimal)=", unpack('H*', $digest);
9065 • RIPEMD160
9067 Computes RIPEMD160 from given $data (all data needs to be loaded
9069 into memory)
9070 my $digest = Net::SSLeay::RIPEMD160($data);
9072 print "digest(hexadecimal)=", unpack('H*', $digest);
9073 • SHA1
9075 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9077 Computes SHA1 from given $data (all data needs to be loaded into
9079 memory)
9080 my $digest = Net::SSLeay::SHA1($data);
9082 print "digest(hexadecimal)=", unpack('H*', $digest);
9083 • SHA256
9085 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9087 requires at least openssl-0.9.8
9088 Computes SHA256 from given $data (all data needs to be loaded into
9090 memory)
9091 my $digest = Net::SSLeay::SHA256($data);
9093 print "digest(hexadecimal)=", unpack('H*', $digest);
9094 • SHA512
9096 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9098 requires at least openssl-0.9.8
9099 Computes SHA512 from given $data (all data needs to be loaded into
9101 memory)
9102 my $digest = Net::SSLeay::SHA512($data);
9104 print "digest(hexadecimal)=", unpack('H*', $digest);
9105 • EVP_Digest
9107 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9109 requires at least openssl-0.9.7
9110 Computes "any" digest from given $data (all data needs to be loaded
9112 into memory)
9113 my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
9115 my $digest = Net::SSLeay::EVP_Digest($data, $md);
9116 print "digest(hexadecimal)=", unpack('H*', $digest);
9117 • EVP_sha1
9119 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9121 my $md = Net::SSLeay::EVP_sha1();
9123 #
9124 # returns: value corresponding to openssl's EVP_MD structure
9125 • EVP_sha256
9127 COMPATIBILITY: requires at least openssl-0.9.8
9129 my $md = Net::SSLeay::EVP_sha256();
9131 #
9132 # returns: value corresponding to openssl's EVP_MD structure
9133 • EVP_sha512
9135 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9137 requires at least openssl-0.9.8
9138 my $md = Net::SSLeay::EVP_sha512();
9140 #
9141 # returns: value corresponding to openssl's EVP_MD structure
9142 • EVP_add_digest
9144 my $rv = Net::SSLeay::EVP_add_digest($digest);
9146 # $digest - value corresponding to openssl's EVP_MD structure
9147 #
9148 # returns: 1 on success, 0 otherwise
9149 Low level API: CIPHER_* related functions
9151 • CIPHER_get_name
9153 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9155 Returns name of the cipher used.
9157 my $rv = Net::SSLeay::CIPHER_get_name($cipher);
9159 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9160 #
9161 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA', '(NONE)' if $cipher is undefined.
9162 Check openssl doc
9164 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
9165 Example:
9167 my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
9169 my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
9170 • CIPHER_description
9172 COMPATIBILITY: doesn't work correctly in Net-SSLeay-1.88 and before
9174 Returns a textual description of the cipher used.
9176 my $rv = Net::SSLeay::CIPHER_description($cipher);
9178 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9179 #
9180 # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
9181 Check openssl doc
9183 <https://www.openssl.org/docs/ssl/SSL_CIPHER_description.html>
9184 • CIPHER_get_bits
9186 COMPATIBILITY: $alg_bits doesn't work correctly in Net-SSLeay-1.88
9188 and before
9189 Returns the number of secret bits used for cipher.
9191 my $rv = Net::SSLeay::CIPHER_get_bits($cipher, $alg_bits);
9193 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9194 # $alg_bits - [optional] empty scalar for storing additional return value
9195 #
9196 # returns: (integer) number of secret bits, 0 on error
9197 # (integer) in $alg_bits for bits processed by the chosen algorithm
9198 Check openssl doc
9200 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_bits.html>
9201 Example:
9203 # bits and alg_bits are not equal for e.g., TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA,
9205 # RFC 8422 name TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
9206 my $alg_bits;
9207 my $bits = Net::SSLeay::CIPHER_get_bits($cipher, $alg_bits);
9208 #my $bits = Net::SSLeay::CIPHER_get_bits($cipher);
9209 print "bits: $bits, alg_bits: $alg_bits\n";
9210 • CIPHER_get_version
9212 COMPATIBILITY: not available in Net-SSLeay-1.88 and before
9214 Returns version of SSL/TLS protocol that first defined the cipher
9216 my $rv = Net::SSLeay::CIPHER_get_version($cipher);
9218 # $cipher - value corresponding to openssl's SSL_CIPHER structure
9219 #
9220 # returns: (string) cipher name e.g. 'TLSv1/SSLv3' with some libraries, 'TLSv1.0' or 'TLSv1.3', '(NONE)' if $cipher is undefined.
9221 Check openssl doc
9223 <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_version.html>
9224 Low level API: RSA_* related functions
9226 • RSA_generate_key
9228 Generates a key pair and returns it in a newly allocated RSA
9230 structure. The pseudo-random number generator must be seeded prior
9231 to calling RSA_generate_key.
9232 my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
9234 # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
9235 # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
9236 # $perl_cb - [optional] reference to perl callback function
9237 # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
9238 #
9239 # returns: value corresponding to openssl's RSA structure (0 on failure)
9240 Check openssl doc
9242 <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
9243 • RSA_free
9245 Frees the RSA structure and its components. The key is erased
9247 before the memory is returned to the system.
9248 Net::SSLeay::RSA_free($r);
9250 # $r - value corresponding to openssl's RSA structure
9251 #
9252 # returns: no return value
9253 Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
9255 • RSA_get_key_parameters
9257 Returns a list of pointers to BIGNUMs representing the parameters
9259 of the key in this order: (n, e, d, p, q, dmp1, dmq1, iqmp)
9260 Caution: returned list consists of SV pointers to BIGNUMs, which
9262 would need to be blessed as Crypt::OpenSSL::Bignum for further use
9263 my (@params) = RSA_get_key_parameters($r);
9265 Low level API: BIO_* related functions
9267 • BIO_eof
9269 Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
9271 varies according to the BIO type.
9272 my $rv = Net::SSLeay::BIO_eof($s);
9274 # $s - value corresponding to openssl's BIO structure
9275 #
9276 # returns: 1 if EOF has been reached 0 otherwise
9277 Check openssl doc
9279 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9280 • BIO_f_ssl
9282 Returns the SSL BIO method. This is a filter BIO which is a wrapper
9284 round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
9285 my $rv = Net::SSLeay::BIO_f_ssl();
9287 #
9288 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9289 Check openssl doc
9291 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9292 • BIO_free
9294 Frees up a single BIO.
9296 my $rv = Net::SSLeay::BIO_free($bio;);
9298 # $bio; - value corresponding to openssl's BIO structure
9299 #
9300 # returns: 1 on success, 0 on failure
9301 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9303 • BIO_new
9305 Returns a new BIO using method $type
9307 my $rv = Net::SSLeay::BIO_new($type);
9309 # $type - value corresponding to openssl's BIO_METHOD structure
9310 #
9311 # returns: value corresponding to openssl's BIO structure (0 on failure)
9312 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9314 • BIO_new_buffer_ssl_connect
9316 Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
9318 (using ctx) and a connect BIO.
9319 my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
9321 # $ctx - value corresponding to openssl's SSL_CTX structure
9322 #
9323 # returns: value corresponding to openssl's BIO structure (0 on failure)
9324 Check openssl doc
9326 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9327 • BIO_new_file
9329 Creates a new file BIO with mode $mode the meaning of mode is the
9331 same as the stdio function fopen(). The BIO_CLOSE flag is set on
9332 the returned BIO.
9333 my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
9335 # $filename - (string) filename
9336 # $mode - (string) opening mode (as mode by stdio function fopen)
9337 #
9338 # returns: value corresponding to openssl's BIO structure (0 on failure)
9339 Check openssl doc
9341 <http://www.openssl.org/docs/crypto/BIO_s_file.html>
9342 • BIO_new_ssl
9344 Allocates an SSL BIO using SSL_CTX ctx and using client mode if
9346 client is non zero.
9347 my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
9349 # $ctx - value corresponding to openssl's SSL_CTX structure
9350 # $client - (integer) 0 or 1 - indicates ssl client mode
9351 #
9352 # returns: value corresponding to openssl's BIO structure (0 on failure)
9353 Check openssl doc
9355 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9356 • BIO_new_ssl_connect
9358 Creates a new BIO chain consisting of an SSL BIO (using ctx)
9360 followed by a connect BIO.
9361 my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
9363 # $ctx - value corresponding to openssl's SSL_CTX structure
9364 #
9365 # returns: value corresponding to openssl's BIO structure (0 on failure)
9366 Check openssl doc
9368 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9369 • BIO_pending
9371 Return the number of pending characters in the BIOs read buffers.
9373 my $rv = Net::SSLeay::BIO_pending($s);
9375 # $s - value corresponding to openssl's BIO structure
9376 #
9377 # returns: the amount of pending data
9378 Check openssl doc
9380 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9381 • BIO_wpending
9383 Return the number of pending characters in the BIOs write buffers.
9385 my $rv = Net::SSLeay::BIO_wpending($s);
9387 # $s - value corresponding to openssl's BIO structure
9388 #
9389 # returns: the amount of pending data
9390 Check openssl doc
9392 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9393 • BIO_read
9395 Read the underlying descriptor.
9397 Net::SSLeay::BIO_read($s, $max);
9399 # $s - value corresponding to openssl's BIO structure
9400 # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
9401 #
9402 # returns: data
9403 Check openssl doc
9405 <http://www.openssl.org/docs/crypto/BIO_read.html>
9406 • BIO_write
9408 Attempts to write data from $buffer to BIO $b.
9410 my $rv = Net::SSLeay::BIO_write($b, $buffer);
9412 # $b - value corresponding to openssl's BIO structure
9413 # $buffer - data
9414 #
9415 # returns: amount of data successfully written
9416 # or that no data was successfully read or written if the result is 0 or -1
9417 # or -2 when the operation is not implemented in the specific BIO type
9418 Check openssl doc
9420 <http://www.openssl.org/docs/crypto/BIO_read.html>
9421 • BIO_s_mem
9423 Return the memory BIO method function.
9425 my $rv = Net::SSLeay::BIO_s_mem();
9427 #
9428 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9429 Check openssl doc
9431 <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
9432 • BIO_ssl_copy_session_id
9434 Copies an SSL session id between BIO chains from and to. It does
9436 this by locating the SSL BIOs in each chain and calling
9437 SSL_copy_session_id() on the internal SSL pointer.
9438 my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
9440 # $to - value corresponding to openssl's BIO structure
9441 # $from - value corresponding to openssl's BIO structure
9442 #
9443 # returns: 1 on success, 0 on failure
9444 Check openssl doc
9446 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9447 • BIO_ssl_shutdown
9449 Closes down an SSL connection on BIO chain bio. It does this by
9451 locating the SSL BIO in the chain and calling SSL_shutdown() on its
9452 internal SSL pointer.
9453 Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
9455 # $ssl_bio - value corresponding to openssl's BIO structure
9456 #
9457 # returns: no return value
9458 Check openssl doc
9460 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9461 Low level API: Server side Server Name Indication (SNI) support
9463 • set_tlsext_host_name
9465 TBA
9467 • get_servername
9469 TBA
9471 • get_servername_type
9473 TBA
9475 • CTX_set_tlsext_servername_callback
9477 COMPATIBILITY: requires at least OpenSSL 0.9.8f
9479 This function is used in a server to support Server side Server
9481 Name Indication (SNI).
9482 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
9484 # $ctx - SSL context
9485 # $code - reference to a subroutine that will be called when a new connection is being initiated
9486 #
9487 # returns: no return value
9488 On the client side: use set_tlsext_host_name($ssl, $servername)
9490 before initiating the SSL connection.
9491 On the server side: Set up an additional SSL_CTX() for each
9493 different certificate;
9494 Add a servername callback to each SSL_CTX() using
9496 CTX_set_tlsext_servername_callback();
9497 The callback function is required to retrieve the client-supplied
9499 servername with get_servername(ssl). Figure out the right SSL_CTX
9500 to go with that host name, then switch the SSL object to that
9501 SSL_CTX with set_SSL_CTX().
9502 Example:
9504 # set callback
9506 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
9507 sub {
9508 my $ssl = shift;
9509 my $h = Net::SSLeay::get_servername($ssl);
9510 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9511 } );
9512 More complete example:
9514 # ... initialize Net::SSLeay
9516 my %hostnames = (
9518 'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
9519 'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
9520 );
9521 # create a new context for each certificate/key pair
9523 for my $name (keys %hostnames) {
9524 $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
9525 Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
9526 Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
9527 $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
9528 }
9529 # create default context
9531 my $ctx = Net::SSLeay::CTX_new or die;
9532 Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
9533 Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
9534 # set callback
9536 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
9537 my $ssl = shift;
9538 my $h = Net::SSLeay::get_servername($ssl);
9539 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9540 } );
9541 # ... later
9543 $s = Net::SSLeay::new($ctx);
9545 Net::SSLeay::set_fd($s, fileno($accepted_socket));
9546 Net::SSLeay::accept($s);
9547 Low level API: NPN (next protocol negotiation) related functions
9549 NPN is being replaced with ALPN, a more recent TLS extension for
9551 application protocol negotiation that's in process of being adopted by
9552 IETF. Please look below for APLN API description.
9553 Simple approach for using NPN support looks like this:
9555 ### client side
9557 use Net::SSLeay;
9558 use IO::Socket::INET;
9559 Net::SSLeay::initialize();
9561 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9562 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9563 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9564 Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
9565 my $ssl = Net::SSLeay::new($ctx) or die;
9566 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9567 Net::SSLeay::connect($ssl);
9568 warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
9570 warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
9571 ### server side
9573 use Net::SSLeay;
9574 use IO::Socket::INET;
9575 Net::SSLeay::initialize();
9577 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9578 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9579 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9580 Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
9581 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9582 while (1) {
9584 my $ssl = Net::SSLeay::new($ctx);
9585 warn("server:waiting for incoming connection...\n");
9586 my $fd = $sock->accept();
9587 Net::SSLeay::set_fd($ssl, $fd->fileno);
9588 Net::SSLeay::accept($ssl);
9589 warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
9590 my $got = Net::SSLeay::read($ssl);
9591 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9592 Net::SSLeay::free($ssl);
9593 $fd->close();
9594 }
9595 # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
9596 Please note that the selection (negotiation) is performed by client
9598 side, the server side simply advertise the list of supported protocols.
9599 Advanced approach allows you to implement your own negotiation
9601 algorithm.
9602 #see below documentation for:
9604 Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9605 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9606 Detection of NPN support (works even in older Net::SSLeay versions):
9608 use Net::SSLeay;
9610 if (exists &Net::SSLeay::P_next_proto_negotiated) {
9612 # do NPN stuff
9613 }
9614 • CTX_set_next_proto_select_cb
9616 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9618 requires at least openssl-1.0.1
9619 NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
9621 connection.
9622 Simple usage - in this case a "common" negotiation algorithm (as
9624 implemented by openssl's function SSL_select_next_proto) is used.
9625 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
9627 # $ctx - value corresponding to openssl's SSL_CTX structure
9628 # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
9629 #
9630 # returns: 0 on success, 1 on failure
9631 Advanced usage (you probably do not need this):
9633 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9635 # $ctx - value corresponding to openssl's SSL_CTX structure
9636 # $perl_callback_function - reference to perl function
9637 # $callback_data - [optional] data to passed to callback function when invoked
9638 #
9639 # returns: 0 on success, 1 on failure
9640 # where callback function looks like
9642 sub npn_advertised_cb_invoke {
9643 my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
9644 my $status;
9645 # ...
9646 $status = 1; #status can be:
9647 # 0 - OPENSSL_NPN_UNSUPPORTED
9648 # 1 - OPENSSL_NPN_NEGOTIATED
9649 # 2 - OPENSSL_NPN_NO_OVERLAP
9650 return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
9651 }
9652 To undefine/clear this callback use:
9654 Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
9656 • CTX_set_next_protos_advertised_cb
9658 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9660 requires at least openssl-1.0.1
9661 NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
9663 connection.
9664 Simple usage:
9666 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
9668 # $ctx - value corresponding to openssl's SSL_CTX structure
9669 # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
9670 #
9671 # returns: 0 on success, 1 on failure
9672 Advanced usage (you probably do not need this):
9674 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9676 # $ctx - value corresponding to openssl's SSL_CTX structure
9677 # $perl_callback_function - reference to perl function
9678 # $callback_data - [optional] data to passed to callback function when invoked
9679 #
9680 # returns: 0 on success, 1 on failure
9681 # where callback function looks like
9683 sub npn_advertised_cb_invoke {
9684 my ($ssl, $callback_data) = @_;
9685 # ...
9686 return ['http1.1','spdy/2']; # the callback has to return arrayref
9687 }
9688 To undefine/clear this callback use:
9690 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
9692 • P_next_proto_negotiated
9694 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9696 requires at least openssl-1.0.1
9697 Returns the name of negotiated protocol for given SSL connection
9699 $ssl.
9700 $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
9702 # $ssl - value corresponding to openssl's SSL structure
9703 #
9704 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9705 • P_next_proto_last_status
9707 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9709 requires at least openssl-1.0.1
9710 Returns the result of the last negotiation for given SSL connection
9712 $ssl.
9713 $rv = Net::SSLeay::P_next_proto_last_status($ssl)
9715 # $ssl - value corresponding to openssl's SSL structure
9716 #
9717 # returns: (integer) negotiation status
9718 # 0 - OPENSSL_NPN_UNSUPPORTED
9719 # 1 - OPENSSL_NPN_NEGOTIATED
9720 # 2 - OPENSSL_NPN_NO_OVERLAP
9721 Low level API: ALPN (application layer protocol negotiation) related
9723 functions
9724 Application protocol can be negotiated via two different mechanisms
9726 employing two different TLS extensions: NPN (obsolete) and ALPN
9727 (recommended).
9728 The API is rather similar, with slight differences reflecting protocol
9730 specifics. In particular, with ALPN the protocol negotiation takes
9731 place on server, while with NPN the client implements the protocol
9732 negotiation logic.
9733 With ALPN, the most basic implementation looks like this:
9735 ### client side
9737 use Net::SSLeay;
9738 use IO::Socket::INET;
9739 Net::SSLeay::initialize();
9741 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9742 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9743 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9744 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9745 my $ssl = Net::SSLeay::new($ctx) or die;
9746 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9747 Net::SSLeay::connect($ssl);
9748 warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
9750 ### server side
9752 use Net::SSLeay;
9753 use IO::Socket::INET;
9754 Net::SSLeay::initialize();
9756 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9757 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9758 Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9759 Net::SSLeay::CTX_set_alpn_select_cb($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9760 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9761 while (1) {
9763 my $ssl = Net::SSLeay::new($ctx);
9764 warn("server:waiting for incoming connection...\n");
9765 my $fd = $sock->accept();
9766 Net::SSLeay::set_fd($ssl, $fd->fileno);
9767 Net::SSLeay::accept($ssl);
9768 warn "server:selected=",Net::SSLeay::P_alpn_selected($ssl),"\n";
9769 my $got = Net::SSLeay::read($ssl);
9770 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9771 Net::SSLeay::free($ssl);
9772 $fd->close();
9773 }
9774 # check with: openssl s_client -connect localhost:5443 -alpn spdy/3,http/1.1
9775 Advanced approach allows you to implement your own negotiation
9777 algorithm.
9778 #see below documentation for:
9780 Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9781 Detection of ALPN support (works even in older Net::SSLeay versions):
9783 use Net::SSLeay;
9785 if (exists &Net::SSLeay::P_alpn_selected) {
9787 # do ALPN stuff
9788 }
9789 • CTX_set_alpn_select_cb
9791 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9793 requires at least openssl-1.0.2
9794 NOTE: You need CTX_set_alpn_select_cb on server side of TLS
9796 connection.
9797 Simple usage - in this case a "common" negotiation algorithm (as
9799 implemented by openssl's function SSL_select_next_proto) is used.
9800 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $arrayref);
9802 # $ctx - value corresponding to openssl's SSL_CTX structure
9803 # $arrayref - list of accepted protocols - e.g. ['http/2.0', 'http/1.1', 'spdy/3']
9804 #
9805 # returns: 0 on success, 1 on failure
9806 Advanced usage (you probably do not need this):
9808 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9810 # $ctx - value corresponding to openssl's SSL_CTX structure
9811 # $perl_callback_function - reference to perl function
9812 # $callback_data - [optional] data to passed to callback function when invoked
9813 #
9814 # returns: 0 on success, 1 on failure
9815 # where callback function looks like
9817 sub alpn_select_cb_invoke {
9818 my ($ssl, $arrayref_proto_list_advertised_by_client, $callback_data) = @_;
9819 # ...
9820 if ($negotiated) {
9821 return 'http/2.0';
9822 } else {
9823 return undef;
9824 }
9825 }
9826 To undefine/clear this callback use:
9828 Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
9830 • set_alpn_protos
9832 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9834 requires at least openssl-1.0.2
9835 NOTE: You need set_alpn_protos on client side of TLS connection.
9837 This adds list of supported application layer protocols to
9839 ClientHello message sent by a client. It advertises the
9840 enumeration of supported protocols:
9841 Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
9843 # returns 0 on success
9844 • CTX_set_alpn_protos
9846 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9848 requires at least openssl-1.0.2
9849 NOTE: You need CTX_set_alpn_protos on client side of TLS
9851 connection.
9852 This adds list of supported application layer protocols to
9854 ClientHello message sent by a client. It advertises the
9855 enumeration of supported protocols:
9856 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9858 # returns 0 on success
9859 • P_alpn_selected
9861 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9863 requires at least openssl-1.0.2
9864 Returns the name of negotiated protocol for given TLS connection
9866 $ssl.
9867 $rv = Net::SSLeay::P_alpn_selected($ssl)
9869 # $ssl - value corresponding to openssl's SSL structure
9870 #
9871 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9872 Low level API: DANE Support
9874 OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
9876 Authentication of Named Entities (DANE) Transport Layer Association
9877 within OpenSSL
9878 • SSL_get_tlsa_record_byname
9880 COMPATIBILITY: DELETED from net-ssleay, since it is not supported
9882 by OpenSSL
9883 In order to facilitate DANE there is additional interface,
9885 SSL_get_tlsa_record_byname, accepting hostname, port and socket
9886 type that returns packed TLSA record. In order to make it even
9887 easier there is additional SSL_ctrl function that calls
9888 SSL_get_tlsa_record_byname for you. Latter is recommended for
9889 programmers that wish to maintain broader binary compatibility,
9890 e.g. make application work with both 1.0.2 and prior version (in
9891 which case call to SSL_ctrl with new code returning error would
9892 have to be ignored when running with prior version).
9893 Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
9895 Low level API: Other functions
9897 • COMP_add_compression_method
9899 Adds the compression method cm with the identifier id to the list
9901 of available compression methods. This list is globally maintained
9902 for all SSL operations within this application. It cannot be set
9903 for specific SSL_CTX or SSL objects.
9904 my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
9906 # $id - (integer) compression method id
9907 # 0 to 63: methods defined by the IETF
9908 # 64 to 192: external party methods assigned by IANA
9909 # 193 to 255: reserved for private use
9910 #
9911 # $cm - value corresponding to openssl's COMP_METHOD structure
9912 #
9913 # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
9914 Check openssl doc
9916 <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
9917 • DH_free
9919 Frees the DH structure and its components. The values are erased
9921 before the memory is returned to the system.
9922 Net::SSLeay::DH_free($dh);
9924 # $dh - value corresponding to openssl's DH structure
9925 #
9926 # returns: no return value
9927 Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
9929 • FIPS_mode_set
9931 Enable or disable FIPS mode in a FIPS capable OpenSSL.
9933 Net::SSLeay:: FIPS_mode_set($enable);
9935 # $enable - (integer) 1 to enable, 0 to disable
9936 Low level API: EC related functions
9938 • CTX_set_tmp_ecdh
9940 TBA
9942 • EC_KEY_free
9944 TBA
9946 • EC_KEY_new_by_curve_name
9948 TBA
9950 • EC_KEY_generate_key
9952 Generates a EC key and returns it in a newly allocated EC_KEY
9954 structure. The EC key then can be used to create a PKEY which can
9955 be used in calls like X509_set_pubkey.
9956 my $key = Net::SSLeay::EVP_PKEY_new();
9958 my $ec = Net::SSLeay::EC_KEY_generate_key($curve);
9959 Net::SSLeay::EVP_PKEY_assign_EC_KEY($key,$ec);
9960 # $curve - curve name like 'secp521r1' or the matching Id (integer) of the curve
9962 #
9963 # returns: value corresponding to openssl's EC_KEY structure (0 on failure)
9964 This function has no equivalent in OpenSSL but combines multiple
9966 OpenSSL functions for an easier interface.
9967 • CTX_set_ecdh_auto, set_ecdh_auto
9969 These functions enable or disable the automatic curve selection on
9971 the server side by calling SSL_CTX_set_ecdh_auto or
9972 SSL_set_ecdh_auto respectively. If enabled the highest preference
9973 curve is automatically used for ECDH temporary keys used during key
9974 exchange. This function is no longer available for OpenSSL 1.1.0
9975 or higher.
9976 Net::SSLeay::CTX_set_ecdh_auto($ctx,1);
9978 Net::SSLeay::set_ecdh_auto($ssl,1);
9979 • CTX_set1_curves_list, set1_curves_list
9981 These functions set the supported curves (in order of preference)
9983 by calling SSL_CTX_set1_curves_list or SSL_set1_curves_list
9984 respectively. For a TLS client these curves are offered to the
9985 server in the supported curves extension while on the server side
9986 these are used to determine the shared curve. These functions are
9987 only available since OpenSSL 1.1.0.
9988 Net::SSLeay::CTX_set1_curves_list($ctx,"P-521:P-384:P-256");
9990 Net::SSLeay::set1_curves_list($ssl,"P-521:P-384:P-256");
9991 • CTX_set1_groups_list, set1_groups_list
9993 These functions set the supported groups (in order of preference)
9995 by calling SSL_CTX_set1_groups_list or SSL_set1_groups_list
9996 respectively. This is practically the same as CTX_set1_curves_list
9997 and set1_curves_list except that all DH groups can be given as
9998 supported by TLS 1.3. These functions are only available since
9999 OpenSSL 1.1.1.
10000 Net::SSLeay::CTX_set1_groups_list($ctx,"P-521:P-384:P-256");
10002 Net::SSLeay::set1_groups_list($ssl,"P-521:P-384:P-256");
10003 Low level API: OSSL_LIB_CTX and OSSL_PROVIDER related functions
10005 • OSSL_LIB_CTX_get0_global_default
10007 Returns a concrete (non NULL) reference to the global default
10009 library context.
10010 my $libctx = Net::SSLeay::OSSL_LIB_CTX_get0_global_default();
10012 # returns: a value corresponding to OSSL_LIB_CTX structure or false on failure
10013 Typically it's simpler to use undef with functions that take an
10015 OSSL_LIB_CTX argument when global default library context is
10016 needed.
10017 Check openssl doc
10019 <https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX_get0_global_default.html>
10020 • OSSL_PROVIDER_load
10022 Loads and initializes a provider
10024 my $provider = Net::SSLeay::OSSL_PROVIDER_load($libctx, $name);
10026 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10027 # $name - (string) provider name, e.g., 'legacy'
10028 #
10029 # returns: a value corresponding to OSSL_PROVIDER or false on failure
10030 Using undef loads the provider within the global default library
10032 context.
10033 my $provider = Net::SSLeay::OSSL_PROVIDER_load(undef, 'legacy');
10035 Check openssl doc
10037 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_load.html>
10038 • OSSL_PROVIDER_try_load
10040 Loads and initializes a provider similar to OSSL_PROVIDER_load with
10042 additional fallback control.
10043 my $provider = Net::SSLeay::OSSL_PROVIDER_try_load($libctx, $name, $retain_fallbacks);
10045 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10046 # $name - (string) provider name, e.g., 'legacy'
10047 # $retain_fallbacks - (integer) 0 or 1
10048 #
10049 # returns: a value corresponding to OSSL_PROVIDER or false on failure
10050 Check openssl doc
10052 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_try_load.html>
10053 • OSSL_PROVIDER_unload
10055 Unloads the given provider.
10057 my $rv = Net::SSLeay::OSSL_PROVIDER_unload($provider);
10059 # $provider - a value corresponding to OSSL_PROVIDER
10060 #
10061 # returns: (integer) 1 on success, 0 on error
10062 Check openssl doc
10064 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_unload.html>
10065 • OSSL_PROVIDER_available
10067 Checks if a named provider is available for use.
10069 my $rv = Net::SSLeay::OSSL_PROVIDER_available($libctx, $name);
10071 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10072 # $name - (string) provider name, e.g., 'legacy'
10073 #
10074 # returns: (integer) 1 if the named provider is available, otherwise 0.
10075 Check openssl doc
10077 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_available.html>
10078 • OSSL_PROVIDER_do_all
10080 Iterates over all loaded providers. A callback is called for each
10082 provider.
10083 my $rv = Net::SSLeay::OSSL_PROVIDER_do_all($libctx, $cb, $cbdata);
10085 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10086 # $cb - reference to a perl callback function
10087 $ $cbdata - data that will be passed to callback function
10088 #
10089 # returns: (integer) 1 if all callbacks returned 1, 0 the first time a callback returns 0.
10090 Example:
10092 sub do_all_cb {
10094 my ($provider, $cbdata) = @_;
10095 my $name = Net::SSLeay::OSSL_PROVIDER_get0_name($provider);
10097 print "Callback for provider: '$name', cbdata: '$cbdata'\n";
10098 return 1;
10099 }
10100 my $data_for_cb = 'Hello';
10101 # Triggers default provider automatic loading.
10103 Net::SSLeay::OSSL_PROVIDER_available(undef, 'default') || die 'default provider not available';
10104 Net::SSLeay::OSSL_PROVIDER_load(undef, 'legacy') || die 'load legacy';
10105 Net::SSLeay::OSSL_PROVIDER_load(undef, 'null') || die 'load null';
10106 Net::SSLeay::OSSL_PROVIDER_do_all(undef, \&do_all_cb, $data_for_cb) || die 'a callback failed';
10107 Check openssl doc
10109 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_do_all.html>
10110 • OSSL_PROVIDER_get0_name
10112 Returns the name of the given provider.
10114 my $name = Net::SSLeay::OSSL_PROVIDER_get0_name($provider);
10116 # $provider - a value corresponding to OSSL_PROVIDER
10117 #
10118 # returns: (string) provider name, e.g., 'legacy'
10119 Check openssl doc
10121 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_get0_name.html>
10122 • OSSL_PROVIDER_self_test
10124 Runs the provider's self tests.
10126 my $rv = Net::SSLeay::OSSL_PROVIDER_self_test($provider);
10128 # $libctx - value corresponding to OSSL_LIB_CTX structure or undef
10129 # $provider - a value corresponding to OSSL_PROVIDER
10130 #
10131 # returns: (integer) returns 1 if the self tests pass, 0 on error
10132 Check openssl doc
10134 <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_self_test.html>
10135 Constants
10137 There are many openssl constants available in Net::SSLeay. You can use
10138 them like this:
10139 use Net::SSLeay;
10141 print &Net::SSLeay::NID_commonName;
10142 #or
10143 print Net::SSLeay::NID_commonName();
10144 Or you can import them and use:
10146 use Net::SSLeay qw/NID_commonName/;
10148 print &NID_commonName;
10149 #or
10150 print NID_commonName();
10151 #or
10152 print NID_commonName;
10153 The constants names are derived from openssl constants, however
10155 constants starting with "SSL_" prefix have name with "SSL_" part
10156 stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
10157 "Net::SSleay::OP_ALL"
10158 The list of all available constant names:
10160 ASN1_STRFLGS_ESC_CTRL OPENSSL_VERSION_STRING
10162 ASN1_STRFLGS_ESC_MSB OP_ALL
10163 ASN1_STRFLGS_ESC_QUOTE OP_ALLOW_NO_DHE_KEX
10164 ASN1_STRFLGS_RFC2253 OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
10165 CB_ACCEPT_EXIT OP_CIPHER_SERVER_PREFERENCE
10166 CB_ACCEPT_LOOP OP_CISCO_ANYCONNECT
10167 CB_ALERT OP_COOKIE_EXCHANGE
10168 CB_CONNECT_EXIT OP_CRYPTOPRO_TLSEXT_BUG
10169 CB_CONNECT_LOOP OP_DONT_INSERT_EMPTY_FRAGMENTS
10170 CB_EXIT OP_ENABLE_MIDDLEBOX_COMPAT
10171 CB_HANDSHAKE_DONE OP_EPHEMERAL_RSA
10172 CB_HANDSHAKE_START OP_LEGACY_SERVER_CONNECT
10173 CB_LOOP OP_MICROSOFT_BIG_SSLV3_BUFFER
10174 CB_READ OP_MICROSOFT_SESS_ID_BUG
10175 CB_READ_ALERT OP_MSIE_SSLV2_RSA_PADDING
10176 CB_WRITE OP_NETSCAPE_CA_DN_BUG
10177 CB_WRITE_ALERT OP_NETSCAPE_CHALLENGE_BUG
10178 ERROR_NONE OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG
10179 ERROR_SSL OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG
10180 ERROR_SYSCALL OP_NON_EXPORT_FIRST
10181 ERROR_WANT_ACCEPT OP_NO_ANTI_REPLAY
10182 ERROR_WANT_CONNECT OP_NO_CLIENT_RENEGOTIATION
10183 ERROR_WANT_READ OP_NO_COMPRESSION
10184 ERROR_WANT_WRITE OP_NO_ENCRYPT_THEN_MAC
10185 ERROR_WANT_X509_LOOKUP OP_NO_QUERY_MTU
10186 ERROR_ZERO_RETURN OP_NO_RENEGOTIATION
10187 EVP_PKS_DSA OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
10188 EVP_PKS_EC OP_NO_SSL_MASK
10189 EVP_PKS_RSA OP_NO_SSLv2
10190 EVP_PKT_ENC OP_NO_SSLv3
10191 EVP_PKT_EXCH OP_NO_TICKET
10192 EVP_PKT_EXP OP_NO_TLSv1
10193 EVP_PKT_SIGN OP_NO_TLSv1_1
10194 EVP_PK_DH OP_NO_TLSv1_2
10195 EVP_PK_DSA OP_NO_TLSv1_3
10196 EVP_PK_EC OP_PKCS1_CHECK_1
10197 EVP_PK_RSA OP_PKCS1_CHECK_2
10198 FILETYPE_ASN1 OP_PRIORITIZE_CHACHA
10199 FILETYPE_PEM OP_SAFARI_ECDHE_ECDSA_BUG
10200 F_CLIENT_CERTIFICATE OP_SINGLE_DH_USE
10201 F_CLIENT_HELLO OP_SINGLE_ECDH_USE
10202 F_CLIENT_MASTER_KEY OP_SSLEAY_080_CLIENT_DH_BUG
10203 F_D2I_SSL_SESSION OP_SSLREF2_REUSE_CERT_TYPE_BUG
10204 F_GET_CLIENT_FINISHED OP_TLSEXT_PADDING
10205 F_GET_CLIENT_HELLO OP_TLS_BLOCK_PADDING_BUG
10206 F_GET_CLIENT_MASTER_KEY OP_TLS_D5_BUG
10207 F_GET_SERVER_FINISHED OP_TLS_ROLLBACK_BUG
10208 F_GET_SERVER_HELLO READING
10209 F_GET_SERVER_VERIFY RECEIVED_SHUTDOWN
10210 F_I2D_SSL_SESSION RSA_3
10211 F_READ_N RSA_F4
10212 F_REQUEST_CERTIFICATE R_BAD_AUTHENTICATION_TYPE
10213 F_SERVER_HELLO R_BAD_CHECKSUM
10214 F_SSL_CERT_NEW R_BAD_MAC_DECODE
10215 F_SSL_GET_NEW_SESSION R_BAD_RESPONSE_ARGUMENT
10216 F_SSL_NEW R_BAD_SSL_FILETYPE
10217 F_SSL_READ R_BAD_SSL_SESSION_ID_LENGTH
10218 F_SSL_RSA_PRIVATE_DECRYPT R_BAD_STATE
10219 F_SSL_RSA_PUBLIC_ENCRYPT R_BAD_WRITE_RETRY
10220 F_SSL_SESSION_NEW R_CHALLENGE_IS_DIFFERENT
10221 F_SSL_SESSION_PRINT_FP R_CIPHER_TABLE_SRC_ERROR
10222 F_SSL_SET_FD R_INVALID_CHALLENGE_LENGTH
10223 F_SSL_SET_RFD R_NO_CERTIFICATE_SET
10224 F_SSL_SET_WFD R_NO_CERTIFICATE_SPECIFIED
10225 F_SSL_USE_CERTIFICATE R_NO_CIPHER_LIST
10226 F_SSL_USE_CERTIFICATE_ASN1 R_NO_CIPHER_MATCH
10227 F_SSL_USE_CERTIFICATE_FILE R_NO_PRIVATEKEY
10228 F_SSL_USE_PRIVATEKEY R_NO_PUBLICKEY
10229 F_SSL_USE_PRIVATEKEY_ASN1 R_NULL_SSL_CTX
10230 F_SSL_USE_PRIVATEKEY_FILE R_PEER_DID_NOT_RETURN_A_CERTIFICATE
10231 F_SSL_USE_RSAPRIVATEKEY R_PEER_ERROR
10232 F_SSL_USE_RSAPRIVATEKEY_ASN1 R_PEER_ERROR_CERTIFICATE
10233 F_SSL_USE_RSAPRIVATEKEY_FILE R_PEER_ERROR_NO_CIPHER
10234 F_WRITE_PENDING R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE
10235 GEN_DIRNAME R_PUBLIC_KEY_ENCRYPT_ERROR
10236 GEN_DNS R_PUBLIC_KEY_IS_NOT_RSA
10237 GEN_EDIPARTY R_READ_WRONG_PACKET_TYPE
10238 GEN_EMAIL R_SHORT_READ
10239 GEN_IPADD R_SSL_SESSION_ID_IS_DIFFERENT
10240 GEN_OTHERNAME R_UNABLE_TO_EXTRACT_PUBLIC_KEY
10241 GEN_RID R_UNKNOWN_REMOTE_ERROR_TYPE
10242 GEN_URI R_UNKNOWN_STATE
10243 GEN_X400 R_X509_LIB
10244 LIBRESSL_VERSION_NUMBER SENT_SHUTDOWN
10245 MBSTRING_ASC SESSION_ASN1_VERSION
10246 MBSTRING_BMP SESS_CACHE_BOTH
10247 MBSTRING_FLAG SESS_CACHE_CLIENT
10248 MBSTRING_UNIV SESS_CACHE_NO_AUTO_CLEAR
10249 MBSTRING_UTF8 SESS_CACHE_NO_INTERNAL
10250 MIN_RSA_MODULUS_LENGTH_IN_BYTES SESS_CACHE_NO_INTERNAL_LOOKUP
10251 MODE_ACCEPT_MOVING_WRITE_BUFFER SESS_CACHE_NO_INTERNAL_STORE
10252 MODE_AUTO_RETRY SESS_CACHE_OFF
10253 MODE_ENABLE_PARTIAL_WRITE SESS_CACHE_SERVER
10254 MODE_RELEASE_BUFFERS SSL2_MT_CLIENT_CERTIFICATE
10255 NID_OCSP_sign SSL2_MT_CLIENT_FINISHED
10256 NID_SMIMECapabilities SSL2_MT_CLIENT_HELLO
10257 NID_X500 SSL2_MT_CLIENT_MASTER_KEY
10258 NID_X509 SSL2_MT_ERROR
10259 NID_ad_OCSP SSL2_MT_REQUEST_CERTIFICATE
10260 NID_ad_ca_issuers SSL2_MT_SERVER_FINISHED
10261 NID_algorithm SSL2_MT_SERVER_HELLO
10262 NID_authority_key_identifier SSL2_MT_SERVER_VERIFY
10263 NID_basic_constraints SSL2_VERSION
10264 NID_bf_cbc SSL3_MT_CCS
10265 NID_bf_cfb64 SSL3_MT_CERTIFICATE
10266 NID_bf_ecb SSL3_MT_CERTIFICATE_REQUEST
10267 NID_bf_ofb64 SSL3_MT_CERTIFICATE_STATUS
10268 NID_cast5_cbc SSL3_MT_CERTIFICATE_URL
10269 NID_cast5_cfb64 SSL3_MT_CERTIFICATE_VERIFY
10270 NID_cast5_ecb SSL3_MT_CHANGE_CIPHER_SPEC
10271 NID_cast5_ofb64 SSL3_MT_CLIENT_HELLO
10272 NID_certBag SSL3_MT_CLIENT_KEY_EXCHANGE
10273 NID_certificate_policies SSL3_MT_ENCRYPTED_EXTENSIONS
10274 NID_client_auth SSL3_MT_END_OF_EARLY_DATA
10275 NID_code_sign SSL3_MT_FINISHED
10276 NID_commonName SSL3_MT_HELLO_REQUEST
10277 NID_countryName SSL3_MT_KEY_UPDATE
10278 NID_crlBag SSL3_MT_MESSAGE_HASH
10279 NID_crl_distribution_points SSL3_MT_NEWSESSION_TICKET
10280 NID_crl_number SSL3_MT_NEXT_PROTO
10281 NID_crl_reason SSL3_MT_SERVER_DONE
10282 NID_delta_crl SSL3_MT_SERVER_HELLO
10283 NID_des_cbc SSL3_MT_SERVER_KEY_EXCHANGE
10284 NID_des_cfb64 SSL3_MT_SUPPLEMENTAL_DATA
10285 NID_des_ecb SSL3_RT_ALERT
10286 NID_des_ede SSL3_RT_APPLICATION_DATA
10287 NID_des_ede3 SSL3_RT_CHANGE_CIPHER_SPEC
10288 NID_des_ede3_cbc SSL3_RT_HANDSHAKE
10289 NID_des_ede3_cfb64 SSL3_RT_HEADER
10290 NID_des_ede3_ofb64 SSL3_RT_INNER_CONTENT_TYPE
10291 NID_des_ede_cbc SSL3_VERSION
10292 NID_des_ede_cfb64 SSLEAY_BUILT_ON
10293 NID_des_ede_ofb64 SSLEAY_CFLAGS
10294 NID_des_ofb64 SSLEAY_DIR
10295 NID_description SSLEAY_PLATFORM
10296 NID_desx_cbc SSLEAY_VERSION
10297 NID_dhKeyAgreement ST_ACCEPT
10298 NID_dnQualifier ST_BEFORE
10299 NID_dsa ST_CONNECT
10300 NID_dsaWithSHA ST_INIT
10301 NID_dsaWithSHA1 ST_OK
10302 NID_dsaWithSHA1_2 ST_READ_BODY
10303 NID_dsa_2 ST_READ_HEADER
10304 NID_email_protect TLS1_1_VERSION
10305 NID_ext_key_usage TLS1_2_VERSION
10306 NID_ext_req TLS1_3_VERSION
10307 NID_friendlyName TLS1_VERSION
10308 NID_givenName TLSEXT_STATUSTYPE_ocsp
10309 NID_hmacWithSHA1 VERIFY_CLIENT_ONCE
10310 NID_id_ad VERIFY_FAIL_IF_NO_PEER_CERT
10311 NID_id_ce VERIFY_NONE
10312 NID_id_kp VERIFY_PEER
10313 NID_id_pbkdf2 VERIFY_POST_HANDSHAKE
10314 NID_id_pe V_OCSP_CERTSTATUS_GOOD
10315 NID_id_pkix V_OCSP_CERTSTATUS_REVOKED
10316 NID_id_qt_cps V_OCSP_CERTSTATUS_UNKNOWN
10317 NID_id_qt_unotice WRITING
10318 NID_idea_cbc X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
10319 NID_idea_cfb64 X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
10320 NID_idea_ecb X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
10321 NID_idea_ofb64 X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
10322 NID_info_access X509_CHECK_FLAG_NO_WILDCARDS
10323 NID_initials X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
10324 NID_invalidity_date X509_FILETYPE_ASN1
10325 NID_issuer_alt_name X509_FILETYPE_DEFAULT
10326 NID_keyBag X509_FILETYPE_PEM
10327 NID_key_usage X509_LOOKUP
10328 NID_localKeyID X509_PURPOSE_ANY
10329 NID_localityName X509_PURPOSE_CRL_SIGN
10330 NID_md2 X509_PURPOSE_NS_SSL_SERVER
10331 NID_md2WithRSAEncryption X509_PURPOSE_OCSP_HELPER
10332 NID_md5 X509_PURPOSE_SMIME_ENCRYPT
10333 NID_md5WithRSA X509_PURPOSE_SMIME_SIGN
10334 NID_md5WithRSAEncryption X509_PURPOSE_SSL_CLIENT
10335 NID_md5_sha1 X509_PURPOSE_SSL_SERVER
10336 NID_mdc2 X509_PURPOSE_TIMESTAMP_SIGN
10337 NID_mdc2WithRSA X509_TRUST_COMPAT
10338 NID_ms_code_com X509_TRUST_EMAIL
10339 NID_ms_code_ind X509_TRUST_OBJECT_SIGN
10340 NID_ms_ctl_sign X509_TRUST_OCSP_REQUEST
10341 NID_ms_efs X509_TRUST_OCSP_SIGN
10342 NID_ms_ext_req X509_TRUST_SSL_CLIENT
10343 NID_ms_sgc X509_TRUST_SSL_SERVER
10344 NID_name X509_TRUST_TSA
10345 NID_netscape X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH
10346 NID_netscape_base_url X509_V_ERR_AKID_SKID_MISMATCH
10347 NID_netscape_ca_policy_url X509_V_ERR_APPLICATION_VERIFICATION
10348 NID_netscape_ca_revocation_url X509_V_ERR_CA_KEY_TOO_SMALL
10349 NID_netscape_cert_extension X509_V_ERR_CA_MD_TOO_WEAK
10350 NID_netscape_cert_sequence X509_V_ERR_CERT_CHAIN_TOO_LONG
10351 NID_netscape_cert_type X509_V_ERR_CERT_HAS_EXPIRED
10352 NID_netscape_comment X509_V_ERR_CERT_NOT_YET_VALID
10353 NID_netscape_data_type X509_V_ERR_CERT_REJECTED
10354 NID_netscape_renewal_url X509_V_ERR_CERT_REVOKED
10355 NID_netscape_revocation_url X509_V_ERR_CERT_SIGNATURE_FAILURE
10356 NID_netscape_ssl_server_name X509_V_ERR_CERT_UNTRUSTED
10357 NID_ns_sgc X509_V_ERR_CRL_HAS_EXPIRED
10358 NID_organizationName X509_V_ERR_CRL_NOT_YET_VALID
10359 NID_organizationalUnitName X509_V_ERR_CRL_PATH_VALIDATION_ERROR
10360 NID_pbeWithMD2AndDES_CBC X509_V_ERR_CRL_SIGNATURE_FAILURE
10361 NID_pbeWithMD2AndRC2_CBC X509_V_ERR_DANE_NO_MATCH
10362 NID_pbeWithMD5AndCast5_CBC X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
10363 NID_pbeWithMD5AndDES_CBC X509_V_ERR_DIFFERENT_CRL_SCOPE
10364 NID_pbeWithMD5AndRC2_CBC X509_V_ERR_EE_KEY_TOO_SMALL
10365 NID_pbeWithSHA1AndDES_CBC X509_V_ERR_EMAIL_MISMATCH
10366 NID_pbeWithSHA1AndRC2_CBC X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD
10367 NID_pbe_WithSHA1And128BitRC2_CBC X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD
10368 NID_pbe_WithSHA1And128BitRC4 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD
10369 NID_pbe_WithSHA1And2_Key_TripleDES_CBC X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD
10370 NID_pbe_WithSHA1And3_Key_TripleDES_CBC X509_V_ERR_EXCLUDED_VIOLATION
10371 NID_pbe_WithSHA1And40BitRC2_CBC X509_V_ERR_HOSTNAME_MISMATCH
10372 NID_pbe_WithSHA1And40BitRC4 X509_V_ERR_INVALID_CA
10373 NID_pbes2 X509_V_ERR_INVALID_CALL
10374 NID_pbmac1 X509_V_ERR_INVALID_EXTENSION
10375 NID_pkcs X509_V_ERR_INVALID_NON_CA
10376 NID_pkcs3 X509_V_ERR_INVALID_POLICY_EXTENSION
10377 NID_pkcs7 X509_V_ERR_INVALID_PURPOSE
10378 NID_pkcs7_data X509_V_ERR_IP_ADDRESS_MISMATCH
10379 NID_pkcs7_digest X509_V_ERR_KEYUSAGE_NO_CERTSIGN
10380 NID_pkcs7_encrypted X509_V_ERR_KEYUSAGE_NO_CRL_SIGN
10381 NID_pkcs7_enveloped X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE
10382 NID_pkcs7_signed X509_V_ERR_NO_EXPLICIT_POLICY
10383 NID_pkcs7_signedAndEnveloped X509_V_ERR_NO_VALID_SCTS
10384 NID_pkcs8ShroudedKeyBag X509_V_ERR_OCSP_CERT_UNKNOWN
10385 NID_pkcs9 X509_V_ERR_OCSP_VERIFY_FAILED
10386 NID_pkcs9_challengePassword X509_V_ERR_OCSP_VERIFY_NEEDED
10387 NID_pkcs9_contentType X509_V_ERR_OUT_OF_MEM
10388 NID_pkcs9_countersignature X509_V_ERR_PATH_LENGTH_EXCEEDED
10389 NID_pkcs9_emailAddress X509_V_ERR_PATH_LOOP
10390 NID_pkcs9_extCertAttributes X509_V_ERR_PERMITTED_VIOLATION
10391 NID_pkcs9_messageDigest X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED
10392 NID_pkcs9_signingTime X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED
10393 NID_pkcs9_unstructuredAddress X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION
10394 NID_pkcs9_unstructuredName X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN
10395 NID_private_key_usage_period X509_V_ERR_STORE_LOOKUP
10396 NID_rc2_40_cbc X509_V_ERR_SUBJECT_ISSUER_MISMATCH
10397 NID_rc2_64_cbc X509_V_ERR_SUBTREE_MINMAX
10398 NID_rc2_cbc X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256
10399 NID_rc2_cfb64 X509_V_ERR_SUITE_B_INVALID_ALGORITHM
10400 NID_rc2_ecb X509_V_ERR_SUITE_B_INVALID_CURVE
10401 NID_rc2_ofb64 X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM
10402 NID_rc4 X509_V_ERR_SUITE_B_INVALID_VERSION
10403 NID_rc4_40 X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED
10404 NID_rc5_cbc X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY
10405 NID_rc5_cfb64 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE
10406 NID_rc5_ecb X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE
10407 NID_rc5_ofb64 X509_V_ERR_UNABLE_TO_GET_CRL
10408 NID_ripemd160 X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER
10409 NID_ripemd160WithRSA X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT
10410 NID_rle_compression X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
10411 NID_rsa X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE
10412 NID_rsaEncryption X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION
10413 NID_rsadsi X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION
10414 NID_safeContentsBag X509_V_ERR_UNNESTED_RESOURCE
10415 NID_sdsiCertificate X509_V_ERR_UNSPECIFIED
10416 NID_secretBag X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX
10417 NID_serialNumber X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE
10418 NID_server_auth X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE
10419 NID_sha X509_V_ERR_UNSUPPORTED_NAME_SYNTAX
10420 NID_sha1 X509_V_FLAG_ALLOW_PROXY_CERTS
10421 NID_sha1WithRSA X509_V_FLAG_CB_ISSUER_CHECK
10422 NID_sha1WithRSAEncryption X509_V_FLAG_CHECK_SS_SIGNATURE
10423 NID_shaWithRSAEncryption X509_V_FLAG_CRL_CHECK
10424 NID_stateOrProvinceName X509_V_FLAG_CRL_CHECK_ALL
10425 NID_subject_alt_name X509_V_FLAG_EXPLICIT_POLICY
10426 NID_subject_key_identifier X509_V_FLAG_EXTENDED_CRL_SUPPORT
10427 NID_surname X509_V_FLAG_IGNORE_CRITICAL
10428 NID_sxnet X509_V_FLAG_INHIBIT_ANY
10429 NID_time_stamp X509_V_FLAG_INHIBIT_MAP
10430 NID_title X509_V_FLAG_LEGACY_VERIFY
10431 NID_undef X509_V_FLAG_NOTIFY_POLICY
10432 NID_uniqueIdentifier X509_V_FLAG_NO_ALT_CHAINS
10433 NID_x509Certificate X509_V_FLAG_NO_CHECK_TIME
10434 NID_x509Crl X509_V_FLAG_PARTIAL_CHAIN
10435 NID_zlib_compression X509_V_FLAG_POLICY_CHECK
10436 NOTHING X509_V_FLAG_POLICY_MASK
10437 OCSP_RESPONSE_STATUS_INTERNALERROR X509_V_FLAG_SUITEB_128_LOS
10438 OCSP_RESPONSE_STATUS_MALFORMEDREQUEST X509_V_FLAG_SUITEB_128_LOS_ONLY
10439 OCSP_RESPONSE_STATUS_SIGREQUIRED X509_V_FLAG_SUITEB_192_LOS
10440 OCSP_RESPONSE_STATUS_SUCCESSFUL X509_V_FLAG_TRUSTED_FIRST
10441 OCSP_RESPONSE_STATUS_TRYLATER X509_V_FLAG_USE_CHECK_TIME
10442 OCSP_RESPONSE_STATUS_UNAUTHORIZED X509_V_FLAG_USE_DELTAS
10443 OPENSSL_BUILT_ON X509_V_FLAG_X509_STRICT
10444 OPENSSL_CFLAGS X509_V_OK
10445 OPENSSL_CPU_INFO XN_FLAG_COMPAT
10446 OPENSSL_DIR XN_FLAG_DN_REV
10447 OPENSSL_ENGINES_DIR XN_FLAG_DUMP_UNKNOWN_FIELDS
10448 OPENSSL_FULL_VERSION_STRING XN_FLAG_FN_ALIGN
10449 OPENSSL_INFO_CONFIG_DIR XN_FLAG_FN_LN
10450 OPENSSL_INFO_CPU_SETTINGS XN_FLAG_FN_MASK
10451 OPENSSL_INFO_DIR_FILENAME_SEPARATOR XN_FLAG_FN_NONE
10452 OPENSSL_INFO_DSO_EXTENSION XN_FLAG_FN_OID
10453 OPENSSL_INFO_ENGINES_DIR XN_FLAG_FN_SN
10454 OPENSSL_INFO_LIST_SEPARATOR XN_FLAG_MULTILINE
10455 OPENSSL_INFO_MODULES_DIR XN_FLAG_ONELINE
10456 OPENSSL_INFO_SEED_SOURCE XN_FLAG_RFC2253
10457 OPENSSL_MODULES_DIR XN_FLAG_SEP_COMMA_PLUS
10458 OPENSSL_PLATFORM XN_FLAG_SEP_CPLUS_SPC
10459 OPENSSL_VERSION XN_FLAG_SEP_MASK
10460 OPENSSL_VERSION_MAJOR XN_FLAG_SEP_MULTILINE
10461 OPENSSL_VERSION_MINOR XN_FLAG_SEP_SPLUS_SPC
10462 OPENSSL_VERSION_NUMBER XN_FLAG_SPC_EQ
10463 OPENSSL_VERSION_PATCH
10464 INTERNAL ONLY functions (do not use these)
10466 The following functions are not intended for use from outside of
10467 Net::SSLeay module. They might be removed, renamed or changed without
10468 prior notice in future version.
10469 Simply DO NOT USE THEM!
10471 • hello
10473 • blength
10475 • constant
10477
10479 One very good example to look at is the implementation of "sslcat()" in
10480 the "SSLeay.pm" file.
10481 The following is a simple SSLeay client (with too little error checking
10483 :-(
10484 #!/usr/bin/perl
10486 use Socket;
10487 use Net::SSLeay qw(die_now die_if_ssl_error) ;
10488 Net::SSLeay::load_error_strings();
10489 Net::SSLeay::SSLeay_add_ssl_algorithms();
10490 Net::SSLeay::randomize();
10491 ($dest_serv, $port, $msg) = @ARGV; # Read command line
10493 $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
10494 $dest_ip = gethostbyname ($dest_serv);
10495 $dest_serv_params = sockaddr_in($port, $dest_ip);
10496 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
10498 connect (S, $dest_serv_params) or die "connect: $!";
10499 select (S); $| = 1; select (STDOUT); # Eliminate STDIO buffering
10500 # The network connection is now open, lets fire up SSL
10502 $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
10504 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10505 or die_if_ssl_error("ssl ctx set options");
10506 $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
10507 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
10508 $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
10509 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10510 # Exchange data
10512 $res = Net::SSLeay::write($ssl, $msg); # Perl knows how long $msg is
10514 die_if_ssl_error("ssl write");
10515 CORE::shutdown S, 1; # Half close --> No more output, sends EOF to server
10516 $got = Net::SSLeay::read($ssl); # Perl returns undef on failure
10517 die_if_ssl_error("ssl read");
10518 print $got;
10519 Net::SSLeay::free ($ssl); # Tear down connection
10521 Net::SSLeay::CTX_free ($ctx);
10522 close S;
10523 The following is a simple SSLeay echo server (non forking):
10525 #!/usr/bin/perl -w
10527 use Socket;
10528 use Net::SSLeay qw(die_now die_if_ssl_error);
10529 Net::SSLeay::load_error_strings();
10530 Net::SSLeay::SSLeay_add_ssl_algorithms();
10531 Net::SSLeay::randomize();
10532 $our_ip = "\0\0\0\0"; # Bind to all interfaces
10534 $port = 1235;
10535 $sockaddr_template = 'S n a4 x8';
10536 $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
10537 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
10539 bind (S, $our_serv_params) or die "bind: $!";
10540 listen (S, 5) or die "listen: $!";
10541 $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
10542 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10543 or die_if_ssl_error("ssl ctx set options");
10544 # Following will ask password unless private key is not encrypted
10546 Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
10547 &Net::SSLeay::FILETYPE_PEM);
10548 die_if_ssl_error("private key");
10549 Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
10550 &Net::SSLeay::FILETYPE_PEM);
10551 die_if_ssl_error("certificate");
10552 while (1) {
10554 print "Accepting connections...\n";
10555 ($addr = accept (NS, S)) or die "accept: $!";
10556 select (NS); $| = 1; select (STDOUT); # Piping hot!
10557 ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
10559 @inetaddr = unpack('C4',$client_ip);
10560 print "$af connection from " .
10561 join ('.', @inetaddr) . ":$client_port\n";
10562 # We now have a network connection, lets fire up SSLeay...
10564 $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
10566 Net::SSLeay::set_fd($ssl, fileno(NS));
10567 $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
10569 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10570 # Connected. Exchange some data.
10572 $got = Net::SSLeay::read($ssl); # Returns undef on fail
10574 die_if_ssl_error("ssl read");
10575 print "Got `$got' (" . length ($got) . " chars)\n";
10576 Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
10578 die_if_ssl_error("ssl write");
10579 Net::SSLeay::free ($ssl); # Tear down connection
10581 close NS;
10582 }
10583 Yet another echo server. This one runs from "/etc/inetd.conf" so it
10585 avoids all the socket code overhead. Only caveat is opening an rsa key
10586 file - it had better be without any encryption or else it will not know
10587 where to ask for the password. Note how "STDIN" and "STDOUT" are wired
10588 to SSL.
10589 #!/usr/bin/perl
10591 # /etc/inetd.conf
10592 # ssltst stream tcp nowait root /path/to/server.pl server.pl
10593 # /etc/services
10594 # ssltst 1234/tcp
10595 use Net::SSLeay qw(die_now die_if_ssl_error);
10597 Net::SSLeay::load_error_strings();
10598 Net::SSLeay::SSLeay_add_ssl_algorithms();
10599 Net::SSLeay::randomize();
10600 chdir '/key/dir' or die "chdir: $!";
10602 $| = 1; # Piping hot!
10603 open LOG, ">>/dev/console" or die "Can't open log file $!";
10604 select LOG; print "server.pl started\n";
10605 $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
10607 $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
10608 Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
10609 and die_if_ssl_error("ssl set options");
10610 # We get already open network connection from inetd, now we just
10612 # need to attach SSLeay to STDIN and STDOUT
10613 Net::SSLeay::set_rfd($ssl, fileno(STDIN));
10614 Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
10615 Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
10617 Net::SSLeay::FILETYPE_PEM);
10618 die_if_ssl_error("private key");
10619 Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
10620 Net::SSLeay::FILETYPE_PEM);
10621 die_if_ssl_error("certificate");
10622 Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
10624 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10625 $got = Net::SSLeay::read($ssl);
10627 die_if_ssl_error("ssl read");
10628 print "Got `$got' (" . length ($got) . " chars)\n";
10629 Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
10631 die_if_ssl_error("ssl write");
10632 Net::SSLeay::free ($ssl); # Tear down the connection
10634 Net::SSLeay::CTX_free ($ctx);
10635 close LOG;
10636 There are also a number of example/test programs in the examples
10638 directory:
10639 sslecho.pl - A simple server, not unlike the one above
10641 minicli.pl - Implements a client using low level SSLeay routines
10642 sslcat.pl - Demonstrates using high level sslcat utility function
10643 get_page.pl - Is a utility for getting html pages from secure servers
10644 callback.pl - Demonstrates certificate verification and callback usage
10645 stdio_bulk.pl - Does SSL over Unix pipes
10646 ssl-inetd-serv.pl - SSL server that can be invoked from inetd.conf
10647 httpd-proxy-snif.pl - Utility that allows you to see how a browser
10648 sends https request to given server and what reply
10649 it gets back (very educative :-)
10650 makecert.pl - Creates a self signed cert (does not use this module)
10651
10653 See README and README.* in the distribution directory for installation
10654 guidance on a variety of platforms.
10655
10657 "Net::SSLeay::read()" uses an internal buffer of 32KB, thus no single
10658 read will return more. In practice one read returns much less, usually
10659 as much as fits in one network packet. To work around this, you should
10660 use a loop like this:
10661 $reply = '';
10663 while ($got = Net::SSLeay::read($ssl)) {
10664 last if print_errs('SSL_read');
10665 $reply .= $got;
10666 }
10667 Although there is no built-in limit in "Net::SSLeay::write()", the
10669 network packet size limitation applies here as well, thus use:
10670 $written = 0;
10672 while ($written < length($message)) {
10674 $written += Net::SSLeay::write($ssl, substr($message, $written));
10675 last if print_errs('SSL_write');
10676 }
10677 Or alternatively you can just use the following convenience functions:
10679 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
10681 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
10682
10684 LibreSSL versions in the 3.1 - 3.3 series contain a TLS 1.3
10685 implementation that is not fully compatible with the libssl API, but is
10686 still advertised during protocol auto-negotiation. If you encounter
10687 problems or unexpected behaviour with SSL or SSL_CTX objects whose
10688 protocol version was automatically negotiated and libssl is provided by
10689 any of these versions of LibreSSL, it could be because the peers
10690 negotiated to use TLS 1.3 - try setting the maximum protocol version to
10691 TLS 1.2 (via "Net::SSLeay::set_max_proto_version()" or
10692 "Net::SSLeay::CTX_set_max_proto_version()") before establishing the
10693 connection. The first stable LibreSSL version with a fully libssl-
10694 compatible TLS 1.3 implementation is 3.4.1.
10695 An OpenSSL bug CVE-2015-0290 "OpenSSL Multiblock Corrupted Pointer
10697 Issue" can cause POST requests of over 90kB to fail or crash. This bug
10698 is reported to be fixed in OpenSSL 1.0.2a.
10699 Autoloader emits a
10701 Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
10703 warning if die_if_ssl_error is made autoloadable. If you figure out
10705 why, drop me a line.
10706 Callback set using "SSL_set_verify()" does not appear to work. This may
10708 well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
10709 using "SSL_CTX_set_verify()" instead and do not be surprised if even
10710 this stops working in future versions.
10711 Callback and certificate verification stuff is generally too little
10713 tested.
10714 Random numbers are not initialized randomly enough, especially if you
10716 do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
10717 platforms - but it's been suggested that cryptorand daemon from the
10718 SUNski package solves this). In this case you should investigate third
10719 party software that can emulate these devices, e.g. by way of a named
10720 pipe to some program.
10721 Another gotcha with random number initialization is randomness
10723 depletion. This phenomenon, which has been extensively discussed in
10724 OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
10725 to block if you use "/dev/random" or to operate insecurely if you use
10726 "/dev/urandom". What happens is that when too much randomness is drawn
10727 from the operating system's randomness pool then randomness can
10728 temporarily be unavailable. "/dev/random" solves this problem by
10729 waiting until enough randomness can be gathered - and this can take a
10730 long time since blocking reduces activity in the machine and less
10731 activity provides less random events: a vicious circle. "/dev/urandom"
10732 solves this dilemma more pragmatically by simply returning predictable
10733 "random" numbers. Some" /dev/urandom" emulation software however
10734 actually seems to implement "/dev/random" semantics. Caveat emptor.
10735 I've been pointed to two such daemons by Mik Firestone
10737 <mik@@speed.stdio._com> who has used them on Solaris 8:
10738 1. Entropy Gathering Daemon (EGD) at
10740 <http://www.lothar.com/tech/crypto/>
10741 2. Pseudo-random number generating daemon (PRNGD) at
10743 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10744 If you are using the low level API functions to communicate with other
10746 SSL implementations, you would do well to call
10747 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10749 or die_if_ssl_error("ssl ctx set options");
10750 to cope with some well know bugs in some other SSL implementations. The
10752 high level API functions always set all known compatibility options.
10753 Sometimes "sslcat()" (and the high level HTTPS functions that build on
10755 it) is too fast in signaling the EOF to legacy HTTPS servers. This
10756 causes the server to return empty page. To work around this problem you
10757 can set the global variable
10758 $Net::SSLeay::slowly = 1; # Add sleep so broken servers can keep up
10760 HTTP/1.1 is not supported. Specifically this module does not know to
10762 issue or serve multiple http requests per connection. This is a serious
10763 shortcoming, but using the SSL session cache on your server helps to
10764 alleviate the CPU load somewhat.
10765 As of version 1.09 many newer OpenSSL auxiliary functions were added
10767 (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
10768 Unfortunately I have not had any opportunity to test these. Some of
10769 them are trivial enough that I believe they "just work", but others
10770 have rather complex interfaces with function pointers and all. In these
10771 cases you should proceed wit great caution.
10772 This module defaults to using OpenSSL automatic protocol negotiation
10774 code for automatically detecting the version of the SSL/TLS protocol
10775 that the other end talks. With most web servers this works just fine,
10776 but once in a while I get complaints from people that the module does
10777 not work with some web servers. Usually this can be solved by
10778 explicitly setting the protocol version, e.g.
10779 $Net::SSLeay::ssl_version = 2; # Insist on SSLv2
10781 $Net::SSLeay::ssl_version = 3; # Insist on SSLv3
10782 $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
10783 $Net::SSLeay::ssl_version = 11; # Insist on TLSv1.1
10784 $Net::SSLeay::ssl_version = 12; # Insist on TLSv1.2
10785 $Net::SSLeay::ssl_version = 13; # Insist on TLSv1.3
10786 Although the autonegotiation is nice to have, the SSL standards do not
10788 formally specify any such mechanism. Most of the world has accepted the
10789 SSLeay/OpenSSL way of doing it as the de facto standard. But for the
10790 few that think differently, you have to explicitly speak the correct
10791 version. This is not really a bug, but rather a deficiency in the
10792 standards. If a site refuses to respond or sends back some nonsensical
10793 error codes (at the SSL handshake level), try this option before
10794 mailing me.
10795 On some systems, OpenSSL may be compiled without support for SSLv2. If
10797 this is the case, Net::SSLeay will warn if ssl_version has been set to
10798 2.
10799 The high level API returns the certificate of the peer, thus allowing
10801 one to check what certificate was supplied. However, you will only be
10802 able to check the certificate after the fact, i.e. you already sent
10803 your form data by the time you find out that you did not trust them,
10804 oops.
10805 So, while being able to know the certificate after the fact is surely
10807 useful, the security minded would still choose to do the connection and
10808 certificate verification first and only then exchange data with the
10809 site. Currently none of the high level API functions do this, thus you
10810 would have to program it using the low level API. A good place to start
10811 is to see how the "Net::SSLeay::http_cat()" function is implemented.
10812 The high level API functions use a global file handle "SSLCAT_S"
10814 internally. This really should not be a problem because there is no way
10815 to interleave the high level API functions, unless you use threads (but
10816 threads are not very well supported in perl anyway). However, you may
10817 run into problems if you call undocumented internal functions in an
10818 interleaved fashion. The best solution is to "require Net::SSLeay" in
10819 one thread after all the threads have been created.
10820
10822 Random number generator not seeded!!!
10823 (W) This warning indicates that "randomize()" was not able to read
10824 "/dev/random" or "/dev/urandom", possibly because your system does
10825 not have them or they are differently named. You can still use SSL,
10826 but the encryption will not be as strong.
10827 open_tcp_connection: destination host not found:`server' (port 123)
10829 ($!)
10830 Name lookup for host named "server" failed.
10831 open_tcp_connection: failed `server', 123 ($!)
10833 The name was resolved, but establishing the TCP connection failed.
10834 msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
10836 proto
10837 SSLeay error string. The first number (123) is the PID, the second
10838 number (1) indicates the position of the error message in SSLeay
10839 error stack. You often see a pile of these messages as errors
10840 cascade.
10841 msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
10843 The same as above, but you didn't call load_error_strings() so
10844 SSLeay couldn't verbosely explain the error. You can still find out
10845 what it means with this command:
10846 /usr/local/ssl/bin/ssleay errstr 02001002
10848 Password is being asked for private key
10850 This is normal behaviour if your private key is encrypted. Either
10851 you have to supply the password or you have to use an unencrypted
10852 private key. Scan OpenSSL.org for the FAQ that explains how to do
10853 this (or just study examples/makecert.pl which is used during "make
10854 test" to do just that).
10855
10857 You can mitigate some of the security vulnerabilities that might be
10858 present in your SSL/TLS application:
10859 BEAST Attack
10861 http://blogs.cisco.com/security/beat-the-beast-with-tls/
10862 https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
10863 http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
10864 The BEAST attack relies on a weakness in the way CBC mode is used in
10866 SSL/TLS. In OpenSSL versions 0.9.6d and later, the protocol-level
10867 mitigation is enabled by default, thus making it not vulnerable to the
10868 BEAST attack.
10869 Solutions:
10871 • Compile with OpenSSL versions 0.9.6d or later, which enables
10873 SSL_OP_ALL by default
10874 • Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
10876 enabled by default)
10877 • Don't support SSLv2, SSLv3
10879 • Actively control the ciphers your server supports with
10881 set_cipher_list:
10882 Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
10884 Session Resumption
10886 http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
10887 The SSL Labs vulnerability test on your SSL server might report in red:
10889 Session resumption No (IDs assigned but not accepted)
10891 This report is not really bug or a vulnerability, since the server will
10893 not accept session resumption requests. However, you can prevent this
10894 noise in the report by disabling the session cache altogether:
10895 Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx,
10896 Net::SSLeay::SESS_CACHE_OFF()); Use 0 if you don't have SESS_CACHE_OFF
10897 constant.
10898 Secure Renegotiation and DoS Attack
10900 https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
10901 This is not a "security flaw," it is more of a DoS vulnerability.
10903 Solutions:
10905 • Do not support SSLv2
10907 • Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
10909 • Compile with OpenSSL 0.9.8m or later
10911
10913 If you encounter a problem with this module that you believe is a bug,
10914 please create a new issue <https://github.com/radiator-software/p5-net-
10915 ssleay/issues/new> in the Net-SSLeay GitHub repository. Please make
10916 sure your bug report includes the following information:
10917 • the code you are trying to run;
10919 • your operating system name and version;
10921 • the output of "perl -V";
10923 • the version of OpenSSL or LibreSSL you are using.
10925
10927 Originally written by Sampo Kellomäki.
10928 Maintained by Florian Ragwitz between November 2005 and January 2010.
10930 Maintained by Mike McCauley between November 2005 and June 2018.
10932 Maintained by Chris Novakovic, Tuure Vartiainen and Heikki Vatiainen
10934 since June 2018.
10935
10937 Copyright (c) 1996-2003 Sampo Kellomäki <sampo@iki.fi>
10938 Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
10940 Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
10942 Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
10944 Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
10946 Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
10948 All rights reserved.
10950
10952 This module is released under the terms of the Artistic License 2.0.
10953 For details, see the "LICENSE" file distributed with Net-SSLeay's
10954 source code.
10955
10957 Net::SSLeay::Handle - File handle interface
10958 ./examples - Example servers and a clients
10959 <http://www.openssl.org/> - OpenSSL source, documentation, etc
10960 openssl-users-request@openssl.org - General OpenSSL mailing list
10961 <http://www.ietf.org/rfc/rfc2246.txt> - TLS 1.0 specification
10962 <http://www.w3c.org> - HTTP specifications
10963 <http://www.ietf.org/rfc/rfc2617.txt> - How to send password
10964 <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
10965 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10966 - pseudo-random number generating daemon (PRNGD)
10967 perl(1)
10968 perlref(1)
10969 perllol(1)
10970 perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
10971perl v5.34.0 2022-01-21 Net::SSLeay(3)