DEKART CRYPTO SERVICE PROVIDER                                                      USERS GUIDE                           ...
DEKART CRYPTO SERVICE PROVIDER                                                           USERS GUIDE                      ...
DEKART CRYPTO SERVICE PROVIDER                                                                                   USERS GUI...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  Purpose  A Cryptographic Se...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  1 About Cryptographic Serv...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  The CSP writer must know th...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE     •    CPGenKey     •    C...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  The key pairs are stored in...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  The CRYPT_VERIFYCONTEXT fl...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  Custom CSPs may involve mo...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  The <CSP type> entry is in...
DEKART CRYPTO SERVICE PROVIDER                                                       USERS GUIDE  Microsoft  Cryptography ...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  name of the DLL file. The t...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  host systems and applicatio...
DEKART CRYPTO SERVICE PROVIDER                                                      USERS GUIDE  Microsoft will sign CSPs ...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE                             ...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE                             ...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  1.3.1.2 Symmetric Encrypti...
DEKART CRYPTO SERVICE PROVIDER                                                      USERS GUIDE   Public Key BLOBs        ...
DEKART CRYPTO SERVICE PROVIDER                                                       USERS GUIDE  e4 1d 44 5c 33 e5 2f 4f ...
DEKART CRYPTO SERVICE PROVIDER                                                       USERS GUIDE  For example, from a 160-...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  1.3.4   Hashing Session Key...
DEKART CRYPTO SERVICE PROVIDER                                                       USERS GUIDE       8. The signature bl...
DEKART CRYPTO SERVICE PROVIDER                                                       USERS GUIDE  Reserved                ...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  The encoded OID strings sh...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  2 Using a Cryptographic Ser...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE   If NULL is input for pbDat...
DEKART CRYPTO SERVICE PROVIDER                                                   USERS GUIDE  // Malloc memory for the siz...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  2.1.3   Enumerating Support...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  CALG_DES                   ...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  access to the matching pri...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  DWORD             dwExport...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE             &cbBlob);  2.2.3...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  // Create the client priva...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  CryptSetKeyParam(         ...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE         case <SSL 3.0>:    ...
DEKART CRYPTO SERVICE PROVIDER                                                     USERS GUIDE  HCRYPTPROV hProv      = <p...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  //-------------------------...
DEKART CRYPTO SERVICE PROVIDER                                                    USERS GUIDE  //-------------------------...
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Dcsp
Upcoming SlideShare
Loading in …5
×

Dcsp

841 views

Published on

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
841
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
13
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Dcsp

  1. 1. DEKART CRYPTO SERVICE PROVIDER USERS 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 SCTDSSSCT 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.
  2. 2. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE MODIFICATION SHEET Date new of modified revision modifications update part index (Type and description) 16/10/99 - 1.0 First releaseDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 2 / 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.
  3. 3. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Contents Purpose ................................................................................................................................................................. 4 Developer Audience .............................................................................................................................................. 4 1 ABOUT CRYPTOGRAPHIC SERVICE PROVIDERS................................................................................. 5 1.1 ARCHITECTURE OF A CRYPTOGRAPHIC SERVICE PROVIDER (CSP) ................................................................ 5 1.1.1 CSP Architectural Overview ................................................................................................................. 5 1.1.2 Entry Points........................................................................................................................................... 6 1.1.3 Persistent Data Objects......................................................................................................................... 7 1.1.4 Volatile Data Objects............................................................................................................................ 8 1.2 WRITING A CSP ............................................................................................................................................. 9 1.2.1 Creating the CSP DLL .......................................................................................................................... 9 1.2.2 Writing the CSP Setup Program ......................................................................................................... 10 1.2.3 Test Signing the CSP........................................................................................................................... 12 1.2.4 Testing the CSP ................................................................................................................................... 13 1.2.5 Getting the CSP Signed....................................................................................................................... 13 1.2.6 Extending CryptoAPI .......................................................................................................................... 15 1.3 CSP INTEROPERABILITY .............................................................................................................................. 16 1.3.1 Supported Algorithms.......................................................................................................................... 17 1.3.2 Key BLOB Formats ............................................................................................................................. 18 1.3.3 Deriving Session Keys......................................................................................................................... 21 1.3.4 Hashing Session Keys ......................................................................................................................... 22 1.3.5 Digital Signature Mechanics............................................................................................................... 22 2 USING A CRYPTOGRAPHIC SERVICE PROVIDER............................................................................... 26 2.1 USING CSPS: GENERAL PROCESSES............................................................................................................. 26 2.1.1 Example Program Limitations ............................................................................................................ 26 2.1.2 Retrieving Data of Unknown Length................................................................................................... 26 2.1.3 Enumerating Supported Protocols ...................................................................................................... 29 2.2 USING SCHANNEL CSPS .............................................................................................................................. 30 2.2.1 Public/Private Key Pair Usage ........................................................................................................... 30 2.2.2 SHA/MD5 RSA Signature Type ........................................................................................................... 31 2.2.3 Creating the Master Key ..................................................................................................................... 31 2.2.4 Deriving Bulk Encryption and MAC Keys .......................................................................................... 39 2.2.5 Finish Messages (TLS 1.0) .................................................................................................................. 43 2.2.6 Bulk Data Encryption.......................................................................................................................... 44 2.2.7 Crossing Process Boundaries ............................................................................................................. 44 2.2.8 Opaque BLOB Type ............................................................................................................................ 44 3 CRYPTOGRAPHIC SERVICE PROVIDER REFERENCE....................................................................... 46 3.1 CSP FUNCTIONS .......................................................................................................................................... 46 3.1.1 CSP Connection Functions ................................................................................................................. 46 3.1.2 Key Generation and Exchange Functions........................................................................................... 58 3.1.3 Data Encryption Functions ................................................................................................................. 82 3.1.4 Hashing and Digital Signature Functions........................................................................................... 87 3.1.5 CSP Auxiliary Functions................................................................................................................... 105 3.2 CSP STRUCTURES AND TYPES ................................................................................................................... 106 3.2.1 PROV_ENUMALGS.......................................................................................................................... 106 3.2.2 PROV_ENUMALGS_EX................................................................................................................... 107 3.2.3 VTableProvStruc............................................................................................................................... 108 3.2.4 BLOBHEADER ................................................................................................................................. 111 3.3 CSP CONSTANTS ....................................................................................................................................... 116 3.3.1 Protocol Flags................................................................................................................................... 116DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 3 / 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.
  4. 4. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Purpose A Cryptographic Service Provider (CSP) contains implementations of cryptographic standards and algorithms. Developer Audience This documentation is written for CSP developers. It defines the CSP interfaces, describes the procedures a CSP writer must use, and the requirements that a CSP writer must fulfill to create a custom CSP. While information in this documentation is primarily intended for a person writing a CSP, it can also be of interest to advanced application developers.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 4 / 116 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.
  5. 5. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 1 About Cryptographic Service Providers A Cryptographic Service Provider (CSP) contains implementations of cryptographic standards and algorithms. At a minimum, a CSP consists of a dynamic-link library (DLL) that implements the functions in CryptoSPI (a system program interface). Most CSPs contain the implementation of all of their own functions; however, some CSPs implement their functions mainly in a Microsoft® Win32®-based service program managed by the Win32 service control manager. Others implement functions in hardware, such as a smart card or secure coprocessor. If a CSP does not implement its own functions, the DLL acts as a pass-through layer, facilitating the communication between the operating system and the actual CSP implementation. This documentation is written for CSP developers. It defines the CSP interfaces, describes the procedures a CSP writer must use, and the requirements that a CSP writer must fulfill to create a custom CSP. While information in this documentation is primarily intended for a person writing a CSP, it can also be of interest to advanced cryptography application developers. This documentation maintains a focus on creating a CSP and assumes familiarity with Crypto API in the Microsoft Platform SDK. The following related subjects, which a CSP developer must be familiar with to implement a CSP, are not covered: • Cryptography • Cryptographic protocols and standards • Cryptographic application programming • Microsoft® Windows® programming 1.1 Architecture of a Cryptographic Service Provider (CSP) 1.1.1 CSP Architectural Overview Applications do not communicate directly with a CSP. Instead, applications call CryptoAPI functions exposed by the operating systems Advapi32.dll and Crypt32.dll files. The operating system filters these function calls and passes them on to the appropriate CSP functions through CryptoSPI (a system program interface).DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 5 / 116 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.
  6. 6. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE The CSP writer must know the nature, order, and meaning of parameters passed by the operating system to the CSP functions and must return the values as expected to the operating system. Applications use handles to refer to data objects within the CSP. Objects that are referenced by their handles include key containers, hash objects, session key objects, and public/private key pair objects. These handles are opaque from both sides; that is, the handle that the application uses to access a data object is not the same one that the CSP uses. For various reasons, the operating system layer always accesses data objects indirectly using handles. 1.1.2 Entry Points All custom CSPs must support all of the following DLL entry points: • CPAcquireContext • CPCreateHash • CPDecrypt • CPDeriveKey • CPDestroyHash • CPDestroyKey • CPEncrypt • CPExportKeyDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 6 / 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.
  7. 7. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE • CPGenKey • CPGenRandom • CPGetHashParam 7 • CPGetKeyParam • CPGetProvParam • CPGetUserKey • CPHashData • CPHashSessionKey • CPImportKey • CPReleaseContext • CPSetHashParam • CPSetKeyParam • CPSetProvParam • CPSignHash • CPVerifySignature All PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL CSPs must also support all of the following DLL entry points: These entry points are optional for other custom CSPs): • CPDuplicateHash • CPDuplicateKey These functions compose the CryptoSPI system program interface. Each function corresponds directly to a CryptoAPI cryptographic function. 1.1.3 Persistent Data Objects The CSP stores public/private key pairs from session to session in persistent memory. A CSP implemented completely in software can store these keys, in encrypted form, in the system registry. CSPs with a hardware component might store the key pairs in tamper-resistant hardware.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 7 / 116 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.
  8. 8. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE The key pairs are stored in logical data objects called key containers. The CSP maintains one key container for each user or client that uses that CSP. Each key container can store one key pair of each type that the CSP supports. For example, the Microsoft® Base Cryptographic Provider supports two key pair types: the key exchange key pair and the digital signature key pair. Several key containers can be open at any given time (either by a single application or multiple ones). Each call to a CryptoSPI function specifies the key container to be used with one of the parameters of the function. This is illustrated by the following drawing. Note In the CryptoSPI context, the HCRYPTPROV data type is a handle to a particular key container within the CSP. In the CryptoAPI context, the HCRYPTPROV data type is a handle for both a key container and the CSP to be used. 1.1.4 Volatile Data Objects A CSP maintains session key objects and hash objects in volatile memory. These objects are created using the CPGenKey and CPCreateHash functions, respectively. These objects are destroyed using CPDestroyKey and CPDestroyHash. They must be destroyed when their associated key container or user context is released by CPReleaseContext. The objects maintained in volatile memory are accessed using their handles as shown below.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 8 / 116 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.
  9. 9. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE The CRYPT_VERIFYCONTEXT flag can be passed as the dwFlags parameter to CPAcquireContext to enable that function to create volatile private keys. Volatile private keys are required for PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL CSPs. 1.2 Writing a CSP This section outlines the steps used to write, test, and implement a custom CSP. Before writing a CSP, a writer must accomplish two tasks: • Select the cryptographic algorithms and data formats to be included. • Obtain implementations for each algorithm and data format. 1.2.1 Creating the CSP DLL A CSP DLL is created like any other DLL. This procedure is explained in the MSDN documentation. For a CSP with hardware components, the DLL might involve writing a smart card device driver or the embedded code that runs on the card. For information on writing any needed device drivers, see the Microsoft Device Developer Kit (DDK). Every custom CSP DLL must expose all of the CryptoSPI functions listed in Entry Points. If a CSP does not actually support a particular function, a call to that function must at least return the E_NOTIMPL error code. A CSP that does not perform all of the cryptographic processes can be created; for example, a CSP specializing in signature verification that does not support data encryption functions.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 9 / 116 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.
  10. 10. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Custom CSPs may involve more than one DLL; however, this is discouraged because it can create run-time complications. For more information, see CPAcquireContex. Regardless of the number of DLLs used for a custom CSP, all of them must be signed by Microsoft to enable the CSP to be used with the released versions of Windows 2000, Windows NT, or Windows 95 and later. 1.2.2 Writing the CSP Setup Program Part of creating a CSP is providing for its installation. At a minimum, a CSP must include a setup program that: • Copies the CSP DLL to a directory pointed to by the PATH environment variable. • Creates the appropriate registry entries. 1.2.2.1 Registering the CSP A CSP is registered under the following registry key: HKEY_LOCAL_MACHINE SOFTWARE Microsoft Cryptography Defaults Provider The following registry entries under the above hKey register the CSP with the operating system. <CSP name> >Image Path:REG_SZ:<CSP DLL name> >Signature:REG_BINARY:<digital signature> >Type:REG_DWORD:<CSP type> The <CSP name> entry is the text name of the CSP. If the CSP has been signed by Microsoft Corporation, this name must exactly match the CSP name that was specified in the Export Compliance Certificate (ECC). The <CSP DLL name> (Image Path) entry is the name of the CSP DLL. If a fully qualified path, such as C: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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 10 / 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.
  11. 11. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025. 1.2.2.2 Setting the Machine Default CSP One machine default CSP can be specified for each CSP type. The machine default CSP is used if an application calls CryptAcquireContext with only a CSP type specified and no user default CSP registry entry exists. Unless there are important reasons for setting up a custom CSP as the machine default CSP, the normal default CSP should not be changed. If a custom CSP must be used, the setup program can install its CSP as the machine default. If the normal default is to be changed, the following registry entry sets the machine default CSP: HKEY_LOCAL_MACHINE SOFTWARE Microsoft Cryptography Defaults Provider Type Type <CSP type> >Name:REG_SZ:<CSP name> The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025. The <CSP Name> entry must be set to the textual name of the CSP. This must exactly match the <CSP Name> registry key discussed in Registering the CSP. 1.2.2.3 Setting the User Default CSP One user default CSP can be specified for each CSP type. The user default CSP is used when an application calls CryptAcquireContext with only a CSP type specified. Unless there are important reasons for setting up a custom CSP as the user default CSP, the normal default CSP should not be changed. If the user default CSP must be changed, user defaults are stored in the registrys 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 SoftwareDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 11 / 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.
  12. 12. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Microsoft Cryptography Provider Type<CSP type> >Name:REG_SZ:<CSP name> The <CSP type> entry is in decimal format and exactly 3 digits in length. For example, if the CSP is of type 25, the key name is Type 025. The <CSP name> entry must be set to the textual name of the CSP. This must exactly match the <CSP name> registry key discussed in Registering the CSP. 1.2.3 Test Signing the CSP A CSP DLL must be signed each time it is built. This includes each build of the CSP that is made for testing purposes. Prior to Windows 2000, the signature is placed appropriately in the registry. Windows 2000 introduces signing a CSP digitally in a resource in the CSP DLL. This eliminates problems with signatures in the registry getting out of synchronization with the CSP binaries on the system. Old signature checking in the registry is still supported in Windows 2000 so CSPs with signatures in that form continue to work. To support the same CSP binary on Windows 2000 computers and Windows NT 4.0 and Windows 95 and later computers, some CSPs may need to be signed both in the resource and in the registry using the old signature form. Windows 2000 continues to support CSPs verifying signatures on loaded DLLs using the FuncVerifyImage callback function from the VTableProvStuc structure passed to the CSP with CPAcquireContext. To use the callback in this way, the pointer to the signature, parameter 1, must be set to NULL. To support the new signature format, the CSP must provide a 144 byte binary resource numbered 0x29A (decimal 666). The signature is placed in this resource. A makefile can be used for the creation process of a CSP to incorporate this signing and registering procedure so that no steps are forgotten. Sign Utility The Sign.exe utility signs CSP DLLs. Given a DLL file, the utility produces a signature file whose contents can be placed into the registry as discussed above and in Setting the User Default CSP. Sign.exe takes three arguments: sign {s|v} <filename> <signature file> The first argument must be s if a signature file is to be generated and v if an existing signature file is to be verified against the DLL file. The second argument must be the fully qualified fileDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 12 / 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.
  13. 13. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE name of the DLL file. The third argument must be the fully qualified file name of the signature file. For the CSP DLL file Myxcsp.dll, the following command generates a signature file. The signature file will be named Myxcsp.sig. sign s myxcsp.dll myxcsp.sig 1.2.4 Testing the CSP In accordance with the U.S. Department of Commerces export restrictions concerning cryptography, Microsoft must digitally sign a CSP so that it will run on Microsoft operating systems. The Microsoft Cryptographic Service Provider Developers 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 CSPs 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 fromDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 13 / 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.
  14. 14. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE host systems and applications, CryptoAPI places the burden of U.S. encryption export restrictions squarely on the CSP vendor, who is subject to those controls regardless. In addition, the operating system validates this signature periodically to ensure that the CSP has not been changed. Microsofts 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 vendors 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 Departments export license process, encryption export controls, and points of contact are described on their Web site at http://www.bxa.doc.gov/encstart.htm.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 14 / 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.
  15. 15. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Microsoft will sign CSPs subject only to the limitations of U.S. export controls. Microsoft will sign CSPs from competitors. At present, CSPs are signed at the Microsoft facilities in Redmond, Washington, USA. For further information, see 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 asDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 15 / 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.
  16. 16. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE necessary. Extensions to CryptoAPI must be made in a responsible manner. Before defining new parameters and algorithm types, a CSP developer should consult Microsoft Corporation, so that: • Common CryptoAPI extensions can be identified and placed into the standard Microsoft® Win32® Wincrypt.h file. • Namespace collisions can be avoided. • It can be determined if the extension is required, or whether a particular operation can be achieved with the current API. Note For a CSP to be compatible with applications developed for the Microsoft Base Cryptographic Provider, it must support all of the preceding items as described in CryptoAPI Reference and in Cryptographic Service Provider Reference. 1.3 CSP Interoperability To provide for interoperability with other cryptographic service providers (CSPs), any PROV_RSA_FULL CSP must conform to specific implementation requirements. The PROV_RSA_SIG provider type is a subset of PROV_RSA_FULL and not all of the implementation requirements discussed apply to PROV_RSA_SIG providers. Major areas that must conform to implementation requirements are listed in the following table. Major requirement 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 thatDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 16 / 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.
  17. 17. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 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 others 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 17 / 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.
  18. 18. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 1.3.1.2 Symmetric Encryption Algorithms Every PROV_RSA_FULL or PROV_RSA_SIG CSP must provide an implementation of the RC2 block cipher and the RC4 stream cipher encryption. These algorithms are used to create session keys for bulk data encryption and decryption. The Microsoft Base Cryptographic Provider uses 40-bit session keys with 88-bit salt values (128 bits total). A new CSP is free to use larger keys, although using longer keys makes exporting the CSP outside the USA and Canada more difficult. Currently, code containing 56-bit encryption and 1024-bit key exchange can be freely exported. For more information on export control, see 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 18 / 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.
  19. 19. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 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 keys 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 blocks 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). Reserved 58 Zero value. 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 f1DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 19 / 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.
  20. 20. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 20 / 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.
  21. 21. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE For example, from a 160-bit SHA hash value, a 40-bit session key with an 88-bit salt value can be created. The first five bytes (40 bits) of the hash are the session key material and the next 11 bytes are the salt. The last 4 bytes of the hash are unused. Note Hash values and session keys are viewed as blocks of binary data, not large integers; therefore, byte ordering (that is, big-endian versus little-endian format) is not relevant. 1.3.3.1 Key Derivation Sample The example data in this section was generated using the Microsoft Base Cryptographic Provider. In a particular instance with another provider, the session key length and salt length can be different, but the basic process is the same. Assume an application will derive a session key from a hash of the password, "124-kelp". The password is hashed using CryptHashData specifying the MD5 hash algorithm. The following sixteen-byte hash value is generated. 73 40 e6 e2 74 b8 ea 39 93 95 aa 29 d6 38 b5 2a The application calls CryptDeriveKey to create the session key, which in this case is an RC4 stream cipher key. The CSP uses the first five bytes of the previous hash value, 73 40 e6 e2 74, as the key itself. If the CRYPT_CREATE_SALT flag is not specified, the key is given a salt value of zero. Using this session key to encrypt the following plaintext buffer: 00 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 50DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 21 / 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.
  22. 22. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 1.3.4 Hashing Session Keys When an application uses the CryptHashSessionKey function to hash a session key, only the base key material must be hashed. For a 40-bit key, this will be 5 bytes of data. The key should be hashed in big-endian byte order. For example, if the Microsoft Base Cryptographic Provider is used to create and hash a session key with a value of 4a 3a ee 77 37, the bytes need to be reversed before the hashing operation is performed. In this example, the following hash values are produced: For an MD5 hash 0b 15 55 0a a0 03 f9 3f 75 82 f7 e7 91 32 bc 8c For an SHA hash 3c 37 72 93 53 ff 2a 4f ef 12 54 18 5b 3a c4 63 03 fd 07 5d 1.3.5 Digital Signature Mechanics An application signs or verifies hash values by using the CryptSignHash and CryptVerifySignature functions. The application often specifies a description string, which must be added to the hash object before it is signed or verified. The following is a typical signature process: 1. The application creates a hash object by using CryptCreateHash. 2. The application adds data to 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 22 / 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.
  23. 23. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 8. The signature block is returned to the application, using the operating system layer. 1.3.5.1 Signature Sample This section steps through the signature process. It uses the hash value from the Key Derivation Sample, the MD5 hash of the "124-kelp" string. This hash value is as follows: 73 40 e6 e2 74 b8 ea 39 93 95 aa 29 d6 38 b5 2a This example uses "Test Signature" as the description string. First, the CSP adds this string to the hash object being signed. The description string, "Test Signature," is received by the CSP in Unicode format as the following hexadecimal bytes: 54 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 keys 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. Reserved 35 Zero value. Padding data (0xffs). The size of this field is adjusted as necessary so Padding 36 to 62 that the signature blocks overall length is correct. Block type 63 The PKCS block type (0x01).DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 23 / 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.
  24. 24. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE Reserved 64 Zero value. The order of this table is reversed from the diagram found in the PKCS documentation because the signature block is built in big-endian on a little-endian computer. The completed signature block in this example is: 2a 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 30DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 24 / 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.
  25. 25. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE The encoded OID strings shown in the previous table include wrapper bytes. For example, the encoded string shown for SHA contains the following information (for clarity, the bytes are in reverse order).DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 25 / 116 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.
  26. 26. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 2 Using a Cryptographic Service Provider 2.1 Using CSPs: General Processes 2.1.1 Example Program Limitations To provide more concise, more readable code, some principles of good programming practice are not always followed in these example programs. In particular: • Only limited error responses are shown. Well-written, complete programs check returned error codes and perform appropriate actions when an error is encountered. • Only limited memory and resource management is done. Well-written, complete programs destroy all keys and hashes, free all allocated memory, close all files, and release all handles. These example programs provide only limited demonstrations of the use of functions that perform these tasks. These example programs perform no memory or resource management tasks in the case of program termination due to errors. 2.1.2 Retrieving Data of Unknown Length Many functions return a potentially large amount of data to an address provided as one of the parameters by the application. In all these cases, the operation is performed in a similar, if not identical, fashion. The parameter that points to the location of the returned data will use the notation convention where pb or pv are the first two characters of the parameter name. Another parameter will have pcb as the first three characters of the parameter name. This parameter represents the size, in bytes, of the data that will be returned to the pb or pv location. For example, consider the following function specification: BOOL WINAPI SomeFunction( PCCRL_CONTEXT pCrlContext, // 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 26 / 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.
  27. 27. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE If NULL is input for pbData and pcbData is non-NULL, no error is returned and the function returns the size in bytes of the needed memory buffer in the variable pointed to by pcbData. This lets an application determine the size of, and the best way to allocate, a buffer for the returned data. Note When NULL is input for pbData to determine the size needed to ensure that the returned data fits in the specified buffer, the second call to the function which populates the buffer with the desired data may not use the whole buffer. After the second call, the actual size of the data returned is contained in pcbData. Use this size when processing the data. The following example code demonstrates how input and output parameters might be implemented for this purpose: //-------------------------------------------------------------------- #include <stdio.h> #include <windows.h> #include <wincrypt.h> #define MY_ENCODING_TYPE (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. //--------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 27 / 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.
  28. 28. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE // 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); }DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 28 / 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.
  29. 29. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 2.1.3 Enumerating Supported Protocols Supported protocols and cipher suites can be listed by calls to CryptGetProvParam with PP_ENUMALGS or PP_ENUMALGS_EX. The PP_ENUMALGS_EX value works like PP_ENUMALGS but returns a PROV_ENUMALGS_EX structure that holds more extensive information on the algorithms supported by the provider. For more information on defined protocol flags and their values, see Protocol Flags. Given that hCryptProv is the handle of an open cryptographic context acquired using CryptAcquireContext with its dwProvType parameter set to PROV_RSA_SCHANNEL, the following code lists the names of all algorithms available in the CSP: PROV_ENUMALGS_EX EnumAlgs; // 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"DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 29 / 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.
  30. 30. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE CALG_DES 56 56 0x0005 "DES" To prepare to send ClientHello or ServerHello messages, the Schannel protocol engine enumerates the algorithms and key sizes supported by the CSP and builds a list internally of supported cipher suites. 2.2 Using Schannel CSPs Beginning with Microsoft® Windows® 2000, cryptogaphic service providers (CSPs) can use Schannel. Cryptographic applications can call CryptAcquireContext using the PROV_RSA_SCHANNEL and PROV_DH_SCHANNEL providers. This section defines the RSA and Diffie-Hellman Schannel CSP types and describes the functionality that a CSP must support to be compatible with Schannel.dll, the Microsoft cryptographic protocol engine. A protocol engine is a program that establishes a secure communications channel between a client and server application. Applications should not attempt to use information in this documentation to use PROV_RSA_SCHANNEL or PROV_DH_SCHANNEL directly. Rather, this documentation explains how CSP developers and vendors must write Schannel CSPs that are compatible with Microsoft Schannel providers. This documentation is intended to help CSP developers implement compatible RSA or 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 andDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 30 / 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.
  31. 31. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE access to the matching private key. The client-side of Schannel needs its certificate with its public key and access to its private key if client authentication is implemented. Since Schannel protocol engines never use the AT_SIGNATURE public/private key pair, that key pair need not be supported by a new CSP supporting only RSA/Schannel or 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 engines key container>; HCRYPTKEY hPublicKey = <servers public key>; HCRYPTKEY hMasterKey; // handle for master key to be created. ALG_ID Algid; DWORD dwGenFlags =CRYPT_EXPORTABLE;DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 31 / 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.
  32. 32. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 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>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; } //-------------------------------------------------------------------- // Generate the master key. CryptGenKey( hProv, Algid, dwGenFlags, &hMasterKey); //-------------------------------------------------------------------- // Export the master key. cbBlob = sizeof(rgbBlob); CryptExportKey( hMasterKey, hPublicKey, SIMPLEBLOB, dwExportFlags, rgbBlob,DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 32 / 116 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.
  33. 33. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE &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 engines key container>; HCRYPTKEY hClientDHKey; // handle to the clients DH key HCRYPTKEY hMasterKey; ALG_ID Algid; PBYTE pbServerPub = <pointer to Server Public Key>; DWORD cbServerPub = <size of Server Public Key>; BYTE rgbServerBlob[<max BLOB size>]; DWORD cbServerBlob; PBYTE pbG = <pointer to generator G from Server>; DWORD cbG = <size of generator G from Server>; PBYTE pbP = <pointer to prime P from Server>; DWORD cbP = <size of prime P from Server>; CRYPT_DATA_BLOB Data; BYTE rgbClientPubBlob[size of the client public key BLOB]; DWORD cbClientPubBlob; //-------------------------------------------------------------------- // Generate and set the parameters on the client DH key // Schannel specifies the key size and [regen flag when generating // a client DH key. CryptGenKey( hProv, CALG_DH_EPHEM, ((cbP * 8) << 16)|CRYPT_PREGEN, &hClientDHKey); Data.pbData = pbP; Data.cbData = cbP; CryptSetKeyParam( hClientDHKey, KP_P, (BYTE*)&Data, 0); Data.pbData = pbG; Data.cbData = cbG; CryptSetKeyParam( hClientDHKey, KP_G, (BYTE*)&Data, 0); //--------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 33 / 116 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.
  34. 34. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE // Create the client private DH key CryptSetKeyParam( hClientDHKey, KP_X, NULL, 0); //-------------------------------------------------------------------- // Build PUBLICKEYBLOB around the servers 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 servers public key and get an agreed key CryptImportKey( hProv, rgbServerBlob, cbServerBlob, hClientDHKey, 0, &hMasterKey); //-------------------------------------------------------------------- // Select the master key type. switch(<protocol being used>) { case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; } //-------------------------------------------------------------------- // Convert the agreed key to the appropriate master keyDSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 34 / 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.
  35. 35. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE 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 = <servers 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; case <SSL 2.0>: Algid = CALG_SSL2_MASTER; if(<we support SSL3>) dwFlags = CRYPT_SSL2_FALLBACK; break;DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 35 / 116 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.
  36. 36. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; 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.DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 36 / 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.
  37. 37. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE HCRYPTPROV hProv = <protocol engines key container>; HCRYPTKEY hServerDHKey; // handle to the clients 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 clients 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 clients public key and get an agreed key CryptImportKey( hProv, rgbClientBlob, cbClientBlob, hServerDHKey, 0, &hMasterKey); //-------------------------------------------------------------------- // Select the master key type. switch(<protocol being used>) { case <SSL 3.0>: Algid = CALG_SSL3_MASTER; break; case <TLS 1.0>: Algid = CALG_TLS1_MASTER; break; }DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 37 / 116 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.
  38. 38. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE //-------------------------------------------------------------------- // Convert the agreed key to the appropriate master key CryptSetKeyParam( hMasterKey, KP_ALGID, (BYTE*)&Algid, 0); 2.2.3.5 Specifying the Algorithms After a master key is created or imported, both RSA/Schannel and Diffie-Hellman/Schannel inform the CSP of the type of bulk encryption keys and MAC keys that will be derived from the master key. The following code specifies these algorithms. The same code is used for both client and server. //-------------------------------------------------------------------- // Algorithms for the SCHANNEL_ALG structure #define SCHANNEL_MAC_KEY 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);DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 38 / 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.
  39. 39. DEKART CRYPTO SERVICE PROVIDER USERS GUIDE //-------------------------------------------------------------------- // Specify hash algorithm. Algorithm.dwUse = SCHANNEL_MAC_KEY; Algorithm.Algid = CALG_MD5; // or CALG_SHA, etc. Algorithm.cBits = 128; // or 160... CryptSetKeyParam( hMasterKey, KP_SCHANNEL_ALG, (PBYTE)&Algorithm, 0); Note An Schannel protocol engine must not specify algorithms and key sizes not supported by the CSP. For more information, see Enumering Supported Protocols. If unsupported algorithms or key sizes are specified, the CSP function must fail and return the NTE_BAD_DATA error code. 2.2.4 Deriving Bulk Encryption and MAC Keys Bulk encryption and MAC keys are derived from a master key but can include other sources depending on the protocol and cipher suite used. The process of deriving bulk encryption and MAC keys is the same for both client and server: 1. The protocol engine calls CryptSetKeyParam on the master key one or more times to provide the CSP with the information needed to build the keys. 2. Because CryptoAPI keys cannot be derived directly from other keys, a hash object is created from the master key using CryptCreateHash. This hash is used to create the new keys. 3. The two bulk encryption keys and the two MAC keys are created from the "master hash" object using four calls to CryptDeriveKey. Note When performing SSL reconnects, a protocol engine can perform the above procedure several times using the same master key. This enables the client and server to have multiple, often simultaneous connections, each using different bulk encryption and MAC keys without additional RSA or Diffie-Hellman operations. All CSPs must use good thread-safe practices. Thread counts of several dozen are not unusual. The following is typical source code for the protocol engine: //-------------------------------------------------------------------- // Define and initialize local variables. BOOL fClient = <TRUE if this is code for the client?>; CRYPT_DATA_BLOB Data; HCRYPTHASH hMasterHash; //--------------------------------------------------------------------DSSSCT File : dcsp Ref : DSPUSG990001 Revision : 1.0 39 / 116 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.

×