{
    "mode": "perldoc",
    "parameter": "IO::Socket::SSL::Intercept",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/IO%3A%3ASocket%3A%3ASSL%3A%3AIntercept/json",
    "generated": "2026-06-12T05:48:21Z",
    "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}",
    "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 with a proxy certificate,\nthus making it easy to intercept SSL connections (man in the middle). It also manages a cache of\nthe generated certificates.\n",
            "subsections": []
        },
        "How Intercepting SSL Works": {
            "content": "Intercepting SSL connections is useful for analyzing encrypted traffic for security reasons or\nfor testing. It does not break the end-to-end security of SSL, e.g. a properly written client\nwill notice the interception unless you explicitly configure the client to trust your\ninterceptor. Intercepting SSL works the following way:\n\n*   Create a new CA certificate, which will be used to sign the cloned certificates. This proxy\nCA certificate should be trusted by the client, or (a properly written client) will throw\nerror messages or deny the connections because it detected a man in the middle attack. Due\nto the way the interception works there no support for client side certificates is possible.\n\nUsing openssl such a proxy CA certificate and private key can be created 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\n*   Configure client to connect to use intercepting proxy or somehow redirect connections from\nclient to the proxy (e.g. packet filter redirects, ARP or DNS spoofing etc).\n\n*   Accept the TCP connection from the client, e.g. don't do any SSL handshakes with the client\nyet.\n\n*   Establish the SSL connection to the server and verify the servers certificate as usually.\nThen create a new certificate based on the original servers certificate, but signed by your\nproxy CA. This is the step where IO::Socket::SSL::Intercept helps.\n\n*   Upgrade the TCP connection to the client to SSL using the cloned certificate from the\nserver. If the client trusts your proxy CA it will accept the upgrade to SSL.\n\n*   Transfer data between client and server. While the connections to client and server are both\nencrypted with SSL you will read/write the unencrypted data in your proxy application.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "IO::Socket::SSL::Intercept helps creating the cloned certificate with the 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 an X509 object from\nNet::SSLeays internal representation, or using a file in PEM format.\n\nproxykey EVPPKEY | proxykeyfile filename\nThis is the key for the proxy certificate. It can be either given by an EVPPKEY\nobject from Net::SSLeays internal representation, or using a file in PEM format. The\nkey should not have a passphrase.\n\npubkey EVPPKEY | pubkeyfile filename\nThis optional argument specifies the public key used for the cloned certificate. It\ncan be either given by an EVPPKEY object from Net::SSLeays internal representation,\nor using a file in PEM format. If not given it will create a new public key on each\ncall of \"new\".\n\nserial INTEGER|CODE\nThis optional argument gives the starting point for the serial numbers of the newly\ncreated certificates. If not set the serial number will be created based on the\ndigest of the original certificate. If the value is code it will be called with\n\"serial(originalcert,CERTasHash(originalcert))\" and should return the new serial\nnumber.\n\ncache HASH | SUBROUTINE\nThis optional argument gives a way to cache created certificates, so that they don't\nget recreated on future accesses to the same host. If the argument ist not given an\ninternal HASH ist used.\n\nIf the argument is a hash it will store for each generated certificate a hash\nreference with \"cert\" and \"atime\" in the hash, where \"atime\" is the time of last\naccess (to expire unused entries) and \"cert\" is the certificate. Please note, that\nthe certificate is in Net::SSLeays internal X509 format and can thus not be simply\ndumped and restored. The key 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 \"$cache->(ident,sub)\". This\ncall should return either an existing (cached) \"(cert,key)\" or call \"sub\" without\narguments to create a new \"(cert,key)\", store it and return it. If called with\n\"$cache->('type')\" the function should just return 1 to signal that it supports the\ncurrent type of cache. If it reutrns nothing instead the older cache interface is\nassumed for compatibility reasons.\n\n($clonecert,$key) = $mitm->clonecert($originalcert,[ $ident ])\nThis clones the given certificate. An ident as the key into the cache can be given (like\n\"host:port\"), if not it will be created from the properties of the original certificate. It\nreturns the cloned 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) which can then be used to\npersistantly store created certificates over restarts of the application. The cache will\nonly be serialized if it is a HASH. To work together with Storable the \"STORABLEfreeze\"\nfunction is defined to call \"serialize\".\n\n$mitm = IO::Socket::SSL::Intercept->unserialize($string)\nThis restores an Intercept object from a serialized string. To work together with Storable\nthe \"STORABLEthaw\" function is defined to call \"unserialize\".\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Steffen Ullrich\n",
            "subsections": []
        }
    },
    "summary": "IO::Socket::SSL::Intercept -- SSL interception (man in the middle)",
    "flags": [],
    "examples": [],
    "see_also": []
}