CSP设计之-密钥的产生和交换函数

 

密钥的产生和交换函数

   CPDeriveKey

   CPDestroyKey

   CPDuplicateKey

   CPExportKey

   CPGenKey

   CPGenRandom

   CPGetKeyParam

   CPGetUserKey

   CPImportKey

   CPSetKeyParam

1.2.1 CPDeriveKey

功能：

创建一个密码派生的密钥。

参数：

【in】hProv： CSP句柄

【in】Algid :算法标识

Value

Meaning

DES

支持

3DES

支持

RC2

支持

RC4

支持

SCB2

支持

SSF33

支持

【in】hBaseData :哈希对象数据

【in】dwFlags :生成标记

Value

Meaning

CRYPT_EXPORTABLE
1
0x1

密钥可以导出的标

CRYPT_CREATE_SALT
4
0x4

不支持

CRYPT_NO_SALT
16
0x10

不支持

CRYPT_USER_PROTECTED
2
0x2

不支持

CRYPT_UPDATE_KEY
8
0x8

不支持

CRYPT_SERVER
1024
0x400

不支持

【out】phKey :密钥对象句柄

返回值：

If the function succeeds, the functionreturns TRUE.

错误情况下设置错误码如下

Value

Description

NTE_BAD_ALGID
0x80090008

指定的算法不支持

NTE_BAD_FLAGS
0x80090009

参数无效

NTE_BAD_HASH
0x80090002

HASH句柄无效

NTE_BAD_HASH_STATE
0x8009000c

状态不对，当HASH为完成状态情况下，再对数据进行运算时会失败。

NTE_FAIL
0x80090020

函数执行失败

NTE_BAD_UID
0x80090001

无效的CSP句柄

NTE_SILENT_CONTEXT
0x80090022

提供者无法执行的行动，因为上下文是无效的。

1.2.2 CPDestroyKey

功能：

释放密钥句柄

参数：

【in】hProv：CSP句柄

【in】hKey：要释放的密钥句柄。

 

返回值：

返回值

描述

NTE_BAD_KEY

无效的密钥句柄

NTE_BAD_UID

无效的CSP句柄

备注：

如果是用Cryptimportkey函数导入的会话密钥或是公钥，释放句柄时密钥所用的内存也将被覆盖。

对于其他句柄，如果是公钥/密钥对，由CryptGetUserKey生成，这个密钥对不会被销毁，只是句柄被销毁。

1.2.3 CPDuplicateKey

功能：

         生成一个hKey的复本

参数：

【in】hUID: CSP句柄

【in】hKey: 密钥句柄

【in】pdwReserved: 保留，NULL

【in】dwFlags: 保留，必须为0

【in】phKey: 复制后的Key句柄，释放时调用CPDestroyKey函数

返回值：

返回值

描述

ERROR_CALL_NOT_IMPLEMENTED

新功能可能还没有生效，CSP不支持

ERROR_INVALID_PARAMETER

无效参数

NTE_BAD_KEY

无效key句柄

备注：

此函数主要用于复制一个hKey复本。有时同一个hkey可能需要不同的混合值，这时就可用这一个函数复制一个hKey复本，为添加不同的混合值。

释放原来的hkey时不会销毁hKey复本，两都互不干扰。

 1.2.4 CPExportKey

功能：

安全导出密钥

参数：

【in】hUID: CSP句柄

【in】hKey: 指定需要导出的密钥句柄

【in】hPubKey:用来加密的公钥句柄，可以为空

【in】dwBlobType: 指定导出的key Blob类型

值

描述

OPAQUEKEYBLOB

表示导出的是对称密钥，密钥用hPubKey指定的公钥加密

PUBLICKEYBLOB

导出公钥

PRIVATEKEYBLOB

导出公私钥对

SIMPLEBLOB

导出session key

【in】dwFlags: 只在SCHANNEL CSP中使用，

值

描述

CRYPT_DESTROYKEY

销毁在OPAQUEKEYBLOB中的密钥

CRYPT_SSL2_FALLBACK

设置8字节填充位0x03而不是随机数，防止SSL3规范中的VERSION ROLLBACK攻击

【in】pdData:导出key BLOB数据缓存区指针（存key BLOB）

【in，out】pdwDataLen:指向DWORD 值的指针，此值指出导出KEY BLOB的长度。在调用此函数前，此值为pbData缓冲区长度，调用此函数后，此值为导出KEY BLOB的长度

 

返回值：成功返回TRUE，失败返回FALSE，由SetLastError获取

Return code

Description

ERROR_MORE_DATA

pbData缓存区不够大

NTE_BAD_FLAGS

dwFlags 参数有无效值

NTE_BAD_KEY

hKey 和hPubKey 无效.

NTE_BAD_KEY_STATE

密钥无法导出创建时没有设置CRYPT_EXPORTABLE 属性

NTE_BAD_PUBLIC_KEY

 key BLOB 指定的类型是PUBLICKEYBLOB, 但是hPubKey没有定义公钥句柄

NTE_BAD_TYPE

 dwBlobType 参数设置了未知的值.

NTE_BAD_UID

未找到hKey

NTE_NO_KEY

hExpKey参数没有指定一个公钥

 1.2.5 CPGenKey

功能：

生成密钥：加密密钥或者签名密钥，或者会话密钥

参数：

[in]hProv: CSP句柄

[in]Algid: 指定产生密钥的加密算法如果是会话密钥用CALG_RC2 、CALG_RC4 、CALG_DES 算法加密,如果是公/私密钥对用AT_KEYEXCHANGE、AT_SIGNATURE

[in]dwFlags: 指定产生密钥的属性值

参数

描述

CRYPT_EXPORTABLE

指定导出会话密钥或公钥，不支持导出私钥；若不设置此标志，不支持导出操作

CRYPT_CREATE_SALT

设置此标志则会话密钥会与一个混合值共同使用，如果没设则会话密钥与0相关联。这个标志不适用于公/私钥对。

CRYPT_NO_SALT

指定没有混合值与40位的对称密钥相关联

CRYPT_USER_PROTECTED

设置用户可以通过对话框或其他方式使用密钥。与CRYPT_SLIENT标志相关联

CRYPT_PREGEN

用Diffie-Hellman/DSS算法产生密钥

[out]phKey: 返回产生新密钥的密钥句

 

返回值：

返回码

描述

NTE_BAD_ALGID

Algid指定的算法CSP不支持

NTE_BAD_FLAGS

dwFlags参数包括无效值

NTE_FAIL

未知错误

NTE_BAD_UID

hProv包含无效参数

NTE_PERM

指定CRYPT_VERIFYCONTEXT参数时要创建密钥对

NTE_SILENT_CONTEXT

指定的行为无法执行，上下文已关闭

备注：

如果密钥容器未打开应用程序无法创建密钥对。如果CPAcquireContext设置了CRYPT_VERIFYCONTEXT是可以正常创建的。CPGenRandom用于产生随机的密钥。对于对称密钥生成分组密码算法必须设置默认的密文块链接(CBC)的模式与一个零的初始化值。这个密码模式提供了一个很好的默认方法bulk-encrypting。这些参数变化使用CPSetKeyParam函数进行修改。

1.2.6 CPGenRandom

功能：

产生随机数:由设备产生.

参数：   

[in]hProv: CSP句柄

[in]dwLen: 产生随机数据的长度

[in]pbBuffer: 复制随机产生的数据到该缓存区

返回值：

返回值

描述

NTE_BAD_UID

hProv句柄无效

NTE_FAIL

未知错误

1.2.7 CPGetKeyParam

功能：

获取密钥参数

参数：

[in]hProv: CSP句柄

[in]hKey: 密钥句柄

[in]dwParam:以下参数

参数

描述

KP_ALGID

all

密钥对象所用的加密算法ALG_ID

KP_BLOCKLEN
all

如果hKey是会话密钥(session key),一个DWORD类型值表示block长度，单位位;

如果hKey是公/私钥对，一个DWORD类型值表示公/私钥对的间隔；

对于RSA钥对表示模数

KP_KEYLEN
all

密钥实际长度

CALG_DES:64bit

CALG_3DES_112:128bit

CALG_3DES:192bit

微软的CALG_CYLINK_MEK:64bit。CALG_CYLINK_MEK:40bit它

用校验位和零值使密钥长度是64位

KP_SALT
all session keys

一个包含混合值的密钥的BYTE数组。这个参数不支持公/私钥对，返回NTE_BAD_TYPE错误

KP_PERMISSIONS
all

一个DWORD类型值表示Key的权限，具体设置看表1

KP_IV
block cipher keys

BYTE数组，密钥的当前初始化变量

KP_PADDING
block cipher keys

DWORD类型值，表示算法填充方法，

KP_MODE
block cipher keys

DWORD类型值，表示加密模式

KP_MODE_BITS
block cipher keys

DWORD类型值，表示返回的位数，只有OFB和CFB加密模式使用

KP_EFFECTIVE_KEYLEN
RC2

DWORD类型值，表示有效的RC2,DES,RC4,SCB2,SF33密钥长度

KP_CERTICATE

获取证书

KP_ALG_TYPE

从传入的数据中获取算法类型

KP_ALGID

获取密钥类型

[in]pbData: 指向数据缓存的指针

[in,out]pdwDataLen:pbData的长度

[in]dwFlags: 无定义，设置为0

返回值：

返回值

描述

ERROR_MORE_DATA

pbData缓存区不够大

NTE_BAD_FLAGS

dwFlags 参数为非零值.

NTE_BAD_KEY or NTE_NO_KEY

hKey 无效

NTE_BAD_TYPE

dwParam指定的参数无效.

NTE_BAD_UID

未找到CSP设备上下文.

备注：

表1:

Permission flag

Description

Value

CRYPT_ENCRYPT

允许加密

0x0001

CRYPT_DECRYPT

允许解密

0x0002

CRYPT_EXPORT

允许导出

0x0004

CRYPT_READ

允许参数读取

0x0008

CRYPT_WRITE

允许参数设置

0x0010

CRYPT_MAC

允许密钥使用验证码

0x0020

The following tablelists the cipher modes that are currently defined.

Cipher mode

Description

Value

CRYPT_MODE_ECB

Electronic codebookg---是一个对一批密码进行操作的模式，其特性是每个可能的明文有一个定义的密码值与之对应，反之亦然

2

CRYPT_MODE_CBC

Cipher block chaining---一种操作分段密码的方式，将一段bit序列加密成一个单独的单元或分成一个密钥提供给整个部分

1

CRYPT_MODE_OFB

输出反馈模式

3

CRYPT_MODE_CFB

密码反馈模式

4

1.2.8 CPGetUserKey

功能：

从密钥容器中获取已持久化的用户密钥句柄:从容器中获取RSA的密钥文件ID标识和。

参数：

[in]hProv: CSP句柄

[in]dwKeySpec: 指定返回的密钥

值

描述

AT_KEYEXCHANGE

交换密钥

AT_SIGNATURE

签名密钥

[in]phUserKey:返回密钥句柄

返回值：

返回值

描述

NTE_BAD_KEY

无效的hKey参数

NTE_BAD_UID

未找到CSP上下文

NTE_NO_KEY

dwKeySpec参数不存在

1.2.9 CPImportKey

功能：

导入密钥

参数：

【in】hProv：CSP句柄

【in】pbData：包含Key BLOB的缓存区，这个Key BLOB由函数CPExportKey产生

【in】dwDataLen：导入Key BLOB的长度

【in】hPubKey：用来加密公钥的句柄

【in】dwFlags: 目前这个参数只是在公/私钥对通过公钥块导入到CSP时使用

【out】phKey：导入密钥句柄

【in】dwFlags：目前这个参数是用于一对公/私钥对导入CSP从PRIVATEKEYBLOB

参数

描述

CRYPT_EXPORTABLE

如果密钥导入后将被导出，必须设置些值

CRYPT_NO_SALT

指定是一个40bit的对称密钥，没有混合值

【out】phKey:一个被导出的密钥句柄的复本地址

返回值：

返回值

描述

NTE_BAD_ALGID

加密算法不支持

NTE_BAD_DATA

CSP不支持这个公钥导入算法

NTE_BAD_FLAGS

dwFlags参数非零

NTE_BAD_TYPE

CSP不支持这个key blob类型

NTE_BAD_UID

hProv不包括可用的CSP上下文设备

NTE_BAD_VER

key BLOB版本CSP不支持

NTE_NO_MEMORY

内存分配失败

1.2.10 CPSetKeyParam

功能：

设置密钥参数

参数：

【in】hProv：CSP句柄

【in】hKey：会话密钥句柄，指定了解密所使用的密钥句柄

【in】dwParam:参数列表如下

参数

描述

KP_SALT

一个BYTE数组，密钥当前包含的混合值

KP_SALT_EX

同上，但这个参数不能被用于公/私钥对，用于将返回NTE_BAD_TYPE错误

KP_PERMISSIONS

DWORD类型值，表示密钥允许的操作（访问权限），列表1中的参数可以与操作进行设置

KP_IV

BYTE数组，密钥的当前初始化变量

KP_PADDING

DWORD类型值，表示算法填充方法，

KP_MODE

DWORD类型值，算法加密模式；用于会话密钥

KP_MODE_BITS

DWORD类型值，表示返回算法的加密模式的反馈位数

KP_EFFECTIVE_KEYLEN

返回密钥的有效长度

KP_CERTIFICATE

写入证书:单容器单个证书，单容器双证书 ，多容器多证书，成功后注册证书到IE

KP_PUK

设置容器管理员口令

KP_PIN

设置用户口令

【in】pbData:指向接收数据的缓冲区指针

【in】dwFlags:未定义，设置为0

返回：

返回码

描述

NTE_BAD_FLAGS

dwFlags参数非零，或者pbData包含无效数据

NTE_BAD_TYPE

dwParam包括未知参数

NTE_BAD_UID

未发现CSP上下文

NTE_FAIL

未知错误

备注：

表1：

允许标志

描述

CRYPT_ENCRYPT

允许加密

CRYPT_DECRYPT

允许解密.

CRYPT_EXPORT

允许密钥导出

CRYPT_READ

允许参数读取

CRYPT_WRITE

允许设置参数.

CRYPT_MAC

允许密钥使用验证码

实现流程：