IPSec Plugin



Users Manual

Reference Manual

Downloads

Purchase








Contents

  1. Prerequisites.
  2. Installing IPSec.
  3. Installing the IKE Server.
  4. Security Associations.
  5. IPSec configuration file.
  6. Description of IPSec attributes.
  7. Typical scenarios.

    1. Transport mode.
      1. Host to Host connection.
    2. Tunnel mode.
      1. Gateway to Gateway connection.
      2. Host to Gateway connection.
      3. Nested SAs case.

  8. Configuring the IKE Server.

    1. Setting up isecrets.cfg.
    2. Starting the IKE Server.

  9. IPSec with Dynamic IP (Road Warrior).
  10. IPSec utilities.

    1. pinit (pluto init utility).
    2. sht (show SA table utilitiy).

  11. Troubleshooting.

    1. Auditable events and logging.


1. Prerequisites.

    In order to create a Virtual Private Network using the InJoy IPSec Plugin, the following steps must be completed:

    1. Install desired InJoy host-product on two hosts
    2. Install IPSec support on two hosts
    3. Install IKE server on two hosts
    4. Define tunnels between the hosts (Security Associations - SA)
      • Define each end (IP addresses)
      • Define whether authentication, or encryption, or both, is to be used.
    5. If encryption is used, exchange IKE Server secrets and ensure that each system knows the appropriate secret.
    6. Initialize system


2. Installing IPSec.

    There are two ways of getting the IPSec Plugin; as a zipped archive ready for extraction into the directory of appropriate InJoy product, or as an integrated part of the host product.

    If you received the plugin as a zipped archive, then extract it with Info-Zip's UNZIP.EXE (or PKUNZIP.EXE using the -d option).

    After installation the new binary file is demand-loaded by the host application when needed.

    Please consult the host product documentation for possible extra installation guidelines and IPSec options.


3. Installing the IKE Server

    Each IPSec endpoint must have an IKE server running that provides the ability to negotiate the Security Associations in a secure and standardized manner.

    For OS/2, the FreeS/WAN IKE Server ("Pluto") has been ported under the GNU Public License to be compatible with the InJoy IPSEC plugin.

    To install Pluto:

    1. Download Pluto from Hobbes.
    2. Download EMX runtime package revision 0.9d or higher from Hobbes.
    3. Install emx runtime packages (see emx documentation for detalis)
    4. Extract the pluto archive to a temp directory
    5. Copy exe-os2\pluto.exe and exe-os2\isecrets.cfg to the host product directory.
      Notice, if you would like to keep Pluto in a seperate directory, then be sure to copy iidll.dll, ipsec.dll and fxipsrt.dll from the host product to the Pluto directory or simply include the host product directory in your libpath.
    6. Configure the "loop back" inteface (ifconfig lo 127.0.0.1)
    7. Configure Pluto (see section "Configuring the IKE Server.").

4. Security Associations.

    A security association (SA) contains all the relevant information that communicating systems need in order to execute the IPSec protocols, such as AH or ESP. For example, a security association will identify the cryptographic algorithm to be used, the keying information, the identities of the participating parties and additional parameters. For better understanding of SA role in IPSec architecture please read "User Guide to IPSec".

    To make administrative tasks more easy Injoy IPSec plugin operates in terms of SA bundles rather then individual SAs. Each bundle determines all information critical to support the IPSec protocol between two IPSec endpoints. Each SA bundle must be defined in a separate section of the ipsec.cfg file.


5. IPSec configuration file.

    The IPSec configuration file ("ipsec.cfg") is made up of sections. Each section describes an SA bundle to be assosiated with an IPSec "connection". Connection is in quotes because IPSec operates on the Network Layer of the layered IP stack and applies to each IP packet regardless of its type and connection state.

    Notice, the entry names in ipsec.cfg are not significant, but only used for logging.

    Example of a section in ipsec.cfg:

    [my_secret_link] ; section name
    mode = tunnel ; mode of ipsec operation
    local = 195.97.1.40 ; local host or gateway IP address
    localnet = 192.168.3.0 ; local net
    localmask = 255.255.255.0 ; local mask
    remote = 195.97.161.1 ; remote host or gateway IP address
    remotenet = 192.168.2.0 ; remote net
    remotemask = 255.255.255.0 ; remote mask
    ah = yes ; requirement of AH support
    esp = yes ; requirement of ESP support
    reinit = yes ; requirement of SA initiation on restart
    [] ; end of section description

    Characters following ';' are comments and skipped by the IPSec Plugin.

    For further explanation of the attributes, refer to the: Description of IPSec attributes.


6. Description of IPSec attributes.

    Attributes
    Possible Values
    Description
    Section name
    string
    (Maximum length = 20 characters)
    Name of SA bundle. Useful for diagnostic purposes such as logging, alerting and monitoring. In Road Warrior SA's, using dynamic IP addresses, it is adviced to to set the name to "road_warrior", to simplify tracing and avoiding having more than one Road Warrior SA.
    mode
    transport
    tunnel
    If mode = transport IPSec applies only to IP packet payload. Original IP packet header is not modified. The AH or ESP header is inserted right after the IP header. This mode can be used only for Host to Host links.

    If mode = tunnel, the original (encapsulated) datagram is the payload for the new IP header. This mode must be used if at least one endpoint is an IPSec gateway. (*)

    local
    any valid IP address
    0.0.0.0
    Local host or IPSec gateway IP address.
    If local = 0.0.0.0, then this is a Road Warrior case. Road Warrior specifies that the local IP address is assigned dynamically (usually for PPP dial-up connections). See "Configuring Dynamic IP address support (Road Warrior case)" for details.
    localnet
    any valid net address
    if the "local" attribute specifies the IP address of a network gateway, then it is possible, using the "localnet" and "localmask" attributes, to specify an intranet for which all traffic will be processed according to the same SA bundle.
    localmask
    any valid net mask
    Netmask for "localnet".
    remote
    any valid IP address
    0.0.0.0
    Remote host or IPSec gateway IP address.
    If remote = 0.0.0.0, then this is Road Warrior case. This means that the section specifies an SA bundle for ALL IPSec hosts and gateways for which the IP addresses are not known. All IKE negotiations will be based on the same common secret. See "Configuring Dynamic IP address support (Road Warrior case)" for details.
    remotenet
    any valid net address
    if the "remote" attribute specifies the IP address of a network gateway, then it is possible to specify the intranet for which all traffic will be processed according to the same SA bundle.
    remotemask
    any valid net mask
    Netmask for "remotenet".
    ah
    yes
    no
    Requirement of AH support.
    esp
    yes
    no
    Requirement of ESP support.
    reinit
    yes
    no
    If reinit = yes, IKE negotiates to establish new SA's when the host application is restarted or re-connected. For example, with the Injoy Dialer that is when a new connection to the ISP is established or when the pinit.exe utility has been run. It is normal and highly recommended to syncronize between endpoints at this point, unless ... See below.

    reinit = no specifies that IKE negotiations won't be started until traffic between endpoints will appear. That's normal when remote = 0.0.0.0 (Road Warrior case) because the real IP address is not known and negotiation needs to be started by Road Warrior.

    (*) Note: Since the encapsulated header is not processed by the Internet routers, only the endpoints of the tunnel (the gateways) need to have globally assigned addresses; the hosts in the intranets behind them can be assigned private addresses, for example 10.x.x.x. NAT processing is not applied to IPSec traffic so both tunnel endpoints can use private addresses as if they were global. This technique dramatically extends the address-space available for the VPN.


7. Typical scenarios.

    This section describes four typical IPSec scenarios.

    The diagrams and text below describe the basic cases. The legend for the diagrams is:

    Transport mode.


    Host to Host connection.

    This scenario represents the simplest case of providing end-to-end security between 2 hosts across the Internet (or an Intranet).

    Config for Host 1
    Host 1 is local host (195.97.1.40).
    Host 2 is remote host (195.97.1.1).

    [host_to_host_case]
    mode = transport ; can be tunnel
    local = 195.97.1.40 ; local host IP address
    remote = 195.97.1.1 ; remote host IP address
    ah = yes
    esp = yes
    reinit = yes
    []

    Config for Host 2
    Host 2 is local host (195.97.161.40).
    Host 1 is remote host (195.97.161.1).

    [host_to_host_case]
    mode = transport ; can be tunnel
    local = 195.97.161.40 ; local host IP address
    remote = 195.97.161.1 ; remote host IP address
    ah = yes
    esp = yes
    reinit = yes
    []

    Note: mode can be tunnel on both sides but it has no special meaning.

    Tunnel mode.


    Gateway to Gateway connection.

    This scenario illustrates simple virtual private networks support.

    Config for Security Gateway 1
    Gateway 1 is local gateway (195.97.161.1).
    Gateway 2 is remote gateway (195.97.161.40).

    [our_company_vpn]
    mode = tunnel
    local = 195.97.161.1 ; local gateway IP address
    localnet = 192.168.3.0 ; local intranet
    localmask = 255.255.255.0 ; local intranet mask
    remote = 195.97.161.40 ; remote gateway IP address
    remotenet = 192.168.2.0 ; remote intranet
    remotemask = 255.255.255.0 ; remote intranet mask
    ah = yes
    esp = yes
    reinit = yes
    []

    Config for Security Gateway 2
    Gateway 2 is local gateway (195.97.161.40).
    Gateway 1 is remote gateway (195.97.161.1).

    [our_company_vpn]
    mode = tunnel
    local = 195.97.161.40 ; local gateway IP address
    localnet = 192.168.2.0 ; local intranet
    localmask = 255.255.255.0 ; local intranet mask
    remote = 195.97.161.1 ; remote gateway IP address
    remotenet = 192.168.3.0 ; remote intranet
    remotemask = 255.255.255.0 ; remote intranet mask
    ah = yes
    esp = yes
    reinit = yes
    []

    It is possible to define additional (nested) SA bundle directly between Host 1 and Host 2. First example ( Host to host connection) describes how to setup such bundle.

    Host to Gateway connection.

    This scenario covers the situation where a remote host (Host 1) uses the Internet to reach an organization's firewall (Gateway 2) and to then gain access to some server or other machine (Host 2). The remote host could be a mobile host (Host 1) dialing up to a local PPP/ARA server on the Internet and then crossing the Internet to the home organization's firewall (Gateway 2).

    Config for Host 1
    Host 1 is local host (195.97.161.1).
    Gateway 2 is remote gateway (195.97.161.40).

    [link_to_company]
    mode = tunnel
    local = 195.97.161.1 ; local host IP address
    remote = 195.97.161.40 ; remote gateway IP address
    remotenet = 192.168.2.0 ; remote intranet
    remotemask = 255.255.255.0 ; remote intranet mask
    ah = yes
    esp = yes
    reinit = yes
    []

    Config for Security Gateway 2
    Gateway 2 is local gateway (195.97.161.40).
    Host 1 is remote host (195.97.161.1).

    [home_employee_1]
    mode = tunnel
    local = 195.97.161.40 ; local gateway IP address
    localnet = 192.168.2.0 ; local intranet
    localmask = 255.255.255.0 ; local intranet mask
    remote = 195.97.161.1 ; remote host IP address
    ah = yes
    esp = yes
    reinit = yes
    []

    Nested SAs case.

    This example extends the previous scenario ( Host to gateway connection) with an additional SA bundle defined between Host 1 and Host 2.

    First, the outgoing traffic from Host 1 to Host 2 will be processed by the IPSec Plugin, according to the SA bundle "first" and after that according to the SA bundle "second". Incoming traffic from Host 2 will be processed in reverse order. For correct operation of the IPSec Plugin, Host 1 must define the "first" bundle prior to the "second". In other words, the order of appearence in the ipsec.cfg file strongly defines the order of IPSec processing.

    Config for Host 1
    Host 1 is local host (195.97.161.1).
    Gateway 2 is the remote gateway (195.97.161.40).
    Host 2 is a host in the remote intranet (192.168.2.50)

    [first] ; This section MUST be defined before section [second]
    mode = tunnel
    local = 195.97.161.1 ; local host IP address
    remote = 195.97.161.40 ; remote gateway IP address
    remotenet = 192.168.2.0 ; remote intranet
    remotemask = 255.255.255.0 ; remote intranet mask
    ah = yes
    esp = yes
    reinit = yes
    []
    [second] ; This section MUST be defined after section [first]
    mode = transport
    local = 195.97.161.1 ; local host IP address
    remote = 192.168.2.50 ; Host 2 IP address
    ah = yes
    esp = yes
    reinit = yes
    []

    Config for the Security Gateway 2
    Gateway 2 is the local gateway (195.97.161.40).
    Host 1 is the remote host (195.97.161.1).

    [home_employee_1]
    mode = tunnel
    local = 195.97.161.40 ; local gateway IP address
    localnet = 192.168.2.0 ; local intranet
    localmask = 255.255.255.0 ; local intranet mask
    remote = 195.97.161.1 ; remote host IP address
    ah = yes
    esp = yes
    reinit = yes
    []

    Config for Host 1
    Host 1 is the remote host (195.97.161.1).
    Gateway 2 is the local gateway (195.97.161.40).
    Host 2 is the local host (192.168.2.50)

    [link_to_host1]
    mode = transport
    local = 192.168.2.50 ; local host IP address
    remote = 195.97.161.1 ; remote host IP address
    ah = yes
    esp = yes
    reinit = yes
    []


8. Configuring the IKE Server.

    Setting up isecrets.cfg.

    A pluto daemon and another IKE daemon (for example, another instance of pluto) must convince each other that they are who they are supposed to be before any negotiation can succeed. This authentication is accomplished by using secrets that have been shared beforehand (manually). There are other techniques, but they have not been implemented in pluto.

    The file isecrets.cfg is used to keep preshared secret keys for authentication with other IKE daemons. The file is a sequence of entries and include directives.

    Here is an example.

    # sample isecrets.cfg file for 10.1.0.1
    10.1.0.1 10.2.0.1 "secret shared by two hosts"
    # an entry may be split across lines,
    # but indentation matters
    10.1.0.1 10.3.0.1 10.4.0.1 1.5.0.1

      10.6.0.1 10.7.0.1 1.8.0.1 "secret shared by 7"
    include ipsec.*.secrets # secrets in other files

    Each entry in the file is a list of indices, followed by a secret. To authenticate a connection between two hosts, the first entry that has both endpoints (hosts) as indices is used. Authentication requires that both systems find the identical secrets (the secret is not actually transmitted by the protocol). By requiring both addresses in the index list, we make the same entry suitable for both systems so verbatim copying can be used. This naturally extends to larger groups sharing the same secret. An index is an IP address (other kinds may come). It may be written in the familiar dotted quad form or as a domain name to be looked up. In many cases it is a bad idea to use domain names because the name server may not be running or may be insecure.

    A secret is a sequence of characters, delimited by the double-quote character ("). The sequence cannot contain a newline or double-quote. Strictly speaking, the secret is actually the sequence of bytes that is used in the file to represent the sequence of characters (excluding the delimiters).

    The first index of an entry must start in the first column of its line. Subsequent indices and the secret are separated by whitespace. A newline is taken as whitespace, but every line of an entry except the first must be indented.

    Whitespace at the end of a line is ignored. At the start of line or after whitespace, # and the following text up to the end of the line is treated as a comment. Within entries, all lines must be indented (including comments; blank lines cannot appear). Outside entries, no line may be indented (this is to make sure that the file layout reflects its structure).

    Between entries, the file may contain an include directive. This causes the contents of the named file to be processed before continuing with the current file. The include directive is a line that starts with the word include, followed by whitespace, followed by the filename (which must not contain whitespace).

    See also comments about special meaning of addresses "0.0.0.0" and "127.0.0.1" in the "Configuring Dynamic IP address support (Road Warrior case)" section.

    Starting the IKE Server.


    It is recommended to start the IKE server (i.e. Pluto) at system startup, or more importantly, before the InJoy host product.

    To start Pluto, issue the following command:

      pluto.exe --noklips

    To switch on full debugging, issue the following command:

      pluto.exe --noklips --debug-all.

    For any IKE Server (incl. Pluto), it is important that the UDP Port 500 is accessible and not occupied by another service.

    Note that all interoperation between Pluto and Injoy IPSec plugin is automatic and no additional preparation (except that documented above) is needed. For example, you need not use the whack utility shipped with Pluto to define or control SA bundles descriptions.

    If you wish to restart Pluto without restarting the InJoy host product, or if Pluto was started after host product, then the utility pinit must be used to "refresh" Pluto..

    All additional details about Pluto IKE Server functionality can be found in the original Pluto documentation.


9. IPSec with Dynamic IP (Road Warrior).

    "Road Warrior" is a term for the laptop user who needs to call home base and wants a secure connection. The problem is that configuration files define connections by the IP addresses involved and a Road Warrior's IP address is not known in advance.

    Current solution is that one connection may be defined for the IP address 0.0.0.0. On getting a connection request from an address not recognized, the Pluto server tries to authenticate it using the secret for 0.0.0.0. If this succeeds, a connection is created to the unrecognised address. This implies that all Road Warriors connecting to a Pluto server must share the same connection description and the same secret.

    As an example, please look at the "Host to gateway connection" diagram in the "Typical scenarios" section and assume that host-1 uses the InJoy Dialer with dynamic IP addressing.

    First it is needed to modify the 2 configuration files on the gateway PC, in order to support the remote road warriors.

    Security Gateway 2 isecrets.cfg:

    0.0.0.0 195.97.161.40 "password"

    Security Gateway 2 ipsec.cfg:

    [road_warrior]
    mode = tunnel
    local = 195.97.161.40 ; local gateway IP address
    localnet = 192.168.2.0 ; local intranet
    localmask = 255.255.255.0 ; local intranet mask
    remote = 0.0.0.0 ; any road warrior can fit
    ah = yes
    esp = yes
    reinit = no ; we don't know actual address so set it to "no"
    []

    Now it is needed to configure IPSec for the road warrior host (i.e. the Injoy Dialer). InJoy will report the server assigned IP address to the IPSec plugin at ISP connect time, requiring 0.0.0.0 in the ipsec.cfg file for Host 1:

    [link_to_company]
    mode = tunnel
    local = 0.0.0.0 ; we are road warrior
    remote = 195.97.161.40 ; remote gateway IP address
    remotenet = 192.168.2.0 ; remote intranet
    remotemask = 255.255.255.0 ; remote intranet mask
    ah = yes
    esp = yes
    reinit = yes
    []

    Immediately following a dialer connection, the IP address in the inner tables of IPSec will be automaticaly updated. The solution for Pluto is equally simple. Simply specify an entry in the isecrets.cfg file with the address of "127.0.0.1" and the address will be replaced (internally - not in the file) to the actual server assigned address.

    Example:

    Host 1 isecrets.cfg:

    195.97.161.40 127.0.0.1 "password"

    In this scenario, the address 195.97.161.40 belongs to the IPSec gateway, while e.g. the dynamic IP address 195.97.161.1 could be assigned to the Road Warrior. Logically the 0.0.0.0 entry in ipsec.cfg and the 127.0.0.1 entry in isecrets.cfg will be replaced with the 195.97.161.1 address.


10. IPSec utilities.

    pinit (pluto init utility).

    This utility instructs the Injoy IPSec plugin to initialize Pluto with parameters known only by the plugin. If Pluto was started before the host application, IPSec will initialize Pluto automatically, but if Pluto was restarted after the host application you need to invoke pinit.exe.

    sht (show SA table utilitiy).


    This utility dumps the current SA bundles table in the following format:

    Name = [bundle_name]
    ESP = [encryption_method/authentication_method/key_length]
    AH = [authentication_method/key_length]
    RW = [is_we_road_warrior?]
    Local IP/Net/Mask = [ip_address/ip_net/ip_mask]
    Remote IP/Net/Mask = [ip_address/ip_net/ip_mask]


11. Troubleshooting.

    Auditable events and logging.

    All auditable events are logged to ipsec.log and pluto.log

    The format of messages in ipsec.log is:

    [Time of message][Prefix][SA bundle name][Message]

    The following table shows the possible prefixes for ipsec.log messages:

    Prefix
    Description
    None
    Informational message. Such a message can include information about interoperations with Pluto or parameters of newly established SAs.
    Warning
    Warnings or non critical errors.
    Error
    This type of message require user attention. Typically such messages can appear in three cases:

  • The configuration of IPSec or IKE server is invalid
  • IKE server is not functioning
  • Your connection is under IPSec attack

    In the last case, log messages contain the reasons for packet dropping.

  • Internal Error
    Internal Error messages

    All errors can be viewed in the output window of the host application. To make sure that IPSec connections are secure, an operator must check for the existence of errors in ipsec.log on a regular basis.
    Remember: Reliability of any security solution is always in your hands!

    You can see examples of ipsec.log messages below:

    Examples
    Description
    Jul 28 01:07:42 : SA name = [secret2]
    Jul 28 01:07:42 : Local gateway (host) ip address = [195.97.161.1]
    Jul 28 01:07:42 : Local net = [255.255.255.255]
    Jul 28 01:07:42 : Local net mask = [0.0.0.0]
    Jul 28 01:07:42 : Remote gateway (host) ip address = [195.97.161.40]
    Jul 28 01:07:42 : Remote net = [192.168.2.0]
    Jul 28 01:07:42 : Remote net mask = [255.255.255.0]
    Jul 28 01:07:42 : SA lifetime = [3600] seconds
    Jul 28 01:07:42 : ESP encr/auth/keylen = [ESP_ALG_CBC_3DES/AH_ALG_NONE/24]
    Jul 28 01:07:42 : AH method/keylen = [AH_ALG_MD5/16]
    Jul 28 01:07:42 : Road Warrior = [yes]
    These are typical informational messages, following the negotiation of the SA with the remote gateway.
    Jul 28 01:59:09 : Warning (secret2) : packet from ipsec host without ah and esp. discarded Remote IPSec sent plain IP packet without AH or ESP header. Possible cause: resyncronization of IPSec required or IPSec at remote site is down.
    Jul 28 23:32:54 1999 : Error (secret2) : ah_check: wrong AH digest. Possible IPSec attack!
    Jul 28 23:12:34 1999 : INTERNAL ERROR : ipsec_out: can't malloc Please report if you see INTERNAL ERRORs in the log.

    For more information about pluto.log, refer to the Pluto documentation.



Copyright © 1999, 2000, F/X Communications. All rights reserved.
InJoy IPSec Plugin is published by F/X Communications
webmaster@fx.dk