src/charon/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/crypters/crypter.h>
  28 #include <crypto/signers/signer.h>
  29 #include <config/proposal.h>
  30 #include <sa/ike_sa_id.h>
  31
  32 typedef struct keymat_t keymat_t;
  33
  34 /**
  35  * Derivation an management of sensitive keying material.
  36  */
  37 struct keymat_t {
  38
  39         /**
  40          * Create a diffie hellman object for key agreement.
  41          *
  42          * The diffie hellman is either for IKE negotiation/rekeying or
  43          * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
  44          * to derive_keys or to derive_child_keys and destroyed after use
  45          *
  46          * @param group                 diffie hellman group
  47          * @return                              DH object, NULL if group not supported
  48          */
  49         diffie_hellman_t* (*create_dh)(keymat_t *this, diffie_hellman_group_t group);
  50
  51         /**
  52          * Derive keys for the IKE_SA.
  53          *
  54          * These keys are not handed out, but are used by the associated signers,
  55          * crypters and authentication functions.
  56          *
  57          * @param proposal      selected algorithms
  58          * @param dh            diffie hellman key allocated by create_dh()
  59          * @param nonce_i       initiators nonce value
  60          * @param nonce_r       responders nonce value
  61          * @param id            IKE_SA identifier
  62          * @param rekey_prf     PRF of old SA if rekeying, PRF_UNDEFINED otherwise
  63          * @param rekey_sdk     SKd of old SA if rekeying
  64          * @return                      TRUE on success
  65          */
  66         bool (*derive_ike_keys)(keymat_t *this, proposal_t *proposal,
  67                                                         diffie_hellman_t *dh, chunk_t nonce_i,
  68                                                         chunk_t nonce_r, ike_sa_id_t *id,
  69                                                         pseudo_random_function_t rekey_function,
  70                                                         chunk_t rekey_skd);
  71         /**
  72          * Derive keys for a CHILD_SA.
  73          *
  74          * The keys for the CHILD_SA are allocated in the integ and encr chunks.
  75          * An implementation might hand out encrypted keys only, which are
  76          * decrypted in the kernel before use.
  77          * If no PFS is used for the CHILD_SA, dh can be NULL.
  78          *
  79          * @param proposal      selected algorithms
  80          * @param dh            diffie hellman key allocated by create_dh(), or NULL
  81          * @param nonce_i       initiators nonce value
  82          * @param nonce_r       responders nonce value
  83          * @param encr_i        chunk to write initiators encryption key to
  84          * @param integ_i       chunk to write initiators integrity key to
  85          * @param encr_r        chunk to write responders encryption key to
  86          * @param integ_r       chunk to write responders integrity key to
  87          * @return                      TRUE on success
  88          */
  89         bool (*derive_child_keys)(keymat_t *this,
  90                                                           proposal_t *proposal, diffie_hellman_t *dh,
  91                                                           chunk_t nonce_i, chunk_t nonce_r,
  92                                                           chunk_t *encr_i, chunk_t *integ_i,
  93                                                           chunk_t *encr_r, chunk_t *integ_r);
  94         /**
  95          * Get SKd to pass to derive_ikey_keys() during rekeying.
  96          *
  97          * @param skd           chunk to write SKd to (internal data)
  98          * @return                      PRF function to derive keymat
  99          */
 100         pseudo_random_function_t (*get_skd)(keymat_t *this, chunk_t *skd);
 101
 102         /**
 103          * Get a signer to sign/verify IKE messages.
 104          *
 105          * @param in            TRUE for inbound (verify), FALSE for outbound (sign)
 106          * @return                      signer
 107          */
 108         signer_t* (*get_signer)(keymat_t *this, bool in);
 109
 110         /*
 111          * Get a crypter to en-/decrypt IKE messages.
 112          *
 113          * @param in            TRUE for inbound (decrypt), FALSE for outbound (encrypt)
 114          * @return                      crypter
 115          */
 116         crypter_t* (*get_crypter)(keymat_t *this, bool in);
 117
 118         /**
 119          * Generate octets to use for authentication procedure (RFC4306 2.15).
 120          *
 121          * This method creates the plain octets and is usually signed by a private
 122          * key. PSK and EAP authentication include a secret into the data, use
 123          * the get_psk_sig() method instead.
 124          *
 125          * @param verify                TRUE to create for verfification, FALSE to sign
 126          * @param ike_sa_init   encoded ike_sa_init message
 127          * @param nonce                 nonce value
 128          * @param id                    identity
 129          * @return                              authentication octets
 130          */
 131         chunk_t (*get_auth_octets)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 132                                                            chunk_t nonce, identification_t *id);
 133         /**
 134          * Build the shared secret signature used for PSK and EAP authentication.
 135          *
 136          * This method wraps the get_auth_octets() method and additionally
 137          * includes the secret into the signature. If no secret is given, SK_p is
 138          * used as secret (used for EAP methods without MSK).
 139          *
 140          * @param verify                TRUE to create for verfification, FALSE to sign
 141          * @param ike_sa_init   encoded ike_sa_init message
 142          * @param nonce                 nonce value
 143          * @param secret                optional secret to include into signature
 144          * @param id                    identity
 145          * @return                              signature octets
 146          */
 147         chunk_t (*get_psk_sig)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 148                                                    chunk_t nonce, chunk_t secret, identification_t *id);
 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_ @}*/