src/libsimaka/simaka_card.h

   1 /*
   2  * Copyright (C) 2008-2011 Martin Willi
   3  *
   4  * Copyright (C) secunet Security Networks AG
   5  *
   6  * This program is free software; you can redistribute it and/or modify it
   7  * under the terms of the GNU General Public License as published by the
   8  * Free Software Foundation; either version 2 of the License, or (at your
   9  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  10  *
  11  * This program is distributed in the hope that it will be useful, but
  12  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  13  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * for more details.
  15  */
  16
  17 /**
  18  * @defgroup simaka_card simaka_card
  19  * @{ @ingroup libsimaka
  20  */
  21
  22 #ifndef SIMAKA_CARD_H_
  23 #define SIMAKA_CARD_H_
  24
  25 typedef struct simaka_card_t simaka_card_t;
  26
  27 #include "simaka_manager.h"
  28
  29 #include <utils/identification.h>
  30
  31 /**
  32  * Interface for a (U)SIM card (used as EAP client).
  33  *
  34  * The SIM card completes triplets/quintuplets requested in a challenge
  35  * received from the server.
  36  * An implementation supporting only one of SIM/AKA authentication may
  37  * implement the other methods with return_false()/return NOT_SUPPORTED/NULL.
  38  */
  39 struct simaka_card_t {
  40
  41         /**
  42          * Calculate SRES/KC from a RAND for SIM authentication.
  43          *
  44          * @param id            permanent identity to get a triplet for
  45          * @param rand          RAND input 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 SRES/KC calculated, FALSE on error/wrong identity
  49          */
  50         bool (*get_triplet)(simaka_card_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          * Calculate CK/IK/RES from RAND/AUTN for AKA authentication.
  56          *
  57          * If the received sequence number (in autn) is out of sync, INVALID_STATE
  58          * is returned.
  59          * The RES value is the only one with variable length. Pass a buffer
  60          * of at least AKA_RES_MAX, the actual number of bytes is written to the
  61          * res_len value. While the standard would allow any bit length between
  62          * 32 and 128 bits, we support only full bytes for now.
  63          *
  64          * @param id            permanent identity to request quintuplet for
  65          * @param rand          random value rand
  66          * @param autn          authentication token autn
  67          * @param ck            buffer receiving encryption key ck
  68          * @param ik            buffer receiving integrity key ik
  69          * @param res           buffer receiving authentication result res
  70          * @param res_len       number of bytes written to res buffer
  71          * @return                      SUCCESS, FAILED, or INVALID_STATE if out of sync
  72          */
  73         status_t (*get_quintuplet)(simaka_card_t *this, identification_t *id,
  74                                                            char rand[AKA_RAND_LEN], char autn[AKA_AUTN_LEN],
  75                                                            char ck[AKA_CK_LEN], char ik[AKA_IK_LEN],
  76                                                            char res[AKA_RES_MAX], int *res_len);
  77
  78         /**
  79          * Calculate AUTS from RAND for AKA resynchronization.
  80          *
  81          * @param id            permanent identity to request quintuplet for
  82          * @param rand          random value rand
  83          * @param auts          resynchronization parameter auts
  84          * @return                      TRUE if parameter generated successfully
  85          */
  86         bool (*resync)(simaka_card_t *this, identification_t *id,
  87                                    char rand[AKA_RAND_LEN], char auts[AKA_AUTS_LEN]);
  88
  89         /**
  90          * Set the pseudonym to use for next authentication.
  91          *
  92          * @param id            permanent identity of the peer
  93          * @param pseudonym     pseudonym identity received from the server
  94          */
  95         void (*set_pseudonym)(simaka_card_t *this, identification_t *id,
  96                                                   identification_t *pseudonym);
  97
  98         /**
  99          * Get the pseudonym previously stored via set_pseudonym().
 100          *
 101          * @param id            permanent identity of the peer
 102          * @return                      associated pseudonym identity, NULL if none stored
 103          */
 104         identification_t* (*get_pseudonym)(simaka_card_t *this, identification_t *id);
 105
 106         /**
 107          * Store parameters to use for the next fast reauthentication.
 108          *
 109          * @param id            permanent identity of the peer
 110          * @param next          next fast reauthentication identity to use
 111          * @param mk            master key MK to store for reauthentication
 112          * @param counter       counter value to store, host order
 113          */
 114         void (*set_reauth)(simaka_card_t *this, identification_t *id,
 115                                            identification_t *next, char mk[HASH_SIZE_SHA1],
 116                                            uint16_t counter);
 117
 118         /**
 119          * Retrieve parameters for fast reauthentication stored via set_reauth().
 120          *
 121          * @param id            permanent identity of the peer
 122          * @param mk            buffer receiving master key MK
 123          * @param counter       pointer receiving counter value, in host order
 124          * @return                      fast reauthentication identity, NULL if not found
 125          */
 126         identification_t* (*get_reauth)(simaka_card_t *this, identification_t *id,
 127                                                                         char mk[HASH_SIZE_SHA1], uint16_t *counter);
 128 };
 129
 130 #endif /** SIMAKA_CARD_H_ @}*/