CryptAcquireContext function

CryptAcquireContext function

 

The CryptAcquireContext function is used to acquire a handle to a particular key container within a particular cryptographic service provider (CSP). This returned handle is used in calls to CryptoAPI functions that use the selected CSP.

获取一个指定的加密服务提供商的密钥容器。

获取一个密钥容器。

This function first attempts to find a CSP with the characteristics described in the dwProvType and pszProvider parameters. If the CSP is found, the function attempts to find a key container within the CSP that matches the name specified by the pszContainer parameter. To acquire the context and the key container of a private key associated with the public key of a certificate, use CryptAcquireCertificatePrivateKey.

With the appropriate setting of dwFlags, this function can also create and destroy key containers and can provide access to a CSP with a temporary key container if access to a private key is not required.

Syntax

C++

 

BOOL WINAPI CryptAcquireContext(
  _Out_ HCRYPTPROV *phProv,　　//指向CSP结构的指针。用于接收
  _In_  LPCTSTR    pszContainer,//指定一个容器名。如果为NULL，那么将会使用默认名。
  _In_  LPCTSTR    pszProvider,//指定CSP提供者的名称 https://msdn.microsoft.com/en-us/library/windows/desktop/aa380243(v=vs.85).aspx  MS_DEF_PROV
  _In_  DWORD      dwProvType,　　//指定需要的加密类型  https://msdn.microsoft.com/en-us/library/windows/desktop/aa380244(v=vs.85).aspx PROV_RSA_FULL
  _In_  DWORD      dwFlags //CRYPT_NEWKEYSET | CRYPT_MACHINE_KEYSET   -------CRYPT_NEWKEYSET:创建一个由pszContainer参数指定的名字的密钥容器
　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　　---------CRYPT_MACHINE_KEYSET：密钥容器存储在用户配置文件里如同用户密码一样。
　　　　　　　　　　------CRYPT_DELETEKEYSET：删除容器，如果没指定名字则删除默认容器并删除所有密钥对。
　　　　　　　　　　　-----CRYPT_SILENT：指定不显示UI窗口。

);//成功返回非零值

Parameters

phProv [out]

A pointer to a handle of a CSP. When you have finished using the CSP, release the handle by calling the CryptReleaseContext function.

指向CSP句柄的指针。

pszContainer [in]

The key container name. This is a null-terminated string that identifies the key container to the CSP.

密钥的容器名。这个以零结束的字符串标记CSP的密钥容器。

This name is independent of the method used to store the keys. Some CSPs store their key containers internally (in hardware), some use the system registry, and others use the file system. In most cases, whendwFlags is set to CRYPT_VERIFYCONTEXT, pszContainer must be set to NULL. However, for hardware-based CSPs, such as a smart card CSP, can be access publically available information in the specfied container.

For more information about the usage of the pszContainer parameter, see Remarks.

pszProvider [in]

A null-terminated string that contains the name of the CSP to be used.

If this parameter is NULL, the user default provider is used. For more information, see Cryptographic Service Provider Contexts. For a list of available cryptographic providers, see Cryptographic Provider Names.

An application can obtain the name of the CSP in use by using the CryptGetProvParam function to read the PP_NAME CSP value in the dwParam parameter.

The default CSP can change between operating system releases. To ensure interoperability on different operating system platforms, the CSP should be explicitly set by using this parameter instead of using the default CSP.

dwProvType [in]

Specifies the type of provider to acquire. Defined provider types are discussed in Cryptographic Provider Types.

dwFlags [in]

Flag values. This parameter is usually set to zero, but some applications set one or more of the following flags.

Value	Meaning
CRYPT_VERIFYCONTEXT	This option is intended for applications that are using ephemeral keys, or applications that do not require access to persisted private keys, such as applications that perform only hashing, encryption, and digital signature verification. Only applications that create signatures or decrypt messages need access to a private key. In most cases, this flag should be set. For file-based CSPs, when this flag is set, the pszContainer parameter must be set to NULL. The application has no access to the persisted private keys of public/private key pairs. When this flag is set, temporary public/private key pairs can be created, but they are not persisted. For hardware-based CSPs, such as a smart card CSP, if the pszContainer parameter is NULL or blank, this flag implies that no access to any keys is required, and that no UI should be presented to the user. This form is used to connect to the CSP to query its capabilities but not to actually use its keys. If the pszContainer parameter is not NULL and not blank, then this flag implies that access to only the publicly available information within the specified container is required. The CSP should not ask for a PIN. Attempts to access private information (for example, the CryptSignHash function) will fail. When CryptAcquireContext is called, many CSPs require input from the owning user before granting access to the private keys in the key container. For example, the private keys can be encrypted, requiring a password from the user before they can be used. However, if theCRYPT_VERIFYCONTEXT flag is specified, access to the private keys is not required and the user interface can be bypassed.
CRYPT_NEWKEYSET	Creates a new key container with the name specified by pszContainer. If pszContainer is NULL, a key container with the default name is created.
CRYPT_MACHINE_KEYSET	By default, keys and key containers are stored as user keys. For Base Providers, this means that user key containers are stored in the user's profile. A key container created without this flag by an administrator can be accessed only by the user creating the key container and a user with administration privileges.   Windows XP:  A key container created without this flag by an administrator can be accessed only by the user creating the key container and the local system account. A key container created without this flag by a user that is not an administrator can be accessed only by the user creating the key container and the local system account. The CRYPT_MACHINE_KEYSET flag can be combined with all of the other flags to indicate that the key container of interest is a computer key container and the CSP treats it as such. For Base Providers, this means that the keys are stored locally on the computer that created the key container. If a key container is to be a computer container, the CRYPT_MACHINE_KEYSET flag must be used with all calls toCryptAcquireContext that reference the computer container. The key container created with CRYPT_MACHINE_KEYSET by an administrator can be accessed only by its creator and by a user with administrator privileges unless access rights to the container are granted usingCryptSetProvParam.   Windows XP:  The key container created with CRYPT_MACHINE_KEYSET by an administrator can be accessed only by its creator and by the local system account unless access rights to the container are granted using CryptSetProvParam. The key container created with CRYPT_MACHINE_KEYSET by a user that is not an administrator can be accessed only by its creator and by the local system account unless access rights to the container are granted using CryptSetProvParam. The CRYPT_MACHINE_KEYSET flag is useful when the user is accessing from a service or user account that did not log on interactively. When key containers are created, most CSPs do not automatically create any public/private key pairs. These keys must be created as a separate step with the CryptGenKey function.
CRYPT_DELETEKEYSET	Delete the key container specified by pszContainer. If pszContainer is NULL, the key container with the default name is deleted. All key pairs in the key container are also destroyed. When this flag is set, the value returned in phProv is undefined, and thus, the CryptReleaseContext function need not be called afterward.
CRYPT_SILENT	The application requests that the CSP not display any user interface (UI) for this context. If the CSP must display the UI to operate, the call fails and the NTE_SILENT_CONTEXT error code is set as the last error. In addition, if calls are made to CryptGenKey with the CRYPT_USER_PROTECTED flag with a context that has been acquired with the CRYPT_SILENT flag, the calls fail and the CSP sets NTE_SILENT_CONTEXT. CRYPT_SILENT is intended for use with applications for which the UI cannot be displayed by the CSP.
CRYPT_DEFAULT_CONTAINER_OPTIONAL	Obtains a context for a smart card CSP that can be used for hashing and symmetric key operations but cannot be used for any operation that requires authentication to a smart card using a PIN. This type of context is most often used to perform operations on an empty smart card, such as setting the PIN by using CryptSetProvParam. This flag can only be used with smart card CSPs.   Windows Server 2003 and Windows XP:  This flag is not supported.

 

Return value

If the function succeeds, the function returns nonzero (TRUE).

If the function fails, it returns zero (FALSE). For extended error information, call GetLastError.