src/charon/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 enum auth_class_t auth_class_t;
  28 typedef struct authenticator_t authenticator_t;
  29
  30 #include <library.h>
  31 #include <config/auth_cfg.h>
  32 #include <sa/ike_sa.h>
  33
  34 /**
  35  * Method to use for authentication, as defined in IKEv2.
  36  */
  37 enum auth_method_t {
  38         /**
  39          * Computed as specified in section 2.15 of RFC using
  40          * an RSA private key over a PKCS#1 padded hash.
  41          */
  42         AUTH_RSA = 1,
  43
  44         /**
  45          * Computed as specified in section 2.15 of RFC using the
  46          * shared key associated with the identity in the ID payload
  47          * and the negotiated prf function
  48          */
  49         AUTH_PSK = 2,
  50
  51         /**
  52          * Computed as specified in section 2.15 of RFC using a
  53          * DSS private key over a SHA-1 hash.
  54          */
  55         AUTH_DSS = 3,
  56
  57         /**
  58          * ECDSA with SHA-256 on the P-256 curve as specified in RFC 4754
  59          */
  60         AUTH_ECDSA_256 = 9,
  61
  62         /**
  63          * ECDSA with SHA-384 on the P-384 curve as specified in RFC 4754
  64          */
  65         AUTH_ECDSA_384 = 10,
  66
  67         /**
  68          * ECDSA with SHA-512 on the P-521 curve as specified in RFC 4754
  69          */
  70         AUTH_ECDSA_521 = 11,
  71 };
  72
  73 /**
  74  * enum names for auth_method_t.
  75  */
  76 extern enum_name_t *auth_method_names;
  77
  78 /**
  79  * Class of authentication to use. This is different to auth_method_t in that
  80  * it does not specify a method, but a class of acceptable methods. The found
  81  * certificate finally dictates wich method is used.
  82  */
  83 enum auth_class_t {
  84         /** any class acceptable */
  85         AUTH_CLASS_ANY = 0,
  86         /** authentication using public keys (RSA, ECDSA) */
  87         AUTH_CLASS_PUBKEY = 1,
  88         /** authentication using a pre-shared secrets */
  89         AUTH_CLASS_PSK = 2,
  90         /** authentication using EAP */
  91         AUTH_CLASS_EAP = 3,
  92 };
  93
  94 /**
  95  * enum strings for auth_class_t
  96  */
  97 extern enum_name_t *auth_class_names;
  98
  99 /**
 100  * Authenticator interface implemented by the various authenticators.
 101  *
 102  * An authenticator implementation handles AUTH and EAP payloads. Received
 103  * messages are passed to the process() method, to send authentication data
 104  * the message is passed to the build() method.
 105  */
 106 struct authenticator_t {
 107
 108         /**
 109          * Process an incoming message using the authenticator.
 110          *
 111          * @param message               message containing authentication payloads
 112          * @return
 113          *                                              - SUCCESS if authentication successful
 114          *                                              - FAILED if authentication failed
 115          *                                              - NEED_MORE if another exchange required
 116          */
 117         status_t (*process)(authenticator_t *this, message_t *message);
 118
 119         /**
 120          * Attach authentication data to an outgoing message.
 121          *
 122          * @param message               message to add authentication data to
 123          * @return
 124          *                                              - SUCCESS if authentication successful
 125          *                                              - FAILED if authentication failed
 126          *                                              - NEED_MORE if another exchange required
 127          */
 128         status_t (*build)(authenticator_t *this, message_t *message);
 129
 130         /**
 131          * Check if the authenticator is capable of mutual authentication.
 132          *
 133          * Some authenticator authenticate both peers, e.g. EAP. To support
 134          * mutual authentication with only a single authenticator (EAP-only
 135          * authentication), it must be mutual. This method is invoked in ike_auth
 136          * to check if the given authenticator is capable of doing so.
 137          */
 138         bool (*is_mutual)(authenticator_t *this);
 139
 140         /**
 141          * Destroy authenticator instance.
 142          */
 143         void (*destroy) (authenticator_t *this);
 144 };
 145
 146 /**
 147  * Create an authenticator to build signatures.
 148  *
 149  * @param ike_sa                        associated ike_sa
 150  * @param cfg                           authentication configuration
 151  * @param received_nonce        nonce received in IKE_SA_INIT
 152  * @param sent_nonce            nonce sent in IKE_SA_INIT
 153  * @param received_init         received IKE_SA_INIT message data
 154  * @param sent_init                     sent IKE_SA_INIT message data
 155  * @return                                      authenticator, NULL if not supported
 156  */
 157 authenticator_t *authenticator_create_builder(
 158                                                                         ike_sa_t *ike_sa, auth_cfg_t *cfg,
 159                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 160                                                                         chunk_t received_init, chunk_t sent_init);
 161
 162 /**
 163  * Create an authenticator to verify signatures.
 164  *
 165  * @param ike_sa                        associated ike_sa
 166  * @param message                       message containing authentication data
 167  * @param received_nonce        nonce received in IKE_SA_INIT
 168  * @param sent_nonce            nonce sent in IKE_SA_INIT
 169  * @param received_init         received IKE_SA_INIT message data
 170  * @param sent_init                     sent IKE_SA_INIT message data
 171  * @return                                      authenticator, NULL if not supported
 172  */
 173 authenticator_t *authenticator_create_verifier(
 174                                                                         ike_sa_t *ike_sa, message_t *message,
 175                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 176                                                                         chunk_t received_init, chunk_t sent_init);
 177
 178 #endif /** AUTHENTICATOR_H_ @}*/