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          * Only DH objects allocated through this method are passed to other
  46          * keymat_t methods, allowing private DH implementations. In some cases
  47          * (such as retrying with a COOKIE), a DH object allocated from a different
  48          * keymat_t instance may be passed to other methods.
  49          *
  50          * @param group                 diffie hellman group
  51          * @return                              DH object, NULL if group not supported
  52          */
  53         diffie_hellman_t* (*create_dh)(keymat_t *this, diffie_hellman_group_t group);
  54
  55         /**
  56          * Derive keys for the IKE_SA.
  57          *
  58          * These keys are not handed out, but are used by the associated signers,
  59          * crypters and authentication functions.
  60          *
  61          * @param proposal      selected algorithms
  62          * @param dh            diffie hellman key allocated by create_dh()
  63          * @param nonce_i       initiators nonce value
  64          * @param nonce_r       responders nonce value
  65          * @param id            IKE_SA identifier
  66          * @param rekey_prf     PRF of old SA if rekeying, PRF_UNDEFINED otherwise
  67          * @param rekey_sdk     SKd of old SA if rekeying
  68          * @return                      TRUE on success
  69          */
  70         bool (*derive_ike_keys)(keymat_t *this, proposal_t *proposal,
  71                                                         diffie_hellman_t *dh, chunk_t nonce_i,
  72                                                         chunk_t nonce_r, ike_sa_id_t *id,
  73                                                         pseudo_random_function_t rekey_function,
  74                                                         chunk_t rekey_skd);
  75         /**
  76          * Derive keys for a CHILD_SA.
  77          *
  78          * The keys for the CHILD_SA are allocated in the integ and encr chunks.
  79          * An implementation might hand out encrypted keys only, which are
  80          * decrypted in the kernel before use.
  81          * If no PFS is used for the CHILD_SA, dh can be NULL.
  82          *
  83          * @param proposal      selected algorithms
  84          * @param dh            diffie hellman key allocated by create_dh(), or NULL
  85          * @param nonce_i       initiators nonce value
  86          * @param nonce_r       responders nonce value
  87          * @param encr_i        chunk to write initiators encryption key to
  88          * @param integ_i       chunk to write initiators integrity key to
  89          * @param encr_r        chunk to write responders encryption key to
  90          * @param integ_r       chunk to write responders integrity key to
  91          * @return                      TRUE on success
  92          */
  93         bool (*derive_child_keys)(keymat_t *this,
  94                                                           proposal_t *proposal, diffie_hellman_t *dh,
  95                                                           chunk_t nonce_i, chunk_t nonce_r,
  96                                                           chunk_t *encr_i, chunk_t *integ_i,
  97                                                           chunk_t *encr_r, chunk_t *integ_r);
  98         /**
  99          * Get SKd to pass to derive_ikey_keys() during rekeying.
 100          *
 101          * @param skd           chunk to write SKd to (internal data)
 102          * @return                      PRF function to derive keymat
 103          */
 104         pseudo_random_function_t (*get_skd)(keymat_t *this, chunk_t *skd);
 105
 106         /*
 107          * Get a AEAD transform to en-/decrypt and sign/verify IKE messages.
 108          *
 109          * @param in            TRUE for inbound (decrypt), FALSE for outbound (encrypt)
 110          * @return                      crypter
 111          */
 112         aead_t* (*get_aead)(keymat_t *this, bool in);
 113
 114         /**
 115          * Generate octets to use for authentication procedure (RFC4306 2.15).
 116          *
 117          * This method creates the plain octets and is usually signed by a private
 118          * key. PSK and EAP authentication include a secret into the data, use
 119          * the get_psk_sig() method instead.
 120          *
 121          * @param verify                TRUE to create for verfification, FALSE to sign
 122          * @param ike_sa_init   encoded ike_sa_init message
 123          * @param nonce                 nonce value
 124          * @param id                    identity
 125          * @param reserved              reserved bytes of id_payload
 126          * @return                              authentication octets
 127          */
 128         chunk_t (*get_auth_octets)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 129                                                            chunk_t nonce, identification_t *id,
 130                                                            char reserved[3]);
 131         /**
 132          * Build the shared secret signature used for PSK and EAP authentication.
 133          *
 134          * This method wraps the get_auth_octets() method and additionally
 135          * includes the secret into the signature. If no secret is given, SK_p is
 136          * used as secret (used for EAP methods without MSK).
 137          *
 138          * @param verify                TRUE to create for verfification, FALSE to sign
 139          * @param ike_sa_init   encoded ike_sa_init message
 140          * @param nonce                 nonce value
 141          * @param secret                optional secret to include into signature
 142          * @param id                    identity
 143          * @param reserved              reserved bytes of id_payload
 144          * @return                              signature octets
 145          */
 146         chunk_t (*get_psk_sig)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 147                                                    chunk_t nonce, chunk_t secret,
 148                                                    identification_t *id, char reserved[3]);
 149         /**
 150          * Destroy a keymat_t.
 151          */
 152         void (*destroy)(keymat_t *this);
 153 };
 154
 155 /**
 156  * Create a keymat instance.
 157  *
 158  * @param initiator             TRUE if we are the initiator
 159  * @return                              keymat instance
 160  */
 161 keymat_t *keymat_create(bool initiator);
 162
 163 #endif /** KEYMAT_H_ @}*/