DCSP

DEKART CRYPTO SERVICE PROVIDER
USER'S GUIDE
DEKART Crypto Service Provider
Users Guide
APPLICATION DATE
16/10/1999
Note : Restricted distribution
DOCUMENT WRITTEN BY
Department SCT Name Kutsy Alexander Petrova Olga Function Date 16/10/1999 Visa
DOCUMENT APPROVED BY
Department SCT Name Function Date Visa
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
1 / 116
Copyright Dekart S.R.L (www.dekart.com)- 1999 This document shall not be disclosed to a third party without prior written consent of Dekart S.R.L.
USER'S GUIDE
MODIFICATION SHEET
Date of update
16/10/99
modified part
-
new revision index

1.0 First release
modifications
(Type and description)
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
2 / 116
USER'S GUIDE
Contents
Purpose ................................................................................................................................................................. 4 Developer Audience .............................................................................................................................................. 4 1 ABOUT CRYPTOGRAPHIC SERVICE PROVIDERS................................................................................. 5 1.1 ARCHITECTURE OF A CRYPTOGRAPHIC SERVICE PROVIDER (CSP) ................................................................ 5 1.1.1 CSP Architectural Overview ................................................................................................................. 5 1.1.2 Entry Points........................................................................................................................................... 6 1.1.3 Persistent Data Objects......................................................................................................................... 7 1.1.4 Volatile Data Objects............................................................................................................................ 8 1.2 WRITING A CSP ............................................................................................................................................. 9 1.2.1 Creating the CSP DLL .......................................................................................................................... 9 1.2.2 Writing the CSP Setup Program ......................................................................................................... 10 1.2.3 Test Signing the CSP........................................................................................................................... 12 1.2.4 Testing the CSP ................................................................................................................................... 13 1.2.5 Getting the CSP Signed....................................................................................................................... 13 1.2.6 Extending CryptoAPI .......................................................................................................................... 15 1.3 CSP INTEROPERABILITY .............................................................................................................................. 16 1.3.1 Supported Algorithms.......................................................................................................................... 17 1.3.2 Key BLOB Formats ............................................................................................................................. 18 1.3.3 Deriving Session Keys......................................................................................................................... 21 1.3.4 Hashing Session Keys ......................................................................................................................... 22 1.3.5 Digital Signature Mechanics............................................................................................................... 22 2 USING A CRYPTOGRAPHIC SERVICE PROVIDER............................................................................... 26 2.1 USING CSPS: GENERAL PROCESSES............................................................................................................. 26 2.1.1 Example Program Limitations ............................................................................................................ 26 2.1.2 Retrieving Data of Unknown Length................................................................................................... 26 2.1.3 Enumerating Supported Protocols ...................................................................................................... 29 2.2 USING SCHANNEL CSPS .............................................................................................................................. 30 2.2.1 Public/Private Key Pair Usage ........................................................................................................... 30 2.2.2 SHA/MD5 RSA Signature Type ........................................................................................................... 31 2.2.3 Creating the Master Key ..................................................................................................................... 31 2.2.4 Deriving Bulk Encryption and MAC Keys .......................................................................................... 39 2.2.5 Finish Messages (TLS 1.0) .................................................................................................................. 43 2.2.6 Bulk Data Encryption.......................................................................................................................... 44 2.2.7 Crossing Process Boundaries ............................................................................................................. 44 2.2.8 Opaque BLOB Type ............................................................................................................................ 44 3 CRYPTOGRAPHIC SERVICE PROVIDER REFERENCE....................................................................... 46 3.1 CSP FUNCTIONS .......................................................................................................................................... 46 3.1.1 CSP Connection Functions ................................................................................................................. 46 3.1.2 Key Generation and Exchange Functions........................................................................................... 58 3.1.3 Data Encryption Functions ................................................................................................................. 82 3.1.4 Hashing and Digital Signature Functions........................................................................................... 87 3.1.5 CSP Auxiliary Functions................................................................................................................... 105 3.2 CSP STRUCTURES AND TYPES ................................................................................................................... 106 3.2.1 PROV_ENUMALGS.......................................................................................................................... 106 3.2.2 PROV_ENUMALGS_EX................................................................................................................... 107 3.2.3 VTableProvStruc............................................................................................................................... 108 3.2.4 BLOBHEADER ................................................................................................................................. 111 3.3 CSP CONSTANTS ....................................................................................................................................... 116 3.3.1 Protocol Flags................................................................................................................................... 116 DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 3 / 116
USER'S GUIDE
Purpose
A Cryptographic Service Provider (CSP) contains implementations of cryptographic standards and algorithms.
Developer Audience
This documentation is written for CSP developers. It defines the CSP interfaces, describes the procedures a CSP writer must use, and the requirements that a CSP writer must fulfill to create a custom CSP. While information in this documentation is primarily intended for a person writing a CSP, it can also be of interest to advanced application developers.
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
4 / 116
USER'S GUIDE
1 About Cryptographic Service Providers

A Cryptographic Service Provider (CSP) contains implementations of cryptographic standards and algorithms. At a minimum, a CSP consists of a dynamic-link library (DLL) that implements the functions in CryptoSPI (a system program interface). Most CSPs contain the implementation of all of their own functions; however, some CSPs implement their functions mainly in a Microsoft Win32-based service program managed by the Win32 service control manager. Others implement functions in hardware, such as a smart card or secure coprocessor. If a CSP does not implement its own functions, the DLL acts as a pass-through layer, facilitating the communication between the operating system and the actual CSP implementation. This documentation is written for CSP developers. It defines the CSP interfaces, describes the procedures a CSP writer must use, and the requirements that a CSP writer must fulfill to create a custom CSP. While information in this documentation is primarily intended for a person writing a CSP, it can also be of interest to advanced cryptography application developers. This documentation maintains a focus on creating a CSP and assumes familiarity with Crypto API in the Microsoft Platform SDK. The following related subjects, which a CSP developer must be familiar with to implement a CSP, are not covered: Cryptography Cryptographic protocols and standards Cryptographic application programming Microsoft Windows programming
1.1 Architecture of a Cryptographic Service Provider (CSP)

1.1.1 CSP Architectural Overview
Applications do not communicate directly with a CSP. Instead, applications call CryptoAPI functions exposed by the operating system's Advapi32.dll and Crypt32.dll files. The operating system filters these function calls and passes them on to the appropriate CSP functions through CryptoSPI (a system program interface).
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
5 / 116
USER'S GUIDE
The CSP writer must know the nature, order, and meaning of parameters passed by the operating system to the CSP functions and must return the values as expected to the operating system.
Applications use handles to refer to data objects within the CSP. Objects that are referenced by their handles include key containers, hash objects, session key objects, and public/private key pair objects. These handles are opaque from both sides; that is, the handle that the application uses to access a data object is not the same one that the CSP uses. For various reasons, the operating system layer always accesses data objects indirectly using handles.
1.1.2
Entry Points
All custom CSPs must support all of the following DLL entry points:
DSSSCT
CPAcquireContext CPCreateHash CPDecrypt CPDeriveKey CPDestroyHash CPDestroyKey CPEncrypt CPExportKey

File : dcsp Ref : DSPUSG990001 Revision : 1.0 6 / 116
USER'S GUIDE
CPGenKey CPGenRandom CPGetHashParam 7 CPGetKeyParam CPGetProvParam CPGetUserKey CPHashData CPHashSessionKey CPImportKey CPReleaseContext CPSetHashParam CPSetKeyParam CPSetProvParam CPSignHash CPVerifySignature
All PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL CSPs must also support all of the following DLL entry points: These entry points are optional for other custom CSPs): CPDuplicateHash CPDuplicateKey
These functions compose the CryptoSPI system program interface. Each function corresponds directly to a CryptoAPI cryptographic function.
1.1.3
Persistent Data Objects
The CSP stores public/private key pairs from session to session in persistent memory. A CSP implemented completely in software can store these keys, in encrypted form, in the system registry. CSPs with a hardware component might store the key pairs in tamper-resistant hardware.
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
7 / 116
USER'S GUIDE
The key pairs are stored in logical data objects called key containers. The CSP maintains one key container for each user or client that uses that CSP. Each key container can store one key pair of each type that the CSP supports. For example, the Microsoft Base Cryptographic Provider supports two key pair types: the key exchange key pair and the digital signature key pair. Several key containers can be open at any given time (either by a single application or multiple ones). Each call to a CryptoSPI function specifies the key container to be used with one of the parameters of the function. This is illustrated by the following drawing.
Note In the CryptoSPI context, the HCRYPTPROV data type is a handle to a particular key container within the CSP. In the CryptoAPI context, the HCRYPTPROV data type is a handle for both a key container and the CSP to be used.
1.1.4
Volatile Data Objects
A CSP maintains session key objects and hash objects in volatile memory. These objects are created using the CPGenKey and CPCreateHash functions, respectively. These objects are destroyed using CPDestroyKey and CPDestroyHash. They must be destroyed when their associated key container or user context is released by CPReleaseContext. The objects maintained in volatile memory are accessed using their handles as shown below.
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
8 / 116
USER'S GUIDE
The CRYPT_VERIFYCONTEXT flag can be passed as the dwFlags parameter to CPAcquireContext to enable that function to create volatile private keys. Volatile private keys are required for PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL CSPs.
1.2 Writing a CSP

This section outlines the steps used to write, test, and implement a custom CSP. Before writing a CSP, a writer must accomplish two tasks: Select the cryptographic algorithms and data formats to be included. Obtain implementations for each algorithm and data format.
1.2.1
Creating the CSP DLL
A CSP DLL is created like any other DLL. This procedure is explained in the MSDN documentation. For a CSP with hardware components, the DLL might involve writing a smart card device driver or the embedded code that runs on the card. For information on writing any needed device drivers, see the Microsoft Device Developer Kit (DDK). Every custom CSP DLL must expose all of the CryptoSPI functions listed in Entry Points. If a CSP does not actually support a particular function, a call to that function must at least return the E_NOTIMPL error code. A CSP that does not perform all of the cryptographic processes can be created; for example, a CSP specializing in signature verification that does not support data encryption functions.
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
9 / 116
USER'S GUIDE
Custom CSPs may involve more than one DLL; however, this is discouraged because it can create run-time complications. For more information, see CPAcquireContex. Regardless of the number of DLLs used for a custom CSP, all of them must be signed by Microsoft to enable the CSP to be used with the released versions of Windows 2000, Windows NT, or Windows 95 and later.
1.2.2
Writing the CSP Setup Program
Part of creating a CSP is providing for its installation. At a minimum, a CSP must include a setup program that: Copies the CSP DLL to a directory pointed to by the PATH environment variable. Creates the appropriate registry entries.
1.2.2.1 Registering the CSP A CSP is registered under the following registry key: HKEY_LOCAL_MACHINE SOFTWARE Microsoft Cryptography Defaults Provider The following registry entries under the above hKey register the CSP with the operating system. <CSP name> >Image Path:REG_SZ:<CSP DLL name> >Signature:REG_BINARY:<digital signature> >Type:REG_DWORD:<CSP type> The <CSP name> entry is the text name of the CSP. If the CSP has been signed by Microsoft Corporation, this name must exactly match the CSP name that was specified in the Export Compliance Certificate (ECC). The <CSP DLL name> (Image Path) entry is the name of the CSP DLL. If a fully qualified path, such as C:\Myx\Rsabase.dll is specified, the CSP DLL need not be placed in a directory pointed to by the PATH environment variable. The <digital signature> (Signature) entry is the digital signature file for the CSP DLL. This signature file can be either the debug signature created with the Sign.exe utility or the release signature obtained from Microsoft. With Windows 2000, the signature can be in a resource within the CSP. Sign.exe is discussed in Test Signing the CSP.
DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 10 / 116
USER'S GUIDE
The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025.
1.2.2.2 Setting the Machine Default CSP One machine default CSP can be specified for each CSP type. The machine default CSP is used if an application calls CryptAcquireContext with only a CSP type specified and no user default CSP registry entry exists. Unless there are important reasons for setting up a custom CSP as the machine default CSP, the normal default CSP should not be changed. If a custom CSP must be used, the setup program can install its CSP as the machine default. If the normal default is to be changed, the following registry entry sets the machine default CSP: HKEY_LOCAL_MACHINE SOFTWARE Microsoft Cryptography Defaults Provider Type Type <CSP type> >Name:REG_SZ:<CSP name> The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025. The <CSP Name> entry must be set to the textual name of the CSP. This must exactly match the <CSP Name> registry key discussed in Registering the CSP.
1.2.2.3 Setting the User Default CSP One user default CSP can be specified for each CSP type. The user default CSP is used when an application calls CryptAcquireContext with only a CSP type specified. Unless there are important reasons for setting up a custom CSP as the user default CSP, the normal default CSP should not be changed. If the user default CSP must be changed, user defaults are stored in the registry's HKEY_CURRENT_USER window and can only be set if the actual end user is currently logged on to the computer. In any case, the end user should be consulted or informed whenever the user default CSP is changed. The user default CSP is set using the CryptSetProvider function, which internally sets the following registry entry: HKEY_CURRENT_USER Software
USER'S GUIDE
Microsoft Cryptography Provider Type<CSP type> >Name:REG_SZ:<CSP name> The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025. The <CSP name> entry must be set to the textual name of the CSP. This must exactly match the <CSP name> registry key discussed in Registering the CSP.
1.2.3
Test Signing the CSP
A CSP DLL must be signed each time it is built. This includes each build of the CSP that is made for testing purposes. Prior to Windows 2000, the signature is placed appropriately in the registry. Windows 2000 introduces signing a CSP digitally in a resource in the CSP DLL. This eliminates problems with signatures in the registry getting out of synchronization with the CSP binaries on the system. Old signature checking in the registry is still supported in Windows 2000 so CSPs with signatures in that form continue to work. To support the same CSP binary on Windows 2000 computers and Windows NT 4.0 and Windows 95 and later computers, some CSPs may need to be signed both in the resource and in the registry using the old signature form. Windows 2000 continues to support CSPs verifying signatures on loaded DLLs using the FuncVerifyImage callback function from the VTableProvStuc structure passed to the CSP with CPAcquireContext. To use the callback in this way, the pointer to the signature, parameter 1, must be set to NULL. To support the new signature format, the CSP must provide a 144 byte binary resource numbered 0x29A (decimal 666). The signature is placed in this resource. A makefile can be used for the creation process of a CSP to incorporate this signing and registering procedure so that no steps are forgotten. Sign Utility The Sign.exe utility signs CSP DLLs. Given a DLL file, the utility produces a signature file whose contents can be placed into the registry as discussed above and in Setting the User Default CSP. Sign.exe takes three arguments:
sign {s|v} <filename> <signature file>
The first argument must be s if a signature file is to be generated and v if an existing signature file is to be verified against the DLL file. The second argument must be the fully qualified file
USER'S GUIDE
name of the DLL file. The third argument must be the fully qualified file name of the signature file. For the CSP DLL file Myxcsp.dll, the following command generates a signature file. The signature file will be named Myxcsp.sig.
sign s myxcsp.dll myxcsp.sig
1.2.4
Testing the CSP
In accordance with the U.S. Department of Commerce's export restrictions concerning cryptography, Microsoft must digitally sign a CSP so that it will run on Microsoft operating systems. The Microsoft Cryptographic Service Provider Developer's Kit (CSPDK) is designed to help test a CSP. After the CSP has been tested and it is ready for signing, send e-mail to cspsign@microsoft.com. Note that Microsoft can only distribute the CSPDK to legal residents of the U.S. and Canada. Information on how to obtain the CSPDK can http://www.microsoft.com/security/tech/cryptoapi/cspdkintrocontent.asp. CSP testing involves the following steps: 1. Sign the CSP with the Sign.exe utility to produce a debug signature (.sig) file. For more information, see Test Signing the CSP. 2. Install the CSP using the setup program written for the CSP 3. Run test code that calls CryptoAPI functions to test the CSP's implementations of those functions. Developers of CSPs for Microsoft Windows CE must develop and test their CSP using the x86 emulator from the CSPDK using Windows CE running natively on a PC. be found at
1.2.5
Getting the CSP Signed
A CSP must be digitally signed by Microsoft to be used with the released versions of Windows 2000, Windows NT, or Windows 95 and later. The digital signature separates applicable legal export controls on the CSP from the host operating system and applications, thereby allowing broader distribution of encryption-enabled products than would be possible under other circumstances. Generally, U.S. export law limits the export outside the U.S. or Canada of products that host strong encryption or an open cryptographic interface. The digital signature requirement effectively prevents arbitrary use of CryptoAPI, and allows export of the host operating system and CryptoAPI-enabled applications. By removing encryption services from
USER'S GUIDE
host systems and applications, CryptoAPI places the burden of U.S. encryption export restrictions squarely on the CSP vendor, who is subject to those controls regardless. In addition, the operating system validates this signature periodically to ensure that the CSP has not been changed. Microsoft's interests in applying signatures to CSPs are To ensure the exportability of CryptoAPI-enabled systems and applications To exercise due diligence under prevailing U.S. and other national export controls. To help maintain the integrity of the CSP
Any disclosure requested by Microsoft is used solely to determine whether export approval is required, or if sufficient export approval exists, for Microsoft to sign a vendor's CSP. Vendors must complete and return an Export Compliance Certificate (ECC) to Microsoft. A copy of the ECC is included at the end in Export Compliance Certificate (ECC). Vendors developing a CSP for distribution only in the U.S. and Canada only need to compete and return the EEC. Vendors who expect to export a CSP outside the U.S. and Canada must obtain export approval from a U.S. or Canadian export licensing authority or claim an exemption under U.S. export law. The completed ECC must contain evidence of export approval or exemption, and certify that the CSP is intended for export outside the U.S. or Canada. Microsoft independently confirms export approval, and when confirmation is complete, will return information on arrangements to sign the CSP. Microsoft makes every effort to review the ECC and sign CSPs as expeditiously as possible. Exact time frames for review and signing depend on the circumstances of each request. Vendors should consult legal counsel or U.S. export authorities to determine whether an export approval or exemption applies to their CSP. Questions and comments about the CSP signing mechanism, signing procedures and CryptoAPI licensing policy can be sent by email to cspsign@microsoft.com. CSP Vendors can also consult U.S. Commerce Department, Bureau of Export Administration Office of Exporter Services for assistance in the classification and/or export licensing of CSPs for export from the U.S. The US Commerce Department's export license process, encryption export controls, and points of contact are described on their Web site at http://www.bxa.doc.gov/encstart.htm.
USER'S GUIDE
Microsoft will sign CSPs subject only to the limitations of U.S. export controls. Microsoft will sign CSPs from competitors. At present, CSPs are signed at the Microsoft facilities in Redmond, Washington, USA. For further information, see Microsofts CSP Signing Policy.
1.2.6
Extending CryptoAPI
CryptoAPI has been designed to be easily extensible. New types and parameters can be defined by any CSP author to make the CryptoAPI bend to the requirements of a wide variety of situations. Extensible items Provider types Comment A provider type represents a particular family or type of cryptographic services. New provider types can be defined, each serving a particular niche. Provider parameters are sent and received using CPSetProvParam and CPGetProvParam, respectively. New provider parameters could allow a CSP to be configured in ways not foreseen by the CryptoAPI designers. The enumeration facilities of CPGetProvParam allow applications to list algorithm identifiers dynamically. New symmetric, public-key, and hash algorithms can be defined at any time. While new key pair types can be defined as needed, currently only signature and key exchange key pairs are used. New key BLOB types could permit session keys, public keys, and public/private key pairs to be exchanged in a flexible manner using the CPExportKey and CPImportKey functions. Key parameters are sent and retrieved using CPSetKeyParam and CPGetKeyParam. New key parameters could enable support for many different types of keys. Hash object parameters are sent and retrieved using CPSetHashParam and CPGetHashParam. New hash object parameters could enable support for many different types of hashes. Most CryptoAPI/CryptoSPI functions have a dwFlags parameter. New dwFlags values could modify the behavior of functions as
Provider parameters
Algorithm identifiers
Public/private key pair types
Key BLOB types
Key parameters
Hash object parameters
Flag values
DSSSCT
USER'S GUIDE
necessary. Extensions to CryptoAPI must be made in a responsible manner. Before defining new parameters and algorithm types, a CSP developer should consult Microsoft Corporation, so that: Common CryptoAPI extensions can be identified and placed into the standard Microsoft Win32 Wincrypt.h file. Namespace collisions can be avoided. It can be determined if the extension is required, or whether a particular operation can be achieved with the current API.
Note For a CSP to be compatible with applications developed for the Microsoft Base Cryptographic Provider, it must support all of the preceding items as described in CryptoAPI Reference and in Cryptographic Service Provider Reference.
1.3 CSP Interoperability

To provide for interoperability with other cryptographic service providers (CSPs), any PROV_RSA_FULL CSP must conform to specific implementation requirements. The PROV_RSA_SIG provider type is a subset of PROV_RSA_FULL and not all of the implementation requirements discussed apply to PROV_RSA_SIG providers. Major areas that must conform to implementation requirements are listed in the following table. Major requirement Supported algorithm Description The minimum set of algorithms that must be supported by all PROV_RSA_FULL and PROV_RSA_SIG providers. The standard encoding schemes for key BLOBs. Using standard encoding schemes enables keys to be exchanged between CSPs even if the CSPs come from different vendors. The procedure for deriving session keys from hash values so that given the same base data, every CSP generates exactly the same session key. The procedure for hashing session keys so that
Ref : DSPUSG990001 Revision : 1.0 16 / 116
Key BLOB formats
Deriving session keys
Hashing session keys

DSSSCT File : dcsp
USER'S GUIDE
given the same session key, every CSP generates exactly the same hash value. Digital signature mechanics The mechanics of digital signatures and signature format so that different CSPs can verify each other's signatures.
1.3.1
Supported Algorithms
All PROV_RSA_FULL or PROV_RSA_SIG providers must support a minimum set of algorithms. Additional algorithms can be implemented, but for security reasons this is discouraged. See the providers listed under Microsoft Cryptographic Service Providers for lists of the algorithms that must be supported. Supported algorithms include: Public Key Algorithms Symmetric Encryption Algorithms Hashing Algorithms
1.3.1.1 Public-Key Algorithms All PROV_RSA_FULL and PROV_RSA_SIG CSPs use the RSA Public-Key Cipher for both digital signatures and key exchange. Two public/private key pairs are defined: the signature key pair and the exchange key pair. The exchange key pair can be used both to exchange session keys and to verify digital signatures. Although the Microsoft Base Cryptographic Provider uses 512-bit public/private keys, this is not a requirement. A new CSP is free to use larger keys, although using larger keys makes a CSP subject to controls on exports outside the United States and Canada. For more information on export control, see Microsofts CSP Signing Policy. The CPVerifySignature function of all CSPs must be able to verify signatures of up to 2048 bits, regardless of the size of the signatures produced by CPSignHash. This ensures that the CSP will be able to validate all compatible certificates, even those signed with large keys. This requirement may be difficult for CSPs implemented in hardware packages with limited memory. It may be necessary for some hardware CSPs to implement a software signature verification algorithm within the primary DLL.
USER'S GUIDE
1.3.1.2 Symmetric Encryption Algorithms Every PROV_RSA_FULL or PROV_RSA_SIG CSP must provide an implementation of the RC2 block cipher and the RC4 stream cipher encryption. These algorithms are used to create session keys for bulk data encryption and decryption. The Microsoft Base Cryptographic Provider uses 40-bit session keys with 88-bit salt values (128 bits total). A new CSP is free to use larger keys, although using longer keys makes exporting the CSP outside the USA and Canada more difficult. Currently, code containing 56-bit encryption and 1024-bit key exchange can be freely exported. For more information on export control, see Microsofts CSP Signing Policy. In addition, using a session key larger than 40-bits makes key exchange with a Microsoft Base Cryptographic Provider more difficult.
1.3.1.3 Hashing Algorithms Every PROV_RSA_FULL or PROV_RSA_SIG CSP must provide implementations of both the MD5 and the SHA hash functions. In addition, supporting the MD2 algorithm is helpful if compatibility is important. To be interoperable with the Microsoft Cryptographic Service Provider, a CSP must also support the SSL3 Client Authentication algorithm.
1.3.2
Key BLOB Formats
Key BLOBs are structures that store keys outside a CSP key container. Every key BLOB consists of one or more fixed-length header structures followed by the key data itself. The key data is variable in length and is often encrypted. Key BLOBs consist of binary data. The size of a key BLOB varies depending on the BLOB type and the key size. Unless stated otherwise, all multibyte numbers are stored in little-endian format; that is, the first byte of a number is the least significant and the last byte is the most significant. For example, the four byte hexadecimal number 0x12345678 will be stored as:
78 56 34 12
This is the most common format for computers running versions of Microsoft Windows. Standard structure formats include the following. Structure format BLOBHEADER
DSSSCT File : dcsp
Description Structure used at the beginning of all key BLOB structures.

USER'S GUIDE
Public Key BLOBs Private Key BLOBs Simple Key BLOBs
BLOB structure that contains a public key. BLOB structure that contains a private key in encrypted form. BLOB structure that contains an encrypted session key.
1.3.2.1 Building a Simple Key BLOB Two data items are required before a SIMPLEBLOB structure can be built: the session key to be transported and the public key used to encrypt the session key. This example shows a typical 40-bit RC4 session key and a public key used to encrypt it. In this example, the hexadecimal value of the session key material is:
74 4f 06 35 3f
The first step is building the PKCS #1, type 2 encryption block. This is always the same size as the public key's modulus (64 bytes) and contains the following fields. Field Bytes Description Session key material. The size of this field varies depending on the size of the session key. Key material 1 to 5 The bytes in the session key data are reversed before they are placed in the encryption block because the operating system formats data in little-endian format, and the encryption block must be built in bigendian format. Zero value. Random padding data. The size of this field is adjusted as necessary so that the encryption block's overall length is correct. It can be longer than the 50 bytes indicated here if a longer RSA key is used. None of these bytes are allowed to be zero. The PKCS block type (0x02). Zero value.
Reserved
Padding
7 to 56
Block type Reserved
57 58
The order of this table is reversed from the diagram found in the PKCS documentation because the encryption block is built in big-endian format on a little-endian computer. After the encryption block has been built, its sixty-four byte hexadecimal value could look something like this:
3f 35 b1 74 99 8a b0 2e dc ac DSSSCT 06 b0 4d 93 9e 4f de 19 fe 9f 74 00 c9 db 8e d4 aa c5 4f 0f ed 24 e9 f4 d4 93 3a 62 be f1 File : dcsp
Ref : DSPUSG990001
Revision : 1.0
19 / 116
DEKART CRYPTO SERVICE PROVIDER e4 1d 44 5c 33 e5 2f 4f 58 01 95 16 36 f7 86 65 68 6c 2a 28 79 55 02 00
USER'S GUIDE
Next, the block is encrypted with the appropriate public key. After this is done, the encrypted block might look like this:
e3 e9 74 f0 27 3e 92 38 c1 50 c7 6c a5 93 e8 d3 78 89 54 ee 99 ba aa 1f 62 fd 19 86 63 9a 15 08 c4 0d bd 05 c4 ea 2c e2 1f 58 97 74 6f 36 50 82 51 bd 3b 16 95 cc a1 cd 4f 9d a0 62 ed 96 3c 90
Finally, the BLOBHEADER structure and the algorithm identifier are tacked onto the front of the encryption block, resulting in a complete SIMPLEBLOB data structure:
01 00 c4 0d bd 05 c4 ea 2c 82 02 a4 1f 58 97 74 6f 36 50 cd 00 00 51 bd 3b 16 95 cc a1 90 00 00 4f 9d a0 62 ed 96 3c 2b 01 e3 e9 74 f0 27 3e 92 d3 68 c1 50 c7 6c a5 93 e8 1f 00 78 89 54 ee 99 ba aa 08 00 62 fd 19 86 63 9a 15 e2
Note The encrypted block begins at byte 13. The BLOBHEADER structure and the algorithm identifier have been assigned the following values:
blobheader.bType blobheader.bVersion blobheader.Reserved blobheader.aiKeyAlg algid = = = = SIMPLEBLOB; CUR_BLOB_VERSION; 0; CALG_RC4; // // // // // // // // // 0x01 in byte number 1 0x02 in byte number 2 0x0000 in bytes 3 and 4 0x00006801 in reverse order in bytes 5, 6, 7, and 8 0x0000a400 in reverse order in bytes 9, 10, 11, and 12
= CALG_RSA_KEYX;
When filling in the BLOBHEADER structure, the two Reserved field bytes are set to zero.
1.3.3
Deriving Session Keys
Applications derive session keys from hash values by using the CryptDeriveKey function. The underlying mechanism is: The required number of bytes from the beginning of the hash value become the session key material. If the CRYPT_CREATE_SALT flag is specified, additional bytes from the hash are used. The remaining bytes of the hash value are not used.
USER'S GUIDE
For example, from a 160-bit SHA hash value, a 40-bit session key with an 88-bit salt value can be created. The first five bytes (40 bits) of the hash are the session key material and the next 11 bytes are the salt. The last 4 bytes of the hash are unused. Note Hash values and session keys are viewed as blocks of binary data, not large integers; therefore, byte ordering (that is, big-endian versus little-endian format) is not relevant.
1.3.3.1 Key Derivation Sample The example data in this section was generated using the Microsoft Base Cryptographic Provider. In a particular instance with another provider, the session key length and salt length can be different, but the basic process is the same. Assume an application will derive a session key from a hash of the password, "124-kelp". The password is hashed using CryptHashData specifying the MD5 hash algorithm. The following sixteen-byte hash value is generated.
73 40 e6 e2 74 b8 ea 39 93 95 aa 29 d6 38 b5 2a
The application calls CryptDeriveKey to create the session key, which in this case is an RC4 stream cipher key. The CSP uses the first five bytes of the previous hash value, 73 40 e6 e2 74, as the key itself. If the CRYPT_CREATE_SALT flag is not specified, the key is given a salt value of zero. Using this session key to encrypt the following plaintext buffer:
00 08 10 18 26 11 04 8d 01 09 11 19 59 0c 2e d5 02 0a 12 1a de bb e3 b4 03 0b 13 1b 24 9d ba 2f 04 0c 14 1c 44 b6 72 56 05 0d 15 1d fa a2 76 cf 06 0e 16 1e 36 bd f3 f8 07 0f 17 1f 9c 24 27 c9
generates the following ciphertext data:
If the application specifies the CRYPT_CREATE_SALT flag during the CryptDeriveKey function call, the key is given the following 11-byte salt value:
b8 ea 39 93 95 aa 29 d6 38 b5 2a
Using the key with the added salt value to encrypt the plaintext generates the following ciphertext:
47 95 da c3 f4 bc a2 b9 5d fc 91 ec e2 39 fb 91 cc fb 80 dd 3b 86 f1 9f 87 d3 2a af 1b 05 22 50 Ref : DSPUSG990001 Revision : 1.0 21 / 116
DSSSCT
File : dcsp
USER'S GUIDE
1.3.4
Hashing Session Keys
When an application uses the CryptHashSessionKey function to hash a session key, only the base key material must be hashed. For a 40-bit key, this will be 5 bytes of data. The key should be hashed in big-endian byte order. For example, if the Microsoft Base Cryptographic Provider is used to create and hash a session key with a value of 4a 3a ee 77 37, the bytes need to be reversed before the hashing operation is performed. In this example, the following hash values are produced: For an MD5 hash
0b 15 55 0a a0 03 f9 3f 75 82 f7 e7 91 32 bc 8c
For an SHA hash

3c 37 72 93 53 ff 2a 4f ef 12 54 18 5b 3a c4 63 03 fd 07 5d
1.3.5
Digital Signature Mechanics
An application signs or verifies hash values by using the CryptSignHash and CryptVerifySignature functions. The application often specifies a description string, which must be added to the hash object before it is signed or verified. The following is a typical signature process: 1. The application creates a hash object by using CryptCreateHash. 2. The application adds data to CryptHashSessionKey, or both. the hash object by using CryptHashData,
3. The application calls the CryptSignHash function to sign the hash value, specifying a description string. 4. The operating system layer accepts the CryptSignHash invocation. If the descriptive string is not already in Unicode, the system converts it to Unicode and hands off the task to the CSP using the CPSignHash function. 5. The CSP adds the Unicode description string to the hash object, using the CPHashData function. The terminating NULL character is not hashed in. 6. The CSP completes the hash and obtains the hash value to be signed by using the CPGetHashParam function. 7. The CSP takes the hash value, pads it out to the size of the public key modulus, and encrypts it by using the signature private key. The padding around the hash value must be in the format specified by the Public-Key Cryptography Standards (PKCS), available from RSA Data Security. The hash algorithm used must be encoded as described in PKCS #1, Section 6.3.
USER'S GUIDE
8. The signature block is returned to the application, using the operating system layer.
1.3.5.1 Signature Sample This section steps through the signature process. It uses the hash value from the Key Derivation Sample, the MD5 hash of the "124-kelp" string. This hash value is as follows:
73 40 e6 e2 74 b8 ea 39 93 95 aa 29 d6 38 b5 2a
This example uses "Test Signature" as the description string. First, the CSP adds this string to the hash object being signed. The description string, "Test Signature," is received by the CSP in Unicode format as the following hexadecimal bytes:
54 20 6e 18 00 00 00 72 65 53 61 00 00 00 00 65 73 00 74 00 69 00 67 00. 74 00 75 00 00
After the description string has been added to the hash, the hash value is:
a8 2b df c2 c9 f1 bb 62 38 78 d4 60 fa ce 5c 2a
Next, a PKCS signature block is built. The signature block is always the same size as the public key's modulus (64 bytes) and contains the following fields. Field Bytes Description Hash of data to be signed. The size of this field varies depending on the hash algorithm used. To be signed 1 to 16 The bytes in the hash value are reversed before they are placed in the encryption block because the operating system formats data in littleendian format, and the encryption block must be built in big-endian format. ASN.1 encoded hash algorithm specifier. The size of this field depends on the hash algorithm used. Note that this data is also reversed. For more information on ASN.1, see the PKCS documentation. Zero value. Padding data (0xff's). The size of this field is adjusted as necessary so that the signature block's overall length is correct. The PKCS block type (0x01).
Algorithm specifier Reserved Padding Block type

DSSSCT
17 to 34
35 36 to 62 63
File : dcsp
USER'S GUIDE
Reserved
64
Zero value.
The order of this table is reversed from the diagram found in the PKCS documentation because the signature block is built in big-endian on a little-endian computer. The completed signature block in this example is:
2a 62 10 86 20 ff ff ff 5c bb 04 48 30 ff ff ff ce f1 00 86 00 ff ff ff fa c9 05 2a ff ff ff ff 60 c2 05 08 ff ff ff ff d4 df 02 06 ff ff ff ff 78 2b 0d 0c ff ff ff 01 38 a8 f7 30 ff ff ff 00
Next, the block is encrypted with the appropriate private key. This example uses a typical but unspecified private key. This encryption results in a completed digital signature:
64 09 03 63 06 3f 14 70 f6 57 35 43 da 1c d0 09 46 43 d6 95 9a ad 58 00 3a cb e4 c4 21 3a 80 e3 97 ca 36 fd 98 db 02 5b 2e 41 6f e2 fc 7c df bd 83 59 2c c4 0a 83 dc 2b 38 0d fc ed 6e 2f 96 45
1.3.5.2 PKCS Hash Algorithm Encoding All RSA digital signature blocks contain an ASN.1 encoded hash algorithm identification string. The following table lists the encoding for the algorithms supported by the Microsoft Base Cryptographic Provider. These algorithms are also supported by most other RSA CSPs. Algorithm MD2 Encoding
10 04 00 05 02 02 0d f7 86 48 86 2a 08 06 0c 30 20 30 10 04 00 05 04 02 0d f7 86 48 86 2a 08 06 0c 300 20 30 10 04 00 05 05 02 0d f7 86 48 86 2a 08 06 0c 30 20 30 14 04 00 05 1a 02 03 0e 2b 05 06 09 30 21 30
MD4
MD5 SHA
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
24 / 116
USER'S GUIDE
The encoded OID strings shown in the previous table include wrapper bytes. For example, the encoded string shown for SHA contains the following information (for clarity, the bytes are in reverse order).
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
25 / 116
USER'S GUIDE
2 Using a Cryptographic Service Provider

2.1 Using CSPs: General Processes
2.1.1 Example Program Limitations
To provide more concise, more readable code, some principles of good programming practice are not always followed in these example programs. In particular: Only limited error responses are shown. Well-written, complete programs check returned error codes and perform appropriate actions when an error is encountered. Only limited memory and resource management is done. Well-written, complete programs destroy all keys and hashes, free all allocated memory, close all files, and release all handles. These example programs provide only limited demonstrations of the use of functions that perform these tasks. These example programs perform no memory or resource management tasks in the case of program termination due to errors.
2.1.2
Retrieving Data of Unknown Length
Many functions return a potentially large amount of data to an address provided as one of the parameters by the application. In all these cases, the operation is performed in a similar, if not identical, fashion. The parameter that points to the location of the returned data will use the notation convention where pb or pv are the first two characters of the parameter name. Another parameter will have pcb as the first three characters of the parameter name. This parameter represents the size, in bytes, of the data that will be returned to the pb or pv location. For example, consider the following function specification:
BOOL WINAPI SomeFunction( PCCRL_CONTEXT pCrlContext, DWORD dwPropId, BYTE *pbData, DWORD *pcbData ); // // // // in in out in/out
In this example pbData is a pointer to the location where the data will be returned, and pcbData is the size, in bytes, of the returned data. Note The companion parameter to the pcb parameter may sometimes carry a slightly different prefix, such as p or pv. Also, for companion parameters using the combination of prefixes pwsz and pcch, the pcch parameter is the count in characters (Unicode or ASCII, as applicable), of the returned data. If the buffer specified by the pbData parameter is not large enough to hold the returned data, the function sets the ERROR_MORE_DATA code (which can be seen by calling GetLastError), and stores the required buffer size, in bytes, in the variable pointed to by pcbData.
USER'S GUIDE
If NULL is input for pbData and pcbData is non-NULL, no error is returned and the function returns the size in bytes of the needed memory buffer in the variable pointed to by pcbData. This lets an application determine the size of, and the best way to allocate, a buffer for the returned data. Note When NULL is input for pbData to determine the size needed to ensure that the returned data fits in the specified buffer, the second call to the function which populates the buffer with the desired data may not use the whole buffer. After the second call, the actual size of the data returned is contained in pcbData. Use this size when processing the data. The following example code demonstrates how input and output parameters might be implemented for this purpose:
//-------------------------------------------------------------------#include <stdio.h> #include <windows.h> #include <wincrypt.h> #define MY_ENCODING_TYPE void HandleError(char *s); void main() { //-------------------------------------------------------------------// Set up SomeFunction variables. PCCRL_CONTEXT pCrlContext; // Initialized elsewhere. DWORD dwPropId; // Initialized elsewhere. DWORD cbData; BYTE *pbData; //-------------------------------------------------------------------// Call SomeFunction to set cbData, the size of // the buffer needed for pbData. if(SomeFunction( pCrlContext, dwPropId, NULL, &cbData)) { printf("The function succeeded.\n"); } else { // The function call failed. Handle the error. HandleError("Function call failed."); } //-------------------------------------------------------------------// The call succeeded; the size for the needed buffer, in bytes, // now resides in cbData. //-------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0
(PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)
27 / 116
DEKART CRYPTO SERVICE PROVIDER // Malloc memory for the size of the message.
USER'S GUIDE
if(pbData = (BYTE*)malloc(cbData)) { printf("Memory has been allocated.\n"); } else { // The allocation failed. Write an error message and exit. HandleError("Malloc operation failed. "); } //-------------------------------------------------------------------// The space for the buffer has been allocated. // Call SomeFunction to fill the buffer with the data. if(SomeFunction( pCrlContext, dwPropId, pbData, &cbData)) { printf("The function succeeded.\n"); } else { // The second function call failed. Handle the error. HandleError("The second call to the function failed."); } //-------------------------------------------------------------------// The function succeeded; the data is now in the buffer // pointed to by pbData. Note that cbData is // updated with the actual size of the data returned. Use this size // to process bytes of pbData. } // End of main //-------------------------------------------------------------------// This example uses the function HandleError, a simple error // handling function, to print an error message to the standard error // (stderr) file and exit the program. // For most applications, replace this function with one // that does more extensive error reporting. void HandleError(char *s) { fprintf(stderr,"An error occurred in running the program.\n"); fprintf(stderr,"%s\n",s); fprintf(stderr,"Error number %x.\n",GetLastError()); fprintf(stderr,"Program terminating.\n"); exit(1); }
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
28 / 116
USER'S GUIDE
2.1.3
Enumerating Supported Protocols
Supported protocols and cipher suites can be listed by calls to CryptGetProvParam with PP_ENUMALGS or PP_ENUMALGS_EX. The PP_ENUMALGS_EX value works like PP_ENUMALGS but returns a PROV_ENUMALGS_EX structure that holds more extensive information on the algorithms supported by the provider. For more information on defined protocol flags and their values, see Protocol Flags. Given that hCryptProv is the handle of an open cryptographic context acquired using CryptAcquireContext with its dwProvType parameter set to PROV_RSA_SCHANNEL, the following code lists the names of all algorithms available in the CSP:
PROV_ENUMALGS_EX EnumAlgs; // // DWORD dFlag = CRYPT_FIRST; // // // // cbData = sizeof(PROV_ENUMALGS_EX); Structure to hold information on a supported algorithm Flag indicating that the first supported algorithm is to be enumerated. Changed to 0 after the first call to the function.
while( CryptGetProvParam( hCryptProv, // handle to an open cryptographic provider PP_ENUMALGS_EX, (BYTE *)&EnumAlgs, // information on the next algorithm &cbData, // number of bytes in the PROV_ENUMALGS_EX dFlag)) // flag to indicate whether this is a first or // subsequent algorithm supported by the // CSP. { printf("Supported Algorithm name %s\n", EnumAlgs.szName); dFlag = 0; // Set to 0 after the first call, } // end of while loop. When all of the supported algorithms have // been enumerated, the function returns FALSE.
The following table lists some algorithms returned by a typical domestic PROV_RSA_SCHANNEL CSP. Notice that neither SSL2 SHA MACs nor SSL2 DES encryption is supported by the CSP in this example.
Algorithm identifier CALG_RSA _KEYX CALG_MD5 CALG_SHA CALG_RC4

DSSSCT
Minimum Key Maximum Key Length Length 512 128 160 40 2048 128 160 128
Protocols 0x0007 0x0007 0x0005 0x0007
Algorithm Name "RSA_KEYX" "MD5" "SHA" "RC4"

Revision : 1.0 29 / 116
File : dcsp
Ref : DSPUSG990001
USER'S GUIDE
CALG_DES
56
56
0x0005
"DES"
To prepare to send ClientHello or ServerHello messages, the Schannel protocol engine enumerates the algorithms and key sizes supported by the CSP and builds a list internally of supported cipher suites.
2.2 Using Schannel CSPs

Beginning with Microsoft Windows 2000, cryptogaphic service providers (CSPs) can use Schannel. Cryptographic applications can call CryptAcquireContext using the PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL providers. This section defines the RSA and Diffie-Hellman Schannel CSP types and describes the functionality that a CSP must support to be compatible with Schannel.dll, the Microsoft cryptographic protocol engine. A protocol engine is a program that establishes a secure communications channel between a client and server application. Applications should not attempt to use information in this documentation to use PROV_RSA_SCHANNEL or PROV_DH_SCHANNEL directly. Rather, this documentation explains how CSP developers and vendors must write Schannel CSPs that are compatible with Microsoft Schannel providers. This documentation is intended to help CSP developers implement compatible RSA or DiffieHellman Schannel CSPs. Developers are assumed to be familiar with the Secure Socket Layer protocol (SSS) version 3.0, public-key cryptography, digital certificates, and the Microsoft CryptoAPI function set. Developers new to these topics are advised to read the SSL Protocol 3.0 specification and the CryptoAPI documentation in this SDK. In addition, RSA and DiffieHellman CSP developers must know Transport Layer Security protocol (TLS) specifications along with the relevant RSA and Diffie-Hellman algorithms. See Creating the Master Key for code used by a Microsoft protocol engine. The calls to cryptography functions in this code result in calls to CP functions a CSP must implement. To write a compatible CSP, a developer must understand the SSL 3.0 specification and combine that knowledge with an understanding of the protocol engine code similar to this example code. Because usage of the Private Communication Technology (PCT) protocol is expected to be minimal in the future, developers of new CSPs need not support this protocol. The Schannel protocol engine supports it strictly for backward compatibility.
2.2.1
Public/Private Key Pair Usage
All normal RSA Schannel and Diffie-Hellman Schannel operations use the AT_KEYEXCHANGE public/private key pair. To provide server authentication, the server-side of Schannel operations must have access to its X.509 certificate containing its public key and
USER'S GUIDE
access to the matching private key. The client-side of Schannel needs its certificate with its public key and access to its private key if client authentication is implemented. Since Schannel protocol engines never use the AT_SIGNATURE public/private key pair, that key pair need not be supported by a new CSP supporting only RSA/Schannel or DiffieHellman/Schannel. If a protocol engine uses an SSL 3.0 export cipher suite with an AT_KEYEXCHANGE key pair larger than 512 bits, the server must use an additional RSA key pair. This additional key pair is always exactly 512 bits and it can be ephemeral. The pair is stored as an AT_KEYEXCHANGE element in a key container owned by the protocol engine. A handle to this key container is typically acquired at protocol engine startup. Diffie-Hellman supports only CALG_DH_EPHEM and uses normal RSA or DSS public keys.
2.2.2
SHA/MD5 RSA Signature Type
CSPs for PROV_RSA_SCHANNEL must support the CALG_SSL3_SHAMD5 hash that is compatible with the Microsoft Base Cryptographic Provider used in SSL 3.0 and TLS 1.0 client authentication. This hash consists of a concatenation of an MD5 hash and an SHA hash signed with an RSA or Diffie-Hellman private key. A handle to a hash value of this type is created with the CryptCreateHash or CPCreateHash function using CALG_SSL3_SHAMD5 as the Algid parameter.
2.2.3
Creating the Master Key
A master key is key data material from which other keys are derived. Depending on the protocol and cipher suite used, the master key can be from 5 to 48 bytes in length. For the RSA/Schannel CSP, the master key is created by the client-side and transferred to the server in an RSA envelope. For a Diffie-Hellman/Schannel CSP, the master key is created by performing a DiffieHellman key exchange.
2.2.3.1 Creating a Master Key: The RSA Client The following is typical RSA/Schannel client-side code for creating a master key:
//-------------------------------------------------------------------// Define and initialize local variables. HCRYPTPROV HCRYPTKEY HCRYPTKEY ALG_ID DWORD DSSSCT hProv = <protocol engine's key container>; hPublicKey = <server's public key>; hMasterKey; // handle for master key to be created. Algid; dwGenFlags =CRYPT_EXPORTABLE; File : dcsp Ref : DSPUSG990001 Revision : 1.0 31 / 116
DEKART CRYPTO SERVICE PROVIDER DWORD BYTE DWORD dwExportFlags =0; rgbBlob[<max BLOB size>]; cbBlob;
USER'S GUIDE
//-------------------------------------------------------------------// The method for creating the master key depends upon the protocol // in use. Schannel protocols include: // PCT 1.0 // SSL 2.0 // SSL 3.0 // TLS 1.0 //-------------------------------------------------------------------// Select the master key type. switch(<protocol being used>) { case <PCT 1.0>: Algid = CALG_PCT1_MASTER; break; case <SSL 2.0>: Algid = CALG_SSL2_MASTER; dwGenFlags |=,key size. << 16; if(<SSL3 or TLS is supported>) dwExportFlags |= CRYPT_SSL2_FALLBACK; break; case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; } //-------------------------------------------------------------------// Generate the master key. CryptGenKey( hProv, Algid, dwGenFlags, &hMasterKey); //-------------------------------------------------------------------// Export the master key. cbBlob = sizeof(rgbBlob); CryptExportKey( hMasterKey, hPublicKey, SIMPLEBLOB, dwExportFlags, rgbBlob, DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 32 / 116
DEKART CRYPTO SERVICE PROVIDER &cbBlob);
USER'S GUIDE
2.2.3.2 Creating a Master Key: The Diffie-Hellman Client The following is typical Diffie-Hellman/Schannel client-side code for creating a master key:
//-------------------------------------------------------------------// Define and initialize local variables. HCRYPTPROV hProv = <protocol engine's key container>; HCRYPTKEY hClientDHKey; // handle to the client's DH key HCRYPTKEY hMasterKey; ALG_ID Algid; PBYTE pbServerPub = <pointer to Server Public Key>; DWORD cbServerPub = <size of Server Public Key>; BYTE rgbServerBlob[<max BLOB size>]; DWORD cbServerBlob; PBYTE pbG = <pointer to generator G from Server>; DWORD cbG = <size of generator G from Server>; PBYTE pbP = <pointer to prime P from Server>; DWORD cbP = <size of prime P from Server>; CRYPT_DATA_BLOB Data; BYTE rgbClientPubBlob[size of the client public key BLOB]; DWORD cbClientPubBlob; //-------------------------------------------------------------------// Generate and set the parameters on the client DH key // Schannel specifies the key size and [regen flag when generating // a client DH key. CryptGenKey( hProv, CALG_DH_EPHEM, ((cbP * 8) << 16)|CRYPT_PREGEN, &hClientDHKey); Data.pbData = pbP; Data.cbData = cbP; CryptSetKeyParam( hClientDHKey, KP_P, (BYTE*)&Data, 0); Data.pbData = pbG; Data.cbData = cbG; CryptSetKeyParam( hClientDHKey, KP_G, (BYTE*)&Data, 0); //-------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 33 / 116
DEKART CRYPTO SERVICE PROVIDER // Create the client private DH key CryptSetKeyParam( hClientDHKey, KP_X, NULL, 0);
USER'S GUIDE
//-------------------------------------------------------------------// Build PUBLICKEYBLOB around the server's public key { BLOBHEADER *pBlobHeader = (BLOBHEADER *)rgbServerBlob; DHPUBKEY *pDHPubKey = (DHPUBKEY *)(pBlobHeader + 1); BYTE *pData = (BYTE *)(pDHPubKey + 1); pBlobHeader->bType pBlobHeader->bVersion pBlobHeader->reserved pBlobHeader->aiKeyAlg = = = = PUBLICKEYBLOB; CUR_BLOB_VERSION; 0; CALG_DH_EPHEM;
pDHPubKey->magic = 0x31484400; pDHPubKey->bitlen = dwServerPub * 8; ReverseMemCopy(pData, pbServerPub, cbServerPub); cbServerBlob = sizeof(BLOBHEADER) + sizeof(DHPUBKEY) + cbServerPub; } //-------------------------------------------------------------------// Import the server's public key and get an agreed key CryptImportKey( hProv, rgbServerBlob, cbServerBlob, hClientDHKey, 0, &hMasterKey); //-------------------------------------------------------------------// Select the master key type. switch(<protocol being used>) { case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; } //-------------------------------------------------------------------// Convert the agreed key to the appropriate master key DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 34 / 116
DEKART CRYPTO SERVICE PROVIDER CryptSetKeyParam( hMasterKey, KP_ALGID, (BYTE*)&Algid, 0);
USER'S GUIDE
//-------------------------------------------------------------------// Export the client Diffie-Hellman public key. cbClientPubBlob = sizeof(rgbClientPubBlob); CryptExportKey( hClientDHKey, 0, PUBLICKEYBLOB, 0, rgbClientPubBlob, & cbClientPubBlob); CryptDestroyKey(hClientDHKey);
2.2.3.3 Creating a Master Key: The RSA Server The following is typical RSA/Schannel server-side code for creating a master key:
//-------------------------------------------------------------------// Define and initialize local variables. HCRYPTPROV PBYTE DWORD HCRYPTKEY HCRYPTKEY ALG_ID DWORD BYTE DWORD hProv = <server's key container>; pbKeyExchange = <pointer to RSA envelope>; dwKeyExchange = <size of RSA envelope>; hPublicKey; hMasterKey; Algid; dwFlags =0 ; rgbBlob[<max BLOB size>]; cbBlob;
//-------------------------------------------------------------------// Select the master key type. switch(<protocol being used>) { case <PCT 1.0>: Algid = CALG_PCT1_MASTER; break; case <SSL 2.0>: Algid = CALG_SSL2_MASTER; if(<we support SSL3>) dwFlags = CRYPT_SSL2_FALLBACK; break; DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 35 / 116
DEKART CRYPTO SERVICE PROVIDER case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; }
USER'S GUIDE
//-------------------------------------------------------------------// Build a SIMPLEBLOB around the RSA envelope. { BLOBHEADER *pBlobHeader = (BLOBHEADER *)rgbBlob; ALG_ID *pAlgid = (ALG_ID *)(pBlobHeader + 1); BYTE *pData = (BYTE *)(pAlgid + 1); pBlobHeader->bType pBlobHeader->bVersion pBlobHeader->reserved pBlobHeader->aiKeyAlg = = = = SIMPLEBLOB; CUR_BLOB_VERSION; 0; Algid;
*pAlgid = CALG_RSA_KEYX; ReverseMemCopy( pData, pbKeyExchange, cbKeyExchange); } //-------------------------------------------------------------------// Decrypt the master key. CryptGetUserKey( hProv, AT_KEYEXCHANGE, &hPublicKey); CryptImportKey( hProv, rgbBlob, cbBlob, hPublicKey, dwFlags, &hMasterKey); CryptDestroyKey(hPublicKey);
2.2.3.4 Creating a Master Key: The Diffie-Hellman Server The following is typical Diffie-Hellman/Schannel server-side code for creating a master key:
//-------------------------------------------------------------------// Define and initialize local variables. DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 36 / 116
USER'S GUIDE
HCRYPTPROV hProv = <protocol engine's key container>; HCRYPTKEY hServerDHKey; // handle to the client's DH key HCRYPTKEY hMasterKey; // handle for the master key to be created. ALG_ID Algid; PBYTE pbClientPub = <pointer to client public key>; DWORD cbServerPub = <size of client public key>; BYTE rgbClientBlob[<max BLOB size>]; DWORD cbClientBlob = <size of the client key BLOB>; CRYPT_DATA_BLOB Data; //-------------------------------------------------------------------// Build a PUBLICKEYBLOB around the client's public key { BLOBHEADER *pBlobHeader = (BLOBHEADER *)rgbClientBlob; DHPUBKEY *pDHPubKey = (DHPUBKEY *)(pBlobHeader + 1); BYTE *pData = (BYTE *)(pDHPubKey + 1); pBlobHeader->bType pBlobHeader->bVersion pBlobHeader->reserved pBlobHeader->aiKeyAlg = = = = PUBLICKEYBLOB; CUR_BLOB_VERSION; 0; CALG_DH_EPHEM;
pDHPubKey->magic = 0x31484400; pDHPubKey->bitlen = dwClientPub * 8; ReverseMemCopy(pData, pbClientPub, cbClientPub); cbClientBlob = sizeof(BLOBHEADER) + sizeof(DHPUBKEY) + cbClientPub; } //-------------------------------------------------------------------// Import the client's public key and get an agreed key CryptImportKey( hProv, rgbClientBlob, cbClientBlob, hServerDHKey, 0, &hMasterKey); //-------------------------------------------------------------------// Select the master key type. switch(<protocol being used>) { case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; } DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 37 / 116
USER'S GUIDE
//-------------------------------------------------------------------// Convert the agreed key to the appropriate master key CryptSetKeyParam( hMasterKey, KP_ALGID, (BYTE*)&Algid, 0);
2.2.3.5 Specifying the Algorithms After a master key is created or imported, both RSA/Schannel and Diffie-Hellman/Schannel inform the CSP of the type of bulk encryption keys and MAC keys that will be derived from the master key. The following code specifies these algorithms. The same code is used for both client and server.
//-------------------------------------------------------------------// Algorithms for the SCHANNEL_ALG structure #define SCHANNEL_MAC_KEY #define SCHANNEL_ENC_KEY 0x00000000 0x00000001
//-------------------------------------------------------------------// dwFlags for the SCHANNEL_ALG structure // This flag will be set when the SSL cipher suite is exportable // outside the United States and Canada. The use of this flag notifies // the CSP that it must perform the extra export steps when deriving // the key. #define INTERNATIONAL USAGE 0x00000001
typedef struct _SCHANNEL_ALG { DWORD dwUse; ALG_ID Algid; DWORD cBits; DWORD dwFlags; DWORD dwReserved; } SCHANNEL_ALG, *PSCHANNEL_ALG; SCHANNEL_ALG Algorithm; //-------------------------------------------------------------------// Specify the bulk encryption algorithm. Algorithm.dwUse = SCHANNEL_ENC_KEY; Algorithm.Algid = CALG_RC4; // or CALG_RC2, CALG_DES, etc. Algorithm.cBits = 40; // or 64, 128, 192, etc. CryptSetKeyParam( hMasterKey, KP_SCHANNEL_ALG, (PBYTE)&Algorithm, 0); DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 38 / 116
USER'S GUIDE
//-------------------------------------------------------------------// Specify hash algorithm. Algorithm.dwUse = SCHANNEL_MAC_KEY; Algorithm.Algid = CALG_MD5; // or CALG_SHA, etc. Algorithm.cBits = 128; // or 160... CryptSetKeyParam( hMasterKey, KP_SCHANNEL_ALG, (PBYTE)&Algorithm, 0);
Note An Schannel protocol engine must not specify algorithms and key sizes not supported by the CSP. For more information, see Enumering Supported Protocols. If unsupported algorithms or key sizes are specified, the CSP function must fail and return the NTE_BAD_DATA error code.
2.2.4
Deriving Bulk Encryption and MAC Keys
Bulk encryption and MAC keys are derived from a master key but can include other sources depending on the protocol and cipher suite used. The process of deriving bulk encryption and MAC keys is the same for both client and server: 1. The protocol engine calls CryptSetKeyParam on the master key one or more times to provide the CSP with the information needed to build the keys. 2. Because CryptoAPI keys cannot be derived directly from other keys, a hash object is created from the master key using CryptCreateHash. This hash is used to create the new keys. 3. The two bulk encryption keys and the two MAC keys are created from the "master hash" object using four calls to CryptDeriveKey. Note When performing SSL reconnects, a protocol engine can perform the above procedure several times using the same master key. This enables the client and server to have multiple, often simultaneous connections, each using different bulk encryption and MAC keys without additional RSA or Diffie-Hellman operations. All CSPs must use good thread-safe practices. Thread counts of several dozen are not unusual. The following is typical source code for the protocol engine:
//-------------------------------------------------------------------// Define and initialize local variables. BOOL fClient = <TRUE if this is code for the client?>; CRYPT_DATA_BLOB Data; HCRYPTHASH hMasterHash; //-------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 39 / 116
DEKART CRYPTO SERVICE PROVIDER // Finish creating the master_secret. switch(<protocol being used>) { case <PCT 1.0>:
USER'S GUIDE
//-----------------------------------------------------------// Specify clear key value. Data.pbData = pClearKey; Data.cbData = cbClearKey; CryptSetKeyParam( hMasterKey, KP_CLEAR_KEY, (PBYTE)&Data, 0); //-----------------------------------------------------------// Specify the CH_CHALLENGE_DATA. Data.pbData = pChallenge; Data.cbData = cbChallenge; CryptSetKeyParam( hMasterKey, KP_CLIENT_RANDOM, (PBYTE)&Data, 0); //-----------------------------------------------------------// Specify the SH_CONNECTION_ID_DATA. Data.pbData = pConnectionID; Data.cbData = cbConnectionID; CryptSetKeyParam( hMasterKey, KP_SERVER_RANDOM, (PBYTE)&Data, 0); //-----------------------------------------------------------// Specify the SH_CERTIFICATE_DATA. Data.pbData = pbServerCertificate; Data.cbData = cbServerCertificate; CryptSetKeyParam( hMasterKey, KP_CERTIFICATE, (PBYTE)&Data, 0); break; case <SSL 2.0>: //-----------------------------------------------------------// Specify clear key value. Data.pbData = pClearKey; DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 40 / 116
DEKART CRYPTO SERVICE PROVIDER Data.cbData = cbClearKey; CryptSetKeyParam( hMasterKey, KP_CLEAR_KEY, (PBYTE)&Data, 0);
USER'S GUIDE
//-----------------------------------------------------------// Specify the CH_CHALLENGE_DATA. Data.pbData = pChallenge; Data.cbData = cbChallenge; CryptSetKeyParam( hMasterKey, KP_CLIENT_RANDOM, (BYTE*)&Data, 0); //-----------------------------------------------------------// Specify the SH_CONNECTION_ID_DATA. Data.pbData = pConnectionID; Data.cbData = cbConnectionID; CryptSetKeyParam( hMasterKey, KP_SERVER_RANDOM, (BYTE*)&Data, 0); break; case <SSL 3.0>: case <TLS 1.0>: //-----------------------------------------------------------// Specify client_random. Data.pbData = pClientRandom; Data.cbData = cbClientRandom; CryptSetKeyParam( hMasterKey, KP_CLIENT_RANDOM, (PBYTE)&Data, 0); //-----------------------------------------------------------// Specify server_random. Data.pbData = pServerRandom; Data.cbData = cbServerRandom; CryptSetKeyParam( hMasterKey, KP_SERVER_RANDOM, (PBYTE)&Data, 0); } DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 41 / 116
USER'S GUIDE
//-----------------------------------------------------------// Create the master hash object from the master key. CryptCreateHash( hProv, CALG_SCHANNEL_MASTER_HASH, hMasterKey, 0, &hMasterHash); //-----------------------------------------------------------// Derive read key from the master hash object. CryptDeriveKey(hProv, CALG_SCHANNEL_ENC_KEY, hMasterHash, fClient ? CRYPT_SERVER : 0, &hReadKey); //-----------------------------------------------------------// Derive write key from the master hash object. CryptDeriveKey( hProv, CALG_SCHANNEL_ENC_KEY, hMasterHash, fClient ? 0 : CRYPT_SERVER, &hWriteKey); if(<protocol being used> != <SSL 2.0>) // for SSL 2.0, the master // key is also the MAC.
{ //-----------------------------------------------------------// Derive read MAC from the master hash object. CryptDeriveKey( hProv, CALG_SCHANNEL_MAC_KEY, hMasterHash, fClient ? CRYPT_SERVER : 0, &hReadMAC); //-----------------------------------------------------------// Derive write MAC from the master hash object. CryptDeriveKey( hProv, CALG_SCHANNEL_MAC_KEY, hMasterHash, fClient ? 0 : CRYPT_SERVER, &hWriteMAC); } CryptDestroyHash(hMasterHash);
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
42 / 116
USER'S GUIDE
2.2.5
Finish Messages (TLS 1.0)
A finish message is sent immediately after a change cipher spec message to verify the success of key exchange and authentication processes. The finish messages in the TLS 1.0 protocol are calculated using Pseudo-Random Function (PRF) with the master key, a label, and a seed as input. PRF produces an output of arbitrary length. The following method is used to generate the PRF output used in TLS 1.0 finish messages. A PRF hash handle is generated using CryptCreateHash with the ALG_ID value set to CALG_TLS1PRF and the handle to the master key passed in the hKey parameter. The label and seed values are set on the hash handle using the values HP_TLS1PRF_LABEL and HP_TLS1PRF_SEED, respectively, in the dwParam parameter with the CryptSetHashParam function. Finally, the protocol engine calls the function CryptGetHashParam with the value HP_HASHVAL in the dwParam parameter to retrieve the PRF data to be included in the finish message. When making the call to CryptGetHashParam, the protocol engine must specify how many bytes of data PRF will produce. This is done in the pdwDataLen parameter, and the resulting data is placed in the buffer pointed to by the pbData parameter. The following is typical source code for this protocol engine:
CRYPT_DATA_BLOB Data; HCRYPTHASH hFinishHash; BYTE rgbFinishPRF[12]; BYTE rgbCliHashOfHandshakes[36]; //-----------------------------------------------------------// get client finish message CryptCreateHash( hProv, CALG_TLS1PRF, hMasterKey, 0, &hFinishHash); Data.pbData = (BYTE*)"client finished"; Data.cbData = 15; CryptSetHashParam( hFinishHash, HP_TLS1PRF_LABEL, (BYTE*)&Data, 0); Data.pbData = rgbCliHashOfHandshakes; Data.cbData = sizeof(rgbCliHashOfHandshakes); CryptSetHashParam( hFinishHash, HP_TLS1PRF_SEED, (BYTE*)&Data, 0); cbFinishPRF = sizeof(rgbFinishPRF); CryptGetHashParam( hFinishHash, DSSSCT File : dcsp Ref : DSPUSG990001
Revision : 1.0
43 / 116
DEKART CRYPTO SERVICE PROVIDER HP_HASHVAL, rgbFinishPRF, &cbFinishPRF, 0); CryptDestroyHash(hFinishHash);
USER'S GUIDE
2.2.6
Bulk Data Encryption
A bulk encryption key is generated by hashing one of the MAC keys using CryptHashSessionKey together with the message contents and other data. The message is encrypted/decrypted with one of the bulk encryption keys in the usual manner. When using a block cipher, the Schannel protocol engine does all necessary block cipher padding. When CryptEncrypt and CryptDerypt are called, the Final flag is always FALSE and the data length is a multiple of whole block lengths. Note The CSP must never buffer data internally. Once the data has been encrypted (or decrypted), the size of the plaintext must always exactly match the size of the ciphertext.
2.2.7
Crossing Process Boundaries
The Schannel protocol engine in Windows 2000 performs the handshaking and authentication in a secure process and the bulk encryption/message passing in the application process. This means that the bulk encryption keys and MAC keys must be copied from one process to another. To do this, use the CryptExportKey and CryptImportKey functions as follows: The secure process exports each key into an OPAQUEKEYBLOB using CryptExportKey, then destroys the key using CryptDestroyKey. Note that if the key is stored in hardware, the CSP must recognize this and must not attempt to destroy the key. The secure process passes the OPAQUEKEYBLOBs to the application process in a manner beyond the scope of this document. The application process imports each OPAQUEKEYBLOB back into the CSP using CryptImportKey. At this point, the key must be in exactly the same state as when it was exported.
2.2.8
Opaque BLOB Type
Opaque BLOBs, also known as OPAQUEKEYBLOBs, are used to store session keys. They contain the base key material and all current state information. This includes information such as the salt value, the initialization vector, and the key table. The format of opaque BLOBs is
USER'S GUIDE
unpublished. Each CSP vendor determines its own BLOB format which should include encrypting the opaque BLOBs with some sort of symmetric key. Because a key is exported into an opaque BLOB in CSP-specific format, it can only be imported into the CSP from which it was originally exported. When two processes are involved, each process calls CryptAcquireContext independently. Each process gets a handle to a key container. It is possible for both processes to have handles to the same key container. One process creates the keys and exports them into opaque BLOBs, then passes the BLOBs to the second process. The second process imports the keys from the BLOB into its key container. If a hardware CSP does not support exporting keys, the BLOB might only contain the index of a key register, or something similar. In this case, the hardware remains unaware of the whole procedure.
<secure process> cbBlob = sizeof(rgbBlob); CryptExportKey( hKey, 0, OPAQUEKEYBLOB, 0, rgbBlob, &cbBlob); hKey = 0; <BLOB is transferred to other process> <user process> CryptImportKey( hProv, pbBlob, cbBlob, 0, 0, &hKey);
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
45 / 116
USER'S GUIDE
3 Cryptographic Service Provider Reference

3.1 CSP Functions
3.1.1 CSP Connection Functions
CSP connection functions work with the characteristics of a cryptographic service provider (CSP) and connect to and disconnect from key containers with a CSP. The following table briefly describes each function. Function CPAcquireContext CPGetProvParam CPReleaseContext CPSetProvParam Description Acquires a handle to a particular key container within the CSP. Retrieves attributes of the CSP. Releases the handle acquired by CPAcquireContext. Sets specific attributes of a CSP.
3.1.1.1 CPAcquireContext The CPAcquireContext function acquires a handle to the key container specified by the pszContainer parameter.
BOOL CPAcquireContext( HCRYPTPROV *phProv, CHAR *pszContainer, DWORD dwFlags, PVTableProvStruc pVTable ); // // // // out in, out in in
Parameters
phProv Address to which the function copies a handle to the CSP. pszContainer Key container name. This is a NULL-terminated string of no more than MAX_PATH characters. The function sets this parameter to NULL if dwFlags is set to CRYPT_VERIFYCONTEXT. If pszContainer is NULL on input, a default key container name is used. The Microsoft RSA Base Provider, for example, uses the logon name of the current user as the default key container name. Other CSPs can use different default key container names.
USER'S GUIDE
dwFlags Can be zero or one of the following flags. Flag value Meaning
The application has no access to the private keys and the return pszContainer parameter must be set to NULL. This option is used with applications that do not use private keys. When CryptAcquireContext is called, many CSPs require input from the user before granting access to the private keys in the key container. For example, private keys might be encrypted, CRYPT_VERIFYCONTEXT requiring a password from the user before being used. However, if CRYPT_VERIFYCONTEXT is specified and access to the private keys is not required, the user interface can be bypassed. When this flag is used and a public/private key pair is created or imported, that pair of keys is treated as treated as ephemeral; that is, the keys are kept only in memory and are automatically destroyed when CPReleaseContext is called. A new key container is created with the name specified by pszContainer. If pszContainer is NULL on input, a key container with the default name is created. While a CSP is not required to create key pairs at this point; at the CSP author's discretion, a CSP can generate key pairs at this time. Keys are created through calls to CPGenKey, either within this call to CPAcquireContext or later as a separate step.
CRYPT_NEWKEYSET
By default, key containers and their keys are stored as keys associated with a specific user. For the CSP currently provided by Microsoft, user key containers are stored in the user's profile. The CRYPT_MACHINE_KEYSET flag is useful when access is being performed from a service or user account that did not log on interactively. The CRYPT_MACHINE_KEYSET flag can be combined with other flags indicating that the key container of interest is a machine key container and the CSP will treat it as such. For CRYPT_MACHINE_KEYSET Microsoft CSPs, this means the keys are stored locally on the computer that created the key container. The CRYPT_MACHINE_KEYSET flag is used for keys that are machine keys, keys that must be accessible to applications not associated with a user account. UI cannot be associated with these keys because they can be used by unattended server applications. With Microsoft CSPs, ACLs can be set on these keys by using CPGetProvParam and CPSetProvParam with the PP_KEYSET_SEC_DESCR value. CSP writers can consider setting ACLs on keys as well.
USER'S GUIDE
If a key container is to be a machine key container, the CRYPT_MACHINE_KEYSET flag must be used with all calls to CryptAcquireContext that reference the container. CRYPT_MACHINE_KEYSET applies specifically to the Microsoft provider types. For a list of these types, see Cryptographic Provider Types. Other provider types can store keys differently, and can ignore this flag. All compatible CSPs must implement the CRYPT_MACHINE_KEYSET flag; however, this implementation can be done by simply ignoring the flag. Deletes the key container specified by pszContainer or, if pszContainer is NULL, the key container with the default name. All key pairs in the key container are also destroyed. After a key container has been deleted, the value returned in phProv is undefined; therefore, the context has been released and the application does not need to call CryptReleaseContext. This flag directs the CSP to not display user interface (UI) for this context. If any future function call using this acquired CSP context requires UI to operate, the function call must fail and the function must set the last error to NTE_SILENT_CONTEXT. If CRYPT_SILENT is set and a later call is made to CPGenKey using CRYPT_USER_PROTECTED, that call will fail and the function must set the last error to NTE_SILENT_CONTEXT. This flag is intended for use with applications that cannot tolerate UI being displayed by the CSP. It is only supported with Microsoft Windows 2000 or later.
CRYPT_DELETEKEYSET
CRYPT_SILENT
pVTable Pointer to a VtableProvStruc structure containing a list of callback functions provided by the operating system for use by the CSP.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS NTE_BAD_KEYSET Description The dwFlags parameter has an illegal value. The key container could not be opened and might not exist.
DSSSCT
File : dcsp
USER'S GUIDE
NTE_BAD_KEYSET_PARAM NTE_BAD_SIGNATURE
The pszContainer parameter is set to an illegal value. The digital signature of an auxiliary DLL did not verify correctly. Either the DLL or the digital signature has been tampered with. The dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists. The pszContainer key container was found but is corrupt. The key container specified by pszContainer does not exist. The CSP ran out of memory during the operation. An auxiliary DLL file could not be loaded and might not exist. If it exists, the file is not a valid DLL.
NTE_EXISTS NTE_KEYSET_ENTRY_BAD NTE_KEYSET_NOT_DEF NTE_NO_MEMORY NTE_PROVIDER_DLL_FAIL
Requirements
Windows NT/2000: Requires Windows NT 4.0 or later. Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 and later). Windows CE: Requires version 1.0 or later. Header: Declared in wincrypt.h.
See Also
CPReleaseContext, CryptAcquireContext, CryptSetProvParam
3.1.1.2 CPGetProvParam The CPGetProvParam function returns data about a cryptographic service provider (CSP).
BOOL CPGetProvParam( HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, DWORD *pdwDataLen, DWORD dwFlags );
// // // // //
in in out in, out in
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
49 / 116
USER'S GUIDE
Parameters hProv Handle to a particular key container within the CSP. This handle is obtained by a previous call to CPAcquireContext. dwParam A DWORD value that determines the nature of the query. The following queries are defined. dwParam value Contents returned in pbData The name of the current key container as a NULLterminated CHAR string. The returned string is identical to the one passed in the pszContainer parameter of the CryptAcquireContext function to specify the key container to use. pszContainer can be read to determine the name of the default key container. Information about an algorithm supported by the CSP being queried. PP_ENUMALGS values must be read repeatedly to list all of the supported algorithms (not enumerated in any particular order). The first time that PP_ENUMALGS is read, the CRYPT_FIRST flag must be specified in dwFlags. Doing so ensures that information about the first algorithm in the enumeration list is returned. PP_ENUMALGS can then be repeatedly read with dwFlags set to 0 to retrieve the information about the rest of the supported algorithms. When the CPGetProvParam function fails with the ERROR_NO_MORE_ITEMS error code, the end of the enumeration list has been reached. This function is not thread-safe and all of the available algorithms may not be enumerated if this function is used in a multithread context. Information about an algorithm supported by the CSP. The structure returned contains more information about the algorithm than the structure returned for PP_ENUMALGS. The PP_ENUMALGS_EX value must be read repeatedly to enumerate all the supported algorithms (not enumerated in any particular order). The first time that PP_ENUMALGS is read, the CRYPT_FIRST flag must be specified in dwFlags. Doing so ensures that information about the first algorithm in the enumeration list is returned. PP_ENUMALGS can then be repeatedly read with dwFlags set to 0 to retrieve the information about the rest
PP_CONTAINER
PP_ENUMALGS
PP_ENUMALGS_EX
DSSSCT
File : dcsp
USER'S GUIDE
of the supported algorithms. When the CryptGetProvParam function fails with the ERROR_NO_MORE_ITEMS error code, the end of the enumeration list has been reached. PP_ENUMALGS_EX is supported in Microsoft Internet Explorer version 4.0 or later, Microsoft Windows NT version 4.0 SP4, Windows 98 or later, and Windows 2000. This function is not thread-safe and all of the available algorithms may not be enumerated if this function is used in a multithread context. The name of one of the key containers maintained by the CSP in the form of a NULL-terminated CHAR string. The PP_ENUMCONTAINERS value can be read repeatedly to enumerate all the container names. Container names are enumerated in the same way as the CSP's supported algorithms. This function is not thread-safe and all of the available container names mayt not be enumerated if this function is used in a multithread context. A DWORD value indicating how the CSP is implemented. Predefined implementation types CRYPT_IMPL_HARDWARE, CRYPT_IMPL_SOFTWARE, CRYPT_IMPL_MIXED, and CRYPT_IMPL_UNKNOWN are supported. The name of the CSP in the form of a NULL-terminated CHAR string. This string is identical to the one passed in the pszProvider parameter of the CryptAcquireContext function to specify that the current CSP be used. The version number of the CSP. The least significant byte contains the minor version number and the next most significant byte contains the major version number. Version 1.0 is represented as 0x00000100. To maintain backward compatibility with earlier versions of the Microsoft Base Cryptographic Provider and Microsoft Enhanced Cryptographic Provider, the provider names retain the "v1.0" designation in later versions. Version 2.0 of these providers is included in Windows 2000. The number of bits for the increment length of
PP_ENUMCONTAINERS
PP_IMPTYPE
PP_NAME
PP_VERSION
PP_SIG_KEYSIZE_INC
DSSSCT File : dcsp
USER'S GUIDE
AT_SIGNATURE keys. This information is used with information returned with PP_ENUMALGS_EX to determine valid AT_SIGNATURE key lengths. These key lengths can then be used with CPGenKey. For example, if a CSP enumerated CALG_RSA_SIGN (AT_SIGNATURE) with a minimum key length of 512 bits, a maximum of 1024 bits, and returned the increment length as 64 bits, then valid key lengths would be 512, 576, 640, and other lengths at 512-bit intervals up to 1024 bits. The number of bits for the increment length of AT_KEYEXCHANGE keys. This information is used with information returned with PP_ENUMALGS_EX to determine valid AT_KEYEXCHANGE key lengths. These key lengths can then be used with CPGenKey. PP_KEYX_KEYSIZE_INC For example, if a CSP enumerated CALG_RSA_SIGN (AT_KEYEXCHANGE) with a minimum key length of 512 bits, a maximum of 1024 bits, and returned the increment length as 64 bits, then valid key lengths would be 512, 576, 640, and other lengths at 512-bit intervals up to 1024 bits. The security descriptor of the registry entry where the key set is stored. This flag is supported in Windows 98 and later and Windows NT 4.0 and later. The unique container name of the current key container in the form of a NULL-terminated CHAR string. For many CSPs, this name is the same as the name returned when PP_CONTAINER is used. The CryptAcquireContext function must work with this container name. A DWORD value indicating the provider type of the CSP.
PP_KEYSET_SEC_ DESCR
PP_UNIQUE_ CONTAINER
PP_PROVTYPE pbData
Pointer to a data buffer. The dwParam parameter specifies the type of data to be copied to this buffer. It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length. pdwDataLen
USER'S GUIDE
Pointer to a buffer to hold length of pbData. Upon function entry, it points to a DWORD value indicating the number of bytes allocated for the pbData buffer. Upon exit, the DWORD value must be set to the number of bytes needed to hold pbData. When one of the enumeration parameters is being read, the value returned in pdwDataLen must indicate the size of the largest item in the enumeration list. If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned by the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen. If this function fails with any error code other than ERROR_MORE_DATA, this parameter returns zero. dwFlags The following flags are defined for this function: CRYPT_FIRST Used only with an enumeration parameter such as PP_ENUMALGS, PP_ENUMALGS_EX, or PP_ENUMCONTAINERS. If this flag is set, the first item in the enumeration list is to be returned. Otherwise, the next item in the list is returned. If this flag is set when a non-enumeration parameter is being read, the NTE_BAD_FLAGS error code is returned. CRYPT_MACHINE_KEYSET Can be set along with PP_ENUMCONTAINERS. If set, the key containers associated with a computer are enumerated, rather than those associated with the logged in user. This flag value is used only by RSA base CSPs. A hardware-based CSP will ignore this flag. SECURITY_INFORMATION If dwParam is set to PP_KEYSET_SEC_DESCR, the security descriptor of the key container is retrieved. For this case, dwFlags is used to pass in bit flags that can be combined with a bitwise OR operation. The pointer to the security descriptor is returned in the pbData parameter and the length of the security descriptor is returned in the pcbData parameter. This flag value is used only by RSA base CSPs. A hardware-based CSP will not use this flag value. For more information, see RegGetKeySecurity and RegSetKeySecurity. The following table contains bit flags indicating the requested security information. Value OWNER_SECURITY_INFORMATION GROUP_SECURITY_INFORMATION
DSSSCT File : dcsp
Meaning Indicates the owner identifier of the object being referenced. Indicates the primary group identifier of
USER'S GUIDE
the object being referenced. DACL_SECURITY_INFORMATION SACL_SECURITY_INFORMATION Indicates the discretionary ACL of the object being referenced. Indicates the system ACL of the object being referenced.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_MORE_DATA Description The pbData buffer is not large enough to hold the requested data. The end of the enumeration list has been reached. No valid data has been placed in the pbData buffer. This error is returned only when dwParam equals PP_ENUMALGS, PP_ENUMALGS_EX, or PP_ENUMCONTAINERS. The value of the dwFlags parameter is invalid. The dwParam parameter parameter number. specifies an unknown
ERROR_NO_MORE_ITEMS
NTE_BAD_FLAGS NTE_BAD_TYPE NTE_BAD_UID
The context specified by hProv is invalid.
Requirements
See Also
CPAcquireContext, CPSetProvParam, CryptGetProvParam
3.1.1.3 CPReleaseContext The CPReleaseContext function releases a context created by CPAcquireContext.

DEKART CRYPTO SERVICE PROVIDER BOOL CPReleaseContext( HCRYPTPROV hProv, // in DWORD dwFlags // in );
USER'S GUIDE
Parameters
hProv Handle of a key container within the CSP. This handle is obtained by a call to CPAcquireContext. dwFlags No flags are currently defined.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS NTE_BAD_UID Description The value of the dwFlags parameter is invalid. The context specified by hProv is invalid.
Remarks
After this function has been executed, the hProv handle becomes invalid. All session keys and hash objects previously created by using the hProv handle can be destroyed at this time. Ideally, the application already did this using CryptDestroyKey and CryptDestroyHash, but a CSP cannot depend upon the keys and hashes being destroyed.
Requirements
See Also
CPAcquireContext, CryptReleaseContext
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
55 / 116
USER'S GUIDE
3.1.1.4 CPSetProvParam The CPSetProvParam function customizes the operations of a cryptographic service provider (CSP).
BOOL CPSetProvParam( HCRYPTPROV hProv, DWORD dwParam, BYTE *pbData, DWORD dwFlags ); // // // // in in in in
Parameters
hProv Handle to a key container within the CSP. This handle is obtained by a call to CPAcquireContext. dwParam Customizable parameter to set. The only currently defined parameter value is: PP_KEYSET_SEC_DESCR Sets the security descriptor of a registry entry where the key set is stored. The new value is contained in pbData. For details on manipulating ACLs, see Secperf.c in the Microsoft Platform SDK. Windows 95 does not support this flag. Customizable parameters can be added as needed. General-purpose parameters can be defined in coordination with Microsoft Corporation to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32 header files. pbData On entry to the function, this buffer contains data as specified by the dwParam parameter. The form and length of this data varies depending on dwParam. dwFlags If pdParam is PP_KEYSET_SEC_DESCR, dwFlags contains the SECURITY_INFORMATION applicable bit flags. These can be combined with a bitwise OR operation. The following table lists defined SECURITY_INFORMATION flags. Value OWNER_SECURITY_INFORMATION Meaning Indicates the owner identifier of the object being referenced.
DSSSCT
File : dcsp
USER'S GUIDE
GROUP_SECURITY_INFORMATION DACL_SECURITY_INFORMATION SACL_SECURITY_INFORMATION
Indicates the primary group identifier of the object being referenced. Indicates the discretionary ACL of the object being referenced. Indicates the system ACL of the object being referenced.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS NTE_BAD_TYPE NTE_BAD_UID NTE_FAIL Description The value of the dwFlags parameter is invalid. The dwParam parameter specifies an unknown parameter number. The context specified by hProv is invalid. The function failed in an unexpected way.
Remarks
Applications can call CryptSetProvParam with the dwParam parameter set to PP_CLIENT_HWND to specify the window handle the CSP is to use when interacting with the user. The call to CryptSetProvParam passes in the window handle as a DWORD value in the pbData buffer. Applications call CryptSetProvParam before calling CryptAcquireContext; therefore, calls to CPSetProvParam with the PP_CLIENT_HWND parameter are not made. The CSP obtains this window handle using a virtual function pointer obtained from the CPAcquireContext function call.
Requirements
See Also
USER'S GUIDE
CPAcquireContext, CPGetParam, CryptSetProvParam
3.1.2
Key Generation and Exchange Functions
Key generation and exchange functions exchange keys with other users and create, configure, and destroy cryptographic keys. The following table briefly describes each function. Function CPDeriveKey CPDestroyKey CPDuplicateKey CPExportKey CPGenKey CPGenRandom CPGetKeyParam CPGetUserKey CPImportKey CPSetKeyParam Description Creates a key derived from a password. Destroys a key. Makes an exact copy of a key, including the state of the key. Transfers a key from the CSP into a key BLOB in the application's memory space. Creates a random key. Generates random data. Retrieves a key's parameters. Gets a handle to the key exchange or signature key. Transfers a key from a key BLOB to a CSP. Specifies a key's parameters.
3.1.2.1 CPDeriveKey The CPDeriveKey function generates a cryptographic session key using a hash of base data. This function guarantees that all keys generated from the same base data using the same algorithms will be identical. The base data can be a password or other user-supplied data.
BOOL CPDeriveKey( HCRYPTPROV hProv, ALG_ID Algid, HCRYPTHASH hBaseData, DWORD dwFlags, HCRYPTKEY *phKey ); // // // // // in in in in out
Parameters
USER'S GUIDE
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. Algid Identifier of the encryption algorithm for which the key is to be generated. This algorithm must be one of those supported by the CSP. The following Algid values are used with Schannel providers. Algid Meaning Generates a bulk encryption key. The key generation algorithm and key size must have been previously specified with a call to the CPSetKeyParam function. The initialization vector (IV) is typically set using CPSetKeyParam with KP_IV. Some protocol and cipher suite combinations insist on building the IV from the key block. In this case, the CSP derives the IV automatically. For SSL 2, this key is also used as the MAC key. Generates a MAC key. The key generation algorithm has previously been specified with a call to CPSetKeyParam.
CALG_SCHANNEL_ ENC_KEY
CALG_SCHANNEL_ MAC_KEY hBaseData
Handle to a hash object that contains a hash of the base data. dwFlags Attributes of the session key generated. Not all CSPs support all flags. Currently defined flags are listed below. Flag value Meaning The session key can be transferred out of the CSP into a key BLOB using CPExportKey. Because keys generally must be exportable, this flag is usually set. If this flag is not set, the session key is not exportable. The session key is available only within the current session and can only be used by the application that created it. This flag does not apply to public/private key pairs. Typically, a number of extra bits are left over when a session key is created from a hash value. There are 88 bits left over when a 40-bit session key is created from a 128- bit hash value.
CRYPT_EXPORTABLE
CRYPT_CREATE_SALT
DSSSCT
File : dcsp
USER'S GUIDE
If this flag is set, the key is assigned a salt value based on the unused hash value bits. This salt value can be retrieved by calling CPGetKeyParam with the dwParam parameter set to KP_SALT. If this flag is not set, the key is given a salt value of zero. When keys with nonzero salt values are exported using CPExportKey, the salt value must also be obtained and kept with the key BLOB. CRYPT_NO_SALT No salt value is allocated for a 40-bit symmetric key. The user is notified through a dialog box or another method when this key is used to attempt certain actions. The precise behavior is specified by the CSP being used. If the provider context is opened with the CRYPT_SILENT flag set, using this flag causes a failure with the last error set to NTE_SILENT_CONTEXT. Microsoft cryptographic providers support this flag in Internet Explorer 4.0 and later, Windows 98, and Windows 2000. Prior to Internet Explorer 4.0, this flag was ignored. Some CSPs use session keys derived from multiple hash values. When this is the case, CPDeriveKey must be called multiple times. If this flag is set, a new session key is not generated. Instead, the key specified by phKey is modified. The precise behavior of this flag is dependent on the type of key being generated and on the particular CSP being used. Microsoft dryptographic providers ignore this flag. This flag is used only with Schannel providers. If this flag is set, the key to be generated is a server-write key; otherwise, it is a client-write key.
CRYPT_USER_ PROTECTED
CRYPT_UPDATE_KEY
CRYPT_SERVER phKey
Address to which the function copies the handle of the newly-generated key.
Remarks
For a description of the master hash object, see CPCreateHash.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.
USER'S GUIDE
Error NTE_BAD_ALGID NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_HASH_STATE NTE_FAIL NTE_BAD_UID NTE_SILENT_CONTEXT
Description The Algid parameter specifies an algorithm that this CSP does not support. The dwFlags parameter contains an invalid value. The hBaseData parameter does not contain a valid handle to a hash object. An attempt was made to add data to a hash object that is already marked as finished. The function failed in an unexpected way. The hProv parameter does not contain a valid context handle. The provider could not perform the action because the context was acquired as silent.
Remarks
The CPDeriveKey function completes the hash of the hash object passed in as hBaseData. After CPDeriveKey has been called, no more data can be added to that hash object. Additional calls to CPHashData or CPHashSessionKey with that hash object fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature use the completed hash object and succeed. If CSP interoperability is important, session keys must be derived in the precise manner specified by the CSP's type. For information on how the key derivation must be performed, see Deriving Session Keys. If interoperability is not a concern, a CSP is free to derive session keys in any manner.
Requirements
See Also
CPDestroyKey, CPGenKey, CryptDeriveKey
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
61 / 116
USER'S GUIDE
3.1.2.2 CPDestroyKey The CPDestroyKey function releases the handle referenced by the hKey parameter. After a key handle has been released, it becomes invalid and can no longer be used.
BOOL CPDestroyKey( HCRYPTPROV hProv, HCRYPTKEY hKey ): // in // in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hKey Handle to the key to be destroyed.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_KEY NTE_BAD_UID Description The hKey parameter does not contain a valid handle to a key. The hProv parameter does not contain a valid context handle.
Remarks
If the handle refers to a session key or to a public key imported into the CSP with CryptImportKey, this function destroys the key and frees the memory that the key occupied. A CSP typically scrubs the memory where the key was held before freeing it. On the other hand, if the handle refers to a public/private key pair (obtained from CryptGetUserKey), the underlying key pair is not destroyed by this function. Only the handle is destroyed.
Requirements
USER'S GUIDE
See Also
CPDeriveKey, CPGenKey, CPGetUserKey, CryptDestroyKey
3.1.2.3 CPDuplicateKey The CPDuplicateKey function makes an exact copy of a key. Some keys have an associated state such as an initialization vector or a salt value. If a key with an associated state is duplicated, the associated state is also copied.
BOOL CPDuplicateKey( HCRYPTPROV hUID, HCRYPTKEY hKey, DWORD *pdwReserved, DWORD dwFlags, HCRYPTKEY *phKey ); // // // // // in in in in out
Parameters
hUID Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. hKey Handle of the key to be duplicated. pdwReserved This parameter is reserved for future use and must be NULL. dwFlags This parameter is reserved for future use and must be zero. phKey Address for the handle to the duplicated key.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_CALL_
DSSSCT File : dcsp
Description Because this is a new function, existing CSPs might not

USER'S GUIDE
NOT_IMPLEMENTED ERROR_INVALID_ PARAMETER NTE_BAD_KEY
implement it. This error is returned if the CSP does not support this function. One of the parameters contains an invalid value. This is most often an illegal pointer. The handle to the original key is not valid.
Remarks
The CPDuplicateKey function is used to make a copy of a key and the exact state of that key. For example, a caller can encrypt two separate messages with the same key, but with different salt values. A key is generated, a duplicate is made with the CPDuplicateKey function, and then different appropriate salt values are set on each key with the CPSetKeyParam function. CPDestroyKey must be called to destroy any keys that are created with CPDuplicateKey. Destroying the original key does not destroy the duplicate key. Once a duplicate key is made, it is separate from the original key. There is no shared state between the two keys.
Requirements
See Also
CPDestroyKey, CryptDuplicateKey
3.1.2.4 CPExportKey The CPExportKey function securely exports cryptographic keys from a CSP's key container.
BOOL CPExportKey( HCRYPTPROV hProv, HCRYPTKEY hKey, HCRYPTKEY hPubKey, DWORD dwBlobType, DWORD dwFlags, BYTE *pbData, DWORD *pdwDataLen ); // // // // // // // in in in in in out in, out
Parameters
hProv
USER'S GUIDE
Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. hKey Handle of the key to be exported. hPubKey Handle of a cryptographic key belonging to the destination user. The exported key data within the created key BLOB is encrypted using this key. This ensures that only the destination user will be able to make use of the key BLOB. Most often, this handle will be the handle of the key exchange public key of the destination user. Certain protocols, however, require that this handle be the handle of a session key belonging to the destination user. If the key BLOB is a PUBLICKEYBLOB and is not to be encrypted, this parameter is not used and must be zero. dwBlobType Type of key BLOB to be exported. The following key BLOB types are defined. BLOB type SIMPLEBLOB PUBLICKEYBLOB PRIVATEKEYBLOB OPAQUEKEYBLOB To transport session keys. To transport public keys. To transport public/private key pairs. To store session keys in an Schannel CSP. The OPAQUEKEYBLOB type is non-transferable and must be used within the CSP that generated the BLOB. Use
Additional key BLOB types can be defined as needed. dwFlags The following values are defined. These values are only used in Schannel CSPs. Flag value CRYPT_DESTROYKEY CRYPT_SSL2_ FALLBACK Effect Destroys the original key in the OPAQUEKEYBLOB. Sets the first eight bytes of the RSA encryption block padding to 0x03 rather than to random data. This prevents version rollback attacks and is discussed in the SSL3 specification.
DSSSCT
USER'S GUIDE
pbData Pointer to a data buffer to return the key BLOB. It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length. pdwDataLen Address of a DWORD value to hold the length of the BLOB to be returned in the pbData buffer. Upon function entry, this DWORD value contains the number of bytes allocated for the pbData buffer. Upon exit, it must be set to the actual number of bytes of data needed for the pbData buffer. If the buffer specified by pbData is not large enough to hold the key BLOB data, the ERROR_MORE_DATA error code is returned with the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen. If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_MORE_DATA NTE_BAD_FLAGS NTE_BAD_KEY Description The pbData buffer is not large enough to hold the requested data. The dwFlags parameter contains an invalid value. One or both of the keys specified by hKey and hPubKey are invalid. The key cannot be exported because the CRYPT_EXPORTABLE flag was not specified when the key was created. The key BLOB type specified by dwBlobType is PUBLICKEYBLOB, but hPubKey does not contain a public key handle. The dwBlobType parameter specifies an unknown BLOB type.
NTE_BAD_KEY_STATE
NTE_BAD_PUBLIC_KEY
NTE_BAD_TYPE
DSSSCT File : dcsp
USER'S GUIDE
NTE_BAD_UID NTE_NO_KEY
The CSP context that was specified when the hKey key was created cannot now be found. A session key is being exported and the hExpKey parameter does not specify a public key.
Requirements
See Also
CPImportKey, CryptExportKey
3.1.2.5 CPGenKey The CPGenKey function generates a random cryptographic key or key pair.
BOOL CPGenKey( HCRYPTPROV hProv, ALG_ID Algid, DWORD dwFlags, HCRYPTKEY *phKey ); // in // in // in // out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. Algid Identifier for the algorithm for which the key is being generated. This algorithm must be one of those supported by this CSP. If a session key is to be generated, this value specifies an encryption algorithm such as:
USER'S GUIDE
CALG_RC2 CALG_RC4 CALG_DES
If a public/private key pair is to be generated, this value specifies a key pair type such as: dwFlags Flags specifying attributes pertaining to the key generated. The sizes of RSA signature and key exchange keys can be set when the key is generated. The key size is set with the upper 16 bits of the dwFlags parameter and these 16 bits represent the length of the modulus in bits. This applies to the Microsoft Base Cryptographic Provider. These are flags currently defined. Flag value Effect When a session key or private key is created and this flag is not set, the CSP must refuse to export the key. If the application attempts to export the key using CPExportKey, that function fails and returns the NTE_BAD_KEY_STATE error code. This flag only applies to the export of session keys and private keys. It does not apply to public keys, which are always exportable. When set, the new session key is assigned a random salt value. If this flag is not set, the session key is assigned a salt value of zero. This flag does not apply to public/private key pairs. Specifies that a no salt value is assigned for 40-bit symmetric keys. For more information, see New Salt Value Functionality. When set, the CSP notifies the user through a dialog box or some other method when certain actions are attempted using this key. The precise behavior is specified by the CSP or the CSP type used. If the provider context was acquired with CRYPT_SILENT set, using this flag causes a failure and the last error is set to NTE_SILENT_CONTEXT The Microsoft Enhanced Cryptographic Provider supports this flag in Internet Explorer 4.0 and later, Windows 98, and Windows 2000. Prior to Internet Explorer 4.0, this flag was
AT_KEYEXCHANGE AT_SIGNATURE
CRYPT_EXPORTABLE
CRYPT_CREATE_SALT
CRYPT_NO_SALT
CRYPT_USER_ PROTECTED
DSSSCT
USER'S GUIDE
ignored. CRYPT_PREGEN phKey Address to which the function copies a handle to the newly-generated key. Specifies an initial Diffie-Hellman or DSS key generation. Currently only useful with Diffie-Hellman/DSS CSPs.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID NTE_BAD_FLAGS NTE_FAIL NTE_BAD_UID NTE_PERM NTE_SILENT_ CONTEXT Description The Algid parameter specifies an algorithm that this CSP does not support. The dwFlags parameter contains an invalid value. The function failed in some unexpected way. The hProv parameter does not contain a valid context handle. An attempt was made to create a key pair when CRYPT_VERIFYCONTEXT was specified. Provider could not perform the action because the context was acquired as silent.
Remarks
An application cannot create new key pairs if no key container is currently open. This can happen if CRYPT_VERIFYCONTEXT was set in the CPAcquireContext call. If a key cannot be created, the NTE_PERM error code is returned. CPGenRandom is generally used to generate the random key material. Keys generated for symmetric block ciphers must be set up by default in cipher block chaining (CBC) mode with an initialization vector of zero. This cipher mode provides a good default method for bulk encrypting data. These parameters are changed using the CPSetKeyParam function.
Requirements
Windows NT/2000: Requires Windows NT 4.0 or later. Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer
USER'S GUIDE
3.02 and later). Windows CE: Requires version 1.0 or later. Header: Declared in wincrypt.h.
See Also
CPDestroyKey, CPExportKey, CPImportKey, CryptGenKey
3.1.2.6 CPGenRandom The CPGenRandom function fills a buffer with random bytes.
BOOL CPGenRandom( HCRYPTPROV hProv , DWORD dwLen , BYTE * pbBuffer ); // in // in // in, out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. dwLen Number of bytes of random data to be generated. pbBuffer Buffer to which the function copies the random data. This buffer is dwLen bytes in length. Upon input to the function, this buffer can contain up to dwLen bytes of random data that the CSP can use to generate a seed value. This is discussed further in Remarks.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_UID NTE_FAIL Description The hProv parameter does not contain a valid context handle. The function failed in some unexpected manner.
Remarks
USER'S GUIDE
CPGenRandom is one of the more difficult functions to implement correctly, and it must be done correctly to maintain the security of a CSP. CPGenRandom is used internally by the CPGenKey function, as well by applications when generating data items used in cryptographic protocols such as challenge strings. A CSP is not producing message security if values of the cryptographic keys or challenge strings produced by a CSP are predictable. There are two components to a good random number generator: a method of getting a random seed, and an algorithm that will generate a good pseudo-random stream of data based on that seed. Generating a random seed can depend on the hardware used by the CSP. If the CSP has access to a hardware random number source such as some slightly radioactive material and a Geiger counter, the problem is solved. A completely software-based CSP might use one of the following sources: The system time. Any high-precision clocks that exist on the system board and peripherals. The cursor or mouse pointer location. Any accumulated physical state information devices such as in keyboard input buffers, I/O service queues, and video drivers. The number of tasks in the OS scheduling queue, their task identifiers, or their code base addresses and sizes. Data from the application, passed into the CryptGenRandom function and passed on to CPGenRandom as the input bytes in pbBuffer.
Some or all of this data can be hashed along with the random seed from the previous session to create a random seed. New seeds should be generated periodically throughout the session, to avoid placing too much reliance on the pseudo-random stream generator. Once the random seed has been obtained, any number of algorithms can be used to generate a pseudo-random stream of data. Sometimes a stream cipher such as RC4 is used for this purpose, with the seed forming the keying material. The following sources describe other algorithms and techniques: Bellare, M., and P. Rogaway. Optimal Asymmetric Encryption. Advances in CryptologyEUROCRYPT '94, ed. by A. deSantis, Springer-Verlag, 1995, pp. 92-111, Lecture Notes in Computer Science, vol. 950. Blum, L. , M. Blum, and M. Shub. A Simple Unpredictable Pseudo-Random Number Generator. SIAM Journal on Computing 15(2)(May 1986); 364-383. M. Blum and S. Micali, "How to generate cryptographically strong sequences of pseudorandom bits," SIAM Journal on Computing 13(4)(November 1984); 850-864.
DSSSCT
USER'S GUIDE
Requirements
See Also
CryptGenRandom
3.1.2.7 CPGetKeyParam The CPGetKeyParam function retrieves data that governs the operations of a key.
BOOL CPGetKeyParam( HCRYPTPROV hProv , HCRYPTKEY hKey , DWORD dwParam , BYTE * pbData , DWORD * pdwDataLen , DWORD dwFlags ); // // // // // // in in in out in, out in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. hKey Handle to the key that is the target of the query. dwParam All key types can use any of the following key parameter types. dwParam value KP_ALGID all Key types Copied to pdData The algorithm identifier (ALG_ID) 4 used by this key object. If hKey is a session key, a DWORD value indicating the block length in bits.
Ref : DSPUSG990001
Returned pdwDataLen
KP_BLOCKLEN
all
DSSSCT
File : dcsp
Revision : 1.0
72 / 116
USER'S GUIDE
If hKey is a public/private key pair, a DWORD value indicating the key pair's granularity. For RSA key pairs, this is the size of the modulus. If the public-key algorithm does not support encryption, the NTE_BAD_TYPE error code is returned. KP_KEYLEN all The actual length of the key in bits. For more information, see 4 Remarks.
KP_SALT
A BYTE array containing the key's current salt value. This parameter does not apply to public/private key Length of the BYTE all session pairs. If hKey references a keys array public/private key pair, the NTE_BAD_TYPE error code is returned. A DWORD value indicating the permission to be associated with 4 the key. See Remarks for a table of permission flags.
KP_ PERMISSIONS
all
KP_IV
A BYTE array containing the key's Length of the BYTE block cipher keys current initialization vector (IV). array A DWORD value indicating the block padding method used. Currently, cipher keys PKCS5_Padding is defined. 4
KP_PADDING
KP_MODE
A DWORD value indicating the block cipher mode used. See the table in 4 cipher keys Remarks for possible values. A DWORD value indicating the block feedback width in bits. This is used 4 cipher keys only with OFB and CFB cipher modes. RC2 A DWORD value indicating the 4 effective key length of an RC2 key.
KP_MODE_BITS
KP_EFFECTIVE_ KEYLEN
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
73 / 116
USER'S GUIDE
More parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32 header files. pbData Pointer to a data buffer. The dwParam parameter specifies the type of data to be copied into this buffer. It is not an error if this parameter is NULL. If pbData is NULL, no data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. See Retrieving Data of Unknown Length for a detailed discussion and examples. pdwDataLen Address of a DWORD to hold the byte length for the pbData buffer. Upon function entry, the DWORD contains the number of bytes allocated for the pbData buffer. Upon exit, it must be set to the actual number of bytes needed for the pbData buffer. If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned with the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen. If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter. dwFlags No flags are currently defined.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_MORE_DATA NTE_BAD_FLAGS NTE_BAD_KEY or NTE_NO_KEY NTE_BAD_TYPE
DSSSCT File : dcsp
Description The pbData buffer is not large enough to hold the requested data. The dwFlags parameter is non-zero. The key specified by the hKey parameter is invalid. The dwParam parameter specifies an unknown parameter number.
USER'S GUIDE
NTE_BAD_UID
The CSP context that was specified when the key was created cannot now be found.
Remarks
Microsoft CSPs return a key length of 64 bits for CALG_DES, 128 for CALG_3DES_112, and 192 for CALG_3DES. These lengths are different from the lengths returned when enumerating algorithms with CryptGetProvParam with dwParam set to PP_ENUMALGS. The length returned CPGetProvParam is the actual size of the key including parity bits. Microsoft CSPs that support the ALG_ID of type CALG_CYLINK_MEK return 64 bits for that algorithm. CALG_CYLINK_MEK is a 40 bit key, but has parity bits and zeroed key bits to make the key length 64 bits. The following table lists the permission flags that are currently defined. Permission flag CRYPT_ENCRYPT CRYPT_DECRYPT CRYPT_EXPORT CRYPT_READ CRYPT_WRITE CRYPT_MAC Description Allows encryption Allows decryption Allows key to be exported Allows parameters to be read Allows parameters to be set Allows MACs to be used with key Value 0x0001 0x0002 0x0004 0x0008 0x0010 0x0020
The following table lists the cipher modes that are currently defined. Cipher mode CRYPT_MODE_ECB CRYPT_MODE_CBC CRYPT_MODE_OFB CRYPT_MODE_CFB Description Electronic codebook Cipher block chaining Output feedback mode Cipher feedback mode Value 2 1 3 4
Requirements
USER'S GUIDE
See Also
CPSetKeyParam, CryptGetKeyParam
3.1.2.8 CPGetUserKey The CPGetUserKey function retrieves the handle of one of the permanent key pairs in the hProv key container.
BOOL CPGetUserKey( HCRYPTPROV hProv , DWORD dwKeySpec , HCRYPTKEY * phUserKey ); // in // in // out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAquireContext. dwKeySpec Specification of the key to retrieve. The following key pair types are currently defined: Key Pair Type AT_KEYEXCHANGE AT_SIGNATURE phUserKey Address to which the function copies the handle of the retrieved key. This pointer must not be NULL. Descriptipn Key used to encrypt and exchange session keys. Keys used to create and verify digital signatues.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_KEY NTE_BAD_UID
DSSSCT File : dcsp
Description The key specified by the hKey parameter is invalid. The CSP context that was specified when the key was created cannot now be found.
USER'S GUIDE
NTE_NO_KEY
The key specified by the dwKeySpec parameter does not exist.
Requirements
See Also
CPExportKey, CPGenKey, CryptGetUserKey
3.1.2.9 CPImportKey The CPImportKey function transfers a cryptographic key from a key BLOB to a CSP key container.
BOOL CPImportKey( HCRYPTPROV hProv , CONST BYTE * pbData , DWORD dwDataLen , HCRYPTKEY hPubKey , DWORD dwFlags , HCRYPTKEY * phKey ); // // // // // // in in in in in out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAquireContext. pbData Buffer containing the key BLOB. This key BLOB was generated by the CPExportKey function, either by this CSP or by a CSP running on a remote computer. This key BLOB consists of a standard header followed by the key material. The key material is often encrypted. dwDataLen Length, in bytes, of the key BLOB. hPubKey
USER'S GUIDE
The meaning of this parameter differs, depending on the CSP type and the type of key BLOB being imported. If a signed key BLOB is being imported, the key is used to validate the signature of the key BLOB. In this case, this parameter must contain a handle to the key exchange public key of the party that created the key BLOB. If the key BLOB is a SIMPLEBLOB encrypted with the key exchange key pair, this parameter can be the handle to the key exchange key. If the key BLOB is encrypted with a session key, as is often done by Fortezza CSPs, for example, this parameter contains a handle to that session key. If the key BLOB is a PUBLICKEYBLOB and is not encrypted, this parameter is not used and is set to zero. dwFlags This parameter is currently used only when a public/private key pair is being imported into the CSP in the form of a PRIVATEKEYBLOB. The following flags are defined: Flag Value Description If the key being imported is eventually to be re-exported, the CRYPT_EXPORTABLE flag must be placed in this parameter. If the CRYPT_EXPORTABLE flag is not used, future calls to CryptExportKey with the key handle will fail. A no-salt value is specified for a 40-bit symmetric key. For more information, see New Salt Value Functionality.
CRYPT_EXPORTABLE
CRYPT_NO_SALT phKey
Address to which the function copies a handle to the key that was imported.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID Description The simple key BLOB being imported is not encrypted with the expected key exchange algorithm. The most likely cause of this error is incompatible CSPs. The algorithm of the public key being imported is not supported by this CSP.
NTE_BAD_DATA
DSSSCT File : dcsp
USER'S GUIDE
NTE_BAD_FLAGS NTE_BAD_TYPE NTE_BAD_UID NTE_BAD_VER
The dwFlags parameter is non-zero. The key BLOB type is not supported by this CSP and is possibly invalid. The hProv parameter does not contain a valid context handle. The key BLOB's version number indicates a key BLOB version that the CSP does not support.
Requirements
See Also
CPExportKey, CPGenKey, CryptImportKey
3.1.2.10 CPSetKeyParam The CPSetKeyParam function customizes the operations of a key.

BOOL CPSetKeyParam( HCRYPTPROV hProv , HCRYPTKEY hKey , DWORD dwParam , BYTE * pbData , DWORD dwFlags ); // // // // // in in in in in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained with a call to CPAcquireContext. hKey Handle to the target key on which to set parameters. dwParam The following table list currently defined dwParam values.
USER'S GUIDE
Value KP_SALT
Contents of the pbData Buffer A BYTE array containing the key's current salt value. A BYTE array containing the key's current salt value.
KP_SALT_EX
This parameter is not used with public/private key pairs. If hKey references a public/private key pair, the NTE_BAD_TYPE error code is returned. A DWORD defining the key's permission flags. Flags can be combined using bitwise OR operations. See the table in the Remarks section for key permission flag values and their meanings. A BYTE array containing the key's current initialization Vector (IV). A DWORD indicating the padding method used by the key's cipher. PKCS5_PADDING is the only padding method value defined. It represents PKCS 5 ( sec 6.2) padding. A DWORD indicating the cipher mode. See the Remarks section for a table of possible cipher modes. A DWORD indicating the feedback width, in bits. This parameter only applies when the OFB or CFB cipher modes are used. A Microsoft base provider implementation compatible CSP using RC2 must support KP_EFFECTIVE_KEYLEN used to set the effective key length of an RC2 key.
KP_ PERMISSIONS KP_IV KP_PADDING
KP_MODE KP_MODE_BITS KP_EFFECTIVE_ KEYLEN
Parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32 header files.. pbData Parameter data buffer. Upon entry to the function, this buffer will contain the data that corresponds to the dwParam parameter value. Notice that the length of this data is not explicitly specified but is implied by the dwParam parameter value. dwFlags No flags are currently defined.
Return Values
If the function succeeds, the return value is TRUE.
USER'S GUIDE
If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS NTE_BAD_TYPE NTE_BAD_UID NTE_FAIL Description The dwFlags parameter is non-zero or the pbData buffer contains an invalid value. The dwParam parameter specifies an unknown parameter. The CSP context that was specified when the hKey key was created cannot now be found. The function failed in some unexpected manner.
Remarks
The following table lists the defined permission flags: Permission flag CRYPT_ENCRYPT CRYPT_DECRYPT CRYPT_EXPORT CRYPT_READ CRYPT_WRITE CRYPT_MAC Description Allows encryption Allows decryption Allows key to be exported Allows parameters to be read Allows parameters to be set Allows MACs to be used with key
The following table lists the defined cipher modes: Cipher mode CRYPT_MODE_ECB CRYPT_MODE_CBC CRYPT_MODE_OFB CRYPT_MODE_CFB Description Electronic codebook Cipher block chaining Output feedback mode Cipher feedback mode
Requirements
Windows NT/2000: Requires Windows NT 4.0 or later. Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02 and later).
USER'S GUIDE
Windows CE: Requires version 1.0 or later. Header: Declared in wincrypt.h.
See Also
CPGenKey, CPGetKeyParam, CryptSetKeyParam
3.1.3
Data Encryption Functions
Data encryption functions support encryption and decryption operations. The following table briefly describes each function. Function CPDecrypt CPEncrypt Description Decrypts a section of ciphertext using the specified encryption key. Encrypts a section of plaintext using the specified encryption key.
3.1.3.1 CPDecrypt The CPDecrypt function decrypts data previously encrypted with the CPEncrypt function. Optionally, the application can specify that the decrypted data be hashed.
BOOL CPDecrypt( HCRYPTPROV hProv , HCRYPTKEY hKey , HCRYPTHASH hHash , BOOL Final , DWORD dwFlags , BYTE * pbData , DWORD * pdwDataLen ); // // // // // // // in in in in in in, out in, out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hKey Handle to the session key for the decryption. This key specifies the decryption algorithm to be used. hHash
USER'S GUIDE
Handle to a hash object. This parameter is used only if a hash of the data is to be computed after the data is decrypted. This parameter is zero if no hash is to be done. Final Boolean value specifying whether this is the last section in a series of data blocks being decrypted. This will be TRUE if this is the last or only block, and FALSE otherwise. dwFlags No flags are currently defined. pbData Buffer on input holding the ciphertext to be decrypted. Once the decryption has been performed, the plaintext is written to this buffer overwriting the ciphertext. If a block cipher is used and dwFlags is TRUE, any padding data must be removed before returning the plaintext to the application. This is simpler than the encryption case, since the plaintext generated is never larger than the ciphertext. pdwDataLen Address of a DWORD. Upon entry, the DWORD is the number of bytes of ciphertext in the pbData buffer. If a block cipher is used and Final is FALSE, this value must be a multiple of the cipher block length. Decryption is done in place, and the CPDecrypt function does not need to buffer any data internally. Upon exit, the DWORD pointed to by this parameter indicates the number of bytes of plaintext in the pbData buffer.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID Description The hKey session key specifies an algorithm that this CSP does not support. The data to be decrypted is invalid. For example, when a block cipher is used and the Final flag is FALSE, the value specified by pdwDataLen must be a multiple of the block size. This error can also be returned when the padding is found to be invalid.
NTE_BAD_DATA
DSSSCT
File : dcsp
USER'S GUIDE
NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_KEY NTE_BAD_LEN NTE_BAD_UID NTE_DOUBLE_ ENCRYPT NTE_FAIL
The dwFlags parameter is non-zero. The hHash parameter contains an invalid handle. The hKey parameter does not contain a valid handle to a session key. The size of the output buffer is too small to hold the generated plaintext. The CSP context that was specified when the key was created cannot now be found. The application attempted to decrypt the same data twice. The function failed in some unexpected way.
Remarks
In Windows 2000, the Microsoft Enhanced RSA Provider supports direct encryption with RSA public keys and decryption with RSA private keys. The encryption is done with PKCS #1 Type 2 padding, and on decryption this padding is verified. The length of ciphertext text data to be decrypted must be the same length as the modulus of the RSA key used to encrypt the data. If the ciphertext has 0x00 bytes in the most significant bytes, these bytes must be included in the input data buffer and in the input buffer length. The ciphertext must be in little endian format. For additional requirement for developing this function for an schannel provider, see Bulk Data Encryption.
Requirements
See Also
CPEncrypt, CPGenKey, CryptDecrypt
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
84 / 116
USER'S GUIDE
3.1.3.2 CPEncrypt The CPEncrypt function encrypts data. Optionally, the application can specify that a hash of the paintext data is to be generated.
BOOL CPEncrypt( HCRYPTPROV hProv , HCRYPTKEY hKey , HCRYPTHASH hHash , BOOL Final , DWORD dwFlags , BYTE * pbData , DWORD * pdwDataLen , DWORD dwBufLen ); // // // // // // // // in in in in in in, out in, out in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hKey Handle to the key to use for the encryption. This key handle includes a a specification of the encryption algorithm to be used. hHash Handle to a hash object. This parameter is used only if a hash of the data is to be computed before time the data is encrypted. This parameter is zero if no hash is to be done. Final Boolean value that specifies whether this is the last section in a series being encrypted. This will be TRUE if this is the last or only block, and FALSE otherwise. dwFlags No flags are currently defined. pbData Buffer holding the plaintext to be encrypted. Once the encryption has been performed, the ciphertext overwrites the plaintext in the pbdata buffer. pdwDataLen Address of a DWORD indicating byte length. Upon function entry, this DWORD specifies the number of bytes of plaintext in the pbData buffer. If a block cipher is used and dwFlags
USER'S GUIDE
is FALSE, this must be a multiple of the cipher block length so that the CPEncrypt function need not buffer any data internally. Upon exit, this DWORD indicates length in bytes of ciphertext in the pbData buffer. When a block cipher is used, the size of the ciphertext generated is sometimes larger than that of the plaintext. However, it must never be greater than dwBufLen. dwBufLen Size of the pbData buffer in bytes.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID Description The hKey session key specifies an algorithm that this CSP does not support. The data to be encrypted is invalid. For example, when a block cipher is used and the Final flag FALSE, the value specified by pdwDataLen must be a multiple of the block size. The dwFlags parameter is non-zero. The hHash parameter contains an invalid handle. An attempt was made to add data to a hash object that is already marked "finished." The hKey parameter does not contain a valid handle to a key. The size of the output buffer is too small to hold the generated ciphertext. The CSP context that was specified when the key was created cannot now be found. The application attempted to encrypt the same data twice. The function failed in some unexpected way.
NTE_BAD_DATA
NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_HASH_STATE NTE_BAD_KEY NTE_BAD_LEN NTE_BAD_UID NTE_DOUBLE_ENCRYPT NTE_FAIL

DSSSCT
USER'S GUIDE
NTE_NO_MEMORY
The CSP ran out of memory during the operation.
Remarks
In Windows 2000, the Microsoft Enhanced RSA Provider supports direct encryption with RSA public keys and decryption with RSA private keys. The encryption is done with PKCS #1 Type 2 padding, and on decryption this padding is verified. The length of plaintext data that can be encrypted with a call to CPEncrypt with an RSA key is the length of the key modulus minus 11 bytes. The 11 bytes is the chosen minimum for PKCS #1 padding. The ciphertext is returned in little endian format.
Requirements
See Also
CPDecrypt, CPGenKey, CryptEncrypt 3.1.4 Hashing and Digital Signature Functions
Hashing and digital signature functions compute hashes and create and verify digital signatures. The following table briefly describes each function. Function CPCreateHash CPDestroyHash CPDuplicateHash CPGetHashParam CPHashData CPHashSessionKey CPSetHashParam CPSignHash CPVerifySignature
DSSSCT File : dcsp
Description Creates a hash object and returns a handle to it. Destroys a hash object. Makes an exact copy of a hash object and the state the hash is in. Retrieves a hash object parameter. Hashes a block of data, adding it to the specified hash object. Hashes a session key, adding it to the specified hash object. Sets a hash object parameter. Signs the specified hash object. Verifies a digital signature.
USER'S GUIDE
3.1.4.1 CPCreateHash The CPCreateHash function creates a hash object and initiates the hashing of a stream of data.
BOOL CPCreateHash( HCRYPTPROV hProv , ALG_ID Algid , HCRYPTKEY hKey , DWORD dwFlags , HCRYPTHASH * phHash ); // // // // // in in in in out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. Algid Algorithm identifier (ALG_ID) of the hash algorithm to be used. hKey If the hash is a keyed hash algorithm such as MAC, the key handle for the hash is passed in this parameter. For non-keyed algorithms, this parameter is set to zero. dwFlags No flags are currently defined. phHash Address to which the function copies a handle to the new hash object.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID NTE_BAD_FLAGS
DSSSCT File : dcsp
Description The Algid parameter specifies an algorithm that this CSP does not support. The dwFlags parameter is non-zero.
USER'S GUIDE
NTE_BAD_KEY
The algid parameter specifies a keyed hash algorithm, such as CALG_MAC, and the hKey parameter is either zero or an invalid key handle. This error code will also be returned if the key is to a stream cipher or if the cipher mode is one that does not use feedback. The CSP ran out of memory during the operation.
NTE_NO_MEMORY
Remarks
For information on writing CPCreateHash for schannel applications, see Schannel CSP Reference.
Requirements
See Also
CPDestroyHash, CPHashData, CryptCreateHash
3.1.4.2 CPDestroyHash The CPDestroyHash function destroys the hash object referenced by the hHash parameter.
BOOL CPDestroyHash( HCRYPTPROV hProv , // in HCRYPTHASH hHash // in );
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to the hash object to be destroyed.
Return Values
If the function succeeds, the return value is TRUE.
USER'S GUIDE
If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID NTE_BAD_HASH NTE_BAD_UID Description The hHash handle specifies an algorithm that this CSP does not support. The hash object specified by the hHash parameter is invalid. The CSP context that was specified when the hash object was created cannot now be found.
Requirements
See Also
CPCreateHash, CryptDestroyHash
3.1.4.3 CPDuplicateHash The CPDuplicateHash function makes an exact copy of a hash and its state.
BOOL CPDuplicateHash( HCRYPTPROV hUID , HCRYPTHASH hHash , DWORD * pdwReserved , DWORD dwFlags , HCRYPTHASH * phHash ); // // // // // in in in in out
Parameters
hUID Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash The handle to the hash to be duplicated.
USER'S GUIDE
pdwReserved This parameter is reserved for future use and must be NULL. dwFlags This parameter is reserved for future use and must be zero. phHash The address of the handle to the duplicated hash. Must be the address of a buffer with enough memory allocated to hold the duplicated hash.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_CALL_ NOT_IMPLEMENTED ERROR_INVALID_ PARAMETER NTE_BAD_HASH Description This is a new function and existing CSPs might not implement it. This error is returned if the CSP does not support this function. One of the parameters contains an invalid value. This is most often an illegal pointer. The handle to the original hash is not valid.
Remarks
CPDuplicateHash makes a copy of a hash including its exact state. To generate two different hashes starting with some common hashed data, 1. create a single hash object 2. hash the common data to that object 3. duplicate the object the CPDuplicateHash function. 4. hash different data to the original hash object and the newly create object CPDestroyHash must be called to destroy any hashes created with CPDuplicateHash. Destroying the original hash does not cause the duplicate hash to be destroyed. Once a duplicate hash is made, it is separate from the original hash. There is no shared state between the two hashes.
Requirements
USER'S GUIDE
See Also
CPDestroyHash, CryptDuplicateHash
3.1.4.4 CPGetHashParam The CPGetHashParam function retrieves data about the operations of a hash object. The actual hash value can be obtained using this function.
BOOL CPGetHashParam( HCRYPTPROV hProv , HCRYPTHASH hHash , DWORD dwParam , BYTE * pbData , DWORD * pdwDataLen , DWORD dwFlags ); // // // // // // in in in out in, out in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to the target hash object on which a query is being made. dwParam Parameter number. The following table lists currently defined dwParam values and their meanings. Value HP_ALGID Return contents of the pbData buffer An algorithm specifier (ALG_ID) indicating the algorithm used by this hash object is copied to the pbData buffer. A value 4 is returned in pdwDataLen. A DWORD specifying the number of bytes in the hash value produced by this hash object is returned in the pbData buffer. A value 4 is returned in pdwDataLen.
HP_HASHSIZE
DSSSCT
USER'S GUIDE
The hash computed value for the hash object specified by hHash is returned in the pbData buffer. The length of the hash value should be returned in pdwDataLen. HP_HASHVALUE The call to CPGetHashParam function completes the hash. After this call, no more data can be added to the hash. Additional calls to CPHashData or CPHashSessionKey must fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature succeed and use the completed hash object.
Parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Microsoft Win32 header files. pbData Pointer to a data buffer. The dwParam parameter specifies the type of data to be copied to this buffer. It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwDataLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. See Retrieving Data of Unknown Length for a detailed discussion and examples. pdwDataLen Address of a DWORD. Upon function entry, this DWORD contains the number of bytes allocated in the pbData buffer. Upon exit, this must be set to the number of bytes need for the pbData buffer. If the buffer specified by pbData is not large enough to hold the requested data, the ERROR_MORE_DATA error code is returned by the SetLastError function. In this case, the required buffer size must be returned in pdwDataLen. If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter. dwFlags No flags are currently defined.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError.
USER'S GUIDE
Error ERROR_MORE_DATA NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_TYPE NTE_BAD_UID
Description The pbData buffer is not large enough to hold the requested data. The dwFlags parameter is non-zero. The hash object specified by the hHash parameter is invalid. The dwParam parameter specifies an unknown parameter number. The CSP context that was specified when the hash was created cannot now be found.
Requirements
See Also
CPCreateHash, CPGetKeyParam, CPSetHashParam, CryptGetHashParam
3.1.4.5 CPHashData The CPHashData function feeds data into a specified hash object.
BOOL CPHashData( HCRYPTPROV hProv , HCRYPTHASH hHash , CONST BYTE * pbData , DWORD dwDataLen , DWORD dwFlags ); // // // // // in in in in in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
94 / 116
USER'S GUIDE
Handle to a hash object. An application obtains this handle by using the CryptCreateHash function. pbData Address of a buffer containing the data to be hashed. dwDataLen Number of bytes of data to be hashed. This must be zero if dwFlags is set to CRYPT_USERDATA. dwFlags The following value is currently defined: CRYPT_USERDATA The CSP must prompt the user to enter directly the data to be added to the hash. Any data entered is used and destroyed within this function and the application has no access to it. This flag can be used to allow the user to enter a PIN, a password, or other unique identification into the system. Support for this flag is optional.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_HASH_STATE Description The hHash handle specifies an algorithm that this CSP does not support. The dwFlags parameter contains an invalid value. The hash object specified by the hHash parameter is invalid. An attempt was made to add data to a hash object that is already marked as "finished." A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key is destroyed before the hashing operating is complete. The CRYPT_USERDATA flag is set, and the dwDataLen parameter has a non-zero value.
NTE_BAD_KEY
NTE_BAD_LEN
DSSSCT
File : dcsp
USER'S GUIDE
NTE_BAD_UID NTE_FAIL NTE_NO_MEMORY
The CSP context that was specified when the hash object was created cannot now be found. The function failed in some unexpected way. The CSP ran out of memory during the operation.
Requirements
See Also
CPCreateHash, CPHashSessionKey, CryptHashData
3.1.4.6 CPHashSessionKey The CPHashSessionKey function feeds a cryptographic key to a specified hash object. This allows a key to be hashed without the application having access to the key material.
BOOL CPHashSessionKey( HCRYPTPROV hProv, HCRYPTHASH hHash, HCRYPTKEY hKey, DWORD dwFlags ); // // // // in in in in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to a hash object. An application obtains this handle by using the CryptCreateHash function (in the CryptoAPI). hKey Handle to the session key object to be hashed. dwFlags
USER'S GUIDE
The following dwFlags value is defined: CRYPT_LITTLE_ENDIAN Bytes of the key will be hashed in a little endian form. The Microsoft Cryptographic Providers support this flag in Microsoft Internet Explorer version 4.0 and later, Windows 98, and Windows 2000. Note By default (dwFlags is 0) the bytes of the key are hashed in a big endian form.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_ALGID NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_ HASH_STATE Description The hHash handle specifies a hash algorithm that this function does not support. The dwFlags parameter is non-zero. The hash object specified by the hHash parameter is invalid. An attempt was made to add data to a hash object that is already marked as "finished." A keyed hash algorithm is being used, but the session key is no longer valid. This error will be generated if the session key passed to CPCreateHash is destroyed before the hashing operating is complete. The CSP context that was specified when the hash object was created cannot now be found. The function failed in some unexpected way.
NTE_BAD_KEY
NTE_BAD_UID NTE_FAIL
Remarks
The only data this function adds to the hash object is the session key material, itself. If necessary, an application, not the CSP, can hash the key's salt, initialization vector, and other hash state material. Depending on the CSP type, the key material might need to be formatted or padded in some specific way before being added to the hash. See CSP Interoperability for more details.
Requirements
Windows NT/2000: Requires Windows NT 4.0 or later. Windows 95/98: Requires Windows 95 OSR2 or later (or Windows 95 with Internet Explorer 3.02
USER'S GUIDE
and later). Windows CE: Requires version 1.0 or later. Header: Declared in wincrypt.h.
See Also
CPCreateHash, CPGenKey, CPHashData, CryptHashSessionKey 3.1.4.7 CPSetHashParam The CPSetHashParam function customizes the operations of a hash object.
BOOL CPSetHashParam( HCRYPTPROV hProv , HCRYPTHASH hHash , DWORD dwParam , BYTE * pbData , DWORD dwFlags ); // // // // // in in in in in
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to the hash object on which to set parameters. dwParam The following defined dwParam parameter value can be set: HP_HASHVAL The pbData buffer contains a BYTE array to be added to the hash object. This data must be of the same size and format as the hash value returned by the CPGetHashParam function. This data is placed directly into the hash object. Typically, the hash object specified by hHash will be empty. If this is not the case, an error can be returned. This parameter gives applications the ability to sign hash values, without having access to the base data. Because the application and the user have no idea what is being signed, this operation is intrinsically risky. It is envisioned that most CSPs will not support this parameter. Parameters can be added as needed. General-purpose parameters can be define in coordination with Microsoft to promote cross-vendor standardization and allow the new parameter numbers to be added to the standard Win32 header files.
USER'S GUIDE
pbData Parameter data buffer. Upon entry to the function, this buffer will contain the data that corresponds to the dwParam parameter number. Notice that the length of this data is not explicitly specified but is implied by the dwParam parameter value. dwFlags No flags are currently defined.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_TYPE NTE_BAD_UID NTE_FAIL Description The dwFlags parameter is non-zero or the pbData buffer contains an invalid value. The hash object specified by the hHash parameter is invalid. The dwParam parameter specifies an unknown parameter. The CSP context that was specified when the hKey key was created cannot now be found. The function failed in some unexpected way.
Requirements
See Also
CPCreateHash, CPGetHashParam, CPSignHash, CryptSetHashParam
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
99 / 116
USER'S GUIDE
3.1.4.8 CPSignHash The CPSignHash function signs a hash object.

BOOL CPSignHash( HCRYPTPROV hProv , HCRYPTHASH hHash , DWORD dwKeySpec , LPCWSTR sDescription , DWORD dwFlags , BYTE * pbSignature , DWORD * pdwSigLen ); // // // // // // // in in in in in out in, out
Parameters
hProv Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to the hash object to be signed. dwKeySpec Type of the key pair to be used to sign the hash. The following values are currently defined. Value AT_KEYEXCHANGE AT_SIGNATURE sDescription A NULL-terminated string with a description of the hash object to be signed. See the Remarks section for details. The use of this parameter is not recommended because of security vulnerabilities. It is recommended that it always be interpreted as set to NULL. Some CSPs might prefer to keep supporting it for backward compatibility with the Microsoft Cryptographic Service Provider. dwFlags The following value is defined for use with RSA providers. CRYPT_NOHASHOID The hash OID is not placed into the RSA public key encryption. If this flag is not set, the hash OID in the default signature is as specified in the definition of DigestInfo in PKCS #7.
Meaning The key exchange public/private key pair is to be used. The digital signature public/private key pair is to be used.
USER'S GUIDE
The Microsoft cryptographic providers support this flag in Windows 2000. This support is not included with Windows 98 or Internet Explorer 5.0 or later. pbSignature Pointer to a data buffer into which the signature data is to be placed. It is not an error if this parameter is NULL. If pbData is NULL, no parameter data is copied. Instead, the required buffer size (in bytes) is returned in pdwSigLen and a second call to the function with the correct number of bytes allocated for the pbData buffer is expected. For a detailed discussion and examples, see Retrieving Data of Unknown Length. pdwSigLen Address of a DWORD value of the signature data length. Upon function entry, this DWORD value contains the number of bytes allocated for the pbSignature buffer. Upon exit, it is set to the number of bytes required for the pbSignature buffer. If memory allocated for the pbSignature buffer is not large enough to hold the signature, the ERROR_MORE_DATA error code is returned by the SetLastError function. The required buffer size is returned in pdwDataLen. If this function fails with any error code other than ERROR_MORE_DATA, zero is returned in this parameter.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error ERROR_MORE_DATA NTE_BAD_ALGID NTE_BAD_FLAGS NTE_BAD_HASH NTE_BAD_UID NTE_NO_KEY NTE_NO_MEMORY
DSSSCT File : dcsp
Description The pbData buffer is not large enough to hold the requested data. The hHash handle specifies a hash algorithm that this function does not support. The dwFlags parameter is non-zero. The hash object specified by the hHash parameter is invalid. The CSP context that was specified when the hash object was created cannot now be found. The private key specified by dwKeySpec does not exist. The CSP ran out of memory during the operation.
USER'S GUIDE
Remarks
Depending on the key pair to be used, many CSPs ask the user directly before performing the signature operation. When this is the case, the sDescription string, if supported, is displayed to the user so that he or she knows what is being signed. CPSignHash typically performs the following steps internally: 1. The hash object is "finished," and the hash value extracted. 2. The hash value is padded out as required by the signature algorithm. 3. The actual signing operation is performed. The CPSignHash function completes the hash. After calling CPSignHash, no more data can be added to the hash. Additional calls to CPHashData or CPHashSessionKey fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature succeed and use the finished hash object.
Requirements
See Also
CPCreateHash, CPHashData, CPVerifySignature, CryptSignHash
3.1.4.9 CPVerifySignature The CPVerifySignature function verifies the digital signature.

BOOL CPVerifySignature( HCRYPTPROV hProv , HCRYPTHASH hHash , CONST BYTE * pbSignature , DWORD dwSigLen , HCRYPTKEY hPubKey , LPCWSTR sDescription , DWORD dwFlags ); // // // // // // // in in in in in in in
Parameters
hProv
USER'S GUIDE
Handle to a particular key container within the CSP. This handle is obtained by a call to CPAcquireContext. hHash Handle to the hash object to be verified. pbSignature Buffer containing the signature data. dwSigLen Length (in bytes) of the signature data. hPubKey Handle to the public key used to verify the signature. sDescription A NULL-terminated string with a description of the hash object. The use of this parameter is not recommended because of security vulnerabilities. It is recommended that it always be interpreted as set to NULL. Some CSPs might prefer to keep supporting it for backward compatibility with the Microsoft Cryptographic Service Provider. dwFlags The following value is defined for RSA providers: CRYPT_NOHASHOID The hash OID is not expected to be present and is not checked. If this flag is not set, the hash OID in the default signature is verified as specified in the definition of DigestInfo in PKCS #7. The Microsoft cryptographic providers support this flag in Windows 2000. This support is not included with Windows 98 or Internet Explorer 5.0 or later.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE, and the appropriate error code from the following table must be set using SetLastError. Error NTE_BAD_FLAGS
DSSSCT File : dcsp
Description The dwFlags parameter is non-zero.

USER'S GUIDE
NTE_BAD_HASH NTE_BAD_KEY
The hash object specified by the hHash parameter is invalid. The hPubKey parameter does not contain a handle to a valid public key. The signature failed to verify. This could be because the data itself has changed, the description string did not match, or the wrong public key was specified by hPubKey. s error might also be returned if the hashing or signature orithms do not match the ones used to create the signature.
NTE_BAD_SIGNATURE
NTE_BAD_UID NTE_NO_MEMORY
The CSP context that was specified when the hash object was created cannot now be found. The CSP ran out of memory during the operation.
Remarks
The CPVerifySignature function typically performs the following steps internally: 1. The sDescription description string, if supported, is added to the hash object. 2. The hash object is "finished," and the hash value extracted. 3. The hash value is padded out as required by the signature algorithm. 4. The actual verification operation is performed by using the hPubKey public key. The NTE_BAD_SIGNATURE error code is returned if the signed hash within the pbSignature buffer and the hash value in the hHash hash object do not match. CPVerifySignature completes a hash. After CPVerifySignature has been called, no more data can be added to the hash. Additional calls to CPHashData or CPHashSessionKey fail. However, additional calls to CPDeriveKey, CPGetHashParam, CPSignHash, and CPVerifySignature succeed and use the finished hash object.
Requirements
See Also
CPCreateHash, CPHashData, CPSignHash, CryptVerifySignature
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
104 / 116
USER'S GUIDE
3.1.5
CSP Auxiliary Functions
Functions in this section are used within a CSP's functions. 3.1.5.1 OffloadModExpo The OffloadModExpo function offloads modular exponentiation from a CSP to a hardware accelerator.
BOOL WINAPI OffloadModExpo( BYTE * pbBase , // in BYTE * pbExpo , // in DWORD cbExpo , // in BYTE * pbMod , // in DWORD cbMod , // in BYTE * pbResult , // out void * pReserved , // reserved DWORD dwFlags // in );
Parameters
pbBase Pointer to the base value to be exponentiated. The value is in little-endian form and the length (number of bytes in the value) must be the length passed in cbMod. The value must be padded with 0x00 bytes if the most significant byte does not have a bit set. This value must be less than the value passed in the pbMod parameter. pbExpo Pointer to the exponent the base value is to be raised to. The value is in little-endian form and the length (number of bytes in the value) must be the length passed in cbMod. The value must be padded with 0x00 bytes if the most significant byte does not have a bit set. This value must be less than the value passed in the pbMod parameter. cbExpo DWORD value representing the length of the exponent in bytes. pbMod Pointer to the modulus. The value is in little-endian form and the length (number of bytes in the value) must be the length passed in cbMod. The most significant byte of the modulus value must not be a 0x00 byte. cbMod DWORD value representing the length of the modulus in bytes. pbResult Pointer to the calculated result.
USER'S GUIDE
pReserved This parameter is reserved for future use and is set to NULL. dwFlags This parameter is reserved for future use and is set to NULL.
Return Values
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.
Remarks
A CSP will check in the registry for the value HKLM\Software\Microsoft\Cryptography\ExpoOffload that can be the name of a DLL. The CSP uses LoadLibrary to load that DLL and calls GetProcAddress to get the OffloadModExpo entry point. The CSP uses the entry point to perform all modular exponentiations for both public and private key operations.
Requirements
3.2 CSP Structures and Types

3.2.1 PROV_ENUMALGS
The PROV_ENUMALGS structure is returned by calls to CryptGetProvParam or CPGetProvParam. It holds information on the algorithms supported by a CSP.
typedef struct _PROV_ENUMALGS { ALG_ID aiAlgid; DWORD dwBitLen; DWORD dwNameLen; CHAR szName[20]; } PROV_ENUMALGS;
Members aiAlgid
USER'S GUIDE
An ALG_ID indicating an algorithm supported. dwBitLen A DWORD value indicating the length of the key. dwNameLen A DWORD value indicating the length of the name of the algorithm. szName A NULL-terminated sting containing the name of the algorithm.
Requirements
3.2.2
PROV_ENUMALGS_EX
The PROV_ENUMALGS_EX structure is returned by calls to CryptGetProvParam or CPGetProvParam. It holds information on the algorithms supported by a CSP.
typedef struct _PROV_ENUMALGS_EX { ALG_ID aiAlgid ; DWORD dwDefaultLen ; DWORD dwMinLen ; DWORD dwMaxLen ; DWORD dwProtocols ; DWORD dwNameLen ; CHAR szName [20]; DWORD dwLongNameLen ; CHAR szLongName [40]; } PROV_ENUMALGS_EX;
Members aiAlgid An ALG_ID identifying an algorithm supported. dwDefaultLen A DWORD value indicating the default key length using the indicated algorithm. dwMinLen
USER'S GUIDE
A DWORD value indicating the minimum key length using the indicated algorithm. dwMaxLen A DWORDvalue indicating the maximum key length using the indicated algorithm. dwProtocols A DWORD value indicating the number of protocols supported. dwNameLen A DWORD value indicating the length of the short protocol name. szName A NULL-terminated string with the name of the supported protocol. dwLongNameLen A DWORD value indicating the length of the supported protocol name. szLongName A NULL-terminated string with the long name of the supported protocol.
Requirements
3.2.3
VTableProvStruc
The VTableProvStruc structure contains pointers to callback functions that can be used by CSP functions.
typedef struct _VTableProvStruc { DWORD Version ; FARPROC FuncVerifyImage ; FARPROC FuncReturnhWnd ; DWORD dwProvType ; BYTE * pbContextInfo ; DWORD cbContextInfo ; LPSTR pszProvName ; } VTableProvStruc, *PVTableProvStruc; BOOL FuncVerifyImage (LPCSTR lpszImage, BYTE *pSigData); BOOL FuncReturnhWnd (DWORD *phWnd); DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 108 / 116
USER'S GUIDE
Members Version A DWORD value indicating the version of the structure. Three versions of this structure are used. Microsoft Windows NT version 4.0 and Microsoft Windows 95 use version 1, which consists of only the first three members: Version, FuncVerifyImage, and FuncReturnhWnd. Version 2 is available with Windows 98. The first six members are used. Version 3 is available with Windows 2000. It includes all seven members. FuncVerifyImage Pointer to a callback function to verify a signature. See Remarks for details. FuncReturnhWnd Pointer to a callback function that returns information on a window handle to use when interacting directly with the user using Microsoft Win32. CSPs that do not communicate directly with the user and CSPs that use dedicated hardware for this purpose can ignore this entry. This window handle is zero by default, but some applications will set it to a different value by using the CryptSetProvParam function. dwProvType A DWORD value that specifies the type of provider to acquire. The following provider types are predefined, and are discussed in detail in CSP Interoperability. PROV_RSA_FULL PROV_RSA_SIG PROV_DSS PROV_FORTEZZA PROV_MS_EXCHANGE
pbContextInfo Pointer to an array of context information. The pbContextInfo and cbContextInfo members together determine the information set used when performing a CPSetProvParam with the PP_CONTEXT_INFO parameter number specified. cbContextInfo A DWORD value indicating the number of elements in the pbContextInfo array. pszProvName
USER'S GUIDE
A string containing the name of the provider.
Remarks
The pointers in the VTableProvStruc structure are only available within CPAcquireContext. If members of the structure are needed after CPAcquireContext is called, copies of the needed structure elements must be made by the CSP. The function pointers in the structure can be copied and the function pointer can be used until the context is released. All auxiliary DLLs into which a CSP makes function calls must be signed in the same manner (and with the same key) as the primary CSP DLL. To make this work properly, the auxiliary DLLs must be loaded dynamically, using the LoadLib function. But before LoadLib is called, the signature of the DLL must be verified. The CSP does this verification by calling the FuncVerifyImage function, as illustrated in the following code fragment:
BOOL (FARPROC *ProvVerifyImage)(LPCSTR lpszImage, BYTE *pSigData); BYTE bSignature[72]; // "ProvVerifyImage" has been set to "pVTable->FuncVerifyImage" // within the CPAcquireContext function. // Load the C:\Winnt40\System32\signature.sig file into the // bSignature buffer. During development, this file is created // with the Sign.exe utility. ... // Verify the signature on the C:\Winnt40\System32\Signature.dll file. if(RCRYPT_FAILED(ProvVerifyImage("c:\\winnt40\\system32\\signature.dll", bSignature)) { SetLastError(NTE_BAD_SIGNATURE); return CRYPT_FAILED; } // Load the DLL with the LoadLib function, then acquire pointers to // the member functions with the GetProcAddress function. ...
Requirements
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
110 / 116
USER'S GUIDE
3.2.4
BLOBHEADER
The BLOBHEADER structure indicates a key's BLOB type and the algorithm that the key uses. One of these structures is located at the beginning of the pbData member of every key BLOB. This structure is not limited to the key BLOBs generated by the PROV_RSA_BASE and PROV_RSA_SIG provider types. The pbData member of any new key BLOB type must begin with this structure.
typedef struct _PUBLICKEYSTRUC { BYTE bType ; BYTE bVersion ; WORD reserved ; ALG_ID aiKeyAlg ; } BLOBHEADER, PUBLICKEYSTRUC;
Members bType Key BLOB type. The only BLOB types currently defined are PUBLICKEYBLOB, PRIVATEKEYBLOB, and SIMPLEBLOB. Other key BLOB types will be defined as needed. PUBLICKEYBLOBs are used to transport public keys, PRIVATEKEYBLOBs are used to transport public/private key pairs, and SIMPLEBLOBs are used to transport session keys. bVersion Version number of the key BLOB format. This currently must always have a value of 0x02. reserved A DWORD value reserved for future use. Must be set to zero. aiKeyAlg Algorithm identifier for the key contained by the key BLOB. Some examples are CALG_RSA_SIGN, CALG_RSA_KEYX, CALG_RC2, and CALG_RC4. Not all algorithm identifiers are valid with all BLOB types. For example, since an RC4 key is a session key, it cannot be exported into a PUBLICKEYBLOB.
Requirements
Windows NT/2000: Requires Windows NT 4.0 SP3 or later (or Windows NT 4.0 with Internet Explorer 3.02 or later). Windows 95/98: Requires Windows 98 (or Windows 95 with Internet Explorer 3.02 or later). Header: Declared in wincrypt.h.
USER'S GUIDE
3.2.4.1 Public Key BLOBs Public key BLOBs (type PUBLICKEYBLOB) are used to store RSA public keys. They have the following format:
BLOBHEADER blobheader; RSAPUBKEY rsapubkey; BYTE modulus[rsapubkey.bitlen/8];
Notice that public key BLOBs are not encrypted, but contain public keys in plaintext form. The RSAPUBKEY structure contains information specific to the particular public key contained in the key BLOB. It is defined as follows:
typedef struct _RSAPUBKEY { DWORD magic; DWORD bitlen; DWORD pubexp; } RSAPUBKEY;
The following table describes each of the fields in the RSAPUBKEY structure. Field magic bitlen pubexp Description This is set to "RSA1" (0x31415352) for public keys and to "RSA2" (0x32415352) for private keys. These hex values are an ASCII encoding of "RSA1" and "RSA2." Number of bits in the modulus. In practice, this must always be a multiple of 8. The public exponent.
The public key modulus data is located directly after the RSAPUBKEY structure. The size of this data will vary depending on the size of the public key. The number of bytes can be determined by dividing the value of the bitlen field of RSAPUBKEY by 8.
Sample Public Key BLOB

The following hex dump shows a sample public key BLOB, generated by the Microsoft Base Cryptographic Provider. This contains a key exchange public key.
0x00000000 0x00000008 0x00000010 0x00000018 0x00000020 0x00000028 0x00000030 0x00000038 0x00000040 0x00000048 0x00000050 06 52 01 27 ed 10 cf a9 4f 09 33 02 53 00 4c 20 e5 17 65 ce ec cf 00 41 01 7b 1a ee 81 b7 f1 c2 a4 00 31 00 da b8 48 f0 4e f2 30 be 00 00 e1 db 66 62 37 75 ad 96 a4 02 94 c5 44 39 8b 83 a0 f8 00 00 84 99 21 ae b5 84 b1 27 00 00 7a dd dc 8f 46 4e 22 2b ........ RSA1.... .......z 'L{..... . ..fD!. ...Hb9.. ....7..F .e.Nu..N O......" ...0..'+ 3...
Notice that the BLOBHEADER and RSAPUBKEY structures have been assigned the following values, and the last 64 bytes of the BLOB contain the public key's modulus data.
DEKART CRYPTO SERVICE PROVIDER blobheader.bType blobheader.bVersion blobheader.reserved blobheader.aiKeyAlg rsapubkey.magic rsapubkey.bitlen rsapubkey.pubexp = = = = = = = PUBLICKEYBLOB; CUR_BLOB_VERSION; 0; CALG_RSA_KEYX; 0x31415352; 512; 65537; // // // // // // //
USER'S GUIDE 0x06 0x02 0x0000 0x0000a400 "RSA1" 0x00000200 0x00010001
When filling in the BLOBHEADER structure, place zero in the reserved field.
3.2.4.2 Private Key BLOBs Private key BLOBs (type PRIVATEKEYBLOB) are used to store RSA public/private key pairs. They have the following format:
BLOBHEADER blobheader; RSAPUBKEY rsapubkey; BYTE modulus[rsapubkey.bitlen/8]; BYTE prime1[rsapubkey.bitlen/16]; BYTE prime2[rsapubkey.bitlen/16]; BYTE exponent1[rsapubkey.bitlen/16]; BYTE exponent2[rsapubkey.bitlen/16]; BYTE coefficient[rsapubkey.bitlen/16]; BYTE privateExponent[rsapubkey.bitlen/8];
If the key BLOB is encrypted, then everything but the BLOBHEADER portion of the BLOB is encrypted. Note that the encryption algorithm and encryption key parameters are not stored along with the private key BLOB. It is the responsibility of the application to manage this information. The following table describes each private key BLOB component. Note that these fields largely correspond to the ones described in section 7.2 of PKCS #1: RSA Encryption Standard. Field blobheader rsapubkey modulus prime1 prime2 exponent1 exponent2
DSSSCT
Description A BLOBHEADER structure as described in a previous section. The bType field must always have a value of PRIVATEKEYBLOB. A RSAPUBKEY structure as described in Public Key BLOBs. The magic field must always have a value of 0x32415352 ("RSA2"). The modulus. This has a value of "prime1 * prime2" and is often known as "n". Prime number 1, often known as "p". Prime number 2, often known as "q". Exponent 1. This has a numeric value of "d mod (p - 1)". Exponent 2. This has a numeric value of "d mod (q - 1)".
USER'S GUIDE
coefficient privateExponent
Coefficient. This has a numeric value of "(inverse of q) mod p". Private exponent, often known as "d".
Sample Private Key BLOB

The following hex dump shows a sample private key BLOB, generated by the Microsoft Base Cryptographic Provider. This contains a key exchange public/private key pair. Note that this sample contains a public key that is different than the one discussed in Public Key BLOBs.
0x00000000 0x00000008 0x00000010 0x00000018 0x00000020 0x00000028 0x00000030 0x00000038 0x00000040 0x00000048 0x00000050 0x00000058 0x00000060 0x00000068 0x00000070 0x00000078 0x00000080 0x00000088 0x00000090 0x00000098 0x000000a0 0x000000a8 0x000000b0 0x000000b8 0x000000c0 0x000000c8 0x000000d0 0x000000d8 0x000000e0 0x000000e8 0x000000f0 0x000000f8 0x00000100 0x00000108 0x00000110 0x00000118 0x00000120 0x00000128 0x00000130 07 52 01 db d1 6d c7 57 e1 71 f2 c3 b4 e1 c7 4e 9d b5 d4 f6 d0 b2 bf f2 83 19 11 ca d6 9f 7e b7 47 66 aa 18 15 2a c3 02 53 00 6f 4c eb 5d 7d ae dd 38 38 13 20 73 c7 92 eb 78 f0 7b eb a2 63 26 51 c8 ee 1f 84 06 16 43 34 fa 58 76 d1 29 00 41 01 10 24 2c c6 3e 2f 39 bb fe 89 31 94 91 0d df 14 7d 10 2e 6a 9b 1f a5 26 4b 49 7f 5e f2 86 ba 6c 95 52 9f a2 00 32 00 5c 7e d5 87 cb 86 fc 8d 00 16 0b ee 73 e8 71 98 63 ae 9f a6 b7 56 92 75 f0 42 1f 8b 5e 85 09 b7 90 56 5c 1e 00 00 6b 32 e7 8c 12 e9 d9 0e 5d 5e d2 81 67 a8 91 66 79 cf 6b 31 1f 33 a8 31 a0 59 2b c3 c9 5e 8a 1a 75 b5 bb 8a a4 02 df bf 2a 0b ea 6a 50 60 2c ca 07 28 be 34 61 dc 44 62 db 34 e9 d0 24 e4 51 eb 75 8f 53 de fb b1 a7 29 3d c0 00 00 51 87 14 95 a9 46 f9 a9 bc cf bc 17 7b 5a 24 e1 b0 67 40 2d 03 fe f5 2b e9 a4 89 70 65 0b 37 21 3e a4 6b 55 00 00 ef 1c 10 7b cd d0 98 d3 1e cd 9b 0c 78 24 dc 77 19 78 b3 cb 42 20 6d bc 83 81 a7 b6 80 57 ac 0b 23 1e 1d ea ........ RSA2.... ....k.Q. .o.\2... .L$~.*.. m.,....{ .]...... W}>..jF. ../..P.. q.9..`.. .8..],.. .8..^... ........ . 1..(.. .s..g.{x N..s.4Z$ .....a$. ...qf..w .x..yD.. ..}c.bgx .{..k.@. ....14-. ..j....B .c..3.. .&.V.$.m .Q..1.+. ..&u.Q.. ..K.Y... ..IB+u.. ......p. ~.^..Se. ...^^..W GC....7. f4....!. ..l.u.># .X...).. .vRV.=k. *..\..U. .)..
Notice that the BLOBHEADER and RSAPUBKEY structures have been assigned the following values:
blobheader.bType = PRIVATEKEYBLOB; blobheader.bVersion = CUR_BLOB_VERSION; DSSSCT File : dcsp // 0x07 // 0x02 Revision : 1.0 114 / 116
Ref : DSPUSG990001
DEKART CRYPTO SERVICE PROVIDER blobheader.reserved blobheader.aiKeyAlg rsapubkey.magic rsapubkey.bitlen rsapubkey.pubexp = = = = = 0; CALG_RSA_KEYX; 0x32415352; 512; 65537; // // // // //
USER'S GUIDE 0x0000 0x0000a400 "RSA2" 0x00000200 0x00010001
The following table shows the numeric values of each of the large numeric fields contained by the sample private key BLOB. As with all of the numbers in the public and private key BLOBs, these are in little-endian byte order. Field name modulus
6b e7 12 d9 df 2a ea 50 51 14 a9 f9 ef 10 cd 98 db 6d 57 71 6f eb 7d dd 10 2c 3e 39 5c d5 cb fc 32 8c e9 0e
Value
bf 0b 6a 60 87 95 46 a9 1c 7b d0 d3 d1 c7 e1 f2 4c 5d ae 38 24 c6 2f bb 7e 87 86 8d
prime1 prime2 exponent1 exponent2 coefficient
5d 2c bc 1e c3 38 fe 00 5e ca cf cd b4 13 89 16 d2 07 bc 9b e1 20 31 0b 81 28 17 0c c7 73 94 ee 67 be 7b 78 4e c7 91 73 a8 34 5a 24 9d 92 0d e8 91 61 24 dc b5 eb df 71 66 dc e1 77 d4 78 14 98 79 44 b0 19 f6 f0 7d 63 cf 62 67 78 d0 7b 10 ae 6b db 40 b3 b2 eb 2e 9f 31 34 2d cb bf a2 6a a6 1f e9 03 42 f2 63 9b b7 33 d0 fe 20 83 26 1f 56 a8 24 f5 6d 19 51 a5 92 31 e4 2b bc 11 c8 26 75 a0 51 e9 83 ca ee 4b f0 59 eb a4 81 d6 1f 49 42 2b 75 89 a7 9f 84 7f 1f c3 8f 70 b6 7e 06 5e 8b c9 8a 75 bb 53 fb a7 3d 65 37 3e 6b 80 ac 23 1d b7 66 18 2a 16 34 58 d1 f2 ba 95 9f 5e 09 90 5c 5e 1a b5 8a de b1 29 c0 0b 21 a4 55 57 0b 1e ea 47 aa 15 c3 43 fa 76 29 86 6c 52 a2 85 b7 56 1e
privateExponent
3.2.4.3 Simple Key BLOBs Simple key BLOBs (type SIMPLEBLOB) are used to store and transport session keys. These are always encrypted with a key exchange public key. They have the following format:
BLOBHEADER blobheader; ALG_ID algid; BYTE encryptedkey[rsapubkey.bitlen/8];
The algorithm identifier that immediately follows the BLOBHEADER structure specifies the encryption algorithm that was used to encrypt the session key data. This typically has a value of
USER'S GUIDE
CALG_RSA_KEYX, indicating that the session key data was encrypted with a key exchange public key, using the RSA Public-Key algorithm. The encrypted session key data is in the form of a PKCS #1, type 2 encryption block. For details on this data format, see The Public-Key Cryptography Standards (PKCS), published by RSA Data Security, Inc. This data is always the same size as the public key's modulus. For example, public keys generated by the Microsoft Base Cryptographic Provider are always 512 bits (64 bytes) in length, so the encrypted session key data is also always 64 bytes.
3.3 CSP Constants

Cryptographic service providers use the following constants defined in Wincrypt.h: 3.3.1 Protocol Flags Flag constant CRYPT_FLAG_PCT1 CRYPT_FLAG_SSL2 CRYPT_FLAG_SSL3 CRYPT_FLAG_TLS1 Value 0x0001 0x0002 0x0004 0x0008
DSSSCT
File : dcsp
Ref : DSPUSG990001
Revision : 1.0
116 / 116

DCSP

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DCSP

Uploaded by

Copyright:

Available Formats

DEKART CRYPTO SERVICE PROVIDER

DEKART Crypto Service Provider

DEKART CRYPTO SERVICE PROVIDER

new revision index

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

1 About Cryptographic Service Providers

1.1 Architecture of a Cryptographic Service Provider (CSP)

DEKART CRYPTO SERVICE PROVIDER

CPAcquireContext CPCreateHash CPDecrypt CPDeriveKey CPDestroyHash CPDestroyKey CPEncrypt CPExportKey

DEKART CRYPTO SERVICE PROVIDER

Persistent Data Objects

DEKART CRYPTO SERVICE PROVIDER

Volatile Data Objects

DEKART CRYPTO SERVICE PROVIDER

1.2 Writing a CSP

Creating the CSP DLL

DEKART CRYPTO SERVICE PROVIDER

Writing the CSP Setup Program

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

Test Signing the CSP

DEKART CRYPTO SERVICE PROVIDER

Testing the CSP

Getting the CSP Signed

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

Public/private key pair types

Key BLOB types

Hash object parameters

DEKART CRYPTO SERVICE PROVIDER

1.3 CSP Interoperability

Key BLOB formats

Deriving session keys

Hashing session keys

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

Key BLOB Formats

Description Structure used at the beginning of all key BLOB structures.

DEKART CRYPTO SERVICE PROVIDER

Public Key BLOBs Private Key BLOBs Simple Key BLOBs

Block type Reserved

DEKART CRYPTO SERVICE PROVIDER e4 1d 44 5c 33 e5 2f 4f 58 01 95 16 36 f7 86 65 68 6c 2a 28 79 55 02 00

Deriving Session Keys

DEKART CRYPTO SERVICE PROVIDER

generates the following ciphertext data:

DEKART CRYPTO SERVICE PROVIDER

Hashing Session Keys

For an SHA hash

Digital Signature Mechanics

DEKART CRYPTO SERVICE PROVIDER

Algorithm specifier Reserved Padding Block type

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

2 Using a Cryptographic Service Provider

Retrieving Data of Unknown Length

DEKART CRYPTO SERVICE PROVIDER

DEKART CRYPTO SERVICE PROVIDER

Enumerating Supported Protocols

Algorithm identifier CALG_RSA _KEYX CALG_MD5 CALG_SHA CALG_RC4