[roudaut <roudaut@xxxxxxxx>]

Hi everyone,

I adapted the IPSEC dissector in order to decrypt ESP payload based on
known SAs.It uses the few algorithms described in RFC 4305.
It also uses libopenssl.

If you prefer a patch please ask me. Otherwise, the file is the following :
- packet-ipsec.c

(It is still possible to decrypt ESP payloads with the assumption that 
it is null encrypted and the Authenticator field is 12 bytes as in the
original dissector).

I wrote a little doc in :
- README_DISSECTOR_IPSEC (have a look to install the dissector)

And I put exemple files :

- A capture file : capture.pcap

- Some preferences files with the configurations for v4 and V6
        - preferences_v4
        - preferences_v6

- The sad has been run using : ipsec.conf (config file for setkey)
  I have not tested it for AES-CTR. So if you can, please send me a
  report on it.

- If you want to get another capture file. You may use both following
scripts on Linux:
         - neigh.sh : for establishing neighborhood
         - ping_v6_v4.sh : in order to send ping v4 and v6


I hope it will be helpfull for some of you.


Best regards,

--
Fr�d�ric ROUDAUT
IRISA-INRIA, Campus de Beaulieu, 35042 Rennes cedex, France
Tl: +33 (0) 2 99 84 71 44, Fax: +33 (0) 2 99 84 71 71








--
Fr�d�ric ROUDAUT
IRISA-INRIA, Campus de Beaulieu, 35042 Rennes cedex, France
Tl: +33 (0) 2 99 84 71 44, Fax: +33 (0) 2 99 84 71 71

README : IPSEC Dissector to decrypt ESP Payload (v1.0)
======================================================


 Author: Frederic ROUDAUT 
(frederic.roudaut@xxxxxxxx or
 frederic.roudaut@xxxxxxx)

 Date : February 2006



1 - INTRODUCTION
2 - NEEDS AND INSTALLATION
3 - IPSEC ALGORITHMS AND KEYS
3.1 - ESP ALGORITHMS
3.1.1 - REQUIREMENTS
3.1.2 : TripleDES-CBC [RFC2451]
3.1.3 : AES-CBC with 128-bit keys [RFC3602]
3.1.4 : AES-CTR [RFC3686]
3.1.5 : DES-CBC [RFC2405]
3.1.6 : HMAC-MD5-96 [RFC2403]
3.1.7 : HMAC-SHA1-96 [RFC2404]
3.1.8 : AES-XCBC-MAC-96 [RFC3566]
3.2 - AH ALGORITHMS
3.2.1 - REQUIREMENTS
4 - ESP PREFERENCES
4.1 - FIELD: Attempt to detect/decode NULL encrypted ESP payloads
4.2 - FIELD: Attempt to detect/decode encrypted ESP payloads
4.3 - SECURITY ASSOCIATIONS AND SA FILTERS
4.4 - ENCRYPTION, AUTHENTICATION ALGORITHMS & KEYS
5 - POSSIBLE EXTENSIONS
6 - CREDITS AND LICENCE
7 - BUGS


1 - INTRODUCTION
----------------

The goal of this README is to provide information for the
evolutions that I have made to the existing IPsec dissector of
Ethereal. (www.ethereal.org)

The current IPsec dissector was suffering from the two followings
points:
 
- It was not possible to decrypt ESP (Encapsulating Security Payload)
  Payload. We nevertheless remind that this is possible to do this
  using tcpdump.
- There was no checking of ESP (Encapsulating Security Payload) and AH
  (Authentication Header) Authenticators.

The Dissector given with this README tries to solve only the first
point although some entries are left to permit future developments for
the second point. 

This Dissector uses LIBOPENSSL. According to the Ethereal Web Pages
(www.ethereal.org), you can use OPENSSL with GPL Software with the
following restrictions:

- On many systems including the major Linux and BSD distributions,
there is no problem. the GPL does not place restrictions on using
libraries that are part of the normal operating system distribution.

- On other systems, the situation is less clear. Some GPL software
  copyright holders claim that you infringe on their rights if you use
  OpenSSL with their software on operating systems that don't normally
  include OpenSSL.

Thus, this Dissector is released under the GPL with the additional
exemption that compiling, linking, and/or using OpenSSL is
allowed. See the LICENCE Chapter for perhaps some more explanations.



2 - NEEDS AND INSTALLATION
--------------------------

Ethereal runs on many platforms, and can be compiled with a number of
different compilers.

This dissector has not been tested against a lot of implementations
but I have tried to respect the README.developer of Ethereal. 

Nevertheless, here are what I have used to develop it :

- OS : Linux (mandrake 10.1, mandriva 2006, Kernel: 2.6), Freebsd 5.3 
- gcc version 3.4.1, 3.4.2
- libopenssl : 0.9.7 & 0.9.7d
- Ethereal 0.10.11 to 0.10.14 and current source available in
  subversion in February 2006.
 
In order to use this dissector, you only need to have Ethereal
sources, libopenssl installed. Copy packet-ipsec.c in
ethereal/epan/dissector. Check that IPSEC_USE_OPENSSL is defined in
packet-ipsec.c, otherwise the dissector will be as the old one
without decryption of ESP Packets. Go into Ethereal root and do :
make distclean && ./configure --with-ssl && make 


3 - IPSEC ALGORITHMS AND KEYS
-----------------------------

Currently IPsec is mainly described by the three followings RFCs:

- RFC4301, Security Architecture for the Internet Protocol, S. Kent,
         K. Seo, December 2005, PROPOSED STANDARD.
- RFC4302, IP Authentication Header, S. Kent, December 2005, PROPOSED
          STANDARD.
- RFC4303, IP Encapsulating Security Payload (ESP), S. Kent, December
         2005, PROPOSED STANDARD.


The Algorithms to use and their requirements are described in
RFC4305: Cryptographic Algorithm Implementation Requirements for
Encapsulating Security Payload (ESP) and Authentication Header (AH),
D. Eastlake 3rd, December 2005, PROPOSED STANDARD.



3.1 - ESP ALGORITHMS (RFC 4305)
------------------------------

The ESP Format is the following:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               Security Parameters Index (SPI)                 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                      Sequence Number                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                    Payload Data (variable)                    |
~                                                               ~
|                                                               |
+               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|               |     Padding (0-255 bytes)                     |
+-+-+-+-+-+-+-+-+               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                               |  Pad Length   | Next Header   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                 Authentication Data (variable)                |
~                                                               ~
|                                                               |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


3.1.1 - REQUIREMENTS
--------------------

The followings tables (RFC 4305) list Encryption and Authentication
algorithms for the IPsec Encapsulating Security Payload protocol.

Requirement    Encryption Algorithm (notes)
-----------    --------------------
MUST           NULL (1)
MUST-          TripleDES-CBC [RFC2451]
SHOULD+        AES-CBC with 128-bit keys [RFC3602]
SHOULD         AES-CTR [RFC3686]
SHOULD NOT     DES-CBC [RFC2405] (3)

Requirement    Authentication Algorithm (notes)
-----------    ------------------------
MUST           HMAC-SHA1-96 [RFC2404]
MUST           NULL (1)
SHOULD+        AES-XCBC-MAC-96 [RFC3566]
MAY            HMAC-MD5-96 [RFC2403] (2)

Notes:

(1) Since ESP Encryption and Authentication are optional, support for
the two "NULL" algorithms is required to maintain consistency
with the way these services are negotiated.  Note that while
Authentication and Encryption can each be "NULL", they MUST NOT
both be "NULL".
(2) Weaknesses have become apparent in MD5; however, these should not
affect the use of MD5 with HMAC.
(3) DES, with its small key size and publicly demonstrated and open-
design special-purpose cracking hardware, is of questionable
security for general use.



3.1.2 : TripleDES-CBC [RFC2451]
-------------------------------

According to RFC 2451, 3DES CBC uses a key of 192 bits. The first 3DES
key is taken from the first 64 bits, the second from the next 64 bits,
and the third from the last 64 bits. Implementations MUST take into
consideration the parity bits when initially accepting a new set of
keys.  Each of the three keys is really 56 bits in length with the
extra 8 bits used for parity.
3DES CBC uses an IV of 8 octets.


3.1.3 : AES-CBC with 128-bit keys [RFC3602]
-------------------------------------------

According to RFC 3602, AES supports three key sizes: 128 bits, 192
bits, and 256 bits.  The default key size is 128 bits, and all
implementations MUST support this key size.  Implementations MAY also
support key sizes of 192 bits and 256 bits. 
AES-CBC uses an IV of 16 octets.


3.1.4 : AES-CTR [RFC3686]
-------------------------

According to RFC 3686, AES supports three key sizes: 128 bits, 192
bits, and 256 bits.  The default key size is 128 bits, and all
implementations MUST support this key size.  Implementations MAY also
support key sizes of 192 bits and 256 bits. 
AES-CTR uses an IV of 8 octets.


3.1.5 : DES-CBC [RFC2405]
-------------------------

According to RFC 2405, DES-CBC is a symmetric secret key
algorithm. The key size is 64-bits. It is commonly known as a 56-bit
key as the key has 56 significant bits; the least significant bit in
every byte is the parity bit. 
DES-CBC uses an IV of 8 octets.


3.1.6 : HMAC-MD5-96 [RFC2403]
-----------------------------

HMAC with MD5 provides data origin Authentication and integrity
protection. HMAC-MD5-96 produces a 128-bit authenticator value.  This
128-bit value can be truncated as described in RFC 2104. For use with
either ESP or AH, a truncated value using the first 96 bits MUST be
supported.  Upon sending, the truncated value is stored within the
authenticator field. Upon receipt, the entire 128-bit value is
computed and the first 96 bits are compared to the value stored in the
authenticator field. No other authenticator value lengths are
supported by HMAC-MD5-96. The length of 96 bits was selected because
it is the default authenticator length as specified in [RFC2402] and
meets the security requirements described in [RFC2104].


3.1.7 : HMAC-SHA1-96 [RFC2404]
------------------------------

SHA-1 [FIPS-180-1] combined with HMAC [RFC2104] provides a keyed
Authentication mechanism. HMAC-SHA-1-96 produces a 160-bit
authenticator value.  This 160-bit value can be truncated as described
in RFC2104.  For use with either ESP or AH, a truncated value using
the first 96 bits MUST be supported. Upon sending, the truncated value
is stored within the authenticator field.  Upon receipt, the entire
160-bit value is computed and the first 96 bits are compared to the
value stored in the authenticator field. No other authenticator value
lengths are supported by HMAC-SHA-1-96. The length of 96 bits was
selected because it is the default authenticator length as specified
in [RFC2402] and meets the security requirements described in
[RFC2104].


3.1.8 : AES-XCBC-MAC-96 [RFC3566]
---------------------------------

AES-XCBC-MAC-96 is a secret key algorithm.  For use with either ESP or
AH a fixed key length of 128-bits MUST be supported.  Key lengths
other than 128-bits MUST NOT be supported (i.e., only 128-bit keys are
to be used by AES-XCBC-MAC-96).

AES-XCBC-MAC-96 actually requires 384 bits of keying material (128
bits for the AES keysize + 2 times the blocksize).  This keying
material can either be provided through the key generation mechanism
or it can be generated from a single 128-bit key.  The latter approach
has been selected for AES-XCBC-MAC-96, since it is analogous to other
authenticators used within IPsec.  The reason AES-XCBC-MAC-96 uses 3
keys is so the length of the input stream does not need to be known in
advance.  This may be useful for systems that do one-pass assembly of
large packets.

AES-XCBC-MAC produces a 128-bit authenticator value.  AES-XCBC-MAC-96
is derived by truncating this 128-bit value as described in [HMAC] and
verified in [XCBC-MAC-2].  For use with either ESP or AH, a truncated
value using the first 96 bits MUST be supported.  Upon sending, the
truncated value is stored within the authenticator field.  Upon
receipt, the entire 128-bit value is computed and the first 96 bits
are compared to the value stored in the authenticator field.  No other
authenticator value lengths are supported by AES-XCBC-MAC-96.

The length of 96 bits was selected because it is the default
authenticator length as specified in [AH] and meets the security
requirements described in [XCBC-MAC-2].



3.2 - AH ALGORITHMS (RFC 4305)
------------------------------

The AH Header is the following:


    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Next Header   |  Payload Len  |          RESERVED             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                 Security Parameters Index (SPI)               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Sequence Number Field                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   +                Authentication Data (variable)                 |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


3.2.1 - REQUIREMENTS
--------------------

The implementation conformance requirements for security algorithms
for AH are given below (RFC4305). As you would suspect, all of these
algorithms are authentication algorithms.

Requirement    Algorithm (notes)
-----------    ---------
MUST           HMAC-SHA1-96 [RFC2404]
SHOULD+        AES-XCBC-MAC-96 [RFC3566]
MAY            HMAC-MD5-96 [RFC2403] (1)

Note:

(1) Weaknesses have become apparent in MD5; however, these should not
affect the use of MD5 with HMAC.



4 - ESP PREFERENCES
-------------------

In order to decrypt ESP Payload, you need to give some elements of the
known Security Associations (SA). I.e :

- The Source Address of the SA. Either IPv6, either IPv4.
- The Destination Address of the SA. Either IPv6, either IPv4.
- The SPI (Security Parameter Index). 
- The Encryption algorithm and the associated key.
- The Authentication algorithm, since it has some impact on the bytes
  alignment.

These differents elements has to be indicated in The ESP Preferences
Menu of Ethereal. Indeed, it would perhaps have been better to set it
in a separate file, but I wanted to have at least a few rules in the
Preferences Box. Moreover the parsing is quite basic, without the use
of any library/tool such as Lex/yacc for example. I did not wanted to
add some other requierements to Ethereal. 

Because I had no way to add a crossbar and dynamic adding of SA in
Ethereal, the number of Security Associations Max is fixed to 5 by
default. If you need to modify this value, you have to do it in the 
dissector by modifying the value of "IPSEC_NB_SA".

 

4.1 - FIELD: Attempt to detect/decode NULL encrypted ESP payloads
-----------------------------------------------------------------

This field is an heuristic in order to decrypt packet. It assumes that
packet are encrypted using the NULL algorithm and the Authentication
uses 12 bytes as with hmac-sha1-96/aes-xcbc-mac-96/hmac-md5-96. 
This field Should be the only one available if Ethereal is not linked
with libopenssl. Otherwise, if set, all packets that are not catched
by the Security Associations are decrypted using this heuristic.  


4.2 - FIELD: Attempt to detect/decode encrypted ESP payloads
------------------------------------------------------------

This field Should be available only if Ethereal is linked with
libopenssl. It is used to activate the Security Associations. When an
IPsec ESP packet will be catched by a Security Assciation
(Source/Destination/SPI) it will be decrypted using the specified
Encryption/Authentication Algorithm and the associated Encryption Key. 
We nevevertheless may notice that choosing one of
hmac-sha1-96/aes-xcbc-mac-96/hmac-md5-96 for Authentication will have
no impact on the decryption since all this algorithm will give a
12-bytes authentictor field. Nevertheless, I have made the distinction
for future purpose ... such as checking the authenticator field for example.


4.3 - SECURITY ASSOCIATIONS AND SA FILTERS
------------------------------------------

This field uses the following syntax : 

Protocol|Source Address|Destination Adress|SPI

Where :

- Protocol: either IPv4, IPv6 (upper and/or lowercase letters)

- SPI : the Security Parameter Index of the Security Association. 
      You may indicate it in decimal (ex: 123) or in hexadecimal
      (ex: 0x45). The special keywords '*' may be used to match any SPI.
      Nevertheless, if you use more than one '*', it will restrict the
      length of the SPI in decimal to as many '*' as indicated. 
      For example '**' will match 23 but not 234. 234 will be match by
      '***'. No checking will be done on the SPI value. Thus you have
      to take into account that the SPI is 4 bytes length. 

- Addresses : In this field we may have IPv6 or IPv4 address. 
      Any address is a combination of an address or a prefix and a
      Prefixlen/Netmask separated by '/'. You may omit the
      Prefixlen/Netmask, assuming that the Adress is 128 bits length
      for IPv6 and 32 bits length for IPv4. The character '*' used at
      the Prefixlen/Netmask position will be as if you had omit it. 
      
      * IPv6 Addresses : Any valid IPv6 address is accepted.
      ex: 3FFE::1/128, 3FFE:4:5:6666::/64, ::1/128, 3FFE:4::5
      
      If your address is incorrect and longer than 16 bytes, only the
      last 16 bytes will be taken into account.       
      You also may use the special character '*' to indicate any 4
      bits block. ie : 3ffe::45*6. If you use only one '*' in the
      Address field it will accept any IPv6 address.

      * IPv4 Addresses : Any valid IPv4 address is accepted. 
      ex : 190.0.0.1/24, 10.0.0.2.
      You also may use the special character '*' to indicate any 8
      bits block. ie : 190.*.*.3. If you use only one '*' in the
      Address field it will accept any IPv4 address. No checking of
      correct IPv4 address will be done. For example 456.345.567.890
      will be accepted. Thus you have to take care about what you
      write. Nevertheless only 3 characters will be taken into account
      for one byte. Ex : 190.0.0.0184 will not be considered
      correct. (Instead a kind of LRU Mechanism will be used and the
      address taken into account will be 190.0.0.418). Moreover only
      the four first values will be used (Ie 190.0.0.12.13 will be
      considered as 190.0.0.12).
 


4.4 - ENCRYPTION, AUTHENTICATION  ALGORITHMS & KEYS
---------------------------------------------------

In these fields you have to describe the Authentication, Encryption
Algorithms and the Encryption Key for the SA. The key size should be
conformant with what is specified in the Algorithms otherwise it will
not work.  


5 - POSSIBLE EXTENSIONS
-----------------------

For sure, you may use some others ESP Encryption algorithms. I only
have done the work for Algorithms specified in RFC4305. Nevertheless, 
it should not be very difficult to add some other ones. 

You also will notice that there is not really a need to describe
Authentication algorithm, since all of them (except the NULL
Authentication) use a 12 bytes field. 
Nevertheless, it will permit to add some other ones with a different 
length. Moreover it could also permit to add the checking of
Authentication. If you have a look to the code you will see that a few
things are already done for that. You have to uncomment specified
parts, to get the Authentication key. What you only need to do then is
to write the checking. It also should be possible to adapt this to
check AH Authentication and why not to do things for IPComp.  

If the maximum number of Security Associations fixed is a problem for
you, you may modify this value in the dissector "IPSEC_NB_SA". 
It could also be interesting to keep a few SAs in the Preferences Box
and have a way to add some more in a separate file.



6 - CREDITS AND LICENCE
-----------------------

The Original Dissector was developed by Gerald Combs
<gerald@xxxxxxxxxxxx> under the GNU General Public License.

This Dissector is released under the GPL with the additional exemption
that compiling, linking, and/or using OpenSSL is allowed. 

This dissector is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.



7 - BUGS
--------

This dissector has been tested using the script "fuzz-test.sh"
available on the Ethereal web pages. 

If you find any bug you may send me the capture file with 
associated keys and algorithms at :

frederic.roudaut@xxxxxxx

Attachment: IPSEC_1.0.tgz
Description: application/compressed-tar