diff options
Diffstat (limited to 'sbin/isakmpd/DESIGN-NOTES')
| -rw-r--r-- | sbin/isakmpd/DESIGN-NOTES | 345 |
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? |