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

NAME

6       Net::SSLeay - Perl extension for using OpenSSL
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       Net::SSLeay module contains perl bindings to openssl
41       (<http://www.openssl.org>) library.
42
43       COMPATIBILITY NOTE: Net::SSLeay cannot be built with pre-0.9.3 openssl.
44       It is strongly recommended to use at least 0.9.7 (as older versions are
45       not tested during development). Some low level API functions may be
46       available with certain openssl versions.
47
48       It is compatible with OpenSSL 1.0 and 1.1. Some functions are not
49       available under OpenSSL 1.1.
50
51       Net::SSLeay module basically comprise of:
52
53       ·   High level functions for accessing web servers (by using
54           HTTP/HTTPS)
55
56       ·   Low level API (mostly mapped 1:1 to openssl's C functions)
57
58       ·   Convenience functions (related to low level API but with more perl
59           friendly interface)
60
61       There is also a related module called Net::SSLeay::Handle included in
62       this distribution that you might want to use instead. It has its own
63       pod documentation.
64
65   High level functions for accessing web servers
66       This module offers some high level convenience functions for accessing
67       web pages on SSL servers (for symmetry, the same API is offered for
68       accessing http servers, too), an "sslcat()" function for writing your
69       own clients, and finally access to the SSL api of the SSLeay/OpenSSL
70       package so you can write servers or clients for more complicated
71       applications.
72
73       For high level functions it is most convenient to import them into your
74       main namespace as indicated in the synopsis.
75
76       Basic set of functions
77
78       ·   get_https
79
80       ·   post_https
81
82       ·   put_https
83
84       ·   head_https
85
86       ·   do_https
87
88       ·   sslcat
89
90       ·   https_cat
91
92       ·   make_form
93
94       ·   make_headers
95
96       Case 1 (in SYNOPSIS) demonstrates the typical invocation of get_https()
97       to fetch an HTML page from secure server. The first argument provides
98       the hostname or IP in dotted decimal notation of the remote server to
99       contact. The second argument is the TCP port at the remote end (your
100       own port is picked arbitrarily from high numbered ports as usual for
101       TCP). The third argument is the URL of the page without the host name
102       part. If in doubt consult the HTTP specifications at
103       <http://www.w3c.org>.
104
105       Case 2 (in SYNOPSIS) demonstrates full fledged use of "get_https()". As
106       can be seen, "get_https()" parses the response and response headers and
107       returns them as a list, which can be captured in a hash for later
108       reference. Also a fourth argument to "get_https()" is used to insert
109       some additional headers in the request. "make_headers()" is a function
110       that will convert a list or hash to such headers. By default
111       "get_https()" supplies "Host" (to make virtual hosting easy) and
112       "Accept" (reportedly needed by IIS) headers.
113
114       Case 2b (in SYNOPSIS) demonstrates how to get a password protected
115       page. Refer to the HTTP protocol specifications for further details
116       (e.g. RFC-2617).
117
118       Case 3 (in SYNOPSIS) invokes "post_https()" to submit a HTML/CGI form
119       to a secure server. The first four arguments are equal to "get_https()"
120       (note that the empty string ('') is passed as header argument).  The
121       fifth argument is the contents of the form formatted according to CGI
122       specification.  Do not post UTF-8 data as content: use utf8::downgrade
123       first. In this case the helper function "make_https()" is used to do
124       the formatting, but you could pass any string. "post_https()"
125       automatically adds "Content-Type" and "Content-Length" headers to the
126       request.
127
128       Case 4 (in SYNOPSIS) shows the fundamental "sslcat()" function
129       (inspired in spirit by the "netcat" utility :-). It's your swiss army
130       knife that allows you to easily contact servers, send some data, and
131       then get the response. You are responsible for formatting the data and
132       parsing the response - "sslcat()" is just a transport.
133
134       Case 5 (in SYNOPSIS) is a full invocation of "sslcat()" which allows
135       the return of errors as well as the server (peer) certificate.
136
137       The $trace global variable can be used to control the verbosity of the
138       high level functions. Level 0 guarantees silence, level 1 (the default)
139       only emits error messages.
140
141       Alternate versions of high-level API
142
143       ·   get_https3
144
145       ·   post_https3
146
147       ·   put_https3
148
149       ·   get_https4
150
151       ·   post_https4
152
153       ·   put_https4
154
155       The above mentioned functions actually return the response headers as a
156       list, which only gets converted to hash upon assignment (this
157       assignment looses information if the same header occurs twice, as may
158       be the case with cookies). There are also other variants of the
159       functions that return unprocessed headers and that return a reference
160       to a hash.
161
162         ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
163         for ($i = 0; $i < $#headers; $i+=2) {
164             print "$headers[$i] = " . $headers[$i+1] . "\n";
165         }
166
167         ($page, $response, $headers, $server_cert)
168           = get_https3('www.bacus.pt', 443, '/');
169         print "$headers\n";
170
171         ($page, $response, $headers_ref)
172           = get_https4('www.bacus.pt', 443, '/');
173         for $k (sort keys %{$headers_ref}) {
174             for $v (@{$$headers_ref{$k}}) {
175                 print "$k = $v\n";
176             }
177         }
178
179       All of the above code fragments accomplish the same thing: display all
180       values of all headers. The API functions ending in "3" return the
181       headers simply as a scalar string and it is up to the application to
182       split them up. The functions ending in "4" return a reference to a hash
183       of arrays (see perlref and perllol if you are not familiar with complex
184       perl data structures). To access a single value of such a header hash
185       you would do something like
186
187         print $$headers_ref{COOKIE}[0];
188
189       Variants 3 and 4 also allow you to discover the server certificate in
190       case you would like to store or display it, e.g.
191
192         ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
193         if (!defined($server_cert) || ($server_cert == 0)) {
194             warn "Subject Name: undefined, Issuer  Name: undefined";
195         } else {
196             warn 'Subject Name: '
197                 . Net::SSLeay::X509_NAME_oneline(
198                        Net::SSLeay::X509_get_subject_name($server_cert))
199                     . 'Issuer  Name: '
200                         . Net::SSLeay::X509_NAME_oneline(
201                                Net::SSLeay::X509_get_issuer_name($server_cert));
202         }
203
204       Beware that this method only allows after the fact verification of the
205       certificate: by the time "get_https3()" has returned the https request
206       has already been sent to the server, whether you decide to trust it or
207       not. To do the verification correctly you must either employ the
208       OpenSSL certificate verification framework or use the lower level API
209       to first connect and verify the certificate and only then send the http
210       data. See the implementation of "ds_https3()" for guidance on how to do
211       this.
212
213       Using client certificates
214
215       Secure web communications are encrypted using symmetric crypto keys
216       exchanged using encryption based on the certificate of the server.
217       Therefore in all SSL connections the server must have a certificate.
218       This serves both to authenticate the server to the clients and to
219       perform the key exchange.
220
221       Sometimes it is necessary to authenticate the client as well. Two
222       options are available: HTTP basic authentication and a client side
223       certificate. The basic authentication over HTTPS is actually quite safe
224       because HTTPS guarantees that the password will not travel in the
225       clear. Never-the-less, problems like easily guessable passwords remain.
226       The client certificate method involves authentication of the client at
227       the SSL level using a certificate. For this to work, both the client
228       and the server have certificates (which typically are different) and
229       private keys.
230
231       The API functions outlined above accept additional arguments that allow
232       one to supply the client side certificate and key files. The format of
233       these files is the same as used for server certificates and the caveat
234       about encrypting private keys applies.
235
236         ($page, $result, %headers) =                                   # 2c
237                = get_https('www.bacus.pt', 443, '/protected.html',
238                     make_headers(Authorization =>
239                                  'Basic ' . MIME::Base64::encode("$user:$pass",'')),
240                     '', $mime_type6, $path_to_crt7, $path_to_key8);
241
242         ($page, $response, %reply_headers)
243                = post_https('www.bacus.pt', 443, '/foo.cgi',           # 3b
244                     make_headers('Authorization' =>
245                                  'Basic ' . MIME::Base64::encode("$user:$pass",'')),
246                     make_form(OK   => '1', name => 'Sampo'),
247                     $mime_type6, $path_to_crt7, $path_to_key8);
248
249       Case 2c (in SYNOPSIS) demonstrates getting a password protected page
250       that also requires a client certificate, i.e. it is possible to use
251       both authentication methods simultaneously.
252
253       Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
254       requires both password authentication and a client certificate, just
255       like in case 2c.
256
257       Note: The client will not send a certificate unless the server requests
258       one.  This is typically achieved by setting the verify mode to
259       "VERIFY_PEER" on the server:
260
261         Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
262
263       See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
264       description.
265
266       Working through a web proxy
267
268       ·   set_proxy
269
270       "Net::SSLeay" can use a web proxy to make its connections. You need to
271       first set the proxy host and port using "set_proxy()" and then just use
272       the normal API functions, e.g:
273
274         Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
275         ($page) = get_https('www.bacus.pt', 443, '/');
276
277       If your proxy requires authentication, you can supply a username and
278       password as well
279
280         Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
281         ($page, $result, %headers) =
282                = get_https('www.bacus.pt', 443, '/protected.html',
283                     make_headers(Authorization =>
284                                  'Basic ' . MIME::Base64::encode("susie:pass",''))
285                     );
286
287       This example demonstrates the case where we authenticate to the proxy
288       as "joe" and to the final web server as "susie". Proxy authentication
289       requires the "MIME::Base64" module to work.
290
291       HTTP (without S) API
292
293       ·   get_http
294
295       ·   post_http
296
297       ·   tcpcat
298
299       ·   get_httpx
300
301       ·   post_httpx
302
303       ·   tcpxcat
304
305       Over the years it has become clear that it would be convenient to use
306       the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
307       (see "LWP" for the heavy-weight object-oriented approach). In fact it
308       would be nice to be able to flip https on and off on the fly. Thus
309       regular HTTP support was evolved.
310
311         use Net::SSLeay qw(get_http post_http tcpcat
312                             get_httpx post_httpx tcpxcat
313                             make_headers make_form);
314
315         ($page, $result, %headers)
316                = get_http('www.bacus.pt', 443, '/protected.html',
317                     make_headers(Authorization =>
318                                  'Basic ' . MIME::Base64::encode("$user:$pass",''))
319                     );
320
321         ($page, $response, %reply_headers)
322                = post_http('www.bacus.pt', 443, '/foo.cgi', '',
323                       make_form(OK   => '1',
324                                 name => 'Sampo'
325                       ));
326
327         ($reply, $err) = tcpcat($host, $port, $request);
328
329         ($page, $result, %headers)
330                = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
331                     make_headers(Authorization =>
332                                  'Basic ' . MIME::Base64::encode("$user:$pass",''))
333                     );
334
335         ($page, $response, %reply_headers)
336                = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
337                       make_form(OK   => '1',  name => 'Sampo' ));
338
339         ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
340
341       As can be seen, the "x" family of APIs takes as the first argument a
342       flag which indicates whether SSL is used or not.
343
344   Certificate verification and Certificate Revocation Lists (CRLs)
345       OpenSSL supports the ability to verify peer certificates. It can also
346       optionally check the peer certificate against a Certificate Revocation
347       List (CRL) from the certificates issuer. A CRL is a file, created by
348       the certificate issuer that lists all the certificates that it
349       previously signed, but which it now revokes. CRLs are in PEM format.
350
351       You can enable "Net::SSLeay CRL" checking like this:
352
353                   &Net::SSLeay::X509_STORE_set_flags
354                       (&Net::SSLeay::CTX_get_cert_store($ssl),
355                        &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
356
357       After setting this flag, if OpenSSL checks a peer's certificate, then
358       it will attempt to find a CRL for the issuer. It does this by looking
359       for a specially named file in the search directory specified by
360       CTX_load_verify_locations.  CRL files are named with the hash of the
361       issuer's subject name, followed by ".r0", ".r1" etc.  For example
362       "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
363       issuer, and then check for a revocation of the peer certificate in all
364       of them.  (You can also force it to look in a specific named CRL file.,
365       see below).  You can find out the hash of the issuer subject name in a
366       CRL with
367
368               openssl crl -in crl.pem -hash -noout
369
370       If the peer certificate does not pass the revocation list, or if no CRL
371       is found, then the handshaking fails with an error.
372
373       You can also force OpenSSL to look for CRLs in one or more arbitrarily
374       named files.
375
376           my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
377           my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
378           if ($crl) {
379               Net::SSLeay::X509_STORE_add_crl(
380                    Net::SSLeay::CTX_get_cert_store($ssl, $crl)
381               );
382           } else {
383               error reading CRL....
384           }
385
386       Usually the URLs where you can download the CRLs is contained in the
387       certificate itself and you can extract them with
388
389           my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
390
391       But there is no automatic downloading of the CRLs and often these CRLs
392       are too huge to just download them to verify a single certificate.
393       Also, these CRLs are often in DER format which you need to convert to
394       PEM before you can use it:
395
396           openssl crl -in crl.der -inform der -out crl.pem
397
398       So as an alternative for faster and timely revocation checks you better
399       use the Online Status Revocation Protocol (OCSP).
400
401   Certificate verification and Online Status Revocation Protocol (OCSP)
402       While checking for revoked certificates is possible and fast with
403       Certificate Revocation Lists, you need to download the complete and
404       often huge list before you can verify a single certificate.
405
406       A faster way is to ask the CA to check the revocation of just a single
407       or a few certificates using OCSP. Basically you generate for each
408       certificate an OCSP_CERTID based on the certificate itself and its
409       issuer, put the ids togetether into an OCSP_REQUEST and send the
410       request to the URL given in the certificate.
411
412       As a result you get back an OCSP_RESPONSE and need to check the status
413       of the response, check that it is valid (e.g. signed by the CA) and
414       finally extract the information about each OCSP_CERTID to find out if
415       the certificate is still valid or got revoked.
416
417       With Net::SSLeay this can be done like this:
418
419           # get id(s) for given certs, like from get_peer_certificate
420           # or get_peer_cert_chain. This will croak if
421           # - one tries to make an OCSP_CERTID for a self-signed certificate
422           # - the issuer of the certificate cannot be found in the SSL objects
423           #   store, nor in the current certificate chain
424           my $cert = Net::SSLeay::get_peer_certificate($ssl);
425           my $id = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) };
426           die "failed to make OCSP_CERTID: $@" if $@;
427
428           # create OCSP_REQUEST from id(s)
429           # Multiple can be put into the same request, if the same OCSP responder
430           # is responsible for them.
431           my $req = Net::SSLeay::OCSP_ids2req($id);
432
433           # determine URI of OCSP responder
434           my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
435
436           # Send stringified OCSP_REQUEST with POST to $uri.
437           # We can ignore certificate verification for https, because the OCSP
438           # response itself is signed.
439           my $ua = HTTP::Tiny->new(verify_SSL => 0);
440           my $res = $ua->request( 'POST',$uri, {
441               headers => { 'Content-type' => 'application/ocsp-request' },
442               content => Net::SSLeay::i2d_OCSP_REQUEST($req)
443           });
444           my $content = $res && $res->{success} && $res->{content}
445               or die "query failed";
446
447           # Extract OCSP_RESPONSE.
448           # this will croak if the string is not an OCSP_RESPONSE
449           my $resp = eval { Net::SSLeay::d2i_OCSP_RESPONSE($content) };
450
451           # Check status of response.
452           my $status = Net::SSLeay::OCSP_response_status($resp);
453           if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL())
454               die "OCSP response failed: ".
455                   Net::SSLeay::OCSP_response_status_str($status);
456           }
457
458           # Verify signature of response and if nonce matches request.
459           # This will croak if there is a nonce in the response, but it does not match
460           # the request. It will return false if the signature could not be verified,
461           # in which case details can be retrieved with Net::SSLeay::ERR_get_error.
462           # It will not complain if the response does not contain a nonce, which is
463           # usually the case with pre-signed responses.
464           if ( ! eval { Net::SSLeay::OCSP_response_verify($ssl,$resp,$req) }) {
465               die "OCSP response verification failed";
466           }
467
468           # Extract information from OCSP_RESPONSE for each of the ids.
469
470           # If called in scalar context it will return the time (as time_t), when the
471           # next update is due (minimum of all successful responses inside $resp). It
472           # will croak on the following problems:
473           # - response is expired or not yet valid
474           # - no response for given OCSP_CERTID
475           # - certificate status is not good (e.g. revoked or unknown)
476           if ( my $nextupd = eval { Net::SSLeay::OCSP_response_results($resp,$id) }) {
477               warn "certificate is valid, next update in ".
478                   ($nextupd-time())." seconds\n";
479           } else {
480               die "certificate is not valid: $@";
481           }
482
483           # But in array context it will return detailed information about each given
484           # OCSP_CERTID instead croaking on errors:
485           # if no @ids are given it will return information about all single responses
486           # in the OCSP_RESPONSE
487           my @results = Net::SSLeay::OCSP_response_results($resp,@ids);
488           for my $r (@results) {
489               print Dumper($r);
490               # @results are in the same order as the @ids and contain:
491               # $r->[0] - OCSP_CERTID
492               # $r->[1] - undef if no error (certificate good) OR error message as string
493               # $r->[2] - hash with details:
494               #   thisUpdate - time_t of this single response
495               #   nextUpdate - time_t when update is expected
496               #   statusType - integer:
497               #      V_OCSP_CERTSTATUS_GOOD(0)
498               #      V_OCSP_CERTSTATUS_REVOKED(1)
499               #      V_OCSP_CERTSTATUS_UNKNOWN(2)
500               #   revocationTime - time_t (only if revoked)
501               #   revocationReason - integer (only if revoked)
502               #   revocationReason_str - reason as string (only if revoked)
503           }
504
505       To further speed up certificate revocation checking one can use a TLS
506       extension to instruct the server to staple the OCSP response:
507
508           # set TLS extension before doing SSL_connect
509           Net::SSLeay::set_tlsext_status_type($ssl,
510               Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
511
512           # setup callback to verify OCSP response
513           my $cert_valid = undef;
514           Net::SSLeay::CTX_set_tlsext_status_cb($context,sub {
515               my ($ssl,$resp) = @_;
516               if (!$resp) {
517                   # Lots of servers don't return an OCSP response.
518                   # In this case we must check the OCSP status outside the SSL
519                   # handshake.
520                   warn "server did not return stapled OCSP response\n";
521                   return 1;
522               }
523               # verify status
524               my $status = Net::SSLeay::OCSP_response_status($resp);
525               if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL()) {
526                   warn "OCSP response failure: $status\n";
527                   return 1;
528               }
529               # verify signature - we have no OCSP_REQUEST here to check nonce
530               if (!eval { Net::SSLeay::OCSP_response_verify($ssl,$resp) }) {
531                   warn "OCSP response verify failed\n";
532                   return 1;
533               }
534               # check if the certificate is valid
535               # we should check here against the peer_certificate
536               my $cert = Net::SSLeay::get_peer_certificate();
537               my $certid = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) } or do {
538                   warn "cannot get certid from cert: $@";
539                   $cert_valid = -1;
540                   return 1;
541               };
542
543               if ( $nextupd = eval {
544                   Net::SSLeay::OCSP_response_results($resp,$certid) }) {
545                   warn "certificate not revoked\n";
546                   $cert_valid = 1;
547               } else {
548                   warn "certificate not valid: $@";
549                   $cert_valid = 0;
550               }
551           });
552
553           # do SSL handshake here
554           ....
555           # check if certificate revocation was checked already
556           if ( ! defined $cert_valid) {
557               # check revocation outside of SSL handshake by asking OCSP responder
558               ...
559           } elsif ( ! $cert_valid ) {
560               die "certificate not valid - closing SSL connection";
561           } elsif ( $cert_valid<0 ) {
562               die "cannot verify certificate revocation - self-signed ?";
563           } else {
564               # everything fine
565               ...
566           }
567
568   Using Net::SSLeay in multi-threaded applications
569       IMPORTANT: versions 1.42 or earlier are not thread-safe!
570
571       Net::SSLeay module implements all necessary stuff to be ready for
572       multi-threaded environment - it requires openssl-0.9.7 or newer. The
573       implementation fully follows thread safety related requirements of
574       openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
575
576       If you are about to use Net::SSLeay (or any other module based on
577       Net::SSLeay) in multi-threaded perl application it is recommended to
578       follow this best-practice:
579
580       Initialization
581
582       Load and initialize Net::SSLeay module in the main thread:
583
584           use threads;
585           use Net::SSLeay;
586
587           Net::SSLeay::load_error_strings();
588           Net::SSLeay::SSLeay_add_ssl_algorithms();
589           Net::SSLeay::randomize();
590
591           sub do_master_job {
592             #... call whatever from Net::SSLeay
593           }
594
595           sub do_worker_job {
596             #... call whatever from Net::SSLeay
597           }
598
599           #start threads
600           my $master  = threads->new(\&do_master_job, 'param1', 'param2');
601           my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
602
603           #waiting for all threads to finish
604           $_->join() for (threads->list);
605
606       NOTE: Openssl's "int SSL_library_init(void)" function (which is also
607       aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
608       and "add_ssl_algorithms") is not re-entrant and multiple calls can
609       cause a crash in threaded application.  Net::SSLeay implements flags
610       preventing repeated calls to this function, therefore even multiple
611       initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
612       without trouble.
613
614       Using callbacks
615
616       Do not use callbacks across threads (the module blocks cross-thread
617       callback operations and throws a warning). Always do the callback
618       setup, callback use and callback destruction within the same thread.
619
620       Using openssl elements
621
622       All openssl elements (X509, SSL_CTX, ...) can be directly passed
623       between threads.
624
625           use threads;
626           use Net::SSLeay;
627
628           Net::SSLeay::load_error_strings();
629           Net::SSLeay::SSLeay_add_ssl_algorithms();
630           Net::SSLeay::randomize();
631
632           sub do_job {
633             my $context = shift;
634             Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
635             #...
636           }
637
638           my $c = Net::SSLeay::CTX_new();
639           threads->create(\&do_job, $c);
640
641       Or:
642
643           use threads;
644           use Net::SSLeay;
645
646           my $context; #does not need to be 'shared'
647
648           Net::SSLeay::load_error_strings();
649           Net::SSLeay::SSLeay_add_ssl_algorithms();
650           Net::SSLeay::randomize();
651
652           sub do_job {
653             Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
654             #...
655           }
656
657           $context = Net::SSLeay::CTX_new();
658           threads->create(\&do_job);
659
660       Using other perl modules based on Net::SSLeay
661
662       It should be fine to use any other module based on Net::SSLeay (like
663       IO::Socket::SSL) in multi-threaded applications. It is generally
664       recommended to do any global initialization of such a module in the
665       main thread before calling "threads->new(..)" or "threads->create(..)"
666       but it might differ module by module.
667
668       To be safe you can load and init Net::SSLeay explicitly in the main
669       thread:
670
671           use Net::SSLeay;
672           use Other::SSLeay::Based::Module;
673
674           Net::SSLeay::load_error_strings();
675           Net::SSLeay::SSLeay_add_ssl_algorithms();
676           Net::SSLeay::randomize();
677
678       Or even safer:
679
680           use Net::SSLeay;
681           use Other::SSLeay::Based::Module;
682
683           BEGIN {
684             Net::SSLeay::load_error_strings();
685             Net::SSLeay::SSLeay_add_ssl_algorithms();
686             Net::SSLeay::randomize();
687           }
688
689       Combining Net::SSLeay with other modules linked with openssl
690
691       BEWARE: This might be a big trouble! This is not guaranteed be thread-
692       safe!
693
694       There are many other (XS) modules linked directly to openssl library
695       (like Crypt::SSLeay).
696
697       As it is expected that also "another" module will call
698       "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
699       multiple openssl initialization by Net::SSLeay and "another" module.
700
701       As you can expect Net::SSLeay is not able to avoid multiple
702       initialization of openssl library called by "another" module, thus you
703       have to handle this on your own (in some cases it might not be possible
704       at all to avoid this).
705
706       Threading with get_https and friends
707
708       The convenience functions get_https, post_https etc all initialize the
709       SSL library by calling Net::SSLeay::initialize which does the
710       conventional library initialization:
711
712           Net::SSLeay::load_error_strings();
713           Net::SSLeay::SSLeay_add_ssl_algorithms();
714           Net::SSLeay::randomize();
715
716       Net::SSLeay::initialize initializes the SSL library at most once.  You
717       can override the Net::SSLeay::initialize function if you desire some
718       other type of initialization behaviour by get_https and friends.  You
719       can call Net::SSLeay::initialize from your own code if you desire this
720       conventional library initialization.
721
722   Convenience routines
723       To be used with Low level API
724
725           Net::SSLeay::randomize($rn_seed_file,$additional_seed);
726           Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
727           $cert = Net::SSLeay::dump_peer_certificate($ssl);
728           Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
729           $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
730
731           $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
732           $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
733           Net::SSLeay::ssl_write_CRLF($ssl, $message);
734
735       ·   randomize
736
737           seeds the openssl PRNG with "/dev/urandom" (see the top of
738           "SSLeay.pm" for how to change or configure this) and optionally
739           with user provided data. It is very important to properly seed your
740           random numbers, so do not forget to call this. The high level API
741           functions automatically call "randomize()" so it is not needed with
742           them. See also caveats.
743
744       ·   set_cert_and_key
745
746           takes two file names as arguments and sets the certificate and
747           private key to those. This can be used to set either server
748           certificates or client certificates.
749
750       ·   dump_peer_certificate
751
752           allows you to get a plaintext description of the certificate the
753           peer (usually the server) presented to us.
754
755       ·   ssl_read_all
756
757           see ssl_write_all (below)
758
759       ·   ssl_write_all
760
761           "ssl_read_all()" and "ssl_write_all()" provide true blocking
762           semantics for these operations (see limitation, below, for
763           explanation). These are much preferred to the low level API
764           equivalents (which implement BSD blocking semantics). The message
765           argument to "ssl_write_all()" can be a reference. This is helpful
766           to avoid unnecessary copying when writing something big, e.g:
767
768               $data = 'A' x 1000000000;
769               Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
770
771       ·   ssl_read_CRLF
772
773           uses "ssl_read_all()" to read in a line terminated with a carriage
774           return followed by a linefeed (CRLF).  The CRLF is included in the
775           returned scalar.
776
777       ·   ssl_read_until
778
779           uses "ssl_read_all()" to read from the SSL input stream until it
780           encounters a programmer specified delimiter.  If the delimiter is
781           undefined, $/ is used.  If $/ is undefined, "\n" is used.  One can
782           optionally set a maximum length of bytes to read from the SSL input
783           stream.
784
785       ·   ssl_write_CRLF
786
787           writes $message and appends CRLF to the SSL output stream.
788
789   Initialization
790       In order to use the low level API you should start your programs with
791       the following incantation:
792
793               use Net::SSLeay qw(die_now die_if_ssl_error);
794               Net::SSLeay::load_error_strings();
795               Net::SSLeay::SSLeay_add_ssl_algorithms();    # Important!
796               Net::SSLeay::ENGINE_load_builtin_engines();  # If you want built-in engines
797               Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
798               Net::SSLeay::randomize();
799
800   Error handling functions
801       I can not emphasize the need to check for error enough. Use these
802       functions even in the most simple programs, they will reduce debugging
803       time greatly. Do not ask questions on the mailing list without having
804       first sprinkled these in your code.
805
806       ·   die_now
807
808       ·   die_if_ssl_error
809
810           "die_now()" and "die_if_ssl_error()" are used to conveniently print
811           the SSLeay error stack when something goes wrong:
812
813                   Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
814
815
816                   Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
817
818       ·   print_errs
819
820           You can also use "Net::SSLeay::print_errs()" to dump the error
821           stack without exiting the program. As can be seen, your code
822           becomes much more readable if you import the error reporting
823           functions into your main name space.
824
825   Sockets
826       Perl uses file handles for all I/O. While SSLeay has a quite flexible
827       BIO mechanism and perl has an evolved PerlIO mechanism, this module
828       still sticks to using file descriptors. Thus to attach SSLeay to a
829       socket you should use "fileno()" to extract the underlying file
830       descriptor:
831
832           Net::SSLeay::set_fd($ssl, fileno(S));   # Must use fileno
833
834       You should also set $| to 1 to eliminate STDIO buffering so you do not
835       get confused if you use perl I/O functions to manipulate your socket
836       handle.
837
838       If you need to select(2) on the socket, go right ahead, but be warned
839       that OpenSSL does some internal buffering so SSL_read does not always
840       return data even if the socket selected for reading (just keep on
841       selecting and trying to read). "Net::SSLeay" is no different from the C
842       language OpenSSL in this respect.
843
844   Callbacks
845       You can establish a per-context verify callback function something like
846       this:
847
848               sub verify {
849                   my ($ok, $x509_store_ctx) = @_;
850                   print "Verifying certificate...\n";
851                       ...
852                   return $ok;
853               }
854
855       It is used like this:
856
857               Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
858
859       Per-context callbacks for decrypting private keys are implemented.
860
861               Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
862               Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
863                                                    Net::SSLeay::FILETYPE_PEM)
864                   or die "Error reading private key";
865               Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
866
867       If Hello Extensions are supported by your OpenSSL, a session secret
868       callback can be set up to be called when a session secret is set by
869       openssl.
870
871       Establish it like this:
872           Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb,
873       $somedata);
874
875       It will be called like this:
876
877           sub session_secret_cb
878           {
879               my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
880           }
881
882       No other callbacks are implemented. You do not need to use any callback
883       for simple (i.e. normal) cases where the SSLeay built-in verify
884       mechanism satisfies your needs.
885
886       It is required to reset these callbacks to undef immediately after use
887       to prevent memory leaks, thread safety problems and crashes on exit
888       that can occur if different threads set different callbacks.
889
890       If you want to use callback stuff, see examples/callback.pl! It's the
891       only one I am able to make work reliably.
892
893   Low level API
894       In addition to the high level functions outlined above, this module
895       contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
896       API.
897
898       See the "*.h" headers from OpenSSL C distribution for a list of low
899       level SSLeay functions to call (check SSLeay.xs to see if some function
900       has been implemented). The module strips the initial "SSL_" off of the
901       SSLeay names.  Generally you should use "Net::SSLeay::" in its place.
902
903       Note that some functions are prefixed with "P_" - these are very close
904       to the original API however contain some kind of a wrapper making its
905       interface more perl friendly.
906
907       For example:
908
909       In C:
910
911               #include <ssl.h>
912
913               err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
914                                          &your_call_back_here);
915
916       In Perl:
917
918               use Net::SSLeay;
919
920               $err = Net::SSLeay::set_verify ($ssl,
921                                               Net::SSLeay::VERIFY_CLIENT_ONCE,
922                                               \&your_call_back_here);
923
924       If the function does not start with "SSL_" you should use the full
925       function name, e.g.:
926
927               $err = Net::SSLeay::ERR_get_error;
928
929       The following new functions behave in perlish way:
930
931               $got = Net::SSLeay::read($ssl);
932                                           # Performs SSL_read, but returns $got
933                                           # resized according to data received.
934                                           # Returns undef on failure.
935
936               Net::SSLeay::write($ssl, $foo) || die;
937                                           # Performs SSL_write, but automatically
938                                           # figures out the size of $foo
939
940       Low level API: Version related functions
941
942       ·   SSLeay
943
944           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
945
946           Gives version number (numeric) of underlaying openssl library.
947
948            my $ver_number = Net::SSLeay::SSLeay();
949            # returns: the number identifying the openssl release
950            #
951            # 0x00903100 => openssl-0.9.3
952            # 0x00904100 => openssl-0.9.4
953            # 0x00905100 => openssl-0.9.5
954            # 0x0090600f => openssl-0.9.6
955            # 0x0090601f => openssl-0.9.6a
956            # 0x0090602f => openssl-0.9.6b
957            # ...
958            # 0x009060df => openssl-0.9.6m
959            # 0x0090700f => openssl-0.9.7
960            # 0x0090701f => openssl-0.9.7a
961            # 0x0090702f => openssl-0.9.7b
962            # ...
963            # 0x009070df => openssl-0.9.7m
964            # 0x0090800f => openssl-0.9.8
965            # 0x0090801f => openssl-0.9.8a
966            # 0x0090802f => openssl-0.9.8b
967            # ...
968            # 0x0090814f => openssl-0.9.8t
969            # 0x1000000f => openssl-1.0.0
970            # 0x1000004f => openssl-1.0.0d
971            # 0x1000007f => openssl-1.0.0g
972
973           You can use it like this:
974
975             if (Net::SSLeay::SSLeay() < 0x0090800f) {
976               die "you need openssl-0.9.8 or higher";
977             }
978
979       ·   SSLeay_version
980
981           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
982
983           Gives version number (string) of underlaying openssl library.
984
985            my $ver_string = Net::SSLeay::SSLeay_version($type);
986            # $type
987            #   SSLEAY_VERSION  - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
988            #   SSLEAY_CFLAGS   - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
989            #   SSLEAY_BUILT_ON - e.g. 'built on: Fri May  6 00:00:46 GMT 2011'
990            #   SSLEAY_PLATFORM - e.g. 'platform: mingw'
991            #   SSLEAY_DIR      - e.g. 'OPENSSLDIR: "z:/...."'
992            #
993            # returns: string
994
995            Net::SSLeay::SSLeay_version();
996            #is equivalent to
997            Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
998
999           Check openssl doc
1000           <https://www.openssl.org/docs/man1.0.2/crypto/SSLeay_version.html>
1001
1002       ·   OpenSSL_version_num
1003
1004           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1005           requires at least OpenSSL 1.1.0
1006
1007           Gives version number (numeric) of underlaying openssl library. See
1008           "SSLeay" for interpreting the result.
1009
1010            my $ver_number = Net::SSLeay::OpenSSL_version_num();
1011            # returns: the number identifying the openssl release
1012
1013       ·   OpenSSL_version
1014
1015           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1016           requires at least OpenSSL 1.1.0
1017
1018           Gives version number (string) of underlaying openssl library.
1019
1020            my $ver_string = Net::SSLeay::OpenSSL_version($t);
1021            # $t
1022            #   OPENSSL_VERSION     - e.g. 'OpenSSL 1.1.0g  2 Nov 2017'
1023            #   OPENSSL_CFLAGS      - e.g. 'compiler: cc -DDSO_DLFCN -DHAVE_DLFCN_H .....'
1024            #   OPENSSL_BUILT_ON    - e.g. 'built on: reproducible build, date unspecified'
1025            #   OPENSSL_PLATFORM    - e.g. 'platform: darwin64-x86_64-cc'
1026            #   OPENSSL_DIR         - e.g. 'OPENSSLDIR: "/opt/openssl-1.1.0g"'
1027            #   OPENSSL_ENGINES_DIR - e.g. 'ENGINESDIR: "/opt/openssl-1.1.0g/lib/engines-1.1"'
1028            #
1029            # returns: string
1030
1031            Net::SSLeay::OpenSSL_version();
1032            #is equivalent to
1033            Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1034
1035           Check openssl doc
1036           <https://www.openssl.org/docs/crypto/OpenSSL_version.html>
1037
1038       Low level API: Initialization related functions
1039
1040       ·   library_init
1041
1042           Initialize SSL library by registering algorithms.
1043
1044            my $rv = Net::SSLeay::library_init();
1045
1046           Check openssl doc
1047           <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1048
1049           While the original function from OpenSSL always returns 1,
1050           Net::SSLeay adds a wrapper around it to make sure that the OpenSSL
1051           function is only called once.  Thus the function will return 1 if
1052           initialization was done and 0 if not, i.e. if initialization was
1053           done already before.
1054
1055       ·   add_ssl_algorithms
1056
1057           The alias for "library_init"
1058
1059            Net::SSLeay::add_ssl_algorithms();
1060
1061       ·   OpenSSL_add_ssl_algorithms
1062
1063           The alias for "library_init"
1064
1065            Net::SSLeay::OpenSSL_add_ssl_algorithms();
1066
1067       ·   SSLeay_add_ssl_algorithms
1068
1069           The alias for "library_init"
1070
1071            Net::SSLeay::SSLeay_add_ssl_algorithms();
1072
1073       ·   load_error_strings
1074
1075           Registers the error strings for all libcrypto + libssl related
1076           functions.
1077
1078            Net::SSLeay::load_error_strings();
1079            #
1080            # returns: no return value
1081
1082           Check openssl doc
1083           <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1084
1085       ·   ERR_load_crypto_strings
1086
1087           Registers the error strings for all libcrypto functions. No need to
1088           call this function if you have already called "load_error_strings".
1089
1090            Net::SSLeay::ERR_load_crypto_strings();
1091            #
1092            # returns: no return value
1093
1094           Check openssl doc
1095           <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1096
1097       ·   ERR_load_RAND_strings
1098
1099           Registers the error strings for RAND related functions. No need to
1100           call this function if you have already called "load_error_strings".
1101
1102            Net::SSLeay::ERR_load_RAND_strings();
1103            #
1104            # returns: no return value
1105
1106       ·   ERR_load_SSL_strings
1107
1108           Registers the error strings for SSL related functions. No need to
1109           call this function if you have already called "load_error_strings".
1110
1111            Net::SSLeay::ERR_load_SSL_strings();
1112            #
1113            # returns: no return value
1114
1115       ·   OpenSSL_add_all_algorithms
1116
1117           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1118
1119           Add algorithms to internal table.
1120
1121            Net::SSLeay::OpenSSL_add_all_algorithms();
1122            #
1123            # returns: no return value
1124
1125           Check openssl doc
1126           <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1127
1128       ·   OPENSSL_add_all_algorithms_conf
1129
1130           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1131
1132           Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1133           config file
1134
1135            Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1136            #
1137            # returns: no return value
1138
1139       ·   OPENSSL_add_all_algorithms_noconf
1140
1141           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1142
1143           Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1144           config file
1145
1146            Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1147            #
1148            # returns: no return value
1149
1150       Low level API: ERR_* and SSL_alert_* related functions
1151
1152       NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1153       from their names.
1154
1155       ·   ERR_clear_error
1156
1157           Clear the error queue.
1158
1159            Net::SSLeay::ERR_clear_error();
1160            #
1161            # returns: no return value
1162
1163           Check openssl doc
1164           <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1165
1166       ·   ERR_error_string
1167
1168           Generates a human-readable string representing the error code
1169           $error.
1170
1171            my $rv = Net::SSLeay::ERR_error_string($error);
1172            # $error - (unsigned integer) error code
1173            #
1174            # returns: string
1175
1176           Check openssl doc
1177           <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1178
1179       ·   ERR_get_error
1180
1181           Returns the earliest error code from the thread's error queue and
1182           removes the entry.  This function can be called repeatedly until
1183           there are no more error codes to return.
1184
1185            my $rv = Net::SSLeay::ERR_get_error();
1186            #
1187            # returns: (unsigned integer) error code
1188
1189           Check openssl doc
1190           <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1191
1192       ·   ERR_peek_error
1193
1194           Returns the earliest error code from the thread's error queue
1195           without modifying it.
1196
1197            my $rv = Net::SSLeay::ERR_peek_error();
1198            #
1199            # returns: (unsigned integer) error code
1200
1201           Check openssl doc
1202           <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1203
1204       ·   ERR_put_error
1205
1206           Adds an error code to the thread's error queue. It signals that the
1207           error of $reason code reason occurred in function $func of library
1208           $lib, in line number $line of $file.
1209
1210            Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
1211            # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
1212            # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
1213            # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
1214            # $file - (string) file name
1215            # $line - (integer) line number in $file
1216            #
1217            # returns: no return value
1218
1219           Check openssl doc
1220           <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
1221           <http://www.openssl.org/docs/crypto/err.html>
1222
1223       ·   alert_desc_string
1224
1225           Returns a two letter string as a short form describing the reason
1226           of the alert specified by value.
1227
1228            my $rv = Net::SSLeay::alert_desc_string($value);
1229            # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1230            #
1231            # returns: description string (2 letters)
1232
1233           Check openssl doc
1234           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1235
1236       ·   alert_desc_string_long
1237
1238           Returns a string describing the reason of the alert specified by
1239           value.
1240
1241            my $rv = Net::SSLeay::alert_desc_string_long($value);
1242            # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1243            #
1244            # returns: description string
1245
1246           Check openssl doc
1247           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1248
1249       ·   alert_type_string
1250
1251           Returns a one letter string indicating the type of the alert
1252           specified by value.
1253
1254            my $rv = Net::SSLeay::alert_type_string($value);
1255            # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1256            #
1257            # returns: string (1 letter)
1258
1259           Check openssl doc
1260           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1261
1262       ·   alert_type_string_long
1263
1264           Returns a string indicating the type of the alert specified by
1265           value.
1266
1267            my $rv = Net::SSLeay::alert_type_string_long($value);
1268            # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1269            #
1270            # returns: string
1271
1272           Check openssl doc
1273           <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1274
1275       Low level API: SSL_METHOD_* related functions
1276
1277       ·   SSLv23_method, SSLv23_server_method and SSLv23_client_method
1278
1279           COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1280
1281           Returns SSL_METHOD structure corresponding to general-purpose
1282           version-flexible TLS method, the return value can be later used as
1283           a param of "CTX_new_with_method".
1284
1285           NOTE: Consider using TLS_method, TLS_server_method or
1286           TLS_client_method with new code.
1287
1288            my $rv = Net::SSLeay::SSLv2_method();
1289            #
1290            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1291
1292       ·   SSLv2_method
1293
1294           Returns SSL_METHOD structure corresponding to SSLv2 method, the
1295           return value can be later used as a param of "CTX_new_with_method".
1296           Only available where supported by the underlying openssl.
1297
1298            my $rv = Net::SSLeay::SSLv2_method();
1299            #
1300            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1301
1302       ·   SSLv3_method
1303
1304           Returns SSL_METHOD structure corresponding to SSLv3 method, the
1305           return value can be later used as a param of "CTX_new_with_method".
1306
1307            my $rv = Net::SSLeay::SSLv3_method();
1308            #
1309            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1310
1311           Check openssl doc
1312           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1313
1314       ·   TLSv1_method, TLSv1_server_method and TLSv1_client_method
1315
1316           COMPATIBILITY: Server and client methods not available in
1317           Net-SSLeay-1.82 and before.
1318
1319           Returns SSL_METHOD structure corresponding to TLSv1 method, the
1320           return value can be later used as a param of "CTX_new_with_method".
1321
1322            my $rv = Net::SSLeay::TLSv1_method();
1323            #
1324            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1325
1326           Check openssl doc
1327           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1328
1329       ·   TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1330
1331           COMPATIBILITY: Server and client methods not available in
1332           Net-SSLeay-1.82 and before.
1333
1334           Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1335           return value can be later used as a param of "CTX_new_with_method".
1336           Only available where supported by the underlying openssl.
1337
1338            my $rv = Net::SSLeay::TLSv1_1_method();
1339            #
1340            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1341
1342           Check openssl doc
1343           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1344
1345       ·   TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1346
1347           COMPATIBILITY: Server and client methods not available in
1348           Net-SSLeay-1.82 and before.
1349
1350           Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1351           return value can be later used as a param of "CTX_new_with_method".
1352           Only available where supported by the underlying openssl.
1353
1354            my $rv = Net::SSLeay::TLSv1_2_method();
1355            #
1356            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1357
1358           Check openssl doc
1359           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1360
1361       ·   TLS_method, TLS_server_method and TLS_client_method
1362
1363           COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1364
1365           Returns SSL_METHOD structure corresponding to general-purpose
1366           version-flexible TLS method, the return value can be later used as
1367           a param of "CTX_new_with_method". Only available where supported by
1368           the underlying openssl.
1369
1370            my $rv = Net::SSLeay::TLS_method();
1371            #
1372            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1373
1374           Check openssl doc
1375           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1376
1377       Low level API: ENGINE_* related functions
1378
1379       ·   ENGINE_load_builtin_engines
1380
1381           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1382           loading support.
1383
1384           Load all bundled ENGINEs into memory and make them visible.
1385
1386            Net::SSLeay::ENGINE_load_builtin_engines();
1387            #
1388            # returns: no return value
1389
1390           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1391
1392       ·   ENGINE_register_all_complete
1393
1394           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1395           loading support.
1396
1397           Register all loaded ENGINEs for every algorithm they collectively
1398           implement.
1399
1400            Net::SSLeay::ENGINE_register_all_complete();
1401            #
1402            # returns: no return value
1403
1404           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1405
1406       ·   ENGINE_set_default
1407
1408           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1409           loading support.
1410
1411           Set default engine to $e + set its flags to $flags.
1412
1413            my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1414            # $e - value corresponding to openssl's ENGINE structure
1415            # $flags - (integer) engine flags
1416            #          flags value can be made by bitwise "OR"ing:
1417            #          0x0001 - ENGINE_METHOD_RSA
1418            #          0x0002 - ENGINE_METHOD_DSA
1419            #          0x0004 - ENGINE_METHOD_DH
1420            #          0x0008 - ENGINE_METHOD_RAND
1421            #          0x0010 - ENGINE_METHOD_ECDH
1422            #          0x0020 - ENGINE_METHOD_ECDSA
1423            #          0x0040 - ENGINE_METHOD_CIPHERS
1424            #          0x0080 - ENGINE_METHOD_DIGESTS
1425            #          0x0100 - ENGINE_METHOD_STORE
1426            #          0x0200 - ENGINE_METHOD_PKEY_METHS
1427            #          0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1428            #          Obvious all-or-nothing cases:
1429            #          0xFFFF - ENGINE_METHOD_ALL
1430            #          0x0000 - ENGINE_METHOD_NONE
1431            #
1432            # returns: 1 on success, 0 on failure
1433
1434           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1435
1436       ·   ENGINE_by_id
1437
1438           Get ENGINE by its identification $id.
1439
1440           COMPATIBILITY: Requires an OpenSSL build with dynamic engine
1441           loading support.
1442
1443            my $rv = Net::SSLeay::ENGINE_by_id($id);
1444            # $id - (string) engine identification e.g. "dynamic"
1445            #
1446            # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1447
1448           Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1449
1450       Low level API: EVP_PKEY_* related functions
1451
1452       ·   EVP_PKEY_copy_parameters
1453
1454           Copies the parameters from key $from to key $to.
1455
1456            my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1457            # $to - value corresponding to openssl's EVP_PKEY structure
1458            # $from - value corresponding to openssl's EVP_PKEY structure
1459            #
1460            # returns: 1 on success, 0 on failure
1461
1462           Check openssl doc
1463           <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1464
1465       ·   EVP_PKEY_new
1466
1467           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1468
1469           Creates a new EVP_PKEY structure.
1470
1471            my $rv = Net::SSLeay::EVP_PKEY_new();
1472            #
1473            # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1474
1475           Check openssl doc
1476           <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1477
1478       ·   EVP_PKEY_free
1479
1480           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1481
1482           Free an allocated EVP_PKEY structure.
1483
1484            Net::SSLeay::EVP_PKEY_free($pkey);
1485            # $pkey - value corresponding to openssl's EVP_PKEY structure
1486            #
1487            # returns: no return value
1488
1489           Check openssl doc
1490           <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1491
1492       ·   EVP_PKEY_assign_RSA
1493
1494           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1495
1496           Set the key referenced by $pkey to $key
1497
1498           NOTE: No reference counter will be increased, i.e. $key will be
1499           freed if $pkey is freed.
1500
1501            my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1502            # $pkey - value corresponding to openssl's EVP_PKEY structure
1503            # $key - value corresponding to openssl's RSA structure
1504            #
1505            # returns: 1 on success, 0 on failure
1506
1507           Check openssl doc
1508           <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1509
1510       ·   EVP_PKEY_assign_EC_KEY
1511
1512           COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1513
1514           Set the key referenced by $pkey to $key
1515
1516           NOTE: No reference counter will be increased, i.e. $key will be
1517           freed if $pkey is freed.
1518
1519            my $rv = Net::SSLeay::EVP_PKEY_assign_EC_KEY($pkey, $key);
1520            # $pkey - value corresponding to openssl's EVP_PKEY structure
1521            # $key - value corresponding to openssl's EC_KEY structure
1522            #
1523            # returns: 1 on success, 0 on failure
1524
1525           Check openssl doc
1526           <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1527
1528       ·   EVP_PKEY_bits
1529
1530           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1531
1532           Returns the size of the key $pkey in bits.
1533
1534            my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1535            # $pkey - value corresponding to openssl's EVP_PKEY structure
1536            #
1537            # returns: size in bits
1538
1539       ·   EVP_PKEY_size
1540
1541           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1542
1543           Returns the maximum size of a signature in bytes. The actual
1544           signature may be smaller.
1545
1546            my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1547            # $pkey - value corresponding to openssl's EVP_PKEY structure
1548            #
1549            # returns: the maximum size in bytes
1550
1551           Check openssl doc
1552           <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1553
1554       ·   EVP_PKEY_id
1555
1556           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1557           requires at least openssl-1.0.0
1558
1559           Returns $pkey type (integer value of corresponding NID).
1560
1561            my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1562            # $pkey - value corresponding to openssl's EVP_PKEY structure
1563            #
1564            # returns: (integer) key type
1565
1566           Example:
1567
1568            my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1569            my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1570            print Net::SSLeay::OBJ_nid2sn($type);             #prints e.g. 'rsaEncryption'
1571
1572       Low level API: PEM_* related functions
1573
1574       Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1575
1576       ·   PEM_read_bio_X509
1577
1578           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1579
1580           Loads PEM formatted X509 certificate via given BIO structure.
1581
1582            my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1583            # $bio - value corresponding to openssl's BIO structure
1584            #
1585            # returns: value corresponding to openssl's X509 structure (0 on failure)
1586
1587           Example:
1588
1589            my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1590            my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1591            Net::SSLeay::BIO_free($bio);
1592
1593       ·   PEM_read_bio_X509_REQ
1594
1595           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1596
1597           Loads PEM formatted X509_REQ object via given BIO structure.
1598
1599            my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1600            # $bio - value corresponding to openssl's BIO structure
1601            #
1602            # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1603
1604           Example:
1605
1606            my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1607            my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1608            Net::SSLeay::BIO_free($bio);
1609
1610       ·   PEM_read_bio_DHparams
1611
1612           Reads DH structure from BIO.
1613
1614            my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1615            # $bio - value corresponding to openssl's BIO structure
1616            #
1617            # returns: value corresponding to openssl's DH structure (0 on failure)
1618
1619       ·   PEM_read_bio_X509_CRL
1620
1621           Reads X509_CRL structure from BIO.
1622
1623            my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1624            # $bio - value corresponding to openssl's BIO structure
1625            #
1626            # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1627
1628       ·   PEM_read_bio_PrivateKey
1629
1630           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1631
1632           Loads PEM formatted private key via given BIO structure.
1633
1634            my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1635            # $bio - value corresponding to openssl's BIO structure
1636            # $cb - reference to perl callback function
1637            # $data - data that will be passed to callback function (see examples below)
1638            #
1639            # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1640
1641           Example:
1642
1643            my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1644            my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1645            Net::SSLeay::BIO_free($bio);
1646
1647           To use password you have the following options:
1648
1649            $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1650            $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1651            $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1652            $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "");       # use empty password
1653
1654           Callback function signature:
1655
1656            sub callback_func {
1657              my ($max_passwd_size, $rwflag, $data) = @_;
1658              # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1659              # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1660              # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1661
1662              return "secret";
1663            }
1664
1665       ·   PEM_X509_INFO_read_bio
1666
1667           Reads a BIO containing a PEM formatted file into a
1668           STACK_OF(X509_INFO) structure.
1669
1670            my $rv = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1671            # $bio - value corresponding to openssl's BIO structure
1672            #
1673            # returns: value corresponding to openssl's STACK_OF(X509_INFO) structure.
1674
1675           Example:
1676
1677            my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1678            my $sk_x509_info = Net::SSLeay::PEM_X509_INFO_read_bio($bio);
1679            Net::SSLeay::BIO_free($bio);
1680
1681       ·   PEM_get_string_X509
1682
1683           NOTE: Does not exactly correspond to any low level API function
1684
1685           Converts/exports X509 certificate to string (PEM format).
1686
1687            Net::SSLeay::PEM_get_string_X509($x509);
1688            # $x509 - value corresponding to openssl's X509 structure
1689            #
1690            # returns: string with $x509 in PEM format
1691
1692       ·   PEM_get_string_PrivateKey
1693
1694           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1695
1696           Converts public key $pk into PEM formatted string (optionally
1697           protected with password).
1698
1699            my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1700            # $pk - value corresponding to openssl's EVP_PKEY structure
1701            # $passwd - [optional] (string) password to use for key encryption
1702            # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1703            #
1704            # returns: PEM formatted string
1705
1706           Examples:
1707
1708            $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1709            $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1710            $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1711
1712       ·   PEM_get_string_X509_CRL
1713
1714           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1715
1716           Converts X509_CRL object $x509_crl into PEM formatted string.
1717
1718            Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1719            # $x509_crl - value corresponding to openssl's X509_CRL structure
1720            #
1721            # returns: no return value
1722
1723       ·   PEM_get_string_X509_REQ
1724
1725           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1726
1727           Converts X509_REQ object $x509_crl into PEM formatted string.
1728
1729            Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1730            # $x509_req - value corresponding to openssl's X509_REQ structure
1731            #
1732            # returns: no return value
1733
1734       Low level API: d2i_* (DER format) related functions
1735
1736       ·   d2i_X509_bio
1737
1738           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1739
1740           Loads DER formatted X509 certificate via given BIO structure.
1741
1742            my $rv = Net::SSLeay::d2i_X509_bio($bp);
1743            # $bp - value corresponding to openssl's BIO structure
1744            #
1745            # returns: value corresponding to openssl's X509 structure (0 on failure)
1746
1747           Example:
1748
1749            my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1750            my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1751            Net::SSLeay::BIO_free($bio);
1752
1753           Check openssl doc
1754           <http://www.openssl.org/docs/crypto/d2i_X509.html>
1755
1756       ·   d2i_X509_CRL_bio
1757
1758           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1759
1760           Loads DER formatted X509_CRL object via given BIO structure.
1761
1762            my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1763            # $bp - value corresponding to openssl's BIO structure
1764            #
1765            # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1766
1767           Example:
1768
1769            my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1770            my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1771            Net::SSLeay::BIO_free($bio);
1772
1773       ·   d2i_X509_REQ_bio
1774
1775           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1776
1777           Loads DER formatted X509_REQ object via given BIO structure.
1778
1779            my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1780            # $bp - value corresponding to openssl's BIO structure
1781            #
1782            # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1783
1784           Example:
1785
1786            my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1787            my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1788            Net::SSLeay::BIO_free($bio);
1789
1790       Low level API: PKCS12 related functions
1791
1792       ·   P_PKCS12_load_file
1793
1794           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1795
1796           Loads X509 certificate + private key + certificates of CA chain (if
1797           present in PKCS12 file).
1798
1799            my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1800            # $filename - name of PKCS12 file
1801            # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1802            # $password - [optional] password for private key
1803            #
1804            # returns: triplet ($privkey, $cert, @cachain)
1805            #          $privkey - value corresponding to openssl's EVP_PKEY structure
1806            #          $cert - value corresponding to openssl's X509 structure
1807            #          @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1808
1809           IMPORTANT NOTE: after you do the job you need to call X509_free()
1810           on $privkey + all members of @cachain and EVP_PKEY_free() on
1811           $privkey.
1812
1813           Examples:
1814
1815            my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1816            #or
1817            my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1818            #or
1819            my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1820            #or
1821            my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1822
1823            #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1824            my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1825
1826           NOTE With some combinations of Windows, perl, compiler and compiler
1827           options, you may see a runtime error "no OPENSSL_Applink", when
1828           calling Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more
1829           details.
1830
1831       Low level API: SESSION_* related functions
1832
1833       ·   d2i_SSL_SESSION
1834
1835           COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1836
1837           Transforms the binary ASN1 representation string of an SSL/TLS
1838           session into an SSL_SESSION object.
1839
1840            my $ses = Net::SSLeay::d2i_SSL_SESSION($data);
1841            # $data - the session as ASN1 representation string
1842            #
1843            # returns: $ses - the new SSL_SESSION
1844
1845           Check openssl doc
1846           <https://www.openssl.org/docs/ssl/i2d_SSL_SESSION.html>
1847
1848       ·   i2d_SSL_SESSION
1849
1850           COMPATIBILITY: does not work in Net-SSLeay-1.85 and before
1851
1852           Transforms the SSL_SESSION object in into the ASN1 representation
1853           and returns it as string.
1854
1855            my $data = Net::SSLeay::i2d_SSL_SESSION($ses);
1856            # $ses - value corresponding to openssl's SSL_SESSION structure
1857            #
1858            # returns: $data - session as string
1859
1860           Check openssl doc
1861           <https://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1862
1863       ·   SESSION_new
1864
1865           Creates a new SSL_SESSION structure.
1866
1867            my $rv = Net::SSLeay::SESSION_new();
1868            #
1869            # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
1870
1871       ·   SESSION_free
1872
1873           Free an allocated SSL_SESSION structure.
1874
1875            Net::SSLeay::SESSION_free($ses);
1876            # $ses - value corresponding to openssl's SSL_SESSION structure
1877            #
1878            # returns: no return value
1879
1880           Check openssl doc
1881           <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
1882
1883       ·   SESSION_up_ref
1884
1885           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1886           requires at least OpenSSL 1.1.0 or LibreSSL 2.7.0
1887
1888           Increases the reference counter on a SSL_SESSION structure.
1889
1890            Net::SSLeay::SESSION_up_ref($ses);
1891            # $ses - value corresponding to openssl's SSL_SESSION structure
1892            #
1893            # returns: 1 on success else 0
1894
1895           Check openssl doc
1896           <https://www.openssl.org/docs/ssl/SSL_SESSION_up_ref.html>
1897
1898       ·   SESSION_dup
1899
1900           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1901           requires at least OpenSSL 1.1.1, not in LibreSSL
1902
1903           Duplicates a SSL_SESSION structure.
1904
1905            Net::SSLeay::SESSION_dup($ses);
1906            # $ses - value corresponding to openssl's SSL_SESSION structure
1907            #
1908            # returns: the duplicated session
1909
1910           Check openssl doc
1911           <https://www.openssl.org/docs/ssl/SSL_SESSION_dup.html>
1912
1913       ·   SESSION_is_resumable
1914
1915           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
1916           requires at least OpenSSL 1.1.1, not in LibreSSL
1917
1918           Determine whether an SSL_SESSION object can be used for resumption.
1919
1920            Net::SSLeay::SESSION_is_resumable($ses);
1921            # $ses - value corresponding to openssl's SSL_SESSION structure
1922            #
1923            # returns: (integer) 1 if it can or 0 if not
1924
1925           Check openssl doc
1926           <https://www.openssl.org/docs/manmaster/man3/SSL_SESSION_is_resumable.html>
1927
1928       ·   SESSION_cmp
1929
1930           Compare two SSL_SESSION structures.
1931
1932            my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
1933            # $sesa - value corresponding to openssl's SSL_SESSION structure
1934            # $sesb - value corresponding to openssl's SSL_SESSION structure
1935            #
1936            # returns: 0 if the two structures are the same
1937
1938           NOTE: Not available in openssl 1.0 or later
1939
1940       ·   SESSION_get_app_data
1941
1942           Can be used to get application defined value/data.
1943
1944            my $rv = Net::SSLeay::SESSION_get_app_data($ses);
1945            # $ses - value corresponding to openssl's SSL_SESSION structure
1946            #
1947            # returns: string/buffer/pointer ???
1948
1949       ·   SESSION_set_app_data
1950
1951           Can be used to set some application defined value/data.
1952
1953            my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
1954            # $s - value corresponding to openssl's SSL_SESSION structure
1955            # $a - (string/buffer/pointer ???) data
1956            #
1957            # returns: ???
1958
1959       ·   SESSION_get_ex_data
1960
1961           Is used to retrieve the information for $idx from session $ses.
1962
1963            my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
1964            # $ses - value corresponding to openssl's SSL_SESSION structure
1965            # $idx - (integer) index for application specific data
1966            #
1967            # returns: pointer to ???
1968
1969           Check openssl doc
1970           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1971
1972       ·   SESSION_set_ex_data
1973
1974           Is used to store application data at arg for idx into the session
1975           object.
1976
1977            my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
1978            # $ss - value corresponding to openssl's SSL_SESSION structure
1979            # $idx - (integer) ???
1980            # $data - (pointer) ???
1981            #
1982            # returns: 1 on success, 0 on failure
1983
1984           Check openssl doc
1985           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1986
1987       ·   SESSION_get_ex_new_index
1988
1989           Is used to register a new index for application specific data.
1990
1991            my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
1992            # $argl - (long) ???
1993            # $argp - (pointer) ???
1994            # $new_func - function pointer ??? (CRYPTO_EX_new *)
1995            # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
1996            # $free_func - function pointer ??? (CRYPTO_EX_free *)
1997            #
1998            # returns: (integer) ???
1999
2000           Check openssl doc
2001           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
2002
2003       ·   SESSION_get_master_key
2004
2005           NOTE: Does not exactly correspond to any low level API function
2006
2007           Returns 'master_key' value from SSL_SESSION structure $s
2008
2009            Net::SSLeay::SESSION_get_master_key($s);
2010            # $s - value corresponding to openssl's SSL_SESSION structure
2011            #
2012            # returns: master key (binary data)
2013
2014       ·   SESSION_set_master_key
2015
2016           Sets 'master_key' value for SSL_SESSION structure $s
2017
2018            Net::SSLeay::SESSION_set_master_key($s, $key);
2019            # $s - value corresponding to openssl's SSL_SESSION structure
2020            # $key - master key (binary data)
2021            #
2022            # returns: no return value
2023
2024           Not available with OpenSSL 1.1 and later.  Code that previously
2025           used
2026                  SESSION_set_master_key must now set $secret in the
2027           session_secret
2028                  callback set with SSL_set_session_secret_cb.
2029
2030       ·   SESSION_get_time
2031
2032           Returns the time at which the session s was established.  The time
2033           is given in seconds since 1.1.1970.
2034
2035            my $rv = Net::SSLeay::SESSION_get_time($s);
2036            # $s - value corresponding to openssl's SSL_SESSION structure
2037            #
2038            # returns: timestamp (seconds since 1.1.1970)
2039
2040           Check openssl doc
2041           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2042
2043       ·   get_time
2044
2045           Technically the same functionality as "SESSION_get_time".
2046
2047            my $rv = Net::SSLeay::get_time($s);
2048
2049       ·   SESSION_get_timeout
2050
2051           Returns the timeout value set for session $s in seconds.
2052
2053            my $rv = Net::SSLeay::SESSION_get_timeout($s);
2054            # $s - value corresponding to openssl's SSL_SESSION structure
2055            #
2056            # returns: timeout (in seconds)
2057
2058           Check openssl doc
2059           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2060
2061       ·   get_timeout
2062
2063           Technically the same functionality as "SESSION_get_timeout".
2064
2065            my $rv = Net::SSLeay::get_timeout($s);
2066
2067       ·   SESSION_print
2068
2069           NOTE: Does not exactly correspond to any low level API function
2070
2071           Prints session details (e.g. protocol version, cipher, session-id
2072           ...) to BIO.
2073
2074            my $rv = Net::SSLeay::SESSION_print($fp, $ses);
2075            # $fp - value corresponding to openssl's BIO structure
2076            # $ses - value corresponding to openssl's SSL_SESSION structure
2077            #
2078            # returns: 1 on success, 0 on failure
2079
2080           You have to use necessary BIO functions like this:
2081
2082            # let us have $ssl corresponding to openssl's SSL structure
2083            my $ses = Net::SSLeay::get_session($ssl);
2084            my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
2085            Net::SSLeay::SESSION_print($bio, $ses);
2086            print Net::SSLeay::BIO_read($bio);
2087
2088       ·   SESSION_print_fp
2089
2090           Prints session details (e.g. protocol version, cipher, session-id
2091           ...) to file handle.
2092
2093            my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
2094            # $fp - perl file handle
2095            # $ses - value corresponding to openssl's SSL_SESSION structure
2096            #
2097            # returns: 1 on success, 0 on failure
2098
2099           Example:
2100
2101            # let us have $ssl corresponding to openssl's SSL structure
2102            my $ses = Net::SSLeay::get_session($ssl);
2103            open my $fh, ">", "output.txt";
2104            Net::SSLeay::SESSION_print_fp($fh,$ses);
2105
2106       ·   SESSION_set_time
2107
2108           Replaces the creation time of the session s with the chosen value
2109           $t (seconds since 1.1.1970).
2110
2111            my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
2112            # $ses - value corresponding to openssl's SSL_SESSION structure
2113            # $t - time value
2114            #
2115            # returns: 1 on success
2116
2117           Check openssl doc
2118           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2119
2120       ·   set_time
2121
2122           Technically the same functionality as "SESSION_set_time".
2123
2124            my $rv = Net::SSLeay::set_time($ses, $t);
2125
2126       ·   SESSION_set_timeout
2127
2128           Sets the timeout value for session s in seconds to $t.
2129
2130            my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
2131            # $s - value corresponding to openssl's SSL_SESSION structure
2132            # $t - timeout (in seconds)
2133            #
2134            # returns: 1 on success
2135
2136           Check openssl doc
2137           <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2138
2139       ·   set_timeout
2140
2141           Technically the same functionality as "SESSION_set_timeout".
2142
2143            my $rv = Net::SSLeay::set_timeout($ses, $t);
2144
2145       Low level API: SSL_CTX_* related functions
2146
2147       NOTE: Please note that the function described in this chapter have
2148       "SSL_" part stripped from their original openssl names.
2149
2150       ·   CTX_add_client_CA
2151
2152           Adds the CA name extracted from $cacert to the list of CAs sent to
2153           the client when requesting a client certificate for $ctx.
2154
2155            my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
2156            # $ctx - value corresponding to openssl's SSL_CTX structure
2157            # $cacert - value corresponding to openssl's X509 structure
2158            #
2159            # returns: 1 on success, 0 on failure
2160
2161           Check openssl doc
2162           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2163
2164       ·   CTX_add_extra_chain_cert
2165
2166           Adds the certificate $x509 to the certificate chain presented
2167           together with the certificate. Several certificates can be added
2168           one after the other.
2169
2170            my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
2171            # $ctx - value corresponding to openssl's SSL_CTX structure
2172            # $x509 - value corresponding to openssl's X509 structure
2173            #
2174            # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
2175
2176           Check openssl doc
2177           <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2178
2179       ·   CTX_add_session
2180
2181           Adds the session $ses to the context $ctx.
2182
2183            my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
2184            # $ctx - value corresponding to openssl's SSL_CTX structure
2185            # $ses - value corresponding to openssl's SSL_SESSION structure
2186            #
2187            # returns: 1 on success, 0 on failure
2188
2189           Check openssl doc
2190           <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2191
2192       ·   CTX_callback_ctrl
2193
2194           ??? (more info needed)
2195
2196            my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
2197            # $ctx - value corresponding to openssl's SSL_CTX structure
2198            # $cmd - (integer) command id
2199            # $fp - (function pointer) ???
2200            #
2201            # returns: ???
2202
2203           Check openssl doc
2204           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2205
2206       ·   CTX_check_private_key
2207
2208           Checks the consistency of a private key with the corresponding
2209           certificate loaded into $ctx.
2210
2211            my $rv = Net::SSLeay::CTX_check_private_key($ctx);
2212            # $ctx - value corresponding to openssl's SSL_CTX structure
2213            #
2214            # returns: 1 on success, otherwise check out the error stack to find out the reason
2215
2216           Check openssl doc
2217           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2218
2219       ·   CTX_ctrl
2220
2221           Internal handling function for SSL_CTX objects.
2222
2223           BEWARE: openssl doc says: This function should never be called
2224           directly!
2225
2226            my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
2227            # $ctx - value corresponding to openssl's SSL_CTX structure
2228            # $cmd - (integer) command id
2229            # $larg - (integer) long ???
2230            # $parg - (string/pointer) ???
2231            #
2232            # returns: (long) result of given command ???
2233
2234            #valid $cmd values
2235             1 - SSL_CTRL_NEED_TMP_RSA
2236             2 - SSL_CTRL_SET_TMP_RSA
2237             3 - SSL_CTRL_SET_TMP_DH
2238             4 - SSL_CTRL_SET_TMP_ECDH
2239             5 - SSL_CTRL_SET_TMP_RSA_CB
2240             6 - SSL_CTRL_SET_TMP_DH_CB
2241             7 - SSL_CTRL_SET_TMP_ECDH_CB
2242             8 - SSL_CTRL_GET_SESSION_REUSED
2243             9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
2244            10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
2245            11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
2246            12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
2247            13 - SSL_CTRL_GET_FLAGS
2248            14 - SSL_CTRL_EXTRA_CHAIN_CERT
2249            15 - SSL_CTRL_SET_MSG_CALLBACK
2250            16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
2251            17 - SSL_CTRL_SET_MTU
2252            20 - SSL_CTRL_SESS_NUMBER
2253            21 - SSL_CTRL_SESS_CONNECT
2254            22 - SSL_CTRL_SESS_CONNECT_GOOD
2255            23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
2256            24 - SSL_CTRL_SESS_ACCEPT
2257            25 - SSL_CTRL_SESS_ACCEPT_GOOD
2258            26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
2259            27 - SSL_CTRL_SESS_HIT
2260            28 - SSL_CTRL_SESS_CB_HIT
2261            29 - SSL_CTRL_SESS_MISSES
2262            30 - SSL_CTRL_SESS_TIMEOUTS
2263            31 - SSL_CTRL_SESS_CACHE_FULL
2264            32 - SSL_CTRL_OPTIONS
2265            33 - SSL_CTRL_MODE
2266            40 - SSL_CTRL_GET_READ_AHEAD
2267            41 - SSL_CTRL_SET_READ_AHEAD
2268            42 - SSL_CTRL_SET_SESS_CACHE_SIZE
2269            43 - SSL_CTRL_GET_SESS_CACHE_SIZE
2270            44 - SSL_CTRL_SET_SESS_CACHE_MODE
2271            45 - SSL_CTRL_GET_SESS_CACHE_MODE
2272            50 - SSL_CTRL_GET_MAX_CERT_LIST
2273            51 - SSL_CTRL_SET_MAX_CERT_LIST
2274            52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
2275            53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
2276            54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
2277            55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
2278            56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
2279            57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
2280            58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
2281            59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
2282            60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
2283            61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
2284            62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
2285            63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
2286            64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
2287            65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
2288            66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
2289            67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
2290            68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
2291            69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
2292            70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
2293            71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
2294            72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
2295            73 - DTLS_CTRL_GET_TIMEOUT
2296            74 - DTLS_CTRL_HANDLE_TIMEOUT
2297            75 - DTLS_CTRL_LISTEN
2298            76 - SSL_CTRL_GET_RI_SUPPORT
2299            77 - SSL_CTRL_CLEAR_OPTIONS
2300            78 - SSL_CTRL_CLEAR_MODE
2301
2302            82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2303            83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2304
2305            88 - SSL_CTRL_CHAIN
2306            89 - SSL_CTRL_CHAIN_CERT
2307
2308            90 - SSL_CTRL_GET_CURVES
2309            91 - SSL_CTRL_SET_CURVES
2310            92 - SSL_CTRL_SET_CURVES_LIST
2311            93 - SSL_CTRL_GET_SHARED_CURVE
2312            94 - SSL_CTRL_SET_ECDH_AUTO
2313            97 - SSL_CTRL_SET_SIGALGS
2314            98 - SSL_CTRL_SET_SIGALGS_LIST
2315            99 - SSL_CTRL_CERT_FLAGS
2316            100 - SSL_CTRL_CLEAR_CERT_FLAGS
2317            101 - SSL_CTRL_SET_CLIENT_SIGALGS
2318            102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
2319            103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
2320            104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
2321            105 - SSL_CTRL_BUILD_CERT_CHAIN
2322            106 - SSL_CTRL_SET_VERIFY_CERT_STORE
2323            107 - SSL_CTRL_SET_CHAIN_CERT_STORE
2324            108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
2325            109 - SSL_CTRL_GET_SERVER_TMP_KEY
2326            110 - SSL_CTRL_GET_RAW_CIPHERLIST
2327            111 - SSL_CTRL_GET_EC_POINT_FORMATS
2328            112 - SSL_CTRL_GET_TLSA_RECORD
2329            113 - SSL_CTRL_SET_TLSA_RECORD
2330            114 - SSL_CTRL_PULL_TLSA_RECORD
2331
2332           Check openssl doc
2333           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2334
2335       ·   CTX_flush_sessions
2336
2337           Causes a run through the session cache of $ctx to remove sessions
2338           expired at time $tm.
2339
2340            Net::SSLeay::CTX_flush_sessions($ctx, $tm);
2341            # $ctx - value corresponding to openssl's SSL_CTX structure
2342            # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
2343            #
2344            # returns: no return value
2345
2346           Check openssl doc
2347           <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2348
2349       ·   CTX_free
2350
2351           Free an allocated SSL_CTX object.
2352
2353            Net::SSLeay::CTX_free($ctx);
2354            # $ctx - value corresponding to openssl's SSL_CTX structure
2355            #
2356            # returns: no return value
2357
2358           Check openssl doc
2359           <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2360
2361       ·   CTX_get_app_data
2362
2363           Can be used to get application defined value/data.
2364
2365            my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2366            # $ctx - value corresponding to openssl's SSL_CTX structure
2367            #
2368            # returns: string/buffer/pointer ???
2369
2370       ·   CTX_set_app_data
2371
2372           Can be used to set some application defined value/data.
2373
2374            my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2375            # $ctx - value corresponding to openssl's SSL_CTX structure
2376            # $arg - (string/buffer/pointer ???) data
2377            #
2378            # returns: ???
2379
2380       ·   CTX_get0_param
2381
2382           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2383           requires at least OpenSSL 1.0.2
2384
2385           Returns the current verification parameters.
2386
2387            my $vpm = Net::SSLeay::CTX_get0_param($ctx);
2388            # $ctx - value corresponding to openssl's SSL_CTX structure
2389            #
2390            # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
2391
2392           Check openssl doc
2393           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2394
2395       ·   CTX_get_cert_store
2396
2397           Returns the current certificate verification storage.
2398
2399            my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2400            # $ctx - value corresponding to openssl's SSL_CTX structure
2401            #
2402            # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2403
2404           Check openssl doc
2405           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2406
2407       ·   CTX_get_client_CA_list
2408
2409           Returns the list of client CAs explicitly set for $ctx using
2410           "CTX_set_client_CA_list".
2411
2412            my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2413            # $ctx - value corresponding to openssl's SSL_CTX structure
2414            #
2415            # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2416
2417           Check openssl doc
2418           <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2419
2420       ·   CTX_get_ex_data
2421
2422           Is used to retrieve the information for index $idx from $ctx.
2423
2424            my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2425            # $ssl - value corresponding to openssl's SSL_CTX structure
2426            # $idx - (integer) index for application specific data
2427            #
2428            # returns: pointer to ???
2429
2430           Check openssl doc
2431           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2432
2433       ·   CTX_get_ex_new_index
2434
2435           Is used to register a new index for application specific data.
2436
2437            my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2438            # $argl - (long) ???
2439            # $argp - (pointer) ???
2440            # $new_func - function pointer ??? (CRYPTO_EX_new *)
2441            # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2442            # $free_func - function pointer ??? (CRYPTO_EX_free *)
2443            #
2444            # returns: (integer) ???
2445
2446           Check openssl doc
2447           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2448
2449       ·   CTX_get_mode
2450
2451           Returns the mode set for ctx.
2452
2453            my $rv = Net::SSLeay::CTX_get_mode($ctx);
2454            # $ctx - value corresponding to openssl's SSL_CTX structure
2455            #
2456            # returns: mode (bitmask)
2457
2458            #to decode the return value (bitmask) use:
2459            0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2460            0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2461            0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2462            0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2463            0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2464            (note: some of the bits might not be supported by older openssl versions)
2465
2466           Check openssl doc
2467           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2468
2469       ·   CTX_set_mode
2470
2471           Adds the mode set via bitmask in $mode to $ctx. Options already set
2472           before are not cleared.
2473
2474            my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2475            # $ctx - value corresponding to openssl's SSL_CTX structure
2476            # $mode - mode bitmask
2477            #
2478            # returns: the new mode bitmask after adding $mode
2479
2480           For bitmask details see "CTX_get_mode" (above).
2481
2482           Check openssl doc
2483           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2484
2485       ·   CTX_get_options
2486
2487           Returns the options (bitmask) set for $ctx.
2488
2489            my $rv = Net::SSLeay::CTX_get_options($ctx);
2490            # $ctx - value corresponding to openssl's SSL_CTX structure
2491            #
2492            # returns: options (bitmask)
2493
2494           BEWARE: The available constants and their values in bitmask depend
2495           on the TLS library. For example, SSL_OP_NO_TLSv1_3 became available
2496           much later than SSL_OP_NO_COMPRESS which is already deprecated by
2497           some libraries. Also, some previously used option values have been
2498           recycled and are now used for newer options. See the list of
2499           constants in this document for options Net::SSLeay currently
2500           supports.
2501
2502           You are strongly encouraged to check your TLS library if you need
2503           to use numeric values directly. The following is a sample of
2504           historic values. It may not be correct anymore.
2505
2506            #to decode the return value (bitmask) use:
2507            0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2508            0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2509            0x00004000 corresponds to SSL_OP_NO_TICKET
2510            0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2511            0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2512            0x04000000 corresponds to SSL_OP_NO_TLSv1
2513
2514           Check openssl doc
2515           <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2516
2517       ·   CTX_set_options
2518
2519           Adds the options set via bitmask in $options to ctx. Options
2520           already set before are not cleared.
2521
2522            Net::SSLeay::CTX_set_options($ctx, $options);
2523            # $ctx - value corresponding to openssl's SSL_CTX structure
2524            # $options - options bitmask
2525            #
2526            # returns: the new options bitmask after adding $options
2527
2528           For bitmask details see "CTX_get_options" (above).
2529
2530           Check openssl doc
2531           <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2532
2533       ·   CTX_get_quiet_shutdown
2534
2535           Returns the 'quiet shutdown' setting of $ctx.
2536
2537            my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2538            # $ctx - value corresponding to openssl's SSL_CTX structure
2539            #
2540            # returns: (integer) the current setting
2541
2542           Check openssl doc
2543           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2544
2545       ·   CTX_get_read_ahead
2546
2547            my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2548            # $ctx - value corresponding to openssl's SSL_CTX structure
2549            #
2550            # returns: (integer) read_ahead value
2551
2552       ·   CTX_get_session_cache_mode
2553
2554           Returns the currently used cache mode (bitmask).
2555
2556            my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2557            # $ctx - value corresponding to openssl's SSL_CTX structure
2558            #
2559            # returns: mode (bitmask)
2560
2561           BEWARE: SESS_CACHE_OFF and other constants are not available in
2562           Net-SSLeay-1.82 and before.  If the constants are not available,
2563           the following values have historically been correct. You are
2564           strongly encouraged to check your TLS library for the current
2565           values.
2566
2567            #to decode the return value (bitmask) use:
2568            0x0000 corresponds to SSL_SESS_CACHE_OFF
2569            0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2570            0x0002 corresponds to SSL_SESS_CACHE_SERVER
2571            0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2572            0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2573            0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2574            (note: some of the bits might not be supported by older openssl versions)
2575
2576           Check openssl doc
2577           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2578
2579       ·   CTX_set_session_cache_mode
2580
2581           Enables/disables session caching by setting the operational mode
2582           for $ctx to $mode.
2583
2584            my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2585            # $ctx - value corresponding to openssl's SSL_CTX structure
2586            # $mode - mode (bitmask)
2587            #
2588            # returns: previously set cache mode
2589
2590           For bitmask details see "CTX_get_session_cache_mode" (above).
2591
2592           Check openssl doc
2593           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2594
2595       ·   CTX_get_timeout
2596
2597           Returns the currently set timeout value for $ctx.
2598
2599            my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2600            # $ctx - value corresponding to openssl's SSL_CTX structure
2601            #
2602            # returns: timeout in seconds
2603
2604           Check openssl doc
2605           <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2606
2607       ·   CTX_get_verify_depth
2608
2609           Returns the verification depth limit currently set in $ctx. If no
2610           limit has been explicitly set, -1 is returned and the default value
2611           will be used.",
2612
2613            my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2614            # $ctx - value corresponding to openssl's SSL_CTX structure
2615            #
2616            # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2617
2618           Check openssl doc
2619           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2620
2621       ·   CTX_get_verify_mode
2622
2623           Returns the verification mode (bitmask) currently set in $ctx.
2624
2625            my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2626            # $ctx - value corresponding to openssl's SSL_CTX structure
2627            #
2628            # returns: mode (bitmask)
2629
2630           For bitmask details see "CTX_set_verify".
2631
2632           Check openssl doc
2633           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_verify_mode.html>
2634
2635       ·   CTX_set_verify
2636
2637           Sets the verification flags for $ctx to be $mode and specifies the
2638           verify_callback function to be used.
2639
2640            Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2641            # $ctx - value corresponding to openssl's SSL_CTX structure
2642            # $mode - mode (bitmask), see OpenSSL manual
2643            # $callback - [optional] reference to perl callback function
2644            #
2645            # returns: no return value
2646
2647           Check openssl doc
2648           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_verify.html>
2649
2650       ·   CTX_set_post_handshake_auth
2651
2652           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
2653           requires at least OpenSSL 1.1.1, not in LibreSSL
2654
2655           Enable the Post-Handshake Authentication extension to be added to
2656           the ClientHello such that post-handshake authentication can be
2657           requested by the server.
2658
2659            Net::SSLeay::CTX_set_posthandshake_auth($ctx, $val);
2660            # $ctx - value corresponding to openssl's SSL_CTX structure
2661            # $val - 0 then the extension is not sent, otherwise it is
2662            #
2663            # returns: no return value
2664
2665           Check openssl doc
2666           https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth
2667           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_post_handshake_auth.html>
2668
2669       ·   CTX_load_verify_locations
2670
2671           Specifies the locations for $ctx, at which CA certificates for
2672           verification purposes are located. The certificates available via
2673           $CAfile and $CApath are trusted.
2674
2675            my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2676            # $ctx - value corresponding to openssl's SSL_CTX structure
2677            # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2678            # $CApath - (string) directory containing CA certificates in PEM format (or '')
2679            #
2680            # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2681
2682           Check openssl doc
2683           <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2684
2685       ·   CTX_need_tmp_RSA
2686
2687           Return the result of
2688           "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2689
2690            my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2691            # $ctx - value corresponding to openssl's SSL_CTX structure
2692            #
2693            # returns: result of SSL_CTRL_NEED_TMP_RSA command
2694
2695           Not available with OpenSSL 1.1 and later.
2696
2697       ·   CTX_new
2698
2699           The same as "CTX_v23_new"
2700
2701            my $rv = Net::SSLeay::CTX_new();
2702            #
2703            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2704
2705           Check openssl doc
2706           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2707
2708           Not available with OpenSSL 1.1 and later.
2709
2710       ·   CTX_v2_new
2711
2712           Creates a new SSL_CTX object - based on SSLv2_method() - as
2713           framework to establish TLS/SSL enabled connections.
2714
2715            my $rv = Net::SSLeay::CTX_v2_new();
2716            #
2717            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2718
2719       ·   CTX_v23_new
2720
2721           Creates a new SSL_CTX object - based on SSLv23_method() - as
2722           framework to establish TLS/SSL enabled connections.
2723
2724            my $rv = Net::SSLeay::CTX_v23_new();
2725            #
2726            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2727
2728       ·   CTX_v3_new
2729
2730           Creates a new SSL_CTX object - based on SSLv3_method() - as
2731           framework to establish TLS/SSL enabled connections.
2732
2733            my $rv = Net::SSLeay::CTX_v3_new();
2734            #
2735            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2736
2737       ·   CTX_tlsv1_new
2738
2739           Creates a new SSL_CTX object - based on TLSv1_method() - as
2740           framework to establish TLS/SSL enabled connections.
2741
2742            my $rv = Net::SSLeay::CTX_tlsv1_new();
2743            #
2744            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2745
2746       ·   CTX_tlsv1_1_new
2747
2748           Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2749           framework to establish TLS/SSL enabled connections. Only available
2750           where supported by the underlying openssl.
2751
2752            my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2753            #
2754            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2755
2756       ·   CTX_tlsv1_2_new
2757
2758           Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2759           framework to establish TLS/SSL enabled connections. Only available
2760           where supported by the underlying openssl.
2761
2762            my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2763            #
2764            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2765
2766       ·   CTX_new_with_method
2767
2768           Creates a new SSL_CTX object based on $meth method
2769
2770            my $rv = Net::SSLeay::CTX_new_with_method($meth);
2771            # $meth - value corresponding to openssl's SSL_METHOD structure
2772            #
2773            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2774
2775            #example
2776            my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2777
2778           Check openssl doc
2779           <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2780
2781       ·   CTX_set_min_proto_version, CTX_set_max_proto_version,
2782           set_min_proto_version and set_max_proto_version,
2783
2784           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2785           requires at least OpenSSL 1.1.0 or LibreSSL 2.6.0
2786
2787           Set the minimum and maximum supported protocol for $ctx or $ssl.
2788
2789            my $rv = Net::SSLeay::CTX_set_min_proto_version($ctx, $version)
2790            # $ctx - value corresponding to openssl's SSL_CTX structure
2791            # $version - (integer) constat version value or 0 for automatic lowest or highest value
2792            #
2793            # returns: 1 on success, 0 on failure
2794
2795            #example: allow only TLS 1.2 for a SSL_CTX
2796            my $rv_min = Net::SSLeay::CTX_set_min_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2797            my $rv_max = Net::SSLeay::CTX_set_max_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2798
2799            #example: allow only TLS 1.1 for a SSL
2800            my $rv_min = Net::SSLeay::set_min_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2801            my $rv_max = Net::SSLeay::set_max_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2802
2803           Check openssl doc
2804           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2805
2806       ·   CTX_get_min_proto_version, CTX_get_max_proto_version,
2807           get_min_proto_version and get_max_proto_version,
2808
2809           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2810           requires at least OpenSSL 1.1.0g
2811
2812           Get the minimum and maximum supported protocol for $ctx or $ssl.
2813
2814            my $version = Net::SSLeay::CTX_get_min_proto_version($ctx)
2815            # $ctx - value corresponding to openssl's SSL_CTX structure
2816            #
2817            # returns: 0 automatic lowest or highest value, configured value otherwise
2818
2819           Check openssl doc
2820           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2821
2822       ·   CTX_remove_session
2823
2824           Removes the session $ses from the context $ctx.
2825
2826            my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2827            # $ctx - value corresponding to openssl's SSL_CTX structure
2828            # $ses - value corresponding to openssl's SSL_SESSION structure
2829            #
2830            # returns: 1 on success, 0 on failure
2831
2832           Check openssl doc
2833           <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2834
2835       ·   CTX_sess_accept
2836
2837            my $rv = Net::SSLeay::CTX_sess_accept($ctx);
2838            # $ctx - value corresponding to openssl's SSL_CTX structure
2839            #
2840            # returns: number of started SSL/TLS handshakes in server mode
2841
2842           Check openssl doc
2843           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2844
2845       ·   CTX_sess_accept_good
2846
2847            my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
2848            # $ctx - value corresponding to openssl's SSL_CTX structure
2849            #
2850            # returns: number of successfully established SSL/TLS sessions in server mode
2851
2852           Check openssl doc
2853           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2854
2855       ·   CTX_sess_accept_renegotiate
2856
2857            my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
2858            # $ctx - value corresponding to openssl's SSL_CTX structure
2859            #
2860            # returns: number of start renegotiations in server mode
2861
2862           Check openssl doc
2863           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2864
2865       ·   CTX_sess_cache_full
2866
2867            my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
2868            # $ctx - value corresponding to openssl's SSL_CTX structure
2869            #
2870            # returns: number of sessions that were removed because the maximum session cache size was exceeded
2871
2872           Check openssl doc
2873           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2874
2875       ·   CTX_sess_cb_hits
2876
2877            my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
2878            # $ctx - value corresponding to openssl's SSL_CTX structure
2879            #
2880            # returns: number of successfully retrieved sessions from the external session cache in server mode
2881
2882           Check openssl doc
2883           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2884
2885       ·   CTX_sess_connect
2886
2887            my $rv = Net::SSLeay::CTX_sess_connect($ctx);
2888            # $ctx - value corresponding to openssl's SSL_CTX structure
2889            #
2890            # returns: number of started SSL/TLS handshakes in client mode
2891
2892           Check openssl doc
2893           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2894
2895       ·   CTX_sess_connect_good
2896
2897            my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
2898            # $ctx - value corresponding to openssl's SSL_CTX structure
2899            #
2900            # returns: number of successfully established SSL/TLS sessions in client mode
2901
2902           Check openssl doc
2903           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2904
2905       ·   CTX_sess_connect_renegotiate
2906
2907            my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
2908            # $ctx - value corresponding to openssl's SSL_CTX structure
2909            #
2910            # returns: number of start renegotiations in client mode
2911
2912           Check openssl doc
2913           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2914
2915       ·   CTX_sess_get_cache_size
2916
2917           Returns the currently valid session cache size.
2918
2919            my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
2920            # $ctx - value corresponding to openssl's SSL_CTX structure
2921            #
2922            # returns: current size
2923
2924           Check openssl doc
2925           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2926
2927       ·   CTX_sess_hits
2928
2929            my $rv = Net::SSLeay::CTX_sess_hits($ctx);
2930            # $ctx - value corresponding to openssl's SSL_CTX structure
2931            #
2932            # returns: number of successfully reused sessions
2933
2934           Check openssl doc
2935           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2936
2937       ·   CTX_sess_misses
2938
2939            my $rv = Net::SSLeay::CTX_sess_misses($ctx);
2940            # $ctx - value corresponding to openssl's SSL_CTX structure
2941            #
2942            # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
2943
2944           Check openssl doc
2945           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2946
2947       ·   CTX_sess_number
2948
2949            my $rv = Net::SSLeay::CTX_sess_number($ctx);
2950            # $ctx - value corresponding to openssl's SSL_CTX structure
2951            #
2952            # returns: current number of sessions in the internal session cache
2953
2954           Check openssl doc
2955           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2956
2957       ·   CTX_sess_set_cache_size
2958
2959           Sets the size of the internal session cache of context $ctx to
2960           $size.
2961
2962            Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
2963            # $ctx - value corresponding to openssl's SSL_CTX structure
2964            # $size - cache size (0 = unlimited)
2965            #
2966            # returns: previously valid size
2967
2968           Check openssl doc
2969           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2970
2971       ·   CTX_sess_timeouts
2972
2973           Returns the number of sessions proposed by clients and either found
2974           in the internal or external session cache in server mode, but that
2975           were invalid due to timeout. These sessions are not included in the
2976           SSL_CTX_sess_hits count.
2977
2978            my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
2979            # $ctx - value corresponding to openssl's SSL_CTX structure
2980            #
2981            # returns: number of sessions
2982
2983           Check openssl doc
2984           <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2985
2986       ·   CTX_sess_set_new_cb
2987
2988           COMPATIBILITY: not available in Net-SSLeay-1.85 and before
2989
2990           Sets the callback function, which is automatically called whenever
2991           a new session was negotiated.
2992
2993            Net::SSLeay::CTX_sess_set_new_cb($ctx, $func);
2994            # $ctx - value corresponding to openssl's SSL_CTX structure
2995            # $func - perl reference to callback function
2996            #
2997            # returns: no return value
2998
2999           Check openssl doc
3000           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_new_cb.html>
3001
3002       ·   CTX_sess_set_remove_cb
3003
3004           COMPATIBILITY: not available in Net-SSLeay-1.85 and before
3005
3006           Sets the callback function, which is automatically called whenever
3007           a session is removed by the SSL engine.
3008
3009            Net::SSLeay::CTX_sess_set_remove_cb($ctx, $func);
3010            # $ctx - value corresponding to openssl's SSL_CTX structure
3011            # $func - perl reference to callback function
3012            #
3013            # returns: no return value
3014
3015           Check openssl doc
3016           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_sess_set_remove_cb.html>
3017
3018       ·   CTX_sessions
3019
3020           Returns a pointer to the lhash databases containing the internal
3021           session cache for ctx.
3022
3023            my $rv = Net::SSLeay::CTX_sessions($ctx);
3024            # $ctx - value corresponding to openssl's SSL_CTX structure
3025            #
3026            # returns: value corresponding to openssl's LHASH structure (0 on failure)
3027
3028           Check openssl doc
3029           <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
3030
3031       ·   CTX_set1_param
3032
3033           Applies X509 verification parameters $vpm on $ctx
3034
3035            my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
3036            # $ctx - value corresponding to openssl's SSL_CTX structure
3037            # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
3038            #
3039            # returns: 1 on success, 0 on failure
3040
3041           Check openssl doc
3042           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3043
3044       ·   CTX_set_cert_store
3045
3046           Sets/replaces the certificate verification storage of $ctx to/with
3047           $store.
3048
3049            Net::SSLeay::CTX_set_cert_store($ctx, $store);
3050            # $ctx - value corresponding to openssl's SSL_CTX structure
3051            # $store - value corresponding to openssl's X509_STORE structure
3052            #
3053            # returns: no return value
3054
3055           Check openssl doc
3056           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
3057
3058       ·   CTX_set_cert_verify_callback
3059
3060           Sets the verification callback function for $ctx. SSL objects that
3061           are created from $ctx inherit the setting valid at the time when
3062           "Net::SSLeay::new($ctx)" is called.
3063
3064            Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
3065            # $ctx - value corresponding to openssl's SSL_CTX structure
3066            # $func - perl reference to callback function
3067            # $data - [optional] data that will be passed to callback function when invoked
3068            #
3069            # returns: no return value
3070
3071           Check openssl doc
3072           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
3073
3074       ·   CTX_set_cipher_list
3075
3076           Sets the list of available ciphers for $ctx using the control
3077           string $str.  The list of ciphers is inherited by all ssl objects
3078           created from $ctx.
3079
3080            my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
3081            # $s - value corresponding to openssl's SSL_CTX structure
3082            # $str - (string) cipher list e.g. '3DES:+RSA'
3083            #
3084            # returns: 1 if any cipher could be selected and 0 on complete failure
3085
3086           The format of $str is described in
3087           <http://www.openssl.org/docs/apps/ciphers.html>
3088
3089           Check openssl doc
3090           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
3091
3092       ·   CTX_set_ciphersuites
3093
3094           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3095           requires at least OpenSSL 1.1.1, not in LibreSSL
3096
3097           Configure the available TLSv1.3 ciphersuites.
3098
3099            my $rv = Net::SSLeay::CTX_set_ciphersuites($ctx, $str);
3100            # $ctx  - value corresponding to openssl's SSL_CTX structure
3101            # $str  - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
3102            #
3103            # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
3104
3105           Check openssl doc
3106           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_ciphersuites.html>
3107
3108       ·   CTX_set_client_CA_list
3109
3110           Sets the list of CAs sent to the client when requesting a client
3111           certificate for $ctx.
3112
3113            Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
3114            # $ctx - value corresponding to openssl's SSL_CTX structure
3115            # $list - value corresponding to openssl's X509_NAME_STACK structure
3116            #
3117            # returns: no return value
3118
3119           Check openssl doc
3120           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3121
3122       ·   CTX_set_default_passwd_cb
3123
3124           Sets the default password callback called when loading/storing a
3125           PEM certificate with encryption.
3126
3127            Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
3128            # $ctx - value corresponding to openssl's SSL_CTX structure
3129            # $func - perl reference to callback function
3130            #
3131            # returns: no return value
3132
3133           Check openssl doc
3134           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3135
3136       ·   CTX_set_default_passwd_cb_userdata
3137
3138           Sets a pointer to userdata which will be provided to the password
3139           callback on invocation.
3140
3141            Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
3142            # $ctx - value corresponding to openssl's SSL_CTX structure
3143            # $userdata - data that will be passed to callback function when invoked
3144            #
3145            # returns: no return value
3146
3147           Check openssl doc
3148           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3149
3150       ·   CTX_set_default_verify_paths
3151
3152           ??? (more info needed)
3153
3154            my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
3155            # $ctx - value corresponding to openssl's SSL_CTX structure
3156            #
3157            # returns: 1 on success, 0 on failure
3158
3159       ·   CTX_set_ex_data
3160
3161           Is used to store application data at $data for $idx into the $ctx
3162           object.
3163
3164            my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
3165            # $ssl - value corresponding to openssl's SSL_CTX structure
3166            # $idx - (integer) ???
3167            # $data - (pointer) ???
3168            #
3169            # returns: 1 on success, 0 on failure
3170
3171           Check openssl doc
3172           <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3173
3174       ·   CTX_set_purpose
3175
3176            my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
3177            # $s - value corresponding to openssl's SSL_CTX structure
3178            # $purpose - (integer) purpose identifier
3179            #
3180            # returns: 1 on success, 0 on failure
3181
3182            #avainable purpose identifier
3183            1 - X509_PURPOSE_SSL_CLIENT
3184            2 - X509_PURPOSE_SSL_SERVER
3185            3 - X509_PURPOSE_NS_SSL_SERVER
3186            4 - X509_PURPOSE_SMIME_SIGN
3187            5 - X509_PURPOSE_SMIME_ENCRYPT
3188            6 - X509_PURPOSE_CRL_SIGN
3189            7 - X509_PURPOSE_ANY
3190            8 - X509_PURPOSE_OCSP_HELPER
3191            9 - X509_PURPOSE_TIMESTAMP_SIGN
3192
3193            #or use corresponding constants
3194            $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3195            ...
3196            $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3197
3198       ·   CTX_set_quiet_shutdown
3199
3200           Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
3201           created from $ctx inherit the mode valid at the time
3202           "Net::SSLeay::new($ctx)" is called.
3203
3204            Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
3205            # $ctx - value corresponding to openssl's SSL_CTX structure
3206            # $mode - 0 or 1
3207            #
3208            # returns: no return value
3209
3210           Check openssl doc
3211           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3212
3213       ·   CTX_set_read_ahead
3214
3215            my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
3216            # $ctx - value corresponding to openssl's SSL_CTX structure
3217            # $val - read_ahead value to be set
3218            #
3219            # returns: the original read_ahead value
3220
3221       ·   CTX_set_session_id_context
3222
3223           Sets the context $sid_ctx of length $sid_ctx_len within which a
3224           session can be reused for the $ctx object.
3225
3226            my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
3227            # $ctx - value corresponding to openssl's SSL_CTX structure
3228            # $sid_ctx - data buffer
3229            # $sid_ctx_len - length of data in $sid_ctx
3230            #
3231            # returns: 1 on success, 0 on failure (the error is logged to the error stack)
3232
3233           Check openssl doc
3234           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3235
3236       ·   CTX_set_ssl_version
3237
3238           Sets a new default TLS/SSL method for SSL objects newly created
3239           from this $ctx.  SSL objects already created with
3240           "Net::SSLeay::new($ctx)" are not affected, except when
3241           "Net::SSLeay:clear($ssl)" is being called.
3242
3243            my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
3244            # $ctx - value corresponding to openssl's SSL_CTX structure
3245            # $meth - value corresponding to openssl's SSL_METHOD structure
3246            #
3247            # returns: 1 on success, 0 on failure
3248
3249           Check openssl doc
3250           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3251
3252       ·   CTX_set_timeout
3253
3254           Sets the timeout for newly created sessions for $ctx to $t. The
3255           timeout value $t must be given in seconds.
3256
3257            my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
3258            # $ctx - value corresponding to openssl's SSL_CTX structure
3259            # $t - timeout in seconds
3260            #
3261            # returns: previously set timeout value
3262
3263           Check openssl doc
3264           <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3265
3266       ·   CTX_set_tmp_dh
3267
3268           Sets DH parameters to be used to be $dh. The key is inherited by
3269           all ssl objects created from $ctx.
3270
3271            my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
3272            # $ctx - value corresponding to openssl's SSL_CTX structure
3273            # $dh - value corresponding to openssl's DH structure
3274            #
3275            # returns: 1 on success, 0 on failure
3276
3277           Check openssl doc
3278           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3279
3280       ·   CTX_set_tmp_dh_callback
3281
3282           Sets the callback function for $ctx to be used when a DH parameters
3283           are required to $tmp_dh_callback.
3284
3285            Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
3286            # $ctx - value corresponding to openssl's SSL_CTX structure
3287            # tmp_dh_callback - (function pointer) ???
3288            #
3289            # returns: no return value
3290
3291           Check openssl doc
3292           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3293
3294       ·   CTX_set_tmp_rsa
3295
3296           Sets the temporary/ephemeral RSA key to be used to be $rsa.
3297
3298            my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
3299            # $ctx - value corresponding to openssl's SSL_CTX structure
3300            # $rsa - value corresponding to openssl's RSA structure
3301            #
3302            # returns: 1 on success, 0 on failure
3303
3304           Check openssl doc
3305           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3306
3307           Not available with OpenSSL 1.1 and later.
3308
3309       ·   CTX_set_tmp_rsa_callback
3310
3311           Sets the callback function for ctx to be used when a
3312           temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3313
3314           ??? (does this function really work?)
3315
3316            Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
3317            # $ctx - value corresponding to openssl's SSL_CTX structure
3318            # $tmp_rsa_callback - (function pointer) ???
3319            #
3320            # returns: no return value
3321
3322           Check openssl doc
3323           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3324
3325           Not available with OpenSSL 1.1 and later.
3326
3327       ·   CTX_set_trust
3328
3329            my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
3330            # $s - value corresponding to openssl's SSL_CTX structure
3331            # $trust - (integer) trust identifier
3332            #
3333            # returns: the original value
3334
3335            #available trust identifiers
3336            1 - X509_TRUST_COMPAT
3337            2 - X509_TRUST_SSL_CLIENT
3338            3 - X509_TRUST_SSL_SERVER
3339            4 - X509_TRUST_EMAIL
3340            5 - X509_TRUST_OBJECT_SIGN
3341            6 - X509_TRUST_OCSP_SIGN
3342            7 - X509_TRUST_OCSP_REQUEST
3343            8 - X509_TRUST_TSA
3344
3345            #or use corresponding constants
3346            $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3347            ...
3348            $trust = &Net::SSLeay::X509_TRUST_TSA;
3349
3350       ·   CTX_set_verify_depth
3351
3352           Sets the maximum depth for the certificate chain verification that
3353           shall be allowed for ctx.
3354
3355            Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
3356            # $ctx - value corresponding to openssl's SSL_CTX structure
3357            # $depth - max. depth
3358            #
3359            # returns: no return value
3360
3361           Check openssl doc
3362           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3363
3364       ·   CTX_use_PKCS12_file
3365
3366           Adds the certificate and private key from PKCS12 file $p12filename
3367           to $ctx.
3368
3369            my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
3370            # $ctx - value corresponding to openssl's SSL_CTX structure
3371            # $p12filename - (string) filename
3372            # $password - (string) password to decrypt private key
3373            #
3374            # returns: 1 on success, 0 on failure
3375
3376       ·   CTX_use_PrivateKey
3377
3378           Adds the private key $pkey to $ctx.
3379
3380            my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
3381            # $ctx - value corresponding to openssl's SSL_CTX structure
3382            # $pkey - value corresponding to openssl's EVP_PKEY structure
3383            #
3384            # returns: 1 on success, otherwise check out the error stack to find out the reason
3385
3386           Check openssl doc
3387           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3388
3389       ·   CTX_use_PrivateKey_file
3390
3391           Adds the first private key found in $file to $ctx.
3392
3393            my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
3394            # $ctx - value corresponding to openssl's SSL_CTX structure
3395            # $file - (string) file name
3396            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3397            #
3398            # returns: 1 on success, otherwise check out the error stack to find out the reason
3399
3400           Check openssl doc
3401           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3402
3403       ·   CTX_use_RSAPrivateKey
3404
3405           Adds the RSA private key $rsa to $ctx.
3406
3407            my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
3408            # $ctx - value corresponding to openssl's SSL_CTX structure
3409            # $rsa - value corresponding to openssl's RSA structure
3410            #
3411            # returns: 1 on success, otherwise check out the error stack to find out the reason
3412
3413           Check openssl doc
3414           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3415
3416       ·   CTX_use_RSAPrivateKey_file
3417
3418           Adds the first RSA private key found in $file to $ctx.
3419
3420            my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
3421            # $ctx - value corresponding to openssl's SSL_CTX structure
3422            # $file - (string) file name
3423            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3424            #
3425            # returns: 1 on success, otherwise check out the error stack to find out the reason
3426
3427       ·   CTX_use_certificate
3428
3429           Loads the certificate $x into $ctx
3430
3431            my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
3432            # $ctx - value corresponding to openssl's SSL_CTX structure
3433            # $x - value corresponding to openssl's X509 structure
3434            #
3435            # returns: 1 on success, otherwise check out the error stack to find out the reason
3436
3437           Check openssl doc
3438           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3439
3440       ·   CTX_use_certificate_chain_file
3441
3442           Loads a certificate chain from $file into $ctx. The certificates
3443           must be in PEM format and must be sorted starting with the
3444           subject's certificate (actual client or server certificate),
3445           followed by intermediate CA certificates if applicable, and ending
3446           at the highest level (root) CA.
3447
3448            my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
3449            # $ctx - value corresponding to openssl's SSL_CTX structure
3450            # $file - (string) file name
3451            #
3452            # returns: 1 on success, otherwise check out the error stack to find out the reason
3453
3454           Check openssl doc
3455           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3456
3457       ·   CTX_use_certificate_file
3458
3459           Loads the first certificate stored in $file into $ctx.
3460
3461            my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
3462            # $ctx - value corresponding to openssl's SSL_CTX structure
3463            # $file - (string) file name
3464            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3465            #
3466            # returns: 1 on success, otherwise check out the error stack to find out the reason
3467
3468           Check openssl doc
3469           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3470
3471       ·   CTX_get_security_level
3472
3473           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3474           requires at least OpenSSL 1.1.0, not in LibreSSL
3475
3476           Returns the security level associated with $ctx.
3477
3478            my $level = Net::SSLeay::CTX_get_security_level($ctx);
3479            # $ctx   - value corresponding to openssl's SSL_CTX structure
3480            #
3481            # returns: (integer) current security level
3482
3483           Check openssl doc
3484           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_security_level.html>
3485
3486       ·   CTX_set_security_level
3487
3488           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3489           requires at least OpenSSL 1.1.0, not in LibreSSL
3490
3491           Sets the security level associated with $ctx to $level.
3492
3493            Net::SSLeay::CTX_set_security_level($ctx, $level);
3494            # $ssl   - value corresponding to openssl's SSL_CTX structure
3495            # $level - new security level
3496            #
3497            # returns: no return value
3498
3499           Check openssl doc
3500           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_security_level.html>
3501
3502       ·   CTX_set_num_tickets
3503
3504           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3505           requires at least OpenSSL 1.1.1, not in LibreSSL
3506
3507           Set number of TLSv1.3 session tickets that will be sent to a
3508           client.
3509
3510            my $rv = Net::SSLeay::CTX_set_num_tickets($ctx, $number_of_tickets);
3511            # $ctx  - value corresponding to openssl's SSL_CTX structure
3512            # $number_of_tickets - number of tickets to send
3513            #
3514            # returns: 1 on success, 0 on failure
3515
3516           Set to zero if you do not no want to support a session resumption.
3517
3518           Check openssl doc
3519           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_num_tickets.html>
3520
3521       ·   CTX_get_num_tickets
3522
3523           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
3524           requires at least OpenSSL 1.1.1, not in LibreSSL
3525
3526           Get number of TLSv1.3 session tickets that will be sent to a
3527           client.
3528
3529            my $number_of_tickets = Net::SSLeay::CTX_get_num_tickets($ctx);
3530            # $ctx  - value corresponding to openssl's SSL_CTX structure
3531            #
3532            # returns: (integer) number of tickets to send
3533
3534           Check openssl doc
3535           <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_get_num_tickets.html>
3536
3537       Low level API: SSL_* related functions
3538
3539       NOTE: Please note that the function described in this chapter have
3540       "SSL_" part stripped from their original openssl names.
3541
3542       ·   new
3543
3544           Creates a new SSL structure which is needed to hold the data for a
3545           TLS/SSL connection.  The new structure inherits the settings of the
3546           underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3547           options, verification settings, timeout settings.
3548
3549            my $rv = Net::SSLeay::new($ctx);
3550            # $ctx - value corresponding to openssl's SSL_CTX structure
3551            #
3552            # returns: value corresponding to openssl's SSL structure (0 on failure)
3553
3554           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3555
3556       ·   accept
3557
3558           Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3559           communication channel must already have been set and assigned to
3560           the ssl by setting an underlying BIO.
3561
3562            my $rv = Net::SSLeay::accept($ssl);
3563            # $ssl - value corresponding to openssl's SSL structure
3564            #
3565            # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3566
3567           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3568
3569       ·   add_client_CA
3570
3571           Adds the CA name extracted from cacert to the list of CAs sent to
3572           the client when requesting a client certificate for the chosen ssl,
3573           overriding the setting valid for ssl's SSL_CTX object.
3574
3575            my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3576            # $ssl - value corresponding to openssl's SSL structure
3577            # $x - value corresponding to openssl's X509 structure
3578            #
3579            # returns: 1 on success, 0 on failure
3580
3581           Check openssl doc
3582           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3583
3584       ·   callback_ctrl
3585
3586           ??? (more info needed)
3587
3588            my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3589            # $ssl - value corresponding to openssl's SSL structure
3590            # $cmd - (integer) command id
3591            # $fp - (function pointer) ???
3592            #
3593            # returns: ???
3594
3595           Check openssl doc
3596           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3597
3598       ·   check_private_key
3599
3600           Checks the consistency of a private key with the corresponding
3601           certificate loaded into $ssl
3602
3603            my $rv = Net::SSLeay::check_private_key($ssl);
3604            # $ssl - value corresponding to openssl's SSL structure
3605            #
3606            # returns: 1 on success, otherwise check out the error stack to find out the reason
3607
3608           Check openssl doc
3609           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3610
3611       ·   clear
3612
3613           Reset SSL object to allow another connection.
3614
3615            Net::SSLeay::clear($ssl);
3616            # $ssl - value corresponding to openssl's SSL structure
3617            #
3618            # returns: no return value
3619
3620           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3621
3622       ·   connect
3623
3624           Initiate the TLS/SSL handshake with an TLS/SSL server.
3625
3626            my $rv = Net::SSLeay::connect($ssl);
3627            # $ssl - value corresponding to openssl's SSL structure
3628            #
3629            # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3630
3631           Check openssl doc
3632           <http://www.openssl.org/docs/ssl/SSL_connect.html>
3633
3634       ·   copy_session_id
3635
3636           Copies the session structure fro $from to $to (+ also the private
3637           key and certificate associated with $from).
3638
3639            Net::SSLeay::copy_session_id($to, $from);
3640            # $to - value corresponding to openssl's SSL structure
3641            # $from - value corresponding to openssl's SSL structure
3642            #
3643            # returns: no return value
3644
3645       ·   ctrl
3646
3647           Internal handling function for SSL objects.
3648
3649           BEWARE: openssl doc says: This function should never be called
3650           directly!
3651
3652            my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3653            # $ssl - value corresponding to openssl's SSL structure
3654            # $cmd - (integer) command id
3655            # $larg - (integer) long ???
3656            # $parg - (string/pointer) ???
3657            #
3658            # returns: (long) result of given command ???
3659
3660           For more details about valid $cmd values check "CTX_ctrl".
3661
3662           Check openssl doc
3663           <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3664
3665       ·   do_handshake
3666
3667           Will wait for a SSL/TLS handshake to take place. If the connection
3668           is in client mode, the handshake will be started. The handshake
3669           routines may have to be explicitly set in advance using either
3670           SSL_set_connect_state or SSL_set_accept_state(3).
3671
3672            my $rv = Net::SSLeay::do_handshake($ssl);
3673            # $ssl - value corresponding to openssl's SSL structure
3674            #
3675            # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3676
3677           Check openssl doc
3678           <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3679
3680       ·   dup
3681
3682           Returns a duplicate of $ssl.
3683
3684            my $rv = Net::SSLeay::dup($ssl);
3685            # $ssl - value corresponding to openssl's SSL structure
3686            #
3687            # returns: value corresponding to openssl's SSL structure (0 on failure)
3688
3689       ·   free
3690
3691           Free an allocated SSL structure.
3692
3693            Net::SSLeay::free($ssl);
3694            # $ssl - value corresponding to openssl's SSL structure
3695            #
3696            # returns: no return value
3697
3698           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3699
3700       ·   get0_param
3701
3702           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
3703           requires at least OpenSSL 1.0.2
3704
3705           Returns the current verification parameters.
3706
3707            my $vpm = Net::SSLeay::get0_param($ssl);
3708            # $ssl - value corresponding to openssl's SSL structure
3709            #
3710            # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
3711
3712           Check openssl doc
3713           <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3714
3715       ·   get_SSL_CTX
3716
3717           Returns a pointer to the SSL_CTX object, from which $ssl was
3718           created with Net::SSLeay::new.
3719
3720            my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3721            # $ssl - value corresponding to openssl's SSL structure
3722            #
3723            # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3724
3725           Check openssl doc
3726           <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3727
3728       ·   set_SSL_CTX
3729
3730           Sets the SSL_CTX the corresponds to an SSL session.
3731
3732            my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3733            # $ssl - value corresponding to openssl's SSL structure
3734            # $ssl_ctx - Change the ssl object to the given ssl_ctx
3735            #
3736            # returns - the ssl_ctx
3737
3738       ·   get_app_data
3739
3740           Can be used to get application defined value/data.
3741
3742            my $rv = Net::SSLeay::get_app_data($ssl);
3743            # $ssl - value corresponding to openssl's SSL structure
3744            #
3745            # returns: string/buffer/pointer ???
3746
3747       ·   set_app_data
3748
3749           Can be used to set some application defined value/data.
3750
3751            my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3752            # $ssl - value corresponding to openssl's SSL structure
3753            # $arg - (string/buffer/pointer ???) data
3754            #
3755            # returns: ???
3756
3757       ·   get_certificate
3758
3759           Gets X509 certificate from an established SSL connection.
3760
3761            my $rv = Net::SSLeay::get_certificate($ssl);
3762            # $ssl - value corresponding to openssl's SSL structure
3763            #
3764            # returns: value corresponding to openssl's X509 structure (0 on failure)
3765
3766       ·   get_cipher
3767
3768           Obtains the name of the currently used cipher.
3769
3770            my $rv = Net::SSLeay::get_cipher($ssl);
3771            # $ssl - value corresponding to openssl's SSL structure
3772            #
3773            # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3774
3775           Check openssl doc
3776           <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3777
3778       ·   get_cipher_bits
3779
3780           Obtain the number of secret/algorithm bits used.
3781
3782            my $rv = Net::SSLeay::get_cipher_bits($ssl);
3783            # $ssl - value corresponding to openssl's SSL structure
3784            #
3785            # returns: number of secret bits used by current cipher
3786
3787           Check openssl doc
3788           <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3789           <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3790
3791       ·   get_cipher_list
3792
3793           Returns the name (string) of the SSL_CIPHER listed for $ssl with
3794           priority $n.
3795
3796            my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
3797            # $ssl - value corresponding to openssl's SSL structure
3798            # $n - (integer) priority
3799            #
3800            # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or '' in case of error
3801
3802           Call Net::SSLeay::get_cipher_list with priority starting from 0 to
3803           obtain the sorted list of available ciphers, until '' is returned:
3804
3805            my $priority = 0;
3806            while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
3807              print "cipher[$priority] = $c\n";
3808              $priority++;
3809            }
3810
3811           Check openssl doc
3812           <http://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
3813
3814       ·   get_client_CA_list
3815
3816           Returns the list of client CAs explicitly set for $ssl using
3817           "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
3818           "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
3819
3820           In client mode, returns the list of client CAs sent from the
3821           server, if any.
3822
3823            my $rv = Net::SSLeay::get_client_CA_list($ssl);
3824            # $ssl - value corresponding to openssl's SSL structure
3825            #
3826            # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
3827
3828           Check openssl doc
3829           <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
3830
3831       ·   get_current_cipher
3832
3833           Returns the cipher actually used.
3834
3835            my $rv = Net::SSLeay::get_current_cipher($ssl);
3836            # $ssl - value corresponding to openssl's SSL structure
3837            #
3838            # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
3839
3840           Check openssl doc
3841           <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3842
3843       ·   get_default_timeout
3844
3845           Returns the default timeout value assigned to SSL_SESSION objects
3846           negotiated for the protocol valid for $ssl.
3847
3848            my $rv = Net::SSLeay::get_default_timeout($ssl);
3849            # $ssl - value corresponding to openssl's SSL structure
3850            #
3851            # returns: (long) timeout in seconds
3852
3853           Check openssl doc
3854           <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
3855
3856       ·   get_error
3857
3858           Returns a result code for a preceding call to "connect", "accept",
3859           "do_handshake", "read", "peek" or "write" on $ssl.
3860
3861            my $rv = Net::SSLeay::get_error($ssl, $ret);
3862            # $ssl - value corresponding to openssl's SSL structure
3863            # $ret - return value of preceding TLS/SSL I/O operation
3864            #
3865            # returns: result code, which is one of the following values:
3866            #  0 - SSL_ERROR_NONE
3867            #  1 - SSL_ERROR_SSL
3868            #  2 - SSL_ERROR_WANT_READ
3869            #  3 - SSL_ERROR_WANT_WRITE
3870            #  4 - SSL_ERROR_WANT_X509_LOOKUP
3871            #  5 - SSL_ERROR_SYSCALL
3872            #  6 - SSL_ERROR_ZERO_RETURN
3873            #  7 - SSL_ERROR_WANT_CONNECT
3874            #  8 - SSL_ERROR_WANT_ACCEPT
3875
3876           Check openssl doc
3877           <http://www.openssl.org/docs/ssl/SSL_get_error.html>
3878
3879       ·   get_ex_data
3880
3881           Is used to retrieve the information for $idx from $ssl.
3882
3883            my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
3884            # $ssl - value corresponding to openssl's SSL structure
3885            # $idx - (integer) index for application specific data
3886            #
3887            # returns: pointer to ???
3888
3889           Check openssl doc
3890           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3891
3892       ·   set_ex_data
3893
3894           Is used to store application data at $data for $idx into the $ssl
3895           object.
3896
3897            my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
3898            # $ssl - value corresponding to openssl's SSL structure
3899            # $idx - (integer) ???
3900            # $data - (pointer) ???
3901            #
3902            # returns: 1 on success, 0 on failure
3903
3904           Check openssl doc
3905           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3906
3907       ·   get_ex_new_index
3908
3909           Is used to register a new index for application specific data.
3910
3911            my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
3912            # $argl - (long) ???
3913            # $argp - (pointer) ???
3914            # $new_func - function pointer ??? (CRYPTO_EX_new *)
3915            # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
3916            # $free_func - function pointer ??? (CRYPTO_EX_free *)
3917            #
3918            # returns: (integer) ???
3919
3920           Check openssl doc
3921           <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3922
3923       ·   get_fd
3924
3925           Returns the file descriptor which is linked to $ssl.
3926
3927            my $rv = Net::SSLeay::get_fd($ssl);
3928            # $ssl - value corresponding to openssl's SSL structure
3929            #
3930            # returns: file descriptor (>=0) or -1 on failure
3931
3932           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
3933
3934       ·   get_finished
3935
3936           Obtains the latest 'Finished' message sent to the peer. Return
3937           value is zero if there's been no Finished message yet. Default
3938           count is 2*EVP_MAX_MD_SIZE that is long enough for all possible
3939           Finish messages. If you supply a non-default count, the resulting
3940           return value may be longer than returned buf's length.
3941
3942            my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
3943            # $ssl - value corresponding to openssl's SSL structure
3944            # $buf - buffer where the returned data will be stored
3945            # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3946            #
3947            # returns: length of latest Finished message
3948
3949       ·   get_peer_finished
3950
3951           Obtains the latest 'Finished' message expected from the peer.
3952           Parameters and return value are similar to get_finished().
3953
3954            my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
3955            # $ssl - value corresponding to openssl's SSL structure
3956            # $buf - buffer where the returned data will be stored
3957            # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3958            #
3959            # returns: length of latest Finished message
3960
3961       ·   get_keyblock_size
3962
3963           Gets the length of the TLS keyblock.
3964
3965           NOTE: Does not exactly correspond to any low level API function.
3966
3967            my $rv = Net::SSLeay::get_keyblock_size($ssl);
3968            # $ssl - value corresponding to openssl's SSL structure
3969            #
3970            # returns: keyblock size, -1 on error
3971
3972       ·   get_mode
3973
3974           Returns the mode (bitmask) set for $ssl.
3975
3976            my $rv = Net::SSLeay::get_mode($ssl);
3977            # $ssl - value corresponding to openssl's SSL structure
3978            #
3979            # returns: mode (bitmask)
3980
3981           To decode the return value (bitmask) see documentation for
3982           "CTX_get_mode".
3983
3984           Check openssl doc
3985           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3986
3987       ·   set_mode
3988
3989           Adds the mode set via bitmask in $mode to $ssl. Options already set
3990           before are not cleared.
3991
3992            my $rv = Net::SSLeay::set_mode($ssl, $mode);
3993            # $ssl - value corresponding to openssl's SSL structure
3994            # $mode - mode (bitmask)
3995            #
3996            # returns: the new mode bitmask after adding $mode
3997
3998           For $mode bitmask details see "CTX_get_mode".
3999
4000           Check openssl doc
4001           <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
4002
4003       ·   get_options
4004
4005           Returns the options (bitmask) set for $ssl.
4006
4007            my $rv = Net::SSLeay::get_options($ssl);
4008            # $ssl - value corresponding to openssl's SSL structure
4009            #
4010            # returns: options (bitmask)
4011
4012           To decode the return value (bitmask) see documentation for
4013           "CTX_get_options".
4014
4015           Check openssl doc
4016           <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4017
4018       ·   set_options
4019
4020           Adds the options set via bitmask in $options to $ssl. Options
4021           already set before are not cleared!
4022
4023            Net::SSLeay::set_options($ssl, $options);
4024            # $ssl - value corresponding to openssl's SSL structure
4025            # $options - options (bitmask)
4026            #
4027            # returns: the new options bitmask after adding $options
4028
4029           For $options bitmask details see "CTX_get_options".
4030
4031           Check openssl doc
4032           <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
4033
4034       ·   get_peer_certificate
4035
4036           Get the X509 certificate of the peer.
4037
4038            my $rv = Net::SSLeay::get_peer_certificate($ssl);
4039            # $ssl - value corresponding to openssl's SSL structure
4040            #
4041            # returns: value corresponding to openssl's X509 structure (0 on failure)
4042
4043           Check openssl doc
4044           <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4045
4046       ·   get_peer_cert_chain
4047
4048           Get the certificate chain of the peer as an array of X509
4049           structures.
4050
4051            my @rv = Net::SSLeay::get_peer_cert_chain($ssl);
4052            # $ssl - value corresponding to openssl's SSL structure
4053            #
4054            # returns: list of X509 structures
4055
4056           Check openssl doc
4057           <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
4058
4059       ·   get_quiet_shutdown
4060
4061           Returns the 'quiet shutdown' setting of ssl.
4062
4063            my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
4064            # $ssl - value corresponding to openssl's SSL structure
4065            #
4066            # returns: (integer) current 'quiet shutdown' value
4067
4068           Check openssl doc
4069           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4070
4071       ·   get_rbio
4072
4073           Get 'read' BIO linked to an SSL object $ssl.
4074
4075            my $rv = Net::SSLeay::get_rbio($ssl);
4076            # $ssl - value corresponding to openssl's SSL structure
4077            #
4078            # returns: value corresponding to openssl's BIO structure (0 on failure)
4079
4080           Check openssl doc
4081           <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4082
4083       ·   get_read_ahead
4084
4085            my $rv = Net::SSLeay::get_read_ahead($ssl);
4086            # $ssl - value corresponding to openssl's SSL structure
4087            #
4088            # returns: (integer) read_ahead value
4089
4090       ·   set_read_ahead
4091
4092            Net::SSLeay::set_read_ahead($ssl, $val);
4093            # $ssl - value corresponding to openssl's SSL structure
4094            # $val - read_ahead value to be set
4095            #
4096            # returns: the original read_ahead value
4097
4098       ·   get_security_level
4099
4100           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4101           requires at least OpenSSL 1.1.0, not in LibreSSL
4102
4103           Returns the security level associated with $ssl.
4104
4105            my $level = Net::SSLeay::get_security_level($ssl);
4106            # $ssl   - value corresponding to openssl's SSL structure
4107            #
4108            # returns: (integer) current security level
4109
4110           Check openssl doc
4111           <https://www.openssl.org/docs/manmaster/man3/SSL_get_security_level.html>
4112
4113       ·   set_security_level
4114
4115           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4116           requires at least OpenSSL 1.1.0, not in LibreSSL
4117
4118           Sets the security level associated with $ssl to $level.
4119
4120            Net::SSLeay::set_security_level($ssl, $level);
4121            # $ssl   - value corresponding to openssl's SSL structure
4122            # $level - new security level
4123            #
4124            # returns: no return value
4125
4126           Check openssl doc
4127           <https://www.openssl.org/docs/manmaster/man3/SSL_set_security_level.html>
4128
4129       ·   set_num_tickets
4130
4131           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4132           requires at least OpenSSL 1.1.1, not in LibreSSL
4133
4134           Set number of TLSv1.3 session tickets that will be sent to a
4135           client.
4136
4137            my $rv = Net::SSLeay::set_num_tickets($ssl, $number_of_tickets);
4138            # $ssl  - value corresponding to openssl's SSL structure
4139            # $number_of_tickets - number of tickets to send
4140            #
4141            # returns: 1 on success, 0 on failure
4142
4143           Set to zero if you do not no want to support a session resumption.
4144
4145           Check openssl doc
4146           <https://www.openssl.org/docs/manmaster/man3/SSL_set_num_tickets.html>
4147
4148       ·   get_num_tickets
4149
4150           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4151           requires at least OpenSSL 1.1.1, not in LibreSSL
4152
4153           Get number of TLSv1.3 session tickets that will be sent to a
4154           client.
4155
4156            my $number_of_tickets = Net::SSLeay::get_num_tickets($ctx);
4157            # $ctx  - value corresponding to openssl's SSL structure
4158            #
4159            # returns: number of tickets to send
4160
4161           Check openssl doc
4162           <https://www.openssl.org/docs/manmaster/man3/SSL_get_num_tickets.html>
4163
4164       ·   get_server_random
4165
4166           Returns internal SSLv3 server_random value.
4167
4168            Net::SSLeay::get_server_random($ssl);
4169            # $ssl - value corresponding to openssl's SSL structure
4170            #
4171            # returns: server_random value (binary data)
4172
4173       ·   get_client_random
4174
4175           NOTE: Does not exactly correspond to any low level API function
4176
4177           Returns internal SSLv3 client_random value.
4178
4179            Net::SSLeay::get_client_random($ssl);
4180            # $ssl - value corresponding to openssl's SSL structure
4181            #
4182            # returns: client_random value (binary data)
4183
4184       ·   export_keying_material
4185
4186           Returns keying material based on the string $label and optional
4187           $context. Note that with TLSv1.2 and lower, empty context (empty
4188           string) and undefined context (no value or 'undef') will return
4189           different values.
4190
4191             my $out = Net::SSLeay::export_keying_material($ssl, $olen, $label, $context);
4192             # $ssl - value corresponding to openssl's SSL structure
4193             # $olen - number of bytes to return
4194             # $label - application specific label
4195             # $context - [optional] context - default is undef for no context
4196             #
4197             # returns: keying material (binary data) or undef on error
4198
4199           Check openssl doc
4200           <https://www.openssl.org/docs/manmaster/man3/SSL_export_keying_material.html>
4201
4202       ·   get_session
4203
4204           Retrieve TLS/SSL session data used in $ssl. The reference count of
4205           the SSL_SESSION is NOT incremented.
4206
4207            my $rv = Net::SSLeay::get_session($ssl);
4208            # $ssl - value corresponding to openssl's SSL structure
4209            #
4210            # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4211
4212           Check openssl doc
4213           <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4214
4215       ·   SSL_get0_session
4216
4217           The alias for "get_session" (note that the name is
4218           "SSL_get0_session" NOT "get0_session").
4219
4220            my $rv = Net::SSLeay::SSL_get0_session();
4221
4222       ·   get1_session
4223
4224           Returns a pointer to the SSL_SESSION actually used in $ssl. The
4225           reference count of the SSL_SESSION is incremented by 1.
4226
4227            my $rv = Net::SSLeay::get1_session($ssl);
4228            # $ssl - value corresponding to openssl's SSL structure
4229            #
4230            # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
4231
4232           Check openssl doc
4233           <http://www.openssl.org/docs/ssl/SSL_get_session.html>
4234
4235       ·   get_shared_ciphers
4236
4237           Returns string with a list (colon ':' separated) of ciphers shared
4238           between client and server within SSL session $ssl.
4239
4240            my $rv = Net::SSLeay::get_shared_ciphers()
4241            #
4242            # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
4243
4244       ·   get_shutdown
4245
4246           Returns the shutdown mode of $ssl.
4247
4248            my $rv = Net::SSLeay::get_shutdown($ssl);
4249            # $ssl - value corresponding to openssl's SSL structure
4250            #
4251            # returns: shutdown mode (bitmask) of ssl
4252
4253            #to decode the return value (bitmask) use:
4254            0 - No shutdown setting, yet
4255            1 - SSL_SENT_SHUTDOWN
4256            2 - SSL_RECEIVED_SHUTDOWN
4257
4258           Check openssl doc
4259           <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4260
4261       ·   get_ssl_method
4262
4263           Returns a function pointer to the TLS/SSL method set in $ssl.
4264
4265            my $rv = Net::SSLeay::get_ssl_method($ssl);
4266            # $ssl - value corresponding to openssl's SSL structure
4267            #
4268            # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
4269
4270           Check openssl doc
4271           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4272
4273       ·   in_init, in_before, is_init_finished, in_connect_init,
4274           in_accept_init
4275
4276           COMPATIBILITY: not available in Net-SSLeay-1.85 and before.
4277
4278           Retrieve information about the handshake state machine. All
4279           functions take $ssl as the only argument and return 0 or 1. These
4280           functions are recommended over get_state() and state().
4281
4282            my $rv = Net::SSLeay::is_init_finished($ssl);
4283            # $ssl - value corresponding to openssl's SSL structure
4284            #
4285            # returns: All functions return 1 or 0
4286
4287           Check openssl doc https://www.openssl.org/docs/ssl/SSL_in_init.html
4288           <http://www.openssl.org/docs/ssl/SSL_in_init.html>
4289
4290       ·   get_state
4291
4292           COMPATIBILITY: OpenSSL 1.1.0 and later use different constants
4293           which are not made available. Use is_init_finished() and related
4294           functions instead.
4295
4296           Returns the SSL connection state.
4297
4298            my $rv = Net::SSLeay::get_state($ssl);
4299            # $ssl - value corresponding to openssl's SSL structure
4300            #
4301            # returns: (integer) state value
4302            #          to decode the returned state check:
4303            #          SSL_ST_* constants in openssl/ssl.h
4304            #          SSL2_ST_* constants in openssl/ssl2.h
4305            #          SSL23_ST_* constants in openssl/ssl23.h
4306            #          SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
4307
4308       ·   state
4309
4310           Exactly the same as "get_state".
4311
4312            my $rv = Net::SSLeay::state($ssl);
4313
4314       ·   set_state
4315
4316           Sets the SSL connection state.
4317
4318            Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4319
4320           Not available with OpenSSL 1.1 and later.
4321
4322       ·   get_verify_depth
4323
4324           Returns the verification depth limit currently set in $ssl.
4325
4326            my $rv = Net::SSLeay::get_verify_depth($ssl);
4327            # $ssl - value corresponding to openssl's SSL structure
4328            #
4329            # returns: current depth or -1 if no limit has been explicitly set
4330
4331           Check openssl doc
4332           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4333
4334       ·   set_verify_depth
4335
4336           Sets the maximum depth for the certificate chain verification that
4337           shall be allowed for $ssl.
4338
4339            Net::SSLeay::set_verify_depth($ssl, $depth);
4340            # $ssl - value corresponding to openssl's SSL structure
4341            # $depth - (integer) depth
4342            #
4343            # returns: no return value
4344
4345           Check openssl doc
4346           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4347
4348       ·   get_verify_mode
4349
4350           Returns the verification mode (bitmask) currently set in $ssl.
4351
4352            my $rv = Net::SSLeay::get_verify_mode($ssl);
4353            # $ssl - value corresponding to openssl's SSL structure
4354            #
4355            # returns: mode (bitmask)
4356
4357           To decode the return value (bitmask) see documentation for
4358           "CTX_get_verify_mode".
4359
4360           Check openssl doc
4361           <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4362
4363       ·   set_verify
4364
4365           Sets the verification flags for $ssl to be $mode and specifies the
4366           $verify_callback function to be used.
4367
4368            Net::SSLeay::set_verify($ssl, $mode, $callback);
4369            # $ssl - value corresponding to openssl's SSL structure
4370            # $mode - mode (bitmask)
4371            # $callback - [optional] reference to perl callback function
4372            #
4373            # returns: no return value
4374
4375           For $mode bitmask details see "CTX_get_verify_mode".
4376
4377           Check openssl doc
4378           <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4379
4380       ·   set_post_handshake_auth
4381
4382           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4383           requires at least OpenSSL 1.1.1, not in LibreSSL
4384
4385           Enable the Post-Handshake Authentication extension to be added to
4386           the ClientHello such that post-handshake authentication can be
4387           requested by the server.
4388
4389            Net::SSLeay::set_posthandshake_auth($ssl, $val);
4390            # $ssl - value corresponding to openssl's SSL structure
4391            # $val - 0 then the extension is not sent, otherwise it is
4392            #
4393            # returns: no return value
4394
4395           Check openssl doc
4396           https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth
4397           <https://www.openssl.org/docs/manmaster/man3/SSL_set_post_handshake_auth.html>
4398
4399       ·   verify_client_post_handshake
4400
4401           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4402           requires at least OpenSSL 1.1.1, not in LibreSSL
4403
4404           verify_client_post_handshake causes a CertificateRequest message to
4405           be sent by a server on the given ssl connection.
4406
4407            my $rv = Net::SSLeay::verify_client_post_handshake($ssl);
4408            # $ssl - value corresponding to openssl's SSL structure
4409            #
4410            # returns: 1 if the request succeeded, and 0 if the request failed. The error stack can be examined to determine the failure reason.
4411
4412           Check openssl doc
4413           <https://www.openssl.org/docs/manmaster/man3/SSL_verify_client_post_handshake.html>
4414
4415       ·   get_verify_result
4416
4417           Returns the result of the verification of the X509 certificate
4418           presented by the peer, if any.
4419
4420            my $rv = Net::SSLeay::get_verify_result($ssl);
4421            # $ssl - value corresponding to openssl's SSL structure
4422            #
4423            # returns: (integer)
4424            #      0 - X509_V_OK: ok
4425            #      2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
4426            #      3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
4427            #      4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
4428            #      5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
4429            #      6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
4430            #      7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
4431            #      8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
4432            #      9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
4433            #     10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
4434            #     11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
4435            #     12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
4436            #     13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
4437            #     14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
4438            #     15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
4439            #     16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
4440            #     17 - X509_V_ERR_OUT_OF_MEM: out of memory
4441            #     18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
4442            #     19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
4443            #     20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
4444            #     21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
4445            #     22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
4446            #     23 - X509_V_ERR_CERT_REVOKED: certificate revoked
4447            #     24 - X509_V_ERR_INVALID_CA: invalid CA certificate
4448            #     25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
4449            #     26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
4450            #     27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
4451            #     28 - X509_V_ERR_CERT_REJECTED: certificate rejected
4452            #     29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
4453            #     30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
4454            #     31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
4455            #     32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
4456            #     50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
4457
4458           Check openssl doc
4459           <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4460
4461       ·   set_verify_result
4462
4463           Override result of peer certificate verification.
4464
4465            Net::SSLeay::set_verify_result($ssl, $v);
4466            # $ssl - value corresponding to openssl's SSL structure
4467            # $v - (integer) result value
4468            #
4469            # returns: no return value
4470
4471           For more info about valid return values see "get_verify_result"
4472
4473           Check openssl doc
4474           <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4475
4476       ·   get_wbio
4477
4478           Get 'write' BIO linked to an SSL object $ssl.
4479
4480            my $rv = Net::SSLeay::get_wbio($ssl);
4481            # $ssl - value corresponding to openssl's SSL structure
4482            #
4483            # returns: value corresponding to openssl's BIO structure (0 on failure)
4484
4485           Check openssl doc
4486           <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4487
4488       ·   load_client_CA_file
4489
4490           Load X509 certificates from file (PEM formatted).
4491
4492            my $rv = Net::SSLeay::load_client_CA_file($file);
4493            # $file - (string) file name
4494            #
4495            # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4496
4497           Check openssl doc
4498           <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4499
4500       ·   clear_num_renegotiations
4501
4502           Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4503
4504            my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4505            # $ssl - value corresponding to openssl's SSL structure
4506            #
4507            # returns: command result
4508
4509       ·   need_tmp_RSA
4510
4511           Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4512
4513            my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4514            # $ssl - value corresponding to openssl's SSL structure
4515            #
4516            # returns: command result
4517
4518           Not available with OpenSSL 1.1 and later.
4519
4520       ·   num_renegotiations
4521
4522           Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4523
4524            my $rv = Net::SSLeay::num_renegotiations($ssl);
4525            # $ssl - value corresponding to openssl's SSL structure
4526            #
4527            # returns: command result
4528
4529       ·   total_renegotiations
4530
4531           Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4532
4533            my $rv = Net::SSLeay::total_renegotiations($ssl);
4534            # $ssl - value corresponding to openssl's SSL structure
4535            #
4536            # returns: command result
4537
4538       ·   peek
4539
4540           Copies $max bytes from the specified $ssl into the returned value.
4541           In contrast to the "Net::SSLeay::read()" function, the data in the
4542           SSL buffer is unmodified after the SSL_peek() operation.
4543
4544            Net::SSLeay::peek($ssl, $max);
4545            # $ssl - value corresponding to openssl's SSL structure
4546            # $max - [optional] max bytes to peek (integer) - default is 32768
4547            #
4548            # in scalar context: data read from the TLS/SSL connection, undef on error
4549            # in list context:   two-item array consisting of data read (undef on error),
4550            #                      and return code from SSL_peek().
4551
4552       ·   peek_ex
4553
4554           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4555           requires at least OpenSSL 1.1.1, not in LibreSSL
4556
4557           Copies $max bytes from the specified $ssl into the returned value.
4558           In contrast to the "Net::SSLeay::read_ex()" function, the data in
4559           the SSL buffer is unmodified after the SSL_peek_ex() operation.
4560
4561            my($got, $rv) = Net::SSLeay::peek_ex($ssl, $max);
4562            # $ssl - value corresponding to openssl's SSL structure
4563            # $max - [optional] max bytes to peek (integer) - default is 32768
4564            #
4565            # returns a list: two-item list consisting of data read (undef on error),
4566            #                 and return code from SSL_peek_ex().
4567
4568           Check openssl doc
4569           <https://www.openssl.org/docs/manmaster/man3/SSL_peek_ex.html>
4570
4571       ·   pending
4572
4573           Obtain number of readable bytes buffered in $ssl object.
4574
4575            my $rv = Net::SSLeay::pending($ssl);
4576            # $ssl - value corresponding to openssl's SSL structure
4577            #
4578            # returns: the number of bytes pending
4579
4580           Check openssl doc
4581           <http://www.openssl.org/docs/ssl/SSL_pending.html>
4582
4583       ·   has_pending
4584
4585           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4586           requires at least OpenSSL 1.1.0, not in LibreSSL
4587
4588           Returns 1 if $ssl has buffered data (whether processed or
4589           unprocessed) and 0 otherwise.
4590
4591            my $rv = Net::SSLeay::has_pending($ssl);
4592            # $ssl - value corresponding to openssl's SSL structure
4593            #
4594            # returns: (integer) 1 or 0
4595
4596           Check openssl doc
4597           <https://www.openssl.org/docs/manmaster/man3/SSL_has_pending.html>
4598
4599       ·   read
4600
4601           Tries to read $max bytes from the specified $ssl.
4602
4603            my $got = Net::SSLeay::read($ssl, $max);
4604            my($got, $rv) = Net::SSLeay::read($ssl, $max);
4605            # $ssl - value corresponding to openssl's SSL structure
4606            # $max - [optional] max bytes to read (integer) - default is 32768
4607            #
4608            # returns:
4609            # in scalar context: data read from the TLS/SSL connection, undef on error
4610            # in list context:   two-item array consisting of data read (undef on error),
4611            #                      and return code from SSL_read().
4612
4613           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4614
4615       ·   read_ex
4616
4617           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4618           requires at least OpenSSL 1.1.1, not in LibreSSL
4619
4620           Tries to read $max bytes from the specified $ssl.
4621
4622            my($got, $rv) = Net::SSLeay::read_ex($ssl, $max);
4623            # $ssl - value corresponding to openssl's SSL structure
4624            # $max - [optional] max bytes to read (integer) - default is 32768
4625            #
4626            # returns a list: two-item list consisting of data read (undef on error),
4627            #                 and return code from SSL_read_ex().
4628
4629           Check openssl doc
4630           <https://www.openssl.org/docs/manmaster/man3/SSL_read_ex.html>
4631
4632       ·   renegotiate
4633
4634           Turn on flags for renegotiation so that renegotiation will happen
4635
4636            my $rv = Net::SSLeay::renegotiate($ssl);
4637            # $ssl - value corresponding to openssl's SSL structure
4638            #
4639            # returns: 1 on success, 0 on failure
4640
4641       ·   rstate_string
4642
4643           Returns a 2 letter string indicating the current read state of the
4644           SSL object $ssl.
4645
4646            my $rv = Net::SSLeay::rstate_string($ssl);
4647            # $ssl - value corresponding to openssl's SSL structure
4648            #
4649            # returns: 2-letter string
4650
4651           Check openssl doc
4652           <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4653
4654       ·   rstate_string_long
4655
4656           Returns a string indicating the current read state of the SSL
4657           object ssl.
4658
4659            my $rv = Net::SSLeay::rstate_string_long($ssl);
4660            # $ssl - value corresponding to openssl's SSL structure
4661            #
4662            # returns: string with current state
4663
4664           Check openssl doc
4665           <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4666
4667       ·   session_reused
4668
4669           Query whether a reused session was negotiated during handshake.
4670
4671            my $rv = Net::SSLeay::session_reused($ssl);
4672            # $ssl - value corresponding to openssl's SSL structure
4673            #
4674            # returns: 0 - new session was negotiated; 1 - session was reused.
4675
4676           Check openssl doc
4677           <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4678
4679       ·   set1_param
4680
4681           Applies X509 verification parameters $vpm on $ssl
4682
4683            my $rv = Net::SSLeay::set1_param($ssl, $vpm);
4684            # $ssl - value corresponding to openssl's SSL structure
4685            # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
4686            #
4687            # returns: 1 on success, 0 on failure
4688
4689       ·   set_accept_state
4690
4691           Sets $ssl to work in server mode.
4692
4693            Net::SSLeay::set_accept_state($ssl);
4694            # $ssl - value corresponding to openssl's SSL structure
4695            #
4696            # returns: no return value
4697
4698           Check openssl doc
4699           <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4700
4701       ·   set_bio
4702
4703           Connects the BIOs $rbio and $wbio for the read and write operations
4704           of the TLS/SSL (encrypted) side of $ssl.
4705
4706            Net::SSLeay::set_bio($ssl, $rbio, $wbio);
4707            # $ssl - value corresponding to openssl's SSL structure
4708            # $rbio - value corresponding to openssl's BIO structure
4709            # $wbio - value corresponding to openssl's BIO structure
4710            #
4711            # returns: no return value
4712
4713           Check openssl doc
4714           <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4715
4716       ·   set_cipher_list
4717
4718           Sets the list of ciphers only for ssl.
4719
4720            my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
4721            # $ssl - value corresponding to openssl's SSL structure
4722            # $str - (string) cipher list e.g. '3DES:+RSA'
4723            #
4724            # returns: 1 if any cipher could be selected and 0 on complete failure
4725
4726           Check openssl doc
4727           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4728
4729       ·   set_ciphersuites
4730
4731           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4732           requires at least OpenSSL 1.1.1, not in LibreSSL
4733
4734           Configure the available TLSv1.3 ciphersuites.
4735
4736            my $rv = Net::SSLeay::set_ciphersuites($ssl, $str);
4737            # $ssl  - value corresponding to openssl's SSL structure
4738            # $str  - colon (":") separated list of TLSv1.3 ciphersuite names in order of preference
4739            #
4740            # returns: (integer) 1 if the requested ciphersuite list was configured, and 0 otherwise
4741
4742           Check openssl doc
4743           <https://www.openssl.org/docs/manmaster/man3/SSL_set_ciphersuites.html>
4744
4745       ·   set_client_CA_list
4746
4747           Sets the list of CAs sent to the client when requesting a client
4748           certificate for the chosen $ssl, overriding the setting valid for
4749           $ssl's SSL_CTX object.
4750
4751            my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
4752            # $ssl - value corresponding to openssl's SSL structure
4753            # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
4754            #
4755            # returns: no return value
4756
4757           Check openssl doc
4758           <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4759
4760       ·   set_connect_state
4761
4762           Sets $ssl to work in client mode.
4763
4764            Net::SSLeay::set_connect_state($ssl);
4765            # $ssl - value corresponding to openssl's SSL structure
4766            #
4767            # returns: no return value
4768
4769           Check openssl doc
4770           <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4771
4772       ·   set_fd
4773
4774           Sets the file descriptor $fd as the input/output facility for the
4775           TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
4776           file descriptor of a network connection.
4777
4778            my $rv = Net::SSLeay::set_fd($ssl, $fd);
4779            # $ssl - value corresponding to openssl's SSL structure
4780            # $fd - (integer) file handle (got via perl's fileno)
4781            #
4782            # returns: 1 on success, 0 on failure
4783
4784           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4785
4786       ·   set_psk_client_callback
4787
4788           Sets the psk client callback.
4789
4790            Net::SSLeay::set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4791            # $ssl - value corresponding to openssl's SSL structure
4792            # $hint - PSK identity hint send by the server
4793            # $identity - PSK identity
4794            # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4795            #
4796            # returns: no return value
4797
4798           Check openssl doc
4799           <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
4800
4801       ·   set_rfd
4802
4803           Sets the file descriptor $fd as the input (read) facility for the
4804           TLS/SSL (encrypted) side of $ssl.
4805
4806            my $rv = Net::SSLeay::set_rfd($ssl, $fd);
4807            # $ssl - value corresponding to openssl's SSL structure
4808            # $fd - (integer) file handle (got via perl's fileno)
4809            #
4810            # returns: 1 on success, 0 on failure
4811
4812           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4813
4814       ·   set_wfd
4815
4816            my $rv = Net::SSLeay::set_wfd($ssl, $fd);
4817            # $ssl - value corresponding to openssl's SSL structure
4818            # $fd - (integer) file handle (got via perl's fileno)
4819            #
4820            # returns: 1 on success, 0 on failure
4821
4822           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4823
4824       ·   set_info_callback
4825
4826           Sets the callback function, that can be used to obtain state
4827           information for $ssl during connection setup and use.  When
4828           callback is undef, the callback setting currently valid for ctx is
4829           used.
4830
4831            Net::SSLeay::set_info_callback($ssl, $cb, [$data]);
4832            # $ssl - value corresponding to openssl's SSL structure
4833            # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4834            #
4835            # returns: no return value
4836
4837           Check openssl doc
4838           <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4839
4840       ·   CTX_set_info_callback
4841
4842           Sets the callback function on ctx, that can be used to obtain state
4843           information during ssl connection setup and use.  When callback is
4844           undef, an existing callback will be disabled.
4845
4846            Net::SSLeay::CTX_set_info_callback($ssl, $cb, [$data]);
4847            # $ssl - value corresponding to openssl's SSL structure
4848            # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4849            #
4850            # returns: no return value
4851
4852           Check openssl doc
4853           <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4854
4855       ·   set_pref_cipher
4856
4857           Sets the list of available ciphers for $ssl using the control
4858           string $str.
4859
4860            my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
4861            # $ssl - value corresponding to openssl's SSL structure
4862            # $str - (string) cipher list e.g. '3DES:+RSA'
4863            #
4864            # returns: 1 if any cipher could be selected and 0 on complete failure
4865
4866           Check openssl doc
4867           <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4868
4869       ·   CTX_set_psk_client_callback
4870
4871           Sets the psk client callback.
4872
4873            Net::SSLeay::CTX_set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4874            # $ssl - value corresponding to openssl's SSL structure
4875            # $hint - PSK identity hint send by the server
4876            # $identity - PSK identity
4877            # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4878            #
4879            # returns: no return value
4880
4881           Check openssl doc
4882           <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
4883
4884       ·   set_purpose
4885
4886            my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
4887            # $ssl - value corresponding to openssl's SSL structure
4888            # $purpose - (integer) purpose identifier
4889            #
4890            # returns: 1 on success, 0 on failure
4891
4892           For more info about available $purpose identifiers see
4893           "CTX_set_purpose".
4894
4895       ·   set_quiet_shutdown
4896
4897           Sets the 'quiet shutdown' flag for $ssl to be $mode.
4898
4899            Net::SSLeay::set_quiet_shutdown($ssl, $mode);
4900            # $ssl - value corresponding to openssl's SSL structure
4901            # $mode - 0 or 1
4902            #
4903            # returns: no return value
4904
4905           Check openssl doc
4906           <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4907
4908       ·   set_session
4909
4910           Set a TLS/SSL session to be used during TLS/SSL connect.
4911
4912            my $rv = Net::SSLeay::set_session($to, $ses);
4913            # $to - value corresponding to openssl's SSL structure
4914            # $ses - value corresponding to openssl's SSL_SESSION structure
4915            #
4916            # returns: 1 on success, 0 on failure
4917
4918           Check openssl doc
4919           <http://www.openssl.org/docs/ssl/SSL_set_session.html>
4920
4921       ·   set_session_id_context
4922
4923           Sets the context $sid_ctx of length $sid_ctx_len within which a
4924           session can be reused for the $ssl object.
4925
4926            my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
4927            # $ssl - value corresponding to openssl's SSL structure
4928            # $sid_ctx - data buffer
4929            # $sid_ctx_len - length of data in $sid_ctx
4930            #
4931            # returns: 1 on success, 0 on failure
4932
4933           Check openssl doc
4934           <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
4935
4936       ·   set_session_secret_cb
4937
4938           Setup pre-shared secret session resumption function.
4939
4940            Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
4941            # $ssl - value corresponding to openssl's SSL structure
4942            # $func - perl reference to callback function
4943            # $data - [optional] data that will be passed to callback function when invoked
4944            #
4945            # returns: no return value
4946
4947           The callback function will be called like:
4948           callback_function($secret, $ciphers, $pref_cipher, $data);
4949
4950           # $secret is the current master session key, usually all 0s at the
4951           beginning of a session # $ciphers is ref to an array of peer cipher
4952           names # $pref_cipher is a ref to an index into the list of cipher
4953           names of #  the preferred cipher. Set it if you want to specify a
4954           preferred cipher # $data is the data passed to
4955           set_session_secret_cb
4956
4957           The callback function should return 1 if it likes the suggested
4958           cipher (or has selected an alternative by setting pref_cipher),
4959           else it should return 0 (in which case OpenSSL will select its own
4960           preferred cipher).
4961
4962           With OpenSSL 1.1 and later, callback_function can change the master
4963           key for the session by altering $secret and returning 1.
4964
4965       ·   CTX_set_tlsext_ticket_getkey_cb
4966
4967           Setup encryption for TLS session tickets (stateless session reuse).
4968
4969            Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($ctx, $func, $data);
4970            # $ctx  - value corresponding to openssl's SSL_CTX structure
4971            # $func - perl reference to callback function
4972            # $data - [optional] data that will be passed to callback function when invoked
4973            #
4974            # returns: no return value
4975
4976           The callback function will be called like:
4977           getkey($data,[$key_name]) -> ($key,$current_key_name)
4978
4979           # $data is the data passed to set_session_secret_cb # $key_name is
4980           the name of the key OpenSSL has extracted from the session ticket #
4981           $key is the requested key for ticket encryption + HMAC #
4982           $current_key_name is the name for the currently valid key
4983
4984           OpenSSL will call the function without a key name if it generates a
4985           new ticket.  It then needs the callback to return the
4986           encryption+HMAC key and an identifier (key name) for this key.
4987
4988           When OpenSSL gets a session ticket from the client it extracts the
4989           key name and calls the callback with this name as argument. It then
4990           expects the callback to return the encryption+HMAC key matching the
4991           requested key name and and also the key name which should be used
4992           at the moment. If the requested key name and the returned key name
4993           differ it means that this session ticket was created with an
4994           expired key and need to be renewed. In this case OpenSSL will call
4995           the callback again with no key name to create a new session ticket
4996           based on the old one.
4997
4998           The key must be at least 32 byte of random data which can be
4999           created with RAND_bytes. Internally the first 16 byte are used as
5000           key in AES-128 encryption while the next 16 byte are used for the
5001           SHA-256 HMAC.  The key name are binary data and must be exactly 16
5002           byte long.
5003
5004           Example:
5005
5006               Net::SSLeay::RAND_bytes(my $oldkey,32);
5007               Net::SSLeay::RAND_bytes(my $newkey,32);
5008               my $oldkey_name = pack("a16",'oldsecret');
5009               my $newkey_name = pack("a16",'newsecret');
5010
5011               my @keys = (
5012                   [ $newkey_name, $newkey ], # current active key
5013                   [ $oldkey_name, $oldkey ], # already expired
5014               );
5015
5016               Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
5017                   my ($mykeys,$name) = @_;
5018
5019                   # return (current_key, current_key_name) if no name given
5020                   return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
5021
5022                   # return (matching_key, current_key_name) if we find a key matching
5023                   # the given name
5024                   for(my $i = 0; $i<@$mykeys; $i++) {
5025                       next if $name ne $mykeys->[$i][0];
5026                       return ($mykeys->[$i][1],$mykeys->[0][0]);
5027                   }
5028
5029                   # no matching key found
5030                   return;
5031               },\@keys);
5032
5033           This function is based on the OpenSSL function
5034           SSL_CTX_set_tlsext_ticket_key_cb but provides a simpler to use
5035           interface. For more information see
5036           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tlsext_ticket_key_cb.html>
5037
5038       ·   set_session_ticket_ext_cb
5039
5040           Setup callback for TLS session tickets (stateless session reuse).
5041
5042            Net::SSLeay::set_session_ticket_ext_cb($ssl, $func, $data);
5043            # $ssl  - value corresponding to openssl's SSL structure
5044            # $func - perl reference to callback function
5045            # $data - [optional] data that will be passed to callback function when invoked
5046            #
5047            # returns: no return value
5048
5049           The callback function will be called like:
5050           getticket($ssl,$ticket,$data) -> $return_value
5051
5052           # $ssl is a value corresponding to openssl's SSL structure #
5053           $ticket is a value of received TLS session ticket (can also be
5054           empty) # $data is the data passed to set_session_ticket_ext_cb #
5055           $return_value is either 0 (failure) or 1 (success)
5056
5057           This function is based on the OpenSSL function
5058           SSL_set_session_ticket_ext_cb.
5059
5060       ·   set_session_ticket_ext
5061
5062           Set TLS session ticket (stateless session reuse).
5063
5064            Net::SSLeay::set_session_ticket_ext($ssl, $ticket);
5065            # $ssl    - value corresponding to openssl's SSL structure
5066            # $ticket - is a value of TLS session ticket which client will send (can also be empty string)
5067            #
5068            # returns: no return value
5069
5070           The callback function will be called like:
5071           getticket($ssl,$ticket,$data) -> $return_value
5072
5073           # $ssl is a value corresponding to openssl's SSL structure #
5074           $ticket is a value of received TLS session ticket (can also be
5075           empty) # $data is the data passed to set_session_ticket_ext_cb #
5076           $return_value is either 0 (failure) or 1 (success)
5077
5078           This function is based on the OpenSSL function
5079           SSL_set_session_ticket_ext_cb.
5080
5081       ·   set_shutdown
5082
5083           Sets the shutdown state of $ssl to $mode.
5084
5085            Net::SSLeay::set_shutdown($ssl, $mode);
5086            # $ssl - value corresponding to openssl's SSL structure
5087            # $mode - (integer) shutdown mode:
5088            #         0 - No shutdown
5089            #         1 - SSL_SENT_SHUTDOWN
5090            #         2 - SSL_RECEIVED_SHUTDOWN
5091            #         3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
5092            #
5093            # returns: no return value
5094
5095           Check openssl doc
5096           <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
5097
5098       ·   set_ssl_method
5099
5100           Sets a new TLS/SSL method for a particular $ssl object.
5101
5102            my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
5103            # $ssl - value corresponding to openssl's SSL structure
5104            # $method - value corresponding to openssl's SSL_METHOD structure
5105            #
5106            # returns: 1 on success, 0 on failure
5107
5108           Check openssl doc
5109           <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
5110
5111       ·   set_tmp_dh
5112
5113           Sets DH parameters to be used to be $dh.
5114
5115            my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
5116            # $ssl - value corresponding to openssl's SSL structure
5117            # $dh - value corresponding to openssl's DH structure
5118            #
5119            # returns: 1 on success, 0 on failure
5120
5121           Check openssl doc
5122           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5123
5124       ·   set_tmp_dh_callback
5125
5126           Sets the callback function for $ssl to be used when a DH parameters
5127           are required to $dh_cb.
5128
5129           ??? (does this function really work?)
5130
5131            Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
5132            # $ssl - value corresponding to openssl's SSL structure
5133            # $dh_cb - pointer to function ???
5134            #
5135            # returns: no return value
5136
5137           Check openssl doc
5138           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
5139
5140       ·   set_tmp_rsa
5141
5142           Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
5143
5144            my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
5145            # $ssl - value corresponding to openssl's SSL structure
5146            # $rsa - value corresponding to openssl's RSA structure
5147            #
5148            # returns: 1 on success, 0 on failure
5149
5150           Example:
5151
5152            $rsakey = Net::SSLeay::RSA_generate_key();
5153            Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
5154            Net::SSLeay::RSA_free($rsakey);
5155
5156           Check openssl doc
5157           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5158
5159       ·   set_tmp_rsa_callback
5160
5161           Sets the callback function for $ssl to be used when a
5162           temporary/ephemeral RSA key is required to $tmp_rsa_callback.
5163
5164           ??? (does this function really work?)
5165
5166            Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
5167            # $ssl - value corresponding to openssl's SSL structure
5168            # $tmp_rsa_callback - (function pointer) ???
5169            #
5170            # returns: no return value
5171
5172           Check openssl doc
5173           <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
5174
5175       ·   set_trust
5176
5177            my $rv = Net::SSLeay::set_trust($ssl, $trust);
5178            # $ssl - value corresponding to openssl's SSL structure
5179            # $trust - (integer) trust identifier
5180            #
5181            # returns: the original value
5182
5183           For more details about $trust values see "CTX_set_trust".
5184
5185       ·   shutdown
5186
5187           Shuts down an active TLS/SSL connection. It sends the 'close
5188           notify' shutdown alert to the peer.
5189
5190            my $rv = Net::SSLeay::shutdown($ssl);
5191            # $ssl - value corresponding to openssl's SSL structure
5192            #
5193            # returns: 1 - shutdown was successfully completed
5194            #          0 - shutdown is not yet finished,
5195            #         -1 - shutdown was not successful
5196
5197           Check openssl doc
5198           <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
5199
5200       ·   state_string
5201
5202           Returns a 6 letter string indicating the current state of the SSL
5203           object $ssl.
5204
5205            my $rv = Net::SSLeay::state_string($ssl);
5206            # $ssl - value corresponding to openssl's SSL structure
5207            #
5208            # returns: 6-letter string
5209
5210           Check openssl doc
5211           <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5212
5213       ·   state_string_long
5214
5215           Returns a string indicating the current state of the SSL object
5216           $ssl.
5217
5218            my $rv = Net::SSLeay::state_string_long($ssl);
5219            # $ssl - value corresponding to openssl's SSL structure
5220            #
5221            # returns: state strings
5222
5223           Check openssl doc
5224           <http://www.openssl.org/docs/ssl/SSL_state_string.html>
5225
5226       ·   set_default_passwd_cb
5227
5228           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5229           requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5230
5231           Sets the default password callback called when loading/storing a
5232           PEM certificate with encryption for $ssl.
5233
5234            Net::SSLeay::set_default_passwd_cb($ssl, $func);
5235            # $ssl - value corresponding to openssl's SSL structure
5236            # $func - perl reference to callback function
5237            #
5238            # returns: no return value
5239
5240           Check openssl doc
5241           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5242
5243       ·   set_default_passwd_cb_userdata
5244
5245           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5246           requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
5247
5248           Sets a pointer to userdata which will be provided to the password
5249           callback of $ssl on invocation.
5250
5251            Net::SSLeay::set_default_passwd_cb_userdata($ssl, $userdata);
5252            # $ssl - value corresponding to openssl's SSL structure
5253            # $userdata - data that will be passed to callback function when invoked
5254            #
5255            # returns: no return value
5256
5257           Check openssl doc
5258           <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
5259
5260       ·   use_PrivateKey
5261
5262           Adds $pkey as private key to $ssl.
5263
5264            my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
5265            # $ssl - value corresponding to openssl's SSL structure
5266            # $pkey - value corresponding to openssl's EVP_PKEY structure
5267            #
5268            # returns: 1 on success, otherwise check out the error stack to find out the reason
5269
5270           Check openssl doc
5271           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5272
5273       ·   use_PrivateKey_ASN1
5274
5275           Adds the private key of type $pk stored in $data to $ssl.
5276
5277            my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
5278            # $pk - (integer) key type, NID of corresponding algorithm
5279            # $ssl - value corresponding to openssl's SSL structure
5280            # $data - key data (binary)
5281            # $len - length of $data
5282            #
5283            # returns: 1 on success, otherwise check out the error stack to find out the reason
5284
5285           Check openssl doc
5286           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5287
5288       ·   use_PrivateKey_file
5289
5290           Adds the first private key found in $file to $ssl.
5291
5292            my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
5293            # $ssl - value corresponding to openssl's SSL structure
5294            # $file - (string) file name
5295            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5296            #
5297            # returns: 1 on success, otherwise check out the error stack to find out the reason
5298
5299           Check openssl doc
5300           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5301
5302       ·   use_RSAPrivateKey
5303
5304           Adds $rsa as RSA private key to $ssl.
5305
5306            my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
5307            # $ssl - value corresponding to openssl's SSL structure
5308            # $rsa - value corresponding to openssl's RSA structure
5309            #
5310            # returns: 1 on success, otherwise check out the error stack to find out the reason
5311
5312           Check openssl doc
5313           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5314
5315       ·   use_RSAPrivateKey_ASN1
5316
5317           Adds RSA private key stored in $data to $ssl.
5318
5319            my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
5320            # $ssl - value corresponding to openssl's SSL structure
5321            # $data - key data (binary)
5322            # $len - length of $data
5323            #
5324            # returns: 1 on success, otherwise check out the error stack to find out the reason
5325
5326           Check openssl doc
5327           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5328
5329       ·   use_RSAPrivateKey_file
5330
5331           Adds the first RSA private key found in $file to $ssl.
5332
5333            my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
5334            # $ssl - value corresponding to openssl's SSL structure
5335            # $file - (string) file name
5336            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5337            #
5338            # returns: 1 on success, otherwise check out the error stack to find out the reason
5339
5340           Check openssl doc
5341           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5342
5343       ·   use_certificate
5344
5345           Loads the certificate $x into $ssl.
5346
5347            my $rv = Net::SSLeay::use_certificate($ssl, $x);
5348            # $ssl - value corresponding to openssl's SSL structure
5349            # $x - value corresponding to openssl's X509 structure
5350            #
5351            # returns: 1 on success, otherwise check out the error stack to find out the reason
5352
5353           Check openssl doc
5354           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5355
5356       ·   use_certificate_ASN1
5357
5358           Loads the ASN1 encoded certificate from $data to $ssl.
5359
5360            my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
5361            # $ssl - value corresponding to openssl's SSL structure
5362            # $data - certificate data (binary)
5363            # $len - length of $data
5364            #
5365            # returns: 1 on success, otherwise check out the error stack to find out the reason
5366
5367           Check openssl doc
5368           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5369
5370       ·   use_certificate_chain_file
5371
5372           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5373           requires at least OpenSSL 1.1.0
5374
5375           Loads a certificate chain from $file into $ssl. The certificates
5376           must be in PEM format and must be sorted starting with the
5377           subject's certificate (actual client or server certificate),
5378           followed by intermediate CA certificates if applicable, and ending
5379           at the highest level (root) CA.
5380
5381            my $rv = Net::SSLeay::use_certificate_chain_file($ssl, $file);
5382            # $ssl - value corresponding to openssl's SSL structure
5383            # $file - (string) file name
5384            #
5385            # returns: 1 on success, otherwise check out the error stack to find out the reason
5386
5387           Check openssl doc
5388           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5389
5390       ·   use_certificate_file
5391
5392           Loads the first certificate stored in $file into $ssl.
5393
5394            my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
5395            # $ssl - value corresponding to openssl's SSL structure
5396            # $file - (string) file name
5397            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5398            #
5399            # returns: 1 on success, otherwise check out the error stack to find out the reason
5400
5401           Check openssl doc
5402           <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5403
5404       ·   get_version
5405
5406           Returns SSL/TLS protocol name
5407
5408            my $rv = Net::SSLeay::get_version($ssl);
5409            # $ssl - value corresponding to openssl's SSL structure
5410            #
5411            # returns: (string) protocol name, see OpenSSL manual for the full list
5412            #          TLSv1
5413            #          TLSv1.3
5414
5415           Check openssl doc
5416           <https://www.openssl.org/docs/manmaster/man3/SSL_get_version.html>
5417
5418       ·   version
5419
5420           Returns SSL/TLS protocol version
5421
5422            my $rv = Net::SSLeay::version($ssl);
5423            # $ssl - value corresponding to openssl's SSL structure
5424            #
5425            # returns: (integer) protocol version, see OpenSSL manual for the full list
5426            #          0x0301 - TLS1_VERSION  (TLSv1)
5427            #          0xFEFF - DTLS1_VERSION (DTLSv1)
5428
5429           Check openssl doc
5430           <https://www.openssl.org/docs/manmaster/man3/SSL_version.html>
5431
5432       ·   client_version
5433
5434           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5435           requires at least OpenSSL 1.1.0, not in LibreSSL
5436
5437           Returns TLS protocol version used by the client when initiating the
5438           connection
5439
5440            my $rv = Net::SSLeay::client_version($ssl);
5441            # $ssl - value corresponding to openssl's SSL structure
5442            #
5443            # returns: (integer) protocol version, see OpenSSL manual for the full list
5444            #          0x0301 - TLS1_VERSION  (TLSv1)
5445            #          0xFEFF - DTLS1_VERSION (DTLSv1)
5446
5447           Check openssl doc
5448           <https://www.openssl.org/docs/manmaster/man3/SSL_client_version.html>
5449
5450       ·   is_dtls
5451
5452           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5453           requires at least OpenSSL 1.1.0, not in LibreSSL
5454
5455            my $rv = Net::SSLeay::is_dtls($ssl);
5456            # $ssl - value corresponding to openssl's SSL structure
5457            #
5458            # returns: (integer) zero or one
5459            #          0 - connection is not using DTLS
5460            #          1 - connection is using DTLS
5461
5462           Check openssl doc
5463           <https://www.openssl.org/docs/manmaster/man3/SSL_is_dtls.html>
5464
5465       ·   want
5466
5467           Returns state information for the SSL object $ssl.
5468
5469            my $rv = Net::SSLeay::want($ssl);
5470            # $ssl - value corresponding to openssl's SSL structure
5471            #
5472            # returns: state
5473            #          1 - SSL_NOTHING
5474            #          2 - SSL_WRITING
5475            #          3 - SSL_READING
5476            #          4 - SSL_X509_LOOKUP
5477
5478           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5479
5480       ·   write
5481
5482           Writes data from the buffer $data into the specified $ssl
5483           connection.
5484
5485            my $rv = Net::SSLeay::write($ssl, $data);
5486            # $ssl - value corresponding to openssl's SSL structure
5487            # $data - data to be written
5488            #
5489            # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5490            #           0 - write not successful, probably the underlying connection was closed
5491            #          <0 - error
5492
5493           Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5494
5495       ·   write_ex
5496
5497           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5498           requires at least OpenSSL 1.1.1, not in LibreSSL
5499
5500           Writes data from the buffer $data into the specified $ssl
5501           connection.
5502
5503            my ($len, $rv) = Net::SSLeay::write_ex($ssl, $data);
5504            # $ssl - value corresponding to openssl's SSL structure
5505            # $data - data to be written
5506            #
5507            # returns a list: two-item list consisting of number of bytes written,
5508            #                 and return code from SSL_write_ex()
5509
5510           Check openssl doc
5511           <https://www.openssl.org/docs/manmaster/man3/SSL_write_ex.html>
5512
5513       ·   write_partial
5514
5515           NOTE: Does not exactly correspond to any low level API function
5516
5517           Writes a fragment of data in $data from the buffer $data into the
5518           specified $ssl connection. This is a non-blocking function like
5519           Net::SSLeay::write().
5520
5521            my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
5522            # $ssl - value corresponding to openssl's SSL structure
5523            # $from - (integer) offset from the beginning of $data
5524            # $count - (integer) length of data to be written
5525            # $data - data buffer
5526            #
5527            # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5528            #           0 - write not successful, probably the underlying connection was closed
5529            #          <0 - error
5530
5531       ·   set_tlsext_host_name
5532
5533           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5534           requires at least openssl-0.9.8f
5535
5536           Sets TLS servername extension on SLL object $ssl to value $name.
5537
5538            my $rv = set_tlsext_host_name($ssl, $name);
5539            # $ssl - value corresponding to openssl's SSL structure
5540            # $name - (string) name to be set
5541            #
5542            # returns: 1 on success, 0 on failure
5543
5544       Low level API: RAND_* related functions
5545
5546       Check openssl doc related to RAND stuff
5547       <http://www.openssl.org/docs/crypto/rand.html>
5548
5549       ·   RAND_add
5550
5551           Mixes the $num bytes at $buf into the PRNG state.
5552
5553            Net::SSLeay::RAND_add($buf, $num, $entropy);
5554            # $buf - buffer with data to be mixed into the PRNG state
5555            # $num - number of bytes in $buf
5556            # $entropy - estimate of how much randomness is contained in $buf (in bytes)
5557            #
5558            # returns: no return value
5559
5560           Check openssl doc
5561           <http://www.openssl.org/docs/crypto/RAND_add.html>
5562
5563       ·   RAND_seed
5564
5565           Equivalent to "RAND_add" when $num == $entropy.
5566
5567            Net::SSLeay::RAND_seed($buf);   # Perlishly figures out buf size
5568            # $buf - buffer with data to be mixed into the PRNG state
5569            # $num - number of bytes in $buf
5570            #
5571            # returns: no return value
5572
5573           Check openssl doc
5574           <http://www.openssl.org/docs/crypto/RAND_add.html>
5575
5576       ·   RAND_status
5577
5578           Gives PRNG status (seeded enough or not).
5579
5580            my $rv = Net::SSLeay::RAND_status();
5581            #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5582
5583           Check openssl doc
5584           <http://www.openssl.org/docs/crypto/RAND_add.html>
5585
5586       ·   RAND_bytes
5587
5588           Puts $num cryptographically strong pseudo-random bytes into $buf.
5589
5590            my $rv = Net::SSLeay::RAND_bytes($buf, $num);
5591            # $buf - buffer where the random data will be stored
5592            # $num - the size (in bytes) of requested random data
5593            #
5594            # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5595
5596           Check openssl doc
5597           <http://www.openssl.org/docs/manmaster/man3/RAND_bytes.html>
5598
5599       ·   RAND_priv_bytes
5600
5601           COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
5602           requires at least OpenSSL 1.1.1, not in LibreSSL
5603
5604           Puts $num cryptographically strong pseudo-random bytes into $buf.
5605
5606            my $rv = Net::SSLeay::RAND_priv_bytes($buf, $num);
5607            # $buf - buffer where the random data will be stored
5608            # $num - the size (in bytes) of requested random data
5609            #
5610            # returns: 1 on success, -1 if not supported by the current RAND method, or 0 on other failure
5611
5612           RAND_priv_bytes has the same semantics as RAND_bytes, but see see
5613           the documentation for more information.
5614
5615           Check openssl doc
5616           <http://www.openssl.org/docs/manmaster/man3/RAND_priv_bytes.html>
5617
5618       ·   RAND_pseudo_bytes
5619
5620           Puts $num pseudo-random (not necessarily unpredictable) bytes into
5621           $buf.
5622
5623            my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
5624            # $buf - buffer where the random data will be stored
5625            # $num - the size (in bytes) of requested random data
5626            #
5627            # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
5628
5629           Check openssl doc
5630           <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5631
5632       ·   RAND_cleanup
5633
5634           Erase the PRNG state.
5635
5636            Net::SSLeay::RAND_cleanup();
5637            # no args, no return value
5638
5639           Check openssl doc
5640           <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5641
5642       ·   RAND_egd_bytes
5643
5644           Queries the entropy gathering daemon EGD on socket $path for $bytes
5645           bytes.
5646
5647            my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
5648            # $path - path to a socket of entropy gathering daemon EGD
5649            # $bytes - number of bytes we want from EGD
5650            #
5651            # returns: the number of bytes read from the daemon on success, and -1 on failure
5652
5653           Check openssl doc
5654           <http://www.openssl.org/docs/crypto/RAND_egd.html>
5655
5656       ·   RAND_file_name
5657
5658           Generates a default path for the random seed file.
5659
5660            my $file = Net::SSLeay::RAND_file_name($num);
5661            # $num - maximum size of returned file name
5662            #
5663            # returns: string with file name on success, '' (empty string) on failure
5664
5665           Check openssl doc
5666           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5667
5668       ·   RAND_load_file
5669
5670           COMPATIBILITY: Is no longer functional on LibreSSL
5671
5672           Reads $max_bytes of bytes from $file_name and adds them to the
5673           PRNG.
5674
5675            my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
5676            # $file_name - the name of file
5677            # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
5678            #
5679            # returns: the number of bytes read
5680
5681           Check openssl doc
5682           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5683
5684       ·   RAND_write_file
5685
5686           Writes 1024 random bytes to $file_name which can be used to
5687           initialize the PRNG by calling "RAND_load_file" in a later session.
5688
5689            my $rv = Net::SSLeay::RAND_write_file($file_name);
5690            # $file_name - the name of file
5691            #
5692            # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
5693
5694           Check openssl doc
5695           <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5696
5697       ·   RAND_poll
5698
5699           Collects some entropy from operating system and adds it to the
5700           PRNG.
5701
5702            my $rv = Net::SSLeay::RAND_poll();
5703            # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5704
5705       Low level API: OBJ_* related functions
5706
5707       ·   OBJ_cmp
5708
5709           Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5710
5711            my $rv = Net::SSLeay::OBJ_cmp($a, $b);
5712            # $a - value corresponding to openssl's ASN1_OBJECT structure
5713            # $b - value corresponding to openssl's ASN1_OBJECT structure
5714            #
5715            # returns: if the two are identical 0 is returned
5716
5717           Check openssl doc
5718           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5719
5720       ·   OBJ_dup
5721
5722           Returns a copy/duplicate of $o.
5723
5724            my $rv = Net::SSLeay::OBJ_dup($o);
5725            # $o - value corresponding to openssl's ASN1_OBJECT structure
5726            #
5727            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5728
5729           Check openssl doc
5730           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5731
5732       ·   OBJ_nid2ln
5733
5734           Returns long name for given NID $n.
5735
5736            my $rv = Net::SSLeay::OBJ_nid2ln($n);
5737            # $n - (integer) NID
5738            #
5739            # returns: (string) long name e.g. 'commonName'
5740
5741           Check openssl doc
5742           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5743
5744       ·   OBJ_ln2nid
5745
5746           Returns NID corresponding to given long name $n.
5747
5748            my $rv = Net::SSLeay::OBJ_ln2nid($s);
5749            # $s - (string) long name e.g. 'commonName'
5750            #
5751            # returns: (integer) NID
5752
5753       ·   OBJ_nid2sn
5754
5755           Returns short name for given NID $n.
5756
5757            my $rv = Net::SSLeay::OBJ_nid2sn($n);
5758            # $n - (integer) NID
5759            #
5760            # returns: (string) short name e.g. 'CN'
5761
5762           Example:
5763
5764            print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
5765
5766       ·   OBJ_sn2nid
5767
5768           Returns NID corresponding to given short name $s.
5769
5770            my $rv = Net::SSLeay::OBJ_sn2nid($s);
5771            # $s - (string) short name e.g. 'CN'
5772            #
5773            # returns: (integer) NID
5774
5775           Example:
5776
5777            print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
5778            print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
5779
5780       ·   OBJ_nid2obj
5781
5782           Returns ASN1_OBJECT for given NID $n.
5783
5784            my $rv = Net::SSLeay::OBJ_nid2obj($n);
5785            # $n - (integer) NID
5786            #
5787            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5788
5789           Check openssl doc
5790           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5791
5792       ·   OBJ_obj2nid
5793
5794           Returns NID corresponding to given ASN1_OBJECT $o.
5795
5796            my $rv = Net::SSLeay::OBJ_obj2nid($o);
5797            # $o - value corresponding to openssl's ASN1_OBJECT structure
5798            #
5799            # returns: (integer) NID
5800
5801           Check openssl doc
5802           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5803
5804       ·   OBJ_txt2obj
5805
5806           Converts the text string s into an ASN1_OBJECT structure. If
5807           $no_name is 0 then long names (e.g. 'commonName') and short names
5808           (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
5809           '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
5810
5811            my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
5812            # $s - text string to be converted
5813            # $no_name - (integer) 0 or 1
5814            #
5815            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5816
5817           Check openssl doc
5818           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5819
5820       ·   OBJ_obj2txt
5821
5822           Converts the ASN1_OBJECT a into a textual representation.
5823
5824            Net::SSLeay::OBJ_obj2txt($a, $no_name);
5825            # $a - value corresponding to openssl's ASN1_OBJECT structure
5826            # $no_name - (integer) 0 or 1
5827            #
5828            # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
5829
5830           Check openssl doc
5831           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5832
5833       ·   OBJ_txt2nid
5834
5835           Returns NID corresponding to text string $s which can be a long
5836           name, a short name or the numerical representation of an object.
5837
5838            my $rv = Net::SSLeay::OBJ_txt2nid($s);
5839            # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
5840            #
5841            # returns: (integer) NID
5842
5843           Example:
5844
5845            my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
5846            Net::SSLeay::OBJ_nid2sn($n);
5847
5848           Check openssl doc
5849           <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5850
5851       Low level API: ASN1_INTEGER_* related functions
5852
5853       ·   ASN1_INTEGER_new
5854
5855           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5856
5857           Creates a new ASN1_INTEGER structure.
5858
5859            my $rv = Net::SSLeay::ASN1_INTEGER_new();
5860            #
5861            # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
5862
5863       ·   ASN1_INTEGER_free
5864
5865           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5866
5867           Free an allocated ASN1_INTEGER structure.
5868
5869            Net::SSLeay::ASN1_INTEGER_free($i);
5870            # $i - value corresponding to openssl's ASN1_INTEGER structure
5871            #
5872            # returns: no return value
5873
5874       ·   ASN1_INTEGER_get
5875
5876           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5877
5878           Returns integer value of given ASN1_INTEGER object.
5879
5880           BEWARE: If the value stored in ASN1_INTEGER is greater than max.
5881           integer that can be stored in 'long' type (usually 32bit but may
5882           vary according to platform) then this function will return -1.  For
5883           getting large ASN1_INTEGER values consider using
5884           "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
5885
5886            my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
5887            # $a - value corresponding to openssl's ASN1_INTEGER structure
5888            #
5889            # returns: integer value of ASN1_INTEGER object in $a
5890
5891       ·   ASN1_INTEGER_set
5892
5893           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5894
5895           Sets value of given ASN1_INTEGER object to value $val
5896
5897           BEWARE: $val has max. limit (= max. integer that can be stored in
5898           'long' type).  For setting large ASN1_INTEGER values consider using
5899           "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
5900
5901            my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
5902            # $i - value corresponding to openssl's ASN1_INTEGER structure
5903            # $val - integer value
5904            #
5905            # returns: 1 on success, 0 on failure
5906
5907       ·   P_ASN1_INTEGER_get_dec
5908
5909           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5910
5911           Returns string with decimal representation of integer value of
5912           given ASN1_INTEGER object.
5913
5914            Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
5915            # $i - value corresponding to openssl's ASN1_INTEGER structure
5916            #
5917            # returns: string with decimal representation
5918
5919       ·   P_ASN1_INTEGER_get_hex
5920
5921           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5922
5923           Returns string with hexadecimal representation of integer value of
5924           given ASN1_INTEGER object.
5925
5926            Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
5927            # $i - value corresponding to openssl's ASN1_INTEGER structure
5928            #
5929            # returns: string with hexadecimal representation
5930
5931       ·   P_ASN1_INTEGER_set_dec
5932
5933           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5934
5935           Sets value of given ASN1_INTEGER object to value $val (decimal
5936           string, suitable for large integers)
5937
5938            Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
5939            # $i - value corresponding to openssl's ASN1_INTEGER structure
5940            # $str - string with decimal representation
5941            #
5942            # returns: 1 on success, 0 on failure
5943
5944       ·   P_ASN1_INTEGER_set_hex
5945
5946           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5947
5948           Sets value of given ASN1_INTEGER object to value $val (hexadecimal
5949           string, suitable for large integers)
5950
5951            Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
5952            # $i - value corresponding to openssl's ASN1_INTEGER structure
5953            # $str - string with hexadecimal representation
5954            #
5955            # returns: 1 on success, 0 on failure
5956
5957       Low level API: ASN1_STRING_* related functions
5958
5959       ·   P_ASN1_STRING_get
5960
5961           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5962
5963           Returns string value of given ASN1_STRING object.
5964
5965            Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
5966            # $s - value corresponding to openssl's ASN1_STRING structure
5967            # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
5968            #
5969            # returns: string
5970
5971            $string = Net::SSLeay::P_ASN1_STRING_get($s);
5972            #is the same as:
5973            $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
5974
5975       Low level API: ASN1_TIME_* related functions
5976
5977       ·   ASN1_TIME_new
5978
5979           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5980
5981            my $time = ASN1_TIME_new();
5982            # returns: value corresponding to openssl's ASN1_TIME structure
5983
5984       ·   ASN1_TIME_free
5985
5986           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5987
5988            ASN1_TIME_free($time);
5989            # $time - value corresponding to openssl's ASN1_TIME structure
5990
5991       ·   ASN1_TIME_set
5992
5993           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5994
5995            ASN1_TIME_set($time, $t);
5996            # $time - value corresponding to openssl's ASN1_TIME structure
5997            # $t - time value in seconds since 1.1.1970
5998
5999           BEWARE: It is platform dependent how this function will handle
6000           dates after 2038.  Although perl's integer is large enough the
6001           internal implementation of this function is dependent on the size
6002           of time_t structure (32bit time_t has problem with 2038).
6003
6004           If you want to safely set date and time after 2038 use function
6005           "P_ASN1_TIME_set_isotime".
6006
6007       ·   P_ASN1_TIME_get_isotime
6008
6009           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6010           requires at least openssl-0.9.7e
6011
6012           NOTE: Does not exactly correspond to any low level API function
6013
6014           Gives ISO-8601 string representation of ASN1_TIME structure.
6015
6016            my $datetime_string = P_ASN1_TIME_get_isotime($time);
6017            # $time - value corresponding to openssl's ASN1_TIME structure
6018            #
6019            # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
6020
6021           The output format is compatible with module
6022           DateTime::Format::RFC3339
6023
6024       ·   P_ASN1_TIME_set_isotime
6025
6026           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
6027           requires at least openssl-0.9.7e
6028
6029           NOTE: Does not exactly correspond to any low level API function
6030
6031           Sets time and date value of ANS1_time structure.
6032
6033            my $rv = P_ASN1_TIME_set_isotime($time, $string);
6034            # $time - value corresponding to openssl's ASN1_TIME structure
6035            # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
6036            #
6037            # returns: 1 on success, 0 on failure
6038
6039           The $string parameter has to be in full form like
6040           "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
6041           "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
6042           "2012-03-22" are not supported.
6043
6044       ·   P_ASN1_TIME_put2string
6045
6046           COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
6047           bugs with openssl-0.9.8i
6048
6049           NOTE: Does not exactly correspond to any low level API function
6050
6051           Gives string representation of ASN1_TIME structure.
6052
6053            my $str = P_ASN1_TIME_put2string($time);
6054            # $time - value corresponding to openssl's ASN1_TIME structure
6055            #
6056            # returns: datetime string like 'May 16 20:39:37 2033 GMT'
6057
6058       ·   P_ASN1_UTCTIME_put2string
6059
6060           NOTE: deprecated function, only for backward compatibility, just an
6061           alias for "P_ASN1_TIME_put2string"
6062
6063       Low level API: X509_* related functions
6064
6065       ·   X509_new
6066
6067           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6068
6069           Allocates and initializes a X509 structure.
6070
6071            my $rv = Net::SSLeay::X509_new();
6072            #
6073            # returns: value corresponding to openssl's X509 structure (0 on failure)
6074
6075           Check openssl doc
6076           <http://www.openssl.org/docs/crypto/X509_new.html>
6077
6078       ·   X509_free
6079
6080           Frees up the X509 structure.
6081
6082            Net::SSLeay::X509_free($a);
6083            # $a - value corresponding to openssl's X509 structure
6084            #
6085            # returns: no return value
6086
6087           Check openssl doc
6088           <http://www.openssl.org/docs/crypto/X509_new.html>
6089
6090       ·   X509_check_host
6091
6092           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6093           requires at least OpenSSL 1.0.2.
6094           X509_CHECK_FLAG_NEVER_CHECK_SUBJECT requires OpenSSL 1.1.0.
6095
6096           Checks f the certificate Subject Alternative Name (SAN) or Subject
6097           CommonName (CN) matches the specified host name.
6098
6099            my $rv = Net::SSLeay::X509_check_host($cert, $name, $flags, $peername);
6100            # $cert - value corresponding to openssl's X509 structure
6101            # $name - host name to check
6102            # $flags (optional, default: 0) - can be the bitwise OR of:
6103            #   &Net::SSLeay::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
6104            #   &Net::SSLeay::X509_CHECK_FLAG_NO_WILDCARDS
6105            #   &Net::SSLeay::X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
6106            #   &Net::SSLeay::X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
6107            #   &Net::SSLeay::X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
6108            #   &Net::SSLeay::X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
6109            # $peername (optional) - If not omitted and $host matches $cert,
6110            #                        a copy of the matching SAN or CN from
6111            #                        the peer certificate is stored in $peername.
6112            #
6113            # returns:
6114            #   1 for a successful match
6115            #   0 for a failed match
6116            #  -1 for an internal error
6117            #  -2 if the input is malformed
6118
6119           Check openssl doc
6120           <https://www.openssl.org/docs/crypto/X509_check_host.html>.
6121
6122       ·   X509_check_email
6123
6124           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6125           requires at least OpenSSL 1.0.2.
6126
6127           Checks if the certificate matches the specified email address.
6128
6129            my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6130            # $cert - value corresponding to openssl's X509 structure
6131            # $address - email address to check
6132            # $flags (optional, default: 0) - see X509_check_host()
6133            #
6134            # returns: see X509_check_host()
6135
6136           Check openssl doc
6137           <https://www.openssl.org/docs/crypto/X509_check_email.html>.
6138
6139       ·   X509_check_ip
6140
6141           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6142           requires at least OpenSSL 1.0.2.
6143
6144           Checks if the certificate matches the specified IPv4 or IPv6
6145           address.
6146
6147            my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6148            # $cert - value corresponding to openssl's X509 structure
6149            # $address - IP address to check in binary format, in network byte order
6150            # $flags (optional, default: 0) - see X509_check_host()
6151            #
6152            # returns: see X509_check_host()
6153
6154           Check openssl doc
6155           <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
6156
6157       ·   X509_check_ip_asc
6158
6159           COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
6160           requires at least OpenSSL 1.0.2.
6161
6162           Checks if the certificate matches the specified IPv4 or IPv6
6163           address.
6164
6165            my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
6166            # $cert - value corresponding to openssl's X509 structure
6167            # $address - IP address to check in text representation
6168            # $flags (optional, default: 0) - see X509_check_host()
6169            #
6170            # returns: see X509_check_host()
6171
6172           Check openssl doc
6173           <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
6174
6175       ·   X509_certificate_type
6176
6177           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6178
6179           Returns bitmask with type of certificate $x.
6180
6181            my $rv = Net::SSLeay::X509_certificate_type($x);
6182            # $x - value corresponding to openssl's X509 structure
6183            #
6184            # returns: (integer) bitmask with certificate type
6185
6186            #to decode bitmask returned by this function use these constants:
6187            &Net::SSLeay::EVP_PKS_DSA
6188            &Net::SSLeay::EVP_PKS_EC
6189            &Net::SSLeay::EVP_PKS_RSA
6190            &Net::SSLeay::EVP_PKT_ENC
6191            &Net::SSLeay::EVP_PKT_EXCH
6192            &Net::SSLeay::EVP_PKT_EXP
6193            &Net::SSLeay::EVP_PKT_SIGN
6194            &Net::SSLeay::EVP_PK_DH
6195            &Net::SSLeay::EVP_PK_DSA
6196            &Net::SSLeay::EVP_PK_EC
6197            &Net::SSLeay::EVP_PK_RSA
6198
6199       ·   X509_digest
6200
6201           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6202
6203           Computes digest/fingerprint of X509 $data using $type hash
6204           function.
6205
6206            my $digest_value = Net::SSLeay::X509_digest($data, $type);
6207            # $data - value corresponding to openssl's X509 structure
6208            # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6209            #
6210            # returns: hash value (binary)
6211
6212            #to get printable (hex) value of digest use:
6213            print unpack('H*', $digest_value);
6214
6215       ·   X509_issuer_and_serial_hash
6216
6217           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6218
6219           Sort of a checksum of issuer name and serial number of X509
6220           certificate $x.  The result is not a full hash (e.g. sha-1), it is
6221           kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
6222           The resulting value might differ across different openssl versions
6223           for the same X509 certificate.
6224
6225            my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
6226            # $x - value corresponding to openssl's X509 structure
6227            #
6228            # returns: number representing checksum
6229
6230       ·   X509_issuer_name_hash
6231
6232           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6233
6234           Sort of a checksum of issuer name of X509 certificate $x.  The
6235           result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6236           truncated to the size of 'unsigned long' (32 bits).  The resulting
6237           value might differ across different openssl versions for the same
6238           X509 certificate.
6239
6240            my $rv = Net::SSLeay::X509_issuer_name_hash($x);
6241            # $x - value corresponding to openssl's X509 structure
6242            #
6243            # returns: number representing checksum
6244
6245       ·   X509_subject_name_hash
6246
6247           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6248
6249           Sort of a checksum of subject name of X509 certificate $x.  The
6250           result is not a full hash (e.g. sha-1), it is kind-of-a-hash
6251           truncated to the size of 'unsigned long' (32 bits).  The resulting
6252           value might differ across different openssl versions for the same
6253           X509 certificate.
6254
6255            my $rv = Net::SSLeay::X509_subject_name_hash($x);
6256            # $x - value corresponding to openssl's X509 structure
6257            #
6258            # returns: number representing checksum
6259
6260       ·   X509_pubkey_digest
6261
6262           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6263           requires at least openssl-0.9.7
6264
6265           Computes digest/fingerprint of public key from X509 certificate
6266           $data using $type hash function.
6267
6268            my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
6269            # $data - value corresponding to openssl's X509 structure
6270            # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6271            #
6272            # returns: hash value (binary)
6273
6274            #to get printable (hex) value of digest use:
6275            print unpack('H*', $digest_value);
6276
6277       ·   X509_set_issuer_name
6278
6279           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6280
6281           Sets issuer of X509 certificate $x to $name.
6282
6283            my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
6284            # $x - value corresponding to openssl's X509 structure
6285            # $name - value corresponding to openssl's X509_NAME structure
6286            #
6287            # returns: 1 on success, 0 on failure
6288
6289       ·   X509_set_pubkey
6290
6291           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6292
6293           Sets public key of X509 certificate $x to $pkey.
6294
6295            my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
6296            # $x - value corresponding to openssl's X509 structure
6297            # $pkey - value corresponding to openssl's EVP_PKEY structure
6298            #
6299            # returns: 1 on success, 0 on failure
6300
6301       ·   X509_set_serialNumber
6302
6303           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6304
6305           Sets serial number of X509 certificate $x to $serial.
6306
6307            my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
6308            # $x - value corresponding to openssl's X509 structure
6309            # $serial - value corresponding to openssl's ASN1_INTEGER structure
6310            #
6311            # returns: 1 on success, 0 on failure
6312
6313            #to create $serial value use one of these:
6314            $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
6315            $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
6316            $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
6317
6318       ·   X509_set_subject_name
6319
6320           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6321
6322           Sets subject of X509 certificate $x to $name.
6323
6324            my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
6325            # $x - value corresponding to openssl's X509 structure
6326            # $name - value corresponding to openssl's X509_NAME structure
6327            #
6328            # returns: 1 on success, 0 on failure
6329
6330       ·   X509_set_version
6331
6332           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6333
6334           Set 'version' value for X509 certificate $ to $version.
6335
6336            my $rv = Net::SSLeay::X509_set_version($x, $version);
6337            # $x - value corresponding to openssl's X509 structure
6338            # $version - (integer) version number
6339            #
6340            # returns: 1 on success, 0 on failure
6341
6342       ·   X509_sign
6343
6344           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6345
6346           Sign X509 certificate $x with private key $pkey (using digest
6347           algorithm $md).
6348
6349            my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
6350            # $x - value corresponding to openssl's X509 structure
6351            # $pkey - value corresponding to openssl's EVP_PKEY structure
6352            # $md - value corresponding to openssl's EVP_MD structure
6353            #
6354            # returns: 1 on success, 0 on failure
6355
6356       ·   X509_verify
6357
6358           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6359
6360           Verifies X509 object $a using public key $r (pubkey of issuing CA).
6361
6362            my $rv = Net::SSLeay::X509_verify($x, $r);
6363            # $x - value corresponding to openssl's X509 structure
6364            # $r - value corresponding to openssl's EVP_PKEY structure
6365            #
6366            # returns: 0 - verify failure, 1 - verify OK, <0 - error
6367
6368       ·   X509_get_ext_count
6369
6370           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6371
6372           Returns the total number of extensions in X509 object $x.
6373
6374            my $rv = Net::SSLeay::X509_get_ext_count($x);
6375            # $x - value corresponding to openssl's X509 structure
6376            #
6377            # returns: count of extensions
6378
6379       ·   X509_get_pubkey
6380
6381           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6382
6383           Returns public key corresponding to given X509 object $x.
6384
6385            my $rv = Net::SSLeay::X509_get_pubkey($x);
6386            # $x - value corresponding to openssl's X509 structure
6387            #
6388            # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6389
6390           NOTE: This method returns only the public key's key bits, without
6391           the algorithm or parameters.  Use "X509_get_X509_PUBKEY()" to
6392           return the full public key (SPKI) instead.
6393
6394       ·   X509_get_X509_PUBKEY
6395
6396           COMPATIBILITY: not available in Net-SSLeay-1.72 and before
6397
6398           Returns the full public key (SPKI) of given X509 certificate $x.
6399
6400            Net::SSLeay::X509_get_X509_PUBKEY($x);
6401            # $x - value corresponding to openssl's X509 structure
6402            #
6403            # returns: public key data in DER format (binary)
6404
6405       ·   X509_get_serialNumber
6406
6407           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6408
6409           Returns serial number of X509 certificate $x.
6410
6411            my $rv = Net::SSLeay::X509_get_serialNumber($x);
6412            # $x - value corresponding to openssl's X509 structure
6413            #
6414            # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6415
6416           See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
6417           "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
6418
6419       ·   X509_get0_serialNumber
6420
6421           COMPATIBILITY: available in Net-SSLeay-1.86 onwards
6422
6423           X509_get0_serialNumber() is the same as X509_get_serialNumber()
6424           except it accepts a const parameter and returns a const result.
6425
6426       ·   X509_get_version
6427
6428           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6429
6430           Returns 'version' value of given X509 certificate $x.
6431
6432            my $rv = Net::SSLeay::X509_get_version($x);
6433            # $x - value corresponding to openssl's X509 structure
6434            #
6435            # returns: (integer) version
6436
6437       ·   X509_get_ext
6438
6439           Returns X509_EXTENSION from $x509 based on given position/index.
6440
6441            my $rv = Net::SSLeay::X509_get_ext($x509, $index);
6442            # $x509 - value corresponding to openssl's X509 structure
6443            # $index - (integer) position/index of extension within $x509
6444            #
6445            # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6446
6447       ·   X509_get_ext_by_NID
6448
6449           Returns X509_EXTENSION from $x509 based on given NID.
6450
6451            my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
6452            # $x509 - value corresponding to openssl's X509 structure
6453            # $nid - (integer) NID value
6454            # $loc - (integer) position to start lookup at
6455            #
6456            # returns: position/index of extension, negative value on error
6457            #          call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
6458
6459       ·   X509_get_fingerprint
6460
6461           Returns fingerprint of certificate $cert.
6462
6463           NOTE: Does not exactly correspond to any low level API function.
6464           The implementation is basen on openssl's "X509_digest()".
6465
6466            Net::SSLeay::X509_get_fingerprint($x509, $type);
6467            # $x509 - value corresponding to openssl's X509 structure
6468            # $type - (string) digest type, currently supported values:
6469            #         "md5"
6470            #         "sha1"
6471            #         "sha256"
6472            #         "ripemd160"
6473            #
6474            # returns: certificate digest - hexadecimal string (NOT binary data!)
6475
6476       ·   X509_get_issuer_name
6477
6478           Return an X509_NAME object representing the issuer of the
6479           certificate $cert.
6480
6481            my $rv = Net::SSLeay::X509_get_issuer_name($cert);
6482            # $cert - value corresponding to openssl's X509 structure
6483            #
6484            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6485
6486       ·   X509_get_notAfter
6487
6488           Return an object giving the time after which the certificate $cert
6489           is not valid.
6490
6491            my $rv = Net::SSLeay::X509_get_notAfter($cert);
6492            # $cert - value corresponding to openssl's X509 structure
6493            #
6494            # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6495
6496           To get human readable/printable form the return value you can use:
6497
6498            my $time = Net::SSLeay::X509_get_notAfter($cert);
6499            print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6500
6501       ·   X509_get_notBefore
6502
6503           Return an object giving the time before which the certificate $cert
6504           is not valid
6505
6506            my $rv = Net::SSLeay::X509_get_notBefore($cert);
6507            # $cert - value corresponding to openssl's X509 structure
6508            #
6509            # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6510
6511           To get human readable/printable form the return value you can use:
6512
6513            my $time = Net::SSLeay::X509_get_notBefore($cert);
6514            print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6515
6516       ·   X509_get_subjectAltNames
6517
6518           NOTE: Does not exactly correspond to any low level API function.
6519
6520           Returns the list of alternative subject names from X509 certificate
6521           $cert.
6522
6523            my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
6524            # $cert - value corresponding to openssl's X509 structure
6525            #
6526            # returns: list containing pairs - name_type (integer), name_value (string)
6527            #          where name_type can be:
6528            #          0 - GEN_OTHERNAME
6529            #          1 - GEN_EMAIL
6530            #          2 - GEN_DNS
6531            #          3 - GEN_X400
6532            #          4 - GEN_DIRNAME
6533            #          5 - GEN_EDIPARTY
6534            #          6 - GEN_URI
6535            #          7 - GEN_IPADD
6536            #          8 - GEN_RID
6537
6538           Note: type 7 - GEN_IPADD contains the IP address as a packed binary
6539           address.
6540
6541       ·   X509_get_subject_name
6542
6543           Returns the subject of the certificate $cert.
6544
6545            my $rv = Net::SSLeay::X509_get_subject_name($cert);
6546            # $cert - value corresponding to openssl's X509 structure
6547            #
6548            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6549
6550       ·   X509_gmtime_adj
6551
6552           Adjust th ASN1_TIME object to the timestamp (in GMT).
6553
6554            my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
6555            # $s - value corresponding to openssl's ASN1_TIME structure
6556            # $adj - timestamp (seconds since 1.1.1970)
6557            #
6558            # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6559
6560           BEWARE: this function may fail for dates after 2038 as it is
6561           dependent on time_t size on your system (32bit time_t does not work
6562           after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
6563
6564       ·   X509_load_cert_crl_file
6565
6566           Takes PEM file and loads all X509 certificates and X509 CRLs from
6567           that file into X509_LOOKUP structure.
6568
6569            my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
6570            # $ctx - value corresponding to openssl's X509_LOOKUP structure
6571            # $file - (string) file name
6572            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6573            #                          if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
6574            #
6575            # returns: 1 on success, 0 on failure
6576
6577       ·   X509_load_cert_file
6578
6579           Loads/adds X509 certificate from $file to X509_LOOKUP structure
6580
6581            my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
6582            # $ctx - value corresponding to openssl's X509_LOOKUP structure
6583            # $file - (string) file name
6584            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6585            #
6586            # returns: 1 on success, 0 on failure
6587
6588       ·   X509_load_crl_file
6589
6590           Loads/adds X509 CRL from $file to X509_LOOKUP structure
6591
6592            my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
6593            # $ctx - value corresponding to openssl's X509_LOOKUP structure
6594            # $file - (string) file name
6595            # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6596            #
6597            # returns: 1 on success, 0 on failure
6598
6599       ·   X509_policy_level_get0_node
6600
6601           ??? (more info needed)
6602
6603            my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
6604            # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6605            # $i - (integer) index/position
6606            #
6607            # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6608
6609       ·   X509_policy_level_node_count
6610
6611           ??? (more info needed)
6612
6613            my $rv = Net::SSLeay::X509_policy_level_node_count($level);
6614            # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6615            #
6616            # returns: (integer) node count
6617
6618       ·   X509_policy_node_get0_parent
6619
6620           ??? (more info needed)
6621
6622            my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
6623            # $node - value corresponding to openssl's X509_POLICY_NODE structure
6624            #
6625            # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6626
6627       ·   X509_policy_node_get0_policy
6628
6629           ??? (more info needed)
6630
6631            my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
6632            # $node - value corresponding to openssl's X509_POLICY_NODE structure
6633            #
6634            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6635
6636       ·   X509_policy_node_get0_qualifiers
6637
6638           ??? (more info needed)
6639
6640            my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
6641            # $node - value corresponding to openssl's X509_POLICY_NODE structure
6642            #
6643            # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
6644
6645       ·   X509_policy_tree_free
6646
6647           ??? (more info needed)
6648
6649            Net::SSLeay::X509_policy_tree_free($tree);
6650            # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6651            #
6652            # returns: no return value
6653
6654       ·   X509_policy_tree_get0_level
6655
6656           ??? (more info needed)
6657
6658            my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
6659            # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6660            # $i - (integer) level index
6661            #
6662            # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
6663
6664       ·   X509_policy_tree_get0_policies
6665
6666           ??? (more info needed)
6667
6668            my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
6669            # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6670            #
6671            # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6672
6673       ·   X509_policy_tree_get0_user_policies
6674
6675           ??? (more info needed)
6676
6677            my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
6678            # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6679            #
6680            # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6681
6682       ·   X509_policy_tree_level_count
6683
6684           ??? (more info needed)
6685
6686            my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
6687            # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6688            #
6689            # returns: (integer) count
6690
6691       ·   X509_verify_cert_error_string
6692
6693           Returns a human readable error string for verification error $n.
6694
6695            my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6696            # $n - (long) numeric error code
6697            #
6698            # returns: error string
6699
6700           Check openssl doc
6701           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6702
6703       ·   P_X509_add_extensions
6704
6705           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6706
6707           Adds one or more X509 extensions to X509 object $x.
6708
6709            my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
6710            # $x - value corresponding to openssl's X509 structure
6711            # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
6712            # $nid - NID identifying extension to be set
6713            # $value - extension value
6714            #
6715            # returns: 1 on success, 0 on failure
6716
6717           You can set more extensions at once:
6718
6719            my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
6720                           &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6721                           &Net::SSLeay::NID_subject_key_identifier => 'hash',
6722                           &Net::SSLeay::NID_authority_key_identifier => 'keyid',
6723                           &Net::SSLeay::NID_authority_key_identifier => 'issuer',
6724                           &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6725                           &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6726                           &Net::SSLeay::NID_netscape_cert_type => 'server',
6727                           &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
6728                     );
6729
6730       ·   P_X509_copy_extensions
6731
6732           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6733
6734           Copies X509 extensions from X509_REQ object to X509 object - handy
6735           when you need to turn X509_REQ into X509 certificate.
6736
6737            Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
6738            # $x509_req - value corresponding to openssl's X509_REQ structure
6739            # $x509 - value corresponding to openssl's X509 structure
6740            # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
6741            #
6742            # returns: 1 on success, 0 on failure
6743
6744       ·   P_X509_get_crl_distribution_points
6745
6746           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6747           requires at least openssl-0.9.7
6748
6749           Get the list of CRL distribution points from X509 certificate.
6750
6751            my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
6752            # $x509 - value corresponding to openssl's X509 structure
6753            #
6754            # returns: list of distribution points (usually URLs)
6755
6756       ·   P_X509_get_ext_key_usage
6757
6758           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6759           requires at least openssl-0.9.7
6760
6761           Gets the list of extended key usage of given X509 certificate
6762           $cert.
6763
6764            my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
6765            # $cert - value corresponding to openssl's X509 structure
6766            # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
6767            #
6768            # returns: list of values
6769
6770           Examples:
6771
6772            my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
6773            # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
6774
6775            my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
6776            # returns for example: (129, 130)
6777
6778            my @extkeyusage_sn  = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
6779            # returns for example: ("serverAuth", "clientAuth")
6780
6781            my @extkeyusage_ln  = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
6782            # returns for example: ("TLS Web Server Authentication",  "TLS Web Client Authentication")
6783
6784       ·   P_X509_get_key_usage
6785
6786           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6787
6788           Gets the list of key usage of given X509 certificate $cert.
6789
6790            my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
6791            # $cert - value corresponding to openssl's X509 structure
6792            #
6793            # returns: list of key usage values which can be none, one or more from the following list:
6794            #          "digitalSignature"
6795            #          "nonRepudiation"
6796            #          "keyEncipherment"
6797            #          "dataEncipherment"
6798            #          "keyAgreement"
6799            #          "keyCertSign"
6800            #          "cRLSign"
6801            #          "encipherOnly"
6802            #          "decipherOnly"
6803
6804       ·   P_X509_get_netscape_cert_type
6805
6806           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6807
6808           Gets the list of Netscape cert types of given X509 certificate
6809           $cert.
6810
6811            Net::SSLeay::P_X509_get_netscape_cert_type($cert);
6812            # $cert - value corresponding to openssl's X509 structure
6813            #
6814            # returns: list of Netscape type values which can be none, one or more from the following list:
6815            #          "client"
6816            #          "server"
6817            #          "email"
6818            #          "objsign"
6819            #          "reserved"
6820            #          "sslCA"
6821            #          "emailCA"
6822            #          "objCA"
6823
6824       ·   P_X509_get_pubkey_alg
6825
6826           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6827
6828           Returns ASN1_OBJECT corresponding to X509 certificate public key
6829           algorithm.
6830
6831            my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
6832            # $x - value corresponding to openssl's X509 structure
6833            #
6834            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6835
6836           To get textual representation use:
6837
6838            my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
6839            # returns for example: "rsaEncryption"
6840
6841       ·   P_X509_get_signature_alg
6842
6843           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6844
6845           Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
6846
6847            my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
6848            # $x - value corresponding to openssl's X509 structure
6849            #
6850            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6851
6852           To get textual representation use:
6853
6854            my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
6855            # returns for example: "sha1WithRSAEncryption"
6856
6857       ·   sk_X509_new_null
6858
6859           Returns a new, empty, STACK_OF(X509) structure.
6860
6861            my $rv = Net::SSLeay::sk_X509_new_null();
6862            #
6863            # returns: value corresponding to openssl's STACK_OF(X509) structure
6864
6865       ·   sk_X509_push
6866
6867           Pushes an X509 structure onto a STACK_OF(X509) structure.
6868
6869            my $rv = Net::SSLeay::sk_X509_push($sk_x509, $x509);
6870            # $sk_x509 - value corresponding to openssl's STACK_OF(X509) structure
6871            # $x509 - value corresponding to openssl's X509 structure
6872            #
6873            # returns: 1 if successful, 0 if unsuccessful
6874
6875       Low level API: X509_REQ_* related functions
6876
6877       ·   X509_REQ_new
6878
6879           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6880
6881           Creates a new X509_REQ structure.
6882
6883            my $rv = Net::SSLeay::X509_REQ_new();
6884            #
6885            # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
6886
6887       ·   X509_REQ_free
6888
6889           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6890
6891           Free an allocated X509_REQ structure.
6892
6893            Net::SSLeay::X509_REQ_free($x);
6894            # $x - value corresponding to openssl's X509_REQ structure
6895            #
6896            # returns: no return value
6897
6898       ·   X509_REQ_add1_attr_by_NID
6899
6900           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6901
6902           Adds an attribute whose name is defined by a NID $nid. The field
6903           value to be added is in $bytes.
6904
6905            my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
6906            # $req - value corresponding to openssl's X509_REQ structure
6907            # $nid - (integer) NID value
6908            # $type - (integer) type of data in $bytes (see below)
6909            # $bytes - data to be set
6910            #
6911            # returns: 1 on success, 0 on failure
6912
6913            # values for $type - use constants:
6914            &Net::SSLeay::MBSTRING_UTF8     - $bytes contains utf8 encoded data
6915            &Net::SSLeay::MBSTRING_ASC      - $bytes contains ASCII data
6916
6917       ·   X509_REQ_digest
6918
6919           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6920
6921           Computes digest/fingerprint of X509_REQ $data using $type hash
6922           function.
6923
6924            my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
6925            # $data - value corresponding to openssl's X509_REQ structure
6926            # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6927            #
6928            # returns: hash value (binary)
6929
6930            #to get printable (hex) value of digest use:
6931            print unpack('H*', $digest_value);
6932
6933       ·   X509_REQ_get_attr_by_NID
6934
6935           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6936
6937           Retrieve the next index matching $nid after $lastpos ($lastpos
6938           should initially be set to -1).
6939
6940            my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
6941            # $req - value corresponding to openssl's X509_REQ structure
6942            # $nid - (integer) NID value
6943            # $lastpos - [optional] (integer) index where to start search (default -1)
6944            #
6945            # returns: index (-1 if there are no more entries)
6946
6947           Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6948           e.g.
6949
6950            my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6951            my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6952
6953       ·   X509_REQ_get_attr_by_OBJ
6954
6955           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6956
6957           Retrieve the next index matching $obj after $lastpos ($lastpos
6958           should initially be set to -1).
6959
6960            my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
6961            # $req - value corresponding to openssl's X509_REQ structure
6962            # $obj - value corresponding to openssl's ASN1_OBJECT structure
6963            # $lastpos - [optional] (integer) index where to start search (default -1)
6964            #
6965            # returns: index (-1 if there are no more entries)
6966
6967           Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6968           e.g.
6969
6970            my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6971            my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6972
6973       ·   X509_REQ_get_attr_count
6974
6975           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6976
6977           Returns the total number of attributes in $req.
6978
6979            my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
6980            # $req - value corresponding to openssl's X509_REQ structure
6981            #
6982            # returns: (integer) items count
6983
6984       ·   X509_REQ_get_pubkey
6985
6986           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6987
6988           Returns public key corresponding to given X509_REQ object $x.
6989
6990            my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
6991            # $x - value corresponding to openssl's X509_REQ structure
6992            #
6993            # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6994
6995       ·   X509_REQ_get_subject_name
6996
6997           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6998
6999           Returns X509_NAME object corresponding to subject name of given
7000           X509_REQ object $x.
7001
7002            my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
7003            # $x - value corresponding to openssl's X509_REQ structure
7004            #
7005            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7006
7007       ·   X509_REQ_get_version
7008
7009           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7010
7011           Returns 'version' value for given X509_REQ object $x.
7012
7013            my $rv = Net::SSLeay::X509_REQ_get_version($x);
7014            # $x - value corresponding to openssl's X509_REQ structure
7015            #
7016            # returns: (integer) version e.g. 0 = "version 1"
7017
7018       ·   X509_REQ_set_pubkey
7019
7020           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7021
7022           Sets public key of given X509_REQ object $x to $pkey.
7023
7024            my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
7025            # $x - value corresponding to openssl's X509_REQ structure
7026            # $pkey - value corresponding to openssl's EVP_PKEY structure
7027            #
7028            # returns: 1 on success, 0 on failure
7029
7030       ·   X509_REQ_set_subject_name
7031
7032           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7033
7034           Sets subject name of given X509_REQ object $x to X509_NAME object
7035           $name.
7036
7037            my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
7038            # $x - value corresponding to openssl's X509_REQ structure
7039            # $name - value corresponding to openssl's X509_NAME structure
7040            #
7041            # returns: 1 on success, 0 on failure
7042
7043       ·   X509_REQ_set_version
7044
7045           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7046
7047           Sets 'version' of given X509_REQ object $x to $version.
7048
7049            my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
7050            # $x - value corresponding to openssl's X509_REQ structure
7051            # $version - (integer) e.g. 0 = "version 1"
7052            #
7053            # returns: 1 on success, 0 on failure
7054
7055       ·   X509_REQ_sign
7056
7057           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7058
7059           Sign X509_REQ object $x with private key $pk (using digest
7060           algorithm $md).
7061
7062            my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
7063            # $x - value corresponding to openssl's X509_REQ structure
7064            # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
7065            # $md - value corresponding to openssl's EVP_MD structure
7066            #
7067            # returns: 1 on success, 0 on failure
7068
7069       ·   X509_REQ_verify
7070
7071           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7072
7073           Verifies X509_REQ object $x using public key $r (pubkey of
7074           requesting party).
7075
7076            my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
7077            # $x - value corresponding to openssl's X509_REQ structure
7078            # $r - value corresponding to openssl's EVP_PKEY structure
7079            #
7080            # returns: 0 - verify failure, 1 - verify OK, <0 - error
7081
7082       ·   P_X509_REQ_add_extensions
7083
7084           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7085
7086           Adds one or more X509 extensions to X509_REQ object $x.
7087
7088            my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
7089            # $x - value corresponding to openssl's X509_REQ structure
7090            # $nid - NID identifying extension to be set
7091            # $value - extension value
7092            #
7093            # returns: 1 on success, 0 on failure
7094
7095           You can set more extensions at once:
7096
7097            my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
7098                       &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
7099                       &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
7100                       &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
7101                       &Net::SSLeay::NID_netscape_cert_type => 'server',
7102                       &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
7103                       &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
7104                     );
7105
7106       ·   P_X509_REQ_get_attr
7107
7108           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7109           requires at least openssl-0.9.7
7110
7111           Returns attribute value for X509_REQ's attribute at index $n.
7112
7113            Net::SSLeay::P_X509_REQ_get_attr($req, $n);
7114            # $req - value corresponding to openssl's X509_REQ structure
7115            # $n - (integer) attribute index
7116            #
7117            # returns: value corresponding to openssl's ASN1_STRING structure
7118
7119       Low level API: X509_CRL_* related functions
7120
7121       ·   X509_CRL_new
7122
7123           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7124
7125           Creates a new X509_CRL structure.
7126
7127            my $rv = Net::SSLeay::X509_CRL_new();
7128            #
7129            # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
7130
7131       ·   X509_CRL_free
7132
7133           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7134
7135           Free an allocated X509_CRL structure.
7136
7137            Net::SSLeay::X509_CRL_free($x);
7138            # $x - value corresponding to openssl's X509_CRL structure
7139            #
7140            # returns: no return value
7141
7142       ·   X509_CRL_digest
7143
7144           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7145
7146           Computes digest/fingerprint of X509_CRL $data using $type hash
7147           function.
7148
7149            my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
7150            # $data - value corresponding to openssl's X509_CRL structure
7151            # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7152            #
7153            # returns: hash value (binary)
7154
7155           Example:
7156
7157            my $x509_crl
7158            my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7159            my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
7160            #to get printable (hex) value of digest use:
7161            print "digest=", unpack('H*', $digest_value), "\n";
7162
7163       ·   X509_CRL_get_ext
7164
7165           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7166
7167           Returns X509_EXTENSION from $x509 based on given position/index.
7168
7169            my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
7170            # $x509 - value corresponding to openssl's X509_CRL structure
7171            # $index - (integer) position/index of extension within $x509
7172            #
7173            # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
7174
7175       ·   X509_CRL_get_ext_by_NID
7176
7177           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7178
7179           Returns X509_EXTENSION from $x509 based on given NID.
7180
7181            my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
7182            # $x509 - value corresponding to openssl's X509_CRL structure
7183            # $nid - (integer) NID value
7184            # $loc - (integer) position to start lookup at
7185            #
7186            # returns: position/index of extension, negative value on error
7187            #          call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
7188
7189       ·   X509_CRL_get_ext_count
7190
7191           COMPATIBILITY: not available in Net-SSLeay-1.54 and before
7192
7193           Returns the total number of extensions in X509_CRL object $x.
7194
7195            my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
7196            # $x - value corresponding to openssl's X509_CRL structure
7197            #
7198            # returns: count of extensions
7199
7200       ·   X509_CRL_get_issuer
7201
7202           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7203
7204           Returns X509_NAME object corresponding to the issuer of X509_CRL
7205           $x.
7206
7207            my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
7208            # $x - value corresponding to openssl's X509_CRL structure
7209            #
7210            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7211
7212           See other "X509_NAME_*" functions to get more info from X509_NAME
7213           structure.
7214
7215       ·   X509_CRL_get_lastUpdate
7216
7217           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7218
7219           Returns 'lastUpdate' date-time value of X509_CRL object $x.
7220
7221            my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
7222            # $x - value corresponding to openssl's X509_CRL structure
7223            #
7224            # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7225
7226       ·   X509_CRL_get_nextUpdate
7227
7228           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7229
7230           Returns 'nextUpdate' date-time value of X509_CRL object $x.
7231
7232            my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
7233            # $x - value corresponding to openssl's X509_CRL structure
7234            #
7235            # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
7236
7237       ·   X509_CRL_get_version
7238
7239           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7240
7241           Returns 'version' value of given X509_CRL structure $x.
7242
7243            my $rv = Net::SSLeay::X509_CRL_get_version($x);
7244            # $x - value corresponding to openssl's X509_CRL structure
7245            #
7246            # returns: (integer) version
7247
7248       ·   X509_CRL_set_issuer_name
7249
7250           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7251           requires at least openssl-0.9.7
7252
7253           Sets the issuer of X509_CRL object $x to X509_NAME object $name.
7254
7255            my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
7256            # $x - value corresponding to openssl's X509_CRL structure
7257            # $name - value corresponding to openssl's X509_NAME structure
7258            #
7259            # returns: 1 on success, 0 on failure
7260
7261       ·   X509_CRL_set_lastUpdate
7262
7263           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7264           requires at least openssl-0.9.7
7265
7266           Sets 'lastUpdate' value of X509_CRL object $x to $tm.
7267
7268            my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
7269            # $x - value corresponding to openssl's X509_CRL structure
7270            # $tm - value corresponding to openssl's ASN1_TIME structure
7271            #
7272            # returns: 1 on success, 0 on failure
7273
7274       ·   X509_CRL_set_nextUpdate
7275
7276           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7277           requires at least openssl-0.9.7
7278
7279           Sets 'nextUpdate' value of X509_CRL object $x to $tm.
7280
7281            my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
7282            # $x - value corresponding to openssl's X509_CRL structure
7283            # $tm - value corresponding to openssl's ASN1_TIME structure
7284            #
7285            # returns: 1 on success, 0 on failure
7286
7287       ·   X509_CRL_set_version
7288
7289           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7290           requires at least openssl-0.9.7
7291
7292           Sets 'version' value of given X509_CRL structure $x to $version.
7293
7294            my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
7295            # $x - value corresponding to openssl's X509_CRL structure
7296            # $version - (integer) version number (1 = version 2 CRL)
7297            #
7298            # returns: 1 on success, 0 on failure
7299
7300           Note that if you want to use any X509_CRL extension you need to set
7301           "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
7302
7303       ·   X509_CRL_sign
7304
7305           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7306
7307           Sign X509_CRL object $x with private key $pkey (using digest
7308           algorithm $md).
7309
7310            my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
7311            # $x - value corresponding to openssl's X509_CRL structure
7312            # $pkey - value corresponding to openssl's EVP_PKEY structure
7313            # $md - value corresponding to openssl's EVP_MD structure
7314            #
7315            # returns: 1 on success, 0 on failure
7316
7317       ·   X509_CRL_sort
7318
7319           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7320           requires at least openssl-0.9.7
7321
7322           Sorts the data of X509_CRL object so it will be written in serial
7323           number order.
7324
7325            my $rv = Net::SSLeay::X509_CRL_sort($x);
7326            # $x - value corresponding to openssl's X509_CRL structure
7327            #
7328            # returns: 1 on success, 0 on failure
7329
7330       ·   X509_CRL_verify
7331
7332           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7333
7334           Verifies X509_CRL object $a using public key $r (pubkey of issuing
7335           CA).
7336
7337            my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
7338            # $a - value corresponding to openssl's X509_CRL structure
7339            # $r - value corresponding to openssl's EVP_PKEY structure
7340            #
7341            # returns: 0 - verify failure, 1 - verify OK, <0 - error
7342
7343       ·   P_X509_CRL_add_revoked_serial_hex
7344
7345           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7346           requires at least openssl-0.9.7
7347
7348           Adds given serial number $serial_hex to X509_CRL object $crl.
7349
7350            Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
7351            # $crl - value corresponding to openssl's X509_CRL structure
7352            # $serial_hex - string (hexadecimal) representation of serial number
7353            # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
7354            # $reason_code - [optional] (integer) reason code (see below) - default 0
7355            # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
7356            #
7357            # returns: no return value
7358
7359            reason codes:
7360            0 - unspecified
7361            1 - keyCompromise
7362            2 - CACompromise
7363            3 - affiliationChanged
7364            4 - superseded
7365            5 - cessationOfOperation
7366            6 - certificateHold
7367            7 - removeFromCRL
7368
7369       ·   P_X509_CRL_get_serial
7370
7371           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7372           requires at least openssl-0.9.7
7373
7374           Returns serial number of X509_CRL object.
7375
7376            my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
7377            # $crl - value corresponding to openssl's X509_CRL structure
7378            #
7379            # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
7380
7381       ·   P_X509_CRL_set_serial
7382
7383           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7384           requires at least openssl-0.9.7
7385
7386           Sets serial number of X509_CRL object to $crl_number.
7387
7388            my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
7389            # $crl - value corresponding to openssl's X509_CRL structure
7390            # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
7391            #
7392            # returns: 1 on success, 0 on failure
7393
7394       Low level API: X509_EXTENSION_* related functions
7395
7396       ·   X509_EXTENSION_get_critical
7397
7398           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7399
7400           Returns 'critical' flag of given X509_EXTENSION object $ex.
7401
7402            my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
7403            # $ex - value corresponding to openssl's X509_EXTENSION structure
7404            #
7405            # returns: (integer) 1 - critical, 0 - noncritical
7406
7407       ·   X509_EXTENSION_get_data
7408
7409           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7410
7411           Returns value (raw data) of X509_EXTENSION object $ne.
7412
7413            my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
7414            # $ne - value corresponding to openssl's X509_EXTENSION structure
7415            #
7416            # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
7417
7418           Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
7419           into perl scalar variable.
7420
7421       ·   X509_EXTENSION_get_object
7422
7423           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7424
7425           Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
7426
7427            my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
7428            # $ex - value corresponding to openssl's X509_EXTENSION structure
7429            #
7430            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7431
7432       ·   X509V3_EXT_print
7433
7434           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7435
7436           Returns string representation of given X509_EXTENSION object $ext.
7437
7438            Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
7439            # $ext - value corresponding to openssl's X509_EXTENSION structure
7440            # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
7441            # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7442            #
7443            # returns: no return value
7444
7445       ·   X509V3_EXT_d2i
7446
7447           Parses an extension and returns its internal structure.
7448
7449            my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
7450            # $ext - value corresponding to openssl's X509_EXTENSION structure
7451            #
7452            # returns: pointer ???
7453
7454       Low level API: X509_NAME_* related functions
7455
7456       ·   X509_NAME_ENTRY_get_data
7457
7458           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7459
7460           Retrieves the field value of $ne in and ASN1_STRING structure.
7461
7462            my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
7463            # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7464            #
7465            # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
7466
7467           Check openssl doc
7468           <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7469
7470       ·   X509_NAME_ENTRY_get_object
7471
7472           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7473
7474           Retrieves the field name of $ne in and ASN1_OBJECT structure.
7475
7476            my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
7477            # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7478            #
7479            # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7480
7481           Check openssl doc
7482           <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7483
7484       ·   X509_NAME_new
7485
7486           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7487           requires at least openssl-0.9.5
7488
7489           Creates a new X509_NAME structure.  Adds a field whose name is
7490           defined by a string $field. The field value to be added is in
7491           $bytes.
7492
7493            my $rv = Net::SSLeay::X509_NAME_new();
7494            #
7495            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7496
7497       ·   X509_NAME_hash
7498
7499           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7500           requires at least openssl-0.9.5
7501
7502           Sort of a checksum of issuer name $name.  The result is not a full
7503           hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
7504           'unsigned long' (32 bits).  The resulting value might differ across
7505           different openssl versions for the same X509 certificate.
7506
7507            my $rv = Net::SSLeay::X509_NAME_hash($name);
7508            # $name - value corresponding to openssl's X509_NAME structure
7509            #
7510            # returns: number representing checksum
7511
7512       ·   X509_NAME_add_entry_by_txt
7513
7514           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7515           requires at least openssl-0.9.5
7516
7517           Adds a field whose name is defined by a string $field. The field
7518           value to be added is in $bytes.
7519
7520            my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
7521            # $name - value corresponding to openssl's X509_NAME structure
7522            # $field - (string) field definition (name) - e.g. "organizationName"
7523            # $type - (integer) type of data in $bytes (see below)
7524            # $bytes - data to be set
7525            # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7526            # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7527            #
7528            # returns: 1 on success, 0 on failure
7529
7530            # values for $type - use constants:
7531            &Net::SSLeay::MBSTRING_UTF8     - $bytes contains utf8 encoded data
7532            &Net::SSLeay::MBSTRING_ASC      - $bytes contains ASCII data
7533
7534           Unicode note: when passing non-ascii (unicode) string in $bytes do
7535           not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
7536           the perl $string via "$bytes = encode('utf-8', $string)".
7537
7538           Check openssl doc
7539           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7540
7541       ·   X509_NAME_add_entry_by_NID
7542
7543           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7544           requires at least openssl-0.9.5
7545
7546           Adds a field whose name is defined by a NID $nid. The field value
7547           to be added is in $bytes.
7548
7549            my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
7550            # $name - value corresponding to openssl's X509_NAME structure
7551            # $nid - (integer) field definition - NID value
7552            # $type - (integer) type of data in $bytes (see below)
7553            # $bytes - data to be set
7554            # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7555            # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7556            #
7557            # returns: 1 on success, 0 on failure
7558
7559           Check openssl doc
7560           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7561
7562       ·   X509_NAME_add_entry_by_OBJ
7563
7564           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7565           requires at least openssl-0.9.5
7566
7567           Adds a field whose name is defined by a object (OID) $obj . The
7568           field value to be added is in $bytes.
7569
7570            my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
7571            # $name - value corresponding to openssl's X509_NAME structure
7572            # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
7573            # $type - (integer) type of data in $bytes (see below)
7574            # $bytes - data to be set
7575            # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7576            # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7577            #
7578            # returns: 1 on success, 0 on failure
7579
7580           Check openssl doc
7581           <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7582
7583       ·   X509_NAME_cmp
7584
7585           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7586
7587           Compares two X509_NAME obejcts.
7588
7589            my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
7590            # $a - value corresponding to openssl's X509_NAME structure
7591            # $b - value corresponding to openssl's X509_NAME structure
7592            #
7593            # returns: 0 if $a matches $b; non zero otherwise
7594
7595       ·   X509_NAME_digest
7596
7597           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7598
7599           Computes digest/fingerprint of X509_NAME $data using $type hash
7600           function.
7601
7602            my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
7603            # $data - value corresponding to openssl's X509_NAME structure
7604            # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7605            #
7606            # returns: hash value (binary)
7607
7608            #to get printable (hex) value of digest use:
7609            print unpack('H*', $digest_value);
7610
7611       ·   X509_NAME_entry_count
7612
7613           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7614
7615           Returns the total number of entries in $name.
7616
7617            my $rv = Net::SSLeay::X509_NAME_entry_count($name);
7618            # $name - value corresponding to openssl's X509_NAME structure
7619            #
7620            # returns: (integer) entries count
7621
7622           Check openssl doc
7623           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7624
7625       ·   X509_NAME_get_entry
7626
7627           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7628
7629           Retrieves the X509_NAME_ENTRY from $name corresponding to index
7630           $loc. Acceptable values for $loc run from 0 to
7631           "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
7632           is an internal pointer which must not be freed.
7633
7634            my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
7635            # $name - value corresponding to openssl's X509_NAME structure
7636            # $loc - (integer) index of wanted entry
7637            #
7638            # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
7639
7640           Check openssl doc
7641           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7642
7643       ·   X509_NAME_print_ex
7644
7645           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7646
7647           Returns a string with human readable version of $name.
7648
7649            Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
7650            # $name - value corresponding to openssl's X509_NAME structure
7651            # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
7652            # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7653            #
7654            # returns: string representation of $name
7655
7656            #available conversion flags - use constants:
7657            &Net::SSLeay::XN_FLAG_COMPAT
7658            &Net::SSLeay::XN_FLAG_DN_REV
7659            &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
7660            &Net::SSLeay::XN_FLAG_FN_ALIGN
7661            &Net::SSLeay::XN_FLAG_FN_LN
7662            &Net::SSLeay::XN_FLAG_FN_MASK
7663            &Net::SSLeay::XN_FLAG_FN_NONE
7664            &Net::SSLeay::XN_FLAG_FN_OID
7665            &Net::SSLeay::XN_FLAG_FN_SN
7666            &Net::SSLeay::XN_FLAG_MULTILINE
7667            &Net::SSLeay::XN_FLAG_ONELINE
7668            &Net::SSLeay::XN_FLAG_RFC2253
7669            &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
7670            &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
7671            &Net::SSLeay::XN_FLAG_SEP_MASK
7672            &Net::SSLeay::XN_FLAG_SEP_MULTILINE
7673            &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
7674            &Net::SSLeay::XN_FLAG_SPC_EQ
7675
7676           Most likely you will be fine with default:
7677
7678            Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
7679
7680           Or you might want RFC2253-like output without utf8 chars escaping:
7681
7682            use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
7683            my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
7684            my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
7685
7686           Check openssl doc
7687           <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7688
7689       ·   X509_NAME_get_text_by_NID
7690
7691           Retrieves the text from the first entry in name which matches $nid,
7692           if no such entry exists -1 is returned.
7693
7694           openssl note: this is a legacy function which has various
7695           limitations which makes it of minimal use in practice. It can only
7696           find the first matching entry and will copy the contents of the
7697           field verbatim: this can be highly confusing if the target is a
7698           multicharacter string type like a BMPString or a UTF8String.
7699
7700            Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
7701            # $name - value corresponding to openssl's X509_NAME structure
7702            # $nid - NID value (integer)
7703            #
7704            # returns: text value
7705
7706           Check openssl doc
7707           <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7708
7709       ·   X509_NAME_oneline
7710
7711           Return an ASCII version of $name.
7712
7713            Net::SSLeay::X509_NAME_oneline($name);
7714            # $name - value corresponding to openssl's X509_NAME structure
7715            #
7716            # returns: (string) ASCII version of $name
7717
7718           Check openssl doc
7719           <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7720
7721       ·   sk_X509_NAME_free
7722
7723           Free an allocated STACK_OF(X509_NAME) structure.
7724
7725            Net::SSLeay::sk_X509_NAME_free($sk);
7726            # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7727            #
7728            # returns: no return value
7729
7730       ·   sk_X509_NAME_num
7731
7732           Return number of items in STACK_OF(X509_NAME)
7733
7734            my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
7735            # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7736            #
7737            # returns: number of items
7738
7739       ·   sk_X509_NAME_value
7740
7741           Returns X509_NAME from position $index in STACK_OF(X509_NAME)
7742
7743            my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
7744            # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7745            # $i - (integer) index/position
7746            #
7747            # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7748
7749       ·   add_file_cert_subjects_to_stack
7750
7751           Add a file of certs to a stack. All certs in $file that are not
7752           already in the $stackCAs will be added.
7753
7754            my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
7755            # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7756            # $file - (string) filename
7757            #
7758            # returns: 1 on success, 0 on failure
7759
7760       ·   add_dir_cert_subjects_to_stack
7761
7762           Add a directory of certs to a stack. All certs in $dir that are not
7763           already in the $stackCAs will be added.
7764
7765            my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
7766            # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7767            # $dir - (string) the directory to append from. All files in this directory will be examined as potential certs. Any that are acceptable to SSL_add_dir_cert_subjects_to_stack() that are not already in the stack will be included.
7768            #
7769            # returns: 1 on success, 0 on failure
7770
7771       Low level API: X509_STORE_* related functions
7772
7773       ·   X509_STORE_CTX_new
7774
7775           returns a newly initialised X509_STORE_CTX structure.
7776
7777       ·   X509_STORE_CTX_init
7778
7779           X509_STORE_CTX_init() sets up an X509_STORE_CTX for a subsequent
7780           verification operation.  It must be called before each call to
7781           X509_verify_cert().
7782
7783           Net::SSLeay::X509_STORE_CTX_init($x509_store_ctx, $x509_store,
7784           $x509, $chain);
7785
7786           # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7787           structure (required) # $x509_store - value corresponding to
7788           openssl's X509_STORE structure (optional) # $x509 - value
7789           corresponding to openssl's X509 structure (optional) # $chain -
7790           value corresponding to openssl's STACK_OF(X509) structure
7791           (optional)
7792
7793           Check openssl doc
7794           <https://www.openssl.org/docs/man1.0.2/crypto/X509_STORE_CTX_init.html>
7795
7796       ·   X509_STORE_CTX_free
7797
7798           Frees an X509_STORE_CTX structure.
7799
7800           Net::SSLeay::X509_STORE_CTX_free($x509_store_ctx);
7801
7802           # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7803           structure
7804
7805       ·   X509_verify_cert
7806
7807           The X509_verify_cert() function attempts to discover and validate a
7808           certificate chain based on parameters in ctx. A complete
7809           description of the process is contained in the verify(1) manual
7810           page.
7811
7812           If this function returns 0, use X509_STORE_CTX_get_error to get
7813           additional error information.
7814
7815           my $rv = Net::SSLeay::X509_verify_cert($x509_store_ctx); #
7816           $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX
7817           structure # # returns: 1 if a complete chain can be built and
7818           validated, otherwise 0
7819
7820           Check openssl doc
7821           <https://www.openssl.org/docs/manmaster/man3/X509_verify_cert.html>
7822
7823       ·   X509_STORE_CTX_get_current_cert
7824
7825           Returns the certificate in ctx which caused the error or 0 if no
7826           certificate is relevant.
7827
7828            my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
7829            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7830            #
7831            # returns: value corresponding to openssl's X509 structure (0 on failure)
7832
7833           Check openssl doc
7834           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7835
7836       ·   X509_STORE_CTX_get_error
7837
7838           Returns the error code of $ctx.
7839
7840            my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
7841            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7842            #
7843            # returns: (integer) error code
7844
7845           For more info about erro code values check function
7846           "get_verify_result".
7847
7848           Check openssl doc
7849           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7850
7851       ·   X509_STORE_CTX_get_error_depth
7852
7853           Returns the depth of the error. This is a non-negative integer
7854           representing where in the certificate chain the error occurred. If
7855           it is zero it occurred in the end entity certificate, one if it is
7856           the certificate which signed the end entity certificate and so on.
7857
7858            my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
7859            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7860            #
7861            # returns: (integer) depth
7862
7863           Check openssl doc
7864           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7865
7866       ·   X509_STORE_CTX_get_ex_data
7867
7868           Is used to retrieve the information for $idx from $x509_store_ctx.
7869
7870            my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
7871            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7872            # $idx - (integer) index for application specific data
7873            #
7874            # returns: pointer to ???
7875
7876       ·   X509_STORE_CTX_set_ex_data
7877
7878           Is used to store application data at arg for idx into
7879           $x509_store_ctx.
7880
7881            my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
7882            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7883            # $idx - (integer) ???
7884            # $data - (pointer) ???
7885            #
7886            # returns: 1 on success, 0 on failure
7887
7888       ·   X509_STORE_CTX_set_cert
7889
7890           Sets the certificate to be verified in $x509_store_ctx to $x.
7891
7892            Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
7893            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7894            # $x - value corresponding to openssl's X509 structure
7895            #
7896            # returns: no return value
7897
7898           Check openssl doc
7899           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
7900
7901       ·   X509_STORE_new
7902
7903           Returns a newly initialized X509_STORE structure.
7904
7905           my $rv = Net::SSLeay::X509_STORE_new(); # # returns: value
7906           corresponding to openssl's X509_STORE structure (0 on failure)
7907
7908       ·   X509_STORE_free
7909
7910           Frees an X509_STORE structure
7911
7912           Net::SSLeay::X509_STORE_free($x509_store); # $x509_store - value
7913           corresponding to openssl's X509_STORE structure
7914
7915       ·   X509_STORE_add_lookup
7916
7917           Adds a lookup to an X509_STORE for a given lookup method.
7918
7919           my $method = &Net::SSLeay::X509_LOOKUP_hash_dir; my $rv =
7920           Net::SSLeay::X509_STORE_add_lookup($x509_store, $method); # $method
7921           - value corresponding to openssl's X509_LOOKUP_METHOD structure #
7922           $x509_store - value corresponding to openssl's X509_STORE structure
7923           # # returns: value corresponding to openssl's X509_LOOKUP structure
7924
7925           Check openssl doc
7926           <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
7927
7928       ·   X509_STORE_CTX_set_error
7929
7930           Sets the error code of $ctx to $s. For example it might be used in
7931           a verification callback to set an error based on additional checks.
7932
7933            Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
7934            # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7935            # $s - (integer) error id
7936            #
7937            # returns: no return value
7938
7939           Check openssl doc
7940           <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7941
7942       ·   X509_STORE_add_cert
7943
7944           Adds X509 certificate $x into the X509_STORE $store.
7945
7946            my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
7947            # $store - value corresponding to openssl's X509_STORE structure
7948            # $x - value corresponding to openssl's X509 structure
7949            #
7950            # returns: 1 on success, 0 on failure
7951
7952       ·   X509_STORE_add_crl
7953
7954           Adds X509 CRL $x into the X509_STORE $store.
7955
7956            my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
7957            # $store - value corresponding to openssl's X509_STORE structure
7958            # $x - value corresponding to openssl's X509_CRL structure
7959            #
7960            # returns: 1 on success, 0 on failure
7961
7962       ·   X509_STORE_set1_param
7963
7964           ??? (more info needed)
7965
7966            my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
7967            # $store - value corresponding to openssl's X509_STORE structure
7968            # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
7969            #
7970            # returns: 1 on success, 0 on failure
7971
7972       ·   X509_LOOKUP_hash_dir
7973
7974           Returns an X509_LOOKUP structure that instructs an X509_STORE to
7975           load files from a directory containing certificates with filenames
7976           in the format hash.N or crls with filenames in the format hash.rN
7977
7978           my $rv = Net::SSLeay::X509_LOOKUP_hash_dir(); # # returns: value
7979           corresponding to openssl's X509_LOOKUP_METHOD structure, with the
7980           hashed directory method
7981
7982           Check openssl doc
7983           <https://www.openssl.org/docs/man1.1.1/man3/X509_load_crl_file.html>
7984
7985       ·   X509_LOOKUP_add_dir
7986
7987           Add a directory to an X509_LOOKUP structure, usually obtained from
7988           X509_STORE_add_lookup.
7989
7990           my $method = &Net::SSLeay::X509_LOOKUP_hash_dir; my $lookup =
7991           Net::SSLeay::X509_STORE_add_lookup($x509_store, $method); my $type
7992           = &Net::SSLeay::X509_FILETYPE_PEM;
7993           Net::SSLeay::X509_LOOKUP_add_dir($lookup, $dir, $type); # $lookup -
7994           value corresponding to openssl's X509_LOOKUP structure # $dir -
7995           string path to a directory s# $type - constant corresponding to the
7996           type of file in the directory - can be X509_FILETYPE_PEM,
7997           X509_FILETYPE_DEFAULT, or X509_FILETYPE_ASN1
7998
7999       ·   X509_STORE_set_flags
8000
8001            Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
8002            # $ctx - value corresponding to openssl's X509_STORE structure
8003            # $flags - (unsigned long) flags to be set (bitmask)
8004            #
8005            # returns: no return value
8006
8007            #to create $flags value use corresponding constants like
8008            $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8009
8010           For more details about $flags bitmask see
8011           "X509_VERIFY_PARAM_set_flags".
8012
8013       ·   X509_STORE_set_purpose
8014
8015            Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
8016            # $ctx - value corresponding to openssl's X509_STORE structure
8017            # $purpose - (integer) purpose identifier
8018            #
8019            # returns: no return value
8020
8021           For more details about $purpose identifier check "CTX_set_purpose".
8022
8023       ·   X509_STORE_set_trust
8024
8025            Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
8026            # $ctx - value corresponding to openssl's X509_STORE structure
8027            # $trust - (integer) trust identifier
8028            #
8029            # returns: no return value
8030
8031           For more details about $trust identifier check "CTX_set_trust".
8032
8033       Low Level API: X509_INFO related functions
8034
8035       ·   sk_X509_INFO_num
8036
8037           Returns the number of values in a STACK_OF(X509_INFO) structure.
8038
8039            my $rv = Net::SSLeay::sk_X509_INFO_num($sk_x509_info);
8040            # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8041            #
8042            # returns: number of values in $sk_X509_info
8043
8044       ·   sk_X509_INFO_value
8045
8046           Returns the value of a STACK_OF(X509_INFO) structure at a given
8047           index.
8048
8049            my $rv = Net::SSLeay::sk_X509_INFO_value($sk_x509_info, $index);
8050            # $sk_x509_info - value corresponding to openssl's STACK_OF(X509_INFO) structure
8051            # $index - index into the stack
8052            #
8053            # returns: value corresponding to openssl's X509_INFO structure at the given index
8054
8055       ·   P_X509_INFO_get_x509
8056
8057           Returns the X509 structure stored in an X509_INFO structure.
8058
8059            my $rv = Net::SSLeay::P_X509_INFO_get_x509($x509_info);
8060            # $x509_info - value corresponding to openssl's X509_INFO structure
8061            #
8062            # returns: value corresponding to openssl's X509 structure
8063
8064       Low level API: X509_VERIFY_PARAM_* related functions
8065
8066       ·   X509_VERIFY_PARAM_add0_policy
8067
8068           Enables policy checking (it is disabled by default) and adds
8069           $policy to the acceptable policy set.
8070
8071            my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
8072            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8073            # $policy - value corresponding to openssl's ASN1_OBJECT structure
8074            #
8075            # returns: 1 on success, 0 on failure
8076
8077           Check openssl doc
8078           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8079
8080       ·   X509_VERIFY_PARAM_add0_table
8081
8082           ??? (more info needed)
8083
8084            my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
8085            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8086            #
8087            # returns: 1 on success, 0 on failure
8088
8089       ·   X509_VERIFY_PARAM_add1_host
8090
8091           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8092           requires at least OpenSSL 1.0.2
8093
8094           Adds an additional reference identifier that can match the peer's
8095           certificate.
8096
8097            my $rv = Net::SSLeay::X509_VERIFY_PARAM_add1_host($param, $name);
8098            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8099            # $name - (string) name to be set
8100            #
8101            # returns: 1 on success, 0 on failure
8102
8103           See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
8104           "X509_VERIFY_PARAM_set_hostflags" for more information, including
8105           wildcard matching.
8106
8107           Check openssl doc
8108           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8109
8110       ·   X509_VERIFY_PARAM_clear_flags
8111
8112           Clears the flags $flags in param.
8113
8114            my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
8115            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8116            # $flags - (unsigned long) flags to be set (bitmask)
8117            #
8118            # returns: 1 on success, 0 on failure
8119
8120           For more details about $flags bitmask see
8121           "X509_VERIFY_PARAM_set_flags".
8122
8123           Check openssl doc
8124           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8125
8126       ·   X509_VERIFY_PARAM_free
8127
8128           Frees up the X509_VERIFY_PARAM structure.
8129
8130            Net::SSLeay::X509_VERIFY_PARAM_free($param);
8131            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8132            #
8133            # returns: no return value
8134
8135       ·   X509_VERIFY_PARAM_get0_peername
8136
8137           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8138           requires at least OpenSSL 1.0.2
8139
8140           Returns the DNS hostname or subject CommonName from the peer
8141           certificate that matched one of the reference identifiers.
8142
8143            my $rv = Net::SSLeay::X509_VERIFY_PARAM_get0_peername($param);
8144            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8145            #
8146            # returns: (string) name e.g. '*.example.com' or undef
8147
8148           Check openssl doc
8149           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8150
8151       ·   X509_VERIFY_PARAM_get_depth
8152
8153           Returns the current verification depth.
8154
8155            my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
8156            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8157            #
8158            # returns: (ineger) depth
8159
8160           Check openssl doc
8161           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8162
8163       ·   X509_VERIFY_PARAM_get_flags
8164
8165           Returns the current verification flags.
8166
8167            my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
8168            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8169            #
8170            # returns: (unsigned long) flags to be set (bitmask)
8171
8172           For more details about returned flags bitmask see
8173           "X509_VERIFY_PARAM_set_flags".
8174
8175           Check openssl doc
8176           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8177
8178       ·   X509_VERIFY_PARAM_set_flags
8179
8180            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
8181            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8182            # $flags - (unsigned long) flags to be set (bitmask)
8183            #
8184            # returns: 1 on success, 0 on failure
8185
8186            #to create $flags value use corresponding constants like
8187            $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
8188
8189           For more details about $flags bitmask, see the OpenSSL docs below.
8190
8191           Check openssl doc
8192           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8193
8194       ·   X509_VERIFY_PARAM_inherit
8195
8196           ??? (more info needed)
8197
8198            my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
8199            # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8200            # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8201            #
8202            # returns: 1 on success, 0 on failure
8203
8204       ·   X509_VERIFY_PARAM_lookup
8205
8206           Finds X509_VERIFY_PARAM by name.
8207
8208            my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
8209            # $name - (string) name we want to find
8210            #
8211            # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8212
8213       ·   X509_VERIFY_PARAM_new
8214
8215           Creates a new X509_VERIFY_PARAM structure.
8216
8217            my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
8218            #
8219            # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
8220
8221       ·   X509_VERIFY_PARAM_set1
8222
8223           Sets the name of X509_VERIFY_PARAM structure $to to the same value
8224           as the name of X509_VERIFY_PARAM structure $from.
8225
8226            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
8227            # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
8228            # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
8229            #
8230            # returns: 1 on success, 0 on failure
8231
8232       ·   X509_VERIFY_PARAM_set1_email
8233
8234           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8235           requires at least OpenSSL 1.0.2
8236
8237           Sets the expected RFC822 email address to email.
8238
8239            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_email($param, $email);
8240            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8241            # $email - (string) email to be set
8242            #
8243            # returns: 1 on success, 0 on failure
8244
8245           Check openssl doc
8246           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8247
8248       ·   X509_VERIFY_PARAM_set1_host
8249
8250           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8251           requires at least OpenSSL 1.0.2
8252
8253           Sets the expected DNS hostname to name clearing any previously
8254           specified host name or names.
8255
8256            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_host($param, $name);
8257            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8258            # $name - (string) name to be set
8259            #
8260            # returns: 1 on success, 0 on failure
8261
8262           See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
8263           "X509_VERIFY_PARAM_set_hostflags" for more information, including
8264           wildcard matching.
8265
8266           Check openssl doc
8267           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8268
8269       ·   X509_VERIFY_PARAM_set1_ip
8270
8271           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8272           requires at least OpenSSL 1.0.2
8273
8274           Sets the expected IP address to ip.
8275
8276            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_ip($param, $ip);
8277            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8278            # $ip - (binary) 4 octet IPv4 or 16 octet IPv6 address
8279            #
8280            # returns: 1 on success, 0 on failure
8281
8282           Check openssl doc
8283           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8284
8285       ·   X509_VERIFY_PARAM_set1_ip_asc
8286
8287           COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
8288           requires at least OpenSSL 1.0.2
8289
8290           Sets the expected IP address to ipasc.
8291
8292            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_asc($param, $ipasc);
8293            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8294            # $ip - (string) IPv4 or IPv6 address
8295            #
8296            # returns: 1 on success, 0 on failure
8297
8298           Check openssl doc
8299           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8300
8301       ·   X509_VERIFY_PARAM_set1_name
8302
8303           Sets the name of X509_VERIFY_PARAM structure $param to $name.
8304
8305            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
8306            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8307            # $name - (string) name to be set
8308            #
8309            # returns: 1 on success, 0 on failure
8310
8311       ·   X509_VERIFY_PARAM_set1_policies
8312
8313           Enables policy checking (it is disabled by default) and sets the
8314           acceptable policy set to policies.  Any existing policy set is
8315           cleared. The policies parameter can be 0 to clear an existing
8316           policy set.
8317
8318            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
8319            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8320            # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
8321            #
8322            # returns: 1 on success, 0 on failure
8323
8324           Check openssl doc
8325           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8326
8327       ·   X509_VERIFY_PARAM_set_depth
8328
8329           Sets the maximum verification depth to depth. That is the maximum
8330           number of untrusted CA certificates that can appear in a chain.
8331
8332            Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
8333            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8334            # $depth - (integer) depth to be set
8335            #
8336            # returns: no return value
8337
8338           Check openssl doc
8339           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8340
8341       ·   X509_VERIFY_PARAM_set_hostflags
8342
8343            Net::SSLeay::X509_VERIFY_PARAM_set_hostflags($param, $flags);
8344            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8345            # $flags - (unsigned int) flags to be set (bitmask)
8346            #
8347            # returns: no return value
8348
8349           See also OpenSSL docs,  "X509_VERIFY_PARAM_add1_host" and
8350           "X509_VERIFY_PARAM_set1_host" for more information.  The flags for
8351           controlling wildcard checks and other features are defined in
8352           OpenSSL docs.
8353
8354           Check openssl doc
8355           <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8356
8357       ·   X509_VERIFY_PARAM_set_purpose
8358
8359           Sets the verification purpose in $param to $purpose. This
8360           determines the acceptable purpose of the certificate chain, for
8361           example SSL client or SSL server.
8362
8363            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
8364            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8365            # $purpose - (integer) purpose identifier
8366            #
8367            # returns: 1 on success, 0 on failure
8368
8369           For more details about $purpose identifier check "CTX_set_purpose".
8370
8371           Check openssl doc
8372           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8373
8374       ·   X509_VERIFY_PARAM_set_time
8375
8376           Sets the verification time in $param to $t. Normally the current
8377           time is used.
8378
8379            Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
8380            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8381            # $t - (time_t) time in seconds since 1.1.1970
8382            #
8383            # returns: no return value
8384
8385           Check openssl doc
8386           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8387
8388       ·   X509_VERIFY_PARAM_set_trust
8389
8390           Sets the trust setting in $param to $trust.
8391
8392            my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
8393            # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
8394            # $trust - (integer) trust identifier
8395            #
8396            # returns: 1 on success, 0 on failure
8397
8398           For more details about $trust identifier check "CTX_set_trust".
8399
8400           Check openssl doc
8401           <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
8402
8403       ·   X509_VERIFY_PARAM_table_cleanup
8404
8405           ??? (more info needed)
8406
8407            Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
8408            #
8409            # returns: no return value
8410
8411       Low level API: Cipher (EVP_CIPHER_*) related functions
8412
8413       ·   EVP_get_cipherbyname
8414
8415           COMPATIBILITY: not available in Net-SSLeay-1.45 and before
8416
8417           Returns an EVP_CIPHER structure when passed a cipher name.
8418
8419            my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
8420            # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
8421            #
8422            # returns: value corresponding to openssl's EVP_CIPHER structure
8423
8424           Check openssl doc
8425           <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
8426
8427       Low level API: Digest (EVP_MD_*) related functions
8428
8429       ·   OpenSSL_add_all_digests
8430
8431           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8432
8433            Net::SSLeay::OpenSSL_add_all_digests();
8434            # no args, no return value
8435
8436           http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
8437
8438       ·   P_EVP_MD_list_all
8439
8440           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8441           requires at least openssl-1.0.0
8442
8443           NOTE: Does not exactly correspond to any low level API function
8444
8445            my $rv = Net::SSLeay::P_EVP_MD_list_all();
8446            #
8447            # returns: arrayref - list of available digest names
8448
8449           The returned digest names correspond to values expected by
8450           "EVP_get_digestbyname".
8451
8452           Note that some of the digests are available by default and some
8453           only after calling "OpenSSL_add_all_digests".
8454
8455       ·   EVP_get_digestbyname
8456
8457           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8458
8459            my $rv = Net::SSLeay::EVP_get_digestbyname($name);
8460            # $name - string with digest name
8461            #
8462            # returns: value corresponding to openssl's EVP_MD structure
8463
8464           The $name param can be:
8465
8466            md2
8467            md4
8468            md5
8469            mdc2
8470            ripemd160
8471            sha
8472            sha1
8473            sha224
8474            sha256
8475            sha512
8476            whirlpool
8477
8478           Or better check the supported digests by calling
8479           "P_EVP_MD_list_all".
8480
8481       ·   EVP_MD_type
8482
8483           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8484
8485            my $rv = Net::SSLeay::EVP_MD_type($md);
8486            # $md - value corresponding to openssl's EVP_MD structure
8487            #
8488            # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
8489
8490       ·   EVP_MD_size
8491
8492           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8493
8494            my $rv = Net::SSLeay::EVP_MD_size($md);
8495            # $md - value corresponding to openssl's EVP_MD structure
8496            #
8497            # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
8498
8499       ·   EVP_MD_CTX_md
8500
8501           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8502           requires at least openssl-0.9.7
8503
8504            Net::SSLeay::EVP_MD_CTX_md($ctx);
8505            # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8506            #
8507            # returns: value corresponding to openssl's EVP_MD structure
8508
8509       ·   EVP_MD_CTX_create
8510
8511           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8512           requires at least openssl-0.9.7
8513
8514           Allocates, initializes and returns a digest context.
8515
8516            my $rv = Net::SSLeay::EVP_MD_CTX_create();
8517            #
8518            # returns: value corresponding to openssl's EVP_MD_CTX structure
8519
8520           The complete idea behind EVP_MD_CTX looks like this example:
8521
8522             Net::SSLeay::OpenSSL_add_all_digests();
8523
8524             my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
8525             my $ctx = Net::SSLeay::EVP_MD_CTX_create();
8526             Net::SSLeay::EVP_DigestInit($ctx, $md);
8527
8528             while(my $chunk = get_piece_of_data()) {
8529               Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
8530             }
8531
8532             my $result = Net::SSLeay::EVP_DigestFinal($ctx);
8533             Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8534
8535             print "digest=", unpack('H*', $result), "\n"; #print hex value
8536
8537       ·   EVP_DigestInit_ex
8538
8539           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8540           requires at least openssl-0.9.7
8541
8542           Sets up digest context $ctx to use a digest $type from ENGINE
8543           $impl, $ctx must be initialized before calling this function, type
8544           will typically be supplied by a function such as
8545           "EVP_get_digestbyname". If $impl is 0 then the default
8546           implementation of digest $type is used.
8547
8548            my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
8549            # $ctx  - value corresponding to openssl's EVP_MD_CTX structure
8550            # $type - value corresponding to openssl's EVP_MD structure
8551            # $impl - value corresponding to openssl's ENGINE structure
8552            #
8553            # returns: 1 for success and 0 for failure
8554
8555       ·   EVP_DigestInit
8556
8557           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8558           requires at least openssl-0.9.7
8559
8560           Behaves in the same way as "EVP_DigestInit_ex" except the passed
8561           context $ctx does not have to be initialized, and it always uses
8562           the default digest implementation.
8563
8564            my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
8565            # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8566            # $type - value corresponding to openssl's EVP_MD structure
8567            #
8568            # returns: 1 for success and 0 for failure
8569
8570       ·   EVP_MD_CTX_destroy
8571
8572           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8573           requires at least openssl-0.9.7
8574
8575           Cleans up digest context $ctx and frees up the space allocated to
8576           it, it should be called only on a context created using
8577           "EVP_MD_CTX_create".
8578
8579            Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8580            # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8581            #
8582            # returns: no return value
8583
8584       ·   EVP_DigestUpdate
8585
8586           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8587           requires at least openssl-0.9.7
8588
8589            my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
8590            # $ctx  - value corresponding to openssl's EVP_MD_CTX structure
8591            # $data - data to be hashed
8592            #
8593            # returns: 1 for success and 0 for failure
8594
8595       ·   EVP_DigestFinal_ex
8596
8597           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8598           requires at least openssl-0.9.7
8599
8600           Retrieves the digest value from $ctx. After calling
8601           "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
8602           be made, but "EVP_DigestInit_ex" can be called to initialize a new
8603           digest operation.
8604
8605            my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
8606            # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8607            #
8608            # returns: hash value (binary)
8609
8610            #to get printable (hex) value of digest use:
8611            print unpack('H*', $digest_value);
8612
8613       ·   EVP_DigestFinal
8614
8615           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8616           requires at least openssl-0.9.7
8617
8618           Similar to "EVP_DigestFinal_ex" except the digest context ctx is
8619           automatically cleaned up.
8620
8621            my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
8622            # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8623            #
8624            # returns: hash value (binary)
8625
8626            #to get printable (hex) value of digest use:
8627            print unpack('H*', $digest_value);
8628
8629       ·   MD2
8630
8631           COMPATIBILITY: no supported by default in openssl-1.0.0
8632
8633           Computes MD2 from given $data (all data needs to be loaded into
8634           memory)
8635
8636            my $digest = Net::SSLeay::MD2($data);
8637            print "digest(hexadecimal)=", unpack('H*', $digest);
8638
8639       ·   MD4
8640
8641           Computes MD4 from given $data (all data needs to be loaded into
8642           memory)
8643
8644            my $digest = Net::SSLeay::MD4($data);
8645            print "digest(hexadecimal)=", unpack('H*', $digest);
8646
8647       ·   MD5
8648
8649           Computes MD5 from given $data (all data needs to be loaded into
8650           memory)
8651
8652            my $digest = Net::SSLeay::MD5($data);
8653            print "digest(hexadecimal)=", unpack('H*', $digest);
8654
8655       ·   RIPEMD160
8656
8657           Computes RIPEMD160 from given $data (all data needs to be loaded
8658           into memory)
8659
8660            my $digest = Net::SSLeay::RIPEMD160($data);
8661            print "digest(hexadecimal)=", unpack('H*', $digest);
8662
8663       ·   SHA1
8664
8665           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8666
8667           Computes SHA1 from given $data (all data needs to be loaded into
8668           memory)
8669
8670            my $digest = Net::SSLeay::SHA1($data);
8671            print "digest(hexadecimal)=", unpack('H*', $digest);
8672
8673       ·   SHA256
8674
8675           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8676           requires at least openssl-0.9.8
8677
8678           Computes SHA256 from given $data (all data needs to be loaded into
8679           memory)
8680
8681            my $digest = Net::SSLeay::SHA256($data);
8682            print "digest(hexadecimal)=", unpack('H*', $digest);
8683
8684       ·   SHA512
8685
8686           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8687           requires at least openssl-0.9.8
8688
8689           Computes SHA512 from given $data (all data needs to be loaded into
8690           memory)
8691
8692            my $digest = Net::SSLeay::SHA512($data);
8693            print "digest(hexadecimal)=", unpack('H*', $digest);
8694
8695       ·   EVP_Digest
8696
8697           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8698           requires at least openssl-0.9.7
8699
8700           Computes "any" digest from given $data (all data needs to be loaded
8701           into memory)
8702
8703            my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
8704            my $digest = Net::SSLeay::EVP_Digest($data, $md);
8705            print "digest(hexadecimal)=", unpack('H*', $digest);
8706
8707       ·   EVP_sha1
8708
8709           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8710
8711            my $md = Net::SSLeay::EVP_sha1();
8712            #
8713            # returns: value corresponding to openssl's EVP_MD structure
8714
8715       ·   EVP_sha256
8716
8717           COMPATIBILITY: requires at least openssl-0.9.8
8718
8719            my $md = Net::SSLeay::EVP_sha256();
8720            #
8721            # returns: value corresponding to openssl's EVP_MD structure
8722
8723       ·   EVP_sha512
8724
8725           COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8726           requires at least openssl-0.9.8
8727
8728            my $md = Net::SSLeay::EVP_sha512();
8729            #
8730            # returns: value corresponding to openssl's EVP_MD structure
8731
8732       ·   EVP_add_digest
8733
8734            my $rv = Net::SSLeay::EVP_add_digest($digest);
8735            # $digest - value corresponding to openssl's EVP_MD structure
8736            #
8737            # returns: 1 on success, 0 otherwise
8738
8739       Low level API: CIPHER_* related functions
8740
8741       ·   CIPHER_get_name
8742
8743           COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8744
8745           Returns name of the cipher used.
8746
8747            my $rv = Net::SSLeay::CIPHER_description($cipher);
8748            # $cipher - value corresponding to openssl's SSL_CIPHER structure
8749            #
8750            # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA'
8751
8752           Check openssl doc
8753           <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8754
8755           Example:
8756
8757            my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
8758            my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
8759
8760       ·   CIPHER_description
8761
8762           Returns a textual description of the cipher used.
8763
8764           ??? (does this function really work?)
8765
8766            my $rv = Net::SSLeay::CIPHER_description($cipher, $buf, $size);
8767            # $cipher - value corresponding to openssl's SSL_CIPHER structure
8768            # $bufer - (string/buffer) ???
8769            # $size - (integer) ???
8770            #
8771            # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
8772
8773           Check openssl doc
8774           <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8775
8776       ·   CIPHER_get_bits
8777
8778           Returns the number of secret bits used for cipher.
8779
8780            my $rv = Net::SSLeay::CIPHER_get_bits($c);
8781            # $c - value corresponding to openssl's SSL_CIPHER structure
8782            #
8783            # returns: (integert) number of secret bits, 0 on error
8784
8785           Check openssl doc
8786           <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8787
8788       Low level API: RSA_* related functions
8789
8790       ·   RSA_generate_key
8791
8792           Generates a key pair and returns it in a newly allocated RSA
8793           structure.  The pseudo-random number generator must be seeded prior
8794           to calling RSA_generate_key.
8795
8796            my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
8797            # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
8798            # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
8799            # $perl_cb - [optional] reference to perl callback function
8800            # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
8801            #
8802            # returns: value corresponding to openssl's RSA structure (0 on failure)
8803
8804           Check openssl doc
8805           <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
8806
8807       ·   RSA_free
8808
8809           Frees the RSA structure and its components. The key is erased
8810           before the memory is returned to the system.
8811
8812            Net::SSLeay::RSA_free($r);
8813            # $r - value corresponding to openssl's RSA structure
8814            #
8815            # returns: no return value
8816
8817           Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
8818
8819       ·   RSA_get_key_parameters
8820
8821           Returns a list of pointers to BIGNUMs representing the parameters
8822           of the key in this order: (n, e, d, p, q, dmp1, dmq1, iqmp)
8823           Caution: returned list consists of SV pointers to BIGNUMs, which
8824           would need to be blessed as Crypt::OpenSSL::Bignum for further use
8825
8826           my (@params) = RSA_get_key_parameters($r);
8827
8828       Low level API: BIO_* related functions
8829
8830       ·   BIO_eof
8831
8832           Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
8833           varies according to the BIO type.
8834
8835            my $rv = Net::SSLeay::BIO_eof($s);
8836            # $s - value corresponding to openssl's BIO structure
8837            #
8838            # returns: 1 if EOF has been reached 0 otherwise
8839
8840           Check openssl doc
8841           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8842
8843       ·   BIO_f_ssl
8844
8845           Returns the SSL BIO method. This is a filter BIO which is a wrapper
8846           round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
8847
8848            my $rv = Net::SSLeay::BIO_f_ssl();
8849            #
8850            # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8851
8852           Check openssl doc
8853           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8854
8855       ·   BIO_free
8856
8857           Frees up a single BIO.
8858
8859            my $rv = Net::SSLeay::BIO_free($bio;);
8860            # $bio; - value corresponding to openssl's BIO structure
8861            #
8862            # returns: 1 on success, 0 on failure
8863
8864           Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8865
8866       ·   BIO_new
8867
8868           Returns a new BIO using method $type
8869
8870            my $rv = Net::SSLeay::BIO_new($type);
8871            # $type - value corresponding to openssl's BIO_METHOD structure
8872            #
8873            # returns: value corresponding to openssl's BIO structure (0 on failure)
8874
8875           Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8876
8877       ·   BIO_new_buffer_ssl_connect
8878
8879           Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
8880           (using ctx) and a connect BIO.
8881
8882            my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
8883            # $ctx - value corresponding to openssl's SSL_CTX structure
8884            #
8885            # returns: value corresponding to openssl's BIO structure (0 on failure)
8886
8887           Check openssl doc
8888           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8889
8890       ·   BIO_new_file
8891
8892           Creates a new file BIO with mode $mode the meaning of mode is the
8893           same as the stdio function fopen(). The BIO_CLOSE flag is set on
8894           the returned BIO.
8895
8896            my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
8897            # $filename - (string) filename
8898            # $mode - (string) opening mode (as mode by stdio function fopen)
8899            #
8900            # returns: value corresponding to openssl's BIO structure (0 on failure)
8901
8902           Check openssl doc
8903           <http://www.openssl.org/docs/crypto/BIO_s_file.html>
8904
8905       ·   BIO_new_ssl
8906
8907           Allocates an SSL BIO using SSL_CTX ctx and using client mode if
8908           client is non zero.
8909
8910            my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
8911            # $ctx - value corresponding to openssl's SSL_CTX structure
8912            # $client - (integer) 0 or 1 - indicates ssl client mode
8913            #
8914            # returns: value corresponding to openssl's BIO structure (0 on failure)
8915
8916           Check openssl doc
8917           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8918
8919       ·   BIO_new_ssl_connect
8920
8921           Creates a new BIO chain consisting of an SSL BIO (using ctx)
8922           followed by a connect BIO.
8923
8924            my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
8925            # $ctx - value corresponding to openssl's SSL_CTX structure
8926            #
8927            # returns: value corresponding to openssl's BIO structure (0 on failure)
8928
8929           Check openssl doc
8930           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8931
8932       ·   BIO_pending
8933
8934           Return the number of pending characters in the BIOs read buffers.
8935
8936            my $rv = Net::SSLeay::BIO_pending($s);
8937            # $s - value corresponding to openssl's BIO structure
8938            #
8939            # returns: the amount of pending data
8940
8941           Check openssl doc
8942           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8943
8944       ·   BIO_wpending
8945
8946           Return the number of pending characters in the BIOs write buffers.
8947
8948            my $rv = Net::SSLeay::BIO_wpending($s);
8949            # $s - value corresponding to openssl's BIO structure
8950            #
8951            # returns: the amount of pending data
8952
8953           Check openssl doc
8954           <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8955
8956       ·   BIO_read
8957
8958           Read the underlying descriptor.
8959
8960            Net::SSLeay::BIO_read($s, $max);
8961            # $s - value corresponding to openssl's BIO structure
8962            # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
8963            #
8964            # returns: data
8965
8966           Check openssl doc
8967           <http://www.openssl.org/docs/crypto/BIO_read.html>
8968
8969       ·   BIO_write
8970
8971           Attempts to write data from $buffer to BIO $b.
8972
8973            my $rv = Net::SSLeay::BIO_write($b, $buffer);
8974            # $b - value corresponding to openssl's BIO structure
8975            # $buffer - data
8976            #
8977            # returns: amount of data successfully written
8978            #          or that no data was successfully read or written if the result is 0 or -1
8979            #          or -2 when the operation is not implemented in the specific BIO type
8980
8981           Check openssl doc
8982           <http://www.openssl.org/docs/crypto/BIO_read.html>
8983
8984       ·   BIO_s_mem
8985
8986           Return the memory BIO method function.
8987
8988            my $rv = Net::SSLeay::BIO_s_mem();
8989            #
8990            # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8991
8992           Check openssl doc
8993           <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
8994
8995       ·   BIO_ssl_copy_session_id
8996
8997           Copies an SSL session id between BIO chains from and to. It does
8998           this by locating the SSL BIOs in each chain and calling
8999           SSL_copy_session_id() on the internal SSL pointer.
9000
9001            my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
9002            # $to - value corresponding to openssl's BIO structure
9003            # $from - value corresponding to openssl's BIO structure
9004            #
9005            # returns: 1 on success, 0 on failure
9006
9007           Check openssl doc
9008           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9009
9010       ·   BIO_ssl_shutdown
9011
9012           Closes down an SSL connection on BIO chain bio. It does this by
9013           locating the SSL BIO in the chain and calling SSL_shutdown() on its
9014           internal SSL pointer.
9015
9016            Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
9017            # $ssl_bio - value corresponding to openssl's BIO structure
9018            #
9019            # returns: no return value
9020
9021           Check openssl doc
9022           <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
9023
9024       Low level API: Server side Server Name Indication (SNI) support
9025
9026       ·   set_tlsext_host_name
9027
9028           TBA
9029
9030       ·   get_servername
9031
9032           TBA
9033
9034       ·   get_servername_type
9035
9036           TBA
9037
9038       ·   CTX_set_tlsext_servername_callback
9039
9040           COMPATIBILITY: requires at least OpenSSL 0.9.8f
9041
9042           This function is used in a server to support Server side Server
9043           Name Indication (SNI).
9044
9045            Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
9046            # $ctx - SSL context
9047            # $code - reference to a subroutine that will be called when a new connection is being initiated
9048            #
9049            # returns: no return value
9050           On the client side:
9051           use set_tlsext_host_name($ssl, $servername) before initiating the SSL connection.
9052
9053           On the server side: Set up an additional SSL_CTX() for each
9054           different certificate;
9055
9056           Add a servername callback to each SSL_CTX() using
9057           CTX_set_tlsext_servername_callback();
9058
9059           The callback function is required to retrieve the client-supplied
9060           servername with get_servername(ssl). Figure out the right SSL_CTX
9061           to go with that host name, then switch the SSL object to that
9062           SSL_CTX with set_SSL_CTX().
9063
9064           Example:
9065
9066            # set callback
9067            Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
9068               sub {
9069                 my $ssl = shift;
9070                 my $h = Net::SSLeay::get_servername($ssl);
9071                 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9072               } );
9073
9074           More complete example:
9075
9076            # ... initialize Net::SSLeay
9077
9078            my %hostnames = (
9079              'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
9080              'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
9081            );
9082
9083            # create a new context for each certificate/key pair
9084            for my $name (keys %hostnames) {
9085              $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
9086              Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
9087              Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
9088              $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
9089            }
9090
9091            # create default context
9092            my $ctx = Net::SSLeay::CTX_new or die;
9093            Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
9094            Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
9095
9096            # set callback
9097            Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
9098              my $ssl = shift;
9099              my $h = Net::SSLeay::get_servername($ssl);
9100              Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
9101              } );
9102
9103            # ... later
9104
9105            $s = Net::SSLeay::new($ctx);
9106            Net::SSLeay::set_fd($s, fileno($accepted_socket));
9107            Net::SSLeay::accept($s);
9108
9109       Low level API: NPN (next protocol negotiation) related functions
9110
9111       NPN is being replaced with ALPN, a more recent TLS extension for
9112       application protocol negotiation that's in process of being adopted by
9113       IETF. Please look below for APLN API description.
9114
9115       Simple approach for using NPN support looks like this:
9116
9117        ### client side
9118        use Net::SSLeay;
9119        use IO::Socket::INET;
9120
9121        Net::SSLeay::initialize();
9122        my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9123        my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9124        Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9125        Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
9126        my $ssl = Net::SSLeay::new($ctx) or die;
9127        Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9128        Net::SSLeay::connect($ssl);
9129
9130        warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
9131        warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
9132
9133        ### server side
9134        use Net::SSLeay;
9135        use IO::Socket::INET;
9136
9137        Net::SSLeay::initialize();
9138        my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9139        Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9140        Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9141        Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
9142        my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9143
9144        while (1) {
9145          my $ssl = Net::SSLeay::new($ctx);
9146          warn("server:waiting for incoming connection...\n");
9147          my $fd = $sock->accept();
9148          Net::SSLeay::set_fd($ssl, $fd->fileno);
9149          Net::SSLeay::accept($ssl);
9150          warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
9151          my $got = Net::SSLeay::read($ssl);
9152          Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9153          Net::SSLeay::free($ssl);
9154          $fd->close();
9155        }
9156        # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
9157
9158       Please note that the selection (negotiation) is performed by client
9159       side, the server side simply advertise the list of supported protocols.
9160
9161       Advanced approach allows you to implement your own negotiation
9162       algorithm.
9163
9164        #see below documentation for:
9165        Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9166        Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9167
9168       Detection of NPN support (works even in older Net::SSLeay versions):
9169
9170        use Net::SSLeay;
9171
9172        if (exists &Net::SSLeay::P_next_proto_negotiated) {
9173          # do NPN stuff
9174        }
9175
9176       ·   CTX_set_next_proto_select_cb
9177
9178           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9179           requires at least openssl-1.0.1
9180
9181           NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
9182           connection.
9183
9184           Simple usage - in this case a "common" negotiation algorithm (as
9185           implemented by openssl's function SSL_select_next_proto) is used.
9186
9187            $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
9188            # $ctx - value corresponding to openssl's SSL_CTX structure
9189            # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
9190            #
9191            # returns: 0 on success, 1 on failure
9192
9193           Advanced usage (you probably do not need this):
9194
9195            $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
9196            # $ctx - value corresponding to openssl's SSL_CTX structure
9197            # $perl_callback_function - reference to perl function
9198            # $callback_data - [optional] data to passed to callback function when invoked
9199            #
9200            # returns: 0 on success, 1 on failure
9201
9202            # where callback function looks like
9203            sub npn_advertised_cb_invoke {
9204              my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
9205              my $status;
9206              # ...
9207              $status = 1;   #status can be:
9208                             # 0 - OPENSSL_NPN_UNSUPPORTED
9209                             # 1 - OPENSSL_NPN_NEGOTIATED
9210                             # 2 - OPENSSL_NPN_NO_OVERLAP
9211              return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
9212            }
9213
9214           To undefine/clear this callback use:
9215
9216            Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
9217
9218       ·   CTX_set_next_protos_advertised_cb
9219
9220           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9221           requires at least openssl-1.0.1
9222
9223           NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
9224           connection.
9225
9226           Simple usage:
9227
9228            $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
9229            # $ctx - value corresponding to openssl's SSL_CTX structure
9230            # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
9231            #
9232            # returns: 0 on success, 1 on failure
9233
9234           Advanced usage (you probably do not need this):
9235
9236            $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
9237            # $ctx - value corresponding to openssl's SSL_CTX structure
9238            # $perl_callback_function - reference to perl function
9239            # $callback_data - [optional] data to passed to callback function when invoked
9240            #
9241            # returns: 0 on success, 1 on failure
9242
9243            # where callback function looks like
9244            sub npn_advertised_cb_invoke {
9245              my ($ssl, $callback_data) = @_;
9246              # ...
9247              return ['http1.1','spdy/2']; # the callback has to return arrayref
9248            }
9249
9250           To undefine/clear this callback use:
9251
9252            Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
9253
9254       ·   P_next_proto_negotiated
9255
9256           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9257           requires at least openssl-1.0.1
9258
9259           Returns the name of negotiated protocol for given SSL connection
9260           $ssl.
9261
9262            $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
9263            # $ssl - value corresponding to openssl's SSL structure
9264            #
9265            # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9266
9267       ·   P_next_proto_last_status
9268
9269           COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
9270           requires at least openssl-1.0.1
9271
9272           Returns the result of the last negotiation for given SSL connection
9273           $ssl.
9274
9275            $rv = Net::SSLeay::P_next_proto_last_status($ssl)
9276            # $ssl - value corresponding to openssl's SSL structure
9277            #
9278            # returns: (integer) negotiation status
9279            #          0 - OPENSSL_NPN_UNSUPPORTED
9280            #          1 - OPENSSL_NPN_NEGOTIATED
9281            #          2 - OPENSSL_NPN_NO_OVERLAP
9282
9283       Low level API: ALPN (application layer protocol negotiation) related
9284       functions
9285
9286       Application protocol can be negotiated via two different mechanisms
9287       employing two different TLS extensions: NPN (obsolete) and ALPN
9288       (recommended).
9289
9290       The API is rather similar, with slight differences reflecting protocol
9291       specifics. In particular, with ALPN the protocol negotiation takes
9292       place on server, while with NPN the client implements the protocol
9293       negotiation logic.
9294
9295       With ALPN, the most basic implementation looks like this:
9296
9297        ### client side
9298        use Net::SSLeay;
9299        use IO::Socket::INET;
9300
9301        Net::SSLeay::initialize();
9302        my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
9303        my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9304        Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9305        Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9306        my $ssl = Net::SSLeay::new($ctx) or die;
9307        Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
9308        Net::SSLeay::connect($ssl);
9309
9310        warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
9311
9312        ### server side
9313        use Net::SSLeay;
9314        use IO::Socket::INET;
9315
9316        Net::SSLeay::initialize();
9317        my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
9318        Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
9319        Net::SSLeay::set_cert_and_key($ctx, "cert.pem", "key.pem");
9320        Net::SSLeay::CTX_set_alpn_select_cb($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9321        my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
9322
9323        while (1) {
9324          my $ssl = Net::SSLeay::new($ctx);
9325          warn("server:waiting for incoming connection...\n");
9326          my $fd = $sock->accept();
9327          Net::SSLeay::set_fd($ssl, $fd->fileno);
9328          Net::SSLeay::accept($ssl);
9329          warn "server:selected=",Net::SSLeay::P_alpn_selected($ssl),"\n";
9330          my $got = Net::SSLeay::read($ssl);
9331          Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
9332          Net::SSLeay::free($ssl);
9333          $fd->close();
9334        }
9335        # check with: openssl s_client -connect localhost:5443 -alpn spdy/3,http/1.1
9336
9337       Advanced approach allows you to implement your own negotiation
9338       algorithm.
9339
9340        #see below documentation for:
9341        Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9342
9343       Detection of ALPN support (works even in older Net::SSLeay versions):
9344
9345        use Net::SSLeay;
9346
9347        if (exists &Net::SSLeay::P_alpn_selected) {
9348          # do ALPN stuff
9349        }
9350
9351       ·   CTX_set_alpn_select_cb
9352
9353           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9354           requires at least openssl-1.0.2
9355
9356           NOTE: You need CTX_set_alpn_select_cb on server side of TLS
9357           connection.
9358
9359           Simple usage - in this case a "common" negotiation algorithm (as
9360           implemented by openssl's function SSL_select_next_proto) is used.
9361
9362            $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $arrayref);
9363            # $ctx - value corresponding to openssl's SSL_CTX structure
9364            # $arrayref - list of accepted protocols - e.g. ['http/2.0', 'http/1.1', 'spdy/3']
9365            #
9366            # returns: 0 on success, 1 on failure
9367
9368           Advanced usage (you probably do not need this):
9369
9370            $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
9371            # $ctx - value corresponding to openssl's SSL_CTX structure
9372            # $perl_callback_function - reference to perl function
9373            # $callback_data - [optional] data to passed to callback function when invoked
9374            #
9375            # returns: 0 on success, 1 on failure
9376
9377            # where callback function looks like
9378            sub alpn_select_cb_invoke {
9379              my ($ssl, $arrayref_proto_list_advertised_by_client, $callback_data) = @_;
9380              # ...
9381              if ($negotiated) {
9382                return 'http/2.0';
9383              } else {
9384                return undef;
9385              }
9386            }
9387
9388           To undefine/clear this callback use:
9389
9390            Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
9391
9392       ·   set_alpn_protos
9393
9394           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9395           requires at least openssl-1.0.2
9396
9397           NOTE: You need set_alpn_protos on client side of TLS connection.
9398
9399           This adds list of supported application layer protocols to
9400           ClientHello message sent by a client.  It advertises the
9401           enumeration of supported protocols:
9402
9403            Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
9404            # returns 0 on success
9405
9406       ·   CTX_set_alpn_protos
9407
9408           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9409           requires at least openssl-1.0.2
9410
9411           NOTE: You need CTX_set_alpn_protos on client side of TLS
9412           connection.
9413
9414           This adds list of supported application layer protocols to
9415           ClientHello message sent by a client.  It advertises the
9416           enumeration of supported protocols:
9417
9418            Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
9419            # returns 0 on success
9420
9421       ·   P_alpn_selected
9422
9423           COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
9424           requires at least openssl-1.0.2
9425
9426           Returns the name of negotiated protocol for given TLS connection
9427           $ssl.
9428
9429            $rv = Net::SSLeay::P_alpn_selected($ssl)
9430            # $ssl - value corresponding to openssl's SSL structure
9431            #
9432            # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
9433
9434       Low level API: DANE Support
9435
9436       OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
9437       Authentication of Named Entities (DANE) Transport Layer Association
9438       within OpenSSL
9439
9440       ·   SSL_get_tlsa_record_byname
9441
9442           COMPATIBILITY: DELETED from net-ssleay, since it is not supported
9443           by OpenSSL
9444
9445           In order to facilitate DANE there is additional interface,
9446           SSL_get_tlsa_record_byname, accepting hostname, port and socket
9447           type that returns packed TLSA record. In order to make it even
9448           easier there is additional SSL_ctrl function that calls
9449           SSL_get_tlsa_record_byname for you. Latter is recommended for
9450           programmers that wish to maintain broader binary compatibility,
9451           e.g. make application work with both 1.0.2 and prior version (in
9452           which case call to SSL_ctrl with new code returning error would
9453           have to be ignored when running with prior version).
9454
9455           Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
9456
9457       Low level API: Other functions
9458
9459       ·   COMP_add_compression_method
9460
9461           Adds the compression method cm with the identifier id to the list
9462           of available compression methods.  This list is globally maintained
9463           for all SSL operations within this application.  It cannot be set
9464           for specific SSL_CTX or SSL objects.
9465
9466            my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
9467            # $id - (integer) compression method id
9468            #       0 to 63:    methods defined by the IETF
9469            #       64 to 192:  external party methods assigned by IANA
9470            #       193 to 255: reserved for private use
9471            #
9472            # $cm - value corresponding to openssl's COMP_METHOD structure
9473            #
9474            # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
9475
9476           Check openssl doc
9477           <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
9478
9479       ·   DH_free
9480
9481           Frees the DH structure and its components. The values are erased
9482           before the memory is returned to the system.
9483
9484            Net::SSLeay::DH_free($dh);
9485            # $dh - value corresponding to openssl's DH structure
9486            #
9487            # returns: no return value
9488
9489           Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
9490
9491       ·   FIPS_mode_set
9492
9493           Enable or disable FIPS mode in a FIPS capable OpenSSL.
9494
9495            Net::SSLeay:: FIPS_mode_set($enable);
9496            # $enable - (integer) 1 to enable, 0 to disable
9497
9498       Low level API: EC related functions
9499
9500       ·   CTX_set_tmp_ecdh
9501
9502           TBA
9503
9504       ·   EC_KEY_free
9505
9506           TBA
9507
9508       ·   EC_KEY_new_by_curve_name
9509
9510           TBA
9511
9512       ·   EC_KEY_generate_key
9513
9514           Generates a EC key and returns it in a newly allocated EC_KEY
9515           structure.  The EC key then can be used to create a PKEY which can
9516           be used in calls like X509_set_pubkey.
9517
9518            my $key = Net::SSLeay::EVP_PKEY_new();
9519            my $ec  = Net::SSLeay::EC_KEY_generate_key($curve);
9520            Net::SSLeay::EVP_PKEY_assign_EC_KEY($key,$ec);
9521
9522            # $curve - curve name like 'secp521r1' or the matching Id (integer) of the curve
9523            #
9524            # returns: value corresponding to openssl's EC_KEY structure (0 on failure)
9525
9526           This function has no equivalent in OpenSSL but combines multiple
9527           OpenSSL functions for an easier interface.
9528
9529       ·   CTX_set_ecdh_auto, set_ecdh_auto
9530
9531           These functions enable or disable the automatic curve selection on
9532           the server side by calling SSL_CTX_set_ecdh_auto or
9533           SSL_set_ecdh_auto respectively.  If enabled the highest preference
9534           curve is automatically used for ECDH temporary keys used during key
9535           exchange.  This function is no longer available for OpenSSL 1.1.0
9536           or higher.
9537
9538             Net::SSLeay::CTX_set_ecdh_auto($ctx,1);
9539             Net::SSLeay::set_ecdh_auto($ssl,1);
9540
9541       ·   CTX_set1_curves_list, set1_curves_list
9542
9543           These functions set the supported curves (in order of preference)
9544           by calling SSL_CTX_set1_curves_list or SSL_set1_curves_list
9545           respectively.  For a TLS client these curves are offered to the
9546           server in the supported curves extension while on the server side
9547           these are used to determine the shared curve.  These functions are
9548           only available since OpenSSL 1.1.0.
9549
9550             Net::SSLeay::CTX_set1_curves_list($ctx,"P-521:P-384:P-256");
9551             Net::SSLeay::set1_curves_list($ssl,"P-521:P-384:P-256");
9552
9553       ·   CTX_set1_groups_list, set1_groups_list
9554
9555           These functions set the supported groups (in order of preference)
9556           by calling SSL_CTX_set1_groups_list or SSL_set1_groups_list
9557           respectively.  This is practically the same as CTX_set1_curves_list
9558           and set1_curves_list except that all DH groups can be given as
9559           supported by TLS 1.3.  These functions are only available since
9560           OpenSSL 1.1.1.
9561
9562             Net::SSLeay::CTX_set1_groups_list($ctx,"P-521:P-384:P-256");
9563             Net::SSLeay::set1_groups_list($ssl,"P-521:P-384:P-256");
9564
9565   Constants
9566       There are many openssl constants available in Net::SSLeay. You can use
9567       them like this:
9568
9569        use Net::SSLeay;
9570        print &Net::SSLeay::NID_commonName;
9571        #or
9572        print Net::SSLeay::NID_commonName();
9573
9574       Or you can import them and use:
9575
9576        use Net::SSLeay qw/NID_commonName/;
9577        print &NID_commonName;
9578        #or
9579        print NID_commonName();
9580        #or
9581        print NID_commonName;
9582
9583       The constants names are derived from openssl constants, however
9584       constants starting with "SSL_" prefix have name with "SSL_" part
9585       stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
9586       "Net::SSleay::OP_ALL"
9587
9588       The list of all available constant names:
9589
9590        ASN1_STRFLGS_ESC_CTRL           NID_netscape                              R_UNKNOWN_REMOTE_ERROR_TYPE
9591        ASN1_STRFLGS_ESC_MSB            NID_netscape_base_url                     R_UNKNOWN_STATE
9592        ASN1_STRFLGS_ESC_QUOTE          NID_netscape_ca_policy_url                R_X509_LIB
9593        ASN1_STRFLGS_RFC2253            NID_netscape_ca_revocation_url            SENT_SHUTDOWN
9594        CB_ACCEPT_EXIT                  NID_netscape_cert_extension               SESSION_ASN1_VERSION
9595        CB_ACCEPT_LOOP                  NID_netscape_cert_sequence                SESS_CACHE_BOTH
9596        CB_ALERT                        NID_netscape_cert_type                    SESS_CACHE_CLIENT
9597        CB_CONNECT_EXIT                 NID_netscape_comment                      SESS_CACHE_NO_AUTO_CLEAR
9598        CB_CONNECT_LOOP                 NID_netscape_data_type                    SESS_CACHE_NO_INTERNAL
9599        CB_EXIT                         NID_netscape_renewal_url                  SESS_CACHE_NO_INTERNAL_LOOKUP
9600        CB_HANDSHAKE_DONE               NID_netscape_revocation_url               SESS_CACHE_NO_INTERNAL_STORE
9601        CB_HANDSHAKE_START              NID_netscape_ssl_server_name              SESS_CACHE_OFF
9602        CB_LOOP                         NID_ns_sgc                                SESS_CACHE_SERVER
9603        CB_READ                         NID_organizationName                      SSL3_VERSION
9604        CB_READ_ALERT                   NID_organizationalUnitName                SSLEAY_BUILT_ON
9605        CB_WRITE                        NID_pbeWithMD2AndDES_CBC                  SSLEAY_CFLAGS
9606        CB_WRITE_ALERT                  NID_pbeWithMD2AndRC2_CBC                  SSLEAY_DIR
9607        ERROR_NONE                      NID_pbeWithMD5AndCast5_CBC                SSLEAY_PLATFORM
9608        ERROR_SSL                       NID_pbeWithMD5AndDES_CBC                  SSLEAY_VERSION
9609        ERROR_SYSCALL                   NID_pbeWithMD5AndRC2_CBC                  ST_ACCEPT
9610        ERROR_WANT_ACCEPT               NID_pbeWithSHA1AndDES_CBC                 ST_BEFORE
9611        ERROR_WANT_CONNECT              NID_pbeWithSHA1AndRC2_CBC                 ST_CONNECT
9612        ERROR_WANT_READ                 NID_pbe_WithSHA1And128BitRC2_CBC          ST_INIT
9613        ERROR_WANT_WRITE                NID_pbe_WithSHA1And128BitRC4              ST_OK
9614        ERROR_WANT_X509_LOOKUP          NID_pbe_WithSHA1And2_Key_TripleDES_CBC    ST_READ_BODY
9615        ERROR_ZERO_RETURN               NID_pbe_WithSHA1And3_Key_TripleDES_CBC    ST_READ_HEADER
9616        EVP_PKS_DSA                     NID_pbe_WithSHA1And40BitRC2_CBC           TLS1_1_VERSION
9617        EVP_PKS_EC                      NID_pbe_WithSHA1And40BitRC4               TLS1_2_VERSION
9618        EVP_PKS_RSA                     NID_pbes2                                 TLS1_3_VERSION
9619        EVP_PKT_ENC                     NID_pbmac1                                TLS1_VERSION
9620        EVP_PKT_EXCH                    NID_pkcs                                  TLSEXT_STATUSTYPE_ocsp
9621        EVP_PKT_EXP                     NID_pkcs3                                 VERIFY_CLIENT_ONCE
9622        EVP_PKT_SIGN                    NID_pkcs7                                 VERIFY_FAIL_IF_NO_PEER_CERT
9623        EVP_PK_DH                       NID_pkcs7_data                            VERIFY_NONE
9624        EVP_PK_DSA                      NID_pkcs7_digest                          VERIFY_PEER
9625        EVP_PK_EC                       NID_pkcs7_encrypted                       VERIFY_POST_HANDSHAKE
9626        EVP_PK_RSA                      NID_pkcs7_enveloped                       V_OCSP_CERTSTATUS_GOOD
9627        FILETYPE_ASN1                   NID_pkcs7_signed                          V_OCSP_CERTSTATUS_REVOKED
9628        FILETYPE_PEM                    NID_pkcs7_signedAndEnveloped              V_OCSP_CERTSTATUS_UNKNOWN
9629        F_CLIENT_CERTIFICATE            NID_pkcs8ShroudedKeyBag                   WRITING
9630        F_CLIENT_HELLO                  NID_pkcs9                                 X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
9631        F_CLIENT_MASTER_KEY             NID_pkcs9_challengePassword               X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
9632        F_D2I_SSL_SESSION               NID_pkcs9_contentType                     X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
9633        F_GET_CLIENT_FINISHED           NID_pkcs9_countersignature                X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
9634        F_GET_CLIENT_HELLO              NID_pkcs9_emailAddress                    X509_CHECK_FLAG_NO_WILDCARDS
9635        F_GET_CLIENT_MASTER_KEY         NID_pkcs9_extCertAttributes               X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
9636        F_GET_SERVER_FINISHED           NID_pkcs9_messageDigest                   X509_FILETYPE_ASN1
9637        F_GET_SERVER_HELLO              NID_pkcs9_signingTime                     X509_FILETYPE_DEFAULT
9638        F_GET_SERVER_VERIFY             NID_pkcs9_unstructuredAddress             X509_FILETYPE_PEM
9639        F_I2D_SSL_SESSION               NID_pkcs9_unstructuredName                X509_LOOKUP
9640        F_READ_N                        NID_private_key_usage_period              X509_PURPOSE_ANY
9641        F_REQUEST_CERTIFICATE           NID_rc2_40_cbc                            X509_PURPOSE_CRL_SIGN
9642        F_SERVER_HELLO                  NID_rc2_64_cbc                            X509_PURPOSE_NS_SSL_SERVER
9643        F_SSL_CERT_NEW                  NID_rc2_cbc                               X509_PURPOSE_OCSP_HELPER
9644        F_SSL_GET_NEW_SESSION           NID_rc2_cfb64                             X509_PURPOSE_SMIME_ENCRYPT
9645        F_SSL_NEW                       NID_rc2_ecb                               X509_PURPOSE_SMIME_SIGN
9646        F_SSL_READ                      NID_rc2_ofb64                             X509_PURPOSE_SSL_CLIENT
9647        F_SSL_RSA_PRIVATE_DECRYPT       NID_rc4                                   X509_PURPOSE_SSL_SERVER
9648        F_SSL_RSA_PUBLIC_ENCRYPT        NID_rc4_40                                X509_PURPOSE_TIMESTAMP_SIGN
9649        F_SSL_SESSION_NEW               NID_rc5_cbc                               X509_TRUST_COMPAT
9650        F_SSL_SESSION_PRINT_FP          NID_rc5_cfb64                             X509_TRUST_EMAIL
9651        F_SSL_SET_FD                    NID_rc5_ecb                               X509_TRUST_OBJECT_SIGN
9652        F_SSL_SET_RFD                   NID_rc5_ofb64                             X509_TRUST_OCSP_REQUEST
9653        F_SSL_SET_WFD                   NID_ripemd160                             X509_TRUST_OCSP_SIGN
9654        F_SSL_USE_CERTIFICATE           NID_ripemd160WithRSA                      X509_TRUST_SSL_CLIENT
9655        F_SSL_USE_CERTIFICATE_ASN1      NID_rle_compression                       X509_TRUST_SSL_SERVER
9656        F_SSL_USE_CERTIFICATE_FILE      NID_rsa                                   X509_TRUST_TSA
9657        F_SSL_USE_PRIVATEKEY            NID_rsaEncryption                         X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH
9658        F_SSL_USE_PRIVATEKEY_ASN1       NID_rsadsi                                X509_V_ERR_AKID_SKID_MISMATCH
9659        F_SSL_USE_PRIVATEKEY_FILE       NID_safeContentsBag                       X509_V_ERR_APPLICATION_VERIFICATION
9660        F_SSL_USE_RSAPRIVATEKEY         NID_sdsiCertificate                       X509_V_ERR_CA_KEY_TOO_SMALL
9661        F_SSL_USE_RSAPRIVATEKEY_ASN1    NID_secretBag                             X509_V_ERR_CA_MD_TOO_WEAK
9662        F_SSL_USE_RSAPRIVATEKEY_FILE    NID_serialNumber                          X509_V_ERR_CERT_CHAIN_TOO_LONG
9663        F_WRITE_PENDING                 NID_server_auth                           X509_V_ERR_CERT_HAS_EXPIRED
9664        GEN_DIRNAME                     NID_sha                                   X509_V_ERR_CERT_NOT_YET_VALID
9665        GEN_DNS                         NID_sha1                                  X509_V_ERR_CERT_REJECTED
9666        GEN_EDIPARTY                    NID_sha1WithRSA                           X509_V_ERR_CERT_REVOKED
9667        GEN_EMAIL                       NID_sha1WithRSAEncryption                 X509_V_ERR_CERT_SIGNATURE_FAILURE
9668        GEN_IPADD                       NID_shaWithRSAEncryption                  X509_V_ERR_CERT_UNTRUSTED
9669        GEN_OTHERNAME                   NID_stateOrProvinceName                   X509_V_ERR_CRL_HAS_EXPIRED
9670        GEN_RID                         NID_subject_alt_name                      X509_V_ERR_CRL_NOT_YET_VALID
9671        GEN_URI                         NID_subject_key_identifier                X509_V_ERR_CRL_PATH_VALIDATION_ERROR
9672        GEN_X400                        NID_surname                               X509_V_ERR_CRL_SIGNATURE_FAILURE
9673        LIBRESSL_VERSION_NUMBER         NID_sxnet                                 X509_V_ERR_DANE_NO_MATCH
9674        MBSTRING_ASC                    NID_time_stamp                            X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
9675        MBSTRING_BMP                    NID_title                                 X509_V_ERR_DIFFERENT_CRL_SCOPE
9676        MBSTRING_FLAG                   NID_undef                                 X509_V_ERR_EE_KEY_TOO_SMALL
9677        MBSTRING_UNIV                   NID_uniqueIdentifier                      X509_V_ERR_EMAIL_MISMATCH
9678        MBSTRING_UTF8                   NID_x509Certificate                       X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD
9679        MIN_RSA_MODULUS_LENGTH_IN_BYTES NID_x509Crl                               X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD
9680        MODE_ACCEPT_MOVING_WRITE_BUFFER NID_zlib_compression                      X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD
9681        MODE_AUTO_RETRY                 NOTHING                                   X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD
9682        MODE_ENABLE_PARTIAL_WRITE       OCSP_RESPONSE_STATUS_INTERNALERROR        X509_V_ERR_EXCLUDED_VIOLATION
9683        MODE_RELEASE_BUFFERS            OCSP_RESPONSE_STATUS_MALFORMEDREQUEST     X509_V_ERR_HOSTNAME_MISMATCH
9684        NID_OCSP_sign                   OCSP_RESPONSE_STATUS_SIGREQUIRED          X509_V_ERR_INVALID_CA
9685        NID_SMIMECapabilities           OCSP_RESPONSE_STATUS_SUCCESSFUL           X509_V_ERR_INVALID_CALL
9686        NID_X500                        OCSP_RESPONSE_STATUS_TRYLATER             X509_V_ERR_INVALID_EXTENSION
9687        NID_X509                        OCSP_RESPONSE_STATUS_UNAUTHORIZED         X509_V_ERR_INVALID_NON_CA
9688        NID_ad_OCSP                     OPENSSL_BUILT_ON                          X509_V_ERR_INVALID_POLICY_EXTENSION
9689        NID_ad_ca_issuers               OPENSSL_CFLAGS                            X509_V_ERR_INVALID_PURPOSE
9690        NID_algorithm                   OPENSSL_DIR                               X509_V_ERR_IP_ADDRESS_MISMATCH
9691        NID_authority_key_identifier    OPENSSL_ENGINES_DIR                       X509_V_ERR_KEYUSAGE_NO_CERTSIGN
9692        NID_basic_constraints           OPENSSL_PLATFORM                          X509_V_ERR_KEYUSAGE_NO_CRL_SIGN
9693        NID_bf_cbc                      OPENSSL_VERSION                           X509_V_ERR_KEYUSAGE_NO_DIGITAL_SIGNATURE
9694        NID_bf_cfb64                    OPENSSL_VERSION_NUMBER                    X509_V_ERR_NO_EXPLICIT_POLICY
9695        NID_bf_ecb                      OP_ALL                                    X509_V_ERR_NO_VALID_SCTS
9696        NID_bf_ofb64                    OP_ALLOW_NO_DHE_KEX                       X509_V_ERR_OCSP_CERT_UNKNOWN
9697        NID_cast5_cbc                   OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION      X509_V_ERR_OCSP_VERIFY_FAILED
9698        NID_cast5_cfb64                 OP_CIPHER_SERVER_PREFERENCE               X509_V_ERR_OCSP_VERIFY_NEEDED
9699        NID_cast5_ecb                   OP_CISCO_ANYCONNECT                       X509_V_ERR_OUT_OF_MEM
9700        NID_cast5_ofb64                 OP_COOKIE_EXCHANGE                        X509_V_ERR_PATH_LENGTH_EXCEEDED
9701        NID_certBag                     OP_CRYPTOPRO_TLSEXT_BUG                   X509_V_ERR_PATH_LOOP
9702        NID_certificate_policies        OP_DONT_INSERT_EMPTY_FRAGMENTS            X509_V_ERR_PERMITTED_VIOLATION
9703        NID_client_auth                 OP_ENABLE_MIDDLEBOX_COMPAT                X509_V_ERR_PROXY_CERTIFICATES_NOT_ALLOWED
9704        NID_code_sign                   OP_EPHEMERAL_RSA                          X509_V_ERR_PROXY_PATH_LENGTH_EXCEEDED
9705        NID_commonName                  OP_LEGACY_SERVER_CONNECT                  X509_V_ERR_PROXY_SUBJECT_NAME_VIOLATION
9706        NID_countryName                 OP_MICROSOFT_BIG_SSLV3_BUFFER             X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN
9707        NID_crlBag                      OP_MICROSOFT_SESS_ID_BUG                  X509_V_ERR_STORE_LOOKUP
9708        NID_crl_distribution_points     OP_MSIE_SSLV2_RSA_PADDING                 X509_V_ERR_SUBJECT_ISSUER_MISMATCH
9709        NID_crl_number                  OP_NETSCAPE_CA_DN_BUG                     X509_V_ERR_SUBTREE_MINMAX
9710        NID_crl_reason                  OP_NETSCAPE_CHALLENGE_BUG                 X509_V_ERR_SUITE_B_CANNOT_SIGN_P_384_WITH_P_256
9711        NID_delta_crl                   OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG        X509_V_ERR_SUITE_B_INVALID_ALGORITHM
9712        NID_des_cbc                     OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG       X509_V_ERR_SUITE_B_INVALID_CURVE
9713        NID_des_cfb64                   OP_NON_EXPORT_FIRST                       X509_V_ERR_SUITE_B_INVALID_SIGNATURE_ALGORITHM
9714        NID_des_ecb                     OP_NO_ANTI_REPLAY                         X509_V_ERR_SUITE_B_INVALID_VERSION
9715        NID_des_ede                     OP_NO_CLIENT_RENEGOTIATION                X509_V_ERR_SUITE_B_LOS_NOT_ALLOWED
9716        NID_des_ede3                    OP_NO_COMPRESSION                         X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY
9717        NID_des_ede3_cbc                OP_NO_ENCRYPT_THEN_MAC                    X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE
9718        NID_des_ede3_cfb64              OP_NO_QUERY_MTU                           X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE
9719        NID_des_ede3_ofb64              OP_NO_RENEGOTIATION                       X509_V_ERR_UNABLE_TO_GET_CRL
9720        NID_des_ede_cbc                 OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION X509_V_ERR_UNABLE_TO_GET_CRL_ISSUER
9721        NID_des_ede_cfb64               OP_NO_SSL_MASK                            X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT
9722        NID_des_ede_ofb64               OP_NO_SSLv2                               X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
9723        NID_des_ofb64                   OP_NO_SSLv3                               X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE
9724        NID_description                 OP_NO_TICKET                              X509_V_ERR_UNHANDLED_CRITICAL_CRL_EXTENSION
9725        NID_desx_cbc                    OP_NO_TLSv1                               X509_V_ERR_UNHANDLED_CRITICAL_EXTENSION
9726        NID_dhKeyAgreement              OP_NO_TLSv1_1                             X509_V_ERR_UNNESTED_RESOURCE
9727        NID_dnQualifier                 OP_NO_TLSv1_2                             X509_V_ERR_UNSPECIFIED
9728        NID_dsa                         OP_NO_TLSv1_3                             X509_V_ERR_UNSUPPORTED_CONSTRAINT_SYNTAX
9729        NID_dsaWithSHA                  OP_PKCS1_CHECK_1                          X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE
9730        NID_dsaWithSHA1                 OP_PKCS1_CHECK_2                          X509_V_ERR_UNSUPPORTED_EXTENSION_FEATURE
9731        NID_dsaWithSHA1_2               OP_PRIORITIZE_CHACHA                      X509_V_ERR_UNSUPPORTED_NAME_SYNTAX
9732        NID_dsa_2                       OP_SAFARI_ECDHE_ECDSA_BUG                 X509_V_FLAG_ALLOW_PROXY_CERTS
9733        NID_email_protect               OP_SINGLE_DH_USE                          X509_V_FLAG_CB_ISSUER_CHECK
9734        NID_ext_key_usage               OP_SINGLE_ECDH_USE                        X509_V_FLAG_CHECK_SS_SIGNATURE
9735        NID_ext_req                     OP_SSLEAY_080_CLIENT_DH_BUG               X509_V_FLAG_CRL_CHECK
9736        NID_friendlyName                OP_SSLREF2_REUSE_CERT_TYPE_BUG            X509_V_FLAG_CRL_CHECK_ALL
9737        NID_givenName                   OP_TLSEXT_PADDING                         X509_V_FLAG_EXPLICIT_POLICY
9738        NID_hmacWithSHA1                OP_TLS_BLOCK_PADDING_BUG                  X509_V_FLAG_EXTENDED_CRL_SUPPORT
9739        NID_id_ad                       OP_TLS_D5_BUG                             X509_V_FLAG_IGNORE_CRITICAL
9740        NID_id_ce                       OP_TLS_ROLLBACK_BUG                       X509_V_FLAG_INHIBIT_ANY
9741        NID_id_kp                       READING                                   X509_V_FLAG_INHIBIT_MAP
9742        NID_id_pbkdf2                   RECEIVED_SHUTDOWN                         X509_V_FLAG_NOTIFY_POLICY
9743        NID_id_pe                       RSA_3                                     X509_V_FLAG_NO_ALT_CHAINS
9744        NID_id_pkix                     RSA_F4                                    X509_V_FLAG_NO_CHECK_TIME
9745        NID_id_qt_cps                   R_BAD_AUTHENTICATION_TYPE                 X509_V_FLAG_PARTIAL_CHAIN
9746        NID_id_qt_unotice               R_BAD_CHECKSUM                            X509_V_FLAG_POLICY_CHECK
9747        NID_idea_cbc                    R_BAD_MAC_DECODE                          X509_V_FLAG_POLICY_MASK
9748        NID_idea_cfb64                  R_BAD_RESPONSE_ARGUMENT                   X509_V_FLAG_SUITEB_128_LOS
9749        NID_idea_ecb                    R_BAD_SSL_FILETYPE                        X509_V_FLAG_SUITEB_128_LOS_ONLY
9750        NID_idea_ofb64                  R_BAD_SSL_SESSION_ID_LENGTH               X509_V_FLAG_SUITEB_192_LOS
9751        NID_info_access                 R_BAD_STATE                               X509_V_FLAG_TRUSTED_FIRST
9752        NID_initials                    R_BAD_WRITE_RETRY                         X509_V_FLAG_USE_CHECK_TIME
9753        NID_invalidity_date             R_CHALLENGE_IS_DIFFERENT                  X509_V_FLAG_USE_DELTAS
9754        NID_issuer_alt_name             R_CIPHER_TABLE_SRC_ERROR                  X509_V_FLAG_X509_STRICT
9755        NID_keyBag                      R_INVALID_CHALLENGE_LENGTH                X509_V_OK
9756        NID_key_usage                   R_NO_CERTIFICATE_SET                      XN_FLAG_COMPAT
9757        NID_localKeyID                  R_NO_CERTIFICATE_SPECIFIED                XN_FLAG_DN_REV
9758        NID_localityName                R_NO_CIPHER_LIST                          XN_FLAG_DUMP_UNKNOWN_FIELDS
9759        NID_md2                         R_NO_CIPHER_MATCH                         XN_FLAG_FN_ALIGN
9760        NID_md2WithRSAEncryption        R_NO_PRIVATEKEY                           XN_FLAG_FN_LN
9761        NID_md5                         R_NO_PUBLICKEY                            XN_FLAG_FN_MASK
9762        NID_md5WithRSA                  R_NULL_SSL_CTX                            XN_FLAG_FN_NONE
9763        NID_md5WithRSAEncryption        R_PEER_DID_NOT_RETURN_A_CERTIFICATE       XN_FLAG_FN_OID
9764        NID_md5_sha1                    R_PEER_ERROR                              XN_FLAG_FN_SN
9765        NID_mdc2                        R_PEER_ERROR_CERTIFICATE                  XN_FLAG_MULTILINE
9766        NID_mdc2WithRSA                 R_PEER_ERROR_NO_CIPHER                    XN_FLAG_ONELINE
9767        NID_ms_code_com                 R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE XN_FLAG_RFC2253
9768        NID_ms_code_ind                 R_PUBLIC_KEY_ENCRYPT_ERROR                XN_FLAG_SEP_COMMA_PLUS
9769        NID_ms_ctl_sign                 R_PUBLIC_KEY_IS_NOT_RSA                   XN_FLAG_SEP_CPLUS_SPC
9770        NID_ms_efs                      R_READ_WRONG_PACKET_TYPE                  XN_FLAG_SEP_MASK
9771        NID_ms_ext_req                  R_SHORT_READ                              XN_FLAG_SEP_MULTILINE
9772        NID_ms_sgc                      R_SSL_SESSION_ID_IS_DIFFERENT             XN_FLAG_SEP_SPLUS_SPC
9773        NID_name                        R_UNABLE_TO_EXTRACT_PUBLIC_KEY            XN_FLAG_SPC_EQ
9774
9775   INTERNAL ONLY functions (do not use these)
9776       The following functions are not intended for use from outside of
9777       Net::SSLeay module.  They might be removed, renamed or changed without
9778       prior notice in future version.
9779
9780       Simply DO NOT USE THEM!
9781
9782       ·   hello
9783
9784       ·   blength
9785
9786       ·   constant
9787

EXAMPLES

9789       One very good example to look at is the implementation of "sslcat()" in
9790       the "SSLeay.pm" file.
9791
9792       The following is a simple SSLeay client (with too little error checking
9793       :-(
9794
9795           #!/usr/bin/perl
9796           use Socket;
9797           use Net::SSLeay qw(die_now die_if_ssl_error) ;
9798           Net::SSLeay::load_error_strings();
9799           Net::SSLeay::SSLeay_add_ssl_algorithms();
9800           Net::SSLeay::randomize();
9801
9802           ($dest_serv, $port, $msg) = @ARGV;      # Read command line
9803           $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
9804           $dest_ip = gethostbyname ($dest_serv);
9805           $dest_serv_params  = sockaddr_in($port, $dest_ip);
9806
9807           socket  (S, &AF_INET, &SOCK_STREAM, 0)  or die "socket: $!";
9808           connect (S, $dest_serv_params)          or die "connect: $!";
9809           select  (S); $| = 1; select (STDOUT);   # Eliminate STDIO buffering
9810
9811           # The network connection is now open, lets fire up SSL
9812
9813           $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
9814           Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9815                or die_if_ssl_error("ssl ctx set options");
9816           $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
9817           Net::SSLeay::set_fd($ssl, fileno(S));   # Must use fileno
9818           $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
9819           print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9820
9821           # Exchange data
9822
9823           $res = Net::SSLeay::write($ssl, $msg);  # Perl knows how long $msg is
9824           die_if_ssl_error("ssl write");
9825           CORE::shutdown S, 1;  # Half close --> No more output, sends EOF to server
9826           $got = Net::SSLeay::read($ssl);         # Perl returns undef on failure
9827           die_if_ssl_error("ssl read");
9828           print $got;
9829
9830           Net::SSLeay::free ($ssl);               # Tear down connection
9831           Net::SSLeay::CTX_free ($ctx);
9832           close S;
9833
9834       The following is a simple SSLeay echo server (non forking):
9835
9836           #!/usr/bin/perl -w
9837           use Socket;
9838           use Net::SSLeay qw(die_now die_if_ssl_error);
9839           Net::SSLeay::load_error_strings();
9840           Net::SSLeay::SSLeay_add_ssl_algorithms();
9841           Net::SSLeay::randomize();
9842
9843           $our_ip = "\0\0\0\0"; # Bind to all interfaces
9844           $port = 1235;
9845           $sockaddr_template = 'S n a4 x8';
9846           $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
9847
9848           socket (S, &AF_INET, &SOCK_STREAM, 0)  or die "socket: $!";
9849           bind (S, $our_serv_params)             or die "bind:   $!";
9850           listen (S, 5)                          or die "listen: $!";
9851           $ctx = Net::SSLeay::CTX_new ()         or die_now("CTX_new ($ctx): $!");
9852           Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9853                or die_if_ssl_error("ssl ctx set options");
9854
9855           # Following will ask password unless private key is not encrypted
9856           Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
9857                                                    &Net::SSLeay::FILETYPE_PEM);
9858           die_if_ssl_error("private key");
9859           Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
9860                                                  &Net::SSLeay::FILETYPE_PEM);
9861           die_if_ssl_error("certificate");
9862
9863           while (1) {
9864               print "Accepting connections...\n";
9865               ($addr = accept (NS, S))           or die "accept: $!";
9866               select (NS); $| = 1; select (STDOUT);  # Piping hot!
9867
9868               ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
9869               @inetaddr = unpack('C4',$client_ip);
9870               print "$af connection from " .
9871               join ('.', @inetaddr) . ":$client_port\n";
9872
9873               # We now have a network connection, lets fire up SSLeay...
9874
9875               $ssl = Net::SSLeay::new($ctx)      or die_now("SSL_new ($ssl): $!");
9876               Net::SSLeay::set_fd($ssl, fileno(NS));
9877
9878               $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
9879               print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9880
9881               # Connected. Exchange some data.
9882
9883               $got = Net::SSLeay::read($ssl);     # Returns undef on fail
9884               die_if_ssl_error("ssl read");
9885               print "Got `$got' (" . length ($got) . " chars)\n";
9886
9887               Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
9888               die_if_ssl_error("ssl write");
9889
9890               Net::SSLeay::free ($ssl);           # Tear down connection
9891               close NS;
9892           }
9893
9894       Yet another echo server. This one runs from "/etc/inetd.conf" so it
9895       avoids all the socket code overhead. Only caveat is opening an rsa key
9896       file - it had better be without any encryption or else it will not know
9897       where to ask for the password. Note how "STDIN" and "STDOUT" are wired
9898       to SSL.
9899
9900           #!/usr/bin/perl
9901           # /etc/inetd.conf
9902           #    ssltst stream tcp nowait root /path/to/server.pl server.pl
9903           # /etc/services
9904           #    ssltst         1234/tcp
9905
9906           use Net::SSLeay qw(die_now die_if_ssl_error);
9907           Net::SSLeay::load_error_strings();
9908           Net::SSLeay::SSLeay_add_ssl_algorithms();
9909           Net::SSLeay::randomize();
9910
9911           chdir '/key/dir' or die "chdir: $!";
9912           $| = 1;  # Piping hot!
9913           open LOG, ">>/dev/console" or die "Can't open log file $!";
9914           select LOG; print "server.pl started\n";
9915
9916           $ctx = Net::SSLeay::CTX_new()     or die_now "CTX_new ($ctx) ($!)";
9917           $ssl = Net::SSLeay::new($ctx)     or die_now "new ($ssl) ($!)";
9918           Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
9919                and die_if_ssl_error("ssl set options");
9920
9921           # We get already open network connection from inetd, now we just
9922           # need to attach SSLeay to STDIN and STDOUT
9923           Net::SSLeay::set_rfd($ssl, fileno(STDIN));
9924           Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
9925
9926           Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
9927                                                Net::SSLeay::FILETYPE_PEM);
9928           die_if_ssl_error("private key");
9929           Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
9930                                              Net::SSLeay::FILETYPE_PEM);
9931           die_if_ssl_error("certificate");
9932
9933           Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
9934           print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9935
9936           $got = Net::SSLeay::read($ssl);
9937           die_if_ssl_error("ssl read");
9938           print "Got `$got' (" . length ($got) . " chars)\n";
9939
9940           Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
9941           die_if_ssl_error("ssl write");
9942
9943           Net::SSLeay::free ($ssl);         # Tear down the connection
9944           Net::SSLeay::CTX_free ($ctx);
9945           close LOG;
9946
9947       There are also a number of example/test programs in the examples
9948       directory:
9949
9950           sslecho.pl   -  A simple server, not unlike the one above
9951           minicli.pl   -  Implements a client using low level SSLeay routines
9952           sslcat.pl    -  Demonstrates using high level sslcat utility function
9953           get_page.pl  -  Is a utility for getting html pages from secure servers
9954           callback.pl  -  Demonstrates certificate verification and callback usage
9955           stdio_bulk.pl       - Does SSL over Unix pipes
9956           ssl-inetd-serv.pl   - SSL server that can be invoked from inetd.conf
9957           httpd-proxy-snif.pl - Utility that allows you to see how a browser
9958                                 sends https request to given server and what reply
9959                                 it gets back (very educative :-)
9960           makecert.pl  -  Creates a self signed cert (does not use this module)
9961

INSTALLATION

9963       See README and README.* in the distribution directory for installation
9964       guidance on a variety of platforms.
9965

LIMITATIONS

9967       "Net::SSLeay::read()" uses an internal buffer of 32KB, thus no single
9968       read will return more. In practice one read returns much less, usually
9969       as much as fits in one network packet. To work around this, you should
9970       use a loop like this:
9971
9972           $reply = '';
9973           while ($got = Net::SSLeay::read($ssl)) {
9974               last if print_errs('SSL_read');
9975               $reply .= $got;
9976           }
9977
9978       Although there is no built-in limit in "Net::SSLeay::write()", the
9979       network packet size limitation applies here as well, thus use:
9980
9981           $written = 0;
9982
9983           while ($written < length($message)) {
9984               $written += Net::SSLeay::write($ssl, substr($message, $written));
9985               last if print_errs('SSL_write');
9986           }
9987
9988       Or alternatively you can just use the following convenience functions:
9989
9990           Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
9991           $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
9992

KNOWN BUGS AND CAVEATS

9994       An OpenSSL bug CVE-2015-0290 "OpenSSL Multiblock Corrupted Pointer
9995       Issue" can cause POST requests of over 90kB to fail or crash. This bug
9996       is reported to be fixed in OpenSSL 1.0.2a.
9997
9998       Autoloader emits a
9999
10000           Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
10001
10002       warning if die_if_ssl_error is made autoloadable. If you figure out
10003       why, drop me a line.
10004
10005       Callback set using "SSL_set_verify()" does not appear to work. This may
10006       well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
10007       using "SSL_CTX_set_verify()" instead and do not be surprised if even
10008       this stops working in future versions.
10009
10010       Callback and certificate verification stuff is generally too little
10011       tested.
10012
10013       Random numbers are not initialized randomly enough, especially if you
10014       do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
10015       platforms - but it's been suggested that cryptorand daemon from the
10016       SUNski package solves this). In this case you should investigate third
10017       party software that can emulate these devices, e.g. by way of a named
10018       pipe to some program.
10019
10020       Another gotcha with random number initialization is randomness
10021       depletion. This phenomenon, which has been extensively discussed in
10022       OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
10023       to block if you use "/dev/random" or to operate insecurely if you use
10024       "/dev/urandom". What happens is that when too much randomness is drawn
10025       from the operating system's randomness pool then randomness can
10026       temporarily be unavailable. "/dev/random" solves this problem by
10027       waiting until enough randomness can be gathered - and this can take a
10028       long time since blocking reduces activity in the machine and less
10029       activity provides less random events: a vicious circle.  "/dev/urandom"
10030       solves this dilemma more pragmatically by simply returning predictable
10031       "random" numbers. Some" /dev/urandom" emulation software however
10032       actually seems to implement "/dev/random" semantics. Caveat emptor.
10033
10034       I've been pointed to two such daemons by Mik Firestone
10035       <mik@@speed.stdio._com> who has used them on Solaris 8:
10036
10037       1.  Entropy Gathering Daemon (EGD) at
10038           <http://www.lothar.com/tech/crypto/>
10039
10040       2.  Pseudo-random number generating daemon (PRNGD) at
10041           <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10042
10043       If you are using the low level API functions to communicate with other
10044       SSL implementations, you would do well to call
10045
10046           Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
10047                or die_if_ssl_error("ssl ctx set options");
10048
10049       to cope with some well know bugs in some other SSL implementations. The
10050       high level API functions always set all known compatibility options.
10051
10052       Sometimes "sslcat()" (and the high level HTTPS functions that build on
10053       it) is too fast in signaling the EOF to legacy HTTPS servers. This
10054       causes the server to return empty page. To work around this problem you
10055       can set the global variable
10056
10057           $Net::SSLeay::slowly = 1;   # Add sleep so broken servers can keep up
10058
10059       HTTP/1.1 is not supported. Specifically this module does not know to
10060       issue or serve multiple http requests per connection. This is a serious
10061       shortcoming, but using the SSL session cache on your server helps to
10062       alleviate the CPU load somewhat.
10063
10064       As of version 1.09 many newer OpenSSL auxiliary functions were added
10065       (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
10066       Unfortunately I have not had any opportunity to test these. Some of
10067       them are trivial enough that I believe they "just work", but others
10068       have rather complex interfaces with function pointers and all. In these
10069       cases you should proceed wit great caution.
10070
10071       This module defaults to using OpenSSL automatic protocol negotiation
10072       code for automatically detecting the version of the SSL/TLS protocol
10073       that the other end talks. With most web servers this works just fine,
10074       but once in a while I get complaints from people that the module does
10075       not work with some web servers. Usually this can be solved by
10076       explicitly setting the protocol version, e.g.
10077
10078          $Net::SSLeay::ssl_version = 2;  # Insist on SSLv2
10079          $Net::SSLeay::ssl_version = 3;  # Insist on SSLv3
10080          $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
10081          $Net::SSLeay::ssl_version = 11; # Insist on TLSv1.1
10082          $Net::SSLeay::ssl_version = 12; # Insist on TLSv1.2
10083          $Net::SSLeay::ssl_version = 13; # Insist on TLSv1.3
10084
10085       Although the autonegotiation is nice to have, the SSL standards do not
10086       formally specify any such mechanism. Most of the world has accepted the
10087       SSLeay/OpenSSL way of doing it as the de facto standard. But for the
10088       few that think differently, you have to explicitly speak the correct
10089       version. This is not really a bug, but rather a deficiency in the
10090       standards. If a site refuses to respond or sends back some nonsensical
10091       error codes (at the SSL handshake level), try this option before
10092       mailing me.
10093
10094       On some systems, OpenSSL may be compiled without support for SSLv2.  If
10095       this is the case, Net::SSLeay will warn if ssl_version has been set to
10096       2.
10097
10098       The high level API returns the certificate of the peer, thus allowing
10099       one to check what certificate was supplied. However, you will only be
10100       able to check the certificate after the fact, i.e. you already sent
10101       your form data by the time you find out that you did not trust them,
10102       oops.
10103
10104       So, while being able to know the certificate after the fact is surely
10105       useful, the security minded would still choose to do the connection and
10106       certificate verification first and only then exchange data with the
10107       site. Currently none of the high level API functions do this, thus you
10108       would have to program it using the low level API. A good place to start
10109       is to see how the "Net::SSLeay::http_cat()" function is implemented.
10110
10111       The high level API functions use a global file handle "SSLCAT_S"
10112       internally. This really should not be a problem because there is no way
10113       to interleave the high level API functions, unless you use threads (but
10114       threads are not very well supported in perl anyway). However, you may
10115       run into problems if you call undocumented internal functions in an
10116       interleaved fashion. The best solution is to "require Net::SSLeay" in
10117       one thread after all the threads have been created.
10118

DIAGNOSTICS

10120       Random number generator not seeded!!!
10121           (W) This warning indicates that "randomize()" was not able to read
10122           "/dev/random" or "/dev/urandom", possibly because your system does
10123           not have them or they are differently named. You can still use SSL,
10124           but the encryption will not be as strong.
10125
10126       open_tcp_connection: destination host not found:`server' (port 123)
10127       ($!)
10128           Name lookup for host named "server" failed.
10129
10130       open_tcp_connection: failed `server', 123 ($!)
10131           The name was resolved, but establishing the TCP connection failed.
10132
10133       msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
10134       proto
10135           SSLeay error string. The first number (123) is the PID, the second
10136           number (1) indicates the position of the error message in SSLeay
10137           error stack.  You often see a pile of these messages as errors
10138           cascade.
10139
10140       msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
10141           The same as above, but you didn't call load_error_strings() so
10142           SSLeay couldn't verbosely explain the error. You can still find out
10143           what it means with this command:
10144
10145               /usr/local/ssl/bin/ssleay errstr 02001002
10146
10147       Password is being asked for private key
10148           This is normal behaviour if your private key is encrypted. Either
10149           you have to supply the password or you have to use an unencrypted
10150           private key. Scan OpenSSL.org for the FAQ that explains how to do
10151           this (or just study examples/makecert.pl which is used during "make
10152           test" to do just that).
10153

SECURITY

10155       You can mitigate some of the security vulnerabilities that might be
10156       present in your SSL/TLS application:
10157
10158   BEAST Attack
10159       http://blogs.cisco.com/security/beat-the-beast-with-tls/
10160       https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
10161       http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
10162
10163       The BEAST attack relies on a weakness in the way CBC mode is used in
10164       SSL/TLS.  In OpenSSL versions 0.9.6d and later, the protocol-level
10165       mitigation is enabled by default, thus making it not vulnerable to the
10166       BEAST attack.
10167
10168       Solutions:
10169
10170       ·   Compile with OpenSSL versions 0.9.6d or later, which enables
10171           SSL_OP_ALL by default
10172
10173       ·   Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
10174           enabled by default)
10175
10176       ·   Don't support SSLv2, SSLv3
10177
10178       ·   Actively control the ciphers your server supports with
10179           set_cipher_list:
10180
10181       Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
10182
10183   Session Resumption
10184       http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
10185
10186       The SSL Labs vulnerability test on your SSL server might report in red:
10187
10188       Session resumption      No (IDs assigned but not accepted)
10189
10190       This report is not really bug or a vulnerability, since the server will
10191       not accept session resumption requests.  However, you can prevent this
10192       noise in the report by disabling the session cache altogether:
10193       Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx,
10194       Net::SSLeay::SESS_CACHE_OFF()); Use 0 if you don't have SESS_CACHE_OFF
10195       constant.
10196
10197   Secure Renegotiation and DoS Attack
10198       https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
10199
10200       This is not a "security flaw," it is more of a DoS vulnerability.
10201
10202       Solutions:
10203
10204       ·   Do not support SSLv2
10205
10206       ·   Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
10207
10208       ·   Compile with OpenSSL 0.9.8m or later
10209

BUGS

10211       If you encounter a problem with this module that you believe is a bug,
10212       please report it in one of the following ways:
10213
10214       ·   create a new issue <https://github.com/radiator-software/p5-net-
10215           ssleay/issues/new> under the Net-SSLeay GitHub project at
10216           <https://github.com/radiator-software/p5-net-ssleay>;
10217
10218       ·   open a ticket <https://rt.cpan.org/Ticket/Create.html?Queue=Net-
10219           SSLeay> using the CPAN RT bug tracker's web interface at
10220           <https://rt.cpan.org/Dist/Display.html?Queue=Net-SSLeay>;
10221
10222       ·   send an email to the CPAN RT bug tracker at
10223           bug-Net-SSLeay@rt.cpan.org <mailto:bug-Net-SSLeay@rt.cpan.org>.
10224
10225       Please make sure your bug report includes the following information:
10226
10227       ·   the code you are trying to run;
10228
10229       ·   your operating system name and version;
10230
10231       ·   the output of "perl -V";
10232
10233       ·   the version of OpenSSL or LibreSSL you are using.
10234

AUTHOR

10236       Originally written by Sampo Kellomäki.
10237
10238       Maintained by Florian Ragwitz between November 2005 and January 2010.
10239
10240       Maintained by Mike McCauley between November 2005 and June 2018.
10241
10242       Maintained by Chris Novakovic, Tuure Vartiainen and Heikki Vatiainen
10243       since June 2018.
10244
10246       Copyright (c) 1996-2003 Sampo Kellomäki <sampo@iki.fi>
10247
10248       Copyright (c) 2005-2010 Florian Ragwitz <rafl@debian.org>
10249
10250       Copyright (c) 2005-2018 Mike McCauley <mikem@airspayce.com>
10251
10252       Copyright (c) 2018- Chris Novakovic <chris@chrisn.me.uk>
10253
10254       Copyright (c) 2018- Tuure Vartiainen <vartiait@radiatorsoftware.com>
10255
10256       Copyright (c) 2018- Heikki Vatiainen <hvn@radiatorsoftware.com>
10257
10258       All rights reserved.
10259

LICENSE

10261       This module is released under the terms of the Artistic License 2.0.
10262       For details, see the "LICENSE" file distributed with Net-SSLeay's
10263       source code.
10264

SEE ALSO

10266         Net::SSLeay::Handle                      - File handle interface
10267         ./examples                               - Example servers and a clients
10268         <http://www.openssl.org/>                - OpenSSL source, documentation, etc
10269         openssl-users-request@openssl.org        - General OpenSSL mailing list
10270         <http://www.ietf.org/rfc/rfc2246.txt>    - TLS 1.0 specification
10271         <http://www.w3c.org>                     - HTTP specifications
10272         <http://www.ietf.org/rfc/rfc2617.txt>    - How to send password
10273         <http://www.lothar.com/tech/crypto/>     - Entropy Gathering Daemon (EGD)
10274         <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
10275                                  - pseudo-random number generating daemon (PRNGD)
10276         perl(1)
10277         perlref(1)
10278         perllol(1)
10279         perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
10280
10281
10282
10283perl v5.30.1                      2020-02-05                    Net::SSLeay(3)
Impressum