path: root/sbin/isakmpd/DESIGN-NOTES

$OpenBSD: DESIGN-NOTES,v 1.4 1998/11/17 11:10:05 niklas Exp $
$EOM: DESIGN-NOTES,v 1.34 1998/10/11 20:25:08 niklas Exp $

General coding conventions
--------------------------
GNU indentation, Max 80 characters per line, KNF comments, mem* instead of b*,
BSD copyright, one header per module specifying the API.
Multiple inclusion protection like this:

#ifndef _HEADERNAME_H_
#define _HEADERNAME_H_

... Here comes the bulk of the header ...

#endif /* _HEADERNAME_H_ */

Start all files with RCS ID tags, i.e.


GCC -Wall clean, ANSI prototypes.  System dependent facilities should be
named sysdep_* and be placed in sysdep.c.  Primary target systems are OpenBSD
and Linux, but porting to Microsoft Windows variants should not be made
overly difficult.

Note places which needs reconsiderations with comments starting with the
string "XXX", e.g.

/* XXX Not implemented yet.  */

TOC
---
app.c		Application support.
asn.c		ASN.1 utilities.
asn_useful.c	ASN.1. useful structure defintions.
cert.c		Dispatching certificate related functions to the according
		module based on the encoding.
conf.c		Interface to isakmpd configuration.
constants.c	Value to name map of constants..
cookie.c	Cookie generation.
crypto.c	Generic cryptography.
dh.c		Diffie-Hellman exchange logic.
doi.c		Generic handling of different DOIs.
exchange.c	Exchange state machinery.
exchange_num.cst
		Some constants used for exhange scripts.
field.c		Generic handling of fields.
genconstants.sh
		Generate constant files from .cst source.
genfields.sh	Generate field description files from .fld source.
gmp_util.c	Utilities to ease interfaceing to GMP.
hash.c		Generic hash handling.
if.c		Network interface details.
ike_auth.c	IKE authentication method abstraction.
ike_main_mode.c	IKE's main mode exchange logic.
ike_quick_mode.c
		IKE's quick mode logic.
init.c		Initialization of all modules (might be autogenned in the 
		future).
ipsec.c		The IPSec DOI.
ipsec_fld.fld	Description of IPSec DOI-specific packet layouts.
ipsec_num.cst	Constants defined by the IPSec DOI.
isakmp_doi.c	The ISAKMP pseudo-DOI.
isakmp_fld.fld	Generic packet layout.
isakmp_num.cst	ISAKMP constants.
isakmpd.c	Main loop.
log.c		Logging of exceptional or informational messages.
math_2n.c	Polynomial math.
math_ec2n.c	Elliptic curve math.
math_group.c	Group math.
message.c	Generic message handling.
pf_encap.c	Interface with PF_ENCAP sockets (for use with IPSEC).
pkcs.c		PKCS#1: RSA Encryption Standard.
prf.c		Pseudo random functions.
sa.c		Handling of Security Associations (SAs).
sysdep-*.c	System dependent definitions.
timer.c		Timed events.
transport.c	Generic transport handling.
udp.c		The UDP transport.
ui.c		The "User Interface", i.e. the FIFO command handler.
util.c		Miscellaneous utility functions.
x509.c		Encoding/Decoding X509 Certificates and related structures.

Central datatypes
-----------------

struct constant_map	A map from constants to their ASCII names.
struct crypto_xf	A crypto class
struct doi		The DOI function switch
struct event		An event that is to happen at some point in time.
struct exchange		A description of an exchange while it is performed.
struct field		A description of an ISAKMP field.
struct group		A class abstracting out Oakley group operations
struct hash		A hashing class
struct ipsec_exch	IPSec-specific exchange fields.
struct ipsec_proto	IPSec-specific protocol attributes.
struct ipsec_sa		IPSec-specific SA stuff.
struct message		A generic ISAKMP message. 
struct payload		A "fat" payload reference pointing into message buffers
struct prf		A pseudo random function class
struct proto		Per-protocol attributes.
struct post_send	Post-send function chain node.
struct sa		A security association.
struct transport	An ISAKMP transport, i.e. a channel where ISAKMP
			messages are passed (not necessarily connection-
			oriented).  This is an abstract class, serving as
			a superclass to the different specific transports.

SAs & exchanges
---------------

struct exchange		Have all fields belonging to a simple exchange
			+ a list of all the SAs being negotiated.
			Short-lived.
struct sa		Only hold SA-specific stuff.  Lives longer.

In order to recognize exchanges and SAs it is good to know what constitutes
their identities:

Phase 1 exchange	Cookie pair (apart from the first message of course,
			where the responder cookie is zero.

ISAKMP SA		Cookie pair.  I.e. there exists a one-to-one
			mapping to the negotiation in this case.

Phase 2 exchange	Cookie pair + message ID.

Generic SA		Cookie pair + message ID + SPI. 

However it would be really nice to have a name of any SA that is natural
to use for human beings, for things like deleteing SAs manually.  The simplest
ID would be the struct sa address.  Another idea would be some kind of sequence
number, either global or per-destination.

The basic idea of control flow
------------------------------

The main loop just waits for events of any kind.  Supposedly a message
comes in, then the daemon looks to see if the cookies describes an
existing ISAKMP SA, if they don't and the rcookie is zero, it triggers a
setup of a new ISAKMP SA.  An exhaustive validation phase of the message
is gone through at this stage.  If anything goes wrong, we drop the packet
and probably send some notification back.  After the SA is found we try to
locate the exchange object and advance its state, else we try to create a
new exchange.

Need exchanges be an abstraction visible in the code?  If so an exchange is
roughly a very simple FSM (only timeouts and retransmissions are events that
does not just advance the state through a sequential single path).  The
informational exchange is such a special case, I am not sure it's interesting
to treat as an exchange in the logic of the implementation.  The only reason
to do so would be to keep the implementation tightly coupled to the
specification for ease of understanding.

When the exchange has been found the exchange engine "runs" a script which
steps forward for each incoming message.

Payload parsing details
-----------------------

After the generic header has been validated, we do a generic payload
parsing pass over the message and sort out the payloads into buckets indexed
by the payload type.  Note that proposals and transforms are part of the SA
payloads.  We then pass over them once more validating each payload
in numeric payload type order.  This makes SA payloads come naturally first.

Messages
--------

I am not sure there is any use in sharing the message structure for both
incoming and outgoing messages but I do it anyhow.  Specifically there are
certain fields which only makes sense in one direction.  Incoming messages
only use one segment in the iovec vector, while outgoing has one segment per
payload as well as one for the ISAKMP header.  The iovec vector is
reallocated for each payload added, maybe we should do it in chunks of a
number of payloads instead, like 10 or so.

Design "errors"
---------------

Currently there are two "errors" in our design.  The first one is that the
coupling between the IPSEC DOI and IKE is tight.  It should be separated by
a clean interface letting other key exchange models fit in instead of IKE.
The second problem is that we need a protocol-specific opaque SA part
in the DOI specific one.  Now both IPSEC ESP attributes takes place even
in ISAKMP SA structures.

User control
------------

In order to control the daemon you send commands through a FIFO called
isakmpd.fifo.  The commands are one-letter codes followed by arguments.
For now, only three commands are planned:

c	connect		Establish an ISAKMP SA with a peer
d	debug		Toggle some debug flag
r	report		Report status information of the daemon

For example you can do:

c udp 127.0.0.1:555 2 1

to get an ISAKMP SA established with the ISAKMP implementation listening
on UDP port 555 at the local host.  The SA will be established with an
identity protection (exchange type 2) exchange and use the IPSEC DOI (DOI 1).

In order to delete an SA you use the 'd' command.  However this is not yet
supported.

To alter the level of debugging in the "LOG_MISC" logging class to 99 you do:

D 0 99

The report command is just an "r", and results in a list of active exchanges
and security associations.

The constant descriptions
-------------------------

We have invented a simple constant description language, for the sake
of easily getting textual representations of manifest constants.
The syntax is best described by an example:

GROUP
  CONSTANT_A		1
  CONSTANT_B		2
.

This defines a constant map "group" with the following two defines:

#define GROUP_CONSTANT_A 1
#define GROUP_CONSTANT_B 2

We can now get the textual representation by:

  cp = constant_name (group, foo);

Here foo is an integer with either of the two constants as a value.

The field descriptions
----------------------

There is language for describing header and payload layouts too,
similar to the constant descriptions.  Here too I just show an example:

RECORD_A
  FIELD_A	raw 4
  FIELD_B	num 2
  FIELD_C	mask 1		group_c_cst
  FIELD_D	ign 1
  FIELD_E	cst 2		group_e1_cst,group_e2_cst
.

RECORD_B : RECORD_A
  FIELD_F	raw
.

This creates some utility constants like RECORD_A_SZ, RECORD_A_FIELD_A_LEN,
RECORD_A_FIELD_A_OFF, RECORD_A_FIELD_B_LEN etc.  The *_OFF contains the
octet offset into the record and the *_LEN constants are the lenghts.
The type fields can be: raw, num, mask, ign & cst.  Raw are used for
octet buffers, num for (unsigned) numbers of 1, 2 or 4 octet's length
in network byteorder, mask is a bitmask where the bit values have symbols
coupled to them via the constant maps given after the length in octets
(also 1, 2 or 4).  Ign is just a filler type, ot padding and lastly cst
denotes constants whose values can be found in the given constant map(s).
The last field in a record can be a raw, without a length, then just an
_OFF symbol will be generated.  You can offset the first symbol to the
size of another record, like is done above for RECORD_B, i.e. in that
case RECORD_A_SZ == RECORD_B_FIELD_F_OFF.  All this data are collected
in struct field arrays which makes it possible to symbolically print out
entire payloads in readable form via field_dump_payload.

Identification
--------------

ISAKMP supports a lot of identity types, and we should too of course.

* Main mode

Today when we connect we do it based on the peer's IP address.  That does not
automatically mean we should do policy decision based on IPs, rather we should
look at the ID the peer provide and get policy info keyed on that.

Perhaps we get an ID saying the peer is FQDN niklas.hallqvist.se, then our
policy rules might look like:

[IQ_FQDN]
# If commented, internal verification is used
#Verificator=	verify_fqdn
Accept=		no

[ID_FQDN niklas.hallqvist.se]
Policy=		MY_POLICY_001

[MY_POLICY_001]
# Whatever policy rules we might have.
Accept=		yes

Which means niklas.hallqvist.se is allowed to negotiate SAs with us, but
noone else.

* Quick mode

In quick mode the identities are implicitly the IP addresses of the peers,
which must mean the IP addresses actually used for the ISAKMP tunnel.

License to use
--------------
/*
 * Copyright (c) 1998 Niklas Hallqvist.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. All advertising materials mentioning features or use of this software
 *    must display the following acknowledgement:
 *	This product includes software developed by Ericsson Radio Systems.
 * 4. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*
 * This code was written under funding by Ericsson Radio Systems.
 */

Maybe we should skip clause 3?  Or redo it to mention the development was not
"by" but rather "funded by"?  I think the comment about funding after the
license might also mention the actual author(s).