├── .gitignore ├── .merlin ├── .travis.yml ├── README.md ├── _tags ├── build ├── common ├── c.ml ├── ike.mlpack ├── monad.ml └── utils.ml ├── helper ├── pf_to_fd.c └── pf_to_tcp.c ├── lwt └── ike_lwt.ml ├── opam ├── pfkey ├── pfkey_coding.ml ├── pfkey_coding.mli ├── pfkey_engine.ml ├── pfkey_engine.mli └── pfkey_wire.ml ├── rfc ├── rfc2367.txt └── rfc7296.txt └── src ├── config.mli ├── control.mli ├── crypto.mli ├── decode.mli ├── dispatcher.ml ├── dispatcher.mli ├── encode.mli ├── engine.ml ├── engine.mli └── packet.ml /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | *byte 3 | *native 4 | helper/pf_to_tcp 5 | helper/pf_to_fd 6 | -------------------------------------------------------------------------------- /.merlin: -------------------------------------------------------------------------------- 1 | S common 2 | S src 3 | S pfkey 4 | S lwt 5 | 6 | B _build/** 7 | 8 | FLG -safe-string -warn_error -w +A-4-6-44-48 9 | 10 | PKG cstruct 11 | PKG lwt 12 | PKG lwt.unix 13 | PKG result 14 | PKG sexplib 15 | PKG nocrypto 16 | PKG astring 17 | PKG logs 18 | PKG logs.lwt 19 | PKG ipaddr 20 | PKG alcotest 21 | PKG fmt 22 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: c 2 | install: wget https://raw.githubusercontent.com/ocaml/ocaml-travisci-skeleton/master/.travis-opam.sh 3 | script: bash -ex .travis-opam.sh 4 | sudo: required 5 | env: 6 | global: 7 | - PACKAGE="ike" 8 | matrix: 9 | - OCAML_VERSION=4.02 10 | - OCAML_VERSION=4.03 11 | - OCAML_VERSION=4.04 12 | notifications: 13 | email: false 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | IKEv2 2 | ===== 3 | 4 | [![Build Status](https://travis-ci.org/isakmp/ike.svg?branch=master)](https://travis-ci.org/isakmp/ike) 5 | 6 | ![Screenshot](http://berlin.ccc.de/~hannes/ike1.png) 7 | 8 | The Internet Key Exchange is the protocol to setup security associations. Those 9 | are used by the kernel to sign and encrypt (depending on policy) IP frames to 10 | peers (in transport or tunnel mode). The IKE daemon supplies keying material 11 | for the ESP/AH connections. 12 | 13 | IKE communicates with the kernel via a raw PF_KEY socket (exchanging information 14 | about security policies, traffic selectors, and security associations (SA) - the 15 | kernel can ask the IKE daemon to establish SAs if there's a policy but no SA). 16 | Also, the kernel signals soft and hard resource limits (time, bytes) on a SA, 17 | the IKE daemon then needs to do rekeying on that SA. NAT traversal is handled 18 | somehow as well. 19 | 20 | IKE also communicates via UDP (port 500) to remote IKE daemons to establish IKE 21 | sessions and negotiate SAs. 22 | 23 | Two more communication channels are a control interface (for the user) to 24 | dynamically adjust selectors (not entirely sure about this!?), and a timer 25 | (mainly for retransmissions). 26 | 27 | 28 | This package will provide at some point in the future IKEv2 and PFKEY_V2, using 29 | the coarse structure (see `_tags` for up-to-date information): 30 | 31 | `common` contains utillities used by the other modules (compiles) 32 | - Utils contains general useful utilities 33 | - Monad is the monadic control flow 34 | - C (the core definitions) contains high-level types 35 | 36 | `pfkey` contains the PFKEYv2 protocol (RFC2367 + policy extensions) (compiles) 37 | - Pfkey_wire wire structs 38 | - Pfkey_coding decoding and encoding stuff 39 | - Pfkey_engine pfkey logic 40 | 41 | `src` contains the IKEv2 (RFC7296) protocol (Dispatcher compiles, rest needs work, likely redesign) 42 | - Packet contains enums from the standard (uses cstruct.ppx) 43 | - Decode contains stateless binary data to high-level type error (uses Packet, C, Control) 44 | - Encode contains stateless high-level type to binary data (uses Packet, C) 45 | - Crypto convenience functions for IKE crypto (uses nocrypto, C) 46 | - Config constructions for IKE configurations (uses C) 47 | - Control is the control socket (such as shutdown, more?) (uses C) 48 | - Engine the main processing pipeline (uses C, Decode, Encode, Crypto, Config) for a single IKE session 49 | - Dispatcher contains a set of IKE sessions (which influence each other, e.g. when `InitialContact is received by one) and coordinates what needs to be done for an incoming event (uses Engine) 50 | 51 | `lwt` contains some side-effecting code (currently compiles some testing code for PF_KEY) 52 | 53 | `helper` a C proxy of raw PF_KEY sockets to PF_INET SOCK_STREAM (compiles, is finished) 54 | 55 | `tests` should be there at some point 56 | -------------------------------------------------------------------------------- /_tags: -------------------------------------------------------------------------------- 1 | true : color(always), bin_annot, safe_string, principal 2 | true : warn(+A-4-44-48) 3 | true : package(result), package(logs), package(cstruct) 4 | "pfkey" : include 5 | "common" : include 6 | "src" : include 7 | 8 | : package(cstruct.ppx), package(sexplib), for-pack(Ike) 9 | : package(sexplib), package(ppx_sexp_conv), package(ipaddr), for-pack(Ike) 10 | : for-pack(Ike) 11 | 12 | : package(sexplib), package(ppx_sexp_conv), for-pack(Ike) 13 | : for-pack(Ike) 14 | : for-pack(Ike) 15 | 16 | : for-pack(Ike) 17 | 18 | : package(lwt), package(lwt.unix), package(sexplib), package(fmt), package(logs.lwt), package(logs.fmt), package(fmt.tty), package(ipaddr) 19 | -------------------------------------------------------------------------------- /build: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | # This script is only used for developement. It is removed by the 3 | # distribution process. 4 | 5 | set -e 6 | 7 | OCAMLBUILD=${OCAMLBUILD:="ocamlbuild -tag debug -classic-display \ 8 | -use-ocamlfind -cflags -warn-error,+A" } 9 | 10 | action () 11 | { 12 | case $1 in 13 | default) action lwt ; action helper ;; 14 | helper) cc -Wall -Werror -std=c99 -O3 -o helper/pf_to_tcp helper/pf_to_tcp.c ; 15 | cc -Wall -Werror -std=c99 -O3 -o helper/pf_to_fd helper/pf_to_fd.c ;; 16 | lwt) action lib ; $OCAMLBUILD lwt/ike_lwt.native ;; 17 | lib) $OCAMLBUILD ike.cmx ike.cmxa ;; 18 | test) action lib ; $OCAMLBUILD rfctests.native ;; 19 | clean) $OCAMLBUILD -clean ; rm -rf _tests ; rm -f helper/pf_to_tcp ; rm -f helper/pf_to_fd ;; 20 | *) $OCAMLBUILD $* ;; 21 | esac 22 | } 23 | 24 | if [ $# -eq 0 ]; 25 | then action default ; 26 | else action $*; fi 27 | -------------------------------------------------------------------------------- /common/c.ml: -------------------------------------------------------------------------------- 1 | 2 | (* high level types used all over, bottom of dependency *) 3 | open Sexplib.Conv 4 | 5 | type satype = [ 6 | | `AH 7 | | `ESP 8 | ] [@@deriving sexp] 9 | 10 | type auth_alg = [ 11 | | `SHA256 (* likely hmac *) 12 | | `SHA384 (* likely hmac *) 13 | | `SHA512 (* likely hmac *) 14 | ] [@@deriving sexp] 15 | 16 | type enc_alg = [ 17 | | `DES (* this is 3des *) 18 | | `AES_CBC 19 | | `AES_CTR 20 | | `AES_GCM16 (* pls read https://eprint.iacr.org/2015/477 if you want shorter tags *) 21 | ] [@@deriving sexp] 22 | 23 | type pfkey_to_kern = [ 24 | | `Flush of satype option 25 | | `Dump of satype option 26 | | `Register of satype 27 | | `Policy_Flush 28 | | `Policy_Dump 29 | ] [@@deriving sexp] 30 | 31 | type pfkey_from_kern = [ 32 | | `Flush of satype option 33 | | `Supported of auth_alg list * (enc_alg * int * int * int) list 34 | | `Policy_Flush 35 | ] [@@deriving sexp] 36 | 37 | type error = 38 | | Failed of string 39 | 40 | let pp_error ppf = function 41 | | Failed s -> Format.fprintf ppf "failed: %s" s 42 | 43 | include Monad.Or_error_make (struct type err = error end) 44 | include Result 45 | -------------------------------------------------------------------------------- /common/ike.mlpack: -------------------------------------------------------------------------------- 1 | Pfkey_wire 2 | Pfkey_coding 3 | Pfkey_engine 4 | C 5 | Monad 6 | Utils 7 | Dispatcher -------------------------------------------------------------------------------- /common/monad.ml: -------------------------------------------------------------------------------- 1 | open Result 2 | 3 | (* 4 | * Monad core -- copied from ocaml-tls at 3428c0f37d4f7df94b371d34307112898c3ad6ea 5 | *) 6 | 7 | (* Generic monad core; we could maybe import it from somewhere else. *) 8 | module type Monad = sig 9 | type 'a t 10 | val return : 'a -> 'a t 11 | val bind : 'a t -> ('a -> 'b t) -> 'b t 12 | end 13 | 14 | (* A larger monadic api over the core. *) 15 | module type Monad_ext = sig 16 | type 'a t 17 | val return : 'a -> 'a t 18 | val bind : 'a t -> ('a -> 'b t) -> 'b t 19 | val (>>=) : 'a t -> ('a -> 'b t) -> 'b t 20 | val (>|=) : 'a t -> ('a -> 'b) -> 'b t 21 | val map : ('a -> 'b) -> 'a t -> 'b t 22 | val sequence : 'a t list -> 'a list t 23 | val sequence_ : 'a t list -> unit t 24 | val mapM : ('a -> 'b t) -> 'a list -> 'b list t 25 | val mapM_ : ('a -> 'b t) -> 'a list -> unit t 26 | val foldM : ('a -> 'b -> 'a t) -> 'a -> 'b list -> 'a t 27 | end 28 | 29 | module Monad_ext_make ( M : Monad ) : 30 | Monad_ext with type 'a t = 'a M.t = 31 | struct 32 | type 'a t = 'a M.t 33 | let return = M.return 34 | let bind = M.bind 35 | let (>>=) = M.bind 36 | let map f a = a >>= fun x -> return (f x) 37 | let (>|=) a f = map f a 38 | let rec sequence = function 39 | | [] -> return [] 40 | | m::ms -> m >>= fun m' -> sequence ms >>= fun ms' -> return (m'::ms') 41 | let rec sequence_ = function 42 | | [] -> return () 43 | | m::ms -> m >>= fun _ -> sequence_ ms 44 | let rec mapM f = function 45 | | [] -> return [] 46 | | x::xs -> f x >>= fun x' -> mapM f xs >>= fun xs' -> return (x'::xs') 47 | let rec mapM_ f = function 48 | | [] -> return () 49 | | x::xs -> f x >>= fun _ -> mapM_ f xs 50 | let rec foldM f z = function 51 | | [] -> return z 52 | | x::xs -> f z x >>= fun z' -> foldM f z' xs 53 | end 54 | 55 | 56 | (* 57 | * Concrete monads. 58 | *) 59 | 60 | module Option = Monad_ext_make ( struct 61 | type 'a t = 'a option 62 | let return a = Some a 63 | let bind a f = match a with 64 | | None -> None 65 | | Some x -> f x 66 | end ) 67 | 68 | module type Or_error = sig 69 | type err 70 | type 'a t 71 | val fail : err -> 'a t 72 | val is_success : 'a t -> bool 73 | val is_error : 'a t -> bool 74 | include Monad_ext with type 'a t := 'a t 75 | val guard : bool -> err -> unit t 76 | val or_else : 'a t -> 'a -> 'a 77 | val or_else_f : 'a t -> ('b -> 'a) -> 'b -> 'a 78 | end 79 | 80 | module Or_error_make (M : sig type err end) : 81 | Or_error with type err = M.err and type 'a t = ('a, M.err) result = 82 | struct 83 | type err = M.err 84 | type 'a t = ('a, err) result 85 | let fail e = Error e 86 | let is_success = function 87 | | Ok _ -> true 88 | | Error _ -> false 89 | let is_error = function 90 | | Ok _ -> false 91 | | Error _ -> true 92 | include ( 93 | Monad_ext_make ( struct 94 | type nonrec 'a t = 'a t 95 | let return a = Ok a 96 | let bind a f = match a with 97 | | Ok x -> f x 98 | | Error e -> Error e 99 | end ) : Monad_ext with type 'a t := 'a t) 100 | let guard pred err = if pred then return () else fail err 101 | let or_else m a = match m with Ok x -> x | _ -> a 102 | let or_else_f m f b = match m with Ok x -> x | _ -> f b 103 | end 104 | -------------------------------------------------------------------------------- /common/utils.ml: -------------------------------------------------------------------------------- 1 | 2 | (* general useful utilities missing from the stdlib *) 3 | 4 | let rec filter_map ~f = function 5 | | [] -> [] 6 | | x::xs -> 7 | match f x with 8 | | None -> filter_map ~f xs 9 | | Some x' -> x' :: filter_map ~f xs 10 | 11 | let rec map_find ~f = function 12 | | [] -> None 13 | | x::xs -> 14 | match f x with 15 | | None -> map_find ~f xs 16 | | Some _ as x' -> x' 17 | 18 | let option none some = function 19 | | None -> none 20 | | Some x -> some x 21 | 22 | 23 | module Hex = struct 24 | let printable s r = 25 | let l = String.length s in 26 | for i = 0 to pred l do 27 | match String.get s i with 28 | | x when int_of_char x > 0x20 && int_of_char x < 0x7F -> Bytes.set r i x 29 | | _ -> Bytes.set r i '.' 30 | done 31 | 32 | let c_to_h c idx s = 33 | let v_to_h = function 34 | | x when x < 10 -> char_of_int (x + 48) 35 | | x -> char_of_int (x + 55) 36 | in 37 | let i = int_of_char c in 38 | let high = (0xf0 land i) lsr 4 39 | and low = 0x0f land i 40 | in 41 | Bytes.set s idx (v_to_h high) ; 42 | Bytes.set s (succ idx) (v_to_h low) 43 | 44 | let to_hex bytes = 45 | if bytes = "" then 46 | "" 47 | else 48 | let s = Bytes.make (String.length bytes * 3 - 1) ' ' in 49 | for i = 0 to pred (String.length bytes) do 50 | c_to_h (String.get bytes i) (i * 3) s 51 | done ; 52 | Bytes.to_string s 53 | 54 | let to_hexdump data = 55 | let rec lines d acc = 56 | if d = "" then List.rev acc 57 | else 58 | let data, left = 59 | let l = String.length d in 60 | if l > 16 then String.sub d 0 16, String.sub d 16 (l - 16) 61 | else d, "" 62 | in 63 | let d1, d2 = 64 | let l = String.length data in 65 | if l > 8 then String.sub data 0 8, String.sub data 8 (l - 8) 66 | else data, "" 67 | in 68 | let p_hex d = 69 | let l = String.length d in 70 | let h = to_hex d in 71 | if l = 0 then 72 | String.make 23 ' ' 73 | else if l < 8 then 74 | h ^ (String.make ((8 - l) * 3) ' ') 75 | else 76 | h 77 | in 78 | let cnt = 79 | let b = Bytes.make 4 ' ' in 80 | let f, s = 81 | let l = 16 * List.length acc in 82 | char_of_int (l lsr 8), char_of_int (l mod 256) 83 | in 84 | c_to_h f 0 b ; 85 | c_to_h s 2 b ; 86 | Bytes.to_string b 87 | in 88 | let hr1 = Bytes.make 8 ' ' 89 | and hr2 = Bytes.make 8 ' ' 90 | in 91 | printable d1 hr1 ; 92 | printable d2 hr2 ; 93 | let d = String.concat " " [ cnt ; p_hex d1 ; p_hex d2 ; Bytes.to_string (Bytes.concat (Bytes.make 1 ' ') [ hr1 ; hr2 ]) ] in 94 | lines left (d :: acc) 95 | in 96 | lines data [] 97 | end 98 | 99 | let pp_cs pp cs = 100 | List.iter (fun hex -> 101 | Format.pp_print_newline pp () ; 102 | Format.pp_print_string pp hex) 103 | (Hex.to_hexdump (Cstruct.to_string cs)) 104 | -------------------------------------------------------------------------------- /helper/pf_to_fd.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | #include 5 | #include 6 | #include 7 | #include 8 | #include 9 | #include 10 | 11 | #ifdef __linux__ 12 | #include 13 | #else 14 | #include 15 | #endif 16 | 17 | #define PERMISSION_BITS 0777 18 | 19 | int send_fd(int sock, int fd) { 20 | struct msghdr msg; 21 | struct cmsghdr *cmsg= NULL; 22 | struct iovec iov = { .iov_base = "X", .iov_len = 1 }; 23 | char buf[CMSG_SPACE(sizeof(fd))]; 24 | 25 | memset(&msg, 0, sizeof(msg)); 26 | memset(buf, 0, sizeof(buf)); 27 | 28 | msg.msg_iov = &iov; 29 | msg.msg_iovlen = 1; 30 | msg.msg_control = buf; 31 | msg.msg_controllen = CMSG_SPACE(sizeof(fd)); 32 | 33 | cmsg = CMSG_FIRSTHDR(&msg); 34 | cmsg->cmsg_level = SOL_SOCKET; 35 | cmsg->cmsg_type = SCM_RIGHTS; 36 | cmsg->cmsg_len = CMSG_LEN(sizeof(fd)); 37 | memcpy(CMSG_DATA(cmsg), (char*)&fd, sizeof(fd)); 38 | 39 | return sendmsg(sock, &msg, 0); 40 | } 41 | 42 | void connection(int lsock) { 43 | int sock; 44 | int pf_sock; 45 | 46 | if (-1 == (sock = accept(lsock, NULL, NULL))) 47 | err (EX_OSERR, "accept?"); 48 | 49 | if (0 > (pf_sock = socket(PF_KEY, SOCK_RAW, PF_KEY_V2))) 50 | err (EX_OSERR, "socket(PF_KEY, ...)?"); 51 | 52 | if (1 != send_fd(sock, pf_sock)) 53 | warn ("send_fd?"); 54 | 55 | if (0 != close (sock)) 56 | warn("close(sock)?"); 57 | 58 | if (0 != close (pf_sock)) 59 | warn("close(pf_sock)?"); 60 | } 61 | 62 | int server (const char *path) { 63 | struct sockaddr_un addr; 64 | int sock; 65 | size_t path_len; 66 | socklen_t addrlen; 67 | 68 | /* UNIX-domain addresses are variable-length file system pathnames of at 69 | most 104 characters. */ 70 | if (104 < (path_len = strlen(path))) 71 | errx(EX_USAGE, "UNIX_domain address is 104 characters max"); 72 | 73 | memset(&addr, 0, sizeof(addr)); 74 | addr.sun_family = AF_LOCAL; 75 | #ifndef __linux__ 76 | addr.sun_len = path_len; 77 | #endif 78 | (void)strncpy(addr.sun_path, path, 104); 79 | 80 | addrlen = sizeof(addr) - sizeof(addr.sun_path) + path_len; 81 | 82 | if (0 > (sock = socket(AF_LOCAL, SOCK_STREAM, 0))) 83 | err(EX_OSERR, "socket?"); 84 | 85 | (void)unlink(path); 86 | 87 | if (0 != bind(sock, (struct sockaddr *) &addr, addrlen)) 88 | err (EX_OSERR, "bind?"); 89 | 90 | (void)chmod(path, PERMISSION_BITS); 91 | 92 | if (0 != listen(sock, 1)) 93 | err (EX_OSERR, "listen?"); 94 | 95 | 96 | for (;;) connection(sock); 97 | return 0; 98 | } 99 | 100 | int main (int argc, char **argv) { 101 | if (2 != argc) 102 | errx(EX_USAGE, "exactly one argument is required: UNIX_domain address"); 103 | return server (argv[1]); 104 | } 105 | -------------------------------------------------------------------------------- /helper/pf_to_tcp.c: -------------------------------------------------------------------------------- 1 | #include 2 | #include 3 | #include 4 | 5 | #include 6 | 7 | #include 8 | #include 9 | 10 | #include 11 | #include 12 | #include 13 | 14 | #ifdef __linux__ 15 | #include 16 | #else 17 | #include 18 | #endif 19 | 20 | #include 21 | 22 | #define bsize 8192 23 | char buffer[bsize]; 24 | ssize_t n; 25 | 26 | #define DEBUG 0 27 | 28 | int read_write (int source, int sink) { 29 | n = read(source, buffer, bsize); 30 | if (n < 0) { 31 | perror("error while reading from socket"); 32 | return -1; 33 | } 34 | 35 | #if DEBUG 36 | printf("read/write (%d->%d) ", source, sink); 37 | for (int i = 0; i < n; i++) { 38 | printf("%02X ", buffer[i]); 39 | } 40 | printf("\n"); 41 | #endif 42 | 43 | if (write(sink, buffer, n) != n) { 44 | perror("error while writing to sink\n"); 45 | return -1; 46 | } 47 | 48 | return 0; 49 | } 50 | 51 | int main (int argc, char* argv[]) { 52 | fd_set readset; 53 | int pf_s, tcp, tcp_c = 0; 54 | int res = 0; 55 | struct sockaddr_in serv_addr, cli_addr; 56 | socklen_t cli_len; 57 | int on = 1; 58 | int port = 1234; 59 | int max; 60 | 61 | if (argc == 2) { 62 | port = atoi(argv[1]); 63 | } 64 | 65 | #if DEBUG 66 | printf("starting with debug enabled\n"); 67 | #endif 68 | pf_s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2); 69 | if (pf_s < 0) { 70 | perror("error while creating PF_KEY socket"); 71 | exit(-1); 72 | } 73 | 74 | printf("[%d] is the PF_KEY socket\n", pf_s); 75 | 76 | tcp = socket(AF_INET, SOCK_STREAM, 0); 77 | if (tcp < 0) { 78 | perror("error while creating SOCK_STREAM socket"); 79 | goto fail; 80 | } 81 | 82 | if (setsockopt(tcp, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on)) < 0) { 83 | perror("error while setsockopt"); 84 | goto fail; 85 | } 86 | 87 | bzero((char *) &serv_addr, sizeof(serv_addr)); 88 | serv_addr.sin_family = AF_INET; 89 | serv_addr.sin_addr.s_addr = inet_addr("127.0.0.1"); 90 | serv_addr.sin_port = htons(port); 91 | 92 | printf("attempt bind to %s:%d\n", 93 | inet_ntoa(serv_addr.sin_addr), 94 | ntohs(serv_addr.sin_port)); 95 | 96 | if (bind(tcp, (struct sockaddr *) &serv_addr, sizeof(serv_addr)) < 0) { 97 | perror("error while binding"); 98 | goto fail; 99 | } 100 | 101 | if (listen(tcp, 1) < 0) { 102 | perror("error while listening"); 103 | goto fail; 104 | } 105 | 106 | printf("[%d] is listening on %s:%d\n", 107 | tcp, 108 | inet_ntoa(serv_addr.sin_addr), 109 | ntohs(serv_addr.sin_port)); 110 | 111 | cli_len = sizeof(cli_addr); 112 | tcp_c = accept(tcp, (struct sockaddr *)&cli_addr, &cli_len); 113 | 114 | if (tcp_c < 0) { 115 | perror("error on accept"); 116 | goto fail; 117 | } 118 | 119 | if (setsockopt(tcp_c, IPPROTO_TCP, TCP_NODELAY, &on, sizeof(on)) < 0) { 120 | perror("error while setsockopt on client socket"); 121 | goto fail; 122 | } 123 | 124 | printf("[%d] accepted connection from %s:%d\n", 125 | tcp_c, 126 | inet_ntoa(cli_addr.sin_addr), 127 | ntohs(cli_addr.sin_port)); 128 | 129 | if (close(tcp) < 0) { 130 | perror("error on close"); 131 | goto fail; 132 | } 133 | tcp = 0; 134 | 135 | max = tcp_c > pf_s ? 1 + tcp_c : 1 + pf_s; 136 | 137 | printf("entering read/write loop\n"); 138 | while (1) { 139 | FD_ZERO(&readset); 140 | FD_SET(pf_s, &readset); 141 | FD_SET(tcp_c, &readset); 142 | res = select(max, &readset, NULL, NULL, NULL); 143 | if (res < 0) { 144 | perror("error in select"); 145 | goto fail; 146 | } else { 147 | if (FD_ISSET(pf_s, &readset)) { 148 | if (read_write(pf_s, tcp_c) < 0) { 149 | goto fail; 150 | } 151 | } 152 | if (FD_ISSET(tcp_c, &readset)) { 153 | if (read_write(tcp_c, pf_s) < 0) { 154 | goto fail; 155 | } 156 | } 157 | } 158 | } 159 | printf("this is never printed\n"); 160 | if (pf_s > 0) { close(pf_s); } 161 | if (tcp_c > 0) { close(tcp_c); } 162 | return 0; 163 | 164 | fail: 165 | if (pf_s > 0) { close(pf_s); } 166 | if (tcp > 0) { close(tcp); } 167 | if (tcp_c > 0) { close(tcp_c); } 168 | exit(-1); 169 | } 170 | -------------------------------------------------------------------------------- /lwt/ike_lwt.ml: -------------------------------------------------------------------------------- 1 | 2 | (* IKEv2 LWT interface 3 | 4 | communication channels: 5 | - kernel: pfkey(v2) - RFC2367 + KAME changes 6 | - user: file descriptor / socket with config (mainly SP) 7 | - network: UDP port 500 IKEv2 (* later also 4500 *) 8 | - timer (for retransmission and keepalive) every 500 ms 9 | 10 | all of them are combined into a Lwt_stream.t, which is consumed element-wise 11 | by the main loop: evaluate Ike.handle, perform received actions (sending 12 | pfkey and udp), goto 0. 13 | *) 14 | 15 | open Lwt.Infix 16 | open Result 17 | 18 | (* this reader has the logic to read a single complete pfkey message! 19 | message length is a 16 bit value, little endian, offset 5, in 64bit words *) 20 | let pfkey_reader src socket () = 21 | let buf = Bytes.create 16 in 22 | Lwt_unix.recv socket buf 0 16 [Lwt_unix.MSG_PEEK] >>= fun _n -> 23 | let cs = Cstruct.of_string (Bytes.to_string (Bytes.sub buf 0 16)) in 24 | let len = (Cstruct.LE.get_uint16 cs 4) * 8 in 25 | let buf = Bytes.create len in 26 | Lwt_unix.read socket buf 0 len >|= fun _n -> 27 | let cs = Cstruct.of_string (Bytes.to_string (Bytes.sub buf 0 len)) in 28 | Logs.debug ~src (fun pp -> pp "read %d %a" len Ike.Utils.pp_cs cs) ; 29 | Some (`Pfkey cs) 30 | 31 | let pfkey_send src socket msg = 32 | let len = Cstruct.len msg in 33 | Logs.debug ~src (fun pp -> pp "writing %d %a" len Ike.Utils.pp_cs msg) ; 34 | let bytes = Bytes.of_string (Cstruct.to_string msg) in 35 | Lwt_unix.write socket bytes 0 len >>= fun n -> 36 | (* should be a fail *) 37 | if n = Cstruct.len msg then 38 | Lwt.return_unit 39 | else 40 | Lwt.fail_with "failed to write to pfkey socket" 41 | 42 | 43 | let pfkey_socket_fd addr = 44 | let buf = " " in 45 | let io_vectors = [ Lwt_unix.io_vector ~buffer:buf ~offset:0 ~length:1 ] in 46 | let socket = Lwt_unix.(socket PF_UNIX SOCK_STREAM 0) in 47 | Lwt_unix.connect socket (Lwt_unix.ADDR_UNIX addr) >>= fun () -> 48 | Lwt_unix.recv_msg ~socket ~io_vectors >>= function 49 | | (1, [pfkey_fd]) -> 50 | Lwt_unix.close socket >>= fun () -> 51 | Lwt.return (Lwt_unix.of_unix_file_descr pfkey_fd) 52 | | ( _ , _ ) -> 53 | Lwt_unix.close socket >>= fun () -> 54 | Lwt.fail_with "failed to aquire pf_key fd" 55 | 56 | let pfkey_socket_tcp port = 57 | let pfkey_fd = Lwt_unix.(socket PF_INET SOCK_STREAM 0) 58 | and addr = Lwt_unix.ADDR_INET (Unix.inet_addr_of_string "127.0.0.1", port) 59 | in 60 | Lwt_unix.connect pfkey_fd addr >>= fun () -> 61 | Lwt.return pfkey_fd 62 | 63 | let pfkey_socket = function 64 | | (_, addr) when (String.length addr) != 0 -> pfkey_socket_fd addr 65 | | (port, _) -> pfkey_socket_tcp port 66 | 67 | (* 68 | let rec user_socket push socket () = 69 | Lwt_unix.read socket >>= fun data -> 70 | push (`Control data) >>= fun () -> 71 | user_socket push socket () 72 | 73 | let rec network_socket push socket () = 74 | Lwt_unix.recv_from socket >>= fun (data, addr) -> 75 | push (`Data (data, addr)) >>= fun () -> 76 | network_socket push socket () 77 | *) 78 | 79 | let tick () = 80 | Lwt_unix.sleep 5. >|= fun () -> 81 | Some `Tick 82 | 83 | let service _user _port pf_key_cnf _config = 84 | Lwt.async_exception_hook := 85 | (* error handling of a failed network send: 86 | - inform IKE (find which t is responsible and do a proper shutdown) 87 | --> maybe emit a `NetworkFailure event to handle? 88 | - what should happen when pfkey socket fails? 89 | - what if control socket fails? 90 | - log error (done ;) *) 91 | (fun exn -> Logs.err (fun pp -> 92 | pp "async exception %s" (Printexc.to_string exn))) ; 93 | 94 | let pfkey_src = Logs.Src.create "lwt_pfkey" in 95 | pfkey_socket pf_key_cnf >>= fun pfkey_fd -> 96 | let pfkey_stream = Lwt_stream.from (pfkey_reader pfkey_src pfkey_fd) in 97 | let maybe_send_pf = function 98 | | None -> Lwt.return_unit 99 | | Some pfkey -> pfkey_send pfkey_src pfkey_fd pfkey 100 | in 101 | 102 | (* Lwt_unix.(socket PF_INET SOCK_STREAM user) >>= fun user -> 103 | Lwt_unix.(socket PF_INET SOCK_DGRAM port) >>= fun network -> *) 104 | (* need to bind / connect *) 105 | (* drop privileges *) 106 | (*Lwt.async (user_socket push user) ; 107 | Lwt.async (network_socket push network) ; *) 108 | 109 | let timer_stream = Lwt_stream.from tick in 110 | (* we might need some fixed choose, https://github.com/ocsigen/lwt/issues/213 (and 214) *) 111 | let stream = Lwt_stream.choose [ pfkey_stream ; timer_stream ] in 112 | let rec go t = 113 | Lwt_stream.next stream >>= fun ev -> 114 | match Ike.Dispatcher.handle t ev with 115 | | Ok (t', `Pfkey pfkey, `Data _nouts) -> 116 | maybe_send_pf pfkey >>= fun () -> 117 | (* Lwt_list.iter_s (Lwt_unix.sendto network) nouts >>= fun () -> *) 118 | go t' 119 | | Error (Ike.C.Failed str) -> 120 | Logs.err (fun pp -> pp "failed (with %s) while executing, goodbye" str) ; 121 | Lwt.return_unit 122 | in 123 | let t, pfkey = Ike.Dispatcher.create (*config*) () in 124 | maybe_send_pf pfkey >>= fun () -> 125 | go t 126 | 127 | (* copied from logs library test/test_lwt.ml *) 128 | let lwt_reporter () = 129 | let buf_fmt ~like = 130 | let b = Buffer.create 512 in 131 | Fmt.with_buffer ~like b, 132 | fun () -> let m = Buffer.contents b in Buffer.reset b; m 133 | in 134 | let app, app_flush = buf_fmt ~like:Fmt.stdout in 135 | let dst, dst_flush = buf_fmt ~like:Fmt.stderr in 136 | let report src level ~over k msgf = 137 | (* we like to print the log source, not the application name! *) 138 | let pp_header ppf (lvl, _) = 139 | Logs_fmt.pp_header ppf (lvl, Some (Logs.Src.name src)) 140 | in 141 | let reporter = Logs_fmt.reporter ~pp_header ~app ~dst () in 142 | let k () = 143 | let write () = match level with 144 | | Logs.App -> Lwt_io.write Lwt_io.stdout (app_flush ()) 145 | | _ -> Lwt_io.write Lwt_io.stderr (dst_flush ()) 146 | in 147 | let unblock () = over (); Lwt.return_unit in 148 | Lwt.finalize write unblock |> Lwt.ignore_result; 149 | k () 150 | in 151 | reporter.Logs.report src level ~over:(fun () -> ()) k msgf; 152 | in 153 | { Logs.report = report } 154 | 155 | (* handle log command-line arguments *) 156 | let pfkey = ref 1234 157 | let user = ref 23 158 | let port = ref 500 159 | let config = ref "" 160 | let un_addr = ref "" 161 | let rest = ref [] 162 | 163 | let usage = "usage " ^ Sys.argv.(0) 164 | 165 | let arglist = [ 166 | ("-u", Arg.Int (fun d -> user := d), "user port (defaults to 23)") ; 167 | ("-p", Arg.Int (fun d -> pfkey := d), "pfkey port (defaults to 1234)") ; 168 | ("-A", Arg.String (fun d -> un_addr := d), "pfkey UNIX-domain address"); 169 | ("-d", Arg.Int (fun d -> port := d), "IKE daemin port (defaults to 500)") ; 170 | ("-c", Arg.String (fun d -> config := d), "IKE configuration file") ; 171 | ] 172 | 173 | let _ = 174 | try 175 | Arg.parse arglist (fun x -> rest := x :: !rest) usage ; 176 | Fmt_tty.setup_std_outputs (); 177 | Logs.set_level @@ Some Logs.Debug; 178 | Logs.set_reporter @@ lwt_reporter (); 179 | Lwt_main.run (service !user !port (!pfkey, !un_addr) !config) 180 | with 181 | | Sys_error s -> print_endline s 182 | -------------------------------------------------------------------------------- /opam: -------------------------------------------------------------------------------- 1 | opam-version: "1.2" 2 | name: "ike" 3 | homepage: "https://github.com/isakmp/ike" 4 | dev-repo: "https://github.com/isakmp/ike.git" 5 | bug-reports: "https://github.com/isakmp/ike/issues" 6 | author: ["a"] 7 | maintainer: ["a"] 8 | license: "BSD2" 9 | 10 | build: [ "./build" ] 11 | 12 | depends: [ 13 | "ocamlfind" {build} 14 | "ocamlbuild" {build} 15 | "ppx_tools" {build} 16 | "ppx_sexp_conv" {build} 17 | "result" 18 | "cstruct" {>= "1.9.0"} 19 | "sexplib" 20 | "nocrypto" {>= "0.5.3"} 21 | "astring" 22 | "logs" {>= "0.6.0"} 23 | "lwt" 24 | "fmt" 25 | "ipaddr" 26 | "alcotest" {test} 27 | ] 28 | 29 | available: [ ocaml-version >= "4.02.3" ] 30 | -------------------------------------------------------------------------------- /pfkey/pfkey_coding.ml: -------------------------------------------------------------------------------- 1 | open C 2 | open Pfkey_wire 3 | 4 | open Sexplib.Conv 5 | 6 | type header = { 7 | typ : message_type ; 8 | errno : int ; 9 | satyp : satype ; 10 | seq : int32 ; 11 | pid : int32 ; 12 | } [@@deriving sexp] 13 | 14 | type alg = 15 | | Auth of aalg * int * int 16 | | Enc of ealg * int * int * int 17 | [@@deriving sexp] 18 | 19 | type extension = 20 | | Supported of alg list 21 | | Policy of Pfkey_wire.policy_type * Pfkey_wire.direction * int32 * int32 22 | | Source of int * int * int * Ipaddr.t 23 | | Destination of int * int * int * Ipaddr.t 24 | [@@deriving sexp] 25 | 26 | module Decode = struct 27 | type 'a result = ('a, C.error) Result.result 28 | 29 | let catch f x = 30 | try f x with 31 | | Invalid_argument _ -> fail (Failed "underflow") 32 | 33 | let unknown fmt arg = Failed (Printf.sprintf fmt arg) 34 | 35 | let check_len should buf = 36 | let is = Cstruct.len buf 37 | and should = should * 8 38 | in 39 | guard (is = should) 40 | (Failed (Printf.sprintf "length: claimed %d real %d" should is)) 41 | 42 | let separate_extensions = catch @@ fun buf -> 43 | let rec one acc cs = 44 | if Cstruct.len cs > 0 then 45 | let len = get_ext_len cs in 46 | let t, xs = Cstruct.split cs (len * 8) in 47 | one (t::acc) xs 48 | else 49 | List.rev acc 50 | in 51 | return (one [] buf) 52 | 53 | let alg buf = 54 | let id = get_alg_id buf 55 | and ivlen = get_alg_ivlen buf 56 | and minbits = get_alg_minbits buf 57 | and maxbits = get_alg_maxbits buf 58 | in 59 | (id, ivlen, minbits, maxbits) 60 | 61 | let algs buf = 62 | let rec go acc cs = 63 | if Cstruct.len cs > 0 then 64 | let this, rest = Cstruct.split cs sizeof_alg in 65 | go (alg this :: acc) rest 66 | else 67 | List.rev acc 68 | in 69 | let algs = Cstruct.shift buf sizeof_supported in 70 | if Cstruct.len algs mod sizeof_alg <> 0 then 71 | fail (unknown "algorithm extensions size is wrong (%d)" (Cstruct.len algs)) 72 | else 73 | return (go [] algs) 74 | 75 | let support_enc src buf = 76 | algs buf >|= fun algs -> 77 | Supported (Utils.filter_map ~f:(fun (id, iv, min, max) -> 78 | match int_to_ealg id with 79 | | None -> Logs.warn ~src (fun pp -> pp "unkown encryption algorithm %d" id) ; None 80 | | Some x -> Some (Enc (x, iv, min, max))) 81 | algs) 82 | 83 | let support_auth src buf = 84 | algs buf >>= fun algs -> 85 | foldM (fun acc (id, iv, min, max) -> 86 | match iv, int_to_aalg id with 87 | | 0, Some x -> return (Auth (x, min, max) :: acc) 88 | | x, Some _ -> fail (unknown "IV field in authentication alg not zero %d" x) 89 | | _ -> 90 | Logs.warn ~src (fun pp -> pp "unknown authentication algorithm %d" id) ; 91 | return acc) 92 | [] 93 | algs >|= fun algs -> 94 | Supported algs 95 | 96 | let policy _src buf = 97 | let ptype = get_policy_ptype buf in 98 | match int_to_policy_type ptype with 99 | | None -> fail (unknown "policy type %d" ptype) 100 | | Some ptype -> 101 | let dir = get_policy_direction buf in 102 | match int_to_direction dir with 103 | | None -> fail (unknown "direction %d" dir) 104 | | Some dir -> 105 | let id = get_policy_id buf 106 | and priority = get_policy_priority buf 107 | in 108 | return (Policy (ptype, dir, id, priority)) 109 | 110 | let address _src buf = 111 | let proto = get_address_proto buf 112 | and prefixlen = get_address_prefixlen buf 113 | in 114 | (* now there is a struct sockaddr -- might be platform-specific *) 115 | let sockaddr = Cstruct.shift buf sizeof_address in 116 | let _sin_len = Cstruct.get_uint8 sockaddr 0 117 | and family = Cstruct.get_uint8 sockaddr 1 118 | and port = Cstruct.LE.get_uint16 sockaddr 2 119 | in 120 | (* depends on family *) 121 | (let open Ipaddr in 122 | let ip = Cstruct.(to_string @@ shift sockaddr 4) in 123 | match family with 124 | | 2 (* AF_INET *) -> return (V4 (V4.of_bytes_raw ip 0)) 125 | | 28 (* AF_INET6 *) -> return (V6 (V6.of_bytes_raw ip 4)) (* there's a uint32_t flowinfo *) 126 | | x -> fail (unknown "address family %d" x)) >|= fun address -> 127 | (proto, prefixlen, port, address) 128 | 129 | let extension src = catch @@ fun buf -> 130 | let typ = get_ext_ext_type buf in 131 | match int_to_extension_type typ with 132 | | None -> fail (unknown "extension type %d" typ) 133 | | Some typ -> 134 | match typ with 135 | | SUPPORTED_ENCRYPT -> support_enc src buf 136 | | SUPPORTED_AUTH -> support_auth src buf 137 | | POLICY -> policy src buf 138 | | ADDRESS_SRC -> 139 | address src buf >|= fun (proto, pflen, port, address) -> 140 | Source (proto, pflen, port, address) 141 | | ADDRESS_DST -> 142 | address src buf >|= fun (proto, pflen, port, address) -> 143 | Destination (proto, pflen, port, address) 144 | | x -> 145 | Logs.debug ~src (fun pp -> pp "buffer is %a" Utils.pp_cs buf) ; 146 | fail (unknown "NYI extension type %s" (extension_type_to_string x)) 147 | 148 | let header_exn buf = 149 | let version = get_message_version buf in 150 | guard (version = 2) (unknown "version %d" version) >>= fun () -> 151 | let msg_type = get_message_msg_type buf in 152 | match int_to_message_type msg_type with 153 | | None -> fail (unknown "message type %d" msg_type) 154 | | Some typ -> 155 | let errno = get_message_errno buf in 156 | let satype = get_message_satype buf in 157 | match int_to_satype satype with 158 | | None -> fail (unknown "satype %d" satype) 159 | | Some satyp -> 160 | let len = get_message_len buf in 161 | check_len len buf >>= fun () -> 162 | let seq = get_message_seq buf in 163 | let pid = get_message_pid buf in 164 | return (Cstruct.sub buf sizeof_message ((len - 2) * 8), 165 | { typ ; errno ; satyp ; seq ; pid }) 166 | 167 | let header = catch @@ header_exn 168 | 169 | end 170 | 171 | module Encode = struct 172 | 173 | let header hdr payload = 174 | let buf = Cstruct.create sizeof_message in 175 | set_message_version buf 2 ; 176 | set_message_msg_type buf (message_type_to_int hdr.typ) ; 177 | set_message_errno buf hdr.errno ; 178 | set_message_satype buf (satype_to_int hdr.satyp) ; 179 | set_message_len buf ((Cstruct.len payload + sizeof_message) / 8) ; 180 | set_message_reserved buf 0 ; 181 | set_message_seq buf hdr.seq ; 182 | set_message_pid buf hdr.pid ; 183 | Cstruct.append buf payload 184 | 185 | end 186 | -------------------------------------------------------------------------------- /pfkey/pfkey_coding.mli: -------------------------------------------------------------------------------- 1 | 2 | type header = { 3 | typ : Pfkey_wire.message_type ; 4 | errno : int ; 5 | satyp : Pfkey_wire.satype ; 6 | seq : int32 ; 7 | pid : int32 ; 8 | } [@@deriving sexp] 9 | 10 | type alg = 11 | | Auth of Pfkey_wire.aalg * int * int 12 | | Enc of Pfkey_wire.ealg * int * int * int 13 | [@@deriving sexp] 14 | 15 | type extension = 16 | | Supported of alg list 17 | | Policy of Pfkey_wire.policy_type * Pfkey_wire.direction * int32 * int32 18 | | Source of int * int * int * Ipaddr.t 19 | | Destination of int * int * int * Ipaddr.t 20 | [@@deriving sexp] 21 | 22 | module Decode : sig 23 | type 'a result = ('a, C.error) Result.result 24 | 25 | val separate_extensions : Cstruct.t -> (Cstruct.t list) result 26 | 27 | val extension : Logs.Src.t -> Cstruct.t -> extension result 28 | 29 | val header : Cstruct.t -> (Cstruct.t * header) result 30 | end 31 | 32 | module Encode : sig 33 | 34 | (* val extension : extension -> Cstruct.t *) 35 | 36 | val header : header -> Cstruct.t -> Cstruct.t 37 | end 38 | -------------------------------------------------------------------------------- /pfkey/pfkey_engine.ml: -------------------------------------------------------------------------------- 1 | open C 2 | 3 | open Pfkey_coding 4 | 5 | type ready_or_not = Waiting | Ready 6 | 7 | type state = { 8 | machina : ready_or_not ; 9 | logger : Logs.src ; 10 | process : int32 ; 11 | sequence : int32 ; 12 | commands : pfkey_to_kern list 13 | } 14 | 15 | let sa_to_satype = 16 | let open Pfkey_wire in 17 | function 18 | | `ESP -> ESP 19 | | `AH -> AH 20 | 21 | let encode s cmd = 22 | let open Pfkey_wire in 23 | let null = Cstruct.create 0 in 24 | let typ, errno, satyp, payload = match cmd with 25 | | `Register satype -> (REGISTER, 0, sa_to_satype satype, null) 26 | | `Dump satype -> 27 | let satype = Utils.option UNSPEC sa_to_satype satype in 28 | (DUMP, 0, satype, null) 29 | | `Flush satype -> 30 | let satype = Utils.option UNSPEC sa_to_satype satype in 31 | (FLUSH, 0, satype, null) 32 | | `Policy_Dump -> (SPDDUMP, 0, UNSPEC, null) 33 | | `Policy_Flush -> (SPDFLUSH, 0, UNSPEC, null) 34 | and seq = s.sequence 35 | and pid = s.process 36 | in 37 | let hdr = { Pfkey_coding.typ ; errno ; satyp ; seq ; pid } in 38 | let cs = Pfkey_coding.Encode.header hdr payload in 39 | Logs.debug ~src:s.logger 40 | (fun pp -> pp "encoded message %s" (Sexplib.Sexp.to_string_hum (Pfkey_coding.sexp_of_header hdr))) ; 41 | ({ s with sequence = Int32.succ seq }, cs) 42 | 43 | let maybe_command s = 44 | Logs.debug ~src:s.logger 45 | (fun pp -> pp "%d comamnds in queue, state %s" (List.length s.commands) 46 | (match s.machina with Waiting -> "waiting" | Ready -> "ready")) ; 47 | match s.machina, s.commands with 48 | | Ready, c::commands -> 49 | let s, cs = encode s c in 50 | ({ s with machina = Waiting ; commands }, Some cs) 51 | | Ready, [] -> (s, None) 52 | | Waiting, commands -> ({ s with commands }, None) 53 | 54 | let enqueue s cmd = { s with commands = s.commands @ [cmd] } 55 | 56 | let create ?(process = 42l) ?(commands = []) () = 57 | let s = { 58 | process ; 59 | sequence = 0l ; 60 | logger = Logs.Src.create "pfkey engine" ; 61 | commands ; 62 | machina = Ready 63 | } 64 | in 65 | maybe_command s 66 | 67 | let aalg_to_auth = 68 | let open Pfkey_wire in 69 | function 70 | | AALG_SHA2_256 -> Some `SHA256 71 | | AALG_SHA2_384 -> Some `SHA384 72 | | AALG_SHA2_512 -> Some `SHA512 73 | | _ -> None 74 | 75 | let ealg_to_enc (id, iv, min, max) = 76 | Utils.option 77 | None 78 | (fun id -> Some (id, iv, min, max)) 79 | (let open Pfkey_wire in 80 | match id with 81 | | EALG_3DESCBC -> Some `DES 82 | | EALG_AESCBC -> Some `AES_CBC 83 | | EALG_AESCTR -> Some `AES_CTR 84 | | EALG_AESGCM16 -> Some `AES_GCM16 85 | | _ -> None) 86 | 87 | let handle_register exts = 88 | let a, e = List.fold_left (fun (a, e) -> function 89 | | Supported algs -> 90 | let auth, enc = List.fold_left (fun (a, es) -> function 91 | | Auth (id, _, _) -> (id :: a, es) 92 | | Enc (id, iv, min, max) -> (a, (id, iv, min, max) :: es)) 93 | ([], []) 94 | algs 95 | in 96 | (a @ Utils.filter_map ~f:aalg_to_auth auth, 97 | e @ Utils.filter_map ~f:ealg_to_enc enc) 98 | | _ -> (a, e)) 99 | ([], []) 100 | exts 101 | in 102 | if List.length a = 0 && List.length e = 0 then 103 | fail (Failed "no supported algorithms") 104 | else if List.exists (function Supported _ -> false | _ -> true) exts then 105 | fail (Failed "invalid register message") 106 | else 107 | return (`Supported (a, e)) 108 | 109 | let maybe_sa hdr = 110 | let open Pfkey_wire in 111 | match hdr.satyp with 112 | | UNSPEC -> None 113 | | AH -> Some `AH 114 | | ESP -> Some `ESP 115 | | _ -> None (* XXX: maybe log some error? *) 116 | 117 | let handle s buf = 118 | Decode.header buf >>= fun (payload, hdr) -> 119 | Decode.separate_extensions payload >>= fun exts -> 120 | mapM (Decode.extension s.logger) exts >>= fun exts -> 121 | Logs.debug ~src:s.logger 122 | (fun pp -> pp "handling message %s with %d extensions: %s" 123 | (Sexplib.Sexp.to_string_hum (sexp_of_header hdr)) 124 | (List.length exts) 125 | (String.concat ", " 126 | (List.map Sexplib.Sexp.to_string_hum 127 | (List.map sexp_of_extension exts)))) ; 128 | 129 | let s = 130 | if hdr.seq = Int32.pred s.sequence && hdr.pid = s.process then 131 | (* this was the outstanding reply *) 132 | { s with machina = Ready } 133 | else if hdr.seq = 0l && hdr.pid = s.process && hdr.typ = Pfkey_wire.SPDDUMP then 134 | (* FreeBSD-CURRENT replies in interesting ways for SPDDUMP 135 | (sys/netipsec/key.c:key_spddump:2398-2451): 136 | - sequence set to number of policies 137 | - for each policy: 138 | - decrese sequence number 139 | - send SPDDUMP with single policy 140 | --> violating the request <-> response protocol 141 | --> violating the mapping of pid|seq from request to response 142 | --> XXX: bug to be reported to FreeBSD people? 143 | --> thus we're ok with the last SPDDUMP msg (seq=0) to be ready again *) 144 | { s with machina = Ready } 145 | else 146 | (* handle unsolicited messages (such as SPDADD from setkey) *) 147 | s 148 | in 149 | (* need to handle errors here... 150 | translate errno to msg (again, platform-specific), unix-errno package *) 151 | (* if hdr.errno <> 0 then *) 152 | let open Pfkey_wire in 153 | match hdr.typ with 154 | | REGISTER -> handle_register exts >|= fun supported -> (s, Some supported) 155 | | FLUSH -> return (s, Some (`Flush (maybe_sa hdr))) 156 | | SPDFLUSH -> return (s, Some `Policy_Flush) 157 | | x -> 158 | Logs.debug ~src:s.logger 159 | (fun pp -> pp "not forwarding %s" (Pfkey_wire.message_type_to_string x)) ; 160 | return (s, None) 161 | -------------------------------------------------------------------------------- /pfkey/pfkey_engine.mli: -------------------------------------------------------------------------------- 1 | open Result 2 | 3 | type state 4 | 5 | val create : ?process:int32 -> ?commands:C.pfkey_to_kern list -> unit -> state * Cstruct.t option 6 | 7 | val enqueue : state -> C.pfkey_to_kern -> state 8 | 9 | val maybe_command : state -> state * Cstruct.t option 10 | 11 | val handle : state -> Cstruct.t -> (state * C.pfkey_from_kern option, C.error) result 12 | 13 | -------------------------------------------------------------------------------- /pfkey/pfkey_wire.ml: -------------------------------------------------------------------------------- 1 | let pf_key_v2 = 2 2 | and pfkeyv2_revision = 199806L 3 | 4 | [%%cenum 5 | type message_type = 6 | | MSG_RESERVED [@id 0] 7 | | GETSPI [@id 1] 8 | | UPDATE [@id 2] 9 | | ADD [@id 3] 10 | | DELETE [@id 4] 11 | | GET [@id 5] 12 | | ACQUIRE [@id 6] 13 | | REGISTER [@id 7] 14 | | EXPIRE [@id 8] 15 | | FLUSH [@id 9] 16 | | DUMP [@id 10] 17 | | PROMISC [@id 11] 18 | | PCHANGE [@id 12] 19 | | SPDUPDATE [@id 13] 20 | | SPDADD [@id 14] 21 | | SPDDELETE [@id 15] (* by policy index *) 22 | | SPDGET [@id 16] 23 | | SPDACQUIRE [@id 17] 24 | | SPDDUMP [@id 18] 25 | | SPDFLUSH [@id 19] 26 | | SPDSETIDX [@id 20] 27 | | SPDEXPIRE [@id 21] 28 | | SPDDELETE2 [@id 22] (* by policy id *) 29 | [@@uint8_t] [@@sexp]] 30 | 31 | [%%cstruct 32 | type message = { 33 | version : uint8_t ; 34 | msg_type : uint8_t ; 35 | errno : uint8_t ; 36 | satype : uint8_t ; 37 | len : uint16_t ; 38 | reserved : uint16_t ; 39 | seq : uint32_t ; 40 | pid : uint32_t ; 41 | } [@@little_endian]] 42 | 43 | [%%cstruct 44 | type ext = { 45 | len : uint16_t ; 46 | ext_type : uint16_t ; 47 | } [@@little_endian]] 48 | 49 | [%%cstruct 50 | type sa = { 51 | len : uint16_t ; 52 | ext_type : uint16_t ; 53 | spi : uint32_t ; (* big endian! *) 54 | replay : uint8_t ; 55 | state : uint8_t ; 56 | auth : uint8_t ; 57 | encrypt : uint8_t ; 58 | flags : uint32_t ; 59 | } [@@little_endian]] 60 | 61 | [%%cstruct 62 | type lifetime = { 63 | len : uint16_t ; 64 | ext_type : uint16_t ; 65 | allocations : uint32_t ; 66 | bytes : uint64_t ; 67 | addtime : uint64_t ; 68 | usetime : uint64_t ; 69 | } [@@little_endian]] 70 | 71 | [%%cstruct 72 | type address = { 73 | len : uint16_t ; 74 | ext_type : uint16_t ; 75 | proto : uint8_t ; 76 | prefixlen : uint8_t ; 77 | reserved : uint16_t ; 78 | } [@@little_endian]] 79 | 80 | [%%cstruct 81 | type key = { 82 | len : uint16_t ; 83 | ext_type : uint16_t ; 84 | key_bits : uint16_t ; 85 | reserved : uint16_t ; 86 | } [@@little_endian]] 87 | 88 | [%%cstruct 89 | type ident = { 90 | len : uint16_t ; 91 | ext_type : uint16_t ; 92 | ident_type : uint16_t ; 93 | reserved : uint16_t ; 94 | id : uint64_t ; 95 | } [@@little_endian]] 96 | 97 | [%%cstruct 98 | type sens = { 99 | len : uint16_t ; 100 | ext_type : uint16_t ; 101 | dpd : uint32_t ; 102 | level : uint8_t ; 103 | sense_len : uint8_t ; 104 | integ_level : uint8_t ; 105 | integ_len : uint8_t ; 106 | reserved : uint32_t ; 107 | } [@@little_endian]] 108 | 109 | [%%cstruct 110 | type prop = { 111 | len : uint16_t ; 112 | ext_type : uint16_t ; 113 | replay : uint8_t ; 114 | reserved : uint8_t [@len 3] ; 115 | } [@@little_endian]] 116 | 117 | [%%cstruct 118 | type comb = { 119 | auth : uint8_t ; 120 | encrypt : uint8_t ; 121 | flags : uint16_t ; 122 | minbits : uint16_t ; 123 | maxbits : uint16_t ; 124 | encrypt_minbits : uint16_t ; 125 | encrypt_maxbits : uint16_t ; 126 | reserved : uint32_t ; 127 | soft_allocations : uint32_t ; 128 | hard_allocations : uint32_t ; 129 | soft_bytes : uint64_t ; 130 | hard_bytes : uint64_t ; 131 | soft_addtime : uint64_t ; 132 | hard_addtime : uint64_t ; 133 | soft_usetime : uint64_t ; 134 | hard_usetime : uint64_t ; 135 | } [@@little_endian]] 136 | 137 | [%%cstruct 138 | type supported = { 139 | len : uint16_t ; 140 | ext_type : uint16_t ; 141 | reserved : uint32_t ; 142 | } [@@little_endian]] 143 | 144 | [%%cstruct 145 | type alg = { 146 | id : uint8_t ; 147 | ivlen : uint8_t ; 148 | minbits : uint16_t ; 149 | maxbits : uint16_t ; 150 | reserved : uint16_t ; 151 | } [@@little_endian]] 152 | 153 | [%%cstruct 154 | type spirange = { 155 | len : uint16_t ; 156 | ext_type : uint16_t ; 157 | min : uint32_t ; 158 | max : uint32_t ; 159 | reserved : uint32_t ; 160 | } [@@little_endian]] 161 | 162 | [%%cstruct 163 | type kmprivate = { 164 | len : uint16_t ; 165 | ext_type : uint16_t ; 166 | reserved : uint32_t ; 167 | } [@@little_endian]] 168 | 169 | (* 170 | * XXX Additional SA Extension. 171 | * mode: tunnel or transport 172 | * reqid: to make SA unique nevertheless the address pair of SA are same. 173 | * Mainly it's for VPN. 174 | *) 175 | [%%cstruct 176 | type sa2 = { 177 | len : uint16_t ; 178 | ext_type : uint16_t ; 179 | mode : uint8_t ; 180 | reserved : uint8_t [@len 3] ; 181 | sequence : uint32_t ; (* lowermost 32bit of sequence number *) 182 | reqid : uint32_t ; 183 | } [@@little_endian]] 184 | 185 | (* XXX Policy Extension *) 186 | [%%cstruct 187 | type policy = { 188 | len : uint16_t ; 189 | ext_type : uint16_t ; 190 | ptype : uint16_t ; (* See policy type of ipsec.h *) 191 | direction : uint8_t ; (* See ipsec.h *) 192 | reserved : uint8_t ; 193 | id : uint32_t ; 194 | priority : uint32_t ; 195 | } [@@little_endian]] 196 | 197 | (* 198 | * When policy_type == IPSEC, it is followed by some of 199 | * the ipsec policy request. 200 | * [total length of ipsec policy requests] 201 | * = (sadb_x_policy_len * sizeof(uint64_t) - sizeof(struct sadb_x_policy)) 202 | *) 203 | 204 | (* XXX IPsec Policy Request Extension *) 205 | [%%cstruct 206 | type ipsecrequest = { 207 | len : uint16_t ; 208 | proto : uint16_t ; (* See ipsec.h *) 209 | mode : uint8_t ; (* See IPSEC_MODE_XX in ipsec.h. *) 210 | level : uint8_t ; (* See IPSEC_LEVEL_XX in ipsec.h *) 211 | reqid : uint16_t ; (* See ipsec.h *) 212 | 213 | (* 214 | * followed by source IP address of SA, and immediately followed by 215 | * destination IP address of SA. These encoded into two of sockaddr 216 | * structure without any padding. Must set each sa_len exactly. 217 | * Each of length of the sockaddr structure are not aligned to 64bits, 218 | * but sum of x_request and addresses is aligned to 64bits. 219 | *) 220 | } [@@little_endian]] 221 | 222 | (* NAT-Traversal type, see RFC 3948 (and drafts). *) 223 | [%%cstruct 224 | type nat_t_type = { 225 | len : uint16_t ; 226 | ext_type : uint16_t ; 227 | nat_type : uint8_t ; 228 | reserved : uint8_t [@len 3] ; 229 | } [@@little_endian]] 230 | 231 | (* NAT-Traversal source or destination port. *) 232 | [%%cstruct 233 | type nat_t_port = { 234 | len : uint16_t ; 235 | ext_type : uint16_t ; 236 | port : uint16_t ; 237 | reserved : uint16_t ; 238 | } [@@little_endian]] 239 | 240 | (* ESP fragmentation size. *) 241 | [%%cstruct 242 | type nat_t_frag = { 243 | len : uint16_t ; 244 | ext_type : uint16_t ; 245 | fraglen : uint16_t ; 246 | reserved : uint16_t ; 247 | } [@@little_endian]] 248 | 249 | [%%cenum 250 | type extension_type = 251 | | EXT_RESERVED [@id 0] 252 | | SA [@id 1] 253 | | LIFETIME_CURRENT [@id 2] 254 | | LIFETIME_HARD [@id 3] 255 | | LIFETIME_SOFT [@id 4] 256 | | ADDRESS_SRC [@id 5] 257 | | ADDRESS_DST [@id 6] 258 | | ADDRESS_PROXY [@id 7] 259 | | KEY_AUTH [@id 8] 260 | | KEY_ENCRYPT [@id 9] 261 | | IDENTITY_SRC [@id 10] 262 | | IDENTITY_DST [@id 11] 263 | | SENSITIVITY [@id 12] 264 | | PROPOSAL [@id 13] 265 | | SUPPORTED_AUTH [@id 14] 266 | | SUPPORTED_ENCRYPT [@id 15] 267 | | SPIRANGE [@id 16] 268 | | KMPRIVATE [@id 17] 269 | | POLICY [@id 18] 270 | | SA2 [@id 19] 271 | | NAT_T_TYPE [@id 20] 272 | | NAT_T_SPORT [@id 21] 273 | | NAT_T_DPORT [@id 22] 274 | (* | NAT_T_OA [@id 23] Deprecated. *) 275 | | NAT_T_OAI [@id 23] (* Peer's NAT_OA for src of SA. *) 276 | | NAT_T_OAR [@id 24] (* Peer's NAT_OA for dst of SA. *) 277 | | NAT_T_FRAG [@id 25] (* Manual MTU override. *) 278 | [@@uint16_t] [@@sexp]] 279 | 280 | [%%cenum 281 | type satype = 282 | | UNSPEC [@id 0] 283 | | AH [@id 2] 284 | | ESP [@id 3] 285 | | RSVP [@id 5] 286 | | OSPFV2 [@id 6] 287 | | RIPV2 [@id 7] 288 | | MIP [@id 8] 289 | | IPCOMP [@id 9] 290 | | OBSOLETE_POLICY [@id 10] (* obsolete, do not reuse *) 291 | | TCPSIGNATURE [@id 11] 292 | [@@uint8_t] [@@sexp]] 293 | 294 | [%%cenum 295 | type sastate = 296 | | LARVAL [@id 0] 297 | | MATURE [@id 1] 298 | | DYING [@id 2] 299 | | DEAD [@id 3] 300 | [@@uint8_t] [@@sexp]] 301 | 302 | 303 | [%%cenum 304 | type saflags = 305 | | SAFLAGS_PFS [@id 1] 306 | [@@uint8_t] [@@sexp]] 307 | 308 | (* 309 | * Though some of these numbers (both _AALG and _EALG) appear to be 310 | * IKEv2 numbers and others original IKE numbers, they have no meaning. 311 | * These are constants that the various IKE daemons use to tell the kernel 312 | * what cipher to use. 313 | * 314 | * Do not use these constants directly to decide which Transformation ID 315 | * to send. You are responsible for mapping them yourself. 316 | *) 317 | [%%cenum 318 | type aalg = 319 | | AALG_NONE [@id 0] 320 | | AALG_MD5HMAC [@id 2] 321 | | AALG_SHA1HMAC [@id 3] 322 | | AALG_SHA2_256 [@id 5] 323 | | AALG_SHA2_384 [@id 6] 324 | | AALG_SHA2_512 [@id 7] 325 | | AALG_RIPEMD160HMAC [@id 8] 326 | | AALG_AES_XCBC_MAC [@id 9] (* RFC3566 *) 327 | | AALG_AES128GMAC [@id 11] (* RFC4543 + Errata1821 *) 328 | | AALG_AES192GMAC [@id 12] 329 | | AALG_AES256GMAC [@id 13] 330 | | AALG_MD5 [@id 249] (* Keyed MD5 *) 331 | | AALG_SHA [@id 250] (* Keyed SHA *) 332 | | AALG_NULL [@id 251] (* null authentication *) 333 | | AALG_TCP_MD5 [@id 252] (* Keyed TCP-MD5 (RFC2385) *) 334 | [@@uint8_t] [@@sexp]] 335 | 336 | [%%cenum 337 | type ealg = 338 | | EALG_NONE [@id 0] 339 | | EALG_DESCBC [@id 2] 340 | | EALG_3DESCBC [@id 3] 341 | | EALG_CAST128CBC [@id 6] 342 | | EALG_BLOWFISHCBC [@id 7] 343 | | EALG_NULL [@id 11] 344 | (* | EALG_RIJNDAELCBC [@id 12] *) 345 | | EALG_AESCBC [@id 12] 346 | | EALG_AESCTR [@id 13] 347 | | EALG_AESGCM8 [@id 18] (* RFC4106 *) 348 | | EALG_AESGCM12 [@id 19] 349 | | EALG_AESGCM16 [@id 20] 350 | | EALG_CAMELLIACBC [@id 22] 351 | | EALG_AESGMAC [@id 23] (* RFC4543 + Errata1821 *) 352 | [@@uint8_t] [@@sexp]] 353 | 354 | (* private allocations - based on RFC2407/IANA assignment *) 355 | [%%cenum 356 | type calg = 357 | | CALG_NONE [@id 0] 358 | | CALG_OUI [@id 1] 359 | | CALG_DEFLATE [@id 2] 360 | | CALG_LZS [@id 3] 361 | [@@uint8_t] [@@sexp]] 362 | 363 | [%%cenum 364 | type ident_type = 365 | | IDENTTYPE_RESERVED [@id 0] 366 | | IDENTTYPE_PREFIX [@id 1] 367 | | IDENTTYPE_FQDN [@id 2] 368 | | IDENTTYPE_USERFQDN [@id 3] 369 | | IDENTTYPE_ADDR [@id 4] 370 | [@@uint8_t] [@@sexp]] 371 | 372 | (* `flags' in sadb_sa structure holds followings *) 373 | let flag_none = 0x0000 (* i.e. new format. *) 374 | and flag_old = 0x0001 (* old format. *) 375 | and flag_iv4b = 0x0010 (* IV length of 4 bytes in use *) 376 | and flag_deriv = 0x0020 (* DES derived *) 377 | and flag_cycseq = 0x0040 (* allowing to cyclic sequence. *) 378 | (* three of followings are exclusive flags each them *) 379 | and flag_pseq = 0x0000 (* sequencial padding for ESP *) 380 | and flag_prand = 0x0100 (* random padding for ESP *) 381 | and flag_pzero = 0x0200 (* zero padding for ESP *) 382 | and flag_pmask = 0x0300 (* mask for padding flag *) 383 | and flag_rawcpi = 0x0080 (* use well known CPI (IPComp) *) 384 | 385 | (* SPI size for PF_KEYv2 *) 386 | (* #define PFKEY_SPI_SIZE sizeof(u_int32_t) *) 387 | 388 | (* Identifier for menber of lifetime structure *) 389 | [%%cenum 390 | type lifetime_type = 391 | | LIFETIME_ALLOCATIONS [@id 0] 392 | | LIFETIME_BYTES [@id 1] 393 | | LIFETIME_ADDTIME [@id 2] 394 | | LIFETIME_USETIME [@id 3] 395 | [@@uint8_t] [@@sexp]] 396 | 397 | (* The rate for SOFT lifetime against HARD one. *) 398 | let soft_lifetime_rate = 80 399 | 400 | (* Utilities *) 401 | (* 402 | #define PFKEY_ALIGN8(a) (1 + (((a) - 1) | (8 - 1))) 403 | #define PFKEY_EXTLEN(msg) \ 404 | PFKEY_UNUNIT64(((struct sadb_ext * )(msg))->sadb_ext_len) 405 | #define PFKEY_ADDR_PREFIX(ext) \ 406 | (((struct sadb_address * )(ext))->sadb_address_prefixlen) 407 | #define PFKEY_ADDR_PROTO(ext) \ 408 | (((struct sadb_address * )(ext))->sadb_address_proto) 409 | #define PFKEY_ADDR_SADDR(ext) \ 410 | ((struct sockaddr * )((caddr_t)(ext) + sizeof(struct sadb_address))) 411 | 412 | (* in 64bits *) 413 | #define PFKEY_UNUNIT64(a) ((a) << 3) 414 | #define PFKEY_UNIT64(a) ((a) >> 3) 415 | *) 416 | 417 | (* from netipsec/ipsec.h *) 418 | (* mode of security protocol *) 419 | (* NOTE: DON'T use IPSEC_MODE_ANY at SPD. It's only use in SAD *) 420 | [%%cenum 421 | type mode = 422 | | MODE_ANY [@id 0] (* i.e. wildcard. *) 423 | | MODE_TRANSPORT [@id 1] 424 | | MODE_TUNNEL [@id 2] 425 | | MODE_TCPMD5 [@id 3] (* TCP MD5 mode *) 426 | [@@uint8_t] [@@sexp]] 427 | 428 | (* 429 | * Direction of security policy. 430 | * NOTE: Since INVALID is used just as flag. 431 | * The other are used for loop counter too. 432 | *) 433 | [%%cenum 434 | type direction = 435 | | DIR_ANY [@id 0] 436 | | DIR_INBOUND [@id 1] 437 | | DIR_OUTBOUND [@id 2] 438 | | DIR_MAX [@id 3] 439 | | DIR_INVALID [@id 4] 440 | [@@uint8_t] [@@sexp]] 441 | 442 | (* Policy level *) 443 | (* 444 | * IPSEC, ENTRUST and BYPASS are allowed for setsockopt() in PCB, 445 | * DISCARD, IPSEC and NONE are allowed for setkey() in SPD. 446 | * DISCARD and NONE are allowed for system default. 447 | *) 448 | [%%cenum 449 | type policy_type = 450 | | POLICY_DISCARD [@id 0] (* discarding packet *) 451 | | POLICY_NONE [@id 1] (* through IPsec engine *) 452 | | POLICY_IPSEC [@id 2] (* do IPsec *) 453 | | POLICY_ENTRUST [@id 3] (* consulting SPD if present. *) 454 | | POLICY_BYPASS [@id 4] (* only for privileged socket. *) 455 | [@@uint16_t] [@@sexp]] 456 | 457 | (* Security protocol level *) 458 | [%%cenum 459 | type level = 460 | | LEVEL_DEFAULT [@id 0] (* reference to system default *) 461 | | LEVEL_USE [@id 1] (* use SA if present. *) 462 | | LEVEL_REQUIRE [@id 2] (* require SA. *) 463 | | LEVEL_UNIQUE [@id 3] (* unique SA. *) 464 | [@@uint8_t] [@@sexp]] 465 | 466 | (* 467 | #define IPSEC_MANUAL_REQID_MAX 0x3fff 468 | /* 469 | * if security policy level == unique, this id 470 | * indicate to a relative SA for use, else is 471 | * zero. 472 | * 1 - 0x3fff are reserved for manual keying. 473 | * 0 are reserved for above reason. Others is 474 | * for kernel use. 475 | * Note that this id doesn't identify SA 476 | * by only itself. 477 | */ 478 | #define IPSEC_REPLAYWSIZE 32 479 | *) 480 | -------------------------------------------------------------------------------- /rfc/rfc2367.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Network Working Group D. McDonald 8 | Request for Comments: 2367 C. Metz 9 | Category: Informational B. Phan 10 | July 1998 11 | 12 | 13 | PF_KEY Key Management API, Version 2 14 | 15 | Status of this Memo 16 | 17 | This memo provides information for the Internet community. It does 18 | not specify an Internet standard of any kind. Distribution of this 19 | memo is unlimited. 20 | 21 | Copyright Notice 22 | 23 | Copyright (C) The Internet Society (1998). All Rights Reserved. 24 | 25 | Abstract 26 | 27 | A generic key management API that can be used not only for IP 28 | Security [Atk95a] [Atk95b] [Atk95c] but also for other network 29 | security services is presented in this document. Version 1 of this 30 | API was implemented inside 4.4-Lite BSD as part of the U. S. Naval 31 | Research Laboratory's freely distributable and usable IPv6 and IPsec 32 | implementation[AMPMC96]. It is documented here for the benefit of 33 | others who might also adopt and use the API, thus providing increased 34 | portability of key management applications (e.g. a manual keying 35 | application, an ISAKMP daemon, a GKMP daemon [HM97a][HM97b], a 36 | Photuris daemon, or a SKIP certificate discovery protocol daemon). 37 | 38 | Table of Contents 39 | 40 | 1 Introduction ............................................. 3 41 | 1.1 Terminology .............................................. 3 42 | 1.2 Conceptual Model ......................................... 4 43 | 1.3 PF_KEY Socket Definition ................................. 8 44 | 1.4 Overview of PF_KEY Messaging Behavior .................... 8 45 | 1.5 Common PF_KEY Operations ................................. 9 46 | 1.6 Differences Between PF_KEY and PF_ROUTE .................. 10 47 | 1.7 Name Space ............................................... 11 48 | 1.8 On Manual Keying ..........................................11 49 | 2 PF_KEY Message Format .................................... 11 50 | 2.1 Base Message Header Format ............................... 12 51 | 2.2 Alignment of Headers and Extension Headers ............... 14 52 | 2.3 Additional Message Fields ................................ 14 53 | 2.3.1 Association Extension .................................... 15 54 | 2.3.2 Lifetime Extension ....................................... 16 55 | 56 | 57 | 58 | McDonald, et. al. Informational [Page 1] 59 | 60 | RFC 2367 PF_KEY Key Management API July 1998 61 | 62 | 63 | 2.3.3 Address Extension ........................................ 18 64 | 2.3.4 Key Extension ............................................ 19 65 | 2.3.5 Identity Extension ....................................... 21 66 | 2.3.6 Sensitivity Extension .................................... 21 67 | 2.3.7 Proposal Extension ....................................... 22 68 | 2.3.8 Supported Algorithms Extension ........................... 25 69 | 2.3.9 SPI Range Extension ...................................... 26 70 | 2.4 Illustration of Message Layout ........................... 27 71 | 3 Symbolic Names ........................................... 30 72 | 3.1 Message Types ............................................ 31 73 | 3.1.1 SADB_GETSPI .............................................. 32 74 | 3.1.2 SADB_UPDATE .............................................. 33 75 | 3.1.3 SADB_ADD ................................................. 34 76 | 3.1.4 SADB_DELETE .............................................. 35 77 | 3.1.5 SADB_GET ................................................. 36 78 | 3.1.6 SADB_ACQUIRE ............................................. 36 79 | 3.1.7 SADB_REGISTER ............................................ 38 80 | 3.1.8 SADB_EXPIRE .............................................. 39 81 | 3.1.9 SADB_FLUSH ............................................... 40 82 | 3.1.10 SADB_DUMP ................................................ 40 83 | 3.2 Security Association Flags ............................... 41 84 | 3.3 Security Association States .............................. 41 85 | 3.4 Security Association Types ............................... 41 86 | 3.5 Algorithm Types .......................................... 42 87 | 3.6 Extension Header Values .................................. 43 88 | 3.7 Identity Extension Values ................................ 44 89 | 3.8 Sensitivity Extension Values ............................. 45 90 | 3.9 Proposal Extension Values ................................ 45 91 | 4 Future Directions ........................................ 45 92 | 5 Examples ................................................. 45 93 | 5.1 Simple IP Security Example ............................... 46 94 | 5.2 Proxy IP Security Example ................................ 47 95 | 5.3 OSPF Security Example .................................... 50 96 | 5.4 Miscellaneous ............................................ 50 97 | 6 Security Considerations .................................. 51 98 | Acknowledgments ............,............................. 52 99 | References ............................................... 52 100 | Disclaimer ............................................... 54 101 | Authors' Addresses ....................................... 54 102 | A Promiscuous Send/Receive Extension ....................... 55 103 | B Passive Change Message Extension ......................... 57 104 | C Key Management Private Data Extension .................... 58 105 | D Sample Header File ....................................... 59 106 | E Change Log ............................................... 64 107 | F Full Copyright Statement ................................. 68 108 | 109 | 110 | 111 | 112 | 113 | 114 | McDonald, et. al. Informational [Page 2] 115 | 116 | RFC 2367 PF_KEY Key Management API July 1998 117 | 118 | 119 | 1 Introduction 120 | 121 | PF_KEY is a new socket protocol family used by trusted privileged key 122 | management applications to communicate with an operating system's key 123 | management internals (referred to here as the "Key Engine" or the 124 | Security Association Database (SADB)). The Key Engine and its 125 | structures incorporate the required security attributes for a session 126 | and are instances of the "Security Association" (SA) concept 127 | described in [Atk95a]. The names PF_KEY and Key Engine thus refer to 128 | more than cryptographic keys and are retained for consistency with 129 | the traditional phrase, "Key Management". 130 | 131 | PF_KEY is derived in part from the BSD routing socket, PF_ROUTE. 132 | [Skl91] This document describes Version 2 of PF_KEY. Version 1 was 133 | implemented in the first five alpha test versions of the NRL 134 | IPv6+IPsec Software Distribution for 4.4-Lite BSD UNIX and the Cisco 135 | ISAKMP/Oakley key management daemon. Version 2 extends and refines 136 | this interface. Theoretically, the messages defined in this document 137 | could be used in a non-socket context (e.g. between two directly 138 | communicating user-level processes), but this document will not 139 | discuss in detail such possibilities. 140 | 141 | Security policy is deliberately omitted from this interface. PF_KEY 142 | is not a mechanism for tuning systemwide security policy, nor is it 143 | intended to enforce any sort of key management policy. The developers 144 | of PF_KEY believe that it is important to separate security 145 | mechanisms (such as PF_KEY) from security policies. This permits a 146 | single mechanism to more easily support multiple policies. 147 | 148 | 1.1 Terminology 149 | 150 | Even though this document is not intended to be an actual Internet 151 | standard, the words that are used to define the significance of 152 | particular features of this interface are usually capitalized. Some 153 | of these words, including MUST, MAY, and SHOULD, are detailed in 154 | [Bra97]. 155 | 156 | - CONFORMANCE and COMPLIANCE 157 | 158 | Conformance to this specification has the same meaning as compliance 159 | to this specification. In either case, the mandatory-to-implement, 160 | or MUST, items MUST be fully implemented as specified here. If any 161 | mandatory item is not implemented as specified here, that 162 | implementation is not conforming and not compliant with this 163 | specification. 164 | 165 | 166 | 167 | 168 | 169 | 170 | McDonald, et. al. Informational [Page 3] 171 | 172 | RFC 2367 PF_KEY Key Management API July 1998 173 | 174 | 175 | This specification also uses many terms that are commonly used in the 176 | context of network security. Other documents provide more 177 | definitions and background information on these [VK83, HA94, Atk95a]. 178 | Two terms deserve special mention: 179 | 180 | - (Encryption/Authentication) Algorithm 181 | 182 | For PF_KEY purposes, an algorithm, whether encryption or 183 | authentication, is the set of operations performed on a packet to 184 | complete authentication or encryption as indicated by the SA type. A 185 | PF_KEY algorithm MAY consist of more than one cryptographic 186 | algorithm. Another possibility is that the same basic cryptographic 187 | algorithm may be applied with different modes of operation or some 188 | other implementation difference. These differences, henceforth called 189 | _algorithm differentiators_, distinguish between different PF_KEY 190 | algorithms, and options to the same algorithm. Algorithm 191 | differentiators will often cause fundamentally different security 192 | properties. 193 | 194 | For example, both DES and 3DES use the same cryptographic algorithm, 195 | but they are used differently and have different security properties. 196 | The triple-application of DES is considered an algorithm 197 | differentiator. There are therefore separate PF_KEY algorithms for 198 | DES and 3DES. Keyed-MD5 and HMAC-MD5 use the same hash function, but 199 | construct their message authentication codes differently. The use of 200 | HMAC is an algorithm differentiator. DES-ECB and DES-CBC are the 201 | same cryptographic algorithm, but use a different mode. Mode (e.g., 202 | chaining vs. code-book) is an algorithm differentiator. Blowfish with 203 | a 128-bit key, however, is similar to Blowfish with a 384-bit key, 204 | because the algorithm's workings are otherwise the same and therefore 205 | the key length is not an algorithm differentiator. 206 | 207 | In terms of IP Security, a general rule of thumb is that whatever 208 | might be labeled the "encryption" part of an ESP transform is 209 | probably a PF_KEY encryption algorithm. Whatever might be labelled 210 | the "authentication" part of an AH or ESP transform is probably a 211 | PF_KEY authentication algorithm. 212 | 213 | 1.2 Conceptual Model 214 | 215 | This section describes the conceptual model of an operating system 216 | that implements the PF_KEY key management application programming 217 | interface. This section is intended to provide background material 218 | useful to understand the rest of this document. Presentation of this 219 | conceptual model does not constrain a PF_KEY implementation to 220 | strictly adhere to the conceptual components discussed in this 221 | subsection. 222 | 223 | 224 | 225 | 226 | McDonald, et. al. Informational [Page 4] 227 | 228 | RFC 2367 PF_KEY Key Management API July 1998 229 | 230 | 231 | Key management is most commonly implemented in whole or in part at 232 | the application layer. For example, the ISAKMP/Oakley, GKMP, and 233 | Photuris proposals for IPsec key management are all application-layer 234 | protocols. Manual keying is also done at the application layer. 235 | Even parts of the SKIP IP-layer keying proposal can be implemented at 236 | the application layer. Figure 1 shows the relationship between a Key 237 | Management daemon and PF_KEY. Key management daemons use PF_KEY to 238 | communicate with the Key Engine and use PF_INET (or PF_INET6 in the 239 | case of IPv6) to communicate, via the network, with a remote key 240 | management entity. 241 | 242 | The "Key Engine" or "Security Association Database (SADB)" is a 243 | logical entity in the kernel that stores, updates, and deletes 244 | Security Association data for various security protocols. There are 245 | logical interfaces within the kernel (e.g. getassocbyspi(), 246 | getassocbysocket()) that security protocols inside the kernel (e.g. 247 | IP Security, aka IPsec) use to request and obtain Security 248 | Associations. 249 | 250 | In the case of IPsec, if by policy a particular outbound packet needs 251 | processing, then the IPsec implementation requests an appropriate 252 | Security Association from the Key Engine via the kernel-internal 253 | interface. If the Key Engine has an appropriate SA, it allocates the 254 | SA to this session (marking it as used) and returns the SA to the 255 | IPsec implementation for use. If the Key Engine has no such SA but a 256 | key management application has previously indicated (via a PF_KEY 257 | SADB_REGISTER message) that it can obtain such SAs, then the Key 258 | Engine requests that such an SA be created (via a PF_KEY SADB_ACQUIRE 259 | message). When the key management daemon creates a new SA, it places 260 | it into the Key Engine for future use. 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | McDonald, et. al. Informational [Page 5] 283 | 284 | RFC 2367 PF_KEY Key Management API July 1998 285 | 286 | 287 | +---------------+ 288 | |Key Mgmt Daemon| 289 | +---------------+ 290 | | | 291 | | | 292 | | | Applications 293 | ======[PF_KEY]====[PF_INET]========================== 294 | | | OS Kernel 295 | +------------+ +-----------------+ 296 | | Key Engine | | TCP/IP, | 297 | | or SADB |---| including IPsec | 298 | +------------+ | | 299 | +-----------------+ 300 | | 301 | +-----------+ 302 | | Network | 303 | | Interface | 304 | +-----------+ 305 | 306 | Figure 1: Relationship of Key Mgmt to PF_KEY 307 | 308 | For performance reasons, some security protocols (e.g. IP Security) 309 | are usually implemented inside the operating system kernel. Other 310 | security protocols (e.g. OSPFv2 Cryptographic Authentication) are 311 | implemented in trusted privileged applications outside the kernel. 312 | Figure 2 shows a trusted, privileged routing daemon using PF_INET to 313 | communicate routing information with a remote routing daemon and 314 | using PF_KEY to request, obtain, and delete Security Associations 315 | used with a routing protocol. 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | McDonald, et. al. Informational [Page 6] 339 | 340 | RFC 2367 PF_KEY Key Management API July 1998 341 | 342 | 343 | +---------------+ 344 | |Routing Daemon| 345 | +---------------+ 346 | | | 347 | | | 348 | | | Applications 349 | ======[PF_KEY]====[PF_INET]========================== 350 | | | OS Kernel 351 | +------------+ +---------+ 352 | | Key Engine | | TCP/IP | 353 | | or SADB |---| | 354 | +------------+ +---------+ 355 | | 356 | +-----------+ 357 | | Network | 358 | | Interface | 359 | +-----------+ 360 | 361 | Figure 2: Relationship of Trusted Application to PF_KEY 362 | 363 | When a trusted privileged application is using the Key Engine but 364 | implements the security protocol within itself, then operation varies 365 | slightly. In this case, the application needing an SA sends a PF_KEY 366 | SADB_ACQUIRE message down to the Key Engine, which then either 367 | returns an error or sends a similar SADB_ACQUIRE message up to one or 368 | more key management applications capable of creating such SAs. As 369 | before, the key management daemon stores the SA into the Key Engine. 370 | Then, the trusted privileged application uses an SADB_GET message to 371 | obtain the SA from the Key Engine. 372 | 373 | In some implementations, policy may be implemented in user-space, 374 | even though the actual cryptographic processing takes place in the 375 | kernel. Such policy communication between the kernel mechanisms and 376 | the user-space policy MAY be implemented by PF_KEY extensions, or 377 | other such mechanism. This document does not specify such 378 | extensions. A PF_KEY implementation specified by the memo does NOT 379 | have to support configuring systemwide policy using PF_KEY. 380 | 381 | Untrusted clients, for example a user's web browser or telnet client, 382 | do not need to use PF_KEY. Mechanisms not specified here are used by 383 | such untrusted client applications to request security services (e.g. 384 | IPsec) from an operating system. For security reasons, only trusted, 385 | privileged applications are permitted to open a PF_KEY socket. 386 | 387 | 388 | 389 | 390 | 391 | 392 | 393 | 394 | McDonald, et. al. Informational [Page 7] 395 | 396 | RFC 2367 PF_KEY Key Management API July 1998 397 | 398 | 399 | 1.3 PF_KEY Socket Definition 400 | 401 | The PF_KEY protocol family (PF_KEY) symbol is defined in 402 | in the same manner that other protocol families are 403 | defined. PF_KEY does not use any socket addresses. Applications 404 | using PF_KEY MUST NOT depend on the availability of a symbol named 405 | AF_KEY, but kernel implementations are encouraged to define that 406 | symbol for completeness. 407 | 408 | The key management socket is created as follows: 409 | 410 | #include 411 | #include 412 | #include 413 | 414 | int s; 415 | s = socket(PF_KEY, SOCK_RAW, PF_KEY_V2); 416 | 417 | The PF_KEY domain currently supports only the SOCK_RAW socket type. 418 | The protocol field MUST be set to PF_KEY_V2, or else EPROTONOSUPPORT 419 | will be returned. Only a trusted, privileged process can create a 420 | PF_KEY socket. On conventional UNIX systems, a privileged process is 421 | a process with an effective userid of zero. On non-MLS proprietary 422 | operating systems, the notion of a "privileged process" is 423 | implementation-defined. On Compartmented Mode Workstations (CMWs) or 424 | other systems that claim to provide Multi-Level Security (MLS), a 425 | process MUST have the "key management privilege" in order to open a 426 | PF_KEY socket[DIA]. MLS systems that don't currently have such a 427 | specific privilege MUST add that special privilege and enforce it 428 | with PF_KEY in order to comply and conform with this specification. 429 | Some systems, most notably some popular personal computers, do not 430 | have the concept of an unprivileged user. These systems SHOULD take 431 | steps to restrict the programs allowed to access the PF_KEY API. 432 | 433 | 1.4 Overview of PF_KEY Messaging Behavior 434 | 435 | A process interacts with the key engine by sending and receiving 436 | messages using the PF_KEY socket. Security association information 437 | can be inserted into and retrieved from the kernel's security 438 | association table using a set of predefined messages. In the normal 439 | case, all properly-formed messages sent to the kernel are returned to 440 | all open PF_KEY sockets, including the sender. Improperly formed 441 | messages will result in errors, and an implementation MUST check for 442 | a properly formed message before returning it to the appropriate 443 | listeners. Unlike the routing socket, most errors are sent in reply 444 | messages, not the errno field when write() or send() fails. PF_KEY 445 | message delivery is not guaranteed, especially in cases where kernel 446 | or socket buffers are exhausted and messages are dropped. 447 | 448 | 449 | 450 | McDonald, et. al. Informational [Page 8] 451 | 452 | RFC 2367 PF_KEY Key Management API July 1998 453 | 454 | 455 | Some messages are generated by the operating system to indicate that 456 | actions need to be taken, and are not necessarily in response to any 457 | message sent down by the user. Such messages are not received by all 458 | PF_KEY sockets, but by sockets which have indicated that kernel- 459 | originated messages are to be received. These messages are special 460 | because of the expected frequency at which they will occur. Also, an 461 | implementation may further wish to restrict return messages from the 462 | kernel, in cases where not all PF_KEY sockets are in the same trust 463 | domain. 464 | 465 | Many of the normal BSD socket calls have undefined behavior on PF_KEY 466 | sockets. These include: bind(), connect(), socketpair(), accept(), 467 | getpeername(), getsockname(), ioctl(), and listen(). 468 | 469 | 1.5 Common PF_KEY Operations 470 | 471 | There are two basic ways to add a new Security Association into the 472 | kernel. The simplest is to send a single SADB_ADD message, 473 | containing all of the SA information, from the application into the 474 | kernel's Key Engine. This approach works particularly well with 475 | manual key management, which is required for IPsec, and other 476 | security protocols. 477 | 478 | The second approach to add a new Security Association into the kernel 479 | is for the application to first request a Security Parameters Index 480 | (SPI) value from the kernel using the SADB_GETSPI message and then 481 | send an SADB_UPDATE message with the complete Security Association 482 | data. This second approach works well with key management daemons 483 | when the SPI values need to be known before the entire Security 484 | Association data is known (e.g. so the SPI value can be indicated to 485 | the remote end of the key management session). 486 | 487 | An individual Security Association can be deleted using the 488 | SADB_DELETE message. Categories of SAs or the entire kernel SA table 489 | can be deleted using the SADB_FLUSH message. 490 | 491 | The SADB_GET message is used by a trusted application-layer process 492 | (e.g. routed(8) or gated(8)) to retrieve an SA (e.g. RIP SA or OSPF 493 | SA) from the kernel's Key Engine. 494 | 495 | The kernel or an application-layer can use the SADB_ACQUIRE message 496 | to request that a Security Association be created by some 497 | application-layer key management process that has registered with the 498 | kernel via an SADB_REGISTER message. This ACQUIRE message will have 499 | a sequence number associated with it. This sequence number MUST be 500 | used by followup SADB_GETSPI, SADB_UPDATE, and SADB_ADD messages, in 501 | order to keep track of which request gets its keying material. The 502 | sequence number (described below) is similar to a transaction ID in a 503 | 504 | 505 | 506 | McDonald, et. al. Informational [Page 9] 507 | 508 | RFC 2367 PF_KEY Key Management API July 1998 509 | 510 | 511 | remote procedure call. 512 | 513 | The SADB_EXPIRE message is sent from the kernel to key management 514 | applications when the "soft lifetime" or "hard lifetime" of a 515 | Security Association has expired. Key management applications should 516 | use receipt of a soft lifetime SADB_EXPIRE message as a hint to 517 | negotiate a replacement SA so the replacement SA will be ready and in 518 | the kernel before it is needed. 519 | 520 | A SADB_DUMP message is also defined, but this is primarily intended 521 | for PF_KEY implementor debugging and is not used in ordinary 522 | operation of PF_KEY. 523 | 524 | 1.6 Differences Between PF_KEY and PF_ROUTE 525 | 526 | The following bullets are points of difference between the routing 527 | socket and PF_KEY. Programmers who are used to the routing socket 528 | semantics will find some differences in PF_KEY. 529 | 530 | * PF_KEY message errors are usually returned in PF_KEY messages 531 | instead of causing write() operations to fail and returning the 532 | error number in errno. This means that other listeners on a PF_KEY 533 | socket can be aware that requests from another process failed, 534 | which can be useful for auditing purposes. This also means that 535 | applications that fail to read PF_KEY messages cannot do error 536 | checking. 537 | 538 | An implementation MAY return the errors EINVAL, ENOMEM, and ENOBUFS 539 | by causing write() operations to fail and returning the error 540 | number in errno. This is an optimization for common error cases in 541 | which it does not make sense for any other process to receive the 542 | error. An application MUST NOT depend on such errors being set by 543 | the write() call, but it SHOULD check for such errors, and handle 544 | them in an appropriate manner. 545 | 546 | * The entire message isn't always reflected in the reply. A SADB_ADD 547 | message is an example of this. 548 | 549 | * The PID is not set by the kernel. The process that originates the 550 | message MUST set the sadb_msg_pid to its own PID. If the kernel 551 | ORIGINATES a message, it MUST set the sadb_msg_pid to 0. A reply 552 | to an original message SHOULD have the pid of the original message. 553 | (E.g. the kernel's response to an SADB_ADD SHOULD have its pid set 554 | to the pid value of the original SADB_ADD message.) 555 | 556 | 557 | 558 | 559 | 560 | 561 | 562 | McDonald, et. al. Informational [Page 10] 563 | 564 | RFC 2367 PF_KEY Key Management API July 1998 565 | 566 | 567 | 1.7 Name Space 568 | 569 | All PF_KEYv2 preprocessor symbols and structure definitions are 570 | defined as a result of including the header file . 571 | There is exactly one exception to this rule: the symbol "PF_KEY" (two 572 | exceptions if "AF_KEY" is also counted), which is defined as a result 573 | of including the header file . All PF_KEYv2 574 | preprocessor symbols start with the prefix "SADB_" and all structure 575 | names start with "sadb_". There are exactly two exceptions to this 576 | rule: the symbol "PF_KEY_V2" and the symbol "PFKEYV2_REVISION". 577 | 578 | The symbol "PFKEYV2_REVISION" is a date-encoded value not unlike 579 | certain values defined by POSIX and X/Open. The current value for 580 | PFKEYV2_REVISION is 199806L, where 1998 is the year and 06 is the 581 | month. 582 | 583 | Inclusion of the file MUST NOT define symbols or 584 | structures in the PF_KEYv2 name space that are not described in this 585 | document without the explicit prior permission of the authors. Any 586 | symbols or structures in the PF_KEYv2 name space that are not 587 | described in this document MUST start with "SADB_X_" or "sadb_x_". An 588 | implementation that fails to obey these rules IS NOT COMPLIANT WITH 589 | THIS SPECIFICATION and MUST NOT make any claim to be. These rules 590 | also apply to any files that might be included as a result of 591 | including the file . This rule provides implementors 592 | with some assurance that they will not encounter namespace-related 593 | surprises. 594 | 595 | 1.8 On Manual Keying 596 | 597 | Not unlike the 4.4-Lite BSD PF_ROUTE socket, this interface allows an 598 | application full-reign over the security associations in a kernel 599 | that implements PF_KEY. A PF_KEY implementation MUST have some sort 600 | of manual interface to PF_KEY, which SHOULD allow all of the 601 | functionality of the programmatic interface described here. 602 | 603 | 2. PF_KEY Message Format 604 | 605 | PF_KEY messages consist of a base header followed by additional data 606 | fields, some of which may be optional. The format of the additional 607 | data is dependent on the type of message. 608 | 609 | PF_KEY messages currently do not mandate any specific ordering for 610 | non-network multi-octet fields. Unless otherwise specified (e.g. SPI 611 | values), fields MUST be in host-specific byte order. 612 | 613 | 614 | 615 | 616 | 617 | 618 | McDonald, et. al. Informational [Page 11] 619 | 620 | RFC 2367 PF_KEY Key Management API July 1998 621 | 622 | 623 | 2.1 Base Message Header Format 624 | 625 | PF_KEY messages consist of the base message header followed by 626 | security association specific data whose types and lengths are 627 | specified by a generic type-length encoding. 628 | 629 | This base header is shown below, using POSIX types. The fields are 630 | arranged primarily for alignment, and where possible, for reasons of 631 | clarity. 632 | 633 | struct sadb_msg { 634 | uint8_t sadb_msg_version; 635 | uint8_t sadb_msg_type; 636 | uint8_t sadb_msg_errno; 637 | uint8_t sadb_msg_satype; 638 | uint16_t sadb_msg_len; 639 | uint16_t sadb_msg_reserved; 640 | uint32_t sadb_msg_seq; 641 | uint32_t sadb_msg_pid; 642 | }; 643 | /* sizeof(struct sadb_msg) == 16 */ 644 | 645 | sadb_msg_version 646 | The version field of this PF_KEY message. This MUST 647 | be set to PF_KEY_V2. If this is not set to PF_KEY_V2, 648 | the write() call MAY fail and return EINVAL. 649 | Otherwise, the behavior is undetermined, given that 650 | the application might not understand the formatting 651 | of the messages arriving from the kernel. 652 | 653 | sadb_msg_type Identifies the type of message. The valid message 654 | types are described later in this document. 655 | 656 | sadb_msg_errno Should be set to zero by the sender. The responder 657 | stores the error code in this field if an error has 658 | occurred. This includes the case where the responder 659 | is in user space. (e.g. user-space negotiation 660 | fails, an errno can be returned.) 661 | 662 | sadb_msg_satype Indicates the type of security association(s). Valid 663 | Security Association types are declared in the file 664 | . The current set of Security 665 | Association types is enumerated later in this 666 | document. 667 | 668 | 669 | 670 | 671 | 672 | 673 | 674 | McDonald, et. al. Informational [Page 12] 675 | 676 | RFC 2367 PF_KEY Key Management API July 1998 677 | 678 | 679 | sadb_msg_len Contains the total length, in 64-bit words, of all 680 | data in the PF_KEY message including the base header 681 | length and additional data after the base header, if 682 | any. This length includes any padding or extra space 683 | that might exist. Unless otherwise stated, all other 684 | length fields are also measured in 64-bit words. 685 | 686 | On user to kernel messages, this field MUST be 687 | verified against the length of the inbound message. 688 | EMSGSIZE MUST be returned if the verification fails. 689 | On kernel to user messages, a size mismatch is most 690 | likely the result of the user not providing a large 691 | enough buffer for the message. In these cases, the 692 | user application SHOULD drop the message, but it MAY 693 | try and extract what information it can out of the 694 | message. 695 | 696 | sadb_msg_reserved 697 | Reserved value. It MUST be zeroed by the sender. All 698 | fields labeled reserved later in the document have 699 | the same semantics as this field. 700 | 701 | sadb_msg_seq Contains the sequence number of this message. This 702 | field, along with sadb_msg_pid, MUST be used to 703 | uniquely identify requests to a process. The sender 704 | is responsible for filling in this field. This 705 | responsibility also includes matching the 706 | sadb_msg_seq of a request (e.g. SADB_ACQUIRE). 707 | 708 | This field is similar to a transaction ID in a 709 | remote procedure call implementation. 710 | 711 | sadb_msg_pid Identifies the process which originated this message, 712 | or which process a message is bound for. For 713 | example, if process id 2112 sends an SADB_UPDATE 714 | message to the kernel, the process MUST set this 715 | field to 2112 and the kernel will set this field 716 | to 2112 in its reply to that SADB_UPDATE 717 | message. This field, along with sadb_msg_seq, can 718 | be used to uniquely identify requests to a 719 | process. 720 | 721 | It is currently assumed that a 32-bit quantity will 722 | hold an operating system's process ID space. 723 | 724 | 725 | 726 | 727 | 728 | 729 | 730 | McDonald, et. al. Informational [Page 13] 731 | 732 | RFC 2367 PF_KEY Key Management API July 1998 733 | 734 | 735 | 2.2 Alignment of Headers and Extension Headers 736 | 737 | The base message header is a multiple of 64 bits and fields after it 738 | in memory will be 64 bit aligned if the base itself is 64 bit 739 | aligned. Some of the subsequent extension headers have 64 bit fields 740 | in them, and as a consequence need to be 64 bit aligned in an 741 | environment where 64 bit quantities need to be 64 bit aligned. 742 | 743 | The basic unit of alignment and length in PF_KEY Version 2 is 64 744 | bits. Therefore: 745 | 746 | * All extension headers, inclusive of the sadb_ext overlay fields, 747 | MUST be a multiple of 64 bits long. 748 | 749 | * All variable length data MUST be padded appropriately such that 750 | its length in a message is a multiple of 64 bits. 751 | 752 | * All length fields are, unless otherwise specified, in units of 753 | 64 bits. 754 | 755 | * Implementations may safely access quantities of between 8 and 64 756 | bits directly within a message without risk of alignment faults. 757 | 758 | All PF_KEYv2 structures are packed and already have all intended 759 | padding. Implementations MUST NOT insert any extra fields, including 760 | hidden padding, into any structure in this document. This forbids 761 | implementations from "extending" or "enhancing" existing headers 762 | without changing the extension header type. As a guard against such 763 | insertion of silent padding, each structure in this document is 764 | labeled with its size in bytes. The size of these structures in an 765 | implementation MUST match the size listed. 766 | 767 | 2.3 Additional Message Fields 768 | 769 | The additional data following the base header consists of various 770 | length-type-values fields. The first 32-bits are of a constant form: 771 | 772 | struct sadb_ext { 773 | uint16_t sadb_ext_len; 774 | uint16_t sadb_ext_type; 775 | }; 776 | /* sizeof(struct sadb_ext) == 4 */ 777 | 778 | sadb_ext_len Length of the extension header in 64 bit words, 779 | inclusive. 780 | 781 | 782 | 783 | 784 | 785 | 786 | McDonald, et. al. Informational [Page 14] 787 | 788 | RFC 2367 PF_KEY Key Management API July 1998 789 | 790 | 791 | sadb_ext_type The type of extension header that follows. Values for 792 | this field are detailed later. The value zero is 793 | reserved. 794 | 795 | Types of extension headers include: Association, Lifetime(s), 796 | Address(s), Key(s), Identity(ies), Sensitivity, Proposal, and 797 | Supported. There MUST be only one instance of a extension type in a 798 | message. (e.g. Base, Key, Lifetime, Key is forbidden). An EINVAL 799 | will be returned if there are duplicate extensions within a message. 800 | Implementations MAY enforce ordering of extensions in the order 801 | presented in the EXTENSION HEADER VALUES section. 802 | 803 | If an unknown extension type is encountered, it MUST be ignored. 804 | Applications using extension headers not specified in this document 805 | MUST be prepared to work around other system components not 806 | processing those headers. Likewise, if an application encounters an 807 | unknown extension from the kernel, it must be prepared to work around 808 | it. Also, a kernel that generates extra extension header types MUST 809 | NOT _depend_ on applications also understanding extra extension 810 | header types. 811 | 812 | All extension definitions include these two fields (len and exttype) 813 | because they are instances of a generic extension (not unlike 814 | sockaddr_in and sockaddr_in6 are instances of a generic sockaddr). 815 | The sadb_ext header MUST NOT ever be present in a message without at 816 | least four bytes of extension header data following it, and, 817 | therefore, there is no problem with it being only four bytes long. 818 | 819 | All extensions documented in this section MUST be implemented by a 820 | PF_KEY implementation. 821 | 822 | 2.3.1 Association Extension 823 | 824 | The Association extension specifies data specific to a single 825 | security association. The only times this extension is not present is 826 | when control messages (e.g. SADB_FLUSH or SADB_REGISTER) are being 827 | passed and on the SADB_ACQUIRE message. 828 | 829 | struct sadb_sa { 830 | uint16_t sadb_sa_len; 831 | uint16_t sadb_sa_exttype; 832 | uint32_t sadb_sa_spi; 833 | uint8_t sadb_sa_replay; 834 | uint8_t sadb_sa_state; 835 | uint8_t sadb_sa_auth; 836 | uint8_t sadb_sa_encrypt; 837 | uint32_t sadb_sa_flags; 838 | }; 839 | 840 | 841 | 842 | McDonald, et. al. Informational [Page 15] 843 | 844 | RFC 2367 PF_KEY Key Management API July 1998 845 | 846 | 847 | /* sizeof(struct sadb_sa) == 16 */ 848 | 849 | sadb_sa_spi The Security Parameters Index value for the security 850 | association. Although this is a 32-bit field, some 851 | types of security associations might have an SPI or 852 | key identifier that is less than 32-bits long. In 853 | this case, the smaller value shall be stored in the 854 | least significant bits of this field and the unneeded 855 | bits shall be zero. This field MUST be in network 856 | byte order. 857 | 858 | sadb_sa_replay The size of the replay window, if not zero. If zero, 859 | then no replay window is in use. 860 | 861 | sadb_sa_state The state of the security association. The currently 862 | defined states are described later in this document. 863 | 864 | sadb_sa_auth The authentication algorithm to be used with this 865 | security association. The valid authentication 866 | algorithms are described later in this document. A 867 | value of zero means that no authentication is used 868 | for this security association. 869 | 870 | sadb_sa_encrypt The encryption algorithm to be used with this 871 | security association. The valid encryption algorithms 872 | are described later in this document. A value of zero 873 | means that no encryption is used for this security 874 | association. 875 | 876 | sadb_sa_flags A bitmap of options defined for the security 877 | association. The currently defined flags are 878 | described later in this document. 879 | 880 | The kernel MUST check these values where appropriate. For example, 881 | IPsec AH with no authentication algorithm is probably an error. 882 | 883 | When used with some messages, the values in some fields in this 884 | header should be ignored. 885 | 886 | 2.3.2 Lifetime Extension 887 | 888 | The Lifetime extension specifies one or more lifetime variants for 889 | this security association. If no Lifetime extension is present the 890 | association has an infinite lifetime. An association SHOULD have a 891 | lifetime of some sort associated with it. Lifetime variants come in 892 | three varieties, HARD - indicating the hard-limit expiration, SOFT - 893 | indicating the soft-limit expiration, and CURRENT - indicating the 894 | current state of a given security association. The Lifetime 895 | 896 | 897 | 898 | McDonald, et. al. Informational [Page 16] 899 | 900 | RFC 2367 PF_KEY Key Management API July 1998 901 | 902 | 903 | extension looks like: 904 | 905 | struct sadb_lifetime { 906 | uint16_t sadb_lifetime_len; 907 | uint16_t sadb_lifetime_exttype; 908 | uint32_t sadb_lifetime_allocations; 909 | uint64_t sadb_lifetime_bytes; 910 | uint64_t sadb_lifetime_addtime; 911 | uint64_t sadb_lifetime_usetime; 912 | }; 913 | /* sizeof(struct sadb_lifetime) == 32 */ 914 | 915 | sadb_lifetime_allocations 916 | For CURRENT, the number of different connections, 917 | endpoints, or flows that the association has been 918 | allocated towards. For HARD and SOFT, the number of 919 | these the association may be allocated towards 920 | before it expires. The concept of a connection, 921 | flow, or endpoint is system specific. 922 | 923 | sadb_lifetime_bytes 924 | For CURRENT, how many bytes have been processed 925 | using this security association. For HARD and SOFT, 926 | the number of bytes that may be processed using 927 | this security association before it expires. 928 | 929 | sadb_lifetime_addtime 930 | For CURRENT, the time, in seconds, when the 931 | association was created. For HARD and SOFT, the 932 | number of seconds after the creation of the 933 | association until it expires. 934 | 935 | For such time fields, it is assumed that 64-bits is 936 | sufficiently large to hold the POSIX time_t value. 937 | If this assumption is wrong, this field will have to 938 | be revisited. 939 | 940 | sadb_lifetime_usetime 941 | For CURRENT, the time, in seconds, when association 942 | was first used. For HARD and SOFT, the number of 943 | seconds after the first use of the association until 944 | it expires. 945 | 946 | The semantics of lifetimes are inclusive-OR, first-to-expire. This 947 | means that if values for bytes and time, or multiple times, are 948 | passed in, the first of these values to be reached will cause a 949 | lifetime expiration. 950 | 951 | 952 | 953 | 954 | McDonald, et. al. Informational [Page 17] 955 | 956 | RFC 2367 PF_KEY Key Management API July 1998 957 | 958 | 959 | 2.3.3 Address Extension 960 | 961 | The Address extension specifies one or more addresses that are 962 | associated with a security association. Address extensions for both 963 | source and destination MUST be present when an Association extension 964 | is present. The format of an Address extension is: 965 | 966 | struct sadb_address { 967 | uint16_t sadb_address_len; 968 | uint16_t sadb_address_exttype; 969 | uint8_t sadb_address_proto; 970 | uint8_t sadb_address_prefixlen; 971 | uint16_t sadb_address_reserved; 972 | }; 973 | /* sizeof(struct sadb_address) == 8 */ 974 | 975 | /* followed by some form of struct sockaddr */ 976 | 977 | The sockaddr structure SHOULD conform to the sockaddr structure of 978 | the system implementing PF_KEY. If the system has an sa_len field, so 979 | SHOULD the sockaddrs in the message. If the system has NO sa_len 980 | field, the sockaddrs SHOULD NOT have an sa_len field. All non-address 981 | information in the sockaddrs, such as sin_zero for AF_INET sockaddrs, 982 | and sin6_flowinfo for AF_INET6 sockaddrs, MUST be zeroed out. The 983 | zeroing of ports (e.g. sin_port and sin6_port) MUST be done for all 984 | messages except for originating SADB_ACQUIRE messages, which SHOULD 985 | fill them in with ports from the relevant TCP or UDP session which 986 | generates the ACQUIRE message. If the ports are non-zero, then the 987 | sadb_address_proto field, normally zero, MUST be filled in with the 988 | transport protocol's number. If the sadb_address_prefixlen is non- 989 | zero, then the address has a prefix (often used in KM access control 990 | decisions), with length specified in sadb_address_prefixlen. These 991 | additional fields may be useful to KM applications. 992 | 993 | The SRC and DST addresses for a security association MUST be in the 994 | same protocol family and MUST always be present or absent together in 995 | a message. The PROXY address MAY be in a different protocol family, 996 | and for most security protocols, represents an actual originator of a 997 | packet. (For example, the inner-packets's source address in a 998 | tunnel.) 999 | 1000 | The SRC address MUST be a unicast or unspecified (e.g., INADDR_ANY) 1001 | address. The DST address can be any valid destination address 1002 | (unicast, multicast, or even broadcast). The PROXY address SHOULD be 1003 | a unicast address (there are experimental security protocols where 1004 | PROXY semantics may be different than described above). 1005 | 1006 | 1007 | 1008 | 1009 | 1010 | McDonald, et. al. Informational [Page 18] 1011 | 1012 | RFC 2367 PF_KEY Key Management API July 1998 1013 | 1014 | 1015 | 2.3.4 Key Extension 1016 | 1017 | The Key extension specifies one or more keys that are associated with 1018 | a security association. A Key extension will not always be present 1019 | with messages, because of security risks. The format of a Key 1020 | extension is: 1021 | 1022 | struct sadb_key { 1023 | uint16_t sadb_key_len; 1024 | uint16_t sadb_key_exttype; 1025 | uint16_t sadb_key_bits; 1026 | uint16_t sadb_key_reserved; 1027 | }; 1028 | /* sizeof(struct sadb_key) == 8 */ 1029 | 1030 | /* followed by the key data */ 1031 | 1032 | sadb_key_bits The length of the valid key data, in bits. A value of 1033 | zero in sadb_key_bits MUST cause an error. 1034 | 1035 | The key extension comes in two varieties. The AUTH version is used 1036 | with authentication keys (e.g. IPsec AH, OSPF MD5) and the ENCRYPT 1037 | version is used with encryption keys (e.g. IPsec ESP). PF_KEY deals 1038 | only with fully formed cryptographic keys, not with "raw key 1039 | material". For example, when ISAKMP/Oakley is in use, the key 1040 | management daemon is always responsible for transforming the result 1041 | of the Diffie-Hellman computation into distinct fully formed keys 1042 | PRIOR to sending those keys into the kernel via PF_KEY. This rule is 1043 | made because PF_KEY is designed to support multiple security 1044 | protocols (not just IP Security) and also multiple key management 1045 | schemes including manual keying, which does not have the concept of 1046 | "raw key material". A clean, protocol-independent interface is 1047 | important for portability to different operating systems as well as 1048 | for portability to different security protocols. 1049 | 1050 | If an algorithm defines its key to include parity bits (e.g. DES) 1051 | then the key used with PF_KEY MUST also include those parity bits. 1052 | For example, this means that a single DES key is always a 64-bit 1053 | quantity. 1054 | 1055 | When a particular security protocol only requires one authentication 1056 | and/or one encryption key, the fully formed key is transmitted using 1057 | the appropriate key extension. When a particular security protocol 1058 | requires more than one key for the same function (e.g. Triple-DES 1059 | using 2 or 3 keys, and asymmetric algorithms), then those two fully 1060 | formed keys MUST be concatenated together in the order used for 1061 | outbound packet processing. In the case of multiple keys, the 1062 | algorithm MUST be able to determine the lengths of the individual 1063 | 1064 | 1065 | 1066 | McDonald, et. al. Informational [Page 19] 1067 | 1068 | RFC 2367 PF_KEY Key Management API July 1998 1069 | 1070 | 1071 | keys based on the information provided. The total key length (when 1072 | combined with knowledge of the algorithm in use) usually provides 1073 | sufficient information to make this determination. 1074 | 1075 | Keys are always passed through the PF_KEY interface in the order that 1076 | they are used for outbound packet processing. For inbound processing, 1077 | the correct order that keys are used might be different from this 1078 | canonical concatenation order used with the PF_KEY interface. It is 1079 | the responsibility of the implementation to use the keys in the 1080 | correct order for both inbound and outbound processing. 1081 | 1082 | For example, consider a pair of nodes communicating unicast using an 1083 | ESP three-key Triple-DES Security Association. Both the outbound SA 1084 | on the sender node, and the inbound SA on the receiver node will 1085 | contain key-A, followed by key-B, followed by key-C in their 1086 | respective ENCRYPT key extensions. The outbound SA will use key-A 1087 | first, followed by key-B, then key-C when encrypting. The inbound SA 1088 | will use key-C, followed by key-B, then key-A when decrypting. 1089 | (NOTE: We are aware that 3DES is actually encrypt-decrypt-encrypt.) 1090 | The canonical ordering of key-A, key-B, key-C is used for 3DES, and 1091 | should be documented. The order of "encryption" is the canonical 1092 | order for this example. [Sch96] 1093 | 1094 | The key data bits are arranged most-significant to least significant. 1095 | For example, a 22-bit key would take up three octets, with the least 1096 | significant two bits not containing key material. Five additional 1097 | octets would then be used for padding to the next 64-bit boundary. 1098 | 1099 | While not directly related to PF_KEY, there is a user interface issue 1100 | regarding odd-digit hexadecimal representation of keys. Consider the 1101 | example of the 16-bit number: 1102 | 1103 | 0x123 1104 | 1105 | That will require two octets of storage. In the absence of other 1106 | information, however, unclear whether the value shown is stored as: 1107 | 1108 | 01 23 OR 12 30 1109 | 1110 | It is the opinion of the authors that the former (0x123 == 0x0123) is 1111 | the better way to interpret this ambiguity. Extra information (for 1112 | example, specifying 0x0123 or 0x1230, or specifying that this is only 1113 | a twelve-bit number) would solve this problem. 1114 | 1115 | 1116 | 1117 | 1118 | 1119 | 1120 | 1121 | 1122 | McDonald, et. al. Informational [Page 20] 1123 | 1124 | RFC 2367 PF_KEY Key Management API July 1998 1125 | 1126 | 1127 | 2.3.5 Identity Extension 1128 | 1129 | The Identity extension contains endpoint identities. This 1130 | information is used by key management to select the identity 1131 | certificate that is used in negotiations. This information may also 1132 | be provided by a kernel to network security aware applications to 1133 | identify the remote entity, possibly for access control purposes. If 1134 | this extension is not present, key management MUST assume that the 1135 | addresses in the Address extension are the only identities for this 1136 | Security Association. The Identity extension looks like: 1137 | 1138 | struct sadb_ident { 1139 | uint16_t sadb_ident_len; 1140 | uint16_t sadb_ident_exttype; 1141 | uint16_t sadb_ident_type; 1142 | uint16_t sadb_ident_reserved; 1143 | uint64_t sadb_ident_id; 1144 | }; 1145 | /* sizeof(struct sadb_ident) == 16 */ 1146 | 1147 | /* followed by the identity string, if present */ 1148 | 1149 | sadb_ident_type The type of identity information that follows. 1150 | Currently defined identity types are described later 1151 | in this document. 1152 | 1153 | sadb_ident_id An identifier used to aid in the construction of an 1154 | identity string if none is present. A POSIX user id 1155 | value is one such identifier that will be used in this 1156 | field. Use of this field is described later in this 1157 | document. 1158 | 1159 | A C string containing a textual representation of the identity 1160 | information optionally follows the sadb_ident extension. The format 1161 | of this string is determined by the value in sadb_ident_type, and is 1162 | described later in this document. 1163 | 1164 | 2.3.6 Sensitivity Extension 1165 | 1166 | The Sensitivity extension contains security labeling information for 1167 | a security association. If this extension is not present, no 1168 | sensitivity-related data can be obtained from this security 1169 | association. If this extension is present, then the need for 1170 | explicit security labeling on the packet is obviated. 1171 | 1172 | struct sadb_sens { 1173 | uint16_t sadb_sens_len; 1174 | uint16_t sadb_sens_exttype; 1175 | 1176 | 1177 | 1178 | McDonald, et. al. Informational [Page 21] 1179 | 1180 | RFC 2367 PF_KEY Key Management API July 1998 1181 | 1182 | 1183 | uint32_t sadb_sens_dpd; 1184 | uint8_t sadb_sens_sens_level; 1185 | uint8_t sadb_sens_sens_len; 1186 | uint8_t sadb_sens_integ_level; 1187 | uint8_t sadb_sens_integ_len; 1188 | uint32_t sadb_sens_reserved; 1189 | }; 1190 | /* sizeof(struct sadb_sens) == 16 */ 1191 | 1192 | /* followed by: 1193 | uint64_t sadb_sens_bitmap[sens_len]; 1194 | uint64_t sadb_integ_bitmap[integ_len]; */ 1195 | 1196 | sadb_sens_dpd Describes the protection domain, which allows 1197 | interpretation of the levels and compartment 1198 | bitmaps. 1199 | sadb_sens_sens_level 1200 | The sensitivity level. 1201 | sadb_sens_sens_len 1202 | The length, in 64 bit words, of the sensitivity 1203 | bitmap. 1204 | sadb_sens_integ_level 1205 | The integrity level. 1206 | sadb_sens_integ_len 1207 | The length, in 64 bit words, of the integrity 1208 | bitmap. 1209 | 1210 | This sensitivity extension is designed to support the Bell-LaPadula 1211 | [BL74] security model used in compartmented-mode or multi-level 1212 | secure systems, the Clark-Wilson [CW87] commercial security model, 1213 | and/or the Biba integrity model [Biba77]. These formal models can be 1214 | used to implement a wide variety of security policies. The definition 1215 | of a particular security policy is outside the scope of this 1216 | document. Each of the bitmaps MUST be padded to a 64-bit boundary if 1217 | they are not implicitly 64-bit aligned. 1218 | 1219 | 2.3.7 Proposal Extension 1220 | 1221 | The Proposal extension contains a "proposed situation" of algorithm 1222 | preferences. It looks like: 1223 | 1224 | struct sadb_prop { 1225 | uint16_t sadb_prop_len; 1226 | uint16_t sadb_prop_exttype; 1227 | uint8_t sadb_prop_replay; 1228 | uint8_t sadb_prop_reserved[3]; 1229 | }; 1230 | /* sizeof(struct sadb_prop) == 8 */ 1231 | 1232 | 1233 | 1234 | McDonald, et. al. Informational [Page 22] 1235 | 1236 | RFC 2367 PF_KEY Key Management API July 1998 1237 | 1238 | 1239 | /* followed by: 1240 | struct sadb_comb sadb_combs[(sadb_prop_len * 1241 | sizeof(uint64_t) - sizeof(struct sadb_prop)) / 1242 | sizeof(struct sadb_comb)]; */ 1243 | 1244 | Following the header is a list of proposed parameter combinations in 1245 | preferential order. The values in these fields have the same 1246 | definition as the fields those values will move into if the 1247 | combination is chosen. 1248 | 1249 | NOTE: Some algorithms in some security protocols will have 1250 | variable IV lengths per algorithm. Variable length IVs 1251 | are not supported by PF_KEY v2. If they were, however, 1252 | proposed IV lengths would go in the Proposal Extension. 1253 | 1254 | These combinations look like: 1255 | 1256 | struct sadb_comb { 1257 | uint8_t sadb_comb_auth; 1258 | uint8_t sadb_comb_encrypt; 1259 | uint16_t sadb_comb_flags; 1260 | uint16_t sadb_comb_auth_minbits; 1261 | uint16_t sadb_comb_auth_maxbits; 1262 | uint16_t sadb_comb_encrypt_minbits; 1263 | uint16_t sadb_comb_encrypt_maxbits; 1264 | uint32_t sadb_comb_reserved; 1265 | uint32_t sadb_comb_soft_allocations; 1266 | uint32_t sadb_comb_hard_allocations; 1267 | uint64_t sadb_comb_soft_bytes; 1268 | uint64_t sadb_comb_hard_bytes; 1269 | uint64_t sadb_comb_soft_addtime; 1270 | uint64_t sadb_comb_hard_addtime; 1271 | uint64_t sadb_comb_soft_usetime; 1272 | uint64_t sadb_comb_hard_usetime; 1273 | }; 1274 | 1275 | /* sizeof(struct sadb_comb) == 72 */ 1276 | 1277 | sadb_comb_auth If this combination is accepted, this will be the 1278 | value of sadb_sa_auth. 1279 | 1280 | sadb_comb_encrypt 1281 | If this combination is accepted, this will be the 1282 | value of sadb_sa_encrypt. 1283 | 1284 | 1285 | 1286 | 1287 | 1288 | 1289 | 1290 | McDonald, et. al. Informational [Page 23] 1291 | 1292 | RFC 2367 PF_KEY Key Management API July 1998 1293 | 1294 | 1295 | sadb_comb_auth_minbits; 1296 | sadb_comb_auth_maxbits; 1297 | The minimum and maximum acceptable authentication 1298 | key lengths, respectably, in bits. If sadb_comb_auth 1299 | is zero, both of these values MUST be zero. If 1300 | sadb_comb_auth is nonzero, both of these values MUST 1301 | be nonzero. If this combination is accepted, a value 1302 | between these (inclusive) will be stored in the 1303 | sadb_key_bits field of KEY_AUTH. The minimum MUST 1304 | NOT be greater than the maximum. 1305 | 1306 | sadb_comb_encrypt_minbits; 1307 | sadb_comb_encrypt_maxbits; 1308 | The minimum and maximum acceptable encryption key 1309 | lengths, respectably, in bits. If sadb_comb_encrypt 1310 | is zero, both of these values MUST be zero. If 1311 | sadb_comb_encrypt is nonzero, both of these values 1312 | MUST be nonzero. If this combination is accepted, a 1313 | value between these (inclusive) will be stored in 1314 | the sadb_key_bits field of KEY_ENCRYPT. The minimum 1315 | MUST NOT be greater than the maximum. 1316 | 1317 | sadb_comb_soft_allocations 1318 | sadb_comb_hard_allocations 1319 | If this combination is accepted, these are proposed 1320 | values of sadb_lifetime_allocations in the SOFT and 1321 | HARD lifetimes, respectively. 1322 | 1323 | sadb_comb_soft_bytes 1324 | sadb_comb_hard_bytes 1325 | If this combination is accepted, these are proposed 1326 | values of sadb_lifetime_bytes in the SOFT and HARD 1327 | lifetimes, respectively. 1328 | 1329 | sadb_comb_soft_addtime 1330 | sadb_comb_hard_addtime 1331 | If this combination is accepted, these are proposed 1332 | values of sadb_lifetime_addtime in the SOFT and HARD 1333 | lifetimes, respectively. 1334 | 1335 | sadb_comb_soft_usetime 1336 | sadb_comb_hard_usetime 1337 | If this combination is accepted, these are proposed 1338 | values of sadb_lifetime_usetime in the SOFT and HARD 1339 | lifetimes, respectively. 1340 | 1341 | 1342 | 1343 | 1344 | 1345 | 1346 | McDonald, et. al. Informational [Page 24] 1347 | 1348 | RFC 2367 PF_KEY Key Management API July 1998 1349 | 1350 | 1351 | Each combination has an authentication and encryption algorithm, 1352 | which may be 0, indicating none. A combination's flags are the same 1353 | as the flags in the Association extension. The minimum and maximum 1354 | key lengths (which are in bits) are derived from possible a priori 1355 | policy decisions, along with basic properties of the algorithm. 1356 | Lifetime attributes are also included in a combination, as some 1357 | algorithms may know something about their lifetimes and can suggest 1358 | lifetime limits. 1359 | 1360 | 2.3.8 Supported Algorithms Extension 1361 | 1362 | The Supported Algorithms extension contains a list of all algorithms 1363 | supported by the system. This tells key management what algorithms it 1364 | can negotiate. Available authentication algorithms are listed in the 1365 | SUPPORTED_AUTH extension and available encryption algorithms are 1366 | listed in the SUPPORTED_ENCRYPT extension. The format of these 1367 | extensions is: 1368 | 1369 | struct sadb_supported { 1370 | uint16_t sadb_supported_len; 1371 | uint16_t sadb_supported_exttype; 1372 | uint32_t sadb_supported_reserved; 1373 | }; 1374 | /* sizeof(struct sadb_supported) == 8 */ 1375 | 1376 | /* followed by: 1377 | struct sadb_alg sadb_algs[(sadb_supported_len * 1378 | sizeof(uint64_t) - sizeof(struct sadb_supported)) / 1379 | sizeof(struct sadb_alg)]; */ 1380 | 1381 | This header is followed by one or more algorithm descriptions. An 1382 | algorithm description looks like: 1383 | 1384 | struct sadb_alg { 1385 | uint8_t sadb_alg_id; 1386 | uint8_t sadb_alg_ivlen; 1387 | uint16_t sadb_alg_minbits; 1388 | uint16_t sadb_alg_maxbits; 1389 | uint16_t sadb_alg_reserved; 1390 | }; 1391 | /* sizeof(struct sadb_alg) == 8 */ 1392 | 1393 | sadb_alg_id The algorithm identification value for this 1394 | algorithm. This is the value that is stored in 1395 | sadb_sa_auth or sadb_sa_encrypt if this algorithm is 1396 | selected. 1397 | 1398 | 1399 | 1400 | 1401 | 1402 | McDonald, et. al. Informational [Page 25] 1403 | 1404 | RFC 2367 PF_KEY Key Management API July 1998 1405 | 1406 | 1407 | sadb_alg_ivlen The length of the initialization vector to be used 1408 | for the algorithm. If an IV is not needed, this 1409 | value MUST be set to zero. 1410 | 1411 | sadb_alg_minbits 1412 | The minimum acceptable key length, in bits. A value 1413 | of zero is invalid. 1414 | 1415 | sadb_alg_maxbits 1416 | The maximum acceptable key length, in bits. A value 1417 | of zero is invalid. The minimum MUST NOT be greater 1418 | than the maximum. 1419 | 1420 | 2.3.9 SPI Range Extension 1421 | 1422 | One PF_KEY message, SADB_GETSPI, might need a range of acceptable SPI 1423 | values. This extension performs such a function. 1424 | 1425 | struct sadb_spirange { 1426 | uint16_t sadb_spirange_len; 1427 | uint16_t sadb_spirange_exttype; 1428 | uint32_t sadb_spirange_min; 1429 | uint32_t sadb_spirange_max; 1430 | uint32_t sadb_spirange_reserved; 1431 | }; 1432 | /* sizeof(struct sadb_spirange) == 16 */ 1433 | 1434 | sadb_spirange_min 1435 | The minimum acceptable SPI value. 1436 | 1437 | sadb_spirange_max 1438 | The maximum acceptable SPI value. The maximum MUST 1439 | be greater than or equal to the minimum. 1440 | 1441 | 1442 | 1443 | 1444 | 1445 | 1446 | 1447 | 1448 | 1449 | 1450 | 1451 | 1452 | 1453 | 1454 | 1455 | 1456 | 1457 | 1458 | McDonald, et. al. Informational [Page 26] 1459 | 1460 | RFC 2367 PF_KEY Key Management API July 1998 1461 | 1462 | 1463 | 2.4 Illustration of Message Layout 1464 | 1465 | The following shows how the octets are laid out in a PF_KEY message. 1466 | Optional fields are indicated as such. 1467 | 1468 | The base header is as follows: 1469 | 1470 | 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 1471 | +---------------+---------------+---------------+---------------+ 1472 | | ...version | sadb_msg_type | sadb_msg_errno| ...msg_satype | 1473 | +---------------+---------------+---------------+---------------+ 1474 | | sadb_msg_len | sadb_msg_reserved | 1475 | +---------------+---------------+---------------+---------------+ 1476 | | sadb_msg_seq | 1477 | +---------------+---------------+---------------+---------------+ 1478 | | sadb_msg_pid | 1479 | +---------------+---------------+---------------+---------------+ 1480 | 1481 | The base header may be followed by one or more of the following 1482 | extension fields, depending on the values of various base header 1483 | fields. The following fields are ordered such that if they appear, 1484 | they SHOULD appear in the order presented below. 1485 | 1486 | An extension field MUST not be repeated. If there is a situation 1487 | where an extension MUST be repeated, it should be brought to the 1488 | attention of the authors. 1489 | 1490 | The Association extension 1491 | 1492 | 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 1493 | +---------------+---------------+---------------+---------------+ 1494 | | sadb_sa_len | sadb_sa_exttype | 1495 | +---------------+---------------+---------------+---------------+ 1496 | | sadb_sa_spi | 1497 | +---------------+---------------+---------------+---------------+ 1498 | | ...replay | sadb_sa_state | sadb_sa_auth |sadb_sa_encrypt| 1499 | +---------------+---------------+---------------+---------------+ 1500 | | sadb_sa_flags | 1501 | +---------------+---------------+---------------+---------------+ 1502 | 1503 | The Lifetime extension 1504 | 1505 | +---------------+---------------+---------------+---------------+ 1506 | | sadb_lifetime_len | sadb_lifetime_exttype | 1507 | +---------------+---------------+---------------+---------------+ 1508 | | sadb_lifetime_allocations | 1509 | +---------------+---------------+---------------+---------------+ 1510 | 1511 | 1512 | 1513 | 1514 | McDonald, et. al. Informational [Page 27] 1515 | 1516 | RFC 2367 PF_KEY Key Management API July 1998 1517 | 1518 | 1519 | +---------------+---------------+---------------+---------------+ 1520 | | sadb_lifetime_bytes | 1521 | | (64 bits) | 1522 | +---------------+---------------+---------------+---------------+ 1523 | | sadb_lifetime_addtime | 1524 | | (64 bits) | 1525 | +---------------+---------------+---------------+---------------+ 1526 | | sadb_lifetime_usetime | 1527 | | (64 bits) | 1528 | +---------------+---------------+---------------+---------------+ 1529 | 1530 | The Address extension 1531 | 1532 | +---------------+---------------+---------------+---------------+ 1533 | | sadb_address_len | sadb_address_exttype | 1534 | +---------------+---------------+---------------+---------------+ 1535 | | _address_proto| ..._prefixlen | sadb_address_reserved | 1536 | +---------------+---------------+---------------+---------------+ 1537 | > Some form of 64-bit aligned struct sockaddr goes here. < 1538 | +---------------+---------------+---------------+---------------+ 1539 | 1540 | The Key extension 1541 | 1542 | +---------------+---------------+---------------+---------------+ 1543 | | sadb_key_len | sadb_key_exttype | 1544 | +---------------+---------------+---------------+---------------+ 1545 | | sadb_key_bits | sadb_key_reserved | 1546 | +---------------+---------------+---------------+---------------+ 1547 | > A key, padded to 64-bits, most significant bits to least. > 1548 | +---------------+---------------+---------------+---------------+ 1549 | 1550 | The Identity extension 1551 | 1552 | +---------------+---------------+---------------+---------------+ 1553 | | sadb_ident_len | sadb_ident_exttype | 1554 | +---------------+---------------+---------------+---------------+ 1555 | | sadb_ident_type | sadb_ident_reserved | 1556 | +---------------+---------------+---------------+---------------+ 1557 | | sadb_ident_id | 1558 | | (64 bits) | 1559 | +---------------+---------------+---------------+---------------+ 1560 | > A null-terminated C-string which MUST be padded out for > 1561 | < 64-bit alignment. < 1562 | +---------------+---------------+---------------+---------------+ 1563 | 1564 | 1565 | 1566 | 1567 | 1568 | 1569 | 1570 | McDonald, et. al. Informational [Page 28] 1571 | 1572 | RFC 2367 PF_KEY Key Management API July 1998 1573 | 1574 | 1575 | The Sensitivity extension 1576 | 1577 | +---------------+---------------+---------------+---------------+ 1578 | | sadb_sens_len | sadb_sens_exttype | 1579 | +---------------+---------------+---------------+---------------+ 1580 | | sadb_sens_dpd | 1581 | +---------------+---------------+---------------+---------------+ 1582 | | ...sens_level | ...sens_len |..._integ_level| ..integ_len | 1583 | +---------------+---------------+---------------+---------------+ 1584 | | sadb_sens_reserved | 1585 | +---------------+---------------+---------------+---------------+ 1586 | > The sensitivity bitmap, followed immediately by the < 1587 | < integrity bitmap, each is an array of uint64_t. > 1588 | +---------------+---------------+---------------+---------------+ 1589 | 1590 | The Proposal extension 1591 | 1592 | +---------------+---------------+---------------+---------------+ 1593 | | sadb_prop_len | sadb_prop_exttype | 1594 | +---------------+---------------+---------------+---------------+ 1595 | |...prop_replay | sadb_prop_reserved | 1596 | +---------------+---------------+---------------+---------------+ 1597 | > One or more combinations, specified as follows... < 1598 | +---------------+---------------+---------------+---------------+ 1599 | 1600 | Combination 1601 | +---------------+---------------+---------------+---------------+ 1602 | |sadb_comb_auth |sadb_comb_encr | sadb_comb_flags | 1603 | +---------------+---------------+---------------+---------------+ 1604 | | sadb_comb_auth_minbits | sadb_comb_auth_maxbits | 1605 | +---------------+---------------+---------------+---------------+ 1606 | | sadb_comb_encrypt_minbits | sadb_comb_encrypt_maxbits | 1607 | +---------------+---------------+---------------+---------------+ 1608 | | sadb_comb_reserved | 1609 | +---------------+---------------+---------------+---------------+ 1610 | | sadb_comb_soft_allocations | 1611 | +---------------+---------------+---------------+---------------+ 1612 | | sadb_comb_hard_allocations | 1613 | +---------------+---------------+---------------+---------------+ 1614 | | sadb_comb_soft_bytes | 1615 | | (64 bits) | 1616 | +---------------+---------------+---------------+---------------+ 1617 | | sadb_comb_hard_bytes | 1618 | | (64 bits) | 1619 | +---------------+---------------+---------------+---------------+ 1620 | | sadb_comb_soft_addtime | 1621 | | (64 bits) | 1622 | +---------------+---------------+---------------+---------------+ 1623 | 1624 | 1625 | 1626 | McDonald, et. al. Informational [Page 29] 1627 | 1628 | RFC 2367 PF_KEY Key Management API July 1998 1629 | 1630 | 1631 | +---------------+---------------+---------------+---------------+ 1632 | | sadb_comb_hard_addtime | 1633 | | (64 bits) | 1634 | +---------------+---------------+---------------+---------------+ 1635 | | sadb_comb_soft_usetime | 1636 | | (64 bits) | 1637 | +---------------+---------------+---------------+---------------+ 1638 | | sadb_comb_hard_usetime | 1639 | | (64 bits) | 1640 | +---------------+---------------+---------------+---------------+ 1641 | 1642 | The Supported Algorithms extension 1643 | 1644 | +---------------+---------------+---------------+---------------+ 1645 | | sadb_supported_len | sadb_supported_exttype | 1646 | +---------------+---------------+---------------+---------------+ 1647 | | sadb_supported_reserved | 1648 | +---------------+---------------+---------------+---------------+ 1649 | 1650 | Followed by one or more Algorithm Descriptors 1651 | 1652 | +---------------+---------------+---------------+---------------+ 1653 | | sadb_alg_id | sadb_alg_ivlen| sadb_alg_minbits | 1654 | +---------------+---------------+---------------+---------------+ 1655 | | sadb_alg_maxbits | sadb_alg_reserved | 1656 | +---------------+---------------+---------------+---------------+ 1657 | 1658 | The SPI Range extension 1659 | 1660 | +---------------+---------------+---------------+---------------+ 1661 | | sadb_spirange_len | sadb_spirange_exttype | 1662 | +---------------+---------------+---------------+---------------+ 1663 | | sadb_spirange_min | 1664 | +---------------+---------------+---------------+---------------+ 1665 | | sadb_spirange_max | 1666 | +---------------+---------------+---------------+---------------+ 1667 | | sadb_spirange_reserved | 1668 | +---------------+---------------+---------------+---------------+ 1669 | 1670 | 3 Symbolic Names 1671 | 1672 | This section defines various symbols used with PF_KEY and the 1673 | semantics associated with each symbol. Applications MUST use the 1674 | symbolic names in order to be portable. The numeric definitions 1675 | shown are for illustrative purposes, unless explicitly stated 1676 | otherwise. The numeric definition MAY vary on other systems. The 1677 | symbolic name MUST be kept the same for all conforming 1678 | implementations. 1679 | 1680 | 1681 | 1682 | McDonald, et. al. Informational [Page 30] 1683 | 1684 | RFC 2367 PF_KEY Key Management API July 1998 1685 | 1686 | 1687 | 3.1 Message Types 1688 | 1689 | The following message types are used with PF_KEY. These are defined 1690 | in the file . 1691 | 1692 | #define SADB_RESERVED 0 1693 | #define SADB_GETSPI 1 1694 | #define SADB_UPDATE 2 1695 | #define SADB_ADD 3 1696 | #define SADB_DELETE 4 1697 | #define SADB_GET 5 1698 | #define SADB_ACQUIRE 6 1699 | #define SADB_REGISTER 7 1700 | #define SADB_EXPIRE 8 1701 | #define SADB_FLUSH 9 1702 | 1703 | #define SADB_DUMP 10 /* not used normally */ 1704 | 1705 | #define SADB_MAX 10 1706 | 1707 | Each message has a behavior. A behavior is defined as where the 1708 | initial message travels (e.g. user to kernel), and what subsequent 1709 | actions are expected to take place. Contents of messages are 1710 | illustrated as: 1711 | 1712 | 1713 | 1714 | The SA extension is sometimes used only for its SPI field. If all 1715 | other fields MUST be ignored, this is represented by "SA(*)". 1716 | 1717 | The lifetime extensions are represented with one to three letters 1718 | after the word "lifetime," representing (H)ARD, (S)OFT, and 1719 | (C)URRENT. 1720 | 1721 | The address extensions are represented with one to three letters 1722 | after the word "address," representing (S)RC, (D)ST, (P)ROXY. 1723 | 1724 | NOTE: Some security association types do not use a source 1725 | address for SA identification, where others do. This may 1726 | cause EEXIST errors for some SA types where others do not 1727 | report collisions. It is expected that application 1728 | authors know enough about the underlying security 1729 | association types to understand these differences. 1730 | 1731 | The key extensions are represented with one or two letters after the 1732 | word "key," representing (A)UTH and (E)NCRYPT. 1733 | 1734 | 1735 | 1736 | 1737 | 1738 | McDonald, et. al. Informational [Page 31] 1739 | 1740 | RFC 2367 PF_KEY Key Management API July 1998 1741 | 1742 | 1743 | The identity extensions are represented with one or two letters after 1744 | the word "identity," representing (S)RC and (D)ST. 1745 | 1746 | In the case of an error, only the base header is returned. 1747 | 1748 | Note that any standard error could be returned for any message. 1749 | 1750 | Typically, they will be either one of the errors specifically listed 1751 | in the description for a message or one of the following: 1752 | 1753 | EINVAL Various message improprieties, including SPI ranges 1754 | that are malformed. 1755 | ENOMEM Needed memory was not available. 1756 | ENOBUFS Needed memory was not available. 1757 | EMSGSIZ The message exceeds the maximum length allowed. 1758 | 1759 | 3.1.1 SADB_GETSPI 1760 | 1761 | The SADB_GETSPI message allows a process to obtain a unique SPI value 1762 | for given security association type, source address, and destination 1763 | address. This message followed by an SADB_UPDATE is one way to 1764 | create a security association (SADB_ADD is the other method). The 1765 | process specifies the type in the base header, the source and 1766 | destination address in address extension. If the SADB_GETSPI message 1767 | is in response to a kernel-generated SADB_ACQUIRE, the sadb_msg_seq 1768 | MUST be the same as the SADB_ACQUIRE message. The application may 1769 | also specify the SPI. This is done by having the kernel select 1770 | within a range of SPI values by using the SPI range extension. To 1771 | specify a single SPI value to be verified, the application sets the 1772 | high and low values to be equal. Permitting range specification is 1773 | important because the kernel can allocate an SPI value based on what 1774 | it knows about SPI values already in use. The kernel returns the 1775 | same message with the allocated SPI value stored in the spi field of 1776 | an association extension. The allocate SPI (and destination address) 1777 | refer to a LARVAL security association. An SADB_UPDATE message can 1778 | later be used to add an entry with the requested SPI value. 1779 | 1780 | It is recommended that associations that are created with SADB_GETSPI 1781 | SHOULD be automatically deleted within a fixed amount of time if they 1782 | are not updated by an SADB_UPDATE message. This allows SA storage 1783 | not to get cluttered with larval associations. 1784 | 1785 | The message behavior of the SADB_GETSPI message is: 1786 | 1787 | Send an SADB_GETSPI message from a user process to the kernel. 1788 | 1789 | 1790 | 1791 | 1792 | 1793 | 1794 | McDonald, et. al. Informational [Page 32] 1795 | 1796 | RFC 2367 PF_KEY Key Management API July 1998 1797 | 1798 | 1799 | The kernel returns the SADB_GETSPI message to all listening 1800 | processes. 1801 | 1802 | 1803 | 1804 | Errors: 1805 | 1806 | EEXIST Requested SPI or SPI range is not available or already 1807 | used. 1808 | 1809 | 3.1.2 SADB_UPDATE Message 1810 | 1811 | The SADB_UPDATE message allows a process to update the information in 1812 | an existing Security Association. Since SADB_GETSPI does not allow 1813 | setting of certain parameters, this message is needed to fully form 1814 | the SADB_SASTATE_LARVAL security association created with 1815 | SADB_GETSPI. The format of the update message is a base header, 1816 | followed by an association header and possibly by several extension 1817 | headers. The kernel searches for the security association with the 1818 | same type, spi, source address and destination address specified in 1819 | the message and updates the Security Association information using 1820 | the content of the SADB_UPDATE message. 1821 | 1822 | The kernel MAY disallow SADB_UPDATE to succeed unless the message is 1823 | issued from the same socket that created the security association. 1824 | Such enforcement significantly reduces the chance of accidental 1825 | changes to an in-use security association. Malicious trusted parties 1826 | could still issue an SADB_FLUSH or SADB_DELETE message, but deletion 1827 | of associations is more easily detected and less likely to occur 1828 | accidentally than an erroneous SADB_UPDATE. The counter argument to 1829 | supporting this behavior involves the case where a user-space key 1830 | management application fails and is restarted. The new instance of 1831 | the application will not have the same socket as the creator of the 1832 | security association. 1833 | 1834 | The kernel MUST sanity check all significant values submitted in an 1835 | SADB_UPDATE message before changing the SA in its database and MUST 1836 | return EINVAL if any of the values are invalid. Examples of checks 1837 | that should be performed are DES key parity bits, key length 1838 | checking, checks for keys known to be weak for the specified 1839 | algorithm, and checks for flags or parameters known to be 1840 | incompatible with the specified algorithm. 1841 | 1842 | Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_UPDATE 1843 | message. If the original SA is an SADB_SASTATE_LARVAL SA, then any 1844 | value in the SA may be changed except for the source address, 1845 | destination address, and SPI. If the original SA is an 1846 | SADB_SASTATE_DEAD SA, any attempt to perform an SADB_UPDATE on the SA 1847 | 1848 | 1849 | 1850 | McDonald, et. al. Informational [Page 33] 1851 | 1852 | RFC 2367 PF_KEY Key Management API July 1998 1853 | 1854 | 1855 | MUST return EINVAL. It is not valid for established keying or 1856 | algorithm information to change without the SPI changing, which would 1857 | require creation of a new SA rather than a change to an existing SA. 1858 | Once keying and algorithm information is negotiated, address and 1859 | identity information is fixed for the SA. Therefore, if the original 1860 | SA is an SADB_SASTATE_MATURE or DYING SA, only the sadb_sa_state 1861 | field in the SA header and lifetimes (hard, soft, and current) may be 1862 | changed and any attempt to change other values MUST result in an 1863 | error return of EINVAL. 1864 | 1865 | The message behavior of the SADB_UPDATE message is: 1866 | 1867 | Send an SADB_UPDATE message from a user process to the kernel. 1868 | 1869 | 1871 | 1872 | The kernel returns the SADB_UPDATE message to all listening 1873 | processes. 1874 | 1875 | 1877 | 1878 | 1879 | The keying material is not returned on the message from the kernel to 1880 | listening sockets because listeners might not have the privileges to 1881 | see such keying material. 1882 | 1883 | Errors: 1884 | ESRCH The security association to be updated was not found. 1885 | EINVAL In addition to other possible causes, this error is 1886 | returned if sanity checking on the SA values (such 1887 | as the keys) fails. 1888 | EACCES Insufficient privilege to update entry. The socket 1889 | issuing the SADB_UPDATE is not creator of the entry 1890 | to be updated. 1891 | 1892 | 3.1.3 SADB_ADD 1893 | 1894 | The SADB_ADD message is nearly identical to the SADB_UPDATE message, 1895 | except that it does not require a previous call to SADB_GETSPI. The 1896 | SADB_ADD message is used in manual keying applications, and in other 1897 | cases where the uniqueness of the SPI is known immediately. 1898 | 1899 | An SADB_ADD message is also used when negotiation is finished, and 1900 | the second of a pair of associations is added. The SPI for this 1901 | association was determined by the peer machine. The sadb_msg_seq 1902 | 1903 | 1904 | 1905 | 1906 | McDonald, et. al. Informational [Page 34] 1907 | 1908 | RFC 2367 PF_KEY Key Management API July 1998 1909 | 1910 | 1911 | MUST be set to the value set in a kernel-generated SADB_ACQUIRE so 1912 | that both associations in a pair are bound to the same ACQUIRE 1913 | request. 1914 | 1915 | The kernel MUST sanity check all used fields in the SA submitted in 1916 | an SADB_ADD message before adding the SA to its database and MUST 1917 | return EINVAL if any of the values are invalid. 1918 | 1919 | Only SADB_SASTATE_MATURE SAs may be submitted in an SADB_ADD message. 1920 | SADB_SASTATE_LARVAL SAs are created by SADB_GETSPI and it is not 1921 | sensible to add a new SA in the DYING or SADB_SASTATE_DEAD state. 1922 | Therefore, the sadb_sa_state field of all submitted SAs MUST be 1923 | SADB_SASTATE_MATURE and the kernel MUST return an error if this is 1924 | not true. 1925 | 1926 | The message behavior of the SADB_ADD message is: 1927 | 1928 | Send an SADB_ADD message from a user process to the kernel. 1929 | 1930 | 1932 | 1933 | The kernel returns the SADB_ADD message to all listening 1934 | processes. 1935 | 1936 | 1938 | 1939 | The keying material is not returned on the message from the kernel to 1940 | listening sockets because listeners may not have the privileges to 1941 | see such keying material. 1942 | 1943 | Errors: 1944 | 1945 | EEXIST The security association that was to be added already 1946 | exists. 1947 | EINVAL In addition to other possible causes, this error is 1948 | returned if sanity checking on the SA values (such 1949 | as the keys) fails. 1950 | 1951 | 3.1.4 SADB_DELETE 1952 | 1953 | The SADB_DELETE message causes the kernel to delete a Security 1954 | Association from the key table. The delete message consists of the 1955 | base header followed by the association, and the source and 1956 | destination sockaddrs in the address extension. The kernel deletes 1957 | the security association matching the type, spi, source address, and 1958 | destination address in the message. 1959 | 1960 | 1961 | 1962 | McDonald, et. al. Informational [Page 35] 1963 | 1964 | RFC 2367 PF_KEY Key Management API July 1998 1965 | 1966 | 1967 | The message behavior for SADB_DELETE is as follows: 1968 | 1969 | Send an SADB_DELETE message from a user process to the kernel. 1970 | 1971 | 1972 | 1973 | The kernel returns the SADB_DELETE message to all listening 1974 | processes. 1975 | 1976 | 1977 | 1978 | 3.1.5 SADB_GET 1979 | 1980 | The SADB_GET message allows a process to retrieve a copy of a 1981 | Security Association from the kernel's key table. The get message 1982 | consists of the base header follows by the relevant extension fields. 1983 | The Security Association matching the type, spi, source address, and 1984 | destination address is returned. 1985 | 1986 | The message behavior of the SADB_GET message is: 1987 | 1988 | Send an SADB_GET message from a user process to the kernel. 1989 | 1990 | 1991 | 1992 | The kernel returns the SADB_GET message to the socket that sent 1993 | the SADB_GET message. 1994 | 1995 | 1997 | 1998 | Errors: 1999 | ESRCH The sought security association was not found. 2000 | 2001 | 3.1.6 SADB_ACQUIRE 2002 | 2003 | The SADB_ACQUIRE message is typically sent only by the kernel to key 2004 | socket listeners who have registered their key socket (see 2005 | SADB_REGISTER message). SADB_ACQUIRE messages can be sent by 2006 | application-level consumers of security associations (such as an 2007 | OSPFv2 implementation that uses OSPF security). The SADB_ACQUIRE 2008 | message is a base header along with an address extension, possibly an 2009 | identity extension, and a proposal extension. The proposed situation 2010 | contains a list of desirable algorithms that can be used if the 2011 | algorithms in the base header are not available. The values for the 2012 | fields in the base header and in the security association data which 2013 | follows the base header indicate the properties of the Security 2014 | Association that the listening process should attempt to acquire. If 2015 | 2016 | 2017 | 2018 | McDonald, et. al. Informational [Page 36] 2019 | 2020 | RFC 2367 PF_KEY Key Management API July 1998 2021 | 2022 | 2023 | the message originates from the kernel (i.e. the sadb_msg_pid is 0), 2024 | the sadb_msg_seq number MUST be used by a subsequent SADB_GETSPI and 2025 | SADB_UPDATE, or subsequent SADB_ADD message to bind a security 2026 | association to the request. This avoids the race condition of two 2027 | TCP connections between two IP hosts that each require unique 2028 | associations, and having one steal another's security association. 2029 | The sadb_msg_errno and sadb_msg_state fields should be ignored by the 2030 | listening process. 2031 | 2032 | The SADB_ACQUIRE message is typically triggered by an outbound packet 2033 | that needs security but for which there is no applicable Security 2034 | Association existing in the key table. If the packet can be 2035 | sufficiently protected by more than one algorithm or combination of 2036 | options, the SADB_ACQUIRE message MUST order the preference of 2037 | possibilities in the Proposal extension. 2038 | 2039 | There are three messaging behaviors for SADB_ACQUIRE. The first is 2040 | where the kernel needs a security association (e.g. for IPsec). 2041 | 2042 | The kernel sends an SADB_ACQUIRE message to registered sockets. 2043 | 2044 | 2046 | 2047 | NOTE: The address(SD) extensions MUST have the port fields 2048 | filled in with the port numbers of the session requiring 2049 | keys if appropriate. 2050 | 2051 | The second is when, for some reason, key management fails, it can 2052 | send an ACQUIRE message with the same sadb_msg_seq as the initial 2053 | ACQUIRE with a non-zero errno. 2054 | 2055 | Send an SADB_ACQUIRE to indicate key management failure. 2056 | 2057 | 2058 | 2059 | The third is where an application-layer consumer of security 2060 | associations (e.g. an OSPFv2 or RIPv2 daemon) needs a security 2061 | association. 2062 | 2063 | Send an SADB_ACQUIRE message from a user process to the kernel. 2064 | 2065 | 2067 | 2068 | The kernel returns an SADB_ACQUIRE message to registered 2069 | sockets. 2070 | 2071 | 2072 | 2073 | 2074 | McDonald, et. al. Informational [Page 37] 2075 | 2076 | RFC 2367 PF_KEY Key Management API July 1998 2077 | 2078 | 2079 | 2081 | 2082 | The user-level consumer waits for an SADB_UPDATE or SADB_ADD 2083 | message for its particular type, and then can use that 2084 | association by using SADB_GET messages. 2085 | 2086 | Errors: 2087 | EINVAL Invalid acquire request. 2088 | EPROTONOSUPPORT No KM application has registered with the Key 2089 | Engine as being able to obtain the requested SA type, so 2090 | the requested SA cannot be acquired. 2091 | 2092 | 3.1.7 SADB_REGISTER 2093 | 2094 | The SADB_REGISTER message allows an application to register its key 2095 | socket as able to acquire new security associations for the kernel. 2096 | SADB_REGISTER allows a socket to receive SADB_ACQUIRE messages for 2097 | the type of security association specified in sadb_msg_satype. The 2098 | application specifies the type of security association that it can 2099 | acquire for the kernel in the type field of its register message. If 2100 | an application can acquire multiple types of security association, it 2101 | MUST register each type in a separate message. Only the base header 2102 | is needed for the register message. Key management applications MAY 2103 | register for a type not known to the kernel, because the consumer may 2104 | be in user-space (e.g. OSPFv2 security). 2105 | 2106 | The reply of the SADB_REGISTER message contains a supported algorithm 2107 | extension. That field contains an array of supported algorithms, one 2108 | per octet. This allows key management applications to know what 2109 | algorithm are supported by the kernel. 2110 | 2111 | In an environment where algorithms can be dynamically loaded and 2112 | unloaded, an asynchronous SADB_REGISTER reply MAY be generated. The 2113 | list of supported algorithms MUST be a complete list, so the 2114 | application can make note of omissions or additions. 2115 | 2116 | The messaging behavior of the SADB_REGISTER message is: 2117 | 2118 | Send an SADB_REGISTER message from a user process to the kernel. 2119 | 2120 | 2121 | 2122 | The kernel returns an SADB_REGISTER message to registered 2123 | sockets, with algorithm types supported by the kernel being 2124 | indicated in the supported algorithms field. 2125 | 2126 | 2127 | 2128 | 2129 | 2130 | McDonald, et. al. Informational [Page 38] 2131 | 2132 | RFC 2367 PF_KEY Key Management API July 1998 2133 | 2134 | 2135 | NOTE: This message may arrive asynchronously due to an 2136 | algorithm being loaded or unloaded into a dynamically 2137 | linked kernel. 2138 | 2139 | 2140 | 2141 | 3.1.8 SADB_EXPIRE Message 2142 | 2143 | The operating system kernel is responsible for tracking SA 2144 | expirations for security protocols that are implemented inside the 2145 | kernel. If the soft limit or hard limit of a Security Association 2146 | has expired for a security protocol implemented inside the kernel, 2147 | then the kernel MUST issue an SADB_EXPIRE message to all key socket 2148 | listeners. If the soft limit or hard limit of a Security Association 2149 | for a user-level security protocol has expired, the user-level 2150 | protocol SHOULD issue an SADB_EXPIRE message. 2151 | 2152 | The base header will contain the security association information 2153 | followed by the source sockaddr, destination sockaddr, (and, if 2154 | present, internal sockaddr,) (and, if present, one or both 2155 | compartment bitmaps). 2156 | 2157 | The lifetime extension of an SADB_EXPIRE message is important to 2158 | indicate which lifetime expired. If a HARD lifetime extension is 2159 | included, it indicates that the HARD lifetime expired. This means 2160 | the association MAY be deleted already from the SADB. If a SOFT 2161 | lifetime extension is included, it indicates that the SOFT lifetime 2162 | expired. The CURRENT lifetime extension will indicate the current 2163 | status, and comparisons to the HARD or SOFT lifetime will indicate 2164 | which limit was reached. HARD lifetimes MUST take precedence over 2165 | SOFT lifetimes, meaning if the HARD and SOFT lifetimes are the same, 2166 | the HARD lifetime will appear on the EXPIRE message. The 2167 | pathological case of HARD lifetimes being shorter than SOFT lifetimes 2168 | is handled such that the SOFT lifetime will never expire. 2169 | 2170 | The messaging behavior of the SADB_EXPIRE message is: 2171 | 2172 | The kernel sends an SADB_EXPIRE message to all listeners when 2173 | the soft limit of a security association has been expired. 2174 | 2175 | 2176 | 2177 | Note that the SADB_EXPIRE message is ONLY sent by the kernel to the 2178 | KMd. It is a one-way informational message that does not have a 2179 | reply. 2180 | 2181 | 2182 | 2183 | 2184 | 2185 | 2186 | McDonald, et. al. Informational [Page 39] 2187 | 2188 | RFC 2367 PF_KEY Key Management API July 1998 2189 | 2190 | 2191 | 3.1.9 SADB_FLUSH 2192 | 2193 | The SADB_FLUSH message causes the kernel to delete all entries in its 2194 | key table for a certain sadb_msg_satype. Only the base header is 2195 | required for a flush message. If sadb_msg_satype is filled in with a 2196 | specific value, only associations of that type are deleted. If it is 2197 | filled in with SADB_SATYPE_UNSPEC, ALL associations are deleted. 2198 | 2199 | The messaging behavior for SADB_FLUSH is: 2200 | 2201 | Send an SADB_FLUSH message from a user process to the kernel. 2202 | 2203 | 2204 | 2205 | The kernel will return an SADB_FLUSH message to all listening 2206 | sockets. 2207 | 2208 | 2209 | 2210 | The reply message happens only after the actual flushing 2211 | of security associations has been attempted. 2212 | 2213 | 3.1.10 SADB_DUMP 2214 | 2215 | The SADB_DUMP message causes the kernel to dump the operating 2216 | system's entire Key Table to the requesting key socket. As in 2217 | SADB_FLUSH, if a sadb_msg_satype value is in the message, only 2218 | associations of that type will be dumped. If SADB_SATYPE_UNSPEC is 2219 | specified, all associations will be dumped. Each Security Association 2220 | is returned in its own SADB_DUMP message. A SADB_DUMP message with a 2221 | sadb_seq field of zero indicates the end of the dump transaction. The 2222 | dump message is used for debugging purposes only and is not intended 2223 | for production use. 2224 | 2225 | Support for the dump message MAY be discontinued in future versions 2226 | of PF_KEY. Key management applications MUST NOT depend on this 2227 | message for basic operation. 2228 | 2229 | The messaging behavior for SADB_DUMP is: 2230 | 2231 | Send an SADB_DUMP message from a user process to the kernel. 2232 | 2233 | 2234 | 2235 | Several SADB_DUMP messages will return from the kernel to the 2236 | sending socket. 2237 | 2238 | 2239 | 2240 | 2241 | 2242 | McDonald, et. al. Informational [Page 40] 2243 | 2244 | RFC 2367 PF_KEY Key Management API July 1998 2245 | 2246 | 2247 | 2249 | 2250 | 3.2 Security Association Flags 2251 | 2252 | The Security Association's flags are a bitmask field. These flags 2253 | also appear in a combination that is part of a PROPOSAL extension. 2254 | The related symbolic definitions below should be used in order that 2255 | applications will be portable: 2256 | 2257 | #define SADB_SAFLAGS_PFS 1 /* perfect forward secrecy */ 2258 | 2259 | The SADB_SAFLAGS_PFS flag indicates to key management that this 2260 | association should have perfect forward secrecy in its key. (In 2261 | other words, any given session key cannot be determined by 2262 | cryptanalysis of previous session keys or some master key.) 2263 | 2264 | 3.3 Security Association States 2265 | 2266 | The security association state field is an integer that describes the 2267 | states of a security association. They are: 2268 | 2269 | #define SADB_SASTATE_LARVAL 0 2270 | #define SADB_SASTATE_MATURE 1 2271 | #define SADB_SASTATE_DYING 2 2272 | #define SADB_SASTATE_DEAD 3 2273 | 2274 | #define SADB_SASTATE_MAX 3 2275 | 2276 | A SADB_SASTATE_LARVAL security association is one that was created by 2277 | the SADB_GETSPI message. A SADB_SASTATE_MATURE association is one 2278 | that was updated with the SADB_UPDATE message or added with the 2279 | SADB_ADD message. A DYING association is one whose soft lifetime has 2280 | expired. A SADB_SASTATE_DEAD association is one whose hard lifetime 2281 | has expired, but hasn't been reaped by system garbage collection. If 2282 | a consumer of security associations has to extend an association 2283 | beyond its normal lifetime (e.g. OSPF Security) it MUST only set the 2284 | soft lifetime for an association. 2285 | 2286 | 3.4 Security Association Types 2287 | 2288 | This defines the type of Security Association in this message. The 2289 | symbolic names are always the same, even on different 2290 | implementations. Applications SHOULD use the symbolic name in order 2291 | to have maximum portability across different implementations. These 2292 | are defined in the file . 2293 | 2294 | 2295 | 2296 | 2297 | 2298 | McDonald, et. al. Informational [Page 41] 2299 | 2300 | RFC 2367 PF_KEY Key Management API July 1998 2301 | 2302 | 2303 | #define SADB_SATYPE_UNSPEC 0 2304 | 2305 | #define SADB_SATYPE_AH 2 /* RFC-1826 */ 2306 | #define SADB_SATYPE_ESP 3 /* RFC-1827 */ 2307 | 2308 | #define SADB_SATYPE_RSVP 5 /* RSVP Authentication */ 2309 | #define SADB_SATYPE_OSPFV2 6 /* OSPFv2 Authentication */ 2310 | #define SADB_SATYPE_RIPV2 7 /* RIPv2 Authentication */ 2311 | #define SADB_SATYPE_MIP 8 /* Mobile IP Auth. */ 2312 | 2313 | #define SADB_SATYPE_MAX 8 2314 | 2315 | SADB_SATYPE_UNSPEC is defined for completeness and means no specific 2316 | type of security association. This type is never used with PF_KEY 2317 | SAs. 2318 | 2319 | SADB_SATYPE_AH is for the IP Authentication Header [Atk95b]. 2320 | 2321 | SADB_SATYPE_ESP is for the IP Encapsulating Security Payload 2322 | [Atk95c]. 2323 | 2324 | SADB_SATYPE_RSVP is for the RSVP Integrity Object. 2325 | 2326 | SADB_SATYPE_OSPFV2 is for OSPFv2 Cryptographic authentication 2327 | [Moy98]. 2328 | 2329 | SADB_SATYPE_RIPV2 is for RIPv2 Cryptographic authentication [BA97]. 2330 | 2331 | SADB_SATYPE_MIP is for Mobile IP's authentication extensions [Per97]. 2332 | 2333 | SADB_SATYPE_MAX is always set to the highest valid numeric value. 2334 | 2335 | 3.5 Algorithm Types 2336 | 2337 | The algorithm type is interpreted in the context of the Security 2338 | Association type defined above. The numeric value might vary between 2339 | implementations, but the symbolic name MUST NOT vary between 2340 | implementations. Applications should use the symbolic name in order 2341 | to have maximum portability to various implementations. 2342 | 2343 | Some of the algorithm types defined below might not be standardized 2344 | or might be deprecated in the future. To obtain an assignment for a 2345 | symbolic name, contact the authors. 2346 | 2347 | The symbols below are defined in . 2348 | 2349 | 2350 | 2351 | 2352 | 2353 | 2354 | McDonald, et. al. Informational [Page 42] 2355 | 2356 | RFC 2367 PF_KEY Key Management API July 1998 2357 | 2358 | 2359 | /* Authentication algorithms */ 2360 | #define SADB_AALG_NONE 0 2361 | #define SADB_AALG_MD5HMAC 2 2362 | #define SADB_AALG_SHA1HMAC 3 2363 | #define SADB_AALG_MAX 3 2364 | 2365 | /* Encryption algorithms */ 2366 | #define SADB_EALG_NONE 0 2367 | #define SADB_EALG_DESCBC 2 2368 | #define SADB_EALG_3DESCBC 3 2369 | #define SADB_EALG_NULL 11 2370 | #define SADB_EALG_MAX 11 2371 | 2372 | The algorithm for SADB_AALG_MD5_HMAC is defined in [MG98a]. The 2373 | algorithm for SADB_AALG_SHA1HMAC is defined in [MG98b]. The 2374 | algorithm for SADB_EALG_DESCBC is defined in [MD98]. SADB_EALG_NULL 2375 | is the NULL encryption algorithm, defined in [GK98]. The 2376 | SADB_EALG_NONE value is not to be used in any security association 2377 | except those which have no possible encryption algorithm in them 2378 | (e.g. IPsec AH). 2379 | 2380 | 3.6 Extension Header Values 2381 | 2382 | To briefly recap the extension header values: 2383 | 2384 | #define SADB_EXT_RESERVED 0 2385 | #define SADB_EXT_SA 1 2386 | #define SADB_EXT_LIFETIME_CURRENT 2 2387 | #define SADB_EXT_LIFETIME_HARD 3 2388 | #define SADB_EXT_LIFETIME_SOFT 4 2389 | #define SADB_EXT_ADDRESS_SRC 5 2390 | #define SADB_EXT_ADDRESS_DST 6 2391 | #define SADB_EXT_ADDRESS_PROXY 7 2392 | #define SADB_EXT_KEY_AUTH 8 2393 | #define SADB_EXT_KEY_ENCRYPT 9 2394 | #define SADB_EXT_IDENTITY_SRC 10 2395 | #define SADB_EXT_IDENTITY_DST 11 2396 | #define SADB_EXT_SENSITIVITY 12 2397 | #define SADB_EXT_PROPOSAL 13 2398 | #define SADB_EXT_SUPPORTED_AUTH 14 2399 | #define SADB_EXT_SUPPORTED_ENCRYPT 15 2400 | #define SADB_EXT_SPIRANGE 16 2401 | 2402 | #define SADB_EXT_MAX 16 2403 | 2404 | 2405 | 2406 | 2407 | 2408 | 2409 | 2410 | McDonald, et. al. Informational [Page 43] 2411 | 2412 | RFC 2367 PF_KEY Key Management API July 1998 2413 | 2414 | 2415 | 3.7 Identity Extension Values 2416 | 2417 | Each identity can have a certain type. 2418 | 2419 | #define SADB_IDENTTYPE_RESERVED 0 2420 | #define SADB_IDENTTYPE_PREFIX 1 2421 | #define SADB_IDENTTYPE_FQDN 2 2422 | #define SADB_IDENTTYPE_USERFQDN 3 2423 | 2424 | #define SADB_IDENTTYPE_MAX 3 2425 | 2426 | The PREFIX identity string consists of a network address followed by a 2427 | forward slash and a prefix length. The network address is in a 2428 | printable numeric form appropriate for the protocol family. The 2429 | prefix length is a decimal number greater than or equal to zero and 2430 | less than the number of bits in the network address. It indicates the 2431 | number of bits in the network address that are significant; all bits 2432 | in the network address that are not significant MUST be set to zero. 2433 | Note that implementations MUST parse the contents of the printable 2434 | address into a binary form for comparison purposes because multiple 2435 | printable strings are valid representations of the same address in 2436 | many protocol families (for example, some allow leading zeros and some 2437 | have letters that are case insensitive). Examples of PREFIX identities 2438 | are "199.33.248.64/27" and "3ffe::1/128". If the source or destination 2439 | identity is a PREFIX identity, the source or destination address for 2440 | the SA (respectively) MUST be within that prefix. The sadb_ident_id 2441 | field is zeroed for these identity types. 2442 | 2443 | The FQDN identity string contains a fully qualified domain name. An 2444 | example FQDN identity is "ministry-of-truth.inner.net". The 2445 | sadb_ident_id field is zeroed for these identity types. 2446 | 2447 | The UserFQDN identity consists of a text string in the format commonly 2448 | used for Internet-standard electronic mail. The syntax is the text 2449 | username, followed by the "@" character, followed in turn by the 2450 | appropriate fully qualified domain name. This identity specifies both 2451 | a username and an associated FQDN. There is no requirement that this 2452 | string specify a mailbox valid for SMTP or other electronic mail 2453 | use. This identity is useful with protocols supporting user-oriented 2454 | keying. It is a convenient identity form because the DNS Security 2455 | extensions can be used to distribute signed public key values by 2456 | associating KEY and SIG records with an appropriate MB DNS record. An 2457 | example UserFQDN identity is "julia@ministry-of-love.inner.net". The 2458 | sadb_ident_id field is used to contain a POSIX user id in the absence 2459 | of an identity string itself so that a user-level application can use 2460 | the getpwuid{,_r}() routine to obtain a textual user login id. If a 2461 | string is present, it SHOULD match the numeric value in the 2462 | sadb_ident_id field. If it does not match, the string SHOULD override 2463 | 2464 | 2465 | 2466 | McDonald, et. al. Informational [Page 44] 2467 | 2468 | RFC 2367 PF_KEY Key Management API July 1998 2469 | 2470 | 2471 | the numeric value. 2472 | 2473 | 3.8 Sensitivity Extension Values 2474 | 2475 | The only field currently defined in the sensitivity extension is the 2476 | sadb_sens_dpd, which represents the data protection domain. The other 2477 | data in the sensitivity extension is based off the sadb_sens_dpd 2478 | value. 2479 | 2480 | The DP/DOI is defined to be the same as the "Labeled Domain Identifier 2481 | Value" of the IP Security DOI specification [Pip98]. As noted in that 2482 | specification, values in the range 0x80000000 to 0xffffffff 2483 | (inclusive) are reserved for private use and values in the range 2484 | 0x00000001 through 0x7fffffff are assigned by IANA. The all-zeros 2485 | DP/DOI value is permanently reserved to mean that "no DP/DOI is in 2486 | use". 2487 | 2488 | 3.9 Proposal Extension Values 2489 | 2490 | These are already mentioned in the Algorithm Types and Security 2491 | Association Flags sections. 2492 | 2493 | 4 Future Directions 2494 | 2495 | While the current specification for the Sensitivity and Integrity 2496 | Labels is believed to be general enough, if a case should arise that 2497 | can't work with the current specification then this might cause a 2498 | change in a future version of PF_KEY. 2499 | 2500 | Similarly, PF_KEY might need extensions to work with other kinds of 2501 | Security Associations in future. It is strongly desirable for such 2502 | extensions to be made in a backwards-compatible manner should they be 2503 | needed. 2504 | 2505 | When more experience is gained with certificate management, it is 2506 | possible that the IDENTITY extension will have to be revisited to 2507 | allow a finer grained selection of certificate identities. 2508 | 2509 | 5. Examples 2510 | 2511 | The following examples illustrate how PF_KEY is used. The first 2512 | example is an IP Security example, where the consumer of the security 2513 | associations is inside an operating system kernel. The second example 2514 | is an OSPF Security example, which illustrates a user-level consumer 2515 | of security associations. The third example covers things not 2516 | mentioned by the first two examples. A real system may closely 2517 | conform to one of these examples, or take parts of them. These 2518 | examples are purely illustrative, and are not intended to mandate a 2519 | 2520 | 2521 | 2522 | McDonald, et. al. Informational [Page 45] 2523 | 2524 | RFC 2367 PF_KEY Key Management API July 1998 2525 | 2526 | 2527 | particular implementation method. 2528 | 2529 | 5.1 Simple IP Security Example 2530 | 2531 | +---------------+ +-------------+ 2532 | |Key Mgmt Daemon| | Application | 2533 | +---------------+ +-------------+ 2534 | | | / 2535 | | | / 2536 | | | | Applications 2537 | ======[PF_KEY]====[PF_INET]========================== 2538 | | | | OS Kernel 2539 | +------------+ +-----------------+ 2540 | | Key Engine | | TCP/IP, | 2541 | | or SADB |---| including IPsec | 2542 | +------------+ | | 2543 | +-----------------+ 2544 | 2545 | When the Key Management daemon (KMd) begins. It must tell PF_KEY 2546 | that it is willing to accept message for the two IPsec services, AH 2547 | and ESP. It does this by sending down two SADB_REGISTER messages. 2548 | 2549 | KMd->Kernel: SADB_REGISTER for ESP 2550 | Kernel->Registered: SADB_REGISTER for ESP, Supported Algorithms 2551 | KMd->Kernel: SADB_REGISTER for AH 2552 | Kernel->Registered: SADB_REGISTER for AH, Supported Algorithms 2553 | 2554 | Each REGISTER message will cause a reply to go to all PF_KEY sockets 2555 | registered for ESP and AH respectively (including the requester). 2556 | 2557 | Assume that no security associations currently exist for IPsec to 2558 | use. Consider when a network application begins transmitting data 2559 | (e.g. a TCP SYN). Because of policy, or the application's request, 2560 | the kernel IPsec module needs an AH security association for this 2561 | data. Since there is not one present, the following message is 2562 | generated: 2563 | 2564 | Kernel->Registered: SADB_ACQUIRE for AH, addrs, ID, sens, 2565 | proposals 2566 | 2567 | The KMd reads the ACQUIRE message, especially the sadb_msg_seq 2568 | number. Before it begins the negotiation, it sends down an 2569 | SADB_GETSPI message with the sadb_msg_seq number equal to the one 2570 | received in the ACQUIRE. The kernel returns the results of the 2571 | GETSPI to all listening sockets. 2572 | 2573 | KMd->Kernel: SADB_GETSPI for AH, addr, SPI range 2574 | Kernel->All: SADB_GETSPI for AH, assoc, addrs 2575 | 2576 | 2577 | 2578 | McDonald, et. al. Informational [Page 46] 2579 | 2580 | RFC 2367 PF_KEY Key Management API July 1998 2581 | 2582 | 2583 | The KMd may perform a second GETSPI operation if it needs both 2584 | directions of IPsec SPI values. Now that the KMd has an SPI for at 2585 | least one of the security associations, it begins negotiation. After 2586 | deriving keying material, and negotiating other parameters, it sends 2587 | down one (or more) SADB_UPDATE messages with the same value in 2588 | sadb_msg_seq. 2589 | 2590 | If a KMd has any error at all during its negotiation, it can send 2591 | down: 2592 | 2593 | KMd->Kernel: SADB_ACQUIRE for AH, assoc (with an error) 2594 | Kernel->All: SADB_ACQUIRE for AH, assoc (same error) 2595 | 2596 | but if it succeeds, it can instead: 2597 | 2598 | KMd->Kernel: SADB_UPDATE for AH, assoc, addrs, keys, 2599 | 2600 | Kernel->All: SADB_UPDATE for AH, assoc, addrs, 2601 | 2602 | The results of the UPDATE (minus the actual keys) are sent to all 2603 | listening sockets. If only one SPI value was determined locally, the 2604 | other SPI (since IPsec SAs are unidirectional) must be added with an 2605 | SADB_ADD message. 2606 | 2607 | KMd->Kernel: SADB_ADD for AH, assoc, addrs, keys, 2608 | Kernel->All: SADB_ADD for AH, assoc, addrs, 2609 | 2610 | If one of the extensions passed down was a Lifetime extension, it is 2611 | possible at some point an SADB_EXPIRE message will arrive when one of 2612 | the lifetimes has expired. 2613 | 2614 | Kernel->All: SADB_EXPIRE for AH, assoc, addrs, 2615 | Hard or Soft, Current, 2616 | 2617 | The KMd can use this as a clue to begin negotiation, or, if it has 2618 | some say in policy, send an SADB_UPDATE down with a lifetime 2619 | extension. 2620 | 2621 | 5.2 Proxy IP Security Example 2622 | 2623 | Many people are interested in using IP Security in a "proxy" or 2624 | "firewall" configuration in which an intermediate system provides 2625 | security services for "inside" hosts. In these environments, the 2626 | intermediate systems can use PF_KEY to communicate with key 2627 | management applications almost exactly as they would if they were the 2628 | actual endpoints. The messaging behavior of PF_KEY in these cases is 2629 | exactly the same as the previous example, but the address information 2630 | is slightly different. 2631 | 2632 | 2633 | 2634 | McDonald, et. al. Informational [Page 47] 2635 | 2636 | RFC 2367 PF_KEY Key Management API July 1998 2637 | 2638 | 2639 | Consider this case: 2640 | 2641 | A ========= B --------- C 2642 | 2643 | Key: 2644 | A "outside" host that implements IPsec 2645 | B "firewall" that implements IPsec 2646 | C "inside" host that does not implement IPsec 2647 | 2648 | === IP_{A<->B} ESP [ IP_{A<->C} ULP ] 2649 | --- IP_{A<->C} ULP 2650 | 2651 | A is a single system that wishes to communicate with the "inside" 2652 | system C. B is a "firewall" between C and the outside world that 2653 | will do ESP and tunneling on C's behalf. A discovers that it needs 2654 | to send traffic to C via B through methods not described here (Use of 2655 | the DNS' KX record might be one method for discovering this). 2656 | 2657 | For packets that flow from left to right, A and B need an IPsec 2658 | Security Association with: 2659 | 2660 | SA type of ESP tunnel-mode 2661 | Source Identity that dominates A (e.g. A's address) 2662 | Destination Identity that dominates B (e.g. B's address) 2663 | Source Address of A 2664 | Destination Address of B 2665 | 2666 | For packets to flow from right to left, A and B need an IPsec 2667 | Security Association with: 2668 | 2669 | SA type of ESP tunnel-mode 2670 | Source Identity that dominates C 2671 | Destination Identity that dominates A 2672 | Source Address of B 2673 | Destination Address of A 2674 | Proxy Address of C 2675 | 2676 | For this second SA (for packets flowing from C towards A), node A 2677 | MUST verify that the inner source address is dominated by the Source 2678 | Identity for the SA used with those packets. If node A does not do 2679 | this, an adversary could forge packets with an arbitrary Source 2680 | Identity and defeat the packet origin protections provided by IPsec. 2681 | 2682 | Now consider a slightly more complex case: 2683 | 2684 | A_1 --| |-- D_1 2685 | |--- B ====== C ---| 2686 | A_2 --| |-- D_2 2687 | 2688 | 2689 | 2690 | McDonald, et. al. Informational [Page 48] 2691 | 2692 | RFC 2367 PF_KEY Key Management API July 1998 2693 | 2694 | 2695 | Key: 2696 | A_n "inside" host on net 1 that does not do IPsec. 2697 | B "firewall" for net 1 that supports IPsec. 2698 | C "firewall" for net 2 that supports IPsec. 2699 | D_n "inside" host on net 2 that does not do IPsec. 2700 | === IP_{B<->C} ESP [ IP_{A<->C} ULP ] 2701 | --- IP_{A<->C} ULP 2702 | 2703 | For A_1 to send a packet to D_1, B and C need an SA with: 2704 | 2705 | SA Type of ESP 2706 | Source Identity that dominates A_1 2707 | Destination Identity that dominates C 2708 | Source Address of B 2709 | Destination Address of C 2710 | Proxy Address of A_1 2711 | 2712 | For D_1 to send a packet to A_1, C and B need an SA with: 2713 | SA Type of ESP Tunnel-mode 2714 | Source Identity that dominates D_1 2715 | Destination Identity that dominates B 2716 | Source Address of C 2717 | Destination Address of B 2718 | Proxy Address of D_1 2719 | 2720 | Note that A_2 and D_2 could be substituted for A_1 and D_1 2721 | (respectively) here; the association of an SA with a particular pair 2722 | of ends or group of those pairs is a policy decision on B and/or C 2723 | and not necessarily a function of key management. The same check of 2724 | the Source Identity against the inner source IP address MUST also be 2725 | performed in this case for the same reason. 2726 | 2727 | For a more detailed discussion of the use of IP Security in complex 2728 | cases, please see [Atk97]. 2729 | 2730 | NOTE: The notion of identity domination might be unfamiliar. Let H 2731 | represent some node. Let Hn represent H's fully qualified domain 2732 | name. Let Ha represent the IP address of H. Let Hs represent the IP 2733 | subnet containing Ha. Let Hd represent a fully qualified domain 2734 | name that is a parent of the fully qualified domain name of H. Let 2735 | M be a UserFQDN identity that whose right-hand part is Hn or Ha. 2736 | 2737 | Any of M, Hn, Ha, Hs, and Hd is considered to dominate H in the 2738 | example above. Hs dominates any node having an IP address within 2739 | the IP address range represented by Hs. Hd dominates any node 2740 | having a fully qualified domain name within underneath Hd. 2741 | 2742 | 2743 | 2744 | 2745 | 2746 | McDonald, et. al. Informational [Page 49] 2747 | 2748 | RFC 2367 PF_KEY Key Management API July 1998 2749 | 2750 | 2751 | 5.3 OSPF Security Example 2752 | 2753 | +---------------+ +-------------+ 2754 | |Key Mgmt Daemon| | OSPF daemon | 2755 | +---------------+ +-------------+ 2756 | | | / / | 2757 | | /------|----+ / | 2758 | | / | +---+ | Applications 2759 | ======[PF_KEY]====[PF_INET]===========[PF_ROUTE]================ 2760 | | | | | OS Kernel 2761 | +------------+ +-----------------+ +---------+ 2762 | | Key Engine | | TCP/IP, | | Routing | 2763 | | or SADB |---| including IPsec |--| Table | 2764 | +------------+ | | +---------+ 2765 | +-----------------+ 2766 | 2767 | As in the previous examples, the KMd registers itself with the Key 2768 | Engine via PF_KEY. Even though the consumer of the security 2769 | associations is in user-space, the PF_KEY and Key Engine 2770 | implementation knows enough to store SAs and to relay messages. 2771 | 2772 | When the OSPF daemon needs to communicate securely with its peers, it 2773 | would perform an SADB_GET message and retrieve the appropriate 2774 | association: 2775 | 2776 | OSPFd->Kernel: SADB_GET of OSPF, assoc, addrs 2777 | Kernel->OSPFd: SADB_GET of OSPF, assoc, addrs, keys, 2778 | 2779 | If this GET fails, the OSPFd may need to acquire a new security 2780 | association. This interaction is as follows: 2781 | 2782 | OSPFd->Kernel: SADB_ACQUIRE of OSPF, addrs, 2783 | proposal 2784 | Kernel->Registered: SADB_ACQUIRE of OSPF, 2785 | 2786 | The KMd sees this and performs actions similar to the previous 2787 | example. One difference, however, is that when the UPDATE message 2788 | comes back, the OSPFd will then perform a GET of the updated SA to 2789 | retrieve all of its parameters. 2790 | 2791 | 5.4 Miscellaneous 2792 | 2793 | Some messages work well only in system maintenance programs, for 2794 | debugging, or for auditing. In a system panic situation, such as a 2795 | detected compromise, an SADB_FLUSH message should be issued for a 2796 | particular SA type, or for ALL SA types. 2797 | 2798 | 2799 | 2800 | 2801 | 2802 | McDonald, et. al. Informational [Page 50] 2803 | 2804 | RFC 2367 PF_KEY Key Management API July 1998 2805 | 2806 | 2807 | Program->Kernel: SADB_FLUSH for ALL 2808 | 2809 | Kernel->All: SADB_FLUSH for ALL 2810 | 2811 | Some SAs may need to be explicitly deleted, either by a KMd, or by a 2812 | system maintenance program. 2813 | 2814 | Program->Kernel: SADB_DELETE for AH, association, addrs 2815 | Kernel->All: SADB_DELETE for AH, association, addrs 2816 | 2817 | Common usage of the SADB_DUMP message is discouraged. For debugging 2818 | purposes, however, it can be quite useful. The output of a DUMP 2819 | message should be read quickly, in order to avoid socket buffer 2820 | overflows. 2821 | 2822 | Program->Kernel: SADB_DUMP for ESP 2823 | Kernel->Program: SADB_DUMP for ESP, association, 2824 | Kernel->Program: SADB_DUMP for ESP, association, 2825 | Kernel->Program: SADB_DUMP for ESP, association, 2826 | 2827 | 2828 | 6 Security Considerations 2829 | 2830 | This memo discusses a method for creating, reading, modifying, and 2831 | deleting Security Associations from an operating system. Only 2832 | trusted, privileged users and processes should be able to perform any 2833 | of these operations. It is unclear whether this mechanism provides 2834 | any security when used with operating systems not having the concept 2835 | of a trusted, privileged user. 2836 | 2837 | If an unprivileged user is able to perform any of these operations, 2838 | then the operating system cannot actually provide the related 2839 | security services. If an adversary knows the keys and algorithms in 2840 | use, then cryptography cannot provide any form of protection. 2841 | 2842 | This mechanism is not a panacea, but it does provide an important 2843 | operating system component that can be useful in creating a secure 2844 | internetwork. 2845 | 2846 | Users need to understand that the quality of the security provided by 2847 | an implementation of this specification depends completely upon the 2848 | overall security of the operating system, the correctness of the 2849 | PF_KEY implementation, and upon the security and correctness of the 2850 | applications that connect to PF_KEY. It is appropriate to use high 2851 | assurance development techniques when implementing PF_KEY and the 2852 | related security association components of the operating system. 2853 | 2854 | 2855 | 2856 | 2857 | 2858 | McDonald, et. al. Informational [Page 51] 2859 | 2860 | RFC 2367 PF_KEY Key Management API July 1998 2861 | 2862 | 2863 | Acknowledgments 2864 | 2865 | The authors of this document are listed primarily in alphabetical 2866 | order. Randall Atkinson and Ron Lee provided useful feedback on 2867 | earlier versions of this document. 2868 | 2869 | At one time or other, all of the authors worked at the Center for 2870 | High Assurance Computer Systems at the U.S. Naval Research 2871 | Laboratory. This work was sponsored by the Information Security 2872 | Program Office (PMW-161), U.S. Space and Naval Warfare Systems 2873 | Command (SPAWAR) and the Computing Systems Technology Office, Defense 2874 | Advanced Research Projects Agency (DARPA/CSTO). We really appreciate 2875 | their sponsorship of our efforts and their continued support of 2876 | PF_KEY development. Without that support, PF_KEY would not exist. 2877 | 2878 | The "CONFORMANCE and COMPLIANCE" wording was taken from [MSST98]. 2879 | 2880 | Finally, the authors would like to thank those who sent in comments 2881 | and questions on the various iterations of this document. This 2882 | specification and implementations of it are discussed on the PF_KEY 2883 | mailing list. If you would like to be added to this list, send a note 2884 | to . 2885 | 2886 | References 2887 | 2888 | [AMPMC96] Randall J. Atkinson, Daniel L. McDonald, Bao G. Phan, Craig 2889 | W. Metz, and Kenneth C. Chin, "Implementation of IPv6 in 4.4-Lite 2890 | BSD", Proceedings of the 1996 USENIX Conference, San Diego, CA, 2891 | January 1996, USENIX Association. 2892 | 2893 | [Atk95a] Atkinson, R., "IP Security Architecture", RFC 1825, August 2894 | 1995. 2895 | 2896 | [Atk95b] Atkinson, R., "IP Authentication Header", RFC 1826, August 2897 | 1995. 2898 | 2899 | [Atk95c] Atkinson, R., "IP Encapsulating Security Payload", RFC 1827, 2900 | August 1995. 2901 | 2902 | [Atk97] Atkinson, R., "Key Exchange Delegation Record for the Domain 2903 | Name System", RFC 2230, October 1997. 2904 | 2905 | [BA97] Baker, F., and R. Atkinson, "RIP-2 MD5 Authentication", RFC 2906 | 2082, January 1997. 2907 | 2908 | [Biba77] K. J. Biba, "Integrity Considerations for Secure Computer 2909 | Systems", MTR-3153, The MITRE Corporation, June 1975; ESD-TR-76-372, 2910 | April 1977. 2911 | 2912 | 2913 | 2914 | McDonald, et. al. Informational [Page 52] 2915 | 2916 | RFC 2367 PF_KEY Key Management API July 1998 2917 | 2918 | 2919 | [BL74] D. Elliot Bell and Leonard J. LaPadula, "Secure Computer 2920 | Systems: Unified Exposition and Multics Interpretation", MTR 2997, 2921 | The MITRE Corporation, April 1974. (AD/A 020 445) 2922 | 2923 | [Bra97] Bradner, S., "Key words for use in RFCs to Indicate 2924 | Requirement Levels", BCP 14, RFC 2119, March 1997. 2925 | 2926 | [CW87] D. D. Clark and D. R. Wilson, "A Comparison of Commercial and 2927 | Military Computer Security Policies", Proceedings of the 1987 2928 | Symposium on Security and Privacy, pp. 184-195, IEEE Computer 2929 | Society, Washington, D.C., 1987. 2930 | 2931 | [DIA] US Defense Intelligence Agency (DIA), "Compartmented Mode 2932 | Workstation Specification", Technical Report DDS-2600-6243-87. 2933 | 2934 | [GK98] Glenn, R., and S. Kent, "The NULL Encryption Algorithm and Its 2935 | Use with IPsec", Work in Progress. 2936 | 2937 | [HM97a] Harney, H., and C. Muckenhirn, "Group Key Management Protocol 2938 | (GKMP) Specification", RFC 2093, July 1997. 2939 | 2940 | [HM97b] Harney, H., and C. Muckenhirn, "Group Key Management Protocol 2941 | (GKMP) Architecture", RFC 2094, July 1997. 2942 | 2943 | [MD98] Madsen, C., and N. Doraswamy, "The ESP DES-CBC Cipher 2944 | Algorithm With Explicit IV", Work in Progress. 2945 | 2946 | [MG98a] Madsen, C., and R. Glenn, "The Use of HMAC-MD5-96 within ESP 2947 | and AH", Work in Progress. 2948 | 2949 | [MG98b] Madsen, C., and R. Glenn, "The Use of HMAC-SHA-1-96 within 2950 | ESP and AH", Work in Progress. 2951 | 2952 | [MSST98] Maughan, D., Schertler, M., Schneider, M., and J. Turner, 2953 | "Internet Security Association and Key Management Protocol (ISAKMP)", 2954 | Work in Progress. 2955 | 2956 | [Moy98] Moy, J., "OSPF Version 2", STD 54, RFC 2328, April 1998. 2957 | 2958 | [Per97] Perkins, C., "IP Mobility Support", RFC 2002, October 1996. 2959 | 2960 | [Pip98] Piper, D., "The Internet IP Security Domain of Interpretation 2961 | for ISAKMP", Work in Progress. 2962 | 2963 | [Sch96] Bruce Schneier, Applied Cryptography, p. 360, John Wiley & 2964 | Sons, Inc., 1996. 2965 | 2966 | 2967 | 2968 | 2969 | 2970 | McDonald, et. al. Informational [Page 53] 2971 | 2972 | RFC 2367 PF_KEY Key Management API July 1998 2973 | 2974 | 2975 | [Skl91] Keith Sklower, "A Tree-based Packet Routing Table for 2976 | Berkeley UNIX", Proceedings of the Winter 1991 USENIX Conference, 2977 | Dallas, TX, USENIX Association. 1991. pp. 93-103. 2978 | 2979 | Disclaimer 2980 | 2981 | The views and specification here are those of the editors and are not 2982 | necessarily those of their employers. The employers have not passed 2983 | judgment on the merits, if any, of this work. The editors and their 2984 | employers specifically disclaim responsibility for any problems 2985 | arising from correct or incorrect implementation or use of this 2986 | specification. 2987 | 2988 | Authors' Addresses 2989 | 2990 | Daniel L. McDonald 2991 | Sun Microsystems, Inc. 2992 | 901 San Antonio Road, MS UMPK17-202 2993 | Palo Alto, CA 94303 2994 | 2995 | Phone: +1 650 786 6815 2996 | EMail: danmcd@eng.sun.com 2997 | 2998 | 2999 | Craig Metz 3000 | (for Code 5544) 3001 | U.S. Naval Research Laboratory 3002 | 4555 Overlook Ave. SW 3003 | Washington, DC 20375 3004 | 3005 | Phone: (DSN) 754-8590 3006 | EMail: cmetz@inner.net 3007 | 3008 | 3009 | Bao G. Phan 3010 | U. S. Naval Research Laboratory 3011 | 3012 | EMail: phan@itd.nrl.navy.mil 3013 | 3014 | 3015 | 3016 | 3017 | 3018 | 3019 | 3020 | 3021 | 3022 | 3023 | 3024 | 3025 | 3026 | McDonald, et. al. Informational [Page 54] 3027 | 3028 | RFC 2367 PF_KEY Key Management API July 1998 3029 | 3030 | 3031 | Appendix A: Promiscuous Send/Receive Message Type 3032 | 3033 | A kernel supporting PF_KEY MAY implement the following extension for 3034 | development and debugging purposes. If it does, it MUST implement the 3035 | extension as specified here. An implementation MAY require an 3036 | application to have additional privileges to perform promiscuous send 3037 | and/or receive operations. 3038 | 3039 | The SADB_X_PROMISC message allows an application to send and receive 3040 | messages in a "promiscuous mode." There are two forms of this 3041 | message: control and data. The control form consists of only a 3042 | message header. This message is used to toggle the promiscuous- 3043 | receive function. A value of one in the sadb_msg_satype field enables 3044 | promiscuous message reception for this socket, while a value of zero 3045 | in that field disables it. 3046 | 3047 | The second form of this message is the data form. This is used to 3048 | send or receive messages in their raw form. Messages in the data form 3049 | consist of a message header followed by an entire new message. There 3050 | will be two message headers in a row: one for the SADB_X_PROMISC 3051 | message, and one for the payload message. 3052 | 3053 | Data messages sent from the application are sent to either the PF_KEY 3054 | socket of a single process identified by a nonzero sadb_msg_seq or to 3055 | all PF_KEY sockets if sadb_msg_seq is zero. These messages are sent 3056 | without any processing of their contents by the PF_KEY interface 3057 | (including sanity checking). This promiscuous-send capability allows 3058 | an application to send messages as if it were the kernel. This also 3059 | allows it to send erroneous messages. 3060 | 3061 | If the promiscuous-receive function has been enabled, a copy of any 3062 | message sent via PF_KEY by another application or by the kernel is 3063 | sent to the promiscuous application. This is done before any 3064 | processing of the message's contents by the PF_KEY interface (again, 3065 | including sanity checking). This promiscuous-receive capability 3066 | allows an application to receive all messages sent by other parties 3067 | using PF_KEY. 3068 | 3069 | The messaging behavior of the SADB_X_PROMISC message is: 3070 | 3071 | Send a control-form SADB_X_PROMISC message from a user process 3072 | to the kernel. 3073 | 3074 | 3075 | 3076 | The kernel returns the SADB_X_PROMISC message to all listening 3077 | processes. 3078 | 3079 | 3080 | 3081 | 3082 | McDonald, et. al. Informational [Page 55] 3083 | 3084 | RFC 2367 PF_KEY Key Management API July 1998 3085 | 3086 | 3087 | 3088 | 3089 | Send a data-form SADB_X_PROMISC message from a user process to 3090 | the kernel. 3091 | 3092 | 3093 | 3094 | The kernel sends the encapsulated message to the target 3095 | process(s). 3096 | 3097 | 3098 | 3099 | If promiscuous-receive is enabled, the kernel will encapsulate 3100 | and send copies of all messages sent via the PF_KEY interface. 3101 | 3102 | 3103 | 3104 | Errors: 3105 | EPERM Additional privileges are required to perform the 3106 | requested operations. 3107 | ESRCH (Data form, sending) The target process in sadb_msg_seq 3108 | does not exist or does not have an open PF_KEY Version 2 3109 | socket. 3110 | 3111 | 3112 | 3113 | 3114 | 3115 | 3116 | 3117 | 3118 | 3119 | 3120 | 3121 | 3122 | 3123 | 3124 | 3125 | 3126 | 3127 | 3128 | 3129 | 3130 | 3131 | 3132 | 3133 | 3134 | 3135 | 3136 | 3137 | 3138 | McDonald, et. al. Informational [Page 56] 3139 | 3140 | RFC 2367 PF_KEY Key Management API July 1998 3141 | 3142 | 3143 | Appendix B: Passive Change Message Type 3144 | 3145 | The SADB_X_PCHANGE message is a passive-side (aka. the "listener" or 3146 | "receiver") counterpart to the SADB_ACQUIRE message. It is useful 3147 | for when key management applications wish to more effectively handle 3148 | incoming key management requests for passive-side sessions that 3149 | deviate from systemwide default security services. If a passive 3150 | session requests that only certain levels of security service be 3151 | allowed, the SADB_X_PCHANGE message expresses this change to any 3152 | registered PF_KEY sockets. Unlike SADB_ACQUIRE, this message is 3153 | purely informational, and demands no other PF_KEY interaction. 3154 | 3155 | The SADB_X_PCHANGE message is typically triggered by either a change 3156 | in an endpoint's requested security services, or when an endpoint 3157 | that made a special request disappears. In the former case, an 3158 | SADB_X_PCHANGE looks like an SADB_ACQUIRE, complete with an 3159 | sadb_proposal extension indicating the preferred algorithms, 3160 | lifetimes, and other attributes. When a passive session either 3161 | disappears, or reverts to a default behavior, an SADB_X_PCHANGE will 3162 | be issued with _no_ sadb_proposal extension, indicating that the 3163 | exception to systemwide default behavior has disappeared. 3164 | 3165 | There are two messaging behaviors for SADB_X_PCHANGE. The first is 3166 | the kernel-originated case: 3167 | 3168 | The kernel sends an SADB_X_PCHANGE message to registered 3169 | sockets. 3170 | 3171 | 3172 | 3173 | NOTE: The address(SD) extensions MUST have the port fields 3174 | filled in with the port numbers of the session 3175 | requiring keys if appropriate. 3176 | 3177 | The second is for a user-level consumer of SAs. 3178 | 3179 | Send an SADB_X_PCHANGE message from a user process to the 3180 | kernel. 3181 | 3182 | 3183 | 3184 | The kernel returns an SADB_X_PCHANGE message to registered 3185 | sockets. 3186 | 3187 | 3188 | 3189 | 3190 | 3191 | 3192 | 3193 | 3194 | McDonald, et. al. Informational [Page 57] 3195 | 3196 | RFC 2367 PF_KEY Key Management API July 1998 3197 | 3198 | 3199 | Appendix C: Key Management Private Data Extension 3200 | 3201 | The Key Management Private Data extension is attached to either an 3202 | SADB_ADD or an SADB_UPDATE message. It attaches a single piece of 3203 | arbitrary data to a security association. It may be useful for key 3204 | managment applications that could use an SADB_DUMP or SADB_GET 3205 | message to obtain additional state if it needs to restart or recover 3206 | after a crash. The format of this extension is: 3207 | 3208 | #define SADB_X_EXT_KMPRIVATE 17 3209 | 3210 | struct sadb_x_kmprivate { 3211 | uint16_t sadb_x_kmprivate_len; 3212 | uint16_t sadb_x_kmprivate_exttype; 3213 | uint32_t sadb_x_kmprivate_reserved; 3214 | }; 3215 | /* sizeof(struct sadb_x_kmprivate) == 8 */ 3216 | 3217 | /* followed by arbitrary data */ 3218 | 3219 | 3220 | The data following the sadb_x_kmprivate extension can be anything. 3221 | It will be stored with the actual security association in the kernel. 3222 | Like all data, it must be padded to an eight byte boundary. 3223 | 3224 | 3225 | 3226 | 3227 | 3228 | 3229 | 3230 | 3231 | 3232 | 3233 | 3234 | 3235 | 3236 | 3237 | 3238 | 3239 | 3240 | 3241 | 3242 | 3243 | 3244 | 3245 | 3246 | 3247 | 3248 | 3249 | 3250 | McDonald, et. al. Informational [Page 58] 3251 | 3252 | RFC 2367 PF_KEY Key Management API July 1998 3253 | 3254 | 3255 | Appendix D: Sample Header File 3256 | 3257 | /* 3258 | This file defines structures and symbols for the PF_KEY Version 2 3259 | key management interface. It was written at the U.S. Naval Research 3260 | Laboratory. This file is in the public domain. The authors ask that 3261 | you leave this credit intact on any copies of this file. 3262 | */ 3263 | #ifndef __PFKEY_V2_H 3264 | #define __PFKEY_V2_H 1 3265 | 3266 | #define PF_KEY_V2 2 3267 | #define PFKEYV2_REVISION 199806L 3268 | 3269 | #define SADB_RESERVED 0 3270 | #define SADB_GETSPI 1 3271 | #define SADB_UPDATE 2 3272 | #define SADB_ADD 3 3273 | #define SADB_DELETE 4 3274 | #define SADB_GET 5 3275 | #define SADB_ACQUIRE 6 3276 | #define SADB_REGISTER 7 3277 | #define SADB_EXPIRE 8 3278 | #define SADB_FLUSH 9 3279 | #define SADB_DUMP 10 3280 | #define SADB_X_PROMISC 11 3281 | #define SADB_X_PCHANGE 12 3282 | #define SADB_MAX 12 3283 | 3284 | struct sadb_msg { 3285 | uint8_t sadb_msg_version; 3286 | uint8_t sadb_msg_type; 3287 | uint8_t sadb_msg_errno; 3288 | uint8_t sadb_msg_satype; 3289 | uint16_t sadb_msg_len; 3290 | uint16_t sadb_msg_reserved; 3291 | uint32_t sadb_msg_seq; 3292 | uint32_t sadb_msg_pid; 3293 | }; 3294 | 3295 | struct sadb_ext { 3296 | uint16_t sadb_ext_len; 3297 | uint16_t sadb_ext_type; 3298 | }; 3299 | 3300 | struct sadb_sa { 3301 | uint16_t sadb_sa_len; 3302 | uint16_t sadb_sa_exttype; 3303 | 3304 | 3305 | 3306 | McDonald, et. al. Informational [Page 59] 3307 | 3308 | RFC 2367 PF_KEY Key Management API July 1998 3309 | 3310 | 3311 | uint32_t sadb_sa_spi; 3312 | uint8_t sadb_sa_replay; 3313 | uint8_t sadb_sa_state; 3314 | uint8_t sadb_sa_auth; 3315 | uint8_t sadb_sa_encrypt; 3316 | uint32_t sadb_sa_flags; 3317 | }; 3318 | 3319 | struct sadb_lifetime { 3320 | uint16_t sadb_lifetime_len; 3321 | uint16_t sadb_lifetime_exttype; 3322 | uint32_t sadb_lifetime_allocations; 3323 | uint64_t sadb_lifetime_bytes; 3324 | uint64_t sadb_lifetime_addtime; 3325 | uint64_t sadb_lifetime_usetime; 3326 | }; 3327 | 3328 | struct sadb_address { 3329 | uint16_t sadb_address_len; 3330 | uint16_t sadb_address_exttype; 3331 | uint8_t sadb_address_proto; 3332 | uint8_t sadb_address_prefixlen; 3333 | uint16_t sadb_address_reserved; 3334 | }; 3335 | 3336 | struct sadb_key { 3337 | uint16_t sadb_key_len; 3338 | uint16_t sadb_key_exttype; 3339 | uint16_t sadb_key_bits; 3340 | uint16_t sadb_key_reserved; 3341 | }; 3342 | 3343 | struct sadb_ident { 3344 | uint16_t sadb_ident_len; 3345 | uint16_t sadb_ident_exttype; 3346 | uint16_t sadb_ident_type; 3347 | uint16_t sadb_ident_reserved; 3348 | uint64_t sadb_ident_id; 3349 | }; 3350 | 3351 | struct sadb_sens { 3352 | uint16_t sadb_sens_len; 3353 | uint16_t sadb_sens_exttype; 3354 | uint32_t sadb_sens_dpd; 3355 | uint8_t sadb_sens_sens_level; 3356 | uint8_t sadb_sens_sens_len; 3357 | uint8_t sadb_sens_integ_level; 3358 | uint8_t sadb_sens_integ_len; 3359 | 3360 | 3361 | 3362 | McDonald, et. al. Informational [Page 60] 3363 | 3364 | RFC 2367 PF_KEY Key Management API July 1998 3365 | 3366 | 3367 | uint32_t sadb_sens_reserved; 3368 | }; 3369 | 3370 | struct sadb_prop { 3371 | uint16_t sadb_prop_len; 3372 | uint16_t sadb_prop_exttype; 3373 | uint8_t sadb_prop_replay; 3374 | uint8_t sadb_prop_reserved[3]; 3375 | }; 3376 | 3377 | struct sadb_comb { 3378 | uint8_t sadb_comb_auth; 3379 | uint8_t sadb_comb_encrypt; 3380 | uint16_t sadb_comb_flags; 3381 | uint16_t sadb_comb_auth_minbits; 3382 | uint16_t sadb_comb_auth_maxbits; 3383 | uint16_t sadb_comb_encrypt_minbits; 3384 | uint16_t sadb_comb_encrypt_maxbits; 3385 | uint32_t sadb_comb_reserved; 3386 | uint32_t sadb_comb_soft_allocations; 3387 | uint32_t sadb_comb_hard_allocations; 3388 | uint64_t sadb_comb_soft_bytes; 3389 | uint64_t sadb_comb_hard_bytes; 3390 | uint64_t sadb_comb_soft_addtime; 3391 | uint64_t sadb_comb_hard_addtime; 3392 | uint64_t sadb_comb_soft_usetime; 3393 | uint64_t sadb_comb_hard_usetime; 3394 | }; 3395 | 3396 | struct sadb_supported { 3397 | uint16_t sadb_supported_len; 3398 | uint16_t sadb_supported_exttype; 3399 | uint32_t sadb_supported_reserved; 3400 | }; 3401 | 3402 | struct sadb_alg { 3403 | uint8_t sadb_alg_id; 3404 | uint8_t sadb_alg_ivlen; 3405 | uint16_t sadb_alg_minbits; 3406 | uint16_t sadb_alg_maxbits; 3407 | uint16_t sadb_alg_reserved; 3408 | }; 3409 | 3410 | struct sadb_spirange { 3411 | uint16_t sadb_spirange_len; 3412 | uint16_t sadb_spirange_exttype; 3413 | uint32_t sadb_spirange_min; 3414 | uint32_t sadb_spirange_max; 3415 | 3416 | 3417 | 3418 | McDonald, et. al. Informational [Page 61] 3419 | 3420 | RFC 2367 PF_KEY Key Management API July 1998 3421 | 3422 | 3423 | uint32_t sadb_spirange_reserved; 3424 | }; 3425 | 3426 | struct sadb_x_kmprivate { 3427 | uint16_t sadb_x_kmprivate_len; 3428 | uint16_t sadb_x_kmprivate_exttype; 3429 | uint32_t sadb_x_kmprivate_reserved; 3430 | }; 3431 | 3432 | #define SADB_EXT_RESERVED 0 3433 | #define SADB_EXT_SA 1 3434 | #define SADB_EXT_LIFETIME_CURRENT 2 3435 | #define SADB_EXT_LIFETIME_HARD 3 3436 | #define SADB_EXT_LIFETIME_SOFT 4 3437 | #define SADB_EXT_ADDRESS_SRC 5 3438 | #define SADB_EXT_ADDRESS_DST 6 3439 | #define SADB_EXT_ADDRESS_PROXY 7 3440 | #define SADB_EXT_KEY_AUTH 8 3441 | #define SADB_EXT_KEY_ENCRYPT 9 3442 | #define SADB_EXT_IDENTITY_SRC 10 3443 | #define SADB_EXT_IDENTITY_DST 11 3444 | #define SADB_EXT_SENSITIVITY 12 3445 | #define SADB_EXT_PROPOSAL 13 3446 | #define SADB_EXT_SUPPORTED_AUTH 14 3447 | #define SADB_EXT_SUPPORTED_ENCRYPT 15 3448 | #define SADB_EXT_SPIRANGE 16 3449 | #define SADB_X_EXT_KMPRIVATE 17 3450 | #define SADB_EXT_MAX 17 3451 | #define SADB_SATYPE_UNSPEC 0 3452 | #define SADB_SATYPE_AH 2 3453 | #define SADB_SATYPE_ESP 3 3454 | #define SADB_SATYPE_RSVP 5 3455 | #define SADB_SATYPE_OSPFV2 6 3456 | #define SADB_SATYPE_RIPV2 7 3457 | #define SADB_SATYPE_MIP 8 3458 | #define SADB_SATYPE_MAX 8 3459 | 3460 | #define SADB_SASTATE_LARVAL 0 3461 | #define SADB_SASTATE_MATURE 1 3462 | #define SADB_SASTATE_DYING 2 3463 | #define SADB_SASTATE_DEAD 3 3464 | #define SADB_SASTATE_MAX 3 3465 | 3466 | #define SADB_SAFLAGS_PFS 1 3467 | 3468 | #define SADB_AALG_NONE 0 3469 | #define SADB_AALG_MD5HMAC 2 3470 | #define SADB_AALG_SHA1HMAC 3 3471 | 3472 | 3473 | 3474 | McDonald, et. al. Informational [Page 62] 3475 | 3476 | RFC 2367 PF_KEY Key Management API July 1998 3477 | 3478 | 3479 | #define SADB_AALG_MAX 3 3480 | 3481 | #define SADB_EALG_NONE 0 3482 | #define SADB_EALG_DESCBC 2 3483 | #define SADB_EALG_3DESCBC 3 3484 | #define SADB_EALG_NULL 11 3485 | #define SADB_EALG_MAX 11 3486 | 3487 | #define SADB_IDENTTYPE_RESERVED 0 3488 | #define SADB_IDENTTYPE_PREFIX 1 3489 | #define SADB_IDENTTYPE_FQDN 2 3490 | #define SADB_IDENTTYPE_USERFQDN 3 3491 | #define SADB_IDENTTYPE_MAX 3 3492 | 3493 | #define SADB_KEY_FLAGS_MAX 0 3494 | #endif /* __PFKEY_V2_H */ 3495 | 3496 | 3497 | 3498 | 3499 | 3500 | 3501 | 3502 | 3503 | 3504 | 3505 | 3506 | 3507 | 3508 | 3509 | 3510 | 3511 | 3512 | 3513 | 3514 | 3515 | 3516 | 3517 | 3518 | 3519 | 3520 | 3521 | 3522 | 3523 | 3524 | 3525 | 3526 | 3527 | 3528 | 3529 | 3530 | McDonald, et. al. Informational [Page 63] 3531 | 3532 | RFC 2367 PF_KEY Key Management API July 1998 3533 | 3534 | 3535 | Appendix E: Change Log 3536 | 3537 | The following changes were made between 05 and 06: 3538 | 3539 | * Last change before becoming an informational RFC. Removed all 3540 | Internet-Draft references. Also standardized citation strings. 3541 | Now cite RFC 2119 for MUST, etc. 3542 | 3543 | * New appendix on optional KM private data extension. 3544 | 3545 | * Fixed example to indicate the ACQUIRE messages with errno mean 3546 | KM failure. 3547 | 3548 | * Added SADB_EALG_NULL. 3549 | 3550 | * Clarified proxy examples to match definition of PROXY address being 3551 | the inner packet's source address. (Basically a sign-flip. The 3552 | example still shows how to protect against policy vulnerabilities 3553 | in tunnel endpoints.) 3554 | 3555 | * Loosened definition of a destination address to include broadcast. 3556 | 3557 | * Recommended that LARVAL security associations have implicit short 3558 | lifetimes. 3559 | 3560 | The following changes were made between 04 and 05: 3561 | 3562 | * New appendix on Passive Change message. 3563 | 3564 | * New sadb_address_prefixlen field. 3565 | 3566 | * Small clarifications on sadb_ident_id usage. 3567 | 3568 | * New PFKEYV2_REVISION value. 3569 | 3570 | * Small clarification on what a PROXY address is. 3571 | 3572 | * Corrected sadb_spirange_{min,max} language. 3573 | 3574 | * In ADD messages that are in response to an ACQUIRE, the 3575 | sadb_msg_seq MUST be the same as that of the originating ACQUIRE. 3576 | 3577 | * Corrected ACQUIRE message behavior, ACQUIRE message SHOULD send up 3578 | PROXY addresses when it needs them. 3579 | 3580 | * Clarification on SADB_EXPIRE and user-level security protocols. 3581 | 3582 | The following changes were made between 03 and 04: 3583 | 3584 | 3585 | 3586 | McDonald, et. al. Informational [Page 64] 3587 | 3588 | RFC 2367 PF_KEY Key Management API July 1998 3589 | 3590 | 3591 | * Stronger language about manual keying. 3592 | 3593 | * PFKEYV2_REVISION, ala POSIX. 3594 | 3595 | * Put in language about sockaddr ports in ACQUIRE messages. 3596 | 3597 | * Mention of asymmetric algorithms. 3598 | 3599 | * New sadb_ident_id field for easier construction of USER_FQDN 3600 | identity strings. 3601 | 3602 | * Caveat about source addresses not always used for collision 3603 | detection. (e.g. IPsec) 3604 | 3605 | The following changes were made between 02 and 03: 3606 | 3607 | 3608 | * Formatting changes. 3609 | 3610 | * Many editorial cleanups, rewordings, clarifications. 3611 | 3612 | * Restrictions that prevent many strange and invalid cases. 3613 | 3614 | * Added definitions section. 3615 | 3616 | * Removed connection identity type (this will reappear when it is 3617 | more clear what it should look like). 3618 | 3619 | * Removed 5.2.1 (Why involve the kernel?). 3620 | 3621 | * Removed INBOUND, OUTBOUND, and FORWARD flags; they can be computed 3622 | from src, dst, and proxy and you had to anyway for sanity checking. 3623 | 3624 | * Removed REPLAY flag; sadb_sa_replay==0 means the same thing. 3625 | 3626 | * Renamed bit lengths to "bits" to avoid potential confusion. 3627 | 3628 | * Explicitly listed lengths for structures. 3629 | 3630 | * Reworked identities to always use a string format. 3631 | 3632 | * Removed requirements for support of shutdown() and SO_USELOOPBACK. 3633 | 3634 | * 64 bit alignment and 64 bit lengths instead of 32 bit. 3635 | 3636 | * time_t replaced with uint64 in lifetimes. 3637 | 3638 | 3639 | 3640 | 3641 | 3642 | McDonald, et. al. Informational [Page 65] 3643 | 3644 | RFC 2367 PF_KEY Key Management API July 1998 3645 | 3646 | 3647 | * Inserted Appendix A (SADB_X_PROMISC) and Appendix B (SAMPLE HEADER 3648 | FILE). 3649 | 3650 | * Explicit error if PF_KEY_V2 not set at socket() call. 3651 | 3652 | * More text on SO_USELOOPBACK. 3653 | 3654 | * Made fields names and symbol names more consistent. 3655 | 3656 | * Explicit error if PF_KEY_V2 is not in sadb_msg_version field. 3657 | 3658 | * Bytes lifetime field now a 64-bit quantity. 3659 | 3660 | * Explicit len/exttype wording. 3661 | 3662 | * Flattening out of extensions (LIFETIME_HARD, LIFETIME_SOFT, etc.) 3663 | 3664 | * UI example (0x123 == 0x1230 or 0x0123). 3665 | 3666 | * Cleaned up and fixed some message behavior examples. 3667 | 3668 | The following changes were made between 01 and 02: 3669 | 3670 | * Mentioned that people COULD use these same messages between user 3671 | progs. (Also mentioned why you still might want to use the actual 3672 | socket.) 3673 | 3674 | * Various wordsmithing changes. 3675 | 3676 | * Took out netkey/ directory, and make net/pfkeyv2.h 3677 | 3678 | * Inserted PF_KEY_V2 proto argument per C. Metz. 3679 | 3680 | * Mentioned other socket calls and how their PF_KEY behavior is 3681 | undefined. 3682 | 3683 | * SADB_EXPIRE now communicates both hard and soft lifetime expires. 3684 | 3685 | * New "association" extension, even smaller base header. 3686 | 3687 | * Lifetime extension improvements. 3688 | 3689 | * Length now first in extensions. 3690 | 3691 | * Errors can be sent from kernel to user, also. 3692 | 3693 | * Examples section inserted. 3694 | 3695 | 3696 | 3697 | 3698 | McDonald, et. al. Informational [Page 66] 3699 | 3700 | RFC 2367 PF_KEY Key Management API July 1998 3701 | 3702 | 3703 | * Some bitfield cleanups, including STATE and SA_OPTIONS cleanup. 3704 | 3705 | * Key splitting now only across auth algorithm and encryption 3706 | algorithm. Thanks for B. Sommerfeld for clues here. 3707 | 3708 | The following changes were made between 00 and 01: 3709 | 3710 | * Added this change log. 3711 | 3712 | * Simplified TLV header syntax. 3713 | 3714 | * Splitting of algorithms. This may be controversial, but it allows 3715 | PF_KEY to be used for more than just IPsec. It also allows some 3716 | kinds of policies to be placed in the KMd easier. 3717 | 3718 | * Added solid definitions and formats for certificate identities, 3719 | multiple keys, etc. 3720 | 3721 | * Specified how keys are to be layed out (most-to-least bits). 3722 | 3723 | * Changed sequence number semantics to be like an RPC transaction ID 3724 | number. 3725 | 3726 | 3727 | 3728 | 3729 | 3730 | 3731 | 3732 | 3733 | 3734 | 3735 | 3736 | 3737 | 3738 | 3739 | 3740 | 3741 | 3742 | 3743 | 3744 | 3745 | 3746 | 3747 | 3748 | 3749 | 3750 | 3751 | 3752 | 3753 | 3754 | McDonald, et. al. Informational [Page 67] 3755 | 3756 | RFC 2367 PF_KEY Key Management API July 1998 3757 | 3758 | 3759 | F. Full Copyright Statement 3760 | 3761 | Copyright (C) The Internet Society (1998). All Rights Reserved. 3762 | 3763 | This document and translations of it may be copied and furnished to 3764 | others, and derivative works that comment on or otherwise explain it 3765 | or assist in its implementation may be prepared, copied, published 3766 | and distributed, in whole or in part, without restriction of any 3767 | kind, provided that the above copyright notice and this paragraph are 3768 | included on all such copies and derivative works. However, this 3769 | document itself may not be modified in any way, such as by removing 3770 | the copyright notice or references to the Internet Society or other 3771 | Internet organizations, except as needed for the purpose of 3772 | developing Internet standards in which case the procedures for 3773 | copyrights defined in the Internet Standards process must be 3774 | followed, or as required to translate it into languages other than 3775 | English. 3776 | 3777 | The limited permissions granted above are perpetual and will not be 3778 | revoked by the Internet Society or its successors or assigns. 3779 | 3780 | This document and the information contained herein is provided on an 3781 | "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 3782 | TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 3783 | BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 3784 | HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 3785 | MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 3786 | 3787 | 3788 | 3789 | 3790 | 3791 | 3792 | 3793 | 3794 | 3795 | 3796 | 3797 | 3798 | 3799 | 3800 | 3801 | 3802 | 3803 | 3804 | 3805 | 3806 | 3807 | 3808 | 3809 | 3810 | McDonald, et. al. Informational [Page 68] 3811 | 3812 | -------------------------------------------------------------------------------- /src/config.mli: -------------------------------------------------------------------------------- 1 | 2 | (* configuration stuff, both sides share the same datatype *) 3 | 4 | type t = { 5 | supported_versions : version list ; 6 | enc : cipher list ; 7 | policies : ?? ; 8 | selectors : ?? ; 9 | peers : ?? ; 10 | } 11 | 12 | val parse : data -> t 13 | -------------------------------------------------------------------------------- /src/control.mli: -------------------------------------------------------------------------------- 1 | 2 | type action = 3 | | `SPDadd 4 | | `SPDremove 5 | | ... 6 | 7 | val decode : Cstruct.t -> action error 8 | -------------------------------------------------------------------------------- /src/crypto.mli: -------------------------------------------------------------------------------- 1 | 2 | (* ike related crypto utilities and mappings *) 3 | -------------------------------------------------------------------------------- /src/decode.mli: -------------------------------------------------------------------------------- 1 | 2 | (* decode : Cstruct.t -> C.something error *) 3 | -------------------------------------------------------------------------------- /src/dispatcher.ml: -------------------------------------------------------------------------------- 1 | open C 2 | 3 | type state = int 4 | 5 | (* XXX: somehow this might be more convenient (works if each module instantiated only once / using a single logger) 6 | let src = Logs.Src.create "dispatcher" ~doc:"xxx" 7 | module Log = (val Logs.src_log src : Logs.LOG) 8 | *) 9 | 10 | type t = { 11 | ts : state list ; 12 | pfkey : Pfkey_engine.state ; 13 | logger : Logs.src ; 14 | (* config : Config.t ; 15 | supported_auth : ?? ; (* from the kernel *) 16 | supported_enc : ?? ; *) 17 | } 18 | 19 | (* 20 | let handle_tick t = 21 | List.fold_left (fun (acc, sads) t -> 22 | match Ike.handle_tick t with 23 | | Ok (state, sads', outs) -> 24 | ({t with state} :: acc, sads' @ sads) 25 | | Error sads' -> 26 | (acc, sads' @ sads)) 27 | ([], []) 28 | ts 29 | 30 | let handle_data t data addr = 31 | let t, others = 32 | match List.partition (spi_matches cs) ts with 33 | | ([t], others) -> (t, others) 34 | | ([], others) -> 35 | let state = Ike.responder config addr in 36 | ({ state ; addr }, others) 37 | | _ -> assert false 38 | in 39 | match Ike.handle_ike t.state addr cs with 40 | | Ok (state, sad_changes, outs) -> 41 | ({t with state} :: others, sad_changes, outs) 42 | | `InitialContact (state, auth, outs) -> 43 | let ts, sad_changes = 44 | List.fold_left (fun (acc, sads) t -> 45 | match Ike.handle_initial_contact t.state auth with 46 | | `Ok state -> ({ t with state } :: acc, sads) 47 | | `Fail sads' -> (acc, sads' @ sads)) 48 | ([], []) 49 | others 50 | in 51 | ({t with state} :: ts, sad_changes) 52 | | Error sad_changes -> (others, sad_changes) 53 | *) 54 | 55 | (* 56 | let handle_control t = function 57 | | _ -> assert false 58 | *) 59 | 60 | let handle t ev = 61 | match ev with 62 | | `Pfkey data -> 63 | Logs.info ~src:t.logger (fun pp -> pp "handling pfkey") ; 64 | Pfkey_engine.handle t.pfkey data >|= fun (pfkey, cmd) -> 65 | let cmdstr = match cmd with 66 | | None -> "none" 67 | | Some x -> Sexplib.Sexp.to_string_hum (sexp_of_pfkey_from_kern x) 68 | in 69 | Logs.info ~src:t.logger (fun pp -> pp "handled pfkeys: %s" cmdstr) ; 70 | let pfkey, out = Pfkey_engine.maybe_command pfkey in 71 | Logs.debug ~src:t.logger (fun pp -> pp "sending out %d" (match out with None -> 0 | Some x -> Cstruct.len x)) ; 72 | ({ t with pfkey }, `Pfkey out, `Data []) 73 | | `Tick -> 74 | Logs.debug ~src:t.logger (fun pp -> pp "tick") ; 75 | Ok (t, `Pfkey None, `Data []) 76 | | _ -> assert false 77 | (* | `Control data > Control.decode data >>= handle_control t 78 | | `Data (data, addr) -> handle_data t data addr *) 79 | 80 | let create () = 81 | (* let config = Config.parse config in *) 82 | let pfkey, out = Pfkey_engine.create 83 | ~commands:[`Dump None ; `Flush None ; `Policy_Dump ; `Policy_Flush ; `Register `AH ; `Register `ESP] () in 84 | ({ ts = [] ; pfkey ; logger = Logs.Src.create "dispatcher" }, out) 85 | -------------------------------------------------------------------------------- /src/dispatcher.mli: -------------------------------------------------------------------------------- 1 | 2 | type t 3 | 4 | (* The dispatcher receives an event and a `t`, and distributes the 5 | event to interested IKE sessions (Engine.t). It is the main 6 | entry point for a side-effecting speaker. *) 7 | val handle : t -> 8 | [ `Pfkey of Cstruct.t | `Control of Cstruct.t | `Data of (Cstruct.t * (Unix.inet_addr * int)) | `Tick ] -> 9 | (t * [ `Pfkey of Cstruct.t option ] * [ `Data of (Cstruct.t * (Unix.inet_addr * int)) list ], 10 | C.error) Result.result 11 | 12 | (* creation of a `t`: it will start with an empty list of Engine.t, and emit 13 | a message to be send to the pfkey socket (REGISTER ESP). It waits for 14 | `Config directives which initially add policies *) 15 | val create : unit -> t * Cstruct.t option 16 | -------------------------------------------------------------------------------- /src/encode.mli: -------------------------------------------------------------------------------- 1 | 2 | (* high-level -> Cstruct.t [no option, no error -- we can encode all high level things] *) 3 | -------------------------------------------------------------------------------- /src/engine.ml: -------------------------------------------------------------------------------- 1 | 2 | 3 | type initiator_state = 4 | | Sa_init_sent of ?? 5 | | Auth_sent of ?? 6 | | Active 7 | | Closing 8 | 9 | type responder_state = 10 | | Initial 11 | | Sa_init_replied of ?? 12 | | Auth_replied of ?? 13 | | Active 14 | | Closing 15 | 16 | type state = 17 | | Initiator of initiator_state 18 | | Responder of responder_state 19 | 20 | let active = function 21 | | Initiator (Active _) | Responder (Active _) -> true 22 | | _ -> false 23 | 24 | type t = { 25 | spi : Cstruct.t ; 26 | message_id : Int32 ; 27 | machina : state ; 28 | window_size : int ; 29 | peer : Ipaddr.t * int ; 30 | childs : sa list ; 31 | replies : (int * Cstruct.t) list ; 32 | requests : (int * Cstruct.t) list ; 33 | crypto_ctx : ?? option ; 34 | log : Logs.Src.t ; 35 | } 36 | 37 | let initiator config peer = 38 | ({ machina = Initiator Sa_init_sent ; 39 | window_size = 1 ; 40 | peer ; 41 | childs = [] ; 42 | replies = [] ; 43 | requests = [] ; 44 | crypto_ctx = None }, 45 | Encoder.encode (SA_INIT ???)) 46 | 47 | let responder config peer = 48 | { machina = Responder Initial ; 49 | window_size = 1 ; 50 | peer ; 51 | childs = [] ; 52 | replies = [] ; 53 | requests = [] ; 54 | crypto_ctx = None } 55 | 56 | let handle_frame t data = 57 | match t.machina, data with 58 | | Responder Initial, SA_INIT data -> 59 | | Responder Sa_init_replied, SA_AUTH data -> 60 | | Initiator Sa_init_sent, SA_INIT data -> 61 | | Initiator Auth_sen, SA_AUTH data -> 62 | | x, y when active x -> handle_y 63 | | _ -> Logs.warn ~src:t.logger (fun p -> p "don't know what to do") 64 | 65 | let pipeline t data = 66 | parse data >>= fun (hdr, frames, encrypted) -> 67 | handle_header t hdr >>= fun t -> 68 | fold handle_frame t frames >>= fun (t, unenc_out, pfkey) -> 69 | decrypt t encrypted >>= fun frames -> 70 | fold handle_enc t frames >>= fun (t, out, pfkey') -> 71 | let enc_out = encrypt t out in 72 | (t, assemble t unenc_out enc_out, pfkey@pfkey') 73 | 74 | 75 | (* initial handshake: SA_INIT; reply; SA_AUTH; reply [done once all received] 76 | responder might reply with cookie or 'do not like group' (or both, up to 8 messages) 77 | *) 78 | let recv_data t data = 79 | match pipeline t data with 80 | | Ok x -> x 81 | | Error e -> 82 | Logs.warn ~src:t.logger (fun p -> p "parse error %s" e) ; 83 | (t, [], []) 84 | -------------------------------------------------------------------------------- /src/engine.mli: -------------------------------------------------------------------------------- 1 | open Return 2 | 3 | (* the main engine *) 4 | type t 5 | 6 | (* failures, to be shown to us *) 7 | type failure = [ 8 | | `InvalidFoo 9 | | `InvalidBar 10 | ] 11 | 12 | val pp_failure : Format.formatter * failure -> unit 13 | 14 | type sad_change 15 | 16 | type ret = 17 | (t * sad_change list * Cstruct.t list, 18 | sad_change list) return 19 | 20 | val active_pads : Config.t -> peer_auth list 21 | 22 | val initiator : Config.t -> peer_auth -> t * (Ipaddr.t * int) 23 | val responder : Config.t -> t 24 | 25 | (* main handler for incoming bytes *) 26 | val handle_ike : t -> addr -> Cstruct.t -> 27 | [ ret | `InitialContact of t * peer_auth * out list ] 28 | 29 | val handle_initial_contact : t -> peer_auth -> 30 | [ `Ok of t | `Fail of sad_change list ] 31 | 32 | val handle_tick : t -> ret 33 | 34 | val spi_matches : t -> Cstruct.t -> bool 35 | 36 | -------------------------------------------------------------------------------- /src/packet.ml: -------------------------------------------------------------------------------- 1 | 2 | (* all the cenums *) 3 | --------------------------------------------------------------------------------