0d6d08f512ab38b695e8b9ddef30258931c6796a
[strongswan.git] / src / charon / sa / keymat.h
1 /*
2 * Copyright (C) 2008 Martin Willi
3 * Hochschule fuer Technik Rapperswil
4 *
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>.
9 *
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
13 * for more details.
14 *
15 * $Id$
16 */
17
18 /**
19 * @defgroup keymat keymat
20 * @{ @ingroup sa
21 */
22
23 #ifndef KEYMAT_H_
24 #define KEYMAT_H_
25
26 #include <library.h>
27 #include <utils/identification.h>
28 #include <crypto/prfs/prf.h>
29 #include <crypto/crypters/crypter.h>
30 #include <crypto/signers/signer.h>
31 #include <config/proposal.h>
32 #include <sa/ike_sa_id.h>
33
34 typedef struct keymat_t keymat_t;
35
36 /**
37 * Derivation an management of sensitive keying material.
38 */
39 struct keymat_t {
40
41 /**
42 * Create a diffie hellman object for key agreement.
43 *
44 * The diffie hellman is either for IKE negotiation/rekeying or
45 * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
46 * to derive_keys or to derive_child_keys and destroyed after use
47 *
48 * @param group diffie hellman group
49 * @return DH object, NULL if group not supported
50 */
51 diffie_hellman_t* (*create_dh)(keymat_t *this, diffie_hellman_group_t group);
52
53 /**
54 * Derive keys for the IKE_SA.
55 *
56 * These keys are not handed out, but are used by the associated signers,
57 * crypters and authentication functions.
58 *
59 * @param proposal selected algorithms
60 * @param dh diffie hellman key allocated by create_dh()
61 * @param nonce_i initiators nonce value
62 * @param nonce_r responders nonce value
63 * @param id IKE_SA identifier
64 * @param rekey_prf PRF of old SA if rekeying, PRF_UNDEFINED otherwise
65 * @param rekey_sdk SKd of old SA if rekeying
66 * @return TRUE on success
67 */
68 bool (*derive_ike_keys)(keymat_t *this, proposal_t *proposal,
69 diffie_hellman_t *dh, chunk_t nonce_i,
70 chunk_t nonce_r, ike_sa_id_t *id,
71 pseudo_random_function_t rekey_function,
72 chunk_t rekey_skd);
73 /**
74 * Derive keys for a CHILD_SA.
75 *
76 * The keys for the CHILD_SA are allocated in the integ and encr chunks.
77 * An implementation might hand out encrypted keys only, which are
78 * decrypted in the kernel before use.
79 * If no PFS is used for the CHILD_SA, dh can be NULL.
80 *
81 * @param proposal selected algorithms
82 * @param dh diffie hellman key allocated by create_dh(), or NULL
83 * @param nonce_i initiators nonce value
84 * @param nonce_r responders nonce value
85 * @param encr_i chunk to write initiators encryption key to
86 * @param integ_i chunk to write initiators integrity key to
87 * @param encr_r chunk to write responders encryption key to
88 * @param integ_r chunk to write responders integrity key to
89 * @return TRUE on success
90 */
91 bool (*derive_child_keys)(keymat_t *this,
92 proposal_t *proposal, diffie_hellman_t *dh,
93 chunk_t nonce_i, chunk_t nonce_r,
94 chunk_t *encr_i, chunk_t *integ_i,
95 chunk_t *encr_r, chunk_t *integ_r);
96 /**
97 * Get SKd to pass to derive_ikey_keys() during rekeying.
98 *
99 * @param skd chunk to write SKd to (internal data)
100 * @return PRF function to derive keymat
101 */
102 pseudo_random_function_t (*get_skd)(keymat_t *this, chunk_t *skd);
103
104 /**
105 * Get a signer to sign/verify IKE messages.
106 *
107 * @param in TRUE for inbound (verify), FALSE for outbound (sign)
108 * @return signer
109 */
110 signer_t* (*get_signer)(keymat_t *this, bool in);
111
112 /*
113 * Get a crypter to en-/decrypt IKE messages.
114 *
115 * @param in TRUE for inbound (decrypt), FALSE for outbound (encrypt)
116 * @return crypter
117 */
118 crypter_t* (*get_crypter)(keymat_t *this, bool in);
119
120 /**
121 * Generate octets to use for authentication procedure (RFC4306 2.15).
122 *
123 * This method creates the plain octets and is usually signed by a private
124 * key. PSK and EAP authentication include a secret into the data, use
125 * the get_psk_sig() method instead.
126 *
127 * @param verify TRUE to create for verfification, FALSE to sign
128 * @param ike_sa_init encoded ike_sa_init message
129 * @param nonce nonce value
130 * @param id identity
131 * @return authentication octets
132 */
133 chunk_t (*get_auth_octets)(keymat_t *this, bool verify, chunk_t ike_sa_init,
134 chunk_t nonce, identification_t *id);
135 /**
136 * Build the shared secret signature used for PSK and EAP authentication.
137 *
138 * This method wraps the get_auth_octets() method and additionally
139 * includes the secret into the signature. If no secret is given, SK_p is
140 * used as secret (used for EAP methods without MSK).
141 *
142 * @param verify TRUE to create for verfification, FALSE to sign
143 * @param ike_sa_init encoded ike_sa_init message
144 * @param nonce nonce value
145 * @param secret optional secret to include into signature
146 * @param id identity
147 * @return signature octets
148 */
149 chunk_t (*get_psk_sig)(keymat_t *this, bool verify, chunk_t ike_sa_init,
150 chunk_t nonce, chunk_t secret, identification_t *id);
151 /**
152 * Destroy a keymat_t.
153 */
154 void (*destroy)(keymat_t *this);
155 };
156
157 /**
158 * Create a keymat instance.
159 *
160 * @param initiator TRUE if we are the initiator
161 * @return keymat instance
162 */
163 keymat_t *keymat_create(bool initiator);
164
165 #endif /* KEYMAT_ @}*/