Merge branch 'trap-manager-uninstall'
[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 typedef struct keymat_t keymat_t;
25
26 #include <library.h>
27 #include <utils/identification.h>
28 #include <crypto/prfs/prf.h>
29 #include <crypto/aead.h>
30 #include <crypto/proposal/proposal.h>
31 #include <config/peer_cfg.h>
32 #include <sa/ike_sa_id.h>
33
34 /**
35 * Constructor function for custom keymat implementations
36 *
37 * @param initiator TRUE if the keymat is used as initiator
38 * @return keymat_t implementation
39 */
40 typedef keymat_t* (*keymat_constructor_t)(bool initiator);
41
42 /**
43 * Derivation an management of sensitive keying material.
44 */
45 struct keymat_t {
46
47 /**
48 * Get IKE version of this keymat.
49 *
50 * @return IKEV1 for keymat_v1_t, IKEV2 for keymat_v2_t
51 */
52 ike_version_t (*get_version)(keymat_t *this);
53
54 /**
55 * Create a diffie hellman object for key agreement.
56 *
57 * The diffie hellman is either for IKE negotiation/rekeying or
58 * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
59 * to derive_keys or to derive_child_keys and destroyed after use.
60 *
61 * Only DH objects allocated through this method are passed to other
62 * keymat_t methods, allowing private DH implementations. In some cases
63 * (such as retrying with a COOKIE), a DH object allocated from a different
64 * keymat_t instance may be passed to other methods.
65 *
66 * @param group diffie hellman group
67 * @return DH object, NULL if group not supported
68 */
69 diffie_hellman_t* (*create_dh)(keymat_t *this,
70 diffie_hellman_group_t group);
71
72 /**
73 * Create a nonce generator object.
74 *
75 * The nonce generator can be used to create nonces needed during IKE/CHILD
76 * SA establishment or rekeying.
77 *
78 * @return nonce generator object
79 */
80 nonce_gen_t* (*create_nonce_gen)(keymat_t *this);
81
82 /**
83 * Get a AEAD transform to en-/decrypt and sign/verify IKE messages.
84 *
85 * @param in TRUE for inbound (decrypt), FALSE for outbound (encrypt)
86 * @return crypter
87 */
88 aead_t* (*get_aead)(keymat_t *this, bool in);
89
90 /**
91 * Destroy a keymat_t.
92 */
93 void (*destroy)(keymat_t *this);
94 };
95
96 /**
97 * Create the appropriate keymat_t implementation based on the IKE version.
98 *
99 * @param version requested IKE version
100 * @param initiator TRUE if we are initiator
101 * @return keymat_t implmenetation
102 */
103 keymat_t *keymat_create(ike_version_t version, bool initiator);
104
105 /**
106 * Look up the key length of an encryption algorithm.
107 *
108 * @param alg algorithm to get key length for
109 * @return key length in bits
110 */
111 int keymat_get_keylen_encr(encryption_algorithm_t alg);
112
113 /**
114 * Look up the key length of an integrity algorithm.
115 *
116 * @param alg algorithm to get key length for
117 * @return key length in bits
118 */
119 int keymat_get_keylen_integ(integrity_algorithm_t alg);
120
121 /**
122 * Register keymat_t constructor for given IKE version.
123 *
124 * @param version IKE version of given keymat constructor
125 * @param create keymat constructor function, NULL to unregister
126 */
127 void keymat_register_constructor(ike_version_t version,
128 keymat_constructor_t create);
129
130 #endif /** KEYMAT_H_ @}*/