summaryrefslogtreecommitdiff
path: root/keyexchange/isakmpd-20041012/DESIGN-NOTES
diff options
context:
space:
mode:
authorOthmar Gsenger <otti@anytun.org>2007-12-08 20:59:57 +0000
committerOthmar Gsenger <otti@anytun.org>2007-12-08 20:59:57 +0000
commitf84dc62cc602eacb0daee3e9918a68b711ba94f0 (patch)
tree1acbdabf30b2ece1da880386da6a4b7c002669c3 /keyexchange/isakmpd-20041012/DESIGN-NOTES
parent* added AuthTag class (diff)
removed isakmpd
Diffstat (limited to 'keyexchange/isakmpd-20041012/DESIGN-NOTES')
-rw-r--r--keyexchange/isakmpd-20041012/DESIGN-NOTES414
1 files changed, 0 insertions, 414 deletions
diff --git a/keyexchange/isakmpd-20041012/DESIGN-NOTES b/keyexchange/isakmpd-20041012/DESIGN-NOTES
deleted file mode 100644
index b47e80b..0000000
--- a/keyexchange/isakmpd-20041012/DESIGN-NOTES
+++ /dev/null
@@ -1,414 +0,0 @@
-$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.
- */
-