$OpenBSD: DESIGN-NOTES,v 1.25 2006/06/02 19:35:55 hshoexer 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 exchange 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 interfacing 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 that might happen sometime in the future where we will need the structure. These events then release 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 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 different 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, instead use the x509test program in src/regress/sbin/isakmpd/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. */