Initial import of isakmpd, an IKE (ISAKMP/Oakley) implementation for the

OpenBSD IPSEC stack by me, Niklas Hallqvist and Niels Provos, funded by
Ericsson Radio Systems.  It is not yet complete or usable in a real scenario
but the missing pieces will soon be there.  The early commit is for people
who wants early access and who are not afraid of looking at source.
isakmpd interops with Cisco, Timestep, SSH & Pluto (Linux FreeS/WAN) so
far, so it is not that incomplete.  It is really mostly configuration that
is lacking.

1 files changed, 345 insertions, 0 deletions

diff --git a/sbin/isakmpd/DESIGN-NOTES b/sbin/isakmpd/DESIGN-NOTES
new file mode 100644
index 00000000000..da3abe9181e
--- /dev/null
+++ b/sbin/isakmpd/DESIGN-NOTES
@@ -0,0 +1,345 @@
+$Id: DESIGN-NOTES,v 1.1 1998/11/15 00:03:48 niklas Exp $
+
+General coding conventions
+--------------------------
+GNU indentation, Max 80 characters per line, KNF comments, mem* instead of b*,
+BSD copyright (GPL alternative?), 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.
+
+/*	$Id: DESIGN-NOTES,v 1.1 1998/11/15 00:03:48 niklas Exp $	*/
+
+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).  Possibly the GPL should
+be added as a 2ary distribution license to use if wanted?