RSA BSAFE® Crypto-C Cryptographic Components for C Intel® Security Hardware User’s Guide Version 4.
Copyright Notice © 1999 RSA Security Inc. All rights reserved. This work contains proprietary information of RSA Security Inc. Distribution is limited to authorized licensees of RSA Security Inc. Any unauthorized reproduction or distribution of this document is strictly prohibited.
Contents Chapter 1 Overview 1 Intel Hardware Security Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 RSA BSAFE Crypto-C Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 How This Book Is Organized . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Additional Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Obtaining a Random Seed from Hardware. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Retrieving Hardware Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Generating Random Numbers in Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 1 Overview RSA Security Inc. and Intel Corporation have teamed to provide C programmers access to the Intel Random Number Generator via the RSA BSAFE® Crypto-C interface. Intel Hardware Security Features The Intel® hardware security features are intended to provide a hardware infrastructure for cryptographic functions, such as random number generation. Version 1.
How This Book Is Organized certain features in their BSAFE Crypto-C software applications. How This Book Is Organized The audience for this document is application programmers who are familiar with Crypto-C and who wish to benefit from Intel’s hardware security features in a Crypto-C application. The following topics are covered: • Chapter 1, “Overview” (this chapter) gives an overview of the Intel hardware security features and the Crypto-C hardware interface.
Overview of a Crypto-C Hardware Application Overview of a Crypto-C Hardware Application Creating a Crypto-C application that can use Intel’s security hardware features is similar to creating any Crypto-C application. If you are not familiar with Crypto-C, you may wish to consult the introductory example in Chapter 1 of the Crypto-C User’s Guide. For an application that will use hardware, the following differences should be noted: Additional algorithm info types (AIs).
The Six-Step Sequence The Six-Step Sequence The model for building a hardware-aware application with Crypto-C is similar to the six-step model described in Chapter 1 of the Crypto-C User’s Manual. The differences are as follows: 1. Create: At this point you may want to create the session chooser that will be used in Step 3. 2. Set 3. Init: In this step, you must pass a modified chooser, the session chooser, to your initialization function.
Chapter 2 Using Intel Hardware With Crypto-C Crypto-C uses the RSA BSAFE Hardware API (BHAPI) to access the Intel hardware security features. In order to use this interface, you need to match the appropriate Crypto-C and Intel algorithm methods via a session chooser. In addition, your application must be linked with the SEC32IPI.lib library that comes with the security driver provided by Intel.
Algorithm Methods capabilities. The AMs required to support the Intel security hardware are included as part of Crypto-C. As with all algorithm methods, the hardware-compatible AMs in Crypto-C are only available for certain algorithm info types (AIs). The AIs in Crypto-C offer differing levels of support for hardware, as follows: • Crypto-C AIs that support hardware only, such as AI_HW_Random.
The Session Chooser The Session Chooser Any Crypto-C application which uses hardware requires your application to declare two choosers: • The baseline software chooser, such as the one that is used in any Crypto-C application. This chooser must be modified to include the generic Crypto-C hardware methods that support the desired hardware. • The hardware chooser, that lists the manufacturer-specific hardware methods that can be used. This chooser has no analogue in a software-only application.
The Session Chooser Creating the Hardware Chooser A hardware chooser is a list of manufacturer-supplied HW_TABLE_ENTRYs. Each entry defines the necessary code for accessing the specified piece of hardware. In the case of the Intel hardware random generator, use HW_INTEL_RANDOM. If you wish, the hardware chooser can contain several HW_TABLE_ENTRYs, possibly supplied by different manufacturers, that all correspond to the same AM in the software chooser.
Hardware Availability make the actual Crypto-C function call during the Crypto-C Init step, for example, as the chooser argument to B_RandomInit. Hardware Availability When you specify a specific hardware device via a manufacturer-specific AM, such as HW_INTEL_RANDOM, the application will verify that the hardware is present during the call to B_CreateSessionChooser. If the hardware is not present, Crypto-C will return an error.
Hardware Errors Hardware Errors If the hardware fails, Crypto-C will return an error of BE_HARDWARE or BE_NOT_SUPPORTED. BE_HARDWARE indicates that the Intel primitive has returned an error. This error can be retrieved using B_GetExtendedErrorInfo (described in the Crypto-C Library Reference Manual), as shown below. In this example, randomAlgorithm is an algorithm that has been created to retrieve a seed from the Intel Random Number Generator.
Hardware Errors A_RSA_EXTENDED_ERROR This Crypto-C structure is defined specifically for retrieving Intel error codes. It is defined as follows: typedef struct { UINT4 errorCode; errorMsg[128]; char } A_RSA_EXTENDED_ERROR Definitions: errorCode The error code returned by the Intel hardware. errorMsg A NULL-terminated description of the error provided by Crypto-C.
Hardware Errors 12 R S A B S A F E C r y p t o - C I n t e l H a r d w a r e U s e r ’s G u i d e
Chapter 3 Using the Intel Random Number Generator This chapter gives some background on random number generators and shows how to use the Intel Random Number Generator (RNG) with a Crypto-C application. Random Numbers All cryptosystems, whether secret-key systems like DES or public-key systems like RSA encryption, need a good source of cryptographic random numbers. The random numbers are used to generate input such as keys and initialization vectors.
Random Numbers The Intel Random Number Generator The Intel Random Number Generator is dedicated hardware that harnesses system thermal noise to generate random values. The generator is free-running, accumulating random bits of data until a 32-bit buffer is filled. Whitening Hardware Results The bits the Intel RNG supplies to the application have been whitened by the hardware; that is, a post-processing algorithm has been applied to reduce patterns in the hardware bits and make them less predictable.
Random Numbers Pseudo-Random Number Generators (PRNGs) Crypto-C provides several pseudo-random number generators that can be seeded via the Intel RNG and used to generate random numbers. The PRNGs in Crypto-C satisfy mathematical tests that measure randomness and are considered cryptographically secure. The Intel RNG can be used to provide a quick, secure seed to a PRNG. Once a PRNG has been seeded, it produces output up to ten thousand times faster than a hardware random number generator.
Generating Random Numbers Generating Random Numbers This example demonstrates how to use the Intel Hardware Random Number Generator to seed a software-based pseudo-random number generator (PRNG). To generate random numbers, do the following: 1. Use the Intel Random Number Generator to generate a random seed. In general, you should use a seed that is at least 256 bits long. 2. Seed a pseudo-random number generator with the random value that you retrieved in the first step.
Generating Random Numbers HW_TABLE_ENTRY *HARDWARE_CHOOSER[] = { &HW_INTEL_RANDOM, (HW_TABLE_ENTRY *)NULL_PTR }; B_ALGORITHM_METHOD **CHOOSER = (B_ALGORITHM_METHOD **)NULL_PTR; if ((status = B_CreateSessionChooser (SOFTWARE_CHOOSER, &CHOOSER, (POINTER *)HARDWARE_CHOOSER, (ITEM *)NULL_PTR, (POINTER *)NULL_PTR, &oemTagList)) != 0) break; Step 1: Create an Algorithm Object The next task is to create the algorithm object. This object will control the random byte generation.
Generating Random Numbers if ((status = B_RandomInit (randomAlgorithm, CHOOSER, (A_SURRENDER_CTX *)NULL_PTR)) != 0) break; Step 4: Update the Random Object Step 4 is not needed for random number seeding in hardware. Step 5: Generate Random Bytes Generate the random bytes for the seed. In this example, you will have the Crypto-C SDK generate seedMaxLength random bytes, storing the data in seedBytes. The last parameter is a surrender context.
Generating Random Numbers Step 6b: Free the Session Chooser Free the session chooser. It is important to free the session chooser, so that any handles to hardware and allocated memory are released. if ((status = B_FreeSessionChooser (&CHOOSER, &oemTagList)) != 0) break; Retrieving Hardware Error Codes If the hardware fails or cannot return a seed, Crypto-C will return an error of BE_HARDWARE or BE_NOT_SUPPORTED. BE_HARDWARE indicates that the Intel Random Number Generator has returned an error.
Generating Random Numbers software. After the seed has been passed to the software algorithm info type, this is similar to any Crypto-C PRNG implementation. The only difference is the fast, truly random, seed operation. For this example, you will use Crypto-C’s SHA1 PRNG to generate random numbers. Note: This example will work whether the seed was gathered from the Intel RNG or via another, backup method.
Generating Random Numbers Step 3: Initialize the Random Algorithm To initialize the random algorithm, you must pass the algorithm object, the algorithm chooser, and a surrender context. As mentioned before, the algorithm chooser does not need to be a session chooser; a simple software chooser will suffice, so this call is also identical to a software implementation.
Generating Random Numbers call would be identical in a software implementation: if ((status = B_RandomUpdate (randomAlgorithm, randomSeed, randomSeedLen, (A_SURRENDER_CTX *)NULL_PTR)) != 0) break; Step 5: Generate Random Numbers Before calling B_GenerateRandomBytes, prepare a buffer for receiving the random bytes. This is a little different than the software implementation.
Appendix A Crypto-C Error Codes Table A-1 lists the hardware-related error values returned by Crypto-C. If Crypto-C receives a hardware-level error from the Intel hardware, Crypto-C will return BE_HARDWARE. The underlying Intel error code can be retrieved using the Crypto-C B_GetExtendedErrorInfo function. See Appendix B for a description of the Intel error codes.
24 R S A B S A F E C r y p t o - C I n t e l H a r d w a r e U s e r ’s G u i d e
Appendix B Intel Security Hardware Error Codes Table B-1 lists the error values returned by the underlying Intel hardware. If Crypto-C returns an error of BE_HARDWARE, the underlying Intel error code can be retrieved using the Crypto-C function B_GetExtendedErrorInfo. Table B-1 Intel Security Hardware Error Codes Value Description ISD_EDISABLED The hardware device has been disabled and can no longer be used. ISD_EINPUT The hardware device is not currently available.
26 R S A B S A F E C r y p t o - C I n t e l H a r d w a r e U s e r ’s G u i d e
Appendix C Redistributing the Intel Security Driver Determining That the Firmware Hub Is Installed on the Target System Before installing the Intel Security Driver, you should verify that the firmware hub is installed on the target system, as follows: Operating System Firmware Hub Installation Check Microsoft Windows 95 Microsoft Windows 98 Check the following registry key: HKEY_LOCAL_MACHINE\Enum\BIOS for *INT0800 Microsoft Windows NT 4.0 There is no way to detect the presence of the firmware hub.
Redistributing the Driver Redistributing the Driver The Intel Security Driver can be redistributed in two ways: via a silent install (using InstallShield) or via .inf files. Redistributing via a Silent Install To redistribute the Intel Security Driver in your security-based applications, add the following steps to your installation script: 1. Copy all files from the \REDISTRIB folder, located at the root of the Crypto-C CD, to the appropriate folder within your application build tree. 2.
Redistributing the Driver Files Installed The silent install places the driver files in the following locations: File O/S Location Description ISECDRV.SYS Microsoft Windows NT 4.0 \windows\system32\drivers Legacy Microsoft Windows NT 4.0 driver ISECDRV.SYS Microsoft Windows 98 \windows\system32\drivers Microsoft wdm style driver ISECDRV.VXD Microsoft Windows \windows\system Microsoft Windows 95 Plug and Play driver SEC32IPI.
Redistributing the Driver Redistributing the Driver via .inf Files Instead of running the InstallShield silent install, described above, you can have the user install the driver on the target system by doing the following. User Instructions for Installing the Intel Security Driver To install the Intel Security Driver, do one of the following, depending on whether you are installing on Microsoft Windows NT 4.0, Microsoft Windows 95, or Microsoft Windows 98. Microsoft Windows NT 4.0 1.
Redistributing the Driver Microsoft Windows 95 1. Copy the following files from the Crypto-C CD to a floppy disk. \REDISTRIB \INF \Win95 ISD_95.INF ISECDRV.VXD 2. Log on to the target system. 3. Insert the floppy disk you created in step 1. 4. Click Start|Settings|Control Panel. 5. Double-click the System Icon. 6. Select the Device Manager Tab on the System Properties dialog box. 7. Double-click the Intel Firmware Hub option in the System Devices section. 8.
Redistributing the Driver Microsoft Windows 98 1. Copy the following files from the Crypto-C CD to a floppy disk. \REDISTRIB \INF \WDM ISD_WDM.INF ISECDRV.SYS ISD_CAT.CAT 2. Log on to the target system. 3. Insert the floppy disk you created in step 1. 4. Click Start|Settings|Control Panel. 5. Double-click the System Icon. 6. Select the Device Manager Tab on the System Properties dialog box. 7. Double-click the Intel Firmware Hub option in the System Devices section. 8.
Index A algorithm info type 3 AI_HW_Random 6 support for hardware 6 algorithm method 3, 5 AM_HW_RANDOM 6, 16 hardware method corresponding to 8 hardware-aware 5 Intel 6 multiple hardware methods and 8 vendor-specific 5 algorithm object 5 B BHAPI 1, 5 C chooser See hardware chooser, session chooser, software chooser E error codes Crypto-C 23 Intel 25 retrieving 10 examples hardware chooser 8 pseudo-random numbers 19 random numbers 16–22 retrieving error codes 10 session chooser 7–9 software chooser 7 H hard
34 R S A B S A F E C r y p t o - C I n t e l S e c u r i t y H a r d w a r e U s e r ’s G u i d e
