{
    "content": [
        {
            "type": "text",
            "text": "# IO::Socket::SSL::Intercept (info)\n\n## NAME\n\nIO::Socket::SSL::Intercept -- SSL interception (man in the middle)\n\n## SYNOPSIS\n\nuse IO::Socket::SSL::Intercept;\n# create interceptor with proxy certificates\nmy $mitm = IO::Socket::SSL::Intercept->new(\nproxycertfile => 'proxycert.pem',\nproxykeyfile  => 'proxykey.pem',\n...\n);\nmy $listen = IO::Socket::INET->new( LocalAddr => .., Listen => .. );\nwhile (1) {\n# TCP accept new client\nmy $client = $listen->accept or next;\n# SSL connect to server\nmy $server = IO::Socket::SSL->new(\nPeerAddr => ..,\nSSLverifymode => ...,\n...\n) or die \"ssl connect failed: $!,$SSLERROR\";\n# clone server certificate\nmy ($cert,$key) = $mitm->clonecert( $server->peercertificate );\n# and upgrade client side to SSL with cloned certificate\nIO::Socket::SSL->startSSL($client,\nSSLserver => 1,\nSSLcert => $cert,\nSSLkey => $key\n) or die \"upgrade failed: $SSLERROR\";\n# now transfer data between $client and $server and analyze\n# the unencrypted data\n...\n}\n\n## DESCRIPTION\n\nThis module provides functionality to clone certificates and sign them\nwith a proxy certificate, thus making it easy to intercept SSL\nconnections (man in the middle). It also manages a cache of the\ngenerated certificates.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **How Intercepting SSL Works**\n- **METHODS**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "IO::Socket::SSL::Intercept",
        "section": "",
        "mode": "info",
        "summary": "IO::Socket::SSL::Intercept -- SSL interception (man in the middle)",
        "synopsis": "use IO::Socket::SSL::Intercept;\n# create interceptor with proxy certificates\nmy $mitm = IO::Socket::SSL::Intercept->new(\nproxycertfile => 'proxycert.pem',\nproxykeyfile  => 'proxykey.pem',\n...\n);\nmy $listen = IO::Socket::INET->new( LocalAddr => .., Listen => .. );\nwhile (1) {\n# TCP accept new client\nmy $client = $listen->accept or next;\n# SSL connect to server\nmy $server = IO::Socket::SSL->new(\nPeerAddr => ..,\nSSLverifymode => ...,\n...\n) or die \"ssl connect failed: $!,$SSLERROR\";\n# clone server certificate\nmy ($cert,$key) = $mitm->clonecert( $server->peercertificate );\n# and upgrade client side to SSL with cloned certificate\nIO::Socket::SSL->startSSL($client,\nSSLserver => 1,\nSSLcert => $cert,\nSSLkey => $key\n) or die \"upgrade failed: $SSLERROR\";\n# now transfer data between $client and $server and analyze\n# the unencrypted data\n...\n}",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 30,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "How Intercepting SSL Works",
                "lines": 41,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 76,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 3,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "IO::Socket::SSL::Intercept -- SSL interception (man in the middle)\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use IO::Socket::SSL::Intercept;\n# create interceptor with proxy certificates\nmy $mitm = IO::Socket::SSL::Intercept->new(\nproxycertfile => 'proxycert.pem',\nproxykeyfile  => 'proxykey.pem',\n...\n);\nmy $listen = IO::Socket::INET->new( LocalAddr => .., Listen => .. );\nwhile (1) {\n# TCP accept new client\nmy $client = $listen->accept or next;\n# SSL connect to server\nmy $server = IO::Socket::SSL->new(\nPeerAddr => ..,\nSSLverifymode => ...,\n...\n) or die \"ssl connect failed: $!,$SSLERROR\";\n# clone server certificate\nmy ($cert,$key) = $mitm->clonecert( $server->peercertificate );\n# and upgrade client side to SSL with cloned certificate\nIO::Socket::SSL->startSSL($client,\nSSLserver => 1,\nSSLcert => $cert,\nSSLkey => $key\n) or die \"upgrade failed: $SSLERROR\";\n# now transfer data between $client and $server and analyze\n# the unencrypted data\n...\n}\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module provides functionality to clone certificates and sign them\nwith a proxy certificate, thus making it easy to intercept SSL\nconnections (man in the middle). It also manages a cache of the\ngenerated certificates.\n",
                "subsections": []
            },
            "How Intercepting SSL Works": {
                "content": "Intercepting SSL connections is useful for analyzing encrypted traffic\nfor security reasons or for testing. It does not break the end-to-end\nsecurity of SSL, e.g. a properly written client will notice the\ninterception unless you explicitly configure the client to trust your\ninterceptor.  Intercepting SSL works the following way:\n\no   Create a new CA certificate, which will be used to sign the cloned\ncertificates.  This proxy CA certificate should be trusted by the\nclient, or (a properly written client) will throw error messages or\ndeny the connections because it detected a man in the middle\nattack.  Due to the way the interception works there no support for\nclient side certificates is possible.\n\nUsing openssl such a proxy CA certificate and private key can be\ncreated with:\n\nopenssl genrsa -out proxykey.pem 1024\nopenssl req -new -x509 -extensions v3ca -key proxykey.pem -out proxycert.pem\n# export as PKCS12 for import into browser\nopenssl pkcs12 -export -in proxycert.pem -inkey proxykey.pem -out proxycert.p12\n\no   Configure client to connect to use intercepting proxy or somehow\nredirect connections from client to the proxy (e.g. packet filter\nredirects, ARP or DNS spoofing etc).\n\no   Accept the TCP connection from the client, e.g. don't do any SSL\nhandshakes with the client yet.\n\no   Establish the SSL connection to the server and verify the servers\ncertificate as usually. Then create a new certificate based on the\noriginal servers certificate, but signed by your proxy CA.  This is\nthe step where IO::Socket::SSL::Intercept helps.\n\no   Upgrade the TCP connection to the client to SSL using the cloned\ncertificate from the server. If the client trusts your proxy CA it\nwill accept the upgrade to SSL.\n\no   Transfer data between client and server. While the connections to\nclient and server are both encrypted with SSL you will read/write\nthe unencrypted data in your proxy application.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "IO::Socket::SSL::Intercept helps creating the cloned certificate with\nthe following methods:\n\n$mitm = IO::Socket::SSL::Intercept->new(%args)\nThis creates a new interceptor object. %args should be\n\nproxycert X509 | proxycertfile filename\nThis is the proxy certificate.  It can be either given by\nan X509 object from Net::SSLeays internal representation,\nor using a file in PEM format.\n\nproxykey EVPPKEY | proxykeyfile filename\nThis is the key for the proxy certificate.  It can be\neither given by an EVPPKEY object from Net::SSLeays\ninternal representation, or using a file in PEM format.\nThe key should not have a passphrase.\n\npubkey EVPPKEY | pubkeyfile filename\nThis optional argument specifies the public key used for\nthe cloned certificate.  It can be either given by an\nEVPPKEY object from Net::SSLeays internal representation,\nor using a file in PEM format.  If not given it will create\na new public key on each call of \"new\".\n\nserial INTEGER|CODE\nThis optional argument gives the starting point for the\nserial numbers of the newly created certificates. If not\nset the serial number will be created based on the digest\nof the original certificate. If the value is code it will\nbe called with\n\"serial(originalcert,CERTasHash(originalcert))\" and\nshould return the new serial number.\n\ncache HASH | SUBROUTINE\nThis optional argument gives a way to cache created\ncertificates, so that they don't get recreated on future\naccesses to the same host.  If the argument ist not given\nan internal HASH ist used.\n\nIf the argument is a hash it will store for each generated\ncertificate a hash reference with \"cert\" and \"atime\" in the\nhash, where \"atime\" is the time of last access (to expire\nunused entries) and \"cert\" is the certificate. Please note,\nthat the certificate is in Net::SSLeays internal X509\nformat and can thus not be simply dumped and restored.  The\nkey for the hash is an \"ident\" either given to \"clonecert\"\nor generated from the original certificate.\n\nIf the argument is a subroutine it will be called as\n\"$cache->(ident,sub)\".  This call should return either an\nexisting (cached) \"(cert,key)\" or call \"sub\" without\narguments to create a new \"(cert,key)\", store it and return\nit.  If called with \"$cache->('type')\" the function should\njust return 1 to signal that it supports the current type\nof cache. If it reutrns nothing instead the older cache\ninterface is assumed for compatibility reasons.\n\n($clonecert,$key) = $mitm->clonecert($originalcert,[ $ident ])\nThis clones the given certificate.  An ident as the key into the\ncache can be given (like \"host:port\"), if not it will be created\nfrom the properties of the original certificate.  It returns the\ncloned certificate and its key (which is the same for alle created\ncertificates).\n\n$string = $mitm->serialize\nThis creates a serialized version of the object (e.g. a string)\nwhich can then be used to persistantly store created certificates\nover restarts of the application. The cache will only be serialized\nif it is a HASH.  To work together with Storable the\n\"STORABLEfreeze\" function is defined to call \"serialize\".\n\n$mitm = IO::Socket::SSL::Intercept->unserialize($string)\nThis restores an Intercept object from a serialized string.  To\nwork together with Storable the \"STORABLEthaw\" function is defined\nto call \"unserialize\".\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Steffen Ullrich\n\nperl v5.32.1                      2022-01-13   IO::Socket::SSL::Intercept(3pm)",
                "subsections": []
            }
        }
    }
}