.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Socket::SSL::Intercept 3pm"
.TH IO::Socket::SSL::Intercept 3pm "2021-01-23" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IO::Socket::SSL::Intercept \-\- SSL interception (man in the middle)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    use IO::Socket::SSL::Intercept;
\&    # create interceptor with proxy certificates
\&    my $mitm = IO::Socket::SSL::Intercept\->new(
\&        proxy_cert_file => \*(Aqproxy_cert.pem\*(Aq,
\&        proxy_key_file  => \*(Aqproxy_key.pem\*(Aq,
\&        ...
\&    );
\&    my $listen = IO::Socket::INET\->new( LocalAddr => .., Listen => .. );
\&    while (1) {
\&        # TCP accept new client
\&        my $client = $listen\->accept or next;
\&        # SSL connect to server
\&        my $server = IO::Socket::SSL\->new(
\&            PeerAddr => ..,
\&            SSL_verify_mode => ...,
\&            ...
\&        ) or die "ssl connect failed: $!,$SSL_ERROR";
\&        # clone server certificate
\&        my ($cert,$key) = $mitm\->clone_cert( $server\->peer_certificate );
\&        # and upgrade client side to SSL with cloned certificate
\&        IO::Socket::SSL\->start_SSL($client,
\&            SSL_server => 1,
\&            SSL_cert => $cert,
\&            SSL_key => $key
\&        ) or die "upgrade failed: $SSL_ERROR";
\&        # now transfer data between $client and $server and analyze
\&        # the unencrypted data
\&        ...
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functionality to clone certificates and sign them with a
proxy certificate, thus making it easy to intercept \s-1SSL\s0 connections (man in the
middle). It also manages a cache of the generated certificates.
.SH "How Intercepting SSL Works"
.IX Header "How Intercepting SSL Works"
Intercepting \s-1SSL\s0 connections is useful for analyzing encrypted traffic for
security reasons or for testing. It does not break the end-to-end security of
\&\s-1SSL,\s0 e.g. a properly written client will notice the interception unless you
explicitly configure the client to trust your interceptor.
Intercepting \s-1SSL\s0 works the following way:
.IP "\(bu" 4
Create a new \s-1CA\s0 certificate, which will be used to sign the cloned certificates.
This proxy \s-1CA\s0 certificate should be trusted by the client, or (a properly
written client) will throw error messages or deny the connections because it
detected a man in the middle attack.
Due to the way the interception works there no support for client side
certificates is possible.
.Sp
Using openssl such a proxy \s-1CA\s0 certificate and private key can be created with:
.Sp
.Vb 4
\&  openssl genrsa \-out proxy_key.pem 1024
\&  openssl req \-new \-x509 \-extensions v3_ca \-key proxy_key.pem \-out proxy_cert.pem
\&  # export as PKCS12 for import into browser
\&  openssl pkcs12 \-export \-in proxy_cert.pem \-inkey proxy_key.pem \-out proxy_cert.p12
.Ve
.IP "\(bu" 4
Configure client to connect to use intercepting proxy or somehow redirect
connections from client to the proxy (e.g. packet filter redirects, \s-1ARP\s0 or \s-1DNS\s0
spoofing etc).
.IP "\(bu" 4
Accept the \s-1TCP\s0 connection from the client, e.g. don't do any \s-1SSL\s0 handshakes with
the client yet.
.IP "\(bu" 4
Establish the \s-1SSL\s0 connection to the server and verify the servers certificate as
usually. Then create a new certificate based on the original servers
certificate, but signed by your proxy \s-1CA.\s0
This is the step where IO::Socket::SSL::Intercept helps.
.IP "\(bu" 4
Upgrade the \s-1TCP\s0 connection to the client to \s-1SSL\s0 using the cloned certificate
from the server. If the client trusts your proxy \s-1CA\s0 it will accept the upgrade
to \s-1SSL.\s0
.IP "\(bu" 4
Transfer data between client and server. While the connections to client and
server are both encrypted with \s-1SSL\s0 you will read/write the unencrypted data in
your proxy application.
.SH "METHODS"
.IX Header "METHODS"
IO::Socket::SSL::Intercept helps creating the cloned certificate with the
following methods:
.IP "\fB\f(CB$mitm\fB = IO::Socket::SSL::Intercept\->new(%args)\fR" 4
.IX Item "$mitm = IO::Socket::SSL::Intercept->new(%args)"
This creates a new interceptor object. \f(CW%args\fR should be
.RS 4
.IP "proxy_cert X509 | proxy_cert_file filename" 8
.IX Item "proxy_cert X509 | proxy_cert_file filename"
This is the proxy certificate.
It can be either given by an X509 object from Net::SSLeays internal
representation, or using a file in \s-1PEM\s0 format.
.IP "proxy_key \s-1EVP_PKEY\s0 | proxy_key_file filename" 8
.IX Item "proxy_key EVP_PKEY | proxy_key_file filename"
This is the key for the proxy certificate.
It can be either given by an \s-1EVP_PKEY\s0 object from Net::SSLeays internal
representation, or using a file in \s-1PEM\s0 format.
The key should not have a passphrase.
.IP "pubkey \s-1EVP_PKEY\s0 | pubkey_file filename" 8
.IX Item "pubkey EVP_PKEY | pubkey_file filename"
This optional argument specifies the public key used for the cloned certificate.
It can be either given by an \s-1EVP_PKEY\s0 object from Net::SSLeays internal
representation, or using a file in \s-1PEM\s0 format.
If not given it will create a new public key on each call of \f(CW\*(C`new\*(C'\fR.
.IP "serial INTEGER|CODE" 8
.IX Item "serial INTEGER|CODE"
This optional argument gives the starting point for the serial numbers of the
newly created certificates. If not set the serial number will be created based
on the digest of the original certificate. If the value is code it will be
called with \f(CW\*(C`serial(original_cert,CERT_asHash(original_cert))\*(C'\fR and should
return the new serial number.
.IP "cache \s-1HASH\s0 | \s-1SUBROUTINE\s0" 8
.IX Item "cache HASH | SUBROUTINE"
This optional argument gives a way to cache created certificates, so that they
don't get recreated on future accesses to the same host.
If the argument ist not given an internal \s-1HASH\s0 ist used.
.Sp
If the argument is a hash it will store for each generated certificate a hash
reference with \f(CW\*(C`cert\*(C'\fR and \f(CW\*(C`atime\*(C'\fR in the hash, where \f(CW\*(C`atime\*(C'\fR is the time of
last access (to expire unused entries) and \f(CW\*(C`cert\*(C'\fR is the certificate. Please
note, that the certificate is in Net::SSLeays internal X509 format and can
thus not be simply dumped and restored.
The key for the hash is an \f(CW\*(C`ident\*(C'\fR either given to \f(CW\*(C`clone_cert\*(C'\fR or generated
from the original certificate.
.Sp
If the argument is a subroutine it will be called as \f(CW\*(C`$cache\->(ident,sub)\*(C'\fR.
This call should return either an existing (cached) \f(CW\*(C`(cert,key)\*(C'\fR or
call \f(CW\*(C`sub\*(C'\fR without arguments to create a new \f(CW\*(C`(cert,key)\*(C'\fR, store it
and return it.
If called with \f(CW\*(C`$cache\->(\*(Aqtype\*(Aq)\*(C'\fR the function should just return 1 to
signal that it supports the current type of cache. If it reutrns nothing
instead the older cache interface is assumed for compatibility reasons.
.RE
.RS 4
.RE
.IP "\fB($clone_cert,$key) = \f(CB$mitm\fB\->clone_cert($original_cert,[ \f(CB$ident\fB ])\fR" 4
.IX Item "($clone_cert,$key) = $mitm->clone_cert($original_cert,[ $ident ])"
This clones the given certificate.
An ident as the key into the cache can be given (like \f(CW\*(C`host:port\*(C'\fR), if not it
will be created from the properties of the original certificate.
It returns the cloned certificate and its key (which is the same for alle
created certificates).
.IP "\fB\f(CB$string\fB = \f(CB$mitm\fB\->serialize\fR" 4
.IX Item "$string = $mitm->serialize"
This creates a serialized version of the object (e.g. a string) which can then
be used to persistantly store created certificates over restarts of the
application. The cache will only be serialized if it is a \s-1HASH.\s0
To work together with Storable the \f(CW\*(C`STORABLE_freeze\*(C'\fR function is defined to
call \f(CW\*(C`serialize\*(C'\fR.
.IP "\fB\f(CB$mitm\fB = IO::Socket::SSL::Intercept\->unserialize($string)\fR" 4
.IX Item "$mitm = IO::Socket::SSL::Intercept->unserialize($string)"
This restores an Intercept object from a serialized string.
To work together with Storable the \f(CW\*(C`STORABLE_thaw\*(C'\fR function is defined to
call \f(CW\*(C`unserialize\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Steffen Ullrich