src/libsimaka/simaka_card.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_card simaka_card
  18  * @{ @ingroup libsimaka
  19  */
  20
  21 #ifndef SIMAKA_CARD_H_
  22 #define SIMAKA_CARD_H_
  23
  24 typedef struct simaka_card_t simaka_card_t;
  25
  26 #include "simaka_manager.h"
  27
  28 #include <utils/identification.h>
  29
  30 /**
  31  * Interface for a (U)SIM card (used as EAP client).
  32  *
  33  * The SIM card completes triplets/quintuplets requested in a challenge
  34  * received from the server.
  35  * An implementation supporting only one of SIM/AKA authentication may
  36  * implement the other methods with return_false()/return NOT_SUPPORTED/NULL.
  37  */
  38 struct simaka_card_t {
  39
  40         /**
  41          * Calculate SRES/KC from a RAND for SIM authentication.
  42          *
  43          * @param id            permanent identity to get a triplet for
  44          * @param rand          RAND input buffer, fixed size 16 bytes
  45          * @param sres          SRES output buffer, fixed size 4 byte
  46          * @param kc            KC output buffer, fixed size 8 bytes
  47          * @return                      TRUE if SRES/KC calculated, FALSE on error/wrong identity
  48          */
  49         bool (*get_triplet)(simaka_card_t *this, identification_t *id,
  50                                                 char rand[SIM_RAND_LEN], char sres[SIM_SRES_LEN],
  51                                                 char kc[SIM_KC_LEN]);
  52
  53         /**
  54          * Calculate CK/IK/RES from RAND/AUTN for AKA authentication.
  55          *
  56          * If the received sequence number (in autn) is out of sync, INVALID_STATE
  57          * is returned.
  58          * The RES value is the only one with variable length. Pass a buffer
  59          * of at least AKA_RES_MAX, the actual number of bytes is written to the
  60          * res_len value. While the standard would allow any bit length between
  61          * 32 and 128 bits, we support only full bytes for now.
  62          *
  63          * @param id            permanent identity to request quintuplet for
  64          * @param rand          random value rand
  65          * @param autn          authentication token autn
  66          * @param ck            buffer receiving encryption key ck
  67          * @param ik            buffer receiving integrity key ik
  68          * @param res           buffer receiving authentication result res
  69          * @param res_len       nubmer of bytes written to res buffer
  70          * @return                      SUCCESS, FAILED, or INVALID_STATE if out of sync
  71          */
  72         status_t (*get_quintuplet)(simaka_card_t *this, identification_t *id,
  73                                                            char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
  74                                                            char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
  75                                                            char res[AKA_RES_MAX], int *res_len);
  76
  77         /**
  78          * Calculate AUTS from RAND for AKA resynchronization.
  79          *
  80          * @param id            permanent identity to request quintuplet for
  81          * @param rand          random value rand
  82          * @param auts          resynchronization parameter auts
  83          * @return                      TRUE if parameter generated successfully
  84          */
  85         bool (*resync)(simaka_card_t *this, identification_t *id,
  86                                    char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
  87
  88         /**
  89          * Set the pseudonym to use for next authentication.
  90          *
  91          * @param id            permanent identity of the peer
  92          * @param pseudonym     pseudonym identity received from the server
  93          */
  94         void (*set_pseudonym)(simaka_card_t *this, identification_t *id,
  95                                                   identification_t *pseudonym);
  96
  97         /**
  98          * Get the pseudonym previously stored via set_pseudonym().
  99          *
 100          * @param id            permanent identity of the peer
 101          * @return                      associated pseudonym identity, NULL if none stored
 102          */
 103         identification_t* (*get_pseudonym)(simaka_card_t *this, identification_t *id);
 104
 105         /**
 106          * Store parameters to use for the next fast reauthentication.
 107          *
 108          * @param id            permanent identity of the peer
 109          * @param next          next fast reauthentication identity to use
 110          * @param mk            master key MK to store for reauthentication
 111          * @param counter       counter value to store, host order
 112          */
 113         void (*set_reauth)(simaka_card_t *this, identification_t *id,
 114                                            identification_t *next, char mk[HASH_SIZE_SHA1],
 115                                            u_int16_t counter);
 116
 117         /**
 118          * Retrieve parameters for fast reauthentication stored via set_reauth().
 119          *
 120          * @param id            permanent identity of the peer
 121          * @param mk            buffer receiving master key MK
 122          * @param counter       pointer receiving counter value, in host order
 123          * @return                      fast reauthentication identity, NULL if not found
 124          */
 125         identification_t* (*get_reauth)(simaka_card_t *this, identification_t *id,
 126                                                                         char mk[HASH_SIZE_SHA1], u_int16_t *counter);
 127 };
 128
 129 #endif /** SIMAKA_CARD_H_ @}*/