src/libcharon/sa/ikev2/keymat_v2.h

   1 /*
   2  * Copyright (C) 2011-2015 Tobias Brunner
   3  * HSR 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_v2 keymat_v2
  18  * @{ @ingroup ikev2
  19  */
  20
  21 #ifndef KEYMAT_V2_H_
  22 #define KEYMAT_V2_H_
  23
  24 #include <sa/keymat.h>
  25 #include <collections/array.h>
  26
  27 typedef struct keymat_v2_t keymat_v2_t;
  28
  29 /**
  30  * Derivation and management of sensitive keying material, IKEv2 variant.
  31  */
  32 struct keymat_v2_t {
  33
  34         /**
  35          * Implements keymat_t.
  36          */
  37         keymat_t keymat;
  38
  39         /**
  40          * Derive keys for the IKE_SA.
  41          *
  42          * These keys are not handed out, but are used by the associated signers,
  43          * crypters and authentication functions.
  44          *
  45          * @param proposal      selected algorithms
  46          * @param dh            diffie hellman key allocated by create_dh()
  47          * @param nonce_i       initiators nonce value
  48          * @param nonce_r       responders nonce value
  49          * @param id            IKE_SA identifier
  50          * @param rekey_prf     PRF of old SA if rekeying, PRF_UNDEFINED otherwise
  51          * @param rekey_sdk     SKd of old SA if rekeying
  52          * @return                      TRUE on success
  53          */
  54         bool (*derive_ike_keys)(keymat_v2_t *this, proposal_t *proposal,
  55                                                         diffie_hellman_t *dh, chunk_t nonce_i,
  56                                                         chunk_t nonce_r, ike_sa_id_t *id,
  57                                                         pseudo_random_function_t rekey_function,
  58                                                         chunk_t rekey_skd);
  59
  60         /**
  61          * Derive SK_d, SK_pi and SK_pr after authentication using the given
  62          * Postquantum Preshared Key and the previous values of these keys that
  63          * were derived by derive_ike_keys().
  64          *
  65          * @param ppk           the postquantum preshared key
  66          * @return                      TRUE on success
  67          */
  68         bool (*derive_ike_keys_ppk)(keymat_v2_t *this, chunk_t ppk);
  69
  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_v2_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_v2_t *this, chunk_t *skd);
 100
 101         /**
 102          * Generate octets to use for authentication procedure (RFC4306 2.15).
 103          *
 104          * This method creates the plain octets and is usually signed by a private
 105          * key. PSK and EAP authentication include a secret into the data, use
 106          * the get_psk_sig() method instead.
 107          *
 108          * @param verify                TRUE to create for verification, FALSE to sign
 109          * @param ike_sa_init   encoded ike_sa_init message
 110          * @param nonce                 nonce value
 111          * @param ppk                   optional postquantum preshared key
 112          * @param id                    identity
 113          * @param reserved              reserved bytes of id_payload
 114          * @param octests               chunk receiving allocated auth octets
 115          * @param schemes               array containing signature schemes
 116          *                                              (signature_params_t*) in case they need to be
 117          *                                              modified by the keymat implementation
 118          * @return                              TRUE if octets created successfully
 119          */
 120         bool (*get_auth_octets)(keymat_v2_t *this, bool verify, chunk_t ike_sa_init,
 121                                                         chunk_t nonce, chunk_t ppk, identification_t *id,
 122                                                         char reserved[3], chunk_t *octets,
 123                                                         array_t *schemes);
 124         /**
 125          * Build the shared secret signature used for PSK and EAP authentication.
 126          *
 127          * This method wraps the get_auth_octets() method and additionally
 128          * includes the secret into the signature. If no secret is given, SK_p is
 129          * used as secret (used for EAP methods without MSK).
 130          *
 131          * @param verify                TRUE to create for verification, FALSE to sign
 132          * @param ike_sa_init   encoded ike_sa_init message
 133          * @param nonce                 nonce value
 134          * @param secret                optional secret to include into signature
 135          * @param ppk                   optional postquantum preshared key
 136          * @param id                    identity
 137          * @param reserved              reserved bytes of id_payload
 138          * @param sign                  chunk receiving allocated signature octets
 139          * @return                              TRUE if signature created successfully
 140          */
 141         bool (*get_psk_sig)(keymat_v2_t *this, bool verify, chunk_t ike_sa_init,
 142                                                 chunk_t nonce, chunk_t secret, chunk_t ppk,
 143                                                 identification_t *id, char reserved[3], chunk_t *sig);
 144
 145         /**
 146          * Add a hash algorithm supported by the peer for signature authentication.
 147          *
 148          * @param hash                  hash algorithm
 149          */
 150         void (*add_hash_algorithm)(keymat_v2_t *this, hash_algorithm_t hash);
 151
 152         /**
 153          * Check if a given hash algorithm is supported by the peer for signature
 154          * authentication.
 155          *
 156          * @param hash                  hash algorithm
 157          * @return                              TRUE if supported, FALSE otherwise
 158          */
 159         bool (*hash_algorithm_supported)(keymat_v2_t *this, hash_algorithm_t hash);
 160 };
 161
 162 /**
 163  * Create a keymat instance.
 164  *
 165  * @param initiator                     TRUE if we are the initiator
 166  * @return                                      keymat instance
 167  */
 168 keymat_v2_t *keymat_v2_create(bool initiator);
 169
 170 #endif /** KEYMAT_V2_H_ @}*/