src/libsimaka/simaka_provider.h

   1 /*
   2  * Copyright (C) 2008-2011 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 simaka_provider simaka_provider
  18  * @{ @ingroup libsimaka
  19  */
  20
  21 #ifndef SIMAKA_PROVIDER_H_
  22 #define SIMAKA_PROVIDER_H_
  23
  24 typedef struct simaka_provider_t simaka_provider_t;
  25
  26 #include "simaka_manager.h"
  27
  28 #include <utils/identification.h>
  29
  30 /**
  31  * Interface for a triplet/quintuplet provider (used as EAP server).
  32  *
  33  * A SIM provider hands out triplets for SIM authentication and quintuplets
  34  * for AKA authentication. Multiple SIM provider instances can serve as
  35  * authentication backend to authenticate clients using SIM/AKA.
  36  * An implementation supporting only one of SIM/AKA authentication may
  37  * implement the other methods with return_false().
  38  */
  39 struct simaka_provider_t {
  40
  41         /**
  42          * Create a challenge for SIM authentication.
  43          *
  44          * @param id            permanent identity of peer to gen triplet for
  45          * @param rand          RAND output buffer, fixed size 16 bytes
  46          * @param sres          SRES output buffer, fixed size 4 byte
  47          * @param kc            KC output buffer, fixed size 8 bytes
  48          * @return                      TRUE if triplet received, FALSE otherwise
  49          */
  50         bool (*get_triplet)(simaka_provider_t *this, identification_t *id,
  51                                                 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
  52                                                 char kc[SIM_KC_LEN]);
  53
  54         /**
  55          * Create a challenge for AKA authentication.
  56          *
  57          * The XRES value is the only one with variable length. Pass a buffer
  58          * of at least AKA_RES_MAX, the actual number of bytes is written to the
  59          * xres_len value. While the standard would allow any bit length between
  60          * 32 and 128 bits, we support only full bytes for now.
  61          *
  62          * @param id            permanent identity of peer to create challenge for
  63          * @param rand          buffer receiving random value rand
  64          * @param xres          buffer receiving expected authentication result xres
  65          * @param xres_len      nubmer of bytes written to xres buffer
  66          * @param ck            buffer receiving encryption key ck
  67          * @param ik            buffer receiving integrity key ik
  68          * @param autn          authentication token autn
  69          * @return                      TRUE if quintuplet generated successfully
  70          */
  71         bool (*get_quintuplet)(simaka_provider_t *this, identification_t *id,
  72                                                    char rand[AKA_RAND_LEN],
  73                                                    char xres[AKA_RES_MAX], int *xres_len,
  74                                                    char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
  75                                                    char autn[AKA_AUTN_LEN]);
  76
  77         /**
  78          * Process AKA resynchroniusation request of a peer.
  79          *
  80          * @param id            permanent identity of peer requesting resynchronisation
  81          * @param rand          random value rand
  82          * @param auts          synchronization parameter auts
  83          * @return                      TRUE if resynchronized successfully
  84          */
  85         bool (*resync)(simaka_provider_t *this, identification_t *id,
  86                                    char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
  87
  88         /**
  89          * Check if peer uses a pseudonym, get permanent identity.
  90          *
  91          * @param id            pseudonym identity candidate
  92          * @return                      permanent identity, NULL if id not a pseudonym
  93          */
  94         identification_t* (*is_pseudonym)(simaka_provider_t *this,
  95                                                                           identification_t *id);
  96
  97         /**
  98          * Generate a pseudonym identitiy for a given peer identity.
  99          *
 100          * @param id            permanent identity to generate a pseudonym for
 101          * @return                      generated pseudonym, NULL to not use a pseudonym identity
 102          */
 103         identification_t* (*gen_pseudonym)(simaka_provider_t *this,
 104                                                                            identification_t *id);
 105
 106         /**
 107          * Check if peer uses reauthentication, retrieve reauth parameters.
 108          *
 109          * @param id            reauthentication identity (candidate)
 110          * @param mk            buffer receiving master key MK
 111          * @param counter       pointer receiving current counter value, host order
 112          * @return                      permanent identity, NULL if id not a reauth identity
 113          */
 114         identification_t* (*is_reauth)(simaka_provider_t *this, identification_t *id,
 115                                                                    char mk[HASH_SIZE_SHA1], uint16_t *counter);
 116
 117         /**
 118          * Generate a fast reauthentication identity, associated to a master key.
 119          *
 120          * @param id            permanent peer identity
 121          * @param mk            master key to store along with generated identity
 122          * @return                      fast reauthentication identity, NULL to not use reauth
 123          */
 124         identification_t* (*gen_reauth)(simaka_provider_t *this, identification_t *id,
 125                                                                         char mk[HASH_SIZE_SHA1]);
 126 };
 127
 128 #endif /** SIMAKA_CARD_H_ @}*/