1Net::SSLeay(3) User Contributed Perl Documentation Net::SSLeay(3)
2
6 Net::SSLeay - Perl extension for using OpenSSL
7
9 use Net::SSLeay qw(get_https post_https sslcat make_headers make_form);
10 ($page) = get_https('www.bacus.pt', 443, '/'); # Case 1
12 ($page, $response, %reply_headers)
14 = get_https('www.bacus.pt', 443, '/', # Case 2
15 make_headers(User-Agent => 'Cryptozilla/5.0b1',
16 Referer => 'https://www.bacus.pt'
17 ));
18 ($page, $result, %headers) = # Case 2b
20 = get_https('www.bacus.pt', 443, '/protected.html',
21 make_headers(Authorization =>
22 'Basic ' . MIME::Base64::encode("$user:$pass",''))
23 );
24 ($page, $response, %reply_headers)
26 = post_https('www.bacus.pt', 443, '/foo.cgi', '', # Case 3
27 make_form(OK => '1',
28 name => 'Sampo'
29 ));
30 $reply = sslcat($host, $port, $request); # Case 4
32 ($reply, $err, $server_cert) = sslcat($host, $port, $request); # Case 5
34 $Net::SSLeay::trace = 2; # 0=no debugging, 1=ciphers, 2=trace, 3=dump data
36 Net::SSLeay::initialize(); # Initialize ssl library once
38
40 Net::SSLeay module contains perl bindings to openssl
41 (<http://www.openssl.org>) library.
42 COMPATIBILITY NOTE: Net::SSLeay cannot be built with pre-0.9.3 openssl.
44 It is strongly recommended to use at least 0.9.7 (as older versions are
45 not tested during development). Some low level API functions may be
46 available with certain openssl versions.
47 It is compatible with OpenSSL 1.0 and 1.1. Some functions are not
49 available under OpenSSL 1.1.
50 Net::SSLeay module basically comprise of:
52 · High level functions for accessing web servers (by using
54 HTTP/HTTPS)
55 · Low level API (mostly mapped 1:1 to openssl's C functions)
57 · Convenience functions (related to low level API but with more perl
59 friendly interface)
60 There is also a related module called Net::SSLeay::Handle included in
62 this distribution that you might want to use instead. It has its own
63 pod documentation.
64 High level functions for accessing web servers
66 This module offers some high level convenience functions for accessing
67 web pages on SSL servers (for symmetry, the same API is offered for
68 accessing http servers, too), an "sslcat()" function for writing your
69 own clients, and finally access to the SSL api of the SSLeay/OpenSSL
70 package so you can write servers or clients for more complicated
71 applications.
72 For high level functions it is most convenient to import them into your
74 main namespace as indicated in the synopsis.
75 Basic set of functions
77 · get_https
79 · post_https
81 · put_https
83 · head_https
85 · do_https
87 · sslcat
89 · https_cat
91 · make_form
93 · make_headers
95 Case 1 (in SYNOPSIS) demonstrates the typical invocation of get_https()
97 to fetch an HTML page from secure server. The first argument provides
98 the hostname or IP in dotted decimal notation of the remote server to
99 contact. The second argument is the TCP port at the remote end (your
100 own port is picked arbitrarily from high numbered ports as usual for
101 TCP). The third argument is the URL of the page without the host name
102 part. If in doubt consult the HTTP specifications at
103 <http://www.w3c.org>.
104 Case 2 (in SYNOPSIS) demonstrates full fledged use of "get_https()". As
106 can be seen, "get_https()" parses the response and response headers and
107 returns them as a list, which can be captured in a hash for later
108 reference. Also a fourth argument to "get_https()" is used to insert
109 some additional headers in the request. "make_headers()" is a function
110 that will convert a list or hash to such headers. By default
111 "get_https()" supplies "Host" (to make virtual hosting easy) and
112 "Accept" (reportedly needed by IIS) headers.
113 Case 2b (in SYNOPSIS) demonstrates how to get a password protected
115 page. Refer to the HTTP protocol specifications for further details
116 (e.g. RFC-2617).
117 Case 3 (in SYNOPSIS) invokes "post_https()" to submit a HTML/CGI form
119 to a secure server. The first four arguments are equal to "get_https()"
120 (note that the empty string ('') is passed as header argument). The
121 fifth argument is the contents of the form formatted according to CGI
122 specification. Do not post UTF-8 data as content: use utf8::downgrade
123 first. In this case the helper function "make_https()" is used to do
124 the formatting, but you could pass any string. "post_https()"
125 automatically adds "Content-Type" and "Content-Length" headers to the
126 request.
127 Case 4 (in SYNOPSIS) shows the fundamental "sslcat()" function
129 (inspired in spirit by the "netcat" utility :-). It's your swiss army
130 knife that allows you to easily contact servers, send some data, and
131 then get the response. You are responsible for formatting the data and
132 parsing the response - "sslcat()" is just a transport.
133 Case 5 (in SYNOPSIS) is a full invocation of "sslcat()" which allows
135 the return of errors as well as the server (peer) certificate.
136 The $trace global variable can be used to control the verbosity of the
138 high level functions. Level 0 guarantees silence, level 1 (the default)
139 only emits error messages.
140 Alternate versions of high-level API
142 · get_https3
144 · post_https3
146 · put_https3
148 · get_https4
150 · post_https4
152 · put_https4
154 The above mentioned functions actually return the response headers as a
156 list, which only gets converted to hash upon assignment (this
157 assignment looses information if the same header occurs twice, as may
158 be the case with cookies). There are also other variants of the
159 functions that return unprocessed headers and that return a reference
160 to a hash.
161 ($page, $response, @headers) = get_https('www.bacus.pt', 443, '/');
163 for ($i = 0; $i < $#headers; $i+=2) {
164 print "$headers[$i] = " . $headers[$i+1] . "\n";
165 }
166 ($page, $response, $headers, $server_cert)
168 = get_https3('www.bacus.pt', 443, '/');
169 print "$headers\n";
170 ($page, $response, $headers_ref)
172 = get_https4('www.bacus.pt', 443, '/');
173 for $k (sort keys %{$headers_ref}) {
174 for $v (@{$$headers_ref{$k}}) {
175 print "$k = $v\n";
176 }
177 }
178 All of the above code fragments accomplish the same thing: display all
180 values of all headers. The API functions ending in "3" return the
181 headers simply as a scalar string and it is up to the application to
182 split them up. The functions ending in "4" return a reference to a hash
183 of arrays (see perlref and perllol if you are not familiar with complex
184 perl data structures). To access a single value of such a header hash
185 you would do something like
186 print $$headers_ref{COOKIE}[0];
188 Variants 3 and 4 also allow you to discover the server certificate in
190 case you would like to store or display it, e.g.
191 ($p, $resp, $hdrs, $server_cert) = get_https3('www.bacus.pt', 443, '/');
193 if (!defined($server_cert) || ($server_cert == 0)) {
194 warn "Subject Name: undefined, Issuer Name: undefined";
195 } else {
196 warn 'Subject Name: '
197 . Net::SSLeay::X509_NAME_oneline(
198 Net::SSLeay::X509_get_subject_name($server_cert))
199 . 'Issuer Name: '
200 . Net::SSLeay::X509_NAME_oneline(
201 Net::SSLeay::X509_get_issuer_name($server_cert));
202 }
203 Beware that this method only allows after the fact verification of the
205 certificate: by the time "get_https3()" has returned the https request
206 has already been sent to the server, whether you decide to trust it or
207 not. To do the verification correctly you must either employ the
208 OpenSSL certificate verification framework or use the lower level API
209 to first connect and verify the certificate and only then send the http
210 data. See the implementation of "ds_https3()" for guidance on how to do
211 this.
212 Using client certificates
214 Secure web communications are encrypted using symmetric crypto keys
216 exchanged using encryption based on the certificate of the server.
217 Therefore in all SSL connections the server must have a certificate.
218 This serves both to authenticate the server to the clients and to
219 perform the key exchange.
220 Sometimes it is necessary to authenticate the client as well. Two
222 options are available: HTTP basic authentication and a client side
223 certificate. The basic authentication over HTTPS is actually quite safe
224 because HTTPS guarantees that the password will not travel in the
225 clear. Never-the-less, problems like easily guessable passwords remain.
226 The client certificate method involves authentication of the client at
227 the SSL level using a certificate. For this to work, both the client
228 and the server have certificates (which typically are different) and
229 private keys.
230 The API functions outlined above accept additional arguments that allow
232 one to supply the client side certificate and key files. The format of
233 these files is the same as used for server certificates and the caveat
234 about encrypting private keys applies.
235 ($page, $result, %headers) = # 2c
237 = get_https('www.bacus.pt', 443, '/protected.html',
238 make_headers(Authorization =>
239 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
240 '', $mime_type6, $path_to_crt7, $path_to_key8);
241 ($page, $response, %reply_headers)
243 = post_https('www.bacus.pt', 443, '/foo.cgi', # 3b
244 make_headers('Authorization' =>
245 'Basic ' . MIME::Base64::encode("$user:$pass",'')),
246 make_form(OK => '1', name => 'Sampo'),
247 $mime_type6, $path_to_crt7, $path_to_key8);
248 Case 2c (in SYNOPSIS) demonstrates getting a password protected page
250 that also requires a client certificate, i.e. it is possible to use
251 both authentication methods simultaneously.
252 Case 3b (in SYNOPSIS) is a full blown POST to a secure server that
254 requires both password authentication and a client certificate, just
255 like in case 2c.
256 Note: The client will not send a certificate unless the server requests
258 one. This is typically achieved by setting the verify mode to
259 "VERIFY_PEER" on the server:
260 Net::SSLeay::set_verify(ssl, Net::SSLeay::VERIFY_PEER, 0);
262 See "perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod" for a full
264 description.
265 Working through a web proxy
267 · set_proxy
269 "Net::SSLeay" can use a web proxy to make its connections. You need to
271 first set the proxy host and port using "set_proxy()" and then just use
272 the normal API functions, e.g:
273 Net::SSLeay::set_proxy('gateway.myorg.com', 8080);
275 ($page) = get_https('www.bacus.pt', 443, '/');
276 If your proxy requires authentication, you can supply a username and
278 password as well
279 Net::SSLeay::set_proxy('gateway.myorg.com', 8080, 'joe', 'salainen');
281 ($page, $result, %headers) =
282 = get_https('www.bacus.pt', 443, '/protected.html',
283 make_headers(Authorization =>
284 'Basic ' . MIME::Base64::encode("susie:pass",''))
285 );
286 This example demonstrates the case where we authenticate to the proxy
288 as "joe" and to the final web server as "susie". Proxy authentication
289 requires the "MIME::Base64" module to work.
290 HTTP (without S) API
292 · get_http
294 · post_http
296 · tcpcat
298 · get_httpx
300 · post_httpx
302 · tcpxcat
304 Over the years it has become clear that it would be convenient to use
306 the light-weight flavour API of "Net::SSLeay" for normal HTTP as well
307 (see "LWP" for the heavy-weight object-oriented approach). In fact it
308 would be nice to be able to flip https on and off on the fly. Thus
309 regular HTTP support was evolved.
310 use Net::SSLeay qw(get_http post_http tcpcat
312 get_httpx post_httpx tcpxcat
313 make_headers make_form);
314 ($page, $result, %headers)
316 = get_http('www.bacus.pt', 443, '/protected.html',
317 make_headers(Authorization =>
318 'Basic ' . MIME::Base64::encode("$user:$pass",''))
319 );
320 ($page, $response, %reply_headers)
322 = post_http('www.bacus.pt', 443, '/foo.cgi', '',
323 make_form(OK => '1',
324 name => 'Sampo'
325 ));
326 ($reply, $err) = tcpcat($host, $port, $request);
328 ($page, $result, %headers)
330 = get_httpx($usessl, 'www.bacus.pt', 443, '/protected.html',
331 make_headers(Authorization =>
332 'Basic ' . MIME::Base64::encode("$user:$pass",''))
333 );
334 ($page, $response, %reply_headers)
336 = post_httpx($usessl, 'www.bacus.pt', 443, '/foo.cgi', '',
337 make_form(OK => '1', name => 'Sampo' ));
338 ($reply, $err, $server_cert) = tcpxcat($usessl, $host, $port, $request);
340 As can be seen, the "x" family of APIs takes as the first argument a
342 flag which indicates whether SSL is used or not.
343 Certificate verification and Certificate Revocation Lists (CRLs)
345 OpenSSL supports the ability to verify peer certificates. It can also
346 optionally check the peer certificate against a Certificate Revocation
347 List (CRL) from the certificates issuer. A CRL is a file, created by
348 the certificate issuer that lists all the certificates that it
349 previously signed, but which it now revokes. CRLs are in PEM format.
350 You can enable "Net::SSLeay CRL" checking like this:
352 &Net::SSLeay::X509_STORE_set_flags
354 (&Net::SSLeay::CTX_get_cert_store($ssl),
355 &Net::SSLeay::X509_V_FLAG_CRL_CHECK);
356 After setting this flag, if OpenSSL checks a peer's certificate, then
358 it will attempt to find a CRL for the issuer. It does this by looking
359 for a specially named file in the search directory specified by
360 CTX_load_verify_locations. CRL files are named with the hash of the
361 issuer's subject name, followed by ".r0", ".r1" etc. For example
362 "ab1331b2.r0", "ab1331b2.r1". It will read all the .r files for the
363 issuer, and then check for a revocation of the peer certificate in all
364 of them. (You can also force it to look in a specific named CRL file.,
365 see below). You can find out the hash of the issuer subject name in a
366 CRL with
367 openssl crl -in crl.pem -hash -noout
369 If the peer certificate does not pass the revocation list, or if no CRL
371 is found, then the handshaking fails with an error.
372 You can also force OpenSSL to look for CRLs in one or more arbitrarily
374 named files.
375 my $bio = Net::SSLeay::BIO_new_file($crlfilename, 'r');
377 my $crl = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
378 if ($crl) {
379 Net::SSLeay::X509_STORE_add_crl(
380 Net::SSLeay::CTX_get_cert_store($ssl, $crl)
381 );
382 } else {
383 error reading CRL....
384 }
385 Usually the URLs where you can download the CRLs is contained in the
387 certificate itself and you can extract them with
388 my @url = Net::SSLeay::P_X509_get_crl_distribution_points($cert)
390 But there is no automatic downloading of the CRLs and often these CRLs
392 are too huge to just download them to verify a single certificate.
393 Also, these CRLs are often in DER format which you need to convert to
394 PEM before you can use it:
395 openssl crl -in crl.der -inform der -out crl.pem
397 So as an alternative for faster and timely revocation checks you better
399 use the Online Status Revocation Protocol (OCSP).
400 Certificate verification and Online Status Revocation Protocol (OCSP)
402 While checking for revoked certificates is possible and fast with
403 Certificate Revocation Lists, you need to download the complete and
404 often huge list before you can verify a single certificate.
405 A faster way is to ask the CA to check the revocation of just a single
407 or a few certificates using OCSP. Basically you generate for each
408 certificate an OCSP_CERTID based on the certificate itself and its
409 issuer, put the ids togetether into an OCSP_REQUEST and send the
410 request to the URL given in the certificate.
411 As a result you get back an OCSP_RESPONSE and need to check the status
413 of the response, check that it is valid (e.g. signed by the CA) and
414 finally extract the information about each OCSP_CERTID to find out if
415 the certificate is still valid or got revoked.
416 With Net::SSLeay this can be done like this:
418 # get id(s) for given certs, like from get_peer_certificate
420 # or get_peer_cert_chain. This will croak if
421 # - one tries to make an OCSP_CERTID for a self-signed certificate
422 # - the issuer of the certificate cannot be found in the SSL objects
423 # store, nor in the current certificate chain
424 my $cert = Net::SSLeay::get_peer_certificate($ssl);
425 my $id = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) };
426 die "failed to make OCSP_CERTID: $@" if $@;
427 # create OCSP_REQUEST from id(s)
429 # Multiple can be put into the same request, if the same OCSP responder
430 # is responsible for them.
431 my $req = Net::SSLeay::OCSP_ids2req($id);
432 # determine URI of OCSP responder
434 my $uri = Net::SSLeay::P_X509_get_ocsp_uri($cert);
435 # Send stringified OCSP_REQUEST with POST to $uri.
437 # We can ignore certificate verification for https, because the OCSP
438 # response itself is signed.
439 my $ua = HTTP::Tiny->new(verify_SSL => 0);
440 my $res = $ua->request( 'POST',$uri, {
441 headers => { 'Content-type' => 'application/ocsp-request' },
442 content => Net::SSLeay::i2d_OCSP_REQUEST($req)
443 });
444 my $content = $res && $res->{success} && $res->{content}
445 or die "query failed";
446 # Extract OCSP_RESPONSE.
448 # this will croak if the string is not an OCSP_RESPONSE
449 my $resp = eval { Net::SSLeay::d2i_OCSP_RESPONSE($content) };
450 # Check status of response.
452 my $status = Net::SSLeay::OCSP_response_status($resp);
453 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL())
454 die "OCSP response failed: ".
455 Net::SSLeay::OCSP_response_status_str($status);
456 }
457 # Verify signature of response and if nonce matches request.
459 # This will croak if there is a nonce in the response, but it does not match
460 # the request. It will return false if the signature could not be verified,
461 # in which case details can be retrieved with Net::SSLeay::ERR_get_error.
462 # It will not complain if the response does not contain a nonce, which is
463 # usually the case with pre-signed responses.
464 if ( ! eval { Net::SSLeay::OCSP_response_verify($ssl,$resp,$req) }) {
465 die "OCSP response verification failed";
466 }
467 # Extract information from OCSP_RESPONSE for each of the ids.
469 # If called in scalar context it will return the time (as time_t), when the
471 # next update is due (minimum of all successful responses inside $resp). It
472 # will croak on the following problems:
473 # - response is expired or not yet valid
474 # - no response for given OCSP_CERTID
475 # - certificate status is not good (e.g. revoked or unknown)
476 if ( my $nextupd = eval { Net::SSLeay::OCSP_response_results($resp,$id) }) {
477 warn "certificate is valid, next update in ".
478 ($nextupd-time())." seconds\n";
479 } else {
480 die "certificate is not valid: $@";
481 }
482 # But in array context it will return detailed information about each given
484 # OCSP_CERTID instead croaking on errors:
485 # if no @ids are given it will return information about all single responses
486 # in the OCSP_RESPONSE
487 my @results = Net::SSLeay::OCSP_response_results($resp,@ids);
488 for my $r (@results) {
489 print Dumper($r);
490 # @results are in the same order as the @ids and contain:
491 # $r->[0] - OCSP_CERTID
492 # $r->[1] - undef if no error (certificate good) OR error message as string
493 # $r->[2] - hash with details:
494 # thisUpdate - time_t of this single response
495 # nextUpdate - time_t when update is expected
496 # statusType - integer:
497 # V_OCSP_CERTSTATUS_GOOD(0)
498 # V_OCSP_CERTSTATUS_REVOKED(1)
499 # V_OCSP_CERTSTATUS_UNKNOWN(2)
500 # revocationTime - time_t (only if revoked)
501 # revocationReason - integer (only if revoked)
502 # revocationReason_str - reason as string (only if revoked)
503 }
504 To further speed up certificate revocation checking one can use a TLS
506 extension to instruct the server to staple the OCSP response:
507 # set TLS extension before doing SSL_connect
509 Net::SSLeay::set_tlsext_status_type($ssl,
510 Net::SSLeay::TLSEXT_STATUSTYPE_ocsp());
511 # setup callback to verify OCSP response
513 my $cert_valid = undef;
514 Net::SSLeay::CTX_set_tlsext_status_cb($context,sub {
515 my ($ssl,$resp) = @_;
516 if (!$resp) {
517 # Lots of servers don't return an OCSP response.
518 # In this case we must check the OCSP status outside the SSL
519 # handshake.
520 warn "server did not return stapled OCSP response\n";
521 return 1;
522 }
523 # verify status
524 my $status = Net::SSLeay::OCSP_response_status($resp);
525 if ($status != Net::SSLeay::OCSP_RESPONSE_STATUS_SUCCESSFUL()) {
526 warn "OCSP response failure: $status\n";
527 return 1;
528 }
529 # verify signature - we have no OCSP_REQUEST here to check nonce
530 if (!eval { Net::SSLeay::OCSP_response_verify($ssl,$resp) }) {
531 warn "OCSP response verify failed\n";
532 return 1;
533 }
534 # check if the certificate is valid
535 # we should check here against the peer_certificate
536 my $cert = Net::SSLeay::get_peer_certificate();
537 my $certid = eval { Net::SSLeay::OCSP_cert2ids($ssl,$cert) } or do {
538 warn "cannot get certid from cert: $@";
539 $cert_valid = -1;
540 return 1;
541 };
542 if ( $nextupd = eval {
544 Net::SSLeay::OCSP_response_results($resp,$certid) }) {
545 warn "certificate not revoked\n";
546 $cert_valid = 1;
547 } else {
548 warn "certificate not valid: $@";
549 $cert_valid = 0;
550 }
551 });
552 # do SSL handshake here
554 ....
555 # check if certificate revocation was checked already
556 if ( ! defined $cert_valid) {
557 # check revocation outside of SSL handshake by asking OCSP responder
558 ...
559 } elsif ( ! $cert_valid ) {
560 die "certificate not valid - closing SSL connection";
561 } elsif ( $cert_valid<0 ) {
562 die "cannot verify certificate revocation - self-signed ?";
563 } else {
564 # everything fine
565 ...
566 }
567 Using Net::SSLeay in multi-threaded applications
569 IMPORTANT: versions 1.42 or earlier are not thread-safe!
570 Net::SSLeay module implements all necessary stuff to be ready for
572 multi-threaded environment - it requires openssl-0.9.7 or newer. The
573 implementation fully follows thread safety related requirements of
574 openssl library(see <http://www.openssl.org/docs/crypto/threads.html>).
575 If you are about to use Net::SSLeay (or any other module based on
577 Net::SSLeay) in multi-threaded perl application it is recommended to
578 follow this best-practice:
579 Initialization
581 Load and initialize Net::SSLeay module in the main thread:
583 use threads;
585 use Net::SSLeay;
586 Net::SSLeay::load_error_strings();
588 Net::SSLeay::SSLeay_add_ssl_algorithms();
589 Net::SSLeay::randomize();
590 sub do_master_job {
592 #... call whatever from Net::SSLeay
593 }
594 sub do_worker_job {
596 #... call whatever from Net::SSLeay
597 }
598 #start threads
600 my $master = threads->new(\&do_master_job, 'param1', 'param2');
601 my @workers = threads->new(\&do_worker_job, 'arg1', 'arg2') for (1..10);
602 #waiting for all threads to finish
604 $_->join() for (threads->list);
605 NOTE: Openssl's "int SSL_library_init(void)" function (which is also
607 aliased as "SSLeay_add_ssl_algorithms", "OpenSSL_add_ssl_algorithms"
608 and "add_ssl_algorithms") is not re-entrant and multiple calls can
609 cause a crash in threaded application. Net::SSLeay implements flags
610 preventing repeated calls to this function, therefore even multiple
611 initialization via Net::SSLeay::SSLeay_add_ssl_algorithms() should work
612 without trouble.
613 Using callbacks
615 Do not use callbacks across threads (the module blocks cross-thread
617 callback operations and throws a warning). Always do the callback
618 setup, callback use and callback destruction within the same thread.
619 Using openssl elements
621 All openssl elements (X509, SSL_CTX, ...) can be directly passed
623 between threads.
624 use threads;
626 use Net::SSLeay;
627 Net::SSLeay::load_error_strings();
629 Net::SSLeay::SSLeay_add_ssl_algorithms();
630 Net::SSLeay::randomize();
631 sub do_job {
633 my $context = shift;
634 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
635 #...
636 }
637 my $c = Net::SSLeay::CTX_new();
639 threads->create(\&do_job, $c);
640 Or:
642 use threads;
644 use Net::SSLeay;
645 my $context; #does not need to be 'shared'
647 Net::SSLeay::load_error_strings();
649 Net::SSLeay::SSLeay_add_ssl_algorithms();
650 Net::SSLeay::randomize();
651 sub do_job {
653 Net::SSLeay::CTX_set_default_passwd_cb($context, sub { "secret" });
654 #...
655 }
656 $context = Net::SSLeay::CTX_new();
658 threads->create(\&do_job);
659 Using other perl modules based on Net::SSLeay
661 It should be fine to use any other module based on Net::SSLeay (like
663 IO::Socket::SSL) in multi-threaded applications. It is generally
664 recommended to do any global initialization of such a module in the
665 main thread before calling "threads->new(..)" or "threads->create(..)"
666 but it might differ module by module.
667 To be safe you can load and init Net::SSLeay explicitly in the main
669 thread:
670 use Net::SSLeay;
672 use Other::SSLeay::Based::Module;
673 Net::SSLeay::load_error_strings();
675 Net::SSLeay::SSLeay_add_ssl_algorithms();
676 Net::SSLeay::randomize();
677 Or even safer:
679 use Net::SSLeay;
681 use Other::SSLeay::Based::Module;
682 BEGIN {
684 Net::SSLeay::load_error_strings();
685 Net::SSLeay::SSLeay_add_ssl_algorithms();
686 Net::SSLeay::randomize();
687 }
688 Combining Net::SSLeay with other modules linked with openssl
690 BEWARE: This might be a big trouble! This is not guaranteed be thread-
692 safe!
693 There are many other (XS) modules linked directly to openssl library
695 (like Crypt::SSLeay).
696 As it is expected that also "another" module will call
698 "SSLeay_add_ssl_algorithms" at some point we have again a trouble with
699 multiple openssl initialization by Net::SSLeay and "another" module.
700 As you can expect Net::SSLeay is not able to avoid multiple
702 initialization of openssl library called by "another" module, thus you
703 have to handle this on your own (in some cases it might not be possible
704 at all to avoid this).
705 Threading with get_https and friends
707 The convenience functions get_https, post_https etc all initialize the
709 SSL library by calling Net::SSLeay::initialize which does the
710 conventional library initialization:
711 Net::SSLeay::load_error_strings();
713 Net::SSLeay::SSLeay_add_ssl_algorithms();
714 Net::SSLeay::randomize();
715 Net::SSLeay::initialize initializes the SSL library at most once. You
717 can override the Net::SSLeay::initialize function if you desire some
718 other type of initialization behaviour by get_https and friends. You
719 can call Net::SSLeay::initialize from your own code if you desire this
720 conventional library initialization.
721 Convenience routines
723 To be used with Low level API
724 Net::SSLeay::randomize($rn_seed_file,$additional_seed);
726 Net::SSLeay::set_cert_and_key($ctx, $cert_path, $key_path);
727 $cert = Net::SSLeay::dump_peer_certificate($ssl);
728 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
729 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
730 $got = Net::SSLeay::ssl_read_CRLF($ssl [, $max_length]);
732 $got = Net::SSLeay::ssl_read_until($ssl [, $delimit [, $max_length]]);
733 Net::SSLeay::ssl_write_CRLF($ssl, $message);
734 · randomize
736 seeds the openssl PRNG with "/dev/urandom" (see the top of
738 "SSLeay.pm" for how to change or configure this) and optionally
739 with user provided data. It is very important to properly seed your
740 random numbers, so do not forget to call this. The high level API
741 functions automatically call "randomize()" so it is not needed with
742 them. See also caveats.
743 · set_cert_and_key
745 takes two file names as arguments and sets the certificate and
747 private key to those. This can be used to set either server
748 certificates or client certificates.
749 · dump_peer_certificate
751 allows you to get a plaintext description of the certificate the
753 peer (usually the server) presented to us.
754 · ssl_read_all
756 see ssl_write_all (below)
758 · ssl_write_all
760 "ssl_read_all()" and "ssl_write_all()" provide true blocking
762 semantics for these operations (see limitation, below, for
763 explanation). These are much preferred to the low level API
764 equivalents (which implement BSD blocking semantics). The message
765 argument to "ssl_write_all()" can be a reference. This is helpful
766 to avoid unnecessary copying when writing something big, e.g:
767 $data = 'A' x 1000000000;
769 Net::SSLeay::ssl_write_all($ssl, \$data) or die "ssl write failed";
770 · ssl_read_CRLF
772 uses "ssl_read_all()" to read in a line terminated with a carriage
774 return followed by a linefeed (CRLF). The CRLF is included in the
775 returned scalar.
776 · ssl_read_until
778 uses "ssl_read_all()" to read from the SSL input stream until it
780 encounters a programmer specified delimiter. If the delimiter is
781 undefined, $/ is used. If $/ is undefined, "\n" is used. One can
782 optionally set a maximum length of bytes to read from the SSL input
783 stream.
784 · ssl_write_CRLF
786 writes $message and appends CRLF to the SSL output stream.
788 Initialization
790 In order to use the low level API you should start your programs with
791 the following incantation:
792 use Net::SSLeay qw(die_now die_if_ssl_error);
794 Net::SSLeay::load_error_strings();
795 Net::SSLeay::SSLeay_add_ssl_algorithms(); # Important!
796 Net::SSLeay::ENGINE_load_builtin_engines(); # If you want built-in engines
797 Net::SSLeay::ENGINE_register_all_complete(); # If you want built-in engines
798 Net::SSLeay::randomize();
799 Error handling functions
801 I can not emphasize the need to check for error enough. Use these
802 functions even in the most simple programs, they will reduce debugging
803 time greatly. Do not ask questions on the mailing list without having
804 first sprinkled these in your code.
805 · die_now
807 · die_if_ssl_error
809 "die_now()" and "die_if_ssl_error()" are used to conveniently print
811 the SSLeay error stack when something goes wrong:
812 Net::SSLeay::connect($ssl) or die_now("Failed SSL connect ($!)");
814 Net::SSLeay::write($ssl, "foo") or die_if_ssl_error("SSL write ($!)");
817 · print_errs
819 You can also use "Net::SSLeay::print_errs()" to dump the error
821 stack without exiting the program. As can be seen, your code
822 becomes much more readable if you import the error reporting
823 functions into your main name space.
824 Sockets
826 Perl uses file handles for all I/O. While SSLeay has a quite flexible
827 BIO mechanism and perl has an evolved PerlIO mechanism, this module
828 still sticks to using file descriptors. Thus to attach SSLeay to a
829 socket you should use "fileno()" to extract the underlying file
830 descriptor:
831 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
833 You should also set $| to 1 to eliminate STDIO buffering so you do not
835 get confused if you use perl I/O functions to manipulate your socket
836 handle.
837 If you need to select(2) on the socket, go right ahead, but be warned
839 that OpenSSL does some internal buffering so SSL_read does not always
840 return data even if the socket selected for reading (just keep on
841 selecting and trying to read). "Net::SSLeay" is no different from the C
842 language OpenSSL in this respect.
843 Callbacks
845 You can establish a per-context verify callback function something like
846 this:
847 sub verify {
849 my ($ok, $x509_store_ctx) = @_;
850 print "Verifying certificate...\n";
851 ...
852 return $ok;
853 }
854 It is used like this:
856 Net::SSLeay::set_verify ($ssl, Net::SSLeay::VERIFY_PEER, \&verify);
858 Per-context callbacks for decrypting private keys are implemented.
860 Net::SSLeay::CTX_set_default_passwd_cb($ctx, sub { "top-secret" });
862 Net::SSLeay::CTX_use_PrivateKey_file($ctx, "key.pem",
863 Net::SSLeay::FILETYPE_PEM)
864 or die "Error reading private key";
865 Net::SSLeay::CTX_set_default_passwd_cb($ctx, undef);
866 If Hello Extensions are supported by your OpenSSL, a session secret
868 callback can be set up to be called when a session secret is set by
869 openssl.
870 Establish it like this:
872 Net::SSLeay::set_session_secret_cb($ssl, \&session_secret_cb,
873 $somedata);
874 It will be called like this:
876 sub session_secret_cb
878 {
879 my ($secret, \@cipherlist, \$preferredcipher, $somedata) = @_;
880 }
881 No other callbacks are implemented. You do not need to use any callback
883 for simple (i.e. normal) cases where the SSLeay built-in verify
884 mechanism satisfies your needs.
885 It is required to reset these callbacks to undef immediately after use
887 to prevent memory leaks, thread safety problems and crashes on exit
888 that can occur if different threads set different callbacks.
889 If you want to use callback stuff, see examples/callback.pl! It's the
891 only one I am able to make work reliably.
892 Low level API
894 In addition to the high level functions outlined above, this module
895 contains straight-forward access to CRYPTO and SSL parts of OpenSSL C
896 API.
897 See the "*.h" headers from OpenSSL C distribution for a list of low
899 level SSLeay functions to call (check SSLeay.xs to see if some function
900 has been implemented). The module strips the initial "SSL_" off of the
901 SSLeay names. Generally you should use "Net::SSLeay::" in its place.
902 Note that some functions are prefixed with "P_" - these are very close
904 to the original API however contain some kind of a wrapper making its
905 interface more perl friendly.
906 For example:
908 In C:
910 #include <ssl.h>
912 err = SSL_set_verify (ssl, SSL_VERIFY_CLIENT_ONCE,
914 &your_call_back_here);
915 In Perl:
917 use Net::SSLeay;
919 $err = Net::SSLeay::set_verify ($ssl,
921 Net::SSLeay::VERIFY_CLIENT_ONCE,
922 \&your_call_back_here);
923 If the function does not start with "SSL_" you should use the full
925 function name, e.g.:
926 $err = Net::SSLeay::ERR_get_error;
928 The following new functions behave in perlish way:
930 $got = Net::SSLeay::read($ssl);
932 # Performs SSL_read, but returns $got
933 # resized according to data received.
934 # Returns undef on failure.
935 Net::SSLeay::write($ssl, $foo) || die;
937 # Performs SSL_write, but automatically
938 # figures out the size of $foo
939 Low level API: Version related functions
941 · SSLeay
943 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
945 Gives version number (numeric) of underlaying openssl library.
947 my $ver_number = Net::SSLeay::SSLeay();
949 # returns: the number identifying the openssl release
950 #
951 # 0x00903100 => openssl-0.9.3
952 # 0x00904100 => openssl-0.9.4
953 # 0x00905100 => openssl-0.9.5
954 # 0x0090600f => openssl-0.9.6
955 # 0x0090601f => openssl-0.9.6a
956 # 0x0090602f => openssl-0.9.6b
957 # ...
958 # 0x009060df => openssl-0.9.6m
959 # 0x0090700f => openssl-0.9.7
960 # 0x0090701f => openssl-0.9.7a
961 # 0x0090702f => openssl-0.9.7b
962 # ...
963 # 0x009070df => openssl-0.9.7m
964 # 0x0090800f => openssl-0.9.8
965 # 0x0090801f => openssl-0.9.8a
966 # 0x0090802f => openssl-0.9.8b
967 # ...
968 # 0x0090814f => openssl-0.9.8t
969 # 0x1000000f => openssl-1.0.0
970 # 0x1000004f => openssl-1.0.0d
971 # 0x1000007f => openssl-1.0.0g
972 You can use it like this:
974 if (Net::SSLeay::SSLeay() < 0x0090800f) {
976 die "you need openssl-0.9.8 or higher";
977 }
978 · SSLeay_version
980 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
982 Gives version number (string) of underlaying openssl library.
984 my $ver_string = Net::SSLeay::SSLeay_version($type);
986 # $type
987 # SSLEAY_VERSION - e.g. 'OpenSSL 1.0.0d 8 Feb 2011'
988 # SSLEAY_CFLAGS - e.g. 'compiler: gcc -D_WINDLL -DOPENSSL_USE_APPLINK .....'
989 # SSLEAY_BUILT_ON - e.g. 'built on: Fri May 6 00:00:46 GMT 2011'
990 # SSLEAY_PLATFORM - e.g. 'platform: mingw'
991 # SSLEAY_DIR - e.g. 'OPENSSLDIR: "z:/...."'
992 #
993 # returns: string
994 Net::SSLeay::SSLeay_version();
996 #is equivalent to
997 Net::SSLeay::SSLeay_version(SSLEAY_VERSION);
998 Check openssl doc
1000 <https://www.openssl.org/docs/man1.0.2/crypto/SSLeay_version.html>
1001 · OpenSSL_version_num
1003 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1005 requires at least OpenSSL 1.1.0
1006 Gives version number (numeric) of underlaying openssl library. See
1008 "SSLeay" for interpreting the result.
1009 my $ver_number = Net::SSLeay::OpenSSL_version_num();
1011 # returns: the number identifying the openssl release
1012 · OpenSSL_version
1014 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
1016 requires at least OpenSSL 1.1.0
1017 Gives version number (string) of underlaying openssl library.
1019 my $ver_string = Net::SSLeay::OpenSSL_version($t);
1021 # $t
1022 # OPENSSL_VERSION - e.g. 'OpenSSL 1.1.0g 2 Nov 2017'
1023 # OPENSSL_CFLAGS - e.g. 'compiler: cc -DDSO_DLFCN -DHAVE_DLFCN_H .....'
1024 # OPENSSL_BUILT_ON - e.g. 'built on: reproducible build, date unspecified'
1025 # OPENSSL_PLATFORM - e.g. 'platform: darwin64-x86_64-cc'
1026 # OPENSSL_DIR - e.g. 'OPENSSLDIR: "/opt/openssl-1.1.0g"'
1027 # OPENSSL_ENGINES_DIR - e.g. 'ENGINESDIR: "/opt/openssl-1.1.0g/lib/engines-1.1"'
1028 #
1029 # returns: string
1030 Net::SSLeay::OpenSSL_version();
1032 #is equivalent to
1033 Net::SSLeay::OpenSSL_version(OPENSSL_VERSION);
1034 Check openssl doc
1036 <https://www.openssl.org/docs/crypto/OpenSSL_version.html>
1037 Low level API: Initialization related functions
1039 · library_init
1041 Initialize SSL library by registering algorithms.
1043 my $rv = Net::SSLeay::library_init();
1045 Check openssl doc
1047 <http://www.openssl.org/docs/ssl/SSL_library_init.html>
1048 While the original function from OpenSSL always returns 1,
1050 Net::SSLeay adds a wrapper around it to make sure that the OpenSSL
1051 function is only called once. Thus the function will return 1 if
1052 initialization was done and 0 if not, i.e. if initialization was
1053 done already before.
1054 · add_ssl_algorithms
1056 The alias for "library_init"
1058 Net::SSLeay::add_ssl_algorithms();
1060 · OpenSSL_add_ssl_algorithms
1062 The alias for "library_init"
1064 Net::SSLeay::OpenSSL_add_ssl_algorithms();
1066 · SSLeay_add_ssl_algorithms
1068 The alias for "library_init"
1070 Net::SSLeay::SSLeay_add_ssl_algorithms();
1072 · load_error_strings
1074 Registers the error strings for all libcrypto + libssl related
1076 functions.
1077 Net::SSLeay::load_error_strings();
1079 #
1080 # returns: no return value
1081 Check openssl doc
1083 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1084 · ERR_load_crypto_strings
1086 Registers the error strings for all libcrypto functions. No need to
1088 call this function if you have already called "load_error_strings".
1089 Net::SSLeay::ERR_load_crypto_strings();
1091 #
1092 # returns: no return value
1093 Check openssl doc
1095 <http://www.openssl.org/docs/crypto/ERR_load_crypto_strings.html>
1096 · ERR_load_RAND_strings
1098 Registers the error strings for RAND related functions. No need to
1100 call this function if you have already called "load_error_strings".
1101 Net::SSLeay::ERR_load_RAND_strings();
1103 #
1104 # returns: no return value
1105 · ERR_load_SSL_strings
1107 Registers the error strings for SSL related functions. No need to
1109 call this function if you have already called "load_error_strings".
1110 Net::SSLeay::ERR_load_SSL_strings();
1112 #
1113 # returns: no return value
1114 · OpenSSL_add_all_algorithms
1116 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1118 Add algorithms to internal table.
1120 Net::SSLeay::OpenSSL_add_all_algorithms();
1122 #
1123 # returns: no return value
1124 Check openssl doc
1126 <http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html>
1127 · OPENSSL_add_all_algorithms_conf
1129 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1131 Similar to "OpenSSL_add_all_algorithms" - will ALWAYS load the
1133 config file
1134 Net::SSLeay::OPENSSL_add_all_algorithms_conf();
1136 #
1137 # returns: no return value
1138 · OPENSSL_add_all_algorithms_noconf
1140 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1142 Similar to "OpenSSL_add_all_algorithms" - will NEVER load the
1144 config file
1145 Net::SSLeay::OPENSSL_add_all_algorithms_noconf();
1147 #
1148 # returns: no return value
1149 Low level API: ERR_* and SSL_alert_* related functions
1151 NOTE: Please note that SSL_alert_* function have "SSL_" part stripped
1153 from their names.
1154 · ERR_clear_error
1156 Clear the error queue.
1158 Net::SSLeay::ERR_clear_error();
1160 #
1161 # returns: no return value
1162 Check openssl doc
1164 <http://www.openssl.org/docs/crypto/ERR_clear_error.html>
1165 · ERR_error_string
1167 Generates a human-readable string representing the error code
1169 $error.
1170 my $rv = Net::SSLeay::ERR_error_string($error);
1172 # $error - (unsigned integer) error code
1173 #
1174 # returns: string
1175 Check openssl doc
1177 <http://www.openssl.org/docs/crypto/ERR_error_string.html>
1178 · ERR_get_error
1180 Returns the earliest error code from the thread's error queue and
1182 removes the entry. This function can be called repeatedly until
1183 there are no more error codes to return.
1184 my $rv = Net::SSLeay::ERR_get_error();
1186 #
1187 # returns: (unsigned integer) error code
1188 Check openssl doc
1190 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1191 · ERR_peek_error
1193 Returns the earliest error code from the thread's error queue
1195 without modifying it.
1196 my $rv = Net::SSLeay::ERR_peek_error();
1198 #
1199 # returns: (unsigned integer) error code
1200 Check openssl doc
1202 <http://www.openssl.org/docs/crypto/ERR_get_error.html>
1203 · ERR_put_error
1205 Adds an error code to the thread's error queue. It signals that the
1207 error of $reason code reason occurred in function $func of library
1208 $lib, in line number $line of $file.
1209 Net::SSLeay::ERR_put_error($lib, $func, $reason, $file, $line);
1211 # $lib - (integer) library id (check openssl/err.h for constants e.g. ERR_LIB_SSL)
1212 # $func - (integer) function id (check openssl/ssl.h for constants e.g. SSL_F_SSL23_READ)
1213 # $reason - (integer) reason id (check openssl/ssl.h for constants e.g. SSL_R_SSL_HANDSHAKE_FAILURE)
1214 # $file - (string) file name
1215 # $line - (integer) line number in $file
1216 #
1217 # returns: no return value
1218 Check openssl doc
1220 <http://www.openssl.org/docs/crypto/ERR_put_error.html> and
1221 <http://www.openssl.org/docs/crypto/err.html>
1222 · alert_desc_string
1224 Returns a two letter string as a short form describing the reason
1226 of the alert specified by value.
1227 my $rv = Net::SSLeay::alert_desc_string($value);
1229 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1230 #
1231 # returns: description string (2 letters)
1232 Check openssl doc
1234 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1235 · alert_desc_string_long
1237 Returns a string describing the reason of the alert specified by
1239 value.
1240 my $rv = Net::SSLeay::alert_desc_string_long($value);
1242 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1243 #
1244 # returns: description string
1245 Check openssl doc
1247 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1248 · alert_type_string
1250 Returns a one letter string indicating the type of the alert
1252 specified by value.
1253 my $rv = Net::SSLeay::alert_type_string($value);
1255 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1256 #
1257 # returns: string (1 letter)
1258 Check openssl doc
1260 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1261 · alert_type_string_long
1263 Returns a string indicating the type of the alert specified by
1265 value.
1266 my $rv = Net::SSLeay::alert_type_string_long($value);
1268 # $value - (integer) allert id (check openssl/ssl.h for SSL3_AD_* and TLS1_AD_* constants)
1269 #
1270 # returns: string
1271 Check openssl doc
1273 <http://www.openssl.org/docs/ssl/SSL_alert_type_string.html>
1274 Low level API: SSL_METHOD_* related functions
1276 · SSLv23_method, SSLv23_server_method and SSLv23_client_method
1278 COMPATIBILITY: not available in Net-SSLeay-1.82 and before.
1280 Returns SSL_METHOD structure corresponding to general-purpose
1282 version-flexible TLS method, the return value can be later used as
1283 a param of "CTX_new_with_method".
1284 NOTE: Consider using TLS_method, TLS_server_method or
1286 TLS_client_method with new code.
1287 my $rv = Net::SSLeay::SSLv2_method();
1289 #
1290 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1291 · SSLv2_method
1293 Returns SSL_METHOD structure corresponding to SSLv2 method, the
1295 return value can be later used as a param of "CTX_new_with_method".
1296 Only available where supported by the underlying openssl.
1297 my $rv = Net::SSLeay::SSLv2_method();
1299 #
1300 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1301 · SSLv3_method
1303 Returns SSL_METHOD structure corresponding to SSLv3 method, the
1305 return value can be later used as a param of "CTX_new_with_method".
1306 my $rv = Net::SSLeay::SSLv3_method();
1308 #
1309 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1310 Check openssl doc
1312 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1313 · TLSv1_method, TLSv1_server_method and TLSv1_client_method
1315 COMPATIBILITY: Server and client methods not available in
1317 Net-SSLeay-1.82 and before.
1318 Returns SSL_METHOD structure corresponding to TLSv1 method, the
1320 return value can be later used as a param of "CTX_new_with_method".
1321 my $rv = Net::SSLeay::TLSv1_method();
1323 #
1324 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1325 Check openssl doc
1327 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1328 · TLSv1_1_method, TLSv1_1_server_method and TLSv1_1_client_method
1330 COMPATIBILITY: Server and client methods not available in
1332 Net-SSLeay-1.82 and before.
1333 Returns SSL_METHOD structure corresponding to TLSv1_1 method, the
1335 return value can be later used as a param of "CTX_new_with_method".
1336 Only available where supported by the underlying openssl.
1337 my $rv = Net::SSLeay::TLSv1_1_method();
1339 #
1340 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1341 Check openssl doc
1343 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1344 · TLSv1_2_method, TLSv1_2_server_method and TLSv1_2_client_method
1346 COMPATIBILITY: Server and client methods not available in
1348 Net-SSLeay-1.82 and before.
1349 Returns SSL_METHOD structure corresponding to TLSv1_2 method, the
1351 return value can be later used as a param of "CTX_new_with_method".
1352 Only available where supported by the underlying openssl.
1353 my $rv = Net::SSLeay::TLSv1_2_method();
1355 #
1356 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1357 Check openssl doc
1359 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1360 · TLS_method, TLS_server_method and TLS_client_method
1362 COMPATIBILITY: Not available in Net-SSLeay-1.82 and before.
1364 Returns SSL_METHOD structure corresponding to general-purpose
1366 version-flexible TLS method, the return value can be later used as
1367 a param of "CTX_new_with_method". Only available where supported by
1368 the underlying openssl.
1369 my $rv = Net::SSLeay::TLS_method();
1371 #
1372 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
1373 Check openssl doc
1375 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
1376 Low level API: ENGINE_* related functions
1378 · ENGINE_load_builtin_engines
1380 Load all bundled ENGINEs into memory and make them visible.
1382 Net::SSLeay::ENGINE_load_builtin_engines();
1384 #
1385 # returns: no return value
1386 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1388 · ENGINE_register_all_complete
1390 Register all loaded ENGINEs for every algorithm they collectively
1392 implement.
1393 Net::SSLeay::ENGINE_register_all_complete();
1395 #
1396 # returns: no return value
1397 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1399 · ENGINE_set_default
1401 Set default engine to $e + set its flags to $flags.
1403 my $rv = Net::SSLeay::ENGINE_set_default($e, $flags);
1405 # $e - value corresponding to openssl's ENGINE structure
1406 # $flags - (integer) engine flags
1407 # flags value can be made by bitwise "OR"ing:
1408 # 0x0001 - ENGINE_METHOD_RSA
1409 # 0x0002 - ENGINE_METHOD_DSA
1410 # 0x0004 - ENGINE_METHOD_DH
1411 # 0x0008 - ENGINE_METHOD_RAND
1412 # 0x0010 - ENGINE_METHOD_ECDH
1413 # 0x0020 - ENGINE_METHOD_ECDSA
1414 # 0x0040 - ENGINE_METHOD_CIPHERS
1415 # 0x0080 - ENGINE_METHOD_DIGESTS
1416 # 0x0100 - ENGINE_METHOD_STORE
1417 # 0x0200 - ENGINE_METHOD_PKEY_METHS
1418 # 0x0400 - ENGINE_METHOD_PKEY_ASN1_METHS
1419 # Obvious all-or-nothing cases:
1420 # 0xFFFF - ENGINE_METHOD_ALL
1421 # 0x0000 - ENGINE_METHOD_NONE
1422 #
1423 # returns: 1 on success, 0 on failure
1424 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1426 · ENGINE_by_id
1428 Get ENGINE by its identification $id.
1430 my $rv = Net::SSLeay::ENGINE_by_id($id);
1432 # $id - (string) engine identification e.g. "dynamic"
1433 #
1434 # returns: value corresponding to openssl's ENGINE structure (0 on failure)
1435 Check openssl doc <http://www.openssl.org/docs/crypto/engine.html>
1437 Low level API: EVP_PKEY_* related functions
1439 · EVP_PKEY_copy_parameters
1441 Copies the parameters from key $from to key $to.
1443 my $rv = Net::SSLeay::EVP_PKEY_copy_parameters($to, $from);
1445 # $to - value corresponding to openssl's EVP_PKEY structure
1446 # $from - value corresponding to openssl's EVP_PKEY structure
1447 #
1448 # returns: 1 on success, 0 on failure
1449 Check openssl doc
1451 <http://www.openssl.org/docs/crypto/EVP_PKEY_cmp.html>
1452 · EVP_PKEY_new
1454 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1456 Creates a new EVP_PKEY structure.
1458 my $rv = Net::SSLeay::EVP_PKEY_new();
1460 #
1461 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1462 Check openssl doc
1464 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1465 · EVP_PKEY_free
1467 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1469 Free an allocated EVP_PKEY structure.
1471 Net::SSLeay::EVP_PKEY_free($pkey);
1473 # $pkey - value corresponding to openssl's EVP_PKEY structure
1474 #
1475 # returns: no return value
1476 Check openssl doc
1478 <http://www.openssl.org/docs/crypto/EVP_PKEY_new.html>
1479 · EVP_PKEY_assign_RSA
1481 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1483 Set the key referenced by $pkey to $key
1485 NOTE: No reference counter will be increased, i.e. $key will be
1487 freed if $pkey is freed.
1488 my $rv = Net::SSLeay::EVP_PKEY_assign_RSA($pkey, $key);
1490 # $pkey - value corresponding to openssl's EVP_PKEY structure
1491 # $key - value corresponding to openssl's RSA structure
1492 #
1493 # returns: 1 on success, 0 on failure
1494 Check openssl doc
1496 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_RSA.html>
1497 · EVP_PKEY_assign_EC_KEY
1499 COMPATIBILITY: not available in Net-SSLeay-1.74 and before
1501 Set the key referenced by $pkey to $key
1503 NOTE: No reference counter will be increased, i.e. $key will be
1505 freed if $pkey is freed.
1506 my $rv = Net::SSLeay::EVP_PKEY_assign_EC_KEY($pkey, $key);
1508 # $pkey - value corresponding to openssl's EVP_PKEY structure
1509 # $key - value corresponding to openssl's EC_KEY structure
1510 #
1511 # returns: 1 on success, 0 on failure
1512 Check openssl doc
1514 <http://www.openssl.org/docs/crypto/EVP_PKEY_assign_EC_KEY.html>
1515 · EVP_PKEY_bits
1517 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1519 Returns the size of the key $pkey in bits.
1521 my $rv = Net::SSLeay::EVP_PKEY_bits($pkey);
1523 # $pkey - value corresponding to openssl's EVP_PKEY structure
1524 #
1525 # returns: size in bits
1526 · EVP_PKEY_size
1528 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1530 Returns the maximum size of a signature in bytes. The actual
1532 signature may be smaller.
1533 my $rv = Net::SSLeay::EVP_PKEY_size($pkey);
1535 # $pkey - value corresponding to openssl's EVP_PKEY structure
1536 #
1537 # returns: the maximum size in bytes
1538 Check openssl doc
1540 <http://www.openssl.org/docs/crypto/EVP_SignInit.html>
1541 · EVP_PKEY_id
1543 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
1545 requires at least openssl-1.0.0
1546 Returns $pkey type (integer value of corresponding NID).
1548 my $rv = Net::SSLeay::EVP_PKEY_id($pkey);
1550 # $pkey - value corresponding to openssl's EVP_PKEY structure
1551 #
1552 # returns: (integer) key type
1553 Example:
1555 my $pubkey = Net::SSLeay::X509_get_pubkey($x509);
1557 my $type = Net::SSLeay::EVP_PKEY_id($pubkey);
1558 print Net::SSLeay::OBJ_nid2sn($type); #prints e.g. 'rsaEncryption'
1559 Low level API: PEM_* related functions
1561 Check openssl doc <http://www.openssl.org/docs/crypto/pem.html>
1563 · PEM_read_bio_X509
1565 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1567 Loads PEM formatted X509 certificate via given BIO structure.
1569 my $rv = Net::SSLeay::PEM_read_bio_X509($bio);
1571 # $bio - value corresponding to openssl's BIO structure
1572 #
1573 # returns: value corresponding to openssl's X509 structure (0 on failure)
1574 Example:
1576 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1578 my $x509 = Net::SSLeay::PEM_read_bio_X509($bio);
1579 Net::SSLeay::BIO_free($bio);
1580 · PEM_read_bio_X509_REQ
1582 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1584 Loads PEM formatted X509_REQ object via given BIO structure.
1586 my $rv = Net::SSLeay::PEM_read_bio_X509_REQ($bio, $x=NULL, $cb=NULL, $u=NULL);
1588 # $bio - value corresponding to openssl's BIO structure
1589 #
1590 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1591 Example:
1593 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1595 my $x509_req = Net::SSLeay::PEM_read_bio_X509_REQ($bio);
1596 Net::SSLeay::BIO_free($bio);
1597 · PEM_read_bio_DHparams
1599 Reads DH structure from BIO.
1601 my $rv = Net::SSLeay::PEM_read_bio_DHparams($bio);
1603 # $bio - value corresponding to openssl's BIO structure
1604 #
1605 # returns: value corresponding to openssl's DH structure (0 on failure)
1606 · PEM_read_bio_X509_CRL
1608 Reads X509_CRL structure from BIO.
1610 my $rv = Net::SSLeay::PEM_read_bio_X509_CRL($bio);
1612 # $bio - value corresponding to openssl's BIO structure
1613 #
1614 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1615 · PEM_read_bio_PrivateKey
1617 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1619 Loads PEM formatted private key via given BIO structure.
1621 my $rv = Net::SSLeay::PEM_read_bio_PrivateKey($bio, $cb, $data);
1623 # $bio - value corresponding to openssl's BIO structure
1624 # $cb - reference to perl callback function
1625 # $data - data that will be passed to callback function (see examples below)
1626 #
1627 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
1628 Example:
1630 my $bio = Net::SSLeay::BIO_new_file($filename, 'r');
1632 my $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio); #ask for password if needed
1633 Net::SSLeay::BIO_free($bio);
1634 To use password you have the following options:
1636 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func); # use callback func for getting password
1638 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, \&callback_func, $data); # use callback_func + pass $data to callback_func
1639 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, "secret"); # use password "secret"
1640 $privkey = Net::SSLeay::PEM_read_bio_PrivateKey($bio, undef, ""); # use empty password
1641 Callback function signature:
1643 sub callback_func {
1645 my ($max_passwd_size, $rwflag, $data) = @_;
1646 # $max_passwd_size - maximum size of returned password (longer values will be discarded)
1647 # $rwflag - indicates whether we are loading (0) or storing (1) - for PEM_read_bio_PrivateKey always 0
1648 # $data - the data passed to PEM_read_bio_PrivateKey as 3rd parameter
1649 return "secret";
1651 }
1652 · PEM_get_string_X509
1654 NOTE: Does not exactly correspond to any low level API function
1656 Converts/exports X509 certificate to string (PEM format).
1658 Net::SSLeay::PEM_get_string_X509($x509);
1660 # $x509 - value corresponding to openssl's X509 structure
1661 #
1662 # returns: string with $x509 in PEM format
1663 · PEM_get_string_PrivateKey
1665 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1667 Converts public key $pk into PEM formatted string (optionally
1669 protected with password).
1670 my $rv = Net::SSLeay::PEM_get_string_PrivateKey($pk, $passwd, $enc_alg);
1672 # $pk - value corresponding to openssl's EVP_PKEY structure
1673 # $passwd - [optional] (string) password to use for key encryption
1674 # $enc_alg - [optional] algorithm to use for key encryption (default: DES_CBC) - value corresponding to openssl's EVP_CIPHER structure
1675 #
1676 # returns: PEM formatted string
1677 Examples:
1679 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk);
1681 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret");
1682 $pem_privkey = Net::SSLeay::PEM_get_string_PrivateKey($pk, "secret", Net::SSLeay::EVP_get_cipherbyname("DES-EDE3-CBC"));
1683 · PEM_get_string_X509_CRL
1685 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1687 Converts X509_CRL object $x509_crl into PEM formatted string.
1689 Net::SSLeay::PEM_get_string_X509_CRL($x509_crl);
1691 # $x509_crl - value corresponding to openssl's X509_CRL structure
1692 #
1693 # returns: no return value
1694 · PEM_get_string_X509_REQ
1696 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1698 Converts X509_REQ object $x509_crl into PEM formatted string.
1700 Net::SSLeay::PEM_get_string_X509_REQ($x509_req);
1702 # $x509_req - value corresponding to openssl's X509_REQ structure
1703 #
1704 # returns: no return value
1705 Low level API: d2i_* (DER format) related functions
1707 · d2i_X509_bio
1709 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1711 Loads DER formatted X509 certificate via given BIO structure.
1713 my $rv = Net::SSLeay::d2i_X509_bio($bp);
1715 # $bp - value corresponding to openssl's BIO structure
1716 #
1717 # returns: value corresponding to openssl's X509 structure (0 on failure)
1718 Example:
1720 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1722 my $x509 = Net::SSLeay::d2i_X509_bio($bio);
1723 Net::SSLeay::BIO_free($bio);
1724 Check openssl doc
1726 <http://www.openssl.org/docs/crypto/d2i_X509.html>
1727 · d2i_X509_CRL_bio
1729 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1731 Loads DER formatted X509_CRL object via given BIO structure.
1733 my $rv = Net::SSLeay::d2i_X509_CRL_bio($bp);
1735 # $bp - value corresponding to openssl's BIO structure
1736 #
1737 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
1738 Example:
1740 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1742 my $x509_crl = Net::SSLeay::d2i_X509_CRL_bio($bio);
1743 Net::SSLeay::BIO_free($bio);
1744 · d2i_X509_REQ_bio
1746 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1748 Loads DER formatted X509_REQ object via given BIO structure.
1750 my $rv = Net::SSLeay::d2i_X509_REQ_bio($bp);
1752 # $bp - value corresponding to openssl's BIO structure
1753 #
1754 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
1755 Example:
1757 my $bio = Net::SSLeay::BIO_new_file($filename, 'rb');
1759 my $x509_req = Net::SSLeay::d2i_X509_REQ_bio($bio);
1760 Net::SSLeay::BIO_free($bio);
1761 Low level API: PKCS12 related functions
1763 · P_PKCS12_load_file
1765 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
1767 Loads X509 certificate + private key + certificates of CA chain (if
1769 present in PKCS12 file).
1770 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, $load_chain, $password);
1772 # $filename - name of PKCS12 file
1773 # $load_chain - [optional] whether load (1) or not(0) CA chain (default: 0)
1774 # $password - [optional] password for private key
1775 #
1776 # returns: triplet ($privkey, $cert, @cachain)
1777 # $privkey - value corresponding to openssl's EVP_PKEY structure
1778 # $cert - value corresponding to openssl's X509 structure
1779 # @cachain - array of values corresponding to openssl's X509 structure (empty if no CA chain in PKCS12)
1780 IMPORTANT NOTE: after you do the job you need to call X509_free()
1782 on $privkey + all members of @cachain and EVP_PKEY_free() on
1783 $privkey.
1784 Examples:
1786 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename);
1788 #or
1789 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 0, $password);
1790 #or
1791 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1);
1792 #or
1793 my ($privkey, $cert, @cachain) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1794 #BEWARE: THIS IS WRONG - MEMORY LEAKS! (you cannot free @cachain items)
1796 my ($privkey, $cert) = Net::SSLeay::P_PKCS12_load_file($filename, 1, $password);
1797 NOTE With some combinations of Windows, perl, compiler and compiler
1799 options, you may see a runtime error "no OPENSSL_Applink", when
1800 calling Net::SSLeay::P_PKCS12_load_file. See README.Win32 for more
1801 details.
1802 Low level API: SESSION_* related functions
1804 · d2i_SSL_SESSION
1806 Transforms the external ASN1 representation of an SSL/TLS session,
1808 stored as binary data at location pp with length of $length, into
1809 an SSL_SESSION object.
1810 ??? (does this function really work?)
1812 my $rv = Net::SSLeay::d2i_SSL_SESSION($a, $pp, $length);
1814 # $a - value corresponding to openssl's SSL_SESSION structure
1815 # $pp - pointer/buffer ???
1816 # $length - ???
1817 #
1818 # returns: ???
1819 Check openssl doc
1821 <http://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1822 · i2d_SSL_SESSION
1824 Transforms the SSL_SESSION object in into the ASN1 representation
1826 and stores it into the memory location pointed to by pp. The length
1827 of the resulting ASN1 representation is returned.
1828 ??? (does this function really work?)
1830 my $rv = Net::SSLeay::i2d_SSL_SESSION($in, $pp);
1832 # $in - value corresponding to openssl's SSL_SESSION structure
1833 # $pp - pointer/data ???
1834 #
1835 # returns: 1 on success, 0
1836 Check openssl doc
1838 <http://www.openssl.org/docs/ssl/d2i_SSL_SESSION.html>
1839 · SESSION_new
1841 Creates a new SSL_SESSION structure.
1843 my $rv = Net::SSLeay::SESSION_new();
1845 #
1846 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
1847 · SESSION_free
1849 Free an allocated SSL_SESSION structure.
1851 Net::SSLeay::SESSION_free($ses);
1853 # $ses - value corresponding to openssl's SSL_SESSION structure
1854 #
1855 # returns: no return value
1856 Check openssl doc
1858 <http://www.openssl.org/docs/ssl/SSL_SESSION_free.html>
1859 · SESSION_cmp
1861 Compare two SSL_SESSION structures.
1863 my $rv = Net::SSLeay::SESSION_cmp($sesa, $sesb);
1865 # $sesa - value corresponding to openssl's SSL_SESSION structure
1866 # $sesb - value corresponding to openssl's SSL_SESSION structure
1867 #
1868 # returns: 0 if the two structures are the same
1869 NOTE: Not available in openssl 1.0 or later
1871 · SESSION_get_app_data
1873 Can be used to get application defined value/data.
1875 my $rv = Net::SSLeay::SESSION_get_app_data($ses);
1877 # $ses - value corresponding to openssl's SSL_SESSION structure
1878 #
1879 # returns: string/buffer/pointer ???
1880 · SESSION_set_app_data
1882 Can be used to set some application defined value/data.
1884 my $rv = Net::SSLeay::SESSION_set_app_data($s, $a);
1886 # $s - value corresponding to openssl's SSL_SESSION structure
1887 # $a - (string/buffer/pointer ???) data
1888 #
1889 # returns: ???
1890 · SESSION_get_ex_data
1892 Is used to retrieve the information for $idx from session $ses.
1894 my $rv = Net::SSLeay::SESSION_get_ex_data($ses, $idx);
1896 # $ses - value corresponding to openssl's SSL_SESSION structure
1897 # $idx - (integer) index for application specific data
1898 #
1899 # returns: pointer to ???
1900 Check openssl doc
1902 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1903 · SESSION_set_ex_data
1905 Is used to store application data at arg for idx into the session
1907 object.
1908 my $rv = Net::SSLeay::SESSION_set_ex_data($ss, $idx, $data);
1910 # $ss - value corresponding to openssl's SSL_SESSION structure
1911 # $idx - (integer) ???
1912 # $data - (pointer) ???
1913 #
1914 # returns: 1 on success, 0 on failure
1915 Check openssl doc
1917 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1918 · SESSION_get_ex_new_index
1920 Is used to register a new index for application specific data.
1922 my $rv = Net::SSLeay::SESSION_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
1924 # $argl - (long) ???
1925 # $argp - (pointer) ???
1926 # $new_func - function pointer ??? (CRYPTO_EX_new *)
1927 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
1928 # $free_func - function pointer ??? (CRYPTO_EX_free *)
1929 #
1930 # returns: (integer) ???
1931 Check openssl doc
1933 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_ex_new_index.html>
1934 · SESSION_get_master_key
1936 NOTE: Does not exactly correspond to any low level API function
1938 Returns 'master_key' value from SSL_SESSION structure $s
1940 Net::SSLeay::SESSION_get_master_key($s);
1942 # $s - value corresponding to openssl's SSL_SESSION structure
1943 #
1944 # returns: master key (binary data)
1945 · SESSION_set_master_key
1947 Sets 'master_key' value for SSL_SESSION structure $s
1949 Net::SSLeay::SESSION_set_master_key($s, $key);
1951 # $s - value corresponding to openssl's SSL_SESSION structure
1952 # $key - master key (binary data)
1953 #
1954 # returns: no return value
1955 Not available with OpenSSL 1.1 and later. Code that previously
1957 used
1958 SESSION_set_master_key must now set $secret in the
1959 session_secret
1960 callback set with SSL_set_session_secret_cb.
1961 · SESSION_get_time
1963 Returns the time at which the session s was established. The time
1965 is given in seconds since 1.1.1970.
1966 my $rv = Net::SSLeay::SESSION_get_time($s);
1968 # $s - value corresponding to openssl's SSL_SESSION structure
1969 #
1970 # returns: timestamp (seconds since 1.1.1970)
1971 Check openssl doc
1973 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1974 · get_time
1976 Technically the same functionality as "SESSION_get_time".
1978 my $rv = Net::SSLeay::get_time($s);
1980 · SESSION_get_timeout
1982 Returns the timeout value set for session $s in seconds.
1984 my $rv = Net::SSLeay::SESSION_get_timeout($s);
1986 # $s - value corresponding to openssl's SSL_SESSION structure
1987 #
1988 # returns: timeout (in seconds)
1989 Check openssl doc
1991 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
1992 · get_timeout
1994 Technically the same functionality as "SESSION_get_timeout".
1996 my $rv = Net::SSLeay::get_timeout($s);
1998 · SESSION_print
2000 NOTE: Does not exactly correspond to any low level API function
2002 Prints session details (e.g. protocol version, cipher, session-id
2004 ...) to BIO.
2005 my $rv = Net::SSLeay::SESSION_print($fp, $ses);
2007 # $fp - value corresponding to openssl's BIO structure
2008 # $ses - value corresponding to openssl's SSL_SESSION structure
2009 #
2010 # returns: 1 on success, 0 on failure
2011 You have to use necessary BIO functions like this:
2013 # let us have $ssl corresponding to openssl's SSL structure
2015 my $ses = Net::SSLeay::get_session($ssl);
2016 my $bio = Net::SSLeay::BIO_new(&Net::SSLeay::BIO_s_mem);
2017 Net::SSLeay::SESSION_print($bio, $ses);
2018 print Net::SSLeay::BIO_read($bio);
2019 · SESSION_print_fp
2021 Prints session details (e.g. protocol version, cipher, session-id
2023 ...) to file handle.
2024 my $rv = Net::SSLeay::SESSION_print_fp($fp, $ses);
2026 # $fp - perl file handle
2027 # $ses - value corresponding to openssl's SSL_SESSION structure
2028 #
2029 # returns: 1 on success, 0 on failure
2030 Example:
2032 # let us have $ssl corresponding to openssl's SSL structure
2034 my $ses = Net::SSLeay::get_session($ssl);
2035 open my $fh, ">", "output.txt";
2036 Net::SSLeay::SESSION_print_fp($fh,$ses);
2037 · SESSION_set_time
2039 Replaces the creation time of the session s with the chosen value
2041 $t (seconds since 1.1.1970).
2042 my $rv = Net::SSLeay::SESSION_set_time($ses, $t);
2044 # $ses - value corresponding to openssl's SSL_SESSION structure
2045 # $t - time value
2046 #
2047 # returns: 1 on success
2048 Check openssl doc
2050 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2051 · set_time
2053 Technically the same functionality as "SESSION_set_time".
2055 my $rv = Net::SSLeay::set_time($ses, $t);
2057 · SESSION_set_timeout
2059 Sets the timeout value for session s in seconds to $t.
2061 my $rv = Net::SSLeay::SESSION_set_timeout($s, $t);
2063 # $s - value corresponding to openssl's SSL_SESSION structure
2064 # $t - timeout (in seconds)
2065 #
2066 # returns: 1 on success
2067 Check openssl doc
2069 <http://www.openssl.org/docs/ssl/SSL_SESSION_get_time.html>
2070 · set_timeout
2072 Technically the same functionality as "SESSION_set_timeout".
2074 my $rv = Net::SSLeay::set_timeout($ses, $t);
2076 Low level API: SSL_CTX_* related functions
2078 NOTE: Please note that the function described in this chapter have
2080 "SSL_" part stripped from their original openssl names.
2081 · CTX_add_client_CA
2083 Adds the CA name extracted from $cacert to the list of CAs sent to
2085 the client when requesting a client certificate for $ctx.
2086 my $rv = Net::SSLeay::CTX_add_client_CA($ctx, $cacert);
2088 # $ctx - value corresponding to openssl's SSL_CTX structure
2089 # $cacert - value corresponding to openssl's X509 structure
2090 #
2091 # returns: 1 on success, 0 on failure
2092 Check openssl doc
2094 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2095 · CTX_add_extra_chain_cert
2097 Adds the certificate $x509 to the certificate chain presented
2099 together with the certificate. Several certificates can be added
2100 one after the other.
2101 my $rv = Net::SSLeay::CTX_add_extra_chain_cert($ctx, $x509);
2103 # $ctx - value corresponding to openssl's SSL_CTX structure
2104 # $x509 - value corresponding to openssl's X509 structure
2105 #
2106 # returns: 1 on success, check out the error stack to find out the reason for failure otherwise
2107 Check openssl doc
2109 <http://www.openssl.org/docs/ssl/SSL_CTX_add_extra_chain_cert.html>
2110 · CTX_add_session
2112 Adds the session $ses to the context $ctx.
2114 my $rv = Net::SSLeay::CTX_add_session($ctx, $ses);
2116 # $ctx - value corresponding to openssl's SSL_CTX structure
2117 # $ses - value corresponding to openssl's SSL_SESSION structure
2118 #
2119 # returns: 1 on success, 0 on failure
2120 Check openssl doc
2122 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2123 · CTX_callback_ctrl
2125 ??? (more info needed)
2127 my $rv = Net::SSLeay::CTX_callback_ctrl($ctx, $cmd, $fp);
2129 # $ctx - value corresponding to openssl's SSL_CTX structure
2130 # $cmd - (integer) command id
2131 # $fp - (function pointer) ???
2132 #
2133 # returns: ???
2134 Check openssl doc
2136 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2137 · CTX_check_private_key
2139 Checks the consistency of a private key with the corresponding
2141 certificate loaded into $ctx.
2142 my $rv = Net::SSLeay::CTX_check_private_key($ctx);
2144 # $ctx - value corresponding to openssl's SSL_CTX structure
2145 #
2146 # returns: 1 on success, otherwise check out the error stack to find out the reason
2147 Check openssl doc
2149 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
2150 · CTX_ctrl
2152 Internal handling function for SSL_CTX objects.
2154 BEWARE: openssl doc says: This function should never be called
2156 directly!
2157 my $rv = Net::SSLeay::CTX_ctrl($ctx, $cmd, $larg, $parg);
2159 # $ctx - value corresponding to openssl's SSL_CTX structure
2160 # $cmd - (integer) command id
2161 # $larg - (integer) long ???
2162 # $parg - (string/pointer) ???
2163 #
2164 # returns: (long) result of given command ???
2165 #valid $cmd values
2167 1 - SSL_CTRL_NEED_TMP_RSA
2168 2 - SSL_CTRL_SET_TMP_RSA
2169 3 - SSL_CTRL_SET_TMP_DH
2170 4 - SSL_CTRL_SET_TMP_ECDH
2171 5 - SSL_CTRL_SET_TMP_RSA_CB
2172 6 - SSL_CTRL_SET_TMP_DH_CB
2173 7 - SSL_CTRL_SET_TMP_ECDH_CB
2174 8 - SSL_CTRL_GET_SESSION_REUSED
2175 9 - SSL_CTRL_GET_CLIENT_CERT_REQUEST
2176 10 - SSL_CTRL_GET_NUM_RENEGOTIATIONS
2177 11 - SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS
2178 12 - SSL_CTRL_GET_TOTAL_RENEGOTIATIONS
2179 13 - SSL_CTRL_GET_FLAGS
2180 14 - SSL_CTRL_EXTRA_CHAIN_CERT
2181 15 - SSL_CTRL_SET_MSG_CALLBACK
2182 16 - SSL_CTRL_SET_MSG_CALLBACK_ARG
2183 17 - SSL_CTRL_SET_MTU
2184 20 - SSL_CTRL_SESS_NUMBER
2185 21 - SSL_CTRL_SESS_CONNECT
2186 22 - SSL_CTRL_SESS_CONNECT_GOOD
2187 23 - SSL_CTRL_SESS_CONNECT_RENEGOTIATE
2188 24 - SSL_CTRL_SESS_ACCEPT
2189 25 - SSL_CTRL_SESS_ACCEPT_GOOD
2190 26 - SSL_CTRL_SESS_ACCEPT_RENEGOTIATE
2191 27 - SSL_CTRL_SESS_HIT
2192 28 - SSL_CTRL_SESS_CB_HIT
2193 29 - SSL_CTRL_SESS_MISSES
2194 30 - SSL_CTRL_SESS_TIMEOUTS
2195 31 - SSL_CTRL_SESS_CACHE_FULL
2196 32 - SSL_CTRL_OPTIONS
2197 33 - SSL_CTRL_MODE
2198 40 - SSL_CTRL_GET_READ_AHEAD
2199 41 - SSL_CTRL_SET_READ_AHEAD
2200 42 - SSL_CTRL_SET_SESS_CACHE_SIZE
2201 43 - SSL_CTRL_GET_SESS_CACHE_SIZE
2202 44 - SSL_CTRL_SET_SESS_CACHE_MODE
2203 45 - SSL_CTRL_GET_SESS_CACHE_MODE
2204 50 - SSL_CTRL_GET_MAX_CERT_LIST
2205 51 - SSL_CTRL_SET_MAX_CERT_LIST
2206 52 - SSL_CTRL_SET_MAX_SEND_FRAGMENT
2207 53 - SSL_CTRL_SET_TLSEXT_SERVERNAME_CB
2208 54 - SSL_CTRL_SET_TLSEXT_SERVERNAME_ARG
2209 55 - SSL_CTRL_SET_TLSEXT_HOSTNAME
2210 56 - SSL_CTRL_SET_TLSEXT_DEBUG_CB
2211 57 - SSL_CTRL_SET_TLSEXT_DEBUG_ARG
2212 58 - SSL_CTRL_GET_TLSEXT_TICKET_KEYS
2213 59 - SSL_CTRL_SET_TLSEXT_TICKET_KEYS
2214 60 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT
2215 61 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB
2216 62 - SSL_CTRL_SET_TLSEXT_OPAQUE_PRF_INPUT_CB_ARG
2217 63 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB
2218 64 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_CB_ARG
2219 65 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_TYPE
2220 66 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_EXTS
2221 67 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_EXTS
2222 68 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_IDS
2223 69 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_IDS
2224 70 - SSL_CTRL_GET_TLSEXT_STATUS_REQ_OCSP_RESP
2225 71 - SSL_CTRL_SET_TLSEXT_STATUS_REQ_OCSP_RESP
2226 72 - SSL_CTRL_SET_TLSEXT_TICKET_KEY_CB
2227 73 - DTLS_CTRL_GET_TIMEOUT
2228 74 - DTLS_CTRL_HANDLE_TIMEOUT
2229 75 - DTLS_CTRL_LISTEN
2230 76 - SSL_CTRL_GET_RI_SUPPORT
2231 77 - SSL_CTRL_CLEAR_OPTIONS
2232 78 - SSL_CTRL_CLEAR_MODE
2233 82 - SSL_CTRL_GET_EXTRA_CHAIN_CERTS
2235 83 - SSL_CTRL_CLEAR_EXTRA_CHAIN_CERTS
2236 88 - SSL_CTRL_CHAIN
2238 89 - SSL_CTRL_CHAIN_CERT
2239 90 - SSL_CTRL_GET_CURVES
2241 91 - SSL_CTRL_SET_CURVES
2242 92 - SSL_CTRL_SET_CURVES_LIST
2243 93 - SSL_CTRL_GET_SHARED_CURVE
2244 94 - SSL_CTRL_SET_ECDH_AUTO
2245 97 - SSL_CTRL_SET_SIGALGS
2246 98 - SSL_CTRL_SET_SIGALGS_LIST
2247 99 - SSL_CTRL_CERT_FLAGS
2248 100 - SSL_CTRL_CLEAR_CERT_FLAGS
2249 101 - SSL_CTRL_SET_CLIENT_SIGALGS
2250 102 - SSL_CTRL_SET_CLIENT_SIGALGS_LIST
2251 103 - SSL_CTRL_GET_CLIENT_CERT_TYPES
2252 104 - SSL_CTRL_SET_CLIENT_CERT_TYPES
2253 105 - SSL_CTRL_BUILD_CERT_CHAIN
2254 106 - SSL_CTRL_SET_VERIFY_CERT_STORE
2255 107 - SSL_CTRL_SET_CHAIN_CERT_STORE
2256 108 - SSL_CTRL_GET_PEER_SIGNATURE_NID
2257 109 - SSL_CTRL_GET_SERVER_TMP_KEY
2258 110 - SSL_CTRL_GET_RAW_CIPHERLIST
2259 111 - SSL_CTRL_GET_EC_POINT_FORMATS
2260 112 - SSL_CTRL_GET_TLSA_RECORD
2261 113 - SSL_CTRL_SET_TLSA_RECORD
2262 114 - SSL_CTRL_PULL_TLSA_RECORD
2263 Check openssl doc
2265 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
2266 · CTX_flush_sessions
2268 Causes a run through the session cache of $ctx to remove sessions
2270 expired at time $tm.
2271 Net::SSLeay::CTX_flush_sessions($ctx, $tm);
2273 # $ctx - value corresponding to openssl's SSL_CTX structure
2274 # $tm - specifies the time which should be used for the expiration test (seconds since 1.1.1970)
2275 #
2276 # returns: no return value
2277 Check openssl doc
2279 <http://www.openssl.org/docs/ssl/SSL_CTX_flush_sessions.html>
2280 · CTX_free
2282 Free an allocated SSL_CTX object.
2284 Net::SSLeay::CTX_free($ctx);
2286 # $ctx - value corresponding to openssl's SSL_CTX structure
2287 #
2288 # returns: no return value
2289 Check openssl doc
2291 <http://www.openssl.org/docs/ssl/SSL_CTX_free.html>
2292 · CTX_get_app_data
2294 Can be used to get application defined value/data.
2296 my $rv = Net::SSLeay::CTX_get_app_data($ctx);
2298 # $ctx - value corresponding to openssl's SSL_CTX structure
2299 #
2300 # returns: string/buffer/pointer ???
2301 · CTX_set_app_data
2303 Can be used to set some application defined value/data.
2305 my $rv = Net::SSLeay::CTX_set_app_data($ctx, $arg);
2307 # $ctx - value corresponding to openssl's SSL_CTX structure
2308 # $arg - (string/buffer/pointer ???) data
2309 #
2310 # returns: ???
2311 · CTX_get0_param
2313 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2315 requires at least OpenSSL 1.0.2
2316 Returns the current verification parameters.
2318 my $vpm = Net::SSLeay::CTX_get0_param($ctx);
2320 # $ctx - value corresponding to openssl's SSL_CTX structure
2321 #
2322 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
2323 Check openssl doc
2325 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2326 · CTX_get_cert_store
2328 Returns the current certificate verification storage.
2330 my $rv = Net::SSLeay::CTX_get_cert_store($ctx);
2332 # $ctx - value corresponding to openssl's SSL_CTX structure
2333 #
2334 # returns: value corresponding to openssl's X509_STORE structure (0 on failure)
2335 Check openssl doc
2337 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2338 · CTX_get_client_CA_list
2340 Returns the list of client CAs explicitly set for $ctx using
2342 "CTX_set_client_CA_list".
2343 my $rv = Net::SSLeay::CTX_get_client_CA_list($ctx);
2345 # $ctx - value corresponding to openssl's SSL_CTX structure
2346 #
2347 # returns: value corresponding to openssl's X509_NAME_STACK structure (0 on failure)
2348 Check openssl doc
2350 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
2351 · CTX_get_ex_data
2353 Is used to retrieve the information for index $idx from $ctx.
2355 my $rv = Net::SSLeay::CTX_get_ex_data($ssl, $idx);
2357 # $ssl - value corresponding to openssl's SSL_CTX structure
2358 # $idx - (integer) index for application specific data
2359 #
2360 # returns: pointer to ???
2361 Check openssl doc
2363 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2364 · CTX_get_ex_new_index
2366 Is used to register a new index for application specific data.
2368 my $rv = Net::SSLeay::CTX_get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
2370 # $argl - (long) ???
2371 # $argp - (pointer) ???
2372 # $new_func - function pointer ??? (CRYPTO_EX_new *)
2373 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
2374 # $free_func - function pointer ??? (CRYPTO_EX_free *)
2375 #
2376 # returns: (integer) ???
2377 Check openssl doc
2379 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
2380 · CTX_get_mode
2382 Returns the mode set for ctx.
2384 my $rv = Net::SSLeay::CTX_get_mode($ctx);
2386 # $ctx - value corresponding to openssl's SSL_CTX structure
2387 #
2388 # returns: mode (bitmask)
2389 #to decode the return value (bitmask) use:
2391 0x00000001 corresponds to SSL_MODE_ENABLE_PARTIAL_WRITE
2392 0x00000002 corresponds to SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER
2393 0x00000004 corresponds to SSL_MODE_AUTO_RETRY
2394 0x00000008 corresponds to SSL_MODE_NO_AUTO_CHAIN
2395 0x00000010 corresponds to SSL_MODE_RELEASE_BUFFERS
2396 (note: some of the bits might not be supported by older openssl versions)
2397 Check openssl doc
2399 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2400 · CTX_set_mode
2402 Adds the mode set via bitmask in $mode to $ctx. Options already set
2404 before are not cleared.
2405 my $rv = Net::SSLeay::CTX_set_mode($ctx, $mode);
2407 # $ctx - value corresponding to openssl's SSL_CTX structure
2408 # $mode - mode bitmask
2409 #
2410 # returns: the new mode bitmask after adding $mode
2411 For bitmask details see "CTX_get_mode" (above).
2413 Check openssl doc
2415 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
2416 · CTX_get_options
2418 Returns the options (bitmask) set for $ctx.
2420 my $rv = Net::SSLeay::CTX_get_options($ctx);
2422 # $ctx - value corresponding to openssl's SSL_CTX structure
2423 #
2424 # returns: options (bitmask)
2425 BEWARE: The available constants and their values in bitmask depend
2427 on the TLS library. For example, SSL_OP_NO_TLSv1_3 became available
2428 much later than SSL_OP_NO_COMPRESS which is already deprecated by
2429 some libraries. Also, some previously used option values have been
2430 recycled and are now used for newer options. See the list of
2431 constants in this document for options Net::SSLeay currently
2432 supports.
2433 You are strongly encouraged to check your TLS library if you need
2435 to use numeric values directly. The following is a sample of
2436 historic values. It may not be correct anymore.
2437 #to decode the return value (bitmask) use:
2439 0x00000004 corresponds to SSL_OP_LEGACY_SERVER_CONNECT
2440 0x00000800 corresponds to SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS
2441 0x00004000 corresponds to SSL_OP_NO_TICKET
2442 0x00010000 corresponds to SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
2443 0x00400000 corresponds to SSL_OP_CIPHER_SERVER_PREFERENCE
2444 0x04000000 corresponds to SSL_OP_NO_TLSv1
2445 Check openssl doc
2447 <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2448 · CTX_set_options
2450 Adds the options set via bitmask in $options to ctx. Options
2452 already set before are not cleared.
2453 Net::SSLeay::CTX_set_options($ctx, $options);
2455 # $ctx - value corresponding to openssl's SSL_CTX structure
2456 # $options - options bitmask
2457 #
2458 # returns: the new options bitmask after adding $options
2459 For bitmask details see "CTX_get_options" (above).
2461 Check openssl doc
2463 <https://www.openssl.org/docs/man1.0.2/ssl/SSL_CTX_set_options.html>
2464 · CTX_get_quiet_shutdown
2466 Returns the 'quiet shutdown' setting of $ctx.
2468 my $rv = Net::SSLeay::CTX_get_quiet_shutdown($ctx);
2470 # $ctx - value corresponding to openssl's SSL_CTX structure
2471 #
2472 # returns: (integer) the current setting
2473 Check openssl doc
2475 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
2476 · CTX_get_read_ahead
2478 my $rv = Net::SSLeay::CTX_get_read_ahead($ctx);
2480 # $ctx - value corresponding to openssl's SSL_CTX structure
2481 #
2482 # returns: (integer) read_ahead value
2483 · CTX_get_session_cache_mode
2485 Returns the currently used cache mode (bitmask).
2487 my $rv = Net::SSLeay::CTX_get_session_cache_mode($ctx);
2489 # $ctx - value corresponding to openssl's SSL_CTX structure
2490 #
2491 # returns: mode (bitmask)
2492 BEWARE: SESS_CACHE_OFF and other constants are not available in
2494 Net-SSLeay-1.82 and before. If the constants are not available,
2495 the following values have historically been correct. You are
2496 strongly encouraged to check your TLS library for the current
2497 values.
2498 #to decode the return value (bitmask) use:
2500 0x0000 corresponds to SSL_SESS_CACHE_OFF
2501 0x0001 corresponds to SSL_SESS_CACHE_CLIENT
2502 0x0002 corresponds to SSL_SESS_CACHE_SERVER
2503 0x0080 corresponds to SSL_SESS_CACHE_NO_AUTO_CLEAR
2504 0x0100 corresponds to SSL_SESS_CACHE_NO_INTERNAL_LOOKUP
2505 0x0200 corresponds to SSL_SESS_CACHE_NO_INTERNAL_STORE
2506 (note: some of the bits might not be supported by older openssl versions)
2507 Check openssl doc
2509 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2510 · CTX_set_session_cache_mode
2512 Enables/disables session caching by setting the operational mode
2514 for $ctx to $mode.
2515 my $rv = Net::SSLeay::CTX_set_session_cache_mode($ctx, $mode);
2517 # $ctx - value corresponding to openssl's SSL_CTX structure
2518 # $mode - mode (bitmask)
2519 #
2520 # returns: previously set cache mode
2521 For bitmask details see "CTX_get_session_cache_mode" (above).
2523 Check openssl doc
2525 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_cache_mode.html>
2526 · CTX_get_timeout
2528 Returns the currently set timeout value for $ctx.
2530 my $rv = Net::SSLeay::CTX_get_timeout($ctx);
2532 # $ctx - value corresponding to openssl's SSL_CTX structure
2533 #
2534 # returns: timeout in seconds
2535 Check openssl doc
2537 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
2538 · CTX_get_verify_depth
2540 Returns the verification depth limit currently set in $ctx. If no
2542 limit has been explicitly set, -1 is returned and the default value
2543 will be used.",
2544 my $rv = Net::SSLeay::CTX_get_verify_depth($ctx);
2546 # $ctx - value corresponding to openssl's SSL_CTX structure
2547 #
2548 # returns: depth limit currently set in $ctx, -1 if no limit has been explicitly set
2549 Check openssl doc
2551 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2552 · CTX_get_verify_mode
2554 Returns the verification mode (bitmask) currently set in $ctx.
2556 my $rv = Net::SSLeay::CTX_get_verify_mode($ctx);
2558 # $ctx - value corresponding to openssl's SSL_CTX structure
2559 #
2560 # returns: mode (bitmask)
2561 #to decode the return value (bitmask) use:
2563 0x00 corresponds to SSL_VERIFY_NONE
2564 0x01 corresponds to SSL_VERIFY_PEER
2565 0x02 corresponds to SSL_VERIFY_FAIL_IF_NO_PEER_CERT
2566 0x04 corresponds to SSL_VERIFY_CLIENT_ONCE
2567 (note: some of the bits might not be supported by older openssl versions)
2568 Check openssl doc
2570 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
2571 · CTX_set_verify
2573 Sets the verification flags for $ctx to be $mode and specifies the
2575 verify_callback function to be used.
2576 Net::SSLeay::CTX_set_verify($ctx, $mode, $callback);
2578 # $ctx - value corresponding to openssl's SSL_CTX structure
2579 # $mode - mode (bitmask)
2580 # $callback - [optional] reference to perl callback function
2581 #
2582 # returns: no return value
2583 For bitmask details see "CTX_get_verify_mode" (above).
2585 Check openssl doc
2587 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
2588 · CTX_load_verify_locations
2590 Specifies the locations for $ctx, at which CA certificates for
2592 verification purposes are located. The certificates available via
2593 $CAfile and $CApath are trusted.
2594 my $rv = Net::SSLeay::CTX_load_verify_locations($ctx, $CAfile, $CApath);
2596 # $ctx - value corresponding to openssl's SSL_CTX structure
2597 # $CAfile - (string) file of CA certificates in PEM format, the file can contain several CA certificates (or '')
2598 # $CApath - (string) directory containing CA certificates in PEM format (or '')
2599 #
2600 # returns: 1 on success, 0 on failure (check the error stack to find out the reason)
2601 Check openssl doc
2603 <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>
2604 · CTX_need_tmp_RSA
2606 Return the result of
2608 "SSL_CTX_ctrl(ctx,SSL_CTRL_NEED_TMP_RSA,0,NULL)"
2609 my $rv = Net::SSLeay::CTX_need_tmp_RSA($ctx);
2611 # $ctx - value corresponding to openssl's SSL_CTX structure
2612 #
2613 # returns: result of SSL_CTRL_NEED_TMP_RSA command
2614 Not available with OpenSSL 1.1 and later.
2616 · CTX_new
2618 The same as "CTX_v23_new"
2620 my $rv = Net::SSLeay::CTX_new();
2622 #
2623 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2624 Check openssl doc
2626 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2627 Not available with OpenSSL 1.1 and later.
2629 · CTX_v2_new
2631 Creates a new SSL_CTX object - based on SSLv2_method() - as
2633 framework to establish TLS/SSL enabled connections.
2634 my $rv = Net::SSLeay::CTX_v2_new();
2636 #
2637 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2638 · CTX_v23_new
2640 Creates a new SSL_CTX object - based on SSLv23_method() - as
2642 framework to establish TLS/SSL enabled connections.
2643 my $rv = Net::SSLeay::CTX_v23_new();
2645 #
2646 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2647 · CTX_v3_new
2649 Creates a new SSL_CTX object - based on SSLv3_method() - as
2651 framework to establish TLS/SSL enabled connections.
2652 my $rv = Net::SSLeay::CTX_v3_new();
2654 #
2655 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2656 · CTX_tlsv1_new
2658 Creates a new SSL_CTX object - based on TLSv1_method() - as
2660 framework to establish TLS/SSL enabled connections.
2661 my $rv = Net::SSLeay::CTX_tlsv1_new();
2663 #
2664 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2665 · CTX_tlsv1_1_new
2667 Creates a new SSL_CTX object - based on TLSv1_1_method() - as
2669 framework to establish TLS/SSL enabled connections. Only available
2670 where supported by the underlying openssl.
2671 my $rv = Net::SSLeay::CTX_tlsv1_1_new();
2673 #
2674 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2675 · CTX_tlsv1_2_new
2677 Creates a new SSL_CTX object - based on TLSv1_2_method() - as
2679 framework to establish TLS/SSL enabled connections. Only available
2680 where supported by the underlying openssl.
2681 my $rv = Net::SSLeay::CTX_tlsv1_2_new();
2683 #
2684 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2685 · CTX_new_with_method
2687 Creates a new SSL_CTX object based on $meth method
2689 my $rv = Net::SSLeay::CTX_new_with_method($meth);
2691 # $meth - value corresponding to openssl's SSL_METHOD structure
2692 #
2693 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
2694 #example
2696 my $ctx = Net::SSLeay::CTX_new_with_method(&Net::SSLeay::TLSv1_method);
2697 Check openssl doc
2699 <http://www.openssl.org/docs/ssl/SSL_CTX_new.html>
2700 · CTX_set_min_proto_version, CTX_set_max_proto_version,
2702 set_min_proto_version and set_max_proto_version,
2703 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2705 requires at least OpenSSL 1.1.0 or LibreSSL 2.6.0
2706 Set the minimum and maximum supported protocol for $ctx or $ssl.
2708 my $rv = Net::SSLeay::CTX_set_min_proto_version($ctx, $version)
2710 # $ctx - value corresponding to openssl's SSL_CTX structure
2711 # $version - (integer) constat version value or 0 for automatic lowest or highest value
2712 #
2713 # returns: 1 on success, 0 on failure
2714 #example: allow only TLS 1.2 for a SSL_CTX
2716 my $rv_min = Net::SSLeay::CTX_set_min_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2717 my $rv_max = Net::SSLeay::CTX_set_max_proto_version($ctx, Net::SSLeay::TLS1_2_VERSION());
2718 #example: allow only TLS 1.1 for a SSL
2720 my $rv_min = Net::SSLeay::set_min_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2721 my $rv_max = Net::SSLeay::set_max_proto_version($ssl, Net::SSLeay::TLS1_1_VERSION());
2722 Check openssl doc
2724 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2725 · CTX_get_min_proto_version, CTX_get_max_proto_version,
2727 get_min_proto_version and get_max_proto_version,
2728 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
2730 requires at least OpenSSL 1.1.0g
2731 Get the minimum and maximum supported protocol for $ctx or $ssl.
2733 my $version = Net::SSLeay::CTX_get_min_proto_version($ctx)
2735 # $ctx - value corresponding to openssl's SSL_CTX structure
2736 #
2737 # returns: 0 automatic lowest or highest value, configured value otherwise
2738 Check openssl doc
2740 <https://www.openssl.org/docs/manmaster/man3/SSL_CTX_set_min_proto_version.html>
2741 · CTX_remove_session
2743 Removes the session $ses from the context $ctx.
2745 my $rv = Net::SSLeay::CTX_remove_session($ctx, $ses);
2747 # $ctx - value corresponding to openssl's SSL_CTX structure
2748 # $ses - value corresponding to openssl's SSL_SESSION structure
2749 #
2750 # returns: 1 on success, 0 on failure
2751 Check openssl doc
2753 <http://www.openssl.org/docs/ssl/SSL_CTX_add_session.html>
2754 · CTX_sess_accept
2756 my $rv = Net::SSLeay::CTX_sess_accept($ctx);
2758 # $ctx - value corresponding to openssl's SSL_CTX structure
2759 #
2760 # returns: number of started SSL/TLS handshakes in server mode
2761 Check openssl doc
2763 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2764 · CTX_sess_accept_good
2766 my $rv = Net::SSLeay::CTX_sess_accept_good($ctx);
2768 # $ctx - value corresponding to openssl's SSL_CTX structure
2769 #
2770 # returns: number of successfully established SSL/TLS sessions in server mode
2771 Check openssl doc
2773 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2774 · CTX_sess_accept_renegotiate
2776 my $rv = Net::SSLeay::CTX_sess_accept_renegotiate($ctx);
2778 # $ctx - value corresponding to openssl's SSL_CTX structure
2779 #
2780 # returns: number of start renegotiations in server mode
2781 Check openssl doc
2783 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2784 · CTX_sess_cache_full
2786 my $rv = Net::SSLeay::CTX_sess_cache_full($ctx);
2788 # $ctx - value corresponding to openssl's SSL_CTX structure
2789 #
2790 # returns: number of sessions that were removed because the maximum session cache size was exceeded
2791 Check openssl doc
2793 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2794 · CTX_sess_cb_hits
2796 my $rv = Net::SSLeay::CTX_sess_cb_hits($ctx);
2798 # $ctx - value corresponding to openssl's SSL_CTX structure
2799 #
2800 # returns: number of successfully retrieved sessions from the external session cache in server mode
2801 Check openssl doc
2803 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2804 · CTX_sess_connect
2806 my $rv = Net::SSLeay::CTX_sess_connect($ctx);
2808 # $ctx - value corresponding to openssl's SSL_CTX structure
2809 #
2810 # returns: number of started SSL/TLS handshakes in client mode
2811 Check openssl doc
2813 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2814 · CTX_sess_connect_good
2816 my $rv = Net::SSLeay::CTX_sess_connect_good($ctx);
2818 # $ctx - value corresponding to openssl's SSL_CTX structure
2819 #
2820 # returns: number of successfully established SSL/TLS sessions in client mode
2821 Check openssl doc
2823 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2824 · CTX_sess_connect_renegotiate
2826 my $rv = Net::SSLeay::CTX_sess_connect_renegotiate($ctx);
2828 # $ctx - value corresponding to openssl's SSL_CTX structure
2829 #
2830 # returns: number of start renegotiations in client mode
2831 Check openssl doc
2833 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2834 · CTX_sess_get_cache_size
2836 Returns the currently valid session cache size.
2838 my $rv = Net::SSLeay::CTX_sess_get_cache_size($ctx);
2840 # $ctx - value corresponding to openssl's SSL_CTX structure
2841 #
2842 # returns: current size
2843 Check openssl doc
2845 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2846 · CTX_sess_hits
2848 my $rv = Net::SSLeay::CTX_sess_hits($ctx);
2850 # $ctx - value corresponding to openssl's SSL_CTX structure
2851 #
2852 # returns: number of successfully reused sessions
2853 Check openssl doc
2855 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2856 · CTX_sess_misses
2858 my $rv = Net::SSLeay::CTX_sess_misses($ctx);
2860 # $ctx - value corresponding to openssl's SSL_CTX structure
2861 #
2862 # returns: number of sessions proposed by clients that were not found in the internal session cache in server mode
2863 Check openssl doc
2865 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2866 · CTX_sess_number
2868 my $rv = Net::SSLeay::CTX_sess_number($ctx);
2870 # $ctx - value corresponding to openssl's SSL_CTX structure
2871 #
2872 # returns: current number of sessions in the internal session cache
2873 Check openssl doc
2875 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2876 · CTX_sess_set_cache_size
2878 Sets the size of the internal session cache of context $ctx to
2880 $size.
2881 Net::SSLeay::CTX_sess_set_cache_size($ctx, $size);
2883 # $ctx - value corresponding to openssl's SSL_CTX structure
2884 # $size - cache size (0 = unlimited)
2885 #
2886 # returns: previously valid size
2887 Check openssl doc
2889 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html>
2890 · CTX_sess_timeouts
2892 Returns the number of sessions proposed by clients and either found
2894 in the internal or external session cache in server mode, but that
2895 were invalid due to timeout. These sessions are not included in the
2896 SSL_CTX_sess_hits count.
2897 my $rv = Net::SSLeay::CTX_sess_timeouts($ctx);
2899 # $ctx - value corresponding to openssl's SSL_CTX structure
2900 #
2901 # returns: number of sessions
2902 Check openssl doc
2904 <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>
2905 · CTX_sessions
2907 Returns a pointer to the lhash databases containing the internal
2909 session cache for ctx.
2910 my $rv = Net::SSLeay::CTX_sessions($ctx);
2912 # $ctx - value corresponding to openssl's SSL_CTX structure
2913 #
2914 # returns: value corresponding to openssl's LHASH structure (0 on failure)
2915 Check openssl doc
2917 <http://www.openssl.org/docs/ssl/SSL_CTX_sessions.html>
2918 · CTX_set1_param
2920 Applies X509 verification parameters $vpm on $ctx
2922 my $rv = Net::SSLeay::CTX_set1_param($ctx, $vpm);
2924 # $ctx - value corresponding to openssl's SSL_CTX structure
2925 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
2926 #
2927 # returns: 1 on success, 0 on failure
2928 Check openssl doc
2930 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
2931 · CTX_set_cert_store
2933 Sets/replaces the certificate verification storage of $ctx to/with
2935 $store.
2936 Net::SSLeay::CTX_set_cert_store($ctx, $store);
2938 # $ctx - value corresponding to openssl's SSL_CTX structure
2939 # $store - value corresponding to openssl's X509_STORE structure
2940 #
2941 # returns: no return value
2942 Check openssl doc
2944 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_store.html>
2945 · CTX_set_cert_verify_callback
2947 Sets the verification callback function for $ctx. SSL objects that
2949 are created from $ctx inherit the setting valid at the time when
2950 "Net::SSLeay::new($ctx)" is called.
2951 Net::SSLeay::CTX_set_cert_verify_callback($ctx, $func, $data);
2953 # $ctx - value corresponding to openssl's SSL_CTX structure
2954 # $func - perl reference to callback function
2955 # $data - [optional] data that will be passed to callback function when invoked
2956 #
2957 # returns: no return value
2958 Check openssl doc
2960 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cert_verify_callback.html>
2961 · CTX_set_cipher_list
2963 Sets the list of available ciphers for $ctx using the control
2965 string $str. The list of ciphers is inherited by all ssl objects
2966 created from $ctx.
2967 my $rv = Net::SSLeay::CTX_set_cipher_list($s, $str);
2969 # $s - value corresponding to openssl's SSL_CTX structure
2970 # $str - (string) cipher list e.g. '3DES:+RSA'
2971 #
2972 # returns: 1 if any cipher could be selected and 0 on complete failure
2973 The format of $str is described in
2975 <http://www.openssl.org/docs/apps/ciphers.html>
2976 Check openssl doc
2978 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
2979 · CTX_set_client_CA_list
2981 Sets the list of CAs sent to the client when requesting a client
2983 certificate for $ctx.
2984 Net::SSLeay::CTX_set_client_CA_list($ctx, $list);
2986 # $ctx - value corresponding to openssl's SSL_CTX structure
2987 # $list - value corresponding to openssl's X509_NAME_STACK structure
2988 #
2989 # returns: no return value
2990 Check openssl doc
2992 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
2993 · CTX_set_default_passwd_cb
2995 Sets the default password callback called when loading/storing a
2997 PEM certificate with encryption.
2998 Net::SSLeay::CTX_set_default_passwd_cb($ctx, $func);
3000 # $ctx - value corresponding to openssl's SSL_CTX structure
3001 # $func - perl reference to callback function
3002 #
3003 # returns: no return value
3004 Check openssl doc
3006 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3007 · CTX_set_default_passwd_cb_userdata
3009 Sets a pointer to userdata which will be provided to the password
3011 callback on invocation.
3012 Net::SSLeay::CTX_set_default_passwd_cb_userdata($ctx, $userdata);
3014 # $ctx - value corresponding to openssl's SSL_CTX structure
3015 # $userdata - data that will be passed to callback function when invoked
3016 #
3017 # returns: no return value
3018 Check openssl doc
3020 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
3021 · CTX_set_default_verify_paths
3023 ??? (more info needed)
3025 my $rv = Net::SSLeay::CTX_set_default_verify_paths($ctx);
3027 # $ctx - value corresponding to openssl's SSL_CTX structure
3028 #
3029 # returns: 1 on success, 0 on failure
3030 · CTX_set_ex_data
3032 Is used to store application data at $data for $idx into the $ctx
3034 object.
3035 my $rv = Net::SSLeay::CTX_set_ex_data($ssl, $idx, $data);
3037 # $ssl - value corresponding to openssl's SSL_CTX structure
3038 # $idx - (integer) ???
3039 # $data - (pointer) ???
3040 #
3041 # returns: 1 on success, 0 on failure
3042 Check openssl doc
3044 <http://www.openssl.org/docs/ssl/SSL_CTX_get_ex_new_index.html>
3045 · CTX_set_purpose
3047 my $rv = Net::SSLeay::CTX_set_purpose($s, $purpose);
3049 # $s - value corresponding to openssl's SSL_CTX structure
3050 # $purpose - (integer) purpose identifier
3051 #
3052 # returns: 1 on success, 0 on failure
3053 #avainable purpose identifier
3055 1 - X509_PURPOSE_SSL_CLIENT
3056 2 - X509_PURPOSE_SSL_SERVER
3057 3 - X509_PURPOSE_NS_SSL_SERVER
3058 4 - X509_PURPOSE_SMIME_SIGN
3059 5 - X509_PURPOSE_SMIME_ENCRYPT
3060 6 - X509_PURPOSE_CRL_SIGN
3061 7 - X509_PURPOSE_ANY
3062 8 - X509_PURPOSE_OCSP_HELPER
3063 9 - X509_PURPOSE_TIMESTAMP_SIGN
3064 #or use corresponding constants
3066 $purpose = &Net::SSLeay::X509_PURPOSE_SSL_CLIENT;
3067 ...
3068 $purpose = &Net::SSLeay::X509_PURPOSE_TIMESTAMP_SIGN;
3069 · CTX_set_quiet_shutdown
3071 Sets the 'quiet shutdown' flag for $ctx to be mode. SSL objects
3073 created from $ctx inherit the mode valid at the time
3074 "Net::SSLeay::new($ctx)" is called.
3075 Net::SSLeay::CTX_set_quiet_shutdown($ctx, $mode);
3077 # $ctx - value corresponding to openssl's SSL_CTX structure
3078 # $mode - 0 or 1
3079 #
3080 # returns: no return value
3081 Check openssl doc
3083 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3084 · CTX_set_read_ahead
3086 my $rv = Net::SSLeay::CTX_set_read_ahead($ctx, $val);
3088 # $ctx - value corresponding to openssl's SSL_CTX structure
3089 # $val - read_ahead value to be set
3090 #
3091 # returns: the original read_ahead value
3092 · CTX_set_session_id_context
3094 Sets the context $sid_ctx of length $sid_ctx_len within which a
3096 session can be reused for the $ctx object.
3097 my $rv = Net::SSLeay::CTX_set_session_id_context($ctx, $sid_ctx, $sid_ctx_len);
3099 # $ctx - value corresponding to openssl's SSL_CTX structure
3100 # $sid_ctx - data buffer
3101 # $sid_ctx_len - length of data in $sid_ctx
3102 #
3103 # returns: 1 on success, 0 on failure (the error is logged to the error stack)
3104 Check openssl doc
3106 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
3107 · CTX_set_ssl_version
3109 Sets a new default TLS/SSL method for SSL objects newly created
3111 from this $ctx. SSL objects already created with
3112 "Net::SSLeay::new($ctx)" are not affected, except when
3113 "Net::SSLeay:clear($ssl)" is being called.
3114 my $rv = Net::SSLeay::CTX_set_ssl_version($ctx, $meth);
3116 # $ctx - value corresponding to openssl's SSL_CTX structure
3117 # $meth - value corresponding to openssl's SSL_METHOD structure
3118 #
3119 # returns: 1 on success, 0 on failure
3120 Check openssl doc
3122 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
3123 · CTX_set_timeout
3125 Sets the timeout for newly created sessions for $ctx to $t. The
3127 timeout value $t must be given in seconds.
3128 my $rv = Net::SSLeay::CTX_set_timeout($ctx, $t);
3130 # $ctx - value corresponding to openssl's SSL_CTX structure
3131 # $t - timeout in seconds
3132 #
3133 # returns: previously set timeout value
3134 Check openssl doc
3136 <http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html>
3137 · CTX_set_tmp_dh
3139 Sets DH parameters to be used to be $dh. The key is inherited by
3141 all ssl objects created from $ctx.
3142 my $rv = Net::SSLeay::CTX_set_tmp_dh($ctx, $dh);
3144 # $ctx - value corresponding to openssl's SSL_CTX structure
3145 # $dh - value corresponding to openssl's DH structure
3146 #
3147 # returns: 1 on success, 0 on failure
3148 Check openssl doc
3150 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3151 · CTX_set_tmp_dh_callback
3153 Sets the callback function for $ctx to be used when a DH parameters
3155 are required to $tmp_dh_callback.
3156 Net::SSLeay::CTX_set_tmp_dh_callback($ctx, $tmp_dh_callback);
3158 # $ctx - value corresponding to openssl's SSL_CTX structure
3159 # tmp_dh_callback - (function pointer) ???
3160 #
3161 # returns: no return value
3162 Check openssl doc
3164 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
3165 · CTX_set_tmp_rsa
3167 Sets the temporary/ephemeral RSA key to be used to be $rsa.
3169 my $rv = Net::SSLeay::CTX_set_tmp_rsa($ctx, $rsa);
3171 # $ctx - value corresponding to openssl's SSL_CTX structure
3172 # $rsa - value corresponding to openssl's RSA structure
3173 #
3174 # returns: 1 on success, 0 on failure
3175 Check openssl doc
3177 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3178 Not available with OpenSSL 1.1 and later.
3180 · CTX_set_tmp_rsa_callback
3182 Sets the callback function for ctx to be used when a
3184 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
3185 ??? (does this function really work?)
3187 Net::SSLeay::CTX_set_tmp_rsa_callback($ctx, $tmp_rsa_callback);
3189 # $ctx - value corresponding to openssl's SSL_CTX structure
3190 # $tmp_rsa_callback - (function pointer) ???
3191 #
3192 # returns: no return value
3193 Check openssl doc
3195 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
3196 Not available with OpenSSL 1.1 and later.
3198 · CTX_set_trust
3200 my $rv = Net::SSLeay::CTX_set_trust($s, $trust);
3202 # $s - value corresponding to openssl's SSL_CTX structure
3203 # $trust - (integer) trust identifier
3204 #
3205 # returns: the original value
3206 #available trust identifiers
3208 1 - X509_TRUST_COMPAT
3209 2 - X509_TRUST_SSL_CLIENT
3210 3 - X509_TRUST_SSL_SERVER
3211 4 - X509_TRUST_EMAIL
3212 5 - X509_TRUST_OBJECT_SIGN
3213 6 - X509_TRUST_OCSP_SIGN
3214 7 - X509_TRUST_OCSP_REQUEST
3215 8 - X509_TRUST_TSA
3216 #or use corresponding constants
3218 $trust = &Net::SSLeay::X509_TRUST_COMPAT;
3219 ...
3220 $trust = &Net::SSLeay::X509_TRUST_TSA;
3221 · CTX_set_verify_depth
3223 Sets the maximum depth for the certificate chain verification that
3225 shall be allowed for ctx.
3226 Net::SSLeay::CTX_set_verify_depth($ctx, $depth);
3228 # $ctx - value corresponding to openssl's SSL_CTX structure
3229 # $depth - max. depth
3230 #
3231 # returns: no return value
3232 Check openssl doc
3234 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
3235 · CTX_use_PKCS12_file
3237 Adds the certificate and private key from PKCS12 file $p12filename
3239 to $ctx.
3240 my $rv = Net::SSLeay::CTX_use_PKCS12_file($ctx, $p12filename, $password);
3242 # $ctx - value corresponding to openssl's SSL_CTX structure
3243 # $p12filename - (string) filename
3244 # $password - (string) password to decrypt private key
3245 #
3246 # returns: 1 on success, 0 on failure
3247 · CTX_use_PrivateKey
3249 Adds the private key $pkey to $ctx.
3251 my $rv = Net::SSLeay::CTX_use_PrivateKey($ctx, $pkey);
3253 # $ctx - value corresponding to openssl's SSL_CTX structure
3254 # $pkey - value corresponding to openssl's EVP_PKEY structure
3255 #
3256 # returns: 1 on success, otherwise check out the error stack to find out the reason
3257 Check openssl doc
3259 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3260 · CTX_use_PrivateKey_file
3262 Adds the first private key found in $file to $ctx.
3264 my $rv = Net::SSLeay::CTX_use_PrivateKey_file($ctx, $file, $type);
3266 # $ctx - value corresponding to openssl's SSL_CTX structure
3267 # $file - (string) file name
3268 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3269 #
3270 # returns: 1 on success, otherwise check out the error stack to find out the reason
3271 Check openssl doc
3273 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3274 · CTX_use_RSAPrivateKey
3276 Adds the RSA private key $rsa to $ctx.
3278 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey($ctx, $rsa);
3280 # $ctx - value corresponding to openssl's SSL_CTX structure
3281 # $rsa - value corresponding to openssl's RSA structure
3282 #
3283 # returns: 1 on success, otherwise check out the error stack to find out the reason
3284 Check openssl doc
3286 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3287 · CTX_use_RSAPrivateKey_file
3289 Adds the first RSA private key found in $file to $ctx.
3291 my $rv = Net::SSLeay::CTX_use_RSAPrivateKey_file($ctx, $file, $type);
3293 # $ctx - value corresponding to openssl's SSL_CTX structure
3294 # $file - (string) file name
3295 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3296 #
3297 # returns: 1 on success, otherwise check out the error stack to find out the reason
3298 · CTX_use_certificate
3300 Loads the certificate $x into $ctx
3302 my $rv = Net::SSLeay::CTX_use_certificate($ctx, $x);
3304 # $ctx - value corresponding to openssl's SSL_CTX structure
3305 # $x - value corresponding to openssl's X509 structure
3306 #
3307 # returns: 1 on success, otherwise check out the error stack to find out the reason
3308 Check openssl doc
3310 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3311 · CTX_use_certificate_chain_file
3313 Loads a certificate chain from $file into $ctx. The certificates
3315 must be in PEM format and must be sorted starting with the
3316 subject's certificate (actual client or server certificate),
3317 followed by intermediate CA certificates if applicable, and ending
3318 at the highest level (root) CA.
3319 my $rv = Net::SSLeay::CTX_use_certificate_chain_file($ctx, $file);
3321 # $ctx - value corresponding to openssl's SSL_CTX structure
3322 # $file - (string) file name
3323 #
3324 # returns: 1 on success, otherwise check out the error stack to find out the reason
3325 Check openssl doc
3327 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3328 · CTX_use_certificate_file
3330 Loads the first certificate stored in $file into $ctx.
3332 my $rv = Net::SSLeay::CTX_use_certificate_file($ctx, $file, $type);
3334 # $ctx - value corresponding to openssl's SSL_CTX structure
3335 # $file - (string) file name
3336 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
3337 #
3338 # returns: 1 on success, otherwise check out the error stack to find out the reason
3339 Check openssl doc
3341 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3342 Low level API: SSL_* related functions
3344 NOTE: Please note that the function described in this chapter have
3346 "SSL_" part stripped from their original openssl names.
3347 · new
3349 Creates a new SSL structure which is needed to hold the data for a
3351 TLS/SSL connection. The new structure inherits the settings of the
3352 underlying context $ctx: connection method (SSLv2/v3/TLSv1),
3353 options, verification settings, timeout settings.
3354 my $rv = Net::SSLeay::new($ctx);
3356 # $ctx - value corresponding to openssl's SSL_CTX structure
3357 #
3358 # returns: value corresponding to openssl's SSL structure (0 on failure)
3359 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_new.html>
3361 · accept
3363 Waits for a TLS/SSL client to initiate the TLS/SSL handshake. The
3365 communication channel must already have been set and assigned to
3366 the ssl by setting an underlying BIO.
3367 my $rv = Net::SSLeay::accept($ssl);
3369 # $ssl - value corresponding to openssl's SSL structure
3370 #
3371 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3372 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_accept.html>
3374 · add_client_CA
3376 Adds the CA name extracted from cacert to the list of CAs sent to
3378 the client when requesting a client certificate for the chosen ssl,
3379 overriding the setting valid for ssl's SSL_CTX object.
3380 my $rv = Net::SSLeay::add_client_CA($ssl, $x);
3382 # $ssl - value corresponding to openssl's SSL structure
3383 # $x - value corresponding to openssl's X509 structure
3384 #
3385 # returns: 1 on success, 0 on failure
3386 Check openssl doc
3388 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
3389 · callback_ctrl
3391 ??? (more info needed)
3393 my $rv = Net::SSLeay::callback_ctrl($ssl, $cmd, $fp);
3395 # $ssl - value corresponding to openssl's SSL structure
3396 # $cmd - (integer) command id
3397 # $fp - (function pointer) ???
3398 #
3399 # returns: ???
3400 Check openssl doc
3402 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3403 · check_private_key
3405 Checks the consistency of a private key with the corresponding
3407 certificate loaded into $ssl
3408 my $rv = Net::SSLeay::check_private_key($ssl);
3410 # $ssl - value corresponding to openssl's SSL structure
3411 #
3412 # returns: 1 on success, otherwise check out the error stack to find out the reason
3413 Check openssl doc
3415 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
3416 · clear
3418 Reset SSL object to allow another connection.
3420 Net::SSLeay::clear($ssl);
3422 # $ssl - value corresponding to openssl's SSL structure
3423 #
3424 # returns: no return value
3425 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_clear.html>
3427 · connect
3429 Initiate the TLS/SSL handshake with an TLS/SSL server.
3431 my $rv = Net::SSLeay::connect($ssl);
3433 # $ssl - value corresponding to openssl's SSL structure
3434 #
3435 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3436 Check openssl doc
3438 <http://www.openssl.org/docs/ssl/SSL_connect.html>
3439 · copy_session_id
3441 Copies the session structure fro $from to $to (+ also the private
3443 key and certificate associated with $from).
3444 Net::SSLeay::copy_session_id($to, $from);
3446 # $to - value corresponding to openssl's SSL structure
3447 # $from - value corresponding to openssl's SSL structure
3448 #
3449 # returns: no return value
3450 · ctrl
3452 Internal handling function for SSL objects.
3454 BEWARE: openssl doc says: This function should never be called
3456 directly!
3457 my $rv = Net::SSLeay::ctrl($ssl, $cmd, $larg, $parg);
3459 # $ssl - value corresponding to openssl's SSL structure
3460 # $cmd - (integer) command id
3461 # $larg - (integer) long ???
3462 # $parg - (string/pointer) ???
3463 #
3464 # returns: (long) result of given command ???
3465 For more details about valid $cmd values check "CTX_ctrl".
3467 Check openssl doc
3469 <http://www.openssl.org/docs/ssl/SSL_CTX_ctrl.html>
3470 · do_handshake
3472 Will wait for a SSL/TLS handshake to take place. If the connection
3474 is in client mode, the handshake will be started. The handshake
3475 routines may have to be explicitly set in advance using either
3476 SSL_set_connect_state or SSL_set_accept_state(3).
3477 my $rv = Net::SSLeay::do_handshake($ssl);
3479 # $ssl - value corresponding to openssl's SSL structure
3480 #
3481 # returns: 1 = success, 0 = handshake not successful, <0 = fatal error during handshake
3482 Check openssl doc
3484 <http://www.openssl.org/docs/ssl/SSL_do_handshake.html>
3485 · dup
3487 Returns a duplicate of $ssl.
3489 my $rv = Net::SSLeay::dup($ssl);
3491 # $ssl - value corresponding to openssl's SSL structure
3492 #
3493 # returns: value corresponding to openssl's SSL structure (0 on failure)
3494 · free
3496 Free an allocated SSL structure.
3498 Net::SSLeay::free($ssl);
3500 # $ssl - value corresponding to openssl's SSL structure
3501 #
3502 # returns: no return value
3503 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_free.html>
3505 · get0_param
3507 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
3509 requires at least OpenSSL 1.0.2
3510 Returns the current verification parameters.
3512 my $vpm = Net::SSLeay::get0_param($ssl);
3514 # $ssl - value corresponding to openssl's SSL structure
3515 #
3516 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure
3517 Check openssl doc
3519 <https://www.openssl.org/docs/ssl/SSL_CTX_get0_param.html>
3520 · get_SSL_CTX
3522 Returns a pointer to the SSL_CTX object, from which $ssl was
3524 created with Net::SSLeay::new.
3525 my $rv = Net::SSLeay::get_SSL_CTX($ssl);
3527 # $ssl - value corresponding to openssl's SSL structure
3528 #
3529 # returns: value corresponding to openssl's SSL_CTX structure (0 on failure)
3530 Check openssl doc
3532 <http://www.openssl.org/docs/ssl/SSL_get_SSL_CTX.html>
3533 · set_SSL_CTX
3535 Sets the SSL_CTX the corresponds to an SSL session.
3537 my $the_ssl_ctx = Net::SSLeay::set_SSL_CTX($ssl, $ssl_ctx);
3539 # $ssl - value corresponding to openssl's SSL structure
3540 # $ssl_ctx - Change the ssl object to the given ssl_ctx
3541 #
3542 # returns - the ssl_ctx
3543 · get_app_data
3545 Can be used to get application defined value/data.
3547 my $rv = Net::SSLeay::get_app_data($ssl);
3549 # $ssl - value corresponding to openssl's SSL structure
3550 #
3551 # returns: string/buffer/pointer ???
3552 · set_app_data
3554 Can be used to set some application defined value/data.
3556 my $rv = Net::SSLeay::set_app_data($ssl, $arg);
3558 # $ssl - value corresponding to openssl's SSL structure
3559 # $arg - (string/buffer/pointer ???) data
3560 #
3561 # returns: ???
3562 · get_certificate
3564 Gets X509 certificate from an established SSL connection.
3566 my $rv = Net::SSLeay::get_certificate($ssl);
3568 # $ssl - value corresponding to openssl's SSL structure
3569 #
3570 # returns: value corresponding to openssl's X509 structure (0 on failure)
3571 · get_cipher
3573 Obtains the name of the currently used cipher.
3575 my $rv = Net::SSLeay::get_cipher($ssl);
3577 # $ssl - value corresponding to openssl's SSL structure
3578 #
3579 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA' or '', when no session has been established.
3580 Check openssl doc
3582 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3583 · get_cipher_bits
3585 Obtain the number of secret/algorithm bits used.
3587 my $rv = Net::SSLeay::get_cipher_bits($ssl);
3589 # $ssl - value corresponding to openssl's SSL structure
3590 #
3591 # returns: number of secret bits used by current cipher
3592 Check openssl doc
3594 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html> and
3595 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
3596 · get_cipher_list
3598 Returns the name (string) of the SSL_CIPHER listed for $ssl with
3600 priority $n.
3601 my $rv = Net::SSLeay::get_cipher_list($ssl, $n);
3603 # $ssl - value corresponding to openssl's SSL structure
3604 # $n - (integer) priority
3605 #
3606 # returns: (string) cipher name e.g. 'EDH-DSS-DES-CBC3-SHA' or '' in case of error
3607 Call Net::SSLeay::get_cipher_list with priority starting from 0 to
3609 obtain the sorted list of available ciphers, until '' is returned:
3610 my $priority = 0;
3612 while (my $c = Net::SSLeay::get_cipher_list($ssl, $priority)) {
3613 print "cipher[$priority] = $c\n";
3614 $priority++;
3615 }
3616 Check openssl doc
3618 <http://www.openssl.org/docs/ssl/SSL_get_ciphers.html>
3619 · get_client_CA_list
3621 Returns the list of client CAs explicitly set for $ssl using
3623 "Net::SSleay::set_client_CA_list" or $ssl's SSL_CTX object with
3624 "Net::SSLeay::CTX_set_client_CA_list", when in server mode.
3625 In client mode, returns the list of client CAs sent from the
3627 server, if any.
3628 my $rv = Net::SSLeay::get_client_CA_list($ssl);
3630 # $ssl - value corresponding to openssl's SSL structure
3631 #
3632 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
3633 Check openssl doc
3635 <http://www.openssl.org/docs/ssl/SSL_get_client_CA_list.html>
3636 · get_current_cipher
3638 Returns the cipher actually used.
3640 my $rv = Net::SSLeay::get_current_cipher($ssl);
3642 # $ssl - value corresponding to openssl's SSL structure
3643 #
3644 # returns: value corresponding to openssl's SSL_CIPHER structure (0 on failure)
3645 Check openssl doc
3647 <http://www.openssl.org/docs/ssl/SSL_get_current_cipher.html>
3648 · get_default_timeout
3650 Returns the default timeout value assigned to SSL_SESSION objects
3652 negotiated for the protocol valid for $ssl.
3653 my $rv = Net::SSLeay::get_default_timeout($ssl);
3655 # $ssl - value corresponding to openssl's SSL structure
3656 #
3657 # returns: (long) timeout in seconds
3658 Check openssl doc
3660 <http://www.openssl.org/docs/ssl/SSL_get_default_timeout.html>
3661 · get_error
3663 Returns a result code for a preceding call to "connect", "accept",
3665 "do_handshake", "read", "peek" or "write" on $ssl.
3666 my $rv = Net::SSLeay::get_error($ssl, $ret);
3668 # $ssl - value corresponding to openssl's SSL structure
3669 # $ret - return value of preceding TLS/SSL I/O operation
3670 #
3671 # returns: result code, which is one of the following values:
3672 # 0 - SSL_ERROR_NONE
3673 # 1 - SSL_ERROR_SSL
3674 # 2 - SSL_ERROR_WANT_READ
3675 # 3 - SSL_ERROR_WANT_WRITE
3676 # 4 - SSL_ERROR_WANT_X509_LOOKUP
3677 # 5 - SSL_ERROR_SYSCALL
3678 # 6 - SSL_ERROR_ZERO_RETURN
3679 # 7 - SSL_ERROR_WANT_CONNECT
3680 # 8 - SSL_ERROR_WANT_ACCEPT
3681 Check openssl doc
3683 <http://www.openssl.org/docs/ssl/SSL_get_error.html>
3684 · get_ex_data
3686 Is used to retrieve the information for $idx from $ssl.
3688 my $rv = Net::SSLeay::get_ex_data($ssl, $idx);
3690 # $ssl - value corresponding to openssl's SSL structure
3691 # $idx - (integer) index for application specific data
3692 #
3693 # returns: pointer to ???
3694 Check openssl doc
3696 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3697 · set_ex_data
3699 Is used to store application data at $data for $idx into the $ssl
3701 object.
3702 my $rv = Net::SSLeay::set_ex_data($ssl, $idx, $data);
3704 # $ssl - value corresponding to openssl's SSL structure
3705 # $idx - (integer) ???
3706 # $data - (pointer) ???
3707 #
3708 # returns: 1 on success, 0 on failure
3709 Check openssl doc
3711 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3712 · get_ex_new_index
3714 Is used to register a new index for application specific data.
3716 my $rv = Net::SSLeay::get_ex_new_index($argl, $argp, $new_func, $dup_func, $free_func);
3718 # $argl - (long) ???
3719 # $argp - (pointer) ???
3720 # $new_func - function pointer ??? (CRYPTO_EX_new *)
3721 # $dup_func - function pointer ??? (CRYPTO_EX_dup *)
3722 # $free_func - function pointer ??? (CRYPTO_EX_free *)
3723 #
3724 # returns: (integer) ???
3725 Check openssl doc
3727 <http://www.openssl.org/docs/ssl/SSL_get_ex_new_index.html>
3728 · get_fd
3730 Returns the file descriptor which is linked to $ssl.
3732 my $rv = Net::SSLeay::get_fd($ssl);
3734 # $ssl - value corresponding to openssl's SSL structure
3735 #
3736 # returns: file descriptor (>=0) or -1 on failure
3737 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_get_fd.html>
3739 · get_finished
3741 Obtains the latest 'Finished' message sent to the peer. Return
3743 value is zero if there's been no Finished message yet. Default
3744 count is 2*EVP_MAX_MD_SIZE that is long enough for all possible
3745 Finish messages. If you supply a non-default count, the resulting
3746 return value may be longer than returned buf's length.
3747 my $rv = Net::SSLeay::get_finished($ssl, $buf, $count);
3749 # $ssl - value corresponding to openssl's SSL structure
3750 # $buf - buffer where the returned data will be stored
3751 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3752 #
3753 # returns: length of latest Finished message
3754 · get_peer_finished
3756 Obtains the latest 'Finished' message expected from the peer.
3758 Parameters and return value are similar to get_finished().
3759 my $rv = Net::SSLeay::get_peer_finished($ssl, $buf, $count);
3761 # $ssl - value corresponding to openssl's SSL structure
3762 # $buf - buffer where the returned data will be stored
3763 # $count - [optional] max size of return data - default is 2*EVP_MAX_MD_SIZE
3764 #
3765 # returns: length of latest Finished message
3766 · get_keyblock_size
3768 Gets the length of the TLS keyblock.
3770 NOTE: Does not exactly correspond to any low level API function.
3772 my $rv = Net::SSLeay::get_keyblock_size($ssl);
3774 # $ssl - value corresponding to openssl's SSL structure
3775 #
3776 # returns: keyblock size, -1 on error
3777 · get_mode
3779 Returns the mode (bitmask) set for $ssl.
3781 my $rv = Net::SSLeay::get_mode($ssl);
3783 # $ssl - value corresponding to openssl's SSL structure
3784 #
3785 # returns: mode (bitmask)
3786 To decode the return value (bitmask) see documentation for
3788 "CTX_get_mode".
3789 Check openssl doc
3791 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3792 · set_mode
3794 Adds the mode set via bitmask in $mode to $ssl. Options already set
3796 before are not cleared.
3797 my $rv = Net::SSLeay::set_mode($ssl, $mode);
3799 # $ssl - value corresponding to openssl's SSL structure
3800 # $mode - mode (bitmask)
3801 #
3802 # returns: the new mode bitmask after adding $mode
3803 For $mode bitmask details see "CTX_get_mode".
3805 Check openssl doc
3807 <http://www.openssl.org/docs/ssl/SSL_CTX_set_mode.html>
3808 · get_options
3810 Returns the options (bitmask) set for $ssl.
3812 my $rv = Net::SSLeay::get_options($ssl);
3814 # $ssl - value corresponding to openssl's SSL structure
3815 #
3816 # returns: options (bitmask)
3817 To decode the return value (bitmask) see documentation for
3819 "CTX_get_options".
3820 Check openssl doc
3822 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
3823 · set_options
3825 Adds the options set via bitmask in $options to $ssl. Options
3827 already set before are not cleared!
3828 Net::SSLeay::set_options($ssl, $options);
3830 # $ssl - value corresponding to openssl's SSL structure
3831 # $options - options (bitmask)
3832 #
3833 # returns: the new options bitmask after adding $options
3834 For $options bitmask details see "CTX_get_options".
3836 Check openssl doc
3838 <http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html>
3839 · get_peer_certificate
3841 Get the X509 certificate of the peer.
3843 my $rv = Net::SSLeay::get_peer_certificate($ssl);
3845 # $ssl - value corresponding to openssl's SSL structure
3846 #
3847 # returns: value corresponding to openssl's X509 structure (0 on failure)
3848 Check openssl doc
3850 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
3851 · get_peer_cert_chain
3853 Get the certificate chain of the peer as an array of X509
3855 structures.
3856 my @rv = Net::SSLeay::get_peer_cert_chain($ssl);
3858 # $ssl - value corresponding to openssl's SSL structure
3859 #
3860 # returns: list of X509 structures
3861 Check openssl doc
3863 <http://www.openssl.org/docs/ssl/SSL_get_peer_certificate.html>
3864 · get_quiet_shutdown
3866 Returns the 'quiet shutdown' setting of ssl.
3868 my $rv = Net::SSLeay::get_quiet_shutdown($ssl);
3870 # $ssl - value corresponding to openssl's SSL structure
3871 #
3872 # returns: (integer) current 'quiet shutdown' value
3873 Check openssl doc
3875 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
3876 · get_rbio
3878 Get 'read' BIO linked to an SSL object $ssl.
3880 my $rv = Net::SSLeay::get_rbio($ssl);
3882 # $ssl - value corresponding to openssl's SSL structure
3883 #
3884 # returns: value corresponding to openssl's BIO structure (0 on failure)
3885 Check openssl doc
3887 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
3888 · get_read_ahead
3890 my $rv = Net::SSLeay::get_read_ahead($ssl);
3892 # $ssl - value corresponding to openssl's SSL structure
3893 #
3894 # returns: (integer) read_ahead value
3895 · set_read_ahead
3897 Net::SSLeay::set_read_ahead($ssl, $val);
3899 # $ssl - value corresponding to openssl's SSL structure
3900 # $val - read_ahead value to be set
3901 #
3902 # returns: the original read_ahead value
3903 · get_server_random
3905 Returns internal SSLv3 server_random value.
3907 Net::SSLeay::get_server_random($ssl);
3909 # $ssl - value corresponding to openssl's SSL structure
3910 #
3911 # returns: server_random value (binary data)
3912 · get_client_random
3914 NOTE: Does not exactly correspond to any low level API function
3916 Returns internal SSLv3 client_random value.
3918 Net::SSLeay::get_client_random($ssl);
3920 # $ssl - value corresponding to openssl's SSL structure
3921 #
3922 # returns: client_random value (binary data)
3923 · export_keying_material
3925 Returns a buffer of $req_len bytes of keying material based on the
3927 constant string $label using the masterkey and client and server
3928 random strings as described in draft-ietf-pppext-eap-ttls-01.txt
3929 and See rfc2716 If p is present, it will be concatenated before
3930 generating the keying material Returns undef on error
3931 my $out = Net::SSLeay::export_keying_material($ssl, $req_len, $label, $p);
3933 · get_session
3935 Retrieve TLS/SSL session data used in $ssl. The reference count of
3937 the SSL_SESSION is NOT incremented.
3938 my $rv = Net::SSLeay::get_session($ssl);
3940 # $ssl - value corresponding to openssl's SSL structure
3941 #
3942 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
3943 Check openssl doc
3945 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
3946 · SSL_get0_session
3948 The alias for "get_session" (note that the name is
3950 "SSL_get0_session" NOT "get0_session").
3951 my $rv = Net::SSLeay::SSL_get0_session();
3953 · get1_session
3955 Returns a pointer to the SSL_SESSION actually used in $ssl. The
3957 reference count of the SSL_SESSION is incremented by 1.
3958 my $rv = Net::SSLeay::get1_session($ssl);
3960 # $ssl - value corresponding to openssl's SSL structure
3961 #
3962 # returns: value corresponding to openssl's SSL_SESSION structure (0 on failure)
3963 Check openssl doc
3965 <http://www.openssl.org/docs/ssl/SSL_get_session.html>
3966 · get_shared_ciphers
3968 Returns string with a list (colon ':' separated) of ciphers shared
3970 between client and server within SSL session $ssl.
3971 my $rv = Net::SSLeay::get_shared_ciphers()
3973 #
3974 # returns: string like 'ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:...'
3975 · get_shutdown
3977 Returns the shutdown mode of $ssl.
3979 my $rv = Net::SSLeay::get_shutdown($ssl);
3981 # $ssl - value corresponding to openssl's SSL structure
3982 #
3983 # returns: shutdown mode (bitmask) of ssl
3984 #to decode the return value (bitmask) use:
3986 0 - No shutdown setting, yet
3987 1 - SSL_SENT_SHUTDOWN
3988 2 - SSL_RECEIVED_SHUTDOWN
3989 Check openssl doc
3991 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
3992 · get_ssl_method
3994 Returns a function pointer to the TLS/SSL method set in $ssl.
3996 my $rv = Net::SSLeay::get_ssl_method($ssl);
3998 # $ssl - value corresponding to openssl's SSL structure
3999 #
4000 # returns: value corresponding to openssl's SSL_METHOD structure (0 on failure)
4001 Check openssl doc
4003 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4004 · get_state
4006 Returns the SSL connection state.
4008 my $rv = Net::SSLeay::get_state($ssl);
4010 # $ssl - value corresponding to openssl's SSL structure
4011 #
4012 # returns: (integer) state value
4013 # to decode the returned state check:
4014 # SSL_ST_* constants in openssl/ssl.h
4015 # SSL2_ST_* constants in openssl/ssl2.h
4016 # SSL23_ST_* constants in openssl/ssl23.h
4017 # SSL3_ST_* + DTLS1_ST_* constants in openssl/ssl3.h
4018 · state
4020 Exactly the same as "get_state".
4022 my $rv = Net::SSLeay::state($ssl);
4024 · set_state
4026 Sets the SSL connection state.
4028 Net::SSLeay::set_state($ssl,Net::SSLeay::SSL_ST_ACCEPT());
4030 Not available with OpenSSL 1.1 and later.
4032 · get_verify_depth
4034 Returns the verification depth limit currently set in $ssl.
4036 my $rv = Net::SSLeay::get_verify_depth($ssl);
4038 # $ssl - value corresponding to openssl's SSL structure
4039 #
4040 # returns: current depth or -1 if no limit has been explicitly set
4041 Check openssl doc
4043 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4044 · set_verify_depth
4046 Sets the maximum depth for the certificate chain verification that
4048 shall be allowed for $ssl.
4049 Net::SSLeay::set_verify_depth($ssl, $depth);
4051 # $ssl - value corresponding to openssl's SSL structure
4052 # $depth - (integer) depth
4053 #
4054 # returns: no return value
4055 Check openssl doc
4057 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4058 · get_verify_mode
4060 Returns the verification mode (bitmask) currently set in $ssl.
4062 my $rv = Net::SSLeay::get_verify_mode($ssl);
4064 # $ssl - value corresponding to openssl's SSL structure
4065 #
4066 # returns: mode (bitmask)
4067 To decode the return value (bitmask) see documentation for
4069 "CTX_get_verify_mode".
4070 Check openssl doc
4072 <http://www.openssl.org/docs/ssl/SSL_CTX_get_verify_mode.html>
4073 · set_verify
4075 Sets the verification flags for $ssl to be $mode and specifies the
4077 $verify_callback function to be used.
4078 Net::SSLeay::set_verify($ssl, $mode, $callback);
4080 # $ssl - value corresponding to openssl's SSL structure
4081 # $mode - mode (bitmask)
4082 # $callback - [optional] reference to perl callback function
4083 #
4084 # returns: no return value
4085 For $mode bitmask details see "CTX_get_verify_mode".
4087 Check openssl doc
4089 <http://www.openssl.org/docs/ssl/SSL_CTX_set_verify.html>
4090 · get_verify_result
4092 Returns the result of the verification of the X509 certificate
4094 presented by the peer, if any.
4095 my $rv = Net::SSLeay::get_verify_result($ssl);
4097 # $ssl - value corresponding to openssl's SSL structure
4098 #
4099 # returns: (integer)
4100 # 0 - X509_V_OK: ok
4101 # 2 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate
4102 # 3 - X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL
4103 # 4 - X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature
4104 # 5 - X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature
4105 # 6 - X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key
4106 # 7 - X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure
4107 # 8 - X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure
4108 # 9 - X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid
4109 # 10 - X509_V_ERR_CERT_HAS_EXPIRED: certificate has expired
4110 # 11 - X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid
4111 # 12 - X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired
4112 # 13 - X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field
4113 # 14 - X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field
4114 # 15 - X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field
4115 # 16 - X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field
4116 # 17 - X509_V_ERR_OUT_OF_MEM: out of memory
4117 # 18 - X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate
4118 # 19 - X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain
4119 # 20 - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate
4120 # 21 - X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate
4121 # 22 - X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long
4122 # 23 - X509_V_ERR_CERT_REVOKED: certificate revoked
4123 # 24 - X509_V_ERR_INVALID_CA: invalid CA certificate
4124 # 25 - X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded
4125 # 26 - X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose
4126 # 27 - X509_V_ERR_CERT_UNTRUSTED: certificate not trusted
4127 # 28 - X509_V_ERR_CERT_REJECTED: certificate rejected
4128 # 29 - X509_V_ERR_SUBJECT_ISSUER_MISMATCH: subject issuer mismatch
4129 # 30 - X509_V_ERR_AKID_SKID_MISMATCH: authority and subject key identifier mismatch
4130 # 31 - X509_V_ERR_AKID_ISSUER_SERIAL_MISMATCH: authority and issuer serial number mismatch
4131 # 32 - X509_V_ERR_KEYUSAGE_NO_CERTSIGN:key usage does not include certificate signing
4132 # 50 - X509_V_ERR_APPLICATION_VERIFICATION: application verification failure
4133 Check openssl doc
4135 <http://www.openssl.org/docs/ssl/SSL_get_verify_result.html>
4136 · set_verify_result
4138 Override result of peer certificate verification.
4140 Net::SSLeay::set_verify_result($ssl, $v);
4142 # $ssl - value corresponding to openssl's SSL structure
4143 # $v - (integer) result value
4144 #
4145 # returns: no return value
4146 For more info about valid return values see "get_verify_result"
4148 Check openssl doc
4150 <http://www.openssl.org/docs/ssl/SSL_set_verify_result.html>
4151 · get_wbio
4153 Get 'write' BIO linked to an SSL object $ssl.
4155 my $rv = Net::SSLeay::get_wbio($ssl);
4157 # $ssl - value corresponding to openssl's SSL structure
4158 #
4159 # returns: value corresponding to openssl's BIO structure (0 on failure)
4160 Check openssl doc
4162 <http://www.openssl.org/docs/ssl/SSL_get_rbio.html>
4163 · load_client_CA_file
4165 Load X509 certificates from file (PEM formatted).
4167 my $rv = Net::SSLeay::load_client_CA_file($file);
4169 # $file - (string) file name
4170 #
4171 # returns: value corresponding to openssl's STACK_OF(X509_NAME) structure (0 on failure)
4172 Check openssl doc
4174 <http://www.openssl.org/docs/ssl/SSL_load_client_CA_file.html>
4175 · clear_num_renegotiations
4177 Executes SSL_CTRL_CLEAR_NUM_RENEGOTIATIONS command on $ssl.
4179 my $rv = Net::SSLeay::clear_num_renegotiations($ssl);
4181 # $ssl - value corresponding to openssl's SSL structure
4182 #
4183 # returns: command result
4184 · need_tmp_RSA
4186 Executes SSL_CTRL_NEED_TMP_RSA command on $ssl.
4188 my $rv = Net::SSLeay::need_tmp_RSA($ssl);
4190 # $ssl - value corresponding to openssl's SSL structure
4191 #
4192 # returns: command result
4193 Not available with OpenSSL 1.1 and later.
4195 · num_renegotiations
4197 Executes SSL_CTRL_GET_NUM_RENEGOTIATIONS command on $ssl.
4199 my $rv = Net::SSLeay::num_renegotiations($ssl);
4201 # $ssl - value corresponding to openssl's SSL structure
4202 #
4203 # returns: command result
4204 · total_renegotiations
4206 Executes SSL_CTRL_GET_TOTAL_RENEGOTIATIONS command on $ssl.
4208 my $rv = Net::SSLeay::total_renegotiations($ssl);
4210 # $ssl - value corresponding to openssl's SSL structure
4211 #
4212 # returns: command result
4213 · peek
4215 Copies $max bytes from the specified $ssl into the returned value.
4217 In contrast to the "Net::SSLeay::read()" function, the data in the
4218 SSL buffer is unmodified after the SSL_peek() operation.
4219 Net::SSLeay::peek($ssl, $max);
4221 # $ssl - value corresponding to openssl's SSL structure
4222 # $max - [optional] max bytes to peek (integer) - default is 32768
4223 #
4224 # in scalar context: data read from the TLS/SSL connection, undef on error
4225 # in list context: two-item array consisting of data read (undef on error),
4226 # and return code from SSL_read().
4227 · pending
4229 Obtain number of readable bytes buffered in $ssl object.
4231 my $rv = Net::SSLeay::pending($ssl);
4233 # $ssl - value corresponding to openssl's SSL structure
4234 #
4235 # returns: the number of bytes pending
4236 Check openssl doc
4238 <http://www.openssl.org/docs/ssl/SSL_pending.html>
4239 · read
4241 Tries to read $max bytes from the specified $ssl.
4243 my $got = Net::SSLeay::read($ssl, $max);
4245 my($got, $rv) = Net::SSLeay::read($ssl, $max);
4246 # $ssl - value corresponding to openssl's SSL structure
4247 # $max - [optional] max bytes to read (integer) - default is 32768
4248 #
4249 # returns:
4250 # in scalar context: data read from the TLS/SSL connection, undef on error
4251 # in list context: two-item array consisting of data read (undef on error),
4252 # and return code from SSL_read().
4253 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_read.html>
4255 · renegotiate
4257 Turn on flags for renegotiation so that renegotiation will happen
4259 my $rv = Net::SSLeay::renegotiate($ssl);
4261 # $ssl - value corresponding to openssl's SSL structure
4262 #
4263 # returns: 1 on success, 0 on failure
4264 · rstate_string
4266 Returns a 2 letter string indicating the current read state of the
4268 SSL object $ssl.
4269 my $rv = Net::SSLeay::rstate_string($ssl);
4271 # $ssl - value corresponding to openssl's SSL structure
4272 #
4273 # returns: 2-letter string
4274 Check openssl doc
4276 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4277 · rstate_string_long
4279 Returns a string indicating the current read state of the SSL
4281 object ssl.
4282 my $rv = Net::SSLeay::rstate_string_long($ssl);
4284 # $ssl - value corresponding to openssl's SSL structure
4285 #
4286 # returns: string with current state
4287 Check openssl doc
4289 <http://www.openssl.org/docs/ssl/SSL_rstate_string.html>
4290 · session_reused
4292 Query whether a reused session was negotiated during handshake.
4294 my $rv = Net::SSLeay::session_reused($ssl);
4296 # $ssl - value corresponding to openssl's SSL structure
4297 #
4298 # returns: 0 - new session was negotiated; 1 - session was reused.
4299 Check openssl doc
4301 <http://www.openssl.org/docs/ssl/SSL_session_reused.html>
4302 · set1_param
4304 Applies X509 verification parameters $vpm on $ssl
4306 my $rv = Net::SSLeay::set1_param($ssl, $vpm);
4308 # $ssl - value corresponding to openssl's SSL structure
4309 # $vpm - value corresponding to openssl's X509_VERIFY_PARAM structure
4310 #
4311 # returns: 1 on success, 0 on failure
4312 · set_accept_state
4314 Sets $ssl to work in server mode.
4316 Net::SSLeay::set_accept_state($ssl);
4318 # $ssl - value corresponding to openssl's SSL structure
4319 #
4320 # returns: no return value
4321 Check openssl doc
4323 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4324 · set_bio
4326 Connects the BIOs $rbio and $wbio for the read and write operations
4328 of the TLS/SSL (encrypted) side of $ssl.
4329 Net::SSLeay::set_bio($ssl, $rbio, $wbio);
4331 # $ssl - value corresponding to openssl's SSL structure
4332 # $rbio - value corresponding to openssl's BIO structure
4333 # $wbio - value corresponding to openssl's BIO structure
4334 #
4335 # returns: no return value
4336 Check openssl doc
4338 <http://www.openssl.org/docs/ssl/SSL_set_bio.html>
4339 · set_cipher_list
4341 Sets the list of ciphers only for ssl.
4343 my $rv = Net::SSLeay::set_cipher_list($ssl, $str);
4345 # $ssl - value corresponding to openssl's SSL structure
4346 # $str - (string) cipher list e.g. '3DES:+RSA'
4347 #
4348 # returns: 1 if any cipher could be selected and 0 on complete failure
4349 Check openssl doc
4351 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4352 · set_client_CA_list
4354 Sets the list of CAs sent to the client when requesting a client
4356 certificate for the chosen $ssl, overriding the setting valid for
4357 $ssl's SSL_CTX object.
4358 my $rv = Net::SSLeay::set_client_CA_list($ssl, $list);
4360 # $ssl - value corresponding to openssl's SSL structure
4361 # $list - value corresponding to openssl's STACK_OF(X509_NAME) structure
4362 #
4363 # returns: no return value
4364 Check openssl doc
4366 <http://www.openssl.org/docs/ssl/SSL_CTX_set_client_CA_list.html>
4367 · set_connect_state
4369 Sets $ssl to work in client mode.
4371 Net::SSLeay::set_connect_state($ssl);
4373 # $ssl - value corresponding to openssl's SSL structure
4374 #
4375 # returns: no return value
4376 Check openssl doc
4378 <http://www.openssl.org/docs/ssl/SSL_set_connect_state.html>
4379 · set_fd
4381 Sets the file descriptor $fd as the input/output facility for the
4383 TLS/SSL (encrypted) side of $ssl, $fd will typically be the socket
4384 file descriptor of a network connection.
4385 my $rv = Net::SSLeay::set_fd($ssl, $fd);
4387 # $ssl - value corresponding to openssl's SSL structure
4388 # $fd - (integer) file handle (got via perl's fileno)
4389 #
4390 # returns: 1 on success, 0 on failure
4391 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4393 · set_psk_client_callback
4395 Sets the psk client callback.
4397 Net::SSLeay::set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4399 # $ssl - value corresponding to openssl's SSL structure
4400 # $hint - PSK identity hint send by the server
4401 # $identity - PSK identity
4402 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4403 #
4404 # returns: no return value
4405 Check openssl doc
4407 <http://www.openssl.org/docs/ssl/SSL_set_psk_client_callback.html>
4408 · set_rfd
4410 Sets the file descriptor $fd as the input (read) facility for the
4412 TLS/SSL (encrypted) side of $ssl.
4413 my $rv = Net::SSLeay::set_rfd($ssl, $fd);
4415 # $ssl - value corresponding to openssl's SSL structure
4416 # $fd - (integer) file handle (got via perl's fileno)
4417 #
4418 # returns: 1 on success, 0 on failure
4419 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4421 · set_wfd
4423 my $rv = Net::SSLeay::set_wfd($ssl, $fd);
4425 # $ssl - value corresponding to openssl's SSL structure
4426 # $fd - (integer) file handle (got via perl's fileno)
4427 #
4428 # returns: 1 on success, 0 on failure
4429 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_set_fd.html>
4431 · set_info_callback
4433 Sets the callback function, that can be used to obtain state
4435 information for $ssl during connection setup and use. When
4436 callback is undef, the callback setting currently valid for ctx is
4437 used.
4438 Net::SSLeay::set_info_callback($ssl, $cb, [$data]);
4440 # $ssl - value corresponding to openssl's SSL structure
4441 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4442 #
4443 # returns: no return value
4444 Check openssl doc
4446 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4447 · CTX_set_info_callback
4449 Sets the callback function on ctx, that can be used to obtain state
4451 information during ssl connection setup and use. When callback is
4452 undef, an existing callback will be disabled.
4453 Net::SSLeay::CTX_set_info_callback($ssl, $cb, [$data]);
4455 # $ssl - value corresponding to openssl's SSL structure
4456 # $cb - sub { my ($ssl,$where,$ret,$data) = @_; ... }
4457 #
4458 # returns: no return value
4459 Check openssl doc
4461 <http://www.openssl.org/docs/ssl/SSL_CTX_set_info_callback.html>
4462 · set_pref_cipher
4464 Sets the list of available ciphers for $ssl using the control
4466 string $str.
4467 my $rv = Net::SSLeay::set_pref_cipher($ssl, $str);
4469 # $ssl - value corresponding to openssl's SSL structure
4470 # $str - (string) cipher list e.g. '3DES:+RSA'
4471 #
4472 # returns: 1 if any cipher could be selected and 0 on complete failure
4473 Check openssl doc
4475 <http://www.openssl.org/docs/ssl/SSL_CTX_set_cipher_list.html>
4476 · CTX_set_psk_client_callback
4478 Sets the psk client callback.
4480 Net::SSLeay::CTX_set_psk_client_callback($ssl, sub { my $hint = shift; return ($identity, $key) } );
4482 # $ssl - value corresponding to openssl's SSL structure
4483 # $hint - PSK identity hint send by the server
4484 # $identity - PSK identity
4485 # $key - PSK key, hex string without the leading '0x', e.g. 'deadbeef'
4486 #
4487 # returns: no return value
4488 Check openssl doc
4490 <http://www.openssl.org/docs/ssl/SSL_CTX_set_psk_client_callback.html>
4491 · set_purpose
4493 my $rv = Net::SSLeay::set_purpose($ssl, $purpose);
4495 # $ssl - value corresponding to openssl's SSL structure
4496 # $purpose - (integer) purpose identifier
4497 #
4498 # returns: 1 on success, 0 on failure
4499 For more info about available $purpose identifiers see
4501 "CTX_set_purpose".
4502 · set_quiet_shutdown
4504 Sets the 'quiet shutdown' flag for $ssl to be $mode.
4506 Net::SSLeay::set_quiet_shutdown($ssl, $mode);
4508 # $ssl - value corresponding to openssl's SSL structure
4509 # $mode - 0 or 1
4510 #
4511 # returns: no return value
4512 Check openssl doc
4514 <http://www.openssl.org/docs/ssl/SSL_CTX_set_quiet_shutdown.html>
4515 · set_session
4517 Set a TLS/SSL session to be used during TLS/SSL connect.
4519 my $rv = Net::SSLeay::set_session($to, $ses);
4521 # $to - value corresponding to openssl's SSL structure
4522 # $ses - value corresponding to openssl's SSL_SESSION structure
4523 #
4524 # returns: 1 on success, 0 on failure
4525 Check openssl doc
4527 <http://www.openssl.org/docs/ssl/SSL_set_session.html>
4528 · set_session_id_context
4530 Sets the context $sid_ctx of length $sid_ctx_len within which a
4532 session can be reused for the $ssl object.
4533 my $rv = Net::SSLeay::set_session_id_context($ssl, $sid_ctx, $sid_ctx_len);
4535 # $ssl - value corresponding to openssl's SSL structure
4536 # $sid_ctx - data buffer
4537 # $sid_ctx_len - length of data in $sid_ctx
4538 #
4539 # returns: 1 on success, 0 on failure
4540 Check openssl doc
4542 <http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html>
4543 · set_session_secret_cb
4545 Setup pre-shared secret session resumption function.
4547 Net::SSLeay::set_session_secret_cb($ssl, $func, $data);
4549 # $ssl - value corresponding to openssl's SSL structure
4550 # $func - perl reference to callback function
4551 # $data - [optional] data that will be passed to callback function when invoked
4552 #
4553 # returns: no return value
4554 The callback function will be called like:
4556 callback_function($secret, $ciphers, $pref_cipher, $data);
4557 # $secret is the current master session key, usually all 0s at the
4559 beginning of a session # $ciphers is ref to an array of peer cipher
4560 names # $pref_cipher is a ref to an index into the list of cipher
4561 names of # the preferred cipher. Set it if you want to specify a
4562 preferred cipher # $data is the data passed to
4563 set_session_secret_cb
4564 The callback function should return 1 if it likes the suggested
4566 cipher (or has selected an alternative by setting pref_cipher),
4567 else it should return 0 (in which case OpenSSL will select its own
4568 preferred cipher).
4569 With OpenSSL 1.1 and later, callback_function can change the master
4571 key for the session by altering $secret and returning 1.
4572 · CTX_set_tlsext_ticket_getkey_cb
4574 Setup encryption for TLS session tickets (stateless session reuse).
4576 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($ctx, $func, $data);
4578 # $ctx - value corresponding to openssl's SSL_CTX structure
4579 # $func - perl reference to callback function
4580 # $data - [optional] data that will be passed to callback function when invoked
4581 #
4582 # returns: no return value
4583 The callback function will be called like:
4585 getkey($data,[$key_name]) -> ($key,$current_key_name)
4586 # $data is the data passed to set_session_secret_cb # $key_name is
4588 the name of the key OpenSSL has extracted from the session ticket #
4589 $key is the requested key for ticket encryption + HMAC #
4590 $current_key_name is the name for the currently valid key
4591 OpenSSL will call the function without a key name if it generates a
4593 new ticket. It then needs the callback to return the
4594 encryption+HMAC key and an identifier (key name) for this key.
4595 When OpenSSL gets a session ticket from the client it extracts the
4597 key name and calls the callback with this name as argument. It then
4598 expects the callback to return the encryption+HMAC key matching the
4599 requested key name and and also the key name which should be used
4600 at the moment. If the requested key name and the returned key name
4601 differ it means that this session ticket was created with an
4602 expired key and need to be renewed. In this case OpenSSL will call
4603 the callback again with no key name to create a new session ticket
4604 based on the old one.
4605 The key must be at least 32 byte of random data which can be
4607 created with RAND_bytes. Internally the first 16 byte are used as
4608 key in AES-128 encryption while the next 16 byte are used for the
4609 SHA-256 HMAC. The key name are binary data and must be exactly 16
4610 byte long.
4611 Example:
4613 Net::SSLeay::RAND_bytes(my $oldkey,32);
4615 Net::SSLeay::RAND_bytes(my $newkey,32);
4616 my $oldkey_name = pack("a16",'oldsecret');
4617 my $newkey_name = pack("a16",'newsecret');
4618 my @keys = (
4620 [ $newkey_name, $newkey ], # current active key
4621 [ $oldkey_name, $oldkey ], # already expired
4622 );
4623 Net::SSLeay::CTX_set_tlsext_ticket_getkey_cb($server2->_ctx, sub {
4625 my ($mykeys,$name) = @_;
4626 # return (current_key, current_key_name) if no name given
4628 return ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;
4629 # return (matching_key, current_key_name) if we find a key matching
4631 # the given name
4632 for(my $i = 0; $i<@$mykeys; $i++) {
4633 next if $name ne $mykeys->[$i][0];
4634 return ($mykeys->[$i][1],$mykeys->[0][0]);
4635 }
4636 # no matching key found
4638 return;
4639 },\@keys);
4640 This function is based on the OpenSSL function
4642 SSL_CTX_set_tlsext_ticket_key_cb but provides a simpler to use
4643 interface. For more information see
4644 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tlsext_ticket_key_cb.html>
4645 · set_session_ticket_ext_cb
4647 Setup callback for TLS session tickets (stateless session reuse).
4649 Net::SSLeay::set_session_ticket_ext_cb($ssl, $func, $data);
4651 # $ssl - value corresponding to openssl's SSL structure
4652 # $func - perl reference to callback function
4653 # $data - [optional] data that will be passed to callback function when invoked
4654 #
4655 # returns: no return value
4656 The callback function will be called like:
4658 getticket($ssl,$ticket,$data) -> $return_value
4659 # $ssl is a value corresponding to openssl's SSL structure #
4661 $ticket is a value of received TLS session ticket (can also be
4662 empty) # $data is the data passed to set_session_ticket_ext_cb #
4663 $return_value is either 0 (failure) or 1 (success)
4664 This function is based on the OpenSSL function
4666 SSL_set_session_ticket_ext_cb.
4667 · set_session_ticket_ext
4669 Set TLS session ticket (stateless session reuse).
4671 Net::SSLeay::set_session_ticket_ext($ssl, $ticket);
4673 # $ssl - value corresponding to openssl's SSL structure
4674 # $ticket - is a value of TLS session ticket which client will send (can also be empty string)
4675 #
4676 # returns: no return value
4677 The callback function will be called like:
4679 getticket($ssl,$ticket,$data) -> $return_value
4680 # $ssl is a value corresponding to openssl's SSL structure #
4682 $ticket is a value of received TLS session ticket (can also be
4683 empty) # $data is the data passed to set_session_ticket_ext_cb #
4684 $return_value is either 0 (failure) or 1 (success)
4685 This function is based on the OpenSSL function
4687 SSL_set_session_ticket_ext_cb.
4688 · CTX_set_num_tickets
4690 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4692 requires at least OpenSSL 1.1.1
4693 Set number of session tickets that will be sent to a client.
4695 my $rv = Net::SSLeay::CTX_set_num_tickets($ctx, $number_of_tickets);
4697 # $ctx - value corresponding to openssl's SSL_CTX structure
4698 # $number_of_tickets - number of tickets to send
4699 # returns: 1 on success, 0 on failure
4700 Set to zero if you do not no want to support a session resumption.
4702 · CTX_get_num_tickets
4704 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4706 requires at least OpenSSL 1.1.1
4707 Get number of session tickets that will be sent to a client.
4709 my $number_of_tickets = Net::SSLeay::CTX_get_num_tickets($ctx);
4711 # $ctx - value corresponding to openssl's SSL_CTX structure
4712 # returns: number of tickets to send
4713 · set_num_tickets
4715 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4717 requires at least OpenSSL 1.1.1
4718 Set number of session tickets that will be sent to a client.
4720 my $rv = Net::SSLeay::set_num_tickets($ssl, $number_of_tickets);
4722 # $ssl - value corresponding to openssl's SSL structure
4723 # $number_of_tickets - number of tickets to send
4724 # returns: 1 on success, 0 on failure
4725 Set to zero if you do not no want to support a session resumption.
4727 · get_num_tickets
4729 COMPATIBILITY: not available in Net-SSLeay-1.85 and before;
4731 requires at least OpenSSL 1.1.1
4732 Get number of session tickets that will be sent to a client.
4734 my $number_of_tickets = Net::SSLeay::get_num_tickets($ctx);
4736 # $ctx - value corresponding to openssl's SSL structure
4737 # returns: number of tickets to send
4738 · set_shutdown
4740 Sets the shutdown state of $ssl to $mode.
4742 Net::SSLeay::set_shutdown($ssl, $mode);
4744 # $ssl - value corresponding to openssl's SSL structure
4745 # $mode - (integer) shutdown mode:
4746 # 0 - No shutdown
4747 # 1 - SSL_SENT_SHUTDOWN
4748 # 2 - SSL_RECEIVED_SHUTDOWN
4749 # 3 - SSL_RECEIVED_SHUTDOWN+SSL_SENT_SHUTDOWN
4750 #
4751 # returns: no return value
4752 Check openssl doc
4754 <http://www.openssl.org/docs/ssl/SSL_set_shutdown.html>
4755 · set_ssl_method
4757 Sets a new TLS/SSL method for a particular $ssl object.
4759 my $rv = Net::SSLeay::set_ssl_method($ssl, $method);
4761 # $ssl - value corresponding to openssl's SSL structure
4762 # $method - value corresponding to openssl's SSL_METHOD structure
4763 #
4764 # returns: 1 on success, 0 on failure
4765 Check openssl doc
4767 <http://www.openssl.org/docs/ssl/SSL_CTX_set_ssl_version.html>
4768 · set_tmp_dh
4770 Sets DH parameters to be used to be $dh.
4772 my $rv = Net::SSLeay::set_tmp_dh($ssl, $dh);
4774 # $ssl - value corresponding to openssl's SSL structure
4775 # $dh - value corresponding to openssl's DH structure
4776 #
4777 # returns: 1 on success, 0 on failure
4778 Check openssl doc
4780 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
4781 · set_tmp_dh_callback
4783 Sets the callback function for $ssl to be used when a DH parameters
4785 are required to $dh_cb.
4786 ??? (does this function really work?)
4788 Net::SSLeay::set_tmp_dh_callback($ssl, $dh);
4790 # $ssl - value corresponding to openssl's SSL structure
4791 # $dh_cb - pointer to function ???
4792 #
4793 # returns: no return value
4794 Check openssl doc
4796 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_dh_callback.html>
4797 · set_tmp_rsa
4799 Sets the temporary/ephemeral RSA key to be used in $ssl to be $rsa.
4801 my $rv = Net::SSLeay::set_tmp_rsa($ssl, $rsa);
4803 # $ssl - value corresponding to openssl's SSL structure
4804 # $rsa - value corresponding to openssl's RSA structure
4805 #
4806 # returns: 1 on success, 0 on failure
4807 Example:
4809 $rsakey = Net::SSLeay::RSA_generate_key();
4811 Net::SSLeay::set_tmp_rsa($ssl, $rsakey);
4812 Net::SSLeay::RSA_free($rsakey);
4813 Check openssl doc
4815 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
4816 · set_tmp_rsa_callback
4818 Sets the callback function for $ssl to be used when a
4820 temporary/ephemeral RSA key is required to $tmp_rsa_callback.
4821 ??? (does this function really work?)
4823 Net::SSLeay::set_tmp_rsa_callback($ssl, $tmp_rsa_callback);
4825 # $ssl - value corresponding to openssl's SSL structure
4826 # $tmp_rsa_callback - (function pointer) ???
4827 #
4828 # returns: no return value
4829 Check openssl doc
4831 <http://www.openssl.org/docs/ssl/SSL_CTX_set_tmp_rsa_callback.html>
4832 · set_trust
4834 my $rv = Net::SSLeay::set_trust($ssl, $trust);
4836 # $ssl - value corresponding to openssl's SSL structure
4837 # $trust - (integer) trust identifier
4838 #
4839 # returns: the original value
4840 For more details about $trust values see "CTX_set_trust".
4842 · shutdown
4844 Shuts down an active TLS/SSL connection. It sends the 'close
4846 notify' shutdown alert to the peer.
4847 my $rv = Net::SSLeay::shutdown($ssl);
4849 # $ssl - value corresponding to openssl's SSL structure
4850 #
4851 # returns: 1 - shutdown was successfully completed
4852 # 0 - shutdown is not yet finished,
4853 # -1 - shutdown was not successful
4854 Check openssl doc
4856 <http://www.openssl.org/docs/ssl/SSL_shutdown.html>
4857 · state_string
4859 Returns a 6 letter string indicating the current state of the SSL
4861 object $ssl.
4862 my $rv = Net::SSLeay::state_string($ssl);
4864 # $ssl - value corresponding to openssl's SSL structure
4865 #
4866 # returns: 6-letter string
4867 Check openssl doc
4869 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
4870 · state_string_long
4872 Returns a string indicating the current state of the SSL object
4874 $ssl.
4875 my $rv = Net::SSLeay::state_string_long($ssl);
4877 # $ssl - value corresponding to openssl's SSL structure
4878 #
4879 # returns: state strings
4880 Check openssl doc
4882 <http://www.openssl.org/docs/ssl/SSL_state_string.html>
4883 · set_default_passwd_cb
4885 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
4887 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
4888 Sets the default password callback called when loading/storing a
4890 PEM certificate with encryption for $ssl.
4891 Net::SSLeay::set_default_passwd_cb($ssl, $func);
4893 # $ssl - value corresponding to openssl's SSL structure
4894 # $func - perl reference to callback function
4895 #
4896 # returns: no return value
4897 Check openssl doc
4899 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
4900 · set_default_passwd_cb_userdata
4902 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
4904 requires at least OpenSSL 1.1.0f. Not needed with LibreSSL.
4905 Sets a pointer to userdata which will be provided to the password
4907 callback of $ssl on invocation.
4908 Net::SSLeay::set_default_passwd_cb_userdata($ssl, $userdata);
4910 # $ssl - value corresponding to openssl's SSL structure
4911 # $userdata - data that will be passed to callback function when invoked
4912 #
4913 # returns: no return value
4914 Check openssl doc
4916 <http://www.openssl.org/docs/ssl/SSL_CTX_set_default_passwd_cb.html>
4917 · use_PrivateKey
4919 Adds $pkey as private key to $ssl.
4921 my $rv = Net::SSLeay::use_PrivateKey($ssl, $pkey);
4923 # $ssl - value corresponding to openssl's SSL structure
4924 # $pkey - value corresponding to openssl's EVP_PKEY structure
4925 #
4926 # returns: 1 on success, otherwise check out the error stack to find out the reason
4927 Check openssl doc
4929 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4930 · use_PrivateKey_ASN1
4932 Adds the private key of type $pk stored in $data to $ssl.
4934 my $rv = Net::SSLeay::use_PrivateKey_ASN1($pk, $ssl, $d, $len);
4936 # $pk - (integer) key type, NID of corresponding algorithm
4937 # $ssl - value corresponding to openssl's SSL structure
4938 # $data - key data (binary)
4939 # $len - length of $data
4940 #
4941 # returns: 1 on success, otherwise check out the error stack to find out the reason
4942 Check openssl doc
4944 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4945 · use_PrivateKey_file
4947 Adds the first private key found in $file to $ssl.
4949 my $rv = Net::SSLeay::use_PrivateKey_file($ssl, $file, $type);
4951 # $ssl - value corresponding to openssl's SSL structure
4952 # $file - (string) file name
4953 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
4954 #
4955 # returns: 1 on success, otherwise check out the error stack to find out the reason
4956 Check openssl doc
4958 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4959 · use_RSAPrivateKey
4961 Adds $rsa as RSA private key to $ssl.
4963 my $rv = Net::SSLeay::use_RSAPrivateKey($ssl, $rsa);
4965 # $ssl - value corresponding to openssl's SSL structure
4966 # $rsa - value corresponding to openssl's RSA structure
4967 #
4968 # returns: 1 on success, otherwise check out the error stack to find out the reason
4969 Check openssl doc
4971 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4972 · use_RSAPrivateKey_ASN1
4974 Adds RSA private key stored in $data to $ssl.
4976 my $rv = Net::SSLeay::use_RSAPrivateKey_ASN1($ssl, $data, $len);
4978 # $ssl - value corresponding to openssl's SSL structure
4979 # $data - key data (binary)
4980 # $len - length of $data
4981 #
4982 # returns: 1 on success, otherwise check out the error stack to find out the reason
4983 Check openssl doc
4985 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
4986 · use_RSAPrivateKey_file
4988 Adds the first RSA private key found in $file to $ssl.
4990 my $rv = Net::SSLeay::use_RSAPrivateKey_file($ssl, $file, $type);
4992 # $ssl - value corresponding to openssl's SSL structure
4993 # $file - (string) file name
4994 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
4995 #
4996 # returns: 1 on success, otherwise check out the error stack to find out the reason
4997 Check openssl doc
4999 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5000 · use_certificate
5002 Loads the certificate $x into $ssl.
5004 my $rv = Net::SSLeay::use_certificate($ssl, $x);
5006 # $ssl - value corresponding to openssl's SSL structure
5007 # $x - value corresponding to openssl's X509 structure
5008 #
5009 # returns: 1 on success, otherwise check out the error stack to find out the reason
5010 Check openssl doc
5012 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5013 · use_certificate_ASN1
5015 Loads the ASN1 encoded certificate from $data to $ssl.
5017 my $rv = Net::SSLeay::use_certificate_ASN1($ssl, $data, $len);
5019 # $ssl - value corresponding to openssl's SSL structure
5020 # $data - certificate data (binary)
5021 # $len - length of $data
5022 #
5023 # returns: 1 on success, otherwise check out the error stack to find out the reason
5024 Check openssl doc
5026 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5027 · use_certificate_chain_file
5029 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
5031 requires at least OpenSSL 1.1.0
5032 Loads a certificate chain from $file into $ssl. The certificates
5034 must be in PEM format and must be sorted starting with the
5035 subject's certificate (actual client or server certificate),
5036 followed by intermediate CA certificates if applicable, and ending
5037 at the highest level (root) CA.
5038 my $rv = Net::SSLeay::use_certificate_chain_file($ssl, $file);
5040 # $ssl - value corresponding to openssl's SSL structure
5041 # $file - (string) file name
5042 #
5043 # returns: 1 on success, otherwise check out the error stack to find out the reason
5044 Check openssl doc
5046 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5047 · use_certificate_file
5049 Loads the first certificate stored in $file into $ssl.
5051 my $rv = Net::SSLeay::use_certificate_file($ssl, $file, $type);
5053 # $ssl - value corresponding to openssl's SSL structure
5054 # $file - (string) file name
5055 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
5056 #
5057 # returns: 1 on success, otherwise check out the error stack to find out the reason
5058 Check openssl doc
5060 <http://www.openssl.org/docs/ssl/SSL_CTX_use_certificate.html>
5061 · version
5063 Returns SSL/TLS protocol version
5065 my $rv = Net::SSLeay::version($ssl);
5067 # $ssl - value corresponding to openssl's SSL structure
5068 #
5069 # returns: (integer) protocol version
5070 # 0x0002 - SSL2_VERSION (SSLv2)
5071 # 0x0300 - SSL3_VERSION (SSLv3)
5072 # 0x0301 - TLS1_VERSION (TLSv1)
5073 # 0xFEFF - DTLS1_VERSION (DTLSv1)
5074 · want
5076 Returns state information for the SSL object $ssl.
5078 my $rv = Net::SSLeay::want($ssl);
5080 # $ssl - value corresponding to openssl's SSL structure
5081 #
5082 # returns: state
5083 # 1 - SSL_NOTHING
5084 # 2 - SSL_WRITING
5085 # 3 - SSL_READING
5086 # 4 - SSL_X509_LOOKUP
5087 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_want.html>
5089 · write
5091 Writes data from the buffer $data into the specified $ssl
5093 connection.
5094 my $rv = Net::SSLeay::write($ssl, $data);
5096 # $ssl - value corresponding to openssl's SSL structure
5097 # $data - data to be written
5098 #
5099 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5100 # 0 - write not successful, probably the underlying connection was closed
5101 # <0 - error
5102 Check openssl doc <http://www.openssl.org/docs/ssl/SSL_write.html>
5104 · write_partial
5106 NOTE: Does not exactly correspond to any low level API function
5108 Writes a fragment of data in $data from the buffer $data into the
5110 specified $ssl connection. This is a non-blocking function like
5111 Net::SSLeay::write().
5112 my $rv = Net::SSLeay::write_partial($ssl, $from, $count, $data);
5114 # $ssl - value corresponding to openssl's SSL structure
5115 # $from - (integer) offset from the beginning of $data
5116 # $count - (integer) length of data to be written
5117 # $data - data buffer
5118 #
5119 # returns: >0 - (success) number of bytes actually written to the TLS/SSL connection
5120 # 0 - write not successful, probably the underlying connection was closed
5121 # <0 - error
5122 · set_tlsext_host_name
5124 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5126 requires at least openssl-0.9.8f
5127 Sets TLS servername extension on SLL object $ssl to value $name.
5129 my $rv = set_tlsext_host_name($ssl, $name);
5131 # $ssl - value corresponding to openssl's SSL structure
5132 # $name - (string) name to be set
5133 #
5134 # returns: 1 on success, 0 on failure
5135 Low level API: RAND_* related functions
5137 Check openssl doc related to RAND stuff
5139 <http://www.openssl.org/docs/crypto/rand.html>
5140 · RAND_add
5142 Mixes the $num bytes at $buf into the PRNG state.
5144 Net::SSLeay::RAND_add($buf, $num, $entropy);
5146 # $buf - buffer with data to be mixed into the PRNG state
5147 # $num - number of bytes in $buf
5148 # $entropy - estimate of how much randomness is contained in $buf (in bytes)
5149 #
5150 # returns: no return value
5151 Check openssl doc
5153 <http://www.openssl.org/docs/crypto/RAND_add.html>
5154 · RAND_seed
5156 Equivalent to "RAND_add" when $num == $entropy.
5158 Net::SSLeay::RAND_seed($buf); # Perlishly figures out buf size
5160 # $buf - buffer with data to be mixed into the PRNG state
5161 # $num - number of bytes in $buf
5162 #
5163 # returns: no return value
5164 Check openssl doc
5166 <http://www.openssl.org/docs/crypto/RAND_add.html>
5167 · RAND_status
5169 Gives PRNG status (seeded enough or not).
5171 my $rv = Net::SSLeay::RAND_status();
5173 #returns: 1 if the PRNG has been seeded with enough data, 0 otherwise
5174 Check openssl doc
5176 <http://www.openssl.org/docs/crypto/RAND_add.html>
5177 · RAND_bytes
5179 Puts $num cryptographically strong pseudo-random bytes into $buf.
5181 my $rv = Net::SSLeay::RAND_bytes($buf, $num);
5183 # $buf - buffer where the random data will be stored
5184 # $num - the size (in bytes) of requested random data
5185 #
5186 # returns: 1 on success, 0 otherwise
5187 Check openssl doc
5189 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5190 · RAND_pseudo_bytes
5192 Puts $num pseudo-random (not necessarily unpredictable) bytes into
5194 $buf.
5195 my $rv = Net::SSLeay::RAND_pseudo_bytes($buf, $num);
5197 # $buf - buffer where the random data will be stored
5198 # $num - the size (in bytes) of requested random data
5199 #
5200 # returns: 1 if the bytes generated are cryptographically strong, 0 otherwise
5201 Check openssl doc
5203 <http://www.openssl.org/docs/crypto/RAND_bytes.html>
5204 · RAND_cleanup
5206 Erase the PRNG state.
5208 Net::SSLeay::RAND_cleanup();
5210 # no args, no return value
5211 Check openssl doc
5213 <http://www.openssl.org/docs/crypto/RAND_cleanup.html>
5214 · RAND_egd_bytes
5216 Queries the entropy gathering daemon EGD on socket $path for $bytes
5218 bytes.
5219 my $rv = Net::SSLeay::RAND_egd_bytes($path, $bytes);
5221 # $path - path to a socket of entropy gathering daemon EGD
5222 # $bytes - number of bytes we want from EGD
5223 #
5224 # returns: the number of bytes read from the daemon on success, and -1 on failure
5225 Check openssl doc
5227 <http://www.openssl.org/docs/crypto/RAND_egd.html>
5228 · RAND_file_name
5230 Generates a default path for the random seed file.
5232 my $file = Net::SSLeay::RAND_file_name($num);
5234 # $num - maximum size of returned file name
5235 #
5236 # returns: string with file name on success, '' (empty string) on failure
5237 Check openssl doc
5239 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5240 · RAND_load_file
5242 Reads $max_bytes of bytes from $file_name and adds them to the
5244 PRNG.
5245 my $rv = Net::SSLeay::RAND_load_file($file_name, $max_bytes);
5247 # $file_name - the name of file
5248 # $max_bytes - bytes to read from $file_name; -1 => the complete file is read
5249 #
5250 # returns: the number of bytes read
5251 Check openssl doc
5253 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5254 · RAND_write_file
5256 Writes 1024 random bytes to $file_name which can be used to
5258 initialize the PRNG by calling "RAND_load_file" in a later session.
5259 my $rv = Net::SSLeay::RAND_write_file($file_name);
5261 # $file_name - the name of file
5262 #
5263 # returns: the number of bytes written, and -1 if the bytes written were generated without appropriate seed
5264 Check openssl doc
5266 <http://www.openssl.org/docs/crypto/RAND_load_file.html>
5267 · RAND_poll
5269 Collects some entropy from operating system and adds it to the
5271 PRNG.
5272 my $rv = Net::SSLeay::RAND_poll();
5274 # returns: 1 on success, 0 on failure (unable to gather reasonable entropy)
5275 Low level API: OBJ_* related functions
5277 · OBJ_cmp
5279 Compares ASN1_OBJECT $a to ASN1_OBJECT $b.
5281 my $rv = Net::SSLeay::OBJ_cmp($a, $b);
5283 # $a - value corresponding to openssl's ASN1_OBJECT structure
5284 # $b - value corresponding to openssl's ASN1_OBJECT structure
5285 #
5286 # returns: if the two are identical 0 is returned
5287 Check openssl doc
5289 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5290 · OBJ_dup
5292 Returns a copy/duplicate of $o.
5294 my $rv = Net::SSLeay::OBJ_dup($o);
5296 # $o - value corresponding to openssl's ASN1_OBJECT structure
5297 #
5298 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5299 Check openssl doc
5301 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5302 · OBJ_nid2ln
5304 Returns long name for given NID $n.
5306 my $rv = Net::SSLeay::OBJ_nid2ln($n);
5308 # $n - (integer) NID
5309 #
5310 # returns: (string) long name e.g. 'commonName'
5311 Check openssl doc
5313 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5314 · OBJ_ln2nid
5316 Returns NID corresponding to given long name $n.
5318 my $rv = Net::SSLeay::OBJ_ln2nid($s);
5320 # $s - (string) long name e.g. 'commonName'
5321 #
5322 # returns: (integer) NID
5323 · OBJ_nid2sn
5325 Returns short name for given NID $n.
5327 my $rv = Net::SSLeay::OBJ_nid2sn($n);
5329 # $n - (integer) NID
5330 #
5331 # returns: (string) short name e.g. 'CN'
5332 Example:
5334 print Net::SSLeay::OBJ_nid2sn(&Net::SSLeay::NID_commonName);
5336 · OBJ_sn2nid
5338 Returns NID corresponding to given short name $s.
5340 my $rv = Net::SSLeay::OBJ_sn2nid($s);
5342 # $s - (string) short name e.g. 'CN'
5343 #
5344 # returns: (integer) NID
5345 Example:
5347 print "NID_commonName constant=", &Net::SSLeay::NID_commonName;
5349 print "OBJ_sn2nid('CN')=", Net::SSLeay::OBJ_sn2nid('CN');
5350 · OBJ_nid2obj
5352 Returns ASN1_OBJECT for given NID $n.
5354 my $rv = Net::SSLeay::OBJ_nid2obj($n);
5356 # $n - (integer) NID
5357 #
5358 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5359 Check openssl doc
5361 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5362 · OBJ_obj2nid
5364 Returns NID corresponding to given ASN1_OBJECT $o.
5366 my $rv = Net::SSLeay::OBJ_obj2nid($o);
5368 # $o - value corresponding to openssl's ASN1_OBJECT structure
5369 #
5370 # returns: (integer) NID
5371 Check openssl doc
5373 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5374 · OBJ_txt2obj
5376 Converts the text string s into an ASN1_OBJECT structure. If
5378 $no_name is 0 then long names (e.g. 'commonName') and short names
5379 (e.g. 'CN') will be interpreted as well as numerical forms (e.g.
5380 '2.5.4.3'). If $no_name is 1 only the numerical form is acceptable.
5381 my $rv = Net::SSLeay::OBJ_txt2obj($s, $no_name);
5383 # $s - text string to be converted
5384 # $no_name - (integer) 0 or 1
5385 #
5386 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
5387 Check openssl doc
5389 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5390 · OBJ_obj2txt
5392 Converts the ASN1_OBJECT a into a textual representation.
5394 Net::SSLeay::OBJ_obj2txt($a, $no_name);
5396 # $a - value corresponding to openssl's ASN1_OBJECT structure
5397 # $no_name - (integer) 0 or 1
5398 #
5399 # returns: textual representation e.g. 'commonName' ($no_name=0), '2.5.4.3' ($no_name=1)
5400 Check openssl doc
5402 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5403 · OBJ_txt2nid
5405 Returns NID corresponding to text string $s which can be a long
5407 name, a short name or the numerical representation of an object.
5408 my $rv = Net::SSLeay::OBJ_txt2nid($s);
5410 # $s - (string) e.g. 'commonName' or 'CN' or '2.5.4.3'
5411 #
5412 # returns: (integer) NID
5413 Example:
5415 my $nid = Net::SSLeay::OBJ_txt2nid('2.5.4.3');
5417 Net::SSLeay::OBJ_nid2sn($n);
5418 Check openssl doc
5420 <http://www.openssl.org/docs/crypto/OBJ_nid2obj.html>
5421 Low level API: ASN1_INTEGER_* related functions
5423 · ASN1_INTEGER_new
5425 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5427 Creates a new ASN1_INTEGER structure.
5429 my $rv = Net::SSLeay::ASN1_INTEGER_new();
5431 #
5432 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
5433 · ASN1_INTEGER_free
5435 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5437 Free an allocated ASN1_INTEGER structure.
5439 Net::SSLeay::ASN1_INTEGER_free($i);
5441 # $i - value corresponding to openssl's ASN1_INTEGER structure
5442 #
5443 # returns: no return value
5444 · ASN1_INTEGER_get
5446 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5448 Returns integer value of given ASN1_INTEGER object.
5450 BEWARE: If the value stored in ASN1_INTEGER is greater than max.
5452 integer that can be stored in 'long' type (usually 32bit but may
5453 vary according to platform) then this function will return -1. For
5454 getting large ASN1_INTEGER values consider using
5455 "P_ASN1_INTEGER_get_dec" or "P_ASN1_INTEGER_get_hex".
5456 my $rv = Net::SSLeay::ASN1_INTEGER_get($a);
5458 # $a - value corresponding to openssl's ASN1_INTEGER structure
5459 #
5460 # returns: integer value of ASN1_INTEGER object in $a
5461 · ASN1_INTEGER_set
5463 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5465 Sets value of given ASN1_INTEGER object to value $val
5467 BEWARE: $val has max. limit (= max. integer that can be stored in
5469 'long' type). For setting large ASN1_INTEGER values consider using
5470 "P_ASN1_INTEGER_set_dec" or "P_ASN1_INTEGER_set_hex".
5471 my $rv = Net::SSLeay::ASN1_INTEGER_set($i, $val);
5473 # $i - value corresponding to openssl's ASN1_INTEGER structure
5474 # $val - integer value
5475 #
5476 # returns: 1 on success, 0 on failure
5477 · P_ASN1_INTEGER_get_dec
5479 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5481 Returns string with decimal representation of integer value of
5483 given ASN1_INTEGER object.
5484 Net::SSLeay::P_ASN1_INTEGER_get_dec($i);
5486 # $i - value corresponding to openssl's ASN1_INTEGER structure
5487 #
5488 # returns: string with decimal representation
5489 · P_ASN1_INTEGER_get_hex
5491 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5493 Returns string with hexadecimal representation of integer value of
5495 given ASN1_INTEGER object.
5496 Net::SSLeay::P_ASN1_INTEGER_get_hex($i);
5498 # $i - value corresponding to openssl's ASN1_INTEGER structure
5499 #
5500 # returns: string with hexadecimal representation
5501 · P_ASN1_INTEGER_set_dec
5503 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5505 Sets value of given ASN1_INTEGER object to value $val (decimal
5507 string, suitable for large integers)
5508 Net::SSLeay::P_ASN1_INTEGER_set_dec($i, $str);
5510 # $i - value corresponding to openssl's ASN1_INTEGER structure
5511 # $str - string with decimal representation
5512 #
5513 # returns: 1 on success, 0 on failure
5514 · P_ASN1_INTEGER_set_hex
5516 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5518 Sets value of given ASN1_INTEGER object to value $val (hexadecimal
5520 string, suitable for large integers)
5521 Net::SSLeay::P_ASN1_INTEGER_set_hex($i, $str);
5523 # $i - value corresponding to openssl's ASN1_INTEGER structure
5524 # $str - string with hexadecimal representation
5525 #
5526 # returns: 1 on success, 0 on failure
5527 Low level API: ASN1_STRING_* related functions
5529 · P_ASN1_STRING_get
5531 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5533 Returns string value of given ASN1_STRING object.
5535 Net::SSLeay::P_ASN1_STRING_get($s, $utf8_decode);
5537 # $s - value corresponding to openssl's ASN1_STRING structure
5538 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
5539 #
5540 # returns: string
5541 $string = Net::SSLeay::P_ASN1_STRING_get($s);
5543 #is the same as:
5544 $string = Net::SSLeay::P_ASN1_STRING_get($s, 0);
5545 Low level API: ASN1_TIME_* related functions
5547 · ASN1_TIME_new
5549 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5551 my $time = ASN1_TIME_new();
5553 # returns: value corresponding to openssl's ASN1_TIME structure
5554 · ASN1_TIME_free
5556 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5558 ASN1_TIME_free($time);
5560 # $time - value corresponding to openssl's ASN1_TIME structure
5561 · ASN1_TIME_set
5563 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
5565 ASN1_TIME_set($time, $t);
5567 # $time - value corresponding to openssl's ASN1_TIME structure
5568 # $t - time value in seconds since 1.1.1970
5569 BEWARE: It is platform dependent how this function will handle
5571 dates after 2038. Although perl's integer is large enough the
5572 internal implementation of this function is dependent on the size
5573 of time_t structure (32bit time_t has problem with 2038).
5574 If you want to safely set date and time after 2038 use function
5576 "P_ASN1_TIME_set_isotime".
5577 · P_ASN1_TIME_get_isotime
5579 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
5581 requires at least openssl-0.9.7e
5582 NOTE: Does not exactly correspond to any low level API function
5584 Gives ISO-8601 string representation of ASN1_TIME structure.
5586 my $datetime_string = P_ASN1_TIME_get_isotime($time);
5588 # $time - value corresponding to openssl's ASN1_TIME structure
5589 #
5590 # returns: datetime string like '2033-05-16T20:39:37Z' or '' on failure
5591 The output format is compatible with module
5593 DateTime::Format::RFC3339
5594 · P_ASN1_TIME_set_isotime
5596 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
5598 requires at least openssl-0.9.7e
5599 NOTE: Does not exactly correspond to any low level API function
5601 Sets time and date value of ANS1_time structure.
5603 my $rv = P_ASN1_TIME_set_isotime($time, $string);
5605 # $time - value corresponding to openssl's ASN1_TIME structure
5606 # $string - ISO-8601 timedate string like '2033-05-16T20:39:37Z'
5607 #
5608 # returns: 1 on success, 0 on failure
5609 The $string parameter has to be in full form like
5611 "2012-03-22T23:55:33" or "2012-03-22T23:55:33Z" or
5612 "2012-03-22T23:55:33CET". Short forms like "2012-03-22T23:55" or
5613 "2012-03-22" are not supported.
5614 · P_ASN1_TIME_put2string
5616 COMPATIBILITY: not available in Net-SSLeay-1.42 and before, has
5618 bugs with openssl-0.9.8i
5619 NOTE: Does not exactly correspond to any low level API function
5621 Gives string representation of ASN1_TIME structure.
5623 my $str = P_ASN1_TIME_put2string($time);
5625 # $time - value corresponding to openssl's ASN1_TIME structure
5626 #
5627 # returns: datetime string like 'May 16 20:39:37 2033 GMT'
5628 · P_ASN1_UTCTIME_put2string
5630 NOTE: deprecated function, only for backward compatibility, just an
5632 alias for "P_ASN1_TIME_put2string"
5633 Low level API: X509_* related functions
5635 · X509_new
5637 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5639 Allocates and initializes a X509 structure.
5641 my $rv = Net::SSLeay::X509_new();
5643 #
5644 # returns: value corresponding to openssl's X509 structure (0 on failure)
5645 Check openssl doc
5647 <http://www.openssl.org/docs/crypto/X509_new.html>
5648 · X509_free
5650 Frees up the X509 structure.
5652 Net::SSLeay::X509_free($a);
5654 # $a - value corresponding to openssl's X509 structure
5655 #
5656 # returns: no return value
5657 Check openssl doc
5659 <http://www.openssl.org/docs/crypto/X509_new.html>
5660 · X509_check_host
5662 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
5664 requires at least OpenSSL 1.0.2.
5665 X509_CHECK_FLAG_NEVER_CHECK_SUBJECT requires OpenSSL 1.1.0.
5666 Checks f the certificate Subject Alternative Name (SAN) or Subject
5668 CommonName (CN) matches the specified host name.
5669 my $rv = Net::SSLeay::X509_check_host($cert, $name, $flags, $peername);
5671 # $cert - value corresponding to openssl's X509 structure
5672 # $name - host name to check
5673 # $flags (optional, default: 0) - can be the bitwise OR of:
5674 # &Net::SSLeay::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
5675 # &Net::SSLeay::X509_CHECK_FLAG_NO_WILDCARDS
5676 # &Net::SSLeay::X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
5677 # &Net::SSLeay::X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
5678 # &Net::SSLeay::X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
5679 # &Net::SSLeay::X509_CHECK_FLAG_NEVER_CHECK_SUBJECT
5680 # $peername (optional) - If not omitted and $host matches $cert,
5681 # a copy of the matching SAN or CN from
5682 # the peer certificate is stored in $peername.
5683 #
5684 # returns:
5685 # 1 for a successful match
5686 # 0 for a failed match
5687 # -1 for an internal error
5688 # -2 if the input is malformed
5689 Check openssl doc
5691 <https://www.openssl.org/docs/crypto/X509_check_host.html>.
5692 · X509_check_email
5694 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
5696 requires at least OpenSSL 1.0.2.
5697 Checks if the certificate matches the specified email address.
5699 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
5701 # $cert - value corresponding to openssl's X509 structure
5702 # $address - email address to check
5703 # $flags (optional, default: 0) - see X509_check_host()
5704 #
5705 # returns: see X509_check_host()
5706 Check openssl doc
5708 <https://www.openssl.org/docs/crypto/X509_check_email.html>.
5709 · X509_check_ip
5711 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
5713 requires at least OpenSSL 1.0.2.
5714 Checks if the certificate matches the specified IPv4 or IPv6
5716 address.
5717 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
5719 # $cert - value corresponding to openssl's X509 structure
5720 # $address - IP address to check in binary format, in network byte order
5721 # $flags (optional, default: 0) - see X509_check_host()
5722 #
5723 # returns: see X509_check_host()
5724 Check openssl doc
5726 <https://www.openssl.org/docs/crypto/X509_check_ip.html>.
5727 · X509_check_ip_asc
5729 COMPATIBILITY: not available in Net-SSLeay-1.68 and before;
5731 requires at least OpenSSL 1.0.2.
5732 Checks if the certificate matches the specified IPv4 or IPv6
5734 address.
5735 my $rv = Net::SSLeay::X509_check_email($cert, $address, $flags);
5737 # $cert - value corresponding to openssl's X509 structure
5738 # $address - IP address to check in text representation
5739 # $flags (optional, default: 0) - see X509_check_host()
5740 #
5741 # returns: see X509_check_host()
5742 Check openssl doc
5744 <https://www.openssl.org/docs/crypto/X509_check_ip_asc.html>.
5745 · X509_certificate_type
5747 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5749 Returns bitmask with type of certificate $x.
5751 my $rv = Net::SSLeay::X509_certificate_type($x);
5753 # $x - value corresponding to openssl's X509 structure
5754 #
5755 # returns: (integer) bitmask with certificate type
5756 #to decode bitmask returned by this function use these constants:
5758 &Net::SSLeay::EVP_PKS_DSA
5759 &Net::SSLeay::EVP_PKS_EC
5760 &Net::SSLeay::EVP_PKS_RSA
5761 &Net::SSLeay::EVP_PKT_ENC
5762 &Net::SSLeay::EVP_PKT_EXCH
5763 &Net::SSLeay::EVP_PKT_EXP
5764 &Net::SSLeay::EVP_PKT_SIGN
5765 &Net::SSLeay::EVP_PK_DH
5766 &Net::SSLeay::EVP_PK_DSA
5767 &Net::SSLeay::EVP_PK_EC
5768 &Net::SSLeay::EVP_PK_RSA
5769 · X509_digest
5771 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5773 Computes digest/fingerprint of X509 $data using $type hash
5775 function.
5776 my $digest_value = Net::SSLeay::X509_digest($data, $type);
5778 # $data - value corresponding to openssl's X509 structure
5779 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5780 #
5781 # returns: hash value (binary)
5782 #to get printable (hex) value of digest use:
5784 print unpack('H*', $digest_value);
5785 · X509_issuer_and_serial_hash
5787 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5789 Sort of a checksum of issuer name and serial number of X509
5791 certificate $x. The result is not a full hash (e.g. sha-1), it is
5792 kind-of-a-hash truncated to the size of 'unsigned long' (32 bits).
5793 The resulting value might differ across different openssl versions
5794 for the same X509 certificate.
5795 my $rv = Net::SSLeay::X509_issuer_and_serial_hash($x);
5797 # $x - value corresponding to openssl's X509 structure
5798 #
5799 # returns: number representing checksum
5800 · X509_issuer_name_hash
5802 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5804 Sort of a checksum of issuer name of X509 certificate $x. The
5806 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
5807 truncated to the size of 'unsigned long' (32 bits). The resulting
5808 value might differ across different openssl versions for the same
5809 X509 certificate.
5810 my $rv = Net::SSLeay::X509_issuer_name_hash($x);
5812 # $x - value corresponding to openssl's X509 structure
5813 #
5814 # returns: number representing checksum
5815 · X509_subject_name_hash
5817 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5819 Sort of a checksum of subject name of X509 certificate $x. The
5821 result is not a full hash (e.g. sha-1), it is kind-of-a-hash
5822 truncated to the size of 'unsigned long' (32 bits). The resulting
5823 value might differ across different openssl versions for the same
5824 X509 certificate.
5825 my $rv = Net::SSLeay::X509_subject_name_hash($x);
5827 # $x - value corresponding to openssl's X509 structure
5828 #
5829 # returns: number representing checksum
5830 · X509_pubkey_digest
5832 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
5834 requires at least openssl-0.9.7
5835 Computes digest/fingerprint of public key from X509 certificate
5837 $data using $type hash function.
5838 my $digest_value = Net::SSLeay::X509_pubkey_digest($data, $type);
5840 # $data - value corresponding to openssl's X509 structure
5841 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
5842 #
5843 # returns: hash value (binary)
5844 #to get printable (hex) value of digest use:
5846 print unpack('H*', $digest_value);
5847 · X509_set_issuer_name
5849 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5851 Sets issuer of X509 certificate $x to $name.
5853 my $rv = Net::SSLeay::X509_set_issuer_name($x, $name);
5855 # $x - value corresponding to openssl's X509 structure
5856 # $name - value corresponding to openssl's X509_NAME structure
5857 #
5858 # returns: 1 on success, 0 on failure
5859 · X509_set_pubkey
5861 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5863 Sets public key of X509 certificate $x to $pkey.
5865 my $rv = Net::SSLeay::X509_set_pubkey($x, $pkey);
5867 # $x - value corresponding to openssl's X509 structure
5868 # $pkey - value corresponding to openssl's EVP_PKEY structure
5869 #
5870 # returns: 1 on success, 0 on failure
5871 · X509_set_serialNumber
5873 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5875 Sets serial number of X509 certificate $x to $serial.
5877 my $rv = Net::SSLeay::X509_set_serialNumber($x, $serial);
5879 # $x - value corresponding to openssl's X509 structure
5880 # $serial - value corresponding to openssl's ASN1_INTEGER structure
5881 #
5882 # returns: 1 on success, 0 on failure
5883 #to create $serial value use one of these:
5885 $serial = Net::SSLeay::P_ASN1_INTEGER_set_hex('45ad6f');
5886 $serial = Net::SSLeay::P_ASN1_INTEGER_set_dec('7896541238529631478');
5887 $serial = Net::SSLeay::ASN1_INTEGER_set(45896);
5888 · X509_set_subject_name
5890 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5892 Sets subject of X509 certificate $x to $name.
5894 my $rv = Net::SSLeay::X509_set_subject_name($x, $name);
5896 # $x - value corresponding to openssl's X509 structure
5897 # $name - value corresponding to openssl's X509_NAME structure
5898 #
5899 # returns: 1 on success, 0 on failure
5900 · X509_set_version
5902 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5904 Set 'version' value for X509 certificate $ to $version.
5906 my $rv = Net::SSLeay::X509_set_version($x, $version);
5908 # $x - value corresponding to openssl's X509 structure
5909 # $version - (integer) version number
5910 #
5911 # returns: 1 on success, 0 on failure
5912 · X509_sign
5914 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5916 Sign X509 certificate $x with private key $pkey (using digest
5918 algorithm $md).
5919 my $rv = Net::SSLeay::X509_sign($x, $pkey, $md);
5921 # $x - value corresponding to openssl's X509 structure
5922 # $pkey - value corresponding to openssl's EVP_PKEY structure
5923 # $md - value corresponding to openssl's EVP_MD structure
5924 #
5925 # returns: 1 on success, 0 on failure
5926 · X509_verify
5928 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5930 Verifies X509 object $a using public key $r (pubkey of issuing CA).
5932 my $rv = Net::SSLeay::X509_verify($x, $r);
5934 # $x - value corresponding to openssl's X509 structure
5935 # $r - value corresponding to openssl's EVP_PKEY structure
5936 #
5937 # returns: 0 - verify failure, 1 - verify OK, <0 - error
5938 · X509_get_ext_count
5940 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5942 Returns the total number of extensions in X509 object $x.
5944 my $rv = Net::SSLeay::X509_get_ext_count($x);
5946 # $x - value corresponding to openssl's X509 structure
5947 #
5948 # returns: count of extensions
5949 · X509_get_pubkey
5951 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5953 Returns public key corresponding to given X509 object $x.
5955 my $rv = Net::SSLeay::X509_get_pubkey($x);
5957 # $x - value corresponding to openssl's X509 structure
5958 #
5959 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
5960 NOTE: This method returns only the public key's key bits, without
5962 the algorithm or parameters. Use "X509_get_X509_PUBKEY()" to
5963 return the full public key (SPKI) instead.
5964 · X509_get_X509_PUBKEY
5966 COMPATIBILITY: not available in Net-SSLeay-1.72 and before
5968 Returns the full public key (SPKI) of given X509 certificate $x.
5970 Net::SSLeay::X509_get_X509_PUBKEY($x);
5972 # $x - value corresponding to openssl's X509 structure
5973 #
5974 # returns: public key data in DER format (binary)
5975 · X509_get_serialNumber
5977 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5979 Returns serial number of X509 certificate $x.
5981 my $rv = Net::SSLeay::X509_get_serialNumber($x);
5983 # $x - value corresponding to openssl's X509 structure
5984 #
5985 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
5986 See "P_ASN1_INTEGER_get_dec", "P_ASN1_INTEGER_get_hex" or
5988 "ASN1_INTEGER_get" to decode ASN1_INTEGER object.
5989 · X509_get_version
5991 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
5993 Returns 'version' value of given X509 certificate $x.
5995 my $rv = Net::SSLeay::X509_get_version($x);
5997 # $x - value corresponding to openssl's X509 structure
5998 #
5999 # returns: (integer) version
6000 · X509_get_ext
6002 Returns X509_EXTENSION from $x509 based on given position/index.
6004 my $rv = Net::SSLeay::X509_get_ext($x509, $index);
6006 # $x509 - value corresponding to openssl's X509 structure
6007 # $index - (integer) position/index of extension within $x509
6008 #
6009 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6010 · X509_get_ext_by_NID
6012 Returns X509_EXTENSION from $x509 based on given NID.
6014 my $rv = Net::SSLeay::X509_get_ext_by_NID($x509, $nid, $loc);
6016 # $x509 - value corresponding to openssl's X509 structure
6017 # $nid - (integer) NID value
6018 # $loc - (integer) position to start lookup at
6019 #
6020 # returns: position/index of extension, negative value on error
6021 # call Net::SSLeay::X509_get_ext($x509, $rv) to get the actual extension
6022 · X509_get_fingerprint
6024 Returns fingerprint of certificate $cert.
6026 NOTE: Does not exactly correspond to any low level API function.
6028 The implementation is basen on openssl's "X509_digest()".
6029 Net::SSLeay::X509_get_fingerprint($x509, $type);
6031 # $x509 - value corresponding to openssl's X509 structure
6032 # $type - (string) digest type, currently supported values:
6033 # "md5"
6034 # "sha1"
6035 # "sha256"
6036 # "ripemd160"
6037 #
6038 # returns: certificate digest - hexadecimal string (NOT binary data!)
6039 · X509_get_issuer_name
6041 Return an X509_NAME object representing the issuer of the
6043 certificate $cert.
6044 my $rv = Net::SSLeay::X509_get_issuer_name($cert);
6046 # $cert - value corresponding to openssl's X509 structure
6047 #
6048 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6049 · X509_get_notAfter
6051 Return an object giving the time after which the certificate $cert
6053 is not valid.
6054 my $rv = Net::SSLeay::X509_get_notAfter($cert);
6056 # $cert - value corresponding to openssl's X509 structure
6057 #
6058 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6059 To get human readable/printable form the return value you can use:
6061 my $time = Net::SSLeay::X509_get_notAfter($cert);
6063 print "notAfter=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6064 · X509_get_notBefore
6066 Return an object giving the time before which the certificate $cert
6068 is not valid
6069 my $rv = Net::SSLeay::X509_get_notBefore($cert);
6071 # $cert - value corresponding to openssl's X509 structure
6072 #
6073 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6074 To get human readable/printable form the return value you can use:
6076 my $time = Net::SSLeay::X509_get_notBefore($cert);
6078 print "notBefore=", Net::SSLeay::P_ASN1_TIME_get_isotime($time), "\n";
6079 · X509_get_subjectAltNames
6081 NOTE: Does not exactly correspond to any low level API function.
6083 Returns the list of alternative subject names from X509 certificate
6085 $cert.
6086 my @rv = Net::SSLeay::X509_get_subjectAltNames($cert);
6088 # $cert - value corresponding to openssl's X509 structure
6089 #
6090 # returns: list containing pairs - name_type (integer), name_value (string)
6091 # where name_type can be:
6092 # 0 - GEN_OTHERNAME
6093 # 1 - GEN_EMAIL
6094 # 2 - GEN_DNS
6095 # 3 - GEN_X400
6096 # 4 - GEN_DIRNAME
6097 # 5 - GEN_EDIPARTY
6098 # 6 - GEN_URI
6099 # 7 - GEN_IPADD
6100 # 8 - GEN_RID
6101 Note: type 7 - GEN_IPADD contains the IP address as a packed binary
6103 address.
6104 · X509_get_subject_name
6106 Returns the subject of the certificate $cert.
6108 my $rv = Net::SSLeay::X509_get_subject_name($cert);
6110 # $cert - value corresponding to openssl's X509 structure
6111 #
6112 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6113 · X509_gmtime_adj
6115 Adjust th ASN1_TIME object to the timestamp (in GMT).
6117 my $rv = Net::SSLeay::X509_gmtime_adj($s, $adj);
6119 # $s - value corresponding to openssl's ASN1_TIME structure
6120 # $adj - timestamp (seconds since 1.1.1970)
6121 #
6122 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6123 BEWARE: this function may fail for dates after 2038 as it is
6125 dependent on time_t size on your system (32bit time_t does not work
6126 after 2038). Consider using "P_ASN1_TIME_set_isotime" instead).
6127 · X509_load_cert_crl_file
6129 Takes PEM file and loads all X509 certificates and X509 CRLs from
6131 that file into X509_LOOKUP structure.
6132 my $rv = Net::SSLeay::X509_load_cert_crl_file($ctx, $file, $type);
6134 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6135 # $file - (string) file name
6136 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6137 # if not FILETYPE_PEM then behaves as Net::SSLeay::X509_load_cert_file()
6138 #
6139 # returns: 1 on success, 0 on failure
6140 · X509_load_cert_file
6142 Loads/adds X509 certificate from $file to X509_LOOKUP structure
6144 my $rv = Net::SSLeay::X509_load_cert_file($ctx, $file, $type);
6146 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6147 # $file - (string) file name
6148 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6149 #
6150 # returns: 1 on success, 0 on failure
6151 · X509_load_crl_file
6153 Loads/adds X509 CRL from $file to X509_LOOKUP structure
6155 my $rv = Net::SSLeay::X509_load_crl_file($ctx, $file, $type);
6157 # $ctx - value corresponding to openssl's X509_LOOKUP structure
6158 # $file - (string) file name
6159 # $type - (integer) type - use constants &Net::SSLeay::FILETYPE_PEM or &Net::SSLeay::FILETYPE_ASN1
6160 #
6161 # returns: 1 on success, 0 on failure
6162 · X509_policy_level_get0_node
6164 ??? (more info needed)
6166 my $rv = Net::SSLeay::X509_policy_level_get0_node($level, $i);
6168 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6169 # $i - (integer) index/position
6170 #
6171 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6172 · X509_policy_level_node_count
6174 ??? (more info needed)
6176 my $rv = Net::SSLeay::X509_policy_level_node_count($level);
6178 # $level - value corresponding to openssl's X509_POLICY_LEVEL structure
6179 #
6180 # returns: (integer) node count
6181 · X509_policy_node_get0_parent
6183 ??? (more info needed)
6185 my $rv = Net::SSLeay::X509_policy_node_get0_parent($node);
6187 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6188 #
6189 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6190 · X509_policy_node_get0_policy
6192 ??? (more info needed)
6194 my $rv = Net::SSLeay::X509_policy_node_get0_policy($node);
6196 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6197 #
6198 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6199 · X509_policy_node_get0_qualifiers
6201 ??? (more info needed)
6203 my $rv = Net::SSLeay::X509_policy_node_get0_qualifiers($node);
6205 # $node - value corresponding to openssl's X509_POLICY_NODE structure
6206 #
6207 # returns: value corresponding to openssl's STACK_OF(POLICYQUALINFO) structure (0 on failure)
6208 · X509_policy_tree_free
6210 ??? (more info needed)
6212 Net::SSLeay::X509_policy_tree_free($tree);
6214 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6215 #
6216 # returns: no return value
6217 · X509_policy_tree_get0_level
6219 ??? (more info needed)
6221 my $rv = Net::SSLeay::X509_policy_tree_get0_level($tree, $i);
6223 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6224 # $i - (integer) level index
6225 #
6226 # returns: value corresponding to openssl's X509_POLICY_LEVEL structure (0 on failure)
6227 · X509_policy_tree_get0_policies
6229 ??? (more info needed)
6231 my $rv = Net::SSLeay::X509_policy_tree_get0_policies($tree);
6233 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6234 #
6235 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6236 · X509_policy_tree_get0_user_policies
6238 ??? (more info needed)
6240 my $rv = Net::SSLeay::X509_policy_tree_get0_user_policies($tree);
6242 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6243 #
6244 # returns: value corresponding to openssl's X509_POLICY_NODE structure (0 on failure)
6245 · X509_policy_tree_level_count
6247 ??? (more info needed)
6249 my $rv = Net::SSLeay::X509_policy_tree_level_count($tree);
6251 # $tree - value corresponding to openssl's X509_POLICY_TREE structure
6252 #
6253 # returns: (integer) count
6254 · X509_verify_cert_error_string
6256 Returns a human readable error string for verification error $n.
6258 my $rv = Net::SSLeay::X509_verify_cert_error_string($n);
6260 # $n - (long) numeric error code
6261 #
6262 # returns: error string
6263 Check openssl doc
6265 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
6266 · P_X509_add_extensions
6268 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6270 Adds one or more X509 extensions to X509 object $x.
6272 my $rv = Net::SSLeay::P_X509_add_extensions($x, $ca_cert, $nid, $value);
6274 # $x - value corresponding to openssl's X509 structure
6275 # $ca_cert - value corresponding to openssl's X509 structure (issuer's cert - necessary for sertting NID_authority_key_identifier)
6276 # $nid - NID identifying extension to be set
6277 # $value - extension value
6278 #
6279 # returns: 1 on success, 0 on failure
6280 You can set more extensions at once:
6282 my $rv = Net::SSLeay::P_X509_add_extensions($x509, $ca_cert,
6284 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6285 &Net::SSLeay::NID_subject_key_identifier => 'hash',
6286 &Net::SSLeay::NID_authority_key_identifier => 'keyid',
6287 &Net::SSLeay::NID_authority_key_identifier => 'issuer',
6288 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6289 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6290 &Net::SSLeay::NID_netscape_cert_type => 'server',
6291 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.dom.com,DNS:s2.dom.com,DNS:s3.dom.com',
6292 );
6293 · P_X509_copy_extensions
6295 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6297 Copies X509 extensions from X509_REQ object to X509 object - handy
6299 when you need to turn X509_REQ into X509 certificate.
6300 Net::SSLeay::P_X509_copy_extensions($x509_req, $x509, $override);
6302 # $x509_req - value corresponding to openssl's X509_REQ structure
6303 # $x509 - value corresponding to openssl's X509 structure
6304 # $override - (integer) flag indication whether to override already existing items in $x509 (default 1)
6305 #
6306 # returns: 1 on success, 0 on failure
6307 · P_X509_get_crl_distribution_points
6309 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6311 requires at least openssl-0.9.7
6312 Get the list of CRL distribution points from X509 certificate.
6314 my @cdp = Net::SSLeay::P_X509_get_crl_distribution_points($x509);
6316 # $x509 - value corresponding to openssl's X509 structure
6317 #
6318 # returns: list of distribution points (usually URLs)
6319 · P_X509_get_ext_key_usage
6321 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6323 requires at least openssl-0.9.7
6324 Gets the list of extended key usage of given X509 certificate
6326 $cert.
6327 my @ext_usage = Net::SSLeay::P_X509_get_ext_key_usage($cert, $format);
6329 # $cert - value corresponding to openssl's X509 structure
6330 # $format - choose type of return values: 0=OIDs, 1=NIDs, 2=shortnames, 3=longnames
6331 #
6332 # returns: list of values
6333 Examples:
6335 my @extkeyusage_oid = Net::SSLeay::P_X509_get_ext_key_usage($x509,0);
6337 # returns for example: ("1.3.6.1.5.5.7.3.1", "1.3.6.1.5.5.7.3.2")
6338 my @extkeyusage_nid = Net::SSLeay::P_X509_get_ext_key_usage($x509,1);
6340 # returns for example: (129, 130)
6341 my @extkeyusage_sn = Net::SSLeay::P_X509_get_ext_key_usage($x509,2);
6343 # returns for example: ("serverAuth", "clientAuth")
6344 my @extkeyusage_ln = Net::SSLeay::P_X509_get_ext_key_usage($x509,3);
6346 # returns for example: ("TLS Web Server Authentication", "TLS Web Client Authentication")
6347 · P_X509_get_key_usage
6349 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6351 Gets the list of key usage of given X509 certificate $cert.
6353 my @keyusage = Net::SSLeay::P_X509_get_key_usage($cert);
6355 # $cert - value corresponding to openssl's X509 structure
6356 #
6357 # returns: list of key usage values which can be none, one or more from the following list:
6358 # "digitalSignature"
6359 # "nonRepudiation"
6360 # "keyEncipherment"
6361 # "dataEncipherment"
6362 # "keyAgreement"
6363 # "keyCertSign"
6364 # "cRLSign"
6365 # "encipherOnly"
6366 # "decipherOnly"
6367 · P_X509_get_netscape_cert_type
6369 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6371 Gets the list of Netscape cert types of given X509 certificate
6373 $cert.
6374 Net::SSLeay::P_X509_get_netscape_cert_type($cert);
6376 # $cert - value corresponding to openssl's X509 structure
6377 #
6378 # returns: list of Netscape type values which can be none, one or more from the following list:
6379 # "client"
6380 # "server"
6381 # "email"
6382 # "objsign"
6383 # "reserved"
6384 # "sslCA"
6385 # "emailCA"
6386 # "objCA"
6387 · P_X509_get_pubkey_alg
6389 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6391 Returns ASN1_OBJECT corresponding to X509 certificate public key
6393 algorithm.
6394 my $rv = Net::SSLeay::P_X509_get_pubkey_alg($x);
6396 # $x - value corresponding to openssl's X509 structure
6397 #
6398 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6399 To get textual representation use:
6401 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_pubkey_alg($x509));
6403 # returns for example: "rsaEncryption"
6404 · P_X509_get_signature_alg
6406 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6408 Returns ASN1_OBJECT corresponding to X509 signarite key algorithm.
6410 my $rv = Net::SSLeay::P_X509_get_signature_alg($x);
6412 # $x - value corresponding to openssl's X509 structure
6413 #
6414 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6415 To get textual representation use:
6417 my $alg = Net::SSLeay::OBJ_obj2txt(Net::SSLeay::P_X509_get_signature_alg($x509))
6419 # returns for example: "sha1WithRSAEncryption"
6420 Low level API: X509_REQ_* related functions
6422 · X509_REQ_new
6424 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6426 Creates a new X509_REQ structure.
6428 my $rv = Net::SSLeay::X509_REQ_new();
6430 #
6431 # returns: value corresponding to openssl's X509_REQ structure (0 on failure)
6432 · X509_REQ_free
6434 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6436 Free an allocated X509_REQ structure.
6438 Net::SSLeay::X509_REQ_free($x);
6440 # $x - value corresponding to openssl's X509_REQ structure
6441 #
6442 # returns: no return value
6443 · X509_REQ_add1_attr_by_NID
6445 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6447 Adds an attribute whose name is defined by a NID $nid. The field
6449 value to be added is in $bytes.
6450 my $rv = Net::SSLeay::X509_REQ_add1_attr_by_NID($req, $nid, $type, $bytes);
6452 # $req - value corresponding to openssl's X509_REQ structure
6453 # $nid - (integer) NID value
6454 # $type - (integer) type of data in $bytes (see below)
6455 # $bytes - data to be set
6456 #
6457 # returns: 1 on success, 0 on failure
6458 # values for $type - use constants:
6460 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
6461 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
6462 · X509_REQ_digest
6464 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6466 Computes digest/fingerprint of X509_REQ $data using $type hash
6468 function.
6469 my $digest_value = Net::SSLeay::X509_REQ_digest($data, $type);
6471 # $data - value corresponding to openssl's X509_REQ structure
6472 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6473 #
6474 # returns: hash value (binary)
6475 #to get printable (hex) value of digest use:
6477 print unpack('H*', $digest_value);
6478 · X509_REQ_get_attr_by_NID
6480 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6482 Retrieve the next index matching $nid after $lastpos ($lastpos
6484 should initially be set to -1).
6485 my $rv = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid, $lastpos=-1);
6487 # $req - value corresponding to openssl's X509_REQ structure
6488 # $nid - (integer) NID value
6489 # $lastpos - [optional] (integer) index where to start search (default -1)
6490 #
6491 # returns: index (-1 if there are no more entries)
6492 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6494 e.g.
6495 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6497 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6498 · X509_REQ_get_attr_by_OBJ
6500 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6502 Retrieve the next index matching $obj after $lastpos ($lastpos
6504 should initially be set to -1).
6505 my $rv = Net::SSLeay::X509_REQ_get_attr_by_OBJ($req, $obj, $lastpos=-1);
6507 # $req - value corresponding to openssl's X509_REQ structure
6508 # $obj - value corresponding to openssl's ASN1_OBJECT structure
6509 # $lastpos - [optional] (integer) index where to start search (default -1)
6510 #
6511 # returns: index (-1 if there are no more entries)
6512 Note: use "P_X509_REQ_get_attr" to get the actual attribute value -
6514 e.g.
6515 my $index = Net::SSLeay::X509_REQ_get_attr_by_NID($req, $nid);
6517 my @attr_values = Net::SSLeay::P_X509_REQ_get_attr($req, $index);
6518 · X509_REQ_get_attr_count
6520 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6522 Returns the total number of attributes in $req.
6524 my $rv = Net::SSLeay::X509_REQ_get_attr_count($req);
6526 # $req - value corresponding to openssl's X509_REQ structure
6527 #
6528 # returns: (integer) items count
6529 · X509_REQ_get_pubkey
6531 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6533 Returns public key corresponding to given X509_REQ object $x.
6535 my $rv = Net::SSLeay::X509_REQ_get_pubkey($x);
6537 # $x - value corresponding to openssl's X509_REQ structure
6538 #
6539 # returns: value corresponding to openssl's EVP_PKEY structure (0 on failure)
6540 · X509_REQ_get_subject_name
6542 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6544 Returns X509_NAME object corresponding to subject name of given
6546 X509_REQ object $x.
6547 my $rv = Net::SSLeay::X509_REQ_get_subject_name($x);
6549 # $x - value corresponding to openssl's X509_REQ structure
6550 #
6551 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6552 · X509_REQ_get_version
6554 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6556 Returns 'version' value for given X509_REQ object $x.
6558 my $rv = Net::SSLeay::X509_REQ_get_version($x);
6560 # $x - value corresponding to openssl's X509_REQ structure
6561 #
6562 # returns: (integer) version e.g. 0 = "version 1"
6563 · X509_REQ_set_pubkey
6565 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6567 Sets public key of given X509_REQ object $x to $pkey.
6569 my $rv = Net::SSLeay::X509_REQ_set_pubkey($x, $pkey);
6571 # $x - value corresponding to openssl's X509_REQ structure
6572 # $pkey - value corresponding to openssl's EVP_PKEY structure
6573 #
6574 # returns: 1 on success, 0 on failure
6575 · X509_REQ_set_subject_name
6577 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6579 Sets subject name of given X509_REQ object $x to X509_NAME object
6581 $name.
6582 my $rv = Net::SSLeay::X509_REQ_set_subject_name($x, $name);
6584 # $x - value corresponding to openssl's X509_REQ structure
6585 # $name - value corresponding to openssl's X509_NAME structure
6586 #
6587 # returns: 1 on success, 0 on failure
6588 · X509_REQ_set_version
6590 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6592 Sets 'version' of given X509_REQ object $x to $version.
6594 my $rv = Net::SSLeay::X509_REQ_set_version($x, $version);
6596 # $x - value corresponding to openssl's X509_REQ structure
6597 # $version - (integer) e.g. 0 = "version 1"
6598 #
6599 # returns: 1 on success, 0 on failure
6600 · X509_REQ_sign
6602 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6604 Sign X509_REQ object $x with private key $pk (using digest
6606 algorithm $md).
6607 my $rv = Net::SSLeay::X509_REQ_sign($x, $pk, $md);
6609 # $x - value corresponding to openssl's X509_REQ structure
6610 # $pk - value corresponding to openssl's EVP_PKEY structure (requestor's private key)
6611 # $md - value corresponding to openssl's EVP_MD structure
6612 #
6613 # returns: 1 on success, 0 on failure
6614 · X509_REQ_verify
6616 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6618 Verifies X509_REQ object $x using public key $r (pubkey of
6620 requesting party).
6621 my $rv = Net::SSLeay::X509_REQ_verify($x, $r);
6623 # $x - value corresponding to openssl's X509_REQ structure
6624 # $r - value corresponding to openssl's EVP_PKEY structure
6625 #
6626 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6627 · P_X509_REQ_add_extensions
6629 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6631 Adds one or more X509 extensions to X509_REQ object $x.
6633 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x, $nid, $value);
6635 # $x - value corresponding to openssl's X509_REQ structure
6636 # $nid - NID identifying extension to be set
6637 # $value - extension value
6638 #
6639 # returns: 1 on success, 0 on failure
6640 You can set more extensions at once:
6642 my $rv = Net::SSLeay::P_X509_REQ_add_extensions($x509_req,
6644 &Net::SSLeay::NID_key_usage => 'digitalSignature,keyEncipherment',
6645 &Net::SSLeay::NID_basic_constraints => 'CA:FALSE',
6646 &Net::SSLeay::NID_ext_key_usage => 'serverAuth,clientAuth',
6647 &Net::SSLeay::NID_netscape_cert_type => 'server',
6648 &Net::SSLeay::NID_subject_alt_name => 'DNS:s1.com,DNS:s2.com',
6649 &Net::SSLeay::NID_crl_distribution_points => 'URI:http://pki.com/crl1,URI:http://pki.com/crl2',
6650 );
6651 · P_X509_REQ_get_attr
6653 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6655 requires at least openssl-0.9.7
6656 Returns attribute value for X509_REQ's attribute at index $n.
6658 Net::SSLeay::P_X509_REQ_get_attr($req, $n);
6660 # $req - value corresponding to openssl's X509_REQ structure
6661 # $n - (integer) attribute index
6662 #
6663 # returns: value corresponding to openssl's ASN1_STRING structure
6664 Low level API: X509_CRL_* related functions
6666 · X509_CRL_new
6668 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6670 Creates a new X509_CRL structure.
6672 my $rv = Net::SSLeay::X509_CRL_new();
6674 #
6675 # returns: value corresponding to openssl's X509_CRL structure (0 on failure)
6676 · X509_CRL_free
6678 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6680 Free an allocated X509_CRL structure.
6682 Net::SSLeay::X509_CRL_free($x);
6684 # $x - value corresponding to openssl's X509_CRL structure
6685 #
6686 # returns: no return value
6687 · X509_CRL_digest
6689 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6691 Computes digest/fingerprint of X509_CRL $data using $type hash
6693 function.
6694 my $digest_value = Net::SSLeay::X509_CRL_digest($data, $type);
6696 # $data - value corresponding to openssl's X509_CRL structure
6697 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
6698 #
6699 # returns: hash value (binary)
6700 Example:
6702 my $x509_crl
6704 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
6705 my $digest_value = Net::SSLeay::X509_CRL_digest($x509_crl, $md);
6706 #to get printable (hex) value of digest use:
6707 print "digest=", unpack('H*', $digest_value), "\n";
6708 · X509_CRL_get_ext
6710 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
6712 Returns X509_EXTENSION from $x509 based on given position/index.
6714 my $rv = Net::SSLeay::X509_CRL_get_ext($x509, $index);
6716 # $x509 - value corresponding to openssl's X509_CRL structure
6717 # $index - (integer) position/index of extension within $x509
6718 #
6719 # returns: value corresponding to openssl's X509_EXTENSION structure (0 on failure)
6720 · X509_CRL_get_ext_by_NID
6722 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
6724 Returns X509_EXTENSION from $x509 based on given NID.
6726 my $rv = Net::SSLeay::X509_CRL_get_ext_by_NID($x509, $nid, $loc);
6728 # $x509 - value corresponding to openssl's X509_CRL structure
6729 # $nid - (integer) NID value
6730 # $loc - (integer) position to start lookup at
6731 #
6732 # returns: position/index of extension, negative value on error
6733 # call Net::SSLeay::X509_CRL_get_ext($x509, $rv) to get the actual extension
6734 · X509_CRL_get_ext_count
6736 COMPATIBILITY: not available in Net-SSLeay-1.54 and before
6738 Returns the total number of extensions in X509_CRL object $x.
6740 my $rv = Net::SSLeay::X509_CRL_get_ext_count($x);
6742 # $x - value corresponding to openssl's X509_CRL structure
6743 #
6744 # returns: count of extensions
6745 · X509_CRL_get_issuer
6747 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6749 Returns X509_NAME object corresponding to the issuer of X509_CRL
6751 $x.
6752 my $rv = Net::SSLeay::X509_CRL_get_issuer($x);
6754 # $x - value corresponding to openssl's X509_CRL structure
6755 #
6756 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
6757 See other "X509_NAME_*" functions to get more info from X509_NAME
6759 structure.
6760 · X509_CRL_get_lastUpdate
6762 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6764 Returns 'lastUpdate' date-time value of X509_CRL object $x.
6766 my $rv = Net::SSLeay::X509_CRL_get_lastUpdate($x);
6768 # $x - value corresponding to openssl's X509_CRL structure
6769 #
6770 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6771 · X509_CRL_get_nextUpdate
6773 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6775 Returns 'nextUpdate' date-time value of X509_CRL object $x.
6777 my $rv = Net::SSLeay::X509_CRL_get_nextUpdate($x);
6779 # $x - value corresponding to openssl's X509_CRL structure
6780 #
6781 # returns: value corresponding to openssl's ASN1_TIME structure (0 on failure)
6782 · X509_CRL_get_version
6784 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6786 Returns 'version' value of given X509_CRL structure $x.
6788 my $rv = Net::SSLeay::X509_CRL_get_version($x);
6790 # $x - value corresponding to openssl's X509_CRL structure
6791 #
6792 # returns: (integer) version
6793 · X509_CRL_set_issuer_name
6795 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6797 requires at least openssl-0.9.7
6798 Sets the issuer of X509_CRL object $x to X509_NAME object $name.
6800 my $rv = Net::SSLeay::X509_CRL_set_issuer_name($x, $name);
6802 # $x - value corresponding to openssl's X509_CRL structure
6803 # $name - value corresponding to openssl's X509_NAME structure
6804 #
6805 # returns: 1 on success, 0 on failure
6806 · X509_CRL_set_lastUpdate
6808 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6810 requires at least openssl-0.9.7
6811 Sets 'lastUpdate' value of X509_CRL object $x to $tm.
6813 my $rv = Net::SSLeay::X509_CRL_set_lastUpdate($x, $tm);
6815 # $x - value corresponding to openssl's X509_CRL structure
6816 # $tm - value corresponding to openssl's ASN1_TIME structure
6817 #
6818 # returns: 1 on success, 0 on failure
6819 · X509_CRL_set_nextUpdate
6821 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6823 requires at least openssl-0.9.7
6824 Sets 'nextUpdate' value of X509_CRL object $x to $tm.
6826 my $rv = Net::SSLeay::X509_CRL_set_nextUpdate($x, $tm);
6828 # $x - value corresponding to openssl's X509_CRL structure
6829 # $tm - value corresponding to openssl's ASN1_TIME structure
6830 #
6831 # returns: 1 on success, 0 on failure
6832 · X509_CRL_set_version
6834 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6836 requires at least openssl-0.9.7
6837 Sets 'version' value of given X509_CRL structure $x to $version.
6839 my $rv = Net::SSLeay::X509_CRL_set_version($x, $version);
6841 # $x - value corresponding to openssl's X509_CRL structure
6842 # $version - (integer) version number (1 = version 2 CRL)
6843 #
6844 # returns: 1 on success, 0 on failure
6845 Note that if you want to use any X509_CRL extension you need to set
6847 "version 2 CRL" - "Net::SSLeay::X509_CRL_set_version($x, 1)".
6848 · X509_CRL_sign
6850 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6852 Sign X509_CRL object $x with private key $pkey (using digest
6854 algorithm $md).
6855 my $rv = Net::SSLeay::X509_CRL_sign($x, $pkey, $md);
6857 # $x - value corresponding to openssl's X509_CRL structure
6858 # $pkey - value corresponding to openssl's EVP_PKEY structure
6859 # $md - value corresponding to openssl's EVP_MD structure
6860 #
6861 # returns: 1 on success, 0 on failure
6862 · X509_CRL_sort
6864 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6866 requires at least openssl-0.9.7
6867 Sorts the data of X509_CRL object so it will be written in serial
6869 number order.
6870 my $rv = Net::SSLeay::X509_CRL_sort($x);
6872 # $x - value corresponding to openssl's X509_CRL structure
6873 #
6874 # returns: 1 on success, 0 on failure
6875 · X509_CRL_verify
6877 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6879 Verifies X509_CRL object $a using public key $r (pubkey of issuing
6881 CA).
6882 my $rv = Net::SSLeay::X509_CRL_verify($a, $r);
6884 # $a - value corresponding to openssl's X509_CRL structure
6885 # $r - value corresponding to openssl's EVP_PKEY structure
6886 #
6887 # returns: 0 - verify failure, 1 - verify OK, <0 - error
6888 · P_X509_CRL_add_revoked_serial_hex
6890 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6892 requires at least openssl-0.9.7
6893 Adds given serial number $serial_hex to X509_CRL object $crl.
6895 Net::SSLeay::P_X509_CRL_add_revoked_serial_hex($crl, $serial_hex, $rev_time, $reason_code, $comp_time);
6897 # $crl - value corresponding to openssl's X509_CRL structure
6898 # $serial_hex - string (hexadecimal) representation of serial number
6899 # $rev_time - (revocation time) value corresponding to openssl's ASN1_TIME structure
6900 # $reason_code - [optional] (integer) reason code (see below) - default 0
6901 # $comp_time - [optional] (compromise time) value corresponding to openssl's ASN1_TIME structure
6902 #
6903 # returns: no return value
6904 reason codes:
6906 0 - unspecified
6907 1 - keyCompromise
6908 2 - CACompromise
6909 3 - affiliationChanged
6910 4 - superseded
6911 5 - cessationOfOperation
6912 6 - certificateHold
6913 7 - removeFromCRL
6914 · P_X509_CRL_get_serial
6916 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6918 requires at least openssl-0.9.7
6919 Returns serial number of X509_CRL object.
6921 my $rv = Net::SSLeay::P_X509_CRL_get_serial($crl);
6923 # $crl - value corresponding to openssl's X509_CRL structure
6924 #
6925 # returns: value corresponding to openssl's ASN1_INTEGER structure (0 on failure)
6926 · P_X509_CRL_set_serial
6928 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
6930 requires at least openssl-0.9.7
6931 Sets serial number of X509_CRL object to $crl_number.
6933 my $rv = Net::SSLeay::P_X509_CRL_set_serial($crl, $crl_number);
6935 # $crl - value corresponding to openssl's X509_CRL structure
6936 # $crl_number - value corresponding to openssl's ASN1_INTEGER structure
6937 #
6938 # returns: 1 on success, 0 on failure
6939 Low level API: X509_EXTENSION_* related functions
6941 · X509_EXTENSION_get_critical
6943 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6945 Returns 'critical' flag of given X509_EXTENSION object $ex.
6947 my $rv = Net::SSLeay::X509_EXTENSION_get_critical($ex);
6949 # $ex - value corresponding to openssl's X509_EXTENSION structure
6950 #
6951 # returns: (integer) 1 - critical, 0 - noncritical
6952 · X509_EXTENSION_get_data
6954 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6956 Returns value (raw data) of X509_EXTENSION object $ne.
6958 my $rv = Net::SSLeay::X509_EXTENSION_get_data($ne);
6960 # $ne - value corresponding to openssl's X509_EXTENSION structure
6961 #
6962 # returns: value corresponding to openssl's ASN1_OCTET_STRING structure (0 on failure)
6963 Note: you can use "P_ASN1_STRING_get" to convert ASN1_OCTET_STRING
6965 into perl scalar variable.
6966 · X509_EXTENSION_get_object
6968 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6970 Returns OID (ASN1_OBJECT) of X509_EXTENSION object $ne.
6972 my $rv = Net::SSLeay::X509_EXTENSION_get_object($ex);
6974 # $ex - value corresponding to openssl's X509_EXTENSION structure
6975 #
6976 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
6977 · X509V3_EXT_print
6979 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
6981 Returns string representation of given X509_EXTENSION object $ext.
6983 Net::SSLeay::X509V3_EXT_print($ext, $flags, $utf8_decode);
6985 # $ext - value corresponding to openssl's X509_EXTENSION structure
6986 # $flags - [optional] (integer) Currently the flag argument is unused and should be set to 0
6987 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
6988 #
6989 # returns: no return value
6990 · X509V3_EXT_d2i
6992 Parses an extension and returns its internal structure.
6994 my $rv = Net::SSLeay::X509V3_EXT_d2i($ext);
6996 # $ext - value corresponding to openssl's X509_EXTENSION structure
6997 #
6998 # returns: pointer ???
6999 Low level API: X509_NAME_* related functions
7001 · X509_NAME_ENTRY_get_data
7003 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7005 Retrieves the field value of $ne in and ASN1_STRING structure.
7007 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_data($ne);
7009 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7010 #
7011 # returns: value corresponding to openssl's ASN1_STRING structure (0 on failure)
7012 Check openssl doc
7014 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7015 · X509_NAME_ENTRY_get_object
7017 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7019 Retrieves the field name of $ne in and ASN1_OBJECT structure.
7021 my $rv = Net::SSLeay::X509_NAME_ENTRY_get_object($ne);
7023 # $ne - value corresponding to openssl's X509_NAME_ENTRY structure
7024 #
7025 # returns: value corresponding to openssl's ASN1_OBJECT structure (0 on failure)
7026 Check openssl doc
7028 <http://www.openssl.org/docs/crypto/X509_NAME_ENTRY_get_object.html>
7029 · X509_NAME_new
7031 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7033 requires at least openssl-0.9.5
7034 Creates a new X509_NAME structure. Adds a field whose name is
7036 defined by a string $field. The field value to be added is in
7037 $bytes.
7038 my $rv = Net::SSLeay::X509_NAME_new();
7040 #
7041 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7042 · X509_NAME_hash
7044 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
7046 requires at least openssl-0.9.5
7047 Sort of a checksum of issuer name $name. The result is not a full
7049 hash (e.g. sha-1), it is kind-of-a-hash truncated to the size of
7050 'unsigned long' (32 bits). The resulting value might differ across
7051 different openssl versions for the same X509 certificate.
7052 my $rv = Net::SSLeay::X509_NAME_hash($name);
7054 # $name - value corresponding to openssl's X509_NAME structure
7055 #
7056 # returns: number representing checksum
7057 · X509_NAME_add_entry_by_txt
7059 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7061 requires at least openssl-0.9.5
7062 Adds a field whose name is defined by a string $field. The field
7064 value to be added is in $bytes.
7065 my $rv = Net::SSLeay::X509_NAME_add_entry_by_txt($name, $field, $type, $bytes, $len, $loc, $set);
7067 # $name - value corresponding to openssl's X509_NAME structure
7068 # $field - (string) field definition (name) - e.g. "organizationName"
7069 # $type - (integer) type of data in $bytes (see below)
7070 # $bytes - data to be set
7071 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7072 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7073 #
7074 # returns: 1 on success, 0 on failure
7075 # values for $type - use constants:
7077 &Net::SSLeay::MBSTRING_UTF8 - $bytes contains utf8 encoded data
7078 &Net::SSLeay::MBSTRING_ASC - $bytes contains ASCII data
7079 Unicode note: when passing non-ascii (unicode) string in $bytes do
7081 not forget to set "$flags = &Net::SSLeay::MBSTRING_UTF8" and encode
7082 the perl $string via "$bytes = encode('utf-8', $string)".
7083 Check openssl doc
7085 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7086 · X509_NAME_add_entry_by_NID
7088 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7090 requires at least openssl-0.9.5
7091 Adds a field whose name is defined by a NID $nid. The field value
7093 to be added is in $bytes.
7094 my $rv = Net::SSLeay::X509_NAME_add_entry_by_NID($name, $nid, $type, $bytes, $len, $loc, $set);
7096 # $name - value corresponding to openssl's X509_NAME structure
7097 # $nid - (integer) field definition - NID value
7098 # $type - (integer) type of data in $bytes (see below)
7099 # $bytes - data to be set
7100 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7101 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7102 #
7103 # returns: 1 on success, 0 on failure
7104 Check openssl doc
7106 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7107 · X509_NAME_add_entry_by_OBJ
7109 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
7111 requires at least openssl-0.9.5
7112 Adds a field whose name is defined by a object (OID) $obj . The
7114 field value to be added is in $bytes.
7115 my $rv = Net::SSLeay::X509_NAME_add_entry_by_OBJ($name, $obj, $type, $bytes, $len, $loc, $set);
7117 # $name - value corresponding to openssl's X509_NAME structure
7118 # $obj - field definition - value corresponding to openssl's ASN1_OBJECT structure
7119 # $type - (integer) type of data in $bytes (see below)
7120 # $bytes - data to be set
7121 # $loc - [optional] (integer) index where the new entry is inserted: if it is -1 (default) it is appended
7122 # $set - [optional] (integer) determines how the new type is added. If it is 0 (default) a new RDN is created
7123 #
7124 # returns: 1 on success, 0 on failure
7125 Check openssl doc
7127 <http://www.openssl.org/docs/crypto/X509_NAME_add_entry_by_txt.html>
7128 · X509_NAME_cmp
7130 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7132 Compares two X509_NAME obejcts.
7134 my $rv = Net::SSLeay::X509_NAME_cmp($a, $b);
7136 # $a - value corresponding to openssl's X509_NAME structure
7137 # $b - value corresponding to openssl's X509_NAME structure
7138 #
7139 # returns: 0 if $a matches $b; non zero otherwise
7140 · X509_NAME_digest
7142 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7144 Computes digest/fingerprint of X509_NAME $data using $type hash
7146 function.
7147 my $digest_value = Net::SSLeay::X509_NAME_digest($data, $type);
7149 # $data - value corresponding to openssl's X509_NAME structure
7150 # $type - value corresponding to openssl's EVP_MD structure - e.g. got via EVP_get_digestbyname()
7151 #
7152 # returns: hash value (binary)
7153 #to get printable (hex) value of digest use:
7155 print unpack('H*', $digest_value);
7156 · X509_NAME_entry_count
7158 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7160 Returns the total number of entries in $name.
7162 my $rv = Net::SSLeay::X509_NAME_entry_count($name);
7164 # $name - value corresponding to openssl's X509_NAME structure
7165 #
7166 # returns: (integer) entries count
7167 Check openssl doc
7169 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7170 · X509_NAME_get_entry
7172 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7174 Retrieves the X509_NAME_ENTRY from $name corresponding to index
7176 $loc. Acceptable values for $loc run from 0 to
7177 "Net::SSLeay::X509_NAME_entry_count($name)- 1". The value returned
7178 is an internal pointer which must not be freed.
7179 my $rv = Net::SSLeay::X509_NAME_get_entry($name, $loc);
7181 # $name - value corresponding to openssl's X509_NAME structure
7182 # $loc - (integer) index of wanted entry
7183 #
7184 # returns: value corresponding to openssl's X509_NAME_ENTRY structure (0 on failure)
7185 Check openssl doc
7187 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7188 · X509_NAME_print_ex
7190 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7192 Returns a string with human readable version of $name.
7194 Net::SSLeay::X509_NAME_print_ex($name, $flags, $utf8_decode);
7196 # $name - value corresponding to openssl's X509_NAME structure
7197 # $flags - [optional] conversion flags (default XN_FLAG_RFC2253) - see below
7198 # $utf8_decode - [optional] 0 or 1 whether the returned value should be utf8 decoded (default=0)
7199 #
7200 # returns: string representation of $name
7201 #available conversion flags - use constants:
7203 &Net::SSLeay::XN_FLAG_COMPAT
7204 &Net::SSLeay::XN_FLAG_DN_REV
7205 &Net::SSLeay::XN_FLAG_DUMP_UNKNOWN_FIELDS
7206 &Net::SSLeay::XN_FLAG_FN_ALIGN
7207 &Net::SSLeay::XN_FLAG_FN_LN
7208 &Net::SSLeay::XN_FLAG_FN_MASK
7209 &Net::SSLeay::XN_FLAG_FN_NONE
7210 &Net::SSLeay::XN_FLAG_FN_OID
7211 &Net::SSLeay::XN_FLAG_FN_SN
7212 &Net::SSLeay::XN_FLAG_MULTILINE
7213 &Net::SSLeay::XN_FLAG_ONELINE
7214 &Net::SSLeay::XN_FLAG_RFC2253
7215 &Net::SSLeay::XN_FLAG_SEP_COMMA_PLUS
7216 &Net::SSLeay::XN_FLAG_SEP_CPLUS_SPC
7217 &Net::SSLeay::XN_FLAG_SEP_MASK
7218 &Net::SSLeay::XN_FLAG_SEP_MULTILINE
7219 &Net::SSLeay::XN_FLAG_SEP_SPLUS_SPC
7220 &Net::SSLeay::XN_FLAG_SPC_EQ
7221 Most likely you will be fine with default:
7223 Net::SSLeay::X509_NAME_print_ex($name, &Net::SSLeay::XN_FLAG_RFC2253);
7225 Or you might want RFC2253-like output without utf8 chars escaping:
7227 use Net::SSLeay qw/XN_FLAG_RFC2253 ASN1_STRFLGS_ESC_MSB/;
7229 my $flag_rfc22536_utf8 = (XN_FLAG_RFC2253) & (~ ASN1_STRFLGS_ESC_MSB);
7230 my $result = Net::SSLeay::X509_NAME_print_ex($name, $flag_rfc22536_utf8, 1);
7231 Check openssl doc
7233 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7234 · X509_NAME_get_text_by_NID
7236 Retrieves the text from the first entry in name which matches $nid,
7238 if no such entry exists -1 is returned.
7239 openssl note: this is a legacy function which has various
7241 limitations which makes it of minimal use in practice. It can only
7242 find the first matching entry and will copy the contents of the
7243 field verbatim: this can be highly confusing if the target is a
7244 multicharacter string type like a BMPString or a UTF8String.
7245 Net::SSLeay::X509_NAME_get_text_by_NID($name, $nid);
7247 # $name - value corresponding to openssl's X509_NAME structure
7248 # $nid - NID value (integer)
7249 #
7250 # returns: text value
7251 Check openssl doc
7253 <http://www.openssl.org/docs/crypto/X509_NAME_get_index_by_NID.html>
7254 · X509_NAME_oneline
7256 Return an ASCII version of $name.
7258 Net::SSLeay::X509_NAME_oneline($name);
7260 # $name - value corresponding to openssl's X509_NAME structure
7261 #
7262 # returns: (string) ASCII version of $name
7263 Check openssl doc
7265 <http://www.openssl.org/docs/crypto/X509_NAME_print_ex.html>
7266 · sk_X509_NAME_free
7268 Free an allocated STACK_OF(X509_NAME) structure.
7270 Net::SSLeay::sk_X509_NAME_free($sk);
7272 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7273 #
7274 # returns: no return value
7275 · sk_X509_NAME_num
7277 Return number of items in STACK_OF(X509_NAME)
7279 my $rv = Net::SSLeay::sk_X509_NAME_num($sk);
7281 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7282 #
7283 # returns: number of items
7284 · sk_X509_NAME_value
7286 Returns X509_NAME from position $index in STACK_OF(X509_NAME)
7288 my $rv = Net::SSLeay::sk_X509_NAME_value($sk, $i);
7290 # $sk - value corresponding to openssl's STACK_OF(X509_NAME) structure
7291 # $i - (integer) index/position
7292 #
7293 # returns: value corresponding to openssl's X509_NAME structure (0 on failure)
7294 · add_file_cert_subjects_to_stack
7296 Add a file of certs to a stack. All certs in $file that are not
7298 already in the $stackCAs will be added.
7299 my $rv = Net::SSLeay::add_file_cert_subjects_to_stack($stackCAs, $file);
7301 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7302 # $file - (string) filename
7303 #
7304 # returns: 1 on success, 0 on failure
7305 · add_dir_cert_subjects_to_stack
7307 Add a directory of certs to a stack. All certs in $dir that are not
7309 already in the $stackCAs will be added.
7310 my $rv = Net::SSLeay::add_dir_cert_subjects_to_stack($stackCAs, $dir);
7312 # $stackCAs - value corresponding to openssl's STACK_OF(X509_NAME) structure
7313 # $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.
7314 #
7315 # returns: 1 on success, 0 on failure
7316 Low level API: X509_STORE_* related functions
7318 · X509_STORE_CTX_new
7320 returns a newly initialised X509_STORE_CTX structure.
7322 · X509_verify_cert
7324 The X509_verify_cert() function attempts to discover and validate a
7326 certificate chain based on parameters in ctx. A complete
7327 description of the process is contained in the verify(1) manual
7328 page.
7329 · X509_STORE_CTX_get_current_cert
7331 Returns the certificate in ctx which caused the error or 0 if no
7333 certificate is relevant.
7334 my $rv = Net::SSLeay::X509_STORE_CTX_get_current_cert($x509_store_ctx);
7336 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7337 #
7338 # returns: value corresponding to openssl's X509 structure (0 on failure)
7339 Check openssl doc
7341 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7342 · X509_STORE_CTX_get_error
7344 Returns the error code of $ctx.
7346 my $rv = Net::SSLeay::X509_STORE_CTX_get_error($x509_store_ctx);
7348 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7349 #
7350 # returns: (integer) error code
7351 For more info about erro code values check function
7353 "get_verify_result".
7354 Check openssl doc
7356 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7357 · X509_STORE_CTX_get_error_depth
7359 Returns the depth of the error. This is a non-negative integer
7361 representing where in the certificate chain the error occurred. If
7362 it is zero it occurred in the end entity certificate, one if it is
7363 the certificate which signed the end entity certificate and so on.
7364 my $rv = Net::SSLeay::X509_STORE_CTX_get_error_depth($x509_store_ctx);
7366 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7367 #
7368 # returns: (integer) depth
7369 Check openssl doc
7371 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7372 · X509_STORE_CTX_get_ex_data
7374 Is used to retrieve the information for $idx from $x509_store_ctx.
7376 my $rv = Net::SSLeay::X509_STORE_CTX_get_ex_data($x509_store_ctx, $idx);
7378 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7379 # $idx - (integer) index for application specific data
7380 #
7381 # returns: pointer to ???
7382 · X509_STORE_CTX_set_ex_data
7384 Is used to store application data at arg for idx into
7386 $x509_store_ctx.
7387 my $rv = Net::SSLeay::X509_STORE_CTX_set_ex_data($x509_store_ctx, $idx, $data);
7389 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7390 # $idx - (integer) ???
7391 # $data - (pointer) ???
7392 #
7393 # returns: 1 on success, 0 on failure
7394 · X509_STORE_CTX_set_cert
7396 Sets the certificate to be verified in $x509_store_ctx to $x.
7398 Net::SSLeay::X509_STORE_CTX_set_cert($x509_store_ctx, $x);
7400 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7401 # $x - value corresponding to openssl's X509 structure
7402 #
7403 # returns: no return value
7404 Check openssl doc
7406 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_new.html>
7407 · X509_STORE_CTX_set_error
7409 Sets the error code of $ctx to $s. For example it might be used in
7411 a verification callback to set an error based on additional checks.
7412 Net::SSLeay::X509_STORE_CTX_set_error($x509_store_ctx, $s);
7414 # $x509_store_ctx - value corresponding to openssl's X509_STORE_CTX structure
7415 # $s - (integer) error id
7416 #
7417 # returns: no return value
7418 Check openssl doc
7420 <http://www.openssl.org/docs/crypto/X509_STORE_CTX_get_error.html>
7421 · X509_STORE_add_cert
7423 Adds X509 certificate $x into the X509_STORE $store.
7425 my $rv = Net::SSLeay::X509_STORE_add_cert($store, $x);
7427 # $store - value corresponding to openssl's X509_STORE structure
7428 # $x - value corresponding to openssl's X509 structure
7429 #
7430 # returns: 1 on success, 0 on failure
7431 · X509_STORE_add_crl
7433 Adds X509 CRL $x into the X509_STORE $store.
7435 my $rv = Net::SSLeay::X509_STORE_add_crl($store, $x);
7437 # $store - value corresponding to openssl's X509_STORE structure
7438 # $x - value corresponding to openssl's X509_CRL structure
7439 #
7440 # returns: 1 on success, 0 on failure
7441 · X509_STORE_set1_param
7443 ??? (more info needed)
7445 my $rv = Net::SSLeay::X509_STORE_set1_param($store, $pm);
7447 # $store - value corresponding to openssl's X509_STORE structure
7448 # $pm - value corresponding to openssl's X509_VERIFY_PARAM structure
7449 #
7450 # returns: 1 on success, 0 on failure
7451 · X509_STORE_set_flags
7453 Net::SSLeay::X509_STORE_set_flags($ctx, $flags);
7455 # $ctx - value corresponding to openssl's X509_STORE structure
7456 # $flags - (unsigned long) flags to be set (bitmask)
7457 #
7458 # returns: no return value
7459 #to create $flags value use corresponding constants like
7461 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
7462 For more details about $flags bitmask see
7464 "X509_VERIFY_PARAM_set_flags".
7465 · X509_STORE_set_purpose
7467 Net::SSLeay::X509_STORE_set_purpose($ctx, $purpose);
7469 # $ctx - value corresponding to openssl's X509_STORE structure
7470 # $purpose - (integer) purpose identifier
7471 #
7472 # returns: no return value
7473 For more details about $purpose identifier check "CTX_set_purpose".
7475 · X509_STORE_set_trust
7477 Net::SSLeay::X509_STORE_set_trust($ctx, $trust);
7479 # $ctx - value corresponding to openssl's X509_STORE structure
7480 # $trust - (integer) trust identifier
7481 #
7482 # returns: no return value
7483 For more details about $trust identifier check "CTX_set_trust".
7485 Low level API: X509_VERIFY_PARAM_* related functions
7487 · X509_VERIFY_PARAM_add0_policy
7489 Enables policy checking (it is disabled by default) and adds
7491 $policy to the acceptable policy set.
7492 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_policy($param, $policy);
7494 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7495 # $policy - value corresponding to openssl's ASN1_OBJECT structure
7496 #
7497 # returns: 1 on success, 0 on failure
7498 Check openssl doc
7500 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7501 · X509_VERIFY_PARAM_add0_table
7503 ??? (more info needed)
7505 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add0_table($param);
7507 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7508 #
7509 # returns: 1 on success, 0 on failure
7510 · X509_VERIFY_PARAM_add1_host
7512 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7514 requires at least OpenSSL 1.0.2
7515 Adds an additional reference identifier that can match the peer's
7517 certificate.
7518 my $rv = Net::SSLeay::X509_VERIFY_PARAM_add1_host($param, $name);
7520 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7521 # $name - (string) name to be set
7522 #
7523 # returns: 1 on success, 0 on failure
7524 See also OpenSSL docs, "X509_VERIFY_PARAM_set1_host" and
7526 "X509_VERIFY_PARAM_set_hostflags" for more information, including
7527 wildcard matching.
7528 Check openssl doc
7530 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7531 · X509_VERIFY_PARAM_clear_flags
7533 Clears the flags $flags in param.
7535 my $rv = Net::SSLeay::X509_VERIFY_PARAM_clear_flags($param, $flags);
7537 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7538 # $flags - (unsigned long) flags to be set (bitmask)
7539 #
7540 # returns: 1 on success, 0 on failure
7541 For more details about $flags bitmask see
7543 "X509_VERIFY_PARAM_set_flags".
7544 Check openssl doc
7546 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7547 · X509_VERIFY_PARAM_free
7549 Frees up the X509_VERIFY_PARAM structure.
7551 Net::SSLeay::X509_VERIFY_PARAM_free($param);
7553 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7554 #
7555 # returns: no return value
7556 · X509_VERIFY_PARAM_get0_peername
7558 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7560 requires at least OpenSSL 1.0.2
7561 Returns the DNS hostname or subject CommonName from the peer
7563 certificate that matched one of the reference identifiers.
7564 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get0_peername($param);
7566 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7567 #
7568 # returns: (string) name e.g. '*.example.com' or undef
7569 Check openssl doc
7571 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7572 · X509_VERIFY_PARAM_get_depth
7574 Returns the current verification depth.
7576 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_depth($param);
7578 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7579 #
7580 # returns: (ineger) depth
7581 Check openssl doc
7583 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7584 · X509_VERIFY_PARAM_get_flags
7586 Returns the current verification flags.
7588 my $rv = Net::SSLeay::X509_VERIFY_PARAM_get_flags($param);
7590 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7591 #
7592 # returns: (unsigned long) flags to be set (bitmask)
7593 For more details about returned flags bitmask see
7595 "X509_VERIFY_PARAM_set_flags".
7596 Check openssl doc
7598 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7599 · X509_VERIFY_PARAM_set_flags
7601 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_flags($param, $flags);
7603 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7604 # $flags - (unsigned long) flags to be set (bitmask)
7605 #
7606 # returns: 1 on success, 0 on failure
7607 #to create $flags value use corresponding constants like
7609 $flags = Net::SSLeay::X509_V_FLAG_CRL_CHECK();
7610 For more details about $flags bitmask, see the OpenSSL docs below.
7612 Check openssl doc
7614 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7615 · X509_VERIFY_PARAM_inherit
7617 ??? (more info needed)
7619 my $rv = Net::SSLeay::X509_VERIFY_PARAM_inherit($to, $from);
7621 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
7622 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
7623 #
7624 # returns: 1 on success, 0 on failure
7625 · X509_VERIFY_PARAM_lookup
7627 Finds X509_VERIFY_PARAM by name.
7629 my $rv = Net::SSLeay::X509_VERIFY_PARAM_lookup($name);
7631 # $name - (string) name we want to find
7632 #
7633 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
7634 · X509_VERIFY_PARAM_new
7636 Creates a new X509_VERIFY_PARAM structure.
7638 my $rv = Net::SSLeay::X509_VERIFY_PARAM_new();
7640 #
7641 # returns: value corresponding to openssl's X509_VERIFY_PARAM structure (0 on failure)
7642 · X509_VERIFY_PARAM_set1
7644 Sets the name of X509_VERIFY_PARAM structure $to to the same value
7646 as the name of X509_VERIFY_PARAM structure $from.
7647 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1($to, $from);
7649 # $to - value corresponding to openssl's X509_VERIFY_PARAM structure
7650 # $from - value corresponding to openssl's X509_VERIFY_PARAM structure
7651 #
7652 # returns: 1 on success, 0 on failure
7653 · X509_VERIFY_PARAM_set1_email
7655 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7657 requires at least OpenSSL 1.0.2
7658 Sets the expected RFC822 email address to email.
7660 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_email($param, $email);
7662 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7663 # $email - (string) email to be set
7664 #
7665 # returns: 1 on success, 0 on failure
7666 Check openssl doc
7668 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7669 · X509_VERIFY_PARAM_set1_host
7671 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7673 requires at least OpenSSL 1.0.2
7674 Sets the expected DNS hostname to name clearing any previously
7676 specified host name or names.
7677 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_host($param, $name);
7679 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7680 # $name - (string) name to be set
7681 #
7682 # returns: 1 on success, 0 on failure
7683 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
7685 "X509_VERIFY_PARAM_set_hostflags" for more information, including
7686 wildcard matching.
7687 Check openssl doc
7689 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7690 · X509_VERIFY_PARAM_set1_ip
7692 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7694 requires at least OpenSSL 1.0.2
7695 Sets the expected IP address to ip.
7697 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_ip($param, $ip);
7699 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7700 # $ip - (binary) 4 octet IPv4 or 16 octet IPv6 address
7701 #
7702 # returns: 1 on success, 0 on failure
7703 Check openssl doc
7705 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7706 · X509_VERIFY_PARAM_set1_ip_asc
7708 COMPATIBILITY: not available in Net-SSLeay-1.82 and before;
7710 requires at least OpenSSL 1.0.2
7711 Sets the expected IP address to ipasc.
7713 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_asc($param, $ipasc);
7715 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7716 # $ip - (string) IPv4 or IPv6 address
7717 #
7718 # returns: 1 on success, 0 on failure
7719 Check openssl doc
7721 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7722 · X509_VERIFY_PARAM_set1_name
7724 Sets the name of X509_VERIFY_PARAM structure $param to $name.
7726 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_name($param, $name);
7728 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7729 # $name - (string) name to be set
7730 #
7731 # returns: 1 on success, 0 on failure
7732 · X509_VERIFY_PARAM_set1_policies
7734 Enables policy checking (it is disabled by default) and sets the
7736 acceptable policy set to policies. Any existing policy set is
7737 cleared. The policies parameter can be 0 to clear an existing
7738 policy set.
7739 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set1_policies($param, $policies);
7741 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7742 # $policies - value corresponding to openssl's STACK_OF(ASN1_OBJECT) structure
7743 #
7744 # returns: 1 on success, 0 on failure
7745 Check openssl doc
7747 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7748 · X509_VERIFY_PARAM_set_depth
7750 Sets the maximum verification depth to depth. That is the maximum
7752 number of untrusted CA certificates that can appear in a chain.
7753 Net::SSLeay::X509_VERIFY_PARAM_set_depth($param, $depth);
7755 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7756 # $depth - (integer) depth to be set
7757 #
7758 # returns: no return value
7759 Check openssl doc
7761 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7762 · X509_VERIFY_PARAM_set_hostflags
7764 Net::SSLeay::X509_VERIFY_PARAM_set_hostflags($param, $flags);
7766 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7767 # $flags - (unsigned int) flags to be set (bitmask)
7768 #
7769 # returns: no return value
7770 See also OpenSSL docs, "X509_VERIFY_PARAM_add1_host" and
7772 "X509_VERIFY_PARAM_set1_host" for more information. The flags for
7773 controlling wildcard checks and other features are defined in
7774 OpenSSL docs.
7775 Check openssl doc
7777 <https://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7778 · X509_VERIFY_PARAM_set_purpose
7780 Sets the verification purpose in $param to $purpose. This
7782 determines the acceptable purpose of the certificate chain, for
7783 example SSL client or SSL server.
7784 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_purpose($param, $purpose);
7786 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7787 # $purpose - (integer) purpose identifier
7788 #
7789 # returns: 1 on success, 0 on failure
7790 For more details about $purpose identifier check "CTX_set_purpose".
7792 Check openssl doc
7794 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7795 · X509_VERIFY_PARAM_set_time
7797 Sets the verification time in $param to $t. Normally the current
7799 time is used.
7800 Net::SSLeay::X509_VERIFY_PARAM_set_time($param, $t);
7802 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7803 # $t - (time_t) time in seconds since 1.1.1970
7804 #
7805 # returns: no return value
7806 Check openssl doc
7808 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7809 · X509_VERIFY_PARAM_set_trust
7811 Sets the trust setting in $param to $trust.
7813 my $rv = Net::SSLeay::X509_VERIFY_PARAM_set_trust($param, $trust);
7815 # $param - value corresponding to openssl's X509_VERIFY_PARAM structure
7816 # $trust - (integer) trust identifier
7817 #
7818 # returns: 1 on success, 0 on failure
7819 For more details about $trust identifier check "CTX_set_trust".
7821 Check openssl doc
7823 <http://www.openssl.org/docs/crypto/X509_VERIFY_PARAM_set_flags.html>
7824 · X509_VERIFY_PARAM_table_cleanup
7826 ??? (more info needed)
7828 Net::SSLeay::X509_VERIFY_PARAM_table_cleanup();
7830 #
7831 # returns: no return value
7832 Low level API: Cipher (EVP_CIPHER_*) related functions
7834 · EVP_get_cipherbyname
7836 COMPATIBILITY: not available in Net-SSLeay-1.45 and before
7838 Returns an EVP_CIPHER structure when passed a cipher name.
7840 my $rv = Net::SSLeay::EVP_get_cipherbyname($name);
7842 # $name - (string) cipher name e.g. 'aes-128-cbc', 'camellia-256-ecb', 'des-ede', ...
7843 #
7844 # returns: value corresponding to openssl's EVP_CIPHER structure
7845 Check openssl doc
7847 <http://www.openssl.org/docs/crypto/EVP_EncryptInit.html>
7848 Low level API: Digest (EVP_MD_*) related functions
7850 · OpenSSL_add_all_digests
7852 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7854 Net::SSLeay::OpenSSL_add_all_digests();
7856 # no args, no return value
7857 http://www.openssl.org/docs/crypto/OpenSSL_add_all_algorithms.html
7859 · P_EVP_MD_list_all
7861 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7863 requires at least openssl-1.0.0
7864 NOTE: Does not exactly correspond to any low level API function
7866 my $rv = Net::SSLeay::P_EVP_MD_list_all();
7868 #
7869 # returns: arrayref - list of available digest names
7870 The returned digest names correspond to values expected by
7872 "EVP_get_digestbyname".
7873 Note that some of the digests are available by default and some
7875 only after calling "OpenSSL_add_all_digests".
7876 · EVP_get_digestbyname
7878 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7880 my $rv = Net::SSLeay::EVP_get_digestbyname($name);
7882 # $name - string with digest name
7883 #
7884 # returns: value corresponding to openssl's EVP_MD structure
7885 The $name param can be:
7887 md2
7889 md4
7890 md5
7891 mdc2
7892 ripemd160
7893 sha
7894 sha1
7895 sha224
7896 sha256
7897 sha512
7898 whirlpool
7899 Or better check the supported digests by calling
7901 "P_EVP_MD_list_all".
7902 · EVP_MD_type
7904 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7906 my $rv = Net::SSLeay::EVP_MD_type($md);
7908 # $md - value corresponding to openssl's EVP_MD structure
7909 #
7910 # returns: the NID (integer) of the OBJECT IDENTIFIER representing the given message digest
7911 · EVP_MD_size
7913 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
7915 my $rv = Net::SSLeay::EVP_MD_size($md);
7917 # $md - value corresponding to openssl's EVP_MD structure
7918 #
7919 # returns: the size of the message digest in bytes (e.g. 20 for SHA1)
7920 · EVP_MD_CTX_md
7922 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7924 requires at least openssl-0.9.7
7925 Net::SSLeay::EVP_MD_CTX_md($ctx);
7927 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7928 #
7929 # returns: value corresponding to openssl's EVP_MD structure
7930 · EVP_MD_CTX_create
7932 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7934 requires at least openssl-0.9.7
7935 Allocates, initializes and returns a digest context.
7937 my $rv = Net::SSLeay::EVP_MD_CTX_create();
7939 #
7940 # returns: value corresponding to openssl's EVP_MD_CTX structure
7941 The complete idea behind EVP_MD_CTX looks like this example:
7943 Net::SSLeay::OpenSSL_add_all_digests();
7945 my $md = Net::SSLeay::EVP_get_digestbyname("sha1");
7947 my $ctx = Net::SSLeay::EVP_MD_CTX_create();
7948 Net::SSLeay::EVP_DigestInit($ctx, $md);
7949 while(my $chunk = get_piece_of_data()) {
7951 Net::SSLeay::EVP_DigestUpdate($ctx,$chunk);
7952 }
7953 my $result = Net::SSLeay::EVP_DigestFinal($ctx);
7955 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
7956 print "digest=", unpack('H*', $result), "\n"; #print hex value
7958 · EVP_DigestInit_ex
7960 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7962 requires at least openssl-0.9.7
7963 Sets up digest context $ctx to use a digest $type from ENGINE
7965 $impl, $ctx must be initialized before calling this function, type
7966 will typically be supplied by a function such as
7967 "EVP_get_digestbyname". If $impl is 0 then the default
7968 implementation of digest $type is used.
7969 my $rv = Net::SSLeay::EVP_DigestInit_ex($ctx, $type, $impl);
7971 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7972 # $type - value corresponding to openssl's EVP_MD structure
7973 # $impl - value corresponding to openssl's ENGINE structure
7974 #
7975 # returns: 1 for success and 0 for failure
7976 · EVP_DigestInit
7978 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7980 requires at least openssl-0.9.7
7981 Behaves in the same way as "EVP_DigestInit_ex" except the passed
7983 context $ctx does not have to be initialized, and it always uses
7984 the default digest implementation.
7985 my $rv = Net::SSLeay::EVP_DigestInit($ctx, $type);
7987 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
7988 # $type - value corresponding to openssl's EVP_MD structure
7989 #
7990 # returns: 1 for success and 0 for failure
7991 · EVP_MD_CTX_destroy
7993 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
7995 requires at least openssl-0.9.7
7996 Cleans up digest context $ctx and frees up the space allocated to
7998 it, it should be called only on a context created using
7999 "EVP_MD_CTX_create".
8000 Net::SSLeay::EVP_MD_CTX_destroy($ctx);
8002 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8003 #
8004 # returns: no return value
8005 · EVP_DigestUpdate
8007 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8009 requires at least openssl-0.9.7
8010 my $rv = Net::SSLeay::EVP_DigestUpdate($ctx, $data);
8012 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8013 # $data - data to be hashed
8014 #
8015 # returns: 1 for success and 0 for failure
8016 · EVP_DigestFinal_ex
8018 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8020 requires at least openssl-0.9.7
8021 Retrieves the digest value from $ctx. After calling
8023 "EVP_DigestFinal_ex" no additional calls to "EVP_DigestUpdate" can
8024 be made, but "EVP_DigestInit_ex" can be called to initialize a new
8025 digest operation.
8026 my $digest_value = Net::SSLeay::EVP_DigestFinal_ex($ctx);
8028 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8029 #
8030 # returns: hash value (binary)
8031 #to get printable (hex) value of digest use:
8033 print unpack('H*', $digest_value);
8034 · EVP_DigestFinal
8036 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8038 requires at least openssl-0.9.7
8039 Similar to "EVP_DigestFinal_ex" except the digest context ctx is
8041 automatically cleaned up.
8042 my $rv = Net::SSLeay::EVP_DigestFinal($ctx);
8044 # $ctx - value corresponding to openssl's EVP_MD_CTX structure
8045 #
8046 # returns: hash value (binary)
8047 #to get printable (hex) value of digest use:
8049 print unpack('H*', $digest_value);
8050 · MD2
8052 COMPATIBILITY: no supported by default in openssl-1.0.0
8054 Computes MD2 from given $data (all data needs to be loaded into
8056 memory)
8057 my $digest = Net::SSLeay::MD2($data);
8059 print "digest(hexadecimal)=", unpack('H*', $digest);
8060 · MD4
8062 Computes MD4 from given $data (all data needs to be loaded into
8064 memory)
8065 my $digest = Net::SSLeay::MD4($data);
8067 print "digest(hexadecimal)=", unpack('H*', $digest);
8068 · MD5
8070 Computes MD5 from given $data (all data needs to be loaded into
8072 memory)
8073 my $digest = Net::SSLeay::MD5($data);
8075 print "digest(hexadecimal)=", unpack('H*', $digest);
8076 · RIPEMD160
8078 Computes RIPEMD160 from given $data (all data needs to be loaded
8080 into memory)
8081 my $digest = Net::SSLeay::RIPEMD160($data);
8083 print "digest(hexadecimal)=", unpack('H*', $digest);
8084 · SHA1
8086 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8088 Computes SHA1 from given $data (all data needs to be loaded into
8090 memory)
8091 my $digest = Net::SSLeay::SHA1($data);
8093 print "digest(hexadecimal)=", unpack('H*', $digest);
8094 · SHA256
8096 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8098 requires at least openssl-0.9.8
8099 Computes SHA256 from given $data (all data needs to be loaded into
8101 memory)
8102 my $digest = Net::SSLeay::SHA256($data);
8104 print "digest(hexadecimal)=", unpack('H*', $digest);
8105 · SHA512
8107 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8109 requires at least openssl-0.9.8
8110 Computes SHA512 from given $data (all data needs to be loaded into
8112 memory)
8113 my $digest = Net::SSLeay::SHA512($data);
8115 print "digest(hexadecimal)=", unpack('H*', $digest);
8116 · EVP_Digest
8118 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8120 requires at least openssl-0.9.7
8121 Computes "any" digest from given $data (all data needs to be loaded
8123 into memory)
8124 my $md = Net::SSLeay::EVP_get_digestbyname("sha1"); #or any other algorithm
8126 my $digest = Net::SSLeay::EVP_Digest($data, $md);
8127 print "digest(hexadecimal)=", unpack('H*', $digest);
8128 · EVP_sha1
8130 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8132 my $md = Net::SSLeay::EVP_sha1();
8134 #
8135 # returns: value corresponding to openssl's EVP_MD structure
8136 · EVP_sha256
8138 COMPATIBILITY: requires at least openssl-0.9.8
8140 my $md = Net::SSLeay::EVP_sha256();
8142 #
8143 # returns: value corresponding to openssl's EVP_MD structure
8144 · EVP_sha512
8146 COMPATIBILITY: not available in Net-SSLeay-1.42 and before;
8148 requires at least openssl-0.9.8
8149 my $md = Net::SSLeay::EVP_sha512();
8151 #
8152 # returns: value corresponding to openssl's EVP_MD structure
8153 · EVP_add_digest
8155 my $rv = Net::SSLeay::EVP_add_digest($digest);
8157 # $digest - value corresponding to openssl's EVP_MD structure
8158 #
8159 # returns: 1 on success, 0 otherwise
8160 Low level API: CIPHER_* related functions
8162 · CIPHER_get_name
8164 COMPATIBILITY: not available in Net-SSLeay-1.42 and before
8166 Returns name of the cipher used.
8168 my $rv = Net::SSLeay::CIPHER_description($cipher);
8170 # $cipher - value corresponding to openssl's SSL_CIPHER structure
8171 #
8172 # returns: (string) cipher name e.g. 'DHE-RSA-AES256-SHA'
8173 Check openssl doc
8175 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8176 Example:
8178 my $ssl_cipher = Net::SSLeay::get_current_cipher($ssl);
8180 my $cipher_name = Net::SSLeay::CIPHER_get_name($ssl_cipher);
8181 · CIPHER_description
8183 Returns a textual description of the cipher used.
8185 ??? (does this function really work?)
8187 my $rv = Net::SSLeay::CIPHER_description($cipher, $buf, $size);
8189 # $cipher - value corresponding to openssl's SSL_CIPHER structure
8190 # $bufer - (string/buffer) ???
8191 # $size - (integer) ???
8192 #
8193 # returns: (string) cipher description e.g. 'DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1'
8194 Check openssl doc
8196 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8197 · CIPHER_get_bits
8199 Returns the number of secret bits used for cipher.
8201 my $rv = Net::SSLeay::CIPHER_get_bits($c);
8203 # $c - value corresponding to openssl's SSL_CIPHER structure
8204 #
8205 # returns: (integert) number of secret bits, 0 on error
8206 Check openssl doc
8208 <http://www.openssl.org/docs/ssl/SSL_CIPHER_get_name.html>
8209 Low level API: RSA_* related functions
8211 · RSA_generate_key
8213 Generates a key pair and returns it in a newly allocated RSA
8215 structure. The pseudo-random number generator must be seeded prior
8216 to calling RSA_generate_key.
8217 my $rv = Net::SSLeay::RSA_generate_key($bits, $e, $perl_cb, $perl_cb_arg);
8219 # $bits - (integer) modulus size in bits e.g. 512, 1024, 2048
8220 # $e - (integer) public exponent, an odd number, typically 3, 17 or 65537
8221 # $perl_cb - [optional] reference to perl callback function
8222 # $perl_cb_arg - [optional] data that will be passed to callback function when invoked
8223 #
8224 # returns: value corresponding to openssl's RSA structure (0 on failure)
8225 Check openssl doc
8227 <http://www.openssl.org/docs/crypto/RSA_generate_key.html>
8228 · RSA_free
8230 Frees the RSA structure and its components. The key is erased
8232 before the memory is returned to the system.
8233 Net::SSLeay::RSA_free($r);
8235 # $r - value corresponding to openssl's RSA structure
8236 #
8237 # returns: no return value
8238 Check openssl doc <http://www.openssl.org/docs/crypto/RSA_new.html>
8240 · RSA_get_key_parameters
8242 Returns a list of pointers to BIGNUMs representing the parameters
8244 of the key in this order: (n, e, d, p, q, dmp1, dmq1, iqmp)
8245 Caution: returned list consists of SV pointers to BIGNUMs, which
8246 would need to be blessed as Crypt::OpenSSL::Bignum for further use
8247 my (@params) = RSA_get_key_parameters($r);
8249 Low level API: BIO_* related functions
8251 · BIO_eof
8253 Returns 1 if the BIO has read EOF, the precise meaning of 'EOF'
8255 varies according to the BIO type.
8256 my $rv = Net::SSLeay::BIO_eof($s);
8258 # $s - value corresponding to openssl's BIO structure
8259 #
8260 # returns: 1 if EOF has been reached 0 otherwise
8261 Check openssl doc
8263 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8264 · BIO_f_ssl
8266 Returns the SSL BIO method. This is a filter BIO which is a wrapper
8268 round the OpenSSL SSL routines adding a BIO 'flavour' to SSL I/O.
8269 my $rv = Net::SSLeay::BIO_f_ssl();
8271 #
8272 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8273 Check openssl doc
8275 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8276 · BIO_free
8278 Frees up a single BIO.
8280 my $rv = Net::SSLeay::BIO_free($bio;);
8282 # $bio; - value corresponding to openssl's BIO structure
8283 #
8284 # returns: 1 on success, 0 on failure
8285 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8287 · BIO_new
8289 Returns a new BIO using method $type
8291 my $rv = Net::SSLeay::BIO_new($type);
8293 # $type - value corresponding to openssl's BIO_METHOD structure
8294 #
8295 # returns: value corresponding to openssl's BIO structure (0 on failure)
8296 Check openssl doc <http://www.openssl.org/docs/crypto/BIO_new.html>
8298 · BIO_new_buffer_ssl_connect
8300 Creates a new BIO chain consisting of a buffering BIO, an SSL BIO
8302 (using ctx) and a connect BIO.
8303 my $rv = Net::SSLeay::BIO_new_buffer_ssl_connect($ctx);
8305 # $ctx - value corresponding to openssl's SSL_CTX structure
8306 #
8307 # returns: value corresponding to openssl's BIO structure (0 on failure)
8308 Check openssl doc
8310 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8311 · BIO_new_file
8313 Creates a new file BIO with mode $mode the meaning of mode is the
8315 same as the stdio function fopen(). The BIO_CLOSE flag is set on
8316 the returned BIO.
8317 my $rv = Net::SSLeay::BIO_new_file($filename, $mode);
8319 # $filename - (string) filename
8320 # $mode - (string) opening mode (as mode by stdio function fopen)
8321 #
8322 # returns: value corresponding to openssl's BIO structure (0 on failure)
8323 Check openssl doc
8325 <http://www.openssl.org/docs/crypto/BIO_s_file.html>
8326 · BIO_new_ssl
8328 Allocates an SSL BIO using SSL_CTX ctx and using client mode if
8330 client is non zero.
8331 my $rv = Net::SSLeay::BIO_new_ssl($ctx, $client);
8333 # $ctx - value corresponding to openssl's SSL_CTX structure
8334 # $client - (integer) 0 or 1 - indicates ssl client mode
8335 #
8336 # returns: value corresponding to openssl's BIO structure (0 on failure)
8337 Check openssl doc
8339 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8340 · BIO_new_ssl_connect
8342 Creates a new BIO chain consisting of an SSL BIO (using ctx)
8344 followed by a connect BIO.
8345 my $rv = Net::SSLeay::BIO_new_ssl_connect($ctx);
8347 # $ctx - value corresponding to openssl's SSL_CTX structure
8348 #
8349 # returns: value corresponding to openssl's BIO structure (0 on failure)
8350 Check openssl doc
8352 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8353 · BIO_pending
8355 Return the number of pending characters in the BIOs read buffers.
8357 my $rv = Net::SSLeay::BIO_pending($s);
8359 # $s - value corresponding to openssl's BIO structure
8360 #
8361 # returns: the amount of pending data
8362 Check openssl doc
8364 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8365 · BIO_wpending
8367 Return the number of pending characters in the BIOs write buffers.
8369 my $rv = Net::SSLeay::BIO_wpending($s);
8371 # $s - value corresponding to openssl's BIO structure
8372 #
8373 # returns: the amount of pending data
8374 Check openssl doc
8376 <http://www.openssl.org/docs/crypto/BIO_ctrl.html>
8377 · BIO_read
8379 Read the underlying descriptor.
8381 Net::SSLeay::BIO_read($s, $max);
8383 # $s - value corresponding to openssl's BIO structure
8384 # $max - [optional] max. bytes to read (if not specified, the value 32768 is used)
8385 #
8386 # returns: data
8387 Check openssl doc
8389 <http://www.openssl.org/docs/crypto/BIO_read.html>
8390 · BIO_write
8392 Attempts to write data from $buffer to BIO $b.
8394 my $rv = Net::SSLeay::BIO_write($b, $buffer);
8396 # $b - value corresponding to openssl's BIO structure
8397 # $buffer - data
8398 #
8399 # returns: amount of data successfully written
8400 # or that no data was successfully read or written if the result is 0 or -1
8401 # or -2 when the operation is not implemented in the specific BIO type
8402 Check openssl doc
8404 <http://www.openssl.org/docs/crypto/BIO_read.html>
8405 · BIO_s_mem
8407 Return the memory BIO method function.
8409 my $rv = Net::SSLeay::BIO_s_mem();
8411 #
8412 # returns: value corresponding to openssl's BIO_METHOD structure (0 on failure)
8413 Check openssl doc
8415 <http://www.openssl.org/docs/crypto/BIO_s_mem.html>
8416 · BIO_ssl_copy_session_id
8418 Copies an SSL session id between BIO chains from and to. It does
8420 this by locating the SSL BIOs in each chain and calling
8421 SSL_copy_session_id() on the internal SSL pointer.
8422 my $rv = Net::SSLeay::BIO_ssl_copy_session_id($to, $from);
8424 # $to - value corresponding to openssl's BIO structure
8425 # $from - value corresponding to openssl's BIO structure
8426 #
8427 # returns: 1 on success, 0 on failure
8428 Check openssl doc
8430 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8431 · BIO_ssl_shutdown
8433 Closes down an SSL connection on BIO chain bio. It does this by
8435 locating the SSL BIO in the chain and calling SSL_shutdown() on its
8436 internal SSL pointer.
8437 Net::SSLeay::BIO_ssl_shutdown($ssl_bio);
8439 # $ssl_bio - value corresponding to openssl's BIO structure
8440 #
8441 # returns: no return value
8442 Check openssl doc
8444 <http://www.openssl.org/docs/crypto/BIO_f_ssl.html>
8445 Low level API: Server side Server Name Indication (SNI) support
8447 · set_tlsext_host_name
8449 TBA
8451 · get_servername
8453 TBA
8455 · get_servername_type
8457 TBA
8459 · CTX_set_tlsext_servername_callback
8461 COMPATIBILITY: requires at least OpenSSL 0.9.8f
8463 This function is used in a server to support Server side Server
8465 Name Indication (SNI).
8466 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, $code)
8468 # $ctx - SSL context
8469 # $code - reference to a subroutine that will be called when a new connection is being initiated
8470 #
8471 # returns: no return value
8472 On the client side:
8473 use set_tlsext_host_name($ssl, $servername) before initiating the SSL connection.
8474 On the server side: Set up an additional SSL_CTX() for each
8476 different certificate;
8477 Add a servername callback to each SSL_CTX() using
8479 CTX_set_tlsext_servername_callback();
8480 The callback function is required to retrieve the client-supplied
8482 servername with get_servername(ssl). Figure out the right SSL_CTX
8483 to go with that host name, then switch the SSL object to that
8484 SSL_CTX with set_SSL_CTX().
8485 Example:
8487 # set callback
8489 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx,
8490 sub {
8491 my $ssl = shift;
8492 my $h = Net::SSLeay::get_servername($ssl);
8493 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
8494 } );
8495 More complete example:
8497 # ... initialize Net::SSLeay
8499 my %hostnames = (
8501 'sni1' => { cert=>'sni1.pem', key=>'sni1.key' },
8502 'sni2' => { cert=>'sni2.pem', key=>'sni2.key' },
8503 );
8504 # create a new context for each certificate/key pair
8506 for my $name (keys %hostnames) {
8507 $hostnames{$name}->{ctx} = Net::SSLeay::CTX_new or die;
8508 Net::SSLeay::CTX_set_cipher_list($hostnames{$name}->{ctx}, 'ALL');
8509 Net::SSLeay::set_cert_and_key($hostnames{$name}->{ctx},
8510 $hostnames{$name}->{cert}, $hostnames{$name}->{key}) or die;
8511 }
8512 # create default context
8514 my $ctx = Net::SSLeay::CTX_new or die;
8515 Net::SSLeay::CTX_set_cipher_list($ctx, 'ALL');
8516 Net::SSLeay::set_cert_and_key($ctx, 'cert.pem','key.pem') or die;
8517 # set callback
8519 Net::SSLeay::CTX_set_tlsext_servername_callback($ctx, sub {
8520 my $ssl = shift;
8521 my $h = Net::SSLeay::get_servername($ssl);
8522 Net::SSLeay::set_SSL_CTX($ssl, $hostnames{$h}->{ctx}) if exists $hostnames{$h};
8523 } );
8524 # ... later
8526 $s = Net::SSLeay::new($ctx);
8528 Net::SSLeay::set_fd($s, fileno($accepted_socket));
8529 Net::SSLeay::accept($s);
8530 Low level API: NPN (next protocol negotiation) related functions
8532 NPN is being replaced with ALPN, a more recent TLS extension for
8534 application protocol negotiation that's in process of being adopted by
8535 IETF. Please look below for APLN API description.
8536 Simple approach for using NPN support looks like this:
8538 ### client side
8540 use Net::SSLeay;
8541 use IO::Socket::INET;
8542 Net::SSLeay::initialize();
8544 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
8545 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
8546 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
8547 Net::SSLeay::CTX_set_next_proto_select_cb($ctx, ['http1.1','spdy/2']);
8548 my $ssl = Net::SSLeay::new($ctx) or die;
8549 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
8550 Net::SSLeay::connect($ssl);
8551 warn "client:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl), "\n";
8553 warn "client:last_status=", Net::SSLeay::P_next_proto_last_status($ssl), "\n";
8554 ### server side
8556 use Net::SSLeay;
8557 use IO::Socket::INET;
8558 Net::SSLeay::initialize();
8560 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
8561 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
8562 Net::SSLeay::set_cert_and_key($ctx, "t/data/cert.pem", "t/data/key.pem");
8563 Net::SSLeay::CTX_set_next_protos_advertised_cb($ctx, ['spdy/2','http1.1']);
8564 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
8565 while (1) {
8567 my $ssl = Net::SSLeay::new($ctx);
8568 warn("server:waiting for incoming connection...\n");
8569 my $fd = $sock->accept();
8570 Net::SSLeay::set_fd($ssl, $fd->fileno);
8571 Net::SSLeay::accept($ssl);
8572 warn "server:negotiated=",Net::SSLeay::P_next_proto_negotiated($ssl),"\n";
8573 my $got = Net::SSLeay::read($ssl);
8574 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
8575 Net::SSLeay::free($ssl);
8576 $fd->close();
8577 }
8578 # check with: openssl s_client -connect localhost:5443 -nextprotoneg http/1.1,spdy/2
8579 Please note that the selection (negotiation) is performed by client
8581 side, the server side simply advertise the list of supported protocols.
8582 Advanced approach allows you to implement your own negotiation
8584 algorithm.
8585 #see below documentation for:
8587 Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
8588 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
8589 Detection of NPN support (works even in older Net::SSLeay versions):
8591 use Net::SSLeay;
8593 if (exists &Net::SSLeay::P_next_proto_negotiated) {
8595 # do NPN stuff
8596 }
8597 · CTX_set_next_proto_select_cb
8599 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
8601 requires at least openssl-1.0.1
8602 NOTE: You need CTX_set_next_proto_select_cb on client side of SSL
8604 connection.
8605 Simple usage - in this case a "common" negotiation algorithm (as
8607 implemented by openssl's function SSL_select_next_proto) is used.
8608 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $arrayref);
8610 # $ctx - value corresponding to openssl's SSL_CTX structure
8611 # $arrayref - list of accepted protocols - e.g. ['http1.0', 'http1.1']
8612 #
8613 # returns: 0 on success, 1 on failure
8614 Advanced usage (you probably do not need this):
8616 $rv = Net::SSleay::CTX_set_next_proto_select_cb($ctx, $perl_callback_function, $callback_data);
8618 # $ctx - value corresponding to openssl's SSL_CTX structure
8619 # $perl_callback_function - reference to perl function
8620 # $callback_data - [optional] data to passed to callback function when invoked
8621 #
8622 # returns: 0 on success, 1 on failure
8623 # where callback function looks like
8625 sub npn_advertised_cb_invoke {
8626 my ($ssl, $arrayref_proto_list_advertised_by_server, $callback_data) = @_;
8627 my $status;
8628 # ...
8629 $status = 1; #status can be:
8630 # 0 - OPENSSL_NPN_UNSUPPORTED
8631 # 1 - OPENSSL_NPN_NEGOTIATED
8632 # 2 - OPENSSL_NPN_NO_OVERLAP
8633 return $status, ['http1.1','spdy/2']; # the callback has to return 2 values
8634 }
8635 To undefine/clear this callback use:
8637 Net::SSleay::CTX_set_next_proto_select_cb($ctx, undef);
8639 · CTX_set_next_protos_advertised_cb
8641 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
8643 requires at least openssl-1.0.1
8644 NOTE: You need CTX_set_next_proto_select_cb on server side of SSL
8646 connection.
8647 Simple usage:
8649 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $arrayref);
8651 # $ctx - value corresponding to openssl's SSL_CTX structure
8652 # $arrayref - list of advertised protocols - e.g. ['http1.0', 'http1.1']
8653 #
8654 # returns: 0 on success, 1 on failure
8655 Advanced usage (you probably do not need this):
8657 $rv = Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, $perl_callback_function, $callback_data);
8659 # $ctx - value corresponding to openssl's SSL_CTX structure
8660 # $perl_callback_function - reference to perl function
8661 # $callback_data - [optional] data to passed to callback function when invoked
8662 #
8663 # returns: 0 on success, 1 on failure
8664 # where callback function looks like
8666 sub npn_advertised_cb_invoke {
8667 my ($ssl, $callback_data) = @_;
8668 # ...
8669 return ['http1.1','spdy/2']; # the callback has to return arrayref
8670 }
8671 To undefine/clear this callback use:
8673 Net::SSleay::CTX_set_next_protos_advertised_cb($ctx, undef);
8675 · P_next_proto_negotiated
8677 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
8679 requires at least openssl-1.0.1
8680 Returns the name of negotiated protocol for given SSL connection
8682 $ssl.
8683 $rv = Net::SSLeay::P_next_proto_negotiated($ssl)
8685 # $ssl - value corresponding to openssl's SSL structure
8686 #
8687 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
8688 · P_next_proto_last_status
8690 COMPATIBILITY: not available in Net-SSLeay-1.45 and before;
8692 requires at least openssl-1.0.1
8693 Returns the result of the last negotiation for given SSL connection
8695 $ssl.
8696 $rv = Net::SSLeay::P_next_proto_last_status($ssl)
8698 # $ssl - value corresponding to openssl's SSL structure
8699 #
8700 # returns: (integer) negotiation status
8701 # 0 - OPENSSL_NPN_UNSUPPORTED
8702 # 1 - OPENSSL_NPN_NEGOTIATED
8703 # 2 - OPENSSL_NPN_NO_OVERLAP
8704 Low level API: ALPN (application layer protocol negotiation) related
8706 functions
8707 Application protocol can be negotiated via two different mechanisms
8709 employing two different TLS extensions: NPN (obsolete) and ALPN
8710 (recommended).
8711 The API is rather similar, with slight differences reflecting protocol
8713 specifics. In particular, with ALPN the protocol negotiation takes
8714 place on server, while with NPN the client implements the protocol
8715 negotiation logic.
8716 With ALPN, the most basic implementation looks like this:
8718 ### client side
8720 use Net::SSLeay;
8721 use IO::Socket::INET;
8722 Net::SSLeay::initialize();
8724 my $sock = IO::Socket::INET->new(PeerAddr=>'encrypted.google.com:443') or die;
8725 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
8726 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
8727 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
8728 my $ssl = Net::SSLeay::new($ctx) or die;
8729 Net::SSLeay::set_fd($ssl, fileno($sock)) or die;
8730 Net::SSLeay::connect($ssl);
8731 warn "client:selected=",Net::SSLeay::P_alpn_selected($ssl), "\n";
8733 ### server side
8735 use Net::SSLeay;
8736 use IO::Socket::INET;
8737 Net::SSLeay::initialize();
8739 my $ctx = Net::SSLeay::CTX_tlsv1_new() or die;
8740 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL);
8741 Net::SSLeay::set_cert_and_key($ctx, "t/data/cert.pem", "t/data/key.pem");
8742 Net::SSLeay::CTX_set_alpn_select_cb($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
8743 my $sock = IO::Socket::INET->new(LocalAddr=>'localhost', LocalPort=>5443, Proto=>'tcp', Listen=>20) or die;
8744 while (1) {
8746 my $ssl = Net::SSLeay::new($ctx);
8747 warn("server:waiting for incoming connection...\n");
8748 my $fd = $sock->accept();
8749 Net::SSLeay::set_fd($ssl, $fd->fileno);
8750 Net::SSLeay::accept($ssl);
8751 warn "server:selected=",Net::SSLeay::P_alpn_selected($ssl),"\n";
8752 my $got = Net::SSLeay::read($ssl);
8753 Net::SSLeay::ssl_write_all($ssl, "length=".length($got));
8754 Net::SSLeay::free($ssl);
8755 $fd->close();
8756 }
8757 # check with: openssl s_client -connect localhost:5443 -alpn spdy/3,http/1.1
8758 Advanced approach allows you to implement your own negotiation
8760 algorithm.
8761 #see below documentation for:
8763 Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
8764 Detection of ALPN support (works even in older Net::SSLeay versions):
8766 use Net::SSLeay;
8768 if (exists &Net::SSLeay::P_alpn_selected) {
8770 # do ALPN stuff
8771 }
8772 · CTX_set_alpn_select_cb
8774 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
8776 requires at least openssl-1.0.2
8777 NOTE: You need CTX_set_alpn_select_cb on server side of TLS
8779 connection.
8780 Simple usage - in this case a "common" negotiation algorithm (as
8782 implemented by openssl's function SSL_select_next_proto) is used.
8783 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $arrayref);
8785 # $ctx - value corresponding to openssl's SSL_CTX structure
8786 # $arrayref - list of accepted protocols - e.g. ['http/2.0', 'http/1.1', 'spdy/3']
8787 #
8788 # returns: 0 on success, 1 on failure
8789 Advanced usage (you probably do not need this):
8791 $rv = Net::SSleay::CTX_set_alpn_select_cb($ctx, $perl_callback_function, $callback_data);
8793 # $ctx - value corresponding to openssl's SSL_CTX structure
8794 # $perl_callback_function - reference to perl function
8795 # $callback_data - [optional] data to passed to callback function when invoked
8796 #
8797 # returns: 0 on success, 1 on failure
8798 # where callback function looks like
8800 sub alpn_select_cb_invoke {
8801 my ($ssl, $arrayref_proto_list_advertised_by_client, $callback_data) = @_;
8802 # ...
8803 if ($negotiated) {
8804 return 'http/2.0';
8805 } else {
8806 return undef;
8807 }
8808 }
8809 To undefine/clear this callback use:
8811 Net::SSleay::CTX_set_alpn_select_cb($ctx, undef);
8813 · set_alpn_protos
8815 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
8817 requires at least openssl-1.0.2
8818 NOTE: You need set_alpn_protos on client side of TLS connection.
8820 This adds list of supported application layer protocols to
8822 ClientHello message sent by a client. It advertises the
8823 enumeration of supported protocols:
8824 Net::SSLeay::set_alpn_protos($ssl, ['http/1.1', 'http/2.0', 'spdy/3]);
8826 # returns 0 on success
8827 · CTX_set_alpn_protos
8829 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
8831 requires at least openssl-1.0.2
8832 NOTE: You need CTX_set_alpn_protos on client side of TLS
8834 connection.
8835 This adds list of supported application layer protocols to
8837 ClientHello message sent by a client. It advertises the
8838 enumeration of supported protocols:
8839 Net::SSLeay::CTX_set_alpn_protos($ctx, ['http/1.1', 'http/2.0', 'spdy/3]);
8841 # returns 0 on success
8842 · P_alpn_selected
8844 COMPATIBILITY: not available in Net-SSLeay-1.55 and before;
8846 requires at least openssl-1.0.2
8847 Returns the name of negotiated protocol for given TLS connection
8849 $ssl.
8850 $rv = Net::SSLeay::P_alpn_selected($ssl)
8852 # $ssl - value corresponding to openssl's SSL structure
8853 #
8854 # returns: (string) negotiated protocol name (or undef if no negotiation was done or failed with fatal error)
8855 Low level API: DANE Support
8857 OpenSSL version 1.0.2 adds preliminary support RFC6698 Domain
8859 Authentication of Named Entities (DANE) Transport Layer Association
8860 within OpenSSL
8861 · SSL_get_tlsa_record_byname
8863 COMPATIBILITY: DELETED from net-ssleay, since it is not supported
8865 by OpenSSL
8866 In order to facilitate DANE there is additional interface,
8868 SSL_get_tlsa_record_byname, accepting hostname, port and socket
8869 type that returns packed TLSA record. In order to make it even
8870 easier there is additional SSL_ctrl function that calls
8871 SSL_get_tlsa_record_byname for you. Latter is recommended for
8872 programmers that wish to maintain broader binary compatibility,
8873 e.g. make application work with both 1.0.2 and prior version (in
8874 which case call to SSL_ctrl with new code returning error would
8875 have to be ignored when running with prior version).
8876 Net::SSLeay::get_tlsa_record_byname($name, $port, $type);
8878 Low level API: Other functions
8880 · COMP_add_compression_method
8882 Adds the compression method cm with the identifier id to the list
8884 of available compression methods. This list is globally maintained
8885 for all SSL operations within this application. It cannot be set
8886 for specific SSL_CTX or SSL objects.
8887 my $rv = Net::SSLeay::COMP_add_compression_method($id, $cm);
8889 # $id - (integer) compression method id
8890 # 0 to 63: methods defined by the IETF
8891 # 64 to 192: external party methods assigned by IANA
8892 # 193 to 255: reserved for private use
8893 #
8894 # $cm - value corresponding to openssl's COMP_METHOD structure
8895 #
8896 # returns: 0 on success, 1 on failure (check the error queue to find out the reason)
8897 Check openssl doc
8899 <http://www.openssl.org/docs/ssl/SSL_COMP_add_compression_method.html>
8900 · DH_free
8902 Frees the DH structure and its components. The values are erased
8904 before the memory is returned to the system.
8905 Net::SSLeay::DH_free($dh);
8907 # $dh - value corresponding to openssl's DH structure
8908 #
8909 # returns: no return value
8910 Check openssl doc <http://www.openssl.org/docs/crypto/DH_new.html>
8912 · FIPS_mode_set
8914 Enable or disable FIPS mode in a FIPS capable OpenSSL.
8916 Net::SSLeay:: FIPS_mode_set($enable);
8918 # $enable - (integer) 1 to enable, 0 to disable
8919 Low level API: EC related functions
8921 · CTX_set_tmp_ecdh
8923 TBA
8925 · EC_KEY_free
8927 TBA
8929 · EC_KEY_new_by_curve_name
8931 TBA
8933 · EC_KEY_generate_key
8935 Generates a EC key and returns it in a newly allocated EC_KEY
8937 structure. The EC key then can be used to create a PKEY which can
8938 be used in calls like X509_set_pubkey.
8939 my $key = Net::SSLeay::EVP_PKEY_new();
8941 my $ec = Net::SSLeay::EC_KEY_generate_key($curve);
8942 Net::SSLeay::EVP_PKEY_assign_EC_KEY($key,$ec);
8943 # $curve - curve name like 'secp521r1' or the matching Id (integer) of the curve
8945 #
8946 # returns: value corresponding to openssl's EC_KEY structure (0 on failure)
8947 This function has no equivalent in OpenSSL but combines multiple
8949 OpenSSL functions for an easier interface.
8950 Constants
8952 There are many openssl constants available in Net::SSLeay. You can use
8953 them like this:
8954 use Net::SSLeay;
8956 print &Net::SSLeay::NID_commonName;
8957 #or
8958 print Net::SSLeay::NID_commonName();
8959 Or you can import them and use:
8961 use Net::SSLeay qw/NID_commonName/;
8963 print &NID_commonName;
8964 #or
8965 print NID_commonName();
8966 #or
8967 print NID_commonName;
8968 The constants names are derived from openssl constants, however
8970 constants starting with "SSL_" prefix have name with "SSL_" part
8971 stripped - e.g. openssl's constant "SSL_OP_ALL" is available as
8972 "Net::SSleay::OP_ALL"
8973 The list of all available constant names:
8975 ASN1_STRFLGS_ESC_CTRL NID_id_qt_cps OP_NO_QUERY_MTU
8977 ASN1_STRFLGS_ESC_MSB NID_id_qt_unotice OP_NO_RENEGOTIATION
8978 ASN1_STRFLGS_ESC_QUOTE NID_idea_cbc OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION
8979 ASN1_STRFLGS_RFC2253 NID_idea_cfb64 OP_NO_SSL_MASK
8980 CB_ACCEPT_EXIT NID_idea_ecb OP_NO_SSLv2
8981 CB_ACCEPT_LOOP NID_idea_ofb64 OP_NO_SSLv3
8982 CB_ALERT NID_info_access OP_NO_TICKET
8983 CB_CONNECT_EXIT NID_initials OP_NO_TLSv1
8984 CB_CONNECT_LOOP NID_invalidity_date OP_NO_TLSv1_1
8985 CB_EXIT NID_issuer_alt_name OP_NO_TLSv1_2
8986 CB_HANDSHAKE_DONE NID_keyBag OP_NO_TLSv1_3
8987 CB_HANDSHAKE_START NID_key_usage OP_PKCS1_CHECK_1
8988 CB_LOOP NID_localKeyID OP_PKCS1_CHECK_2
8989 CB_READ NID_localityName OP_PRIORITIZE_CHACHA
8990 CB_READ_ALERT NID_md2 OP_SAFARI_ECDHE_ECDSA_BUG
8991 CB_WRITE NID_md2WithRSAEncryption OP_SINGLE_DH_USE
8992 CB_WRITE_ALERT NID_md5 OP_SINGLE_ECDH_USE
8993 ERROR_NONE NID_md5WithRSA OP_SSLEAY_080_CLIENT_DH_BUG
8994 ERROR_SSL NID_md5WithRSAEncryption OP_SSLREF2_REUSE_CERT_TYPE_BUG
8995 ERROR_SYSCALL NID_md5_sha1 OP_TLSEXT_PADDING
8996 ERROR_WANT_ACCEPT NID_mdc2 OP_TLS_BLOCK_PADDING_BUG
8997 ERROR_WANT_CONNECT NID_mdc2WithRSA OP_TLS_D5_BUG
8998 ERROR_WANT_READ NID_ms_code_com OP_TLS_ROLLBACK_BUG
8999 ERROR_WANT_WRITE NID_ms_code_ind READING
9000 ERROR_WANT_X509_LOOKUP NID_ms_ctl_sign RECEIVED_SHUTDOWN
9001 ERROR_ZERO_RETURN NID_ms_efs RSA_3
9002 EVP_PKS_DSA NID_ms_ext_req RSA_F4
9003 EVP_PKS_EC NID_ms_sgc R_BAD_AUTHENTICATION_TYPE
9004 EVP_PKS_RSA NID_name R_BAD_CHECKSUM
9005 EVP_PKT_ENC NID_netscape R_BAD_MAC_DECODE
9006 EVP_PKT_EXCH NID_netscape_base_url R_BAD_RESPONSE_ARGUMENT
9007 EVP_PKT_EXP NID_netscape_ca_policy_url R_BAD_SSL_FILETYPE
9008 EVP_PKT_SIGN NID_netscape_ca_revocation_url R_BAD_SSL_SESSION_ID_LENGTH
9009 EVP_PK_DH NID_netscape_cert_extension R_BAD_STATE
9010 EVP_PK_DSA NID_netscape_cert_sequence R_BAD_WRITE_RETRY
9011 EVP_PK_EC NID_netscape_cert_type R_CHALLENGE_IS_DIFFERENT
9012 EVP_PK_RSA NID_netscape_comment R_CIPHER_TABLE_SRC_ERROR
9013 FILETYPE_ASN1 NID_netscape_data_type R_INVALID_CHALLENGE_LENGTH
9014 FILETYPE_PEM NID_netscape_renewal_url R_NO_CERTIFICATE_SET
9015 F_CLIENT_CERTIFICATE NID_netscape_revocation_url R_NO_CERTIFICATE_SPECIFIED
9016 F_CLIENT_HELLO NID_netscape_ssl_server_name R_NO_CIPHER_LIST
9017 F_CLIENT_MASTER_KEY NID_ns_sgc R_NO_CIPHER_MATCH
9018 F_D2I_SSL_SESSION NID_organizationName R_NO_PRIVATEKEY
9019 F_GET_CLIENT_FINISHED NID_organizationalUnitName R_NO_PUBLICKEY
9020 F_GET_CLIENT_HELLO NID_pbeWithMD2AndDES_CBC R_NULL_SSL_CTX
9021 F_GET_CLIENT_MASTER_KEY NID_pbeWithMD2AndRC2_CBC R_PEER_DID_NOT_RETURN_A_CERTIFICATE
9022 F_GET_SERVER_FINISHED NID_pbeWithMD5AndCast5_CBC R_PEER_ERROR
9023 F_GET_SERVER_HELLO NID_pbeWithMD5AndDES_CBC R_PEER_ERROR_CERTIFICATE
9024 F_GET_SERVER_VERIFY NID_pbeWithMD5AndRC2_CBC R_PEER_ERROR_NO_CIPHER
9025 F_I2D_SSL_SESSION NID_pbeWithSHA1AndDES_CBC R_PEER_ERROR_UNSUPPORTED_CERTIFICATE_TYPE
9026 F_READ_N NID_pbeWithSHA1AndRC2_CBC R_PUBLIC_KEY_ENCRYPT_ERROR
9027 F_REQUEST_CERTIFICATE NID_pbe_WithSHA1And128BitRC2_CBC R_PUBLIC_KEY_IS_NOT_RSA
9028 F_SERVER_HELLO NID_pbe_WithSHA1And128BitRC4 R_READ_WRONG_PACKET_TYPE
9029 F_SSL_CERT_NEW NID_pbe_WithSHA1And2_Key_TripleDES_CBC R_SHORT_READ
9030 F_SSL_GET_NEW_SESSION NID_pbe_WithSHA1And3_Key_TripleDES_CBC R_SSL_SESSION_ID_IS_DIFFERENT
9031 F_SSL_NEW NID_pbe_WithSHA1And40BitRC2_CBC R_UNABLE_TO_EXTRACT_PUBLIC_KEY
9032 F_SSL_READ NID_pbe_WithSHA1And40BitRC4 R_UNKNOWN_REMOTE_ERROR_TYPE
9033 F_SSL_RSA_PRIVATE_DECRYPT NID_pbes2 R_UNKNOWN_STATE
9034 F_SSL_RSA_PUBLIC_ENCRYPT NID_pbmac1 R_X509_LIB
9035 F_SSL_SESSION_NEW NID_pkcs SENT_SHUTDOWN
9036 F_SSL_SESSION_PRINT_FP NID_pkcs3 SESSION_ASN1_VERSION
9037 F_SSL_SET_FD NID_pkcs7 SESS_CACHE_BOTH
9038 F_SSL_SET_RFD NID_pkcs7_data SESS_CACHE_CLIENT
9039 F_SSL_SET_WFD NID_pkcs7_digest SESS_CACHE_NO_AUTO_CLEAR
9040 F_SSL_USE_CERTIFICATE NID_pkcs7_encrypted SESS_CACHE_NO_INTERNAL
9041 F_SSL_USE_CERTIFICATE_ASN1 NID_pkcs7_enveloped SESS_CACHE_NO_INTERNAL_LOOKUP
9042 F_SSL_USE_CERTIFICATE_FILE NID_pkcs7_signed SESS_CACHE_NO_INTERNAL_STORE
9043 F_SSL_USE_PRIVATEKEY NID_pkcs7_signedAndEnveloped SESS_CACHE_OFF
9044 F_SSL_USE_PRIVATEKEY_ASN1 NID_pkcs8ShroudedKeyBag SESS_CACHE_SERVER
9045 F_SSL_USE_PRIVATEKEY_FILE NID_pkcs9 SSL3_VERSION
9046 F_SSL_USE_RSAPRIVATEKEY NID_pkcs9_challengePassword SSLEAY_BUILT_ON
9047 F_SSL_USE_RSAPRIVATEKEY_ASN1 NID_pkcs9_contentType SSLEAY_CFLAGS
9048 F_SSL_USE_RSAPRIVATEKEY_FILE NID_pkcs9_countersignature SSLEAY_DIR
9049 F_WRITE_PENDING NID_pkcs9_emailAddress SSLEAY_PLATFORM
9050 GEN_DIRNAME NID_pkcs9_extCertAttributes SSLEAY_VERSION
9051 GEN_DNS NID_pkcs9_messageDigest ST_ACCEPT
9052 GEN_EDIPARTY NID_pkcs9_signingTime ST_BEFORE
9053 GEN_EMAIL NID_pkcs9_unstructuredAddress ST_CONNECT
9054 GEN_IPADD NID_pkcs9_unstructuredName ST_INIT
9055 GEN_OTHERNAME NID_private_key_usage_period ST_OK
9056 GEN_RID NID_rc2_40_cbc ST_READ_BODY
9057 GEN_URI NID_rc2_64_cbc ST_READ_HEADER
9058 GEN_X400 NID_rc2_cbc TLS1_1_VERSION
9059 LIBRESSL_VERSION_NUMBER NID_rc2_cfb64 TLS1_2_VERSION
9060 MBSTRING_ASC NID_rc2_ecb TLS1_3_VERSION
9061 MBSTRING_BMP NID_rc2_ofb64 TLS1_VERSION
9062 MBSTRING_FLAG NID_rc4 TLSEXT_STATUSTYPE_ocsp
9063 MBSTRING_UNIV NID_rc4_40 VERIFY_CLIENT_ONCE
9064 MBSTRING_UTF8 NID_rc5_cbc VERIFY_FAIL_IF_NO_PEER_CERT
9065 MIN_RSA_MODULUS_LENGTH_IN_BYTES NID_rc5_cfb64 VERIFY_NONE
9066 MODE_ACCEPT_MOVING_WRITE_BUFFER NID_rc5_ecb VERIFY_PEER
9067 MODE_AUTO_RETRY NID_rc5_ofb64 V_OCSP_CERTSTATUS_GOOD
9068 MODE_ENABLE_PARTIAL_WRITE NID_ripemd160 V_OCSP_CERTSTATUS_REVOKED
9069 MODE_RELEASE_BUFFERS NID_ripemd160WithRSA V_OCSP_CERTSTATUS_UNKNOWN
9070 NID_OCSP_sign NID_rle_compression WRITING
9071 NID_SMIMECapabilities NID_rsa X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT
9072 NID_X500 NID_rsaEncryption X509_CHECK_FLAG_MULTI_LABEL_WILDCARDS
9073 NID_X509 NID_rsadsi X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS
9074 NID_ad_OCSP NID_safeContentsBag X509_CHECK_FLAG_NO_WILDCARDS
9075 NID_ad_ca_issuers NID_sdsiCertificate X509_CHECK_FLAG_SINGLE_LABEL_SUBDOMAINS
9076 NID_algorithm NID_secretBag X509_LOOKUP
9077 NID_authority_key_identifier NID_serialNumber X509_PURPOSE_ANY
9078 NID_basic_constraints NID_server_auth X509_PURPOSE_CRL_SIGN
9079 NID_bf_cbc NID_sha X509_PURPOSE_NS_SSL_SERVER
9080 NID_bf_cfb64 NID_sha1 X509_PURPOSE_OCSP_HELPER
9081 NID_bf_ecb NID_sha1WithRSA X509_PURPOSE_SMIME_ENCRYPT
9082 NID_bf_ofb64 NID_sha1WithRSAEncryption X509_PURPOSE_SMIME_SIGN
9083 NID_cast5_cbc NID_shaWithRSAEncryption X509_PURPOSE_SSL_CLIENT
9084 NID_cast5_cfb64 NID_stateOrProvinceName X509_PURPOSE_SSL_SERVER
9085 NID_cast5_ecb NID_subject_alt_name X509_PURPOSE_TIMESTAMP_SIGN
9086 NID_cast5_ofb64 NID_subject_key_identifier X509_TRUST_COMPAT
9087 NID_certBag NID_surname X509_TRUST_EMAIL
9088 NID_certificate_policies NID_sxnet X509_TRUST_OBJECT_SIGN
9089 NID_client_auth NID_time_stamp X509_TRUST_OCSP_REQUEST
9090 NID_code_sign NID_title X509_TRUST_OCSP_SIGN
9091 NID_commonName NID_undef X509_TRUST_SSL_CLIENT
9092 NID_countryName NID_uniqueIdentifier X509_TRUST_SSL_SERVER
9093 NID_crlBag NID_x509Certificate X509_TRUST_TSA
9094 NID_crl_distribution_points NID_x509Crl X509_V_FLAG_ALLOW_PROXY_CERTS
9095 NID_crl_number NID_zlib_compression X509_V_FLAG_CB_ISSUER_CHECK
9096 NID_crl_reason NOTHING X509_V_FLAG_CHECK_SS_SIGNATURE
9097 NID_delta_crl OCSP_RESPONSE_STATUS_INTERNALERROR X509_V_FLAG_CRL_CHECK
9098 NID_des_cbc OCSP_RESPONSE_STATUS_MALFORMEDREQUEST X509_V_FLAG_CRL_CHECK_ALL
9099 NID_des_cfb64 OCSP_RESPONSE_STATUS_SIGREQUIRED X509_V_FLAG_EXPLICIT_POLICY
9100 NID_des_ecb OCSP_RESPONSE_STATUS_SUCCESSFUL X509_V_FLAG_EXTENDED_CRL_SUPPORT
9101 NID_des_ede OCSP_RESPONSE_STATUS_TRYLATER X509_V_FLAG_IGNORE_CRITICAL
9102 NID_des_ede3 OCSP_RESPONSE_STATUS_UNAUTHORIZED X509_V_FLAG_INHIBIT_ANY
9103 NID_des_ede3_cbc OPENSSL_BUILT_ON X509_V_FLAG_INHIBIT_MAP
9104 NID_des_ede3_cfb64 OPENSSL_CFLAGS X509_V_FLAG_NOTIFY_POLICY
9105 NID_des_ede3_ofb64 OPENSSL_DIR X509_V_FLAG_POLICY_CHECK
9106 NID_des_ede_cbc OPENSSL_ENGINES_DIR X509_V_FLAG_POLICY_MASK
9107 NID_des_ede_cfb64 OPENSSL_PLATFORM X509_V_FLAG_TRUSTED_FIRST
9108 NID_des_ede_ofb64 OPENSSL_VERSION X509_V_FLAG_USE_CHECK_TIME
9109 NID_des_ofb64 OPENSSL_VERSION_NUMBER X509_V_FLAG_USE_DELTAS
9110 NID_description OP_ALL X509_V_FLAG_X509_STRICT
9111 NID_desx_cbc OP_ALLOW_NO_DHE_KEX X509_V_OK
9112 NID_dhKeyAgreement OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION XN_FLAG_COMPAT
9113 NID_dnQualifier OP_CIPHER_SERVER_PREFERENCE XN_FLAG_DN_REV
9114 NID_dsa OP_CISCO_ANYCONNECT XN_FLAG_DUMP_UNKNOWN_FIELDS
9115 NID_dsaWithSHA OP_COOKIE_EXCHANGE XN_FLAG_FN_ALIGN
9116 NID_dsaWithSHA1 OP_CRYPTOPRO_TLSEXT_BUG XN_FLAG_FN_LN
9117 NID_dsaWithSHA1_2 OP_DONT_INSERT_EMPTY_FRAGMENTS XN_FLAG_FN_MASK
9118 NID_dsa_2 OP_EPHEMERAL_RSA XN_FLAG_FN_NONE
9119 NID_email_protect OP_LEGACY_SERVER_CONNECT XN_FLAG_FN_OID
9120 NID_ext_key_usage OP_MICROSOFT_BIG_SSLV3_BUFFER XN_FLAG_FN_SN
9121 NID_ext_req OP_MICROSOFT_SESS_ID_BUG XN_FLAG_MULTILINE
9122 NID_friendlyName OP_MSIE_SSLV2_RSA_PADDING XN_FLAG_ONELINE
9123 NID_givenName OP_NETSCAPE_CA_DN_BUG XN_FLAG_RFC2253
9124 NID_hmacWithSHA1 OP_NETSCAPE_CHALLENGE_BUG XN_FLAG_SEP_COMMA_PLUS
9125 NID_id_ad OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG XN_FLAG_SEP_CPLUS_SPC
9126 NID_id_ce OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG XN_FLAG_SEP_MASK
9127 NID_id_kp OP_NON_EXPORT_FIRST XN_FLAG_SEP_MULTILINE
9128 NID_id_pbkdf2 OP_NO_CLIENT_RENEGOTIATION XN_FLAG_SEP_SPLUS_SPC
9129 NID_id_pe OP_NO_COMPRESSION XN_FLAG_SPC_EQ
9130 NID_id_pkix OP_NO_ENCRYPT_THEN_MAC
9131 INTERNAL ONLY functions (do not use these)
9133 The following functions are not intended for use from outside of
9134 Net::SSLeay module. They might be removed, renamed or changed without
9135 prior notice in future version.
9136 Simply DO NOT USE THEM!
9138 · hello
9140 · blength
9142 · constant
9144
9146 One very good example to look at is the implementation of "sslcat()" in
9147 the "SSLeay.pm" file.
9148 The following is a simple SSLeay client (with too little error checking
9150 :-(
9151 #!/usr/bin/perl
9153 use Socket;
9154 use Net::SSLeay qw(die_now die_if_ssl_error) ;
9155 Net::SSLeay::load_error_strings();
9156 Net::SSLeay::SSLeay_add_ssl_algorithms();
9157 Net::SSLeay::randomize();
9158 ($dest_serv, $port, $msg) = @ARGV; # Read command line
9160 $port = getservbyname ($port, 'tcp') unless $port =~ /^\d+$/;
9161 $dest_ip = gethostbyname ($dest_serv);
9162 $dest_serv_params = sockaddr_in($port, $dest_ip);
9163 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
9165 connect (S, $dest_serv_params) or die "connect: $!";
9166 select (S); $| = 1; select (STDOUT); # Eliminate STDIO buffering
9167 # The network connection is now open, lets fire up SSL
9169 $ctx = Net::SSLeay::CTX_new() or die_now("Failed to create SSL_CTX $!");
9171 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9172 or die_if_ssl_error("ssl ctx set options");
9173 $ssl = Net::SSLeay::new($ctx) or die_now("Failed to create SSL $!");
9174 Net::SSLeay::set_fd($ssl, fileno(S)); # Must use fileno
9175 $res = Net::SSLeay::connect($ssl) and die_if_ssl_error("ssl connect");
9176 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9177 # Exchange data
9179 $res = Net::SSLeay::write($ssl, $msg); # Perl knows how long $msg is
9181 die_if_ssl_error("ssl write");
9182 CORE::shutdown S, 1; # Half close --> No more output, sends EOF to server
9183 $got = Net::SSLeay::read($ssl); # Perl returns undef on failure
9184 die_if_ssl_error("ssl read");
9185 print $got;
9186 Net::SSLeay::free ($ssl); # Tear down connection
9188 Net::SSLeay::CTX_free ($ctx);
9189 close S;
9190 The following is a simple SSLeay echo server (non forking):
9192 #!/usr/bin/perl -w
9194 use Socket;
9195 use Net::SSLeay qw(die_now die_if_ssl_error);
9196 Net::SSLeay::load_error_strings();
9197 Net::SSLeay::SSLeay_add_ssl_algorithms();
9198 Net::SSLeay::randomize();
9199 $our_ip = "\0\0\0\0"; # Bind to all interfaces
9201 $port = 1235;
9202 $sockaddr_template = 'S n a4 x8';
9203 $our_serv_params = pack ($sockaddr_template, &AF_INET, $port, $our_ip);
9204 socket (S, &AF_INET, &SOCK_STREAM, 0) or die "socket: $!";
9206 bind (S, $our_serv_params) or die "bind: $!";
9207 listen (S, 5) or die "listen: $!";
9208 $ctx = Net::SSLeay::CTX_new () or die_now("CTX_new ($ctx): $!");
9209 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9210 or die_if_ssl_error("ssl ctx set options");
9211 # Following will ask password unless private key is not encrypted
9213 Net::SSLeay::CTX_use_RSAPrivateKey_file ($ctx, 'plain-rsa.pem',
9214 &Net::SSLeay::FILETYPE_PEM);
9215 die_if_ssl_error("private key");
9216 Net::SSLeay::CTX_use_certificate_file ($ctx, 'plain-cert.pem',
9217 &Net::SSLeay::FILETYPE_PEM);
9218 die_if_ssl_error("certificate");
9219 while (1) {
9221 print "Accepting connections...\n";
9222 ($addr = accept (NS, S)) or die "accept: $!";
9223 select (NS); $| = 1; select (STDOUT); # Piping hot!
9224 ($af,$client_port,$client_ip) = unpack($sockaddr_template,$addr);
9226 @inetaddr = unpack('C4',$client_ip);
9227 print "$af connection from " .
9228 join ('.', @inetaddr) . ":$client_port\n";
9229 # We now have a network connection, lets fire up SSLeay...
9231 $ssl = Net::SSLeay::new($ctx) or die_now("SSL_new ($ssl): $!");
9233 Net::SSLeay::set_fd($ssl, fileno(NS));
9234 $err = Net::SSLeay::accept($ssl) and die_if_ssl_error('ssl accept');
9236 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9237 # Connected. Exchange some data.
9239 $got = Net::SSLeay::read($ssl); # Returns undef on fail
9241 die_if_ssl_error("ssl read");
9242 print "Got `$got' (" . length ($got) . " chars)\n";
9243 Net::SSLeay::write ($ssl, uc ($got)) or die "write: $!";
9245 die_if_ssl_error("ssl write");
9246 Net::SSLeay::free ($ssl); # Tear down connection
9248 close NS;
9249 }
9250 Yet another echo server. This one runs from "/etc/inetd.conf" so it
9252 avoids all the socket code overhead. Only caveat is opening an rsa key
9253 file - it had better be without any encryption or else it will not know
9254 where to ask for the password. Note how "STDIN" and "STDOUT" are wired
9255 to SSL.
9256 #!/usr/bin/perl
9258 # /etc/inetd.conf
9259 # ssltst stream tcp nowait root /path/to/server.pl server.pl
9260 # /etc/services
9261 # ssltst 1234/tcp
9262 use Net::SSLeay qw(die_now die_if_ssl_error);
9264 Net::SSLeay::load_error_strings();
9265 Net::SSLeay::SSLeay_add_ssl_algorithms();
9266 Net::SSLeay::randomize();
9267 chdir '/key/dir' or die "chdir: $!";
9269 $| = 1; # Piping hot!
9270 open LOG, ">>/dev/console" or die "Can't open log file $!";
9271 select LOG; print "server.pl started\n";
9272 $ctx = Net::SSLeay::CTX_new() or die_now "CTX_new ($ctx) ($!)";
9274 $ssl = Net::SSLeay::new($ctx) or die_now "new ($ssl) ($!)";
9275 Net::SSLeay::set_options($ssl, &Net::SSLeay::OP_ALL)
9276 and die_if_ssl_error("ssl set options");
9277 # We get already open network connection from inetd, now we just
9279 # need to attach SSLeay to STDIN and STDOUT
9280 Net::SSLeay::set_rfd($ssl, fileno(STDIN));
9281 Net::SSLeay::set_wfd($ssl, fileno(STDOUT));
9282 Net::SSLeay::use_RSAPrivateKey_file ($ssl, 'plain-rsa.pem',
9284 Net::SSLeay::FILETYPE_PEM);
9285 die_if_ssl_error("private key");
9286 Net::SSLeay::use_certificate_file ($ssl, 'plain-cert.pem',
9287 Net::SSLeay::FILETYPE_PEM);
9288 die_if_ssl_error("certificate");
9289 Net::SSLeay::accept($ssl) and die_if_ssl_err("ssl accept: $!");
9291 print "Cipher `" . Net::SSLeay::get_cipher($ssl) . "'\n";
9292 $got = Net::SSLeay::read($ssl);
9294 die_if_ssl_error("ssl read");
9295 print "Got `$got' (" . length ($got) . " chars)\n";
9296 Net::SSLeay::write ($ssl, uc($got)) or die "write: $!";
9298 die_if_ssl_error("ssl write");
9299 Net::SSLeay::free ($ssl); # Tear down the connection
9301 Net::SSLeay::CTX_free ($ctx);
9302 close LOG;
9303 There are also a number of example/test programs in the examples
9305 directory:
9306 sslecho.pl - A simple server, not unlike the one above
9308 minicli.pl - Implements a client using low level SSLeay routines
9309 sslcat.pl - Demonstrates using high level sslcat utility function
9310 get_page.pl - Is a utility for getting html pages from secure servers
9311 callback.pl - Demonstrates certificate verification and callback usage
9312 stdio_bulk.pl - Does SSL over Unix pipes
9313 ssl-inetd-serv.pl - SSL server that can be invoked from inetd.conf
9314 httpd-proxy-snif.pl - Utility that allows you to see how a browser
9315 sends https request to given server and what reply
9316 it gets back (very educative :-)
9317 makecert.pl - Creates a self signed cert (does not use this module)
9318
9320 See README and README.* in the distribution directory for installation
9321 guidance on a variety of platforms.
9322
9324 "Net::SSLeay::read()" uses an internal buffer of 32KB, thus no single
9325 read will return more. In practice one read returns much less, usually
9326 as much as fits in one network packet. To work around this, you should
9327 use a loop like this:
9328 $reply = '';
9330 while ($got = Net::SSLeay::read($ssl)) {
9331 last if print_errs('SSL_read');
9332 $reply .= $got;
9333 }
9334 Although there is no built-in limit in "Net::SSLeay::write()", the
9336 network packet size limitation applies here as well, thus use:
9337 $written = 0;
9339 while ($written < length($message)) {
9341 $written += Net::SSLeay::write($ssl, substr($message, $written));
9342 last if print_errs('SSL_write');
9343 }
9344 Or alternatively you can just use the following convenience functions:
9346 Net::SSLeay::ssl_write_all($ssl, $message) or die "ssl write failure";
9348 $got = Net::SSLeay::ssl_read_all($ssl) or die "ssl read failure";
9349
9351 An OpenSSL bug CVE-2015-0290 "OpenSSL Multiblock Corrupted Pointer
9352 Issue" can cause POST requests of over 90kB to fail or crash. This bug
9353 is reported to be fixed in OpenSSL 1.0.2a.
9354 Autoloader emits a
9356 Argument "xxx" isn't numeric in entersub at blib/lib/Net/SSLeay.pm'
9358 warning if die_if_ssl_error is made autoloadable. If you figure out
9360 why, drop me a line.
9361 Callback set using "SSL_set_verify()" does not appear to work. This may
9363 well be an openssl problem (e.g. see "ssl/ssl_lib.c" line 1029). Try
9364 using "SSL_CTX_set_verify()" instead and do not be surprised if even
9365 this stops working in future versions.
9366 Callback and certificate verification stuff is generally too little
9368 tested.
9369 Random numbers are not initialized randomly enough, especially if you
9371 do not have "/dev/random" and/or "/dev/urandom" (such as in Solaris
9372 platforms - but it's been suggested that cryptorand daemon from the
9373 SUNski package solves this). In this case you should investigate third
9374 party software that can emulate these devices, e.g. by way of a named
9375 pipe to some program.
9376 Another gotcha with random number initialization is randomness
9378 depletion. This phenomenon, which has been extensively discussed in
9379 OpenSSL, Apache-SSL, and Apache-mod_ssl forums, can cause your script
9380 to block if you use "/dev/random" or to operate insecurely if you use
9381 "/dev/urandom". What happens is that when too much randomness is drawn
9382 from the operating system's randomness pool then randomness can
9383 temporarily be unavailable. "/dev/random" solves this problem by
9384 waiting until enough randomness can be gathered - and this can take a
9385 long time since blocking reduces activity in the machine and less
9386 activity provides less random events: a vicious circle. "/dev/urandom"
9387 solves this dilemma more pragmatically by simply returning predictable
9388 "random" numbers. Some" /dev/urandom" emulation software however
9389 actually seems to implement "/dev/random" semantics. Caveat emptor.
9390 I've been pointed to two such daemons by Mik Firestone
9392 <mik@@speed.stdio._com> who has used them on Solaris 8:
9393 1. Entropy Gathering Daemon (EGD) at
9395 <http://www.lothar.com/tech/crypto/>
9396 2. Pseudo-random number generating daemon (PRNGD) at
9398 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
9399 If you are using the low level API functions to communicate with other
9401 SSL implementations, you would do well to call
9402 Net::SSLeay::CTX_set_options($ctx, &Net::SSLeay::OP_ALL)
9404 or die_if_ssl_error("ssl ctx set options");
9405 to cope with some well know bugs in some other SSL implementations. The
9407 high level API functions always set all known compatibility options.
9408 Sometimes "sslcat()" (and the high level HTTPS functions that build on
9410 it) is too fast in signaling the EOF to legacy HTTPS servers. This
9411 causes the server to return empty page. To work around this problem you
9412 can set the global variable
9413 $Net::SSLeay::slowly = 1; # Add sleep so broken servers can keep up
9415 HTTP/1.1 is not supported. Specifically this module does not know to
9417 issue or serve multiple http requests per connection. This is a serious
9418 shortcoming, but using the SSL session cache on your server helps to
9419 alleviate the CPU load somewhat.
9420 As of version 1.09 many newer OpenSSL auxiliary functions were added
9422 (from "REM_AUTOMATICALLY_GENERATED_1_09" onwards in "SSLeay.xs").
9423 Unfortunately I have not had any opportunity to test these. Some of
9424 them are trivial enough that I believe they "just work", but others
9425 have rather complex interfaces with function pointers and all. In these
9426 cases you should proceed wit great caution.
9427 This module defaults to using OpenSSL automatic protocol negotiation
9429 code for automatically detecting the version of the SSL protocol that
9430 the other end talks. With most web servers this works just fine, but
9431 once in a while I get complaints from people that the module does not
9432 work with some web servers. Usually this can be solved by explicitly
9433 setting the protocol version, e.g.
9434 $Net::SSLeay::ssl_version = 2; # Insist on SSLv2
9436 $Net::SSLeay::ssl_version = 3; # Insist on SSLv3
9437 $Net::SSLeay::ssl_version = 10; # Insist on TLSv1
9438 Although the autonegotiation is nice to have, the SSL standards do not
9440 formally specify any such mechanism. Most of the world has accepted the
9441 SSLeay/OpenSSL way of doing it as the de facto standard. But for the
9442 few that think differently, you have to explicitly speak the correct
9443 version. This is not really a bug, but rather a deficiency in the
9444 standards. If a site refuses to respond or sends back some nonsensical
9445 error codes (at the SSL handshake level), try this option before
9446 mailing me.
9447 On some systems, OpenSSL may be compiled without support for SSLv2. If
9449 this is the case, Net::SSLeay will warn if ssl_version has been set to
9450 2.
9451 The high level API returns the certificate of the peer, thus allowing
9453 one to check what certificate was supplied. However, you will only be
9454 able to check the certificate after the fact, i.e. you already sent
9455 your form data by the time you find out that you did not trust them,
9456 oops.
9457 So, while being able to know the certificate after the fact is surely
9459 useful, the security minded would still choose to do the connection and
9460 certificate verification first and only then exchange data with the
9461 site. Currently none of the high level API functions do this, thus you
9462 would have to program it using the low level API. A good place to start
9463 is to see how the "Net::SSLeay::http_cat()" function is implemented.
9464 The high level API functions use a global file handle "SSLCAT_S"
9466 internally. This really should not be a problem because there is no way
9467 to interleave the high level API functions, unless you use threads (but
9468 threads are not very well supported in perl anyway (as of version
9469 5.6.1). However, you may run into problems if you call undocumented
9470 internal functions in an interleaved fashion. The best solution is to
9471 "require Net::SSLeay" in one thread after all the threads have been
9472 created.
9473
9475 Random number generator not seeded!!!
9476 (W) This warning indicates that "randomize()" was not able to read
9477 "/dev/random" or "/dev/urandom", possibly because your system does
9478 not have them or they are differently named. You can still use SSL,
9479 but the encryption will not be as strong.
9480 open_tcp_connection: destination host not found:`server' (port 123)
9482 ($!)
9483 Name lookup for host named "server" failed.
9484 open_tcp_connection: failed `server', 123 ($!)
9486 The name was resolved, but establishing the TCP connection failed.
9487 msg 123: 1 - error:140770F8:SSL routines:SSL23_GET_SERVER_HELLO:unknown
9489 proto
9490 SSLeay error string. The first number (123) is the PID, the second
9491 number (1) indicates the position of the error message in SSLeay
9492 error stack. You often see a pile of these messages as errors
9493 cascade.
9494 msg 123: 1 - error:02001002::lib(2) :func(1) :reason(2)
9496 The same as above, but you didn't call load_error_strings() so
9497 SSLeay couldn't verbosely explain the error. You can still find out
9498 what it means with this command:
9499 /usr/local/ssl/bin/ssleay errstr 02001002
9501 Password is being asked for private key
9503 This is normal behaviour if your private key is encrypted. Either
9504 you have to supply the password or you have to use an unencrypted
9505 private key. Scan OpenSSL.org for the FAQ that explains how to do
9506 this (or just study examples/makecert.pl which is used during "make
9507 test" to do just that).
9508
9510 You can mitigate some of the security vulnerabilities that might be
9511 present in your SSL/TLS application:
9512 BEAST Attack
9514 http://blogs.cisco.com/security/beat-the-beast-with-tls/
9515 https://community.qualys.com/blogs/securitylabs/2011/10/17/mitigating-the-beast-attack-on-tls
9516 http://blog.zoller.lu/2011/09/beast-summary-tls-cbc-countermeasures.html
9517 The BEAST attack relies on a weakness in the way CBC mode is used in
9519 SSL/TLS. In OpenSSL versions 0.9.6d and later, the protocol-level
9520 mitigation is enabled by default, thus making it not vulnerable to the
9521 BEAST attack.
9522 Solutions:
9524 · Compile with OpenSSL versions 0.9.6d or later, which enables
9526 SSL_OP_ALL by default
9527 · Ensure SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS is not enabled (its not
9529 enabled by default)
9530 · Don't support SSLv2, SSLv3
9532 · Actively control the ciphers your server supports with
9534 set_cipher_list:
9535 Net::SSLeay::set_cipher_list($ssl, 'RC4-SHA:HIGH:!ADH');
9537 Session Resumption
9539 http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html
9540 The SSL Labs vulnerability test on your SSL server might report in red:
9542 Session resumption No (IDs assigned but not accepted)
9544 This report is not really bug or a vulnerability, since the server will
9546 not accept session resumption requests. However, you can prevent this
9547 noise in the report by disabling the session cache altogether:
9548 Net::SSLeay::CTX_set_session_cache_mode($ssl_ctx,
9549 Net::SSLeay::SESS_CACHE_OFF()); Use 0 if you don't have SESS_CACHE_OFF
9550 constant.
9551 Secure Renegotiation and DoS Attack
9553 https://community.qualys.com/blogs/securitylabs/2011/10/31/tls-renegotiation-and-denial-of-service-attacks
9554 This is not a "security flaw," it is more of a DoS vulnerability.
9556 Solutions:
9558 · Do not support SSLv2
9560 · Do not set the SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION option
9562 · Compile with OpenSSL 0.9.8m or later
9564
9566 Please report any bugs or feature requests to "bug-Net-SSLeay at
9567 rt.cpan.org", or through the web interface at
9568 <http://rt.cpan.org/Public/Dist/Display.html?Name=Net-SSLeay>. I will
9569 be notified, and then you'll automatically be notified of progress on
9570 your bug as I make changes.
9571 Subversion access to the latest source code etc can be obtained at
9573 <http://alioth.debian.org/projects/net-ssleay>
9574 The developer mailing list (for people interested in contributing to
9576 the source code) can be found at
9577 <http://lists.alioth.debian.org/mailman/listinfo/net-ssleay-devel>
9578 You can find documentation for this module with the "perldoc" command.
9580 perldoc Net::SSLeay
9582 You can also look for information at:
9584 · AnnoCPAN: Annotated CPAN documentation
9586 <http://annocpan.org/dist/Net-SSLeay>
9588 · CPAN Ratings
9590 <http://cpanratings.perl.org/d/Net-SSLeay>
9592 · Search CPAN
9594 <http://search.cpan.org/dist/Net-SSLeay>
9596 Commercial support for Net::SSLeay may be obtained from
9598 Symlabs (netssleay@symlabs.com)
9600 Tel: +351-214.222.630
9601 Fax: +351-214.222.637
9602
9604 Maintained by Mike McCauley and Florian Ragwitz since November 2005
9605 Originally written by Sampo Kellomäki <sampo@symlabs.com>
9607
9609 Copyright (c) 1996-2003 Sampo Kellomäki <sampo@symlabs.com>
9610 Copyright (C) 2005-2006 Florian Ragwitz <rafl@debian.org>
9612 Copyright (C) 2005 Mike McCauley <mikem@airspayce.com>
9614 All Rights Reserved.
9616 Distribution and use of this module is under the same terms as the
9618 OpenSSL package itself (i.e. free, but mandatory attribution; NO
9619 WARRANTY). Please consult LICENSE file in the root of the Net-SSLeay
9620 distribution, and also included in this distribution.
9621 The Authors credit Eric Young and the OpenSSL team with the development
9623 of the excellent OpenSSL library, which this Perl package uses.
9624 And remember, you, and nobody else but you, are responsible for
9626 auditing this module and OpenSSL library for security problems,
9627 backdoors, and general suitability for your application.
9628
9630 From version 1.66 onwards, this Net-SSLeay library is issued under the
9631 "Perl Artistic License 2.0", the same license as Perl itself.
9632 (ignore this line: this is to keep kwalitee happy by saying: Not GPL)
9634
9636 Net::SSLeay::Handle - File handle interface
9637 ./examples - Example servers and a clients
9638 <http://www.openssl.org/> - OpenSSL source, documentation, etc
9639 openssl-users-request@openssl.org - General OpenSSL mailing list
9640 <http://www.ietf.org/rfc/rfc2246.txt> - TLS 1.0 specification
9641 <http://www.w3c.org> - HTTP specifications
9642 <http://www.ietf.org/rfc/rfc2617.txt> - How to send password
9643 <http://www.lothar.com/tech/crypto/> - Entropy Gathering Daemon (EGD)
9644 <http://www.aet.tu-cottbus.de/personen/jaenicke/postfix_tls/prngd.html>
9645 - pseudo-random number generating daemon (PRNGD)
9646 perl(1)
9647 perlref(1)
9648 perllol(1)
9649 perldoc ~openssl/doc/ssl/SSL_CTX_set_verify.pod
9650perl v5.28.1 2019-01-19 Net::SSLeay(3)