Dcsp

DEKART CRYPTO SERVICE PROVIDER USER'S GUIDE

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 16/10/1999
Petrova Olga

DOCUMENT APPROVED BY

Department Name Function Date Visa
SCT

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.


MODIFICATION SHEET

Date new
of modified revision modifications
update part index (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:MyxRsabase.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
cspsign@microsoft.com.
Note that Microsoft can only distribute the CSPDK to legal residents of the U.S. and Canada.
Information on how to obtain the CSPDK can 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 cspsign@microsoft.com.
CSP Vendors can also consult
U.S. Commerce Department,
Bureau of Export Administration
Office of Exporter Services
for assistance in the classification and/or export licensing of CSPs for export from the U.S. The
US Commerce Department's export license process, encryption export controls, and points of
contact are described on their Web site at http://www.bxa.doc.gov/encstart.htm.



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

A provider type represents a particular family or type of
Provider types cryptographic services. New provider types can be defined, each
serving a particular niche.

Provider parameters are sent and received using
CPSetProvParam and CPGetProvParam, respectively. New
Provider parameters
provider parameters could allow a CSP to be configured in ways
not foreseen by the CryptoAPI designers.

The enumeration facilities of CPGetProvParam allow
applications to list algorithm identifiers dynamically. New
Algorithm identifiers
symmetric, public-key, and hash algorithms can be defined at
any time.

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

New key BLOB types could permit session keys, public keys,
Key BLOB types and public/private key pairs to be exchanged in a flexible manner
using the CPExportKey and CPImportKey functions.

Key parameters are sent and retrieved using CPSetKeyParam
Key parameters and CPGetKeyParam. New key parameters could enable
support for many different types of keys.

Hash object parameters are sent and retrieved using
CPSetHashParam and CPGetHashParam. New hash object
Hash object parameters
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

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

The standard encoding schemes for key BLOBs.
Using standard encoding schemes enables keys to
Key BLOB formats
be exchanged between CSPs even if the CSPs
come from different vendors.

The procedure for deriving session keys from
hash values so that given the same base data,
Deriving session keys
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.

The mechanics of digital signatures and signature
Digital signature mechanics 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

Session key material. The size of this field varies depending on the
size of the session key.
Key The bytes in the session key data are reversed before they are placed
1 to 5
material 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.

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
Padding 7 to 56
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

Hash of data to be signed. The size of this field varies depending on
the hash algorithm used.
To be The bytes in the hash value are reversed before they are placed in the
1 to 16
signed encryption block because the operating system formats data in little-
endian format, and the encryption block must be built in big-endian
format.

ASN.1 encoded hash algorithm specifier. The size of this field
Algorithm depends on the hash algorithm used. Note that this data is also
17 to 34
specifier reversed. For more information on ASN.1, see the PKCS
documentation.


Padding data (0xff's). The size of this field is adjusted as necessary so
Padding 36 to 62
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
10 04 00 05 02 02 0d f7
MD2 86 48 86 2a 08 06 0c 30
20 30

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

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

14 04 00 05 1a 02 03 0e
SHA 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,"%sn",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 %sn", 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.

Minimum Key Maximum Key Algorithm
Algorithm identifier Protocols
Length Length Name

CALG_RSA
512 2048 0x0007 "RSA_KEYX"
_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;

case <SSL 3.0>:
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:
//--------------------------------------------------------------------

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

//--------------------------------------------------------------------

{
case <SSL 3.0>:
break;

case <TLS 1.0>:
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:
//--------------------------------------------------------------------

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;

//--------------------------------------------------------------------

{
case <PCT 1.0>:
Algid = CALG_PCT1_MASTER;
break;

case <SSL 2.0>:
if(<we support SSL3>)
dwFlags = CRYPT_SSL2_FALLBACK;
break;



case <SSL 3.0>:
break;

case <TLS 1.0>:
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->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:
//--------------------------------------------------------------------



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

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

//--------------------------------------------------------------------

{
case <SSL 3.0>:
break;

case <TLS 1.0>:
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:
//--------------------------------------------------------------------

BOOL fClient = <TRUE if this is code for the client?>;
HCRYPTHASH hMasterHash;

//--------------------------------------------------------------------


// Finish creating the master_secret.

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

Dcsp

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (17)

Similaire à Dcsp

Similaire à Dcsp (20)

Plus de CompaniaDekartSRL

Plus de CompaniaDekartSRL (20)

Dcsp