/*
 * 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 */