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 /**
 151  * Create a keymat instance.
 152  *
 153  * @param initiator             TRUE if we are the initiator
 154  * @return                              keymat instance
 155  */
 156 keymat_t *keymat_create(bool initiator);
 157
 158 #endif /** KEYMAT_H_ @}*/