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 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 [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]