summaryrefslogtreecommitdiff
path: root/keyexchange/isakmpd-20041012/DESIGN-NOTES
diff options
context:
space:
mode:
authorOthmar Gsenger <otti@anytun.org>2007-12-27 11:13:13 +0000
committerOthmar Gsenger <otti@anytun.org>2007-12-27 11:13:13 +0000
commit6dc4f1912caf7f01f4b977ff8aaa50be61db2aba (patch)
treed7a281c430052e04156265d9ab3108c631360a5e /keyexchange/isakmpd-20041012/DESIGN-NOTES
parentremoved old isakmpd (diff)
adden new isakmpd
Diffstat (limited to 'keyexchange/isakmpd-20041012/DESIGN-NOTES')
-rw-r--r--keyexchange/isakmpd-20041012/DESIGN-NOTES414
1 files changed, 414 insertions, 0 deletions
diff --git a/keyexchange/isakmpd-20041012/DESIGN-NOTES b/keyexchange/isakmpd-20041012/DESIGN-NOTES
new file mode 100644
index 0000000..b47e80b
--- /dev/null
+++ b/keyexchange/isakmpd-20041012/DESIGN-NOTES
@@ -0,0 +1,414 @@
+$OpenBSD: DESIGN-NOTES,v 1.22 2003/06/04 07:27:31 ho Exp $
+$EOM: DESIGN-NOTES,v 1.48 1999/08/12 22:34:25 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.
+
+GCC -Wall clean, ANSI prototypes. System dependent facilities should be
+named sysdep_* and be placed in sysdep.c. Every C file should include
+sysdep.h as the first isakmpd include file. Primary target systems are OpenBSD
+and Linux, but porting to Microsoft Windows variants should not be made
+overly difficult.
+
+Note places which need reconsiderations with comments starting with the
+string "XXX", e.g.
+
+/* XXX Not implemented yet. */
+
+TOC
+---
+app.c Application support.
+attribute.c Attribute handling.
+cert.c Dispatching certificate related functions to the according
+ module based on the encoding.
+conf.c Interface to isakmpd configuration.
+connection.c Handle the high-level connection concept.
+constants.c Value to name map of constants.
+cookie.c Cookie generation.
+crypto.c Generic cryptography.
+dh.c Diffie-Hellman exchange logic.
+dnssec.c IKE authentication using signed DNS KEY RRs.
+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_aggressive.c
+ IKE's aggressive mode exchange logic.
+ike_auth.c IKE authentication method abstraction.
+ike_main_mode.c IKE's main mode exchange logic.
+ike_phase_1.c Common parts IKE's main & aggressive modes' 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.
+key.c Generic key handling.
+libcrypto.c Initialize crypto (OpenSSL).
+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_key_v2.c Interface with PF_KEY sockets (for use with IPsec).
+policy.c Keynote glue.
+prf.c Pseudo random functions.
+sa.c Handling of Security Associations (SAs).
+sysdep/*/sysdep.c
+ System dependent stuff.
+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 connection Persistent connections.
+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 deleting 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. Right now I have introduced a name
+for SAs, non-unique, that binds together SAs and their configuration
+parameters. This means both manual exchange runs and rekeying are simpler.
+Both struct exchange and struct sa does hold a reference count, but this is
+not entirely like a reference count in the traditional meaning where
+every reference gets counted. Perhaps it will be in the future, but for now
+we increment the count at allocation time and at times we schedule events
+tha might happen sometime in the future where we will need the structure.
+These events then realeases its reference when done. This way intermediate
+deallocation of these structures are OK.
+
+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. As the code looks now, exchanges
+*are* an abstraction in the code, and it has proven to be a rather nice
+way of having things.
+
+When the exchange has been found the exchange engine "runs" a script which
+steps forward for each incoming message, and on each reply to them.
+
+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, eleven such commands are implemented:
+
+c connect Establish a connection with a peer
+C configure Add or remove configuration entries
+d delete Delete an SA given cookies and message-IDs
+D debug Change logging level for a debug class
+p packet capture Enable/disable packet capture feature
+r report Report status information of the daemon
+t teardown Teardown a connection
+Q quit Quit the isakmpd process
+R reinitialize Reinitialize isakmpd (re-read configuration file)
+S report SA Report SA information to file /var/run/isakmp_sa
+T teardown all Teardown all Phase 2 connections
+
+For example you can do:
+
+c ISAKMP-peer
+
+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 "C" command takes 3 subcommands: set, rm and rms, for adding and removing
+entries + remove complete sections respectively. Examples:
+
+C set [Net-A]:Address=192.168.0.0
+C rm [Net-A]:Address
+C rms [Net-A]
+
+All these commands are atomic, i.e. they are not collected into larger
+transactions, which there should be a way to do, but currently isn't.
+
+The FIFO UI is also described in the isakmpd(8) man page.
+
+In addition to giving commands over the FIFO, you may send signals to the
+daemon. Currently two such signals are implemented:
+
+SIGHUP Re-initialize isakmpd (not fully implemented yet)
+SIGUSR1 Generate a report, much as the "r" FIFO command.
+
+For example, to generate a report, you do:
+
+unix# kill -USR1 <PID of isakmpd process>
+
+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 lengths.
+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.
+
+Configuration
+-------------
+
+Internally isakmpd uses a section-tag-value triplet database for
+configuration. Currently this happen to map really well to the
+configuration file format, which on the other hand does not map
+equally well to humans. It is envisioned that the configuration
+database should be dynamically modifiable, and through a lot of
+differnet mechanisms. Therefore we have designed an API for this
+purpose.
+
+int conf_begin ();
+int conf_set (int transaction, char *section, char *tag, char *value,
+ int override);
+int conf_remove (int transaction, char *section, char *tag);
+int conf_remove_section (int transaction, char *section);
+int conf_end (int transaction, int commit);
+
+The caller will always be responsible for the memory management of the
+passed strings, conf_set will copy the values, and not use the original
+strings after it has returned. Return value will be zero on success and
+non-zero otherwise. Note that the conf_remove* functions consider not
+finding anything to remove as failure.
+
+Identification
+--------------
+
+ISAKMP supports a lot of identity types, and we should too of course.
+
+* Phase 1, Main mode or Aggressive 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.
+
+* Phase 2, 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.
+Otherwise we today support IPV4_ADDR & IPV4_ADDR_SUBNET as ID types.
+
+X509-Certificates
+-----------------
+To use RSA Signature mode you are required to generate certificates.
+This can be done with ssleay, see man ssl. But the X509 certificates
+require a subjectAltname extension that can either be an IPV4 address,
+a User-FQDN or just FQDN. ssleay can not create those extension,
+insead use the x509test program in regress/x509 to modify an existing
+certificate. It will insert the subjectAltname extension and sign it
+with the provided private Key. The resulting certificate then needs
+to be stored in the directory pointed to by "Certs-directory" in
+section "X509-certificates".
+
+License to use
+--------------
+/*
+ * Copyright (c) 1999 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.
+ *
+ * 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.
+ */
+