CSP设计之-设备连接

1.1CSP连接函数

CSP 连接函数

CPAcquireContext

CPSetProvParam

CPGetProvParam

CPReleaseContext

 

 

 

 

 

 

1.1.1 CPAcquireContext

功能：

用来取得CSP 密钥容器句柄，以后的任何加密操作就是针对此句柄而言。由适当的dwFlags 标志，这个函数就可以创建和销毁密钥容器。

参数：

【out】 phProv：CSP句柄

【in】pszContainer：密钥容器名称指针，容器名最大长度不超过MAX_PATH。如果设置的dwFlags CRYPT_VERIFYCONTEXT，pszContainer必须设备为NULL。如果pszContainer输入NULL或零长度字符串，使用默认密钥容器名称。例如，微软RSA BaseProvider，使用默认密钥容器的名称作为当前用户的登录名称。其他CSP可以使用不同的默认密钥容器名称。

【in】dwFlags：一个标志位可以是0或者以下的标志位.

值	含义
CRYPT_VERIFYCONTEXT	应用程序没有访问的私钥和pszContainer参数必须设置为NULL。CryptAcquireContext被调用时，当使用此标志，并创建或导入公私密钥对，密钥被视为短暂使用，密钥只保留在内存中，当调用CPReleaseContext时自动销毁。
CRYPT_VERIFYCONTEXT_SM2	(国密算法)应用程序没有访问的私钥和pszContainer参数必须设置为NULL。CryptAcquireContext被调用时，当使用此标志，并创建或导入公私密钥对，密钥被视为短暂使用，密钥只保留在内存中，当调用CPReleaseContext时自动销毁。
CRYPT_NEWKEYSET	使用指定的密钥容器名称创建一个新的密钥容器。如果pszContainer 为NULL，密钥容器就使用却省的名称创建。
CRYPT_NEWKEYSET_SM2	(国密算法)使用指定的密钥容器名称创建一个新的密钥容器。如果pszContainer 为NULL，密钥容器就使用却省的名称创建。
CRYPT_DELETEKEYSET	删除由pszContainer 指定的密钥容器。如果pszContainer为NULL，却省名称的容器就会被删除。此时应用程序并不需要调用CryptReleaseContext来释放上下文。
CRYPT_DELETEKEYSET_SM2	删除由pszContainer 指定的密钥容器。如果pszContainer为NULL，却省名称的容器就会被删除。此时应用程序并不需要调用CryptReleaseContext来释放上下文。
CRYPT_SILENT	此标志指示不显示用户界面（UI）。如果任何之后函数调用要求有UI操作，函数调用必须失败并且最后一个错误设置为NTE_SILENT_CONTEXT。此标志的目的是为应用程序无法容忍的UI被显示的CSP使用。
CRYPT_MACHINE_KEYSET	此标志 （CSP不予做处理）

【in】pVTable：指向一个VTableProvStruc结构的指针，这个结构体包含由操作系统提供的CSP使用的回调函数列表的指针。（此参数设置为NULL）。

返回值：

如果成功返回 TRUE，否则返回 FALSE并通过GetLastError来获取错误码。

返回错误码	描述
NTE_BAD_FLAGS	dwFlags非法的
NTE_BAD_KEYSET	1.密钥容器不存在。 2.您无权访问密钥容器。 3."受保护的存储服务"没有运行。
NTE_BAD_KEYSET_PARAM	pszContainer值是非法的
NTE_BAD_SIGNATURE	辅助DLL的数字签名没有正确地验证。 DLL或数字签名已被篡改。
NTE_EXISTS	密钥容器已存在，但您正在尝试创建它。如果打开密钥的上次尝试以 NTE_BAD_KEYSET 失败，则意味着拒绝了对密钥容器的访问。
NTE_KEYSET_ENTRY_BAD	pszContainer 密钥容器被发现但是已经被破坏了。
NTE_KEYSET_NOT_DEF	制定的密钥容器不存在
NTE_NO_MEMORY	CSP内存耗尽
NTE_PROVIDER_DLL_FAIL	一个辅助的DLL文件无法加载，可能不存在。如果它存在，该文件是不是一个有效的DLL。

 1.1.2 CPSetProvParam

功能：

设置CSP 的各种参数。

参数：

【in】hProv：CSP句柄

【in】dwParam：一个DWORD值，确定查询的性质。下面的查询定义。

值	含义
PP_KEYEXCHANGE_PIN	验证使用交换密钥的PIN
PP_SIGNATURE_PIN	验证使用签名密钥的PIN
PP_CHANGE_PIN	(扩展指令)修改用户PIN
PP_UNBLOCK_PIN	(扩展指令)解锁用户PIN
PP_CA_CERTIFICATE	(扩展指令)导入CA证书
PP_INIT_TOKEN	(扩展指令)初始化Key：用于第三方开发定制使用，当前可以不实现。
PP_USE_HARDWARE_RNG	设定使用硬件产生随机数
PP_ROOT_CERTSTORE	设置智能卡的根证书存储。
PP_KEYSET_SEC_DESCR	设置一个注册表项，其中关键的一组存储的安全描述符。新的值包含在pbData。有关操纵的ACL信息，请参见Platform SDK中的Secperf.c。
PP_UI_PROMPT	对于智能卡供应商，将显示提示插入智能卡用户的搜索字符串。这个字符串被传递结构，通过的SCardUIDlgSelectCard功能的OPENCARDNAME_EX lpstrSearchDesc成员。此字符串用于调用进程的生命周期。pbData参数是null结尾的Unicode字符串，其中包含搜索字符串的地址。

根据需要，可以添加自定义的参数。通用参数可以与微软的协调，以促进跨供应商的标准化，并允许新的参数号码被添加到操作系统的标准头文件中定义。

【in】pbData：输入数据，根据不同的dwParam，数据内容不同。

【in】dwFlags：一个DWORD值有一下含义（CSP开发中用不到次参数） 

值	含义
OWNER_SECURITY_INFORMATION	被引用的对象自己标示符标。
GROUP_SECURITY_INFORMATION	被引用的对象的主要组标识符。
DACL_SECURITY_INFORMATION	对象的ACL被引用。
SACL_SECURITY_INFORMATION	被引用的对象的系统ACL。

返回值：

如果成功返回 TRUE，否则返回 FALSE并通过GetLastError来获取错误码。

返回码	描述
NTE_BAD_FLAGS	dwFlags 参数是无效的
NTE_BAD_TYPE	dwParam参数指定是未知的
NTE_BAD_UID	设备上下文句柄是无效的
NTE_FAIL	未知错误.

1.1.3 CPGetProvParam

功能：

获得CSP 的各种参数。

参数：

【in】hProv：CSP句柄

【in】dwParam：一个DWORD值，确定查询的性质。下面的查询定义。

值	含义
PP_CONTAINER	指向密钥名称的字符串
PP_CONTAINER_ALG	获取容器的算法标识
PP_KEYSPEC	密钥的用途
PP_READER	读卡器的名称
PP_CA_CERTIFICATE	获取CA证书
PP_USE_HARDWARE_RNG	硬件产生随机数
PP_ENUMALGS	不断的读出CSP 支持的所有算法。反复读的PP_ENUMALGS值必须列出所有支持的算法（没有在任何特定的顺序列举）。第一次被读取PP_ENUMALGS中，CRYPT_FIRST标志必须指定的dwFlags。这样做可以确保返回枚举列表中的第一个算法的信息。的PP_ENUMALGS然后可以反复阅读的dwFlags设置为零，以获取有关支持的算法其余的信息。当CPGetProvParam功能与的ERROR_NO_MORE_ITEMS错误代码失败，枚举列表的末尾已到达。这个函数不是线程安全的，而且，如果在一个多线程的上下文中使用此功能，所有可用的算法可能无法一一列举。
PP_ENUMALGS_EX	PP_ENUMALGS 获得更多的算法信息
PP_ENUMCONTAINERS	不断的读出CSP 支持的RSA类型的容器
PP_SM2_ENUMCONTAINERS	不断的读出CSP 支持SM2类型的容器
P_IMPTYPE	一个DWORD值，表明CSP是如何实现的。支持以下预定义的实施类型： CRYPT_IMPL_HARDWARE CRYPT_IMPL_SOFTWARE CRYPT_IMPL_MIXED CRYPT_IMPL_UNKNOWN
PP_KEYX_KEYSIZE_INC	交换密的位数
PP_KEYSET_SEC_DESCR	密钥的安全描述符
PP_NAME	指向CSP 名称的字符串
PP_PROVTYPE	一个DWORD值，表示提供的CSP类型。
PP_SIG_KEYSIZE_INC	签名密钥的位数
PP_UNIQUE_CONTAINER	当前密钥容器的唯一名称
PP_VERSION	CSP的版本号。最重要的字节包含次要版本号和未来最重要的字节包含主版本号。 2.0版本表示为0x00000200。为了保持向后兼容早期版本的Microsoft基本加密提供程序和Microsoft增强加密提供，供应商名称保留“V1.0”指定在以后的版本。
PP_ROOT_CERTSTORE	（默认调用微软接口）获取智能卡根证书存储
PP_SMARTCARD_GUID	（默认调用微软接口）获得了智能卡的标识。
PP_SMARTCARD_READER	（默认调用微软接口）获得智能卡阅读器的名称。
PP_USER_CERTSTORE	（默认调用微软接口）获得智能卡的用户证书存储

【out】pbData：数据缓冲区的指针。如果pbData为NULL，没有参数的数据被复制,返回需要的数据长度。

【inout】pdwDataLen：缓冲区的指针长度。进入函数时，它指向一个DWORD值，表示为pbData缓冲区分配的字节数。退出后，将DWORD值必须设置为返回时的pbData字节数。如果没有大到足以容纳所要求的数据由pbData指定的缓冲区，ERROR_MORE_DATA错误代码返回通过SetLastError功能。在这种情况下，所需的缓冲区大小必须在pdwDataLen返回。如果是其他错误，此长度必须设置为0。

【in】dwFlags：这个参数可以是下列标志之一。

值	含义
CRYPT_FIRST	与枚举混合使用。
CRYPT_MACHINE_KEYSET	（默认调用微软接口）忽略此标志。
SECURITY_INFORMATION	（默认调用微软接口）忽略此标志。

返回值：

如果成功返回 TRUE，否则返回 FALSE并通过GetLastError来获取错误码。

返回码	描述
ERROR_MORE_DATA	pbData缓冲区过小
ERROR_NO_MORE_ITEMS	枚举列表的末尾已到达。没有有效的数据被放置在pbData缓冲区中。
NTE_BAD_FLAGS	dwFlags 参数是无效的
NTE_BAD_TYPE	dwParam 指定一个未知参数
NTE_BAD_UID	CSP句柄被破坏

1.1.4 CPReleaseContext

功能：

函数释放由CPAcquireContext创建一个上下文。

参数：

【in】hProv：CSP句柄

【in】dwFlags：目前没有任何标志的定义。必须设置为0。

返回值：

如果成功返回 TRUE，否则返回 FALSE并通过GetLastError来获取错误码。

返回码	描述
NTE_BAD_FLAGS	无效的dwFlags值
NTE_BAD_UID	指定的CSP句柄已经失效

备注：

此函数被调用后，hProv句柄不再有效。在这个时候，所有的会话密钥和以前使用hProv手柄创建哈希对象都被销毁。理想的情况下，密钥和哈希对象已经被销毁，一个CSP调用中不应该由此函数来销毁会话密钥和哈希对象。