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