Main Page   Data Structures   File List   Data Fields   Globals   Related Pages  

auth.h File Reference

Authentication declarations. More...

#include <types.h>

Go to the source code of this file.

Defines

#define AUTH_FLAG_PIN   0x01
 Flag for authstate signalling a successful PIN verification. More...

#define AUTH_FLAG_KEY   0x02
 Flag for authstate signalling a successful external authentication or key verification. More...

#define AUTH_AC_ALW   0x0
 Access Condition: Always. More...

#define AUTH_AC_PIN   0x1
 Access Condition: PIN. More...

#define AUTH_AC_ADM   0x2
 Access Condition: Key. More...

#define AUTH_AC_POA   0x3
 Access Condition: PIN or Key. More...

#define AUTH_AC_PAA   0x4
 Access Condition: PIN and Key. More...

#define AUTH_AC_NEV   0xF
 Access Condition: Never. More...

#define PIN_MAX_RETRIES   3
 Default max. retries for PIN. More...

#define PUK_MAX_RETRIES   10
 Default max. retries for PUK. More...

#define PIN_TYPE_PIN   0
 PIN type: PIN. More...

#define PIN_TYPE_PUK   1
 PIN type: PUK. More...

#define PIN_TYPE_EXT   2
 PIN type: Key for external authentication. More...

#define PIN_TYPE_INT   3
 PIN type: Key for internal authentication. More...

#define KEY_MAX_RETRIES   10
 Default max. retries for keys. More...

#define AUTH_FID_EXTAUTH   0xFF00
 FID for file with external authentication key. More...

#define AUTH_FID_INTAUTH   0xFF01
 FID for file with internal authentication key. More...

#define AUTH_FID_PINPUK   0xFF02
 FID for file with PIN and PUK. More...


Functions

bool auth_init (void)
 Initialize authentication variables. More...

bool auth_checkAc (iu8 ac)
 Check fullfillment of access condition. More...

bool auth_getCheckPinLen (iu8 pintype, iu8 pinlen, iu16 *addr, iu8 *len, iu16 *rcaddr, iu8 *maxret)
 Verifies length of PIN and returns addresses of PIN in EEPROM. More...

bool auth_setPin (iu8 pintype, iu8 *pin, iu8 pinlen)
 Write PIN, PUK, External Authentication key or Internal Authentication key. More...

bool auth_verifyPin (iu8 pintype, iu8 *pin, iu8 pinlen)
 Verifies PIN, PUK or External Authentication key and sets flags in authstate. More...

bool auth_getChallenge (iu8 *dst, iu8 rndlen)
 Returns 8 byte challenge for External Authentication. More...

bool auth_createVerifyCryptogram (iu8 *cry, iu8 crylen, bool create, bool enc)
 Encrypt or decrypt challenge or verify cryptogram. More...


Variables

iu8 challvalidity
 Validity of challenge. More...


Detailed Description

Authentication declarations.

Here are the declarations and definitions for the authentication functions. The authentication types supported are:

Todo:
Here are certainly some optimizations possible to reduce code size.

Id:
auth.h,v 1.11 2002/12/22 15:42:55 m Exp


Define Documentation

#define AUTH_AC_ADM   0x2
 

Access Condition: Key.

#define AUTH_AC_ALW   0x0
 

Access Condition: Always.

#define AUTH_AC_NEV   0xF
 

Access Condition: Never.

#define AUTH_AC_PAA   0x4
 

Access Condition: PIN and Key.

#define AUTH_AC_PIN   0x1
 

Access Condition: PIN.

#define AUTH_AC_POA   0x3
 

Access Condition: PIN or Key.

#define AUTH_FID_EXTAUTH   0xFF00
 

FID for file with external authentication key.

It is only searched for the file in the MF and not in any DF.

#define AUTH_FID_INTAUTH   0xFF01
 

FID for file with internal authentication key.

It is only searched for the file in the MF and not in any DF.

#define AUTH_FID_PINPUK   0xFF02
 

FID for file with PIN and PUK.

It is only searched for the file in the MF and not in any DF.

#define AUTH_FLAG_KEY   0x02
 

Flag for authstate signalling a successful external authentication or key verification.

#define AUTH_FLAG_PIN   0x01
 

Flag for authstate signalling a successful PIN verification.

#define KEY_MAX_RETRIES   10
 

Default max. retries for keys.

#define PIN_MAX_RETRIES   3
 

Default max. retries for PIN.

#define PIN_TYPE_EXT   2
 

PIN type: Key for external authentication.

#define PIN_TYPE_INT   3
 

PIN type: Key for internal authentication.

#define PIN_TYPE_PIN   0
 

PIN type: PIN.

#define PIN_TYPE_PUK   1
 

PIN type: PUK.

#define PUK_MAX_RETRIES   10
 

Default max. retries for PUK.


Function Documentation

bool auth_checkAc iu8    ac
 

Check fullfillment of access condition.

This function checks, if the current setting of authstate fullfills the condition specified with ac.

Parameters:
ac  A nibble specifying an access condition.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_createVerifyCryptogram iu8   cry,
iu8    crylen,
bool    create,
bool    enc
 

Encrypt or decrypt challenge or verify cryptogram.

To include the decryption process CONF_WITH_DECRYPT must be set to 1.

Parameters:
cry  Pointer to byte array, which supplies challenge and which is used to return the encrypted or decrypted challenge or a cryptogram.
crylen  Length of challenge or cryptogram.
create  If set to TRUE, a challenge is processed, else a cryptogram is verified.
enc  If CONF_WITH_DECRYPT is not set to 1, this has no effect. Otherwise, if TRUE encrypt the challenge, else decrypt it. If create is FALSE, this parameter is ignored.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_getChallenge iu8   dst,
iu8    rndlen
 

Returns 8 byte challenge for External Authentication.

The challenge is also written to the challenge array and challvalidity is set to 2.

Parameters:
dst  Destination byte array.
rndlen  Length of requested data. This must be 8.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_getCheckPinLen iu8    pintype,
iu8    pinlen,
iu16   addr,
iu8   len,
iu16   rcaddr,
iu8   maxret
 

Verifies length of PIN and returns addresses of PIN in EEPROM.

This functions does depending on pintype:

  • Check the length of the PIN or key.
  • Return the address of the PIN or key in EEPROM.
  • Return the length of the PIN or key in EEPROM.
  • Return the address of the retry counter in EEPROM.
  • Return the default max. value for the retry counter.
Parameters:
pintype  PIN type. One of the PIN_TYPE defines.
pinlen  Length of supplied PIN or key.
addr  Returns the address of the PIN or key in EEPROM.
len  Returns the length ofthe PIN or key in EEPROM.
rcaddr  Returns the address of the retry counter for the PIN or key.
maxret  Returns the default max. value for the retry counter.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_init void   
 

Initialize authentication variables.

This function resets authstate and challvalidity. It must be called after reset.

Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_setPin iu8    pintype,
iu8   pin,
iu8    pinlen
 

Write PIN, PUK, External Authentication key or Internal Authentication key.

The process is secured by transactions.

Parameters:
pintype  Type of the PIN/Key. May be one of the PIN_TYPE_* defines.
pin  Pointer to byte array containing PIN/Key.
pinlen  Length of PIN/Key.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.

bool auth_verifyPin iu8    pintype,
iu8   pin,
iu8    pinlen
 

Verifies PIN, PUK or External Authentication key and sets flags in authstate.

The update of the retry counter is secured by transactions.

Warning: Currently the retry counter is not handled in a secure way. For more information see e.g. Rankl/Effing.

Parameters:
pintype  Type of the PIN/Key. May be one of the PIN_TYPE_* defines.
pin  Pointer to byte array containing PIN/Key.
pinlen  Length of PIN/Key.
Return values:
TRUE  on success.
FALSE  on failure. Error code given in sw.


Variable Documentation

iu8 challvalidity
 

Validity of challenge.

The initial value if challvalidity is 2. This is decremented at the start of the command loop, so that it is 1 at the command following a Get Challenge.


Copyright 2002 by Matthias Bruestle. This is licensed under the GNU General Public License.