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