#include "3s_pub.h"

/*
				3S 接口說明
*/

/*
1. 初始化口令

(1) 3S 出廠時提供四組口令 PWD_A, PWD_B, PWD_C, PWD_D.
    PWD_A 與 PWD_B 同時作用于控制對每個 LMK 的注入
    PWD_C 與 PWD_D 同時作用于控制對每個 KKM 的產生與注入.
(2) 3S 提供更改每一口令的功能.
*/

int	change_pwd (			/* 入口參數 */
	char	pwd_id,			/* 被修改口令組號 'A', 'B', 'C', 'D' */
	uchar	old_pwd [ PWD_LEN ],	/* 原口令值 */
	uchar	new_pwd [ PWD_LEN ]	/* 新口令值 */
	);



/*
2. 密鑰的注入( Key Store )
*/
/*
(1) 密鑰的注入, 即將用戶輸入的密鑰保存在 3S 中.
(2) 需注入的密鑰有三類:

第一類	LMK:	由用戶自行產生, 用于加密存儲所有其他密鑰.
		每個 LMK 分為兩個分量( Key Component ), 分別由兩人輸入,
		由 3S 計算后產生最終密鑰, 明文存放于 3S 中.
		PWD_A 與 PWD_B 同時正確, 方能注入一個 LMK 的兩個分量.
*/

int	LMK_store (			/* 入口參數 */
	uchar	pwd_1 [ PWD_LEN ],	/* PWD_A */
	uchar	pwd_2 [ PWD_LEN ],	/* PWD_B */
	uchar	component_1 [ D_LEN ],	/* component input by MANAGER_A */
	uchar	component_2 [ D_LEN ],	/* component input by MANAGER_B */
					/* 出口參數 */
	int	* lmk_id		/* 密鑰序號 */
	);


/*
第二類	KKM:	由密鑰分配中心分配, 人工分發, 用于加密需線路傳送的密鑰.
		每個 KKM 分為兩個分量( Key Component ), 分別由兩人輸入,
		由 3S 計算后產生最終密鑰, 由 LMK 加密存儲于 3S 中.
		PWD_C 與 PWD_D 同時正確, 方能注入一個 KKM 的兩個分量.
*/

int	ZMK_store (			/* 入口參數 */
	int	lmk_id,			/* 加密用的 LMK */
	uchar	pwd_1 [ PWD_LEN ],	/* PWD_C */
	uchar	pwd_2 [ PWD_LEN ],	/* PWD_D */
	uchar	component_1 [ D_LEN ],	/* component input by or MANAGER_C */
	uchar	component_2 [ D_LEN ],	/* component input by or MANAGER_D */
	char	length,			/* key length */
					/* 出口參數 */
	int	* zmk_id		/* 密鑰序號 */
	);


/*
第三類	KK/KD:	一般密鑰, 加密后通過線路傳送, 由 LMK 加密存儲于 3S 中.
*/

int	key_store (			/* 入口參數 */
	char	key_length,		/* 'S': Single, 'D': Double */
	uchar	key_kek [ D_LEN ],	/* 由 kek 加密的 key 的密文 */
	int	kek_id,			/* 加密 key 的密鑰 kek 的序號 */
	uchar	kek_counter [ CT_LEN ],	/* kek 的計數器 */
	int	lmk_id,			/* 加密 key 用的 LMK 序號 */
					/* 出口參數 */
	int	* key_id		/* 密鑰序號 */
	);



/*
3. 密鑰的產生及刪除( Key Generate and Remove )

(1) 密鑰的產生, 即由 3S 產生一個隨機數作為一個密鑰,
    并選用一個 LMK 加密后存放在 3S 中.
(2) 應可由用戶輸入指定加密用的 LMK.
(3) 應可由用戶輸入指定產生單倍長密鑰或雙倍長密鑰.
*/

int	key_generate (			/* 入口參數 */
	int	lmk_id,			/* 加密用的 LMK */
	char	key_length,		/* 'S': Single, 'D': Double */
					/* 出口參數 */
	int	* key_id		/* 密鑰序號 */
	);

int	key_remove (			/* 入口參數 */
	int	key_id,			/* 密鑰序號 */
	uchar	pwd_1 [ PWD_LEN ],	/* PWD_A or PWD_C */
	uchar	pwd_2 [ PWD_LEN ]	/* PWD_B or PWD_D */
	);


/*
4. 密鑰的變換 ( Key Translate )

(1) 3S 應能將用戶輸入的一個用 LMK 密鑰加密的密鑰, 先解密成明文,
    再用用戶指定的密鑰 B 加密后輸出.
(2) 3S 應能將一個密鑰與用戶輸入的數據進行計算后的值作為密鑰使用.
*/

int	key_translate (			/* 入口參數 */
	int	key_id,			/* 密鑰 key 的序號 */
	int	kek_id,			/* 加密 key 的密鑰 kek 的序號 */
	uchar	kek_counter [ CT_LEN ],	/* kek 的計數器 */
					/* 出口參數 */
	uchar	key_kek [ D_LEN ]	/* kek 加密的 key */
	);



/*
5. PIN 加密/解密與校驗 ( PIN Encrypt/Decrypt and Verify )

(1) PIN 的加密采用 ANSI X9.8 算法. 用戶輸入 PIN 的明文及卡號,
    由 3S 計算出 PINBLOCK, 并使用用戶指定的密鑰加密后輸出.
*/

int	PIN_encrypt (			/* 入口參數 */
	uchar	pin [ PIN_LEN ],	/* pin 明文 */
	int	pin_length,		/* pin 長度 */
	uchar	card_no [ CARD_LEN ],	/* 卡號 */
	int	pinkey_id,		/* pinkey 的序號 */
					/* 出口參數 */
	uchar	pinblock_pinkey [ S_LEN ]	/* pinkey 加密后的 pinblock */
	);

/*
(2) PIN 的解密采用 ANSI X9.8 算法. 用戶輸入 PINBLOCK 的密文及卡號,
    并指定 PIN KEY, 由 3S 計算出 PIN 明文.
*/

int	PIN_decrypt (			/* 入口參數 */
	uchar	pinblock_pinkey [ S_LEN ],	/* pinkey 加密后的 pinblock */
	uchar	card_no [ CARD_LEN ],	/* 卡號 */
	int	pinkey_id,		/* pinkey 的序號 */
					/* 出口參數 */
	uchar	pin [ PIN_LEN ],	/* pin 明文 */
	int	* pin_length		/* pin 長度 */
	);

/*
(3) PIN 的校驗是將 3S 計算出的 PIN 密文與用戶輸入的 PIN 密文值比較,
    輸出比較結果.
*/

int	PIN_verify (			/* 入口參數 */
	uchar	pinblock_pinkey [ S_LEN ],	/* pinkey 加密后的 pinblock */
	uchar	card_no [ CARD_LEN ],	/* 卡號 */
	uchar	offset [ OFFSET_LEN ],	/* pin offset */
	int	pinkey_id,		/* pinkey 的序號 */
	int	pvk_id,			/* pin verify key 的序號 */
					/* 出口參數 */
	char	* yorn			/* 'Y': valid, 'N': invalid */
	);

/*
6. MAC 計算與校驗 ( MAC Generate and Verify )

(1) MAC 的計算采用 ANSI X9.9 算法. 用戶輸入數據包,
    由 3S 計算出 MAC, 并使用用戶指定的密鑰加密后輸出.
*/

int	MAC_generate (			/* 入口參數 */
	uchar	* data,			/* 數據內容 */
	int	data_length,		/* 數據長度 */
	int	mackey_id,		/* MAC key 的序號 */
					/* 出口參數 */
	uchar	mac [ S_LEN ]		/* MAC 值 */
	);

/*
(2) MAC 的校驗是將 3S 計算出的 MAC 與用戶輸入的 MAC 值比較,
    輸出比較結果.
*/

int	MAC_verify (			/* 入口參數 */
	uchar	* data,			/* 數據內容 */
	int	data_length,		/* 數據長度 */
	int	mackey_id,		/* MAC key 的序號 */
	uchar	mac [ S_LEN ],		/* MAC 值 */
					/* 出口參數 */
	char	* yorn			/* 'Y': valid, 'N': invalid */
	);



/*
7. 隨機數產生 ( Random Number Generate )
	
(1) 隨機數的產生, 即由 3S 產生一個隨機數輸出.
(2) 應可由用戶輸入指定產生 8 字節 或 16 字節隨機數.
*/

int	RN_generate (			/* 入口參數 */
	char	RN_length,		/* 'S': Single, 'D': Double */
					/* 出口參數 */
	uchar	RN [ D_LEN ]		/* 產生的隨機數 */
	);



/*
8. 數據加密及解密 ( Data Encrypt and Decrypt )

(1) 用戶輸入數據并指定密鑰, 3S 將加密結果輸出.
*/

int	data_encrypt (			/* 入口參數 */
	uchar	data [ D_LEN ],		/* 明文 */
	char	data_length,		/* 'S': 8 bytes, 'D': 16 bytes */
	int	key_id, 		/* 加密用的密鑰的序號  */
					/* 出口參數 */
	uchar	data_key [ D_LEN ]	/* key 加密后的數據 */
	);


/*
(2) 用戶輸入數據并指定密鑰, 3S 將加密結果輸出.
*/

int	data_decrypt (			/* 入口參數 */
	uchar	data_key [ D_LEN ],	/* key 加密的數據 */
	char	data_length,		/* 'S': 8 bytes, 'D': 16 bytes */
	int	key_id, 		/* 解密用的密鑰的序號  */
					/* 出口參數 */
	uchar	data [ D_LEN ]		/* 明文 */
	);


/*
(3) 3S 應能將用戶輸入的一個用 A 密鑰加密的數據, 先解密成明文,
    再用用戶指定的密鑰 B 加密后輸出.
    PIN Translate 可用此功能實現.
*/

int	data_translate (		/* 入口參數 */
	uchar	data_oldkey [ D_LEN ],	/* 用 oldkey 加密的數據 */
	char	data_length,		/* 'S': 8 bytes, 'D': 16 bytes */
	int	oldkey_id,		/* 原加密密鑰的序號  */
	int	newkey_id,		/* 新加密密鑰的序號  */
					/* 出口參數 */
	uchar	data_newkey [ D_LEN ]	/* 用 newkey 加密的數據 */
	);


/*
函數返回值:	
	0 	-- 操作完成
	其他	-- 操作錯誤碼
*/