{ "content": [ { "type": "text", "text": "# IO::Socket::SSL (perldoc)\n\n## NAME\n\nIO::Socket::SSL - SSL sockets with IO::Socket interface\n\n## SYNOPSIS\n\nuse strict;\nuse IO::Socket::SSL;\n# simple client\nmy $cl = IO::Socket::SSL->new('www.google.com:443');\nprint $cl \"GET / HTTP/1.0\\r\\n\\r\\n\";\nprint <$cl>;\n# simple server\nmy $srv = IO::Socket::SSL->new(\nLocalAddr => '0.0.0.0:1234',\nListen => 10,\nSSLcertfile => 'server-cert.pem',\nSSLkeyfile => 'server-key.pem',\n);\n$srv->accept;\n\n## DESCRIPTION\n\nIO::Socket::SSL makes using SSL/TLS much easier by wrapping the necessary functionality into the\nfamiliar IO::Socket interface and providing secure defaults whenever possible. This way,\nexisting applications can be made SSL-aware without much effort, at least if you do blocking I/O\nand don't use select or poll.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **Essential Information About SSL/TLS**\n- **Basic SSL Client**\n- **Basic SSL Server**\n- **Common Usage Errors**\n- **Common Problems with SSL**\n- **Using Non-Blocking Sockets**\n- **Advanced Usage** (1 subsections)\n- **Integration Into Own Modules**\n- **Description Of Methods** (22 subsections)\n- **DEPRECATIONS** (6 subsections)\n- **EXAMPLES**\n- **BUGS**\n- **SEE ALSO**\n- **THANKS**\n- **AUTHORS**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "IO::Socket::SSL", "section": "", "mode": "perldoc", "summary": "IO::Socket::SSL - SSL sockets with IO::Socket interface", "synopsis": "use strict;\nuse IO::Socket::SSL;\n# simple client\nmy $cl = IO::Socket::SSL->new('www.google.com:443');\nprint $cl \"GET / HTTP/1.0\\r\\n\\r\\n\";\nprint <$cl>;\n# simple server\nmy $srv = IO::Socket::SSL->new(\nLocalAddr => '0.0.0.0:1234',\nListen => 10,\nSSLcertfile => 'server-cert.pem',\nSSLkeyfile => 'server-key.pem',\n);\n$srv->accept;", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "See the 'example' directory, the tests in 't' and also the tools in 'util'." ], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 17, "subsections": [] }, { "name": "DESCRIPTION", "lines": 36, "subsections": [] }, { "name": "Essential Information About SSL/TLS", "lines": 82, "subsections": [] }, { "name": "Basic SSL Client", "lines": 104, "subsections": [] }, { "name": "Basic SSL Server", "lines": 49, "subsections": [] }, { "name": "Common Usage Errors", "lines": 115, "subsections": [] }, { "name": "Common Problems with SSL", "lines": 75, "subsections": [] }, { "name": "Using Non-Blocking Sockets", "lines": 72, "subsections": [] }, { "name": "Advanced Usage", "lines": 20, "subsections": [ { "name": "Talk Plain and SSL With The Same Socket", "lines": 35 } ] }, { "name": "Integration Into Own Modules", "lines": 12, "subsections": [] }, { "name": "Description Of Methods", "lines": 32, "subsections": [ { "name": "new", "lines": 541 }, { "name": "connect", "lines": 4 }, { "name": "close", "lines": 18 }, { "name": "sysread", "lines": 17 }, { "name": "syswrite", "lines": 10 }, { "name": "peek", "lines": 5 }, { "name": "pending", "lines": 4 }, { "name": "get_fingerprint", "lines": 6 }, { "name": "get_fingerprint_bin", "lines": 5 }, { "name": "get_cipher", "lines": 2 }, { "name": "get_sslversion", "lines": 2 }, { "name": "get_sslversion_int", "lines": 2 }, { "name": "get_session_reused", "lines": 4 }, { "name": "dump_peer_certificate", "lines": 3 }, { "name": "peer_certificate", "lines": 23 }, { "name": "sock_certificate", "lines": 16 }, { "name": "verify_hostname", "lines": 80 }, { "name": "next_proto_negotiated", "lines": 6 }, { "name": "alpn_selected", "lines": 6 }, { "name": "errstr", "lines": 9 }, { "name": "opened", "lines": 22 }, { "name": "stop_SSL", "lines": 184 } ] }, { "name": "DEPRECATIONS", "lines": 2, "subsections": [ { "name": "context_init", "lines": 2 }, { "name": "socketToSSL", "lines": 2 }, { "name": "kill_socket", "lines": 2 }, { "name": "get_peer_certificate", "lines": 4 }, { "name": "issuer_name", "lines": 2 }, { "name": "subject_name", "lines": 2 } ] }, { "name": "EXAMPLES", "lines": 2, "subsections": [] }, { "name": "BUGS", "lines": 19, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "THANKS", "lines": 5, "subsections": [] }, { "name": "AUTHORS", "lines": 8, "subsections": [] }, { "name": "COPYRIGHT", "lines": 9, "subsections": [] } ], "sections": { "NAME": { "content": "IO::Socket::SSL - SSL sockets with IO::Socket interface\n", "subsections": [] }, "SYNOPSIS": { "content": "use strict;\nuse IO::Socket::SSL;\n\n# simple client\nmy $cl = IO::Socket::SSL->new('www.google.com:443');\nprint $cl \"GET / HTTP/1.0\\r\\n\\r\\n\";\nprint <$cl>;\n\n# simple server\nmy $srv = IO::Socket::SSL->new(\nLocalAddr => '0.0.0.0:1234',\nListen => 10,\nSSLcertfile => 'server-cert.pem',\nSSLkeyfile => 'server-key.pem',\n);\n$srv->accept;\n", "subsections": [] }, "DESCRIPTION": { "content": "IO::Socket::SSL makes using SSL/TLS much easier by wrapping the necessary functionality into the\nfamiliar IO::Socket interface and providing secure defaults whenever possible. This way,\nexisting applications can be made SSL-aware without much effort, at least if you do blocking I/O\nand don't use select or poll.\n\nBut, under the hood, SSL is a complex beast. So there are lots of methods to make it do what you\nneed if the default behavior is not adequate. Because it is easy to inadvertently introduce\ncritical security bugs or just hard to debug problems, I would recommend studying the following\ndocumentation carefully.\n\nThe documentation consists of the following parts:\n\n* \"Essential Information About SSL/TLS\"\n\n* \"Basic SSL Client\"\n\n* \"Basic SSL Server\"\n\n* \"Common Usage Errors\"\n\n* \"Common Problems with SSL\"\n\n* \"Using Non-Blocking Sockets\"\n\n* \"Advanced Usage\"\n\n* \"Integration Into Own Modules\"\n\n* \"Description Of Methods\"\n\nAdditional documentation can be found in\n\n* IO::Socket::SSL::Intercept - Doing Man-In-The-Middle with SSL\n\n* IO::Socket::SSL::Utils - Useful functions for certificates etc\n", "subsections": [] }, "Essential Information About SSL/TLS": { "content": "SSL (Secure Socket Layer) or its successor TLS (Transport Layer Security) are protocols to\nfacilitate end-to-end security. These protocols are used when accessing web sites (https),\ndelivering or retrieving email, and in lots of other use cases. In the following documentation\nwe will refer to both SSL and TLS as simply 'SSL'.\n\nSSL enables end-to-end security by providing two essential functions:\n\nEncryption\nThis part encrypts the data for transit between the communicating parties, so that nobody in\nbetween can read them. It also provides tamper resistance so that nobody in between can\nmanipulate the data.\n\nIdentification\nThis part makes sure that you talk to the right peer. If the identification is done\nincorrectly it is easy to mount man-in-the-middle attacks, e.g. if Alice wants to talk to\nBob it would be possible for Mallory to put itself in the middle, so that Alice talks to\nMallory and Mallory to Bob. All the data would still be encrypted, but not end-to-end\nbetween Alice and Bob, but only between Alice and Mallory and then between Mallory and Bob.\nThus Mallory would be able to read and modify all traffic between Alice and Bob.\n\nIdentification is the part which is the hardest to understand and the easiest to get wrong.\n\nWith SSL, the Identification is usually done with certificates inside a PKI (Public Key\nInfrastructure). These Certificates are comparable to an identity card, which contains\ninformation about the owner of the card. The card then is somehow signed by the issuer of the\ncard, the CA (Certificate Agency).\n\nTo verify the identity of the peer the following must be done inside SSL:\n\n* Get the certificate from the peer. If the peer does not present a certificate we cannot\nverify it.\n\n* Check if we trust the certificate, e.g. make sure it's not a forgery.\n\nWe believe that a certificate is not a fake if we either know the certificate already or if\nwe trust the issuer (the CA) and can verify the issuers signature on the certificate. In\nreality there is often a hierarchy of certificate agencies and we only directly trust the\nroot of this hierarchy. In this case the peer not only sends his own certificate, but also\nall intermediate certificates. Verification will be done by building a trust path from the\ntrusted root up to the peers certificate and checking in each step if the we can verify the\nissuer's signature.\n\nThis step often causes problems because the client does not know the necessary trusted root\ncertificates. These are usually stored in a system dependent CA store, but often the\nbrowsers have their own CA store.\n\n* Check if the certificate is still valid. Each certificate has a lifetime and should not be\nused after that time because it might be compromised or the underlying cryptography got\nbroken in the mean time.\n\n* Check if the subject of the certificate matches the peer. This is like comparing the picture\non the identity card against the person representing the identity card.\n\nWhen connecting to a server this is usually done by comparing the hostname used for\nconnecting against the names represented in the certificate. A certificate might contain\nmultiple names or wildcards, so that it can be used for multiple hosts (e.g. *.example.com\nand *.example.org).\n\nAlthough nobody sane would accept an identity card where the picture does not match the\nperson we see, it is a common implementation error with SSL to omit this check or get it\nwrong.\n\n* Check if the certificate was revoked by the issuer. This might be the case if the\ncertificate was compromised somehow and now somebody else might use it to claim the wrong\nidentity. Such revocations happened a lot after the heartbleed attack.\n\nFor SSL there are two ways to verify a revocation, CRL and OCSP. With CRLs (Certificate\nRevocation List) the CA provides a list of serial numbers for revoked certificates. The\nclient somehow has to download the list (which can be huge) and keep it up to date. With\nOCSP (Online Certificate Status Protocol) the client can check a single certificate directly\nby asking the issuer.\n\nRevocation is the hardest part of the verification and none of today's browsers get it fully\ncorrect. But, they are still better than most other implementations which don't implement\nrevocation checks or leave the hard parts to the developer.\n\nWhen accessing a web site with SSL or delivering mail in a secure way the identity is usually\nonly checked one way, e.g. the client wants to make sure it talks to the right server, but the\nserver usually does not care which client it talks to. But, sometimes the server wants to\nidentify the client too and will request a certificate from the client which the server must\nverify in a similar way.\n", "subsections": [] }, "Basic SSL Client": { "content": "A basic SSL client is simple:\n\nmy $client = IO::Socket::SSL->new('www.example.com:443')\nor die \"error=$!, sslerror=$SSLERROR\";\n\nThis will take the OpenSSL default CA store as the store for the trusted CA. This usually works\non UNIX systems. If there are no certificates in the store it will try use Mozilla::CA which\nprovides the default CAs of Firefox.\n\nIn the default settings, IO::Socket::SSL will use a safer cipher set and SSL version, do a\nproper hostname check against the certificate, and use SNI (server name indication) to send the\nhostname inside the SSL handshake. This is necessary to work with servers which have different\ncertificates behind the same IP address. It will also check the revocation of the certificate\nwith OCSP, but currently only if the server provides OCSP stapling (for deeper checks see\n\"ocspresolver\" method).\n\nLots of options can be used to change ciphers, SSL version, location of CA and much more. See\ndocumentation of methods for details.\n\nWith protocols like SMTP it is necessary to upgrade an existing socket to SSL. This can be done\nlike this:\n\nmy $client = IO::Socket::INET->new('mx.example.com:25') or die $!;\n# .. read greeting from server\n# .. send EHLO and read response\n# .. send STARTTLS command and read response\n# .. if response was successful we can upgrade the socket to SSL now:\nIO::Socket::SSL->startSSL($client,\n# explicitly set hostname we should use for SNI\nSSLhostname => 'mx.example.com'\n) or die $SSLERROR;\n\nA more complete example for a simple HTTP client:\n\nmy $client = IO::Socket::SSL->new(\n# where to connect\nPeerHost => \"www.example.com\",\nPeerPort => \"https\",\n\n# certificate verification - VERIFYPEER is default\nSSLverifymode => SSLVERIFYPEER,\n\n# location of CA store\n# need only be given if default store should not be used\nSSLcapath => '/etc/ssl/certs', # typical CA path on Linux\nSSLcafile => '/etc/ssl/cert.pem', # typical CA file on BSD\n\n# or just use default path on system:\nIO::Socket::SSL::defaultca(), # either explicitly\n# or implicitly by not giving SSLca*\n\n# easy hostname verification\n# It will use PeerHost as default name a verification\n# scheme as default, which is safe enough for most purposes.\nSSLverifycnname => 'foo.bar',\nSSLverifycnscheme => 'http',\n\n# SNI support - defaults to PeerHost\nSSLhostname => 'foo.bar',\n\n) or die \"failed connect or ssl handshake: $!,$SSLERROR\";\n\n# send and receive over SSL connection\nprint $client \"GET / HTTP/1.0\\r\\n\\r\\n\";\nprint <$client>;\n\nAnd to do revocation checks with OCSP (only available with OpenSSL 1.0.0 or higher and\nNet::SSLeay 1.59 or higher):\n\n# default will try OCSP stapling and check only leaf certificate\nmy $client = IO::Socket::SSL->new($dst);\n\n# better yet: require checking of full chain\nmy $client = IO::Socket::SSL->new(\nPeerAddr => $dst,\nSSLocspmode => SSLOCSPFULLCHAIN,\n);\n\n# even better: make OCSP errors fatal\n# (this will probably fail with lots of sites because of bad OCSP setups)\n# also use common OCSP response cache\nmy $ocspcache = IO::Socket::SSL::OCSPCache->new;\nmy $client = IO::Socket::SSL->new(\nPeerAddr => $dst,\nSSLocspmode => SSLOCSPFULLCHAIN|SSLOCSPFAILHARD,\nSSLocspcache => $ocspcache,\n);\n\n# disable OCSP stapling in case server has problems with it\nmy $client = IO::Socket::SSL->new(\nPeerAddr => $dst,\nSSLocspmode => SSLOCSPNOSTAPLE,\n);\n\n# check any certificates which are not yet checked by OCSP stapling or\n# where we have already cached results. For your own resolving combine\n# $ocsp->requests with $ocsp->addresponse(uri,response).\nmy $ocsp = $client->ocspresolver();\nmy $errors = $ocsp->resolveblocking();\nif ($errors) {\nwarn \"OCSP verification failed: $errors\";\nclose($client);\n}\n", "subsections": [] }, "Basic SSL Server": { "content": "A basic SSL server looks similar to other IO::Socket servers, only that it also contains\nsettings for certificate and key:\n\n# simple server\nmy $server = IO::Socket::SSL->new(\n# where to listen\nLocalAddr => '127.0.0.1',\nLocalPort => 8080,\nListen => 10,\n\n# which certificate to offer\n# with SNI support there can be different certificates per hostname\nSSLcertfile => 'cert.pem',\nSSLkeyfile => 'key.pem',\n) or die \"failed to listen: $!\";\n\n# accept client\nmy $client = $server->accept or die\n\"failed to accept or ssl handshake: $!,$SSLERROR\";\n\nThis will automatically use a secure set of ciphers and SSL version and also supports Forward\nSecrecy with (Elliptic-Curve) Diffie-Hellmann Key Exchange.\n\nIf you are doing a forking or threading server, we recommend that you do the SSL handshake\ninside the new process/thread so that the master is free for new connections. We recommend this\nbecause a client with improper or slow SSL handshake could make the server block in the\nhandshake which would be bad to do on the listening socket:\n\n# inet server\nmy $server = IO::Socket::INET->new(\n# where to listen\nLocalAddr => '127.0.0.1',\nLocalPort => 8080,\nListen => 10,\n);\n\n# accept client\nmy $client = $server->accept or die;\n\n# SSL upgrade client (in new process/thread)\nIO::Socket::SSL->startSSL($client,\nSSLserver => 1,\nSSLcertfile => 'cert.pem',\nSSLkeyfile => 'key.pem',\n) or die \"failed to ssl handshake: $SSLERROR\";\n\nLike with normal sockets, neither forking nor threading servers scale well. It is recommended to\nuse non-blocking sockets instead, see \"Using Non-Blocking Sockets\"\n", "subsections": [] }, "Common Usage Errors": { "content": "This is a list of typical errors seen with the use of IO::Socket::SSL:\n\n* Disabling verification with \"SSLverifymode\".\n\nAs described in \"Essential Information About SSL/TLS\", a proper identification of the peer\nis essential and failing to verify makes Man-In-The-Middle attacks possible.\n\nNevertheless, lots of scripts and even public modules or applications disable verification,\nbecause it is probably the easiest way to make the thing work and usually nobody notices any\nsecurity problems anyway.\n\nIf the verification does not succeed with the default settings, one can do the following:\n\n* Make sure the needed CAs are in the store, maybe use \"SSLcafile\" or \"SSLcapath\"\nto specify a different CA store.\n\n* If the validation fails because the certificate is self-signed and that's what you\nexpect, you can use the \"SSLfingerprint\" option to accept specific leaf\ncertificates by their certificate or pubkey fingerprint.\n\n* If the validation failed because the hostname does not match and you cannot access\nthe host with the name given in the certificate, you can use \"SSLverifycnname\" to\nspecify the hostname you expect in the certificate.\n\nA common error pattern is also to disable verification if they found no CA store (different\nmodules look at different \"default\" places). Because IO::Socket::SSL is now able to provide\na usable CA store on most platforms (UNIX, Mac OSX and Windows) it is better to use the\ndefaults provided by IO::Socket::SSL. If necessary these can be checked with the\n\"defaultca\" method.\n\n* Polling of SSL sockets (e.g. select, poll and other event loops).\n\nIf you sysread one byte on a normal socket it will result in a syscall to read one byte.\nThus, if more than one byte is available on the socket it will be kept in the network stack\nof your OS and the next select or poll call will return the socket as readable. But, with\nSSL you don't deliver single bytes. Multiple data bytes are packaged and encrypted together\nin an SSL frame. Decryption can only be done on the whole frame, so a sysread for one byte\nactually reads the complete SSL frame from the socket, decrypts it and returns the first\ndecrypted byte. Further sysreads will return more bytes from the same frame until all bytes\nare returned and the next SSL frame will be read from the socket.\n\nThus, in order to decide if you can read more data (e.g. if sysread will block) you must\ncheck if there are still data in the current SSL frame by calling \"pending\" and if there are\nno data pending you might check the underlying socket with select or poll. Another way might\nbe if you try to sysread at least 16kByte all the time. 16kByte is the maximum size of an\nSSL frame and because sysread returns data from only a single SSL frame you can guarantee\nthat there are no pending data.\n\nAdditionally, contrary to plain sockets the data delivered on the socket are not necessarily\napplication payload. It might be a TLS handshake, it might just be the beginning of a TLS\nrecord or it might be TLS session tickets which are send after the TLS handshake in TLS 1.3.\nIn such situations select will return that data are available for read since it only looks\nat the plain socket. A sysread on the IO::Socket::SSL socket will not return any data though\nsince it is an abstraction which only returns application data. This causes the sysread to\nhang in case the socket was blocking or to return an error with EAGAIN on non-blocking\nsockets. Applications using select or similar should therefore set the socket to\nnon-blocking and also expect that the sysread might temporarily fail with EAGAIN.\n\nSee also \"Using Non-Blocking Sockets\".\n\n* Expecting exactly the same behavior as plain sockets.\n\nIO::Socket::SSL tries to emulate the usual socket behavior as good as possible, but full\nemulation can not be done. Specifically a read on the SSL socket might also result in a\nwrite on the TCP socket or a write on the SSL socket might result in a read on the TCP\nsocket. Also \"accept\" and close on the SSL socket will result in writing and reading data to\nthe TCP socket too.\n\nEspecially the hidden writes might result in a connection reset if the underlying TCP socket\nis already closed by the peer. Unless signal PIPE is explicitly handled by the application\nthis will usually result in the application crashing. It is thus recommended to explicitly\nIGNORE signal PIPE so that the errors get propagated as EPIPE instead of causing a crash of\nthe application.\n\n* Set 'SSLversion' or 'SSLcipherlist' to a \"better\" value.\n\nIO::Socket::SSL tries to set these values to reasonable, secure values which are compatible\nwith the rest of the world. But, there are some scripts or modules out there which tried to\nbe smart and get more secure or compatible settings. Unfortunately, they did this years ago\nand never updated these values, so they are still forced to do only 'TLSv1' (instead of also\nusing TLSv12 or TLSv11). Or they set 'HIGH' as the cipher list and thought they were secure,\nbut did not notice that 'HIGH' includes anonymous ciphers, e.g. without identification of\nthe peer.\n\nSo it is recommended to leave the settings at the secure defaults which IO::Socket::SSL sets\nand which get updated from time to time to better fit the real world.\n\n* Make SSL settings inaccessible by the user, together with bad builtin settings.\n\nSome modules use IO::Socket::SSL, but don't make the SSL settings available to the user.\nThis is often combined with bad builtin settings or defaults (like switching verification\noff).\n\nThus the user needs to hack around these restrictions by using \"setargsfilterhack\" or\nsimilar.\n\n* Use of constants as strings.\n\nConstants like \"SSLVERIFYPEER\" or \"SSLWANTREAD\" should be used as constants and not be\nput inside quotes, because they represent numerical values.\n\n* Forking and handling the socket in parent and child.\n\nA fork of the process will duplicate the internal user space SSL state of the socket. If\nboth master and child interact with the socket by using their own SSL state strange error\nmessages will happen. Such interaction includes explicit or implicit close of the SSL\nsocket. To avoid this the socket should be explicitly closed with SSLnoshutdown.\n\n* Forking and executing a new process.\n\nSince the SSL state is stored in user space it will be duplicated by a fork but it will be\nlost when doing exec. This means it is not possible to simply redirect stdin and stdout for\nthe new process to the SSL socket by duplicating the relevant file handles. Instead\nexplicitly exchanging plain data between child-process and SSL socket are needed.\n", "subsections": [] }, "Common Problems with SSL": { "content": "SSL is a complex protocol with multiple implementations and each of these has their own quirks.\nWhile most of these implementations work together, it often gets problematic with older\nversions, minimal versions in load balancers, or plain wrong setups.\n\nUnfortunately these problems are hard to debug. Helpful for debugging are a knowledge of SSL\ninternals, wireshark and the use of the debug settings of IO::Socket::SSL and Net::SSLeay, which\ncan both be set with $IO::Socket::SSL::DEBUG. The following debugs levels are defined, but used\nnot in any consistent way:\n\n* 0 - No debugging (default).\n\n* 1 - Print out errors from IO::Socket::SSL and ciphers from Net::SSLeay.\n\n* 2 - Print also information about call flow from IO::Socket::SSL and progress information\nfrom Net::SSLeay.\n\n* 3 - Print also some data dumps from IO::Socket::SSL and from Net::SSLeay.\n\nAlso, \"analyze-ssl.pl\" from the ssl-tools repository at \nmight be a helpful tool when debugging SSL problems, as do the \"openssl\" command line tool and a\ncheck with a different SSL implementation (e.g. a web browser).\n\nThe following problems are not uncommon:\n\n* Bad server setup: missing intermediate certificates.\n\nIt is a regular problem that administrators fail to include all necessary certificates into\ntheir server setup, e.g. everything needed to build the trust chain from the trusted root.\nIf they check the setup with the browser everything looks ok, because browsers work around\nthese problems by caching any intermediate certificates and apply them to new connections if\ncertificates are missing.\n\nBut, fresh browser profiles which have never seen these intermediates cannot fill in the\nmissing certificates and fail to verify; the same is true with IO::Socket::SSL.\n\n* Old versions of servers or load balancers which do not understand specific TLS versions or\ncroak on specific data.\n\nFrom time to time one encounters an SSL peer, which just closes the connection inside the\nSSL handshake. This can usually be worked around by downgrading the SSL version, e.g. by\nsetting \"SSLversion\". Modern Browsers usually deal with such servers by automatically\ndowngrading the SSL version and repeat the connection attempt until they succeed.\n\nWorse servers do not close the underlying TCP connection but instead just drop the relevant\npacket. This is harder to detect because it looks like a stalled connection. But downgrading\nthe SSL version often works here too.\n\nA cause of such problems are often load balancers or security devices, which have hardware\nacceleration and only a minimal (and less robust) SSL stack. They can often be detected\nbecause they support much fewer ciphers than other implementations.\n\n* Bad or old OpenSSL versions.\n\nIO::Socket::SSL uses OpenSSL with the help of the Net::SSLeay library. It is recommend to\nhave a recent version of this library, because it has more features and usually fewer known\nbugs.\n\n* Validation of client certificates fail.\n\nMake sure that the purpose of the certificate allows use as ssl client (check with \"openssl\nx509 -purpose\", that the necessary root certificate is in the path specified by \"SSLca*\"\n(or the default path) and that any intermediate certificates needed to build the trust chain\nare sent by the client.\n\n* Validation of self-signed certificate fails even if it is given with \"SSLca*\" argument.\n\nThe \"SSLca*\" arguments do not give a general trust store for arbitrary certificates but\nonly specify a store for CA certificates which then can be used to verify other\ncertificates. This especially means that certificates which are not a CA get simply ignored,\nnotably self-signed certificates which do not also have the CA-flag set.\n\nThis behavior of OpenSSL differs from the more general trust-store concept which can be\nfound in browsers and where it is possible to simply added arbitrary certificates (CA or\nnot) as trusted.\n", "subsections": [] }, "Using Non-Blocking Sockets": { "content": "If you have a non-blocking socket, the expected behavior on read, write, accept or connect is to\nset $! to EWOULDBLOCK if the operation cannot be completed immediately. Note that EWOULDBLOCK is\nthe same as EAGAIN on UNIX systems, but is different on Windows.\n\nWith SSL, handshakes might occur at any time, even within an established connection. In these\ncases it is necessary to finish the handshake before you can read or write data. This might\nresult in situations where you want to read but must first finish the write of a handshake or\nwhere you want to write but must first finish a read. In these cases $! is set to EAGAIN like\nexpected, and additionally $SSLERROR is set to either SSLWANTREAD or SSLWANTWRITE. Thus if\nyou get EWOULDBLOCK on a SSL socket you must check $SSLERROR for SSLWANT* and adapt your\nevent mask accordingly.\n\nUsing readline on non-blocking sockets does not make much sense and I would advise against using\nit. And, while the behavior is not documented for other IO::Socket classes, it will try to\nemulate the behavior seen there, e.g. to return the received data instead of blocking, even if\nthe line is not complete. If an unrecoverable error occurs it will return nothing, even if it\nalready received some data.\n\nAlso, I would advise against using \"accept\" with a non-blocking SSL object because it might\nblock and this is not what most would expect. The reason for this is that \"accept\" on a\nnon-blocking TCP socket (e.g. IO::Socket::IP, IO::Socket::INET..) results in a new TCP socket\nwhich does not inherit the non-blocking behavior of the master socket. And thus, the initial SSL\nhandshake on the new socket inside \"IO::Socket::SSL::accept\" will be done in a blocking way. To\nwork around this you are safer by doing a TCP accept and later upgrade the TCP socket in a\nnon-blocking way with \"startSSL\" and \"acceptSSL\".\n\nmy $cl = IO::Socket::SSL->new($dst);\n$cl->blocking(0);\nmy $sel = IO::Select->new($cl);\nwhile (1) {\n# with SSL a call for reading n bytes does not result in reading of n\n# bytes from the socket, but instead it must read at least one full SSL\n# frame. If the socket has no new bytes, but there are unprocessed data\n# from the SSL frame canread will block!\n\n# wait for data on socket\n$sel->canread();\n\n# new data on socket or eof\nREAD:\n# this does not read only 1 byte from socket, but reads the complete SSL\n# frame and then just returns one byte. On subsequent calls it than\n# returns more byte of the same SSL frame until it needs to read the\n# next frame.\nmy $n = sysread( $cl,my $buf,1);\nif ( ! defined $n ) {\ndie $! if not $!{EWOULDBLOCK};\nnext if $SSLERROR == SSLWANTREAD;\nif ( $SSLERROR == SSLWANTWRITE ) {\n# need to write data on renegotiation\n$sel->canwrite;\nnext;\n}\ndie \"something went wrong: $SSLERROR\";\n} elsif ( ! $n ) {\nlast; # eof\n} else {\n# read next bytes\n# we might have still data within the current SSL frame\n# thus first process these data instead of waiting on the underlying\n# socket object\ngoto READ if $cl->pending; # goto sysread\nnext; # goto $sel->canread\n}\n}\n\nAdditionally there are differences to plain sockets when using select, poll, kqueue or similar\ntechnologies to get notified if data are available. Relying only on these calls is not\nsufficient in all cases since unread data might be internally buffered in the SSL stack. To\ndetect such buffering pending() need to be used. Alternatively the buffering can be avoided by\nusing sysread with the maximum size of an SSL frame. See \"Common Usage Errors\" for details.\n", "subsections": [] }, "Advanced Usage": { "content": "SNI Support\nNewer extensions to SSL can distinguish between multiple hostnames on the same IP address using\nServer Name Indication (SNI).\n\nSupport for SNI on the client side was added somewhere in the OpenSSL 0.9.8 series, but with 1.0\na bug was fixed when the server could not decide about its hostname. Therefore client side SNI\nis only supported with OpenSSL 1.0 or higher in IO::Socket::SSL. With a supported version, SNI\nis used automatically on the client side, if it can determine the hostname from \"PeerAddr\" or\n\"PeerHost\" (which are synonyms in the underlying IO::Socket:: classes and thus should never be\nset both or at least not to different values). On unsupported OpenSSL versions it will silently\nnot use SNI. The hostname can also be given explicitly given with \"SSLhostname\", but in this\ncase it will throw in error, if SNI is not supported. To check for support you might call\n\"IO::Socket::SSL->canclientsni()\".\n\nOn the server side, earlier versions of OpenSSL are supported, but only together with\nNet::SSLeay version >= 1.50. To check for support you might call\n\"IO::Socket::SSL->canserversni()\". If server side SNI is supported, you might specify\ndifferent certificates per host with \"SSLcert*\" and \"SSLkey*\", and check the requested name\nusing \"getservername\".\n", "subsections": [ { "name": "Talk Plain and SSL With The Same Socket", "content": "It is often required to first exchange some plain data and then upgrade the socket to SSL after\nsome kind of STARTTLS command. Protocols like FTPS even need a way to downgrade the socket again\nback to plain.\n\nThe common way to do this would be to create a normal socket and use \"startSSL\" to upgrade and\nstopSSL to downgrade:\n\nmy $sock = IO::Socket::INET->new(...) or die $!;\n... exchange plain data on $sock until starttls command ...\nIO::Socket::SSL->startSSL($sock,%sslargs) or die $SSLERROR;\n... now $sock is an IO::Socket::SSL object ...\n... exchange data with SSL on $sock until stoptls command ...\n$sock->stopSSL or die $SSLERROR;\n... now $sock is again an IO::Socket::INET object ...\n\nBut, lots of modules just derive directly from IO::Socket::INET. While this base class can be\nreplaced with IO::Socket::SSL, these modules cannot easily support different base classes for\nSSL and plain data and switch between these classes on a starttls command.\n\nTo help in this case, IO::Socket::SSL can be reduced to a plain socket on startup, and\nconnectSSL/acceptSSL/startSSL can be used to enable SSL and \"stopSSL\" to talk plain again:\n\nmy $sock = IO::Socket::SSL->new(\nPeerAddr => ...\nSSLstartHandshake => 0,\n%sslargs\n) or die $!;\n... exchange plain data on $sock until starttls command ...\n$sock->connectSSL or die $SSLERROR;\n... now $sock is an IO::Socket::SSL object ...\n... exchange data with SSL on $sock until stoptls command ...\n$sock->stopSSL or die $SSLERROR;\n... $sock is still an IO::Socket::SSL object ...\n... but data exchanged again in plain ...\n" } ] }, "Integration Into Own Modules": { "content": "IO::Socket::SSL behaves similarly to other IO::Socket modules and thus could be integrated in\nthe same way, but you have to take special care when using non-blocking I/O (like for handling\ntimeouts) or using select or poll. Please study the documentation on how to deal with these\ndifferences.\n\nAlso, it is recommended to not set or touch most of the \"SSL*\" options, so that they keep their\nsecure defaults. It is also recommended to let the user override these SSL specific settings\nwithout the need of global settings or hacks like \"setargsfilterhack\".\n\nThe notable exception is \"SSLverifycnscheme\". This should be set to the hostname verification\nscheme required by the module or protocol.\n", "subsections": [] }, "Description Of Methods": { "content": "IO::Socket::SSL inherits from another IO::Socket module. The choice of the super class depends\non the installed modules:\n\n* If IO::Socket::IP with at least version 0.20 is installed it will use this module as super\nclass, transparently providing IPv6 and IPv4 support.\n\n* If IO::Socket::INET6 is installed it will use this module as super class, transparently\nproviding IPv6 and IPv4 support.\n\n* Otherwise it will fall back to IO::Socket::INET, which is a perl core module. With\nIO::Socket::INET you only get IPv4 support.\n\nPlease be aware that with the IPv6 capable super classes, it will look first for the IPv6\naddress of a given hostname. If the resolver provides an IPv6 address, but the host cannot be\nreached by IPv6, there will be no automatic fallback to IPv4. To avoid these problems you can\nenforce IPv4 for a specific socket by using the \"Domain\" or \"Family\" option with the value\nAFINET as described in IO::Socket::IP. Alternatively you can enforce IPv4 globally by loading\nIO::Socket::SSL with the option 'inet4', in which case it will use the IPv4 only class\nIO::Socket::INET as the super class.\n\nIO::Socket::SSL will provide all of the methods of its super class, but sometimes it will\noverride them to match the behavior expected from SSL or to provide additional arguments.\n\nThe new or changed methods are described below, but please also read the section about SSL\nspecific error handling.\n\nError Handling\nIf an SSL specific error occurs, the global variable $SSLERROR will be set. If the error\noccurred on an existing SSL socket, the method \"errstr\" will give access to the latest\nsocket specific error. Both $SSLERROR and the \"errstr\" method give a dualvar similar to $!,\ne.g. providing an error number in numeric context or an error description in string context.\n", "subsections": [ { "name": "new", "content": "Creates a new IO::Socket::SSL object. You may use all the friendly options that came bundled\nwith the super class (e.g. IO::Socket::IP, IO::Socket::INET, ...) plus (optionally) the ones\ndescribed below. If you don't specify any SSL related options it will do its best in using\nsecure defaults, e.g. choosing good ciphers, enabling proper verification, etc.\n\nSSLserver\nSet this option to a true value if the socket should be used as a server. If this is not\nexplicitly set it is assumed if the \"Listen\" parameter is given when creating the socket.\n\nSSLhostname\nThis can be given to specify the hostname used for SNI, which is needed if you have\nmultiple SSL hostnames on the same IP address. If not given it will try to determine the\nhostname from \"PeerAddr\", which will fail if only an IP was given or if this argument is\nused within \"startSSL\".\n\nIf you want to disable SNI, set this argument to ''.\n\nCurrently only supported for the client side and will be ignored for the server side.\n\nSee section \"SNI Support\" for details of SNI the support.\n\nSSLstartHandshake\nIf this option is set to false (defaults to true) it will not start the SSL handshake yet.\nThis has to be done later with \"acceptSSL\" or \"connectSSL\". Before the handshake is\nstarted read/write/etc. can be used to exchange plain data.\n\nSSLkeepSocketOnError\nIf this option is set to true (defaults to false) it will not close the underlying TCP\nsocket on errors. In most cases there is no real use for this behavior since both sides of\nthe TCP connection will probably have a different idea of the current state of the\nconnection.\n\nSSLca | SSLcafile | SSLcapath\nUsually you want to verify that the peer certificate has been signed by a trusted\ncertificate authority. In this case you should use this option to specify the file\n(\"SSLcafile\") or directory (\"SSLcapath\") containing the certificate(s) of the trusted\ncertificate authorities.\n\n\"SSLcapath\" can also be an array or a string containing multiple path, where the path\nare separated by the platform specific separator. This separator is \";\" on DOS, Windows,\nNetware, \",\" on VMS and \":\" for all the other systems. If multiple path are given at least\none of these must be accessible.\n\nYou can also give a list of X509* certificate handles (like you get from Net::SSLeay or\nIO::Socket::SSL::Utils::PEMxxx2cert) with \"SSLca\". These will be added to the CA store\nbefore path and file and thus take precedence. If neither SSLca, nor SSLcafile or\nSSLcapath are set it will use \"defaultca()\" to determine the user-set or system\ndefaults. If you really don't want to set a CA set SSLcafile or SSLcapath to \"\\undef\"\nor SSLca to an empty list. (unfortunately '' is used by some modules using\nIO::Socket::SSL when CA is not explicitly given).\n\nSSLclientca | SSLclientcafile\nIf verifymode is VERIFYPEER on the server side these options can be used to set the list\nof acceptable CAs for the client. This way the client can select they required certificate\nfrom a list of certificates. The value for these options is similar to \"SSLca\" and\n\"SSLcafile\".\n\nSSLfingerprint\nSometimes you have a self-signed certificate or a certificate issued by an unknown CA and\nyou really want to accept it, but don't want to disable verification at all. In this case\nyou can specify the fingerprint of the certificate as 'algo$hexfingerprint'. \"algo\" is a\nfingerprint algorithm supported by OpenSSL, e.g. 'sha1','sha256'... and \"hexfingerprint\"\nis the hexadecimal representation of the binary fingerprint. Any colons inside the hex\nstring will be ignored.\n\nIf you want to use the fingerprint of the pubkey inside the certificate instead of the\ncertificate use the syntax 'algo$pub$hexfingerprint' instead. To get the fingerprint of\nan established connection you can use \"getfingerprint\".\n\nIt is also possible to skip \"algo$\", i.e. only specify the fingerprint. In this case the\nlikely algorithms will be automatically detected based on the length of the digest string.\n\nYou can specify a list of fingerprints in case you have several acceptable certificates.\nIf a fingerprint matches the topmost (i.e. leaf) certificate no additional validations can\nmake the verification fail.\n\nSSLcertfile | SSLcert | SSLkeyfile | SSLkey\nIf you create a server you usually need to specify a server certificate which should be\nverified by the client. Same is true for client certificates, which should be verified by\nthe server. The certificate can be given as a file with SSLcertfile or as an internal\nrepresentation of an X509* object (like you get from Net::SSLeay or\nIO::Socket::SSL::Utils::PEMxxx2cert) with SSLcert. If given as a file it will\nautomatically detect the format. Supported file formats are PEM, DER and PKCS#12, where\nPEM and PKCS#12 can contain the certificate and the chain to use, while DER can only\ncontain a single certificate.\n\nIf given as a list of X509* please note, that the all the chain certificates (e.g. all\nexcept the first) will be \"consumed\" by openssl and will be freed if the SSL context gets\ndestroyed - so you should never free them yourself. But the servers certificate (e.g. the\nfirst) will not be consumed by openssl and thus must be freed by the application.\n\nFor each certificate a key is need, which can either be given as a file with SSLkeyfile\nor as an internal representation of an EVPPKEY* object with SSLkey (like you get from\nNet::SSLeay or IO::Socket::SSL::Utils::PEMxxx2key). If a key was already given within the\nPKCS#12 file specified by SSLcertfile it will ignore any SSLkey or SSLkeyfile. If no\nSSLkey or SSLkeyfile was given it will try to use the PEM file given with SSLcertfile\nagain, maybe it contains the key too.\n\nIf your SSL server should be able to use different certificates on the same IP address,\ndepending on the name given by SNI, you can use a hash reference instead of a file with\n\">.\n\nIf your SSL server should be able to use both RSA and ECDSA certificates for the same\ndomain/IP a similar hash reference like with SNI is given. The domain names used to\nspecify the additional certificates should be \"hostname%whatever\", i.e. \"hostname%ecc\" or\nsimilar. This needs at least OpenSSL 1.0.2. To let the server pick the certificate based\non the clients cipher preference \"SSLhonorcipherorder\" should be set to false.\n\nIn case certs and keys are needed but not given it might fall back to builtin defaults,\nsee \"Defaults for Cert, Key and CA\".\n\nExamples:\n\nSSLcertfile => 'mycert.pem',\nSSLkeyfile => 'mykey.pem',\n\nSSLcertfile => {\n\"foo.example.org\" => 'foo-cert.pem',\n\"foo.example.org%ecc\" => 'foo-ecc-cert.pem',\n\"bar.example.org\" => 'bar-cert.pem',\n# used when nothing matches or client does not support SNI\n'' => 'default-cert.pem',\n'%ecc' => 'default-ecc-cert.pem',\n},\nSSLkeyfile => {\n\"foo.example.org\" => 'foo-key.pem',\n\"foo.example.org%ecc\" => 'foo-ecc-key.pem',\n\"bar.example.org\" => 'bar-key.pem',\n# used when nothing matches or client does not support SNI\n'' => 'default-key.pem',\n'%ecc' => 'default-ecc-key.pem',\n}\n\nSSLpasswdcb\nIf your private key is encrypted, you might not want the default password prompt from\nNet::SSLeay. This option takes a reference to a subroutine that should return the password\nrequired to decrypt your private key.\n\nSSLusecert\nIf this is true, it forces IO::Socket::SSL to use a certificate and key, even if you are\nsetting up an SSL client. If this is set to 0 (the default), then you will only need a\ncertificate and key if you are setting up a server.\n\nSSLusecert will implicitly be set if SSLserver is set. For convenience it is also set\nif it was not given but a cert was given for use (SSLcertfile or similar).\n\nSSLversion\nSets the version of the SSL protocol used to transmit data. 'SSLv23' uses a handshake\ncompatible with SSL2.0, SSL3.0 and TLS1.x, while 'SSLv2', 'SSLv3', 'TLSv1', 'TLSv11',\n'TLSv12', or 'TLSv13' restrict handshake and protocol to the specified version. All\nvalues are case-insensitive. Instead of 'TLSv11', 'TLSv12', and 'TLSv13' one can also\nuse 'TLSv11', 'TLSv12', and 'TLSv13'. Support for 'TLSv11', 'TLSv12', and 'TLSv13'\nrequires recent versions of Net::SSLeay and openssl.\n\nIndependent from the handshake format you can limit to set of accepted SSL versions by\nadding !version separated by ':'.\n\nThe default SSLversion is 'SSLv23:!SSLv3:!SSLv2' which means, that the handshake format\nis compatible to SSL2.0 and higher, but that the successful handshake is limited to TLS1.0\nand higher, that is no SSL2.0 or SSL3.0 because both of these versions have serious\nsecurity issues and should not be used anymore. You can also use !TLSv11 and !TLSv12 to\ndisable TLS versions 1.1 and 1.2 while still allowing TLS version 1.0.\n\nSetting the version instead to 'TLSv1' might break interaction with older clients, which\nneed and SSL2.0 compatible handshake. On the other side some clients just close the\nconnection when they receive a TLS version 1.1 request. In this case setting the version\nto 'SSLv23:!SSLv2:!SSLv3:!TLSv11:!TLSv12' might help.\n\nSSLcipherlist\nIf this option is set the cipher list for the connection will be set to the given value,\ne.g. something like 'ALL:!LOW:!EXP:!aNULL'. This will only affect ciphers for TLS 1.2 and\nlower. See the OpenSSL documentation\n() for\nmore details.\n\nUnless you fail to contact your peer because of no shared ciphers it is recommended to\nleave this option at the default setting, which uses the system default but disables some\ninsecure ciphers which might still be enabled on older systems.\n\nIn case different cipher lists are needed for different SNI hosts a hash can be given with\nthe host as key and the cipher suite as value, similar to SSLcert*.\n\nSSLciphersuites\nIf this option is set the TLS 1.3 ciphersuites for the connection will be set to the given\nvalue. This is similar to SSLcipherlist, but only for TLS 1.3 ciphers. See argument\n\"-ciphersuits\" in the OpenSSL documentation\n() for details.\n\nUnless you fail to contact your peer because of no shared ciphers it is recommended to\nleave this option at the default setting, which uses the system default.\n\nIn case different cipher lists are needed for different SNI hosts a hash can be given with\nthe host as key and the cipher suite as value, similar to SSLcert*.\n\nSSLhonorcipherorder\nIf this option is true the cipher order the server specified is used instead of the order\nproposed by the client. This option defaults to true to make use of our secure cipher list\nsetting.\n\nSSLdhfile\nTo create a server which provides forward secrecy you need to either give the DH\nparameters or (better, because faster) the ECDH curve. This setting cares about DH\nparameters.\n\nTo support non-elliptic Diffie-Hellman key exchange a suitable file needs to be given here\nor the SSLdh should be used with an appropriate value. See dhparam command in openssl for\nmore information.\n\nIf neither \"SSLdhfile\" nor \"SSLdh\" are set a builtin DH parameter with a length of 2048\nbit is used to offer DH key exchange by default. If you don't want this (e.g. disable DH\nkey exchange) explicitly set this or the \"SSLdh\" parameter to undef.\n\nSSLdh\nLike SSLdhfile, but instead of giving a file you use a preloaded or generated DH*.\n\nSSLecdhcurve\nTo create a server which provides forward secrecy you need to either give the DH\nparameters or (better, because faster) the ECDH curve. This setting cares about the ECDH\ncurve(s).\n\nTo support Elliptic Curve Diffie-Hellmann key exchange the OID or NID of at least one\nsuitable curve needs to be provided here.\n\nWith OpenSSL 1.1.0+ this parameter defaults to \"auto\", which means that it lets OpenSSL\npick the best settings. If support for CTXsetecdhauto is implemented in Net::SSLeay\n(needs at least version 1.86) it will use this to implement the same default. Otherwise it\nwill default to \"prime256v1\" (builtin of OpenSSL) in order to offer ECDH key exchange by\ndefault.\n\nIf setting groups or curves is supported by Net::SSLeay (needs at least version 1.86) then\nmultiple curves can be given here in the order of the preference, i.e.\n\"P-521:P-384:P-256\". When used at the client side this will include the supported curves\nas extension in the TLS handshake.\n\nIf you don't want to have ECDH key exchange this could be set to undef or set\n\"SSLciphers\" to exclude all of these ciphers.\n\nYou can check if ECDH support is available by calling \"IO::Socket::SSL->canecdh\".\n\nSSLverifymode\nThis option sets the verification mode for the peer certificate. You may combine\nSSLVERIFYPEER (verifypeer), SSLVERIFYFAILIFNOPEERCERT (fail verification if no\npeer certificate exists; ignored for clients), SSLVERIFYCLIENTONCE (verify client once;\nignored for clients). See OpenSSL man page for SSLCTXsetverify for more information.\n\nThe default is SSLVERIFYNONE for server (e.g. no check for client certificate) and\nSSLVERIFYPEER for client (check server certificate).\n\nSSLverifycallback\nIf you want to verify certificates yourself, you can pass a sub reference along with this\nparameter to do so. When the callback is called, it will be passed:\n\n1. a true/false value that indicates what OpenSSL thinks of the certificate,\n2. a C-style memory address of the certificate store,\n3. a string containing the certificate's issuer attributes and owner attributes, and\n4. a string containing any errors encountered (0 if no errors).\n5. a C-style memory address of the peer's own certificate (convertible to PEM form with\nNet::SSLeay::PEMgetstringX509()).\n6. The depth of the certificate in the chain. Depth 0 is the leaf certificate.\n\nThe function should return 1 or 0, depending on whether it thinks the certificate is valid\nor invalid. The default is to let OpenSSL do all of the busy work.\n\nThe callback will be called for each element in the certificate chain.\n\nSee the OpenSSL documentation for SSLCTXsetverify for more information.\n\nSSLverifycnscheme\nThe scheme is used to correctly verify the identity inside the certificate by using the\nhostname of the peer. See the information about the verification schemes in\nverifyhostname.\n\nIf you don't specify a scheme it will use 'default', but only complain loudly if the name\nverification fails instead of letting the whole certificate verification fail. THIS WILL\nCHANGE, e.g. it will let the certificate verification fail in the future if the hostname\ndoes not match the certificate !!!! To override the name used in verification use\nSSLverifycnname.\n\nThe scheme 'default' is a superset of the usual schemes, which will accept the hostname in\ncommon name and subjectAltName and allow wildcards everywhere. While using this scheme is\nway more secure than no name verification at all you better should use the scheme specific\nto your application protocol, e.g. 'http', 'ftp'...\n\nIf you are really sure, that you don't want to verify the identity using the hostname you\ncan use 'none' as a scheme. In this case you'd better have alternative forms of\nverification, like a certificate fingerprint or do a manual verification later by calling\nverifyhostname yourself.\n\nSSLverifycnpublicsuffix\nThis option is used to specify the behavior when checking wildcards certificates for\npublic suffixes, e.g. no wildcard certificates for *.com or *.co.uk should be accepted,\nwhile *.example.com or *.example.co.uk is ok.\n\nIf not specified it will simply use the builtin default of IO::Socket::SSL::PublicSuffix,\nyou can create another object with fromstring or fromfile of this module.\n\nTo disable verification of public suffix set this option to ''.\n\nSSLverifycnname\nSet the name which is used in verification of hostname. If SSLverifycnscheme is set and\nno SSLverifycnname is given it will try to use SSLhostname or PeerHost and PeerAddr\nsettings and fail if no name can be determined. If SSLverifycnscheme is not set it will\nuse a default scheme and warn if it cannot determine a hostname, but it will not fail.\n\nUsing PeerHost or PeerAddr works only if you create the connection directly with\n\"IO::Socket::SSL->new\", if an IO::Socket::INET object is upgraded with startSSL the name\nhas to be given in SSLverifycnname or SSLhostname.\n\nSSLcheckcrl\nIf you want to verify that the peer certificate has not been revoked by the signing\nauthority, set this value to true. OpenSSL will search for the CRL in your SSLcapath, or\nuse the file specified by SSLcrlfile. See the Net::SSLeay documentation for more\ndetails. Note that this functionality appears to be broken with OpenSSL < v0.9.7b, so its\nuse with lower versions will result in an error.\n\nSSLcrlfile\nIf you want to specify the CRL file to be used, set this value to the pathname to be used.\nThis must be used in addition to setting SSLcheckcrl.\n\nSSLocspmode\nDefines how certificate revocation is done using OCSP (Online Status Revocation Protocol).\nThe default is to send a request for OCSP stapling to the server and if the server sends\nan OCSP response back the result will be used.\n\nAny other OCSP checking needs to be done manually with \"ocspresolver\".\n\nThe following flags can be combined with \"|\":\n\nSSLOCSPNOSTAPLE\nDon't ask for OCSP stapling. This is the default if SSLverifymode is\nVERIFYNONE.\n\nSSLOCSPTRYSTAPLE\nTry OCSP stapling, but don't complain if it gets no stapled response back. This is\nthe default if SSLverifymode is VERIFYPEER (the default).\n\nSSLOCSPMUSTSTAPLE\nConsider it a hard error, if the server does not send a stapled OCSP response\nback. Most servers currently send no stapled OCSP response back.\n\nSSLOCSPFAILHARD\nFail hard on response errors, default is to fail soft like the browsers do. Soft\nerrors mean, that the OCSP response is not usable, e.g. no response, error\nresponse, no valid signature etc. Certificate revocations inside a verified\nresponse are considered hard errors in any case.\n\nSoft errors inside a stapled response are never considered hard, e.g. it is\nexpected that in this case an OCSP request will be send to the responsible OCSP\nresponder.\n\nSSLOCSPFULLCHAIN\nThis will set up the \"ocspresolver\" so that all certificates from the peer chain\nwill be checked, otherwise only the leaf certificate will be checked against\nrevocation.\n\nSSLocspstaplecallback\nIf this callback is defined, it will be called with the SSL object and the OCSP response\nhandle obtained from the peer, e.g. \"<$cb-\"($ssl,$resp)>>. If the peer did not provide a\nstapled OCSP response the function will be called with \"$resp=undef\". Because the OCSP\nresponse handle is no longer valid after leaving this function it should not by copied or\nfreed. If access to the response is necessary after leaving this function it can be\nserialized with \"Net::SSLeay::i2dOCSPRESPONSE\".\n\nIf no such callback is provided, it will use the default one, which verifies the response\nand uses it to check if the certificate(s) of the connection got revoked.\n\nSSLocspcache\nWith this option a cache can be given for caching OCSP responses, which could be shared\nbetween different SSL contexts. If not given a cache specific to the SSL context only will\nbe used.\n\nYou can either create a new cache with \"IO::Socket::SSL::OCSPCache->new([size])\" or\nimplement your own cache, which needs to have methods \"put($key,\\%entry)\" and \"get($key)\"\n(returning \"\\%entry\") where entry is the hash representation of the OCSP response with\nfields like \"nextUpdate\". The default implementation of the cache will consider responses\nvalid as long as \"nextUpdate\" is less then the current time.\n\nSSLreusectx\nIf you have already set the above options for a previous instance of IO::Socket::SSL, then\nyou can reuse the SSL context of that instance by passing it as the value for the\nSSLreusectx parameter. You may also create a new instance of the\nIO::Socket::SSL::SSLContext class, using any context options that you desire without\nspecifying connection options, and pass that here instead.\n\nIf you use this option, all other context-related options that you pass in the same call\nto new() will be ignored unless the context supplied was invalid. Note that, contrary to\nversions of IO::Socket::SSL below v0.90, a global SSL context will not be implicitly used\nunless you use the setdefaultcontext() function.\n\nSSLcreatectxcallback\nWith this callback you can make individual settings to the context after it got created\nand the default setup was done. The callback will be called with the CTX object from\nNet::SSLeay as the single argument.\n\nExample for limiting the server session cache size:\n\nSSLcreatectxcallback => sub {\nmy $ctx = shift;\nNet::SSLeay::CTXsesssetcachesize($ctx,128);\n}\n\nSSLsessioncachesize\nIf you make repeated connections to the same host/port and the SSL renegotiation time is\nan issue, you can turn on client-side session caching with this option by specifying a\npositive cache size. For successive connections, pass the SSLreusectx option to the\nnew() calls (or use setdefaultcontext()) to make use of the cached sessions. The session\ncache size refers to the number of unique host/port pairs that can be stored at one time;\nthe oldest sessions in the cache will be removed if new ones are added.\n\nThis option does not effect the session cache a server has for it's clients, e.g. it does\nnot affect SSL objects with SSLserver set.\n\nNote that session caching with TLS 1.3 needs at least Net::SSLeay 1.86.\n\nSSLsessioncache\nSpecifies session cache object which should be used instead of creating a new. Overrules\nSSLsessioncachesize. This option is useful if you want to reuse the cache, but not the\nrest of the context.\n\nA session cache object can be created using \"IO::Socket::SSL::SessionCache->new(\ncachesize )\".\n\nUse setdefaultsessioncache() to set a global cache object.\n\nSSLsessionkey\nSpecifies a key to use for lookups and inserts into client-side session cache. Per default\nip:port of destination will be used, but sometimes you want to share the same session over\nmultiple ports on the same server (like with FTPS).\n\nSSLsessionidcontext\nThis gives an id for the servers session cache. It's necessary if you want clients to\nconnect with a client certificate. If not given but SSLverifymode specifies the need for\nclient certificate a context unique id will be picked.\n\nSSLerrortrap\nWhen using the accept() or connect() methods, it may be the case that the actual socket\nconnection works but the SSL negotiation fails, as in the case of an HTTP client\nconnecting to an HTTPS server. Passing a subroutine ref attached to this parameter allows\nyou to gain control of the orphaned socket instead of having it be closed forcibly. The\nsubroutine, if called, will be passed two parameters: a reference to the socket on which\nthe SSL negotiation failed and the full text of the error message.\n\nSSLnpnprotocols\nIf used on the server side it specifies list of protocols advertised by SSL server as an\narray ref, e.g. ['spdy/2','http1.1']. On the client side it specifies the protocols\noffered by the client for NPN as an array ref. See also method \"nextprotonegotiated\".\n\nNext Protocol Negotiation (NPN) is available with Net::SSLeay 1.46+ and openssl-1.0.1+.\nNPN is unavailable in TLSv1.3 protocol. To check support you might call\n\"IO::Socket::SSL->cannpn()\". If you use this option with an unsupported\nNet::SSLeay/OpenSSL it will throw an error.\n\nSSLalpnprotocols\nIf used on the server side it specifies list of protocols supported by the SSL server as\nan array ref, e.g. ['http/2.0', 'spdy/3.1','http/1.1']. On the client side it specifies\nthe protocols advertised by the client for ALPN as an array ref. See also method\n\"alpnselected\".\n\nApplication-Layer Protocol Negotiation (ALPN) is available with Net::SSLeay 1.56+ and\nopenssl-1.0.2+. More details about the extension are in RFC7301. To check support you\nmight call \"IO::Socket::SSL->canalpn()\". If you use this option with an unsupported\nNet::SSLeay/OpenSSL it will throw an error.\n\nNote that some client implementations may encounter problems if both NPN and ALPN are\nspecified. Since ALPN is intended as a replacement for NPN, try providing ALPN protocols\nthen fall back to NPN if that fails.\n\nSSLticketkeycb => [$sub,$data] | $sub\nThis is a callback used for stateless session reuse (Session Tickets, RFC 5077).\n\nThis callback will be called as \"$sub->($data,[$keyname])\" where $data is the argument\ngiven to SSLticketkeycb (or undef) and $keyname depends on the mode:\n\nencrypt ticket\nIf a ticket needs to be encrypted the callback will be called without $keyname.\nIn this case it should return \"($currentkey,$currentkeyname\") where\n$currentkey is the current key (32 byte random data) and $currentkeyname the\nname associated with this key (exactly 16 byte). This $currentkeyname will be\nincorporated into the ticket.\n\ndecrypt ticket\nIf a ticket needs to be decrypted the callback will be called with $keyname as\nfound in the ticket. It should return \"($key,$currentkeyname\") where $key is the\nkey associated with the given $keyname and $currentkeyname the name associated\nwith the currently active key. If $currentkeyname is different from the given\n$keyname the callback will be called again to re-encrypt the ticket with the\ncurrently active key.\n\nIf no key can be found which matches the given $keyname then this function should\nreturn nothing (empty list).\n\nThis mechanism should be used to limit the life time for each key encrypting the\nticket. Compromise of a ticket encryption key might lead to decryption of SSL\nsessions which used session tickets protected by this key.\n\nExample:\n\nNet::SSLeay::RANDbytes(my $oldkey,32);\nNet::SSLeay::RANDbytes(my $newkey,32);\nmy $oldkeyname = pack(\"a16\",'oldsecret');\nmy $newkeyname = pack(\"a16\",'newsecret');\n\nmy @keys = (\n[ $newkeyname, $newkey ], # current active key\n[ $oldkeyname, $oldkey ], # already expired\n);\n\nmy $keycb = [ sub {\nmy ($mykeys,$name) = @;\n\n# return (currentkey, currentkeyname) if no name given\nreturn ($mykeys->[0][1],$mykeys->[0][0]) if ! $name;\n\n# return (matchingkey, currentkeyname) if we find a key matching\n# the given name\nfor(my $i = 0; $i<@$mykeys; $i++) {\nnext if $name ne $mykeys->[$i][0];\nreturn ($mykeys->[$i][1],$mykeys->[0][0]);\n}\n\n# no matching key found\nreturn;\n},\\@keys ];\n\nmy $srv = IO::Socket::SSL->new(..., SSLticketkeycb => $keycb);\n\nSSLmodereleasebuffers 1|0\nThis enables or disables the SSLMODERELEASEBUFFERS option on the SSL object. With this\noption the read buffer will be released after each SSLread but will need to be\nreallocated for each new SSLread. If memory usage is a concern this might save lots of\nmemory in the mean time though, about 34k per idle SSL connection according to the\ndocumentation in SSLCTXsetmode(3ssl).\n\naccept\nThis behaves similar to the accept function of the underlying socket class, but additionally\ndoes the initial SSL handshake. But because the underlying socket class does return a\nblocking file handle even when accept is called on a non-blocking socket, the SSL handshake\non the new file object will be done in a blocking way. Please see the section about\nnon-blocking I/O for details. If you don't like this behavior you should do accept on the\nTCP socket and then upgrade it with \"startSSL\" later.\n" }, { "name": "connect", "content": "This behaves similar to the connect function but also does an SSL handshake. Because you\ncannot give SSL specific arguments to this function, you should better either use \"new\" to\ncreate a connect SSL socket or \"startSSL\" to upgrade an established TCP socket to SSL.\n" }, { "name": "close", "content": "Contrary to a close for a simple INET socket a close in SSL also mandates a proper shutdown\nof the SSL part. This is done by sending a close notify message by both peers.\n\nA naive implementation would thus wait until it receives the close notify message from the\npeer - which conflicts with the commonly expected semantic that a close will not block. The\ndefault behavior is thus to only send a close notify but not wait for the close notify of\nthe peer. If this is required \"SSLfastshutdown\" need to be explicitly set to false.\n\nThere are also cases where a SSL shutdown should not be done at all. This is true for\nexample when forking to let a child deal with the socket and closing the socket in the\nparent process. A naive explicit \"close\" or an implicit close when destroying the socket in\nthe parent would send a close notify to the peer which would make the SSL socket in the\nclient process unusable. In this case an explicit \"close\" with \"SSLnoshutdown\" set to true\nshould be done in the parent process.\n\nFor more details and other arguments see \"stopSSL\" which gets called from \"close\" to\nshutdown the SSL state of the socket.\n" }, { "name": "sysread", "content": "This function behaves from the outside the same as sysread in other IO::Socket objects, e.g.\nit returns at most LEN bytes of data. But in reality it reads not only LEN bytes from the\nunderlying socket, but at a single SSL frame. It then returns up to LEN bytes it decrypted\nfrom this SSL frame. If the frame contained more data than requested it will return only LEN\ndata, buffer the rest and return it on further read calls. This means, that it might be\npossible to read data, even if the underlying socket is not readable, so using poll or\nselect might not be sufficient.\n\nsysread will only return data from a single SSL frame, e.g. either the pending data from the\nalready buffered frame or it will read a frame from the underlying socket and return the\ndecrypted data. It will not return data spanning several SSL frames in a single call.\n\nAlso, calls to sysread might fail, because it must first finish an SSL handshake.\n\nTo understand these behaviors is essential, if you write applications which use event loops\nand/or non-blocking sockets. Please read the specific sections in this documentation.\n" }, { "name": "syswrite", "content": "This functions behaves from the outside the same as syswrite in other IO::Socket objects,\ne.g. it will write at most LEN bytes to the socket, but there is no guarantee, that all LEN\nbytes are written. It will return the number of bytes written. Because it basically just\ncalls SSLwrite from OpenSSL syswrite will write at most a single SSL frame. This means,\nthat no more than 16.384 bytes, which is the maximum size of an SSL frame, will be written\nat once.\n\nFor non-blocking sockets SSL specific behavior applies. Pease read the specific section in\nthis documentation.\n" }, { "name": "peek", "content": "This function has exactly the same syntax as sysread, and performs nearly the same task but\nwill not advance the read position so that successive calls to peek() with the same\narguments will return the same results. This function requires OpenSSL 0.9.6a or later to\nwork.\n" }, { "name": "pending", "content": "This function gives you the number of bytes available without reading from the underlying\nsocket object. This function is essential if you work with event loops, please see the\nsection about polling SSL sockets.\n" }, { "name": "get_fingerprint", "content": "This methods returns the fingerprint of the given certificate in the form \"algo$digesthex\",\nwhere \"algo\" is the used algorithm, default 'sha256'. If no certificate is given the peer\ncertificate of the connection is used. If \"pubkey\" is true it will not return the\nfingerprint of the certificate but instead the fingerprint of the pubkey inside the\ncertificate as \"algo$pub$digesthex\".\n" }, { "name": "get_fingerprint_bin", "content": "This methods returns the binary fingerprint of the given certificate by using the algorithm\n\"algo\", default 'sha256'. If no certificate is given the peer certificate of the connection\nis used. If \"pubkey\" is true it will not return the fingerprint of the certificate but\ninstead the fingerprint of the pubkey inside the certificate.\n" }, { "name": "get_cipher", "content": "Returns the string form of the cipher that the IO::Socket::SSL object is using.\n" }, { "name": "get_sslversion", "content": "Returns the string representation of the SSL version of an established connection.\n" }, { "name": "get_sslversion_int", "content": "Returns the integer representation of the SSL version of an established connection.\n" }, { "name": "get_session_reused", "content": "This returns true if the session got reused and false otherwise. Note that with a reused\nsession no certificates are send within the handshake and no ciphers are offered and thus\nfunctions which rely on this might not work.\n" }, { "name": "dump_peer_certificate", "content": "Returns a parsable string with select fields from the peer SSL certificate. This method\ndirectly returns the result of the dumppeercertificate() method of Net::SSLeay.\n" }, { "name": "peer_certificate", "content": "If a peer certificate exists, this function can retrieve values from it. If no field is\ngiven the internal representation of certificate from Net::SSLeay is returned. If refresh is\ntrue it will not used a cached version, but check again in case the certificate of the\nconnection has changed due to renegotiation.\n\nThe following fields can be queried:\n\nauthority (alias issuer)\nThe certificate authority which signed the certificate.\n\nowner (alias subject)\nThe owner of the certificate.\n\ncommonName (alias cn) - only for Net::SSLeay version >=1.30\nThe common name, usually the server name for SSL certificates.\n\nsubjectAltNames - only for Net::SSLeay version >=1.33\nAlternative names for the subject, usually different names for the same server, like\nexample.org, example.com, *.example.com.\n\nIt returns a list of (typ,value) with typ GENDNS, GENIPADD etc (these constants\nare exported from IO::Socket::SSL). See Net::SSLeay::X509getsubjectAltNames.\n" }, { "name": "sock_certificate", "content": "This is similar to \"peercertificate\" but will return the sites own certificate. The same\narguments for $field can be used. If no $field is given the certificate handle from the\nunderlying OpenSSL will be returned. This handle will only be valid as long as the SSL\nconnection exists and if used afterwards it might result in strange crashes of the\napplication.\n\npeercertificates\nThis returns all the certificates send by the peer, e.g. first the peers own certificate and\nthen the rest of the chain. You might use CERTasHash from IO::Socket::SSL::Utils to inspect\neach of the certificates.\n\nThis function depends on a version of Net::SSLeay >= 1.58 .\n\ngetservername\nThis gives the name requested by the client if Server Name Indication (SNI) was used.\n" }, { "name": "verify_hostname", "content": "This verifies the given hostname against the peer certificate using the given scheme.\nHostname is usually what you specify within the PeerAddr. See the\n\"SSLverifycnpublicsuffix\" parameter for an explanation of suffix checking and for the\npossible values.\n\nVerification of hostname against a certificate is different between various applications and\nRFCs. Some scheme allow wildcards for hostnames, some only in subjectAltNames, and even\ntheir different wildcard schemes are possible. RFC 6125 provides a good overview.\n\nTo ease the verification the following schemes are predefined (both protocol name and\nrfcXXXX name can be used):\n\nrfc2818, xmpp (rfc3920), ftp (rfc4217)\nExtended wildcards in subjectAltNames and common name are possible, e.g.\n*.example.org or even www*.example.org. The common name will be only checked if no\nDNS names are given in subjectAltNames.\n\nhttp (alias www)\nWhile name checking is defined in rfc2818 the current browsers usually accept also\nan IP address (w/o wildcards) within the common name as long as no subjectAltNames\nare defined. Thus this is rfc2818 extended with this feature.\n\nsmtp (rfc2595), imap, pop3, acap (rfc4642), netconf (rfc5538), syslog (rfc5425), snmp\n(rfc5953)\nSimple wildcards in subjectAltNames are possible, e.g. *.example.org matches\nwww.example.org but not lala.www.example.org. If nothing from subjectAltNames match\nit checks against the common name, where wildcards are also allowed to match the\nfull leftmost label.\n\nldap (rfc4513)\nSimple wildcards are allowed in subjectAltNames, but not in common name. Common name\nwill be checked even if subjectAltNames exist.\n\nsip (rfc5922)\nNo wildcards are allowed and common name is checked even if subjectAltNames exist.\n\ngist (rfc5971)\nSimple wildcards are allowed in subjectAltNames and common name, but common name\nwill only be checked if their are no DNS names in subjectAltNames.\n\ndefault This is a superset of all the rules and is automatically used if no scheme is given\nbut a hostname (instead of IP) is known. Extended wildcards are allowed in\nsubjectAltNames and common name and common name is checked always.\n\nnone No verification will be done. Actually is does not make any sense to call\nverifyhostname in this case.\n\nThe scheme can be given either by specifying the name for one of the above predefined\nschemes, or by using a hash which can have the following keys and values:\n\ncheckcn: 0|'always'|'whenonly'\nDetermines if the common name gets checked. If 'always' it will always be checked\n(like in ldap), if 'whenonly' it will only be checked if no names are given in\nsubjectAltNames (like in http), for any other values the common name will not be\nchecked.\n\nwildcardsinalt: 0|'fulllabel'|'anywhere'\nDetermines if and where wildcards in subjectAltNames are possible. If 'fulllabel'\nonly cases like *.example.org will be possible (like in ldap), for 'anywhere'\nwww*.example.org is possible too (like http), dangerous things like but www.*.org or\neven '*' will not be allowed. For compatibility with older versions 'leftmost' can\nbe given instead of 'fulllabel'.\n\nwildcardsincn: 0|'fulllabel'|'anywhere'\nSimilar to wildcardsinalt, but checks the common name. There is no predefined\nscheme which allows wildcards in common names.\n\nipincn: 0|1|4|6\nDetermines if an IP address is allowed in the common name (no wildcards are\nallowed). If set to 4 or 6 it only allows IPv4 or IPv6 addresses, any other true\nvalue allows both.\n\ncallback: \\&coderef\nIf you give a subroutine for verification it will be called with the arguments\n($hostname,$commonName,@subjectAltNames), where hostname is the name given for\nverification, commonName is the result from peercertificate('cn') and\nsubjectAltNames is the result from peercertificate('subjectAltNames').\n\nAll other arguments for the verification scheme will be ignored in this case.\n" }, { "name": "next_proto_negotiated", "content": "This method returns the name of negotiated protocol - e.g. 'http/1.1'. It works for both\nclient and server side of SSL connection.\n\nNPN support is available with Net::SSLeay 1.46+ and openssl-1.0.1+. To check support you\nmight call \"IO::Socket::SSL->cannpn()\".\n" }, { "name": "alpn_selected", "content": "Returns the protocol negotiated via ALPN as a string, e.g. 'http/1.1', 'http/2.0' or\n'spdy/3.1'.\n\nALPN support is available with Net::SSLeay 1.56+ and openssl-1.0.2+. To check support, use\n\"IO::Socket::SSL->canalpn()\".\n" }, { "name": "errstr", "content": "Returns the last error (in string form) that occurred. If you do not have a real object to\nperform this method on, call IO::Socket::SSL::errstr() instead.\n\nFor read and write errors on non-blocking sockets, this method may include the string \"SSL\nwants a read first!\" or \"SSL wants a write first!\" meaning that the other side is expecting\nto read from or write to the socket and wants to be satisfied before you get to do anything.\nBut with version 0.98 you are better comparing the global exported variable $SSLERROR\nagainst the exported symbols SSLWANTREAD and SSLWANTWRITE.\n" }, { "name": "opened", "content": "This returns false if the socket could not be opened, 1 if the socket could be opened and\nthe SSL handshake was successful done and -1 if the underlying IO::Handle is open, but the\nSSL handshake failed.\n\nIO::Socket::SSL->startSSL($socket, ... )\nThis will convert a glob reference or a socket that you provide to an IO::Socket::SSL\nobject. You may also pass parameters to specify context or connection options as with a call\nto new(). If you are using this function on an accept()ed socket, you must set the parameter\n\"SSLserver\" to 1, i.e. IO::Socket::SSL->startSSL($socket, SSLserver => 1). If you have a\nclass that inherits from IO::Socket::SSL and you want the $socket to be blessed into your\nown class instead, use MyClass->startSSL($socket) to achieve the desired effect.\n\nNote that if startSSL() fails in SSL negotiation, $socket will remain blessed in its\noriginal class. For non-blocking sockets you better just upgrade the socket to\nIO::Socket::SSL and call acceptSSL or connectSSL and the upgraded object. To just upgrade\nthe socket set SSLstartHandshake explicitly to 0. If you call startSSL w/o this parameter\nit will revert to blocking behavior for acceptSSL and connectSSL.\n\nIf given the parameter \"Timeout\" it will stop if after the timeout no SSL connection was\nestablished. This parameter is only used for blocking sockets, if it is not given the\ndefault Timeout from the underlying IO::Socket will be used.\n" }, { "name": "stop_SSL", "content": "This is the opposite of startSSL(), connectSSL() and acceptSSL(), e.g. it will shutdown\nthe SSL connection and return to the class before startSSL(). It gets the same arguments as\nclose(), in fact close() calls stopSSL() (but without downgrading the class).\n\nWill return true if it succeeded and undef if failed. This might be the case for\nnon-blocking sockets. In this case $! is set to EWOULDBLOCK and the ssl error to\nSSLWANTREAD or SSLWANTWRITE. In this case the call should be retried again with the same\narguments once the socket is ready.\n\nFor calling from \"stopSSL\" \"SSLfastshutdown\" default to false, e.g. it waits for the\nclosenotify of the peer. This is necessary in case you want to downgrade the socket and\ncontinue to use it as a plain socket.\n\nAfter stopSSL the socket can again be used to exchange plain data.\n\nconnectSSL, acceptSSL\nThese functions should be used to do the relevant handshake, if the socket got created with\n\"new\" or upgraded with \"startSSL\" and \"SSLstartHandshake\" was set to false. They will\nreturn undef until the handshake succeeded or an error got thrown. As long as the function\nreturns undef and $! is set to EWOULDBLOCK one could retry the call after the socket got\nreadable (SSLWANTREAD) or writeable (SSLWANTWRITE).\n\nocspresolver\nThis will create an OCSP resolver object, which can be used to create OCSP requests for the\ncertificates of the SSL connection. Which certificates are verified depends on the setting\nof \"SSLocspmode\": by default only the leaf certificate will be checked, but with\nSSLOCSPFULLCHAIN all chain certificates will be checked.\n\nBecause to create an OCSP request the certificate and its issuer certificate need to be\nknown it is not possible to check certificates when the trust chain is incomplete or if the\ncertificate is self-signed.\n\nThe OCSP resolver gets created by calling \"$ssl->ocspresolver\" and provides the following\nmethods:\n\nharderror\nThis returns the hard error when checking the OCSP response. Hard errors are\ncertificate revocations. With the \"SSLocspmode\" of SSLOCSPFAILHARD any soft\nerror (e.g. failures to get signed information about the certificates) will be\nconsidered a hard error too.\n\nThe OCSP resolving will stop on the first hard error.\n\nThe method will return undef as long as no hard errors occurred and still requests\nto be resolved. If all requests got resolved and no hard errors occurred the method\nwill return ''.\n\nsofterror\nThis returns the soft error(s) which occurred when asking the OCSP responders.\n\nrequests\nThis will return a hash consisting of \"(url,request)\"-tuples, e.g. which contain the\nOCSP request string and the URL where it should be sent too. The usual way to send\nsuch a request is as HTTP POST request with a content-type of\n\"application/ocsp-request\" or as a GET request with the base64 and url-encoded\nrequest is added to the path of the URL.\n\nAfter you've handled all these requests and added the response with \"addresponse\"\nyou should better call this method again to make sure, that no more requests are\noutstanding. IO::Socket::SSL will combine multiple OCSP requests for the same server\ninside a single request, but some server don't give a response to all these\nrequests, so that one has to ask again with the remaining requests.\n\naddresponse($uri,$response)\nThis method takes the HTTP body of the response which got received when sending the\nOCSP request to $uri. If no response was received or an error occurred one should\neither retry or consider $response as empty which will trigger a soft error.\n\nThe method returns the current value of \"harderror\", e.g. a defined value when no\nmore requests need to be done.\n\nresolveblocking(%args)\nThis combines \"requests\" and \"addresponse\" which HTTP::Tiny to do all necessary\nrequests in a blocking way. %args will be given to HTTP::Tiny so that you can put\nproxy settings etc here. HTTP::Tiny will be called with \"verifySSL\" of false,\nbecause the OCSP responses have their own signatures so no extra SSL verification is\nneeded.\n\nIf you don't want to use blocking requests you need to roll your own user agent with\n\"requests\" and \"addresponse\".\n\nIO::Socket::SSL->newfromfd($fd, [mode], %sslargs)\nThis will convert a socket identified via a file descriptor into an SSL socket. Note that\nthe argument list does not include a \"MODE\" argument; if you supply one, it will be\nthoughtfully ignored (for compatibility with IO::Socket::INET). Instead, a mode of '+<' is\nassumed, and the file descriptor passed must be able to handle such I/O because the initial\nSSL handshake requires bidirectional communication.\n\nInternally the given $fd will be upgraded to a socket object using the \"newfromfd\" method\nof the super class (IO::Socket::INET or similar) and then \"startSSL\" will be called using\nthe given %sslargs. If $fd is already an IO::Socket object you should better call\n\"startSSL\" directly.\n\nIO::Socket::SSL::defaultca([ path|dir| SSLcafile = ..., SSLcapath => ... ])>\nDetermines or sets the default CA path. If existing path or dir or a hash is given it will\nset the default CA path to this value and never try to detect it automatically. If \"undef\"\nis given it will forget any stored defaults and continue with detection of system defaults.\nIf no arguments are given it will start detection of system defaults, unless it has already\nstored user-set or previously detected values.\n\nThe detection of system defaults works similar to OpenSSL, e.g. it will check the directory\nspecified in environment variable SSLCERTDIR or the path OPENSSLDIR/certs (SSLCERTS: on\nVMS) and the file specified in environment variable SSLCERTFILE or the path\nOPENSSLDIR/cert.pem (SSLCERTS:cert.pem on VMS). Contrary to OpenSSL it will check if the\nSSLcapath contains PEM files with the hash as file name and if the SSLcafile looks like\nPEM. If no usable system default can be found it will try to load and use Mozilla::CA and if\nnot available give up detection. The result of the detection will be saved to speed up\nfuture calls.\n\nThe function returns the saved default CA as hash with SSLcafile and SSLcapath.\n\nIO::Socket::SSL::setdefaultcontext(...)\nYou may use this to make IO::Socket::SSL automatically re-use a given context (unless\nspecifically overridden in a call to new()). It accepts one argument, which should be either\nan IO::Socket::SSL object or an IO::Socket::SSL::SSLContext object. See the SSLreusectx\noption of new() for more details. Note that this sets the default context globally, so use\nwith caution (esp. in modperl scripts).\n\nIO::Socket::SSL::setdefaultsessioncache(...)\nYou may use this to make IO::Socket::SSL automatically re-use a given session cache (unless\nspecifically overridden in a call to new()). It accepts one argument, which should be an\nIO::Socket::SSL::SessionCache object or similar (e.g. something which implements\ngetsession, addsession and delsession like IO::Socket::SSL::SessionCache does). See the\nSSLsessioncache option of new() for more details. Note that this sets the default cache\nglobally, so use with caution.\n\nIO::Socket::SSL::setdefaults(%args)\nWith this function one can set defaults for all SSL* parameter used for creation of the\ncontext, like the SSLverify* parameter. Any SSL* parameter can be given or the following\nshort versions:\n\nmode - SSLverifymode\ncallback - SSLverifycallback\nscheme - SSLverifycnscheme\nname - SSLverifycnname\n\nIO::Socket::SSL::setclientdefaults(%args)\nSimilar to \"setdefaults\", but only sets the defaults for client mode.\n\nIO::Socket::SSL::setserverdefaults(%args)\nSimilar to \"setdefaults\", but only sets the defaults for server mode.\n\nIO::Socket::SSL::setargsfilterhack(\\&code|'usedefaults')\nSometimes one has to use code which uses unwanted or invalid arguments for SSL, typically\ndisabling SSL verification or setting wrong ciphers or SSL versions. With this hack it is\npossible to override these settings and restore sanity. Example:\n\nIO::Socket::SSL::setargsfilterhack( sub {\nmy ($isserver,$args) = @;\nif ( ! $isserver ) {\n# client settings - enable verification with default CA\n# and fallback hostname verification etc\ndelete @{$args}{qw(\nSSLverifymode\nSSLcafile\nSSLcapath\nSSLverifycnscheme\nSSLversion\n)};\n# and add some fingerprints for known certs which are signed by\n# unknown CAs or are self-signed\n$args->{SSLfingerprint} = ...\n}\n});\n\nWith the short setting \"setargsfilterhack('usedefaults')\" it will prefer the default\nsettings in all cases. These default settings can be modified with \"setdefaults\",\n\"setclientdefaults\" and \"setserverdefaults\".\n\nThe following methods are unsupported (not to mention futile!) and IO::Socket::SSL will emit a\nlarge CROAK() if you are silly enough to use them:\n\ntruncate\nstat\nungetc\nsetbuf\nsetvbuf\nfdopen\nsend/recv\nNote that send() and recv() cannot be reliably trapped by a tied filehandle (such as that\nused by IO::Socket::SSL) and so may send unencrypted data over the socket. Object-oriented\ncalls to these functions will fail, telling you to use the print/printf/syswrite and\nread/sysread families instead.\n" } ] }, "DEPRECATIONS": { "content": "The following functions are deprecated and are only retained for compatibility:\n", "subsections": [ { "name": "context_init", "content": "use the SSLreusectx option if you want to re-use a context\n" }, { "name": "socketToSSL", "content": "use IO::Socket::SSL->startSSL() instead\n" }, { "name": "kill_socket", "content": "use close() instead\n" }, { "name": "get_peer_certificate", "content": "use the peercertificate() function instead. Used to return X509Certificate with methods\nsubjectname and issuername. Now simply returns $self which has these methods (although\ndeprecated).\n" }, { "name": "issuer_name", "content": "use peercertificate( 'issuer' ) instead\n" }, { "name": "subject_name", "content": "use peercertificate( 'subject' ) instead\n" } ] }, "EXAMPLES": { "content": "See the 'example' directory, the tests in 't' and also the tools in 'util'.\n", "subsections": [] }, "BUGS": { "content": "If you use IO::Socket::SSL together with threads you should load it (e.g. use or require) inside\nthe main thread before creating any other threads which use it. This way it is much faster\nbecause it will be initialized only once. Also there are reports that it might crash the other\nway.\n\nCreating an IO::Socket::SSL object in one thread and closing it in another thread will not work.\n\nIO::Socket::SSL does not work together with Storable::fdretrieve/fdstore. See BUGS file for\nmore information and how to work around the problem.\n\nNon-blocking and timeouts (which are based on non-blocking) are not supported on Win32, because\nthe underlying IO::Socket::INET does not support non-blocking on this platform.\n\nIf you have a server and it looks like you have a memory leak you might check the size of your\nsession cache. Default for Net::SSLeay seems to be 20480, see the example for\nSSLcreatectxcallback for how to limit it.\n\nTLS 1.3 support regarding session reuse is incomplete.\n", "subsections": [] }, "SEE ALSO": { "content": "IO::Socket::INET, IO::Socket::INET6, IO::Socket::IP, Net::SSLeay.\n", "subsections": [] }, "THANKS": { "content": "Many thanks to all who added patches or reported bugs or helped IO::Socket::SSL another way.\nPlease keep reporting bugs and help with patches, even if they just fix the documentation.\n\nSpecial thanks to the team of Net::SSLeay for the good cooperation.\n", "subsections": [] }, "AUTHORS": { "content": "Steffen Ullrich, is the current maintainer.\n\nPeter Behroozi, (Note the lack of an \"i\" at the end of \"behrooz\")\n\nMarko Asplund, , was the original author of IO::Socket::SSL.\n\nPatches incorporated from various people, see file Changes.\n", "subsections": [] }, "COPYRIGHT": { "content": "The original versions of this module are Copyright (C) 1999-2002 Marko Asplund.\n\nThe rewrite of this module is Copyright (C) 2002-2005 Peter Behroozi.\n\nVersions 0.98 and newer are Copyright (C) 2006-2014 Steffen Ullrich.\n\nThis module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n", "subsections": [] } } } }