1Net::SSLeay(3)        User Contributed Perl Documentation       Net::SSLeay(3)
2
3
4

NAME

6       Net::SSLeay - Perl bindings for OpenSSL and LibreSSL
7

SYNOPSIS

9         use Net::SSLeay qw(get_https post_https sslcat make_headers make_form);
10
11         ($page) = get_https('www.bacus.pt', 443, '/');                 # Case 1
12
13         ($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
19         ($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
25         ($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
31         $reply = sslcat($host, $port, $request);                       # Case 4
32
33         ($reply, $err, $server_cert) = sslcat($host, $port, $request); # Case 5
34
35         $Net::SSLeay::trace = 2;  # 0=no debugging, 1=ciphers, 2=trace, 3=dump data
36
37         Net::SSLeay::initialize(); # Initialize ssl library once
38

DESCRIPTION

40       This module provides Perl bindings for libssl (an SSL/TLS API) and
41       libcrypto (a cryptography API).
42

COMPATIBILITY

44       Net::SSLeay supports the following libssl implementations:
45
46       •   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
49       •   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
52       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
56       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
67       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
78           if ( defined &Net::SSLeay::libssl_function ) {
79               # libssl_function() (or SSL_libssl_function()) is available
80               Net::SSLeay::libssl_function(...);
81           }
82

OVERVIEW

84       Net::SSLeay module basically comprise of:
85
86       •   High level functions for accessing web servers (by using
87           HTTP/HTTPS)
88
89       •   Low level API (mostly mapped 1:1 to openssl's C functions)
90
91       •   Convenience functions (related to low level API but with more perl
92           friendly interface)
93
94       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
98   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
106       For high level functions it is most convenient to import them into your
107       main namespace as indicated in the synopsis.
108
109       Basic set of functions
110
111       •   get_https
112
113       •   post_https
114
115       •   put_https
116
117       •   head_https
118
119       •   do_https
120
121       •   sslcat
122
123       •   https_cat
124
125       •   make_form
126
127       •   make_headers
128
129       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
138       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
147       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
151       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
161       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
167       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
170       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
174       Alternate versions of high-level API
175
176       •   get_https3
177
178       •   post_https3
179
180       •   put_https3
181
182       •   get_https4
183
184       •   post_https4
185
186       •   put_https4
187
188       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
195         ($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
200         ($page, $response, $headers, $server_cert)
201           = get_https3('www.bacus.pt', 443, '/');
202         print "$headers\n";
203
204         ($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
212       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
220         print $$headers_ref{COOKIE}[0];
221
222       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
225         ($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
237       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
246       Using client certificates
247
248       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
254       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
264       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
269         ($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
275         ($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
282       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
286       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
290       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
294         Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
295
296       See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
297       description.
298
299       Working through a web proxy
300
301       •   set_proxy
302
303       "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
307         Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
308         ($page) = get_https('www.bacus.pt', 443, '/');
309
310       If your proxy requires authentication, you can supply a username and
311       password as well
312
313         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
320       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
324       HTTP (without S) API
325
326       •   get_http
327
328       •   post_http
329
330       •   tcpcat
331
332       •   get_httpx
333
334       •   post_httpx
335
336       •   tcpxcat
337
338       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
344         use Net::SSLeay qw(get_http post_http tcpcat
345                             get_httpx post_httpx tcpxcat
346                             make_headers make_form);
347
348         ($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
354         ($page, $response, %reply_headers)
355                = post_http('www.bacus.pt', 443, '/foo.cgi', '',
356                       make_form(OK   => '1',
357                                 name => 'Sampo'
358                       ));
359
360         ($reply, $err) = tcpcat($host, $port, $request);
361
362         ($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
368         ($page, $response, %reply_headers)
369                = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
370                       make_form(OK   => '1',  name => 'Sampo' ));
371
372         ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
373
374       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
377   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
384       You can enable "Net::SSLeay CRL" checking like this:
385
386                   &Net::SSLeay::X509_STORE_set_flags
387                       (&Net::SSLeay::CTX_get_cert_store($ssl),
388                        &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
389
390       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
401               openssl crl -in crl.pem -hash -noout
402
403       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
406       You can also force OpenSSL to look for CRLs in one or more arbitrarily
407       named files.
408
409           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
419       Usually the URLs where you can download the CRLs is contained in the
420       certificate itself and you can extract them with
421
422           my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
423
424       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
429           openssl crl -in crl.der -inform der -out crl.pem
430
431       So as an alternative for faster and timely revocation checks you better
432       use the Online Status Revocation Protocol (OCSP).
433
434   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
439       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
445       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
450       With Net::SSLeay this can be done like this:
451
452           # 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
461           # 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
466           # determine URI of OCSP responder
467           my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
468
469           # 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
480           # 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
484           # 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
491           # 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
501           # Extract information from OCSP_RESPONSE for each of the ids.
502
503           # 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
516           # 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
538       To further speed up certificate revocation checking one can use a TLS
539       extension to instruct the server to staple the OCSP response:
540
541           # set TLS extension before doing SSL_connect
542           Net::SSLeay::set_tlsext_status_type($ssl,
543               Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
544
545           # 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
576               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
586           # 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
601   Using Net::SSLeay in multi-threaded applications
602       IMPORTANT: versions 1.42 or earlier are not thread-safe!
603
604       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
609       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
613       Initialization
614
615       Load and initialize Net::SSLeay module in the main thread:
616
617           use threads;
618           use Net::SSLeay;
619
620           Net::SSLeay::load_error_strings();
621           Net::SSLeay::SSLeay_add_ssl_algorithms();
622           Net::SSLeay::randomize();
623
624           sub do_master_job {
625             #... call whatever from Net::SSLeay
626           }
627
628           sub do_worker_job {
629             #... call whatever from Net::SSLeay
630           }
631
632           #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
636           #waiting for all threads to finish
637           $_->join() for (threads->list);
638
639       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
647       Using callbacks
648
649       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
653       Using openssl elements
654
655       All openssl elements (X509, SSL_CTX, ...) can be directly passed
656       between threads.
657
658           use threads;
659           use Net::SSLeay;
660
661           Net::SSLeay::load_error_strings();
662           Net::SSLeay::SSLeay_add_ssl_algorithms();
663           Net::SSLeay::randomize();
664
665           sub do_job {
666             my $context = shift;
667             Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
668             #...
669           }
670
671           my $c = Net::SSLeay::CTX_new();
672           threads->create(\&do_job, $c);
673
674       Or:
675
676           use threads;
677           use Net::SSLeay;
678
679           my $context; #does not need to be 'shared'
680
681           Net::SSLeay::load_error_strings();
682           Net::SSLeay::SSLeay_add_ssl_algorithms();
683           Net::SSLeay::randomize();
684
685           sub do_job {
686             Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
687             #...
688           }
689
690           $context = Net::SSLeay::CTX_new();
691           threads->create(\&do_job);
692
693       Using other perl modules based on Net::SSLeay
694
695       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
701       To be safe you can load and init Net::SSLeay explicitly in the main
702       thread:
703
704           use Net::SSLeay;
705           use Other::SSLeay::Based::Module;
706
707           Net::SSLeay::load_error_strings();
708           Net::SSLeay::SSLeay_add_ssl_algorithms();
709           Net::SSLeay::randomize();
710
711       Or even safer:
712
713           use Net::SSLeay;
714           use Other::SSLeay::Based::Module;
715
716           BEGIN {
717             Net::SSLeay::load_error_strings();
718             Net::SSLeay::SSLeay_add_ssl_algorithms();
719             Net::SSLeay::randomize();
720           }
721
722       Combining Net::SSLeay with other modules linked with openssl
723
724       BEWARE: This might be a big trouble! This is not guaranteed be thread-
725       safe!
726
727       There are many other (XS) modules linked directly to openssl library
728       (like Crypt::SSLeay).
729
730       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
734       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
739       Threading with get_https and friends
740
741       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
745           Net::SSLeay::load_error_strings();
746           Net::SSLeay::SSLeay_add_ssl_algorithms();
747           Net::SSLeay::randomize();
748
749       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
755   Convenience routines
756       To be used with Low level API
757
758           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
764           $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
768       •   randomize
769
770           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
777       •   set_cert_and_key
778
779           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
783       •   dump_peer_certificate
784
785           allows you to get a plaintext description of the certificate the
786           peer (usually the server) presented to us.
787
788       •   ssl_read_all
789
790           see ssl_write_all (below)
791
792       •   ssl_write_all
793
794           "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
801               $data = 'A' x 1000000000;
802               Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
803
804       •   ssl_read_CRLF
805
806           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
810       •   ssl_read_until
811
812           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
818       •   ssl_write_CRLF
819
820           writes $message and appends CRLF to the SSL output stream.
821
822   Initialization
823       In order to use the low level API you should start your programs with
824       the following incantation:
825
826               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
833   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
839       •   die_now
840
841       •   die_if_ssl_error
842
843           "die_now()" and "die_if_ssl_error()" are used to conveniently print
844           the SSLeay error stack when something goes wrong:
845
846                   Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
847
848
849                   Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
850
851       •   print_errs
852
853           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
858   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
865           Net::SSLeay::set_fd($ssl, fileno(S));   # Must use fileno
866
867       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
871       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
877   Callbacks
878       You can establish a per-context verify callback function something like
879       this:
880
881               sub verify {
882                   my ($ok, $x509_store_ctx) = @_;
883                   print "Verifying certificate...\n";
884                       ...
885                   return $ok;
886               }
887
888       It is used like this:
889
890               Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
891
892       Per-context callbacks for decrypting private keys are implemented.
893
894               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
900       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
904       Establish it like this:
905
906           Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb, $somedata);
907
908       It will be called like this:
909
910           sub session_secret_cb
911           {
912               my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
913           }
914
915       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
919       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
923       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
926   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
931       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
936       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
940       For example:
941
942       In C:
943
944               #include <ssl.h>
945
946               err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
947                                          &your_call_back_here);
948
949       In Perl:
950
951               use Net::SSLeay;
952
953               $err = Net::SSLeay::set_verify ($ssl,
954                                               Net::SSLeay::VERIFY_CLIENT_ONCE,
955                                               \&your_call_back_here);
956
957       If the function does not start with "SSL_" you should use the full
958       function name, e.g.:
959
960               $err = Net::SSLeay::ERR_get_error;
961
962       The following new functions behave in perlish way:
963
964               $got = Net::SSLeay::read($ssl);
965                                           # Performs SSL_read, but returns $got
966                                           # resized according to data received.
967                                           # Returns undef on failure.
968
969               Net::SSLeay::write($ssl, $foo) || die;
970                                           # Performs SSL_write, but automatically
971                                           # figures out the size of $foo
972
973       Low level API: Version and library information related functions
974
975       •   OpenSSL_version_num and SSLeay
976
977           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
981           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
985           Both functions return OPENSSL_VERSION_NUMBER constant (numeric) as
986           defined by the underlying OpenSSL or LibreSSL library.
987
988            my $ver_number = Net::SSLeay::SSLeay();
989           or
990            my $ver_number = Net::SSLeay::OpenSSL_version_num();
991            # returns: OPENSSL_VERSION_NUMBER constant
992
993            OpenSSL version numbering is:
994
995            # 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
1028            Note that OpenSSL 3.0.0 and later do not set the status nibble in the
1029            least significant octet to f.
1030
1031            LibreSSL returns 0x20000000 always:
1032
1033            # 0x20000000 => libressl-2.2.1
1034            # ...
1035            # 0x20000000 => libressl-3.4.2
1036
1037           You can use the version number like this when you know that the
1038           underlying library is OpenSSL:
1039
1040             if (Net::SSLeay::SSLeay() < 0x0090800f) {
1041               die "You need OpenSSL 0.9.8 or higher";
1042             }
1043
1044           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
1050             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
1055           Check openssl doc
1056           <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version_num.html>
1057
1058           See OpenSSL 1.1.1 and earlier documentation for the details of
1059           status nibble and the format interpretation.
1060
1061       •   SSLeay_version
1062
1063           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
1064
1065           Returns different strings depending on $type.
1066
1067            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
1077            Net::SSLeay::SSLeay_version();
1078            #is equivalent to
1079            Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
1080
1081           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
1086           Check openssl doc
1087           <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1088
1089           OpenSSL website no longer has a manual page for SSLeay_version().
1090
1091       •   OpenSSL_version
1092
1093           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
1096           Returns different strings depending on $t. Available $t constants
1097           depend on the library version.
1098
1099            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
1110            Net::SSLeay::OpenSSL_version();
1111            #is equivalent to
1112            Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1113
1114           Check openssl doc
1115           <https://www.openssl.org/docs/manmaster/man3/OpenSSL_version.html>
1116
1117       •   OPENSSL_info
1118
1119           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1120           requires at least OpenSSL 3.0.0-alpha1
1121
1122           Returns different strings depending on $t. Available $t constants
1123           depend on the library version.
1124
1125            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
1132           Check openssl doc
1133           <https://www.openssl.org/docs/manmaster/man3/OPENSSL_info.html>
1134
1135       •   OPENSSL_version_major, OPENSSL_version_minor and
1136           OPENSSL_version_patch
1137
1138           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1139           requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1140
1141           Return constants OPENSSL_VERSION_MAJOR, OPENSSL_VERSION_MINOR and
1142           OPENSSL_VERSION_PATCH, respectively.
1143
1144            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
1150           For example with OpenSSL 3.0.1, $major is 3, $minor is 0 and $patch
1151           is 1.
1152
1153           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
1159           Check openssl doc
1160           <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_major.html>
1161
1162       •   OPENSSL_version_pre_release
1163
1164           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1165           requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1166
1167           Return constant string defined by C macro
1168           OPENSSL_VERSION_PRE_RELEASE.
1169
1170            my $pre_release = Net::SSLeay::OPENSSL_version_pre_release();
1171            #
1172            # returns: string
1173
1174            For example: "-alpha3" or "" for a release version.
1175
1176           When the macro is not defined, an empty string is returned instead.
1177
1178           Check openssl doc
1179           <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_pre_release.html>
1180
1181OPENSSL_version_build_metadata()
1182
1183           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
1184           requires at least OpenSSL 3.0.0-alpha1, not in LibreSSL
1185
1186           Return constant string defined by C macro
1187           OPENSSL_VERSION_BUILD_METADATA.
1188
1189            my $metadata = Net::SSLeay::OPENSSL_version_build_metadata();
1190            #
1191            # returns: string
1192
1193            For example: "+fips" or "".
1194
1195           When the macro is not defined, an empty string is returned instead.
1196
1197           Check openssl doc
1198           <https://www.openssl.org/docs/manmaster/man3/OPENSSL_version_build_metadata.html>
1199
1200       Low level API: Initialization related functions
1201
1202       •   library_init
1203
1204           Initialize SSL library by registering algorithms.
1205
1206            my $rv = Net::SSLeay::library_init();
1207
1208           Check openssl doc
1209           <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1210
1211           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
1217       •   add_ssl_algorithms
1218
1219           The alias for "library_init"
1220
1221            Net::SSLeay::add_ssl_algorithms();
1222
1223       •   OpenSSL_add_ssl_algorithms
1224
1225           The alias for "library_init"
1226
1227            Net::SSLeay::OpenSSL_add_ssl_algorithms();
1228
1229       •   SSLeay_add_ssl_algorithms
1230
1231           The alias for "library_init"
1232
1233            Net::SSLeay::SSLeay_add_ssl_algorithms();
1234
1235       •   load_error_strings
1236
1237           Registers the error strings for all libcrypto + libssl related
1238           functions.
1239
1240            Net::SSLeay::load_error_strings();
1241            #
1242            # returns: no return value
1243
1244           Check openssl doc
1245           <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1246
1247       •   ERR_load_crypto_strings
1248
1249           Registers the error strings for all libcrypto functions. No need to
1250           call this function if you have already called "load_error_strings".
1251
1252            Net::SSLeay::ERR_load_crypto_strings();
1253            #
1254            # returns: no return value
1255
1256           Check openssl doc
1257           <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1258
1259       •   ERR_load_RAND_strings
1260
1261           Registers the error strings for RAND related functions. No need to
1262           call this function if you have already called "load_error_strings".
1263
1264            Net::SSLeay::ERR_load_RAND_strings();
1265            #
1266            # returns: no return value
1267
1268       •   ERR_load_SSL_strings
1269
1270           Registers the error strings for SSL related functions. No need to
1271           call this function if you have already called "load_error_strings".
1272
1273            Net::SSLeay::ERR_load_SSL_strings();
1274            #
1275            # returns: no return value
1276
1277       •   OpenSSL_add_all_algorithms
1278
1279           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1280
1281           Add algorithms to internal table.
1282
1283            Net::SSLeay::OpenSSL_add_all_algorithms();
1284            #
1285            # returns: no return value
1286
1287           Check openssl doc
1288           <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1289
1290       •   OPENSSL_add_all_algorithms_conf
1291
1292           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1293
1294           Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1295           config file
1296
1297            Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1298            #
1299            # returns: no return value
1300
1301       •   OPENSSL_add_all_algorithms_noconf
1302
1303           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1304
1305           Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1306           config file
1307
1308            Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1309            #
1310            # returns: no return value
1311
1312       Low level API: ERR_* and SSL_alert_* related functions
1313
1314       NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1315       from their names.
1316
1317       •   ERR_clear_error
1318
1319           Clear the error queue.
1320
1321            Net::SSLeay::ERR_clear_error();
1322            #
1323            # returns: no return value
1324
1325           Check openssl doc
1326           <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1327
1328       •   ERR_error_string
1329
1330           Generates a human-readable string representing the error code
1331           $error.
1332
1333            my $rv = Net::SSLeay::ERR_error_string($error);
1334            # $error - (unsigned integer) error code
1335            #
1336            # returns: string
1337
1338           Check openssl doc
1339           <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1340
1341       •   ERR_get_error
1342
1343           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
1347            my $rv = Net::SSLeay::ERR_get_error();
1348            #
1349            # returns: (unsigned integer) error code
1350
1351           Check openssl doc
1352           <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1353
1354       •   ERR_peek_error
1355
1356           Returns the earliest error code from the thread's error queue
1357           without modifying it.
1358
1359            my $rv = Net::SSLeay::ERR_peek_error();
1360            #
1361            # returns: (unsigned integer) error code
1362
1363           Check openssl doc
1364           <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1365
1366       •   ERR_put_error
1367
1368           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
1372            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
1381           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
1385       •   alert_desc_string
1386
1387           Returns a two letter string as a short form describing the reason
1388           of the alert specified by value.
1389
1390            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
1395           Check openssl doc
1396           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1397
1398       •   alert_desc_string_long
1399
1400           Returns a string describing the reason of the alert specified by
1401           value.
1402
1403            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
1408           Check openssl doc
1409           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1410
1411       •   alert_type_string
1412
1413           Returns a one letter string indicating the type of the alert
1414           specified by value.
1415
1416            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
1421           Check openssl doc
1422           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1423
1424       •   alert_type_string_long
1425
1426           Returns a string indicating the type of the alert specified by
1427           value.
1428
1429            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
1434           Check openssl doc
1435           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1436
1437       Low level API: SSL_METHOD_* related functions
1438
1439       •   SSLv23_method, SSLv23_server_method and SSLv23_client_method
1440
1441           COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1442
1443           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
1447           NOTE: Consider using TLS_method, TLS_server_method or
1448           TLS_client_method with new code.
1449
1450            my $rv = Net::SSLeay::SSLv2_method();
1451            #
1452            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1453
1454       •   SSLv2_method
1455
1456           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
1460            my $rv = Net::SSLeay::SSLv2_method();
1461            #
1462            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1463
1464       •   SSLv3_method
1465
1466           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
1469            my $rv = Net::SSLeay::SSLv3_method();
1470            #
1471            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1472
1473           Check openssl doc
1474           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1475
1476       •   TLSv1_method, TLSv1_server_method and TLSv1_client_method
1477
1478           COMPATIBILITY: Server and client methods not available in
1479           Net-SSLeay-1.82 and before.
1480
1481           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
1484            my $rv = Net::SSLeay::TLSv1_method();
1485            #
1486            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1487
1488           Check openssl doc
1489           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1490
1491       •   TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1492
1493           COMPATIBILITY: Server and client methods not available in
1494           Net-SSLeay-1.82 and before.
1495
1496           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
1500            my $rv = Net::SSLeay::TLSv1_1_method();
1501            #
1502            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1503
1504           Check openssl doc
1505           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1506
1507       •   TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1508
1509           COMPATIBILITY: Server and client methods not available in
1510           Net-SSLeay-1.82 and before.
1511
1512           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
1516            my $rv = Net::SSLeay::TLSv1_2_method();
1517            #
1518            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1519
1520           Check openssl doc
1521           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1522
1523       •   TLS_method, TLS_server_method and TLS_client_method
1524
1525           COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1526
1527           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
1532            my $rv = Net::SSLeay::TLS_method();
1533            #
1534            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1535
1536           Check openssl doc
1537           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1538
1539       Low level API: ENGINE_* related functions
1540
1541       •   ENGINE_load_builtin_engines
1542
1543           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1544           loading support.
1545
1546           Load all bundled ENGINEs into memory and make them visible.
1547
1548            Net::SSLeay::ENGINE_load_builtin_engines();
1549            #
1550            # returns: no return value
1551
1552           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1553
1554       •   ENGINE_register_all_complete
1555
1556           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1557           loading support.
1558
1559           Register all loaded ENGINEs for every algorithm they collectively
1560           implement.
1561
1562            Net::SSLeay::ENGINE_register_all_complete();
1563            #
1564            # returns: no return value
1565
1566           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1567
1568       •   ENGINE_set_default
1569
1570           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1571           loading support.
1572
1573           Set default engine to $e + set its flags to $flags.
1574
1575            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
1596           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1597
1598       •   ENGINE_by_id
1599
1600           Get ENGINE by its identification $id.
1601
1602           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1603           loading support.
1604
1605            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
1610           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1611
1612       Low level API: EVP_PKEY_* related functions
1613
1614       •   EVP_PKEY_copy_parameters
1615
1616           Copies the parameters from key $from to key $to.
1617
1618            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
1624           Check openssl doc
1625           <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1626
1627       •   EVP_PKEY_new
1628
1629           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1630
1631           Creates a new EVP_PKEY structure.
1632
1633            my $rv = Net::SSLeay::EVP_PKEY_new();
1634            #
1635            # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1636
1637           Check openssl doc
1638           <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1639
1640       •   EVP_PKEY_free
1641
1642           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1643
1644           Free an allocated EVP_PKEY structure.
1645
1646            Net::SSLeay::EVP_PKEY_free($pkey);
1647            # $pkey - value corresponding to openssl's EVP_PKEY structure
1648            #
1649            # returns: no return value
1650
1651           Check openssl doc
1652           <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1653
1654       •   EVP_PKEY_assign_RSA
1655
1656           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1657
1658           Set the key referenced by $pkey to $key
1659
1660           NOTE: No reference counter will be increased, i.e. $key will be
1661           freed if $pkey is freed.
1662
1663            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
1669           Check openssl doc
1670           <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1671
1672       •   EVP_PKEY_assign_EC_KEY
1673
1674           COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1675
1676           Set the key referenced by $pkey to $key
1677
1678           NOTE: No reference counter will be increased, i.e. $key will be
1679           freed if $pkey is freed.
1680
1681            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
1687           Check openssl doc
1688           <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1689
1690       •   EVP_PKEY_bits
1691
1692           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1693
1694           Returns the size of the key $pkey in bits.
1695
1696            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
1701       •   EVP_PKEY_size
1702
1703           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1704
1705           Returns the maximum size of a signature in bytes. The actual
1706           signature may be smaller.
1707
1708            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
1713           Check openssl doc
1714           <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1715
1716       •   EVP_PKEY_id
1717
1718           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1719           requires at least openssl-1.0.0
1720
1721           Returns $pkey type (integer value of corresponding NID).
1722
1723            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
1728           Example:
1729
1730            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
1734       Low level API: PEM_* related functions
1735
1736       Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1737
1738       •   PEM_read_bio_X509
1739
1740           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1741
1742           Loads PEM formatted X509 certificate via given BIO structure.
1743
1744            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
1749           Example:
1750
1751            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
1755       •   PEM_read_bio_X509_REQ
1756
1757           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1758
1759           Loads PEM formatted X509_REQ object via given BIO structure.
1760
1761            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
1766           Example:
1767
1768            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
1772       •   PEM_read_bio_DHparams
1773
1774           Reads DH structure from BIO.
1775
1776            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
1781       •   PEM_read_bio_X509_CRL
1782
1783           Reads X509_CRL structure from BIO.
1784
1785            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
1790       •   PEM_read_bio_PrivateKey
1791
1792           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1793
1794           Loads PEM formatted private key via given BIO structure.
1795
1796            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
1803           Example:
1804
1805            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
1809           To use password you have the following options:
1810
1811            $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
1816           Callback function signature:
1817
1818            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
1824              return "secret";
1825            }
1826
1827       •   PEM_X509_INFO_read_bio
1828
1829           Reads a BIO containing a PEM formatted file into a
1830           STACK_OF(X509_INFO) structure.
1831
1832            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
1837           Example:
1838
1839            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
1843       •   PEM_get_string_X509
1844
1845           NOTE: Does not exactly correspond to any low level API function
1846
1847           Converts/exports X509 certificate to string (PEM format).
1848
1849            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
1854       •   PEM_get_string_PrivateKey
1855
1856           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1857
1858           Converts public key $pk into PEM formatted string (optionally
1859           protected with password).
1860
1861            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
1868           Examples:
1869
1870            $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
1874       •   PEM_get_string_X509_CRL
1875
1876           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1877
1878           Converts X509_CRL object $x509_crl into PEM formatted string.
1879
1880            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
1885       •   PEM_get_string_X509_REQ
1886
1887           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1888
1889           Converts X509_REQ object $x509_crl into PEM formatted string.
1890
1891            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
1896       Low level API: d2i_* (DER format) related functions
1897
1898       •   d2i_X509_bio
1899
1900           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1901
1902           Loads DER formatted X509 certificate via given BIO structure.
1903
1904            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
1909           Example:
1910
1911            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
1915           Check openssl doc
1916           <http://www.openssl.org/docs/crypto/d2i_X509.html>
1917
1918       •   d2i_X509_CRL_bio
1919
1920           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1921
1922           Loads DER formatted X509_CRL object via given BIO structure.
1923
1924            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
1929           Example:
1930
1931            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
1935       •   d2i_X509_REQ_bio
1936
1937           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1938
1939           Loads DER formatted X509_REQ object via given BIO structure.
1940
1941            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
1946           Example:
1947
1948            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
1952       Low level API: PKCS12 related functions
1953
1954       •   P_PKCS12_load_file
1955
1956           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1957
1958           Loads X509 certificate + private key + certificates of CA chain (if
1959           present in PKCS12 file).
1960
1961            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
1971           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
1975           Examples:
1976
1977            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
1985            #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
1988           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
1993       Low level API: SESSION_* related functions
1994
1995       •   d2i_SSL_SESSION
1996
1997           COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1998
1999           Transforms the binary ASN1 representation string of an SSL/TLS
2000           session into an SSL_SESSION object.
2001
2002            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
2007           Check openssl doc
2008           <https://www.openssl.org/docs/ssl/i2d_SSL_SESSION.html>
2009
2010       •   i2d_SSL_SESSION
2011
2012           COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
2013
2014           Transforms the SSL_SESSION object in into the ASN1 representation
2015           and returns it as string.
2016
2017            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
2022           Check openssl doc
2023           <https://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
2024
2025       •   SESSION_new
2026
2027           Creates a new SSL_SESSION structure.
2028
2029            my $rv = Net::SSLeay::SESSION_new();
2030            #
2031            # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
2032
2033       •   SESSION_free
2034
2035           Free an allocated SSL_SESSION structure.
2036
2037            Net::SSLeay::SESSION_free($ses);
2038            # $ses - value corresponding to openssl's SSL_SESSION structure
2039            #
2040            # returns: no return value
2041
2042           Check openssl doc
2043           <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
2044
2045       •   SESSION_up_ref
2046
2047           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
2050           Increases the reference counter on a SSL_SESSION structure.
2051
2052            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
2057           Check openssl doc
2058           <https://www.openssl.org/docs/ssl/SSL_SESSION_up_ref.html>
2059
2060       •   SESSION_dup
2061
2062           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2063           requires at least OpenSSL 1.1.1, not in LibreSSL
2064
2065           Duplicates a SSL_SESSION structure.
2066
2067            Net::SSLeay::SESSION_dup($ses);
2068            # $ses - value corresponding to openssl's SSL_SESSION structure
2069            #
2070            # returns: the duplicated session
2071
2072           Check openssl doc
2073           <https://www.openssl.org/docs/ssl/SSL_SESSION_dup.html>
2074
2075       •   SESSION_is_resumable
2076
2077           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2078           requires at least OpenSSL 1.1.1, not in LibreSSL
2079
2080           Determine whether an SSL_SESSION object can be used for resumption.
2081
2082            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
2087           Check openssl doc
2088           <https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html>
2089
2090       •   SESSION_cmp
2091
2092           Compare two SSL_SESSION structures.
2093
2094            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
2100           NOTE: Not available in openssl 1.0 or later
2101
2102       •   SESSION_get_app_data
2103
2104           Can be used to get application defined value/data.
2105
2106            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
2111       •   SESSION_set_app_data
2112
2113           Can be used to set some application defined value/data.
2114
2115            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
2121       •   SESSION_get_ex_data
2122
2123           Is used to retrieve the information for $idx from session $ses.
2124
2125            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
2131           Check openssl doc
2132           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2133
2134       •   SESSION_set_ex_data
2135
2136           Is used to store application data at arg for idx into the session
2137           object.
2138
2139            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
2146           Check openssl doc
2147           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2148
2149       •   SESSION_get_ex_new_index
2150
2151           Is used to register a new index for application specific data.
2152
2153            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
2162           Check openssl doc
2163           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2164
2165       •   SESSION_get_master_key
2166
2167           NOTE: Does not exactly correspond to any low level API function
2168
2169           Returns 'master_key' value from SSL_SESSION structure $s
2170
2171            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
2176       •   SESSION_set_master_key
2177
2178           Sets 'master_key' value for SSL_SESSION structure $s
2179
2180            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
2186           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
2192       •   SESSION_get_time
2193
2194           Returns the time at which the session s was established.  The time
2195           is given in seconds since 1.1.1970.
2196
2197            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
2202           Check openssl doc
2203           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2204
2205       •   get_time
2206
2207           Technically the same functionality as "SESSION_get_time".
2208
2209            my $rv = Net::SSLeay::get_time($s);
2210
2211       •   SESSION_get_timeout
2212
2213           Returns the timeout value set for session $s in seconds.
2214
2215            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
2220           Check openssl doc
2221           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2222
2223       •   get_timeout
2224
2225           Technically the same functionality as "SESSION_get_timeout".
2226
2227            my $rv = Net::SSLeay::get_timeout($s);
2228
2229       •   SESSION_print
2230
2231           NOTE: Does not exactly correspond to any low level API function
2232
2233           Prints session details (e.g. protocol version, cipher, session-id
2234           ...) to BIO.
2235
2236            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
2242           You have to use necessary BIO functions like this:
2243
2244            # 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
2250       •   SESSION_print_fp
2251
2252           Prints session details (e.g. protocol version, cipher, session-id
2253           ...) to file handle.
2254
2255            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
2261           Example:
2262
2263            # 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
2268       •   SESSION_set_time
2269
2270           Replaces the creation time of the session s with the chosen value
2271           $t (seconds since 1.1.1970).
2272
2273            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
2279           Check openssl doc
2280           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2281
2282       •   set_time
2283
2284           Technically the same functionality as "SESSION_set_time".
2285
2286            my $rv = Net::SSLeay::set_time($ses, $t);
2287
2288       •   SESSION_set_timeout
2289
2290           Sets the timeout value for session s in seconds to $t.
2291
2292            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
2298           Check openssl doc
2299           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2300
2301       •   set_timeout
2302
2303           Technically the same functionality as "SESSION_set_timeout".
2304
2305            my $rv = Net::SSLeay::set_timeout($ses, $t);
2306
2307       Low level API: SSL_CTX_* related functions
2308
2309       NOTE: Please note that the function described in this chapter have
2310       "SSL_" part stripped from their original openssl names.
2311
2312       •   CTX_add_client_CA
2313
2314           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
2317            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
2323           Check openssl doc
2324           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2325
2326       •   CTX_add_extra_chain_cert
2327
2328           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
2332            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
2338           Check openssl doc
2339           <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2340
2341       •   CTX_add_session
2342
2343           Adds the session $ses to the context $ctx.
2344
2345            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
2351           Check openssl doc
2352           <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2353
2354       •   CTX_callback_ctrl
2355
2356           ??? (more info needed)
2357
2358            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
2365           Check openssl doc
2366           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2367
2368       •   CTX_check_private_key
2369
2370           Checks the consistency of a private key with the corresponding
2371           certificate loaded into $ctx.
2372
2373            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
2378           Check openssl doc
2379           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2380
2381       •   CTX_ctrl
2382
2383           Internal handling function for SSL_CTX objects.
2384
2385           BEWARE: openssl doc says: This function should never be called
2386           directly!
2387
2388            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
2396            #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
2464            82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2465            83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2466
2467            88 - SSL_CTRL_CHAIN
2468            89 - SSL_CTRL_CHAIN_CERT
2469
2470            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
2494           Check openssl doc
2495           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2496
2497       •   CTX_flush_sessions
2498
2499           Causes a run through the session cache of $ctx to remove sessions
2500           expired at time $tm.
2501
2502            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
2508           Check openssl doc
2509           <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2510
2511       •   CTX_free
2512
2513           Free an allocated SSL_CTX object.
2514
2515            Net::SSLeay::CTX_free($ctx);
2516            # $ctx - value corresponding to openssl's SSL_CTX structure
2517            #
2518            # returns: no return value
2519
2520           Check openssl doc
2521           <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2522
2523       •   CTX_get_app_data
2524
2525           Can be used to get application defined value/data.
2526
2527            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
2532       •   CTX_set_app_data
2533
2534           Can be used to set some application defined value/data.
2535
2536            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
2542       •   CTX_get0_param
2543
2544           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
2547           Returns the current verification parameters.
2548
2549            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
2554           Check openssl doc
2555           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2556
2557       •   CTX_get_cert_store
2558
2559           Returns the current certificate verification storage.
2560
2561            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
2566           Check openssl doc
2567           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2568
2569       •   CTX_get_client_CA_list
2570
2571           Returns the list of client CAs explicitly set for $ctx using
2572           "CTX_set_client_CA_list".
2573
2574            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
2579           Check openssl doc
2580           <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2581
2582       •   CTX_get_ex_data
2583
2584           Is used to retrieve the information for index $idx from $ctx.
2585
2586            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
2592           Check openssl doc
2593           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2594
2595       •   CTX_get_ex_new_index
2596
2597           Is used to register a new index for application specific data.
2598
2599            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
2608           Check openssl doc
2609           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2610
2611       •   CTX_get_mode
2612
2613           Returns the mode set for ctx.
2614
2615            my $rv = Net::SSLeay::CTX_get_mode($ctx);
2616            # $ctx - value corresponding to openssl's SSL_CTX structure
2617            #
2618            # returns: mode (bitmask)
2619
2620            #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
2628           Check openssl doc
2629           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2630
2631       •   CTX_set_mode
2632
2633           Adds the mode set via bitmask in $mode to $ctx. Options already set
2634           before are not cleared.
2635
2636            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
2642           For bitmask details see "CTX_get_mode" (above).
2643
2644           Check openssl doc
2645           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2646
2647       •   CTX_get_options
2648
2649           Returns the options (bitmask) set for $ctx.
2650
2651            my $rv = Net::SSLeay::CTX_get_options($ctx);
2652            # $ctx - value corresponding to openssl's SSL_CTX structure
2653            #
2654            # returns: options (bitmask)
2655
2656           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
2664           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
2668            #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
2676           Check openssl doc
2677           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_options.html>
2678
2679       •   CTX_set_options
2680
2681           Adds the options set via bitmask in $options to ctx. Options
2682           already set before are not cleared.
2683
2684            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
2690           For bitmask details see "CTX_get_options" (above).
2691
2692           Check openssl doc
2693           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_options.html>
2694
2695       •   CTX_get_quiet_shutdown
2696
2697           Returns the 'quiet shutdown' setting of $ctx.
2698
2699            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
2704           Check openssl doc
2705           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2706
2707       •   CTX_get_read_ahead
2708
2709            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
2714       •   CTX_get_session_cache_mode
2715
2716           Returns the currently used cache mode (bitmask).
2717
2718            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
2723           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
2729            #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
2738           Check openssl doc
2739           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2740
2741       •   CTX_set_session_cache_mode
2742
2743           Enables/disables session caching by setting the operational mode
2744           for $ctx to $mode.
2745
2746            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
2752           For bitmask details see "CTX_get_session_cache_mode" (above).
2753
2754           Check openssl doc
2755           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2756
2757       •   CTX_get_timeout
2758
2759           Returns the currently set timeout value for $ctx.
2760
2761            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
2766           Check openssl doc
2767           <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2768
2769       •   CTX_get_verify_depth
2770
2771           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
2775            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
2780           Check openssl doc
2781           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2782
2783       •   CTX_get_verify_mode
2784
2785           Returns the verification mode (bitmask) currently set in $ctx.
2786
2787            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
2792           For bitmask details see "CTX_set_verify".
2793
2794           Check openssl doc
2795           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_verify_mode.html>
2796
2797       •   CTX_set_verify
2798
2799           Sets the verification flags for $ctx to be $mode and specifies the
2800           verify_callback function to be used.
2801
2802            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
2809           Check openssl doc
2810           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html>
2811
2812       •   CTX_set_post_handshake_auth
2813
2814           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2815           requires at least OpenSSL 1.1.1, not in LibreSSL
2816
2817           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
2821            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
2827           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
2831       •   CTX_load_verify_locations
2832
2833           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
2837            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
2844           Check openssl doc
2845           <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2846
2847       •   CTX_need_tmp_RSA
2848
2849           Return the result of
2850           "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2851
2852            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
2857           Not available with OpenSSL 1.1 and later.
2858
2859       •   CTX_new
2860
2861           The same as "CTX_v23_new"
2862
2863            my $rv = Net::SSLeay::CTX_new();
2864            #
2865            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2866
2867           Check openssl doc
2868           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2869
2870           Not available with OpenSSL 1.1 and later.
2871
2872       •   CTX_v2_new
2873
2874           Creates a new SSL_CTX object - based on SSLv2_method() - as
2875           framework to establish TLS/SSL enabled connections.
2876
2877            my $rv = Net::SSLeay::CTX_v2_new();
2878            #
2879            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2880
2881       •   CTX_v23_new
2882
2883           Creates a new SSL_CTX object - based on SSLv23_method() - as
2884           framework to establish TLS/SSL enabled connections.
2885
2886            my $rv = Net::SSLeay::CTX_v23_new();
2887            #
2888            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2889
2890       •   CTX_v3_new
2891
2892           Creates a new SSL_CTX object - based on SSLv3_method() - as
2893           framework to establish TLS/SSL enabled connections.
2894
2895            my $rv = Net::SSLeay::CTX_v3_new();
2896            #
2897            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2898
2899       •   CTX_tlsv1_new
2900
2901           Creates a new SSL_CTX object - based on TLSv1_method() - as
2902           framework to establish TLS/SSL enabled connections.
2903
2904            my $rv = Net::SSLeay::CTX_tlsv1_new();
2905            #
2906            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2907
2908       •   CTX_tlsv1_1_new
2909
2910           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
2914            my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2915            #
2916            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2917
2918       •   CTX_tlsv1_2_new
2919
2920           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
2924            my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2925            #
2926            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2927
2928       •   CTX_new_with_method
2929
2930           Creates a new SSL_CTX object based on $meth method
2931
2932            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
2937            #example
2938            my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2939
2940           Check openssl doc
2941           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2942
2943       •   CTX_set_min_proto_version, CTX_set_max_proto_version,
2944           set_min_proto_version and set_max_proto_version,
2945
2946           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
2949           Set the minimum and maximum supported protocol for $ctx or $ssl.
2950
2951            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
2957            #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
2961            #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
2965           Check openssl doc
2966           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2967
2968       •   CTX_get_min_proto_version, CTX_get_max_proto_version,
2969           get_min_proto_version and get_max_proto_version,
2970
2971           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2972           requires at least OpenSSL 1.1.0g
2973
2974           Get the minimum and maximum supported protocol for $ctx or $ssl.
2975
2976            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
2981           Check openssl doc
2982           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2983
2984       •   CTX_remove_session
2985
2986           Removes the session $ses from the context $ctx.
2987
2988            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
2994           Check openssl doc
2995           <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2996
2997       •   CTX_sess_accept
2998
2999            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
3004           Check openssl doc
3005           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3006
3007       •   CTX_sess_accept_good
3008
3009            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
3014           Check openssl doc
3015           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3016
3017       •   CTX_sess_accept_renegotiate
3018
3019            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
3024           Check openssl doc
3025           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3026
3027       •   CTX_sess_cache_full
3028
3029            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
3034           Check openssl doc
3035           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3036
3037       •   CTX_sess_cb_hits
3038
3039            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
3044           Check openssl doc
3045           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3046
3047       •   CTX_sess_connect
3048
3049            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
3054           Check openssl doc
3055           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3056
3057       •   CTX_sess_connect_good
3058
3059            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
3064           Check openssl doc
3065           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3066
3067       •   CTX_sess_connect_renegotiate
3068
3069            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
3074           Check openssl doc
3075           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3076
3077       •   CTX_sess_get_cache_size
3078
3079           Returns the currently valid session cache size.
3080
3081            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
3086           Check openssl doc
3087           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3088
3089       •   CTX_sess_hits
3090
3091            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
3096           Check openssl doc
3097           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3098
3099       •   CTX_sess_misses
3100
3101            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
3106           Check openssl doc
3107           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3108
3109       •   CTX_sess_number
3110
3111            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
3116           Check openssl doc
3117           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3118
3119       •   CTX_sess_set_cache_size
3120
3121           Sets the size of the internal session cache of context $ctx to
3122           $size.
3123
3124            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
3130           Check openssl doc
3131           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
3132
3133       •   CTX_sess_timeouts
3134
3135           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
3140            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
3145           Check openssl doc
3146           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
3147
3148       •   CTX_sess_set_new_cb
3149
3150           COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3151
3152           Sets the callback function, which is automatically called whenever
3153           a new session was negotiated.
3154
3155            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
3161           Check openssl doc
3162           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html>
3163
3164       •   CTX_sess_set_remove_cb
3165
3166           COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3167
3168           Sets the callback function, which is automatically called whenever
3169           a session is removed by the SSL engine.
3170
3171            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
3177           Check openssl doc
3178           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_remove_cb.html>
3179
3180       •   CTX_sessions
3181
3182           Returns a pointer to the lhash databases containing the internal
3183           session cache for ctx.
3184
3185            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
3190           Check openssl doc
3191           <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
3192
3193       •   CTX_set1_param
3194
3195           COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
3196
3197           Applies X509 verification parameters $vpm on $ctx
3198
3199            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
3205           Check openssl doc
3206           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3207
3208       •   CTX_set_cert_store
3209
3210           Sets/replaces the certificate verification storage of $ctx to/with
3211           $store.
3212
3213            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
3219           Check openssl doc
3220           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
3221
3222       •   CTX_set_cert_verify_callback
3223
3224           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
3228            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
3235           Check openssl doc
3236           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
3237
3238       •   CTX_set_cipher_list
3239
3240           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
3244            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
3250           The format of $str is described in
3251           <https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html>
3252
3253           Check openssl doc
3254           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_cipher_list.html>
3255
3256       •   CTX_set_ciphersuites
3257
3258           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3259           requires at least OpenSSL 1.1.1, not in LibreSSL
3260
3261           Configure the available TLSv1.3 ciphersuites.
3262
3263            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
3269           Check openssl doc
3270           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html>
3271
3272       •   CTX_set_client_CA_list
3273
3274           Sets the list of CAs sent to the client when requesting a client
3275           certificate for $ctx.
3276
3277            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
3283           Check openssl doc
3284           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3285
3286       •   CTX_set_default_passwd_cb
3287
3288           Sets the default password callback called when loading/storing a
3289           PEM certificate with encryption.
3290
3291            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
3297           Check openssl doc
3298           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3299
3300       •   CTX_set_default_passwd_cb_userdata
3301
3302           Sets a pointer to userdata which will be provided to the password
3303           callback on invocation.
3304
3305            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
3311           Check openssl doc
3312           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3313
3314       •   CTX_set_default_verify_paths
3315
3316           ??? (more info needed)
3317
3318            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
3323       •   CTX_set_ex_data
3324
3325           Is used to store application data at $data for $idx into the $ctx
3326           object.
3327
3328            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
3335           Check openssl doc
3336           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3337
3338       •   CTX_set_purpose
3339
3340            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
3346            #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
3357            #or use corresponding constants
3358            $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3359            ...
3360            $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3361
3362       •   CTX_set_quiet_shutdown
3363
3364           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
3368            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
3374           Check openssl doc
3375           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3376
3377       •   CTX_set_read_ahead
3378
3379            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
3385       •   CTX_set_session_id_context
3386
3387           Sets the context $sid_ctx of length $sid_ctx_len within which a
3388           session can be reused for the $ctx object.
3389
3390            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
3397           Check openssl doc
3398           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3399
3400       •   CTX_set_ssl_version
3401
3402           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
3407            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
3413           Check openssl doc
3414           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3415
3416       •   CTX_set_timeout
3417
3418           Sets the timeout for newly created sessions for $ctx to $t. The
3419           timeout value $t must be given in seconds.
3420
3421            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
3427           Check openssl doc
3428           <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3429
3430       •   CTX_set_tmp_dh
3431
3432           Sets DH parameters to be used to be $dh. The key is inherited by
3433           all ssl objects created from $ctx.
3434
3435            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
3441           Check openssl doc
3442           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3443
3444       •   CTX_set_tmp_dh_callback
3445
3446           Sets the callback function for $ctx to be used when a DH parameters
3447           are required to $tmp_dh_callback.
3448
3449            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
3455           Check openssl doc
3456           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3457
3458       •   CTX_set_tmp_rsa
3459
3460           Sets the temporary/ephemeral RSA key to be used to be $rsa.
3461
3462            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
3468           Check openssl doc
3469           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3470
3471           Not available with OpenSSL 1.1 and later.
3472
3473       •   CTX_set_tmp_rsa_callback
3474
3475           Sets the callback function for ctx to be used when a
3476           temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3477
3478           ??? (does this function really work?)
3479
3480            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
3486           Check openssl doc
3487           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3488
3489           Not available with OpenSSL 1.1 and later.
3490
3491       •   CTX_set_trust
3492
3493            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
3499            #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
3509            #or use corresponding constants
3510            $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3511            ...
3512            $trust = &Net::SSLeay::X509_TRUST_TSA;
3513
3514       •   CTX_set_verify_depth
3515
3516           Sets the maximum depth for the certificate chain verification that
3517           shall be allowed for ctx.
3518
3519            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
3525           Check openssl doc
3526           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3527
3528       •   CTX_use_PKCS12_file
3529
3530           Adds the certificate and private key from PKCS12 file $p12filename
3531           to $ctx.
3532
3533            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
3540       •   CTX_use_PrivateKey
3541
3542           Adds the private key $pkey to $ctx.
3543
3544            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
3550           Check openssl doc
3551           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3552
3553       •   CTX_use_PrivateKey_file
3554
3555           Adds the first private key found in $file to $ctx.
3556
3557            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
3564           Check openssl doc
3565           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3566
3567       •   CTX_use_RSAPrivateKey
3568
3569           Adds the RSA private key $rsa to $ctx.
3570
3571            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
3577           Check openssl doc
3578           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3579
3580       •   CTX_use_RSAPrivateKey_file
3581
3582           Adds the first RSA private key found in $file to $ctx.
3583
3584            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
3591       •   CTX_use_certificate
3592
3593           Loads the certificate $x into $ctx
3594
3595            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
3601           Check openssl doc
3602           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3603
3604       •   CTX_use_certificate_chain_file
3605
3606           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
3612            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
3618           Check openssl doc
3619           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3620
3621       •   CTX_use_certificate_file
3622
3623           Loads the first certificate stored in $file into $ctx.
3624
3625            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
3632           Check openssl doc
3633           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3634
3635       •   CTX_get_security_level
3636
3637           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3638           requires at least OpenSSL 1.1.0, not in LibreSSL
3639
3640           Returns the security level associated with $ctx.
3641
3642            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
3647           Check openssl doc
3648           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html>
3649
3650       •   CTX_set_security_level
3651
3652           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3653           requires at least OpenSSL 1.1.0, not in LibreSSL
3654
3655           Sets the security level associated with $ctx to $level.
3656
3657            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
3663           Check openssl doc
3664           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html>
3665
3666       •   CTX_set_num_tickets
3667
3668           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3669           requires at least OpenSSL 1.1.1, not in LibreSSL
3670
3671           Set number of TLSv1.3 session tickets that will be sent to a
3672           client.
3673
3674            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
3680           Set to zero if you do not no want to support a session resumption.
3681
3682           Check openssl doc
3683           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html>
3684
3685       •   CTX_get_num_tickets
3686
3687           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3688           requires at least OpenSSL 1.1.1, not in LibreSSL
3689
3690           Get number of TLSv1.3 session tickets that will be sent to a
3691           client.
3692
3693            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
3698           Check openssl doc
3699           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_num_tickets.html>
3700
3701       •   CTX_set_keylog_callback
3702
3703           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3704           requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3705
3706           Set the TLS key logging callback.
3707
3708            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
3714           The callback function will be called like this:
3715
3716            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
3720           Check openssl doc
3721           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_keylog_callback.html>
3722
3723       •   CTX_get_keylog_callback
3724
3725           COMPATIBILITY: not available in Net-SSLeay-1.90 and before;
3726           requires at least OpenSSL 1.1.1pre1, not in LibreSSL
3727
3728           Retrieve the previously set TLS key logging callback.
3729
3730            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
3735           Check openssl doc
3736           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_keylog_callback.html>
3737
3738       Low level API: SSL_* related functions
3739
3740       NOTE: Please note that the function described in this chapter have
3741       "SSL_" part stripped from their original openssl names.
3742
3743       •   new
3744
3745           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
3750            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
3755           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3756
3757       •   accept
3758
3759           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
3763            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
3768           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3769
3770       •   add_client_CA
3771
3772           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
3776            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
3782           Check openssl doc
3783           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3784
3785       •   callback_ctrl
3786
3787           ??? (more info needed)
3788
3789            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
3796           Check openssl doc
3797           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3798
3799       •   check_private_key
3800
3801           Checks the consistency of a private key with the corresponding
3802           certificate loaded into $ssl
3803
3804            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
3809           Check openssl doc
3810           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3811
3812       •   clear
3813
3814           Reset SSL object to allow another connection.
3815
3816            Net::SSLeay::clear($ssl);
3817            # $ssl - value corresponding to openssl's SSL structure
3818            #
3819            # returns: no return value
3820
3821           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3822
3823       •   connect
3824
3825           Initiate the TLS/SSL handshake with an TLS/SSL server.
3826
3827            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
3832           Check openssl doc
3833           <http://www.openssl.org/docs/ssl/SSL_connect.html>
3834
3835       •   copy_session_id
3836
3837           Copies the session structure fro $from to $to (+ also the private
3838           key and certificate associated with $from).
3839
3840            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
3846       •   ctrl
3847
3848           Internal handling function for SSL objects.
3849
3850           BEWARE: openssl doc says: This function should never be called
3851           directly!
3852
3853            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
3861           For more details about valid $cmd values check "CTX_ctrl".
3862
3863           Check openssl doc
3864           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3865
3866       •   do_handshake
3867
3868           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
3873            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
3878           Check openssl doc
3879           <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3880
3881       •   dup
3882
3883           Returns a duplicate of $ssl.
3884
3885            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
3890       •   free
3891
3892           Free an allocated SSL structure.
3893
3894            Net::SSLeay::free($ssl);
3895            # $ssl - value corresponding to openssl's SSL structure
3896            #
3897            # returns: no return value
3898
3899           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3900
3901       •   get0_param
3902
3903           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
3906           Returns the current verification parameters.
3907
3908            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
3913           Check openssl doc
3914           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3915
3916       •   get_SSL_CTX
3917
3918           Returns a pointer to the SSL_CTX object, from which $ssl was
3919           created with Net::SSLeay::new.
3920
3921            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
3926           Check openssl doc
3927           <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3928
3929       •   set_SSL_CTX
3930
3931           COMPATIBILITY: requires at least OpenSSL 0.9.8f
3932
3933           Sets the SSL_CTX the corresponds to an SSL session.
3934
3935            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
3941       •   get_app_data
3942
3943           Can be used to get application defined value/data.
3944
3945            my $rv = Net::SSLeay::get_app_data($ssl);
3946            # $ssl - value corresponding to openssl's SSL structure
3947            #
3948            # returns: string/buffer/pointer ???
3949
3950       •   set_app_data
3951
3952           Can be used to set some application defined value/data.
3953
3954            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
3960       •   get_certificate
3961
3962           Gets X509 certificate from an established SSL connection.
3963
3964            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
3969       •   get_cipher
3970
3971           Obtains the name of the currently used cipher.
3972
3973            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
3978           Check openssl doc
3979           <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3980
3981       •   get_cipher_bits
3982
3983           Obtain the number of secret/algorithm bits used.
3984
3985            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
3990           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
3994       •   get_ciphers
3995
3996           COMPATIBILITY: not available in Net-SSLeay-1.88 and before
3997
3998           Returns a list of SSL_CIPHER structures available for $ssl sorted
3999           by preference
4000
4001            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
4006           Example:
4007
4008            my @ciphers = Net::SSLeay::get_ciphers($ssl);
4009            foreach my $c (@ciphers) {
4010              print Net::SSLeay::CIPHER_get_name($c) . "\n";
4011            }
4012
4013           Check openssl doc
4014           <https://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
4015
4016       •   get_cipher_list
4017
4018           Returns the name (string) of the SSL_CIPHER listed for $ssl with
4019           priority $n.
4020
4021            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
4027           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
4031            my $priority = 0;
4032            while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
4033              print "cipher[$priority] = $c\n";
4034              $priority++;
4035            }
4036
4037           Check openssl doc
4038           <https://www.openssl.org/docs/ssl/SSL_get_cipher_list.html>
4039
4040       •   get_client_CA_list
4041
4042           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
4046           In client mode, returns the list of client CAs sent from the
4047           server, if any.
4048
4049            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
4054           Check openssl doc
4055           <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
4056
4057       •   get_current_cipher
4058
4059           Returns the cipher actually used.
4060
4061            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
4066           Check openssl doc
4067           <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
4068
4069       •   get_default_timeout
4070
4071           Returns the default timeout value assigned to SSL_SESSION objects
4072           negotiated for the protocol valid for $ssl.
4073
4074            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
4079           Check openssl doc
4080           <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
4081
4082       •   get_error
4083
4084           Returns a result code for a preceding call to "connect", "accept",
4085           "do_handshake", "read", "peek" or "write" on $ssl.
4086
4087            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
4102           Check openssl doc
4103           <http://www.openssl.org/docs/ssl/SSL_get_error.html>
4104
4105       •   get_ex_data
4106
4107           Is used to retrieve the information for $idx from $ssl.
4108
4109            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
4115           Check openssl doc
4116           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4117
4118       •   set_ex_data
4119
4120           Is used to store application data at $data for $idx into the $ssl
4121           object.
4122
4123            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
4130           Check openssl doc
4131           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4132
4133       •   get_ex_new_index
4134
4135           Is used to register a new index for application specific data.
4136
4137            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
4146           Check openssl doc
4147           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
4148
4149       •   get_fd
4150
4151           Returns the file descriptor which is linked to $ssl.
4152
4153            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
4158           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
4159
4160       •   get_finished
4161
4162           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
4168            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
4175       •   get_peer_finished
4176
4177           Obtains the latest 'Finished' message expected from the peer.
4178           Parameters and return value are similar to get_finished().
4179
4180            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
4187       •   get_keyblock_size
4188
4189           Gets the length of the TLS keyblock.
4190
4191           NOTE: Does not exactly correspond to any low level API function.
4192
4193            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
4198       •   get_mode
4199
4200           Returns the mode (bitmask) set for $ssl.
4201
4202            my $rv = Net::SSLeay::get_mode($ssl);
4203            # $ssl - value corresponding to openssl's SSL structure
4204            #
4205            # returns: mode (bitmask)
4206
4207           To decode the return value (bitmask) see documentation for
4208           "CTX_get_mode".
4209
4210           Check openssl doc
4211           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4212
4213       •   set_mode
4214
4215           Adds the mode set via bitmask in $mode to $ssl. Options already set
4216           before are not cleared.
4217
4218            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
4224           For $mode bitmask details see "CTX_get_mode".
4225
4226           Check openssl doc
4227           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4228
4229       •   get_options
4230
4231           Returns the options (bitmask) set for $ssl.
4232
4233            my $rv = Net::SSLeay::get_options($ssl);
4234            # $ssl - value corresponding to openssl's SSL structure
4235            #
4236            # returns: options (bitmask)
4237
4238           To decode the return value (bitmask) see documentation for
4239           "CTX_get_options".
4240
4241           Check openssl doc
4242           <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4243
4244       •   set_options
4245
4246           Adds the options set via bitmask in $options to $ssl. Options
4247           already set before are not cleared!
4248
4249            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
4255           For $options bitmask details see "CTX_get_options".
4256
4257           Check openssl doc
4258           <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4259
4260       •   get_peer_certificate
4261
4262           Get the X509 certificate of the peer.
4263
4264            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
4269           Check openssl doc
4270           <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4271
4272       •   get_peer_cert_chain
4273
4274           Get the certificate chain of the peer as an array of X509
4275           structures.
4276
4277            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
4282           Check openssl doc
4283           <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4284
4285       •   get_quiet_shutdown
4286
4287           Returns the 'quiet shutdown' setting of ssl.
4288
4289            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
4294           Check openssl doc
4295           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4296
4297       •   get_rbio
4298
4299           Get 'read' BIO linked to an SSL object $ssl.
4300
4301            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
4306           Check openssl doc
4307           <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4308
4309       •   get_read_ahead
4310
4311            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
4316       •   set_read_ahead
4317
4318            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
4324       •   get_security_level
4325
4326           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4327           requires at least OpenSSL 1.1.0, not in LibreSSL
4328
4329           Returns the security level associated with $ssl.
4330
4331            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
4336           Check openssl doc
4337           <https://www.openssl.org/docs/manmaster/man3/SSL_get_security_level.html>
4338
4339       •   set_security_level
4340
4341           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4342           requires at least OpenSSL 1.1.0, not in LibreSSL
4343
4344           Sets the security level associated with $ssl to $level.
4345
4346            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
4352           Check openssl doc
4353           <https://www.openssl.org/docs/manmaster/man3/SSL_set_security_level.html>
4354
4355       •   set_num_tickets
4356
4357           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4358           requires at least OpenSSL 1.1.1, not in LibreSSL
4359
4360           Set number of TLSv1.3 session tickets that will be sent to a
4361           client.
4362
4363            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
4369           Set to zero if you do not no want to support a session resumption.
4370
4371           Check openssl doc
4372           <https://www.openssl.org/docs/manmaster/man3/SSL_set_num_tickets.html>
4373
4374       •   get_num_tickets
4375
4376           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4377           requires at least OpenSSL 1.1.1, not in LibreSSL
4378
4379           Get number of TLSv1.3 session tickets that will be sent to a
4380           client.
4381
4382            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
4387           Check openssl doc
4388           <https://www.openssl.org/docs/manmaster/man3/SSL_get_num_tickets.html>
4389
4390       •   get_server_random
4391
4392           Returns internal SSLv3 server_random value.
4393
4394            Net::SSLeay::get_server_random($ssl);
4395            # $ssl - value corresponding to openssl's SSL structure
4396            #
4397            # returns: server_random value (binary data)
4398
4399       •   get_client_random
4400
4401           NOTE: Does not exactly correspond to any low level API function
4402
4403           Returns internal SSLv3 client_random value.
4404
4405            Net::SSLeay::get_client_random($ssl);
4406            # $ssl - value corresponding to openssl's SSL structure
4407            #
4408            # returns: client_random value (binary data)
4409
4410       •   export_keying_material
4411
4412           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
4417             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
4425           Check openssl doc
4426           <https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html>
4427
4428       •   get_session
4429
4430           Retrieve TLS/SSL session data used in $ssl. The reference count of
4431           the SSL_SESSION is NOT incremented.
4432
4433            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
4438           Check openssl doc
4439           <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4440
4441       •   SSL_get0_session
4442
4443           The alias for "get_session" (note that the name is
4444           "SSL_get0_session" NOT "get0_session").
4445
4446            my $rv = Net::SSLeay::SSL_get0_session();
4447
4448       •   get1_session
4449
4450           Returns a pointer to the SSL_SESSION actually used in $ssl. The
4451           reference count of the SSL_SESSION is incremented by 1.
4452
4453            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
4458           Check openssl doc
4459           <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4460
4461       •   get_shared_ciphers
4462
4463           Returns string with a list (colon ':' separated) of ciphers shared
4464           between client and server within SSL session $ssl.
4465
4466            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
4470       •   get_shutdown
4471
4472           Returns the shutdown mode of $ssl.
4473
4474            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
4479            #to decode the return value (bitmask) use:
4480            0 - No shutdown setting, yet
4481            1 - SSL_SENT_SHUTDOWN
4482            2 - SSL_RECEIVED_SHUTDOWN
4483
4484           Check openssl doc
4485           <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4486
4487       •   get_ssl_method
4488
4489           Returns a function pointer to the TLS/SSL method set in $ssl.
4490
4491            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
4496           Check openssl doc
4497           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4498
4499       •   in_init, in_before, is_init_finished, in_connect_init,
4500           in_accept_init
4501
4502           COMPATIBILITY: not available in Net-SSLeay-1.85 and before.
4503
4504           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
4508            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
4513           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
4516       •   get_state
4517
4518           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
4522           Returns the SSL connection state.
4523
4524            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
4534       •   state
4535
4536           Exactly the same as "get_state".
4537
4538            my $rv = Net::SSLeay::state($ssl);
4539
4540       •   set_state
4541
4542           Sets the SSL connection state.
4543
4544            Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4545
4546           Not available with OpenSSL 1.1 and later.
4547
4548       •   get_verify_depth
4549
4550           Returns the verification depth limit currently set in $ssl.
4551
4552            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
4557           Check openssl doc
4558           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4559
4560       •   set_verify_depth
4561
4562           Sets the maximum depth for the certificate chain verification that
4563           shall be allowed for $ssl.
4564
4565            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
4571           Check openssl doc
4572           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4573
4574       •   get_verify_mode
4575
4576           Returns the verification mode (bitmask) currently set in $ssl.
4577
4578            my $rv = Net::SSLeay::get_verify_mode($ssl);
4579            # $ssl - value corresponding to openssl's SSL structure
4580            #
4581            # returns: mode (bitmask)
4582
4583           To decode the return value (bitmask) see documentation for
4584           "CTX_get_verify_mode".
4585
4586           Check openssl doc
4587           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4588
4589       •   set_verify
4590
4591           Sets the verification flags for $ssl to be $mode and specifies the
4592           $verify_callback function to be used.
4593
4594            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
4601           For $mode bitmask details see "CTX_get_verify_mode".
4602
4603           Check openssl doc
4604           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4605
4606       •   set_post_handshake_auth
4607
4608           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4609           requires at least OpenSSL 1.1.1, not in LibreSSL
4610
4611           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
4615            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
4621           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
4625       •   verify_client_post_handshake
4626
4627           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4628           requires at least OpenSSL 1.1.1, not in LibreSSL
4629
4630           verify_client_post_handshake causes a CertificateRequest message to
4631           be sent by a server on the given ssl connection.
4632
4633            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
4638           Check openssl doc
4639           <https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html>
4640
4641       •   get_verify_result
4642
4643           Returns the result of the verification of the X509 certificate
4644           presented by the peer, if any.
4645
4646            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
4684           Check openssl doc
4685           <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4686
4687       •   set_verify_result
4688
4689           Override result of peer certificate verification.
4690
4691            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
4697           For more info about valid return values see "get_verify_result"
4698
4699           Check openssl doc
4700           <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4701
4702       •   get_wbio
4703
4704           Get 'write' BIO linked to an SSL object $ssl.
4705
4706            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
4711           Check openssl doc
4712           <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4713
4714       •   load_client_CA_file
4715
4716           Load X509 certificates from file (PEM formatted).
4717
4718            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
4723           Check openssl doc
4724           <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4725
4726       •   clear_num_renegotiations
4727
4728           Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4729
4730            my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4731            # $ssl - value corresponding to openssl's SSL structure
4732            #
4733            # returns: command result
4734
4735       •   need_tmp_RSA
4736
4737           Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4738
4739            my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4740            # $ssl - value corresponding to openssl's SSL structure
4741            #
4742            # returns: command result
4743
4744           Not available with OpenSSL 1.1 and later.
4745
4746       •   num_renegotiations
4747
4748           Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4749
4750            my $rv = Net::SSLeay::num_renegotiations($ssl);
4751            # $ssl - value corresponding to openssl's SSL structure
4752            #
4753            # returns: command result
4754
4755       •   total_renegotiations
4756
4757           Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4758
4759            my $rv = Net::SSLeay::total_renegotiations($ssl);
4760            # $ssl - value corresponding to openssl's SSL structure
4761            #
4762            # returns: command result
4763
4764       •   peek
4765
4766           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
4770            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
4778       •   peek_ex
4779
4780           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4781           requires at least OpenSSL 1.1.1, not in LibreSSL
4782
4783           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
4787            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
4794           Check openssl doc
4795           <https://www.openssl.org/docs/manmaster/man3/SSL_peek_ex.html>
4796
4797       •   pending
4798
4799           Obtain number of readable bytes buffered in $ssl object.
4800
4801            my $rv = Net::SSLeay::pending($ssl);
4802            # $ssl - value corresponding to openssl's SSL structure
4803            #
4804            # returns: the number of bytes pending
4805
4806           Check openssl doc
4807           <http://www.openssl.org/docs/ssl/SSL_pending.html>
4808
4809       •   has_pending
4810
4811           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4812           requires at least OpenSSL 1.1.0, not in LibreSSL
4813
4814           Returns 1 if $ssl has buffered data (whether processed or
4815           unprocessed) and 0 otherwise.
4816
4817            my $rv = Net::SSLeay::has_pending($ssl);
4818            # $ssl - value corresponding to openssl's SSL structure
4819            #
4820            # returns: (integer) 1 or 0
4821
4822           Check openssl doc
4823           <https://www.openssl.org/docs/manmaster/man3/SSL_has_pending.html>
4824
4825       •   read
4826
4827           Tries to read $max bytes from the specified $ssl.
4828
4829            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
4839           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4840
4841       •   read_ex
4842
4843           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4844           requires at least OpenSSL 1.1.1, not in LibreSSL
4845
4846           Tries to read $max bytes from the specified $ssl.
4847
4848            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
4855           Check openssl doc
4856           <https://www.openssl.org/docs/manmaster/man3/SSL_read_ex.html>
4857
4858       •   renegotiate
4859
4860           Turn on flags for renegotiation so that renegotiation will happen
4861
4862            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
4867       •   rstate_string
4868
4869           Returns a 2 letter string indicating the current read state of the
4870           SSL object $ssl.
4871
4872            my $rv = Net::SSLeay::rstate_string($ssl);
4873            # $ssl - value corresponding to openssl's SSL structure
4874            #
4875            # returns: 2-letter string
4876
4877           Check openssl doc
4878           <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4879
4880       •   rstate_string_long
4881
4882           Returns a string indicating the current read state of the SSL
4883           object ssl.
4884
4885            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
4890           Check openssl doc
4891           <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4892
4893       •   session_reused
4894
4895           Query whether a reused session was negotiated during handshake.
4896
4897            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
4902           Check openssl doc
4903           <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4904
4905       •   set1_param
4906
4907           COMPATIBILITY: requires at least OpenSSL 1.0.0-beta3
4908
4909           Applies X509 verification parameters $vpm on $ssl
4910
4911            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
4917       •   set_accept_state
4918
4919           Sets $ssl to work in server mode.
4920
4921            Net::SSLeay::set_accept_state($ssl);
4922            # $ssl - value corresponding to openssl's SSL structure
4923            #
4924            # returns: no return value
4925
4926           Check openssl doc
4927           <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4928
4929       •   set_bio
4930
4931           Connects the BIOs $rbio and $wbio for the read and write operations
4932           of the TLS/SSL (encrypted) side of $ssl.
4933
4934            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
4941           Check openssl doc
4942           <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4943
4944       •   set_cipher_list
4945
4946           Sets the list of ciphers only for ssl.
4947
4948            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
4954           Check openssl doc
4955           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4956
4957       •   set_ciphersuites
4958
4959           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4960           requires at least OpenSSL 1.1.1, not in LibreSSL
4961
4962           Configure the available TLSv1.3 ciphersuites.
4963
4964            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
4970           Check openssl doc
4971           <https://www.openssl.org/docs/manmaster/man3/SSL_set_ciphersuites.html>
4972
4973       •   set_client_CA_list
4974
4975           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
4979            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
4985           Check openssl doc
4986           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4987
4988       •   set_connect_state
4989
4990           Sets $ssl to work in client mode.
4991
4992            Net::SSLeay::set_connect_state($ssl);
4993            # $ssl - value corresponding to openssl's SSL structure
4994            #
4995            # returns: no return value
4996
4997           Check openssl doc
4998           <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4999
5000       •   set_fd
5001
5002           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
5006            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
5012           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5013
5014       •   set_psk_client_callback
5015
5016           Sets the psk client callback.
5017
5018            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
5026           Check openssl doc
5027           <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
5028
5029       •   set_rfd
5030
5031           Sets the file descriptor $fd as the input (read) facility for the
5032           TLS/SSL (encrypted) side of $ssl.
5033
5034            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
5040           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5041
5042       •   set_wfd
5043
5044            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
5050           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
5051
5052       •   set_info_callback
5053
5054           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
5059            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
5065           Check openssl doc
5066           <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5067
5068       •   CTX_set_info_callback
5069
5070           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
5074            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
5080           Check openssl doc
5081           <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
5082
5083       •   set_msg_callback
5084
5085           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
5092            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
5098           Check openssl doc
5099           <http://www.openssl.org/docs/manmaster/man3/SSL_set_msg_callback.html>
5100
5101       •   CTX_set_msg_callback
5102
5103           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
5110            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
5116           Check openssl doc
5117           <http://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_msg_callback.html>
5118
5119       •   set_pref_cipher
5120
5121           Sets the list of available ciphers for $ssl using the control
5122           string $str.
5123
5124            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
5130           Check openssl doc
5131           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
5132
5133       •   CTX_set_psk_client_callback
5134
5135           Sets the psk client callback.
5136
5137            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
5145           Check openssl doc
5146           <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
5147
5148       •   set_purpose
5149
5150            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
5156           For more info about available $purpose identifiers see
5157           "CTX_set_purpose".
5158
5159       •   set_quiet_shutdown
5160
5161           Sets the 'quiet shutdown' flag for $ssl to be $mode.
5162
5163            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
5169           Check openssl doc
5170           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
5171
5172       •   set_session
5173
5174           Set a TLS/SSL session to be used during TLS/SSL connect.
5175
5176            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
5182           Check openssl doc
5183           <http://www.openssl.org/docs/ssl/SSL_set_session.html>
5184
5185       •   set_session_id_context
5186
5187           Sets the context $sid_ctx of length $sid_ctx_len within which a
5188           session can be reused for the $ssl object.
5189
5190            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
5197           Check openssl doc
5198           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
5199
5200       •   set_session_secret_cb
5201
5202           Setup pre-shared secret session resumption function.
5203
5204            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
5211           The callback function will be called like:
5212
5213            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
5220           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
5225           With OpenSSL 1.1 and later, callback_function can change the master
5226           key for the session by altering $secret and returning 1.
5227
5228       •   CTX_set_tlsext_ticket_getkey_cb
5229
5230           Setup encryption for TLS session tickets (stateless session reuse).
5231
5232            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
5239           The callback function will be called like:
5240
5241            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
5247           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
5251           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
5261           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
5267           Example:
5268
5269               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
5274               my @keys = (
5275                   [ $newkey_name, $newkey ], # current active key
5276                   [ $oldkey_name, $oldkey ], # already expired
5277               );
5278
5279               Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
5280                   my ($mykeys,$name) = @_;
5281
5282                   # return (current_key, current_key_name) if no name given
5283                   return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
5284
5285                   # 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
5292                   # no matching key found
5293                   return;
5294               },\@keys);
5295
5296           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
5301       •   set_session_ticket_ext_cb
5302
5303           Setup callback for TLS session tickets (stateless session reuse).
5304
5305            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
5312           The callback function will be called like:
5313
5314            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
5320           This function is based on the OpenSSL function
5321           SSL_set_session_ticket_ext_cb.
5322
5323       •   set_session_ticket_ext
5324
5325           Set TLS session ticket (stateless session reuse).
5326
5327            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
5333           The callback function will be called like:
5334
5335            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
5341           This function is based on the OpenSSL function
5342           SSL_set_session_ticket_ext_cb.
5343
5344       •   set_shutdown
5345
5346           Sets the shutdown state of $ssl to $mode.
5347
5348            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
5358           Check openssl doc
5359           <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
5360
5361       •   set_ssl_method
5362
5363           Sets a new TLS/SSL method for a particular $ssl object.
5364
5365            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
5371           Check openssl doc
5372           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
5373
5374       •   set_tmp_dh
5375
5376           Sets DH parameters to be used to be $dh.
5377
5378            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
5384           Check openssl doc
5385           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5386
5387       •   set_tmp_dh_callback
5388
5389           Sets the callback function for $ssl to be used when a DH parameters
5390           are required to $dh_cb.
5391
5392           ??? (does this function really work?)
5393
5394            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
5400           Check openssl doc
5401           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5402
5403       •   set_tmp_rsa
5404
5405           Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
5406
5407            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
5413           Example:
5414
5415            $rsakey = Net::SSLeay::RSA_generate_key();
5416            Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
5417            Net::SSLeay::RSA_free($rsakey);
5418
5419           Check openssl doc
5420           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5421
5422       •   set_tmp_rsa_callback
5423
5424           Sets the callback function for $ssl to be used when a
5425           temporary/ephemeral RSA key is required to $tmp_rsa_callback.
5426
5427           ??? (does this function really work?)
5428
5429            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
5435           Check openssl doc
5436           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5437
5438       •   set_trust
5439
5440            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
5446           For more details about $trust values see "CTX_set_trust".
5447
5448       •   shutdown
5449
5450           Shuts down an active TLS/SSL connection. It sends the 'close
5451           notify' shutdown alert to the peer.
5452
5453            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
5460           Check openssl doc
5461           <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
5462
5463       •   state_string
5464
5465           Returns a 6 letter string indicating the current state of the SSL
5466           object $ssl.
5467
5468            my $rv = Net::SSLeay::state_string($ssl);
5469            # $ssl - value corresponding to openssl's SSL structure
5470            #
5471            # returns: 6-letter string
5472
5473           Check openssl doc
5474           <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5475
5476       •   state_string_long
5477
5478           Returns a string indicating the current state of the SSL object
5479           $ssl.
5480
5481            my $rv = Net::SSLeay::state_string_long($ssl);
5482            # $ssl - value corresponding to openssl's SSL structure
5483            #
5484            # returns: state strings
5485
5486           Check openssl doc
5487           <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5488
5489       •   set_default_passwd_cb
5490
5491           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5492           requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5493
5494           Sets the default password callback called when loading/storing a
5495           PEM certificate with encryption for $ssl.
5496
5497            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
5503           Check openssl doc
5504           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5505
5506       •   set_default_passwd_cb_userdata
5507
5508           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5509           requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5510
5511           Sets a pointer to userdata which will be provided to the password
5512           callback of $ssl on invocation.
5513
5514            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
5520           Check openssl doc
5521           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5522
5523       •   use_PrivateKey
5524
5525           Adds $pkey as private key to $ssl.
5526
5527            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
5533           Check openssl doc
5534           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5535
5536       •   use_PrivateKey_ASN1
5537
5538           Adds the private key of type $pk stored in $data to $ssl.
5539
5540            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
5548           Check openssl doc
5549           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5550
5551       •   use_PrivateKey_file
5552
5553           Adds the first private key found in $file to $ssl.
5554
5555            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
5562           Check openssl doc
5563           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5564
5565       •   use_RSAPrivateKey
5566
5567           Adds $rsa as RSA private key to $ssl.
5568
5569            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
5575           Check openssl doc
5576           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5577
5578       •   use_RSAPrivateKey_ASN1
5579
5580           Adds RSA private key stored in $data to $ssl.
5581
5582            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
5589           Check openssl doc
5590           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5591
5592       •   use_RSAPrivateKey_file
5593
5594           Adds the first RSA private key found in $file to $ssl.
5595
5596            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
5603           Check openssl doc
5604           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5605
5606       •   use_certificate
5607
5608           Loads the certificate $x into $ssl.
5609
5610            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
5616           Check openssl doc
5617           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5618
5619       •   use_certificate_ASN1
5620
5621           Loads the ASN1 encoded certificate from $data to $ssl.
5622
5623            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
5630           Check openssl doc
5631           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5632
5633       •   use_certificate_chain_file
5634
5635           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5636           requires at least OpenSSL 1.1.0
5637
5638           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
5644            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
5650           Check openssl doc
5651           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5652
5653       •   use_certificate_file
5654
5655           Loads the first certificate stored in $file into $ssl.
5656
5657            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
5664           Check openssl doc
5665           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5666
5667       •   get_version
5668
5669           Returns SSL/TLS protocol name
5670
5671            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
5678           Check openssl doc
5679           <https://www.openssl.org/docs/manmaster/man3/SSL_get_version.html>
5680
5681       •   version
5682
5683           Returns SSL/TLS protocol version
5684
5685            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
5692           Check openssl doc
5693           <https://www.openssl.org/docs/manmaster/man3/SSL_version.html>
5694
5695       •   client_version
5696
5697           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5698           requires at least OpenSSL 1.1.0, not in LibreSSL
5699
5700           Returns TLS protocol version used by the client when initiating the
5701           connection
5702
5703            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
5710           Check openssl doc
5711           <https://www.openssl.org/docs/manmaster/man3/SSL_client_version.html>
5712
5713       •   is_dtls
5714
5715           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5716           requires at least OpenSSL 1.1.0, not in LibreSSL
5717
5718            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
5725           Check openssl doc
5726           <https://www.openssl.org/docs/manmaster/man3/SSL_is_dtls.html>
5727
5728       •   want
5729
5730           Returns state information for the SSL object $ssl.
5731
5732            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
5741           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5742
5743       •   write
5744
5745           Writes data from the buffer $data into the specified $ssl
5746           connection.
5747
5748            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
5756           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5757
5758       •   write_ex
5759
5760           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5761           requires at least OpenSSL 1.1.1, not in LibreSSL
5762
5763           Writes data from the buffer $data into the specified $ssl
5764           connection.
5765
5766            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
5773           Check openssl doc
5774           <https://www.openssl.org/docs/manmaster/man3/SSL_write_ex.html>
5775
5776       •   write_partial
5777
5778           NOTE: Does not exactly correspond to any low level API function
5779
5780           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
5784            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
5794       •   set_tlsext_host_name
5795
5796           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5797           requires at least openssl-0.9.8f
5798
5799           Sets TLS servername extension on SLL object $ssl to value $name.
5800
5801            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
5807       Low level API: RAND_* related functions
5808
5809       Check openssl doc related to RAND stuff
5810       <http://www.openssl.org/docs/crypto/rand.html>
5811
5812       •   RAND_add
5813
5814           Mixes the $num bytes at $buf into the PRNG state.
5815
5816            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
5823           Check openssl doc
5824           <http://www.openssl.org/docs/crypto/RAND_add.html>
5825
5826       •   RAND_seed
5827
5828           Equivalent to "RAND_add" when $num == $entropy.
5829
5830            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
5836           Check openssl doc
5837           <http://www.openssl.org/docs/crypto/RAND_add.html>
5838
5839       •   RAND_status
5840
5841           Gives PRNG status (seeded enough or not).
5842
5843            my $rv = Net::SSLeay::RAND_status();
5844            #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5845
5846           Check openssl doc
5847           <http://www.openssl.org/docs/crypto/RAND_add.html>
5848
5849       •   RAND_bytes
5850
5851           Puts $num cryptographically strong pseudo-random bytes into $buf.
5852
5853            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
5859           Check openssl doc
5860           <http://www.openssl.org/docs/manmaster/man3/RAND_bytes.html>
5861
5862       •   RAND_priv_bytes
5863
5864           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5865           requires at least OpenSSL 1.1.1, not in LibreSSL
5866
5867           Puts $num cryptographically strong pseudo-random bytes into $buf.
5868
5869            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
5875           RAND_priv_bytes has the same semantics as RAND_bytes, but see see
5876           the documentation for more information.
5877
5878           Check openssl doc
5879           <http://www.openssl.org/docs/manmaster/man3/RAND_priv_bytes.html>
5880
5881       •   RAND_pseudo_bytes
5882
5883           Puts $num pseudo-random (not necessarily unpredictable) bytes into
5884           $buf.
5885
5886            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
5892           Check openssl doc
5893           <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5894
5895       •   RAND_cleanup
5896
5897           Erase the PRNG state.
5898
5899            Net::SSLeay::RAND_cleanup();
5900            # no args, no return value
5901
5902           Check openssl doc
5903           <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5904
5905       •   RAND_egd_bytes
5906
5907           Queries the entropy gathering daemon EGD on socket $path for $bytes
5908           bytes.
5909
5910            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
5916           Check openssl doc
5917           <http://www.openssl.org/docs/crypto/RAND_egd.html>
5918
5919       •   RAND_file_name
5920
5921           Generates a default path for the random seed file.
5922
5923            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
5928           LibreSSL and OpenSSL 1.1.0a and later return undef when, for
5929           example, $num is not large enough to hold the filename.
5930
5931           Check openssl doc
5932           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5933
5934       •   RAND_load_file
5935
5936           COMPATIBILITY: Is no longer functional on LibreSSL
5937
5938           Reads $max_bytes of bytes from $file_name and adds them to the
5939           PRNG.
5940
5941            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
5947           Check openssl doc
5948           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5949
5950       •   RAND_write_file
5951
5952           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
5955            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
5960           Check openssl doc
5961           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5962
5963       •   RAND_poll
5964
5965           Collects some entropy from operating system and adds it to the
5966           PRNG.
5967
5968            my $rv = Net::SSLeay::RAND_poll();
5969            # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5970
5971       Low level API: OBJ_* related functions
5972
5973       •   OBJ_cmp
5974
5975           Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5976
5977            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
5983           Check openssl doc
5984           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5985
5986       •   OBJ_dup
5987
5988           Returns a copy/duplicate of $o.
5989
5990            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
5995           Check openssl doc
5996           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5997
5998       •   OBJ_nid2ln
5999
6000           Returns long name for given NID $n.
6001
6002            my $rv = Net::SSLeay::OBJ_nid2ln($n);
6003            # $n - (integer) NID
6004            #
6005            # returns: (string) long name e.g. 'commonName'
6006
6007           Check openssl doc
6008           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6009
6010       •   OBJ_ln2nid
6011
6012           Returns NID corresponding to given long name $n.
6013
6014            my $rv = Net::SSLeay::OBJ_ln2nid($s);
6015            # $s - (string) long name e.g. 'commonName'
6016            #
6017            # returns: (integer) NID
6018
6019       •   OBJ_nid2sn
6020
6021           Returns short name for given NID $n.
6022
6023            my $rv = Net::SSLeay::OBJ_nid2sn($n);
6024            # $n - (integer) NID
6025            #
6026            # returns: (string) short name e.g. 'CN'
6027
6028           Example:
6029
6030            print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
6031
6032       •   OBJ_sn2nid
6033
6034           Returns NID corresponding to given short name $s.
6035
6036            my $rv = Net::SSLeay::OBJ_sn2nid($s);
6037            # $s - (string) short name e.g. 'CN'
6038            #
6039            # returns: (integer) NID
6040
6041           Example:
6042
6043            print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
6044            print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
6045
6046       •   OBJ_nid2obj
6047
6048           Returns ASN1_OBJECT for given NID $n.
6049
6050            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
6055           Check openssl doc
6056           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6057
6058       •   OBJ_obj2nid
6059
6060           Returns NID corresponding to given ASN1_OBJECT $o.
6061
6062            my $rv = Net::SSLeay::OBJ_obj2nid($o);
6063            # $o - value corresponding to openssl's ASN1_OBJECT structure
6064            #
6065            # returns: (integer) NID
6066
6067           Check openssl doc
6068           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6069
6070       •   OBJ_txt2obj
6071
6072           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
6077            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
6083           Check openssl doc
6084           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6085
6086       •   OBJ_obj2txt
6087
6088           Converts the ASN1_OBJECT a into a textual representation.
6089
6090            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
6096           Check openssl doc
6097           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6098
6099       •   OBJ_txt2nid
6100
6101           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
6104            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
6109           Example:
6110
6111            my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
6112            Net::SSLeay::OBJ_nid2sn($n);
6113
6114           Check openssl doc
6115           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
6116
6117       Low level API: ASN1_INTEGER_* related functions
6118
6119       •   ASN1_INTEGER_new
6120
6121           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6122
6123           Creates a new ASN1_INTEGER structure.
6124
6125            my $rv = Net::SSLeay::ASN1_INTEGER_new();
6126            #
6127            # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6128
6129       •   ASN1_INTEGER_free
6130
6131           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6132
6133           Free an allocated ASN1_INTEGER structure.
6134
6135            Net::SSLeay::ASN1_INTEGER_free($i);
6136            # $i - value corresponding to openssl's ASN1_INTEGER structure
6137            #
6138            # returns: no return value
6139
6140       •   ASN1_INTEGER_get
6141
6142           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6143
6144           Returns integer value of given ASN1_INTEGER object.
6145
6146           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
6152            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
6157       •   ASN1_INTEGER_set
6158
6159           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6160
6161           Sets value of given ASN1_INTEGER object to value $val
6162
6163           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
6167            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
6173       •   P_ASN1_INTEGER_get_dec
6174
6175           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6176
6177           Returns string with decimal representation of integer value of
6178           given ASN1_INTEGER object.
6179
6180            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
6185       •   P_ASN1_INTEGER_get_hex
6186
6187           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6188
6189           Returns string with hexadecimal representation of integer value of
6190           given ASN1_INTEGER object.
6191
6192            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
6197       •   P_ASN1_INTEGER_set_dec
6198
6199           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6200
6201           Sets value of given ASN1_INTEGER object to value $val (decimal
6202           string, suitable for large integers)
6203
6204            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
6210       •   P_ASN1_INTEGER_set_hex
6211
6212           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6213
6214           Sets value of given ASN1_INTEGER object to value $val (hexadecimal
6215           string, suitable for large integers)
6216
6217            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
6223       Low level API: ASN1_STRING_* related functions
6224
6225       •   P_ASN1_STRING_get
6226
6227           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6228
6229           Returns string value of given ASN1_STRING object.
6230
6231            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
6237            $string = Net::SSLeay::P_ASN1_STRING_get($s);
6238            #is the same as:
6239            $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
6240
6241       Low level API: ASN1_TIME_* related functions
6242
6243       •   ASN1_TIME_new
6244
6245           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6246
6247            my $time = ASN1_TIME_new();
6248            # returns: value corresponding to openssl's ASN1_TIME structure
6249
6250       •   ASN1_TIME_free
6251
6252           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6253
6254            ASN1_TIME_free($time);
6255            # $time - value corresponding to openssl's ASN1_TIME structure
6256
6257       •   ASN1_TIME_set
6258
6259           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
6260
6261            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
6265           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
6270           If you want to safely set date and time after 2038 use function
6271           "P_ASN1_TIME_set_isotime".
6272
6273       •   P_ASN1_TIME_get_isotime
6274
6275           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6276           requires at least openssl-0.9.7e
6277
6278           NOTE: Does not exactly correspond to any low level API function
6279
6280           Gives ISO-8601 string representation of ASN1_TIME structure.
6281
6282            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
6287           The output format is compatible with module
6288           DateTime::Format::RFC3339
6289
6290       •   P_ASN1_TIME_set_isotime
6291
6292           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6293           requires at least openssl-0.9.7e
6294
6295           NOTE: Does not exactly correspond to any low level API function
6296
6297           Sets time and date value of ANS1_time structure.
6298
6299            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
6305           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
6310       •   P_ASN1_TIME_put2string
6311
6312           COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
6313           bugs with openssl-0.9.8i
6314
6315           NOTE: Does not exactly correspond to any low level API function
6316
6317           Gives string representation of ASN1_TIME structure.
6318
6319            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
6324       •   P_ASN1_UTCTIME_put2string
6325
6326           NOTE: deprecated function, only for backward compatibility, just an
6327           alias for "P_ASN1_TIME_put2string"
6328
6329       Low level API: X509_* related functions
6330
6331       •   X509_new
6332
6333           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6334
6335           Allocates and initializes a X509 structure.
6336
6337            my $rv = Net::SSLeay::X509_new();
6338            #
6339            # returns: value corresponding to openssl's X509 structure (0 on failure)
6340
6341           Check openssl doc
6342           <http://www.openssl.org/docs/crypto/X509_new.html>
6343
6344       •   X509_free
6345
6346           Frees up the X509 structure.
6347
6348            Net::SSLeay::X509_free($a);
6349            # $a - value corresponding to openssl's X509 structure
6350            #
6351            # returns: no return value
6352
6353           Check openssl doc
6354           <http://www.openssl.org/docs/crypto/X509_new.html>
6355
6356       •   X509_check_host
6357
6358           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
6362           Checks if the certificate Subject Alternative Name (SAN) or Subject
6363           CommonName (CN) matches the specified host name.
6364
6365            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
6385           Check openssl doc
6386           <https://www.openssl.org/docs/crypto/X509_check_host.html>.
6387
6388       •   X509_check_email
6389
6390           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6391           requires at least OpenSSL 1.0.2.
6392
6393           Checks if the certificate matches the specified email address.
6394
6395            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
6402           Check openssl doc
6403           <https://www.openssl.org/docs/crypto/X509_check_email.html>.
6404
6405       •   X509_check_ip
6406
6407           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6408           requires at least OpenSSL 1.0.2.
6409
6410           Checks if the certificate matches the specified IPv4 or IPv6
6411           address.
6412
6413            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
6420           Check openssl doc
6421           <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
6422
6423       •   X509_check_ip_asc
6424
6425           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6426           requires at least OpenSSL 1.0.2.
6427
6428           Checks if the certificate matches the specified IPv4 or IPv6
6429           address.
6430
6431            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
6438           Check openssl doc
6439           <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
6440
6441       •   X509_certificate_type
6442
6443           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6444
6445           Returns bitmask with type of certificate $x.
6446
6447            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
6452            #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
6465       •   X509_digest
6466
6467           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6468
6469           Computes digest/fingerprint of X509 $data using $type hash
6470           function.
6471
6472            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
6478            #to get printable (hex) value of digest use:
6479            print unpack('H*', $digest_value);
6480
6481       •   X509_issuer_and_serial_hash
6482
6483           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6484
6485           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
6491            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
6496       •   X509_issuer_name_hash
6497
6498           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6499
6500           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
6506            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
6511       •   X509_subject_name_hash
6512
6513           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6514
6515           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
6521            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
6526       •   X509_pubkey_digest
6527
6528           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6529           requires at least openssl-0.9.7
6530
6531           Computes digest/fingerprint of public key from X509 certificate
6532           $data using $type hash function.
6533
6534            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
6540            #to get printable (hex) value of digest use:
6541            print unpack('H*', $digest_value);
6542
6543       •   X509_set_issuer_name
6544
6545           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6546
6547           Sets issuer of X509 certificate $x to $name.
6548
6549            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
6555       •   X509_set_pubkey
6556
6557           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6558
6559           Sets public key of X509 certificate $x to $pkey.
6560
6561            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
6567       •   X509_set_serialNumber
6568
6569           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6570
6571           Sets serial number of X509 certificate $x to $serial.
6572
6573            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
6579            #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
6584       •   X509_set_subject_name
6585
6586           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6587
6588           Sets subject of X509 certificate $x to $name.
6589
6590            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
6596       •   X509_set_version
6597
6598           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6599
6600           Set 'version' value for X509 certificate $ to $version.
6601
6602            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
6608       •   X509_sign
6609
6610           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6611
6612           Sign X509 certificate $x with private key $pkey (using digest
6613           algorithm $md).
6614
6615            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
6622       •   X509_verify
6623
6624           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6625
6626           Verifies X509 object $a using public key $r (pubkey of issuing CA).
6627
6628            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
6634       •   X509_get_ext_count
6635
6636           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6637
6638           Returns the total number of extensions in X509 object $x.
6639
6640            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
6645       •   X509_get_pubkey
6646
6647           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6648
6649           Returns public key corresponding to given X509 object $x.
6650
6651            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
6656           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
6660       •   X509_get_X509_PUBKEY
6661
6662           COMPATIBILITY: not available in Net-SSLeay-1.72 and before
6663
6664           Returns the full public key (SPKI) of given X509 certificate $x.
6665
6666            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
6671       •   X509_get_serialNumber
6672
6673           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6674
6675           Returns serial number of X509 certificate $x.
6676
6677            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
6682           See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
6683           "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
6684
6685       •   X509_get0_serialNumber
6686
6687           COMPATIBILITY: available in Net-SSLeay-1.86 onwards
6688
6689           X509_get0_serialNumber() is the same as X509_get_serialNumber()
6690           except it accepts a const parameter and returns a const result.
6691
6692       •   X509_get_version
6693
6694           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6695
6696           Returns 'version' value of given X509 certificate $x.
6697
6698            my $rv = Net::SSLeay::X509_get_version($x);
6699            # $x - value corresponding to openssl's X509 structure
6700            #
6701            # returns: (integer) version
6702
6703       •   X509_get_ext
6704
6705           Returns X509_EXTENSION from $x509 based on given position/index.
6706
6707            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
6713       •   X509_get_ext_by_NID
6714
6715           Returns X509_EXTENSION from $x509 based on given NID.
6716
6717            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
6725       •   X509_get_fingerprint
6726
6727           Returns fingerprint of certificate $cert.
6728
6729           NOTE: Does not exactly correspond to any low level API function.
6730           The implementation is based on openssl's "X509_digest()".
6731
6732            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
6742       •   X509_get_issuer_name
6743
6744           Return an X509_NAME object representing the issuer of the
6745           certificate $cert.
6746
6747            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
6752       •   X509_get_notAfter
6753
6754           Return an object giving the time after which the certificate $cert
6755           is not valid.
6756
6757            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
6762           To get human readable/printable form the return value you can use:
6763
6764            my $time = Net::SSLeay::X509_get_notAfter($cert);
6765            print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6766
6767       •   X509_get_notBefore
6768
6769           Return an object giving the time before which the certificate $cert
6770           is not valid
6771
6772            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
6777           To get human readable/printable form the return value you can use:
6778
6779            my $time = Net::SSLeay::X509_get_notBefore($cert);
6780            print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6781
6782       •   X509_get_subjectAltNames
6783
6784           NOTE: Does not exactly correspond to any low level API function.
6785
6786           Returns the list of alternative subject names from X509 certificate
6787           $cert.
6788
6789            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
6804           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
6811       •   X509_get_subject_name
6812
6813           Returns the subject of the certificate $cert.
6814
6815            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
6820       •   X509_gmtime_adj
6821
6822           Adjust th ASN1_TIME object to the timestamp (in GMT).
6823
6824            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
6830           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
6834       •   X509_load_cert_crl_file
6835
6836           Takes PEM file and loads all X509 certificates and X509 CRLs from
6837           that file into X509_LOOKUP structure.
6838
6839            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
6847       •   X509_load_cert_file
6848
6849           Loads/adds X509 certificate from $file to X509_LOOKUP structure
6850
6851            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
6858       •   X509_load_crl_file
6859
6860           Loads/adds X509 CRL from $file to X509_LOOKUP structure
6861
6862            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
6869       •   X509_policy_level_get0_node
6870
6871           ??? (more info needed)
6872
6873            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
6879       •   X509_policy_level_node_count
6880
6881           ??? (more info needed)
6882
6883            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
6888       •   X509_policy_node_get0_parent
6889
6890           ??? (more info needed)
6891
6892            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
6897       •   X509_policy_node_get0_policy
6898
6899           ??? (more info needed)
6900
6901            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
6906       •   X509_policy_node_get0_qualifiers
6907
6908           ??? (more info needed)
6909
6910            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
6915       •   X509_policy_tree_free
6916
6917           ??? (more info needed)
6918
6919            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
6924       •   X509_policy_tree_get0_level
6925
6926           ??? (more info needed)
6927
6928            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
6934       •   X509_policy_tree_get0_policies
6935
6936           ??? (more info needed)
6937
6938            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
6943       •   X509_policy_tree_get0_user_policies
6944
6945           ??? (more info needed)
6946
6947            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
6952       •   X509_policy_tree_level_count
6953
6954           ??? (more info needed)
6955
6956            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
6961       •   X509_verify_cert_error_string
6962
6963           Returns a human readable error string for verification error $n.
6964
6965            my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6966            # $n - (long) numeric error code
6967            #
6968            # returns: error string
6969
6970           Check openssl doc
6971           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6972
6973       •   P_X509_add_extensions
6974
6975           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6976
6977           Adds one or more X509 extensions to X509 object $x.
6978
6979            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
6987           You can set more extensions at once:
6988
6989            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
7000       •   P_X509_copy_extensions
7001
7002           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7003
7004           Copies X509 extensions from X509_REQ object to X509 object - handy
7005           when you need to turn X509_REQ into X509 certificate.
7006
7007            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
7014       •   P_X509_get_crl_distribution_points
7015
7016           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7017           requires at least openssl-0.9.7
7018
7019           Get the list of CRL distribution points from X509 certificate.
7020
7021            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
7026       •   P_X509_get_ext_key_usage
7027
7028           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7029           requires at least openssl-0.9.7
7030
7031           Gets the list of extended key usage of given X509 certificate
7032           $cert.
7033
7034            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
7040           Examples:
7041
7042            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
7045            my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
7046            # returns for example: (129, 130)
7047
7048            my @extkeyusage_sn  = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
7049            # returns for example: ("serverAuth", "clientAuth")
7050
7051            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
7054       •   P_X509_get_key_usage
7055
7056           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7057
7058           Gets the list of key usage of given X509 certificate $cert.
7059
7060            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
7074       •   P_X509_get_netscape_cert_type
7075
7076           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7077
7078           Gets the list of Netscape cert types of given X509 certificate
7079           $cert.
7080
7081            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
7094       •   P_X509_get_pubkey_alg
7095
7096           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7097
7098           Returns ASN1_OBJECT corresponding to X509 certificate public key
7099           algorithm.
7100
7101            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
7106           To get textual representation use:
7107
7108            my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
7109            # returns for example: "rsaEncryption"
7110
7111       •   P_X509_get_signature_alg
7112
7113           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7114
7115           Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
7116
7117            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
7122           To get textual representation use:
7123
7124            my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
7125            # returns for example: "sha1WithRSAEncryption"
7126
7127       •   sk_X509_new_null
7128
7129           Returns a new, empty, STACK_OF(X509) structure.
7130
7131            my $rv = Net::SSLeay::sk_X509_new_null();
7132            #
7133            # returns: value corresponding to openssl's STACK_OF(X509) structure
7134
7135       •   sk_X509_push
7136
7137           Pushes an X509 structure onto a STACK_OF(X509) structure.
7138
7139            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
7145       •   sk_X509_pop
7146
7147           Pops an single X509 structure from a STACK_OF(X509) structure.
7148
7149            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
7154           Check openssl doc
7155           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_pop.html>
7156
7157       •   sk_X509_shift
7158
7159           Shifts an single X509 structure onto a STACK_OF(X509) structure.
7160
7161            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
7167           Check openssl doc
7168           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_shift.html>
7169
7170       •   sk_X509_unshift
7171
7172           Unshifts an single X509 structure from a STACK_OF(X509) structure.
7173
7174            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
7179           Check openssl doc
7180           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_unshift.html>
7181
7182       •   sk_X509_insert
7183
7184           Inserts a single X509 structure into a STACK_OF(X509) at the
7185           specified index.
7186
7187            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
7194           Check openssl doc
7195           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_insert.html>
7196
7197       •   sk_X509_delete
7198
7199           Delete a single X509 structure from a STACK_OF(X509) at the
7200           specified index.
7201
7202            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
7208           Check openssl doc
7209           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_delete.html>
7210
7211       •   sk_X509_value
7212
7213           Return a single X509 structure from a STACK_OF(X509) at the
7214           specified index.
7215
7216            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
7222           Check openssl doc
7223           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_value.html>
7224
7225       •   sk_X509_num
7226
7227           Return the number of X509 elements in a STACK_OF(X509).
7228
7229            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
7234           Check openssl doc
7235           <https://www.openssl.org/docs/manmaster/man3/sk_TYPE_num.html>
7236
7237       Low level API: X509_REQ_* related functions
7238
7239       •   X509_REQ_new
7240
7241           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7242
7243           Creates a new X509_REQ structure.
7244
7245            my $rv = Net::SSLeay::X509_REQ_new();
7246            #
7247            # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
7248
7249       •   X509_REQ_free
7250
7251           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7252
7253           Free an allocated X509_REQ structure.
7254
7255            Net::SSLeay::X509_REQ_free($x);
7256            # $x - value corresponding to openssl's X509_REQ structure
7257            #
7258            # returns: no return value
7259
7260       •   X509_REQ_add1_attr_by_NID
7261
7262           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7263
7264           Adds an attribute whose name is defined by a NID $nid. The field
7265           value to be added is in $bytes.
7266
7267            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
7275            # 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
7279       •   X509_REQ_digest
7280
7281           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7282
7283           Computes digest/fingerprint of X509_REQ $data using $type hash
7284           function.
7285
7286            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
7292            #to get printable (hex) value of digest use:
7293            print unpack('H*', $digest_value);
7294
7295       •   X509_REQ_get_attr_by_NID
7296
7297           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7298
7299           Retrieve the next index matching $nid after $lastpos ($lastpos
7300           should initially be set to -1).
7301
7302            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
7309           Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7310           e.g.
7311
7312            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
7315       •   X509_REQ_get_attr_by_OBJ
7316
7317           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7318
7319           Retrieve the next index matching $obj after $lastpos ($lastpos
7320           should initially be set to -1).
7321
7322            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
7329           Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
7330           e.g.
7331
7332            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
7335       •   X509_REQ_get_attr_count
7336
7337           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7338
7339           Returns the total number of attributes in $req.
7340
7341            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
7346       •   X509_REQ_get_pubkey
7347
7348           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7349
7350           Returns public key corresponding to given X509_REQ object $x.
7351
7352            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
7357       •   X509_REQ_get_subject_name
7358
7359           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7360
7361           Returns X509_NAME object corresponding to subject name of given
7362           X509_REQ object $x.
7363
7364            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
7369       •   X509_REQ_get_version
7370
7371           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7372
7373           Returns 'version' value for given X509_REQ object $x.
7374
7375            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
7380       •   X509_REQ_set_pubkey
7381
7382           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7383
7384           Sets public key of given X509_REQ object $x to $pkey.
7385
7386            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
7392       •   X509_REQ_set_subject_name
7393
7394           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7395
7396           Sets subject name of given X509_REQ object $x to X509_NAME object
7397           $name.
7398
7399            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
7405       •   X509_REQ_set_version
7406
7407           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7408
7409           Sets 'version' of given X509_REQ object $x to $version.
7410
7411            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
7417       •   X509_REQ_sign
7418
7419           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7420
7421           Sign X509_REQ object $x with private key $pk (using digest
7422           algorithm $md).
7423
7424            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
7431       •   X509_REQ_verify
7432
7433           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7434
7435           Verifies X509_REQ object $x using public key $r (pubkey of
7436           requesting party).
7437
7438            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
7444       •   P_X509_REQ_add_extensions
7445
7446           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7447
7448           Adds one or more X509 extensions to X509_REQ object $x.
7449
7450            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
7457           You can set more extensions at once:
7458
7459            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
7468       •   P_X509_REQ_get_attr
7469
7470           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7471           requires at least openssl-0.9.7
7472
7473           Returns attribute value for X509_REQ's attribute at index $n.
7474
7475            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
7481       Low level API: X509_CRL_* related functions
7482
7483       •   X509_CRL_new
7484
7485           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7486
7487           Creates a new X509_CRL structure.
7488
7489            my $rv = Net::SSLeay::X509_CRL_new();
7490            #
7491            # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
7492
7493       •   X509_CRL_free
7494
7495           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7496
7497           Free an allocated X509_CRL structure.
7498
7499            Net::SSLeay::X509_CRL_free($x);
7500            # $x - value corresponding to openssl's X509_CRL structure
7501            #
7502            # returns: no return value
7503
7504       •   X509_CRL_digest
7505
7506           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7507
7508           Computes digest/fingerprint of X509_CRL $data using $type hash
7509           function.
7510
7511            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
7517           Example:
7518
7519            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
7525       •   X509_CRL_get_ext
7526
7527           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7528
7529           Returns X509_EXTENSION from $x509 based on given position/index.
7530
7531            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
7537       •   X509_CRL_get_ext_by_NID
7538
7539           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7540
7541           Returns X509_EXTENSION from $x509 based on given NID.
7542
7543            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
7551       •   X509_CRL_get_ext_count
7552
7553           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7554
7555           Returns the total number of extensions in X509_CRL object $x.
7556
7557            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
7562       •   X509_CRL_get_issuer
7563
7564           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7565
7566           Returns X509_NAME object corresponding to the issuer of X509_CRL
7567           $x.
7568
7569            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
7574           See other "X509_NAME_*" functions to get more info from X509_NAME
7575           structure.
7576
7577       •   X509_CRL_get_lastUpdate
7578
7579           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7580
7581           Returns 'lastUpdate' date-time value of X509_CRL object $x.
7582
7583            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
7588       •   X509_CRL_get_nextUpdate
7589
7590           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7591
7592           Returns 'nextUpdate' date-time value of X509_CRL object $x.
7593
7594            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
7599       •   X509_CRL_get_version
7600
7601           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7602
7603           Returns 'version' value of given X509_CRL structure $x.
7604
7605            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
7610       •   X509_CRL_set_issuer_name
7611
7612           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7613           requires at least openssl-0.9.7
7614
7615           Sets the issuer of X509_CRL object $x to X509_NAME object $name.
7616
7617            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
7623       •   X509_CRL_set_lastUpdate
7624
7625           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7626           requires at least openssl-0.9.7
7627
7628           Sets 'lastUpdate' value of X509_CRL object $x to $tm.
7629
7630            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
7636       •   X509_CRL_set_nextUpdate
7637
7638           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7639           requires at least openssl-0.9.7
7640
7641           Sets 'nextUpdate' value of X509_CRL object $x to $tm.
7642
7643            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
7649       •   X509_CRL_set_version
7650
7651           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7652           requires at least openssl-0.9.7
7653
7654           Sets 'version' value of given X509_CRL structure $x to $version.
7655
7656            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
7662           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
7665       •   X509_CRL_sign
7666
7667           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7668
7669           Sign X509_CRL object $x with private key $pkey (using digest
7670           algorithm $md).
7671
7672            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
7679       •   X509_CRL_sort
7680
7681           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7682           requires at least openssl-0.9.7
7683
7684           Sorts the data of X509_CRL object so it will be written in serial
7685           number order.
7686
7687            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
7692       •   X509_CRL_verify
7693
7694           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7695
7696           Verifies X509_CRL object $a using public key $r (pubkey of issuing
7697           CA).
7698
7699            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
7705       •   P_X509_CRL_add_revoked_serial_hex
7706
7707           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7708           requires at least openssl-0.9.7
7709
7710           Adds given serial number $serial_hex to X509_CRL object $crl.
7711
7712            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
7721            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
7731       •   P_X509_CRL_get_serial
7732
7733           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7734           requires at least openssl-0.9.7
7735
7736           Returns serial number of X509_CRL object.
7737
7738            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
7743       •   P_X509_CRL_set_serial
7744
7745           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7746           requires at least openssl-0.9.7
7747
7748           Sets serial number of X509_CRL object to $crl_number.
7749
7750            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
7756       •   P_X509_CRL_add_extensions
7757
7758           COMPATIBILITY: not available in Net-SSLeay-1.88 and before
7759
7760           Adds one or more X509 extensions to X509 CRL object $x.
7761
7762            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
7770           For more details see "P_X509_add_extensions".
7771
7772       Low level API: X509_EXTENSION_* related functions
7773
7774       •   X509_EXTENSION_get_critical
7775
7776           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7777
7778           Returns 'critical' flag of given X509_EXTENSION object $ex.
7779
7780            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
7785       •   X509_EXTENSION_get_data
7786
7787           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7788
7789           Returns value (raw data) of X509_EXTENSION object $ne.
7790
7791            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
7796           Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
7797           into perl scalar variable.
7798
7799       •   X509_EXTENSION_get_object
7800
7801           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7802
7803           Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
7804
7805            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
7810       •   X509V3_EXT_print
7811
7812           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7813
7814           Returns string representation of given X509_EXTENSION object $ext.
7815
7816            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
7823       •   X509V3_EXT_d2i
7824
7825           Parses an extension and returns its internal structure.
7826
7827            my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
7828            # $ext - value corresponding to openssl's X509_EXTENSION structure
7829            #
7830            # returns: pointer ???
7831
7832       Low level API: X509_NAME_* related functions
7833
7834       •   X509_NAME_ENTRY_get_data
7835
7836           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7837
7838           Retrieves the field value of $ne in and ASN1_STRING structure.
7839
7840            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
7845           Check openssl doc
7846           <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7847
7848       •   X509_NAME_ENTRY_get_object
7849
7850           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7851
7852           Retrieves the field name of $ne in and ASN1_OBJECT structure.
7853
7854            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
7859           Check openssl doc
7860           <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7861
7862       •   X509_NAME_new
7863
7864           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7865           requires at least openssl-0.9.5
7866
7867           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
7871            my $rv = Net::SSLeay::X509_NAME_new();
7872            #
7873            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7874
7875       •   X509_NAME_hash
7876
7877           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7878           requires at least openssl-0.9.5
7879
7880           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
7885            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
7890       •   X509_NAME_add_entry_by_txt
7891
7892           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7893           requires at least openssl-0.9.5
7894
7895           Adds a field whose name is defined by a string $field. The field
7896           value to be added is in $bytes.
7897
7898            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
7908            # 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
7912           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
7916           Check openssl doc
7917           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7918
7919       •   X509_NAME_add_entry_by_NID
7920
7921           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7922           requires at least openssl-0.9.5
7923
7924           Adds a field whose name is defined by a NID $nid. The field value
7925           to be added is in $bytes.
7926
7927            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
7937           Check openssl doc
7938           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7939
7940       •   X509_NAME_add_entry_by_OBJ
7941
7942           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7943           requires at least openssl-0.9.5
7944
7945           Adds a field whose name is defined by a object (OID) $obj . The
7946           field value to be added is in $bytes.
7947
7948            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
7958           Check openssl doc
7959           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7960
7961       •   X509_NAME_cmp
7962
7963           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7964
7965           Compares two X509_NAME obejcts.
7966
7967            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
7973       •   X509_NAME_digest
7974
7975           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7976
7977           Computes digest/fingerprint of X509_NAME $data using $type hash
7978           function.
7979
7980            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
7986            #to get printable (hex) value of digest use:
7987            print unpack('H*', $digest_value);
7988
7989       •   X509_NAME_entry_count
7990
7991           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7992
7993           Returns the total number of entries in $name.
7994
7995            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
8000           Check openssl doc
8001           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8002
8003       •   X509_NAME_get_entry
8004
8005           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8006
8007           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
8012            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
8018           Check openssl doc
8019           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8020
8021       •   X509_NAME_print_ex
8022
8023           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8024
8025           Returns a string with human readable version of $name.
8026
8027            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
8034            #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
8054           Most likely you will be fine with default:
8055
8056            Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
8057
8058           Or you might want RFC2253-like output without utf8 chars escaping:
8059
8060            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
8064           Check openssl doc
8065           <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8066
8067       •   X509_NAME_get_text_by_NID
8068
8069           Retrieves the text from the first entry in name which matches $nid,
8070           if no such entry exists -1 is returned.
8071
8072           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
8078            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
8084           Check openssl doc
8085           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
8086
8087       •   X509_NAME_oneline
8088
8089           Return an ASCII version of $name.
8090
8091            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
8096           Check openssl doc
8097           <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
8098
8099       •   sk_X509_NAME_free
8100
8101           Free an allocated STACK_OF(X509_NAME) structure.
8102
8103            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
8108       •   sk_X509_NAME_num
8109
8110           Return number of items in STACK_OF(X509_NAME)
8111
8112            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
8117       •   sk_X509_NAME_value
8118
8119           Returns X509_NAME from position $index in STACK_OF(X509_NAME)
8120
8121            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
8127       •   add_file_cert_subjects_to_stack
8128
8129           Add a file of certs to a stack. All certs in $file that are not
8130           already in the $stackCAs will be added.
8131
8132            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
8138       •   add_dir_cert_subjects_to_stack
8139
8140           Add a directory of certs to a stack. All certs in $dir that are not
8141           already in the $stackCAs will be added.
8142
8143            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
8149       Low level API: X509_STORE_* related functions
8150
8151       •   X509_STORE_CTX_new
8152
8153           returns a newly initialised X509_STORE_CTX structure.
8154
8155       •   X509_STORE_CTX_init
8156
8157           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
8161            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
8171           Check openssl doc
8172           <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_init.html>
8173
8174       •   X509_STORE_CTX_free
8175
8176           Frees an X509_STORE_CTX structure.
8177
8178            Net::SSLeay::X509_STORE_CTX_free($x509_store_ctx);
8179
8180           # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
8181           structure
8182
8183       •   X509_verify_cert
8184
8185           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
8190           If this function returns 0, use X509_STORE_CTX_get_error to get
8191           additional error information.
8192
8193            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
8198           Check openssl doc
8199           <https://www.openssl.org/docs/manmaster/man3/X509_verify_cert.html>
8200
8201       •   X509_STORE_CTX_get_current_cert
8202
8203           Returns the certificate in ctx which caused the error or 0 if no
8204           certificate is relevant.
8205
8206            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
8211           Check openssl doc
8212           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8213
8214       •   X509_STORE_CTX_get0_cert
8215
8216           COMPATIBILITY: not available in Net-SSLeay-1.88 and before;
8217           requires at least OpenSSL 1.1.0pre6 or LibreSSL 2.7.0
8218
8219           Returns an internal pointer to the certificate being verified by
8220           the ctx.
8221
8222            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
8227           Check openssl doc
8228           <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get0_cert.html>
8229
8230       •   X509_STORE_CTX_get1_chain
8231
8232           Returns a returns a complete validate chain if a previous call to
8233           X509_verify_cert() is successful.
8234
8235            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
8240           Check openssl doc
8241           <https://www.openssl.org/docs/manmaster/man3/X509_STORE_CTX_get1_chain.html>
8242
8243       •   X509_STORE_CTX_get_error
8244
8245           Returns the error code of $ctx.
8246
8247            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
8252           For more info about erro code values check function
8253           "get_verify_result".
8254
8255           Check openssl doc
8256           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8257
8258       •   X509_STORE_CTX_get_error_depth
8259
8260           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
8265            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
8270           Check openssl doc
8271           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8272
8273       •   X509_STORE_CTX_get_ex_data
8274
8275           Is used to retrieve the information for $idx from $x509_store_ctx.
8276
8277            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
8283       •   X509_STORE_CTX_set_ex_data
8284
8285           Is used to store application data at arg for idx into
8286           $x509_store_ctx.
8287
8288            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
8295       •   X509_STORE_CTX_set_cert
8296
8297           Sets the certificate to be verified in $x509_store_ctx to $x.
8298
8299            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
8305           Check openssl doc
8306           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
8307
8308       •   X509_STORE_new
8309
8310           Returns a newly initialized X509_STORE structure.
8311
8312            my $rv = Net::SSLeay::X509_STORE_new();
8313            #
8314            # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
8315
8316       •   X509_STORE_free
8317
8318           Frees an X509_STORE structure
8319
8320            Net::SSLeay::X509_STORE_free($x509_store);
8321            # $x509_store - value corresponding to openssl's X509_STORE structure
8322
8323       •   X509_STORE_add_lookup
8324
8325           Adds a lookup to an X509_STORE for a given lookup method.
8326
8327            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
8334           Check openssl doc
8335           <https://www.openssl.org/docs/manmaster/man3/X509_STORE_add_lookup.html>
8336
8337       •   X509_STORE_CTX_set_error
8338
8339           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
8342            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
8348           Check openssl doc
8349           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
8350
8351       •   X509_STORE_add_cert
8352
8353           Adds X509 certificate $x into the X509_STORE $store.
8354
8355            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
8361       •   X509_STORE_add_crl
8362
8363           Adds X509 CRL $x into the X509_STORE $store.
8364
8365            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
8371       •   X509_STORE_set1_param
8372
8373           ??? (more info needed)
8374
8375            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
8381       •   X509_LOOKUP_hash_dir
8382
8383           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
8387            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
8391           Check openssl doc
8392           <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
8393
8394       •   X509_LOOKUP_add_dir
8395
8396           Add a directory to an X509_LOOKUP structure, usually obtained from
8397           X509_STORE_add_lookup.
8398
8399            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
8407       •   X509_STORE_set_flags
8408
8409            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
8415            #to create $flags value use corresponding constants like
8416            $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8417
8418           For more details about $flags bitmask see
8419           "X509_VERIFY_PARAM_set_flags".
8420
8421       •   X509_STORE_set_purpose
8422
8423            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
8429           For more details about $purpose identifier check "CTX_set_purpose".
8430
8431       •   X509_STORE_set_trust
8432
8433            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
8439           For more details about $trust identifier check "CTX_set_trust".
8440
8441       Low Level API: X509_INFO related functions
8442
8443       •   sk_X509_INFO_num
8444
8445           Returns the number of values in a STACK_OF(X509_INFO) structure.
8446
8447            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
8452       •   sk_X509_INFO_value
8453
8454           Returns the value of a STACK_OF(X509_INFO) structure at a given
8455           index.
8456
8457            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
8463       •   P_X509_INFO_get_x509
8464
8465           Returns the X509 structure stored in an X509_INFO structure.
8466
8467            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
8472       Low level API: X509_VERIFY_PARAM_* related functions
8473
8474       •   X509_VERIFY_PARAM_add0_policy
8475
8476           Enables policy checking (it is disabled by default) and adds
8477           $policy to the acceptable policy set.
8478
8479            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
8485           Check openssl doc
8486           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8487
8488       •   X509_VERIFY_PARAM_add0_table
8489
8490           ??? (more info needed)
8491
8492            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
8497       •   X509_VERIFY_PARAM_add1_host
8498
8499           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
8502           Adds an additional reference identifier that can match the peer's
8503           certificate.
8504
8505            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
8511           See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
8512           "X509_VERIFY_PARAM_set_hostflags" for more information, including
8513           wildcard matching.
8514
8515           Check openssl doc
8516           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8517
8518       •   X509_VERIFY_PARAM_clear_flags
8519
8520           Clears the flags $flags in param.
8521
8522            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
8528           For more details about $flags bitmask see
8529           "X509_VERIFY_PARAM_set_flags".
8530
8531           Check openssl doc
8532           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8533
8534       •   X509_VERIFY_PARAM_free
8535
8536           Frees up the X509_VERIFY_PARAM structure.
8537
8538            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
8543       •   X509_VERIFY_PARAM_get0_peername
8544
8545           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
8548           Returns the DNS hostname or subject CommonName from the peer
8549           certificate that matched one of the reference identifiers.
8550
8551            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
8556           Check openssl doc
8557           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8558
8559       •   X509_VERIFY_PARAM_get_depth
8560
8561           Returns the current verification depth.
8562
8563            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
8568           Check openssl doc
8569           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8570
8571       •   X509_VERIFY_PARAM_get_flags
8572
8573           Returns the current verification flags.
8574
8575            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
8580           For more details about returned flags bitmask see
8581           "X509_VERIFY_PARAM_set_flags".
8582
8583           Check openssl doc
8584           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8585
8586       •   X509_VERIFY_PARAM_set_flags
8587
8588            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
8594            #to create $flags value use corresponding constants like
8595            $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8596
8597           For more details about $flags bitmask, see the OpenSSL docs below.
8598
8599           Check openssl doc
8600           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8601
8602       •   X509_VERIFY_PARAM_inherit
8603
8604           ??? (more info needed)
8605
8606            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
8612       •   X509_VERIFY_PARAM_lookup
8613
8614           Finds X509_VERIFY_PARAM by name.
8615
8616            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
8621       •   X509_VERIFY_PARAM_new
8622
8623           Creates a new X509_VERIFY_PARAM structure.
8624
8625            my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
8626            #
8627            # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8628
8629       •   X509_VERIFY_PARAM_set1
8630
8631           Sets the name of X509_VERIFY_PARAM structure $to to the same value
8632           as the name of X509_VERIFY_PARAM structure $from.
8633
8634            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
8640       •   X509_VERIFY_PARAM_set1_email
8641
8642           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
8645           Sets the expected RFC822 email address to email.
8646
8647            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
8653           Check openssl doc
8654           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8655
8656       •   X509_VERIFY_PARAM_set1_host
8657
8658           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
8661           Sets the expected DNS hostname to name clearing any previously
8662           specified host name or names.
8663
8664            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
8670           See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8671           "X509_VERIFY_PARAM_set_hostflags" for more information, including
8672           wildcard matching.
8673
8674           Check openssl doc
8675           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8676
8677       •   X509_VERIFY_PARAM_set1_ip
8678
8679           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
8682           Sets the expected IP address to ip.
8683
8684            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
8690           Check openssl doc
8691           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8692
8693       •   X509_VERIFY_PARAM_set1_ip_asc
8694
8695           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
8698           Sets the expected IP address to ipasc.
8699
8700            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
8706           Check openssl doc
8707           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8708
8709       •   X509_VERIFY_PARAM_set1_name
8710
8711           Sets the name of X509_VERIFY_PARAM structure $param to $name.
8712
8713            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
8719       •   X509_VERIFY_PARAM_set1_policies
8720
8721           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
8726            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
8732           Check openssl doc
8733           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8734
8735       •   X509_VERIFY_PARAM_set_depth
8736
8737           Sets the maximum verification depth to depth. That is the maximum
8738           number of untrusted CA certificates that can appear in a chain.
8739
8740            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
8746           Check openssl doc
8747           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8748
8749       •   X509_VERIFY_PARAM_set_hostflags
8750
8751           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
8754            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
8760           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
8765           Check openssl doc
8766           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8767
8768       •   X509_VERIFY_PARAM_set_purpose
8769
8770           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
8774            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
8780           For more details about $purpose identifier check "CTX_set_purpose".
8781
8782           Check openssl doc
8783           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8784
8785       •   X509_VERIFY_PARAM_set_time
8786
8787           Sets the verification time in $param to $t. Normally the current
8788           time is used.
8789
8790            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
8796           Check openssl doc
8797           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8798
8799       •   X509_VERIFY_PARAM_set_trust
8800
8801           Sets the trust setting in $param to $trust.
8802
8803            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
8809           For more details about $trust identifier check "CTX_set_trust".
8810
8811           Check openssl doc
8812           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8813
8814       •   X509_VERIFY_PARAM_table_cleanup
8815
8816           ??? (more info needed)
8817
8818            Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
8819            #
8820            # returns: no return value
8821
8822       Low level API: Cipher (EVP_CIPHER_*) related functions
8823
8824       •   EVP_get_cipherbyname
8825
8826           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8827
8828           Returns an EVP_CIPHER structure when passed a cipher name.
8829
8830            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
8835           Check openssl doc
8836           <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
8837
8838       Low level API: Digest (EVP_MD_*) related functions
8839
8840       •   OpenSSL_add_all_digests
8841
8842           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8843
8844            Net::SSLeay::OpenSSL_add_all_digests();
8845            # no args, no return value
8846
8847           http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
8848
8849       •   P_EVP_MD_list_all
8850
8851           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8852           requires at least openssl-1.0.0
8853
8854           NOTE: Does not exactly correspond to any low level API function
8855
8856            my $rv = Net::SSLeay::P_EVP_MD_list_all();
8857            #
8858            # returns: arrayref - list of available digest names
8859
8860           The returned digest names correspond to values expected by
8861           "EVP_get_digestbyname".
8862
8863           Note that some of the digests are available by default and some
8864           only after calling "OpenSSL_add_all_digests".
8865
8866       •   EVP_get_digestbyname
8867
8868           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8869
8870            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
8875           The $name param can be:
8876
8877            md2
8878            md4
8879            md5
8880            mdc2
8881            ripemd160
8882            sha
8883            sha1
8884            sha224
8885            sha256
8886            sha512
8887            whirlpool
8888
8889           Or better check the supported digests by calling
8890           "P_EVP_MD_list_all".
8891
8892       •   EVP_MD_type
8893
8894           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8895
8896            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
8901       •   EVP_MD_size
8902
8903           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8904
8905            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
8910       •   EVP_MD_CTX_md
8911
8912           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8913           requires at least openssl-0.9.7
8914
8915            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
8920       •   EVP_MD_CTX_create
8921
8922           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8923           requires at least openssl-0.9.7
8924
8925           Allocates, initializes and returns a digest context.
8926
8927            my $rv = Net::SSLeay::EVP_MD_CTX_create();
8928            #
8929            # returns: value corresponding to openssl's EVP_MD_CTX structure
8930
8931           The complete idea behind EVP_MD_CTX looks like this example:
8932
8933             Net::SSLeay::OpenSSL_add_all_digests();
8934
8935             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
8939             while(my $chunk = get_piece_of_data()) {
8940               Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
8941             }
8942
8943             my $result = Net::SSLeay::EVP_DigestFinal($ctx);
8944             Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8945
8946             print "digest=", unpack('H*', $result), "\n"; #print hex value
8947
8948       •   EVP_DigestInit_ex
8949
8950           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8951           requires at least openssl-0.9.7
8952
8953           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
8959            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
8966       •   EVP_DigestInit
8967
8968           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8969           requires at least openssl-0.9.7
8970
8971           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
8975            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
8981       •   EVP_MD_CTX_destroy
8982
8983           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8984           requires at least openssl-0.9.7
8985
8986           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
8990            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
8995       •   EVP_DigestUpdate
8996
8997           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8998           requires at least openssl-0.9.7
8999
9000            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
9006       •   EVP_DigestFinal_ex
9007
9008           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9009           requires at least openssl-0.9.7
9010
9011           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
9016            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
9021            #to get printable (hex) value of digest use:
9022            print unpack('H*', $digest_value);
9023
9024       •   EVP_DigestFinal
9025
9026           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9027           requires at least openssl-0.9.7
9028
9029           Similar to "EVP_DigestFinal_ex" except the digest context ctx is
9030           automatically cleaned up.
9031
9032            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
9037            #to get printable (hex) value of digest use:
9038            print unpack('H*', $digest_value);
9039
9040       •   MD2
9041
9042           COMPATIBILITY: no supported by default in openssl-1.0.0
9043
9044           Computes MD2 from given $data (all data needs to be loaded into
9045           memory)
9046
9047            my $digest = Net::SSLeay::MD2($data);
9048            print "digest(hexadecimal)=", unpack('H*', $digest);
9049
9050       •   MD4
9051
9052           Computes MD4 from given $data (all data needs to be loaded into
9053           memory)
9054
9055            my $digest = Net::SSLeay::MD4($data);
9056            print "digest(hexadecimal)=", unpack('H*', $digest);
9057
9058       •   MD5
9059
9060           Computes MD5 from given $data (all data needs to be loaded into
9061           memory)
9062
9063            my $digest = Net::SSLeay::MD5($data);
9064            print "digest(hexadecimal)=", unpack('H*', $digest);
9065
9066       •   RIPEMD160
9067
9068           Computes RIPEMD160 from given $data (all data needs to be loaded
9069           into memory)
9070
9071            my $digest = Net::SSLeay::RIPEMD160($data);
9072            print "digest(hexadecimal)=", unpack('H*', $digest);
9073
9074       •   SHA1
9075
9076           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9077
9078           Computes SHA1 from given $data (all data needs to be loaded into
9079           memory)
9080
9081            my $digest = Net::SSLeay::SHA1($data);
9082            print "digest(hexadecimal)=", unpack('H*', $digest);
9083
9084       •   SHA256
9085
9086           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9087           requires at least openssl-0.9.8
9088
9089           Computes SHA256 from given $data (all data needs to be loaded into
9090           memory)
9091
9092            my $digest = Net::SSLeay::SHA256($data);
9093            print "digest(hexadecimal)=", unpack('H*', $digest);
9094
9095       •   SHA512
9096
9097           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9098           requires at least openssl-0.9.8
9099
9100           Computes SHA512 from given $data (all data needs to be loaded into
9101           memory)
9102
9103            my $digest = Net::SSLeay::SHA512($data);
9104            print "digest(hexadecimal)=", unpack('H*', $digest);
9105
9106       •   EVP_Digest
9107
9108           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9109           requires at least openssl-0.9.7
9110
9111           Computes "any" digest from given $data (all data needs to be loaded
9112           into memory)
9113
9114            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
9118       •   EVP_sha1
9119
9120           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9121
9122            my $md = Net::SSLeay::EVP_sha1();
9123            #
9124            # returns: value corresponding to openssl's EVP_MD structure
9125
9126       •   EVP_sha256
9127
9128           COMPATIBILITY: requires at least openssl-0.9.8
9129
9130            my $md = Net::SSLeay::EVP_sha256();
9131            #
9132            # returns: value corresponding to openssl's EVP_MD structure
9133
9134       •   EVP_sha512
9135
9136           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
9137           requires at least openssl-0.9.8
9138
9139            my $md = Net::SSLeay::EVP_sha512();
9140            #
9141            # returns: value corresponding to openssl's EVP_MD structure
9142
9143       •   EVP_add_digest
9144
9145            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
9150       Low level API: CIPHER_* related functions
9151
9152       •   CIPHER_get_name
9153
9154           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
9155
9156           Returns name of the cipher used.
9157
9158            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
9163           Check openssl doc
9164           <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
9165
9166           Example:
9167
9168            my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
9169            my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
9170
9171       •   CIPHER_description
9172
9173           COMPATIBILITY: doesn't work correctly in Net-SSLeay-1.88 and before
9174
9175           Returns a textual description of the cipher used.
9176
9177            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
9182           Check openssl doc
9183           <https://www.openssl.org/docs/ssl/SSL_CIPHER_description.html>
9184
9185       •   CIPHER_get_bits
9186
9187           COMPATIBILITY: $alg_bits doesn't work correctly in Net-SSLeay-1.88
9188           and before
9189
9190           Returns the number of secret bits used for cipher.
9191
9192            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
9199           Check openssl doc
9200           <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_bits.html>
9201
9202           Example:
9203
9204            # 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
9211       •   CIPHER_get_version
9212
9213           COMPATIBILITY: not available in Net-SSLeay-1.88 and before
9214
9215           Returns version of SSL/TLS protocol that first defined the cipher
9216
9217            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
9222           Check openssl doc
9223           <https://www.openssl.org/docs/ssl/SSL_CIPHER_get_version.html>
9224
9225       Low level API: RSA_* related functions
9226
9227       •   RSA_generate_key
9228
9229           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
9233            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
9241           Check openssl doc
9242           <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
9243
9244       •   RSA_free
9245
9246           Frees the RSA structure and its components. The key is erased
9247           before the memory is returned to the system.
9248
9249            Net::SSLeay::RSA_free($r);
9250            # $r - value corresponding to openssl's RSA structure
9251            #
9252            # returns: no return value
9253
9254           Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
9255
9256       •   RSA_get_key_parameters
9257
9258           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
9261           Caution: returned list consists of SV pointers to BIGNUMs, which
9262           would need to be blessed as Crypt::OpenSSL::Bignum for further use
9263
9264            my (@params) = RSA_get_key_parameters($r);
9265
9266       Low level API: BIO_* related functions
9267
9268       •   BIO_eof
9269
9270           Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
9271           varies according to the BIO type.
9272
9273            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
9278           Check openssl doc
9279           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9280
9281       •   BIO_f_ssl
9282
9283           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
9286            my $rv = Net::SSLeay::BIO_f_ssl();
9287            #
9288            # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9289
9290           Check openssl doc
9291           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9292
9293       •   BIO_free
9294
9295           Frees up a single BIO.
9296
9297            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
9302           Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9303
9304       •   BIO_new
9305
9306           Returns a new BIO using method $type
9307
9308            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
9313           Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
9314
9315       •   BIO_new_buffer_ssl_connect
9316
9317           Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
9318           (using ctx) and a connect BIO.
9319
9320            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
9325           Check openssl doc
9326           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9327
9328       •   BIO_new_file
9329
9330           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
9334            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
9340           Check openssl doc
9341           <http://www.openssl.org/docs/crypto/BIO_s_file.html>
9342
9343       •   BIO_new_ssl
9344
9345           Allocates an SSL BIO using SSL_CTX ctx and using client mode if
9346           client is non zero.
9347
9348            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
9354           Check openssl doc
9355           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9356
9357       •   BIO_new_ssl_connect
9358
9359           Creates a new BIO chain consisting of an SSL BIO (using ctx)
9360           followed by a connect BIO.
9361
9362            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
9367           Check openssl doc
9368           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9369
9370       •   BIO_pending
9371
9372           Return the number of pending characters in the BIOs read buffers.
9373
9374            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
9379           Check openssl doc
9380           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9381
9382       •   BIO_wpending
9383
9384           Return the number of pending characters in the BIOs write buffers.
9385
9386            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
9391           Check openssl doc
9392           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
9393
9394       •   BIO_read
9395
9396           Read the underlying descriptor.
9397
9398            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
9404           Check openssl doc
9405           <http://www.openssl.org/docs/crypto/BIO_read.html>
9406
9407       •   BIO_write
9408
9409           Attempts to write data from $buffer to BIO $b.
9410
9411            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
9419           Check openssl doc
9420           <http://www.openssl.org/docs/crypto/BIO_read.html>
9421
9422       •   BIO_s_mem
9423
9424           Return the memory BIO method function.
9425
9426            my $rv = Net::SSLeay::BIO_s_mem();
9427            #
9428            # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
9429
9430           Check openssl doc
9431           <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
9432
9433       •   BIO_ssl_copy_session_id
9434
9435           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
9439            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
9445           Check openssl doc
9446           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9447
9448       •   BIO_ssl_shutdown
9449
9450           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
9454            Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
9455            # $ssl_bio - value corresponding to openssl's BIO structure
9456            #
9457            # returns: no return value
9458
9459           Check openssl doc
9460           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9461
9462       Low level API: Server side Server Name Indication (SNI) support
9463
9464       •   set_tlsext_host_name
9465
9466           TBA
9467
9468       •   get_servername
9469
9470           TBA
9471
9472       •   get_servername_type
9473
9474           TBA
9475
9476       •   CTX_set_tlsext_servername_callback
9477
9478           COMPATIBILITY: requires at least OpenSSL 0.9.8f
9479
9480           This function is used in a server to support Server side Server
9481           Name Indication (SNI).
9482
9483            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
9489           On the client side: use set_tlsext_host_name($ssl, $servername)
9490           before initiating the SSL connection.
9491
9492           On the server side: Set up an additional SSL_CTX() for each
9493           different certificate;
9494
9495           Add a servername callback to each SSL_CTX() using
9496           CTX_set_tlsext_servername_callback();
9497
9498           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
9503           Example:
9504
9505            # 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
9513           More complete example:
9514
9515            # ... initialize Net::SSLeay
9516
9517            my %hostnames = (
9518              'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
9519              'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
9520            );
9521
9522            # 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
9530            # 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
9535            # 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
9542            # ... later
9543
9544            $s = Net::SSLeay::new($ctx);
9545            Net::SSLeay::set_fd($s, fileno($accepted_socket));
9546            Net::SSLeay::accept($s);
9547
9548       Low level API: NPN (next protocol negotiation) related functions
9549
9550       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
9554       Simple approach for using NPN support looks like this:
9555
9556        ### client side
9557        use Net::SSLeay;
9558        use IO::Socket::INET;
9559
9560        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
9569        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
9572        ### server side
9573        use Net::SSLeay;
9574        use IO::Socket::INET;
9575
9576        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
9583        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
9597       Please note that the selection (negotiation) is performed by client
9598       side, the server side simply advertise the list of supported protocols.
9599
9600       Advanced approach allows you to implement your own negotiation
9601       algorithm.
9602
9603        #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
9607       Detection of NPN support (works even in older Net::SSLeay versions):
9608
9609        use Net::SSLeay;
9610
9611        if (exists &Net::SSLeay::P_next_proto_negotiated) {
9612          # do NPN stuff
9613        }
9614
9615       •   CTX_set_next_proto_select_cb
9616
9617           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9618           requires at least openssl-1.0.1
9619
9620           NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
9621           connection.
9622
9623           Simple usage - in this case a "common" negotiation algorithm (as
9624           implemented by openssl's function SSL_select_next_proto) is used.
9625
9626            $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
9632           Advanced usage (you probably do not need this):
9633
9634            $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
9641            # 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
9653           To undefine/clear this callback use:
9654
9655            Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
9656
9657       •   CTX_set_next_protos_advertised_cb
9658
9659           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9660           requires at least openssl-1.0.1
9661
9662           NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
9663           connection.
9664
9665           Simple usage:
9666
9667            $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
9673           Advanced usage (you probably do not need this):
9674
9675            $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
9682            # 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
9689           To undefine/clear this callback use:
9690
9691            Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
9692
9693       •   P_next_proto_negotiated
9694
9695           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9696           requires at least openssl-1.0.1
9697
9698           Returns the name of negotiated protocol for given SSL connection
9699           $ssl.
9700
9701            $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
9706       •   P_next_proto_last_status
9707
9708           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9709           requires at least openssl-1.0.1
9710
9711           Returns the result of the last negotiation for given SSL connection
9712           $ssl.
9713
9714            $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
9722       Low level API: ALPN (application layer protocol negotiation) related
9723       functions
9724
9725       Application protocol can be negotiated via two different mechanisms
9726       employing two different TLS extensions: NPN (obsolete) and ALPN
9727       (recommended).
9728
9729       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
9734       With ALPN, the most basic implementation looks like this:
9735
9736        ### client side
9737        use Net::SSLeay;
9738        use IO::Socket::INET;
9739
9740        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
9749        warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
9750
9751        ### server side
9752        use Net::SSLeay;
9753        use IO::Socket::INET;
9754
9755        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
9762        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
9776       Advanced approach allows you to implement your own negotiation
9777       algorithm.
9778
9779        #see below documentation for:
9780        Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9781
9782       Detection of ALPN support (works even in older Net::SSLeay versions):
9783
9784        use Net::SSLeay;
9785
9786        if (exists &Net::SSLeay::P_alpn_selected) {
9787          # do ALPN stuff
9788        }
9789
9790       •   CTX_set_alpn_select_cb
9791
9792           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9793           requires at least openssl-1.0.2
9794
9795           NOTE: You need CTX_set_alpn_select_cb on server side of TLS
9796           connection.
9797
9798           Simple usage - in this case a "common" negotiation algorithm (as
9799           implemented by openssl's function SSL_select_next_proto) is used.
9800
9801            $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
9807           Advanced usage (you probably do not need this):
9808
9809            $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
9816            # 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
9827           To undefine/clear this callback use:
9828
9829            Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
9830
9831       •   set_alpn_protos
9832
9833           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9834           requires at least openssl-1.0.2
9835
9836           NOTE: You need set_alpn_protos on client side of TLS connection.
9837
9838           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
9842            Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
9843            # returns 0 on success
9844
9845       •   CTX_set_alpn_protos
9846
9847           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9848           requires at least openssl-1.0.2
9849
9850           NOTE: You need CTX_set_alpn_protos on client side of TLS
9851           connection.
9852
9853           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
9857            Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9858            # returns 0 on success
9859
9860       •   P_alpn_selected
9861
9862           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9863           requires at least openssl-1.0.2
9864
9865           Returns the name of negotiated protocol for given TLS connection
9866           $ssl.
9867
9868            $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
9873       Low level API: DANE Support
9874
9875       OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
9876       Authentication of Named Entities (DANE) Transport Layer Association
9877       within OpenSSL
9878
9879       •   SSL_get_tlsa_record_byname
9880
9881           COMPATIBILITY: DELETED from net-ssleay, since it is not supported
9882           by OpenSSL
9883
9884           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
9894            Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
9895
9896       Low level API: Other functions
9897
9898       •   COMP_add_compression_method
9899
9900           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
9905            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
9915           Check openssl doc
9916           <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
9917
9918       •   DH_free
9919
9920           Frees the DH structure and its components. The values are erased
9921           before the memory is returned to the system.
9922
9923            Net::SSLeay::DH_free($dh);
9924            # $dh - value corresponding to openssl's DH structure
9925            #
9926            # returns: no return value
9927
9928           Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
9929
9930       •   FIPS_mode_set
9931
9932           Enable or disable FIPS mode in a FIPS capable OpenSSL.
9933
9934            Net::SSLeay:: FIPS_mode_set($enable);
9935            # $enable - (integer) 1 to enable, 0 to disable
9936
9937       Low level API: EC related functions
9938
9939       •   CTX_set_tmp_ecdh
9940
9941           TBA
9942
9943       •   EC_KEY_free
9944
9945           TBA
9946
9947       •   EC_KEY_new_by_curve_name
9948
9949           TBA
9950
9951       •   EC_KEY_generate_key
9952
9953           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
9957            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
9961            # $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
9965           This function has no equivalent in OpenSSL but combines multiple
9966           OpenSSL functions for an easier interface.
9967
9968       •   CTX_set_ecdh_auto, set_ecdh_auto
9969
9970           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
9977             Net::SSLeay::CTX_set_ecdh_auto($ctx,1);
9978             Net::SSLeay::set_ecdh_auto($ssl,1);
9979
9980       •   CTX_set1_curves_list, set1_curves_list
9981
9982           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
9989             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
9992       •   CTX_set1_groups_list, set1_groups_list
9993
9994           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
10001             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
10004       Low level API: OSSL_LIB_CTX and OSSL_PROVIDER related functions
10005
10006       •   OSSL_LIB_CTX_get0_global_default
10007
10008           Returns a concrete (non NULL) reference to the global default
10009           library context.
10010
10011            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
10014           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
10018           Check openssl doc
10019           <https://www.openssl.org/docs/manmaster/man3/OSSL_LIB_CTX_get0_global_default.html>
10020
10021       •   OSSL_PROVIDER_load
10022
10023           Loads and initializes a provider
10024
10025            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
10031           Using undef loads the provider within the global default library
10032           context.
10033
10034            my $provider = Net::SSLeay::OSSL_PROVIDER_load(undef, 'legacy');
10035
10036           Check openssl doc
10037           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_load.html>
10038
10039       •   OSSL_PROVIDER_try_load
10040
10041           Loads and initializes a provider similar to OSSL_PROVIDER_load with
10042           additional fallback control.
10043
10044            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
10051           Check openssl doc
10052           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_try_load.html>
10053
10054       •   OSSL_PROVIDER_unload
10055
10056           Unloads the given provider.
10057
10058            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
10063           Check openssl doc
10064           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_unload.html>
10065
10066       •   OSSL_PROVIDER_available
10067
10068           Checks if a named provider is available for use.
10069
10070            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
10076           Check openssl doc
10077           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_available.html>
10078
10079       •   OSSL_PROVIDER_do_all
10080
10081           Iterates over all loaded providers. A callback is called for each
10082           provider.
10083
10084            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
10091           Example:
10092
10093            sub do_all_cb {
10094                my ($provider, $cbdata) = @_;
10095
10096                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
10102             # 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
10108           Check openssl doc
10109           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_do_all.html>
10110
10111       •   OSSL_PROVIDER_get0_name
10112
10113           Returns the name of the given provider.
10114
10115            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
10120           Check openssl doc
10121           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_get0_name.html>
10122
10123       •   OSSL_PROVIDER_self_test
10124
10125           Runs the provider's self tests.
10126
10127            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
10133           Check openssl doc
10134           <https://www.openssl.org/docs/manmaster/man3/OSSL_PROVIDER_self_test.html>
10135
10136   Constants
10137       There are many openssl constants available in Net::SSLeay. You can use
10138       them like this:
10139
10140        use Net::SSLeay;
10141        print &Net::SSLeay::NID_commonName;
10142        #or
10143        print Net::SSLeay::NID_commonName();
10144
10145       Or you can import them and use:
10146
10147        use Net::SSLeay qw/NID_commonName/;
10148        print &NID_commonName;
10149        #or
10150        print NID_commonName();
10151        #or
10152        print NID_commonName;
10153
10154       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
10159       The list of all available constant names:
10160
10161           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
10465   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
10470       Simply DO NOT USE THEM!
10471
10472       •   hello
10473
10474       •   blength
10475
10476       •   constant
10477

EXAMPLES

10479       One very good example to look at is the implementation of "sslcat()" in
10480       the "SSLeay.pm" file.
10481
10482       The following is a simple SSLeay client (with too little error checking
10483       :-(
10484
10485           #!/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
10492           ($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
10497           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
10501           # The network connection is now open, lets fire up SSL
10502
10503           $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
10511           # Exchange data
10512
10513           $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
10520           Net::SSLeay::free ($ssl);               # Tear down connection
10521           Net::SSLeay::CTX_free ($ctx);
10522           close S;
10523
10524       The following is a simple SSLeay echo server (non forking):
10525
10526           #!/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
10533           $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
10538           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
10545           # 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
10553           while (1) {
10554               print "Accepting connections...\n";
10555               ($addr = accept (NS, S))           or die "accept: $!";
10556               select (NS); $| = 1; select (STDOUT);  # Piping hot!
10557
10558               ($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
10563               # We now have a network connection, lets fire up SSLeay...
10564
10565               $ssl = Net::SSLeay::new($ctx)      or die_now("SSL_new ($ssl): $!");
10566               Net::SSLeay::set_fd($ssl, fileno(NS));
10567
10568               $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
10569               print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10570
10571               # Connected. Exchange some data.
10572
10573               $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
10577               Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
10578               die_if_ssl_error("ssl write");
10579
10580               Net::SSLeay::free ($ssl);           # Tear down connection
10581               close NS;
10582           }
10583
10584       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
10590           #!/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
10596           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
10601           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
10606           $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
10611           # 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
10616           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
10623           Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
10624           print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
10625
10626           $got = Net::SSLeay::read($ssl);
10627           die_if_ssl_error("ssl read");
10628           print "Got `$got' (" . length ($got) . " chars)\n";
10629
10630           Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
10631           die_if_ssl_error("ssl write");
10632
10633           Net::SSLeay::free ($ssl);         # Tear down the connection
10634           Net::SSLeay::CTX_free ($ctx);
10635           close LOG;
10636
10637       There are also a number of example/test programs in the examples
10638       directory:
10639
10640           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

INSTALLATION

10653       See README and README.* in the distribution directory for installation
10654       guidance on a variety of platforms.
10655

LIMITATIONS

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
10662           $reply = '';
10663           while ($got = Net::SSLeay::read($ssl)) {
10664               last if print_errs('SSL_read');
10665               $reply .= $got;
10666           }
10667
10668       Although there is no built-in limit in "Net::SSLeay::write()", the
10669       network packet size limitation applies here as well, thus use:
10670
10671           $written = 0;
10672
10673           while ($written < length($message)) {
10674               $written += Net::SSLeay::write($ssl, substr($message, $written));
10675               last if print_errs('SSL_write');
10676           }
10677
10678       Or alternatively you can just use the following convenience functions:
10679
10680           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

KNOWN BUGS AND CAVEATS

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
10696       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
10700       Autoloader emits a
10701
10702           Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
10703
10704       warning if die_if_ssl_error is made autoloadable. If you figure out
10705       why, drop me a line.
10706
10707       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
10712       Callback and certificate verification stuff is generally too little
10713       tested.
10714
10715       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
10722       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
10736       I've been pointed to two such daemons by Mik Firestone
10737       <mik@@speed.stdio._com> who has used them on Solaris 8:
10738
10739       1.  Entropy Gathering Daemon (EGD) at
10740           <http://www.lothar.com/tech/crypto/>
10741
10742       2.  Pseudo-random number generating daemon (PRNGD) at
10743           <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10744
10745       If you are using the low level API functions to communicate with other
10746       SSL implementations, you would do well to call
10747
10748           Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10749                or die_if_ssl_error("ssl ctx set options");
10750
10751       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
10754       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
10759           $Net::SSLeay::slowly = 1;   # Add sleep so broken servers can keep up
10760
10761       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
10766       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
10773       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
10780          $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
10787       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
10796       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
10800       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
10806       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
10813       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

DIAGNOSTICS

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
10828       open_tcp_connection: destination host not found:`server' (port 123)
10829       ($!)
10830           Name lookup for host named "server" failed.
10831
10832       open_tcp_connection: failed `server', 123 ($!)
10833           The name was resolved, but establishing the TCP connection failed.
10834
10835       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
10842       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
10847               /usr/local/ssl/bin/ssleay errstr 02001002
10848
10849       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

SECURITY

10857       You can mitigate some of the security vulnerabilities that might be
10858       present in your SSL/TLS application:
10859
10860   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
10865       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
10870       Solutions:
10871
10872       •   Compile with OpenSSL versions 0.9.6d or later, which enables
10873           SSL_OP_ALL by default
10874
10875       •   Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
10876           enabled by default)
10877
10878       •   Don't support SSLv2, SSLv3
10879
10880       •   Actively control the ciphers your server supports with
10881           set_cipher_list:
10882
10883       Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
10884
10885   Session Resumption
10886       http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
10887
10888       The SSL Labs vulnerability test on your SSL server might report in red:
10889
10890       Session resumption      No (IDs assigned but not accepted)
10891
10892       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
10899   Secure Renegotiation and DoS Attack
10900       https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
10901
10902       This is not a "security flaw," it is more of a DoS vulnerability.
10903
10904       Solutions:
10905
10906       •   Do not support SSLv2
10907
10908       •   Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
10909
10910       •   Compile with OpenSSL 0.9.8m or later
10911

BUGS

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
10918       •   the code you are trying to run;
10919
10920       •   your operating system name and version;
10921
10922       •   the output of "perl -V";
10923
10924       •   the version of OpenSSL or LibreSSL you are using.
10925

AUTHOR

10927       Originally written by Sampo Kellomäki.
10928
10929       Maintained by Florian Ragwitz between November 2005 and January 2010.
10930
10931       Maintained by Mike McCauley between November 2005 and June 2018.
10932
10933       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
10939       Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
10940
10941       Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
10942
10943       Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
10944
10945       Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
10946
10947       Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
10948
10949       All rights reserved.
10950

LICENSE

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

SEE ALSO

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
10971
10972
10973
10974perl v5.36.0                      2022-07-22                    Net::SSLeay(3)
Impressum