1IO::Socket::SSL::IntercUespetr(3C)ontributed Perl DocumeInOt:a:tSioocnket::SSL::Intercept(3)
2
6 IO::Socket::SSL::Intercept -- SSL interception (man in the middle)
7
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
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
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 • 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 Using openssl such a proxy CA certificate and private key can be
60 created with:
61 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 • 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 • Accept the TCP connection from the client, e.g. don't do any SSL
72 handshakes with the client yet.
73 • 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 • 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 • 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
88 IO::Socket::SSL::Intercept helps creating the cloned certificate with
89 the following methods:
90 $mitm = IO::Socket::SSL::Intercept->new(%args)
92 This creates a new interceptor object. %args should be
93 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 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 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 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 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 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 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 ($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 $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 $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
165 Steffen Ullrich
166perl v5.38.0 2023-07-20 IO::Socket::SSL::Intercept(3)