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  * $Id$
  16  */
  17
  18 /**
  19  * @defgroup keymat keymat
  20  * @{ @ingroup sa
  21  */
  22
  23 #ifndef KEYMAT_H_
  24 #define KEYMAT_H_
  25
  26 #include <library.h>
  27 #include <utils/identification.h>
  28 #include <crypto/prfs/prf.h>
  29 #include <crypto/crypters/crypter.h>
  30 #include <crypto/signers/signer.h>
  31 #include <config/proposal.h>
  32 #include <sa/ike_sa_id.h>
  33
  34 typedef struct keymat_t keymat_t;
  35
  36 /**
  37  * Derivation an management of sensitive keying material.
  38  */
  39 struct keymat_t {
  40
  41         /**
  42          * Create a diffie hellman object for key agreement.
  43          *
  44          * The diffie hellman is either for IKE negotiation/rekeying or
  45          * CHILD_SA rekeying (using PFS). The resulting DH object must be passed
  46          * to derive_ike_keys or to derive_child_keys and destroyed after use
  47          *
  48          * @param group                 diffie hellman group
  49          * @return                              DH object, NULL if group not supported
  50          */
  51         diffie_hellman_t* (*create_dh)(keymat_t *this, diffie_hellman_group_t group);
  52
  53         /**
  54          * Derive keys from the shared secret.
  55          *
  56          * @param proposal      selected algorithms
  57          * @param nonce_i       initiators nonce value
  58          * @param nonce_r       responders nonce value
  59          * @param id            IKE_SA identifier
  60          * @param rekey         keymat of old SA if we are rekeying
  61          * @return                      TRUE on success
  62          */
  63         bool (*derive_keys)(keymat_t *this, proposal_t *proposal,
  64                                                 diffie_hellman_t *dh, chunk_t nonce_i, chunk_t nonce_r,
  65                                                 ike_sa_id_t *id, keymat_t *rekey);
  66         /**
  67          * Get a signer to sign/verify IKE messages.
  68          *
  69          * @param in            TRUE for inbound (verify), FALSE for outbound (sign)
  70          * @return                      signer
  71          */
  72         signer_t* (*get_signer)(keymat_t *this, bool in);
  73
  74         /*
  75          * Get a crypter to en-/decrypt IKE messages.
  76          *
  77          * @param in            TRUE for inbound (decrypt), FALSE for outbound (encrypt)
  78          * @return                      crypter
  79          */
  80         crypter_t* (*get_crypter)(keymat_t *this, bool in);
  81
  82         /**
  83          * Get a keyed PRF to derive keymat for children.
  84          *
  85          * @return                      PRF to derive CHILD_SA keymat from
  86          */
  87         prf_t* (*get_child_prf)(keymat_t *this);
  88
  89         /**
  90          * Get the selected proposal passed to derive_keys().
  91          *
  92          * @return                      selected proposal
  93          */
  94         proposal_t* (*get_proposal)(keymat_t *this);
  95
  96         /**
  97          * Generate octets to use for authentication procedure (RFC4306 2.15).
  98          *
  99          * This method creates the plain octets and is usually signed by a private
 100          * key. PSK and EAP authentication include a secret into the data, use
 101          * the get_psk_sig() method instead.
 102          *
 103          * @param verify                TRUE to create for verfification, FALSE to sign
 104          * @param ike_sa_init   encoded ike_sa_init message
 105          * @param nonce                 nonce value
 106          * @param id                    identity
 107          * @return                              authentication octets
 108          */
 109         chunk_t (*get_auth_octets)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 110                                                            chunk_t nonce, identification_t *id);
 111         /**
 112          * Build the shared secret signature used for PSK and EAP authentication.
 113          *
 114          * This method wraps the get_auth_octets() method and additionally
 115          * includes the secret into the signature. If no secret is given, SK_p is
 116          * used as secret (used for EAP methods without MSK).
 117          *
 118          * @param verify                TRUE to create for verfification, FALSE to sign
 119          * @param ike_sa_init   encoded ike_sa_init message
 120          * @param nonce                 nonce value
 121          * @param secret                optional secret to include into signature
 122          * @param id                    identity
 123          * @return                              signature octets
 124          */
 125         chunk_t (*get_psk_sig)(keymat_t *this, bool verify, chunk_t ike_sa_init,
 126                                                    chunk_t nonce, chunk_t secret, identification_t *id);
 127         /**
 128          * Destroy a keymat_t.
 129          */
 130         void (*destroy)(keymat_t *this);
 131 };
 132
 133 /**
 134  * Create a keymat instance.
 135  *
 136  * @param initiator             TRUE if we are the initiator
 137  * @return                              keymat instance
 138  */
 139 keymat_t *keymat_create(bool initiator);
 140
 141 #endif /* KEYMAT_ @}*/