diff options
Diffstat (limited to 'keyexchange/isakmpd-20041012/DESIGN-NOTES')
| -rw-r--r-- | keyexchange/isakmpd-20041012/DESIGN-NOTES | 414 |
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. + */ + |