2 * Copyright (C) 2008 Martin Willi
3 * Hochschule fuer Technik Rapperswil
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 * @defgroup keymat keymat
25 #include <utils/identification.h>
26 #include <crypto/prfs/prf.h>
27 #include <crypto/aead.h>
28 #include <config/proposal.h>
29 #include <sa/ike_sa_id.h>
31 typedef struct keymat_t keymat_t
;
34 * Derivation an management of sensitive keying material.
39 * Create a diffie hellman object for key agreement.
41 * The diffie hellman is either for IKE negotiation/rekeying or
42 * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
43 * to derive_keys or to derive_child_keys and destroyed after use.
45 * Only DH objects allocated through this method are passed to other
46 * keymat_t methods, allowing private DH implementations. In some cases
47 * (such as retrying with a COOKIE), a DH object allocated from a different
48 * keymat_t instance may be passed to other methods.
50 * @param group diffie hellman group
51 * @return DH object, NULL if group not supported
53 diffie_hellman_t
* (*create_dh
)(keymat_t
*this, diffie_hellman_group_t group
);
56 * Derive keys for the IKE_SA.
58 * These keys are not handed out, but are used by the associated signers,
59 * crypters and authentication functions.
61 * @param proposal selected algorithms
62 * @param dh diffie hellman key allocated by create_dh()
63 * @param nonce_i initiators nonce value
64 * @param nonce_r responders nonce value
65 * @param id IKE_SA identifier
66 * @param rekey_prf PRF of old SA if rekeying, PRF_UNDEFINED otherwise
67 * @param rekey_sdk SKd of old SA if rekeying
68 * @return TRUE on success
70 bool (*derive_ike_keys
)(keymat_t
*this, proposal_t
*proposal
,
71 diffie_hellman_t
*dh
, chunk_t nonce_i
,
72 chunk_t nonce_r
, ike_sa_id_t
*id
,
73 pseudo_random_function_t rekey_function
,
76 * Derive keys for a CHILD_SA.
78 * The keys for the CHILD_SA are allocated in the integ and encr chunks.
79 * An implementation might hand out encrypted keys only, which are
80 * decrypted in the kernel before use.
81 * If no PFS is used for the CHILD_SA, dh can be NULL.
83 * @param proposal selected algorithms
84 * @param dh diffie hellman key allocated by create_dh(), or NULL
85 * @param nonce_i initiators nonce value
86 * @param nonce_r responders nonce value
87 * @param encr_i chunk to write initiators encryption key to
88 * @param integ_i chunk to write initiators integrity key to
89 * @param encr_r chunk to write responders encryption key to
90 * @param integ_r chunk to write responders integrity key to
91 * @return TRUE on success
93 bool (*derive_child_keys
)(keymat_t
*this,
94 proposal_t
*proposal
, diffie_hellman_t
*dh
,
95 chunk_t nonce_i
, chunk_t nonce_r
,
96 chunk_t
*encr_i
, chunk_t
*integ_i
,
97 chunk_t
*encr_r
, chunk_t
*integ_r
);
99 * Get SKd to pass to derive_ikey_keys() during rekeying.
101 * @param skd chunk to write SKd to (internal data)
102 * @return PRF function to derive keymat
104 pseudo_random_function_t (*get_skd
)(keymat_t
*this, chunk_t
*skd
);
107 * Get a AEAD transform to en-/decrypt and sign/verify IKE messages.
109 * @param in TRUE for inbound (decrypt), FALSE for outbound (encrypt)
112 aead_t
* (*get_aead
)(keymat_t
*this, bool in
);
115 * Generate octets to use for authentication procedure (RFC4306 2.15).
117 * This method creates the plain octets and is usually signed by a private
118 * key. PSK and EAP authentication include a secret into the data, use
119 * the get_psk_sig() method instead.
121 * @param verify TRUE to create for verfification, FALSE to sign
122 * @param ike_sa_init encoded ike_sa_init message
123 * @param nonce nonce value
125 * @param reserved reserved bytes of id_payload
126 * @return authentication octets
128 chunk_t (*get_auth_octets
)(keymat_t
*this, bool verify
, chunk_t ike_sa_init
,
129 chunk_t nonce
, identification_t
*id
,
132 * Build the shared secret signature used for PSK and EAP authentication.
134 * This method wraps the get_auth_octets() method and additionally
135 * includes the secret into the signature. If no secret is given, SK_p is
136 * used as secret (used for EAP methods without MSK).
138 * @param verify TRUE to create for verfification, FALSE to sign
139 * @param ike_sa_init encoded ike_sa_init message
140 * @param nonce nonce value
141 * @param secret optional secret to include into signature
143 * @param reserved reserved bytes of id_payload
144 * @return signature octets
146 chunk_t (*get_psk_sig
)(keymat_t
*this, bool verify
, chunk_t ike_sa_init
,
147 chunk_t nonce
, chunk_t secret
,
148 identification_t
*id
, char reserved
[3]);
150 * Destroy a keymat_t.
152 void (*destroy
)(keymat_t
*this);
156 * Create a keymat instance.
158 * @param initiator TRUE if we are the initiator
159 * @return keymat instance
161 keymat_t
*keymat_create(bool initiator
);
163 #endif /** KEYMAT_H_ @}*/