Security Toolkit Version 2.1 final beta Copyright Peter Gutmann 1992-1999 March 1999 2 Introduction INTRODUCTION 10 cryptlib Overview 10 cryptlib features 11 Programming Interface 11 Security Features 11 Standards Compliance 12 Y2K Compliance 12 Performance 12 Encrypted Object Management 12 Certificate Management 13 Key Database Interface 13 Smart Card Support 14 Cryptographic Random Number Management 14 Configuration Options 14 Document conventions 14 Recommended Reading 15 INSTALLATION 16 Installing cryptlib for Windows 3.x 16 Installing cryptlib for Windows’95/98 and Windows NT 16 Installing from Source Code 16 BeOS 16 DOS 16 DOS32 16 OS2 16 Windows 3.x 17 Windows’95/98 and Windows NT 17 Unix 17 Other systems 18 Key Database Setup 19 Certificate Installation 19 Cut-down cryptlib Versions 19 Support for Vendor-specific Algorithms 20 CRYPTLIB BASICS 21 Programming interfaces 21 Envelope interface 22 Encryption object interface 22 Low-level interface 22 Objects and Interfaces 22 Interfacing with cryptlib 23 Initialisation 23 Additional Initialisation 23 Interaction with External Events 23 Object Security 24 ENVELOPING CONCEPTS 27 Creating/Destroying Envelopes 27 The Data Enveloping Process 28 Data Size Considerations 29 Basic Data Enveloping 30 Password-based Encryption Enveloping 30 De-enveloping Mixed Data 31 Enveloping Large Data Quantities 32 cryptlib Overview 3 Alternative Processing Techniques 33 Enveloping with Many Resources 34 ADVANCED ENVELOPING 36 Public-Key Encrypted Enveloping 36 Digitally Signed Enveloping 37 Enveloping with Multiple Resources 39 Envelope Resource Cursor Management 39 Processing Multiple Resources 40 Nested Envelopes 41 KEY DATABASES 43 Creating/Destroying Keyset Objects 43 File Keysets 44 LDAP Keysets 45 Relational Database Keysets 46 Smart Card Keysets 47 Extended Keyset Initialisation 48 LDAP Keysets 49 Relational Database Keysets 49 Smart Card Keysets 50 Accessing a Keyset 52 Reading a Key from a Keyset 52 Obtaining a Key for a User 53 Obtaining a Key for an Exported Key/Signature/Certificate Object 54 Writing a Key to a Keyset 55 General Keyset Queries 56 Deleting a Key 58 ENCRYPTION AND DECRYPTION 59 Creating/Destroying Encryption Contexts 59 Extended Initialization 60 Generating a Key into an Encryption Context 60 Public/Private Key Generation 61 Deriving a Key into an Encryption Context 62 Loading Keys into Encryption Contexts 63 Loading Initialisation Vectors 63 Working with Public/Private Keys 64 Multibyte Integer Formats 64 Loading Multibyte Integers 65 ENCRYPTING/DECRYPTING DATA 67 Using Encryption Contexts to Encrypt/Decrypt Data 67 EXCHANGING KEYS 69 Exporting a Key 69 Exporting using Conventional Encryption 70 Importing a Key 71 Importing using Conventional Encryption 71 Querying an Exported Key Object 72 Conventionally encrypted objects 72 Public-key encrypted objects 73 Extended Key Export/Import 73 Key Agreement 74 4 Introduction SIGNING DATA 76 Querying a Signature Object 77 Extended Signature Creation/Checking 78 CERTIFICATE MANAGEMENT 80 Overview of Certificates 80 Certificates and Standards Compliance 80 The Certification Process 81 Creating/Destroying Certificate Objects 82 Working with Certificate Components 82 Component Types 83 Querying/Setting/Deleting Components 83 Certificate Structures 84 Attribute Certificate Structure 85 Certificate Structure 86 Certification Request Structure 88 CRL Structure 88 Basic Certificate Management 89 Certificate Identification Information 91 DN Structure for Business Use 92 DN Structure for Private Use 92 Other DN Structures 93 Working with Distinguished Names 93 Extended Certificate Identification Information 93 Working with GeneralNames 94 Certificate Fingerprints 95 Importing/Exporting Certificates 95 Signing/Verifying Certificates 97 Certificate Trust Management 99 Working with Trust Settings 100 Certificate Errors 100 CERTIFICATE EXTENSIONS 102 Extension Structure 102 Working with Extension Components 102 Extension Cursor Management 103 Composite Extension Fields 105 X.509 Extensions 106 Alternative Names 106 Basic Constraints 106 Certificate Policies, Policy Mappings, and Policy Constraints 107 CRL Distribution Points and Authority Information Access 108 Directory Attributes 108 Key Usage, Extended Key Usage, and Netscape cert-type 108 Name Constraints 111 Private Key Usage Period 112 Subject and Authority Key Identifiers 112 CRL Extensions 113 CRL Reasons, CRL Numbers, Delta CRL Indicators 113 Hold Instruction Code 114 Invalidity Date 114 Issuing Distribution Point and Certificate Issuer 114 SET Extensions 115 SET Card Required and Merchant Data 115 SET Certificate Type, Hashed Root Key, and Tunneling 115 cryptlib Overview 5 Vendor-specific Extensions 116 Netscape Certificate Extensions 116 Thawte Certificate Extensions 117 MAINTAINING KEYS AND CERTIFICATES 118 Updating a Private Key with Certificate Information 118 The Certification Process 119 Certificate Chains 121 Working with Certificate Chains 121 Signing Certificate Chains 122 Checking Certificate Chains 123 Exporting Certificate Chains 124 Certificate Revocation Lists 124 Working with CRL’s 124 Creating CRL’s 125 Advanced CRL Creation 126 Checking Certificates against CRL’s 126 Automated CRL Checking 127 FURTHER CERTIFICATE OBJECTS 128 Certificate-like Object Structure 128 CMS Attributes 128 CMS Attributes 128 Content Type 128 Countersignature 129 MAC Value 129 Message Digest 129 Signing Time 130 Extended CMS Attributes 130 AuthentiCode Attributes 130 Content Hints 131 Mail List Expansion History 131 Receipt Request 131 Security Label, Equivalent Label 132 Signing Certificate 133 S/MIME 134 S/MIME Enveloping 134 Encrypted Enveloping 135 Digitally Signed Enveloping 135 Detached Signatures 136 Extra Signature Information 137 From Envelopes to S/MIME 138 S/MIME Content Types 139 Data 139 Signed Data 139 Detached Signature 139 Encrypted Data 140 Nested Content 140 Implementing S/MIME using cryptlib 140 Example: Eudora 140 ENCRYPTION DEVICES AND MODULES 142 Creating/Destroying Device Objects 142 Activating and Controlling Cryptographic Devices 143 Initialise Device 143 6 Introduction User Authentication 143 Zeroise Device 143 Extended Device Control Functions 144 Setting/Changing User Authentication Values 144 Working with Device Objects 144 Considerations when Working with Devices 145 PKCS #11 Devices 145 Installing New PKCS #11 Modules 146 PKCS #11 Functions used by cryptlib 146 RANDOM NUMBERS 147 Gathering Random Information 147 Random Information Gathering Techniques 147 BeOS 148 DOS 148 Macintosh 148 OS/2 149 UNIX 149 Windows 3.x 150 Windows 95 150 Windows NT 150 Hardware Random Number Generation 151 MISCELLANEOUS TOPICS 153 Querying cryptlib’s Capabilities 153 Working with Configuration Options 153 Configuration Option Types 154 Querying/Setting Configuration Options 154 Storing/Retrieving Configuration Options 155 Obtaining Information About Cryptlib 155 Working with Newer Versions of cryptlib 156 ERROR HANDLING 157 Extended Error Reporting 159 ALGORITHMS AND MODES 161 Blowfish 161 CAST-128 161 DES 161 Triple DES 161 Diffie-Hellman 162 DSA 162 ElGamal 162 HMAC-MD5 162 HMAC-SHA1 162 HMAC-RIPEMD-160 162 IDEA 162 MD2 163 MD4 163 MD5 164 MDC2 164 RC2 164 RC4 164 cryptlib Overview 7 RC5 164 RIPEMD-160 164 RSA 164 SAFER 165 SAFER-SK 165 SHA 165 Skipjack 165 ECB 165 CBC 165 CFB 165 OFB 165 DATA TYPES AND CONSTANTS 170 CRYPT_ALGO 170 CRYPT_CERTERROR_TYPE 171 CRYPT_CERTFORMAT_TYPE 171 CRYPT_CERTINFO_TYPE 172 CRYPT_CERTTYPE_TYPE 172 CRYPT_DEVICE_TYPE 172 CRYPT_DEVICECONTROL_TYPE 173 CRYPT_ENVINFO_TYPE 173 CRYPT_FORMAT_TYPE 174 CRYPT_KEYID_TYPE 174 CRYPT_KEYOPT 174 CRYPT_KEYSET_TYPE 179 CRYPT_MODE 179 CRYPT_OBJECT_TYPE 180 CRYPT_OPTION_TYPE 180 CRYPT_PROPERTY_TYPE 184 Data Size Constants 184 Miscellaneous Constants 185 DATA STRUCTURES 186 CRYPT_INFO Structures 186 CRYPT_OBJECT_INFO Structure 186 CRYPT_PKCINFO Structures 187 CRYPT_QUERY_INFO Structure 188 FUNCTION REFERENCE 189 cryptAddCertComponentNumeric 189 cryptAddCertComponentString 189 cryptAddCertExtension 189 cryptAddEnvComponentNumeric 190 cryptAddEnvComponentString 190 cryptAddPrivateKey 191 cryptAddPublicKey 191 cryptAddRandom 191 cryptAsyncCancel 192 cryptAsyncQuery 192 8 Introduction cryptCheckCert 192 cryptCheckSignature 192 cryptCheckSignatureEx 193 cryptCreateCert 193 cryptCreateContext 193 cryptCreateContextEx 194 cryptCreateDeenvelope 195 cryptCreateDeenvelopeEx 195 cryptCreateEnvelope 195 cryptCreateEnvelopeEx 195 cryptCreateSignature 196 cryptCreateSignatureEx 196 cryptDecrypt 197 cryptDeleteCertComponent 197 cryptDeleteCertExtension 198 cryptDeleteKey 198 cryptDeriveKey 198 cryptDeriveKeyEx 199 cryptDestroyCert 199 cryptDestroyContext 200 cryptDestroyEnvelope 200 cryptDestroyObject 200 cryptDeviceClose 200 cryptDeviceControl 201 cryptDeviceControlEx 201 cryptDeviceCreateContext 201 cryptDeviceOpen 202 cryptDeviceOpenEx 202 cryptEncrypt 202 cryptEnd 203 cryptExportCert 203 cryptExportKey 203 cryptExportKeyEx 204 cryptGenerateKey 205 cryptGenerateKeyAsync 205 cryptGenerateKeyEx 205 cryptGenerateKeyAsyncEx 206 cryptGetCertComponentNumeric 206 cryptGetCertComponentString 206 cryptGetCertExtension 207 cryptGetEnvComponentNumeric 207 cryptGetErrorInfo 208 cryptGetErrorMessage 208 cryptGetObjectProperty 208 cryptGetOptionNumeric 209 cryptGetOptionString 209 cryptGetPrivateKey 209 cryptlib Overview 9 cryptGetPublicKey 210 cryptGetRandom 210 cryptImportCert 211 cryptImportKey 211 cryptImportKeyEx 211 cryptInit 212 cryptInitEx 212 cryptKeysetClose 212 cryptKeysetOpen 213 cryptKeysetOpenEx 213 cryptKeysetQuery 213