Personal CSP

This article applies to Windows only.

Personal Cryptographic Service Provider (CSP) is registered with the operating system and it allows use of tokens through Microsoft CryptoAPI (CAPI). Personal CSP is optimized for use with SSL in Internet Explorer to access secure web sites.

Personal Desktop includes a Microsoft CSP of type PROV_RSA_FULL. Hence, the tokens supported by Personal Token-API are exposed in the Microsoft CryptoAPI. The certificates in Personal Desktop are imported to, and removed from, Microsoft Certificate Store by a process continuously running in the personal.exe application.

Whenever necessary, the CSP will present a PIN dialog window, for input of the PIN code needed to access the private keys in the token. This will for example happen when accessing a secure web server that requests client authentication.

Introduction to Personal CSP

Any application using MS CAPI can automatically access the smart card and smart card reader support of Personal Desktop. Some examples of applications using this API are WinLogon, Microsoft Office 2003 (and later), Internet Explorer, and various VPN clients.

Personal CSP has the following characteristics:

Provider type: PROV_RSA_FULL
Provider name: Personal CSP

Implemented CSP functions

Function	Description
CSP Connection
`CPAcquireContext`	Acquires a handle to a key container in a particular CSP.
`CPGetProvParam`	Retrieves attributes from Personal CSP.
`CPReleaseContext`	Releases the handle acquired by the `CPAcquireContext` function.
`CPSetProvParam`	Specifies attributes of a CSP.
Key Management
`CPDestroyKey`	Destroys or releases a handle to a key.
`CPExportKey`	Transfers a key from the CSP to a key BLOB in the application's memory space.
`CPGenKey`	Generates a random key.
`CPGetUserKey`	Gets a handle to the key exchange or signature key.
`CPGenRandom`	Generates random data.
`CPGetKeyParam`	Retrieves the parameters of a key.
`CPImportKey`	Transfers a key from a key BLOB to a CSP.
`CPSetKeyParam`	Specifies the parameters of a key.
Hashing and Digital Signatures
`CPCreateHash`	Creates an empty hash object.
`CPGetHashParam`	Retrieves a hash object parameter.
`CPHashData`	Hashes a block of data and adds it to the specified hash object.
`CPSetHashParam`	Sets a hash object parameter.
`CPSignHash`	Signs the specified hash object.
Encryption
`CPDecrypt`	Decrypts a section of plain text by using the specified encryption key.

Exceptions from the MS CAPI specification

These are the deviations in the Personal CSP implementation of the Microsoft CryptoAPI functions.

Function	Exception
`CPAcquireContext()`	The flags CRYPT_VERIFYCONTEXT, CRYPT_SILENT, CRYPT_DELETEKEYSET, and CRYPT_NEWKEYSET are supported. The flag CRYPT_MACHINE_KEYSET is ignored. If this method is called with container parameter = NULL, the default key container will be used. The default key container in the configuration file will be used if specified, otherwise, Personal CSP will try to create a context according to the following principles: Use the first card reader having a smart card inserted. Use the first card reader without a card. A context will be created similar to if `CPAcquireContext` is called with the flag CRYPT_VERIFYCONTEXT. Personal CSP supports the following types of container names: Card reader containers using the Microsoft format: \\.\<reader_name>\. Example: \\.\Gemplus USB Smart Card Reader 0\. A container representing a certificate. The container name is then the SHA-1 hash of the certificate. Example: 90C75B312BEE4F8117EA90EDC7F8F395314ECFEA Other supported container names, described in “Container Name ”, are GUID (Globally Unique IDentifier) \\.\<reader>\<id> and \\.\<reader>\0x<id>
`CPGetProvParam()`	The query PP_KEYSET_SEC_DESCR is not supported. If a CSP function returns NTE_FAIL, it is possible to call `CryptGetProvParam` with dwParam=PP_NX_LAST_ERROR in order to get a more detailed explanation of the error situation. PP_NX_LAST_ERROR 0x80000001 The following error codes are defined: ERROR_NX_UNDEFINED 0x80007000 ERROR_NX_PIN_INCORRECT 0x80007001 ERROR_NX_PIN_BLOCKED 0x80007002 For each call to a CSP API function, the error code is reset to ERROR_NX_UNDEFINED. The error codes are set per thread. If several threads are running, only the one that got NTE_FAIL in return from CSP can call CryptGetProvParam to get PP_NX_LAST_ERROR. Parameter PP_NX_CONTEXT_FLAGS can be used to get more information about the token: NX_FLAG_HW_TOKEN 0x00000001 <text>Smart card token</text> NX_FLAG_HAS_PROTECTED_AUTH_PATH 0x00000002 <text>PIN-Pad reader</text> NX_FLAG_TOKEN_REMOVABL0E x00000004 <text>Token on removable media</text> NX_FLAG_TOKEN_PRESENT 0x00000008 <text>Token is available</text>
`CPSetProvParam()`	Parameter PP_KEYSET_SEC_DESCR is not supported. Additional supported parameters are: PP_KEYEXCHANGE_PIN (value 32) and PP_SIGNATURE_PIN (value 33). pbData should point to a string containing the PIN.
`CPExportKey()`	OPAQUEKEYBLOB and PRIVATEKEYBLOB are not supported.
`CPGenKey()`	If algorithm identifier AT_KEYEXCHANGE or AT_SIGNATURE is used, the flag CRYPT_USER_PROTECTED has to be set. The flag CRYPT_EXPORTABLE must not be set. Supported key lengths are 512, 768, 1024, and 2048 bits.
`CPGetKeyParam()`	Additional parameter value supported is KP_CERTIFICATE (value 26), which, if successful, will return a certificate associated with the key.
`CPImportKey()`	Supported key BLOB types are PUBLICKEYBLOB, SIMPLEBLOB and PRIVATEKEYBLOB.
`CPSetKeyParam()`	Additional parameter value supported is KP_CERTIFICATE (value 26). When using this parameter, a certificate is stored on the token having the key associated with this certificate.
`CPCreateHash()`	Supported mechanisms are CALG_SSL3_SHAMD5, CALG_MD5 and CALG_SHA1.
`CPHashData()`	CRYPT_USERDATA is not supported.
`CPSetHashParam()`	Supported parameter is HP_HASHVAL.
`CPSignHash()`	The flag CRYPT_NOHASHOID is supported for all tokens that support RSA with PKCS#1 padding. All soft tokens support this, and the requirement for cards is that no hash OID is added to the data that is signed.

Additional information

Useful links