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