/*
* Copyright 2006 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _FINSVCS_H
#define _FINSVCS_H
#pragma ident "@(#)finsvcs.h 1.5 06/04/19 SMI"
#ifdef __cplusplus
extern "C" {
#endif
#if !defined(CPU_XSCALE) && !defined(_KERNEL)
/* Financial Services Library Handle */
typedef void *fsLibHandle_t;
/* session handle */
typedef void *fsSessHandle_t;
#endif /* !XSCALE && !KERNEL */
/* finsvc error codes */
typedef enum fsReturn {
fsOK,
fsError, /* processing error */
fsVerifyFail, /* verification failed (card or PIN) */
fsInvalidKey,
fsInvalidPEK, /* invalid PIN encryption key */
fsInvalidPVK, /* invalid PIN verification key */
fsInvalidPVKI, /* invalid PVK index */
fsInvalidCVK, /* invalid card verification key */
fsInvalidKEK, /* invalid key encryption key */
fsInvalidKeyType,
fsInvalidKeyUsage,
fsBufferTooSmall,
fsInvalidArgs,
fsInvalidHandle,
fsNoMem, /* memory allocation failure */
fsInvalidPin, /* pin block corrupt */
fsInvalidPinType, /* invalid pin block format */
fsInvalidDectbl,
fsInvalidPan,
fsInvalidCmd,
fsInvalidState,
fsNotInitialized,
fsNotFound,
fsInvalidLibVersion
} fsReturn_t;
/* fs state */
typedef enum {
fsStateUninit,
fsStateNormalMode, /* core functionality enabled */
fsStateSensitiveMode, /* import/export key enabled */
fsStateTestMode, /* Test mode enabled */
fsStateMfkChange /* mfk change in progress */
} fsState_t;
/* Supported Personal Identification Number (PIN) algorithms */
typedef enum fsPinAlg {
PVV = 1,
IBM3624
} fsPinAlg_t;
/* supported magnetic/credit card algorithms */
typedef enum fsCardAlg {
CVV,
CSC
} fsCardAlg_t;
/* MAC'ing Algorithms - used by fs_mac_generate/fs_mac_verify */
typedef enum fsMacAlg {
X9_9,
X9_19,
X9_19_3DES
} fsMacAlg_t;
/*
* supported PIN types
*
* ISO Format 0 is defined as follows (nibbles)
* [0][N][P][P][P][P][P/F][P/F][P/F][P/F][P/F][P/F][P/F][P/F][F][F]
*
* where:
* N = PIN length
* P = PIN digit
* F = Fill = 0xf
*
* ISO Format 1 is defined as follows:
* [1][N][P][P][P][P][P/R][P/R][P/R][P/R][P/R][P/R][P/R][P/R][R][R]
*
* where:
* N = PIN length
* P = PIN digit
* R = random digit between o and 0xf
*/
typedef enum fsPinType {
ISOFormat0,
ISOFormat1
} fsPinType_t;
#define FS_PIN_SIZE 8
/* Personal Identificatin Number (PIN) data type */
typedef struct fsPin {
fsPinType_t type;
uint8_t pin[FS_PIN_SIZE];
} fsPin_t;
/* PVV PIN data types */
typedef uint8_t fsPvki_t; /* PIN Verification Key Index */
#define FS_DEC_TABLE_SIZE 8
/* Decimalization table - used in IBM3624 PIN operations */
typedef struct fsDecTable_s {
uint8_t table[FS_DEC_TABLE_SIZE];
uint8_t pad[FS_DEC_TABLE_SIZE]; /* pad to 16 bytes for AES */
} fsDecTable_t;
#define BYTES2NIBS(x) (2 * x)
#define NIBS2BYTES(x) (2 / x)
/*
* Financial Key Usage.
* These are standard key usages as defined in the financial community
*/
typedef enum fsKeyUsage {
TPK = 1, /* Terminal PIN Key (PEK) */
ZWK, /* Zone Working Key (PEK) */
CVK, /* Card Verification Key */
PVK, /* PIN Verification Key */
KEK, /* Key Encryption Key */
MACK /* MAC Key */
} fsKeyUsage_t;
#define MAX_KEY_USAGE 6
/* Financial Key Types - DESx only currently */
typedef enum fsKeyType {
DES = 1, /* Single length DES */
DES2, /* Double length DES */
DES3 /* 3DES */
} fsKeyType_t;
#define FS_KEY_SZ 48
#define FS_KCV_SZ 3
/* FS key format - key is just a byte stream to users */
typedef struct fsKey_s {
uint8_t keydata[FS_KEY_SZ];
} fsKey_t;
/* ISO 9.17 Key Format - common external key format */
#define FS_KEYSIZE_917 24
#define FS_KCVSIZE_917 3
/* ANSI X9.17 key definition - used for import/export operations */
typedef struct fsKey917 {
uint8_t length;
uint8_t kcv[FS_KCVSIZE_917];
uint8_t key[FS_KEYSIZE_917];
} fsKey917_t;
#define FS_PAN_SIZE 10
#define FS_PAN_CONTROL_SIZE 2
#define FS_PAN_PIN_SIZE 12 /* PIN op PAN size (nibbles) */
#define FS_PAN_PIN_TOTAL \
((FS_PAN_CONTROL_SIZE * 2) + FS_PAN_PIN_SIZE)
/* Personal Account Number (PAN) data structure */
typedef struct fsPan {
uint8_t length; /* in nibbles/digits (from 12 to 19) */
uint8_t pan[FS_PAN_SIZE];
} fsPan_t;
typedef enum fsObjectType {
fsObjDecTable,
fsObjKey
} fsObjectType_t;
typedef struct fsObjectData_s {
fsObjectType_t type;
union {
fsDecTable_t decTable;
fsKey_t key;
} object;
} fsObjectData_t;
#define FS_3624_VALDATA_SIZE 8
#define FS_3624_OFFSET_SIZE 6
#define FS_PVV_SIZE 2
/*
* Personal Identification Number (PIN) data.
* Used for both PVV and IBM3624 PIN verification.
*/
typedef union fsPinData {
struct {
fsPvki_t pvki;
uint8_t pvv[FS_PVV_SIZE];
} pvv;
struct {
fsDecTable_t decTable;
uint8_t valData[FS_3624_VALDATA_SIZE];
uint8_t checkLen;
uint8_t refOffset[FS_3624_OFFSET_SIZE];
} ibm3624;
} fsPinData_t;
/*
* Card verification data - supports both CVV (visa/mastercard)
* and CSC (american express) card verification.
*/
typedef struct fsCardData {
fsPan_t pan;
uint8_t expDate[2]; /* expiration date */
union {
struct {
uint8_t refCVV[2];
uint8_t servCode[2]; /* service code */
} cvv;
struct {
uint8_t cscLen;
uint8_t refCSC[3];
} csc;
} data;
} fsCardData_t;
#if !defined(CPU_XSCALE) && !defined(_KERNEL)
/* Library prototypes */
/* general purpose routines */
fsLibHandle_t fs_lib_open(char *, fsReturn_t *);
fsReturn_t fs_lib_close(fsLibHandle_t);
fsSessHandle_t fs_session_open(fsLibHandle_t);
fsReturn_t fs_session_close(fsSessHandle_t);
/* PIN processing functions */
fsReturn_t fs_pin_verify(fsSessHandle_t, fsPinAlg_t, fsKey_t *, fsKey_t *,
fsPan_t *, fsPin_t *, fsPinData_t *);
fsReturn_t fs_pin_translate(fsSessHandle_t, fsKey_t *, fsKey_t *,
fsPin_t *, fsPin_t *, fsPan_t *);
/* card processing functions */
fsReturn_t fs_card_verify(fsSessHandle_t, fsCardAlg_t, fsKey_t *,
fsPan_t *, fsCardData_t *);
/* Key/object management functions */
fsReturn_t fs_key_generate(fsSessHandle_t, fsKeyType_t, fsKeyUsage_t,
fsKey_t *);
fsReturn_t fs_key_translate(fsSessHandle_t, fsKey_t *, fsKey_t *);
fsReturn_t fs_key_import(fsSessHandle_t, fsKeyUsage_t, fsKey_t *,
fsKey917_t *, fsKey_t *, boolean_t);
fsReturn_t fs_key_export(fsSessHandle_t, fsKeyUsage_t, fsKey_t *,
fsKey_t *, fsKey917_t *, boolean_t);
fsReturn_t fs_retrieve_object(fsSessHandle_t, fsObjectType_t, char *,
fsObjectData_t *);
fsReturn_t fs_status(fsSessHandle_t, fsState_t *);
#endif /* !CPU_XSCALE && !KERNEL */
#ifdef __cplusplus
}
#endif
#endif /* _FINSVCS_H */
|