RSA Security Crypto-C User Manual
RSA BSAFE
®
Crypto-C
Cryptographic Components for C
Developer’s Guide
Version 5.2.2
RSA Security Inc.
20 Crosby Drive
Bedford, MA 01730 USA
Tel (US) 1 877 RSA 4900, +1 781 301 5000
Fax +1 781 301 5170
www.rsasecurity.com
RSA Security Ireland Limited
Bay 127, Shannon Free Zone
Shannon, County Clare, Ireland
Tel +353 61 72 5100
Fax +353 61 72 5110
www.rsasecurity.ie
See our Web Site for regional Customer Service telephone and fax numbers.
Trademarks
ACE/Server, BSAFE, Genuine RSA Encryption Engine, Keon, RC2, RC4, RC5, RSA,
RSA SecurPC, SecurCare, SecurID, SoftID, and WebID are registered trademarks, and
RC6, RSA Security, RSA Secured, SecurSight, and The Most Trusted Name in
e-Security are trademarks, of RSA Security Inc.
Other product and company names mentioned herein may be the trademarks of their
respective owners.
License agreement
This software and the associated documentation are proprietary and confidential to
RSA Security, are furnished under license, and may be used and copied only in
accordance with the terms of such license and with the inclusion of the copyright
below. This software and any copies thereof may not be provided or otherwise made
available to any other person.
Note on encryption technologies
This product may contain encryption technology. Many countries prohibit or restrict
the use, import, or export of encryption technologies, and current use, import, and
export regulations should be followed when exporting this product.
Distribution
Limit distribution of this document to trusted personnel.
RSA Security notice
The RC5® Block Encryption Algorithm With Data-Dependent Rotations is protected
by U.S. Patent #5,724,428 and #5,835,600.
The RC6™ Encryption Algorithm is the subject of pending U.S. and foreign patent
applications.
The DES implementation in this product contains code based on the "libdes" package
written by Eric A. Young (eay@pobox.com) and is included with his permission.
Compaq MultiPrime™ technology is protected by United States patent 5,848,159 and
is the subject of patent applications in other countries.
© 2001 RSA Security Inc. All rights reserved. 001-019003-522-001-000
First printing: May 2001
Contents
Preface xv
What’s New in Version 5.2.2? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Organization of This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvii
Conventions Used in This Manual. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Terms and Abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xx
How to Contact RSA Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxii
Improved performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
Hardware support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
MultiPrime RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvi
Serialization for algorithm objects performing RC4, Diffie Hellman key exchange . . . . .xvi
Advanced Encryption Standard (AES) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
RSA Security Web Site . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Getting Support and Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
SecurCare® Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Technical Support Telephone Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Call Handling and Escalation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Chapter 1 Introduction 1
The Crypto-C Toolkit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Symmetric Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Message Digests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Message Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Random-Number Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Public-Key Algorithms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Digital Signatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Elliptic Curve Public-Key Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Secret Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Hardware Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
iii
Cryptographic Standards and Crypto-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
PKCS Standards and Crypto-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
NIST Standards and Crypto-C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
PKCS Compared with NIST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ANSI X9 Standards and Crypto-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2 Quick Start 7
The Six-Step Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Introductory Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Saving the Object State (optional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Putting It All Together. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Decrypting the Introductory Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Multiple Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Summary of the Six Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Chapter 3
Cryptography 35
Cryptography Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Symmetric-Key Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Block Ciphers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Ciphers in Crypto-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
DES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Triple DES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
DESX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
RC2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
RC5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
RC6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
AES. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Modes of Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Stream Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Message Digests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Message Digests and Pseudo-Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Hash-Based Message Authentication Codes (HMAC) . . . . . . . . . . . . . . . . . . . . . . 49
Password-Based Encryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Public-Key Cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
The RSA Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Digital Envelopes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
iv RSA BSAFE Crypto-C Developer’s Guide
Optimal Asymmetric Encryption Padding (OAEP). . . . . . . . . . . . . . . . . . . . . . . . . . .55
Authentication and Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Digital Signature Algorithm (DSA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Digital Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Diffie-Hellman Public Key Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Elliptic Curve Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Elliptic Curve Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
The Finite Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
The Point P and its Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Summary of Elliptic Curve Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Representing Fields of Even Characteristic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72
Elliptic Curve Key Pair Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Creating the Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
ECDSA Signature Scheme. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Signing a Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Verifying a Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
The Math. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
Elliptic Curve Authenticated Encryption Scheme (ECAES) . . . . . . . . . . . . . . . . . . . . . . . . 75
Encrypting a Message Using the Public Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
Decrypting a Message Using the Private Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Elliptic Curve Diffie-Hellman Key Agreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
Phase 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
Phase 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
The Math. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Secret Sharing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80
Working with Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Key Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Key Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Key Escrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
ASCII Encoding and Decoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Applications of Cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Local Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Point-to-Point Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
Client/Server Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Peer-to-Peer Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Choosing Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Public-Key vs. Symmetric-Key Cryptography. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Stream vs. Block Symmetric-Key Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Block Symmetric-Key Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Key Agreement vs. Digital Envelopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Secret Sharing and Key Escrow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Contents v
Elliptic Curve Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Interoperability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Elliptic Curve Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Security Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Handling Private Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Temporary Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Pseudo-Random Numbers and Seed Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Choosing Passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Initialization Vectors and Salts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
DES Weak Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Stream Ciphers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Timing Attacks and Blinding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Choosing Key Sizes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
RSA Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Diffie-Hellman Parameters and DSA Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
RC2 Effective Key Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
RC4 Key Bits. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
RC5 Key Bits and Rounds. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Triple DES Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Elliptic Curve Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapter 4 Using Crypto-C 101
Algorithms in Crypto-C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Information Formats Provided by Crypto-C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Basic Algorithm Info Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
BER-Based Algorithm Info Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
PEM-Based Algorithm Info Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
BSAFE1 Algorithm Info Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Summary of AIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Keys In Crypto-C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Summary of KIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
System Considerations In Crypto-C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Algorithm Choosers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
An Encryption Algorithm Chooser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
An RSA Algorithm Chooser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
The Surrender Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
A Sample Surrender Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Saving State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
When to Allocate Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
vi RSA BSAFE Crypto-C Developer’s Guide
Memory-Management Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Memory-Management Routines and Standard C Libraries . . . . . . . . . . . . . . . . . .122
Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
BER/DER Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Symmetric Block Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
The RSA Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
General Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
Key Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
DES Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
RSA Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Using Cryptographic Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Interfacing with a BHAPI Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
PKCS #11 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Using a PKCS #11 Device with Crypto-C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
PKCS #11 Support for DSA Key Pair Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
Advanced PKCS #11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Hardware Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
Chapter 5 Non-Cryptographic Operations 151
Message Digests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Creating a Digest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
BER-Encoding the Digest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Saving the State of a Digest Algorithm Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Saved State. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
Hash-Based Message Authentication Code (HMAC) . . . . . . . . . . . . . . . . . . . . . . . 161
Generating Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Generating Random Numbers with SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Generating Independent Streams of Randomness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Converting Data Between Binary and ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Encoding Binary Data To ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
Decoding ASCII-Encoded Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Contents vii
Chapter 6 Symmetric-Key Operations 177
Block Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
DES with CBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
The RC2 Cipher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
The RC5 Cipher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
The RC6 Cipher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
The AES Cipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
Password-Based Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Decrypting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Chapter 7 Public-Key Operations 213
Performing RSA Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Generating a Key Pair. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
MultiPrime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
What is MultiPrime?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
How Many Primes?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Generating an RSA MultiPrime Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Distributing an RSA Public Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Crypto-C Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
BER/DER Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
RSA Public-Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
RSA Private-Key Decryption. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Optimal Asymetric Encryption Padding (OAEP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Raw RSA Encryption and Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
RSA Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Computing a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Verifying a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Performing DSA Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Generating DSA Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Generating a DSA Key Pair. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
DSA Signatures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Computing a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Verifying a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
viii RSA BSAFE Crypto-C Developer’ s Guide
Performing Diffie-Hellman Key Agreement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Generating Diffie-Hellman Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Distributing Diffie-Hellman Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
Crypto-C Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
BER Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Diffie-Hellman Key Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
Saving the Object State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259
Performing Elliptic Curve Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Generating Elliptic Curve Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Retrieving Elliptic Curve Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
Generating an Elliptic Curve Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
Retrieving an Elliptic Curve Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271
Generating Acceleration Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Generating a Generic Acceleration Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Generating a Public-Key Acceleration Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . .277
Performing EC Diffie-Hellman Key Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
Performing ECDSA in Compliance with ANSI X9.62. . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Generating EC Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
Generating an EC Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
Computing a Digital Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
Verifying a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
Performing ECDSA with X9.62-Compliant BER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Generating EC Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291
Generating an EC Key Pair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Computing a Digital Signature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .293
Verifying a Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296
Using ECAES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297
Using Elliptic Curve Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
Using an EC Key Pair. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
ECAES Public-Key Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298
ECAES Private-Key Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .302
Chapter 8 Secret Sharing Operations 305
Secret Sharing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Generating Shares. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305
Reconstructing the Secret . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .309
Chapter 9 Putting It All Together: An X9.31 Example 313
The X9.31 Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Contents ix
Appendix A Command-Line Demos 327
Overview of the Demos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
Command-Line Demo User’s Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
BDEMO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Starting BDEMO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Specifying User Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
Using BDEMO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
BDEMODSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Running BDEMODSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Using BDEMODSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
BDEMOEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Running BDEMOEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Using BDEMOEC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
File Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
BSLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Glossary 339
Index 349
x RSA BSAFE Crypto-C Developer’ s Guide
List of Figures
Figure 3-1 Symmetric-Key Encryption and Decryption . . . . . . . . . . . . . . . . . . . . 36
Figure 3-2 Triple DES Encryption as Implemented in Crypto-C. . . . . . . . . . . . . . 38
Figure 3-3 Electronic Codebook (ECB) Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Figure 3-4 Cipher-Block Chaining (CBC) Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Figure 3-5 Cipher Feedback (CFB) Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Figure 3-6 Output Feedback Mode (OFB) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Figure 3-7 RC4 Encryption or Decryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Figure 3-8 DES Key and IV Generation for Password Based Encryption . . . . . . 50
Figure 3-9 Public-Key Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Figure 3-10 Digital Envelope. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 3-11 RSA Digital Signature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Figure 3-12 The Diffie-Hellman Key Agreement Protocol . . . . . . . . . . . . . . . . . . 63
Figure 3-13 Elliptic Curve Diffie-Hellman Key Agreement . . . . . . . . . . . . . . . . . . 79
Figure 3-14 Secret Sharing — Key Share Assignment . . . . . . . . . . . . . . . . . . . . 81
Figure 3-15 Secret Sharing — Full Key Generation From Shares . . . . . . . . . . . . 81
Figure 4-1 Algorithm Object in a Software Implementation . . . . . . . . . . . . . . 132
Figure 4-2 Algorithm Object in a Hardware Implementation . . . . . . . . . . . . . . 133
xi
xii RSA BSAFE Crypto-C Developer’s Guide
List of Tables
Table 3-1 Calculation of 827 mod 55. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Table 3-2 Elliptic Curve Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Table 3-3 DES Weak and Semi-Weak Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Table 3-4 Summary of Recommended Key Sizes . . . . . . . . . . . . . . . . . . . . . . . 98
Table 4-1 Message Digests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Table 4-2 Message Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Table 4-3 ASCII Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Table 4-4 Pseudo-Random Number Generation . . . . . . . . . . . . . . . . . . . . . . . 104
Table 4-5 Symmetric Stream Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Table 4-6 Symmetric Block Ciphers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Table 4-7 RSA Public-Key Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Table 4-8 DSA Public-Key Cryptography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Table 4-9 Diffie-Hellman Key Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Table 4-10 Elliptic Curve Public-Key Cryptography . . . . . . . . . . . . . . . . . . . . . . 110
Table 4-11 Bloom-Shamir Secret Sharing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Table 4-12 Hardware Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Table 4-13 Advanced Encryption Standard (AES) . . . . . . . . . . . . . . . . . . . . . . . 112
Table 4-14 Generic Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Table 4-15 Block Cipher Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Table 4-16 RSA Public and Private Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Table 4-17 DSA Public and Private Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Table 4-18 Elliptic Curve Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Table 4-19 Token Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Table 4-20 Input Limits for RSA PKCS Encryption . . . . . . . . . . . . . . . . . . . . . . . 127
Table 5-1 Code Sample: DigestDataSavedState() . . . . . . . . . . . . . . . . . . . . . 159
Table A-1 Demo Program Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
xiii
xiv RSA BSAFE Crypto-C Developer’s Guide
Preface
Dear Crypto-C Developer:
Congratulations on your purchase of RSA BSAFE®
the-art in cryptographic software toolkits. Crypto-C provides developers with the
most important privacy, authentication, and data integrity routines. Crypto-C
contains a full palette of popular cryptographic algorithms. This software
development kit enables you to develop applications for a wide range of purposes,
including electronic commerce, home banking, Webcasting, and enterprise security.
RSA BSAFE®
software for enabling applications to share encrypted information, verify the
correspondent’s authenticity, and confirm data integrity. RSA Security’s generalpurpose cryptography software has the flexibility to suit a wide variety of security
applications or services. This robust, fully supported product is from the most trusted
name in e-security: RSA Security.
Crypto-C is written in C and is intended to be completely portable. It is available on a
number of platforms and can be ported to most platforms with a minimum of effort.
Crypto-C is a toolkit, not an application; it is intended to be integrated into operating
systems, communications systems, and other applications. Therefore, you have a
modest amount of work ahead of you. We have tried to make this task as clear as
possible without limiting your options. This User’s Manual, with its code samples and
tutorials, is the best place to start.
Crypto-C 5.2.2 is the latest version of RSA Security’s cryptographic
Crypto-C (Crypto-C), the state-of-
Thanks, and welcome to the RSA Security family.
Sincerely,
The Crypto-C Development Team
RSA Security
xv
What’s New in Version 5.2.2?
What’s New in Version 5.2.2?
Following is a list of RSA BSAFE Crypto-C features that are new in version 5.2.2:
Improved performance
With the new performance improvements, you’ll be able to use RSA BSAFE CryptoC’s algorithms at unprecedented levels of speed and throughput across a wide range
of hardware platforms. RSA BSAFE Crypto-C’s support for the Intel Itanium™ and
Pentium™4 processors will allow developers the ability to take advantage of benefits
of these powerful processors. Also, RSA Security’s implementation of Compaq’s
patented MultiPrime technology is designed to process encryption/decryption tasks
more than two times faster than previous methods. Typical tasks where customers
will experience these performance enhancements are for SSL transactions (signing on
the server or client side) and non-repudiation operations (verifying on the client side).
Hardware support
RSA BSAFE Crypto-C products include PKCS #11 hardware support to allow
communication with hardware like smart cards (for secure key storage) and
cryptographic accelerator cards (for performance improvements). PKCS #11 support
is in addition to the BHAPI hardware support offered in previous versions of CryptoC.
MultiPrime RSA
MultiPrime RSA functionality has been added to Crypto-C v5.2. Use this new
function to generate RSA public/private key pairs. RSA MultiPrime key generation
follows the same steps as standard RSA key generation with two exceptions: the use
of a different AI, AI_RSAMultiPrimeKeyGen, and a different AM must be passed in
during the B_GenerateInit call: AM_RSA_MULTI_PRIME_KEY_GEN.
Serialization for algorithm objects performing RC4, Diffie Hellman key exchange
A new algorithm information type, AI_RC4Serialize, has been added to Crypto-C
xvi RSA BSAFE Crypto-C Developer’s Guide
Organization of This Manual
V5.2. Use this AI to save the internal state of an RC4 encryption or decryption object,
or to create a new object from the saved state of a previous RC4 object.
Advanced Encryption Standard (AES)
Crypto-C includes basic AES support for the cutting edge in processor technology:
Intel Itanium and Pentium 4.
Organization of This Manual
This manual is organized as follows:
• Chapter 1, “Introduction,” introduces the Crypto-C toolkit. It lists the algorithms,
cryptographic standards, NIST standards, and ANSI X9 standards used in
Crypto-C.
• Chapter 2, “Quick Start,” uses a code example to describe the basic encryption
and decryption operations in Crypto-C.
• Chapter 3, “Cryptography,” presents a brief outline of the basic cryptographic
principles and terminology that are used in this manual.
• Chapter 4, “Using Crypto-C,” presents a brief description of the Crypto-C
algorithm info types and key info types by functionality. It also covers system
considerations when using Crypto-C.
• Chapters 5-8 present sample code for the major Crypto-C operations.
• Chapter 9, “Putting it all Together: An X9.31 Example,” presents sample code for
the steps involved in creating and verifying RSA digital signatures in accordance
with the X9.31 standard.
• Appendix A, “Command-Line Demos,” describes the three Crypto-C command
line demo applications: BDEMO, BDEMODSA, and BDEMOEC.
• Glossary
• Index
Preface xvii
Conventions Used in This Manual
Conventions Used in This Manual
The following typographical conventions are used in this manual.
Italic is used for:
• new terms where they are introduced
• the names of manuals and books
Lucida Typewriter Sans is used for:
• anything that appears literally in a C program, such as the names of structures
and functions supplied by Crypto-C: for example,
B_DecodeInit
Lucida Typewriter Sans Italic
is used for:
• function parameters and placeholders that indicate that an item is replaced by
some actual value in your own program: for example,
Lucida Typewriter Bold
is used for:
randomAlgorithm
• text the user types in command line demos and text that is printed to the screen
by the demos (Appendix A only)
Structures and routines defined by Crypto-C are boxed. Direct quotes from the RSA
BSAFE Crypto-C Reference Manual are also boxed:
/* Structures defined by Crypto-C */
Crypto-C procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal;
Application code and samples are displayed in a box with a shaded outline:
/* Application code and samples */
Some Crypto-C functions are only available when used with a hardware
application that has a BSAFE Hardware API interface (BHAPI). These
functions are marked with the icon of a hammer.
xviii RSA BSAFE Crypto-C Developer’s Guide
Terms and Abbreviations
Terms and Abbreviations
The following table lists terms and abbreviations used in this document. Refer to the
Glossary for a list of security and cryptographic terms and abbreviations, along with
their definitions, that are used throughout the RSA BSAFE Crypto-C documentation
set.
Term or Abbreviation Definition
Crypto-C RSA BSAFE Crypto-C: Cryptographic software development kit developers
use to develop secure applications.
.doc (file) Word for Windows, version 6.x or version 7.x files.
.htm (file) Hypertext Markup Language formatted files used for releasing documents on
the RSA Security internet site.
.pdf (file) Portable Document Format created by Adobe Acrobat Distiller and read by
using Adobe Acrobat Reader.
.rtf (file) Rich Text Format files that are compatable with Microsoft Word for Windows.
.txt (file) Unformatted, cross-platform text files.
PKI The Public Key Infrastructure that combines private key, trust, and certificate
databases for the reserve of needed private keys and certificates for signing
or encrypting messages.
Public Client API The default application programming interface between PKI services and the
developer's application.
SPI Service provider interfaces that enable customized implementation to
augment or replace the default Cert-J functionality.
User Interface Any interface that the end user sees or accesses. This includes any HTML
browser-based interfaces
Preface xix
Related Documents
Related Documents
Following is a list of documents referenced in this book and suggested material for
further reading.
1. The Public-Key Cryptography Standards (PKCS), RSA Laboratories.
(
http://www.rsasecurity.com/rsalabs/PKCS/)
2. Frequently Asked Questions (FAQ) About Today’s Cryptography, RSA Laboratories.
(http://www.rsasecurity.com/rsalabs/faq/)
3. The following Internet Standard documents:
• RFCs 1421, 1422, 1423, 1424 on Privacy Enhancement for Internet
Electronic Mail.
• RFCs 1319 (MD2), 1321 (MD5).
4. The following CCITT Recommendation documents:
• X.690: Specifications for the Basic Encoding Rules (BER) for Abstract
Notation One (ASN.1).
• X.509: The Directory — Authentication Framework.
5. Rivest, Shamir, and Adleman, A method for obtaining digital signatures and
public-key cryptosystems. Communications of the ACM, 21(2):120-126, February
1978.
6. A. Shamir, How to share a secret. Communications of the ACM, 22(11):
612-613, November 1979.
7. W. Diffie and M. E. Hellman, New directions in cryptography. IEEE Transactions
on Information Theory, IT-22:644-654, 1976.
8. Data Encryption Standard, FIPS Pub 46-2, National Institute of Standards and
Technology. Available from
9. DES Modes of Operations, FIPS Pub 81, National Institute of Standards and
Technology, 1980.
10. Digital Signature Standard and Secure Hashing Algorithm (DSS and SHA):
• FIPS Pub 180-1
• X9.30 Part III
11. The following reports from RSA Laboratories (http://www.rsasecurity.com/
rsalabs/technotes
and http://www.rsasecurity.com/rsalabs/bulletins):
• Stream Ciphers
• MD2, MD4, MD5, SHA and Other Hash Functions
• On Pseudo-collisions in MD5
http://www.nist.gov.itl/div897/pubs/index.htm.
xx RSA BSAFE Crypto-C Developer’s Guide
Related Documents
• Results from the RSA Factoring Challenge
• Recommendations on Elliptic Curve Cryptosystems
• Recent Results for MD2, MD4, and MD5
12. The following OAEP specifications:
• SET Secure Electronic Transaction Specification. Book 3: Formal Protocol
Definition, version 1.0. SETCo, 1997. (
http://www.setco.org/)
• PKCS#1: RSA Cryptography Specifications. Version 2.0. RSA Security, 1998.
(
http://www.rsasecurity.com/rsalabs/pkcs/)
13. The following ANSI Financial Services Industry documents:
• X9.31 (RSA signatures, reversible DSA)
• X9.52 Draft (Triple DES)
• X9.62 and X9.63 (Elliptic Curves)
14. IEEE Standard Specifications for Public-Key Cryptography on
http://stdsbbs.ieee.org/groups/1363/index.html.
15. B. Schneier, Applied Cryptography, John Wiley & Sons, Inc., New York, 1994.
16. G. Simmons, Contemporary Cryptography, IEEE Press.
17. Alfred J. Menezes, Paul C. van Oorschot, and Scott A. Vanstone. Handbook of
Applied Cryptography. CRC Press, 1996. Chapter 2 of this book, which covers all
aspects of modern cryptography, provides mathematical background on finite
fields.
18. A. Menezes, I. Blake, X. Gao, R. Mullin, S. Vanstone, and T. Yaghoobian.
Applications of Finite Fields. Kluwer Academic Publishers, 1993. Provides further
reference material on finite fields, including techniques for representing elements.
19. A. Menezes, Elliptic Curve Public Key Cryptosystems, Kluwer Academic Publishers,
1993.
20. Joseph H. Silverman and John Tate, Rational Points on Elliptic Curves, Springer-
Verlag New York, Inc., 1992.
Preface xxi
How to Contact RSA Security
How to Contact RSA Security
RSA Security Web Site
You can visit the RSA Security Web site at http://www.rsasecurity.com. It contains
the latest RSA Security news, security bulletins, and information about coming
events.
RSA BSAFE product information is available at
products/bsafe
http://www.rsasecurity.com/rsalabs/faq.
. RSA Laboratories’ Cryptography FAQ can also be found at
http://www.rsasecurity.com/
Getting Support and Service
You can get technical support as follows:
SecurCare® Online
www.rsasecurity.com/securcare/index.html
Technical Support Telephone Numbers
www.rsasecurity.com/support/news/tollfree.html
Call Handling and Escalation Process
www.rsasecurity.com/support/news/escproc.html
xxii RSA BSAFE Crypto-C Developer’s Guide
Chapter 1
Introduction
This chapter introduces the Crypto-C toolkit. It lists the algorithms, cryptographic
standards, NIST standards, and ANSI X9 standards used in Crypto-C. This chapter is
organized as follows:
• The Crypto-C Toolkit
- Algorithms
- Hardware Support
• Cryptographic Standards and Crypto-C
- PKCS Standards and Crypto-C
- NIST Standards and Crypto-C
-PKCS Compared with NIST
- ANSI X9 Standards and Crypto-C
1
The Crypto-C Toolkit
The Crypto-C Toolkit
Crypto-C provides developers with a state-of-the-art implementation of the most
important privacy, authentication, and data integrity routines.
Algorithms
The following algorithms are implemented in Crypto-C:
Symmetric Ciphers
• AES
• DES
• Triple DES
• DESX
• RC2® block cipher
• RC4® stream cipher
• RC5™ block cipher
• RC6™ block cipher
Message Digests
• MD
• MD2
• MD5
• SHA1
Message Authentication
• HMAC
Random-Number Generation
• MD2
• MD5
• SHA1
• X931
2 RSA BSAFE Crypto-C Developer’s Guide
Public-Key Algorithms
• RSA Public Key Cryptosystem
• Diffie-Hellman Key Agreement
Digital Signatures
• DSA
• RSA Digital Signatures
Elliptic Curve Public-Key Algorithms
• Elliptic Curve Digital Signature Algorithm (ECDSA)
• Elliptic Curve Diffie-Hellman Key Agreement
• Elliptic Curve Authenticated Encryption Scheme (ECAES)
Secret Sharing
• Bloom-Shamir Secret Sharing
The Crypto-C Toolkit
Hardware Support
In addition to the cryptographic algorithms listed here, Crypto-C offers a hardware
interface that allows vendors of cryptographic hardware to support the Crypto-C
API. One such vendor is Intel®, whose Intel hardware security primitives include the
Intel Random Number Generator.
For information on using the Intel hardware (when present) with Crypto-C, see the
Intel Security Hardware User’s Guide, included on the Crypto-C CD-ROM. For
information about using Crypto-C with other cryptographic hardware, contact the
specific hardware vendor.
RSA BSAFE Crypto-C products include PKCS #11 hardware support to allow
communication with hardware like smart cards (for secure key storage) and
cryptographic accelerator cards (for performance improvements). PKCS #11 support
is in addition to the BHAPI hardware support offered in previous versions of CryptoC.
Chapter 1 Introduction 3
Cryptographic Standards and Crypto-C
Cryptographic Standards and Crypto-C
PKCS Standards and Crypto-C
Crypto-C is a general-purpose programming tool that developers can use to write a
wide variety of applications. Crypto-C was built to help developers implement the
Public-Key Cryptography Standards (PKCS), a series of documents that specify a
standard way of performing basic cryptographic operations. Several higher-level
standards, such as S/MIME, SET, IPSec, and SSL, require implementation of various
PKCS standards. Since Crypto-C complies with PKCS standards, developers should
find it fairly easy to integrate Crypto-C into software that implements the PKCS
standards.
For copies of the PKCS documents, see the PKCS section of RSA Security’s Web site at
http://www.rsasecurity.com/rsalabs/pkcs, or contact our sales department for a
PKCS diskette.
NIST Standards and Crypto-C
Certain Crypto-C releases may be used to produce applications that are compliant
with the Federal Information Processing Standards. Compliance with the FIPS
standards is often required by government agencies and contractors. The National
Institute of Standards and Technologies (NIST) establishes the FIPS standards, and
certifies FIPS-compliant applications.
As changes are made in a new release, RSA Security may need to reapply for NIST
certification. If you need to verify whether or not a specific release is compliant with
FIPS, contact your sales representative.
NIST Approval and Windows 32-bit Platforms
If you require NIST approval for your Windows 32-bit applications, you may benefit
from using the FIPS-compliant Crypto-C algorithms listed following this paragraph.
NIST may approve the use of these algorithms in your application without requiring
further algorithm-level testing of your application, based on the algorithm certificates
issued to Crypto-C. For more information, see the algorithm compliance Web site
provided by NIST.
Crypto-C includes the following FIPS-compliant algorithms:
4 RSA BSAFE Crypto-C Developer’s Guide
Cryptographic Standards and Crypto-C
• Secure Hash Algorithm (SHA1), as specified in FIPS PUB 180-1, Secure Hash
Standard (SHS)
• RSA Digital Signatures (rDSA), as specified in FIPS PUB 186-2
• Digital Signature Algorithm (DSA), as specified in FIPS PUB 186, Digital
Signature Standard (DSS)
• Data Encryption Standard (DES), as specified in FIPS PUB 46-2
• DES Modes of Operation, as specified in FIPS PUB 81
NIST Approval and Windows NT Platforms
If you require NIST approval for your Windows NT applications, you may benefit
from using the “Crypto-C Cryptographic Services Module,” a DLL that is compliant
with the FIPS 140-1 standard. NIST may approve the use of this module in your
application without requiring further testing of your application, based on the NIST
certification issued to the Crypto-C module. For more information, see the \FIPS140
folder on the Crypto-C CD-ROM for Windows NT.
PKCS Compared with NIST
In some cases, such as the RSA algorithm, the PKCS standards differ from the NIST
standards. In such cases, the standard you choose depends primarily on the scope of
your application and how it will be deployed.
As mentioned previously, the PKCS standards, many of which have been in place for
a long time, have widespread acceptance and are used as the base for many other
higher-level standards (for example, S/MIME, SET, IPSec, and SSL). Therefore, if you
are implementing one of these higher-level standards, or if you want compatibility
with other applications that use the PKCS standards, you should use the PKCS-based
implementation.
However, the United States government may have specific standards requirements
for certain government agencies and for government contractors. These are usually
the standards as defined by NIST. If you are creating applications for U.S.
government use, you should ensure that you are in compliance with any required
protocols.
Chapter 1 Introduction 5
Cryptographic Standards and Crypto-C
ANSI X9 Standards and Crypto-C
Crypto-C also complies with a number of standards established by the X9 Financial
Services Industry committee of the American National Standards Institute (ANSI). If
you are writing a financial or government application that must comply with one of
the X9 standards, you may benefit by using Crypto-C. This release is fully compliant
with the following ANSI X9 standards:
• The ANSI X9.31 Standard, which specifies an implementation of RSA Digital
Signatures (rDSA). (Note that this implementation also complies with the NIST
standard for rDSA, specified in FIPS PUB 186-2, as mentioned previously.)
• The ANSI X9.62 Standard, which specifies an implementation of the Elliptic
Curve Digital Signature Algorithm (ECDSA).
For more information, see the X9 Web site at
http://www.x9.org.
6 RSA BSAFE Crypto-C Developer’s Guide
Chapter 2
Quick Start
This chapter provides an introduction to using Crypto-C. You are first presented with
the Crypto-C model and then you are presented an introductory example. This
chapter is organized as follows:
• The Six-Step Sequence
• Introductory Example
• Decrypting the Introductory Example
• Multiple Updates
• Summary of the Six Steps
7
The Six-Step Sequence
The Six-Step Sequence
The Crypto-C model generally follows a six-step sequence:
1. Create
2. Set
3. Init
4. Update
5. Final
6. Destroy
In addition, for every application, you must include the necessary header files; we
will call this Step 0.
The six-step sequence makes it easier to maintain your code. For example, if you have
implemented a message digest routine using MD2 and wish to use SHA1 instead, you
simply need to make changes in Steps 2 and 3, Set and Init. The rest of your code can
be reused. Similarly, if you originally programmed a routine under the assumption
that it would get all the data from a single buffer, and you want to modify it to take
data from multiple buffers, you can simply change Step 4, Update.
Note: In some cases, an algorithm may not require an Update step.
The sections in this chapter show the following:
• A six-step encryption example
• A six-step decryption example
• An example using multiple Updates
• A summary of the six-step process
8 RSA BSAFE Crypto-C Developer’s Guide
Loading...