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