Dcsp

DEKART CRYPTO SERVICE PROVIDER USER'S GUIDE

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.

DEKART Crypto Service

Provider

User’s Guide

APPLICATION DATE 16/10/1999

Note : Restricted distribution

DOCUMENT WRITTEN BY

Department Name Function Date Visa SCT

Kutsy Alexander

Petrova Olga 16/10/1999

DOCUMENT APPROVED BY

Department Name Function Date Visa SCT




MODIFICATION SHEET

Date of

update modified

part

new revision index

modifications (Type and description)

16/10/99 - 1.0 First release




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




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.




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).




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:

• CPAcquireContext

• CPCreateHash

• CPDecrypt

• CPDeriveKey

• CPDestroyHash

• CPDestroyKey

• CPEncrypt

• CPExportKey




• 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.




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.




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.




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.




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 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




Microsoft Cryptography Provider Type<CSP type> >Name:REG_SZ:<CSP name>


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




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 [email protected].

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 be found at 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.

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




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 [email protected].

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.




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 Microsoft’s 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 Comment

Provider types 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

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.

Algorithm identifiers

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.

Public/private key pair types While new key pair types can be defined as needed, currently only signature and key exchange key pairs are used.

Key BLOB types 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 Key parameters are sent and retrieved using CPSetKeyParamand CPGetKeyParam. New key parameters could enable support for many different types of keys.

Hash object parameters

Hash object parameters are sent and retrieved using CPSetHashParam and CPGetHashParam. New hash object parameters could enable support for many different types of hashes.

Flag values Most CryptoAPI/CryptoSPI functions have a dwFlags parameter. New dwFlags values could modify the behavior of functions as




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 Description

Supported algorithm The minimum set of algorithms that must be supported by all PROV_RSA_FULL and PROV_RSA_SIG providers.

Key BLOB formats

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.

Deriving session keys

The procedure for deriving session keys from hash values so that given the same base data, every CSP generates exactly the same session key.

Hashing session keys The procedure for hashing session keys so that




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 Microsoft’s 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.




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 Microsoft’s 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 Description

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




Public Key BLOBs BLOB structure that contains a public key.

Private Key BLOBs BLOB structure that contains a private key in encrypted form.

Simple Key BLOBs 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

Key material 1 to 5

Session key material. The size of this field varies depending on the size of the session key.

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 big-endian format.

Reserved 6 Zero value.

Padding 7 to 56

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.

Block type 57 The PKCS block type (0x02).


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 06 4f 74 00 c9 db b1 74 b0 de 8e d4 aa c5 99 8a 4d 19 4f 0f ed 24 b0 2e 93 fe e9 f4 d4 93 dc ac 9e 9f 3a 62 be f1




e4 1d 44 5c 33 e5 2f 4f 58 01 95 16 36 f7 86 65 68 6c 2a 28 79 55 02 00 Next, the block is encrypted with the appropriate public key. After this is done, the encrypted block might look like this: e3 c1 78 62 c4 1f 51 4f e9 50 89 fd 0d 58 bd 9d 74 c7 54 19 bd 97 3b a0 f0 6c ee 86 05 74 16 62 27 a5 99 63 c4 6f 95 ed 3e 93 ba 9a ea 36 cc 96 92 e8 aa 15 2c 50 a1 3c 38 d3 1f 08 e2 82 cd 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 02 00 00 01 68 00 00 00 a4 00 00 e3 c1 78 62 c4 1f 51 4f e9 50 89 fd 0d 58 bd 9d 74 c7 54 19 bd 97 3b a0 f0 6c ee 86 05 74 16 62 27 a5 99 63 c4 6f 95 ed 3e 93 ba 9a ea 36 cc 96 92 e8 aa 15 2c 50 a1 3c d3 1f 08 e2 82 cd 90 2b Note The encrypted block begins at byte 13.

The BLOBHEADER structure and the algorithm identifier have been assigned the following values: blobheader.bType = SIMPLEBLOB; // 0x01 in byte number 1 blobheader.bVersion = CUR_BLOB_VERSION; // 0x02 in byte number 2 blobheader.Reserved = 0; // 0x0000 in bytes 3 and 4 blobheader.aiKeyAlg = CALG_RC4; // 0x00006801 in reverse // order in bytes 5, 6, 7, // and 8 algid = CALG_RSA_KEYX; // 0x0000a400 in reverse // order in bytes 9, 10, 11, // and 12 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.




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 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f generates the following ciphertext data: 26 59 de 24 44 fa 36 9c 11 0c bb 9d b6 a2 bd 24 04 2e e3 ba 72 76 f3 27 8d d5 b4 2f 56 cf f8 c9 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 f4 5d e2 cc 3b 87 1b 95 bc fc 39 fb 86 d3 05 da a2 91 fb 80 f1 2a 22 c3 b9 ec 91 dd 9f af 50




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 the hash object by using CryptHashData,CryptHashSessionKey, or both.

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.




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 00 65 00 73 00 74 00 20 00 53 00 69 00 67 00. 6e 00 61 00 74 00 75 00 18 72 00 65 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

To be signed 1 to 16

Hash of data to be signed. The size of this field varies depending on the hash algorithm used.

The bytes in the hash value 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 big-endian format.

Algorithm specifier 17 to 34

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.


Padding 36 to 62 Padding data (0xff's). The size of this field is adjusted as necessary so that the signature block's overall length is correct.

Block type 63 The PKCS block type (0x01).





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 5c ce fa 60 d4 78 38 62 bb f1 c9 c2 df 2b a8 10 04 00 05 05 02 0d f7 86 48 86 2a 08 06 0c 30 20 30 00 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff 01 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 f6 46 3a 97 2e 83 38 09 57 43 cb ca 41 59 0d 03 35 d6 e4 36 6f 2c fc 63 43 95 c4 fd e2 c4 ed 06 da 9a 21 98 fc 0a 6e 3f 1c ad 3a db 7c 83 2f 14 d0 58 80 02 df dc 96 70 09 00 e3 5b bd 2b 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 Encoding

MD2 10 04 00 05 02 02 0d f7 86 48 86 2a 08 06 0c 30 20 30

MD4 10 04 00 05 04 02 0d f7 86 48 86 2a 08 06 0c 300 20 30

MD5 10 04 00 05 05 02 0d f7 86 48 86 2a 08 06 0c 30 20 30

SHA 14 04 00 05 1a 02 03 0e 2b 05 06 09 30 21 30




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).




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, // in DWORD dwPropId, // in BYTE *pbData, // out DWORD *pcbData // 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.




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 (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING) 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. //--------------------------------------------------------------------




// Malloc memory for the size of the message. 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); }




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; // Structure to hold information on // a supported algorithm DWORD dFlag = CRYPT_FIRST; // Flag indicating that the first // supported algorithm is to be // enumerated. Changed to 0 after the // first call to the function. cbData = sizeof(PROV_ENUMALGS_EX); 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 Minimum Key Length

Maximum Key Length Protocols Algorithm

Name

CALG_RSA _KEYX 512 2048 0x0007 "RSA_KEYX"

CALG_MD5 128 128 0x0007 "MD5"

CALG_SHA 160 160 0x0005 "SHA"

CALG_RC4 40 128 0x0007 "RC4"




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 Diffie-Hellman 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 Diffie-Hellman 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




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 Diffie-Hellman/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 Diffie-Hellman 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 hProv = <protocol engine's key container>;HCRYPTKEY hPublicKey = <server's public key>;HCRYPTKEY hMasterKey; // handle for master key to be created. ALG_ID Algid; DWORD dwGenFlags =CRYPT_EXPORTABLE;




DWORD dwExportFlags =0; BYTE rgbBlob[<max BLOB size>]; DWORD cbBlob; //-------------------------------------------------------------------- // 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;


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,




&cbBlob);

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); //--------------------------------------------------------------------




// Create the client private DH key CryptSetKeyParam( hClientDHKey, KP_X, NULL, 0); //-------------------------------------------------------------------- // Build PUBLICKEYBLOB around the server's public key {

BLOBHEADER *pBlobHeader = (BLOBHEADER *)rgbServerBlob; DHPUBKEY *pDHPubKey = (DHPUBKEY *)(pBlobHeader + 1); BYTE *pData = (BYTE *)(pDHPubKey + 1);

pBlobHeader->bType = PUBLICKEYBLOB; pBlobHeader->bVersion = CUR_BLOB_VERSION; pBlobHeader->reserved = 0; pBlobHeader->aiKeyAlg = 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>){


break;


break; }

//-------------------------------------------------------------------- // Convert the agreed key to the appropriate master key




CryptSetKeyParam( hMasterKey, KP_ALGID, (BYTE*)&Algid, 0); //-------------------------------------------------------------------- // 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 hProv = <server's key container>;PBYTE pbKeyExchange = <pointer to RSA envelope>;DWORD dwKeyExchange = <size of RSA envelope>;HCRYPTKEY hPublicKey; HCRYPTKEY hMasterKey; ALG_ID Algid; DWORD dwFlags =0 ; BYTE rgbBlob[<max BLOB size>]; DWORD cbBlob; //-------------------------------------------------------------------- // Select the master key type. switch(<protocol being used>){

case <PCT 1.0>:Algid = CALG_PCT1_MASTER;

break;


if(<we support SSL3>)dwFlags = CRYPT_SSL2_FALLBACK;

break;





break;


break; }

//-------------------------------------------------------------------- // 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 = SIMPLEBLOB; pBlobHeader->bVersion = CUR_BLOB_VERSION; pBlobHeader->reserved = 0; pBlobHeader->aiKeyAlg = 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.




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 = PUBLICKEYBLOB; pBlobHeader->bVersion = CUR_BLOB_VERSION; pBlobHeader->reserved = 0; pBlobHeader->aiKeyAlg = 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>){


break;


break; }




//-------------------------------------------------------------------- // 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 0x00000000 #define SCHANNEL_ENC_KEY 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);




//-------------------------------------------------------------------- // 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; //--------------------------------------------------------------------




// Finish creating the master_secret. switch(<protocol being used>){

case <PCT 1.0>:

//------------------------------------------------------------ // 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;




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, (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); }




//------------------------------------------------------------ // 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);




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,




HP_HASHVAL, rgbFinishPRF, &cbFinishPRF, 0); CryptDestroyHash(hFinishHash);

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




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);




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 Description

CPAcquireContext Acquires a handle to a particular key container within the CSP.

CPGetProvParam Retrieves attributes of the CSP.

CPReleaseContext Releases the handle acquired by CPAcquireContext.

CPSetProvParam 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, // out CHAR *pszContainer, // in, out DWORD dwFlags, // in PVTableProvStruc pVTable // 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.




dwFlags

Can be zero or one of the following flags.

Flag value Meaning

CRYPT_VERIFYCONTEXT

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, 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.

CRYPT_NEWKEYSET

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_MACHINE_KEYSET

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 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.




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.

CRYPT_DELETEKEYSET

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.

CRYPT_SILENT

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 CPGenKeyusing 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.

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 Description

NTE_BAD_FLAGS The dwFlags parameter has an illegal value.

NTE_BAD_KEYSET The key container could not be opened and might not exist.




NTE_BAD_KEYSET_PARAM The pszContainer parameter is set to an illegal value.

NTE_BAD_SIGNATUREThe digital signature of an auxiliary DLL did not verify correctly. Either the DLL or the digital signature has been tampered with.

NTE_EXISTS The dwFlags parameter is CRYPT_NEWKEYSET, but the key container already exists.

NTE_KEYSET_ENTRY_BAD The pszContainer key container was found but is corrupt.

NTE_KEYSET_NOT_DEF The key container specified by pszContainer does not exist.

NTE_NO_MEMORY The CSP ran out of memory during the operation.

NTE_PROVIDER_DLL_FAIL An auxiliary DLL file could not be loaded and might not exist. If it exists, the file is not a valid DLL.

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, // in DWORD dwParam, // in BYTE *pbData, // out DWORD *pdwDataLen, // in, out DWORD dwFlags // in );




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

PP_CONTAINER

The name of the current key container as a NULL-terminated CHAR string. The returned string is identical to the one passed in the pszContainer parameter of the CryptAcquireContext function to specify the keycontainer to use. pszContainer can be read to determine the name of the default key container.

PP_ENUMALGS

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 CPGetProvParamfunction 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.

PP_ENUMALGS_EX

Information about an algorithm supported by the CSP. The structure returned contains more information about thealgorithm 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 bespecified 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 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.

PP_ENUMCONTAINERS

The name of one of the key containers maintained by theCSP 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.

PP_IMPTYPE

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.

PP_NAME

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 CryptAcquireContextfunction to specify that the current CSP be used.

PP_VERSION

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.

PP_SIG_KEYSIZE_INC The number of bits for the increment length of




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.

PP_KEYX_KEYSIZE_INC

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.

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.

PP_KEYSET_SEC_ DESCR

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.

PP_UNIQUE_ CONTAINER

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 CryptAcquireContextfunction must work with this container name.

PP_PROVTYPE A DWORD value indicating the provider type of the CSP.

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




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 Meaning

OWNER_SECURITY_INFORMATION Indicates the owner identifier of the object being referenced.

GROUP_SECURITY_INFORMATION Indicates the primary group identifier of




the object being referenced.

DACL_SECURITY_INFORMATION Indicates the discretionary ACL of the object being referenced.

SACL_SECURITY_INFORMATION Indicates the system ACL of the object being referenced.

Return Values



Error Description

ERROR_MORE_DATA The pbData buffer is not large enough to hold the requested data.

ERROR_NO_MORE_ITEMS

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.

NTE_BAD_FLAGS The value of the dwFlags parameter is invalid.

NTE_BAD_TYPE The dwParam parameter specifies an unknown parameter number.

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.




BOOL CPReleaseContext( HCRYPTPROV hProv, // in DWORD dwFlags // in ); 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



Error Description



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




3.1.1.4 CPSetProvParam

The CPSetProvParam function customizes the operations of a cryptographic service provider (CSP). BOOL CPSetProvParam( HCRYPTPROV hProv, // in DWORD dwParam, // in BYTE *pbData, // in DWORD dwFlags // 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 Meaning

OWNER_SECURITY_INFORMATION Indicates the owner identifier of the object being referenced.




GROUP_SECURITY_INFORMATION Indicates the primary group identifier of the object being referenced.

DACL_SECURITY_INFORMATION Indicates the discretionary ACL of the object being referenced.

SACL_SECURITY_INFORMATION Indicates the system ACL of the object being referenced.

Return Values



Error Description




NTE_FAIL 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




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.


CPDeriveKey Creates a key derived from a password.

CPDestroyKey Destroys a key.

CPDuplicateKey Makes an exact copy of a key, including the state of the key.

CPExportKey Transfers a key from the CSP into a key BLOB in the application's memory space.

CPGenKey Creates a random key.

CPGenRandom Generates random data.

CPGetKeyParam Retrieves a key's parameters.

CPGetUserKey Gets a handle to the key exchange or signature key.

CPImportKey Transfers a key from a key BLOB to a CSP.

CPSetKeyParam 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, // in ALG_ID Algid, // in HCRYPTHASH hBaseData, // in DWORD dwFlags, // in HCRYPTKEY *phKey // out ); Parameters




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

CALG_SCHANNEL_ ENC_KEY

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.

CALG_SCHANNEL_ MAC_KEY

Generates a MAC key. The key generation algorithm has previously been specified with a call to CPSetKeyParam.

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

CRYPT_EXPORTABLE

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.

CRYPT_CREATE_SALT 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.




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.

CRYPT_USER_ PROTECTED

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.

CRYPT_UPDATE_KEY

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.

CRYPT_SERVER 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.

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






Error Description

NTE_BAD_ALGID The Algid parameter specifies an algorithm that this CSP does not support.

NTE_BAD_FLAGS The dwFlags parameter contains an invalid value.

NTE_BAD_HASH The hBaseData parameter does not contain a valid handle to a hash object.

NTE_BAD_HASH_STATE An attempt was made to add data to a hash object that is already marked as finished.

NTE_FAIL The function failed in an unexpected way.

NTE_BAD_UID The hProv parameter does not contain a valid context handle.

NTE_SILENT_CONTEXT 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




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, // in HCRYPTKEY hKey // 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



Error Description

NTE_BAD_KEY The hKey parameter does not contain a valid handle to a key.


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





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, // in HCRYPTKEY hKey, // in DWORD *pdwReserved, // in DWORD dwFlags, // in HCRYPTKEY *phKey // out ); Parameters

hUID


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



Error Description

ERROR_CALL_ Because this is a new function, existing CSPs might not




NOT_IMPLEMENTED implement it. This error is returned if the CSP does not support this function.

ERROR_INVALID_ PARAMETER

One of the parameters contains an invalid value. This is most often an illegal pointer.

NTE_BAD_KEY 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, // in HCRYPTKEY hKey, // in HCRYPTKEY hPubKey, // in DWORD dwBlobType, // in DWORD dwFlags, // in BYTE *pbData, // out DWORD *pdwDataLen // in, out );

Parameters

hProv





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 Use

SIMPLEBLOB To transport session keys.

PUBLICKEYBLOB To transport public keys.

PRIVATEKEYBLOB To transport public/private key pairs.

OPAQUEKEYBLOB 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.

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 Effect

CRYPT_DESTROYKEY Destroys the original key in the OPAQUEKEYBLOB.

CRYPT_SSL2_ FALLBACK

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.




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



Error Description



NTE_BAD_KEY One or both of the keys specified by hKey and hPubKey are invalid.

NTE_BAD_KEY_STATEThe key cannot be exported because the CRYPT_EXPORTABLE flag was not specified when the key was created.

NTE_BAD_PUBLIC_KEYThe key BLOB type specified by dwBlobType is PUBLICKEYBLOB, but hPubKey does not contain a public key handle.

NTE_BAD_TYPE The dwBlobType parameter specifies an unknown BLOB type.




NTE_BAD_UID The CSP context that was specified when the hKey key was created cannot now be found.

NTE_NO_KEY 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, // in ALG_ID Algid, // in DWORD dwFlags, // in HCRYPTKEY *phKey // out ); Parameters

hProv


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:




• 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:

• AT_KEYEXCHANGE

• AT_SIGNATURE

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

CRYPT_EXPORTABLE

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.

CRYPT_CREATE_SALT

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.

CRYPT_NO_SALT Specifies that a no salt value is assigned for 40-bit symmetric keys. For more information, see New Salt Value Functionality.

CRYPT_USER_ PROTECTED

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_CONTEXTThe 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




ignored.

CRYPT_PREGEN Specifies an initial Diffie-Hellman or DSS key generation. Currently only useful with Diffie-Hellman/DSS CSPs.

phKey

Address to which the function copies a handle to the newly-generated key.

Return Values



Error Description



NTE_FAIL The function failed in some unexpected way.


NTE_PERM An attempt was made to create a key pair when CRYPT_VERIFYCONTEXT was specified.

NTE_SILENT_CONTEXT

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




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 , // in DWORD dwLen , // in BYTE * pbBuffer // in, out );

Parameters

hProv


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



Error Description


NTE_FAIL The function failed in some unexpected manner.

Remarks




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 Cryptology—EUROCRYPT '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 pseudo-random bits," SIAM Journal on Computing 13(4)(November 1984); 850-864.




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 , // in HCRYPTKEY hKey , // in DWORD dwParam , // in BYTE * pbData , // out DWORD * pdwDataLen , // in, out DWORD dwFlags // in ); Parameters

hProv


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 Key types Copied to pdData Returned

pdwDataLen

KP_ALGID all The algorithm identifier (ALG_ID) used by this key object. 4

KP_BLOCKLEN all If hKey is a session key, a DWORD value indicating the block length in bits.

4




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 Remarks.

4

KP_SALT all session keys

A BYTE array containing the key's current salt value. This parameter does not apply to public/private key pairs. If hKey references a public/private key pair, the NTE_BAD_TYPE error code is returned.

Length of the BYTE array

KP_ PERMISSIONS all

A DWORD value indicating the permission to be associated with the key. See Remarks for a table of permission flags.

4

KP_IV block cipher keys

A BYTE array containing the key's current initialization vector (IV).

Length of the BYTE array

KP_PADDING block cipher keys

A DWORD value indicating the padding method used. Currently, PKCS5_Padding is defined.

4

KP_MODE block cipher keys

A DWORD value indicating the cipher mode used. See the table in Remarks for possible values.

4

KP_MODE_BITS block cipher keys

A DWORD value indicating the feedback width in bits. This is used only with OFB and CFB cipher modes.

4

KP_EFFECTIVE_ KEYLEN RC2 A DWORD value indicating the

effective key length of an RC2 key. 4




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.


dwFlags


Return Values



Error Description


NTE_BAD_FLAGS The dwFlags parameter is non-zero.

NTE_BAD_KEY or NTE_NO_KEY The key specified by the hKey parameter is invalid.





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 Description Value

CRYPT_ENCRYPT Allows encryption 0x0001

CRYPT_DECRYPT Allows decryption 0x0002

CRYPT_EXPORT Allows key to be exported 0x0004

CRYPT_READ Allows parameters to be read 0x0008

CRYPT_WRITE Allows parameters to be set 0x0010

CRYPT_MAC Allows MACs to be used with key 0x0020

The following table lists the cipher modes that are currently defined.

Cipher mode Description Value

CRYPT_MODE_ECB Electronic codebook 2

CRYPT_MODE_CBC Cipher block chaining 1

CRYPT_MODE_OFB Output feedback mode 3

CRYPT_MODE_CFB Cipher feedback mode 4

Requirements





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 , // in DWORD dwKeySpec , // in HCRYPTKEY * phUserKey // 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 Descriptipn

AT_KEYEXCHANGE Key used to encrypt and exchange session keys.

AT_SIGNATURE Keys used to create and verify digital signatues.

phUserKey

Address to which the function copies the handle of the retrieved key. This pointer must not be NULL.

Return Values



Error Description

NTE_BAD_KEY The key specified by the hKey parameter is invalid.





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 , // in CONST BYTE * pbData , // in DWORD dwDataLen , // in HCRYPTKEY hPubKey , // in DWORD dwFlags , // in HCRYPTKEY * phKey // 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




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

CRYPT_EXPORTABLE

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.

CRYPT_NO_SALT A no-salt value is specified for a 40-bit symmetric key. For more information, see New Salt Value Functionality.

phKey

Address to which the function copies a handle to the key that was imported.

Return Values



Error Description

NTE_BAD_ALGIDThe simple key BLOB being imported is not encrypted with the expected key exchange algorithm. The most likely cause of this error is incompatible CSPs.

NTE_BAD_DATA The algorithm of the public key being imported is not supported by this CSP.





NTE_BAD_TYPE The key BLOB type is not supported by this CSP and is possibly invalid.


NTE_BAD_VER 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 , // in HCRYPTKEY hKey , // in DWORD dwParam , // in BYTE * pbData , // in DWORD dwFlags // in );

Parameters

hProv


hKey

Handle to the target key on which to set parameters.

dwParam

The following table list currently defined dwParam values.




Value Contents of the pbData Buffer

KP_SALT A BYTE array containing the key's current salt value.

KP_SALT_EX

A BYTE array containing the key's current salt value.

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.

KP_ PERMISSIONS

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.

KP_IV A BYTE array containing the key's current initialization Vector (IV).

KP_PADDING 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.

KP_MODE A DWORD indicating the cipher mode.

See the Remarks section for a table of possible cipher modes.

KP_MODE_BITS A DWORD indicating the feedback width, in bits. This parameter only applies when the OFB or CFB cipher modes are used.

KP_EFFECTIVE_ KEYLEN

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.

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


Return Values






Error Description

NTE_BAD_FLAGS The dwFlags parameter is non-zero or the pbData buffer contains an invalid value.

NTE_BAD_TYPE The dwParam parameter specifies an unknown parameter.


NTE_FAIL The function failed in some unexpected manner.

Remarks

The following table lists the defined permission flags:

Permission flag Description

CRYPT_ENCRYPT Allows encryption

CRYPT_DECRYPT Allows decryption

CRYPT_EXPORT Allows key to be exported

CRYPT_READ Allows parameters to be read

CRYPT_WRITE Allows parameters to be set

CRYPT_MAC Allows MACs to be used with key

The following table lists the defined cipher modes:

Cipher mode Description

CRYPT_MODE_ECB Electronic codebook

CRYPT_MODE_CBC Cipher block chaining

CRYPT_MODE_OFB Output feedback mode

CRYPT_MODE_CFB 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).




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.


CPDecrypt Decrypts a section of ciphertext using the specified encryption key.

CPEncrypt 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 , // in HCRYPTKEY hKey , // in HCRYPTHASH hHash , // in BOOL Final , // in DWORD dwFlags , // in BYTE * pbData , // in, out DWORD * pdwDataLen // in, out );

Parameters

hProv


hKey

Handle to the session key for the decryption. This key specifies the decryption 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 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


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



Error Description

NTE_BAD_ALGID The hKey session key specifies an algorithm that this CSP does not support.

NTE_BAD_DATA

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_HASH The hHash parameter contains an invalid handle.

NTE_BAD_KEY The hKey parameter does not contain a valid handle to a session key.

NTE_BAD_LEN The size of the output buffer is too small to hold the generated plaintext.


NTE_DOUBLE_ENCRYPT The application attempted to decrypt the same data twice.


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




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 , // in HCRYPTKEY hKey , // in HCRYPTHASH hHash , // in BOOL Final , // in DWORD dwFlags , // in BYTE * pbData , // in, out DWORD * pdwDataLen , // in, out DWORD dwBufLen // in ); Parameters

hProv


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


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




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



Error Description

NTE_BAD_ALGID The hKey session key specifies an algorithm that this CSP does not support.

NTE_BAD_DATA

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.


NTE_BAD_HASH The hHash parameter contains an invalid handle.

NTE_BAD_HASH_STATE An attempt was made to add data to a hash object that is already marked "finished."

NTE_BAD_KEY The hKey parameter does not contain a valid handle to a key.

NTE_BAD_LEN The size of the output buffer is too small to hold the generated ciphertext.


NTE_DOUBLE_ENCRYPT The application attempted to encrypt the same data twice.






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.


CPCreateHash Creates a hash object and returns a handle to it.

CPDestroyHash Destroys a hash object.

CPDuplicateHash Makes an exact copy of a hash object and the state the hash is in.

CPGetHashParam Retrieves a hash object parameter.

CPHashData Hashes a block of data, adding it to the specified hash object.

CPHashSessionKey Hashes a session key, adding it to the specified hash object.

CPSetHashParam Sets a hash object parameter.

CPSignHash Signs the specified hash object.

CPVerifySignature Verifies a digital signature.




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 , // in ALG_ID Algid , // in HCRYPTKEY hKey , // in DWORD dwFlags , // in HCRYPTHASH * phHash // out ); Parameters

hProv


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


phHash

Address to which the function copies a handle to the new hash object.

Return Values



Error Description






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.


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


hHash

Handle to the hash object to be destroyed.

Return Values






Error Description

NTE_BAD_ALGID The hHash handle specifies an algorithm that this CSP does not support.

NTE_BAD_HASH The hash object specified by the hHash parameter is invalid.

NTE_BAD_UID 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 , // in HCRYPTHASH hHash , // in DWORD * pdwReserved , // in DWORD dwFlags , // in HCRYPTHASH * phHash // out );

Parameters

hUID


hHash

The handle to the hash 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.

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



Error Description

ERROR_CALL_ NOT_IMPLEMENTED

This is a new function and existing CSPs might not implement it. This error is returned if the CSP does not support this function.

ERROR_INVALID_ PARAMETER

One of the parameters contains an invalid value. This is most often an illegal pointer.

NTE_BAD_HASH 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





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 , // in HCRYPTHASH hHash , // in DWORD dwParam , // in BYTE * pbData , // out DWORD * pdwDataLen , // in, out DWORD dwFlags // in ); Parameters

hProv


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 Return contents of the pbData buffer

HP_ALGID 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.

HP_HASHSIZE 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_HASHVALUE

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.

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.


dwFlags


Return Values






Error Description





NTE_BAD_UID 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 , // in HCRYPTHASH hHash , // in CONST BYTE * pbData , // in DWORD dwDataLen , // in DWORD dwFlags // in );

Parameters

hProv


hHash




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



Error Description

NTE_BAD_ALGID The hHash handle specifies an algorithm that this CSP does not support.



NTE_BAD_HASH_STATE An attempt was made to add data to a hash object that is already marked as "finished."

NTE_BAD_KEYA 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.

NTE_BAD_LEN The CRYPT_USERDATA flag is set, and the dwDataLen parameter has a non-zero value.







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, // in HCRYPTHASH hHash, // in HCRYPTKEY hKey, // in DWORD dwFlags // in );

Parameters

hProv


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




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



Error Description

NTE_BAD_ALGID The hHash handle specifies a hash algorithm that this function does not support.



NTE_BAD_HASH_STATE

An attempt was made to add data to a hash object that is already marked as "finished."

NTE_BAD_KEY

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.



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




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 , // in HCRYPTHASH hHash , // in DWORD dwParam , // in BYTE * pbData , // in DWORD dwFlags // in ); Parameters

hProv


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.




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


Return Values



Error Description

NTE_BAD_FLAGS The dwFlags parameter is non-zero or the pbData buffer contains an invalid value.


NTE_BAD_TYPE The dwParam parameter specifies an unknown parameter.



Requirements


See Also

CPCreateHash, CPGetHashParam, CPSignHash, CryptSetHashParam




3.1.4.8 CPSignHash

The CPSignHash function signs a hash object. BOOL CPSignHash( HCRYPTPROV hProv , // in HCRYPTHASH hHash , // in DWORD dwKeySpec , // in LPCWSTR sDescription , // in DWORD dwFlags , // in BYTE * pbSignature , // out DWORD * pdwSigLen // in, out );

Parameters

hProv


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 Meaning

AT_KEYEXCHANGE The key exchange public/private key pair is to be used.

AT_SIGNATURE The digital signature public/private key pair is to be used.

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.




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.


Return Values



Error Description


NTE_BAD_ALGID The hHash handle specifies a hash algorithm that this function does not support.




NTE_NO_KEY The private key specified by dwKeySpec does not exist.





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 , // in HCRYPTHASH hHash , // in CONST BYTE * pbSignature , // in DWORD dwSigLen , // in HCRYPTKEY hPubKey , // in LPCWSTR sDescription , // in DWORD dwFlags // in ); Parameters

hProv





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



Error Description






NTE_BAD_KEY The hPubKey parameter does not contain a handle to a valid public key.

NTE_BAD_SIGNATURE

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.



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




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.




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 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




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




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);




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




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





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.




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 Description

magic 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."

bitlen Number of bits in the modulus. In practice, this must always be a multiple of 8.

pubexp 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 06 02 00 00 00 a4 00 00 ........ 0x00000008 52 53 41 31 00 02 00 00 RSA1.... 0x00000010 01 00 01 00 e1 94 84 7a .......z 0x00000018 27 4c 7b da db c5 99 dd 'L{..... 0x00000020 ed 20 1a b8 66 44 21 dc . ..fD!. 0x00000028 10 e5 ee 48 62 39 ae 8f ...Hb9.. 0x00000030 cf 17 81 f0 37 8b b5 46 ....7..F 0x00000038 a9 65 b7 4e 75 83 84 4e .e.Nu..N 0x00000040 4f ce f1 f2 ad a0 b1 22 O......" 0x00000048 09 ec c2 30 96 f8 27 2b ...0..'+ 0x00000050 33 cf a4 be 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.




blobheader.bType = PUBLICKEYBLOB; // 0x06 blobheader.bVersion = CUR_BLOB_VERSION; // 0x02 blobheader.reserved = 0; // 0x0000 blobheader.aiKeyAlg = CALG_RSA_KEYX; // 0x0000a400 rsapubkey.magic = 0x31415352; // "RSA1" rsapubkey.bitlen = 512; // 0x00000200 rsapubkey.pubexp = 65537; // 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 Description

blobheader A BLOBHEADER structure as described in a previous section. The bType field must always have a value of PRIVATEKEYBLOB.

rsapubkey A RSAPUBKEY structure as described in Public Key BLOBs. The magic field must always have a value of 0x32415352 ("RSA2").

modulus The modulus. This has a value of "prime1 * prime2" and is often known as "n".

prime1 Prime number 1, often known as "p".

prime2 Prime number 2, often known as "q".

exponent1 Exponent 1. This has a numeric value of "d mod (p - 1)".

exponent2 Exponent 2. This has a numeric value of "d mod (q - 1)".




coefficient Coefficient. This has a numeric value of "(inverse of q) mod p".

privateExponent 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 07 02 00 00 00 a4 00 00 ........ 0x00000008 52 53 41 32 00 02 00 00 RSA2.... 0x00000010 01 00 01 00 6b df 51 ef ....k.Q. 0x00000018 db 6f 10 5c 32 bf 87 1c .o.\2... 0x00000020 d1 4c 24 7e e7 2a 14 10 .L$~.*.. 0x00000028 6d eb 2c d5 8c 0b 95 7b m.,....{ 0x00000030 c7 5d c6 87 12 ea a9 cd .]...... 0x00000038 57 7d 3e cb e9 6a 46 d0 W}>..jF. 0x00000040 e1 ae 2f 86 d9 50 f9 98 ../..P.. 0x00000048 71 dd 39 fc 0e 60 a9 d3 q.9..`.. 0x00000050 f2 38 bb 8d 5d 2c bc 1e .8..],.. 0x00000058 c3 38 fe 00 5e ca cf cd .8..^... 0x00000060 b4 13 89 16 d2 07 bc 9b ........ 0x00000068 e1 20 31 0b 81 28 17 0c . 1..(.. 0x00000070 c7 73 94 ee 67 be 7b 78 .s..g.{x 0x00000078 4e c7 91 73 a8 34 5a 24 N..s.4Z$ 0x00000080 9d 92 0d e8 91 61 24 dc .....a$. 0x00000088 b5 eb df 71 66 dc e1 77 ...qf..w 0x00000090 d4 78 14 98 79 44 b0 19 .x..yD.. 0x00000098 f6 f0 7d 63 cf 62 67 78 ..}c.bgx 0x000000a0 d0 7b 10 ae 6b db 40 b3 .{..k.@. 0x000000a8 b2 eb 2e 9f 31 34 2d cb ....14-. 0x000000b0 bf a2 6a a6 1f e9 03 42 ..j....B 0x000000b8 f2 63 9b b7 33 d0 fe 20 .c..3.. 0x000000c0 83 26 1f 56 a8 24 f5 6d .&.V.$.m 0x000000c8 19 51 a5 92 31 e4 2b bc .Q..1.+. 0x000000d0 11 c8 26 75 a0 51 e9 83 ..&u.Q.. 0x000000d8 ca ee 4b f0 59 eb a4 81 ..K.Y... 0x000000e0 d6 1f 49 42 2b 75 89 a7 ..IB+u.. 0x000000e8 9f 84 7f 1f c3 8f 70 b6 ......p. 0x000000f0 7e 06 5e 8b c9 53 65 80 ~.^..Se. 0x000000f8 b7 16 f2 5e 5e de 0b 57 ...^^..W 0x00000100 47 43 86 85 8a fb 37 ac GC....7. 0x00000108 66 34 ba 09 1a b1 21 0b f4....!. 0x00000110 aa fa 6c b7 75 a7 3e 23 ..l.u.># 0x00000118 18 58 95 90 b5 29 a4 1e .X...).. 0x00000120 15 76 52 56 bb 3d 6b 1d .vRV.=k. 0x00000128 2a d1 9f 5c 8a c0 55 ea *..\..U. 0x00000130 c3 29 a2 1e .).. Notice that the BLOBHEADER and RSAPUBKEY structures have been assigned the following values: blobheader.bType = PRIVATEKEYBLOB; // 0x07 blobheader.bVersion = CUR_BLOB_VERSION; // 0x02




blobheader.reserved = 0; // 0x0000 blobheader.aiKeyAlg = CALG_RSA_KEYX; // 0x0000a400 rsapubkey.magic = 0x32415352; // "RSA2" rsapubkey.bitlen = 512; // 0x00000200 rsapubkey.pubexp = 65537; // 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 Value

modulus 6b df 51 ef db 6f 10 5c 32 bf 87 1c d1 4c 24 7e e7 2a 14 10 6d eb 2c d5 8c 0b 95 7b c7 5d c6 87 12 ea a9 cd 57 7d 3e cb e9 6a 46 d0 e1 ae 2f 86 d9 50 f9 98 71 dd 39 fc 0e 60 a9 d3 f2 38 bb 8d

prime1 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

prime2 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

exponent1 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

exponent2 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

coefficient 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

privateExponent c9 53 65 80 b7 16 f2 5e 5e de 0b 57 47 43 86 85 8a fb 37 ac 66 34 ba 09 1a b1 21 0b aa fa 6c b7 75 a7 3e 23 18 58 95 90 b5 29 a4 1e 15 76 52 56 bb 3d 6b 1d 2a d1 9f 5c 8a c0 55 ea c3 29 a2 1e

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




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 Value

CRYPT_FLAG_PCT1 0x0001

CRYPT_FLAG_SSL2 0x0002

CRYPT_FLAG_SSL3 0x0004

CRYPT_FLAG_TLS1 0x0008

Dcsp

Documents

Transcript of Dcsp