src/libcharon/sa/authenticators/authenticator.h

   1 /*
   2  * Copyright (C) 2005-2009 Martin Willi
   3  * Copyright (C) 2008 Tobias Brunner
   4  * Copyright (C) 2005 Jan Hutter
   5  * Hochschule fuer Technik Rapperswil
   6  *
   7  * This program is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License as published by the
   9  * Free Software Foundation; either version 2 of the License, or (at your
  10  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  11  *
  12  * This program is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  14  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  * for more details.
  16  */
  17
  18 /**
  19  * @defgroup authenticator authenticator
  20  * @{ @ingroup authenticators
  21  */
  22
  23 #ifndef AUTHENTICATOR_H_
  24 #define AUTHENTICATOR_H_
  25
  26 typedef enum auth_method_t auth_method_t;
  27 typedef struct authenticator_t authenticator_t;
  28
  29 #include <library.h>
  30 #include <credentials/auth_cfg.h>
  31 #include <sa/ike_sa.h>
  32
  33 /**
  34  * Method to use for authentication, as defined in IKEv2.
  35  */
  36 enum auth_method_t {
  37         /**
  38          * Computed as specified in section 2.15 of RFC using
  39          * an RSA private key over a PKCS#1 padded hash.
  40          */
  41         AUTH_RSA = 1,
  42
  43         /**
  44          * Computed as specified in section 2.15 of RFC using the
  45          * shared key associated with the identity in the ID payload
  46          * and the negotiated prf function
  47          */
  48         AUTH_PSK = 2,
  49
  50         /**
  51          * Computed as specified in section 2.15 of RFC using a
  52          * DSS private key over a SHA-1 hash.
  53          */
  54         AUTH_DSS = 3,
  55
  56         /**
  57          * ECDSA with SHA-256 on the P-256 curve as specified in RFC 4754
  58          */
  59         AUTH_ECDSA_256 = 9,
  60
  61         /**
  62          * ECDSA with SHA-384 on the P-384 curve as specified in RFC 4754
  63          */
  64         AUTH_ECDSA_384 = 10,
  65
  66         /**
  67          * ECDSA with SHA-512 on the P-521 curve as specified in RFC 4754
  68          */
  69         AUTH_ECDSA_521 = 11,
  70 };
  71
  72 /**
  73  * enum names for auth_method_t.
  74  */
  75 extern enum_name_t *auth_method_names;
  76
  77 /**
  78  * Authenticator interface implemented by the various authenticators.
  79  *
  80  * An authenticator implementation handles AUTH and EAP payloads. Received
  81  * messages are passed to the process() method, to send authentication data
  82  * the message is passed to the build() method.
  83  */
  84 struct authenticator_t {
  85
  86         /**
  87          * Process an incoming message using the authenticator.
  88          *
  89          * @param message               message containing authentication payloads
  90          * @return
  91          *                                              - SUCCESS if authentication successful
  92          *                                              - FAILED if authentication failed
  93          *                                              - NEED_MORE if another exchange required
  94          */
  95         status_t (*process)(authenticator_t *this, message_t *message);
  96
  97         /**
  98          * Attach authentication data to an outgoing message.
  99          *
 100          * @param message               message to add authentication data to
 101          * @return
 102          *                                              - SUCCESS if authentication successful
 103          *                                              - FAILED if authentication failed
 104          *                                              - NEED_MORE if another exchange required
 105          */
 106         status_t (*build)(authenticator_t *this, message_t *message);
 107
 108         /**
 109          * Check if the authenticator is capable of mutual authentication.
 110          *
 111          * Some authenticator authenticate both peers, e.g. EAP. To support
 112          * mutual authentication with only a single authenticator (EAP-only
 113          * authentication), it must be mutual. This method is invoked in ike_auth
 114          * to check if the given authenticator is capable of doing so.
 115          */
 116         bool (*is_mutual)(authenticator_t *this);
 117
 118         /**
 119          * Destroy authenticator instance.
 120          */
 121         void (*destroy) (authenticator_t *this);
 122 };
 123
 124 /**
 125  * Create an authenticator to build signatures.
 126  *
 127  * @param ike_sa                        associated ike_sa
 128  * @param cfg                           authentication configuration
 129  * @param received_nonce        nonce received in IKE_SA_INIT
 130  * @param sent_nonce            nonce sent in IKE_SA_INIT
 131  * @param received_init         received IKE_SA_INIT message data
 132  * @param sent_init                     sent IKE_SA_INIT message data
 133  * @param reserved                      reserved bytes of the ID payload
 134  * @return                                      authenticator, NULL if not supported
 135  */
 136 authenticator_t *authenticator_create_builder(
 137                                                                         ike_sa_t *ike_sa, auth_cfg_t *cfg,
 138                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 139                                                                         chunk_t received_init, chunk_t sent_init,
 140                                                                         char reserved[3]);
 141
 142 /**
 143  * Create an authenticator to verify signatures.
 144  *
 145  * @param ike_sa                        associated ike_sa
 146  * @param message                       message containing authentication data
 147  * @param received_nonce        nonce received in IKE_SA_INIT
 148  * @param sent_nonce            nonce sent in IKE_SA_INIT
 149  * @param received_init         received IKE_SA_INIT message data
 150  * @param sent_init                     sent IKE_SA_INIT message data
 151  * @param reserved                      reserved bytes of the ID payload
 152  * @return                                      authenticator, NULL if not supported
 153  */
 154 authenticator_t *authenticator_create_verifier(
 155                                                                         ike_sa_t *ike_sa, message_t *message,
 156                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 157                                                                         chunk_t received_init, chunk_t sent_init,
 158                                                                         char reserved[3]);
 159
 160 #endif /** AUTHENTICATOR_H_ @}*/