src/libcharon/sa/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 sa
  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         /**
  39          * No authentication used.
  40          */
  41         AUTH_NONE = 0,
  42
  43         /**
  44          * Computed as specified in section 2.15 of RFC using
  45          * an RSA private key over a PKCS#1 padded hash.
  46          */
  47         AUTH_RSA = 1,
  48
  49         /**
  50          * Computed as specified in section 2.15 of RFC using the
  51          * shared key associated with the identity in the ID payload
  52          * and the negotiated prf function
  53          */
  54         AUTH_PSK = 2,
  55
  56         /**
  57          * Computed as specified in section 2.15 of RFC using a
  58          * DSS private key over a SHA-1 hash.
  59          */
  60         AUTH_DSS = 3,
  61
  62         /**
  63          * ECDSA with SHA-256 on the P-256 curve as specified in RFC 4754
  64          */
  65         AUTH_ECDSA_256 = 9,
  66
  67         /**
  68          * ECDSA with SHA-384 on the P-384 curve as specified in RFC 4754
  69          */
  70         AUTH_ECDSA_384 = 10,
  71
  72         /**
  73          * ECDSA with SHA-512 on the P-521 curve as specified in RFC 4754
  74          */
  75         AUTH_ECDSA_521 = 11,
  76
  77         /**
  78          * Generic Secure Password Authentication Method as specified in RFC 6467
  79          */
  80         AUTH_GSPM = 12,
  81
  82         /**
  83          * NULL Authentication Method as specified in draft-ietf-ipsecme-ikev2-null-auth
  84          */
  85         AUTH_NULL = 13,
  86
  87         /**
  88          * Digital Signature as specified in RFC 7427
  89          */
  90         AUTH_DS = 14,
  91
  92         /**
  93          * BLISS Authentication Method
  94          */
  95         AUTH_BLISS = 220,
  96
  97         /**
  98          * IKEv1 initiator XAUTH with PSK, outside of IANA range
  99          */
 100         AUTH_XAUTH_INIT_PSK = 256,
 101
 102         /**
 103          * IKEv1 responder XAUTH with PSK, outside of IANA range
 104          */
 105         AUTH_XAUTH_RESP_PSK,
 106
 107         /**
 108          * IKEv1 initiator XAUTH with RSA, outside of IANA range
 109          */
 110         AUTH_XAUTH_INIT_RSA,
 111
 112         /**
 113          * IKEv1 responder XAUTH with RSA, outside of IANA range
 114          */
 115         AUTH_XAUTH_RESP_RSA,
 116
 117         /**
 118          * IKEv1 initiator XAUTH, responder RSA, outside of IANA range
 119          */
 120         AUTH_HYBRID_INIT_RSA,
 121
 122         /**
 123          * IKEv1 responder XAUTH, initiator RSA, outside of IANA range
 124          */
 125         AUTH_HYBRID_RESP_RSA,
 126 };
 127
 128 /**
 129  * enum names for auth_method_t.
 130  */
 131 extern enum_name_t *auth_method_names;
 132
 133 /**
 134  * Authenticator interface implemented by the various authenticators.
 135  *
 136  * An authenticator implementation handles AUTH and EAP payloads. Received
 137  * messages are passed to the process() method, to send authentication data
 138  * the message is passed to the build() method.
 139  */
 140 struct authenticator_t {
 141
 142         /**
 143          * Process an incoming message using the authenticator.
 144          *
 145          * @param message               message containing authentication payloads
 146          * @return
 147          *                                              - SUCCESS if authentication successful
 148          *                                              - FAILED if authentication failed
 149          *                                              - NEED_MORE if another exchange required
 150          */
 151         status_t (*process)(authenticator_t *this, message_t *message);
 152
 153         /**
 154          * Attach authentication data to an outgoing message.
 155          *
 156          * @param message               message to add authentication data to
 157          * @return
 158          *                                              - SUCCESS if authentication successful
 159          *                                              - FAILED if authentication failed
 160          *                                              - NEED_MORE if another exchange required
 161          */
 162         status_t (*build)(authenticator_t *this, message_t *message);
 163
 164         /**
 165          * Check if the authenticator is capable of mutual authentication.
 166          *
 167          * Some authenticator authenticate both peers, e.g. EAP. To support
 168          * mutual authentication with only a single authenticator (EAP-only
 169          * authentication), it must be mutual. This method is invoked in ike_auth
 170          * to check if the given authenticator is capable of doing so.
 171          */
 172         bool (*is_mutual)(authenticator_t *this);
 173
 174         /**
 175          * Destroy authenticator instance.
 176          */
 177         void (*destroy) (authenticator_t *this);
 178 };
 179
 180 /**
 181  * Create an IKEv2 authenticator to build signatures.
 182  *
 183  * @param ike_sa                        associated ike_sa
 184  * @param cfg                           authentication configuration
 185  * @param received_nonce        nonce received in IKE_SA_INIT
 186  * @param sent_nonce            nonce sent in IKE_SA_INIT
 187  * @param received_init         received IKE_SA_INIT message data
 188  * @param sent_init                     sent IKE_SA_INIT message data
 189  * @param reserved                      reserved bytes of the ID payload
 190  * @return                                      authenticator, NULL if not supported
 191  */
 192 authenticator_t *authenticator_create_builder(
 193                                                                         ike_sa_t *ike_sa, auth_cfg_t *cfg,
 194                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 195                                                                         chunk_t received_init, chunk_t sent_init,
 196                                                                         char reserved[3]);
 197
 198 /**
 199  * Create an IKEv2 authenticator to verify signatures.
 200  *
 201  * @param ike_sa                        associated ike_sa
 202  * @param message                       message containing authentication data
 203  * @param received_nonce        nonce received in IKE_SA_INIT
 204  * @param sent_nonce            nonce sent in IKE_SA_INIT
 205  * @param received_init         received IKE_SA_INIT message data
 206  * @param sent_init                     sent IKE_SA_INIT message data
 207  * @param reserved                      reserved bytes of the ID payload
 208  * @return                                      authenticator, NULL if not supported
 209  */
 210 authenticator_t *authenticator_create_verifier(
 211                                                                         ike_sa_t *ike_sa, message_t *message,
 212                                                                         chunk_t received_nonce, chunk_t sent_nonce,
 213                                                                         chunk_t received_init, chunk_t sent_init,
 214                                                                         char reserved[3]);
 215
 216 /**
 217  * Create an IKEv1 authenticator to build and verify signatures or hash
 218  * payloads.
 219  *
 220  * @note Due to the fixed ID, these authenticators can only be used in one
 221  * direction at a time.
 222  *
 223  * @param ike_sa                        associated IKE_SA
 224  * @param initiator                     TRUE if we are the IKE_SA initiator
 225  * @param auth_method           negotiated authentication method to use
 226  * @param dh                            diffie hellman key exchange
 227  * @param dh_value                      others public diffie hellman value
 228  * @param sa_payload            generated SA payload data, without payload header
 229  * @param id_payload            encoded ID payload of peer to authenticate or verify
 230  *                                                      without payload header (gets owned)
 231  * @return                                      authenticator, NULL if not supported
 232  */
 233 authenticator_t *authenticator_create_v1(ike_sa_t *ike_sa, bool initiator,
 234                                                                 auth_method_t auth_method, diffie_hellman_t *dh,
 235                                                                 chunk_t dh_value, chunk_t sa_payload,
 236                                                                 chunk_t id_payload);
 237
 238 #endif /** AUTHENTICATOR_H_ @}*/