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 a
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
113 This optional argument gives the starting point for the
114 serial numbers of the newly created certificates. Default
115 to 1.
116 cache HASH | SUBROUTINE
118 This optional argument gives a way to cache created
119 certificates, so that they don't get recreated on future
120 accesses to the same host. If the argument ist not given
121 an internal HASH ist used.
122 If the argument is a hash it will store for each generated
124 certificate a hash reference with "cert" and "atime" in the
125 hash, where "atime" is the time of last access (to expire
126 unused entries) and "cert" is the certificate. Please note,
127 that the certificate is in Net::SSLeays internal X509
128 format and can thus not be simply dumped and restored. The
129 key for the hash is an "ident" either given to "clone_cert"
130 or generated from the original certificate.
131 If the argument is a subroutine it will be called as
133 "$cache->(ident)" to get an existing certificate and with
134 "$cache->(ident,cert)" to cache the newly created
135 certificate.
136 ($clone_cert,$key) = $mitm->clone_cert($original_cert,[ $ident ])
138 This clones the given certificate. An ident as the key into the
139 cache can be given (like "host:port"), if not it will be created
140 from the properties of the original certificate. It returns the
141 cloned certificate and its key (which is the same for alle created
142 certificates).
143 $string = $mitm->serialize
145 This creates a serialized version of the object (e.g. a string)
146 which can then be used to persistantly store created certificates
147 over restarts of the application. The cache will only be serialized
148 if it is a HASH. To work together with Storable the
149 "STORABLE_freeze" function is defined to call "serialize".
150 $mitm = IO::Socket::SSL::Intercept->unserialize($string)
152 This restores an Intercept object from a serialized string. To
153 work together with Storable the "STORABLE_thaw" function is defined
154 to call "unserialize".
155
157 Steffen Ullrich
158perl v5.16.3 2013-05-31 IO::Socket::SSL::Intercept(3)