Internet DRAFT - draft-baldwin-bsafe
draft-baldwin-bsafe
HTTP/1.1 200 OK
Date: Mon, 08 Apr 2002 22:40:27 GMT
Server: Apache/1.3.20 (Unix)
Last-Modified: Wed, 12 May 1999 12:40:00 GMT
ETag: "2e7d6b-8ef34-373976a0"
Accept-Ranges: bytes
Content-Length: 585524
Connection: close
Content-Type: text/plain
RSA Working Group B. Baldwin
Internet Draft A. Wilson
Expiration Date: November 17, 1999 S. Nishimura
Category: Informational M. Yurovitsky
RSA Data Security, Inc.
May 1999
BSAFE CRYPTOGRAPHIC SECURITY COMPONENTS
<draft-baldwin-bsafe-00.txt>
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 except that the right to
produce derivative works is not granted.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six
months and may be updated, replaced, or obsoleted by other documents
at any time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1idabstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This memo provides information for the Internet community. This memo
does not specify an Internet standard of any kind. Distribution of
this memo is unlimited.
Abstract
This Internet-Draft describes protocols, procedures, and conventions
to be employed by peers implementing a generic cryptographic
application program interface. Version 4.0 of this API was
implemented inside RSA Data Security, Inc.'s BSAFE product. The API
provides a model for implementing symmetric ciphers, message digests,
message authentication, random number generation, public-key
algorithms, digital signatures, and secret sharing. The API is
documented here for the benefit of others who might also adopt and
use the API, thus providing increased portability of security
applications.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 1]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Copyright Notice
Copyright (C) The Internet Society (1998). All Rights Reserved.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 2]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Table of Contents
1. Introduction....................................................32
1.1 Organization..............................................32
1.2 The BSAFE Environment.....................................32
1.3 Code Example..............................................33
1.4 The Algorithm Object......................................35
1.5 The Key Object............................................35
1.6 The Algorithm Chooser.....................................36
1.6.1 Defining an Algorithm Chooser......................36
1.7 The Surrender Function....................................37
1.7.1 Surrender..........................................38
1.8 The ITEM Structure........................................38
2. Algorithm Info Types............................................38
2.1 Description of subsections following each algorithm
info type.................................................38
2.1.1 Purpose............................................38
2.1.2 Type of information this allows you to use:........39
2.1.3 Format of info supplied to B_SetAlgorithmInfo:.....39
2.1.4 Format of info returned by B_GetAlgorithmInfo:.....39
2.1.5 BSAFE procedures to use with algorithm object:.....39
2.1.6 Algorithm methods to include in application's
algorithm chooser: ................................39
2.1.7 Key info types for keyObject:......................39
2.1.8 Compatible representation:.........................39
2.1.9 Input constraints:.................................39
2.1.10 Output considerations:............................40
2.2 AI_BSSecretSharing........................................40
2.2.1 Purpose:...........................................40
2.2.2 Type of information this allows you to use:........40
2.2.3 Format of info supplied to B_SetAlgorithmInfo:.....40
2.2.4 Format of info returned by B_GetAlgorithmInfo:.....40
2.2.5 BSAFE procedures to use with algorithm object:.....40
2.2.6 Output considerations:.............................41
2.3 AI_CBC_IV8................................................41
2.3.1 Purpose:...........................................41
2.3.2 Type of information this allows you to use:........41
2.3.3 Format of info supplied to B_SetAlgorithmInfo:.....41
2.3.4 Format of info returned by B_GetAlgorithmInfo:.....42
2.3.5 BSAFE procedures to use with algorithm object:.....42
2.4 AI_DES_CBC_IV8............................................42
2.4.1 Purpose:...........................................42
2.4.2 Type of information this allows you to use:........42
2.4.3 Format of info supplied to B_SetAlgorithmInfo:.....42
2.4.4 Format of info returned by B_GetAlgorithmInfo:.....42
2.4.5 BSAFE procedures to use with algorithm object:.....42
2.4.6 Algorithm methods to include in application's
algorithm chooser: ................................43
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 3]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.4.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................43
2.4.9 Token-based algorithm methods:.....................43
2.5 AI_DES_CBCPadBER..........................................43
2.5.1 Purpose:...........................................43
2.5.2 Type of information this allows you to use:........43
2.5.3 Format of info supplied to B_SetAlgorithmInfo:.....43
2.5.4 Format of info returned by B_GetAlgorithmInfo:.....44
2.5.5 BSAFE procedures to use with algorithm object:.....44
2.5.6 Algorithm methods to include in application's
algorithm chooser: ................................44
2.5.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................44
2.5.8 Compatible representation:.........................44
2.5.9 Output considerations:.............................44
2.6 AI_DES_CBCPadIV8..........................................44
2.6.1 Purpose:...........................................44
2.6.2 Type of information this allows you to use:........44
2.6.3 Format of info supplied to B_SetAlgorithmInfo:.....45
2.6.4 Format of info returned by B_GetAlgorithmInfo:.....45
2.6.5 BSAFE procedures to use with algorithm object:.....45
2.6.6 Algorithm methods to include in application's
algorithm chooser: ................................45
2.6.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................45
2.6.8 Compatible representation:.........................45
2.6.9 Output considerations:.............................45
2.7 AI_DES_CBCPadPEM..........................................45
2.7.1 Purpose:...........................................45
2.7.2 Type of information this allows you to use:........46
2.7.3 Format of info supplied to B_SetAlgorithmInfo:.....46
2.7.4 Format of info returned by B_GetAlgorithmInfo:.....46
2.7.5 BSAFE procedures to use with algorithm object:.....46
2.7.6 Algorithm methods to include in application's
algorithm chooser: ................................46
2.7.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................46
2.7.9 Output considerations:.............................46
2.8 AI_DES_EDE3_CBC_IV8.......................................46
2.8.1 Purpose:...........................................47
2.8.2 Type of information this allows you to use:........47
2.8.3 Format of info supplied to B_SetAlgorithmInfo:.....47
2.8.4 Format of info returned by B_GetAlgorithmInfo:.....47
2.8.5 BSAFE procedures to use with algorithm object:.....47
2.8.6 Algorithm methods to include in application's
algorithm chooser: ................................47
2.8.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................47
2.8.8 Input constraints:.................................47
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 4]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.8.9 Token-based algorithm methods:.....................47
2.9 AI_DES_EDE3_CBCPadBER.....................................48
2.9.1 Purpose:...........................................48
2.9.2 Type of information this allows you to use:........48
2.9.3 Format of info supplied to B_SetAlgorithmInfo:.....48
2.9.4 Format of info returned by B_GetAlgorithmInfo:.....48
2.9.5 BSAFE procedures to use with algorithm object:.....48
2.9.6 Algorithm methods to include in application's
algorithm chooser: ................................48
2.9.8 Compatible representation:.........................49
2.9.9 Output considerations:.............................49
2.10 AI_DES_EDE3_CBCPadIV8....................................49
2.10.1 Purpose:..........................................49
2.10.2 Type of information this allows you to use:.......49
2.10.3 Format of info supplied to B_SetAlgorithmInfo:....49
2.10.4 Format of info returned by B_GetAlgorithmInfo:....49
2.10.5 BSAFE procedures to use with algorithm object:....49
2.10.6 Algorithm methods to include in application's
algorithm .........................................49
chooser:..................................................49
2.10.8 Compatible representation:........................50
2.10.9 Output considerations:............................50
2.11 AI_DESX_CBC_IV8..........................................50
2.11.1 Purpose:..........................................50
2.11.2 Type of information this allows you to use:.......50
2.11.3 Format of info supplied to B_SetAlgorithmInfo:....50
2.11.4 Format of info returned by B_GetAlgorithmInfo:....50
2.11.5 BSAFE procedures to use with algorithm object:....50
2.11.6 Algorithm methods to include in application's
algorithm .........................................51
chooser:..................................................51
2.11.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................51
2.11.8 Input constraints:................................51
2.12 AI_DESX_CBCPadBER........................................51
2.12.1 Purpose:..........................................51
2.12.2 Type of information this allows you to use:.......51
2.12.3 Format of info supplied to B_SetAlgorithmInfo:....51
2.12.4 Format of info returned by B_GetAlgorithmInfo:....52
2.12.5 BSAFE procedures to use with algorithm object:....52
chooser:..................................................52
2.12.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................52
2.12.8 Compatible representation:........................52
2.12.9 Output considerations:............................52
2.13 AI_DESX_CBCPadIV8........................................52
2.13.1 Purpose:..........................................52
2.13.2 Type of information this allows you to use:.......52
2.13.3 Format of info supplied to B_SetAlgorithmInfo:....53
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 5]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.13.4 Format of info returned by B_GetAlgorithmInfo:....53
2.13.5 BSAFE procedures to use with algorithm object:....53
chooser:..................................................53
2.13.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................53
2.13.8 Compatible representation:........................53
2.13.9 Output considerations:............................53
2.14 AI_DHKeyAgree............................................53
2.14.2 Type of information this allows you to use:.......53
2.14.3 Format of info supplied to B_SetAlgorithmInfo:....54
2.14.4 Format of info returned by B_GetAlgorithmInfo:....54
2.14.5 BSAFE procedures to use with algorithm object:....54
2.14.6 Algorithm methods to include in application's
algorithm .........................................54
chooser:..................................................54
2.14.7 Compatible representation:........................54
2.14.8 Output considerations:............................54
2.15 AI_DHKeyAgreeBER.........................................54
2.15.1 Purpose:..........................................54
2.15.2 Type of information this allows you to use:.......55
2.15.3 Format of info supplied to B_SetAlgorithmInfo:....55
2.15.4 Format of info returned by B_GetAlgorithmInfo:....55
2.15.5 BSAFE procedures to use with algorithm object:....55
2.15.6 Algorithm methods to include in application's
algorithm .........................................55
chooser:..................................................55
2.15.7 Compatible representation:........................55
2.15.8 Output considerations:............................55
2.16 AI_DHParamGen............................................56
2.16.1 Purpose:..........................................56
2.16.2 Type of information this allows you to use:.......56
2.16.3 Format of info supplied to B_SetAlgorithmInfo:....56
2.16.5 BSAFE procedures to use with algorithm object:....56
2.16.6 Algorithm methods to include in application's
algorithm .........................................56
chooser:..................................................56
2.17 AI_DSA...................................................56
2.17.1 Purpose:..........................................56
2.17.2 Type of information this allows you to use:.......57
2.17.3 Format of info supplied to B_SetAlgorithmInfo:....57
2.17.4 Format of info returned by B_GetAlgorithmInfo:....57
2.17.5 BSAFE procedures to use with algorithm object:....57
2.17.6 Algorithm methods to include in application's
algorithm .........................................57
chooser:..................................................57
2.17.7 Key info types for keyObject in B_SignInit:.......57
2.17.8 Key info types for keyObject in B_VerifyInit:.....57
2.17.9 Input constraints:................................57
2.17.10 Output considerations:...........................57
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 6]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.17.11 Token-based algorithm methods:...................57
2.18 AI_DSAKeyGen.............................................58
2.18.1 Purpose:..........................................58
2.18.2 Type of information this allows you to use:.......58
2.18.3 Format of info supplied to B_SetAlgorithmInfo:....58
2.18.4 Format of info returned by B_GetAlgorithmInfo:....58
2.18.5 BSAFE procedures to use with algorithm object:....58
2.18.6 Algorithm methods to include in application's
algorithm .........................................58
chooser:..................................................58
2.19 AI_DSAParamGen...........................................59
2.19.1 Purpose:..........................................59
2.19.2 Type of information this allows you to use:.......59
2.19.3 Format of info supplied to B_SetAlgorithmInfo:....59
2.19.4 Format of info returned by B_GetAlgorithmInfo:....59
2.19.5 BSAFE procedures to use with algorithm object:....59
2.19.6 Algorithm methods to include in application's
algorithm .........................................59
2.19.7 Notes:............................................59
2.20 AI_DSAWithSHA1...........................................59
2.20.1 Purpose:..........................................59
2.20.2 Type of information this allows you to use:.......60
2.20.3 Format of info supplied to B_SetAlgorithmInfo:....60
2.20.4 Format of info returned by B_GetAlgorithmInfo:....60
2.20.5 BSAFE procedures to use with algorithm object:....60
2.20.6 Algorithm methods to include in application's
algorithm .........................................60
chooser:..................................................60
2.20.7 Key info types for keyObject in B_SignInit:.......60
2.20.8 Key info types for keyObject in B_VerifyInit:.....60
2.20.9 Compatible representation:........................60
2.20.10 Output considerations:...........................60
2.21 AI_DSAWithSHA1_BER.......................................61
2.21.1 Purpose:..........................................61
2.21.2 Type of information this allows you to use:.......61
2.21.3 Format of info supplied to B_SetAlgorithmInfo:....61
2.21.4 Format of info returned by B_GetAlgorithmInfo:....61
2.21.5 BSAFE procedures to use with algorithm object:....61
2.21.6 Algorithm methods to include in application's
algorithm .........................................61
chooser:..................................................61
2.21.7 Key info types for keyObject in B_SignInit:.......61
2.21.8 Key info types for keyObject in B_VerifyInit:.....62
2.21.9 Compatible representation:........................62
2.21.10 Output considerations:...........................62
2.22 AI_ECAcceleratorTable....................................62
2.22.1 Purpose:..........................................62
2.22.2 Type of information this allows you to use:.......62
2.22.3 Format of info supplied to B_SetAlgorithmInfo:....62
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 7]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.22.4 Format of info returned by B_GetAlgorithmInfo:....62
2.22.5 BSAFE procedures to use with algorithm object:....62
2.22.6 Algorithm methods to include in application's
algorithm .........................................63
chooser:..................................................63
2.23 AI_ECBuildAcceleratorTable...............................63
2.23.1 Purpose:..........................................63
2.23.2 Type of information this allows you to use:.......63
2.23.3 Format of info supplied to B_SetAlgorithmInfo:....63
2.23.4 Format of info returned by B_GetAlgorithmInfo:....64
2.23.5 BSAFE procedures to use with algorithm object:....64
2.23.6 Algorithm methods to include in application's
algorithm .........................................64
chooser:..................................................64
2.23.7 Output Considerations:............................64
2.24 AI_ECBuildPubKeyAccelTable...............................64
2.24.1 Purpose:..........................................64
2.24.2 Type of information this allows you to use:.......64
2.24.3 Format of info supplied to B_SetAlgorithmInfo:....64
2.24.4 Format of info returned by B_GetAlgorithmInfo:....65
2.24.6 Algorithm methods to include in application's
algorithm .........................................65
chooser:..................................................65
2.24.7 Output Considerations:............................65
2.25 AI_EC_DHKeyAgree.........................................65
2.25.1 Purpose:..........................................65
2.25.2 Type of information this allows you to use:.......65
2.25.3 Format of info supplied to B_SetAlgorithmInfo:....65
2.25.4 Format of info returned by B_GetAlgorithmInfo:....66
2.25.5 BSAFE procedures to use with algorithm object:....66
2.25.6 Algorithm methods to include in application's
algorithm .........................................66
chooser:..................................................66
2.25.7 Output considerations:............................66
2.26 AI_EC_DSA................................................66
2.26.1 Purpose:..........................................66
2.26.2 Type of information this allows you to use:.......67
2.26.3 Format of info supplied to B_SetAlgorithmInfo:....67
2.26.4 Format of info returned by B_GetAlgorithmInfo:....67
2.26.5 BSAFE procedures to use with algorithm object:....67
2.26.6 Algorithm methods to include in application's
algorithm .........................................67
chooser:..................................................67
2.26.7 Key info types for keyObject in B_SignInit:.......67
2.26.8 Key info types for keyObject in B_VerifyInit:.....67
2.26.9 Input constraints:................................67
2.26.10 Output considerations:...........................68
2.27 AI_EC_DSAWithDigest......................................68
2.27.1 Purpose:..........................................68
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 8]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.27.2 Type of information this allows you to use:.......68
2.27.3 Format of info supplied to B_SetAlgorithmInfo:....68
2.27.4 Format of info returned by B_GetAlgorithmInfo:....68
2.27.5 BSAFE procedures to use with algorithm object:....68
2.27.6 Algorithm methods to include in application's
algorithm .........................................69
chooser:..................................................69
2.27.7 Key info types for keyObject in B_SignInit:.......69
2.27.8 Key info types for keyObject in B_VerifyInit:.....69
2.27.9 Output considerations:............................69
2.28 AI_EC_ES.................................................69
2.28.1 Purpose:..........................................69
2.28.2 Type of information this allows you to use:.......69
2.28.3 Format of info supplied to B_SetAlgorithmInfo:....69
2.28.4 Format of info returned by B_GetAlgorithmInfo:....69
2.28.5 BSAFE procedures to use with algorithm object:....70
2.28.6 Algorithm methods to include in application's
algorithm .........................................70
chooser:..................................................70
2.28.7 Output Considerations:............................70
2.29 AI_ECKeyGen..............................................70
2.29.1 Purpose:..........................................70
2.29.2 Type of information this allows you to use:.......70
2.29.4 Format of info returned by B_GetAlgorithmInfo:....71
2.29.5 BSAFE procedures to use with algorithm object:....71
2.29.6 Algorithm methods to include in application's
algorithm .........................................71
chooser:..................................................71
2.30 AI_ECParameters..........................................71
2.30.1 Purpose:..........................................71
2.30.2 Type of information this allows you to use:.......71
2.30.3 Format of info supplied to B_SetAlgorithmInfo:....71
2.30.4 Format of info returned by B_GetAlgorithmInfo:....72
2.30.5 BSAFE procedures to use with algorithm object:....72
2.30.6 Algorithm methods to include in application's
algorithm .........................................72
chooser:..................................................72
2.31 AI_ECParamGen............................................72
2.31.1 Purpose:..........................................72
2.31.2 Type of information this allows you to use:.......72
2.31.4 Format of info returned by B_GetAlgorithmInfo:....74
2.31.5 BSAFE procedures to use with algorithm object:....74
2.31.6 Algorithm methods to include in application's
algorithm .........................................74
chooser:..................................................74
2.31.7 Notes:............................................75
2.32 AI_ECPubKey..............................................75
2.32.1 Purpose:..........................................75
2.32.2 Type of information this allows you to use:.......75
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 9]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.32.3 Format of info supplied to B_SetKeyInfo:..........75
2.32.4 Format of info returned by B_GetAlgorithmInfo:....75
2.32.5 Can get this info type if algorithm object
already has: ......................................75
2.33 AI_FeedbackCipher........................................76
2.33.1 Purpose:..........................................76
2.33.2 Type of information this allows you to use:.......76
2.33.3 Format of info supplied to B_SetAlgorithmInfo:....76
2.33.4 Format of info returned by B_GetAlgorithmInfo:....76
2.33.5 Type of padding schemes available:................76
2.33.6 BSAFE procedures to use with algorithm object:....77
2.33.7 Algorithm methods to include in application's
algorithm .........................................77
chooser:..................................................77
2.33.9 Compatible representations:.......................80
2.33.10 Output considerations:...........................80
2.34 AI_HMAC..................................................80
2.34.1 Purpose:..........................................80
2.34.2 Type of information this allows you to use:.......80
2.34.3 Format of info supplied to B_SetAlgorithmInfo:....80
2.34.4 Format of info returned by B_GetAlgorithmInfo:....81
2.34.5 BSAFE procedures to use with algorithm object:....81
2.34.6 Algorithm methods to include in application's
algorithm .........................................81
chooser:..................................................81
2.34.7 Output considerations:............................81
2.35 AI_HW_RANDOM.............................................81
2.35.1 Purpose:..........................................81
2.35.2 Type of information this allows you to use:.......81
2.35.3 Format of info supplied to B_SetAlgorithmInfo:....81
2.35.4 Format of info returned by B_GetAlgorithmInfo:....81
2.35.5 BSAFE procedures to use with algorithm object:....81
2.35.6 Algorithm methods to include in application's
algorithm .........................................82
chooser:..................................................82
2.35.7 Notes:............................................82
2.36 AI_KeypairTokenGen.......................................82
2.36.1 Purpose:..........................................82
2.36.2 Type of information this allows you to use:.......82
2.36.3 Format of info supplied to B_SetAlgorithmInfo:....82
2.36.4 Format of info returned by B_GetAlgorithmInfo:....83
2.36.5 BSAFE procedures to use with algorithm object:....83
2.36.6 Algorithm methods to include in application's
algorithm .........................................83
2.36.7 Notes:............................................83
2.37 AI_MAC...................................................84
2.37.1 Purpose:..........................................84
2.37.2 Type of information this allows you to use:.......84
2.37.3 Format of info supplied to B_SetAlgorithmInfo:....84
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 10]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.37.4 Format of info returned by B_GetAlgorithmInfo:....84
2.37.5 BSAFE procedures to use with algorithm object:....84
2.37.6 Algorithm methods to include in application's
algorithm .........................................84
2.37.7 Output considerations:............................84
2.38 AI_MD2...................................................84
2.38.1 Purpose:..........................................84
2.38.2 Type of information this allows you to use:.......85
2.38.3 Format of info supplied to B_SetAlgorithmInfo:....85
2.38.4 Format of info returned by B_GetAlgorithmInfo:....85
2.38.5 BSAFE procedures to use with algorithm object:....85
2.38.6 Algorithm methods to include in application's
algorithm .........................................85
2.38.7 Compatible representation:........................85
2.38.8 Output considerations:............................85
2.39 AI_MD2_BER...............................................85
2.39.1 Purpose:..........................................85
2.39.2 Type of information this allows you to use:.......86
2.39.3 Format of info supplied to B_SetAlgorithmInfo:....86
2.39.4 Format of info returned by B_GetAlgorithmInfo:....86
2.39.5 BSAFE procedures to use with algorithm object:....86
2.39.6 Algorithm methods to include in application's
algorithm .........................................86
2.39.7 Compatible representation:........................86
2.39.8 Output considerations:............................86
2.40 AI_MD2_PEM...............................................86
2.40.1 Purpose:..........................................86
2.40.2 Type of information this allows you to use:.......87
2.40.3 Format of info supplied to B_SetAlgorithmInfo:....87
2.40.4 Format of info returned by B_GetAlgorithmInfo:....87
2.40.5 BSAFE procedures to use with algorithm object:....87
2.40.6 Algorithm methods to include in application's
algorithm .........................................87
2.40.7 Compatible representation:........................87
2.40.8 Output considerations:............................87
2.41 AI_MD2Random..............................................87
2.41.1 Purpose:..........................................87
2.41.2 Type of information this allows you to use:.......88
2.41.3 Format of info supplied to B_SetAlgorithmInfo:....88
2.41.4 Format of info returned by B_GetAlgorithmInfo:....88
2.41.5 BSAFE procedures to use with algorithm object:....88
2.41.6 Algorithm methods to include in application's
algorithm .........................................88
2.42 AI_MD2WithDES_CBCPad.....................................88
2.42.1 Purpose:..........................................88
2.42.2 Type of information this allows you to use:.......89
2.42.3 Format of info supplied to B_SetAlgorithmInfo:....89
2.42.4 Format of info returned by B_GetAlgorithmInfo:....89
2.42.5 BSAFE procedures to use with algorithm object:....89
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 11]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.42.6 Algorithm methods to include in application's
algorithm .........................................89
2.42.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................89
2.42.8 Compatible representation:........................89
2.42.9 Output considerations:............................89
2.43 AI_MD2WithDES_CBCPadBER..................................89
2.43.1 Purpose:..........................................89
2.43.2 Type of information this allows you to use:.......90
2.43.3 Format of info supplied to B_SetAlgorithmInfo:....90
2.43.4 Format of info returned by B_GetAlgorithmInfo:....90
2.43.5 BSAFE procedures to use with algorithm object:....90
2.43.6 Algorithm methods to include in application's
algorithm .........................................90
2.44 AI_MD2WithRC2_CBCPad.....................................91
2.44.1 Purpose:..........................................91
2.44.2 Type of information this allows you to use:.......91
2.44.3 Format of info supplied to B_SetAlgorithmInfo:....91
2.44.4 Format of info returned by B_GetAlgorithmInfo:....91
2.44.5 BSAFE procedures to use with algorithm object:....91
2.44.6 Algorithm methods to include in application's
algorithm .........................................92
2.44.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................92
2.44.8 Compatible representation:........................92
2.44.9 Output considerations:............................92
2.45 AI_MD2WithRC2_CBCPadBER..................................92
2.45.1 Purpose:..........................................92
2.45.2 Type of information this allows you to use:.......92
2.45.3 Format of info supplied to B_SetAlgorithmInfo:....92
2.45.4 Format of info returned by B_GetAlgorithmInfo:....93
2.45.5 BSAFE procedures to use with algorithm object:....93
2.45.6 Algorithm methods to include in application's
algorithm .........................................93
2.45.8 Compatible representation:........................93
2.45.9 Output considerations:............................93
2.46 AI_MD2WithRSAEncryption..................................93
2.46.1 Purpose:..........................................93
2.46.2 Type of information this allows you to use:.......93
2.46.3 Format of info supplied to B_SetAlgorithmInfo:....94
2.46.4 Format of info returned by B_GetAlgorithmInfo:....94
2.46.5 BSAFE procedures to use with algorithm object:....94
2.46.6 Algorithm methods to include in application's
algorithm .........................................94
2.46.7 Key info types for keyObject in B_SignInit:.......94
2.46.8 Key info types for keyObject in B_VerifyInit:.....94
2.46.9 Compatible representation:........................94
2.46.10 Output considerations:...........................94
2.46.11 Notes:...........................................94
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 12]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.47 AI_MD2WithRSAEncryptionBER...............................95
2.47.1 Purpose:..........................................95
2.47.2 Type of information this allows you to use:.......95
2.47.4 Format of info returned by B_GetAlgorithmInfo:....95
2.47.5 BSAFE procedures to use with algorithm object:....95
2.47.6 Algorithm methods to include in application's
algorithm .........................................95
2.47.7 Key info types for keyObject in B_SignInit:.......96
2.47.8 Key info types for keyObject in B_VerifyInit:.....96
2.47.9 Compatible representation:........................96
2.47.10 Output considerations:...........................96
2.47.11 Notes:...........................................96
2.48 AI_MD5...................................................96
2.48.1 Purpose:..........................................96
2.48.2 Type of information this allows you to use:.......96
2.48.3 Format of info supplied to B_SetAlgorithmInfo:....96
2.48.4 Format of info returned by B_GetAlgorithmInfo:....97
2.48.5 BSAFE procedures to use with algorithm object:....97
2.48.6 Algorithm methods to include in application's
algorithm .........................................97
2.48.7 Compatible representation:........................97
2.48.8 Output considerations:............................97
2.49 AI_MD5_BER...............................................97
2.49.1 Purpose:..........................................97
2.49.2 Type of information this allows you to use:.......97
2.49.3 Format of info supplied to B_SetAlgorithmInfo:....98
2.49.4 Format of info returned by B_GetAlgorithmInfo:....98
2.49.5 BSAFE procedures to use with algorithm object:....98
2.49.6 Algorithm methods to include in application's
algorithm .........................................98
2.49.7 Compatible representation:........................98
2.49.8 Output considerations:............................98
2.50 AI_MD5_PEM...............................................98
2.50.1 Purpose:..........................................98
2.50.2 Type of information this allows you to use:.......99
2.50.3 Format of info supplied to B_SetAlgorithmInfo:....99
2.50.4 Format of info returned by B_GetAlgorithmInfo:....99
2.50.5 BSAFE procedures to use with algorithm object:....99
2.50.6 Algorithm methods to include in application's
algorithm .........................................99
2.50.7 Compatible representation:........................99
2.50.8 Output considerations:............................99
2.51 AI_MD5Random.............................................99
2.51.1 Purpose:..........................................99
2.51.2 Type of information this allows you to use:.......100
2.51.3 Format of info supplied to B_SetAlgorithmInfo:....100
2.51.4 Format of info returned by B_GetAlgorithmInfo:....100
2.51.5 BSAFE procedures to use with algorithm object:....100
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 13]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.51.6 Algorithm methods to include in application's
algorithm .........................................100
2.52 AI_MD5WithDES_CBCPad.....................................100
2.52.1 Purpose:..........................................100
2.52.2 Type of information this allows you to use:.......101
2.52.3 Format of info supplied to B_SetAlgorithmInfo:....101
2.52.4 Format of info returned by B_GetAlgorithmInfo:....101
2.52.5 BSAFE procedures to use with algorithm object:....101
2.52.6 Algorithm methods to include in application's
algorithm .........................................102
2.52.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................102
2.52.8 Compatible representation:........................102
2.52.9 Output considerations:............................102
2.53 AI_MD5WithDES_CBCPadBER..................................102
2.53.1 Purpose:..........................................102
2.53.2 Type of information this allows you to use:.......102
2.53.3 Format of info supplied to B_SetAlgorithmInfo:....102
2.53.4 Format of info returned by B_GetAlgorithmInfo:....103
2.53.5 BSAFE procedures to use with algorithm object:....103
2.53.6 Algorithm methods to include in application's
algorithm .........................................103
2.53.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................103
2.53.8 Compatible representation:........................103
2.53.9 Output considerations:............................103
2.54 AI_MD5WithRC2_CBCPad.....................................103
2.54.1 Purpose:..........................................103
2.54.2 Type of information this allows you to use:.......104
2.54.3 Format of info supplied to B_SetAlgorithmInfo:....104
2.54.4 Format of info returned by B_GetAlgorithmInfo:....104
2.54.5 BSAFE procedures to use with algorithm object:....104
2.54.6 Algorithm methods to include in application's
algorithm .........................................105
2.54.8 Compatible representation:........................105
2.54.9 Output considerations:............................105
2.55 AI_MD5WithRC2_CBCPadBER..................................105
2.55.1 Purpose:..........................................105
2.55.2 Type of information this allows you to use:.......105
2.55.3 Format of info supplied to B_SetAlgorithmInfo:....106
2.55.4 Format of info returned by B_GetAlgorithmInfo:....106
2.55.5 BSAFE procedures to use with algorithm object:....106
2.55.6 Algorithm methods to include in application's
algorithm .........................................106
2.55.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................106
2.55.8 Compatible representation:........................106
2.55.9 Output considerations:............................106
2.56 AI_MD5WithRSAEncryption..................................106
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 14]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.56.1 Purpose:..........................................107
2.56.2 Type of information this allows you to use:.......107
2.56.3 Format of info supplied to B_SetAlgorithmInfo:....107
2.56.4 Format of info returned by B_GetAlgorithmInfo:....107
2.56.5 BSAFE procedures to use with algorithm object:....107
2.56.6 Algorithm methods to include in application's
algorithm .........................................107
2.56.7 Key info types for keyObject in B_SignInit:.......108
2.56.8 Key info types for keyObject in B_VerifyInit:.....108
2.56.9 Compatible representation:........................108
2.56.10 Output considerations:...........................108
2.56.11 Notes:...........................................108
2.57 AI_MD5WithRSAEncryptionBER...............................108
2.57.2 Type of information this allows you to use:.......108
2.57.3 Format of info supplied to B_SetAlgorithmInfo:....109
2.57.4 Format of info returned by B_GetAlgorithmInfo:....109
2.57.5 BSAFE procedures to use with algorithm object:....109
2.57.6 Algorithm methods to include in application's
algorithm .........................................109
2.57.7 Key info types for keyObject in B_SignInit:.......109
2.57.8 Key info types for keyObject in B_VerifyInit:.....109
2.57.9 Compatible representation:........................109
2.57.10 Output considerations:...........................110
2.57.11 Notes:...........................................110
2.58 AI_MD5WithXOR............................................110
2.58.1 Purpose:..........................................110
2.58.2 Type of information this allows you to use:.......110
2.58.3 Format of info supplied to B_SetAlgorithmInfo:....110
2.58.4 Format of info returned by B_GetAlgorithmInfo:....110
2.58.5 BSAFE procedures to use with algorithm object:....111
2.58.6 Algorithm methods to include in application's
algorithm .........................................111
2.58.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................111
2.58.8 Compatible representation:........................111
2.59 AI_MD5WithXOR_BER........................................111
2.59.1 Purpose:..........................................111
2.59.2 Type of information this allows you to use:.......111
2.59.3 Format of info supplied to B_SetAlgorithmInfo:....112
2.59.4 Format of info returned by B_GetAlgorithmInfo:....112
2.59.5 BSAFE procedures to use with algorithm object:....112
2.59.6 Algorithm methods to include in application's
algorithm .........................................112
2.59.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................112
2.59.8 Compatible representation:........................112
2.60 AI_PKCS_OAEP_RSAPrivate..................................112
2.60.1 Purpose:..........................................112
2.60.2 Type of information this allows you to use:.......113
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 15]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.60.3 Format of info supplied to B_SetAlgorithmInfo:....113
2.60.4 Format of info supplied to B_GetAlgorithmInfo:....114
2.60.5 BSAFE procedures to use with algorithm object:....114
2.60.6 Algorithm methods to include in application's
algorithm .........................................115
2.60.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................115
2.60.8 Compatible representation:........................115
2.60.9 Output considerations:............................115
2.61 AI_PKCS_OAEP_RSAPrivateBER...............................115
2.61.1 Purpose:..........................................115
2.61.2 Type of information this allows you to use:.......115
2.61.3 Format of info supplied to B_SetAlgorithmInfo:....116
2.61.4 Format of info supplied to B_GetAlgorithmInfo:....118
2.61.5 BSAFE procedures to use with algorithm object:....118
2.61.6 Algorithm methods to include in application's
algorithm .........................................118
2.61.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................118
2.61.8 Compatible representation:........................118
2.61.9 Output considerations:............................118
2.62 AI_PKCS_OAEP_RSAPublic...................................118
2.62.1 Purpose:..........................................118
2.62.2 Type of information this allows you to use:.......119
2.62.3 Format of info supplied to B_SetAlgorithmInfo:....119
2.62.4 Format of info supplied to B_GetAlgorithmInfo:....120
2.62.5 BSAFE procedures to use with algorithm object:....120
2.62.6 Algorithm methods to include in application's
algorithm .........................................121
2.62.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................121
2.62.8 Compatible representation:........................121
2.62.9 Input constraints:................................121
2.62.10 Output considerations:...........................121
2.63 AI_PKCS_OAEP_RSAPublicBER................................121
2.63.1 Purpose:..........................................121
2.63.2 Type of information this allows you to use:.......122
2.63.3 Format of info supplied to B_SetAlgorithmInfo:....122
2.63.4 Format of info supplied to B_GetAlgorithmInfo:....124
2.63.5 BSAFE procedures to use with algorithm object:....124
2.63.6 Algorithm methods to include in application's
algorithm .........................................124
2.63.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................124
2.63.8 Compatible representation:........................124
2.63.9 Input constraints:................................125
2.64 AI_PKCS_OAEPRecode.......................................125
2.64.1 Purpose:..........................................125
2.64.2 Type of information this allows you to use:.......125
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 16]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.64.3 Format of info supplied to B_SetAlgorithmInfo:....125
2.64.4 Format of info supplied to B_GetAlgorithmInfo:....127
2.64.5 BSAFE procedures to use with algorithm object:....127
2.64.6 Algorithm methods to include in application's
algorithm .........................................127
2.64.7 Compatible representation:........................127
2.64.8 Input constraints:................................127
2.64.9 Output considerations:............................127
2.65 AI_PKCS_OAEPRecodeBER....................................128
2.65.1 Purpose:..........................................128
2.65.2 Type of information this allows you to use:.......128
2.65.3 Format of info supplied to B_SetAlgorithmInfo:....128
2.65.4 Format of info supplied to B_GetAlgorithmInfo:....130
2.65.5 BSAFE procedures to use with algorithm object:....130
2.65.6 Algorithm methods to include in application's
algorithm .........................................131
2.65.7 Compatible representation:........................131
2.65.8 Input constraints:................................131
2.65.9 Output considerations:............................131
2.66 AI_PKCS_RSAPrivate.......................................131
2.66.1 Purpose:..........................................131
2.66.2 Type of information this allows you to use:.......131
2.66.3 Format of info supplied to B_SetAlgorithmInfo:....131
2.66.4 Format of info returned by B_GetAlgorithmInfo:....132
2.66.5 BSAFE procedures to use with algorithm object:....132
2.66.6 Algorithm methods to include in application's
algorithm .........................................132
2.66.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................132
2.66.8 Compatible representation:........................132
2.66.9 Input constraints:................................132
2.66.10 Output considerations:...........................132
2.67 AI_PKCS_RSAPrivateBER....................................132
2.67.1 Purpose:..........................................132
2.67.2 Type of information this allows you to use:.......133
2.67.3 Format of info supplied to B_SetAlgorithmInfo:....133
2.67.4 Format of info returned by B_GetAlgorithmInfo:....133
2.67.5 BSAFE procedures to use with algorithm object:....133
2.67.6 Algorithm methods to include in application's
algorithm .........................................133
2.67.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................134
2.67.8 Compatible representation:........................134
2.67.9 Input constraints:................................134
2.67.10 Output considerations:...........................134
2.68 AI_PKCS_RSAPrivatePEM....................................134
2.68.1 Purpose:..........................................134
2.68.2 Type of information this allows you to use:.......134
2.68.3 Format of info supplied to B_SetAlgorithmInfo:....134
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 17]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.68.4 Format of info returned by B_GetAlgorithmInfo:....135
2.68.5 BSAFE procedures to use with algorithm object:....135
2.68.6 Algorithm methods to include in application's
algorithm .........................................135
2.68.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................135
2.68.8 Compatible representation:........................135
2.68.9 Input constraints:................................135
2.68.10 Output considerations:...........................135
2.69 AI_PKCS_RSAPublic........................................136
2.69.1 Purpose:..........................................136
2.69.2 Type of information this allows you to use:.......136
2.69.3 Format of info supplied to B_SetAlgorithmInfo:....136
2.69.4 Format of info returned by B_GetAlgorithmInfo:....136
2.69.5 BSAFE procedures to use with algorithm object:....136
2.69.6 Algorithm methods to include in application's
algorithm .........................................136
2.69.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................136
2.69.8 Compatible representation:........................136
2.69.9 Input constraints:................................137
2.69.10 Output considerations:...........................137
2.70 AI_PKCS_RSAPublicBER.....................................137
2.70.1 Purpose:..........................................137
2.70.2 Type of information this allows you to use:.......137
2.70.3 Format of info supplied to B_SetAlgorithmInfo:....137
2.70.4 Format of info returned by B_GetAlgorithmInfo:....137
2.70.5 BSAFE procedures to use with algorithm object:....137
2.70.6 Algorithm methods to include in application's
algorithm .........................................138
2.70.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................138
2.70.8 Compatible representation:........................138
2.70.9 Input constraints:................................138
2.70.10 Output considerations:...........................138
2.71 AI_PKCS_RSAPublicPEM.....................................138
2.71.1 Purpose:..........................................138
2.71.2 Type of information this allows you to use:.......138
2.71.3 Format of info supplied to B_SetAlgorithmInfo:....139
2.71.4 Format of info returned by B_GetAlgorithmInfo:....139
2.71.5 BSAFE procedures to use with algorithm object:....139
2.71.6 Algorithm methods to include in application's
algorithm .........................................139
2.71.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................139
2.71.8 Compatible representation:........................139
2.71.9 Input constraints:................................139
2.71.10 Output considerations:...........................140
2.72 AI_RC2_CBC...............................................140
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 18]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.72.1 Purpose:..........................................140
2.72.2 Type of information this allows you to use:.......140
2.72.3 Format of info supplied to B_SetAlgorithmInfo:....140
2.72.4 Format of info returned by B_GetAlgorithmInfo:....140
2.72.5 BSAFE procedures to use with algorithm object:....140
2.72.6 Algorithm methods to include in application's
algorithm .........................................140
2.72.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................141
2.72.8 Input constraints:................................141
2.72.9 Token-based algorithm methods:....................141
2.73 AI_RC2_CBCPad............................................141
2.73.1 Purpose:..........................................141
2.73.2 Type of information this allows you to use:.......141
2.73.3 Format of info supplied to B_SetAlgorithmInfo:....141
2.73.4 Format of info returned by B_GetAlgorithmInfo:....141
2.73.5 BSAFE procedures to use with algorithm object:....142
2.73.6 Algorithm methods to include in application's
algorithm .........................................142
2.73.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................142
2.73.8 Compatible representation:........................142
2.73.9 Output considerations:............................142
2.74 AI_RC2_CBCPadBER.........................................142
2.74.1 Purpose:..........................................142
2.74.2 Type of information this allows you to use:.......142
2.74.3 Format of info supplied to B_SetAlgorithmInfo:....142
2.74.4 Format of info returned by B_GetAlgorithmInfo:....143
2.74.5 BSAFE procedures to use with algorithm object:....143
2.74.6 Algorithm methods to include in application's
algorithm .........................................143
2.74.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................143
2.74.8 Compatible representation:........................143
2.74.9 Output considerations:............................143
2.75 AI_RC2_CBCPadPEM.........................................143
2.75.1 Purpose:..........................................143
2.75.2 Type of information this allows you to use:.......144
2.75.3 Format of info supplied to B_SetAlgorithmInfo:....144
2.75.4 Format of info returned by B_GetAlgorithmInfo:....144
2.75.5 BSAFE procedures to use with algorithm object:....144
2.75.6 Algorithm methods to include in application's
algorithm .........................................144
2.75.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................144
2.75.8 Compatible representation:........................144
2.75.9 Output considerations:............................144
2.76 AI_RC4...................................................144
2.76.1 Purpose:..........................................145
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 19]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.76.2 Type of information this allows you to use:.......145
2.76.3 Format of info supplied to B_SetAlgorithmInfo:....145
2.76.4 Format of info returned by B_GetAlgorithmInfo:....145
2.76.5 BSAFE procedures to use with algorithm object:....145
2.76.6 Algorithm methods to include in application's
algorithm .........................................145
2.76.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................145
2.76.8 Compatible representation:........................145
2.76.9 Token-based algorithm methods:....................145
2.77 AI_RC4_BER...............................................146
2.77.1 Purpose:..........................................146
2.77.2 Type of information this allows you to use:.......146
2.77.3 Format of info supplied to B_SetAlgorithmInfo:....146
2.77.4 Format of info returned by B_GetAlgorithmInfo:....146
2.77.5 BSAFE procedures to use with algorithm object:....146
2.77.6 Algorithm methods to include in application's
algorithm .........................................146
2.77.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................147
2.77.8 Compatible representation:........................147
2.78 AI_RC4WithMAC............................................147
2.78.1 Purpose:..........................................147
2.78.2 Type of information this allows you to use:.......147
2.78.3 Format of info supplied to B_SetAlgorithmInfo:....147
2.78.4 Format of info returned by B_GetAlgorithmInfo:....148
2.78.5 BSAFE procedures to use with algorithm object:....148
2.78.6 Algorithm methods to include in application's
algorithm .........................................148
2.78.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................148
2.78.8 Compatible representation:........................148
2.78.9 Output considerations:............................148
2.78.10 Token-based algorithm methods:...................148
2.79 AI_RC4WithMAC_BER........................................148
2.79.1 Purpose:..........................................148
2.79.2 Type of information this allows you to use:.......149
2.79.3 Format of info supplied to B_SetAlgorithmInfo:....149
2.79.4 Format of info returned by B_GetAlgorithmInfo:....149
2.79.5 BSAFE procedures to use with algorithm object:....149
2.79 6 Algorithm methods to include in application's
algorithm .........................................149
2.79.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................149
2.79.8 Compatible representation:........................150
2.79.9 Output considerations:............................150
2.80 AI_RC5_CBC...............................................150
2.80.1 Purpose:..........................................150
2.80.2 Type of information this allows you to use:.......150
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 20]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.80.3 Format of info supplied to B_SetAlgorithmInfo:....150
2.80.4 Format of info returned by B_GetAlgorithmInfo:....150
2.80.5 BSAFE procedures to use with algorithm object:....150
2.80.6 Algorithm methods to include in application's
algorithm .........................................151
2.80.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................151
2.80.8 Input Constraints:................................151
2.80.9 Token-based algorithm methods:....................151
2.81 AI_RC5_CBCPad............................................151
2.81.1 Purpose:..........................................151
2.81.2 Type of information this allows you to use:.......151
2.81.4 Format of info returned by B_GetAlgorithmInfo:....152
2.81.5 BSAFE procedures to use with algorithm object:....152
2.81.6 Algorithm methods to include in application's
algorithm .........................................152
2.81.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................152
2.81.8 Compatible representation:........................152
2.81.9 Output considerations:............................152
2.82 AI_RC5_CBCPadBER.........................................152
2.82.1 Purpose:..........................................152
2.82.2 Type of information this allows you to use:.......153
2.82.3 Format of info supplied to B_SetAlgorithmInfo:....153
2.82.4 Format of info returned by B_GetAlgorithmInfo:....153
2.82.5 BSAFE procedures to use with algorithm object:....153
2.82.6 Algorithm methods to include in application's
algorithm .........................................153
2.82.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................153
2.82.8 Compatible representation:........................153
2.82.9 Output considerations:............................153
2.83 AI_RESET_IV..............................................153
2.83.1 Purpose:..........................................154
2.83.2 Type of Information this allows you to use:.......154
2.83.3 Format of info supplied to B_SetAlgorithmInfo.....154
2.83.4 Format of info returned by B_GetAlgorithmInfo
returns ...........................................154
2.83.5 BSAFE procedures to use with algorithm object:....154
2.83.6 Algorithm methods to include in chooser...........154
2.84 AI_RFC1113Recode.........................................154
2.84.1 Purpose:..........................................154
2.84.2 Type of information this allows you to use:.......155
2.84.3 Format of info supplied to B_SetAlgorithmInfo:....155
2.84.4 Format of info returned by B_GetAlgorithmInfo:....155
2.84.5 BSAFE procedures to use with algorithm object:....155
2.84.6 Output considerations:............................155
2.85 AI_RSAKeyGen.............................................155
2.85.1 Purpose:..........................................155
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 21]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.85.2 Type of information this allows you to use:.......155
2.85.3 Format of info supplied to B_SetAlgorithmInfo:....155
2.85.4 Format of info returned by B_GetAlgorithmInfo:....156
2.85.5 BSAFE procedures to use with algorithm object:....156
2.84.6 Algorithm methods to include in application's
algorithm .........................................156
2.86 AI_RSAPrivate............................................156
2.86.1 Purpose:..........................................156
2.86.2 Type of information this allows you to use:.......156
2.86.3 Format of info supplied to B_SetAlgorithmInfo:....157
2.86.4 Format of info returned by B_GetAlgorithmInfo:....157
2.86.5 BSAFE procedures to use with algorithm object:....157
2.86.6 Algorithm methods to include in application's
algorithm .........................................157
2.86.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................157
2.86.8 Input constraints:................................157
2.86.9 Token-based algorithm methods:....................157
2.87 AI_RSAPublic.............................................157
2.87.1 Purpose:..........................................157
2.87.2 Type of information this allows you to use:.......158
2.87.3 Format of info supplied to B_SetAlgorithmInfo:....158
2.87.4 Format of info returned by B_GetAlgorithmInfo:....158
2.87.5 BSAFE procedures to use with algorithm object:....158
2.86.6 Algorithm methods to include in application's
algorithm .........................................158
2.87.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................158
2.87.8 Input constraints:................................158
2.87.9 Token-based algorithm methods:....................159
2.88 AI_RSAStrongKeyGen.......................................159
2.88.1 Purpose:..........................................159
2.88.2 Type of information this allows you to use:.......159
2.88.3 Format of info supplied to B_SetAlgorithmInfo:....159
2.88.4 Format of info returned by B_GetAlgorithmInfo:....159
2.88.5 BSAFE procedures to use with algorithm object:....160
2.88.6 Algorithm methods to include in application's
algorithm .........................................160
2.89 AI_SET_OAEP_RSAPrivate..............................160
2.89.1 Purpose:..........................................160
2.89.3 Format of info supplied to B_SetAlgorithmInfo:....160
2.89.4 Format of info returned by B_GetAlgorithmInfo:....160
2.89.5 BSAFE procedures to use with algorithm object:....160
2.89.6 Algorithm methods to include in application's
algorithm .........................................161
2.89.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................161
2.89.8 Input considerations:.............................161
2.89.9 Output considerations:............................161
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 22]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.90 AI_SET_OAEP_RSAPublic....................................161
2.90.1 Purpose:..........................................161
2.90.2 Type of information this allows you to use:.......162
2.90.3 Format of info supplied to B_SetAlgorithmInfo:....162
2.90.4 Format of info returned by B_GetAlgorithmInfo:....162
2.90.5 BSAFE procedures to use with algorithm object:....162
2.90.6 Algorithm methods to include in application's
algorithm .........................................162
2.90.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................162
2.90.9 Output considerations:............................162
2.91 AI_SHA1..................................................163
2.91.1 Purpose:..........................................163
2.91.2 Type of information this allows you to use:.......163
2.91.3 Format of info supplied to B_SetAlgorithmInfo:....163
2.91.4 Format of info returned by B_GetAlgorithmInfo:....163
2.91.5 BSAFE procedures to use with algorithm object:....163
2.91.6 Algorithm methods to include in application's
algorithm .........................................163
2.91.7 Compatible representation:........................163
2.91.8 Output considerations:............................164
2.92 AI_SHA1_BER..............................................164
2.92.1 Purpose:..........................................164
2.92.2 Type of information this allows you to use:.......164
2.92.3 Format of info supplied to B_SetAlgorithmInfo:....164
2.92.4 Format of info returned by B_GetAlgorithmInfo:....164
2.92.5 BSAFE procedures to use with algorithm object:....164
2.92.6 Algorithm methods to include in application's
algorithm .........................................164
2.92.7 Compatible representation:........................165
2.92.8 Output considerations:............................165
2.93 AI_SHA1Random............................................165
2.93.1 Purpose:..........................................165
2.93.2 Notes:............................................165
2.94 AI_SHA1WithDES_CBCPad....................................165
2.94.1 Purpose:..........................................165
2.94.2 Type of information this allows you to use:.......166
2.94.3 Format of info supplied to B_SetAlgorithmInfo:....166
2.94.4 Format of info returned by B_GetAlgorithmInfo:....166
2.94.5 BSAFE procedures to use with algorithm object:....166
2.94.6 Algorithm methods to include in application's
algorithm .........................................167
2.94.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................167
2.94.8 Compatible representation:........................167
2.94.9 Output considerations:............................167
2.95 AI_SHA1WithDES_CBCPadBER.................................167
2.95.1 Purpose:..........................................167
2.95.2 Type of information this allows you to use:.......167
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 23]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.95.3 Format of info supplied to B_SetAlgorithmInfo:....168
2.95.4 Format of info returned by B_GetAlgorithmInfo:....168
2.95.5 BSAFE procedures to use with algorithm object:....168
2.95.6 Algorithm methods to include in application's
algorithm .........................................168
2.95.7 Key info types for keyObject in B_EncryptInit or
B_DecryptInit: ....................................168
2.95.8 Compatible representation:........................168
2.95.9 Output considerations:............................168
2.96 AI_SHA1WithRSAEncryption.................................168
2.96.1 Purpose:..........................................169
2.96.2 Type of information this allows you to use:.......169
2.96.3 Format of info supplied to B_SetAlgorithmInfo:....169
2.96.4 Format of info returned by B_GetAlgorithmInfo:....169
2.96.5 BSAFE procedures to use with algorithm object:....169
2.96.6 Algorithm methods to include in application's
algorithm .........................................169
2.96.7 Key info types for keyObject in B_SignInit:.......170
2.96.8 Key info types for keyObject in B_VerifyInit:.....170
2.96.9 Compatible representation:........................170
2.96.10 Output considerations:...........................170
2.97 AI_SHA1WithRSAEncryptionBER..............................170
2.97.1 Purpose:..........................................170
2.97.2 Type of information this allows you to use:.......170
2.97.3 Format of info supplied to B_SetAlgorithmInfo:....171
2.97.4 Format of info returned by B_GetAlgorithmInfo:....171
2.97.5 BSAFE procedures to use with algorithm object:....171
2.97.6 Algorithm methods to include in application's
algorithm .........................................171
2.97.7 Key info types for keyObject in B_SignInit:.......171
2.97.8 Key info types for keyObject in B_VerifyInit:.....171
2.97.9 Compatible representation:........................171
2.97.10 Output considerations:...........................172
2.97.11 Notes:...........................................172
2.98 AI_SignVerify............................................172
2.98.1 Purpose:..........................................172
2.98.2 Type of information this allows you to use:.......172
2.98.3 Format of info supplied to B_SetAlgorithmInfo:....172
2.98.4 Format of info returned by B_GetAlgorithmInfo:....173
2.98.5 BSAFE procedures to use with algorithm object:....173
2.98.6 Algorithm methods to include in application's
algorithm .........................................173
2.98.7 Key info types for keyObject in B_SignInit or
B_VerifyInit: .....................................173
2.99 AI_SymKeyTokenGen........................................173
2.99.1 Purpose:..........................................173
2.99.2 Type of information this allows you to use:.......173
2.99.3 Format of info supplied to B_SetAlgorithmInfo:....173
2.99.4 Format of info returned by B_GetAlgorithmInfo:....174
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 24]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.99.5 BSAFE procedures to use with algorithm object:....174
2.99.6 Algorithm methods to include in application's
algorithm .........................................174
2.99.7 Notes:............................................174
2.100 AI_X962Random_V0........................................174
2.100.1 Purpose:.........................................174
2.100.2 Type of information this allows you to use:......175
2.100.3 Format of info supplied to B_SetAlgorithmInfo:...175
2.100.4 Format of info returned by B_GetAlgorithmInfo:...175
2.100.5 BSAFE procedures to use with algorithm object:...175
2.100.6 Algorithm methods to include in application's
algorithm .........................................175
2.100.7 Notes:...........................................175
3. Key Info Types..................................................176
3.1 The format for each entry is as follows:..................176
3.1.1 Purpose:...........................................176
3.1.2 Type of information this allows you to use:........176
3.1.3 Format of info supplied to B_SetKeyInfo:...........176
3.1.4 Format of info returned by B_GetKeyInfo:...........176
3.1.5 Can get this info type if key object already has:..176
3.2 KI_8Byte..................................................176
3.2.2 Type of information this allows you to use:........177
3.2.3 Format of info supplied to B_SetKeyInfo:...........177
3.2.4 Format of info returned by B_GetKeyInfo:...........177
3.2.5 Can get this info type if key object already has:..177
3.3 KI_24Byte.................................................177
3.3.1 Purpose:...........................................177
3.3.2 Type of information this allows you to use:........177
3.3.3 Format of info supplied to B_SetKeyInfo:...........177
3.3.4 Format of info returned by B_GetKeyInfo:...........177
3.3.5 Can get this info type if key object already has:..177
3.4 KI_DES8...................................................177
3.4.2 Type of information this allows you to use:........178
3.4.3 Format of info supplied to B_SetKeyInfo:...........178
3.4.4 Format of info returned by B_GetKeyInfo:...........178
3.4.5 Can get this info type if key object already has:..178
3.4.6 Notes:.............................................178
3.5 KI_DES8Strong.............................................178
3.5.1 Purpose:...........................................178
3.5.2 Type of information this allows you to use:........178
3.5.3 Format of info supplied to B_SetKeyInfo:...........179
3.5.4 Format of info returned by B_GetKeyInfo:...........179
3.5.5 Can get this info type if key object already has:..179
3.6 KI_DES24Strong............................................179
3.6.1 Purpose:...........................................179
3.6.2 Type of information this allows you to use:........179
3.6.3 Format of info supplied to B_SetKeyInfo:...........179
3.6.4 Format of info returned by B_GetKeyInfo:...........179
3.6.5 Can get this info type if key object already has:..180
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 25]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.7 KI_DESX...................................................180
3.7.1 Purpose:...........................................180
3.7.2 Type of information this allows you to use:........180
3.7.3 Format of info supplied to B_SetKeyInfo:...........180
3.7.4 Format of info returned by B_GetKeyInfo:...........180
3.7.5 Can get this info type if key object already has:..180
3.8 KI_DSAPrivate.............................................180
3.8.1 Purpose:...........................................181
3.8.2 Type of information this allows you to use:........181
3.8.3 Format of info supplied to B_SetKeyInfo:...........181
3.8.4 Format of info returned by B_GetKeyInfo:...........181
3.8.5 Can get this info type if key object already has:..181
3.9 KI_DSAPrivateBER..........................................181
3.9.1 Purpose:...........................................181
3.9.2 Type of information this allows you to use:........182
3.9.3 Format of info supplied to B_SetKeyInfo:...........182
3.9.4 Format of info returned by B_GetKeyInfo:...........182
3.9.5 Can get this info type if key object already has:..182
3.10 KI_DSAPublic.............................................182
3.10.1 Purpose:..........................................182
3.10.2 Type of information this allows you to use:.......182
3.10.3 Format of info supplied to B_SetKeyInfo:..........182
3.10.4 Format of info returned by B_GetKeyInfo:..........183
3.10.5 Can get this info type if key object already
has: ..............................................183
3.11 KI_DSAPublicBER..........................................183
3.11.1 Purpose:..........................................183
3.11.2 Type of information this allows you to use:.......183
3.11.3 Format of info supplied to B_SetKeyInfo:..........184
3.11.4 Format of info returned by B_GetKeyInfo:..........184
3.11.5 Can get this info type if key object already
has: ..............................................184
3.12 KI_ECPrivate.............................................184
3.12.1 Purpose:..........................................184
3.12.2 Type of information this allows you to use:.......184
3.12.3 Format of info supplied to B_SetKeyInfo:..........184
3.12.4 Format of info returned by B_GetKeyInfo:..........184
3.12.5 Can get this info type if key object already
has: ..............................................185
3.13 KI_ECPrivateComponent....................................185
3.13.1 Purpose:..........................................185
3.13.2 Type of information this allows you to use:.......185
3.13.3 Format of info supplied to B_SetKeyInfo:..........185
3.13.4 Format of info returned by B_GetKeyInfo:..........185
3.13.5 Restrictions:.....................................185
3.13.6 Can get this info type if key object already
has: ..............................................185
3.14 KI_ECPublic..............................................185
3.14.1 Purpose:..........................................185
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 26]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.14.2 Type of information this allows you to use:.......185
3.14.3 Format of info supplied to B_SetKeyInfo:..........186
3.14.4 Format of info returned by B_GetKeyInfo:..........186
3.14.5 Can get this info type if key object already
has: ..............................................186
3.15 KI_ECPublicComponent.....................................186
3.15.1 Purpose:..........................................186
3.15.2 Type of information this allows you to use:.......186
3.15.3 Format of info supplied to B_SetKeyInfo:..........186
3.15.4 Format of info returned by B_GetKeyInfo:..........186
3.15.5 Restrictions:.....................................187
3.15.6 Can get this info type if key object already
has: ..............................................187
3.16 KI_ExtendedToken.........................................187
3.16.1 Purpose:..........................................187
3.16.2 Type of information this allows you to use:.......187
3.16.3 Format of info supplied to B_SetKeyInfo:..........187
3.16.4 Format of info returned by B_GetKeyInfo:..........188
3.16.5 Can get this info type if key object already
has: ..............................................188
3.16.6 Notes:............................................188
3.17 KI_Item..................................................188
3.17.1 Purpose:..........................................188
3.17.2 Type of information this allows you to use:.......188
3.17.3 Format of info supplied to B_SetKeyInfo:..........188
3.17.4 Format of info returned by B_GetKeyInfo:..........188
3.17.5 Can get this info type if key object already
has: ..............................................189
3.18 KI_KeypairToken..........................................189
3.18.1 Purpose:..........................................189
3.18.2 Type of information this allows you to use:.......189
3.18.3 Format of info supplied to B_SetKeyInfo:..........189
3.18.4 Format of info returned by B_GetKeyInfo:..........189
3.18.5 Can get this info type if key object already
has: ..............................................189
3.18.6 Notes:............................................190
3.19 KI_PKCS_RSAPrivate.......................................190
3.19.1 Purpose:..........................................190
3.19.2 Type of information this allows you to use:.......190
3.19.3 Format of info supplied to B_SetKeyInfo:..........190
3.19.4 Format of info returned by B_GetKeyInfo:..........190
3.19.5 Can get this info type if key object already
has: ..............................................191
3.20 KI_PKCS_RSAPrivateBER....................................191
3.20.1 Purpose:..........................................191
3.20.2 Type of information this allows you to use:.......191
3.20.3 Format of info supplied to B_SetKeyInfo:..........191
3.20.4 Format of info returned by B_GetKeyInfo:..........191
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 27]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.20.5 Can get this info type if key object already
has: ..............................................191
3.21 KI_RSA_CRT...............................................191
3.21.1 Purpose:..........................................192
3.21.2 Type of information this allows you to use:.......192
3.21.3 Format of info supplied to B_SetKeyInfo:..........192
3.21.4 Format of info returned by B_GetKeyInfo:..........192
3.21.5 Can get this info type if key object already
has: ..............................................192
3.22 KI_RSAPrivate............................................192
3.22.1 Purpose:..........................................192
3.22.2 Type of information this allows you to use:.......193
3.22.4 Format of info returned by B_GetKeyInfo:..........193
3.22.5 Can get this info type if key object already
has: ..............................................193
3.22.6 Note:.............................................193
3.23 KI_RSAPublic.............................................193
3.23.1 Purpose:..........................................193
3.23.2 Type of information this allows you to use:.......193
3.23.3 Format of info supplied to B_SetKeyInfo:..........194
3.23.4 Format of info returned by B_GetKeyInfo:..........194
3.23.5 Can get this info type if key object already
has: ..............................................194
3.24 KI_RSAPublicBER..........................................194
3.24.1 Purpose:..........................................194
3.24.2 Type of information this allows you to use:.......194
3.24.3 Format of info supplied to B_SetKeyInfo:..........194
3.24.4 Format of info returned by B_GetKeyInfo:..........195
3.25 KI_Token.................................................195
3.25.1 Purpose:..........................................195
3.25.2 Type of information this allows you to use:.......195
3.25.3 Format of info supplied to B_SetKeyInfo:..........195
3.25.4 Format of info returned by B_GetKeyInfo:..........195
3.25.5 Can get this info type if key object already
has: ..............................................195
3.25.6 Notes:............................................196
4. Details of BSAFE Functions......................................196
4.1 B_BuildTableFinal.........................................196
4.1.1 Return Value.......................................196
4.2 B_BuildTableGetBufSize....................................196
4.2.1 Return Value.......................................197
4.3 B_BuildTableInit..........................................197
4.3.1 Return Value.......................................197
4.4.1 Return value.......................................197
4.5 B_CreateKeyObject.........................................197
4.5.1 Return Value.......................................197
4.6 B_CreateSessionChooser....................................198
4.6.1 Return Value.......................................198
4.7 B_DecodeDigestInfo........................................198
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 28]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.7.1 Return value.......................................199
4.8 B_DecodeFinal.............................................199
4.8.1 Return value.......................................199
4.9 B_DecodeInit..............................................199
4.9.1 Return value.......................................200
4.10 B_DecodeUpdate...........................................200
4.10.1 Return value......................................200
4.11 B_DecryptFinal...........................................200
4.11.1 Return value......................................201
4.12 B_DecryptInit............................................201
4.12.1 Return value......................................201
4.13 B_DecryptUpdate..........................................201
4.13.1 Return value......................................202
4.14 B_DestroyAlgorithmObject.................................202
4.15 B_DestroyKeyObject.......................................202
4.15.1 Return value......................................203
4.16 B_DigestFinal............................................203
4.16.1 Return value......................................203
4.17 B_DigestInit.............................................203
4.17.1 Return value......................................204
4.18 B_DigestUpdate...........................................204
4.18.1 Return value......................................204
4.19 B_EncodeDigestInfo.......................................204
4.19.1 Return value......................................205
4.20 B_EncodeFinal............................................205
4.20.1 Return value......................................205
4.21 B_EncodeInit.............................................205
4.21.1 Return value......................................206
4.22 B_EncodeUpdate...........................................206
4.22.1 Return value......................................206
4.23 B_EncryptFinal...........................................206
4.23.1 Return value......................................207
4.24 B_EncryptInit............................................207
4.24.1 Return value......................................208
4.25 B_EncryptUpdate..........................................208
4.25.1 Return value......................................208
4.26 B_FreeSessionChooser.....................................208
4.26.1 Return Value......................................209
4.27 B_GenerateInit...........................................209
4.27.1 Return value......................................209
4.28 B_GenerateKeypair........................................209
4.28.1 Return value......................................210
4.29 B_GenerateParameters.....................................210
4.29.1 Return value......................................210
4.30 B_GenerateRandomBytes....................................210
4.30.1 Return value......................................211
4.31 B_GetAlgorithmInfo.......................................211
4.31.1 Return value......................................211
4.32 B_GetExtendedErrorInfo...................................211
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 29]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.32.1 Notes.............................................211
4.33 B_GetKeyExtendedErrorInfo................................212
4.33.1 Notes.............................................212
4.33.2 Return Value......................................212
4.34 B_GetKeyInfo.............................................212
4.34.1 Return value......................................213
4.35 B_IntegerBits............................................213
4.35.1 Return value......................................213
4.36 B_KeyAgreeInit...........................................213
4.36.1 Return value......................................214
4.37 B_KeyAgreePhase1.........................................214
4.38 B_KeyAgreePhase2.........................................214
4.38.1 Return value......................................215
4.39 B_RandomInit.............................................215
4.39.1 Return value......................................216
4.40 B_RandomUpdate...........................................216
4.40.1 Return value......................................216
4.41 B_SetAlgorithmInfo.......................................216
4.41.1 Return value......................................217
4.42 B_SetKeyInfo.............................................217
4.42.1 Return value......................................217
4.43 B_SignFinal..............................................217
4.43.1 Return value......................................218
4.44 B_SignInit...............................................218
4.44.1 Return value......................................218
4.45 B_SignUpdate.............................................219
4.45.1 Return value......................................219
4.46 B_SymmetricKeyGenerate...................................219
4.46.1 Return Value......................................219
4.47 B_SymmetricKeyGenerateInit...............................219
4.47.1 Return Value......................................220
4.48 B_VerifyFinal............................................220
4.48.1 Return value......................................220
4.49 B_VerifyInit.............................................220
4.49.1 Return value......................................221
4.50 B_VerifyUpdate...........................................221
4.50.1 Return value......................................221
4.51 T_free...................................................221
4.51.1 Return value......................................221
4.52 T_malloc.................................................222
4.52.1 Return value......................................222
4.53 T_memcmp.................................................222
4.53.1 Return value......................................222
4.54 T_memcpy.................................................222
4.54.1 Return value......................................223
4.55 T_memmove................................................223
4.55.1 Return value......................................223
4.56 T_memset.................................................223
4.56.1 Return value......................................223
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 30]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.57 T_realloc................................................223
4.57.1 Return value......................................224
5. Security Considerations.........................................224
5.1 Handling Private Keys.....................................224
5.2 Temporary Buffers.........................................224
5.3 Pseudo-Random Numbers and Seed Generation.................224
5.4 Choosing Passwords........................................226
5.5 Initialization Vectors and Salts..........................226
5.6 DES Weak Keys.............................................226
5.6.1 DES weak and semi-weak keys........................226
5.7 Stream Ciphers............................................227
5.8 Timing Attacks and Blinding...............................228
5.9 Choosing Key Sizes........................................229
5.9.1 Summary of Recommended Key Sizes...................230
5.9.2 RSA Keys...........................................230
5.9.3 Diffie-Hellman Parameters and DSA Keys.............231
5.9.4 RC2 Effective Key Bits.............................231
5.9.5 RC4 Key Bits.......................................231
5.9.6 RC5 Key Bits and Rounds............................231
5.9.7 Triple DES Keys....................................232
5.9.8 Elliptic Curve Keys................................232
6. References Section..............................................232
6.1 PKCS Suite................................................233
7. Authors' Address................................................234
8. Appendix A BSAFE Error Types....................................235
9. Appendix B Algorithm Details....................................237
9.1 AI_MAC....................................................237
9.2 AI_RC4WithMAC.............................................239
10. Appendix C BSAFE Header Files..................................240
10.1 BSAFE.H..................................................240
10.2 AGLOBAL.H................................................257
10.3 ATYPES.H.................................................258
10.5 STDLIBRF.H...............................................263
10.6 BSFPLATF.H...............................................264
10.7 BSFMACRO.H...............................................268
11. Trademark and Patent Issues....................................269
12. Copyright Section..............................................270
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 31]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
1. Introduction
This Internet-Draft is being distributed to members of the Internet
community in order to solicit their reactions to the proposals
contained in it. While the issues discussed may not be directly
relevant to the research problems of the Internet, they may be
interesting to a number of researchers and implementers.
1.1 Organization
This section outlines the components of the BSAFE environment using a
code example.
Sections 2 and 3 are alphabetical listings of BSAFE algorithm info
types (AIs) and key info types (KIs) that specify the exact format of
information supplied to and returned by BSAFE.
Section 4 lists BSAFE's functions alphabetically, giving full details
of calling format and error return codes.
Appendix A lists BSAFE error types.
Appendix B lists additional details about some algorithms.
Appendix C presents the header files.
1.2 The BSAFE Environment
The typical BSAFE environment consists of five components:
1. an application
2. an algorithm chooser
3. a surrender function
4. the BSAFE toolkit
5. memory management routines
These components are either application specific, platform specific,
or part of the BSAFE toolkit.
The application can be an encryption application, key-generation
application, or other similar application. The application calls
BSAFE and supplies the algorithm chooser and a callback to the
surrender function. The algorithm chooser tells BSAFE which specific
method to use for a given algorithm, and the surrender function
allows processing or canceling during lengthy operations.
The BSAFE toolkit performs the cryptographic functions such as
encryption and key generation. The toolkit is reentrant and suitable
for shared or dynamic-link libraries.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 32]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
The memory management routines perform the functions for allocating
memory (T_malloc, T_realloc and T_free) and operating on memory
(T_memcmp, T_memcpy, T_memmove, and T_memset). See Section 4,
"Details of BSAFE Functions," for descriptions and prototypes of
these functions.
These functions are modeled after conventional C library functions
such as malloc, memset, etc. Since these are calls, not callbacks,
BSAFE can be statically linked to the memory-management routines to
form a platform-specific, shared library for cryptographic
applications.
1.3 Code Example
As a way of introducing BSAFE, consider the following code example.
The example encrypts a buffer of data with a DES key, using a
function named EncryptData. The inputs to EncryptData are: a pointer
to the buffer of data, the data's length, a pointer to the 8-byte DES
key value, and a pointer to the 8-byte initialization vector used by
the DES-CBC algorithm. EncryptData writes the encrypted data to the
buffer supplied by the caller and returns the length of the encrypted
data.
#include "aglobal.h"
#include "bsafe.h"
#include "demochos.h"
#define NULL_SURRENDER_PTR ((A_SURRENDER_CTX *)NULL_PTR)
int EncryptData
(output, outputLen, maxOutputLen, input, inputLen, keyValue, iv)
unsigned char *output; /* pointer to output data */
unsigned int outputLen; /* pointer to length of encrytped data */
unsigned int maxOutputLen; /* size of output buffer */
unsigned char *input; /* pointer to input data buffer */
unsigned int inputLen; /* length of input data */
unsigned char *keyValue; /* pointer to 8-byte DES key */
unsigned char *iv; /* pointer to 8-byte initialization vector */
{
B_ALGORITHM_OBJ desAlgorithm = (B_ALGORITHM_OBJ)NULL_PTR;
B_KEY_OBJ desKey = (B_KEY_OBJ)NULL_PTR;
B_BLK_CIPHER_W_FEEDBACK_PARAMS feedbackParams;
ITEM initVector;
unsigned int partOutLen;
int status;
/* break commands jump to the end of the do while (0) block */
do {
if ((status = B_CreateKeyObject (&desKey)) != 0)
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 33]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
break;
if ((status = B_SetKeyInfo
(desKey, KI_DES8Strong, (POINTER)keyValue)) != 0)
break;
if ((status = B_CreateAlgorithmObject (&desAlgorithm)) != 0)
break;
initVector.data = iv;
initVector.len = 8;
feedbackParams.encryptionMethodName = "des";
feedbackParams.encryptionParams = NULL_PTR;
feedbackParams.feedbackMethodName = "cbc";
feedbackParams.feedbackParams = initVector;
feedbackParams.paddingMethodName = "pad";
feedbackParams.paddingParams = NULL_PTR;
if ((status = B_SetAlgorithmInfo
(desAlgorithm, (POINTER)&AI_FeedbackCipher,
(POINTER)&feedbackParams)) != 0)
break;
if ((status = B_EncryptInit
(desAlgorithm, desKey, DEMO_ALGORITHM_CHOOSER,
NULL_SURRENDER_PTR)) != 0)
break;
if ((status = B_EncryptUpdate
(desAlgorithm, output, outputLen, maxOutputLen, input,
inputLen, (B_ALGORITHM_OBJ)NULL_PTR,
NULL_SURRENDER_PTR)) != 0)
break;
if ((status = B_EncryptFinal
(desAlgorithm, output + *outputLen, &partOutLen,
maxOutputLen - *outputLen, (B_ALGORITHM_OBJ)NULL_PTR,
NULL_SURRENDER_PTR)) != 0)
break;
*outputLen += partOutLen;
} while (0);
B_KEY_OBJ desKey = (B_KEY_OBJ)NULL_PTR;
B_ALGORITHM_OBJ desAlgorithm = (B_ALGORITHM_OBJ)NULL_PTR;
return (status);
}
The main work in EncryptData is done by the functions B_EncryptInit,
B_EncryptUpdate, and B_EncryptFinal. The calling format for these and
other functions is shown in Section 4, "Details of BSAFE Functions".
Most BSAFE procedures return zero for success or one of the error
types listed in Section 8, Appendix A.
EncryptData uses DEMO_ALGORITHM_CHOOSER as the algorithmChooser
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 34]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
argument to B_EncryptInit. The algorithm chooser is described in
Section 1.6. EncryptData also uses (A_SURRENDER_CTX *)NULL_PTR as the
surrenderContext argument to B_EncryptInit, B_EncryptUpdate, and
B_EncryptFinal. As explained in Section 4, this tells BSAFE not to
call the surrender function. To use a surrender function, see Section
1.7, "The Surrender Function."
1.4 The Algorithm Object
In the example, B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal
use an algorithm object called desAlgorithm. An algorithm object is
used to hold information about an algorithm's parameters (for
example, the DES initialization vector), and to keep a context during
a cryptographic operation (for example, DES encryption).
Before it can be used by BSAFE, an algorithm object must be created
and set with B_CreateAlgorithmObject and B_SetAlgorithmInfo.
Every algorithm object that is created by B_CreateAlgorithmObject
must be destroyed by B_DestroyAlgorithmObject. For security, when
BSAFE destroys an algorithm object, it zeroizes any sensitive memory
that the object allocated, as well as freeing it. Note that an
algorithm object can be used for either encryption or decryption, but
not for both. You must create separate algorithm objects to handle
each case. Once an algorithm has been set, it should not be reset, so
that once B_SetAlgorithmInfo has been called for a particular
algorithm object, it should not be called for the same object until
it has been destroyed and recreated.
As shown in Section 4, B_SetAlgorithmInfo has three input arguments,
algorithmObject, infoType, and info. algorithmObject is the name of
the algorithm object you are setting. infoType is one of the AI
algorithm info types listed in Section 2. The algorithm info type
specifies which algorithm to use, such as DES-CBC, as well as the
format of the algorithm information supplied by info.
As shown in Section 2, the format of info supplied to
B_SetAlgorithmInfo for AI_FeedbackCipher is a pointer to a
B_BLK_CIPHER_W_FEEDBACK_PARAMS structure that holds the necessary
information for the encryption object. This data includes the
encryption method name ("des"), the feedback method name ("cbc"), and
a pointer to an ITEM structure that contains the 8 bytes of the
initialization vector. In the example, the data in the item structure
is the iv input argument to EncryptData.
1.5 The Key Object
In the example, B_EncryptInit uses a key object called desKey. A key
object is used to hold a key's value, such as the DES key, and to
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 35]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
supply this value to functions such as B_EncryptInit that need a key.
A key object is also used to receive the output of key generation
such as B_GenerateKeypair.
Before it can be used by BSAFE, a key object must be created and set
with B_CreateKeyObject and B_SetKeyInfo. Every key object that is
created by B_CreateKeyObject must be destroyed by B_DestroyKeyObject.
For security, when BSAFE destroys a key object, it zeroizes any
sensitive memory that the object allocated, as well as freeing it.
Once B_SetKeyInfo has been called for a particular key object, it
should not be called for the same object until it has been destroyed
and recreated.
As shown in Section 4, B_SetKeyInfo has two input arguments, infoType
and info. infoType is one of the KI key info types listed in Section
3. The key info type specifies the format of the key information
supplied by info.
As shown in Section 4, the format of info supplied to B_SetKeyInfo
for KI_DES8Strong is a pointer to an unsigned char array that holds
the 8-byte DES key. In the example, this is the keyValue input
argument to EncryptData.
1.6 The Algorithm Chooser
The algorithm chooser lists all the algorithm methods that BSAFE will
use in the application. In this way, only the code that is needed
will be linked in, thus reducing the executable size.
1.6.1 Defining an Algorithm Chooser
The main reason for an application to define its own algorithm
chooser is to make the executable image smaller. The linker links
in the object code for all algorithm methods that are listed in the
algorithm chooser. An application that only uses MD5 and DES-CBC may
define an algorithm chooser with only the MD5 and DES-CBC methods so
that the linker will only link in that object code.
An algorithm chooser is an array of pointers to B_ALGORITHM_METHOD
values. The last element of the array must be (B_ALGORITHM_METHOD
*)NULL_PTR. Here is an example that defines an algorithm chooser
called MD5_DES_CBC_CHOOSER for the MD5 and DES-CBC algorithm methods
that are needed when using the AI_MD5WithDES_CBCPad algorithm info
type:
B_ALGORITHM_METHOD *MD5_DES_CBC_CHOOSER[] = {
&AM_MD5,
&AM_DES_CBC_ENCRYPT,
&AM_DES_CBC_DECRYPT,
(B_ALGORITHM_METHOD *)NULL_PTR
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 36]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
};
Notice that encrypting/decrypting algorithm methods such as DES-CBC
have separate entries for the encryption method and decryption
method. So if an application only performs encryption, it may use
an algorithm chooser with only the encrypt method to prevent the
linker from linking in the object code for decryption.
Note: Early versions of BSAFE offered optimized AMs for some
algorithms on selected platforms. For instance, when employing RSA
public encryption, there were: AM_RSA_ENCRYPT, AM_RSA_ENCRYPT_68 for
the MPW compiler on 68K machines, and AM_RSA_ENCRYPT_86 for the
Microsoft compiler on x86 platforms. In versions 3.0 and higher, the
optimized code for a particular algorithm, when available, is
automatically linked in with the standard AM. So while it is no
longer necessary to specify an optimized AM to link in optimized
code, the old AMs specifying optimized code are still valid.
1.7 The Surrender Function
During lengthy operations, such as public-key computations and key
generation, BSAFE surrenders control to the application by calling
the application's surrender function. The surrender function may
notify users of the operation being performed, indicate that it is
still performing, process operating system tasks, or execute other
operations before returning to BSAFE. The surrender function may also
cause BSAFE to cancel the operation by returning a non-zero value.
The surrender function is specified to BSAFE through A_SURRENDER_CTX
values, which is supplied as the surrenderContext argument to BSAFE
functions such as B_EncryptInit. A_SURRENDER_CTX is defined as
follows:
typedef struct {
int (*Surrender) ( ); /* surrender function callback */
POINTER handle; /* application-specific information */
POINTER reserved; /* reserved for future use */
} A_SURRENDER_CTX;
An A_SURRENDER_CTX value consists of a pointer to the
application-specific callback function that constitutes BSAFE's
surrender function and a pointer to application-specific information.
The pointer to application-specific information is supplied directly
to the callback and is not otherwise manipulated by BSAFE. The
reserved value should be set to NULL_PTR for future compatibility.
A typical application initializes the A_SURRENDER_CTX value before
calling a BSAFE procedure. Each A_SURRENDER_CTX value may specify a
different surrender function callback and a different handle.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 37]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
1.7.1 Surrender
The surrender function callback must have the following form:
int (*Surrender) (
POINTER handle /* application-specific information */
);
Surrender is a developer-supplied function that actually performs the
tasks required by the application. handle is the application-specific
handle from the surrender context.
Surrender should return 0 for BSAFE to continue its operation, or a
non-zero value for BSAFE to cancel its operation.
1.8 The ITEM Structure
Often, BSAFE requires that input be in the form of an ITEM structure,
defined as follows:
typedef struct {
unsigned char *data;
unsigned int len;
} ITEM;
2. Algorithm Info Types
This section lists the standard algorithm info types (AIs) offered in
BSAFE. A typical application supplies an algorithm info type as the
infoType argument to B_SetAlgorithmInfo.
An algorithm info type not only specifies which algorithm to use, but
also specifies the format of the algorithm parameters. The algorithm
parameters are supplied as the info argument to B_SetAlgorithmInfo.
Some algorithm info types, such as encryption and signature
algorithms, need a key object. See Section 3 for details of the key
info types (KIs).
The algorithm info types pass information from and to various B_
functions. See Section 4 for the descriptions and prototypes of these
functions.
2.1 Description of subsections following each algorithm info type
2.1.1 Purpose
Describes the AI, what it is for, what it does, and how it relates
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 38]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
to similar AIs.
2.1.2 Type of information this allows you to use:
Describes the type of algorithm and parameters you can use with the
algorithm info type.
2.1.3 Format of info supplied to B_SetAlgorithmInfo:
Describes the exact format for supplying the algorithm parameters to
B_SetAlgorithmInfo. Some algorithms, such as AI_RC4, do not have
parameters; in this case, this entry will specify NULL_PTR.
2.1.4 Format of info returned by B_GetAlgorithmInfo:
Describes the exact format that B_GetAlgorithmInfo returns for the
algorithm parameters. This is generally a "cleaned up" version of the
format supplied to B_SetAlgorithmInfo. For example,
B_GetAlgorithmInfo with AI_RSAKeyGen returns the public exponent with
the leading zeros stripped off.
2.1.5 BSAFE procedures to use with algorithm object:
Describes which BSAFE procedures to use. Most algorithms employ Init,
Update, and Final steps. For example, AI_MD5, an MD5 message
algorithm, uses B_DigestInit, B_DigestUpdate, and B_DigestFinal.
2.1.6 Algorithm methods to include in application's algorithm chooser:
Describes which algorithm methods can be used in your algorithm
chooser.
2.1.7 Key info types for keyObject:
For algorithms which need a key object, such as encryption and
signature algorithms, describes which KI key info type to use when
setting the key object.
2.1.8 Compatible representation:
Some algorithms have multiple representations for the algorithm
parameters: for example, BSAFE's own format and BER-encoded format.
In this case, the underlying algorithm is the same, but the parameter
representation is different. These are called "compatible
representations"
2.1.9 Input constraints:
Describes any constraints on the total number of input bytes passed
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 39]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
to the update procedure.
2.1.10 Output considerations:
Describes how much space will be required for output buffers. For
those AIs without this category, the output buffer should be the same
size as the input buffer.
2.2 AI_BSSecretSharing
2.2.1 Purpose:
This AI allows you to split a highly sensitive secret, such as a
private key, into several "shares" which can be reassembled to
recreate the original secret. The secret can only be recreated if
there are at least the "threshold" number of shares present. For
example, the secret can be divided into five shares, and any three of
them can be used to reconstruct the secret. In this example, the
threshold is three.
2.2.2 Type of information this allows you to use:
the Bloom-Shamir secret sharing algorithm as defined in "Generalized
Linear Threshold Scheme" by S.C. Kothari, Proceedings of CRYPTO 84.
2.2.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_SECRET_SHARING_PARAMS structure:
typedef struct {
unsigned int threshold; /* share threshold */
} B_SECRET_SHARING_PARAMS;
The threshold is the minimum number of shares required to recover the
secret key; it has a minimum value of 2 and maximum of 255.
2.2.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_SECRET_SHARING_PARAMS structure (see above).
2.2.5 BSAFE procedures to use with algorithm object:
The functions B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal are
used to create the shares from the secret key. The functions
B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal are used to
recover the secret key from the shares.
B_EncryptUpdate must be called a minimum of threshold times. Each
time, the secret that is being split must be supplied as the input
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 40]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
and one new share is returned as the output. B_EncryptFinal returns a
status of BE_OUTPUT_COUNT if the number of calls to B_EncryptUpdate
calls is less than the threshold. B_EncryptFinal supplies no output.
You must supply an initialized random algorithm to B_EncryptUpdate.
(The random algorithm is used only on the first call to
B_EncryptUpdate). Supply (B_ALGORITHM_OBJ)NULL_PTR as the
randomAlgorithm for B_EncryptFinal.
B_DecryptUpdate must be called threshold times to supply enough
shares to recover the secret key. B_DecryptFinal returns a status of
BE_INPUT_COUNT if the number of calls to B_DecryptUpdate is less than
the threshold; otherwise it returns a success status and outputs the
secret key.
Supply (B_ALGORITHM_OBJ)NULL_PTR as the randomAlgorithm for
B_DecryptUpdate and B_DecryptFinal. Supply (B_KEY_OBJ)NULL_PTR as the
keyObject for B_EncryptInit and B_DecryptInit.
2.2.6 Output considerations:
The size of the output from each call to B_EncryptUpdate will be one
byte more than the size of the secret.
2.3 AI_CBC_IV8
2.3.1 Purpose:
This AI allows you to change the initialization vector (IV) for a CBC
mode cipher without needing to create a new algorithm object or bind
in a new key. This increases the performance of applications that
have a long-lived symmetric key (e.g., DES key) that is used to
encrypt many blocks or messages that each has a unique IV.
2.3.2 Type of information this allows you to use:
an 8-byte initialization vector to reset the IV in a CBC algorithm
object that was set with one of the following AIs:
AI_DES_CBC_IV8, AI_DES_CBCPadIV8, AI_DES_CBCPadBER, AI_DES_CBCPadPEM,
AI_DES_EDE3_CBC_IV8, AI_DES_EDE3_CBCPadIV8, AI_DES_EDE3_CBCPadBER,
AI_DESX_CBC_IV8, AI_DESX_CBCPadIV8, AI_DESX_CBCPadBER, AI_RC2_CBC,
AI_RC2_CBCPad, AI_RC2_CBCPadBER, AI_RC2_CBCPadPEM, AI_RC5_CBC,
AI_RC5_CBCPad.
2.3.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an 8-byte unsigned char array containing the new
initialization vector.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 41]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
This new initialization vector will not affect the current algorithm
object until the next call to B_EncryptInit, B_EncryptFinal,
B_DecryptInit, or B_DecryptFinal.
After the new IV takes effect on the algorithm object, any results
from a previous call to B_GetAlgorithmInfo on the algorithm object
are undefined.
2.3.4 Format of info returned by B_GetAlgorithmInfo:
B_GetAlgorithmInfo is not supported for AI_CBC_IV8.
2.3.5 BSAFE procedures to use with algorithm object:
B_SetAlgorithmInfo. To change the IV for an encryption or decryption
algorithm, call B_SetAlgorithmInfo using this AI and a pointer to the
new 8-byte IV value. The new IV will take effect immediately if
B_EncryptFinal or B_DecryptFinal have already been called on the
algorithm object.
2.4 AI_DES_CBC_IV8
2.4.1 Purpose:
This AI allows you to perform DES encryption or decryption in CBC
mode with an 8-byte initialization vector on data that is a multiple
of eight bytes long. No padding will be performed. See
AI_DES_CBCPadIV8 for the same algorithm type with padding.
2.4.2 Type of information this allows you to use:
an 8-byte initialization vector for the DES-CBC encryption algorithm
as defined in FIPS PUB 46-1 and FIPS PUB 81.
2.4.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.4.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.4.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 42]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.4.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_CBC_ENCRYPT for encrypting and AM_DES_CBC_DECRYPT for
decrypting.
2.4.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES8Strong, KI_DES8, KI_8Byte, or KI_Item (if the length of the
ITEM is 8).
Because this algorithm does not pad, the total number of input bytes
must be a multiple of eight.
2.4.9 Token-based algorithm methods:
[Hardware Algorithm] AI_DES_CBC_IV8 can be used to access the
hardware-related algorithm methods AM_TOKEN_DES_CBC_ENCRYPT and
AM_TOKEN_DES_CBC_DECRYPT, for use in conjunction with BHAPI.
2.5 AI_DES_CBCPadBER
2.5.1 Purpose:
This AI represents the same algorithm type as AI_DES_CBCPadIV8 except
that it uses the ASN.1 BER format. It allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the
initialization vector. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_DES_CBCPadBER, AI_DES_CBCPadIV8 or
AI_DES_CBCPadPEM. The OID for this algorithm, excluding the tag and
length bytes, in decimal, is "43, 14, 3, 2, 7". Also see
AI_DES_CBCPadIV8.
2.5.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the DES-CBC
With Padding encryption algorithm as defined in FIPS PUB 46-1 and
FIPS PUB 81 with padding scheme defined in PKCS #5 and desCBC
algorithm identifier defined in [NIST91].
2.5.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 43]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than DES-CBC With Padding.
2.5.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.5.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.5.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_CBC_ENCRYPT for encrypting and AM_DES_CBC_DECRYPT for
decrypting.
2.5.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES8Strong, KI_DES8, KI_8Byte, or KI_Item (if the length of the
ITEM is 8).
2.5.8 Compatible representation:
AI_DES_CBCPadIV8, AI_DES_CBCPadPEM.
2.5.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.6 AI_DES_CBCPadIV8
2.6.1 Purpose:
This AI allows you to perform DES encryption or decryption in CBC
mode with an 8-byte initialization vector on data that is of any byte
length. The padding mode is PKCS #5, which makes the ciphertext one
to eight bytes longer than the plaintext. See AI_DES_CBC_IV8 for the
same algorithm type with no padding. See AI_DES_CBCPadBER for the
same algorithm type with BER encoding.
2.6.2 Type of information this allows you to use:
an 8-byte initialization vector for the DES-CBC With Padding
encryption algorithm as defined in FIPS PUB 46-1 and FIPS PUB 81 with
padding scheme defined in PKCS #5.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 44]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.6.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.6.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.6.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.6.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_CBC_ENCRYPT for encrypting and AM_DES_CBC_DECRYPT for
decrypting.
2.6.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES8Strong, KI_DES8, KI_8Byte, or KI_Item (if the length of the
ITEM is 8).
2.6.8 Compatible representation:
AI_DES_CBCPadBER, AI_DES_CBCPadPEM.
2.6.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.7 AI_DES_CBCPadPEM
2.7.1 Purpose:
This AI represents the same algorithm type as AI_DES_CBCPadIV8 except
that it uses the PEM format. It allows you to parse and create PEM
algorithm identifiers such as used in the Privacy Enhanced Mail
protocol. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the
initialization vector. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_DES_CBCPadPEM, AI_DES_CBCPadIV8 or
AI_DES_CBCPadBER. Also see AI_DES_CBCPadIV8.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 45]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.7.2 Type of information this allows you to use:
an RFC 1423 identifier that specifies the DES-CBC With Padding
encryption algorithm as defined in FIPS PUB 46-1 and FIPS PUB 81 with
padding scheme defined in RFC 1423. This algorithm info type is
intended to process the value of a DEK-Info field in a PEM
encapsulated header.
2.7.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the DES-CBC
identifier and 8-byte initialization vector; for example, "DES-CBC,
0123456789ABCDEF." Space and tab characters are removed from the
string before it is copied to the algorithm object.
B_SetAlgorithmInfo returns BE_WRONG_ALGORITHM_INFO if the algorithm
identifier specifies an identifier other than DES-CBC.
2.7.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the DES-CBC identifier
and 8-byte initialization vector.
2.7.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.7.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_CBC_ENCRYPT for encrypting and AM_DES_CBC_DECRYPT for
decrypting.
2.7.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES8Strong, KI_DES8, KI_8Byte, or KI_Item (if the length of the
ITEM is 8).
2.7.8 Compatible representation:
AI_DES_CBCPadIV8, AI_DES_CBCPadBER.
2.7.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.8 AI_DES_EDE3_CBC_IV8
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 46]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.8.1 Purpose:
This AI allows you to perform three-key DES in
encrypt-decrypt-encrypt mode as defined in ANSI X9.17 using the
outer-CBC mode. It is initialized with an 8-byte IV and operates on
data that is an exact multiple of 8 bytes long. No padding will be
performed. See AI_DES_EDE3_CBCPadIV8 for the same algorithm type with
padding.
2.8.2 Type of information this allows you to use:
an 8-byte initialization vector for the DES-EDE3-CBC encryption
algorithm.
2.8.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.8.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.8.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.8.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_EDE3_CBC_ENCRYPT for encrypting and AM_DES_EDE3_CBC_DECRYPT
for decrypting.
2.8.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, KI_Item (if the length of the ITEM is 24).
2.8.8 Input constraints:
Since this algorithm does not pad, the total number of input bytes
must be a multiple of eight.
2.8.9 Token-based algorithm methods:
[Hardware Algorithm] AI_DES_EDE3_CBC_IV8 may be used to access the
hardware-related algorithm methods AM_TOKEN_DES_EDE3_CBC_ENCRYPT and
AM_TOKEN_DES_EDE3_CBC_DECRYPT, for use with BHAPI.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 47]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.9 AI_DES_EDE3_CBCPadBER
2.9.1 Purpose:
This AI represents the same algorithm type as AI_DES_EDE3_CBCPadIV8
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the
initialization vector. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_DES_EDE3_CBC_PadIV8 or AI_DES_EDE3_CBCPadBER.
The OID for this algorithm, excluding the tag and length bytes, in
decimal, is "42, 134, 72, 134, 247, 13, 3, 7". Also see
AI_DES_EDE3_CBCPadIV8.
2.9.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the
DES-EDE3-CBC encryption algorithm, with padding scheme defined in
PKCS #5.
2.9.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than DES-EDE3-CBC With Padding.
2.9.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.9.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.9.6 Algorithm methods to include in application's algorithm chooser:
AM_DES_EDE3_CBC_ENCRYPT for encrypting and AM_DES_EDE3_CBC_DECRYPT
for decrypting.
2.9.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, or KI_Item (if the length of the ITEM is
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 48]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
24).
2.9.8 Compatible representation:
AI_DES_EDE3_CBCPadIV8.
2.9.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.10 AI_DES_EDE3_CBCPadIV8
2.10.1 Purpose:
This AI allows you to perform three-key DES in
encrypt-decrypt-encrypt mode as defined in ANSI X9.17 using the
outer-CBC mode. It is initialized with an 8-byte IV and operates on
data that is of any byte length. The padding mode is PKCS #5, which
makes the ciphertext one to eight bytes longer than the plaintext.
See AI_DES_EDE3_CBC_IV8 for the same algorithm type with no padding.
See AI_DES_EDE3_CBCPadBER for the same algorithm type with BER
encoding.
2.10.2 Type of information this allows you to use:
an 8-byte initialization vector for the DES-EDE3-CBC encryption
algorithm, with padding scheme defined in PKCS #5.
2.10.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.10.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.10.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.10.6 Algorithm methods to include in application's algorithm
chooser:
AM_DES_EDE3_CBC_ENCRYPT for encrypting and AM_DES_EDE3_CBC_DECRYPT
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 49]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
for decrypting.
2.10.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, KI_Item (if the length of the ITEM is 24).
2.10.8 Compatible representation:
AI_DES_EDE3_CBCPadBER.
2.10.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.11 AI_DESX_CBC_IV8
2.11.1 Purpose:
This AI allows you to perform DESX encryption or decryption in CBC
mode with an 8-byte initialization vector on data that is a multiple
of eight bytes long. This algorithm takes 24 bytes of keying
material. The first 8 bytes of the key form a standard 56-bit DES
key, the second eight bytes become the input whitening, and the last
eight bytes become the output whitening. The DESX algorithm has
64-bit input and output blocks like DES and it is used in all the
same modes. Internally, the plaintext is exclusive-or'ed with the
input whitening before running it through a DES encryption and the
output of DES is exclusive-or'ed with the output whitening to produce
the output block of DESX. Decryption reverses those steps. See
AI_DESX_CBCPadIV8 for the same algorithm type with padding.
2.11.2 Type of information this allows you to use:
an 8-byte initialization vector for the DESX-CBC encryption
algorithm, as defined by RSA Data Security, Inc.
2.11.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.11.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.11.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 50]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.11.6 Algorithm methods to include in application's algorithm
chooser:
AM_DESX_CBC_ENCRYPT for encrypting and AM_DESX_CBC_DECRYPT for
decrypting.
2.11.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, KI_Item (if the length of the ITEM is 24),
or KI_DESX.
2.11.8 Input constraints:
Since this algorithm does not pad, the total number of input bytes
must be a multiple of eight.
2.12 AI_DESX_CBCPadBER
2.12.1 Purpose:
This AI represents the same algorithm type as AI_DESX_CBCPadIV8
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the
initialization vector. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_DESX_CBCPadIV8 or AI_DESX_CBCPadBER. The OID for
this algorithm, excluding the tag and length bytes, in decimal, is
"42, 134, 72, 134, 247, 13, 3, 6". Also see AI_DESX_CBCPadIV8.
2.12.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the DESX-CBC
encryption algorithm, as defined by RSA Data Security, Inc., with
padding scheme defined in PKCS #5.
2.12.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than DESX-CBC With Padding.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 51]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.12.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.12.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.12.6 Algorithm methods to include in application's algorithm
chooser:
AM_DESX_CBC_ENCRYPT for encrypting and AM_DESX_CBC_DECRYPT for
decrypting.
2.12.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, KI_Item (if the length of the ITEM is 24),
or KI_DESX.
2.12.8 Compatible representation:
AI_DESX_CBCPadIV8.
2.12.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.13 AI_DESX_CBCPadIV8
2.13.1 Purpose:
This AI allows you to perform DESX encryption or decryption in CBC
mode. It is initialized with an 8-byte IV and operates on data that
is any byte length. The padding mode is PKCS #5, which makes the
ciphertext one to eight bytes longer than the plaintext. See
AI_DESX_CBC_IV8 for the same algorithm type with no padding. See
AI_DESX_CBCPadBER for the same algorithm type with BER encoding.
2.13.2 Type of information this allows you to use:
an 8-byte initialization vector for the DESX-CBC encryption algorithm
as defined by RSA Data Security, Inc., with padding scheme defined in
PKCS #5.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 52]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.13.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.13.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an unsigned char array that holds the 8 bytes of the
initialization vector.
2.13.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.13.6 Algorithm methods to include in application's algorithm
chooser:
AM_DESX_CBC_ENCRYPT for encrypting and AM_DESX_CBC_DECRYPT for
decrypting.
2.13.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_DES24Strong, KI_24Byte, KI_Item (if the length of the ITEM is 24),
or KI_DESX.
2.13.8 Compatible representation:
AI_DESX_CBCPadBER.
2.13.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.14 AI_DHKeyAgree
2.14.1 Purpose:
This AI allows you to perform Diffie-Hellman key agreement. The
mutually agreed on system parameters are passed to
B_SetAlgorithmInfo. The function B_KeyAgreePhase1 creates the public
value that is sent to the other party, and B_KeyAgreePhase2 processes
the value from the other party to produce the shared secret value.
See AI_DHKeyAgreeBER for the same algorithm type with BER encoding.
2.14.2 Type of information this allows you to use:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 53]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Diffie-Hellman system parameters, where the prime and base integers
and the exponent size are specified for performing Diffie-Hellman key
agreement as defined in PKCS #3.
2.14.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_DH_KEY_AGREE_PARAMS structure:
typedef struct {
ITEM prime; /* prime modulus */
ITEM base; /* base generator */
unsigned int exponentBits; /* size of random exponent in bits */
} A_DH_KEY_AGREE_PARAMS;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the algorithm object.
2.14.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_DH_KEY_AGREE_PARAMS structure (see above). All
leading zeros have been stripped from each integer in the structure.
2.14.5 BSAFE procedures to use with algorithm object:
B_KeyAgreeInit, B_KeyAgreePhase1, and B_KeyAgreePhase2. You must pass
an initialized random algorithm to B_KeyAgreePhase1.
2.14.6 Algorithm methods to include in application's algorithm
chooser:
AM_DH_KEY_AGREE.
2.14.7 Compatible representation:
AI_DHKeyAgreeBER.
2.14.8 Output considerations:
The size of the output of B_KeyAgreePhase1 (the public value) will be
the same size as the prime. The size of the output of
B_KeyAgreePhase2 (the agreed-upon secret) will also be the same size
as the prime.
2.15 AI_DHKeyAgreeBER
2.15.1 Purpose:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 54]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
This AI represents the same algorithm type as AI_DHKeyAgree except
that it uses the ASN.1 BER format. It allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the prime
modulus, base and private value length. You call B_GetAlgorithmInfo
with this AI to create an encoded algorithm identifier from an
algorithm object that was created using AI_DHKeyAgree or
AI_DHKeyAgreeBER. The OID for this algorithm, excluding the tag and
length bytes, in decimal, is "42, 134, 72, 134, 247, 13, 1, 3, 1".
Also see AI_DHKeyAgree.
2.15.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies Diffie-Hellman
key agreement as defined in PKCS #3.
2.15.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than Diffie-Hellman.
2.15.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.15.5 BSAFE procedures to use with algorithm object:
B_KeyAgreeInit, B_KeyAgreePhase1, and B_KeyAgreePhase2. You must pass
an initialized random algorithm to B_KeyAgreePhase1.
2.15.6 Algorithm methods to include in application's algorithm
chooser:
AM_DH_KEY_AGREE.
2.15.7 Compatible representation:
AI_DHKeyAgree.
2.15.8 Output considerations:
The size of the output of B_KeyAgreePhase1 (the public value) will be
the same size as the prime. The size of the output of
B_KeyAgreePhase2 (the agreed-upon secret) will also be the same size
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 55]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
as the prime.
2.16 AI_DHParamGen
2.16.1 Purpose:
This AI allows you to generate Diffie-Hellman system parameters,
which are the prime modulus, base and private value length.
2.16.2 Type of information this allows you to use:
the parameters for generating Diffie-Hellman system parameters as
defined in PKCS #3, where the size of the prime modulus and random
exponent are specified. The optimized generating algorithm is defined
by RSA Data Security, Inc.
2.16.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_DH_PARAM_GEN_PARAMS structure:
typedef struct {
unsigned int primeBits; /* size of prime modulus in bits */
unsigned int exponentBits; /* size of random exponent in bits */
} A_DH_PARAM_GEN_PARAMS;
The exponentBits must be less than primeBits.
2.16.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_DH_PARAM_GEN_PARAMS structure (see above).
2.16.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateParameters. B_GenerateParameters sets
the resultAlgorithmObject with the AI_DHKeyAgree information. You
must pass an initialized random algorithm to B_GenerateParameters.
2.16.6 Algorithm methods to include in application's algorithm
chooser:
AM_DH_PARAM_GEN.
2.17 AI_DSA
2.17.1 Purpose:
This AI allows you to create or verify raw DSA signatures where the
20-byte input is already known. It does not compute a message digest
before applying the signature operation. See AI_DSAWithSHA1 for the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 56]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
DSA algorithm type that involves the SHA1 digest operation.
2.17.2 Type of information this allows you to use:
the DSA signature algorithm for performing raw DSA signing and
verifying as defined in FIPS PUB 186.
2.17.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.17.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.17.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You must pass a random algorithm
in B_SignFinal, but may pass (B_ALGORITHM_OBJ)NULL_PTR for all other
randomAlgorithm arguments.
2.17.6 Algorithm methods to include in application's algorithm
chooser:
AM_DSA_SIGN for signing, AM_DSA_VERIFY for verifying.
2.17.7 Key info types for keyObject in B_SignInit:
KI_DSAPrivate or KI_DSAPrivateBER.
2.17.8 Key info types for keyObject in B_VerifyInit:
KI_DSAPublic or KI_DSAPublicBER.
2.17.9 Input constraints:
The DSA algorithm requires that the input data (the data to sign) be
exactly 20 bytes long. Normally, this 20-byte input is the result of
SHA1 output.
2.17.10 Output considerations:
The signature result of B_SignFinal will be 40 bytes long; these
bytes appear in the order (r,s).
2.17.11 Token-based algorithm methods:
[Hardware algorithm] AI_DSA may be used to access the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 57]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
hardware-related algorithm methods AM_TOKEN_DSA_SIGN and
AM_TOKEN_DSA_VERIFY, for use with BHAPI.
2.18 AI_DSAKeyGen
2.18.1 Purpose:
This AI allows you to generate a DSA key pair. The system parameters
are passed to B_SetAlgorithmInfo and the keys are made by calling
B_GenerateInit and B_GenerateKeypair. The AI_DSAParamGen algorithm
type may generate the system parameters that are used to generate a
DSA key. Also see AI_DSAParamGen.
2.18.2 Type of information this allows you to use:
the parameters for generating a compatible DSA key pair as defined in
FIPS PUB 186.
2.18.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_DSA_PARAMS structure:
typedef struct {
ITEM prime; /* the prime p */
ITEM subPrime; /* the subprime q */
ITEM base; /* the base g */
} A_DSA_PARAMS;
An ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first,
and the ITEM's len gives its length. All leading zeros are stripped
from the integer before it is copied to the algorithm object.
2.18.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_DSA_PARAM_GEN_PARAMS structure (see above).
2.18.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateKeypair. B_GenerateKeypair sets the
publicKey key object with the KI_DSAPublic information and the
privateKey key object with the KI_DSAPrivate information. You must
pass an initialized random algorithm to B_GenerateKeypair.
2.18.6 Algorithm methods to include in application's algorithm
chooser:
AM_DSA_KEY_GEN.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 58]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.19 AI_DSAParamGen
2.19.1 Purpose:
This AI allows you to generate DSA system parameters. The size of the
parameters is passed to B_SetAlgorithmInfo and the parameters are
made by calling B_GenerateInit and B_GenerateParameters. DSA
parameters that are generated by this AI will be used to generate a
DSA key pair. Also see AI_DSAKeyGen.
2.19.2 Type of information this allows you to use:
the number of prime bits for generating a prime, a subprime, and a
base (p, q, and g) compatible with FIPS PUB 186.
2.19.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an B_DSA_PARAM_GEN_PARAMS structure:
typedef struct {
unsigned int primeBits; /* size of prime in bits */
} B_DSA_PARAM_GEN_PARAMS;
2.19.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_DSA_PARAM_GEN_PARAMS structure (see above).
2.19.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateParameters. B_GenerateParameters sets
the resultAlgorithmObject algorithm object with the AI_DSAKeyGen
information. You must pass an initialized random algorithm to
B_GenerateParameters.
2.19.6 Algorithm methods to include in application's algorithm
chooser:
AM_DSA_PARAM_GEN.
2.19.7 Notes:
The size of the subprime is always 160 bits.
2.20 AI_DSAWithSHA1
2.20.1 Purpose:
This AI allows you to create or verify SHA1 DSA signatures. It is
passed the plaintext and computes the SHA1 digest as well as the DSA
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 59]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
signature of that digest. See AI_DSA for the DSA algorithm type
without the SHA1 digest operation. See AI_DSAWithSHA1_BER for the
same algorithm type with BER encoding.
2.20.2 Type of information this allows you to use:
the DSA With SHA1 signature algorithm that uses the SHA1 digest
algorithm and DSA to create and verify DSA digital signatures as
defined in X9.57 Draft Section 5.3.1 and FIPS PUB 186.
2.20.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.20.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.20.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You must pass a random algorithm
in B_SignFinal, but may pass (B_ALGORITHM_OBJ)NULL_PTR for all other
randomAlgorithm arguments.
2.20.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA and AM_DSA_SIGN for signing or AM_DSA_VERIFY for verifying.
2.20.7 Key info types for keyObject in B_SignInit:
KI_DSAPrivate or KI_DSAPrivateBER.
2.20.8 Key info types for keyObject in B_VerifyInit:
KI_DSAPublic or KI_DSAPublicBER.
2.20.9 Compatible representation:
AI_DSAWithSHA1_BER.
2.20.10 Output considerations:
The signature result of B_SignFinal is a BER-encoded value of type
SEQUENCE (INTEGER, INTEGER), where the first field is the value r and
the second field is the value s as defined in section 5.3.1 of X9.57
Draft. The size of signature may be as many as 48 bytes.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 60]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.21 AI_DSAWithSHA1_BER
2.21.1 Purpose:
This AI represents the same algorithm type as AI_DSAWithSHA1 except
that it uses the ASN.1 BER format. It allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using AI_
DSAWithSHA1 or AI_DSAWithSHA1_BER. The OID for this algorithm,
excluding the tag and length bytes, in decimal, is "43, 14, 3, 2,
27". Also see AI_DSAWithSHA1.
2.21.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the DSA With
SHA1 signature algorithm that uses the SHA1 digest algorithm and DSA
to create and verify DSA digital signatures as defined in X9.57 Draft
Section 5.3.1 and FIPS PUB 186.
2.21.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than DSA With SHA1.
2.21.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.21.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You must pass a random algorithm
in B_SignFinal, but may pass (B_ALGORITHM_OBJ)NULL_PTR for all other
randomAlgorithm arguments.
2.21.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA1 and AM_DSA_SIGN for signing or AM_DSA_VERIFY for verifying.
2.21.7 Key info types for keyObject in B_SignInit:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 61]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
KI_DSAPrivate or KI_DSAPrivateBER.
2.21.8 Key info types for keyObject in B_VerifyInit:
KI_DSAPublic or KI_DSAPublicBER.
2.21.9 Compatible representation:
AI_DSAWithSHA1.
2.21.10 Output considerations:
The signature result of B_SignFinal is a BER-encoded value of type
SEQUENCE (INTEGER, INTEGER) where the first field is the value r and
the second field is the value s as defined in section 5.3.1 of X9.57
Draft. The size of signature may be as many as 48 bytes.
2.22 AI_ECAcceleratorTable
2.22.1 Purpose:
This AI allows you to use the acceleration table for various EC
operations that include encryption, signature creation and
verification, key pair generation, and key agreement operations.
2.22.2 Type of information this allows you to use:
the acceleration table produced by operating
AI_ECBuildAcceleratorTable on EC parameters or the table produced by
operating AI_ECBuildPubKeyAccelTable on EC parameters.
2.22.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM holding the accelerator table.
2.22.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM holding the accelerator table.
2.22.5 BSAFE procedures to use with algorithm object:
use the table generated by AI_ECBuildAcceleratorTable with
B_SetAlgorithmInfo to accelerate EC encryption in AI_EC_ES, signature
and verification in AI_EC_DSA and AI_EC_DSAWithDigest, key pair
generation in AI_ECKeyGen, and phase 1 of key agreement operations in
AI_EC_DHKeyAgree. Use the table generated by
AI_ECBuildPubKeyAccelTable with B_SetAlgorithmInfo to accelerate
verification in AI_EC_DSA and AI_EC_DSAWithDigest.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 62]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.22.6 Algorithm methods to include in application's algorithm
chooser:
None.
2.23 AI_ECBuildAcceleratorTable
2.23.1 Purpose:
This AI allows you to build an acceleration table for a base point.
See AI_ECBuildPubKeyAccelTable for the AI that involves the
public key as well as base point.
2.23.2 Type of information this allows you to use:
elliptic curve parameters as defined in X9.62 Draft to generate
auxiliary data for accelerating EC operations with base point.
Elliptic curve parameters can be generated by executing
AI_ECParamGen.
2.23.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_EC_PARAMS structure:
typedef struct {
B_INFO_TYPE parameterInfoType; /* used to interpret EC params */
POINTER parameterInfoValue; /* describes elliptic curve */
} B_EC_PARAMS;
where parameterInfoType must be AI_ECParameters and
parameterInfoValue must be a pointer to an A_EC_PARAMS structure:
typedef struct {
unsigned int version; /* implementation version */
unsigned int fieldType; /* indicates type of base field */
ITEM fieldInfo; /* It is the prime number */
/* in case that fieldType = FT_FP; */
/* the basis polynomial if fieldType = FT_F2_POLYNOMIAL; */
/* and the degree of the field if fieldType = FT_F2_ONB */
ITEM coeffA; /* elliptic curve coefficient */
ITEM coeffB; /* elliptic curve coefficient */
ITEM base; /* elliptic curve group generator */
ITEM order; /* order of subgroup's generating element */
ITEM cofactor; /* the cofactor of the subgroup */
unsigned int compressIndicator; /* controls field element */
/* representation */
unsigned int fieldElementBits; /* field element size in bits */
} A_EC_PARAMS;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 63]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.23.4 Format of info returned by B_GetAlgorithmInfo:
B_GetAlgorithmInfo is not supported with this AI. If called, it will
return an error.
2.23.5 BSAFE procedures to use with algorithm object:
B_BuildTableInit and B_BuildTableFinal.
2.23.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_BLD_ACCEL_TABLE for odd prime fields and
AM_ECF2POLY_BLD_ACCEL_TABLE for even characteristic.
2.23.7 Output Considerations:
The size of the accelerator table may be found by calling
B_BuildTableGetBufSize after calling B_BuildTableInit.
2.24 AI_ECBuildPubKeyAccelTable
2.24.1 Purpose:
This AI allows you to build an acceleration table for a public key
and and the base point. The acceleration comes from a table that
includes values built for the base point, which are the same as those
from AI_ECBuildAcceleratorTable, and values built for the public key.
The speed advantages of this algorithm type over
AI_ECBuildAcceleratorTable are for the ECDSA verify and ECDH Phase 2
operations.
2.24.2 Type of information this allows you to use:
elliptic curve parameters as defined in X9.62 Draft to generate
auxiliary data for accelerating elliptic curve operations with base
point and public key. Elliptic curve parameters can be generated by
executing AI_ECParamGen.
2.24.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_EC_PARAMS structure:
typedef struct {
B_INFO_TYPE parameterInfoType;/* used to interpret EC parameters */
POINTER parameterInfoValue /* describes elliptic curve */
} B_EC_PARAMS;
where parameterInfoType must be AI_ECPubKey and parameterInfoValue
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 64]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
must be an A_EC_PUBLIC_KEY structure:
typedef struct {
A_EC_PARAMS curveParams; /* underlying elliptic curve parameters */
ITEM publicKey; /* public component */
} A_EC_PUBLIC_KEY;
2.24.4 Format of info returned by B_GetAlgorithmInfo:
B_GetAlgorithmInfo is not supported with this AI. If called, it will
return an error.
2.24.5 BSAFE procedures to use with algorithm object:
B_BuildTableInit and B_BuildTableFinal.
2.24.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_BLD_PUB_KEY_ACCEL_TABLE for odd prime fields and
AM_ECF2POLY_BLD_PUB_KEY_ACCEL_TABLE for even characteristic.
2.24.7 Output Considerations:
The size of the accelerator table may be found by calling
B_BuildTableGetBufSize after calling B_BuildTableInit.
2.25 AI_EC_DHKeyAgree
2.25.1 Purpose:
This AI allows you to perform elliptic curve Diffie-Hellman key
agreement for given EC parameters. The mutually agreed on system
parameters are passed to B_SetAlgorithmInfo. The function
B_KeyAgreePhase1 creates the public value that is sent to the other
party, and B_KeyAgreePhase2 processes the value from the other party
to produce the shared secret value.
2.25.2 Type of information this allows you to use:
elliptic curve system parameters for performing elliptic curve
Diffie-Hellman key agreement as defined in X9.63 Draft.
2.25.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an B_EC_PARAMS structure:
typedef struct {
B_INFO_TYPE *parameterInfoType; /* used to interpret EC params */
POINTER parameterInfoValue; /* describes elliptic curve */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 65]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
} B_EC_PARAMS;
where parameterInfoType must be AI_ECParameters and
parameterInfoValue must be an A_EC_PARAMS structure:
typedef struct {
unsigned int version; /* implementation version */
unsigned int fieldType; /* indicates type of base field */
ITEM fieldInfo; /* It is the prime number */
/* in case that fieldType = FT_FP; */
/* the basis polynomial if fieldType = FT_F2_POLYNOMIAL; */
/* and the degree of the field if fieldType = FT_F2_ONB */
ITEM coeffA; /* elliptic curve coefficient */
ITEM coeffB; /* elliptic curve coefficient */
ITEM base; /* elliptic curve group generator */
ITEM order; /* order of subgroup's generating element */
ITEM cofactor; /* the cofactor of the subgroup */
unsigned int compressIndicator; /* controls field element */
/* representation */
unsigned int fieldElementBits; /* field element size in bits */
} A_EC_PARAMS;
2.25.4 Format of info returned by B_GetAlgorithmInfo:
B_GetAlgorithmInfo is not supported with this AI. If called, it will
return an error.
2.25.5 BSAFE procedures to use with algorithm object:
B_KeyAgreeInit, B_KeyAgreePhase1, and B_KeyAgreePhase2. You must pass
an initialized random algorithm to B_KeyAgreePhase1.
2.25.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_DH_KEY_AGREE for odd prime fields and
AM_ECF2POLY_DH_KEY_AGREE for even characteristic.
2.25.7 Output considerations:
The size of Phase 1 output is 1 + 2 * (size of field element) bytes;
the size of Phase 2 output is the (size of field element) bytes
2.26 AI_EC_DSA
2.26.1 Purpose:
This AI allows you perform raw ECDSA signing or verifying operations.
It does not compute a message digest before applying the signature
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 66]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
operation. See AI_EC_DSAWithDigest for the ECDSA signature algorithm
that involves the SHA1 message digest operation.
2.26.2 Type of information this allows you to use:
the ECDSA signature algorithm for performing raw ECDSA signing and
verifying as defined in X9.62 Draft. One may also optionally use
tables generated by exercising AI_ECBuildAcceleratorTable or
AI_ECBuildPubKeyAccelTable. The public-key-specific acceleration
table accelerates verification only; for this operation, it provides
greater acceleration than the AI_ECBuildAcceleratorTable at the cost
of greater memory usage.
2.26.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.26.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.26.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You must pass a random algorithm
in B_SignFinal, but may pass (B_ALGORITHM_OBJ)NULL_PTR for all other
randomAlgorithm arguments.
2.26.6 Algorithm methods to include in application's algorithm
chooser:
For signing, AM_ECFP_DSA_SIGN for odd prime fields and
AM_ECF2POLY_DSA_SIGN for even characteristic. For verifying,
AM_ECFP_DSA_VERIFY for odd prime fields and AM_ECF2POLY_DSA_VERIFY
for even characteristic.
2.26.7 Key info types for keyObject in B_SignInit:
KI_ECPrivate.
2.26.8 Key info types for keyObject in B_VerifyInit:
KI_ECPublic.
2.26.9 Input constraints:
In practice, the input to the ECDSA algorithm - that is, the data to
sign - is generally the result of a digest operation. In BSAFE's
implementation, however, the only restrictions on the input are that
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 67]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
it must be at least 16 bytes and no more than 32 bytes long.
2.26.10 Output considerations:
The signature result of B_SignFinal is a value of type SEQUENCE
(INTEGER, INTEGER) where the first field is the value r and the
second field is the value s, as defined in section 5.3.1 of X9.57
Draft. The size of signature is 2*(length of order) bytes. For
instance, if the order is 160 bits (20 bytes), the signature will be
40 bytes long.
2.27 AI_EC_DSAWithDigest
2.27.1 Purpose:
This AI allows you to create or verify SHA1 ECDSA signatures. It is
passed the plaintext and computes the SHA1 digest as well as the
ECDSA signature of that digest. See AI_EC_DSA for the ECDSA algorithm
type without the SHA1 digest.
2.27.2 Type of information this allows you to use:
the specified digest algorithm combined with the ECDSA signature
algorithm for performing ECDSA signing and verifying as defined in
X9.62 Draft. The only digest method supported in this API is SHA1.
2.27.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_DIGEST_SPECIFIER structure:
typedef struct {
B_INFO_TYPE digestInfoType;
POINTER digestInfoParams;
} B_DIGEST_SPECIFIER;
This API supports only AI_SHA1 as a digestInfoType, with NULL_PTR as
the digestInfoParams.
2.27.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_DIGEST_SPECIFIER structure.
2.27.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You must pass an initialized
random algorithm in B_SignFinal, but may pass
(B_ALGORITHM_OBJ)NULL_PTR for all other randomAlgorithm arguments.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 68]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.27.6 Algorithm methods to include in application's algorithm
chooser:
For signing, AM_ECFP_DSA_SIGN for odd prime fields and
AM_ECF2POLY_DSA_SIGN for even characteristic. For verifying,
AM_ECFP_DSA_VERIFY for odd prime fields and AM_ECF2POLY_DSA_VERIFY
for even characteristic. Also required is the appropriate AM for the
digest specified, for instance, AM_SHA when the digestInfoType is
AI_SHA1.
2.27.7 Key info types for keyObject in B_SignInit:
KI_ECPrivate.
2.27.8 Key info types for keyObject in B_VerifyInit:
KI_ECPublic.
2.27.9 Output considerations:
The signature result of B_SignFinal is a BER-encoded value of type
SEQUENCE (INTEGER, INTEGER) where the first field is the value r and
the second field is the value s, as defined in section 5.3.1 of X9.57
Draft. The size of signature is 6 + (2 * (length of order)) bytes.
For instance, if the order is 160 bits (20 bytes), the signature will
be 46 bytes long.
2.28 AI_EC_ES
2.28.1 Purpose:
This AI allows you to perform public-key encryption or private-key
decryption using the Elliptic-Curve Authenticated Encryption System,
where ciphertext includes the SHA1 digest as well as encrypted
plaintext.
2.28.2 Type of information this allows you to use:
the elliptic curve authenticated encryption scheme as defined in
X9.63 Draft, as of 10/97.
2.28.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.28.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 69]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.28.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, B_DecryptFinal. You must pass an initialized random
algorithm in B_EncryptFinal, but may pass (B_ALGORITHM_OBJ)NULL_PTR
for all other randomAlgorithm arguments.
2.28.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_ENCRYPT for encrypting and AM_ECFP_DECRYPT for decrypting
with odd prime fields, AM_ECF2POLY_ENCRYPT for encrypting and
AM_ECF2POLY_DECRYPT for decrypting with even characteristic.
2.28.7 Output Considerations:
The encrypted data can be as much as ((21 + 2 * (the size of a field
element in bytes) + (length of input in bytes)) bytes long.
2.29 AI_ECKeyGen
2.29.1 Purpose:
This AI allows you to generate an elliptic curve key pair for given
EC parameters.
2.29.2 Type of information this allows you to use:
the parameters for generating a compatible elliptic curve key pair.
The precomputed table values from AI_ECAcceleratorTable can
optionally be used to accelerate this operation.
2.29.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_EC_PARAMS structure:
typedef struct {
B_INFO_TYPE parameterInfoType; /* used to interpret EC parameters */
POINTER parameterInfoValue; /* describes elliptic curve */
} B_EC_PARAMS;
where parameterInfoType must be AI_ECParameters and
parameterInfoValue must be a pointer to an A_EC_PARAMS structure:
typedef struct {
unsigned int version; /* implementation version */
unsigned int fieldType; /* indicates type of base field */
ITEM fieldInfo; /* It is the prime number */
/* in case that fieldType = FT_FP; */
/* the basis polynomial if fieldType = FT_F2_POLYNOMIAL; */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 70]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* and the degree of the field if fieldType = FT_F2_ONB */
ITEM coeffA; /* elliptic curve coefficient */
ITEM coeffB; /* elliptic curve coefficient */
ITEM base; /* elliptic curve group generator */
ITEM order; /* order of subgroup's generating element */
ITEM cofactor; /* the cofactor of the subgroup */
unsigned int compressIndicator; /* controls field element */
/* representation */
unsigned int fieldElementBits; /* field element size in bits */
} A_EC_PARAMS;
2.29.4 Format of info returned by B_GetAlgorithmInfo:
B_GetAlgorithmInfo is not supported with this AI. If called, it will
return an error.
2.29.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateKeypair. B_GenerateKeypair sets the
publicKey key object with the KI_ECPublic information and the
privateKey key object with the KI_ECPrivate information. You must
pass an initialized random algorithm to B_GenerateKeypair.
2.29.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_KEY_GEN for odd prime fields and AM_ECF2POLY_KEY_GEN for even
characteristic.
2.30 AI_ECParameters
2.30.1 Purpose:
This AI allows you to specify EC parameters to be used for elliptic
curve operations. New EC parameters may be generated using the
AI_ECParamGen algorithm type.
2.30.2 Type of information this allows you to use:
the parameters generated by executing AI_ECParamGen for either
generating keys or executing key agreements.
2.30.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a A_EC_PARAMS structure that has been set by
AI_ECParamGen:
typedef struct {
unsigned int version; /* implementation version */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 71]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int fieldType; /* indicates type of base field */
ITEM fieldInfo; /* It is the prime number */
/* in case that fieldType = FT_FP; */
/* the basis polynomial if fieldType = FT_F2_POLYNOMIAL; */
/* and the degree of the field if fieldType = FT_F2_ONB */
ITEM coeffA; /* elliptic curve coefficient */
ITEM coeffB; /* elliptic curve coefficient */
ITEM base; /* elliptic curve group generator */
ITEM order; /* order of subgroup's generating element */
ITEM cofactor; /* the cofactor of the subgroup */
unsigned int compressIndicator; /* controls field element */
/* representation */
unsigned int fieldElementBits; /* field element size in bits */
} A_EC_PARAMS;
2.30.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_EC_PARAMS structure (see above).
2.30.5 BSAFE procedures to use with algorithm object:
B_SetAlgorithmInfo and B_GetAlgorithmInfo.
2.30.6 Algorithm methods to include in application's algorithm
chooser:
None.
2.31 AI_ECParamGen
2.31.1 Purpose:
This AI allows you to generate EC parameters to be used for elliptic
curve operations.
2.31.2 Type of information this allows you to use:
the input parameters for generating an elliptic curve system as
defined in X9.62 Draft and IEEE P1363 Draft.
2.31.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_EC_PARAM_GEN_PARAMS structure:
typedef struct {
unsigned int version; /* implementation version */
unsigned int fieldType; /* base field for the elliptic curve */
unsigned int fieldElementBits; /* length of field element */
/* in bits */
unsigned int compressIndicator; /* ignored for now */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 72]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int minOrderBits; /* minimum size of group */
/* generated by base input of 0 */
/* defaults to fieldElementBits - 7 */
unsigned int trialDivBound; /* maximum size of second largest */
/* prime subgroup of group generated */
/* by base input of 0 defaults to 255 */
unsigned int tableLookup; /* characteristic 2 only. Set if the */
/* use of precomputed params is desired */
} B_EC_PARAM_GEN_PARAMS;
Set the arguments as follows:
Argument Values Comments
version 0 Only value currently available;
allows growth for future versions
fieldType FT_FP odd prime field
FT_F2_ONB even characteristic, optimal
normal basis
FT_F2_POLYNOMIAL even characteristic, polynomial
basis
compressIndicator CI_NO_COMPRESS do not compress the base or
public key
CI_HYBRID express the base and public key
in "hybrid" form; that is, do
not compress, but append the
compressed y-coordinate.
fieldElementBits 64 - 384 bits fieldType = FT_FP or
FT_F2_POLYNOMIAL
65, 66, 69, 74, 81, 82,
83, 86, 89, 90, 95, 98,
99, 100, 105, 106, 113,
119, 130, 131, 134, 135,
138, 146, 148, 155, 158,
162, 172, 173, 174, 178,
179, 180, 183, 186, 189,
191, 194, 196, 209, 210,
221, 226, 230, 231, 233,
239, 243, 245, 251, 254,
261, 268, 270, 273, 278,
281, 292, 293, 299, 303,
306, 309, 316, 323, 326,
329, 330, 338, 346, 348,
350, 354, 359, 371, 372,
375, 378 fieldType = FT_F2_ONB
minOrderBits 0 (recommended);
1 to fieldElementBits 0 tells BSAFE to choose the
value.
Note that not all values in the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 73]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
range 1 - fieldElementBits are
secure.
Must be set to 0 if
tableLookup = 1.
trialDivBound 0 (recommended);
1 - 384 0 tells BSAFE to choose the
value.
Must be set to 0 if
tableLookup = 1.
tableLookup 0 or 1 set to 0 if
fieldType = FT_FP
set to 0 if
fieldType = FT_F2_ONB
or FT_F2_POLYNOMIAL, and you
want BSAFE to generate new
parameters from scratch.
minOrderBits and trialDivBound
may be non-zero.
set to 1 if
fieldType = FT_F2_ONB
or FT_F2_POLYNOMIAL, and you
want to generate curves using
table lookup. Curve generation
will be fast, but minOrderBits
and trialDivBound must be
set to 0.
The parameter range given above for minOrderBits includes values that
are not secure. If you pass 0 for minOrderBits, BSAFE will choose the
value for you. You should only pass a non-zero value if you are sure
that you are fully aware of the underlying cryptographic issues.
2.31.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_EC_PARAM_GEN_PARAMS structure (see above).
2.31.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateParameters. B_GenerateParameters sets
the resultAlgorithmObject with the parameter information. You must
pass an initialized random algorithm to B_GenerateParameters.
2.31.6 Algorithm methods to include in application's algorithm
chooser:
AM_ECFP_PARAM_GEN for odd prime fields and AM_ECF2POLY_PARAM_GEN for
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 74]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
even characteristic.
2.31.7 Notes:
Generating an elliptic curve for even characteristic without table
lookup (fieldType = FT_F2_ONB or FT_F2_POLYNOMIAL and tableLookup
= 0) can be extremely time-consuming, taking several hours in some
cases. In general, larger values for minOrderBits mean longer times
for curve generation. Therefore, if you wish to generate curves for
even characteristic, but do not want to use table lookup, you can
speed curve generation by setting a smaller value for minOrderBits.
Remember, however, that the size of minOrderBits is directly tied to
the security of your elliptic curve cryptosystem. Setting
minOrderBits allows you to make a trade-off between the time it takes
to generate curves and the security of your system.
2.32 AI_ECPubKey
2.32.1 Purpose:
This AI allows you to specify an EC public key and underlying EC
parameters in order to build an acceleration table.
2.32.2 Type of information this allows you to use:
a specified elliptic curve public key to build a public-key specific
acceleration table.
2.32.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_EC_PUBLIC_KEY structure:
typedef struct {
A_EC_PARAMS curveParams; /* the underlying elliptic curve params */
ITEM publicKey; /* public component */
} A_EC_PUBLIC_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. For all ITEM values except the
public component (x) and the curve parameter base, leading zeros are
stripped before they are copied to the key object.
2.32.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_EC_PUBLIC_KEY structure.
2.32.5 Can get this info type if algorithm object already has:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 75]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AI_ECPubKey.
2.33 AI_FeedbackCipher
2.33.1 Purpose:
This AI allows you to perform a various kind of block cipher
encryption or decryption with feedback. The parameters of this AI
include encryption method, feedback method and padding method.
2.33.2 Type of information this allows you to use:
a descriptor for block ciphers with feedback, as defined in X9.52.
2.33.3 Format of info supplied to B_SetAlgorithmInfo:
a pointer to a B_BLK_CIPHER_W_FEEDBACK_PARAMS structure:
typedef struct {
unsigned char *encryptionMethodName; /* examples include */
/* "des", "des_ede" */
POINTER encryptionParams; /* e.g., RC5 parameters */
unsigned char *feedbackMethodName;
POINTER feedbackParams; /* Points at init vector ITEM */
/* for all feedback modes except cfb */
unsigned char *paddingMethodName;
POINTER paddingParams; /* Ignored for now, but may be */
/* used for new padding schemes */
} B_BLK_CIPHER_W_FEEDBACK_PARAMS;
2.33.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a structure of type B_BLK_CIPHER_W_FEEDBACK_PARAMS.
2.33.5 Type of padding schemes available:
Padding Scheme Reference String Comments
Standard CBC padding "pad"
No padding "nopad" Input length must be a
multiple of cipher block
length (= 8 for
all but rc5-64)
Stream "stream" Only available when using
CFB in 1-bit and 8-bit modes.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 76]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.33.6 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal, and
B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.33.7 Algorithm methods to include in application's algorithm
chooser:
the block cipher AM and the feedback mode AM specified by
encryptionMethodName and feedbackMethodName, respectively.
Algorithm methods for block ciphers
Algorithm methods for block ciphers
encryptionMethodName Algorithm methods Parameters Key Size
to include
in chooser
Encryption
"des" AM_DES_ENCRYPT; null 8 bytes
"des_ede" AM_DES_EDE_ENCRYPT; null 24 bytes
"desx" AM_DESX_ENCRYPT; null 24 bytes
"rc2" AM_RC2_ENCRYPT; Pointer to an A_RC2_PARAMS
structure
1 - 128 bytes
"rc5" AM_RC5_ENCRYPT; Pointer to an A_RC5_PARAMS
structure
0 - 255 bytes; 32-bit word
"rc5_64" AM_RC5_64ENCRYPT; Pointer to an A_RC5_PARAMS
structure
0 - 255 bytes; 64-bit word
Decryption
"des" AM_DES_DECRYPT; null 8 bytes
"des_ede" AM_DES_EDE_DECRYPT; null 24 bytes
"desx" AM_DESX_DECRYPT; null 24 bytes
"rc2" AM_RC2_DECRYPT; Pointer to an A_RC2_PARAMS
structure
1 - 128 bytes
"rc5" AM_RC5_DECRYPT; Pointer to an A_RC5_PARAMS
structure
0 - 255 bytes; 32-bit word
"rc5_64" AM_RC5_64DECRYPT; Pointer to an A_RC5_PARAMS
structure
0 - 255 bytes; 64-bit word
The RC2 algorithm methods, AM_RC2_ENCRYPT and AM_RC2_DECRYPT, require
an A_RC2_PARAMS structure:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 77]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef struct {
unsigned int effectiveKeyBits; /* effective key size in bits */
} A_RC2_PARAMS;
The RC5 algorithm methods, AM_RC5_ENCRYPT, AM_RC564_ENCRYPT,
AM_RC5_DECRYPT, and AM_RC564_DECRYPT, require an A_RC5_PARAMS
structure. Note that the 64-bit versions of RC5, AM_RC5_64_ENCRYPT
and AM_RC5_64_DECRYPT, are evaluation implementations and are not
optimized in this API:
typedef struct {
unsigned int version; /* currently version 1.0 - defined as 0x10 */
unsigned int rounds; /* number of rounds (0 - 255) */
unsigned int wordSizeInBits; /* 32 for "rc5" or 64 for "rc5_64" */
} A_RC5_PARAMS;
Algorithm methods for feedback modes
feedbackMethodName Algorithm methods
Parameter Type to include
in chooser
Encryption
"cbc" AM_CBC_ENCRYPT;
ITEM that contains the
initialization vector
"cbc_interleaved" AM_CBC_INTER_LEAVED_ENCRYPT;
ITEM that contains the
initialization vector
"cfb" AM_CFB_ENCRYPT;
B_CFB_PARAMS
"cfb_pipelined" AM_CFB_PIPELINED_ENCRYPT;
B_CFB_PARAMS
"ecb" AM_ECB_ENCRYPT;
unsigned int that gives the
block length
"ofb" AM_OFB_ENCRYPT;
ITEM that contains the
initialization vector
"ofb_pipelined" AM_OFB_PIPELINED_ENCRYPT;
ITEM that contains the
initialization vector
Decryption
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 78]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
"cbc" AM_CBC_DECRYPT;
ITEM that contains the
initialization vector
"cbc_interleaved" AM_CBC_INTER_LEAVED_DECRYPT;
ITEM that contains the
initialization vector
"cfb" AM_CFB_DECRYPT;
B_CFB_PARAMS
"cfb_pipelined" AM_CFB_PIPELINED_DECRYPT;
B_CFB_PARAMS
"ecb" AM_ECB_DECRYPT;
unsigned int that gives the
block length
"ofb" AM_OFB_DECRYPT;
ITEM that contains the
initialization vector
"ofb_pipelined" AM_OFB_PIPELINED_DECRYPT;
ITEM that contains the
initialization vector
The CFB modes require a B_CFB_PARAMS structure:
typedef struct {
ITEM ivItem;
unsigned int transferSize;
} B_CFB_PARAMS;
The initialization vector should be the same size as the block. In
particular, the IV should be 8 bytes, except for RC5 implemented with
a 64-bit word, which requires a 16-byte IV.
2.33.8 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
Depends on cipher type, as follows:
Cipher KIs
DES KI_Item, KI_DES8, KI_DES8Strong, KI_8Byte
Triple DES KI_Item, KI_DES24Strong, KI_24Byte
DESX KI_Item, KI_DES24Strong, KI_24Byte
RC2 KI_Item, KI_8Byte
RC5 KI_Item, which gives the address and length of RC5 Key.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 79]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.33.9 Compatible representations:
Depends on cipher type, as follows:
Cipher Compatible representations
DES with CBC mode AI_DES_CBC_IV8, AI_DES_CBCPadIV8,
AI_DES_CBCPadBER, and AI_DES_CBCPadPEM
TDES with CBC mode AI_DES_EDE3_CBC_IV8, AI_DES_EDE3_CBCPadIV8,
and AI_DES_EDE3_CBCPadBER
DESX with CBC mode AI_DESX_CBC_IV8, AI_DESX_CBCPadIV8, and
AI_DESX_CBCPadBER
RC2 with CBC mode AI_RC2_CBC, AI_RC2_CBCPad,
AI_RC2_CBCPadBER, and AI_RC2_CBCPadPEM
RC5 with CBC mode AI_RC5_CBC and AI_RC5_CBCPad
and 32-bit word
2.33.10 Output considerations:
For encryption, when padding is used, the total number of output
bytes can be as many as one block size more than the total input. For
decryption, the output buffer should be the same size as the input
buffer, even if padding was used.
2.34 AI_HMAC
2.34.1 Purpose:
This AI allows you to create a message authentication code using a
keyed hashing algorithm called HMAC.
2.34.2 Type of information this allows you to use:
the specified digest algorithm for performing HMAC (Hashed-based
Message Authentication Code) as defined in the SET draft standard, a
subset of the Draft-IETF-IPSEC-AH-HMAC-SHA-04.
2.34.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_DIGEST_SPECIFIER structure:
typedef struct {
B_INFO_TYPE digestInfoType;
POINTER digestInfoParams;
} B_DIGEST_SPECIFIER;
BSAFE4.0 only supports AI_SHA1 as a digestInfoType, with NULL_PTR as
the digestInfoParams.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 80]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.34.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_DIGEST_SPECIFIER structure.
2.34.5 BSAFE procedures to use with algorithm object:
B_DigestInit, B_DigestUpdate, and B_DigestFinal. You must pass a key
object compatible with KI_Item with at least one byte of keying
material as the keyObject argument in B_DigestInit. It is recommended
that minimally 20 bytes of key be used when SHA1 is the hash
function. More bytes are recommended if the key bytes are weakly
random (low entropy keys).
2.34.6 Algorithm methods to include in application's algorithm
chooser:
The appropriate AM for the digest specified; for instance, AM_SHA
when the digestInfoType is AI_SHA1.
2.34.7 Output considerations:
The output of B_DigestFinal will be the length of the output of the
digest specified; for instance, 20 bytes when digestInfoType is
AI_SHA1.
2.35 AI_HW_RANDOM
2.35.1 Purpose:
This AI allows you to generate random bytes using a hardware device.
2.35.2 Type of information this allows you to use:
random bytes generated by your hardware device.
2.35.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.35.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.35.5 BSAFE procedures to use with algorithm object:
B_RandomInit and B_GenerateRandomBytes, and as the randomAlgorithm
argument to other procedures.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 81]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.35.6 Algorithm methods to include in application's algorithm
chooser:
AM_HW_RANDOM.
2.35.7 Notes:
Can only be used in conjunction with a hardware implementation; if no
hardware implementation is present, AM_HW_RANDOM does not do
anything. AM_HW_RANDOM can only be used if you have called
B_CreateSessionChooser for your application.
2.36 AI_KeypairTokenGen
2.36.1 Purpose:
This AI allows you to generate the token form of a public/private key
pair with a hardware device.
2.36.2 Type of information this allows you to use:
the parameters for generating the token form of a public/private key
pair. The BSAFE Hardware API (BHAPI) supports token forms of RSA
strong key pair generation as defined in PKCS #1 and DSA key pair
generation as defined in FIPS PUB 186.
2.36.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_KEYPAIR_SPECIFIER structure:
typedef struct {
A_KEYPAIR_DEFINER privateKeyDef; /* Specs for private key */
A_KEYPAIR_DEFINER publicKeyDef;/* Specifications for public key */
POINTER keyParams; /* Points to RSA params in RSA case, ie, */
/* A_RSA_KEY_GEN_PARAMS. */
/* Points to DSA params in DSA case. */
unsigned char *cipherName; /* String tag for key's cipher class */
/* Either "rsa" or "dsa" to tag */
} A_KEYPAIR_SPECIFIER;
where A_KEYPAIR_DEFINER is defined by:
typedef struct {
unsigned int keyUsage; /* X509 key usage bit map */
UINT4 lifeTime; /* Key lifetime; under consideration */
unsigned int protectFlag; /* Store key in encrypted form */
} A_KEYPAIR_DEFINER;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 82]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.36.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_KEYPAIR_SPECIFIER structure (see above).
2.36.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateKeypair. If hardware is present,
B_GenerateKeypair sets the publicKeyDef and privateKeyDef key objects
with the public and private key information from KI_Token. If no
hardware is present, and software emulation methods have been
included in the hardware chooser, B_GenerateKeypair sets the
publicKeyDef and privateKeyDef key objects with the public and
private key information from KI_KeypairToken. You must pass an
initialized random algorithm to B_GenerateKeypair, unless the
hardware manufacturer has it internally implemented. In this case, a
properly cast NULL_PTR should be used.
2.36.6 Algorithm methods to include in application's algorithm
chooser:
the key-pair generation AM specified by cipherName:
cipherName Algorithm methods to include in chooser
"dsa" AM_DSA_KEY_TOKEN_GEN
"rsa" AM_RSA_KEY_TOKEN_GEN
2.36.7 Notes:
Can only be used in conjunction with a hardware implementation or
software emulation; if no hardware implementation is present,
AI_KeypairTokenGen does not do anything. AI_KeypairTokenGen can only
be used if you have called B_CreateSessionChooser for your
application.
The corresponding software-emulation methods passed to
B_CreateSessionChooser via the HARDWARE_CHOOSER list are a
HW_TABLE_ENTRY SF_RSA_KEY_TOKEN_GEN for RSA keys and a HW_TABLE_ENTRY
SF_DSA_KEY_TOKEN_GEN for DSA keys. These provides software support in
the case that hardware is unavailable. These methods can be utilized
only by including inside the hardware chooser table.
At B_GenerateInit the key generation object is bound to the hardware
device, if one is available. If no hardware device is present, the
key-generation object is bound to the software-emulation method if it
has been included in the hardware chooser; it defaults to the null
method otherwise. For example, for an RSA key token, if no hardware
is present, the key generation object is bound to
SF_RSA_KEY_TOKEN_GEN if it is included in the hardware chooser and
defaults to AM_RSA_KEY_TOKEN_GEN otherwise.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 83]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.37 AI_MAC
2.37.1 Purpose:
This AI allows you to create a variable-length message authentication
code on a non-linear feedback shift register. See Appendix B for
detailed description of the algorithm.
2.37.2 Type of information this allows you to use:
the MAC length parameter for the MAC message authentication code
algorithm
2.37.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_MAC_PARAMS structure:
typedef struct {
unsigned int macLen; /* length of MAC value */
} B_MAC_PARAMS;
The minimum macLen is 2.
2.37.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_MAC_PARAMS structure (see above).
2.37.5 BSAFE procedures to use with algorithm object:
B_DigestInit, B_DigestUpdate, and B_DigestFinal. Supply NULL_PTR for
the keyObject argument in B_DigestInit.
2.37.6 Algorithm methods to include in application's algorithm
chooser:
AM_MAC.
2.37.7 Output considerations:
The output of B_DigestFinal will be macLen bytes long.
2.38 AI_MD2
2.38.1 Purpose:
This AI allows you to create a message digest using the MD2 digest
algorithm as defined in RFC 1319. This algorithm processes input data
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 84]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
16 bytes at a time but the length of the input does not have to be a
multiple of 16 as the algorithm pads automatically. The primary use
for this AI is to authenticate data. Other algorithms that can be
used for message digesting are AI_MD5 and AI_SHA1 and their variants.
See AI_MD2_BER for the MD2 algorithm type with BER encoding. See
AI_MD2_PEM for the MD2 algorithm type with PEM encoding.
2.38.2 Type of information this allows you to use:
the MD2 message digest algorithm as defined in RFC 1319.
2.38.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.38.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.38.5 BSAFE procedures to use with algorithm object:
B_DigestInit, B_DigestUpdate, and B_DigestFinal. Supply NULL_PTR for
the keyObject argument in B_DigestInit.
2.38.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2.
2.38.7 Compatible representation:
AI_MD2_BER, AI_MD2_PEM.
2.38.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.39 AI_MD2_BER
2.39.1 Purpose:
This AI represents the same algorithm type as AI_MD2 except that it
uses the ASN.1 BER format. It allows you to parse and create ASN.1
algorithm identifiers such as used in PKCS #7 and other protocols.
You call B_SetAlgorithmInfo to initialize an algorithm object from
the encoded algorithm identifier. You call B_GetAlgorithmInfo with
this AI to create an encoded algorithm identifier from an algorithm
object that was created using AI_MD2, AI_MD2_BER or AI_MD2_PEM. The
OID for this algorithm, excluding the tag and length bytes, in
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 85]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
decimal, is "42, 134, 72, 134, 247, 13, 2, 2". Also see AI_MD2.
2.39.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD2
message digest algorithm as defined in RFC 1319.
2.39.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
a message digest algorithm other than MD2.
2.39.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.39.5 BSAFE procedures to use with algorithm object:
B_DigestInit, B_DigestUpdate, and B_DigestFinal. Supply NULL_PTR for
the keyObject argument in B_DigestInit.
2.39.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2.
2.39.7 Compatible representation:
AI_MD2, AI_MD2_PEM.
2.39.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.40 AI_MD2_PEM
2.40.1 Purpose:
This AI represents the same algorithm type as AI_MD2 except that it
uses the PEM format. It allows you to parse and create PEM algorithm
identifiers such as used in the Privacy Enhanced Mail protocol. You
call B_SetAlgorithmInfo to initialize an algorithm object from the
encoded algorithm identifier. You call B_GetAlgorithmInfo with this
AI to create an encoded algorithm identifier from an algorithm object
that was created using AI_MD2, AI_MD2_BER or AI_MD2_PEM. Also see
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 86]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AI_MD2.
2.40.2 Type of information this allows you to use:
an RFC 1423 identifier that specifies the MD2 message digest
algorithm as defined in RFC 1319. This algorithm info type is
intended to process the digest identifier in a MIC-Info field in a
PEM encapsulated header.
2.40.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the RSA-MD2
identifier. For example, "RSA-MD2." Space and tab characters are
removed from the string before it is copied to the algorithm object.
B_SetAlgorithmInfo returns BE_WRONG_ALGORITHM_INFO if the algorithm
identifier specifies an identifier other than RSA-MD2.
2.40.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the RSA-MD2
identifier.
2.40.5 BSAFE procedures to use with algorithm object:
B_DigestInit, B_DigestUpdate, and B_DigestFinal. Supply NULL_PTR for
the keyObject argument in B_DigestInit.
2.40.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2.
2.40.7 Compatible representation:
AI_MD2, AI_MD2_BER.
2.40.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.41 AI_MD2Random
2.41.1 Purpose:
This AI allows you to generate a stream of pseudo-random numbers
which are guaranteed to have a very high degree of randomness. Random
numbers are used in deriving public and private keys, initialization
vectors, etc. This algorithm is the same as AI_MD5Random described in
RSA Labs Bulletin #8 except that the underlying digest algorithm used
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 87]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
is MD2 instead of MD5. The details of the AI_MD5Random algorithm are
available online at http://www.rsa.com/rsalabs/html/bulletins.html.
Other algorithms that can be used to generate pseudo-random numbers
are AI_MD5Random, AI_SHA1Random, and AI_X962Random_V0.
2.41.2 Type of information this allows you to use:
the MD2-Random algorithm for generating pseudo-random numbers, as
defined by RSA Data Security, Inc.
2.41.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.41.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.41.5 BSAFE procedures to use with algorithm object:
B_RandomInit, B_RandomUpdate, and B_GenerateRandomBytes, and as the
randomAlgorithm argument to other procedures.
2.41.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2_RANDOM.
2.42 AI_MD2WithDES_CBCPad
2.42.1 Purpose:
This AI allows you to perform password-based encryption. This means
that the input data will be encrypted with a secret key derived from
a password, and it can be successfully decrypted only when the
correct password is provided. Although this AI can be used to encrypt
arbitrary data, its intended primary use is for encrypting private
keys when transferring them from one computer system to another, as
described in PKCS #8.
This AI employs DES secret-key encryption in cipher-block chaining
(CBC) mode with padding, where the secret key is derived from a
password using the MD2 message digest algorithm. The details of this
algorithm are contained in PKCS #5. DES is defined in FIPS PUB 81,
and CBC mode of DES is defined in FIPS PUB 46-1. RFC 1319 describes
MD2. Other algorithms that can be used for password-based encryption
are AI_MD5WithDES_CBCPad, AI_MD5WithRC2_CBCPad, AI_MD2WithRC2_CBCPad,
and AI_SHA1WithDES_CBCPad.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 88]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.42.2 Type of information this allows you to use:
the salt and iteration count for the MD2 With DES-CBC password-based
encryption algorithm as defined in PKCS #5.
2.42.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure:
typedef struct {
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_PBE_PARAMS;
2.42.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure (see above).
2.42.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.42.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2 and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.42.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.42.8 Compatible representation:
AI_MD2WithDES_CBCPadBER.
2.42.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.43 AI_MD2WithDES_CBCPadBER
2.43.1 Purpose:
This AI represents the same algorithm type as AI_MD2WithDES_CBCPad
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 89]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the salt
and iteration count. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_MD2WithDES_CBCPad or AI_MD2WithDES_CBCPadBER.
The OID for this algorithm, excluding the tag and length bytes, in
decimal, is "42, 134, 72, 134, 247, 13, 1, 5, 1". Also see
AI_MD2WithDES_CBCPad.
2.43.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD2 With
DES-CBC password-based encryption algorithm as defined in PKCS #5.
2.43.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD2 With DES-CBC.
2.43.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.43.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.43.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2 and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.43.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.43.8 Compatible representation:
AI_MD2WithDES_CBCPad.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 90]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.43.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.44 AI_MD2WithRC2_CBCPad
2.44.1 Purpose:
This AI allows you to perform password-based encryption. This means
that the input data will be encrypted with a secret key derived from
a password, and it can be successfully decrypted only when the
correct password is provided. Although this AI can be used to encrypt
arbitrary data, its intended primary use is for encrypting private
keys when transferring them from one computer system to another, as
described in PKCS #8.
This AI employs RC2 block cipher with padding, where the secret key
is derived from a password using the MD2 message digest algorithm.
MD2 is described in RFC 1319. RC2 is described in RFC 2268. The CBC
mode is similar to the one used in RC5-CBC which can be found in RFC.
Other algorithms that can be used for password-based encryption are
AI_MD5WithDES_CBCPad, AI_MD5WithRC2_CBCPad, AI_MD2WithDES_CBCPad, and
AI_SHA1WithDES_CBCPad.
2.44.2 Type of information this allows you to use:
the effective key size, salt, and iteration count for the MD2 With
RC2-CBC password-based encryption algorithm, as defined by RSA Data
Security, Inc.
2.44.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_RC2_PBE_PARAMS structure:
typedef struct {
unsigned int effectiveKeyBits; /* effective key size in bits */
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_RC2_PBE_PARAMS;
2.44.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_RC2_PBE_PARAMS structure (see above).
2.44.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 91]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.44.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2 and AM_RC2_CBC_ENCRYPT for encrypting or AM_RC2_CBC_DECRYPT
for decrypting.
2.44.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.44.8 Compatible representation:
AI_MD2WithRC2_CBCPadBER.
2.44.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.45 AI_MD2WithRC2_CBCPadBER
2.45.1 Purpose:
This AI represents the same algorithm type as AI_MD2WithRC2_CBCPad
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the
effective key size, salt and iteration count. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_MD2WithRC2_CBCPad or AI_MD2WithRC2_CBCPadBER. The OID for this
algorithm, excluding the tag and length bytes, in decimal, is "42,
134, 72, 134, 247, 13, 1, 5, 4". Also see AI_MD2WithRC2_CBCPad.
2.45.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD2 With
RC2-CBC password-based encryption algorithm, as defined by RSA Data
Security, Inc.
2.45.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 92]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
an algorithm other than MD2 With RC2-CBC.
2.45.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.45.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.45.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2 and AM_RC2_CBC_ENCRYPT for encrypting or AM_RC2_CBC_DECRYPT
for decrypting.
2.45.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.45.8 Compatible representation:
AI_MD2WithRC2_CBCPad.
2.45.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.46 AI_MD2WithRSAEncryption
2.46.1 Purpose:
This AI allows you to perform signature operations that involve the
MD2 digest algorithm and RSA public key algorithm. The digest of a
message is created using the MD2 algorithm and then it is signed
using PKCS#1 digital signature algorithm. Other algorithms that can
be used for the same purpose are AI_MD5WithRSAEncryption and
AI_SHA1WithRSAEncryption. See AI_MD2WithRSAEncryptionBER for the same
algorithm type with BER encoding.
2.46.2 Type of information this allows you to use:
the MD2 With RSA Encryption signature algorithm that uses the MD2
digest algorithm and RSA to create and verify RSA digital signatures
as defined in PKCS #1. Note that in order to perform PKCS #1 digital
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 93]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
signatures with a 16-byte digest, the RSA key must be at least 360
bits long.
2.46.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.46.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.46.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.46.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD2 and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
2.46.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, or KI_PKCS_RSAPrivateBER.
2.46.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic or KI_RSAPublicBER.
2.46.9 Compatible representation:
AI_MD2WithRSAEncryptionBER.
2.46.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.46.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 94]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.47 AI_MD2WithRSAEncryptionBER
2.47.1 Purpose:
This AI represents the same algorithm type as AI_MD2WithRSAEncryption
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_MD2WithRSAEncryption or AI_MD2WithRSAEncryptionBER. The OID for
this algorithm, excluding the tag and length bytes, in decimal, is
"42, 134, 72, 134, 247, 13, 1, 1, 2". Also see
AI_MD2WithRSAEncryption.
2.47.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD2 With
RSA Encryption signature algorithm that uses the MD2 digest algorithm
and RSA to create and verify RSA digital signatures as defined in
PKCS #1.
Note that in order to perform PKCS #1 digital signatures with a
16-byte digest, the RSA key must be at least 360 bits long.
2.47.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD2 With RSA Encryption.
2.47.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.47.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.47.6 Algorithm methods to include in application's algorithm
chooser:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 95]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AM_MD2 and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
2.47.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, or KI_PKCS_RSAPrivateBER.
2.47.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic or KI_RSAPublicBER.
2.47.9 Compatible representation:
AI_MD2WithRSAEncryption.
2.47.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.47.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
2.48 AI_MD5
2.48.1 Purpose:
This AI allows you to create a message digest using the MD5 digest
algorithm as defined in RFC 1321. This algorithm processes input data
64 bytes at a time but the length of the input does not have to be a
multiple of 64 as the algorithm pads automatically.
The primary use for this AI is to authenticate data. Other algorithms
that can be used for message digesting are AI_MD2 and AI_SHA1 and
their variants.
2.48.2 Type of information this allows you to use:
the MD5 message digest algorithm as defined in RFC 1321.
2.48.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 96]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.48.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.48.5 BSAFE procedures to use with algorithm object:
Call B_DigestInit to prepare this object for digesting data, and
supply NULL_PTR for the keyObject argument. Then call B_DigestUpdate
zero or more times supplying it with the data to digest. You might
want to call this function more than once if you have separate units
of data, such as two or more files or several strings. Finally, call
B_DigestFinal to finalize the digesting process and retrieve the
result. This call reinitializes the object, so you can start a new
digest without calling B_DigestInit first.
2.48.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5.
2.48.7 Compatible representation:
AI_MD5_BER, AI_MD5_PEM.
2.48.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.49 AI_MD5_BER
2.49.1 Purpose:
This AI represents the same algorithm type as AI_MD5 except that it
uses the ASN.1 BER format. This AI allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using AI_MD5,
AI_MD5_BER or AI_MD5_PEM. The OID for this algorithm, excluding the
tag and length bytes, in decimal is "42, 134, 72, 134, 247, 13, 2,
5".
2.49.2 Type of information this allows you to use:
The encoding of an algorithm identifier that specifies the MD5
message digest algorithm as defined in RFC 1321.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 97]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.49.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
a message digest algorithm other than MD5.
2.49.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.49.5 BSAFE procedures to use with algorithm object:
Call B_DigestInit to prepare this object for digesting data, and
supply NULL_PTR for the keyObject argument. Then call B_DigestUpdate
zero or more times supplying it with the data to digest. You might
want to call this function more than once if you have separate units
of data, such as two or more files or several strings. Finally, call
B_DigestFinal to finalize the digesting process and retrieve the
result. This call reinitializes the object, so you can start a new
digest without calling B_DigestInit first.
2.49.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5.
2.49.7 Compatible representation:
AI_MD5, AI_MD5_PEM.
2.49.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.50 AI_MD5_PEM
2.50.1 Purpose:
This AI represents the same algorithm type as AI_MD5 except that it
uses the PEM format. This AI allows you to parse and create PEM
algorithm identifiers such as used in Privacy Enhanced Mail protocol.
You call B_SetAlgorithmInfo to initialize an algorithm object from
the encoded algorithm identifier. You call B_GetAlgorithmInfo with
this AI to create an encoded algorithm identifier from an algorithm
object that was created using AI_MD5, AI_MD5_BER, or AI_MD5_PEM.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 98]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.50.2 Type of information this allows you to use:
an RFC 1423 identifier that specifies the MD5 message digest
algorithm as defined in RFC 1321. This algorithm info type is
intended to process the digest identifier in a MIC-Info field in a
PEM encapsulated header.
2.50.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the RSA-MD5
identifier. For example, "Rsa-MD5". Space and tab characters are
removed from the string before it is copied to the algorithm object.
B_SetAlgorithmInfo returns BE_WRONG_ALGORITHM_INFO if the algorithm
identifier specifies an identifier other than RSA-MD5.
2.50.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the RSA-MD5
identifier.
2.50.5 BSAFE procedures to use with algorithm object:
Call B_DigestInit to prepare this object for digesting data, and
supply NULL_PTR for the keyObject argument. Then call B_DigestUpdate
zero or more times supplying it with the data to digest. You might
want to call this function more than once if you have separate units
of data, such as two or more files or several strings. Finally, call
B_DigestFinal to finalize the digesting process and retrieve the
result. This call reinitializes the object, so you can start a new
digest without calling B_DigestInit first.
2.50.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5.
2.50.7 Compatible representation:
AI_MD5, AI_MD5_BER.
2.50.8 Output considerations:
The output of B_DigestFinal will be 16 bytes long.
2.51 AI_MD5Random
2.51.1 Purpose:
This AI allows you to generate a stream of pseudo-random numbers
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 99]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
which are guaranteed to have a very high degree of randomness. Random
numbers are used in deriving public and private keys, initialization
vectors, etc. This AI uses MD5 as an underlying hashing function. The
details of this algorithm are available from RSA Laboratories'
Bulletin #8, or online at
http://www.rsa.com/rsalabs/html/bulletins.html.
Other algorithms that can be used to generate pseudo-random numbers
are AI_MD2Random, AI_SHA1Random, and AI_X962Random_V0.
2.51.2 Type of information this allows you to use:
the MD5-Random algorithm for generating pseudo-random numbers.
2.51.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.51.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.51.5 BSAFE procedures to use with algorithm object:
This AI should be initialized with the call to B_RandomInit. It
should be seeded with a call to B_RandomUpdate.
Call B_GenerateRandomBytes one or more times to obtain the
pseudo-random byte stream. You may call B_RandomUpdate between calls
to B_GenerateRandomBytes to provide additional seeding.
This AI can be used as the randomAlgorithm argument to other
procedures.
2.51.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5_RANDOM.
2.52 AI_MD5WithDES_CBCPad
2.52.1 Purpose:
This AI allows you to perform password-based encryption. This means
that the input data will be encrypted with a secret key derived from
a password, and it can be successfully decrypted only when the
correct password is provided. Although this AI can be used to encrypt
arbitrary data, its intended primary use is for encrypting private
keys when transferring them from one computer system to another, as
described in PKCS #8.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 100]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
This AI employs DES secret-key encryption in cipher-block chaining
(CBC) mode with padding, where the secret key is derived from a
password using the MD5 message digest algorithm. The details of this
algorithm are contained in PKCS #5. DES is defined in FIPS PUB 81,
and CBC mode of DES is defined in FIPS PUB 46-1. RFC 1321 describes
MD5. Other algorithms that can be used for password-based encryption
are AI_MD2WithDES_CBCPad, AI_MD2WithRC2_CBCPad, AI_MD5WithRC2_CBCPad,
and AI_SHA1WithDES_CBCPad.
2.52.2 Type of information this allows you to use:
the salt and iteration count for the MD5 With DES-CBC password-based
encryption algorithm as defined in PKCS #5. The salt is concatenated
with the password before being digested by MD5, and the iteration
count specifies how many times the digest needs to be run. The count
of 2 indicates that the result of digesting password-and-salt string
needs to be run once more through MD5. The first 8 bytes of the final
digest become the secret key for the DES cipher after being adjusted
for parity as required by FIPS PUB 81, and the last 8 bytes become
the initialization vector.
2.52.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure:
typedef struct {
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_PBE_PARAMS;
2.52.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure (see above).
2.52.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 101]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.52.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.52.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.52.8 Compatible representation:
AI_MD5WithDES_CBCPadBER.
2.52.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.53 AI_MD5WithDES_CBCPadBER
2.53.1 Purpose:
This AI represents the same algorithm type as AI_MD5WithDES_CBCPad
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier which includes
ASN.1 encoding of the B_PBE_PARAMS structure defined in the
description of AI_MD5WithDES_CBCPad. You call B_GetAlgorithmInfo with
this AI to create an encoded algorithm identifier from an algorithm
object that was created using AI_MD5WithDES_CBCPad or
AI_MD5WithDES_CBCPad. The OID for this algorithm, excluding the tag
and length bytes, in decimal is "42, 134, 72, 134, 247, 13, 1, 5, 3"
2.53.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD5 With
DES-CBC password-based encryption algorithm as defined in PKCS #5.
2.53.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD5 With DES-CBC.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 102]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.53.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.53.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.53.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.53.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.53.8 Compatible representation:
AI_MD5WithDES_CBCPad.
2.53.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.54 AI_MD5WithRC2_CBCPad
2.54.1 Purpose:
This AI allows you to perform password-based encryption. This means
that the input data will be encrypted with a secret key derived from
a password, and it can be successfully decrypted only when the
correct password is provided. Although this AI can be used to encrypt
arbitrary data, its intended primary use is for encrypting private
keys when transferring them from one computer system to another, as
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 103]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
described in PKCS #8.
This AI employs RC2 block cipher with padding, where the secret key
is derived from a password using the MD5 message digest algorithm.
MD5 is described in RFC 1321. RC2 is described in RFC 2268. The CBC
mode is similar to the one used in RC5-CBC which can be found in RFC
2040.
Other algorithms that can be used for password-based encryption are
AI_MD2WithDES_CBCPad, AI_MD2WithRC2_CBCPad, AI_MD5WithDES_CBCPad, and
AI_SHA1WithDES_CBCPad.
2.54.2 Type of information this allows you to use:
the effective key size, salt, and iteration count for the MD5 With
RC2-CBC password-based encryption algorithm. The salt is concatenated
with the password before being processed by MD5, and the iteration
count specifies how many times the digest needs to be run. The count
of 2 indicates that the result of digesting password-and-salt string
needs to be run once more through MD5. The first 8 bytes of the final
digest are used as an initialization vector for cipher-block chaining
mode, while the last 8 bytes are supplied as the key material to the
RC2_CBCPad algorithm. This algorithm modifies the 64 key bits
according to the effectiveKeyBits parameter. RSA Data Security, Inc.
recommends using values between 40 and 128 bits for the
effectiveKeyBits parameter. Since only 64 bits of key material are
supplied to the algorithm, effectiveKeyBits values over 64 bits do
not improve security.
2.54.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_RC2_PBE_PARAMS structure:
typedef struct {
unsigned int effectiveKeyBits; /* effective key size in bits */
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_RC2_PBE_PARAMS;
2.54.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_RC2_PBE_PARAMS structure (see above).
2.54.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 104]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.54.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_RC2_CBC_ENCRYPT for encrypting or AM_RC2_CBC_DECRYPT
for decrypting.
2.54.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.54.8 Compatible representation:
AI_MD5WithRC2_CBCPadBER.
2.54.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.55 AI_MD5WithRC2_CBCPadBER
2.55.1 Purpose:
This AI represents the same algorithm type as AI_MD5WithRC2_CBCPad
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier which includes
ASN.1 encoding of the B_RC2_PBE_PARAMS structure defined in the
description of AI_MD5WithRC2_CBCPad. You call B_GetAlgorithmInfo with
this AI to create an encoded algorithm identifier from an algorithm
object that was created using AI_MD5WithRC2_CBCPad or
AI_MD5WithRC2_CBCPadBER. The OID for this algorithm, excluding the
tag and length bytes, in decimal is "42, 134, 72, 134, 247, 13, 1, 5,
6"
2.55.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD5 With
RC2-CBC password-based encryption algorithm.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 105]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.55.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD5 With RC2-CBC.
2.55.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.55.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.55.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_RC2_CBC_ENCRYPT for encrypting or AM_RC2_CBC_DECRYPT
for decrypting.
2.55.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.55.8 Compatible representation:
AI_MD5WithRC2_CBCPad.
2.55.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.56 AI_MD5WithRSAEncryption
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 106]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.56.1 Purpose:
This AI allows you to perform signature operations that involve the
MD5 digest algorithm and RSA public key algorithm. The digest of a
message is created using the MD5 algorithm and then it is signed
using PKCS#1 digital signature algorithm. Other algorithms that can
be used for the same purpose are AI_MD2WithRSAEncryption and
AI_SHA1WithRSAEncryption.
2.56.2 Type of information this allows you to use:
the MD5 With RSA signature algorithm that uses the MD5 digest
algorithm and RSA to create and verify RSA digital signatures as
defined in PKCS #1. Note that in order to perform PKCS #1 digital
signatures with a 16-byte digest, the RSA key must be at least 360
bits long.
2.56.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.56.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.56.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_SignInit. Then call
B_SignUpdate zero or more times to sign your data. You may want to
call this function more than once if the data to sign resides in
separate files or buffers. Call B_SignFinal to obtain the signature.
To verify the signature, call B_VerifyInit and then call
B_VerifyUpdate zero or more times supplying it with input data. Call
B_VerifyFinal and pass the signature that you want to verify.
B_VerifyFinal returns BE_SIGNATURE if the signature of the input data
does not match the signature that was passed as an argument to it.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.56.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 107]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.56.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.56.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic, KI_RSAPublicBER.
2.56.9 Compatible representation:
AI_MD5WithRSAEncryptionBER.
2.56.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.56.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
2.57 AI_MD5WithRSAEncryptionBER
2.57.1 Purpose:
This AI represents the same algorithm type as AI_MD5WithRSAEncryption
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_MD5WithRSAEncryption or AI_MD5WithRSAEncryptionBER. The OID for
this algorithm, excluding the tag and length bytes, in decimal is
"42, 134, 72, 134, 247, 13, 1, 1, 4"
2.57.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD5 With
RSA signature algorithm that uses the MD5 digest algorithm and RSA to
create and verify RSA digital signatures as defined in PKCS #1.
Note that in order to perform PKCS #1 digital signatures with a
16-byte digest, the RSA key must be at least 360 bits long.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 108]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.57.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD5 With RSA Encryption.
2.57.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.57.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_SignInit. Then call
B_SignUpdate zero or more times to sign your data. You may want to
call this function more than once if the data to sign resides in
separate files or buffers. Call B_SignFinal to obtain the signature.
To verify the signature, call B_VerifyInit and then call
B_VerifyUpdate zero or more times supplying it with input data. Call
B_VerifyFinal and pass the signature that you want to verify.
B_VerifyFinal returns BE_SIGNATURE if the signature of the input data
does not match the signature supplied for verification.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.57.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
2.57.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.57.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic, KI_RSAPublicBER.
2.57.9 Compatible representation:
AI_MD5WithRSAEncryption.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 109]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.57.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.57.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
2.58 AI_MD5WithXOR
2.58.1 Purpose:
This AI is used for encrypting the file keys. This algorithm
implements a variant of password-based encryption. The data
being encrypted is XOR'ed with a secret key derived from a password,
and it can be successfully decrypted only when the correct password
is provided. Since the secret key is a 128-bit output of MD5 message
digest algorithm, the data being encrypted should be no longer than
128 bits. Description of MD5 can be found in RFC 1321.
2.58.2 Type of information this allows you to use:
the salt and iteration count for the MD5 With XOR password-based
encryption algorithm. The salt is concatenated with the password
before being digested by MD5, and the iteration count specifies how
many times the digest needs to be run. The count of 2 indicates that
the result of digesting password-and-salt string needs to be run once
more through MD5. The final digest is XOR'ed with the data to obtain
the encryption.
2.58.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure:
typedef struct {
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_PBE_PARAMS;
2.58.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure (see above).
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 110]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.58.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.58.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_MD5_RANDOM.
2.58.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.58.8 Compatible representation:
AI_MD5WithXOR_BER.
2.59 AI_MD5WithXOR_BER
2.59.1 Purpose:
This AI represents the same algorithm type as AI_MD5WithXOR except
that it uses the ASN.1 BER format. This AI allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier which includes ASN.1
encoding of the B_PBE_PARAMS structure defined in the description of
AI_MD5WithXOR. You call B_GetAlgorithmInfo with this AI to create an
encoded algorithm identifier from an algorithm object that was
created using AI_MD5WithXOR or AI_MD5WithXOR_BER. The OID for this
algorithm, excluding the tag and length bytes, in decimal is "42,
134, 72, 134, 247, 13, 1, 5, 9"
2.59.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the MD5 With
XOR password-based encryption algorithm, as defined by RSA Data
Security, Inc.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 111]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.59.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than MD5 With XOR.
2.59.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.59.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.59.6 Algorithm methods to include in application's algorithm
chooser:
AM_MD5 and AM_MD5_RANDOM.
2.59.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the password.
2.59.8 Compatible representation:
AI_MD5WithXOR.
2.60 AI_PKCS_OAEP_RSAPrivate
2.60.1 Purpose:
This AI allows you to decrypt data using the RSA public-key algorithm
with the OAEP padding scheme defined in PKCS #1 v2.0. The OAEP
padding scheme prevents a theoretical attack on interactive
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 112]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
key-establishment protocols that use PKCS #1 v1.5. The parameters of
this algorithm include the hash function, mask generator function and
P source function that are explained below. AI_PKCS_RSAPrivate
provides the PKCS #1 v1.5 version of the RSA private key decryption
algorithm. AI_SET_OAEP_RSAPrivate provides a different type of OAEP
padding scheme defined by the SET specification. See
AI_PKCS_OAEP_RSAPrivateBER for the same algorithm type with BER
encoding.
2.60.2 Type of information this allows you to use:
the RSA algorithm for performing private key decryption with OAEP
message padding as defined in PKCS #1 v2.0 (DRAFT 1- July 14, 1998).
When decrypting, this algorithm decodes the data according to the
definition of EME-OAEP-Decode as specified in PKCS #1 v2.0.
2.60.3 Format of info supplied to B_SetAlgorithmInfo:
either:
NULL_PTR. The following parameters are employed when NULL_PTR is
specified:
PKCS OAEP RSA PARAMETER DEFAULT PARAMETERDEFAULT
PARAMS
hashFunc "sha1" EMPTY ITEM
maskGenFunc "mgf1" EMPTY ITEM
maskGenFuncUnderlyingAlg "sha1" EMPTY ITEM
pSourceFunc "specifiedParameters" EMPTY ITEM
or:
a pointer to an A_PKCS_OAEP_PARAMS structure:
typedef struct {
/* hashFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "sha1". In both cases SHA1 will
become the digest function.
*/
unsigned char* hashFunc;
ITEM hashFuncParams;
/* maskGenFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "mgf1". In both cases MGF1 will
become the Mask Generator Function.
*/
unsigned char* maskGenFunc;
ITEM maskGenFuncParams;
/* maskGenFuncUnderlyingAlg may contain a NULL_PTR or a pointer
to the null-terminated ASCII string, "sha1". In both cases SHA1
will become the underlying algorithm.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 113]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
*/
unsigned char* maskGenFuncUnderlyingAlg;
ITEM maskGenFuncUnderlyingAlgParams;
/* pSourceFunc is the method for determining the PKCS #1 v2.0 OAEP
parameter, P. pSourceFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "specifiedParameters". In both cases
"specifiedParameters" will become the pSource method.
If pSourceFunc is "specifiedParameters" and if pSourceParams.len = 0,
then P is assumed to be empty. pSourceParams may also be initialized
to the caller's data as in this example:
pSourceParams.len = sizeof(dataObject);
pSourceParams.data = &dataObject;
*/
unsigned char* pSourceFunc;
ITEM pSourceParams;
} A_PKCS_OAEP_PARAMS;
The parameters hashFuncParams, maskGenFuncParams, and
maskGenFuncUnderlyingAlgParams are available to provide for future
growth. The caller should initialize these parameters as ITEM types
as follows:
hashFuncParams.len = 0;
hashFuncParams.data = NULL_PTR
maskGenFuncParams.len = 0;
maskGenFuncParams.data = NULL_PTR
maskGenFuncUnderlyingAlgParams.len = 0;
maskGenFuncUnderlyingAlgParams.data = NULL_PTR
Failure to properly implement these parameters may cause bugs when
they are implemented in future versions of BSAFE.
The default parameters for pSourceParams should be set by the caller
as follows:
pSourceParams.len = 0;
pSourceParams.data = NULL_PTR;
2.60.4 Format of info supplied to B_GetAlgorithmInfo:
NULL_PTR.
2.60.5 BSAFE procedures to use with algorithm object:
B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for the randomAlgorithm
argument in B_DecryptUpdate and B_DecryptFinal.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 114]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.60.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_DECRYPT_BLIND will perform blinding to protect against
timing attacks and AM_RSA_CRT_DECRYPT will not.
AM_SHA is required for the default pSource digest function. It is
also required for MGF1 as underlying algorithm.
2.60.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, or KI_PKCS_RSAPrivateBER.
2.60.8 Compatible representation:
AI_PKCS_OAEP_RSAPrivateBER.
2.60.9 Output considerations:
The output of decryption will be the same size as the original
message.
2.61 AI_PKCS_OAEP_RSAPrivateBER
2.61.1 Purpose:
This AI represents the same algorithm type
as AI_PKCS_OAEP_RSAPrivate except that it uses the ASN.1 BER
format. It allows you to parse and create ASN.1 algorithm
identifiers such as used in PKCS #7 and other protocols.
You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the hash
function, mask generator function and P source function. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_OAEP_RSAPrivate or AI_PKCS_OAEP_RSAPrivateBER. The OID for
the RSA OAEP encryption, excluding the tag and length bytes, in
decimal, is "42, 134, 72, 134, 247, 13, 1, 1, 7". The OID for the
mask function, excluding the tag and length bytes, in decimal, is
"42, 134, 72, 134, 247, 13, 1, 1, 8". The OID for the P source
function, excluding the tag and length bytes, in decimal, is "42,
134, 72, 134, 247, 13, 1, 1, 9". Also see AI_PKCS_OAEP_RSAPrivate.
2.61.2 Type of information this allows you to use:
the RSA algorithm for performing private key decryption with OAEP
message padding as defined in PKCS #1 v2.0 (DRAFT 1- July 14, 1998).
When decrypting, this algorithm decodes the data according to the
definition of EME-OAEP-Decode as specified in PKCS #1 v2.0.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 115]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.61.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an item structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RSAES-OAEP Encryption as specified by PKCS #1
v2.0.
The general ASN.1 syntax for RSAES-OAEP is complicated, the simple
DER encoding of the default algorithm is given first, followed by the
general syntax.
-- Default Algorithm Identifier for RSAES-OAEP.
-- The DER Encoding of this is in hexadecimal given below.
-- Notice that the DER encoding of the default parameters
-- is just an empty sequence.
-- 30 0D
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 07
-- 30 00
--
RSAES-OAEP-Default-Identifier ::= AlgorithmIdentifier {
id-RSAES-OAEP,
{ sha1Identifier,
mgf1SHA1Identifier,
pSpecifiedEmptyIdentifier
}
}
The general syntax is:
RSAES-OAEP ::= Sequence {
algorithm OBJECT IDENTIFIER (id-RSAES-OAEP),
parameters RSAES-OAEP-params
}
-- Identifier for PKCS #1 v2.0 OAEP.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 07
--
id-RSAES-OAEP OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) RSAES-OAEP(7)}
-- Identifier for the PKCS #1 v2.0 mask generation function,
-- which takes a hash function AlgID as a parameter.
-- The DER for this in hexadecimal is:
-- 06 09
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 116]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
-- 2A 86 48 86 F7 0D 01 01 08
--
id-mgf1 OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) mgf1(8)}
-- The identifier says that the algorithm by which the P
-- string for RSAES-OAEP is generated is by setting it
-- equal to the contents of the OCTET STRING which is
-- the parameter for this AlgorithmIdentifier.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 09
--
id-pSpecified OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) pSpecified(9)}
-- Identifier for the SHA1 digest function.
-- The DER for this in hexadecimal is:
-- 06 05
-- 2B 0E 03 02 1A
--
id-sha1 OBJECT IDENTIFIER ::= {
iso(1) identified-organization(3) oiw(14) secsig(3)
algorithms(2) sha1(26) }
-- Syntax of AlgorithmIdentifier.parameters for RSAES-OAEP.
-- Note that the tags in this Sequence are explicit.
-- The DER encoding of DEFAULT values is to omit them.
--
RSAES-OAEP-params ::= SEQUENCE {
hashFunc [0] AlgorithmIdentifier {
{oaepDigestAlgorithms} }
DEFAULT sha1Identifier,
maskGenFunc [1] AlgorithmIdentifier {
{pkcs1MGFAlgorithms} }
DEFAULT mgf1SHA1Identifier,
pSourceFunc [2] AlgorithmIdentifier {
{pkcs1PGenAlgorithms} }
DEFAULT pSpecifiedEmptyIdentifier
}
-- Algorithm Identifier for SHA1, which is the OAEP default.
--
sha1Identifier ::= AlgorithmIdentifier {
id-sha1, NULL }
-- Default AlgorithmIdentifier for id-RSAES-OAEP.maskGenFunc.
--
mgf1SHA1Identifier ::= AlgorithmIdentifier {
id-mgf1, sha1Identifier }
-- This identifier means that P is an empty string, so the digest
-- of the empty string appears in the RSA block before masking.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 117]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
--
pSpecifiedEmptyIdentifier ::= AlgorithmIdentifier {
id-pSpecified, OCTET STRING SIZE (0)
}
2.61.4 Format of info supplied to B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.61.5 BSAFE procedures to use with algorithm object:
The following procedures perform OAEP padding with encryption:
B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for the randomAlgorithm
argument in B_DecryptUpdate and B_DecryptFinal.
2.61.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_DECRYPT_BLIND will perform blinding to protect against
timing attacks and AM_RSA_CRT_DECRYPT will not.
AM_SHA is required for the default pSource digest function. It is
also required for MGF1 as underlying algorithm.
2.61.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, or KI_PKCS_RSAPrivateBER.
2.61.8 Compatible representation:
AI_PKCS_OAEP_RSAPrivate.
2.61.9 Output considerations:
The output of decryption will be the same size as the original
message.
2.62 AI_PKCS_OAEP_RSAPublic
2.62.1 Purpose:
This AI allows you to encrypt data using the
RSA public-key algorithm with the OAEP padding scheme defined in
PKCS #1 v2.0. The OAEP padding scheme prevents a theoretical attack
on interactive key-establishment protocols that use PKCS #1 v1.5.
The parameters of this algorithm include the hash function, mask
generator function and P source function that are explained below.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 118]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AI_PKCS_RSAPublic provides the PKCS #1 v1.5 version of the RSA
public key encryption algorithm. AI_SET_OAEP_RSAPublic provides
a different type of OAEP padding scheme defined by the SET
specification. See AI_PKCS_OAEP_RSAPublicBER for the same
algorithm type with BER encoding.
2.62.2 Type of information this allows you to use:
the RSA algorithm for performing public key encryption with OAEP
message padding as defined in PKCS #1 v2.0 (DRAFT 1- July 14, 1998).
When encrypting, this algorithm encodes the data according to the
definition of EME-OAEP-Encode as specified in PKCS #1 v2.0.
2.62.3 Format of info supplied to B_SetAlgorithmInfo:
either:
NULL_PTR. The following parameters are employed when NULL_PTR is
specified:
PKCS OAEP RSA PARAMETER DEFAULT PARAMETER DEFAULT PARAMS
hashFunc "sha1" EMPTY ITEM
maskGenFunc "mgf1" EMPTY ITEM
maskGenFuncUnderlyingAlg "sha1" EMPTY ITEM
pSourceFunc "specifiedParameters" EMPTY ITEM
or:
a pointer to an A_PKCS_OAEP_PARAMS structure:
typedef struct {
/* hashFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "sha1". In both cases SHA1 will
become the digest function.
*/
unsigned char* hashFunc;
ITEM hashFuncParams;
/* maskGenFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "mgf1". In both cases MGF1 will
become the Mask Generator Function.
*/
unsigned char* maskGenFunc;
ITEM maskGenFuncParams;
/* maskGenFuncUnderlyingAlg may contain a NULL_PTR or a pointer
to the null-terminated ASCII string, "sha1". In both cases SHA1
will become the underlying algorithm.
*/
unsigned char* maskGenFuncUnderlyingAlg;
ITEM maskGenFuncUnderlyingAlgParams;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 119]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* pSourceFunc is the method for determining the PKCS #1 v2.0 OAEP
parameter, P. pSourceFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "specifiedParameters". In both cases
"specifiedParameters" will become the pSource method.
If pSourceFunc is "specifiedParameters" and if pSourceParams.len = 0,
then P is assumed to be empty. pSourceParams may also be initialized
to the caller's data as in this example:
pSourceParams.len = sizeof(dataObject);
pSourceParams.data = &dataObject;
*/
unsigned char* pSourceFunc;
ITEM pSourceParams;
} A_PKCS_OAEP_PARAMS;
The parameters hashFuncParams, maskGenFuncParams, and
maskGenFuncUnderlyingAlgParams are available to provide for future
growth. The caller should initialize these parameters as ITEM types
as follows:
hashFuncParams.len = 0;
hashFuncParams.data = NULL_PTR
maskGenFuncParams.len = 0;
maskGenFuncParams.data = NULL_PTR
maskGenFuncUnderlyingAlgParams.len = 0;
maskGenFuncUnderlyingAlgParams.data = NULL_PTR
Failure to properly implement these parameters may cause bugs when
they are implemented in future versions of BSAFE.
The default parameters for pSourceParams should be set by the caller
as follows:
pSourceParams.len = 0;
pSourceParams.data = NULL_PTR;
2.62.4 Format of info supplied to B_GetAlgorithmInfo:
NULL_PTR.
2.62.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal.
B_EncryptFinal requires a valid random number generator as a
B_ALGORITHM_OBJ in its randomAlgorithm argument. PKCS #1 v2.0 does
not specify the random number generation method. It is recommended
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 120]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
that AI_X962Random_V0 or AI_SHA1Random be initialized with enough
seed bytes to produce 160 bits of entropy.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for the randomAlgorithm
argument in B_EncryptUpdate.
2.62.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT.
AM_SHA is required for the default pSource digest function and also
for the default MGF underlying digest method.
2.62.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic or KI_RSAPublicBER.
2.62.8 Compatible representation:
AI_PKCS_RSAPublicBER.
2.62.9 Input constraints:
The key's modulus must be at least [(2 * hLen) + 2] bytes longer than
the message.
2.62.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.63 AI_PKCS_OAEP_RSAPublicBER
2.63.1 Purpose:
This AI represents the same algorithm type as
AI_PKCS_OAEP_RSAPublic except that it uses the ASN.1 BER format.
It allows you to parse and create ASN.1 algorithm identifiers such
as used in PKCS #7 and other protocols. You call
B_SetAlgorithmInfo to initialize an algorithm object from the
encoded algorithm identifier that includes the hash
function, mask generator function and P source function. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_OAEP_RSAPublic or AI_PKCS_OAEP_RSAPublicBER. The OID for the
RSA OAEP encryption, excluding the tag and length bytes, in decimal,
is "42, 134, 72, 134, 247, 13, 1, 1, 7". The OID for the mask
function, excluding the tag and length bytes, in decimal, is "42,
134, 72, 134, 247, 13, 1, 1, 8". The OID for the P source function,
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 121]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
excluding the tag and length bytes, in decimal, is "42, 134, 72,
134, 247, 13, 1, 1, 9". Also see AI_PKCS_OAEP_RSAPublic.
2.63.2 Type of information this allows you to use:
the RSA algorithm for performing public key encryption with OAEP
message padding as defined in PKCS #1 v2.0 (DRAFT 1- July 14, 1998).
When encrypting, this algorithm encodes the data according to the
definition of EME-OAEP-Encode as specified in PKCS #1 v2.0.
2.63.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an item structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RSAES-OAEP Encryption as specified by PKCS #1
v2.0.
The general ASN.1 syntax for RSAES-OAEP is complicated. Here the
simple DER encoding of the default algorithm is given first, followed
by the general syntax.
-- Default Algorithm Identifier for RSAES-OAEP.
-- The DER Encoding of this is in hexadecimal given below.
-- Notice that the DER encoding of the default parameters
-- is just an empty sequence.
-- 30 0D
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 07
-- 30 00
--
RSAES-OAEP-Default-Identifier ::= AlgorithmIdentifier {
id-RSAES-OAEP,
{ sha1Identifier,
mgf1SHA1Identifier,
pSpecifiedEmptyIdentifier
}
}
The general syntax is:
RSAES-OAEP ::= Sequence {
algorithm OBJECT IDENTIFIER (id-RSAES-OAEP),
parameters RSAES-OAEP-params
}
-- Identifier for PKCS #1 v2.0 OAEP.
-- The DER for this in hexadecimal is:
-- 06 09
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 122]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
-- 2A 86 48 86 F7 0D 01 01 07
--
id-RSAES-OAEP OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) RSAES-OAEP(7)}
-- Identifier for the PKCS #1 v2.0 mask generation function,
-- which takes a hash function AlgID as a parameter.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 08
--
id-mgf1 OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) mgf1(8)}
-- The identifier says that the algorithm by which the P
-- string for RSAES-OAEP is generated is by setting it
-- equal to the contents of the OCTET STRING which is
-- the parameter for this AlgorithmIdentifier.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 09
--
id-pSpecified OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) pSpecified(9)}
-- Identifier for the SHA1 digest function.
-- The DER for this in hexadecimal is:
-- 06 05
-- 2B 0E 03 02 1A
--
id-sha1 OBJECT IDENTIFIER ::= {
iso(1) identified-organization(3) oiw(14) secsig(3)
algorithms(2) sha1(26) }
-- Syntax of AlgorithmIdentifier.parameters for RSAES-OAEP.
-- Note that the tags in this Sequence are explicit.
-- The DER encoding of DEFAULT values is to omit them.
--
RSAES-OAEP-params ::= SEQUENCE {
hashFunc [0] AlgorithmIdentifier {
{oaepDigestAlgorithms} }
DEFAULT sha1Identifier,
maskGenFunc [1] AlgorithmIdentifier {
{pkcs1MGFAlgorithms} }
DEFAULT mgf1SHA1Identifier,
pSourceFunc [2] AlgorithmIdentifier {
{pkcs1PGenAlgorithms} }
DEFAULT pSpecifiedEmptyIdentifier
}
-- Algorithm Identifier for SHA1, which is the OAEP default.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 123]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
--
sha1Identifier ::= AlgorithmIdentifier {
id-sha1, NULL }
-- Default AlgorithmIdentifier for id-RSAES-OAEP.maskGenFunc.
--
mgf1SHA1Identifier ::= AlgorithmIdentifier {
id-mgf1, sha1Identifier }
-- This identifier means that P is an empty string, so the digest
-- of the empty string appears in the RSA block before masking.
--
pSpecifiedEmptyIdentifier ::= AlgorithmIdentifier {
id-pSpecified, OCTET STRING SIZE (0)
}
2.63.4 Format of info supplied to B_GetAlgorithmInfo:
Pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.63.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal.
B_EncryptFinal requires a valid random number generator as a
B_ALGORITHM_OBJ in its randomAlgorithm argument. PKCS #1 v2.0 does
not specify the random number generation method. It is recommended
that AI_X962Random_V0 or AI_SHA1Random be initialized with enough
seed bytes to produce 160 bits of entropy.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for the randomAlgorithm
argument in B_EncryptUpdate.
2.63.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT.
AM_SHA is required for the default pSource digest function and also
for the default MGF underlying digest method.
2.63.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic and KI_RSAPublicBER may be used to perform RSA
encryption or decryption.
2.63.8 Compatible representation:
AI_PKCS_OAEP_RSAPublic.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 124]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.63.9 Input constraints:
The key's modulus must be at least [(2 * hLen) + 2] bytes longer than
the message.
2.63.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.64 AI_PKCS_OAEPRecode
2.64.1 Purpose:
[Hardware Algorithm] This AI allows you to perform raw or
hardware-based encoding or decoding using the PKCS #1 v2.0 OAEP
padding scheme. The OAEP padding scheme prevents a theoretical attack
on interactive key-establishment protocols that use PKCS #1 v1.5. The
parameters of this algorithm include the hash function, mask
generator function and P source function that are explained below.
Encrypting with the AI_PKCS_OAEP_RSAPublic algorithm is equivalent to
first encoding the data with AI_PKCS_OAEPRecode using the B_Encode
routines and then encrypting with AI_RSAPublic using the B_Encrypt
routines. See AI_PKCS_OAEPRecodeBER for the same algorithm type with
BER encoding.
2.64.2 Type of information this allows you to use:
[Hardware Algorithm] OAEP message padding as defined in PKCS #1 v2.0
(DRAFT 1- July 14, 1998). When encoding, this algorithm encodes the
data according to the definition of EME-OAEP-Encode as specified in
PKCS #1 v2.0. When decoding, this algorithm decodes the data
according to the definition of EME-OAEP-Decode.
This permits the use of raw or hardware-based RSA with the PKCS #1
v2.0 flavor of Optimal Asymmetric Encryption Padding.
2.64.3 Format of info supplied to B_SetAlgorithmInfo:
Either:
NULL_PTR.
The following parameters are employed when NULL_PTR is specified:
PKCS OAEP RSA PARAMETER DEFAULT PARAMETER DEFAULT PARAMS
hashFunc "sha1" EMPTY ITEM
maskGenFunc "mgf1" EMPTY ITEM
maskGenFuncUnderlyingAlg "sha1" EMPTY ITEM
pSourceFunc "specifiedParameters" EMPTY ITEM
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 125]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Or:
a pointer to an A_PKCS_OAEP_PARAMS structure:
typedef struct {
/* hashFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "sha1". In both cases SHA1 will
become the digest function.
*/
unsigned char* hashFunc;
ITEM hashFuncParams;
/* maskGenFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "mgf1". In both cases MGF1 will
become the Mask Generator Function.
*/
unsigned char* maskGenFunc;
ITEM maskGenFuncParams;
/* maskGenFuncUnderlyingAlg may contain a NULL_PTR or a pointer
to the null-terminated ASCII string, "sha1". In both cases SHA1
will become the underlying algorithm.
*/
unsigned char* maskGenFuncUnderlyingAlg;
ITEM maskGenFuncUnderlyingAlgParams;
/* pSourceFunc is the method for determining the PKCS #1 v2.0 OAEP
parameter, P. pSourceFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "specifiedParameters". In both cases
"specifiedParameters" will become the pSource method.
If pSourceFunc is "specifiedParameters" and if pSourceParams.len = 0,
then P is assumed to be empty. pSourceParams may also be initialized
to the caller's data as in this example:
pSourceParams.len = sizeof(dataObject);
pSourceParams.data = &dataObject;
*/
unsigned char* pSourceFunc;
ITEM pSourceParams;
} A_PKCS_OAEP_PARAMS;
The parameters hashFuncParams, maskGenFuncParams, and
maskGenFuncUnderlyingAlgParams are available to provide for future
growth. The caller should initialize these parameters as ITEM types
as follows:
hashFuncParams.len = 0;
hashFuncParams.data = NULL_PTR
maskGenFuncParams.len = 0;
maskGenFuncParams.data = NULL_PTR
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 126]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
maskGenFuncUnderlyingAlgParams.len = 0;
maskGenFuncUnderlyingAlgParams.data = NULL_PTR
Failure to properly implement these parameters may cause bugs when
they are implemented in future versions of BSAFE.
The default parameters for pSourceParams should be set by the caller
as follows:
pSourceParams.len = 0;
pSourceParams.data = NULL_PTR;
2.64.4 Format of info supplied to B_GetAlgorithmInfo:
NULL_PTR.
2.64.5 BSAFE procedures to use with algorithm object:
B_EncodeInit, B_EncodeUpdate, B_EncodeFinal, or B_DecodeInit,
B_DecodeUpdate, and B_DecodeFinal.
The final call to B_EncodeUpdate does not contain message data.
Rather, the trailing call to B_EncodeUpdate is included to pass in a
number of random seed bytes for the OAEP encoding process. It is
recommended that the caller use AI_X962Random_V0 or AI_SHA1Random to
generate hLen bytes initialized with 160 bits of entropy. The default
digest algorithm for PKCS #1 v2.0 OAEP is SHA1. SHA1 produces a
digest of 20 bytes, so hLen for SHA1 is 20 bytes.
B_Decode_Update does not contain an extra call for seed bytes.
2.64.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA is required for the default pSource digest function and also
for the default MGF underlying digest method.
2.64.7 Compatible representation:
AI_PKCS_OAEPRecodeBER.
2.64.8 Input constraints:
The total number of bytes to encode must be at least [(2 * hLen) + 1]
bytes long.
2.64.9 Output considerations:
The output of encoding will be an encoded message that is the same
size as maxPartOutLen. (See B_EncodeUpdate, B_EncodeFinal,
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 127]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_DecodeUpdate, and B_DecodeFinal.) The output of the decoding will
be the original message.
2.65 AI_PKCS_OAEPRecodeBER
2.65.1 Purpose:
This AI represents the same algorithm type as AI_PKCS_OAEPRecode
except that it uses the ASN.1 BER format. It allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier that includes the hash
function, mask generator function and P source function. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_OAEPRecode or AI_PKCS_OAEPRecodeBER. The OID for the RSA OAEP
encryption, excluding the tag and length bytes, in decimal, is "42,
134, 72, 134, 247, 13, 1, 1, 7". The OID for the mask function,
excluding the tag and length bytes, in decimal, is "42, 134, 72, 134,
247, 13, 1, 1, 8". The OID for the P source function, excluding the
tag and length bytes, in decimal, is "42, 134, 72, 134, 247, 13, 1,
1, 9". Also see AI_PKCS_OAEPRecode.
2.65.2 Type of information this allows you to use:
[Hardware Algorithm] OAEP message padding as defined in PKCS #1 v2.0
(DRAFT 1- July 14, 1998). When encoding, this algorithm encodes the
data according to the definition of EME-OAEP-Encode as specified in
PKCS #1 v2.0. When decoding, this algorithm decodes the data
according to the definition of EME-OAEP-Decode.
This permits the use of raw or hardware-based RSA with the PKCS #1
v2.0 flavor of Optimal Asymmetric Encryption Padding.
2.65.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an item structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RSAES-OAEP Encryption as specified by PKCS #1
v2.0.
The general ASN.1 syntax for RSAES-OAEP is complicated, the simple
DER encoding of the default algorithm is given first, followed by the
general syntax.
-- Default Algorithm Identifier for RSAES-OAEP.
-- The DER Encoding of this is in hexadecimal given below.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 128]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
-- Notice that the DER encoding of the default parameters
-- is just an empty sequence.
-- 30 0D
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 07
-- 30 00
--
RSAES-OAEP-Default-Identifier ::= AlgorithmIdentifier {
id-RSAES-OAEP,
{ sha1Identifier,
mgf1SHA1Identifier,
pSpecifiedEmptyIdentifier
}
}
The general syntax is:
RSAES-OAEP ::= Sequence {
algorithm OBJECT IDENTIFIER (id-RSAES-OAEP),
parameters RSAES-OAEP-params
}
-- Identifier for PKCS #1 v2.0 OAEP.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 07
--
id-RSAES-OAEP OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) RSAES-OAEP(7)}
-- Identifier for the PKCS #1 v2.0 mask generation function,
-- which takes a hash function AlgID as a parameter.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 08
--
id-mgf1 OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) mgf1(8)}
-- The identifier says that the algorithm by which the P
-- string for RSAES-OAEP is generated is by setting it
-- equal to the contents of the OCTET STRING which is
-- the parameter for this AlgorithmIdentifier.
-- The DER for this in hexadecimal is:
-- 06 09
-- 2A 86 48 86 F7 0D 01 01 09
--
id-pSpecified OBJECT IDENTIFIER ::= {
iso(1) member-body(2) us(840) rsadsi(113549)
pkcs(1) pkcs-1(1) pSpecified(9)}
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 129]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
-- Identifier for the SHA1 digest function.
-- The DER for this in hexadecimal is:
-- 06 05
-- 2B 0E 03 02 1A
--
id-sha1 OBJECT IDENTIFIER ::= {
iso(1) identified-organization(3) oiw(14) secsig(3)
algorithms(2) sha1(26) }
-- Syntax of AlgorithmIdentifier.parameters for RSAES-OAEP.
-- Note that the tags in this Sequence are explicit.
-- The DER encoding of DEFAULT values is to omit them.
--
RSAES-OAEP-params ::= SEQUENCE {
hashFunc [0] AlgorithmIdentifier {
{oaepDigestAlgorithms} }
DEFAULT sha1Identifier,
maskGenFunc [1] AlgorithmIdentifier {
{pkcs1MGFAlgorithms} }
DEFAULT mgf1SHA1Identifier,
pSourceFunc [2] AlgorithmIdentifier {
{pkcs1PGenAlgorithms} }
DEFAULT pSpecifiedEmptyIdentifier
}
-- Algorithm Identifier for SHA1, which is the OAEP default.
--
sha1Identifier ::= AlgorithmIdentifier {
id-sha1, NULL }
-- Default AlgorithmIdentifier for id-RSAES-OAEP.maskGenFunc.
--
mgf1SHA1Identifier ::= AlgorithmIdentifier {
id-mgf1, sha1Identifier }
-- This identifier means that P is an empty string, so the digest
-- of the empty string appears in the RSA block before masking.
--
pSpecifiedEmptyIdentifier ::= AlgorithmIdentifier {
id-pSpecified, OCTET STRING SIZE (0)
}
2.65.4 Format of info supplied to B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.65.5 BSAFE procedures to use with algorithm object:
B_EncodeInit, B_EncodeUpdate, B_EncodeFinal, or B_DecodeInit,
B_DecodeUpdate, and B_DecodeFinal.
The final call to B_EncodeUpdate does not contain message data.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 130]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Rather, the trailing call to B_EncodeUpdate is included to pass in a
number of random seed bytes for the OAEP encoding process. It is
recommended that the caller use AI_X962Random_V0 or AI_SHA1Random to
generate hLen bytes initialized with 160 bits of entropy. The default
digest algorithm for PKCS #1 v2.0 OAEP is SHA1. SHA1 produces a
digest of 20 bytes, so hLen for SHA1 is 20 bytes.
B_Decode_Update does not contain an extra call for seed bytes.
2.65.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA is required for the default pSource digest function and also
for the default MGF underlying digest method.
2.65.7 Compatible representation:
AI_PKCS_OAEPRecodeBER.
2.65.8 Input constraints:
The total number of bytes to encode must be at least [(2 * hLen) + 1]
bytes long.
2.65.9 Output considerations:
The output of encoding will be an encoded message that is the same
size as maxPartOutLen. (See B_EncodeUpdate, B_EncodeFinal,
B_DecodeUpdate, and B_DecodeFinal.) The output of the decoding will
be the original message.
2.66 AI_PKCS_RSAPrivate
2.66.1 Purpose:
This AI allows you to decrypt data encrypted using RSA public-key
cryptosystem as defined in PKCS #1.
2.66.2 Type of information this allows you to use:
the RSA algorithm for performing private key decryption as defined in
PKCS #1. When encrypting, this algorithm encodes the data according
to block type 01. When decrypting, this algorithm decodes the data
from a block type 02.
2.66.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 131]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.66.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.66.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.66.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for encrypting, or
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_ENCRYPT_BLIND and AM_RSA_CRT_DECRYPT_BLIND will perform
blinding to protect against timing attacks and AM_RSA_CRT_ENCRYPT and
AM_RSA_CRT_DECRYPT will not.
2.66.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.66.8 Compatible representation:
AI_PKCS_RSAPrivateBER, AI_PKCS_RSAPrivatePEM.
2.66.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the key's modulus size in bytes.
2.66.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.67 AI_PKCS_RSAPrivateBER
2.67.1 Purpose:
This AI represents the same algorithm type as AI_PKCS_RSAPrivate
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 132]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_RSAPrivate, AI_PKCS_RSAPrivateBER or AI_PKCS_RSAPrivatePEM.
The OID for this algorithm, excluding the tag and length bytes, in
decimal is "42, 134, 72, 134, 247, 13, 1, 1, 1"
2.67.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RSA
algorithm for performing private key decryption as defined in PKCS
#1. When encrypting, this algorithm encodes the data according to
block type 01. When decrypting, this algorithm decodes the data from
a block type 02.
2.67.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RSA Encryption.
2.67.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.67.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.67.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for encrypting, or
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 133]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AM_RSA_CRT_ENCRYPT_BLIND and AM_RSA_CRT_DECRYPT_BLIND will perform
blinding to protect against timing attacks and AM_RSA_CRT_ENCRYPT and
AM_RSA_CRT_DECRYPT will not.
2.67.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.67.8 Compatible representation:
AI_PKCS_RSAPrivate, AI_PKCS_RSAPrivatePEM.
2.67.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the key's modulus size in bytes.
2.67.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.68 AI_PKCS_RSAPrivatePEM
2.68.1 Purpose:
This AI represents the same algorithm type as AI_PKCS_RSAPrivate
except that it uses the PEM format. This AI allows you to parse and
create PEM algorithm identifiers such as used in Privacy Enhanced
Mail protocol. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_RSAPrivate, AI_PKCS_RSAPrivateBER or AI_PKCS_RSAPrivatePEM.
2.68.2 Type of information this allows you to use:
an RFC 1423 identifier that specifies the RSA algorithm for
performing private key decryption as defined in PKCS #1. When
encrypting, this algorithm encodes the data according to block type
01. When decrypting, this algorithm decodes the data from a block
type 02.
This algorithm info type is intended to process the asymmetric
encryption identifier in a MIC-Info and Key-Info field in a PEM
encapsulated header.
2.68.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the RSA
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 134]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
identifier, for example, "RSA". Space and tab characters are removed
from the string before it is copied to the algorithm object.
B_SetAlgorithmInfo returns BE_WRONG_ALGORITHM_INFO if the algorithm
identifier specifies an identifier other than RSA.
2.68.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the RSA identifier.
2.68.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.68.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for encrypting, or
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_ENCRYPT_BLIND and AM_RSA_CRT_DECRYPT_BLIND will perform
blinding to protect against timing attacks and AM_RSA_CRT_ENCRYPT and
AM_RSA_CRT_DECRYPT will not.
2.68.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.68.8 Compatible representation:
AI_PKCS_RSAPrivate, AI_PKCS_RSAPrivateBER.
2.68.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the keys modulus size in bytes.
2.68.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 135]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.69 AI_PKCS_RSAPublic
2.69.1 Purpose:
This AI allows you to encrypt data using RSA public-key cryptosystem
as defined in PKCS #1.
2.69.2 Type of information this allows you to use:
the RSA algorithm for performing public key encryption as defined in
PKCS #1. When encrypting, this algorithm encodes the data according
to block type 02. When decrypting, this algorithm decodes the data
from a block type 01.
2.69.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.69.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.69.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.69.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT for encrypting or AM_RSA_DECRYPT for decrypting.
2.69.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic, KI_RSAPublicBER.
2.69.8 Compatible representation:
AI_PKCS_RSAPublicBER, AI_PKCS_RSAPublicPEM.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 136]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.69.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the key's modulus size in bytes.
2.69.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.70 AI_PKCS_RSAPublicBER
2.70.1 Purpose:
This AI represents the same algorithm type as AI_PKCS_RSAPublic
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_RSAPublic, AI_PKCS_RSAPublicBER or AI_PKCS_RSAPublicPEM. The
OID for this algorithm, excluding the tag and length bytes, in
decimal is "42, 134, 72, 134, 247, 13, 1, 1, 1".
2.70.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RSA
algorithm for performing public key encryption as defined in PKCS #1.
When encrypting, this algorithm encodes the data according to block
type 02. When decrypting, this algorithm decodes the data from a
block type 01.
2.70.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RSA Encryption.
2.70.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.70.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 137]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.70.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT for encrypting or AM_RSA_DECRYPT for decrypting.
2.70.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic, KI_RSAPublicBER.
2.70.8 Compatible representation:
AI_PKCS_RSAPublic, AI_PKCS_RSAPublicPEM.
2.70.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the key's modulus size in bytes.
2.70.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.71 AI_PKCS_RSAPublicPEM
2.71.1 Purpose:
This AI represents the same algorithm type as AI_PKCS_RSAPublic
except that it uses the PEM format. This AI allows you to parse and
create PEM algorithm identifiers such as used in Privacy Enhanced
Mail protocol. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using
AI_PKCS_RSAPublic, AI_PKCS_RSAPublicBER, or AI_PKCS_RSAPublicPEM.
2.71.2 Type of information this allows you to use:
an RFC 1423 identifier that specifies the RSA algorithm for
performing public key encryption as defined in PKCS #1. When
encrypting, this algorithm encodes the data according to block type
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 138]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
02. When decrypting, this algorithm decodes the data from a block
type 01.
This algorithm info type is intended to process the asymmetric
encryption identifier in a MIC-Info and Key-Info field in a PEM
encapsulated header.
2.71.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the RSA
identifier. For example, "RSA". Space and tab characters are removed
from the string before it is copied to the algorithm object.
B_SetAlgorithmInfo returns BE_WRONG_ALGORITHM_INFO if the algorithm
identifier specifies an identifier other than RSA.
2.71.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the RSA identifier.
2.71.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit and then call
B_EncryptUpdate zero or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit and then call
B_DecryptUpdate supplying it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.71.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT for encrypting or AM_RSA_DECRYPT for decrypting.
2.71.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic, KI_RSAPublicBER.
2.71.8 Compatible representation:
AI_PKCS_RSAPublic, AI_PKCS_RSAPublicBER.
2.71.9 Input constraints:
The total number of bytes to encrypt may not be more than k - 11,
where k is the key's modulus size in bytes.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 139]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.71.10 Output considerations:
The output of encryption will be the same size as the key's modulus.
2.72 AI_RC2_CBC
2.72.1 Purpose:
This AI allows you to perform RC2 encryption or decryption in CBC
mode with an 8-byte initialization vector. Since AI_RC2_CBC does not
pad, the total number of input bytes must be a multiple of eight. See
AI_RC2_CBCPad for the same algorithm with padding. RC2 is a
variable-key-size block cipher which means that the key can be
anywhere between 1 and 128 bytes. The larger the key, the greater the
security. RC2 is described in RFC 2268, and CBC mode is similar to
the one described in RFC 2040.
Other algorithms that can be used for encryption/decryption in CBC
mode without padding are AI_DES_CBC_IV8, AI_DES_EDE3_CBC_IV8,
AI_DESX_CBC_IV8, and AI_RC5_CBC.
2.72.2 Type of information this allows you to use:
an effective key size and an 8-byte initialization vector for the
RC2-CBC encryption algorithm.
2.72.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RC2_CBC_PARAMS structure:
typedef struct {
unsigned int effectiveKeyBits; /* effective key size in bits */
unsigned char *iv; /* initialization vector */
} A_RC2_CBC_PARAMS;
2.72.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_RC2_CBC_PARAMS structure (see above).
2.72.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.72.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC2_CBC_ENCRYPT for encrypting and AM_RC2_CBC_DECRYPT for
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 140]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
decrypting.
2.72.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_8Byte, KI_Item.
2.72.8 Input constraints:
Since this algorithm does not pad, the total number of input bytes
must be a multiple of eight.
2.72.9 Token-based algorithm methods:
[Hardware Algorithm] AI_RC2_CBC may be used to access the
hardware-related algorithm methods AM_TOKEN_RC2_CBC_ENCRYPT and
AM_TOKEN_RC2_CBC_DECRYPT, for use with BHAPI.
2.73 AI_RC2_CBCPad
2.73.1 Purpose:
This AI allows you to perform RC2 encryption or decryption in CBC
mode with an 8-byte initialization vector. This algorithms pads as
described in PKCS #5, so the input data does not have to be a
multiple of eight. RC2 is a variable-key-size block cipher which
means that the key can be anywhere between 1 and 128 bytes. The
larger the key, the greater the security. RC2 is described in RFC
2268, and CBC mode is similar to the one described in RFC 2040.
Other algorithms that can be used for encryption/decryption in CBC
mode with padding are AI_DES_CBCPadIV8, AI_DES_EDE3_CBCPadIV8,
AI_DESX_CBCPadIV8, and AI_RC5_CBCPad.
2.73.2 Type of information this allows you to use:
an 8-byte initialization vector and effective key size for the
RC2-CBC With Padding encryption algorithm.
2.73.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RC2_CBC_PARAMS structure:
typedef struct {
unsigned int effectiveKeyBits; /* effective key size in bits */
unsigned char *iv; /* initialization vector */
} A_RC2_CBC_PARAMS;
2.73.4 Format of info returned by B_GetAlgorithmInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 141]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an A_RC2_CBC_PARAMS structure (see above).
2.73.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.73.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC2_CBC_ENCRYPT for encrypting and AM_RC2_CBC_DECRYPT for
decrypting.
2.73.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_8Byte, KI_Item.
2.73.8 Compatible representation:
AI_RC2_CBCPadBER, AI_RC2_CBCPadPEM.
2.73.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.74 AI_RC2_CBCPadBER
2.74.1 Purpose:
This AI represents the same algorithm type as AI_RC2_CBCPad except
that it uses the ASN.1 BER format. This AI allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier which includes ASN.1
encoding of the A_RC2_CBC_PARAMS structure defined in the description
of AI_RC2_CBCPad. You call B_GetAlgorithmInfo with this AI to create
an encoded algorithm identifier from an algorithm object that was
created using AI_RC2_CBCPad, AI_RC2_CBCPadBER or AI_RC2_CBCPadPEM.
The OID for this algorithm, excluding the tag and length bytes, in
decimal is "42, 134, 72, 134, 247, 13, 3, 2".
2.74.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RC2-CBC
With Padding encryption algorithm.
2.74.3 Format of info supplied to B_SetAlgorithmInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 142]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RC2-CBC With Padding.
2.74.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.74.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.74.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC2_CBC_ENCRYPT for encrypting and AM_RC2_CBC_DECRYPT for
decrypting.
2.74.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_8Byte, KI_Item.
2.74.8 Compatible representation:
AI_RC2_CBCPad, AI_RC2_CBCPadPEM.
2.74.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.75 AI_RC2_CBCPadPEM
2.75.1 Purpose:
This AI represents the same algorithm type as AI_RC2_CBCPad except
that it uses the PEM format. This AI allows you to parse and create
PEM algorithm identifiers such as used in Privacy Enhanced Mail
protocol. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier which includes PEM
encoding of the A_RC2_CBC_PARAMS structure defined in the description
of AI_RC2_CBCPad. You call B_GetAlgorithmInfo with this AI to create
an encoded algorithm identifier from an algorithm object that was
created using AI_RC2_CBCPad, AI_RC2_CBCPadBER, or AI_RC2_CBCPadPEM.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 143]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.75.2 Type of information this allows you to use:
an RFC 1423-style identifier that specifies the RC2-CBC With Padding
encryption algorithm. This algorithm info type is intended to process
the value of a DEK-Info field in a PEM encapsulated header.
2.75.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a null-terminated string (char *) that gives the RC2-CBC
identifier and parameters. For example, "RC2-CBC,BAgRIjNEVWZ3iA==".
Space and tab characters are removed from the string before it is
copied to the algorithm object. B_SetAlgorithmInfo returns
BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies an
identifier other than RC2-CBC.
2.75.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a null-terminated string that gives the RC2-CBC identifier
and parameters.
2.75.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.75.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC2_CBC_ENCRYPT for encrypting and AM_RC2_CBC_DECRYPT for
decrypting.
2.75.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_8Byte, KI_Item.
2.75.8 Compatible representation:
AI_RC2_CBCPad, AI_RC2_CBCPadBER.
2.75.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.76 AI_RC4
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 144]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.76.1 Purpose:
This AI allows you to perform RC4 encryption and decryption. RC4 is a
stream cipher and its description can be found in B. Schneier's book
"Applied Cryptography". Because it is a stream cipher, there are no
restrictions on the length of input data. A similar algorithm that
allows you to authenticate the encrypted data is AI_RC4WithMAC.
2.76.2 Type of information this allows you to use:
the RC4 encryption algorithm.
2.76.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.76.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.76.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
Due to the nature of the RC4 algorithm, security is compromised if
multiple data blocks are encrypted with the same RC4 key. Therefore,
B_EncryptUpdate cannot be called after B_EncryptFinal. To begin an
encryption operation for a new data block, you must call
B_EncryptInit and supply a new key.
2.76.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC4_ENCRYPT for encrypting or AM_RC4_DECRYPT for decrypting.
2.76.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the address and length of the RC4 key.
2.76.8 Compatible representation:
AI_RC4_BER.
2.76.9 Token-based algorithm methods:
[Hardware Algorithm] AI_RC4 may be used to access the
hardware-related algorithm methods AM_TOKEN_RC4_ENCRYPT and
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 145]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AM_TOKEN_RC4_DECRYPT, for use with BHAPI.
2.77 AI_RC4_BER
2.77.1 Purpose:
This AI represents the same algorithm type as AI_RC4 except that it
uses the ASN.1 BER format. This AI allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using AI_RC4 or
AI_RC4_BER. The OID for this algorithm, excluding the tag and length
bytes, in decimal is "42, 134, 72, 134, 247, 13, 3, 4".
2.77.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RC4
encryption algorithm.
2.77.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RC4.
2.77.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.77.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
Due to the nature of the RC4 algorithm, security is compromised if
multiple data blocks are encrypted with the same RC4 key. Therefore,
B_EncryptUpdate cannot be called after B_EncryptFinal. To begin an
encryption operation for a new data block, you must call
B_EncryptInit and supply a new key.
2.77.6 Algorithm methods to include in application's algorithm
chooser:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 146]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AM_RC4_ENCRYPT for encrypting or AM_RC4_DECRYPT for decrypting.
2.77.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the address and length of the RC4 key.
2.77.8 Compatible representation:
AI_RC4.
2.78 AI_RC4WithMAC
2.78.1 Purpose:
This algorithm implements a stream cipher with a simple
tamper-detection message authentication code based on AI_MAC. When
applied to a plaintext buffer of N bytes, it produces a ciphertext of
N bytes using the same algorithm as AI_RC4, and then it appends a MAC
of macLen bytes. You can find the description of AI_RC4 in B.
Schneier's "Applied Cryptography", and the detailed description of
AI_MAC can be found in Appendix B.
2.78.2 Type of information this allows you to use:
the RC4 With MAC encryption algorithm. The MAC is computed using
AI_MAC by first passing the key to AI_MAC, then the plaintext, and
finally a block of macLen zero bytes. The resulting value from AI_MAC
is appended to the ciphertext. For decryption, the MAC value is
checked.
The key passed to both AI_RC4 and AI_MAC is created by appending the
salt bytes to the end of the key passed to B_EncryptInit or
B_DecryptInit. That is, for this AI, the RC4 key depends on the salt
as well as the key object passed to Init routine.
2.78.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_RC4_WITH_MAC_PARAMS structure:
typedef struct {
ITEM salt; /* variable-length salt */
unsigned int macLen; /* length to use for MAC value */
} B_RC4_WITH_MAC_PARAMS;
The salt ITEM supplies the salt value that is appended to the key,
where the ITEM's data points to an unsigned byte array and the ITEM's
len gives its length. If the length is zero, no salt is appended to
the key, and the ITEM's data is ignored. macLen has a minimum of 2
and maximum of 16.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 147]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.78.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_RC4_WITH_MAC_PARAMS structure (see above).
2.78.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. B_DecryptFinal returns
BE_INPUT_DATA if the MAC does not match. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
Due to the nature of the RC4 algorithm, security is compromised if
multiple data blocks are encrypted with the same RC4 key. Therefore,
B_EncryptUpdate cannot be called after B_EncryptFinal. To begin an
encryption operation for a new data block, you must call
B_EncryptInit and supply a new key.
2.78.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC4_WITH_MAC_ENCRYPT for encrypting, or AM_RC4_WITH_MAC_DECRYPT
for decrypting.
2.78.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the address and length of the RC4 key.
2.78.8 Compatible representation:
AI_RC4WithMAC_BER.
2.78.9 Output considerations:
The total number of output bytes from encryption will be macLen bytes
more than the input.
2.78.10 Token-based algorithm methods:
[Hardware Algorithm] AI_RC4WithMAC may be used to access the
hardware-related algorithm methods AM_TOKEN_RC4_ENCRYPT and
AM_TOKEN_RC4_DECRYPT, for use with BHAPI.
2.79 AI_RC4WithMAC_BER
2.79.1 Purpose:
This AI represents the same algorithm type as AI_RC4WithMAC except
that it uses the ASN.1 BER format. This AI allows you to parse and
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 148]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier which includes ASN.1
encoding of the B_RC4_WITH_MAC_PARAMS structure defined in the
description of AI_RC4WithMAC. You call B_GetAlgorithmInfo with this
AI to create an encoded algorithm identifier from an algorithm object
that was created using AI_RC4WithMAC or AI_RC4WithMAC_BER. The OID
for this algorithm, excluding the tag and length bytes, in decimal is
"42, 134, 72, 134, 247, 13, 3, 5".
2.79.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RC4 With
MAC encryption algorithm.
2.79.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RC4.
2.79.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.79.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. B_DecryptFinal returns
BE_INPUT_DATA if the MAC does not match. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
Due to the nature of the RC4 algorithm, security is compromised if
multiple data blocks are encrypted with the same RC4 key. Therefore,
B_EncryptUpdate cannot be called after B_EncryptFinal. To begin an
encryption operation for a new data block, you must call
B_EncryptInit and supply a new key.
2.79 6 Algorithm methods to include in application's algorithm
chooser:
AM_RC4_WITH_MAC_ENCRYPT for encrypting or AM_RC4_WITH_MAC_DECRYPT for
decrypting.
2.79.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 149]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
KI_Item that gives the address and length of the RC4 key.
2.79.8 Compatible representation:
AI_RC4WithMAC.
2.79.9 Output considerations:
The total number of output bytes from encryption will be macLen bytes
more than the input.
2.80 AI_RC5_CBC
2.80.1 Purpose:
This AI allows you to perform RC5 encryption and decryption in CBC
mode with an 8-byte initialization vector, and a variable number of
rounds, as defined in RFC 2040. Since AI_RC5_CBC does not pad, the
total number of input bytes must be a multiple of eight. See
AI_RC5_CBCPad for the same algorithm with padding.
Other algorithms that can be used for encryption/decryption in CBC
mode without padding are AI_DES_CBC_IV8, AI_DES_EDE3_CBC_IV8,
AI_DESX_CBC_IV8, and AI_RC2_CBC.
2.80.2 Type of information this allows you to use:
a version number, a rounds count, a word size, and an 8-byte
initialization vector for the RC5 32/r/b CBC encryption algorithm.
Note that to implement RC5 with a word size other than 32 bits, you
should use AI_FeedbackCipher.
2.80.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RC5_CBC_PARAMS structure:
typedef struct {
unsigned int version; /* currently 1.0 defined 0x10 */
unsigned int rounds; /* number of rounds (0 - 255) */
unsigned int wordSizeInBits; /* AI_RC5_CBC requires 32 */
unsigned char *iv; /* initialization vector (8 bytes) */
} A_RC5_CBC_PARAMS;
2.80.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_RC5_CBC_PARAMS structure (see above).
2.80.5 BSAFE procedures to use with algorithm object:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 150]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.80.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC5_CBC_ENCRYPT for encrypting and AM_RC5_CBC_DECRYPT for
decrypting.
2.80.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item, that gives the address and length of the RC5 key.
2.80.8 Input Constraints:
Since this algorithm does not pad, the total number of input bytes
must be a multiple of eight.
2.80.9 Token-based algorithm methods:
[Hardware Algorithm] AI_RC5_CBC may be used to access the
hardware-related (BHAPI) algorithm methods AM_TOKEN_RC5_CBC_ENCRYPT
and AM_TOKEN_RC5_CBC_DECRYPT.
2.81 AI_RC5_CBCPad
2.81.1 Purpose:
This AI allows you to perform RC5 encryption or decryption in CBC
mode with an 8-byte initialization vector, and a variable number of
rounds, as defined in RFC 2040. This algorithms pads, so the input
data does not have to be a multiple of eight.
Other algorithms that can be used for encryption/decryption in CBC
mode with padding are AI_DES_CBCPadIV8, AI_DES_EDE3_CBCPadIV8,
AI_DESX_CBCPadIV8, and AI_RC2_CBCPad.
2.81.2 Type of information this allows you to use:
a version number, a rounds count, a word size and an 8-byte
initialization vector for the RC5 32/r/b CBC encryption algorithm.
Table 0 To implement RC5 with a word size other than 32 bits, use
AI_FeedbackCipher.
2.81.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RC5_CBC_PARAMS structure:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 151]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef struct {
unsigned int version; /* currently 1.0 defined 0x10 */
unsigned int rounds; /* number of rounds (0 - 255) */
unsigned int wordSizeInBits; /* AI_RC5_CBCPad requires 32 */
unsigned char *iv; /* initialization vector (8 bytes) */
} A_RC5_CBC_PARAMS;
2.81.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_RC5_CBC_PARAMS structure (see above).
2.81.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.81.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC5_CBC_ENCRYPT for encrypting and AM_RC5_CBC_DECRYPT for
decrypting.
2.81.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item, that gives the address and length of the RC5 key.
2.81.8 Compatible representation:
AI_RC5_CBCPadBER.
2.81.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.82 AI_RC5_CBCPadBER
2.82.1 Purpose:
This AI represents the same algorithm type as AI_RC5_CBCPad except
that it uses the ASN.1 BER format. This AI allows you to parse and
create ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier which includes ASN.1
encoding of the A_RC5_CBC_PARAMS structure defined in the description
of AI_RC5_CBCPad. You call B_GetAlgorithmInfo with this AI to create
an encoded algorithm identifier from an algorithm object that was
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 152]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
created using AI_RC5_CBCPad, AI_RC5_CBCPadBER or AI_RC5_CBCPadPEM.
The OID for this algorithm, excluding the tag and length bytes, in
decimal is "42, 134, 72, 134, 247, 13, 3, 9".
2.82.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the RC5 32/r/b
CBC encryption algorithm.
2.82.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than RC5-CBC With Padding.
2.82.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.82.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.82.6 Algorithm methods to include in application's algorithm
chooser:
AM_RC5_CBC_ENCRYPT for encrypting and AM_RC5_CBC_DECRYPT for
decrypting.
2.82.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item, that gives the address and length of the RC5 key.
2.82.8 Compatible representation:
AI_RC5_CBCPad.
2.82.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.83 AI_RESET_IV
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 153]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.83.1 Purpose:
This AI allows you to change the initialization vector (IV) for a
cipher object created with AI_FeedbackCipher without needing to
create a new algorithm object or bind in a new key. This increases
the performance of applications that have a long-lived symmetric key
(e.g., DES key) that is used to encrypt many blocks or messages that
each has a unique IV.
A similar AI that can be used to change IV of a CBC mode cipher is
AI_CBC_IV8.
2.83.2 Type of Information this allows you to use:
a new initialization vector to reset an encryption/decryption object
defined with AI_FeedbackCipher.
2.83.3 Format of info supplied to B_SetAlgorithmInfo
a pointer to an ITEM of length equal to the old initialization
vector.
2.83.4 Format of info returned by B_GetAlgorithmInfo returns
a pointer to an ITEM.
2.83.5 BSAFE procedures to use with algorithm object:
To change the IV for an encryption or decryption algorithm, call
B_SetAlgorithmInfo using this AI and a pointer to the new IV value.
The new IV will take effect immediately if B_EncryptFinal or
B_DecryptFinal have already been called on the algorithm object.
2.83.6 Algorithm methods to include in chooser
none.
Table 0 Reinitialization may be done anytime after an
encryption/decryption has been set with its algorithm
info. It takes effect after the next initialization. It
may be used in conjunction with a new key to start a new
encryption/decryption session.
2.84 AI_RFC1113Recode
2.84.1 Purpose:
This AI allows you to convert data from binary format to ASCII, and
vice versa, as defined by RFC 1113.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 154]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.84.2 Type of information this allows you to use:
the binary to printable recoding algorithm as defined by RFC 1113;
see also RFC 1421 for updated version of the standard.
2.84.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.84.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.84.5 BSAFE procedures to use with algorithm object:
B_EncodeInit, B_EncodeUpdate, B_EncodeFinal, and B_DecodeInit,
B_DecodeUpdate, and B_DecodeFinal.
2.84.6 Output considerations:
When encoding, for each three bytes of input there are four bytes of
output. When decoding, for each four bytes of input there are three
bytes of output.
2.85 AI_RSAKeyGen
2.85.1 Purpose:
This AI allows you to specify the parameters for generating an RSA
public/private key pair as defined in PKCS #1. You may also use
AI_RSAStrongKeyGen to generate RSA key pairs.
2.85.2 Type of information this allows you to use:
the parameters for generating an RSA public/private key pair as
defined in PKCS #1, where the modulus size and public exponent are
specified.
2.85.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RSA_KEY_GEN_PARAMS structure:
typedef struct {
unsigned int modulusBits; /* size of modulus in bits */
ITEM publicExponent; /* fixed public exponent */
} A_RSA_KEY_GEN_PARAMS;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 155]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
The publicExponent ITEM supplies an integer in canonical format,
where the ITEM's data points to an unsigned byte array, most
significant byte first, and the ITEM's len gives its length. All
leading zeros are stripped from the integer before it is copied to
the algorithm object.
2.85.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_RSA_KEY_GEN_PARAMS structure (see above). All leading
zeros have been stripped from the publicExponent integer.
2.85.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateKeypair. B_GenerateKeypair sets the
publicKey key object with the KI_RSAPublic information and the
privateKey key object with the KI_PKCS_RSAPrivate information. You
must pass an initialized random algorithm to B_GenerateKeypair.
2.84.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_KEY_GEN.
2.86 AI_RSAPrivate
2.86.1 Purpose:
This AI allows you to encrypt data using the raw RSA algorithm. You
can find the description of this algorithm in B. Schneier's "Applied
Cryptography".
AI_RSAPrivate is different from AI_PKCS_RSAPrivate because the former
allows you to encrypt up raw data, while the latter encrypts data in
PKCS #1 format.
Because this algorithm does not pad, the total number of input bytes
must be a multiple of the key's modulus size in bytes. Your
application is responsible for padding the data as appropriate. Also,
each modulus-size block of input, interpreted as an integer with the
most significant byte first, must be numerically less than the key's
modulus. To do this, divide your data into blocks that are one byte
smaller than the modulus, and prepend one byte of 0 to each block.
To perform RSA encryption you can also use AI_PKCS_RSAPrivate and
AI_SET_OAEP_RSAPrivate. But you can use AI_RSAPrivate only if the
data will be decrypted with AI_RSAPublic.
2.86.2 Type of information this allows you to use:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 156]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
the RSA algorithm for performing raw private-key encryption.
2.86.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.86.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.86.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.86.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for encrypting, or
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_ENCRYPT_BLIND and AM_RSA_CRT_DECRYPT_BLIND will perform
blinding to protect against timing attacks and AM_RSA_CRT_ENCRYPT and
AM_RSA_CRT_DECRYPT will not.
2.86.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.86.8 Input constraints:
Because this algorithm does not pad, the total number of input bytes
must be a multiple of the key's modulus size in bytes. Also, each
modulus-size block of input, interpreted as an integer with the most
significant byte first, must be numerically less than the key's
modulus.
2.86.9 Token-based algorithm methods:
[Hardware Algorithm] AI_RSAPrivate may include the hardware algorithm
method AM_TOKEN_RSA_PRV_ENCRYPT in the algorithm chooser, for use
with BHAPI.
2.87 AI_RSAPublic
2.87.1 Purpose:
This AI allows you to decrypt data using the raw RSA algorithm. You
can find the description of this algorithm in B. Schneier's "Applied
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 157]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Cryptography".
AI_RSAPublic is different from AI_PKCS_RSAPublic because the latter
allows you to decrypt k-11 bytes, where k is the size of the modulus
in bytes, while you can use the former to decrypt up to k bytes. Note
that it is the application's responsibility to strip the padding that
was appended by the application to the data during encryption with
AI_RSAPrivate.
Because this algorithm does not pad, the total number of input bytes
must be a multiple of the key's modulus size in bytes. Also, each
modulus-size block of input, interpreted as an integer with the most
significant byte first, must be numerically less than the key's
modulus.
To perform RSA decryption you can also use AI_PKCS_RSAPublic and
AI_SET_OAEP_RSAPublic. But you can use AI_RSAPublic only if the data
has been encrypted with AI_RSAPrivate.
2.87.2 Type of information this allows you to use:
the RSA algorithm for performing raw public-key decryption.
2.87.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.87.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.87.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, B_EncryptFinal, and B_DecryptInit,
B_DecryptUpdate, and B_DecryptFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.86.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT for encrypting or AM_RSA_DECRYPT for decrypting.
2.87.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic, KI_RSAPublicBER.
2.87.8 Input constraints:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 158]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Because this algorithm does not pad, the total number of input bytes
must be a multiple of the key's modulus size in bytes. Also, each
modulus-size block of input, interpreted as an integer with the most
significant byte first, must be numerically less than the key's
modulus.
2.87.9 Token-based algorithm methods:
[Hardware Algorithm] AI_RSAPublic may include the hardware algorithm
methods AM_TOKEN_RSA_ENCRYPT, AM_TOKEN_RSA_DECRYPT, and
AM_TOKEN_RSA_PUB_DECRYPT in the algorithm chooser for use with BHAPI.
2.88 AI_RSAStrongKeyGen
2.88.1 Purpose:
This AI allows you to specify the parameters for generating an RSA
public/private key pair as defined in PKCS #1. The moduli generated
are in conformance with the strength criteria of the ANSI X9.31
Draft. If this conformance is not desired, you may use a faster
AI_RSAKeyGen to generate RSA key pairs.
2.88.2 Type of information this allows you to use:
the parameters for generating an RSA public/private key pair as
defined in PKCS #1, where the modulus size and public exponent are
specified. The moduli generated are in conformance with the strength
criteria of the ANSI X9.31 Draft.
2.88.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_RSA_KEY_GEN_PARAMS structure:
typedef struct {
unsigned int modulusBits; /* size of modulus in bits */
ITEM publicExponent; /* fixed public exponent */
} A_RSA_KEY_GEN_PARAMS;
The publicExponent ITEM supplies an integer in canonical format,
where the ITEM's data points to an unsigned byte array, most
significant byte first and the ITEM's len gives its length. All
leading zeros are stripped from the integer before it is copied to
the algorithm object. modulusBits must be at least 512 and must be a
multiple of 16.
2.88.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_RSA_KEY_GEN_PARAMS structure (see above). All leading
zeros have been stripped from the publicExponent integer.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 159]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.88.5 BSAFE procedures to use with algorithm object:
B_GenerateInit and B_GenerateKeypair. B_GenerateKeypair sets the
publicKey key object with the KI_RSAPublic information and the
privateKey key object with the KI_PKCS_RSAPrivate information. You
must pass an initialized random algorithm to B_GenerateKeypair.
2.88.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_STRONG_KEY_GEN.
2.89 AI_SET_OAEP_RSAPrivate
2.89.1 Purpose:
This AI allows you to decrypt data encrypted using
AI_SET_OAEP_RSAPublic. This algorithm is used by the Secure
Electronic Transaction (SET) protocol defined by Visa and MasterCard
in the SET 1.0 specification released August 1, 1996. It replaces
PKCS #1 v1.5 padding with a form of Optimal Asymmetric Encryption
Padding (OAEP) that was developed for the SET protocol. OAEP
provides protection against cryptanalytic attacks on the padding
algorithm which are possible when most of the message being
encrypted is known to the attacker. A more standard form of OAEP is
now part of version 2.0 of the PKCS #1 standard and is implemented by
AI_PKCS_OAEP_RSAPrivate and AI_PKCS_OAEP_RSAPublic.
2.89.2 Type of information this allows you to use:
the RSA algorithm for performing private key decryption following the
OAEP procedure outlined in the Aug. 1, 1996 version of the SET
specifications.
2.89.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.89.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.89.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal for encryption,
and B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal for
decryption. B_EncryptUpdate and B_EncryptFinal require a random
algorithm. You may pass (B_ALGORITHM_OBJ)NULL_PTR for the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 160]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
randomAlgorithm argument in B_DecryptUpdate and B_DecryptFinal.
2.89.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for encrypting and
AM_RSA_CRT_DECRYPT or AM_RSA_CRT_DECRYPT_BLIND for decrypting.
AM_RSA_CRT_ENCRYPT_BLIND and AM_RSA_CRT_DECRYPT_BLIND will perform
blinding to protect against timing attacks and AM_RSA_CRT_ENCRYPT and
AM_RSA_CRT_DECRYPT will not.
2.89.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.89.8 Input considerations:
The key size, in bits, must be a multiple of 8. For instance, 1024 is
a valid key size; 1030 is not.
If encrypting, the total number of bytes to encrypt must be 25 fewer
than the key size in bytes. For instance, with a 1024-bit key (128
bytes) the input must be 103 bytes (128 - 25). The SET standard calls
for the input data to follow a particular format. The first byte is
the block content (BC) and the following bytes are the actual data
bytes (ADB). This AI does not check whether those bytes adhere to the
SET specifications.
2.89.9 Output considerations:
The output of encryption will be the same size as the key's modulus.
The output of decryption will be 25 bytes fewer than the key size in
bytes.
2.90 AI_SET_OAEP_RSAPublic
2.90.1 Purpose:
This AI allows you to encrypt data which will be decrypted using
AI_SET_OAEP_RSAPrivate. This algorithm is used by Secure Electronic
Transaction (SET) protocol defined by Visa and MasterCard in the SET
1.0 specification released August 1, 1996. It replaces PKCS #1 v1.5
padding with a form of Optimal Asymmetric Encryption Padding (OAEP)
that was developed for the SET protocol. OAEP provides protection
against cryptanalytic attacks on the padding algorithm which are
possible when most of the message being encrypted is known to the
attacker. A more standard form of OAEP is now part of version 2.0 of
the PKCS #1 standard and is implemented by AI_PKCS_OAEP_RSAPrivate
and AI_PKCS_OAEP_RSAPublic.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 161]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.90.2 Type of information this allows you to use:
the RSA algorithm for performing public key encryption following the
OAEP procedure outlined in the Aug. 1, 1996 version of the SET
specifications.
2.90.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.90.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.90.5 BSAFE procedures to use with algorithm object:
B_EncryptInit, B_EncryptUpdate, and B_EncryptFinal, and
B_DecryptInit, B_DecryptUpdate, and B_DecryptFinal. B_EncryptUpdate
and B_EncryptFinal require a random algorithm. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for the randomAlgorithm argument in
B_DecryptUpdate and B_DecryptFinal.
2.90.6 Algorithm methods to include in application's algorithm
chooser:
AM_RSA_ENCRYPT for encrypting and AM_RSA_DECRYPT for decrypting.
2.90.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_RSAPublic, KI_RSAPublicBER.
2.90.8 Input considerations:
The key size in bits must be a multiple of 8; e.g., 1024 is a valid
key size; 1030 is not.
If encrypting, the total number of bytes to encrypt must be 25 fewer
than the key size in bytes. For instance, with a 1024-bit key (128
bytes) the input must be 103 bytes (128 - 25). The SET standard calls
for the input data to follow a particular format. The first byte is
the block content (BC) and the following bytes are the actual data
bytes (ADB). This AI does not check whether those bytes adhere to the
SET specifications.
2.90.9 Output considerations:
The output of encryption will be the same size as the key's modulus.
The output of decryption will be 25 bytes fewer than the key size in
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 162]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
bytes.
2.91 AI_SHA1
2.91.1 Purpose:
This AI allows you to create a message digest using the SHA1 digest
algorithm as defined in FIPS PUB 180-1. This algorithm processes
input data 64 bytes at a time but the length of the input does not
have to be a multiple of 64 as the algorithm pads automatically.
The primary use for this AI is to authenticate data. Other algorithms
that can be used for message digesting are AI_MD2 and AI_MD5 and
their variants.
2.91.2 Type of information this allows you to use:
the 20-byte SHA1 message digest algorithm as defined in FIPS PUB
180-1.
2.91.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.91.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.91.5 BSAFE procedures to use with algorithm object:
Call B_DigestInit to prepare this object for digesting data, and
supply NULL_PTR for the keyObject argument. Then call B_DigestUpdate
zero or more times supplying it with the data to digest. You might
want to call this function more than once if you have separate units
of data, such as two or more files or several strings. Finally, call
B_DigestFinal to finalize the digesting process and retrieve the
result. This call reinitializes the object, so you can start a new
digest without calling B_DigestInit first.
2.91.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA.
2.91.7 Compatible representation:
AI_SHA1_BER
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 163]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.91.8 Output considerations:
The output of B_DigestFinal will be 20 bytes long.
2.92 AI_SHA1_BER
2.92.1 Purpose:
This AI represents the same algorithm type as AI_SHA1 except that it
uses the ASN.1 BER format. This AI allows you to parse and create
ASN.1 algorithm identifiers such as used in PKCS #7 and other
protocols. You call B_SetAlgorithmInfo to initialize an algorithm
object from the encoded algorithm identifier. You call
B_GetAlgorithmInfo with this AI to create an encoded algorithm
identifier from an algorithm object that was created using AI_SHA1 or
AI_SHA1_BER. The OID for this algorithm, excluding the tag and length
bytes, in decimal is "43, 14, 3, 2, 26".
2.92.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the SHA1
message digest algorithm as defined in FIPS PUB 180-1.
2.92.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
a message digest algorithm other than SHA1.
2.92.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.92.5 BSAFE procedures to use with algorithm object:
Call B_DigestInit to prepare this object for digesting data, and
supply NULL_PTR for the keyObject argument. Then call B_DigestUpdate
zero or more times supplying it with the data to digest. You might
want to call this function more than once if you have separate units
of data, such as two or more files or several strings. Finally, call
B_DigestFinal to finalize the digesting process and retrieve the
result. This call reinitializes the object, so you can start a new
digest without calling B_DigestInit first.
2.92.6 Algorithm methods to include in application's algorithm
chooser:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 164]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AM_SHA.
2.92.7 Compatible representation:
AI_SHA1
2.92.8 Output considerations:
The output of B_DigestFinal will be 20 bytes long.
2.93 AI_SHA1Random
2.93.1 Purpose:
This AI allows you to generate a stream of pseudo-random numbers
which are guaranteed to have a very high degree of randomness. Random
numbers are used in deriving public and private keys, initialization
vectors, etc. This AI uses SHA1 as an underlying hashing function.
The details of this algorithm are available from RSA Laboratories'
Bulletin #8, or online at
http://www.rsa.com/rsalabs/html/bulletins.html.
Other algorithms that can be used to generate pseudo-random numbers
are AI_MD2Random, AI_MD5Random, and AI_X962Random_V0.
2.93.2 Notes:
In this API, AI_SHA1Random is identical to AI_X962Random_V0 (Section
2.97); however, this identification may change in future versions of
BSAFE. For forward compatibility, we recommend that you do not use
the name AI_SHA1Random in your applications; use AI_X962Random_V0
instead.
AI_X962Random_V0 provides an implementation of SHA-1 Random that is
based on the X9.62 Draft standard; this is different from the
implementation of SHA-1 Random in RSA Data Security's Java
cryptographic toolkit, JSAFE. Future versions of BSAFE may implement
AI_SHA1Random in a manner compatible with the implementation provided
via the "SHA1Random" value passed to the JSAFE_SecureRandom class in
JSAFE.
2.94 AI_SHA1WithDES_CBCPad
2.94.1 Purpose:
This AI allows you to perform password-based encryption. This means
that the input data will be encrypted with a secret key derived from
a password, and it can be successfully decrypted only when the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 165]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
correct password is provided. Although this AI can be used to encrypt
arbitrary data, its intended primary use is for encrypting private
keys when transferring them from one computer system to another, as
described in PKCS #8.
This AI employs DES secret-key encryption in cipher-block chaining
(CBC) mode with padding, where the secret key is derived from a
password using the SHA1 message digest algorithm. The details of this
algorithm are contained in PKCS #5. DES is defined in FIPS PUB 81,
and CBC mode of DES is defined in FIPS PUB 46-1. FIPS PUB 180-1
describes SHA1.
Other algorithms that can be used for password-based encryption are
AI_MD2WithDES_CBCPad, AI_MD2WithRC2_CBCPad, AI_MD5WithRC2_CBCPad, and
AI_MD5WithDES_CBCPad.
2.94.2 Type of information this allows you to use:
the salt and iteration count for the SHA1 With DES-CBC password-based
encryption algorithm. The salt is concatenated with the password
before being digested by SHA1, and the iteration count specifies how
many times the digest needs to be run. The count of 2 indicates that
the result of digesting password-and-salt string needs to be run once
more through SHA1. The first 8 bytes of the final digest become the
secret key for the DES cipher after being adjusted for parity as
required by FIPS PUB 81, the next 8 bytes become the initialization
vector, and the last 4 bytes are ignored.
2.94.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure:
typedef struct {
unsigned char *salt; /* pointer to 8-byte salt value */
unsigned int iterationCount; /* iteration count */
} B_PBE_PARAMS;
2.94.4 Format of info returned by B_GetAlgorithmInfo:
pointer to a B_PBE_PARAMS structure (see above).
2.94.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 166]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.94.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.94.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the address and length of the password.
2.94.8 Compatible representation:
AI_SHA1WithDES_CBCPadBER.
2.94.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.95 AI_SHA1WithDES_CBCPadBER
2.95.1 Purpose:
This AI represents the same algorithm type as AI_SHA1WithDES_CBCPad
except that it uses the ASN.1 BER format. This AI allows you to parse
and create ASN.1 algorithm identifiers such as used in PKCS #7 and
other protocols. You call B_SetAlgorithmInfo to initialize an
algorithm object from the encoded algorithm identifier which includes
ASN.1 encoding of the B_PBE_PARAMS structure defined in the
description of AI_SHA1WithDES_CBCPad. You call B_GetAlgorithmInfo
with this AI to create an encoded algorithm identifier from an
algorithm object that was created using AI_SHA1WithDES_CBCPad or
AI_SHA1WithDES_CBCPad. The OID for this algorithm, excluding the tag
and length bytes, in decimal is "42, 134, 72, 134, 247, 13, 1, 5, 10"
2.95.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies the SHA1 With
DES-CBC password-based encryption algorithm, as defined by RSA Data
Security, Inc.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 167]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.95.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than SHA1 With DES-CBC.
2.95.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.95.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_EncryptInit supplying a
key object that has been derived from a password. Then call
B_EncryptUpdate one or more times to encrypt your data. Call
B_EncryptFinal to obtain the last block of encrypted data.
To perform decryption, call B_DecryptInit supplying a key object
derived from the same password used during encryption. Then call
B_DecryptUpdate providing it with the encrypted data. Call
B_DecryptFinal to obtain the last block of decrypted data.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.95.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA and AM_DES_CBC_ENCRYPT for encrypting or AM_DES_CBC_DECRYPT
for decrypting.
2.95.7 Key info types for keyObject in B_EncryptInit or B_DecryptInit:
KI_Item that gives the address and length of the password.
2.95.8 Compatible representation:
AI_SHA1WithDES_CBCPad.
2.95.9 Output considerations:
Due to padding, the total number of output bytes from encryption can
be as many as eight more than the total input.
2.96 AI_SHA1WithRSAEncryption
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 168]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.96.1 Purpose:
This AI allows you to perform signature operations that involve the
SHA1 digest algorithm and RSA public key algorithm. The digest of a
message is created using the SHA1 algorithm and then it is signed
using PKCS#1 digital signature algorithm. Other algorithms that can
be used for the same purpose are AI_MD2WithRSAEncryption and
AI_MD5WithRSAEncryption.
2.96.2 Type of information this allows you to use:
RSA Data Security, Inc.'s SHA1 With RSA signature algorithm that uses
the SHA1 digest algorithm and RSA to create and verify RSA digital
signatures as defined in PKCS #1.
Note that in order to perform PKCS #1 digital signatures with a
20-byte digest, the RSA key must be at least 368 bits long.
2.96.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR.
2.96.4 Format of info returned by B_GetAlgorithmInfo:
NULL_PTR.
2.96.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_SignInit. Then call
B_SignUpdate zero or more times to sign your data. You may want to
call this function more than once if the data to sign resides in
separate files or buffers. Call B_SignFinal to obtain the signature.
To verify the signature, call B_VerifyInit and then call
B_VerifyUpdate zero or more times supplying it with input data. Call
B_VerifyFinal and pass the signature that you want to verify.
B_VerifyFinal returns BE_SIGNATURE if the signature of the input data
does not match the signature that was passed as an argument to it.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.96.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 169]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.96.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.96.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic, KI_RSAPublicBER.
2.96.9 Compatible representation:
AI_SHA1WithRSAEncryptionBER.
2.96.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.96.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
2.97 AI_SHA1WithRSAEncryptionBER
2.97.1 Purpose:
This AI represents the same algorithm type as
AI_SHA1WithRSAEncryption except that it uses the ASN.1 BER format.
This AI allows you to parse and create ASN.1 algorithm identifiers
such as used in PKCS #7 and other protocols. You call
B_SetAlgorithmInfo to initialize an algorithm object from the encoded
algorithm identifier. You call B_GetAlgorithmInfo with this AI to
create an encoded algorithm identifier from an algorithm object that
was created using AI_SHA1WithRSAEncryption or
AI_SHA1WithRSAEncryptionBER. The OID for this algorithm, excluding
the tag and length bytes, in decimal is "42, 134, 72, 134, 247, 13,
1, 1, 5"
2.97.2 Type of information this allows you to use:
the encoding of an algorithm identifier that specifies RSA Data
Security, Inc.'s SHA1 With RSA signature algorithm that uses the SHA1
digest algorithm and RSA to create and verify RSA digital signatures
as defined in PKCS #1.
Note that in order to perform PKCS #1 digital signatures with a
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 170]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
20-byte digest, the RSA key must be at least 368 bits long.
2.97.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
BER-encoded algorithm identifier. The encoding is converted to DER
before it is copied to the algorithm object. B_SetAlgorithmInfo
returns BE_WRONG_ALGORITHM_INFO if the algorithm identifier specifies
an algorithm other than SHA1 With RSA Encryption.
2.97.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an ITEM structure that gives the address and length of the
DER-encoded algorithm identifier.
2.97.5 BSAFE procedures to use with algorithm object:
Initialize this AI object with a call to B_SignInit. Then call
B_SignUpdate zero or more times to sign your data. You may want to
call this function more than once if the data to sign resides in
separate files or buffers. Call B_SignFinal to obtain the signature.
To verify the signature, call B_VerifyInit and then call
B_VerifyUpdate zero or more times supplying it with input data. Call
B_VerifyFinal and pass the signature that you want to verify.
B_VerifyFinal returns BE_SIGNATURE if the signature of the input data
does not match the signature supplied for verification.
You may pass (B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm
arguments required by the above functions.
2.97.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA and AM_RSA_CRT_ENCRYPT or AM_RSA_CRT_ENCRYPT_BLIND for signing
or AM_RSA_DECRYPT for verifying. AM_RSA_CRT_ENCRYPT_BLIND will
perform blinding to protect against timing attacks and
AM_RSA_CRT_ENCRYPT will not.
2.97.7 Key info types for keyObject in B_SignInit:
KI_RSA_CRT, KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER.
2.97.8 Key info types for keyObject in B_VerifyInit:
KI_RSAPublic, KI_RSAPublicBER.
2.97.9 Compatible representation:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 171]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AI_SHA1WithRSAEncryption.
2.97.10 Output considerations:
The signature result of B_SignFinal will be the same size as the RSA
key's modulus.
2.97.11 Notes:
Although the RSA signature operation is called "encryption" and the
verification operation is called "decryption", the signer uses the
digest and the private key and follows the steps needed to decrypt,
while the verifier uses the transmitted digest and the public key and
follows the steps needed to encrypt.
2.98 AI_SignVerify
2.98.1 Purpose:
This AI allows you to sign a message in compliance with the X9.31
Draft standard, or to verify X9.31 Draft compliant signatures.
2.98.2 Type of information this allows you to use:
an RSA private key to sign a message in compliance with the X9.31
Draft standard, or an RSA public key to verify X9.31 Draft compliant
signatures. For keys with even public exponent that were created with
AI_RSAStrongKeyGen, uses the Rabin-Williams algorithm as in X9.31
Draft.
2.98.3 Format of info supplied to B_SetAlgorithmInfo:
a pointer to a B_SIGN_VERIFY_PARAMS structure:
typedef struct { /* Current Choices */
unsigned char *encryptionMethodName; /* "rsaSignX931", */
/* "rsaVerifyX931" */
POINTER encryptionParams; /* Null for what is */
/* currently available */
unsigned char *digestMethodName; /* "sha1" */
POINTER digestParams; /* Null for sha1 */
unsigned char *formatMethodName; /*"formatX931" */
POINTER formatParams; /* structure of type */
/* A_X931_PARAMS for sha1 */
} B_SIGN_VERIFY_PARAMS;
If formatMethodName is "formatX931", formatParams must be given a
pointer to a structure of type A_X931_PARAMS:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 172]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef struct {
unsigned int blockLen;
unsigned int oidNum;
} A_X931_PARAMS;
2.98.4 Format of info returned by B_GetAlgorithmInfo:
a pointer to a B_SIGN_VERIFY_PARAMS structure.
2.98.5 BSAFE procedures to use with algorithm object:
B_SignInit, B_SignUpdate, B_SignFinal, and B_VerifyInit,
B_VerifyUpdate, and B_VerifyFinal. You may pass
(B_ALGORITHM_OBJ)NULL_PTR for all randomAlgorithm arguments.
2.98.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA, AM_FORMAT_X931, and AM_RSA_CRT_X931_ENCRYPT for signing; or
AM_SHA, AM_EXTRACT_X931, and AM_RSA_X931_DECRYPT for verifying.
2.98.7 Key info types for keyObject in B_SignInit or B_VerifyInit:
KI_RSAPrivate or compatible key types for signing; KI_RSAPublic or
compatible key types for verifying.
2.99 AI_SymKeyTokenGen
2.99.1 Purpose:
[Hardware Algorithm] This AI allows you to generate the token form of
a symmetric-cipher key.
2.99.2 Type of information this allows you to use:
the parameters for generating the token form of a symmetric key. The
BSAFE Hardware API supports token forms of DES, RC2, RC4, RC5, and
TDES keys.
2.99.3 Format of info supplied to B_SetAlgorithmInfo:
pointer to an A_SYMMETRIC_KEY_SPECIFIER structure:
typedef struct {
unsigned int keyUsage; /* X509 key usage bit map */
unsigned int keyLengthInBytes;
unsigned long lifeTime; /* Key lifetime; under consideration */
unsigned int protectFlag; /* Store key in encrypted form */
unsigned char *cipherName;/* String tag for key's cipher class */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 173]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* , eg, "des" */
} A_SYMMETRIC_KEY_SPECIFIER;
where cipherName is one of: "des", "desx", "rc2", "rc4", "rc5", or
"tripledes".
2.99.4 Format of info returned by B_GetAlgorithmInfo:
pointer to an A_SYMMETRIC_KEY_SPECIFIER structure.
2.99.5 BSAFE procedures to use with algorithm object:
B_SymmetricKeyGenerateInit and B_SymmetricKeyGenerate.
2.99.6 Algorithm methods to include in application's algorithm
chooser:
AM_SYMMETRIC_KEY_TOKEN_GEN
2.99.7 Notes:
Can only be used in conjunction with a hardware implementation; if no
hardware implementation is present, AI_SymKeyTokenGen does not do
anything. AI_SymKeyTokenGen can only be used if you have called
B_CreateSessionChooser for your application.
The corresponding software-based method is a HW_TABLE_ENTRY
SF_SYMMETRIC_KEY_TOKEN_GEN. This provides software support in the
case that hardware is unavailable. This method can be utilized only
by including inside the hardware chooser table.
2.100 AI_X962Random_V0
2.100.1 Purpose:
This AI allows you to generate a stream of pseudo-random numbers
which are guaranteed to have a very high degree of randomness.
Random numbers are used in deriving public and private keys,
initialization vectors, etc. This AI uses SHA1 as an underlying
hashing function. The details of this algorithm are specified in the
American National Standard X9.62-1997 Draft and it is similar to the
algorithm in section A.2.1 of X9.31-1997 Draft.
This algorithm can produce numbers between zero and the value of a
given prime minus one. Such numbers are useful for the US Government
Digital Signature Standard.
Other algorithms that can be used to generate pseudo-random numbers
are AI_MD2Random, AI_SHA1Random, and AI_MD5Random.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 174]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
2.100.2 Type of information this allows you to use:
the SHA-1 pseudo-random generator as defined in the X9.62 Draft
standard.
2.100.3 Format of info supplied to B_SetAlgorithmInfo:
NULL_PTR, if it is desired to use the AI_SHA1Random object in the
same fashion as AI_MD5Random.
a pointer to an A_SHA_RANDOM_PARAMS struct:
typedef struct {
ITEM prime; /* Optional input for X-9.62 mode only. Used to */
/* generate a pseudo-random number (but not uniform) */
/* in [1, prime - 1]. Set prime.len to zero */
/* otherwise */
ITEM seed; /* Special additional seeding of 20 to 128 bytes */
/* long. May be used in place of usual B_RandomUpdate*/
/* seeding calls, but requires the availability of */
/* nearly perfectly random bytes. If B_RandomUpdate */
/* seeding calls are used, then this additional */
/* seeding material is used to augment the */
/* randomness of the pseudo-random numbers generated.*/
} A_SHA_RANDOM_PARAMS;
2.100.4 Format of info returned by B_GetAlgorithmInfo:
returns a NULL_PTR if set with NULL_PTR; otherwise returns a pointer
to an A_SHA_RANDOM_PARAMS struct.
2.100.5 BSAFE procedures to use with algorithm object:
B_RandomInit, B_RandomUpdate, and B_GenerateRandomBytes, and as the
randomAlgorithm argument to other procedures.
2.100.6 Algorithm methods to include in application's algorithm
chooser:
AM_SHA_RANDOM.
2.100.7 Notes:
There are a number of possible implementations of SHA-1 pseudo random
number generation. AI_X962Random_V0 implements an SHA-1 Random
generator that is based on the X9.62 Draft standard. The FIPS 186
standard defines a similar algorithm (also defined in X9.31 Draft),
but due to slight differences between FIPS 186 and X9.62 Draft, the
same seeding sequence will produce different outputs. In addition,
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 175]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
AI_X962Random_V0's implementation of SHA-1 Random is substantially
different from the implementation in RSA Data Security's Java
cryptographic toolkit, JSAFE.
3. Key Info Types
This section lists the standard key info types (KIs) offered with
BSAFE. A typical application supplies a key info type as the infoType
argument to B_SetKeyInfo.
3.1 The format for each entry is as follows:
3.1.1 Purpose:
Describes the KI, what it is for, and what it does.
3.1.2 Type of information this allows you to use:
Describes the type and format of key information you can use with the
key info type.
3.1.3 Format of info supplied to B_SetKeyInfo:
Describes the exact format for supplying the key value to
B_SetKeyInfo.
3.1.4 Format of info returned by B_GetKeyInfo:
Describes the exact format that B_GetKeyInfo returns for the key
value. This is generally a "cleaned up" version of the format
supplied to B_SetKeyInfo. For example, B_GetKeyInfo with KI_DES8
returns the DES key with the DES key parity set.
3.1.5 Can get this info type if key object already has:
Most keys have multiple representations for the key information. For
example, you can specify an 8-byte RC2 key with KI_8Byte or KI_Item.
This describes what type of key information a key object must already
have if you want to call B_GetKeyInfo using this key info type.
3.2 KI_8Byte
3.2.1 Purpose:
This KI allows you to specify a generic 8-byte key for a symmetric
encryption algorithm that may be RC2, DES or any other symmetric
algorithm. For DES encryption, there exist more specific variants of
8-byte key info types, which are KI_DES8, and KI_DES8Strong.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 176]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.2.2 Type of information this allows you to use:
an 8-byte value for symmetric keys such as DES and RC2. Note that
KI_DES8Strong is usually used for a DES key because it sets the DES
parity and checks for weak DES keys.
3.2.3 Format of info supplied to B_SetKeyInfo:
pointer to an unsigned char array that holds the 8 bytes.
3.2.4 Format of info returned by B_GetKeyInfo:
pointer to an unsigned char array that holds the 8 bytes.
3.2.5 Can get this info type if key object already has:
KI_8Byte, KI_Item (if the length of the ITEM is 8), or KI_DES8.
3.3 KI_24Byte
3.3.1 Purpose:
This KI allows you to specify a generic 24-byte key for a symmetric
encryption algorithm such as Triple DES. It may also be used as
keying material for certain MAC algorithms such as HMAC. See
KI_DES24Strong for a Triple DES specific variant of this key info
type.
3.3.2 Type of information this allows you to use:
a 24-byte value for symmetric keys such as DES_EDE.
3.3.3 Format of info supplied to B_SetKeyInfo:
pointer to an unsigned char array that holds the 24 bytes.
3.3.4 Format of info returned by B_GetKeyInfo:
pointer to an unsigned char array that holds the 24 bytes.
3.3.5 Can get this info type if key object already has:
KI_24Byte, KI_Item (if the length of the ITEM is 24), KI_DESX.
3.4 KI_DES8
3.4.1 Purpose:
This KI allows you to specify an 8-byte key used by the DES
algorithm. The key object will satisfy the DES parity requirement.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 177]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Unlike KI_DES8Strong, it does not check against known DES weak keys.
See Section 5.6 "DES Weak Keys."
3.4.2 Type of information this allows you to use:
an 8-byte value for a DES key where the information stored in the key
object must be DES parity adjusted according to FIPS 46-1. BSAFE
treats the least significant bit of each byte of the key data as the
DES parity adjustment bit.
3.4.3 Format of info supplied to B_SetKeyInfo:
pointer to an unsigned char array that holds the 8-byte DES key. The
key is DES parity adjusted when it is copied to the key object.
For added security, it is prudent to check the proposed key data
against know byte sequences that produce weak DES keys before calling
B_SetKeyInfo. See Section 5.6 "DES Weak Keys."
3.4.4 Format of info returned by B_GetKeyInfo:
pointer to an unsigned char array that holds the 8-byte DES key that
is DES parity adjusted.
3.4.5 Can get this info type if key object already has:
KI_DES8, KI_Item (if the length of the ITEM is 8 and the data's DES
parity is correct), or KI_8Byte (if the DES parity is correct).
3.4.6 Notes:
It is more secure to use KI_DES8Strong instead of KI_DES8. When you
call B_SetAlgorithmInfo with KI_DES8Strong, BSAFE checks the key
against a list of known weak keys and returns an error if the
resulting key would be weak. See Section 5.6 "DES Weak Keys."
3.5 KI_DES8Strong
3.5.1 Purpose:
This KI allows you to specify an 8-byte key used by the DES
algorithm. The key object will satisfy the DES parity requirement and
will be checked against known DES weak keys. Also see KI_DES8.
3.5.2 Type of information this allows you to use:
an 8-byte value for a DES key where the information stored in the key
object will be DES parity adjusted according to FIPS 46-1. BSAFE
treats the least significant bit of each byte of the key data as the
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 178]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
DES parity adjustment bit. When setting a key object with this KI,
BSAFE will check the input data against a list of known DES weak
keys. If the resulting key would be weak, BSAFE returns an error.
3.5.3 Format of info supplied to B_SetKeyInfo:
pointer to an unsigned char array that holds the 8-byte DES key. The
key is DES parity adjusted when it is copied to the key object.
3.5.4 Format of info returned by B_GetKeyInfo:
pointer to an unsigned char array that holds the 8-byte DES key,
which is DES parity adjusted.
3.5.5 Can get this info type if key object already has:
KI_DES8Strong, KI_DES8 (if the key is not weak), KI_Item (if the
length of the ITEM is 8, the data's DES parity is correct, and the
key is not weak), or KI_8Byte (if the DES parity is correct and the
key is not weak.
3.6 KI_DES24Strong
3.6.1 Purpose:
This KI allows you to specify a 24-byte key used by the Triple DES
algorithm. The key object will satisfy the DES parity requirement and
will be checked against known DES weak keys.
3.6.2 Type of information this allows you to use:
24-byte value for a Triple DES key where the information stored in
the key object will be DES parity-adjusted according to FIPS 46-1.
BSAFE treats the least significant bit of each byte of the key data
as the DES parity-adjustment bit. When setting a key object with this
KI, BSAFE will check the input data against a list of known DES weak
keys. If the resulting key would be weak, BSAFE returns an error.
3.6.3 Format of info supplied to B_SetKeyInfo:
pointer to an unsigned char array that holds the 24-byte Triple DES
key. The key is DES parity adjusted when it is copied to the key
object.
3.6.4 Format of info returned by B_GetKeyInfo:
pointer to an unsigned char array that holds the 24-byte Triple DES
key that is DES parity adjusted.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 179]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.6.5 Can get this info type if key object already has:
KI_DES24Strong, KI_24Byte (if the key is not weak), KI_Item (if the
length of the ITEM is 24 and the key is not weak), KI_DESX (if the
key is not weak).
3.7 KI_DESX
3.7.1 Purpose:
This KI allows you to specify keying materials for the DESX
algorithm. They include the key value, input whitener and output
whitener. The key value will be used as the DES encryption key for
the DESX algorithm and thus it will be parity adjusted. See the
AI_DESX_CBC_IV8 section for descriptions of the DESX algorithm.
3.7.2 Type of information this allows you to use:
a DESX key where the key value, input whitener, and output whitener
are specified.
3.7.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_DESX_KEY structure:
typedef struct {
unsigned char *key; /* pointer to 8- byte key */
unsigned char *inputWhitener; /* pointer to 8-byte input */
/* whitener */
unsigned char *outputWhitener; /* pointer to 8-byte output */
/* whitener */
} A_DESX_KEY;
The value of key is DES parity adjusted when it is copied to the key
object.
3.7.4 Format of info returned by B_GetKeyInfo:
pointer to an A_DESX_KEY structure (see above). The value of key is
DES parity adjusted.
3.7.5 Can get this info type if key object already has:
KI_24Byte (if the DES parity is correct), KI_Item (if the length of
the ITEM is 24 and the data's DES parity is correct), or KI_DESX.
3.8 KI_DSAPrivate
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 180]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.8.1 Purpose:
This KI allows you to specify a private key used by the DSA
algorithm. The information consists of a private component and the
three parameters: p, q, and g, which are explained below. See
KI_DSAPrivateBER for the same key type with BER encoding.
3.8.2 Type of information this allows you to use:
a DSA private key. The parameters of the key are specified as the
following: private component (x), the prime (p), the subprime (q) and
the base (g).
3.8.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_DSA_PRIVATE_KEY structure:
typedef struct {
ITEM x; /* private component */
A_DSA_PARAMS params; /* the DSA parameters, p, q and g */
} A_DSA_PRIVATE_KEY;
where A_DSA_PARAMS is defined as
typedef struct {
ITEM prime; /* the prime p */
ITEM subPrime; /* the subprime q */
ITEM base; /* the base g */
} A_DSA_PARAMS;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.8.4 Format of info returned by B_GetKeyInfo:
pointer to an A_DSA_PRIVATE_KEY structure (see above). All leading
zeros have been stripped from each integer in the structure.
3.8.5 Can get this info type if key object already has:
KI_DSAPrivate or KI_DSAPrivateBER.
3.9 KI_DSAPrivateBER
3.9.1 Purpose:
This KI represents the same algorithm type as KI_DSAPrivate except
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 181]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
that it uses the ASN.1 BER format. It allows you to parse and create
an ASN.1 key info type encoded with the PKCS #8 standard. You call
B_SetKeyInfo to initialize a key object from the encoded key info
type that includes the private component, prime, subprime and base.
You call B_GetKeyInfo with this KI to create an encoded key info type
from a key object that was created using KI_DSAPrivate or
KI_DSAPrivateBER. The OID for DSA keys, excluding the tag and length
bytes, in decimal, is "43, 14, 3, 2, 12". Also see KI_DSAPrivate.
3.9.2 Type of information this allows you to use:
the encoding of a DSA private key that is encoded as a PKCS #8
PrivateKeyInfo type that contains an RSA Data Security, Inc.
DSAPrivateKey type. Note that this encoding contains all of the
information specified by KI_DSAPrivate.
3.9.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
BER encoding. The encoding is converted to DER before it is copied to
the key object. B_SetKeyInfo returns BE_WRONG_KEY_INFO if the
PrivateKeyInfo specifies a private key for an algorithm other than
DSA.
3.9.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
DER encoding.
3.9.5 Can get this info type if key object already has:
KI_DSAPrivate or KI_DSAPrivateBER.
3.10 KI_DSAPublic
3.10.1 Purpose:
This KI allows you to specify a public key used by the DSA algorithm.
The information consists of a private component and the three
parameters: p, q, and g, which are explained below. See
KI_DSAPublicBER for the same key type with BER encoding.
3.10.2 Type of information this allows you to use:
a DSA public key where all the parameters are specified as in X9.30
Part III: the public component (y), the prime (p), the subprime (q),
and the base (g).
3.10.3 Format of info supplied to B_SetKeyInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 182]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an A_DSA_PUBLIC_KEY structure:
typedef struct {
ITEM y; /* public component */
A_DSA_PARAMS params; /* the DSA parameters; p, q, and g */
} A_DSA_PUBLIC_KEY;
where A_DSA_PARAMS is defined as:
typedef struct {
ITEM prime; /* the prime p */
ITEM subPrime; /* the subprime q */
ITEM base; /* the base g */
} A_DSA_PARAMS;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.10.4 Format of info returned by B_GetKeyInfo:
pointer to an A_DSA_PUBLIC_KEY structure (see above). All leading
zeros have been stripped from each integer in the structure.
3.10.5 Can get this info type if key object already has:
KI_DSAPublic or KI_DSAPublicBER.
3.11 KI_DSAPublicBER
3.11.1 Purpose:
This KI represents the same algorithm type as KI_DSAPublic except
that it uses the ASN.1 BER format. It allows you to parse and create
an ASN.1 key info type encoded with the X.509 standard for
SubjectPublicKeyInfo. You call B_SetKeyInfo to initialize a key
object from the encoded key info type that includes the public
component, prime, subprime and base. You call B_GetKeyInfo with this
KI to create an encoded key info type from a key object that was
created using KI_DSAPublic or KI_DSAPublicBER. The OID for DSA keys,
excluding the tag and length bytes, in decimal, is "43, 14, 3, 2,
12". Also see KI_DSAPublic.
3.11.2 Type of information this allows you to use:
the encoding of a DSA public key that is encoded as an X.509
SubjectPublicKeyInfo type as defined in X9.30 Part III. Note that
this encoding contains all of the information specified by
KI_DSAPublic.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 183]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.11.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
BER encoding. The encoding is converted to DER before it is copied to
the key object. B_SetKeyInfo returns BE_WRONG_KEY_INFO if the
PublicKeyInfo specifies a public key for an algorithm other than DSA.
3.11.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
DER encoding.
3.11.5 Can get this info type if key object already has:
KI_DSAPublic or KI_DSAPublicBER.
3.12 KI_ECPrivate
3.12.1 Purpose:
This KI allows you to specify a private key used by the Elliptic
Curve algorithm. The information consists of the private component
and the underlying elliptic curve parameters that are explained
below.
3.12.2 Type of information this allows you to use:
an elliptic curve private key. The parameters of the key are
specified as the private component privateKey, and the underlying
elliptic curve parameters.
3.12.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_EC_PRIVATE_KEY structure:
typedef struct {
A_EC_PARAMS curveParams; /* underlying elliptic curve parameters */
ITEM privateKey; /* private component */
} A_EC_PRIVATE_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first,
and the ITEM's len gives its length. For all ITEM values except the
curve parameters base, leading zeros are stripped before it is copied
to the key object.
3.12.4 Format of info returned by B_GetKeyInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 184]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an A_EC_PRIVATE_KEY structure.
3.12.5 Can get this info type if key object already has:
KI_ECPrivate.
3.13 KI_ECPrivateComponent
3.13.1 Purpose:
This KI allows you to specify the private component of an EC private
key. Unlike KI_ECPrivate, it does not contain the underlying EC
parameters and it is not to be used with any algorithms. It provides
a way to extract the EC private key.
3.13.2 Type of information this allows you to use:
the private component of an EC private key.
3.13.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure containing the private component of an
EC private key.
3.13.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure containing the private component of an
EC private key.
3.13.5 Restrictions:
Key objects built with this KI are not compatible with any BSAFE AI.
This KI is supplied only as a convenience to extract the EC private
component.
3.13.6 Can get this info type if key object already has:
KI_ECPrivateComponent or KI_ECPrivate.
3.14 KI_ECPublic
3.14.1 Purpose:
This KI allows you to specify a public key used by the Elliptic Curve
algorithm. The information consists of the public component and the
underlying elliptic curve parameters that are explained below.
3.14.2 Type of information this allows you to use:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 185]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
an elliptic curve public key. The parameters of the key are specified
as the public component (publicKey), and the underlying elliptic
curve parameters.
3.14.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_EC_PUBLIC_KEY structure:
typedef struct {
A_EC_PARAMS curveParams; /* underlying elliptic curve parameters */
ITEM publicKey; /* public component */
} A_EC_PUBLIC_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first,
and the ITEM's len gives its length. For all ITEM values except the
public component (x) and the curve parameter base, leading zeros are
stripped before it is copied to the key object.
3.14.4 Format of info returned by B_GetKeyInfo:
pointer to an A_EC_PUBLIC_KEY structure.
3.14.5 Can get this info type if key object already has:
KI_ECPublic.
3.15 KI_ECPublicComponent
3.15.1 Purpose:
This KI allows you to specify the public key component of an EC
public key. Unlike KI_ECPublic, it does not specify the underlying EC
parameters and it is not to be used with any algorithms. It provides
a way to extract the EC public key.
3.15.2 Type of information this allows you to use:
the public component of an elliptic curve public key.
3.15.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure containing the public component of an EC
public key.
3.15.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure containing the public component of an EC
public key.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 186]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.15.5 Restrictions:
Key objects built with this KI are not compatible with any BSAFE AI.
This KI is supplied only as a convenience to extract the EC public
component.
3.15.6 Can get this info type if key object already has:
KI_ECPublicComponent or KI_ECPublic.
3.16 KI_ExtendedToken
3.16.1 Purpose:
This KI allows you to specify a software-based token form of a
symmetric key. See KI_KeypairToken for a token form of a
public/private key pair.
3.16.2 Type of information this allows you to use:
software-based token forms of symmetric keys. Downward compatible
with KI_Token.
3.16.3 Format of info supplied to B_SetKeyInfo:
pointer to a KI_EXTENDED_TOKEN_INFO structure
typedef struct {
KI_TOKEN_INFO keyDataStruct;
A_X509_ATTRIB_INFO attributes;
} KI_EXTENDED_TOKEN_INFO;
where A_X509_ATTRIB_INFO is defined by:
typedef struct {
A_SYMMETRIC_KEY_DEFINER externalSpecs;
unsigned char *keyOID; /* Currently unimplemented */
unsigned int keyOIDLen; /* ditto */
unsigned long dateOfBirth; /* When the key was created. */
/* This time stamp currently */
/* defaults to time () function */
} A_X509_ATTRIB_INFO;
and A_SYMMETRIC_KEY_DEFINER is defined by:
typedef struct {
unsigned int keyUsage;
unsigned int keyLengthInBytes;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 187]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
UINT4 lifeTime;
unsigned int protectFlag;
} A_SYMMETRIC_KEY_DEFINER;
3.16.4 Format of info returned by B_GetKeyInfo:
pointer to a KI_EXTENDED_TOKEN_INFO structure (see above).
3.16.5 Can get this info type if key object already has:
a symmetric key of the appropriate type, for example, a DES key when
using DES. Used when one of the algorithm methods used by
AI_SymKeyTokenGen has been listed in
the fixedChooser argument to B_CreateSessionChooser, but no hardware
is present.
3.16.6 Notes:
KI_ExtendedToken can only be used if you have called
B_CreateSessionChooser for your application.
3.17 KI_Item
3.17.1 Purpose:
This KI allows you to specify a generic keying material of any
length. It may be used to hold a secret key of a symmetric encryption
algorithm, a key of a keyed hash algorithm, a password object, etc.
3.17.2 Type of information this allows you to use:
a variable-length block of data (such as an RC4 key), a password for
password-based encryption algorithms, or the value of a secret key
when it is recovered from a public-key encryption block.
3.17.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure:
typedef struct {
unsigned char *data;
unsigned int len;
} ITEM;
where data is the address of the unsigned byte array and len is its
length.
3.17.4 Format of info returned by B_GetKeyInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 188]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an ITEM structure (see above)
3.17.5 Can get this info type if key object already has:
KI_Item, KI_8Byte, KI_24Byte, KI_DES8, or KI_DESX.
3.18 KI_KeypairToken
3.18.1 Purpose:
This KI allows you to specify a software-based token form of a public
and private key pair of RSA or DSA. See KI_ExtendedToken for a token
form of a symmetric key.
3.18.2 Type of information this allows you to use:
software-based token forms of RSA or DSA public and private key
pairs. Downward compatible with KI_Token.
3.18.3 Format of info supplied to B_SetKeyInfo:
pointer to a KI_KEYPAIR_TOKEN_INFO structure:
typedef struct {
KI_TOKEN_INFO keyDataStruct;
A_X509_KEYPAIR_ATTRIB_INFO attributes;
} KI_KEYPAIR_TOKEN_INFO;
where A_X509_KEYPAIR_ATTRIB_INFO is defined by:
typedef struct {
A_KEYPAIR_DEFINER externalSpecs;
unsigned long dateOfBirth;
} A_X509_KEYPAIR_ATTRIB_INFO;
and A_KEYPAIR_DEFINER is defined by:
typedef struct {
unsigned int keyUsage; /* X509 key usage bit map */
UINT4 lifeTime; /* Key lifetime; under consideration */
unsigned int protectFlag; /* Store key in encrypted form */
} A_KEYPAIR_DEFINER;
3.18.4 Format of info returned by B_GetKeyInfo:
pointer to a KI_KEYPAIR_TOKEN_INFO structure.
3.18.5 Can get this info type if key object already has:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 189]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
an RSA or DSA key pair. Used when one of the algorithm methods used
by AI_KeypairTokenGen has been listed in the fixedChooser argument to
B_CreateSessionChooser, but no hardware is present.
3.18.6 Notes:
KI_KeypairToken can only be used if you have called
B_CreateSessionChooser for your application.
3.19 KI_PKCS_RSAPrivate
3.19.1 Purpose:
This KI allows you to specify a private key of the RSA algorithm as
defined in PKCS #1. The information consists of the modulus,
exponents, two primes and the Chinese Remainder Theorem information
that are explained below. See KI_PKCS_RSAPrivateBER for the same key
info type with BER encoding.
3.19.2 Type of information this allows you to use:
an RSA private key where all the integers are specified as in PKCS
#1: modulus, public and private exponents, and Chinese Remainder
Theorem information. Note that KI_RSA_CRT can be used for a private
key that has the modulus and Chinese Remainder Theorem information
but no public or private exponent.
3.19.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_PKCS_RSA_PRIVATE_KEY structure:
typedef struct {
ITEM modulus; /* modulus */
ITEM publicExponent; /* exponent for public key */
ITEM privateExponent; /* exponent for private key */
ITEM prime[2]; /* prime factors */
ITEM primeExponent[2]; /* exponents for prime factors */
ITEM coefficient; /* CRT coefficient */
} A_PKCS_RSA_PRIVATE_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.19.4 Format of info returned by B_GetKeyInfo:
pointer to an A_PKCS_RSA_PRIVATE_KEY structure (see above). All
leading zeros have been stripped from each integer in the structure.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 190]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.19.5 Can get this info type if key object already has:
KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER or KI_RSA_CRT.
3.20 KI_PKCS_RSAPrivateBER
3.20.1 Purpose:
This KI represents the same algorithm type as KI_PKCS_RSAPrivate
except that it uses the ASN.1 BER format. It allows you to parse and
create an ASN.1 key info type that is encoded with the PKCS #8
standard. You call B_SetKeyInfo to initialize a key object from the
encoded key info type that includes the modulus, exponents, two
primes and Chinese Remainder Theorem information. You call
B_GetKeyInfo with this KI to create an encoded key info type from a
key object that was created using KI_PKCS_RSAPrivate,
KI_PKCS_RSAPrivateBER or KI_RSA_CRT. The OID for RSA PKCS #1
encryption, excluding the tag and length bytes, in decimal, is "42,
134, 72, 134, 247, 13, 1, 1, 1". Also see KI_PKCS_RSAPrivate.
3.20.2 Type of information this allows you to use:
the encoding of an RSA private key that is encoded as a PKCS #8
PrivateKeyInfo type that contains a PKCS #1 RSAPrivateKey type. Note
that this encoding contains all of the information specified by
KI_PKCS_RSAPrivate.
3.20.3 Format of info supplied to B_SetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
BER encoding. The encoding is converted to DER before it is copied to
the key object. B_SetKeyInfo returns BE_WRONG_KEY_INFO if the
PrivateKeyInfo specifies a private key for an algorithm other than
RSA.
3.20.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
DER encoding.
3.20.5 Can get this info type if key object already has:
KI_PKCS_RSAPrivate, KI_PKCS_RSAPrivateBER or KI_RSA_CRT.
3.21 KI_RSA_CRT
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 191]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.21.1 Purpose:
This KI allows you to specify a private key of the RSA algorithm
without the public or private key exponent information. The modulus
and Chinese Remainder Theorem information have to be provided.
3.21.2 Type of information this allows you to use:
an RSA private key where the modulus and Chinese Remainder Theorem
information integers are specified, but not the public or private
exponent integers. (For RSA private key information with the public
and private exponent integers, see KI_PKCS_RSAPrivate.)
3.21.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_RSA_CRT_KEY structure:
typedef struct {
ITEM modulus; /* modulus */
ITEM prime[2]; /* prime factors */
ITEM primeExponent[2]; /* exponents for prime */
/* factors */
ITEM coefficient; /* CRT coefficient */
} A_RSA_CRT_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.21.4 Format of info returned by B_GetKeyInfo:
pointer to an A_RSA_CRT_KEY structure (see above). All leading zeros
have been stripped from each integer in the structure.
3.21.5 Can get this info type if key object already has:
KI_RSA_CRT, KI_PKCS_RSAPrivate, or KI_PKCS_RSAPrivateBER.
3.22 KI_RSAPrivate
3.22.1 Purpose:
This KI allows you to specify an RSA private key with the modulus and
private key exponent. Unlike KI_PKCS_RSAPrivate, it does not contain
the Chinese Remainder Theorem information and it is not be used with
any algorithms. It provides a way to store or transport a private
key.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 192]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.22.2 Type of information this allows you to use:
an RSA private key where the modulus and private exponent integers
are specified, but not the Chinese Remainder Theorem information.
3.22.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_RSA_KEY structure:
typedef struct {
ITEM modulus; /* modulus */
ITEM exponent; /* exponent */
} A_RSA_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.22.4 Format of info returned by B_GetKeyInfo:
pointer to an A_RSA_KEY structure (see above). All leading zeros have
been stripped from each integer in the structure.
3.22.5 Can get this info type if key object already has:
KI_RSAPrivate, KI_PKCS_RSAPrivate or KI_PKCS_RSAPrivateBER.
3.22.6 Note:
You can use KI_RSAPrivate to set a key object with your private
modulus and private exponent. This can be used for storing your key
information or when you need to export the information in "raw" form
to another application. However, there are no BSAFE algorithms that
use this key type.
3.23 KI_RSAPublic
3.23.1 Purpose:
This KI allows you to specify an RSA public key with the modulus and
public key exponent. See KI_RSAPublicBER for the same key info type
with BER encoding.
3.23.2 Type of information this allows you to use:
an RSA public key where the modulus and exponent integers are
specified.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 193]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
3.23.3 Format of info supplied to B_SetKeyInfo:
pointer to an A_RSA_KEY structure:
typedef struct {
ITEM modulus; /* modulus */
ITEM exponent; /* exponent */
} A_RSA_KEY;
Each ITEM supplies an integer in canonical format, where the ITEM's
data points to an unsigned byte array, most significant byte first
and the ITEM's len gives its length. All leading zeros are stripped
from each integer before it is copied to the key object.
3.23.4 Format of info returned by B_GetKeyInfo:
pointer to an A_RSA_KEY structure (see above). All leading zeros have
been stripped from each integer in the structure.
3.23.5 Can get this info type if key object already has:
KI_RSAPublic, KI_RSAPublicBER, KI_PKCS_RSAPrivate, or
KI_PKCS_RSAPrivateBER.
3.24 KI_RSAPublicBER
3.24.1 Purpose:
This KI represents the same algorithm type as KI_RSAPublic except
that it uses the ASN.1 BER format. It allows you to parse and create
an ASN.1 key info type that is encoded with the X.509 standard of
SubjectPublicKeyInfo. You call B_SetKeyInfo to initialize a key
object from the encoded key info type that includes the modulus, and
public exponent. You call B_GetKeyInfo with this KI to create an
encoded key info type from a key object that was created using
KI_RSAPublic, KI_RSAPublicBER, KI_PKCS_RSAPrivate or
KI_PKCS_RSAPrivateBER. The OID for RSA PKCS #1 encryption, excluding
the tag and length bytes, in decimal, is "42, 134, 72, 134, 247, 13,
1, 1, 1". Also see KI_RSAPublic.
3.24.2 Type of information this allows you to use:
the encoding of an RSA public key that is encoded as an X.509
SubjectPublicKeyInfo type that contains an X.509 RSAPublicKey type
(also defined in PKCS #1). Note that this encoding contains all of
the information specified by KI_RSAPublic.
3.24.3 Format of info supplied to B_SetKeyInfo:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 194]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
pointer to an ITEM structure that gives the address and length of the
BER encoding. The encoding is converted to DER before it is copied to
the key object. B_SetKeyInfo returns BE_WRONG_KEY_INFO if the public
key info specifies a public key for an algorithm other than RSA. Note
that B_SetKeyInfo will accept an encoding that contains an object
identifier for rsa as well as rsaEncryption (defined in PKCS #1).
3.24.4 Format of info returned by B_GetKeyInfo:
pointer to an ITEM structure that gives the address and length of the
DER encoding. Note that B_GetKeyInfo returns an encoding that
contains the object identifier for rsaEncryption (defined in PKCS #1)
as opposed to rsa.
3.24.5 Can get this info type if key object already has:
KI_RSAPublicBER, KI_RSAPublic, KI_PKCS_RSAPrivate, or
KI_PKCS_RSAPrivateBER.
3.25 KI_Token
3.25.1 Purpose:
This KI allows you to specify a hardware-based token form of a key,
which may be either a symmetric key or a public/private key pair.
Also see KI_ExtendedToken and KI_KeypairToken for other key info
types with token forms.
3.25.2 Type of information this allows you to use:
hardware-based token forms of symmetric keys and public/private key
pairs.
3.25.3 Format of info supplied to B_SetKeyInfo:
pointer to a KI_TOKEN_INFO structure
typedef struct {
ITEM manufacturerId; /* tag used to differentiate */
/* different hardware tokens */
ITEM internalKey; /* OEM-supplied key handle */
} KI_TOKEN_INFO;
:
3.25.4 Format of info returned by B_GetKeyInfo:
pointer to a KI_TOKEN_INFO structure (see above).
3.25.5 Can get this info type if key object already has:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 195]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
a key object of the appropriate type, for example, an RSA key pair
for RSA or a DES key for DES. Hardware that uses key tokens must be
present.
3.25.6 Notes:
Can only be used in conjunction with a hardware implementation; in
particular, KI_Token can only be used if you have called
B_CreateSessionChooser for your application.
4. Details of BSAFE Functions
This section describes the toolkit's top level API and its bottom
level platform specific routines. The procedures with names that
start "B_" make up the top level API which is called by applications.
The procedure names starting with "T_" are called by the toolkit's
internal routines to perform platform specific operations like
allocating and copying memory.
4.1 B_BuildTableFinal
int B_BuildTableFinal (
B_ALGORITHM_OBJ buildTableObj, /* table-building object */
unsigned char *accelTable, /* acceleration table buffer */
unsigned int *accTableByteLen, * size of created acceleration */
/* table in bytes */
unsigned int maxAccTableLength, /* size of acceleration table */
/* buffer */
A_SURRENDER_CTX * surrenderCtx /* surrender context */
);
Generates and outputs the acceleration table to accelTable, setting
accTableByteLen to the number of bytes output. It returns
BE_OUTPUT_LEN if maxAccTableLength is smaller than needed.
4.1.1 Return Value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.2 B_BuildTableGetBufSize
int B_BuildTableGetBufSize (
B_ALGORITHM_OBJ buildTableObj, /* table-building object */
unsigned int * tableSizeInBytes /* size of table in bytes */
);
Sets tableSizeInBytes to the buffer size needed to accommodate the
generated table.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 196]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.2.1 Return Value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.3 B_BuildTableInit
int B_BuildTableInit (
B_ALGORITHM_OBJ buildTableObj, /* table-building object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX surrenderCtx /* surrender context */
);
Initializes a table-building object used to build acceleration
tables for elliptic curve cryptography.
4.3.1 Return Value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.4 B_CreateAlgorithmObject
int B_CreateAlgorithmObject (
B_ALGORITHM_OBJ *algorithmObject /* new algorithm object */
);
B_CreateAlgorithmObject allocates and initializes a new algorithm
object, storing the result in algorithmObject. If
B_CreateAlgorithmObject is unsuccessful, no memory is allocated and
algorithmObject is set to (B_ALGORITHM_OBJ)NULL_PTR.
4.4.1 Return value
0 success
non-zero see Appendix A, BSAFE Error Types
4.5 B_CreateKeyObject
int B_CreateKeyObject (
B_KEY_OBJ *keyObject /* new key object */
);
B_CreateKeyObject allocates and initializes a new key object, storing
the result in keyObject. If B_CreateKeyObject is unsuccessful, no
memory is allocated and keyObject is set to (B_KEY_OBJ)NULL_PTR.
4.5.1 Return Value
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 197]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.6 B_CreateSessionChooser
int B_CreateSessionChooser (
B_Chooser fixedChooser, /* Chooser consisting of software-based */
/* algorithm methods. */
B_Chooser *sessionChooser, /* Runtime chooser dynamically bound to */
/* available hardware based methods. */
HW_TABLE_ENTRY *staticHardwareList[ ], /* List of statically */
/* defined hardware methods */
/* terminated by a properly cast NULL_PTR. */
ITEM *passPhrase, /* List of hardware passphrases, terminated */
/* by properly cast NULL_PTR. */
POINTER *amTagList, /* For now pass (*)NULL_PTR */
unsigned char ***listOfOEMTags /* Returns list of OEM tags */
/* for methods in sessionChooser */
);
B_CreateSessionChooser replicates the fixed chooser inclusive of
making private copies of the AM structures. Whenever possible
the software-based methods are replaced with the hardware-based
methods defined either statically by staticHardwareList or
dynamically determined by platform specific routines. All methods
in the fixedChooser will be represented in the sessionChooser and
will appear multiple times if there are multiple hardware substitutes
available.
4.6.1 Return Value
0 success
non-zero unsuccessful, allocation error
4.7 B_DecodeDigestInfo
int B_DecodeDigestInfo (
ITEM *algorithmID, /* message digest algorithm identifier */
ITEM *digest, /* message digest value */
unsigned char *digestInfo, /* digestInfo encoding */
unsigned int digestInfoLen /* length of digestInfo */
)*;
B_DecodeDigestInfo decodes the BER encoding of a PKCS #1 DigestInfo
type that is given by digestInfo of length digestInfoLen. On output,
the algorithmID ITEM gives the digest algorithm identifier and the
digest ITEM gives the digest value. The ITEM type is defined by the
KI_Item key info type in Section 3.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 198]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.7.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.8 B_DecodeFinal
int B_DecodeFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen /* size of output data buffer */
);
B_DecodeFinal finalizes the decoding process specified by
algorithmObject, writing any remaining decoded output to partOut,
which is a buffer supplied by the caller of at least maxPartOutLen
bytes, and setting partOutLen to the number of bytes written to
partOut. algorithmObject is reset to the state it was in after the
call to B_DecodeInit, so that another decoding process may be
performed. See B_DecodeInit.
4.8.1 Return value
0 success
non-zero see Appendix A, BSAFE Error Types
4.9 B_DecodeInit
int B_DecodeInit (
B_ALGORITHM_OBJ algorithmObject /* algorithm object */
);
B_DecodeInit allocates and initializes algorithmObject for decoding
(not decrypting) data using the algorithm specified by a previous
call to B_SetAlgorithmInfo. For example, the AI_RFC1113Recode
algorithm provides Base64 encoding and decoding to convert binary
data to and from a printable form suitable for most email systems.
Notice that there are no cryptographic keys for encoding or decoding.
B_DecodeInit only needs to be called once to set up a decode
algorithm. The B_DecodeUpdate routine can be called multiple times to
process blocks of data, and B_DecodeFinal is called once to process
the last block which includes removing any trailing pad bytes. After
B_DecodeFinal is called, B_DecodeUpdate can be called to start
decoding another sequence of blocks. There is no need to call
B_DecodeInit again.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 199]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.9.1 Return value
0 success
non-zero see Appendix A, BSAFE Error Types
4.10 B_DecodeUpdate
int B_DecodeUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
unsigned chart *partIn, /* input data */
unsigned int partInLen /* length of output data */
);
B_DecodeUpdate updates the decoding process specified by
algorithmObject with partInLen bytes from partIn, writing the decoded
output to partOut, which is a buffer supplied by the caller of at
least maxPartOutLen bytes, and setting partOutLen to the number of
bytes written to partOut. B_DecodeUpdate may be called zero or more
times to supply the data by parts. See B_DecodeInit.
4.10.1 Return value
0 success
non-zero see Appendix A, BSAFE Error Types
4.11 B_DecryptFinal
int B_DecryptFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_DecryptFinal finalizes the decrypting process specified by
algorithmObject, writing any remaining decrypted output to partOut,
which is a buffer supplied by the caller of at least maxPartOutLen
bytes, and setting partOutLen to the number of bytes written to
partOut. The algorithm object for supplying random numbers is
randomAlgorithm; it may be (B_ALGORITHM_OBJ)NULL_PTR for decrypting
algorithms that do not need random numbers. The surrender context for
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. algorithmObject is reset to the state it was in
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 200]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
after the call to B_DecryptInit, so that another decrypting process
may be performed. See B_DecryptInit.
4.11.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.12 B_DecryptInit
int B_DecryptInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_DecryptInit initializes algorithmObject for decrypting data using
the algorithm specified by a previous call to B_SetAlgorithmInfo. The
key object for supplying the key information is keyObject. The
chooser for selecting the algorithm method is algorithmChooser. The
surrender context for processing and canceling during lengthy
operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
B_DecryptInit only needs to be called once to set up a key. The
B_DecryptUpdate routine can be called multiple times to process
blocks of data, and B_DecryptFinal is called once to process the last
block, which includes removing the trailing pad bytes.
After B_DecryptFinal is called, B_DecryptUpdate can be called to
start processing another sequence of blocks that were encrypted in
the same key. If a different CBC Initialization Vector (IVs) is used
with each sequence of blocks, B_SetAlgorithmInfo can be called with
AI_CBC_IV8 to set the new IV before calling B_DecryptUpdate. There
is no need to call B_DecryptInit again with the same key.
4.12.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.13 B_DecryptUpdate
int B_DecryptUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
unsigned char *partIn, /* input data */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 201]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int partInLen, /* length of input data */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_DecryptUpdate updates the decrypting process specified by
algorithmObject with partInLen bytes from partIn, writing the
decrypted output to partOut, which is a buffer supplied by the caller
of at least maxPartOutLen bytes, and setting partOutLen to the number
of bytes written to partOut. The algorithm object for supplying
random numbers is randomAlgorithm; it may be
(B_ALGORITHM_OBJ)NULL_PTR for decrypting algorithms that do not need
random numbers. The surrender context for processing and canceling
during lengthy operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
B_DecryptUpdate may be called zero or more times to supply the data
by parts. See B_DecryptInit.
4.13.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.14 B_DestroyAlgorithmObject
void B_DestroyAlgorithmObject (
B_ALGORITHM_OBJ *algorithmObject /* ptr to algorithm object */
);
B_DestroyAlgorithmObject destroys algorithmObject, zeroizing any
sensitive information, freeing the memory the algorithm object
occupied, and setting algorithmObject to (B_ALGORITHM_OBJ)NULL_PTR.
If algorithmObject is already (B_ALGORITHM_OBJ)NULL_PTR or is not a
valid algorithm object, no action is taken.
See B_CreateAlgorithmObject.
After this routine is called, all the pointers to information blocks
returned by calls to B_GetAlgorithmInfo will no longer be valid,
since the memory associated with those blocks will have been zeroed
and freed.
4.14.1 Return value
There is no return value.
4.15 B_DestroyKeyObject
void B_DestroyKeyObject (
B_KEY_OBJ *keyObject /* pointer to key object */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 202]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
);
B_DestroyKeyObject destroys keyObject, zeroizing any sensitive
information, freeing the memory the key object occupied, and setting
keyObject to (B_KEY_OBJ)NULL_PTR. If keyObject is already
(B_KEY_OBJ)NULL_PTR or is not a valid key object, no action is taken.
See B_CreateKeyObject.
After this routine is called, all the pointers to information blocks
returned by calls to B_GetKeyInfo will no longer be valid, since the
memory associated with those blocks will have been zeroed and freed.
4.15.1 Return value
There is no return value.
4.16 B_DigestFinal
int B_DigestFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *digest, /* message digest output buffer */
unsigned int *digestLen, /* length of message digest output */
unsigned int maxDigestLen, /* size of output buffer */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_DigestFinal finalizes the digesting process for algorithmObject and
writes the message digest to digest, which is a buffer supplied by
the caller of at least maxDigestLen bytes, and sets digestLen to the
length of the digest. The surrender context for processing and
canceling during lengthy operations is surrenderContext; if its value
is (A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
algorithmObject is reset to the state it was in after the call to
B_DigestInit, so that another message digesting process may be
performed. See B_DigestInit.
4.16.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.17 B_DigestInit
int B_DigestInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 203]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_DigestInit initializes algorithmObject for computing a message
digest using the algorithm specified by a previous call to
B_SetAlgorithmInfo. The chooser for selecting the algorithm method is
algorithmChooser. The key object for supplying the key information is
keyObject; it should be (B_KEY_OBJ)NULL_PTR for keyless digesting
algorithms. The surrender context for processing and canceling during
lengthy operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
B_DigestInit only needs to be called once to set up a digest
algorithm. The B_DigestUpdate routine can be called multiple times to
process blocks of data, and B_DigestFinal is called once to process
the last block which includes producing the result. After
B_DigestFinal is called, B_DigestUpdate can be called to start
digesting another sequence of blocks. There is no need to call
B_DigestInit again.
4.17.1 Return value
0 success
non-zero see Appendix A, BSAFE Error Types
4.18 B_DigestUpdate
int B_DigestUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partIn, /* input data */
unsigned int partInLen, /* length of input data */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_DigestUpdate updates algorithmObject with partInLen bytes from
partIn. The surrender context for processing and canceling during
lengthy operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it. B_DigestUpdate
may be called zero or more times to supply the data by parts. See
B_DigestInit.
4.18.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.19 B_EncodeDigestInfo
int B_EncodeDigestInfo (
unsigned char *digestInfo, /* encoded output buffer */
unsigned int *digestInfoLen, /* length of encoded output */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 204]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int maxDigestInfoLen, /* size of digestInfo buffer */
ITEM *algorithmID, /* msg digest algorithm id */
unsigned char *digest, /* message digest value */
unsigned int digestLen /* length of digest */
);
B_EncodeDigestInfo encodes the DER encoding of a PKCS #1 DigestInfo
type, writing the encoding to digestInfo, which is a buffer supplied
by the caller of at least maxDigestInfoLen bytes, and sets
digestInfoLen to the length of the encoding. algorithmID points to an
ITEM that gives the DER encoding of the message digest algorithm.
The ITEM type is defined by the KI_Item key info type in Section 3.
Typically, algorithmID is the value of info returned by calling
B_GetAlgorithmInfo. digest points to the message digest value of
length digestLen. Typically, digest is returned by B_DigestFinal.
4.19.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.20 B_EncodeFinal
int B_EncodeFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen /* size of output data buffer */
);
B_EncodeFinal finalizes the encoding process specified by
algorithmObject, writing any remaining encoded output to partOut,
which is a buffer supplied by the caller of at least maxPartOutLen
bytes, and setting partOutLen to the number of bytes written to
partOut. algorithmObject is reset to the state it was in after the
call to B_EncodeInit, so that another encoding process may be
performed. See B_EncodeInit.
4.20.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.21 B_EncodeInit
int B_EncodeInit (
B_ALGORITHM_OBJ algorithmObject /* algorithm object */
);
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 205]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_EncodeInit initializes algorithmObject for encoding data using the
algorithm specified by a previous call to B_SetAlgorithmInfo. For
example, the AI_RFC1113Recode algorithm provides Base64 encoding and
decoding to convert binary data to and from a printable form suitable
for most email systems. Notice that there are no cryptographic keys
for encoding or decoding.
B_EncodeInit only needs to be called once to set up a Encode
algorithm. The B_EncodeUpdate routine can be called multiple times to
process blocks of data, and B_EncodeFinal is called once to process
the last block which includes adding any trailing pad bytes. After
B_EncodeFinal is called, B_EncodeUpdate can be called to start
decoding another sequence of blocks. There is no need to call
B_EncodeInit again.
4.21.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.22 B_EncodeUpdate
int B_EncodeUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
unsigned char *partIn, /* input data */
unsigned int partInLen /* length of input data */
);
B_EncodeUpdate updates the encoding process specified by
algorithmObject with partInLen bytes from partIn, writing the encoded
output to partOut, which is a buffer supplied by the caller of at
least maxPartOutLen bytes, and setting partOutLen to the number of
bytes written to partOut. B_EncodeUpdate may be called zero or more
times to supply the data by parts. See B_EncodeInit.
4.22.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.23 B_EncryptFinal
int B_EncryptFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 206]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_EncryptFinal finalizes the encrypting process specified by
algorithmObject, writing any remaining encrypted output to partOut,
which is a buffer supplied by the caller of at least maxPartOutLen
bytes, and setting partOutLen to the number of bytes written to
partOut. The algorithm object for supplying random numbers is
randomAlgorithm; it may be (B_ALGORITHM_OBJ)NULL_PTR for encrypting
algorithms that do not need random numbers. The surrender context for
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. algorithmObject is reset to the state it was in
after the call to B_EncryptInit, so that another encrypting process
may be performed. See B_EncryptInit.
4.23.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.24 B_EncryptInit
int B_EncryptInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_EncryptInit initializes algorithmObject for encrypting data using
the algorithm specified by a previous call to B_SetAlgorithmInfo. The
key object for supplying the key information is keyObject. The
chooser for selecting the algorithm method is algorithmChooser. The
surrender context for processing and canceling during lengthy
operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
B_EncryptInit only needs to be called once to set up a key. The
B_EncryptUpdate routine can be called multiple times to process
blocks of data, and B_EncryptFinal is called once to process the last
block, which includes adding the trailing pad bytes.
After B_EncryptFinal is called, B_EncryptUpdate can be called to
start processing another sequence of blocks. If a different CBC
Initialization Vector (IVs) is used with each sequence of blocks,
B_SetAlgorithmInfo can be called with AI_CBC_IV8 to set the new IV
before calling B_EncryptUpdate.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 207]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
There is no need to call B_EncryptInit again with the same key.
4.24.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.25 B_EncryptUpdate
int B_EncryptUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partOut, /* output data buffer */
unsigned int *partOutLen, /* length of output data */
unsigned int maxPartOutLen, /* size of output data buffer */
unsigned char *partIn, /* input data */
unsigned int partInLen, /* length of input data */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_EncryptUpdate updates the encrypting process specified by
algorithmObject with partInLen bytes from partIn, writing the
encrypted output to partOut, which is a buffer supplied by the caller
of at least maxPartOutLen bytes, and setting partOutLen to the number
of bytes written to partOut. The algorithm object for supplying
random numbers is randomAlgorithm; it may be
(B_ALGORITHM_OBJ)NULL_PTR for encrypting algorithms that do not need
random numbers. The surrender context for processing and canceling
during lengthy operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it. B_EncryptUpdate
may be called zero or more times to supply the data by parts.
4.25.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.26 B_FreeSessionChooser
int B_FreeSessionChooser (
B_ALGORITHM_CHOOSER *sessionChooser, /* Address of runtime chooser */
/* dynamically bound to available */
/* hardware-based methods */
unsigned char ***oemTagList /* Address of list of OEM hardware */
/* method tags */
);
[Hardware Function] B_FreeSessionChooser frees the memory allocated
in the process of creating sessionChooser and oemTagList. Whenever a
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 208]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
non-null information pointer from the extended AM is encountered, its
corresponding Final function is called to destroy it.
4.26.1 Return Value
0 successful
nonzero unsuccessful, allocation error
4.27 B_GenerateInit
int B_GenerateInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_GenerateInit initializes algorithmObject using the algorithm
specified by a previous call to B_SetAlgorithmInfo. The chooser for
selecting the algorithm method is algorithmChooser. The surrender
context for processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it.
This routine is used to initialize several of the toolkit's parameter
generation algorithms like B_GenerateKeypair or B_GenerateParameters.
However, B_RandomInit is used to initialize the generator for
B_GenerateRandomBytes.
4.27.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.28 B_GenerateKeypair
int B_GenerateKeypair (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ publicKey, /* new public key */
B_KEY_OBJ privateKey, /* new private key */
B_ALGORITHM_OBJ randomAlgorithm, /* random algorithm */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_GenerateKeypair uses algorithmObject to generate a keypair, setting
publicKey and privateKey to the result. The algorithm object for
supplying random numbers is randomAlgorithm. The surrender context
for processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. algorithmObject is reset to the state it was in
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 209]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
after the call to B_GenerateInit, so that another keypair generation
may be performed. See B_GenerateInit.
4.28.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.29 B_GenerateParameters
int B_GenerateParameters (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_ALGORITHM_OBJ resultAlgorithmObject, /* result alg obj */
B_ALGORITHM_OBJ randomAlgorithmObject, /* random alg */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_GenerateParameters uses algorithmObject to generate algorithm
parameters, setting resultAlgorithmObject to the result. The
application may then use B_GetAlgorithmInfo to get the new parameters
from resultAlgorithmObject. The algorithm object for supplying random
numbers is randomAlgorithmObject. The surrender context for
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. algorithmObject is reset to the state it was in
after the call to B_GenerateInit, so that another parameter
generation may be performed. See B_GenerateInit.
4.29.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.30 B_GenerateRandomBytes
int B_GenerateRandomBytes (
B_ALGORITHM_OBJ randomAlgorithm, /* random algorithm */
unsigned char *output, /* buffer for output bytes */
unsigned int outputLen, /* number of bytes to output */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_GenerateRandomBytes generates outputLen pseudo-random bytes from
randomAlgorithm, storing the result in output. The randomAlgorithm
must have been seeded. The surrender context for processing and
canceling during lengthy operations is surrenderContext; if its value
is (A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it. See
B_RandomInit.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 210]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.30.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.31 B_GetAlgorithmInfo
int B_GetAlgorithmInfo (
POINTER *info, /* algorithm information */
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_INFO_TYPE infoType /* type of algorithm information */
);
B_GetAlgorithmInfo gets the information held by algorithmObject in
the format specified by infoType, storing the result in info. The
value of infoType is one of the algorithm info types with an
AI_ prefix listed in Section 2. The format of the information
returned by B_GetAlgorithmInfo is the same as the format supplied
to B_SetAlgorithmInfo.
This routine can be used to convert between external representations
of information. For example, an algorithm can be set up to perform
encryption using AI_MD2WithDES_CBCPad, and later the BER
representation of that algorithm can be computed by calling
B_GetAlgorithmInfo with AI_MD2WithDES_CBCPadBER. These external
representations of algorithm identifiers are used in RSA's PKCS
standards and other industry cryptographic standards.
4.31.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.32 B_GetExtendedErrorInfo
void B_GetExtendedErrorInfo (
B_ALGORITHM_OBJ algorithmObj, /* algorithm object */
ITEM *errorDataItem, /* returns pointer to error data */
/* and length of data */
POINTER *AM /* Set to point at method table */
);
[Hardware Function] B_GetExtendedErrorInfo sets errorDataItem->data
to point at the error data, and errorDataItem->len to the length in
bytes of the error data. AM is set to the address of the algorithm
method that originated the error if any.
4.32.1 Notes
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 211]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
A null extended error is indicated by a length of zero. The error
data may in reality be a data structure that includes pointers to
allocated memory. These allocations are cleaned up using an error
destruction routine assigned during the creation of the extended
error data.
4.32.2 Return Value
There is no return value.
4.33 B_GetKeyExtendedErrorInfo
void B_GetKeyExtendedErrorInfo (
B_KEY_OBJ keyObject, /* key object */
ITEM *errorDataItem, /* returns pointer to error */
data and length of data */
POINTER *AM; /* set to point at method table */
);
[Hardware Function] B_GetKeyExtendedErrorInfo sets
errorDataItem->data to point at the error data, and
errorDataItem->len to the length in bytes of the error data. AM is
optionally set by the hardware manufacturer; consult the
documentation supplied by your hardware vendor for more information.
4.33.1 Notes
A null extended error is indicated by a length of zero. The error
data may in reality be a data structure that includes pointers to
allocated memory. These allocations are cleaned up using an error
destruction routine assigned during the creation of the extended
error data.
4.33.2 Return Value
There is no return value.
4.34 B_GetKeyInfo
int B_GetKeyInfo (
POINTER *info, /* key information */
B_KEY_OBJ keyObject, /* key object */
B_INFO_TYPE infoType /* type of key information */
);
B_GetKeyInfo gets the information held by keyObject in the format
specified by infoType, storing the result in info. The value of
infoType is one of the key info types with a KI_ prefix listed in
Section 3. The format of the information returned by B_GetKeyInfo is
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 212]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
not always identical to the format supplied to B_SetKeyInfo because
B_SetKeyInfo may canonicalize the information before it stores it in
the key object. For example, KI_DES8 sets the DES parity before
storing, KI_RSAPublicBER converts a BER encoding to DER, and
KI_RSAPublic strips off leading zeros from the modulus and exponent
integers.
4.34.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.35 B_IntegerBits
unsigned int B_IntegerBits (
unsigned char *integer, /* canonical integer */
unsigned int integerLen /* length in bytes */
);
B_IntegerBits returns the number of significant bits in an
arbitrary-length integer, where integer points to an unsigned byte
array, most significant byte first and integerLen gives its length.
Leading zeroes are ignored. The integer is considered unsigned; that
is, the most-significant bit is counted and is not considered a sign
bit. If integerLen is zero, integer is ignored and B_IntegerBits
returns zero. A typical application uses B_IntegerBits to determine
the key size in bits of an RSA key by passing in the modulus.
This routine can be used to examine the value of a large integer such
as the ones returned by B_GetKeyInfo for KI's like KI_RSAPublic.
4.35.1 Return value
number of significant bits in integer
4.36 B_KeyAgreeInit
int B_KeyAgreeInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_KeyAgreeInit initializes algorithmObject for performing key
agreement using the algorithm specified by a previous call to
B_SetAlgorithmInfo. The chooser for selecting the algorithm method is
algorithmChooser. The key object for supplying the key information is
keyObject; it should be (B_KEY_OBJ)NULL_PTR for key agreement
algorithms that do not need an input key. The surrender context for
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 213]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it.
This routine can be used for Diffie-Hellman key agreement. First
B_KeyAgreeInit is called to setup the algorithm, then each party
calls B_KeyAgreePhase1 to generate the value that is then sent to the
other party. Each party then passes the received value to
B_KeyAgreePhase2, which computes the agreed upon key. If several key
agreements are done using the same algorithm, there is no need to
call B_KeyAgreeInit again.
4.36.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.37 B_KeyAgreePhase1
int B_KeyAgreePhase1 (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *output, /* output data buffer */
unsigned int *outputLen, /* length of output data */
unsigned int maxOutputLen, /* size of output data buffer */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_KeyAgreePhase1 uses algorithmObject to generate the initial value
for the other party, writing it to output, which is a buffer supplied
by the caller of at least maxOutputLen bytes, and setting outputLen
to the number of bytes written to output. The algorithm object for
supplying random numbers is randomAlgorithm. The surrender context
for processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. See B_KeyAgreeInit.
4.37.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.38 B_KeyAgreePhase2
int B_KeyAgreePhase2 (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *output, /* output data buffer */
unsigned int *outputLen, /* length of output data */
unsigned int maxOutputLen, /* size of output data buffer */
unsigned char *input, /* input data */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 214]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int inputLen, /* length of input data */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_KeyAgreePhase2 performs a round of key agreement as specified by
algorithmObject, receiving inputLen bytes from input, which is the
other party's intermediate value. B_KeyAgreePhase2 writes the output
to output, which is a buffer supplied by the caller of at least
maxOutputLen bytes, and sets outputLen to the number of bytes written
to output. If input is the other party's final intermediate value,
output is the agreed-upon key; otherwise, output is a new
intermediate value to send to the other party. The surrender context
for processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. See B_KeyAgreeInit.
B_KeyAgreePhase2 may be called one or more times to process
intermediate values, depending on how many other parties are involved
in the key agreement. For an algorithm like Diffie-Hellman,
B_KeyAgreePhase2 is called once.
4.38.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.39 B_RandomInit
int B_RandomInit (
B_ALGORITHM_OBJ randomAlgorithm, /* random algorithm object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_RandomInit initializes randomAlgorithm for generating random bytes
using the algorithm specified by a previous call to
B_SetAlgorithmInfo. randomAlgorithm is ready to generate bytes after
the call to B_RandomInit. However, it is necessary to mix in random
seed values with B_RandomUpdate. Otherwise, without seed values, the
bytes generated by the algorithm follow a default unseeded byte
sequence. The chooser for selecting the algorithm method is
algorithmChooser. The surrender context for processing and canceling
during lengthy operations is surrenderContext; if its value is
(A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
B_RandomInit is called once to create the generator, then
B_RandomUpdate is called one or more times to add "seed" bytes
(values that are hard for an attacker to predict) to the generator.
After enough seed is added, say at least 128 bytes, then
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 215]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_GenerateRandomBytes can be called one or more times to generate
blocks of pseudo-random data. If B_RandomUpdate is only called once
before B_GenerateRandomBytes, then the BSAFE 2 algorithms will be
used. Two or more calls to B_RandomUpdate will cause the improved
BSAFE 3 algorithms to be used. It is also OK to call B_RandomUpdate
after calling B_GenerateRandomBytes in order to add more hard to
predict values to the generator. There is no need to call
B_RandomInit again.
4.39.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.40 B_RandomUpdate
int B_RandomUpdate (
B_ALGORITHM_OBJ randomAlgorithm, /* random algorithm */
unsigned char *input, /* block values to mix in */
unsigned int inputLen, /* length of input block */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_RandomUpdate mixes inputLen bytes from input into randomAlgorithm.
The surrender context for processing and canceling during lengthy
operations is surrenderContext; if its value is (A_SURRENDER_CTX
*)NULL_PTR, BSAFE does not use it. See B_RandomInit.
4.40.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.41 B_SetAlgorithmInfo
int B_SetAlgorithmInfo (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_INFO_TYPE infoType, /* type of algorithm information */
POINTER info /* algorithm information */
);
B_SetAlgorithmInfo sets the parameters of algorithmObject to the
information pointed to by info. The type of algorithm and the format
of the parameters is specified by infoType, which is one of the
algorithm info types with an AI_ prefix listed in Section 2. A
separate copy of the information supplied by info is allocated inside
the algorithm object so that info may be changed after the call to
B_SetAlgorithmInfo. B_SetAlgorithmInfo returns
BE_WRONG_ALGORITHM_INFO if the algorithm type encoded in info is not
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 216]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
the type expected by infoType.
Once an algorithm object has been set, it should not be reset, that
is, do not call B_SetAlgorithmInfo twice on a single created
algorithm object. Either create a new algorithm object or destroy an
existing one and create it again.
4.41.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.42 B_SetKeyInfo
int B_SetKeyInfo (
B_KEY_OBJ keyObject, /* key object */
B_INFO_TYPE infoType, /* type of key information */
POINTER info /* key information */
);
B_SetKeyInfo sets the value of keyObject to the information pointed
to by info. The format of the information is specified by infoType,
which is one of the key info types with a KI_ prefix listed in
Section 3. Also, some of the AI algorithm info types listed in
Section 2 specify the key info type that should be used to set the
key object needed by the algorithm. A separate copy of the
information supplied by info is allocated inside the key object so
that info may be changed after the call to B_SetKeyInfo.
B_SetKeyInfo returns BE_WRONG_KEY_INFO if the key type encoded in
info is not the type expected by infoType. Once a key object has been
set, it should not be reset, that is, do not call B_SetKeyInfo twice
on a single created key object. Either create a new key object or
destroy an existing one and create it again.
4.42.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.43 B_SignFinal
int B_SignFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *signature, /* signature output buffer */
unsigned int *signatureLen, /* length of signature output */
unsigned int maxSignatureLen, /* size of output buffer */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 217]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
B_SignFinal finalizes the digesting process for algorithmObject and
computes the digital signature, writing the signature to signature,
which is a buffer supplied by the caller of at least maxSignatureLen
bytes, and sets signatureLen to the length of the signature. The
algorithm object for supplying random numbers is randomAlgorithm; it
may be (B_ALGORITHM_OBJ)NULL_PTR for signature algorithms that do not
need random numbers. The surrender context for processing and
canceling during lengthy operations is surrenderContext; if its value
is (A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it.
algorithmObject is reset to the state it was in after the call to
B_SignInit, so that another signing process may be performed.
See B_SignInit.
4.43.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.44 B_SignInit
int B_SignInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_SignInit initializes algorithmObject for computing a digital
signature using the algorithm specified by a previous call to
B_SetAlgorithmInfo. The chooser for selecting the algorithm method is
algorithmChooser. The key object for supplying the key information is
keyObject, which is typically a private key. The surrender context
for processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it.
B_SignInit only needs to be called once to set up a signature
algorithm. The B_SignUpdate routine can be called multiple times to
process blocks of data, and B_SignFinal is called once to process the
last block which includes producing the result. After B_SignFinal is
called, B_SignUpdate can be called to start signing another sequence
of blocks. There is no need to call B_SignInit again.
4.44.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 218]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
4.45 B_SignUpdate
int B_SignUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partIn, /* input data */
unsigned int partInLen, /* length of input data */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_SignUpdate updates the digesting process for algorithmObject with
partInLen bytes from partIn. The surrender context for processing and
canceling during lengthy operations is surrenderContext; if its value
is (A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it. B_SignUpdate
may be called zero or more times to supply the data by parts. See
B_SignInit.
4.45.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.46 B_SymmetricKeyGenerate
int B_SymmetricKeyGenerate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ symmetricKey, /* new symmetric key */
B_ALGORITHM_OBJ randomObject, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
[Hardware Function] Creates a symmetric key in accordance with data
specified during the B_SetAlgorithmInfo step. If hardware is present,
the key information is stored in a KI_TOKEN_INFO structure. If no
hardware is present, the key information is stored in
KI_EXTENDED_TOKEN_INFO format, which extends the KI_Token base type.
4.46.1 Return Value
0 successful
nonzero error
4.47 B_SymmetricKeyGenerateInit
int B_SymmetricKeyGenerateInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_ALGORITHM_CHOOSER algorithmChooser, /* algorithm chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 219]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Initializes key generation object.
4.47.1 Return Value
0 successful
nonzero error
4.48 B_VerifyFinal
int B_VerifyFinal (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *signature, /* signature to verify */
unsigned int signatureLen, /* length of signature */
B_ALGORITHM_OBJ randomAlgorithm, /* random byte source */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_VerifyFinal finalizes the digesting process for algorithmObject and
verifies the digital signature supplied by signature of signatureLen
bytes. The algorithm object for supplying random numbers is
randomAlgorithm; it may be (B_ALGORITHM_OBJ)NULL_PTR for signature
algorithms that do not need random numbers. The surrender context for
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
does not use it. algorithmObject is reset to the state it was in
after the call to B_VerifyInit, so that another verifying process may
be performed. See B_VerifyInit.
4.48.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.49 B_VerifyInit
int B_VerifyInit (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
B_KEY_OBJ keyObject, /* key object */
B_ALGORITHM_CHOOSER algorithmChooser, /* alg chooser */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);tm
B_VerifyInit initializes algorithmObject for verifying a digital
signature using the algorithm specified by a previous call to
B_SetAlgorithmInfo. The chooser for selecting the algorithm method is
algorithmChooser. The key object for supplying the key information is
keyObject, which is typically a public key. The surrender context for
processing and canceling during lengthy operations is
surrenderContext; if its value is (A_SURRENDER_CTX *)NULL_PTR, BSAFE
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 220]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
does not use it.
B_VerifyInit only needs to be called once to set up a verification
algorithm. The B_VerifyUpdate routine can be called multiple times to
process blocks of data, and B_VerifyFinal is called once to process
the last block which includes checking the computed signature against
the expected signature that is passed to B_VerifyFinal. After
B_VerifyFinal is called, B_VerifyUpdate can be called to start
verifying another sequence of blocks. There is no need to call
B_VerifyInit again.
4.49.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.50 B_VerifyUpdate
int B_VerifyUpdate (
B_ALGORITHM_OBJ algorithmObject, /* algorithm object */
unsigned char *partIn, /* input data */
unsigned int partInLen, /* length of input data */
A_SURRENDER_CTX *surrenderContext /* surrender context */
);
B_VerifyUpdate updates the digesting process for algorithmObject with
partInLen bytes from partIn. The surrender context for processing and
canceling during lengthy operations is surrenderContext; if its value
is (A_SURRENDER_CTX *)NULL_PTR, BSAFE does not use it. B_VerifyUpdate
may be called zero or more times to supply the data by parts. See
B_VerifyInit.
4.50.1 Return value
0 success
non-zero see Appendix A, "BSAFE Error Types"
4.51 T_free
void T_free (
POINTER block /* block address */
);
T_free deallocates block. The value of block is allocated with
T_malloc or reallocated with T_realloc, or it is NULL_PTR. If block
is NULL_PTR, T_free performs no operation.
4.51.1 Return value
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 221]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
There is no return value.
4.52 T_malloc
POINTER T_malloc (
unsigned int len /* length of block */
);
T_malloc allocates a memory block of at least len bytes. The value of
len can be zero, in which case T_malloc returns a valid non-NULL_PTR
value.
4.52.1 Return value
address of block success
NULL_PTR error
4.53 T_memcmp
int T_memcmp (
POINTER firstBlock, /* first block */
POINTER secondBlock, /* second block */
unsigned int len /* length of blocks */
);
T_memcmp compares the first len bytes of firstBlock and secondBlock.
The value of len can be zero, in which case firstBlock and
secondBlock are undefined and T_memcmp returns zero. T_memcmp
compares the blocks by scanning the blocks from lowest address to
highest until a difference is found. The smaller-valued block is the
one with the smaller-valued byte at the point of difference. If no
difference is found, then the blocks are equal.
4.53.1 Return value
< 0 firstBlock is smaller
0 blocks are equal
> 0 firstBlock is larger
4.54 T_memcpy
void T_memcpy(
POINTER output, /* output block */
POINTER input, /* input block */
unsigned int len /* length of blocks */
);
T_memcpy copies the first len bytes of input to output. The value of
len can be zero, in which case output and input are undefined. The
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 222]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
blocks do not overlap.
4.54.1 Return value
There is no return value.
4.55 T_memmove
void T_memmove (
POINTER output, /* output block */
POINTER input, /* input block */
unsigned int len /* length of blocks */
);
T_memmove copies the first len bytes of input to output. The blocks
can overlap. The value of len can be zero, in which case output and
input are undefined.
4.55.1 Return value
There is no return value.
4.56 T_memset
void T_memset (
POINTER output, /* output block */
int value, /* value */
unsigned int len /* length of block */
);
T_memset sets the first len bytes of output to value. If the value of
len is zero, output is undefined.
4.56.1 Return value
There is no return value.
4.57 T_realloc
POINTER T_realloc (
POINTER block, /* block address */
unsigned int len /* new length */
);
T_realloc changes the size of block to len. It allocates a memory
block of length len bytes, copies as many bytes as possible from the
old memory block to the new one, and frees the old block. The address
of the new block can be different from the address of the old block.
The value of len can be zero, in which case T_realloc returns a valid
non-NULL_PTR value. On error, block is freed. Note that many
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 223]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
implementations of realloc do not free the block on error, so
T_realloc must take care to do this. The value of block is allocated
with T_malloc or reallocated with T_realloc, or it is NULL_PTR. If
block is NULL_PTR, T_realloc performs as T_malloc.
4.57.1 Return value
address of new block success
NULL_PTR error
5. Security Considerations
5.1 Handling Private Keys
In public-key cryptography, only the owner of a private key can
create a digital signature or open digital envelopes. However, if
someone other than the owner is able to obtain the private key, the
security fails. To ensure that no one other than the owner has access
to a private key, it should be stored encrypted, generally with a
password-based encryption method. An application will decrypt the
private key when it is needed. Always overwrite the memory that held
a private key with zeroes or random bytes immediately after the key
has performed its function.
Operating systems will frequently use the hard disk space as virtual
memory and so an unencrypted private key may, through no intention of
a user, end up on a hard disk. Hence, for key buffers, an application
should use the operating system's mechanisms that ensure allocation
of core memory, and not virtual memory.
It is a good idea to generate new public/private key pairs every so
often to thwart long-term factoring attacks. Material encrypted using
the old key pair should be re-encrypted with the new. However, an
application may not have access to all material protected by an old
key pair, so it may be necessary to retain old key pairs in a secure
environment.
5.2 Temporary Buffers
Even though a temporary buffer may not contain a private key, it
still may hold sensitive data, such as a message to be encrypted or a
symmetric key. Such temporary buffers require the same security as
private-key buffers. After using the data, overwrite the buffer with
zeroes or random bytes. Make sure the operating system uses core
memory and not hard disk virtual memory.
5.3 Pseudo-Random Numbers and Seed Generation
BSAFE uses pseudo-random number algorithms for generating both
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 224]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
symmetric keys and public/private key pairs. The random number
generation algorithms are the same as the message digest algorithms,
and are verified to have very high degree of randomness.
Any method that is employed to generate random values begins with a
random seed. The security issue then becomes one of making sure that
an attacker cannot determine the seed. Generally, any random number
generator will produce pseudo-random numbers, given any seed.
Therefore, to generate random number, you do not need to start with a
seed that is itself random. However, the seed should be
"unrepeatable." That is, no one should be able to apply some sort of
algorithm which can "guess" the seed in a reasonable amount of time.
For instance, suppose that a message was encrypted using RC2 with 80
effective key bits from 10 bytes of key data, but that the key data
was generated using an MD5 random byte generating algorithm with a
4-byte seed. An attacker could try every possible 10-byte key
combination to crack the message, or could try every 4-byte seed
combination to generate 10 bytes of key data. Further, suppose that
4-byte seed was the time of day. Now the attacker has an even smaller
range of possible seeds to test before finding the right one.
The seed should contain at least as many unrepeatable bits as the
key. If the seed is based on a user's typing a series of letters and
characters on the keyboard, then an attacker can predict two or three
of the bits in each seed byte. Bit 7, for instance, will always be 0.
Furthermore, many of the keystrokes can be predicted: they will
probably be lower-case letters that alternate between the left and
right hand. Analysis of this issue has determined that there is only
one bit of entropy from each keystroke (think of the term "entropy"
as "unrepeatability"). When using keystrokes, use at least one for
each bit of key size.
There are other schemes for finding seed bytes, including tracking
mouse movements, timing keystrokes, "listening" to hardware noise, or
capturing machine state information. Many schemes will provide more
than one bit of entropy per byte of seed; however, it is an
easy-to-remember rule of thumb to use as many bytes of seed data as
bits of key.
Whatever the scheme, it may seem unusual to expend more effort to
produce a seed than it will take to produce the random key data
itself. Why not simply use the seed data in the key? The strength of
cryptography relies on key data that is random or pseudo-random. If
an attacker knows that the key data is not random, cracking the
cipher becomes easier. The seed will almost certainly not be random.
The eavesdropper may not be able to repeat the seed gathering process
exactly, but non-random key data leaves a cipher algorithm as a whole
open to various attacks. Hence, use a large unrepeatable seed to
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 225]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
generate pseudo-random data.
5.4 Choosing Passwords
In almost any security application, users are required to have
passwords that indicate authorized access to the system. Often, when
given a choice, users choose the same password for various
applications. For instance, they may use their login password to
encrypt a private key. Many times, users will choose passwords an
attacker can easily deduce. Therefore, it is a good idea for
developers to build good password protocols into their applications.
The following are a list of possible guidelines in choosing
passwords.
Note: Enforce a minimum password length, generally eight characters.
Note: Inform users to avoid "easy to guess" passwords, such as common
names or birthday dates.
Note: Check an entered password against a dictionary.
Note: Require a combination of numeric, special, and upper- and
lower-case alphabetic characters.
Note: Include support for password expiration dates to limit the
available searching time an attacker has to break into the system.
5.5 Initialization Vectors and Salts
Although IVs and salts are not secret information, it is still a good
idea to use random values. If a salt is not random, an attacker will
have much fewer precomputations to make in generating keys from
possible password/salt combinations.
An IV should also be used for only one message. Using the same IV
with the same key on two separate messages may provide an attacker
with useful information.
5.6 DES Weak Keys
Researchers over the years have found that some DES keys are more
susceptible to attack than others. Some of these keys are known as
"weak", others, when used in pairs, as "semi-weak". Using a weak key
or a semi-weak pair may not necessarily pose a security risk; it
could depend on the mode of DES. However, it is simply easier to
avoid these keys (listed in Table 2-3) altogether.
5.6.1 DES weak and semi-weak keys
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 226]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
0101010101010101
FEFEFEFEFEFEFEFE
1F1F1F1F1F1F1F1F
E0E0E0E0E0E0E0E0
01FE01FE01FE01FE
1FE01FE00EF10EF1
01E001E001F101F1
1FFE1FFE0EFE0EFE
011F011F010E010E
E0FEE0FEF1FEF1FE
FE01FE01FE01FE01
E01FE01FF10EF10E
E001E001F101F101
FE1FFE1FFE0EFE0E
1F011F010E010E01
FEE0FEE0FEF1FEF1
5.7 Stream Ciphers
A stream cipher (such as RC4) will create a stream of pseudo-random
bytes based on the secret key; this is known as the key stream. To
encrypt, you XOR the plaintext with the key stream, byte by byte. The
XOR operation has the property that the ciphertext XORed with the
same key stream decrypts, restoring the plaintext. This also means
that an XOR operation between the plaintext and the ciphertext will
reproduce the key stream. Hence, knowing or guessing part of the
plaintext allows an attacker to determine the corresponding part of
the key stream. This still will not enable the attacker to deduce the
entire key or any more of the key stream, but this does pose a threat
if the same key is used in two different messages.
The same key always produces the same key stream. Therefore, if two
messages use the same key, knowing part of the key stream in one
message means knowing the same part of the key stream in the second
message. An attacker can thus determine some of the plaintext in the
second message. That is why you should never use the same stream
cipher key twice.
Incidentally, this attack does not work on block ciphers. Knowledge
of part of the plaintext does not automatically grant to the attacker
knowledge of the key.
Another stream cipher attack involves a dictionary of key streams.
Suppose you had an application you wanted to export and so kept the
key size to 40 bits. An attacker could create a dictionary of the
first eight bytes of the key stream from every possible 40-bit
(5-byte) key. Then, the attacker "decrypts" the first eight bytes of
an intercepted message with each possible key stream, until one
produces a reasonable result. The key that generated the stream that
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 227]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
worked is the right one.
To thwart this attack, you can implement salting. Design the
application to use an 80-bit (10-byte) key, but send 40 bits in the
clear. That 40 bits in the clear is known as a salt. For example, in
an email application, encrypt the message using RC4 with a 10-byte
key. Then encrypt the first five bytes of the key using the
recipient's RSA public key. Now the RSA digital envelope consists of
the public-key-encrypted five secret bytes, five salt bytes sent in
the clear and the RC4-encrypted message. In this way the attacker's
dictionary is rendered useless. That dictionary is valid for 40-bit
keys, but the message used an 80-bit key. Still, only 40 bits are
kept secret to comply with export regulations. A dictionary of 80-bit
key streams is not feasible - it would require 2^80 entries. That is
about 1.2 * 10^24, or 1.2 times one trillion times one trillion.
5.8 Timing Attacks and Blinding
If the time it takes to execute a cryptographic operation varies
based on the input parameters, then in theory, an attacker with
access to accurate timings can determine unknown values. This is the
case for RSA, Diffie-Hellman, and DSA operations. For instance, in an
RSA signing operation, purportedly an attacker who knows the message
being signed and exactly how long it takes to create the digital
signature can determine the signer's RSA private key.
Currently, there is no known successful implementation of such a
procedure. Proposed algorithms under scrutiny either require several
absolutely exact timings or thousands of inexact (but still accurate
to the millisecond) timings to succeed. However, there are two simple
ways to guard against this attack. One is to "equalize" private key
operations, by padding shorter transactions with a few extra
milliseconds to make sure that all times are the same. The second
method is known as blinding.
For a timing attack to succeed, the eavesdropper must know that the
input being processed is only altered before the operation is
performed and that the true answer is recovered after the operation
by reversing the alteration procedure.
For example, in an RSA signature operation, the input is the
BER-encoding of the digest of the data to sign and some pad bytes. To
blind the attacker, that input is modular multiplied by a secret
random number. Then the product, not the input, is modular
exponentiated. To produce the actual signature, the result is modular
multiplied by the inverse of the random number.
In mathematical terms, instead of performing the usual RSA encryption
process:
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 228]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
sig = m^d mod n
pick a random value r and compute:
m' = mr^e mod n
where e is the public exponent. Now find:
s = (m')^d mod n
Then to compute the actual signature, find:
sig = (r^-1) * s mod n
In this way, the timing attack fails because the attacker does not
know what value was exponentiated.
To see that the signature is the same in both cases, note that:
r(mr^e)^d mod n = (r^-1)(m)^d(r^e)^d
= (r)(r^ed)(m^d)
= (r^-1)(r)(m^d)
= (1)(m^d) mod n
BSAFE offers both blinding and non-blinding RSA private operations
through separate algorithm methods. It currently offers no blinding
technique in Diffie-Hellman or DSA operations.
BSAFE uses MD5 random number generation to produce the random value
r. The seed is the following digest:
MD5(p || padP || MD5(q || padQ || m))
where p and q are the two primes, padP and padQ are paddings of zeros
to make sure the length is a multiple of 64 bytes, and the symbol ||
means concatenation. An attacker will not know what r is without
knowing what the seed is, and will not know what the seed is without
knowing what p and q are. An attacker who knows p and q is not going
to implement a timing attack to determine the private key, because
knowledge of p and q is equivalent to knowledge of the private key
already.
5.9 Choosing Key Sizes
In cryptography, security is measured in key size: the bigger the
key, the greater the security. Key size, in turn, is measured in
bits. However, that bit number might not describe the entire key.
For instance, a DES key is 56 bits. However, that size refers to its
cryptographic size, not its "physical" size. To build a DES key, you
need 64 bits, but because eight of those bits are "parity bits," that
is, bits that are known, out of the 64, you really only get 56 secret
bits. Hence, a DES key, while consisting of 64 bits of data, is only
56 cryptographic bits large.
An RSA key pair measurement describes the modulus length. When
cryptographers talk about a "768-bit RSA key pair," what they really
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 229]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
mean is that the modulus is 768 bits long. The security of an RSA key
pair is tied up in how big the modulus is; hence, the measurement
used is the bit size of the modulus. The actual keys themselves will
contain more information than the modulus, so the "physical" size
will be much larger.
In choosing a key size, if larger keys offer greater security, why
not simply always choose the largest possible key? Larger RSA,
Diffie-Hellman, DSA, and elliptic curve keys can slow down
cryptographic operations. In addition, there are restrictions on key
size for applications seeking export.
For RC2, RC4, and RC5, larger keys generally do not significantly
degrade performance. However, larger keys do require more management.
Table 2-4 gives a summary of the recommended key sizes for the
algorithms supported in BSAFE. These recommendations were current at
the time this document was published. Please note, however, that such
recommendations are always provisional and can be affected by changes
in the cryptographic state of the art.
5.9.1 Summary of Recommended Key Sizes
ALGORITHM USER KEY ORGANIZATIONAL ROOT KEY
OR LONG-TERM KEY
Diffie-Hellman 768-bit prime 1024-bit prime 2048-bit prime
DSA 768-bit prime 1024-bit prime 2048-bit prime
ECAES 160-170-bit modulus Not recommended
at this time
EC Diffie-Hellman 160-170-bit modulus Not recommended
at this time
ECDSA 160-170-bit modulus Not recommended
at this time
RC2 ----------8-128 effective key bits----------
RC4 ----------8-128 effective key bits----------
RC5 8-128 effective key bits with
16 rounds for 32-bit word or 20 rounds for 64-bit word
RSA 768-bit modulus 1024-bit modulus 2048-bit modulus
5.9.2 RSA Keys
The security of the RSA algorithm is based on the difficulty of
factoring large integers. Therefore, the choice for the key size
depends on the efficiency of integer-factoring algorithms. Because
users will probably want a key pair to last a few years, it is
advisable to choose a size that will not only remain secure against
current state of the art factoring, but will probably defeat improved
factoring attempts of the future. The RSA Laboratories publication,
"Frequently Asked Questions About Today's Cryptography" describes
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 230]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
current factoring capabilities.
For normal user data, RSA Data Security recommends a modulus size of
768 bits. For organization keys or for long-term applications, a
1024-bit modulus is advisable. For root keys, RSA recommends a
2048-bit modulus. This safeguards against progress in factoring
algorithms and improvements in computing power.
5.9.3 Diffie-Hellman Parameters and DSA Keys
The security of the Diffie-Hellman algorithm and DSA are both
dependent on the complexity of computing logarithms modulo a prime
number. Generally, this is equivalent to the complexity of the
factoring problem, because modern factoring algorithms generally
apply to the discrete logarithm problem. Therefore, the designer is
advised to use similar sizes for the Diffie-Hellman parameters and
DSA keys as for RSA operations: a 768-bit prime for user keys,
1024-bit prime for organizational keys and a 2048-bit prime for root
keys. Note: The Digital Signature Standard lists a maximum of 1024
bits for DSA, but the algorithm does not have an inherent limit.
BSAFE's implementation allows up to 2048-bit DSA keys.
5.9.4 RC2 Effective Key Bits
A key with 80 to 128 effective key bits is sufficient for most
applications using the RC2 algorithm. Export regulations may limit
the size to 48 effective bits. A key size of 40 bits generally
expedites the export permission.
5.9.5 RC4 Key Bits
An 80- to 128-bit key is sufficient for most applications using the
RC4 algorithm. Export regulations may limit the size to 48 bits. A
key size of 40 bits generally expedites the export permission.
5.9.6 RC5 Key Bits and Rounds
An 80- to 128-bit key is sufficient for most applications using the
RC5 algorithm. Note also that the security of the RC5 algorithm is
dependent on the number of rounds. For RC5 with a 32-bit word size,
RSA Data Security recommends at least 12 rounds for applications;
while no practical attacks are known for 12-round RC5-32, recent
cryptanalytic work suggests 16 rounds is now a more conservative
choice. For RC5 with a 64-bit word size, RSA Data Security recommends
at least 16 rounds; a conservative choice for the 64-bit version is
20 rounds. Note that the BSAFE implementation of the 64-bit word is
for evaluation purposes only.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 231]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
5.9.7 Triple DES Keys
It is possible to implement Triple DES with one, two, or three keys.
One key in EDE mode (encrypt-decrypt-encrypt) is equivalent to DES,
and is used to provide compatibility with applications that only
understand DES. There are known attacks against Triple DES using two
keys, so RSA Data Security recommends using three keys.
5.9.8 Elliptic Curve Keys
For prototyping and evaluation, RSA recommends setting the order of
the base point to be between 160 and 170 bits. Currently, RSA does
not recommend using elliptic curve cryptography for long-term
applications.
6. References Section
FIPS PUB 46-1 National Bureau of Standards. FIPS Publication
46-1: Data Encryption Standard. January 1988.
FIPS PUB 81 National Bureau of Standards. FIPS Publication
81: DES Modes of Operation. December 1980.
FIPS PUB 180-1 National Institute of Standards and Technology.
FIPS Publication 180-1: Secure Hash Standard.
May 1993.
FIPS PUB 186 National Institute of Standards and Technology.
FIPS Publication 186: Digital Signature
Standard. May 1994.
P1363 Draft D1IEEE. Standard Specifications for Public Key
Cryptography. December 1997.
RFC 1113 J. Linn. RFC 1113: Privacy Enhancement for
Internet Electronic Mail: Part I Message
Encipherment and Authentication Procedures.
August 1989.
RFC 1319 B. Kaliski. The MD2 Message-Digest Algorithm.
April 1992.
RFC 1321 R. Rivest. The MD5 Message-Digest Algorithm.
April 1992.
RFC 1423 D. Balenson. RFC 1423: Privacy Enhancement for
Internet Electronic Mail: Part III Algorithms,
Modes, and Identifiers. `February 1993.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 232]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
X.208 CCITT. Recommendation X.208: Specification of
Basic Encoding Rules for Abstract Syntax
Notation One (ASN.1). 1988.
X.209 CCITT. Recommendation X.209: Specification of
Abstract Syntax Notation One (ASN.1). 1988.
X.509 CCITT. Recommendation X.509: The Directory
Authentication Framework. 1988.
X9.31 Draft Digital signatures Using Reversible Public
Key Cryptography for the Financial Services
Industry (rDSA). December 1997.
X9.44 Draft Key management using reversible public key
cryptography for the financial services
industry. January 1998.
X9.52 Draft Triple Data Encryption Algorithm Modes of
Operation. December 1997.
X9.57 Draft ANSI. Certificate Management, N5-95,
June 15, 1995.
X9.62 Draft ANSI. The Elliptic Curve Digital Signature
Algorithm (ECDSA). August 29, 1997.
X9.63 Draft Public Key Cryptography for the Financial
Services Industry: Elliptic Curve Key Agreement
and Transport Protocols. December 1997.
[NIST91] NIST. Special Publication 500-202: Stable
Implementation Agreements for Open Systems
Interconnection Protocols. Version 5, Edition 1,
Part 12. December 1991.
S.C. Kothari. Proceedings of CRYPTO 84: Generalized Linear
Threshold Scheme. 1984.
6.1 PKCS Suite
The following references are from RSA Data Security, Inc.'s
Public-Key Cryptography Standards (PKCS) suite:
PKCS documents are available by anonymous FTP from the host
ftp.rsa.com in the files pub/pkcs/pkcs*.ps, or by sending
electronic mail to pkcs@rsa.com.
PKCS #1 RSA Data Security, Inc. PKCS #1: RSA
Encryption Standard. Version 1.5, November 1993.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 233]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
PKCS #3 RSA Data Security, Inc. PKCS #3: Diffie-Hellman
Key- Agreement Standard. Version 1.4, November
1993.
PKCS #5 RSA Data Security, Inc. PKCS #5: Password-Based
Encryption Standard. Version 1.5, November 1993.
PKCS #7 RSA Data Security, Inc. PKCS #7: Cryptographic
Message Syntax Standard. Version 1.5, November
1993.
PKCS #8 RSA Data Security, Inc. PKCS #8: Private-Key
Information Syntax Standard. Version 1.2,
November 1993.
7. Authors' Address
Bob Baldwin
RSA Data Security, Inc.
2955 Campus Drive, Suite 400
San Mateo, CA 94403-2507
Phone: +1 650-295-7600
Fax: +1 650-358-2530
EMail: baldwin@rsa.com
Anne Wilson
RSA Data Security, Inc.
2955 Campus Drive, Suite 400
San Mateo, CA 94403-2507
Phone: +1 650-295-7600
Fax: +1 650-358-2530
EMail: wilson@rsa.com
Sayuri Nishimura
RSA Data Security, Inc.
2955 Campus Drive, Suite 400
San Mateo, CA 94403-2507
Phone: +1 650-295-7600
Fax: +1 650-358-2530
EMail: sayuri@rsa.com
Michael Yurovitsky
RSA Data Security, Inc.
2955 Campus Drive, Suite 400
San Mateo, CA 94403-2507
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 234]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
Phone: +1 650-295-7600
Fax: +1 650-358-2530
EMail: myurovitsky@rsa.com
8. Appendix A BSAFE Error Types
This appendix lists the BSAFE error types.
Hex Dec Error Code Description
0x0200 512 BE_ALGORITHM_ALREADY_SET the value of the algorithm
object has already been set by
a call to B_SetAlgorithmInfo
or by an algorithm parameter
generation
0x0201 513 BE_ALGORITHM_INFO invalid format for the
algorithm information in the
algorithm object
0x0202 514 BE_ALGORITHM_NOT_INITIALIZED algorithm object has not been
initialized by a call to the
Init procedure
0x0203 515 BE_ALGORITHM_NOT_SET the algorithm object
has not been set by a call to
B_SetAlgorithmInfo
0x0204 516 BE_ALGORITHM_OBJ invalid algorithm object
0x0205 517 BE_ALG_OPERATION_UNKNOWN unknown operation for an
algorithm or algorithm info
type
0x0206 518 BE_ALLOC insufficient memory
0x0207 519 BE_CANCEL operation was cancelled by the
surrender function
0x0208 520 BE_DATA generic data error
0x0209 521 BE_EXPONENT_EVEN invalid even value for public
exponent in keypair
generation
0x020a 522 BE_EXPONENT_LEN invalid exponent length for
public exponent in keypair
generation
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 235]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
0x020b 523 BE_HARDWARE cryptographic hardware error
0x020c 524 BE_INPUT_DATA invalid encoding format for
input data
0x020d 525 BE_INPUT_LEN invalid total length for input
data
0x020e 526 BE_KEY_ALREADY_SET the value of the key object
has already been set by a call
to B_SetKeyInfo or by a key
generation
0x020f 527 BE_KEY_INFO invalid format for the key
information in the key object
0x0210 528 BE_KEY_LEN invalid key length
0x0211 529 BE_KEY_NOT_SET the key object has not been
set by a call to
B_SetKeyInfo or by a key
generation
0x0212 530 BE_KEY_OBJ invalid key object
0x0213 531 BE_KEY_OPERATION_UNKNOWN unknown operation
for a key info type
0x0214 532 BE_MEMORY_OBJ invalid internal memory object
0x0215 533 BE_MODULUS_LEN unsupported modulus length for
a key or for algorithm
parameters
0x0216 534 BE_NOT_INITIALIZED algorithm is improperly
initialized
0x0217 535 BE_NOT_SUPPORTED the algorithm chooser does not
support the type of key
information in the key object
for the specified algorithm
0x0218 536 BE_OUTPUT_LEN the maximum size or the output
buffer is too small to receive
the output
0x0219 537 BE_OVER_32K data block exceeds 32,767
bytes
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 236]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
0x021a 538 BE_RANDOM_NOT_INITIALIZED the random algorithm has not
been initialized by a call to
B_RandomInit
0x021b 539 BE_RANDOM_OBJ invalid algorithm object for
the random algorithm
0x021c 540 BE_SIGNATURE signature does not verify
0x021d 541 BE_WRONG_ALGORITHM_INFO the required algorithm
information is not in the
algorithm object
0x021e 542 BE_WRONG_KEY_INFO the required key information
is not in the key object
0x021f 543 BE_INPUT_COUNT Update called an invalid
number of times for
inputting data
0x0220 544 BE_OUTPUT_COUNT Update called an invalid
number of times for
outputting data
0x0221 545 BE_METHOD_NOT_IN_CHOOSER algorithm chooser doesn't
contain the algorithm method
for the algorithm specified by
the previous call to
B_SetAlgorithmInfo
0x0222 546 BE_KEY_WEAK the key data supplied would
generate a known weak key
0x0223 547 BE_EXPONENT_ONE the value of the public
exponent can not be 1
0x0224 548 BE_BAD_POINTER invalid pointer
0x0225 549 BE_BAD_PASSPHRASE invalid password
9. Appendix B Algorithm Details
This appendix presents additional details of some of the algorithms.
9.1 AI_MAC
This algorithm implements a simple non-linear feedback shift register
that can be used to construct a variable-length message
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 237]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
authentication codes (MAC's). The length of the desired MAC, which is
set by calling B_SetAlgorithmInfo with the macLen parameter,
determines the number of bytes in the shift register. For example, a
keyed MAC can be implemented using AI_MAC by first passing the key to
B_DigestUpdate, then the message, and finally a block of zeros at
least as long as the macLen.
AI_MAC is a fast algorithm with modest security properties. In most
cases a stronger algorithm such as AI_HMAC, AI_SHA1, or AI_MD5 should
be used.
The algorithm is based on a fixed 8-bit substitution table called
MAC_PI_SUBST that implements a non-linear mapping from 8-bits to
8-bits. The name of this table reflects that it was created using
digits of PI. The table can be defined in the C programming language
by the following statement:
unsigned char MAC_PI_SUBST[256] = {
189, 86,234,242,162,241,172, 42,
176,147,209,156, 27, 51,253,208,
48, 4,182,220,125,223, 50, 75,
247,203, 69,155, 49,187, 33, 90,
65,159,225,217, 74, 77,158,218,
160,104, 44,195, 39, 95,128, 54,
62,238,251,149, 26,254,206,168,
52,169, 19,240,166, 63,216, 12,
120, 36,175, 35, 82,193,103, 23,
245,102,144,231,232, 7,184, 96,
72,230, 30, 83,243,146,164,114,
140, 8, 21,110,134, 0,132,250,
244,127,138, 66, 25,246,219,205,
20,141, 80, 18,186, 60, 6, 78,
236,179, 53, 17,161,136,142,43,
148,153,183,113,116,211,228,191,
58,222,150, 14,188, 10,237,119,
252, 55,107, 3,121,137, 98,198,
215,192,210,124,106,139, 34,163,
91, 5, 93, 2,117,213, 97,227,
24,143, 85, 81,173, 31, 11, 94,
133,229,194, 87, 99,202, 61,108,
180,197,204,112,178,145, 89, 13,
71, 32,200, 79, 88,224, 1,226,
22, 56,196,111, 59, 15,101, 70,
190,126, 45,123,130,249, 64,181,
29,115,248,235, 38,199,135,151,
37, 84,177, 40,170,152,157,165,
100,109,122,212, 16,129, 68,239,
73,214,174, 46,221,118, 92, 47,
167, 28,201, 9,105,154,131,207,
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 238]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
41, 57,185,233, 76,255, 67,171
};
The algorithm represents the shift register using an array of bytes
called MAC, which contains macLen bytes. The MAC array is initially
zeroed. Conceptually the bytes shift from left to right in the array.
The new left byte of MAC is computed as the exclusive-or of the next
input byte passed to B_DigestUpdate and the MAC_PI_SUBST substitution
applied to the exclusive-or of the two rightmost bytes of the MAC
array. All the bytes are then shifted right. Of course, pointers can
be used to avoid actually shifting the bytes of MAC.
Some test vectors are listed below.
MacLen = 4
HexInputBytes =
ba62e4d9f590cd4e89e66658f3de540f
d6a411c711e31d60c8fb7d135bf70fc4
8fcbc03a454b7b87bc191e6984287e20
4c852b61392b3a03a06804a94c41a5a9
HexOuputBytes = 25d9f281
MacLen = 4
HexInputBytes =
8168572d190eb3a86b4ca25e02782ba2
2ceb5c1ede921446f01e8bc49321e4d0
319318094d331c13f9933bad0bac4e82
0676a9de2a4af7c5190a92f47b3b21bb
HexOuputBytes = fe9f43a5
MacLen = 8
HexInputBytes =
9058e3e6bba94527ceef6189f1091ada
cbc8ab4e5787febbb1f7a44f0f05f96e
e37b205dd2625d4b4ca9d41aadae3619
b51ae8e10ed4f62499ebf9de5ac48e86
HexOuputBytes = 4981df90a4c7e5cc
MacLen = 8
HexInputBytes =
aa2be83649040b6b4725eed4cde35e76
b182ed965f3db1af3bb58e115f740519
1123aca13aa97818ba1bf0234a385829
94f3668ff2cafeb0b946d71c3fb2752e
HexOuputBytes = dba728ba227bcc85
9.2 AI_RC4WithMAC
This algorithm implements a stream cipher with a simple
tamper-detection MAC based on AI_MAC. When applied to a plaintext
buffer of N bytes, it produces a ciphertext of N bytes using the same
algorithm as AI_RC4, and then it appends a MAC of macLen bytes. The
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 239]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
MAC is computed using AI_MAC by first passing the key to AI_MAC, then
the plaintext, and finally a block of macLen zero bytes. The
resulting value from AI_MAC is appended to the ciphertext. For
decryption, the MAC value is checked.
The key passed to both AI_RC4 and AI_MAC is created by appending the
salt bytes passed to B_SetAlgorithmInfo to the end of the key passed
to B_EncryptInit or B_DecryptInit. That is, for this AI, the RC4 key
depends on the salt as well as the key object passed to Init routine.
AI_MAC is a fast algorithm with modest security properties. In most
cases a stronger algorithm such as AI_HMAC, AI_SHA1, or AI_MD5 should
be used.
Some test vectors are listed below.
MacLen = 4
HexSaltBytes = 76543210
HexKey = fedcba98
HexInputBytes =
0123456789abcdeffedcba9876543210
HexOuputBytes =
dae10fb4e886c6671003cb322806393d929f6334
MacLen = 8
HexSaltBytes = 76543210
HexKey = fedcba98
HexInputBytes =
0123456789abcdeffedcba9876543210
HexOuputBytes =
dae10fb4e886c6671003cb322806393d7110b2ab11b2db55
10. Appendix C BSAFE Header Files
10.1 BSAFE.H
#ifndef _BSAFE_H_
#define _BSAFE_H_ 1
#include "bsfmacro.h"
#include "bsfplatf.h"
#include "aglobal.h"
#include "atypes.h"
#include "bexterr.h"
#define RSA_STD_ALLOC_FUNCS RSA_ENABLED
#define RSA_STD_MEM_FUNCS RSA_ENABLED
#include "stdlibrf.h"
#ifdef __cplusplus
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 240]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
extern "C" {
#endif
#define BE_ALGORITHM_ALREADY_SET 0x0200
#define BE_ALGORITHM_INFO 0x0201
#define BE_ALGORITHM_NOT_INITIALIZED 0x0202
#define BE_ALGORITHM_NOT_SET 0x0203
#define BE_ALGORITHM_OBJ 0x0204
#define BE_ALG_OPERATION_UNKNOWN 0x0205
#define BE_ALLOC 0x0206
#define BE_CANCEL 0x0207
#define BE_DATA 0x0208
#define BE_EXPONENT_EVEN 0x0209
#define BE_EXPONENT_LEN 0x020a
#define BE_HARDWARE 0x020b
#define BE_INPUT_DATA 0x020c
#define BE_INPUT_LEN 0x020d
#define BE_KEY_ALREADY_SET 0x020e
#define BE_KEY_INFO 0x020f
#define BE_KEY_LEN 0x0210
#define BE_KEY_NOT_SET 0x0211
#define BE_KEY_OBJ 0x0212
#define BE_KEY_OPERATION_UNKNOWN 0x0213
#define BE_MEMORY_OBJ 0x0214
#define BE_MODULUS_LEN 0x0215
#define BE_NOT_INITIALIZED 0x0216
#define BE_NOT_SUPPORTED 0x0217
#define BE_OUTPUT_LEN 0x0218
#define BE_OVER_32K 0x0219
#define BE_RANDOM_NOT_INITIALIZED 0x021a
#define BE_RANDOM_OBJ 0x021b
#define BE_SIGNATURE 0x021c
#define BE_WRONG_ALGORITHM_INFO 0x021d
#define BE_WRONG_KEY_INFO 0x021e
#define BE_INPUT_COUNT 0x021f
#define BE_OUTPUT_COUNT 0x0220
#define BE_METHOD_NOT_IN_CHOOSER 0x221
#define BE_KEY_WEAK 0x222
#define BE_EXPONENT_ONE 0x0223
#define BE_BAD_POINTER 0x0224
#define BE_BAD_PASSPHRASE 0x0225
#define BE_AM_DOMESTIC_ONLY 0x226
typedef POINTER B_KEY_OBJ;
typedef POINTER B_ALGORITHM_OBJ;
typedef int (RSA_CALLING_CONV *B_INFO_TYPE) PROTO_LIST ((POINTER *));
#ifndef _BUILD_LIBRARY_
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 241]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef char B_ALGORITHM_METHOD;
typedef B_ALGORITHM_METHOD **B_ALGORITHM_CHOOSER;
#endif
/* Version information.
*/
extern char * RSA_CALLING_CONV BSAFE_VERSION;
/* The data profiling object */
int RSA_CALLING_CONV B_BuildTableInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_BuildTableUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_BuildTableGetBufSize PROTO_LIST
((B_ALGORITHM_OBJ, unsigned int *));
int RSA_CALLING_CONV B_BuildTableFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
A_SURRENDER_CTX *));
/* The compression object */
int RSA_CALLING_CONV B_CompressInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_CompressUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int, unsigned int*,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_CompressFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecompressInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecompressUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int, unsigned int *,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecompressFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
A_SURRENDER_CTX *));
/* The key object.
*/
int RSA_CALLING_CONV B_CreateKeyObject PROTO_LIST ((B_KEY_OBJ *));
void RSA_CALLING_CONV B_DestroyKeyObject PROTO_LIST ((B_KEY_OBJ *));
int RSA_CALLING_CONV B_SetKeyInfo PROTO_LIST
((B_KEY_OBJ, B_INFO_TYPE, POINTER));
void RSA_CALLING_CONV B_GetKeyExtendedErrorInfo PROTO_LIST
((B_KEY_OBJ, ITEM *, POINTER *));
int RSA_CALLING_CONV B_GetKeyInfo PROTO_LIST
((POINTER *, B_KEY_OBJ, B_INFO_TYPE));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 242]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* The algorithm object.
*/
int RSA_CALLING_CONV B_CreateAlgorithmObject PROTO_LIST
((B_ALGORITHM_OBJ *));
void RSA_CALLING_CONV B_DestroyAlgorithmObject PROTO_LIST
((B_ALGORITHM_OBJ *));
int RSA_CALLING_CONV B_SetAlgorithmInfo PROTO_LIST
((B_ALGORITHM_OBJ, B_INFO_TYPE, POINTER));
int RSA_CALLING_CONV B_GetAlgorithmInfo PROTO_LIST
((POINTER *, B_ALGORITHM_OBJ, B_INFO_TYPE));
void RSA_CALLING_CONV B_GetExtendedErrorInfo PROTO_LIST
((B_ALGORITHM_OBJ, ITEM *, POINTER *));
unsigned int B_IntegerBits PROTO_LIST ((unsigned char *,
unsigned int));
/* Algorithm operations.
*/
int RSA_CALLING_CONV B_RandomInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_RandomUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_GenerateRandomBytes PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DigestInit PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DigestUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DigestFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_EncryptInit PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_EncryptUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_EncryptFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
B_ALGORITHM_OBJ, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecryptInit PROTO_LIST
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 243]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecryptUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_DecryptFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
B_ALGORITHM_OBJ, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_EncodeInit PROTO_LIST ((B_ALGORITHM_OBJ));
int RSA_CALLING_CONV B_EncodeUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int));
int RSA_CALLING_CONV B_EncodeFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int));
int RSA_CALLING_CONV B_DecodeInit PROTO_LIST ((B_ALGORITHM_OBJ));
int RSA_CALLING_CONV B_DecodeUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int));
int RSA_CALLING_CONV B_DecodeFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int));
int B_OpenEnvelopeInit PROTO_LIST
((B_ALGORITHM_OBJ, unsigned int *, ITEM *, B_KEY_OBJ,
B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_OpenEnvelope PROTO_LIST
((B_ALGORITHM_OBJ, ITEM *, unsigned int, ITEM *, B_KEY_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SealEnvelope PROTO_LIST
((B_ALGORITHM_OBJ, ITEM *, unsigned int, ITEM *, B_KEY_OBJ,
B_ALGORITHM_OBJ, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SealEnvelopeInit PROTO_LIST
((B_ALGORITHM_OBJ, unsigned int *, ITEM *, B_KEY_OBJ, B_KEY_OBJ,
B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SignInit PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SignUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SignFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
B_ALGORITHM_OBJ, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_VerifyInit PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 244]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
int RSA_CALLING_CONV B_VerifyUpdate PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_VerifyFinal PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_KeyAgreeInit PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_CHOOSER,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_KeyAgreePhase1 PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
B_ALGORITHM_OBJ, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_KeyAgreePhase2 PROTO_LIST
((B_ALGORITHM_OBJ, unsigned char *, unsigned int *, unsigned int,
unsigned char *, unsigned int, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_GenerateInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_GenerateKeypair PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_KEY_OBJ, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_GenerateParameters PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_OBJ, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SymmetricKeyGenerateInit PROTO_LIST
((B_ALGORITHM_OBJ, B_ALGORITHM_CHOOSER, A_SURRENDER_CTX *));
int RSA_CALLING_CONV B_SymmetricKeyGenerate PROTO_LIST
((B_ALGORITHM_OBJ, B_KEY_OBJ, B_ALGORITHM_OBJ,
A_SURRENDER_CTX *));
int B_CreateSessionChooser PROTO_LIST
((B_ALGORITHM_CHOOSER, B_ALGORITHM_CHOOSER *, POINTER *, ITEM *,
POINTER *, unsigned char ***));
int B_FreeSessionChooser PROTO_LIST
((B_ALGORITHM_CHOOSER *, unsigned char ***));
/* Information for BSAFE 1.x-compatible encryption algorithms.
*/
#define B_BSAFE1_PAD 1
#define B_BSAFE1_PAD_CHECKSUM 2
#define B_BSAFE1_RAW 3
typedef struct {
int encryptionType; /* encryption type: B_BSAFE1_PAD, etc. */
} B_BSAFE1_ENCRYPTION_PARAMS;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 245]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef struct {
unsigned char *key; /* pointer to 8-byte key */
unsigned int effectiveKeyBits; /* effective key length */
} B_RC2_BSAFE1_PARAMS_KEY;
/* Information for password-based encryption (PBE) algorithms.
*/
typedef struct {
unsigned char *salt; /* salt value */
unsigned int iterationCount; /* iteration count */
} B_PBE_PARAMS;
typedef struct {
unsigned int effectiveKeyBits; /* effective key length */
unsigned char *salt; /* salt value */
unsigned int iterationCount; /* iteration count */
} B_RC2_PBE_PARAMS;
typedef struct {
B_INFO_TYPE cryptInfoType;
ITEM *cryptParams;
B_INFO_TYPE formatInfoType;
ITEM *formatParams;
} B_SEAL_OPEN_PARAMS;
typedef struct {
ITEM ivItem;
unsigned int transferSize;
} B_CFB_PARAMS;
/* Information used to specify a block cipher with feedback */
typedef struct {
unsigned char *encryptionMethodName;
POINTER encryptionParams; /* Could be rc5 params for example */
unsigned char *feedbackMethodName;
POINTER feedbackParams; /* May be a ptr to an ITEM for an IV */
unsigned char *paddingMethodName;
POINTER paddingParams;
} B_BLK_CIPHER_W_FEEDBACK_PARAMS;
/* Information used to specify signing or verifying */
typedef struct {
unsigned char *encryptionMethodName;
POINTER encryptionParams; /* Most likely to be null */
unsigned char *digestMethodName;
POINTER digestParams; /* Most likely to be null */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 246]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned char *formatMethodName;
POINTER formatParams;
} B_SIGN_VERIFY_PARAMS;
/* Info used to specify key pair tokens at generation time */
typedef struct {
POINTER keyParameters;
UINT4 privateKeyUsage;
UINT4 publicKeyUsage;
unsigned int protectFlag;
unsigned long publicLifeTime;
unsigned long privateLifeTime;
} B_TOKEN_KEYPAIR_GEN_INFO;
/* Information contained in key token types */
typedef struct {
ITEM manufacturerId;
ITEM internalKey;
} KI_TOKEN_INFO;
typedef struct {
KI_TOKEN_INFO keyDataStruct;
A_X509_ATTRIB_INFO attributes;
} KI_EXTENDED_TOKEN_INFO;
typedef struct {
KI_TOKEN_INFO keyDataStruct;
A_X509_KEYPAIR_ATTRIB_INFO attributes;
} KI_KEYPAIR_TOKEN_INFO;
/* Information for MAC algorithm.
*/
typedef struct {
unsigned int macLen; /* length of MAC value */
} B_MAC_PARAMS;
/* Information for RC4 with MAC algorithm.
*/
typedef struct {
ITEM salt; /* variable-length salt */
unsigned int macLen; /* length to use for MAC value */
} B_RC4_WITH_MAC_PARAMS;
/* Information for DSA parameter generation
*/
typedef struct {
unsigned int primeBits;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 247]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
} B_DSA_PARAM_GEN_PARAMS;
/* Information for EC parameter generation
*/
typedef struct {
unsigned int version;
unsigned int fieldType; /* base field for elliptic curve */
unsigned int fieldElementBits; /* len of field element in bits */
unsigned int compressIndicator; /* ignored for now */
unsigned int minOrderBits; /* minimum size of group */
/* generated by base */
/* input of 0 defaults to */
/* fieldElementBits - 7 */
unsigned int trialDivBound; /* max size of second largest prime */
/* subgroup of group generated by base */
/* input of 0 defaults to 255 */
unsigned int tableLookup; /* relevant only to even field case. */
/* Set if the use of precomputed */
/* params is desired */
} B_EC_PARAM_GEN_PARAMS;
/* How EC parameters are passed.
*/
typedef struct {
B_INFO_TYPE parameterInfoType;
POINTER parameterInfoValue;
} B_EC_PARAMS;
/* How a digest algorithm is specified in a signature scheme.
*/
typedef struct {
B_INFO_TYPE digestInfoType;
POINTER digestInfoParams;
} B_DIGEST_SPECIFIER;
/* Information for Secret sharing algorithm
*/
typedef struct {
unsigned int threshold; /* share threshold */
} B_SECRET_SHARING_PARAMS;
/* Information for PKCS V2 OAEP Algorithm
*/
typedef struct {
/* hashFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "sha1".
In both cases SHA1 will become the digest function.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 248]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
*/
unsigned char* hashFunc;
ITEM hashFuncParams;
/* maskGenFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "mgf1". In both cases MGF1
will become the Mask Generator Function.
*/
unsigned char* maskGenFunc;
ITEM maskGenFuncParams;
/* maskGenFuncUnderlyingAlg may contain a NULL_PTR or a pointer
to the null-terminated ASCII string, "sha1". In both cases
SHA1 will become the underlying algorithm.
*/
unsigned char* maskGenFuncUnderlyingAlg;
ITEM maskGenFuncUnderlyingAlgParams;
/* pSourceFunc is the method for determining the parameters, P.
pSourceFunc may contain a NULL_PTR or a pointer to the
null-terminated ASCII string, "specified parameters".
In both cases "specified parameters" will become the
pSource method.
If pSourceFunc is "specified parameters" then pSourceParams
may be specified in two ways:
1. As a NULL_PTR. P is then assumed to be empty.
2. As an ITEM ITEM contains the specified value for P.
*/
unsigned char* pSourceFunc;
ITEM pSourceParams;
} A_PKCS_OAEP_PARAMS;
/* Key Info Types.
*/
int RSA_CALLING_CONV KI_8Byte PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_24Byte PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_Token PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_ExtendedToken PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DES8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DES8Strong PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DES24Strong PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DESX PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DSAPrivateBER PROTO_LIST ((POINTER *));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 249]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
int RSA_CALLING_CONV KI_DSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DSAPublicBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_ECPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_ECPrivateComponent PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_ECPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_ECPublicComponent PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_Item PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_PKCS_RSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_PKCS_RSAPrivateBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSAPublicBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSA_CRT PROTO_LIST ((POINTER *));
/* Key Info Types for BSAFE 1.x Support.
*/
int RSA_CALLING_CONV KI_DES_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_DESX_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RC2WithBSAFE1Params PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RC2_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSAPrivateBSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV KI_RSAPublicBSAFE1 PROTO_LIST ((POINTER *));
/* Algorithm Info Types.
*/
int RSA_CALLING_CONV AI_BSSecretSharing PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_CBC_IV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_HW_Random PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_CBC_IV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_CBCPadBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_CBCPadPEM PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_EDE3_CBC_IV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_EDE3_CBCPadIV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_EDE3_CBCPadBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DES_CBCPadIV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DESX_CBC_IV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DESX_CBCPadIV8 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DESX_CBCPadBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DHKeyAgree PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DHKeyAgreeBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DHParamGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DSA PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DSAKeyGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DSAParamGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DSAWithSHA1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DSAWithSHA1_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_ECParamGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_ECParameters PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_ECPubKey PROTO_LIST ((POINTER *));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 250]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
int RSA_CALLING_CONV AI_ECKeyGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_EC_DHKeyAgree PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_EC_DSAWithDigest PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_EC_DSA PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_EC_ES PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_ECAcceleratorTable PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_ECBuildAcceleratorTable PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_ECBuildPubKeyAccelTable PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_FeedbackCipher PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_HMAC PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_KeypairTokenGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2Random PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2WithDES_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2WithDES_CBCPadBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD2WithRC2_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2WithRC2_CBCPadBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD2WithRSAEncryption PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD2WithRSAEncryptionBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD2_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD2_PEM PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5Random PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5WithDES_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5WithDES_CBCPadBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD5WithRC2_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5WithRC2_CBCPadBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD5WithRSAEncryption PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD5WithRSAEncryptionBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_MD5WithXOR PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5WithXOR_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD5_PEM PROTO_LIST ((POINTER *));
/* PKCS OAEP added for Bsafe 4.1 */
int RSA_CALLING_CONV AI_PKCS_OAEPRecode PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_OAEPRecodeBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_OAEP_RSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_OAEP_RSAPublicBER PROTO_LIST
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 251]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
((POINTER *));
int RSA_CALLING_CONV AI_PKCS_OAEP_RSAPrivate PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_PKCS_OAEP_RSAPrivateBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SET_OAEP_RSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPrivateBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPrivatePEM PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SET_OAEP_RSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPublicBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_PKCS_RSAPublicPEM PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2_CBC PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2_CBCPadBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2_CBCPadPEM PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC4 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC4WithMAC PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC4WithMAC_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC4_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC5_CBC PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC5_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC5_CBCPadBER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RESET_IV PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RFC1113Recode PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAKeyGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAStrongKeyGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SignVerify PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAPrivate PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAPublic PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SHA1 PROTO_LIST ((POINTER *));
/* We recommend that customers use AI_X962Random_V0 instead */
/* of AI_SHA1Random because future releases of BSAFE may */
/* change the behavior of AI_SHA1Random to match the */
/* algorithm by that name in JSAFE. */
int RSA_CALLING_CONV AI_SHA1Random PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SHA1_BER PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SHA1WithDES_CBCPad PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_SHA1WithDES_CBCPadBER PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_SHA1WithRSAEncryption PROTO_LIST
((POINTER *));
int RSA_CALLING_CONV AI_SHA1WithRSAEncryptionBER PROTO_LIST
((POINTER *));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 252]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
int RSA_CALLING_CONV AI_SymKeyTokenGen PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_X962Random_V0 PROTO_LIST ((POINTER *));
/* Algorithm Info Types for BSAFE 1.x Support.
*/
int RSA_CALLING_CONV AI_DES_CBC_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_DESX_CBC_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MAC PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_MD PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RC2_CBC_BSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAPrivateBSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV AI_RSAPublicBSAFE1 PROTO_LIST ((POINTER *));
int RSA_CALLING_CONV B_EncodeDigestInfo PROTO_LIST
((unsigned char *, unsigned int *, unsigned int, ITEM *,
unsigned char *, unsigned int));
int RSA_CALLING_CONV B_DecodeDigestInfo PROTO_LIST
((ITEM *, ITEM *, unsigned char *, unsigned int));
/* Algorithm methods used when implementing block ciphers with
feedback
*/
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DESX_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DESX_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_EDE_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_EDE_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_CBC_INTER_LEAVED_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_CBC_INTER_LEAVED_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CFB_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CFB_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CFB_PIPELINED_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_CFB_PIPELINED_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECB_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECB_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_OFB_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_OFB_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_OFB_PIPELINED_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_OFB_PIPELINED_DECRYPT;
/* Algorithm methods for use in the algorithm chooser.
*/
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_DES_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_DES_CBC_DECRYPT;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 253]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_TOKEN_DES_EDE3_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_TOKEN_DES_EDE3_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_HW_RANDOM;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_FORMAT_X931;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_EXTRACT_X931;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_PRV_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_PUB_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_CRT_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_RSA_CRT_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_EDE3_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DES_EDE3_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DESX_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DESX_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DH_KEY_AGREE;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DH_PARAM_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DSA_KEY_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DSA_PARAM_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DSA_SIGN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DSA_VERIFY;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DSA_KEY_TOKEN_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_DSA_SIGN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_TOKEN_DSA_VERIFY;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DYN_HUFF_COMPRESS;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_DYN_HUFF_DECOMPRESS;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_PARAM_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_PARAM_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_BLD_ACCEL_TABLE;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_ECFP_BLD_PUB_KEY_ACC_TAB;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_ECF2POLY_BLD_ACCEL_TABLE;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_ECF2POLY_BLD_PUB_KEY_ACC_TAB;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_KEY_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_KEY_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_DH_KEY_AGREE;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_DH_KEY_AGREE;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_DSA_SIGN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_DSA_SIGN;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 254]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECFP_DSA_VERIFY;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_ECF2POLY_DSA_VERIFY;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MAC;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD2;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD2_RANDOM;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD2_RANDOM_2X;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD5;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD5_RANDOM;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD5_RANDOM_2X;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_MD;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC2_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC2_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC2_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC2_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC4_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC4_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC4_WITH_MAC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC4_WITH_MAC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_64DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_64ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_CBC_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RC5_CBC_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_CRT_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_CRT_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_CRT_DECRYPT_BLIND;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_CRT_ENCRYPT_BLIND;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_CRT_X931_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_X931_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_DECRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_ENCRYPT;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_KEY_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_STRONG_KEY_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_RSA_KEY_TOKEN_GEN;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_SHA;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV AM_SHA_RANDOM;
extern B_ALGORITHM_METHOD RSA_CALLING_CONV
AM_SYMMETRIC_KEY_TOKEN_GEN;
/* If the compiler doesn't support global data initialization for
function pointers, you should compile your application with
GLOBAL_FUNCTION_POINTERS defined as 0 and call the appropriate
AM_ Init function for the corresponding AM_. By default,
GLOBAL_FUNCTION_POINTERS is defined as 1.
*/
#if RSA_GLOBAL_FUNCTION_POINTERS == RSA_DISABLED
void RSA_CALLING_CONV BSAFE_VERSIONInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_TokenDES_CBCEncryptInit PROTO_LIST ((void));
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 255]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
void RSA_CALLING_CONV AM_TokenDES_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_HWRandomInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_TokenRSAPrvEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_TokenRSAPubDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DES_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DES_CBCEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DES_EDE3_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DES_EDE3_CBCEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DESX_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DESX_CBCEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DHKeyAgreeInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DHParamGenInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DSAKeyGenInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DSAParamGenInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DSASignInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_DSAVerifyInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECFPEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECF2PolyEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECFPDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECF2PolyDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECFPBldAccelTableInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECFPBldPubKeyAccTabInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ECF2PolyBldAccelTableInit PROTO_LIST
((void));
void RSA_CALLING_CONV AM_FormatX931Init PROTO_LIST ((void));
void RSA_CALLING_CONV AM_ExtractX931Init PROTO_LIST ((void));
void RSA_CALLING_CONV AM_HMACInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MACInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD2Init PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD2RandomInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD2RandomInit_2X PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD5Init PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD5RandomInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MD5RandomInit_2X PROTO_LIST ((void));
void RSA_CALLING_CONV AM_MDInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC2DecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC2EncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC2_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC2_CBCEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC4EncryptDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC4WithMacEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC4WithMacDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC5DecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC5EncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC5_CBCDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RC5_CBCEncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RSA_CRTEncryptDecryptInit PROTO_LIST
((void));
void RSA_CALLING_CONV AM_RSA_CRTEncryptDecryptBlindInit PROTO_LIST
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 256]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
((void));
void RSA_CALLING_CONV AM_RSAEncryptDecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RSAX931DecryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RSA_CRT_X931EncryptInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_RSAKeyGenInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_SHAInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_SHARandomInit PROTO_LIST ((void));
void RSA_CALLING_CONV AM_SymmetricKeyTokenGenInit PROTO_LIST (void);
#endif
#ifdef __cplusplus
}
#endif
#endif /* end _BSAFE_H_ */
10.2 AGLOBAL.H
#ifndef _AGLOBAL_H_
#define _AGLOBAL_H_ 1
#include "bsfmacro.h"
#include "bsfplatf.h"
#ifdef __cplusplus
extern "C" {
#endif
/* POINTER defines a generic pointer type */
typedef unsigned char *POINTER;
/* UINT2 defines a two byte word */
typedef unsigned short int UINT2;
typedef struct {
unsigned char *data;
unsigned int len;
} ITEM;
typedef struct {
int (RSA_CALLING_CONV *Surrender) PROTO_LIST ((POINTER));
POINTER handle;
POINTER reserved;
} A_SURRENDER_CTX;
/* UINT4 defines a four byte word */
#if RSA_REGISTER_SIZE == RSA_16_BIT_REGISTER || \
RSA_REGISTER_SIZE == RSA_32_BIT_REGISTER
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 257]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
typedef unsigned long int UINT4;
#endif
#if RSA_REGISTER_SIZE == RSA_64_BIT_REGISTER
typedef unsigned int UINT4;
#endif
#define NULL_PTR ((POINTER)0)
#define UNUSED_ARG(x) x = *(&x);
#ifdef __cplusplus
}
#endif
#endif /* end _AGLOBAL_H_ */
10.3 ATYPES.H
#ifndef _ATYPES_H_
#define _ATYPES_H_ 1
#include "bsfmacro.h"
#include "bsfplatf.h"
#include "aglobal.h"
#ifdef __cplusplus
extern "C" {
#endif
typedef struct {
unsigned char *key; /* 8-byte DES key */
unsigned char *inputWhitener; /* 8-byte input whitener */
unsigned char *outputWhitener; /* 8-byte output whitener */
} A_DESX_KEY;
typedef struct {
ITEM prime; /* prime */
ITEM base; /* base */
unsigned int exponentBits;
} A_DH_KEY_AGREE_PARAMS;
typedef struct {
unsigned int primeBits;
unsigned int exponentBits;
} A_DH_PARAM_GEN_PARAMS;
typedef struct {
unsigned int primeBits;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 258]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int subPrimeBits;
unsigned int seedBytesLen;
} A_PQG_PARAM_GEN_PARAMS;
typedef struct {
ITEM prime; /* prime (p) */
ITEM subPrime; /* sub prime (q) */
ITEM base; /* base (g) */
ITEM seed; /* as per FIPS 186 standard */
unsigned int counterValue; /* ditto */
} A_PQG_PARAMS;
typedef A_PQG_PARAMS A_DSA_PARAMS;
/* Note that fieldElementBits is not contained in A_EC_PARAMS,
but can be easily recovered from fieldInfo. */
/* The following #define's are for fieldType.
FT_FP is odd prime characteristic
FT_F2_ONB is characteristic 2, optimal normal basis
FT_F2_POLYNOMIAL is characteristic 2, polynomial basis
*/
#define FT_FP 0
#define FT_F2_ONB 1
#define FT_F2_POLYNOMIAL 2
#define FT_F2_TRINOMIAL 3
/* The following #define's are for compressIndicator
CI_COMPRESS compress the base and public key (if generated)
CI_NO_COMPRESS no compression
*/
#define CI_NO_COMPRESS 0
#define CI_COMPRESS 1
#define CI_HYBRID 2
typedef struct {
unsigned int version;
unsigned int fieldType; /* base field for elliptic curve */
unsigned int fieldElementBits; /* length of field element */
/* in bits. */
unsigned int minOrderBits; /* minimum size of group */
/* generated by base */
unsigned int trialDivBound; /* maximum size of second largest */
/* prime subgroup of group generated by base */
unsigned int compressIndicator;
unsigned int tableLookup; /* tableLookup option */
/* available for F_{2^m} only */
} A_EC_GEN_PARAMS;
typedef struct {
unsigned int version;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 259]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int fieldType;
ITEM fieldInfo;
ITEM coeffA;
ITEM coeffB;
ITEM base;
ITEM order;
ITEM cofactor; /* cofactor * order = # points on curve */
unsigned int compressIndicator;
unsigned int fieldElementBits;
} A_EC_PARAMS;
typedef struct {
A_EC_PARAMS curveParams; /* Must be first field to support */
/* pointer casting */
ITEM publicKey;
} A_EC_PUBLIC_KEY;
typedef struct {
A_EC_PUBLIC_KEY ecParams; /* Treated as a union for */
/* programming conven. */
ITEM *precomTable;
} A_EC_PARAMS_EXTEND;
typedef struct {
A_EC_PARAMS curveParams; /* Must be first field to support */
/* pointer casting */
ITEM privateKey;
} A_EC_PRIVATE_KEY;
typedef struct {
ITEM modulus;
ITEM publicExponent;
ITEM privateExponent;
ITEM prime[2]; /* prime factors */
ITEM primeExponent[2]; /* exponents for prime factors */
ITEM coefficient; /* CRT coefficient */
} A_PKCS_RSA_PRIVATE_KEY;
typedef struct {
unsigned int effectiveKeyBits;
unsigned char *iv;
} A_RC2_CBC_PARAMS;
typedef struct {
unsigned int effectiveKeyBits;
} A_RC2_PARAMS;
typedef struct {
unsigned int version;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 260]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int rounds;
unsigned int wordSizeInBits;
unsigned char *iv;
} A_RC5_CBC_PARAMS;
typedef struct {
unsigned int version;
unsigned int rounds;
unsigned int wordSizeInBits;
} A_RC5_PARAMS;
typedef struct {
A_RC5_CBC_PARAMS rc5Params;
ITEM encryptingKey;
} A_RC5_KEY_ENCRYPTING_PARAMS;
typedef struct {
ITEM modulus;
ITEM prime[2]; /* prime factors */
ITEM primeExponent[2]; /* exponents for prime factors */
ITEM coefficient; /* CRT coefficient */
} A_RSA_CRT_KEY;
typedef struct {
ITEM modulus; /* modulus */
ITEM exponent; /* exponent */
} A_RSA_KEY;
typedef struct {
unsigned int modulusBits;
ITEM publicExponent;
} A_RSA_KEY_GEN_PARAMS;
typedef struct {
A_RSA_KEY_GEN_PARAMS keySpecs;
unsigned int publicKeyUsage;
unsigned int privateKeyUsage;
UINT4 publicLifeTime;
UINT4 privateLifeTime;
unsigned int protectFlag;
} A_TOKEN_RSA_KEY_GEN_PARAMS;
typedef struct {
ITEM y; /* public component */
A_DSA_PARAMS params; /* parameters (p, q, g) */
} A_DSA_PUBLIC_KEY;
typedef struct {
ITEM x; /* private component */
A_DSA_PARAMS params; /* parameters (p, q, g) */
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 261]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
} A_DSA_PRIVATE_KEY;
typedef struct {
unsigned int numMatchBits;
unsigned int numIndexBits;
} A_LZ77_COMPRESS_PARAMS;
typedef struct {
unsigned int encryptionBlockLen;
} A_PKCS_PARAMS;
/* Info data structure used by FIPS SHA Random number generator
*/
typedef struct {
ITEM prime;
ITEM seed;
} A_SHA_RANDOM_PARAMS;
typedef struct {
unsigned int blockLen; /* Must go first to be compatible */
/* with ahchform.c */
unsigned int oidNum;
} A_X931_PARAMS;
typedef struct {
unsigned int keyUsage;
unsigned int keyLengthInBytes;
UINT4 lifeTime;
unsigned int protectFlag;
unsigned char *cipherName;
} A_SYMMETRIC_KEY_SPECIFIER;
typedef struct {
unsigned int keyUsage;
unsigned int keyLengthInBytes;
UINT4 lifeTime;
unsigned int protectFlag;
} A_SYMMETRIC_KEY_DEFINER;
typedef struct {
A_SYMMETRIC_KEY_DEFINER externalSpecs;
unsigned char *keyOID;
unsigned int keyOIDLen;
UINT4 dateOfBirth;
} A_X509_ATTRIB_INFO;
typedef struct {
unsigned int keyUsage;
UINT4 lifeTime;
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 262]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
unsigned int protectFlag;
} A_KEYPAIR_DEFINER;
typedef struct {
A_KEYPAIR_DEFINER privateKeyDef;
A_KEYPAIR_DEFINER publicKeyDef;
POINTER keyParams;
unsigned char *cipherName;
} A_KEYPAIR_SPECIFIER;
typedef struct {
A_KEYPAIR_DEFINER externalSpecs;
UINT4 dateOfBirth;
} A_X509_KEYPAIR_ATTRIB_INFO;
#ifdef __cplusplus
}
#endif
#endif /* _ATYPES_H_ */
10.4 BEXTERR.H
#ifndef _BEXTERR_H_
#define _BEXTERR_H_ 1
#include "resizeob.h"
typedef struct B_ExtendedError {
POINTER AM;
ResizeContext errorContext;
} B_ExtendedError;
void B_ExtendedErrorDestructor PROTO_LIST ((B_ExtendedError *));
void B_ExtendedErrorConstructor PROTO_LIST ((B_ExtendedError *));
#endif
10.5 STDLIBRF.H
#ifndef _STDLIBRF_H_
#define _STDLIBRF_H_ 1
#include "bsfmacro.h"
#include "bsfplatf.h"
#ifdef __cplusplus
extern "C" {
#endif
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 263]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* Routines supplied by the implementor.
*/
/* memory manipulation
*/
#if RSA_STD_MEM_FUNCS == RSA_ENABLED
void RSA_CALLING_CONV T_memset PROTO_LIST ((POINTER, int,
unsigned int));
void RSA_CALLING_CONV T_memcpy PROTO_LIST ((POINTER, POINTER,
unsigned int));
void RSA_CALLING_CONV T_memmove PROTO_LIST ((POINTER, POINTER,
unsigned int));
int RSA_CALLING_CONV T_memcmp PROTO_LIST ((POINTER, POINTER,
unsigned int));
#endif
/* memory allocation
*/
#if RSA_STD_ALLOC_FUNCS == RSA_ENABLED
POINTER RSA_CALLING_CONV T_malloc PROTO_LIST ((unsigned int));
POINTER RSA_CALLING_CONV T_realloc PROTO_LIST ((POINTER,
unsigned int));
void RSA_CALLING_CONV T_free PROTO_LIST ((POINTER));
#endif
/* string manipulation functions
*/
#if RSA_STD_STRING_FUNCS == RSA_ENABLED
void RSA_CALLING_CONV T_strcpy PROTO_LIST ((char *, char *));
int RSA_CALLING_CONV T_strcmp PROTO_LIST ((char *, char *));
unsigned int RSA_CALLING_CONV T_strlen PROTO_LIST ((char *));
#endif
/* standard Time functions
*/
#if RSA_STD_TIME_FUNCS == RSA_ENABLED
void RSA_CALLING_CONV T_time PROTO_LIST ((UINT4 *));
#endif
#ifdef __cplusplus
}
#endif
#endif /* _STDLIBRF_H_ */
10.6 BSFPLATF.H
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 264]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* The include file bsfmacro.h contains all the alternatives for */
macro definitions.
*/
#include "bsfmacro.h"
#if RSA_PLATFORM == RSA_I386_486
#define RSA_PLATFORM_SPECIFIC
#include "bsplti32.h"
#endif
#if RSA_PLATFORM == RSA_HP_PA
#define RSA_PLATFORM_SPECIFIC
#include "bshp1020.h"
#endif
#if RSA_PLATFORM == RSA_SPARC_SUN_SOLARIS25
#define RSA_PLATFORM_SPECIFIC
#include "bsparc64.h"
#endif
#ifndef RSA_PLATFORM_SPECIFIC
#ifdef __cplusplus
extern "C" {
#endif
/* Is this BSAFE to use full, domestic strength key sizes or export
strength? */
#define RSA_BSAFE_DESTINATION RSA_DOMESTIC_VERSION
/* The default calling convention is C, the macro RSA_CALLING_CONV
should be "nothing".
If the application is using the PASCAL calling convention then
RSA_CALLING_CONV should be defined approrpriately so that the
application can call the public API accordingly.
For example, the PASCAL calling convention on Windows 95 is
#define RSA_CALLING_CONV ???
*/
#define RSA_CALLING_CONV
/* temporary, when all files have converted, take this next line out.
*/
#define CALL_CONV
/* RSA_GLOBAL_FUNCTION_POINTERS should be set to RSA_ENABLED if and
only if the compiler can intitialize global or static function
pointers. If not (such as with MAC code resource), function
pointers can be set only at run time through an initializing
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 265]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
routine. If that is the case, set RSA_GLOBAL_FUNCTION_POINTERS
to RSA_DISABLED.
*/
#define RSA_GLOBAL_FUNCTION_POINTERS RSA_ENABLED
/* Set RSA_ENDIAN to RSA_LITTLE_ENDIAN for little endian machines
(Intel, for instance). Set it to RSA_BIG_ENDIAN for big endian
machines (Mac and most UNIX, for example).
*/
#define RSA_ENDIAN RSA_BIG_ENDIAN
/* Set RSA_FETCH_UINT4 to RSA_FETCH_ALIGNED_ONLY if the CPU can fetch
UINT4 values only from byte-aligned addresses. Set it to
RSA_FETCH_UNALIGNED if it is possible to fetch from unaligned
addresses. Unaligned fetches enables speedups in the handling of 4
and 8 byte quantities (e.g., in CBC). Old Sun SPARC chips, for
instance, cannot do this.
*/
#define RSA_FETCH_UINT4 RSA_FETCH_ALIGNED_ONLY
/* RSA_REGISTER_SIZE defines the bit size of a register, or word. For
instance, a Pentium's register is 32 bits, so set the value to
RSA_32_BIT_REGISTER. On the other hand, an Alpha's register is 64
bits, so set the value to RSA_64_BIT_REGISTER.
*/
#define RSA_REGISTER_SIZE RSA_32_BIT_REGISTER
/* If the platform accepts prototyping in the function definition,
set RSA_PROTOTYPES to RSA_ENABLED. If not, set the value to
RSA_DISABLED.
*/
#define RSA_PROTOTYPES RSA_ENABLED
/* PROTO_LIST is defined depending on how RSA_PROTOTYPES is defined.
If enabled, then PROTO_LIST returns the list, otherwise it returns
an empty list.
*/
#if RSA_PROTOTYPES == RSA_ENABLED
#define PROTO_LIST(list) list
#endif
#if RSA_PROTOTYPES == RSA_DISABLED
#define PROTO_LIST(list) ()
#endif
/* On the outside chance that some strange platform exists that does
not use 8-bit bytes, define BITS_PER_BYTE.
*/
#define RSA_BITS_PER_BYTE 8
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 266]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
/* The following are all the optimizations we have made so far. An
optimization may exist on a certain platform or it may not. If the
optimization exists, set the macro to the platform macro. If not
leave it as C code. For instance, on Alpha NT, there is a CMP
multiply optimization, but no MD5 transform optimization. Hence,
set RSA_CMP_MULT_WORDS_OPT to RSA_ALPHA_DEC_NT_MSVC40 but leave
RSA_MD5_TRANSFORM_OPT at RSA_C_CODE
*/
#define RSA_CMP_WORD_SIZE RSA_C_CODE
#define RSA_CMP_MULT_WORDS_OPT RSA_C_CODE
#define RSA_CMP_VECTOR_MULT_OPT RSA_C_CODE
#define RSA_CMP_ADD_IN_TRACE_OPT RSA_C_CODE
#define RSA_CMP_MONT_PRODUCT_OPT RSA_C_CODE
#define RSA_CMP_MONT_SQUARE_OPT RSA_C_CODE
#define RSA_CMP_MULTIPLY_OPT RSA_C_CODE
#define RSA_CMP_PA2_0_TEST RSA_C_CODE
#define RSA_DES_ENCRYPT_OPT RSA_C_CODE
#define RSA_DES_INIT_ENCRYPT_OPT RSA_C_CODE
#define RSA_DES_INIT_DECRYPT_OPT RSA_C_CODE
#define RSA_RC2_ENCRYPT_OPT RSA_C_CODE
#define RSA_RC2_DECRYPT_OPT RSA_C_CODE
#define RSA_RC2_INIT_OPT RSA_C_CODE
#define RSA_RC4_UPDATE_OPT RSA_C_CODE
#define RSA_RC5_INIT_OPT RSA_C_CODE
#define RSA_RC5_ENCRYPT_OPT RSA_C_CODE
#define RSA_RC5_DECRYPT_OPT RSA_C_CODE
#define RSA_RC5_64_ENCRYPT_OPT RSA_C_CODE
#define RSA_RC5_64_DECRYPT_OPT RSA_C_CODE
#define RSA_RC5_64_INIT_OPT RSA_C_CODE
#define RSA_MD5_TRANSFORM_OPT RSA_C_CODE
#define RSA_MAC_UPDATE_OPT RSA_C_CODE
#define RSA_SHA1_UPDATE_OPT RSA_C_CODE
#define RSA_CMP_EC_EVEN_OPT RSA_C_CODE
/* The following are included to smooth the transition. Take them out
when all files are converted to the new style.
*/
#define BITS_PER_BYTE RSA_BITS_PER_BYTE
#define RSA_PRIME_BITS(modulusBits) (((modulusBits) + 1) / 2)
#define RSA_PRIME_LEN(modulusBits) \
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 267]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
((RSA_PRIME_BITS (modulusBits) + RSA_BITS_PER_BYTE) \
/ RSA_BITS_PER_BYTE)
#define BITS_TO_LEN(modulusBits) \
(((modulusBits) + RSA_BITS_PER_BYTE - 1) / RSA_BITS_PER_BYTE)
#define MAX_RSA_MODULUS_BITS 2048
#define MIN_RSA_MODULUS_BITS 256
#define MIN_STRONG_RSA_MODULUS_BITS 432
#define A_MIN_DIGEST_LEN 16
#define A_MAX_DIGEST_LEN 32
#define GLOBAL_FUNCTION_POINTERS 1
#ifdef __cplusplus
}
#endif
#endif /* RSA_PLATFORM == RSA_C_CODE */
#endif /* _BSAFE_PLATFORM_H_ */
10.7 BSFMACRO.H
/* This file lists all the possible values macros may take on.
*/
#ifndef _BSAFE_MACRO_H_
#define _BSAFE_MACRO_H_ 1
#ifdef __cplusplus
extern "C" {
#endif
#define RSA_DISABLED 0
#define RSA_ENABLED 1
#define RSA_BIG_ENDIAN 0
#define RSA_LITTLE_ENDIAN 1
#define RSA_DOMESTIC_VERSION 0
#define RSA_EXPORT_VERSION 1
#define RSA_16_BIT_REGISTER 16
#define RSA_32_BIT_REGISTER 32
#define RSA_64_BIT_REGISTER 64
#define RSA_FETCH_ALIGNED_ONLY 0
#define RSA_FETCH_UNALIGNED 1
/* The following are the values defining the platform and compiler.
RSA <chip/machine> <OS/compiler> [register size]
They are to be used to indicate which optimizations are
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 268]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
available.
The default is C code, so the first value is a platform
independent macro.
*/
#define RSA_C_CODE 0
#define RSA_INTEL_MSVC15_16_BIT 10
#define RSA_INTEL_MSVC20_32_BIT 12
#define RSA_INTEL_MSVC40_32_BIT 14
#define RSA_INTEL_BORLAND45_16_BIT 20
#define RSA_INTEL_BORLAND45_32_BIT 22
#define RSA_INTEL_LINUX21_32_BIT 30
#define RSA_INTEL_LINUX30_32_BIT 32
#define RSA_INTEL_SCO50_32_BIT 40
#define RSA_SPARC_SUN_OS_412 100
#define RSA_SPARC_SUN_SOLARIS25 102
#define RSA_MAC_68K_CODE_WARRIER 120
#define RSA_MAC_68K_SYMANTEC 122
#define RSA_MAC_PPC_CODE_WARRIER 130
#define RSA_MAC_PPC_SYMANTEC 132
#define RSA_ALPHA_DEC_OSF_UNIX 140
#define RSA_ALPHA_DEC_NT_MSVC40 142
#define RSA_ALPHA_DEC_VMS 144
#define RSA_MIPS_R2000_IRIX53 160
#define RSA_MIPS_R4000_IRIX60 162
#define RSA_HP_PA 180
#define RSA_AIX_414 200
#define RSA_RS6000_PPC_AIX414 202
#define RSA_RS6000_PWR_AIX414 204
#define RSA_I386_486 210
#define RSA_S390_OS390R13 220
#ifdef __cplusplus
}
#endif
#endif /* _BSAFE_MACRO_H_ */
11. Trademark and Patent Issues
BSAFE and JSAFE are trademarks of RSA Data Security, Inc.
The RSA Public Key Cryptosystem is protected by U.S. Patent
#4,405,829.
The RC5 algorithm is protected by U.S. Patent #5,724,428.
The DES implementation in this document contains code based
on the "libdes" package written by Eric A. Young
(eay@mincom.oz.au) and is included with his permission.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 269]
draft-baldwin-bsafe-00.txt BSAFE CRYPTOGRAPHIC May 1999
12. Copyright Section
Copyright (C) The Internet Society May 1999.
All Rights Reserved.
This document and translations of it may be copied and furnished
to others, and derivative works that comment on or otherwise
explain it or assist in its implementation may be prepared, copied,
published and distributed, in whole or in part, without
restriction of any kind, provided that the above copyright notice
and this paragraph are included on all such copies and derivative
works. However, this document itself may not be modified in any
way, such as by removing the copyright notice or references to the
Internet Society or other Internet organizations, except as needed
for the purpose of developing Internet standards in which case the
procedures for copyrights defined in the Internet Standards
process must be followed, or as required to translate it into
languages other than English.
The limited permissions granted above are perpetual and will not
be revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on
an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
The IETF takes no position regarding the validity or scope of
any intellectual property or other rights that might be claimed
to pertain to the implementation or use of the technology
described in this document or the extent to which any license
under such rights might or might not be available; neither does
it represent that it has made any effort to identify any such
rights. Information on the IETF's procedures with respect to
rights in standards-track and standards-related documentation
can be found in BCP-11. Copies of claims of rights made
available for publication and any assurances of licenses to
be made available, or the result of an attempt made
to obtain a general license or permission for the use of such
proprietary rights by implementors or users of this
specification can be obtained from the IETF Secretariat.
Baldwin, et alia Informational, Expiration: 11/17/1999 [Page 270]
