1IO::Socket::SSL::IntercUespetr(3C)ontributed Perl DocumeInOt:a:tSioocnket::SSL::Intercept(3)
2
3
4

NAME

6       IO::Socket::SSL::Intercept -- SSL interception (man in the middle)
7

SYNOPSIS

9           use IO::Socket::SSL::Intercept;
10           # create interceptor with proxy certificates
11           my $mitm = IO::Socket::SSL::Intercept->new(
12               proxy_cert_file => 'proxy_cert.pem',
13               proxy_key_file  => 'proxy_key.pem',
14               ...
15           );
16           my $listen = IO::Socket::INET->new( LocalAddr => .., Listen => .. );
17           while (1) {
18               # TCP accept new client
19               my $client = $listen->accept or next;
20               # SSL connect to server
21               my $server = IO::Socket::SSL->new(
22                   PeerAddr => ..,
23                   SSL_verify_mode => ...,
24                   ...
25               ) or die "ssl connect failed: $!,$SSL_ERROR";
26               # clone server certificate
27               my ($cert,$key) = $mitm->clone_cert( $server->peer_certificate );
28               # and upgrade client side to SSL with cloned certificate
29               IO::Socket::SSL->start_SSL($client,
30                   SSL_server => 1,
31                   SSL_cert => $cert,
32                   SSL_key => $key
33               ) or die "upgrade failed: $SSL_ERROR";
34               # now transfer data between $client and $server and analyze
35               # the unencrypted data
36               ...
37           }
38

DESCRIPTION

40       This module provides functionality to clone certificates and sign them
41       with a proxy certificate, thus making it easy to intercept SSL
42       connections (man in the middle). It also manages a cache of the
43       generated certificates.
44

How Intercepting SSL Works

46       Intercepting SSL connections is useful for analyzing encrypted traffic
47       for security reasons or for testing. It does not break the end-to-end
48       security of SSL, e.g. a properly written client will notice the
49       interception unless you explicitly configure the client to trust your
50       interceptor.  Intercepting SSL works the following way:
51
52       •   Create a new CA certificate, which will be used to sign the cloned
53           certificates.  This proxy CA certificate should be trusted by the
54           client, or (a properly written client) will throw error messages or
55           deny the connections because it detected a man in the middle
56           attack.  Due to the way the interception works there no support for
57           client side certificates is possible.
58
59           Using openssl such a proxy CA certificate and private key can be
60           created with:
61
62             openssl genrsa -out proxy_key.pem 1024
63             openssl req -new -x509 -extensions v3_ca -key proxy_key.pem -out proxy_cert.pem
64             # export as PKCS12 for import into browser
65             openssl pkcs12 -export -in proxy_cert.pem -inkey proxy_key.pem -out proxy_cert.p12
66
67       •   Configure client to connect to use intercepting proxy or somehow
68           redirect connections from client to the proxy (e.g. packet filter
69           redirects, ARP or DNS spoofing etc).
70
71       •   Accept the TCP connection from the client, e.g. don't do any SSL
72           handshakes with the client yet.
73
74       •   Establish the SSL connection to the server and verify the servers
75           certificate as usually. Then create a new certificate based on the
76           original servers certificate, but signed by your proxy CA.  This is
77           the step where IO::Socket::SSL::Intercept helps.
78
79       •   Upgrade the TCP connection to the client to SSL using the cloned
80           certificate from the server. If the client trusts your proxy CA it
81           will accept the upgrade to SSL.
82
83       •   Transfer data between client and server. While the connections to
84           client and server are both encrypted with SSL you will read/write
85           the unencrypted data in your proxy application.
86

METHODS

88       IO::Socket::SSL::Intercept helps creating the cloned certificate with
89       the following methods:
90
91       $mitm = IO::Socket::SSL::Intercept->new(%args)
92           This creates a new interceptor object. %args should be
93
94           proxy_cert X509 | proxy_cert_file filename
95                   This is the proxy certificate.  It can be either given by
96                   an X509 object from Net::SSLeays internal representation,
97                   or using a file in PEM format.
98
99           proxy_key EVP_PKEY | proxy_key_file filename
100                   This is the key for the proxy certificate.  It can be
101                   either given by an EVP_PKEY object from Net::SSLeays
102                   internal representation, or using a file in PEM format.
103                   The key should not have a passphrase.
104
105           pubkey EVP_PKEY | pubkey_file filename
106                   This optional argument specifies the public key used for
107                   the cloned certificate.  It can be either given by an
108                   EVP_PKEY object from Net::SSLeays internal representation,
109                   or using a file in PEM format.  If not given it will create
110                   a new public key on each call of "new".
111
112           serial INTEGER|CODE
113                   This optional argument gives the starting point for the
114                   serial numbers of the newly created certificates. If not
115                   set the serial number will be created based on the digest
116                   of the original certificate. If the value is code it will
117                   be called with
118                   "serial(original_cert,CERT_asHash(original_cert))" and
119                   should return the new serial number.
120
121           cache HASH | SUBROUTINE
122                   This optional argument gives a way to cache created
123                   certificates, so that they don't get recreated on future
124                   accesses to the same host.  If the argument ist not given
125                   an internal HASH ist used.
126
127                   If the argument is a hash it will store for each generated
128                   certificate a hash reference with "cert" and "atime" in the
129                   hash, where "atime" is the time of last access (to expire
130                   unused entries) and "cert" is the certificate. Please note,
131                   that the certificate is in Net::SSLeays internal X509
132                   format and can thus not be simply dumped and restored.  The
133                   key for the hash is an "ident" either given to "clone_cert"
134                   or generated from the original certificate.
135
136                   If the argument is a subroutine it will be called as
137                   "$cache->(ident,sub)".  This call should return either an
138                   existing (cached) "(cert,key)" or call "sub" without
139                   arguments to create a new "(cert,key)", store it and return
140                   it.  If called with $cache->('type') the function should
141                   just return 1 to signal that it supports the current type
142                   of cache. If it reutrns nothing instead the older cache
143                   interface is assumed for compatibility reasons.
144
145       ($clone_cert,$key) = $mitm->clone_cert($original_cert,[ $ident ])
146           This clones the given certificate.  An ident as the key into the
147           cache can be given (like "host:port"), if not it will be created
148           from the properties of the original certificate.  It returns the
149           cloned certificate and its key (which is the same for alle created
150           certificates).
151
152       $string = $mitm->serialize
153           This creates a serialized version of the object (e.g. a string)
154           which can then be used to persistantly store created certificates
155           over restarts of the application. The cache will only be serialized
156           if it is a HASH.  To work together with Storable the
157           "STORABLE_freeze" function is defined to call "serialize".
158
159       $mitm = IO::Socket::SSL::Intercept->unserialize($string)
160           This restores an Intercept object from a serialized string.  To
161           work together with Storable the "STORABLE_thaw" function is defined
162           to call "unserialize".
163

AUTHOR

165       Steffen Ullrich
166
167
168
169perl v5.38.0                      2023-07-20     IO::Socket::SSL::Intercept(3)
Impressum