IBM PCI Cryptographic Coprocessor CCA Basic Services Reference and Guide Release 2.54 IBM iSeries PCICC Feature CCA Release 2.
CCA Release 2.54 Note! Before using this information and the product it supports, be sure to read the general information under “Notices” on page xiii. | Thirteenth Edition (December, 2004) | | | This manual describes the IBM Common Cryptographic Architecture (CCA) Basic Services API, Release 2.54 as revised in December 2004, implemented for the IBM eServer iSeries PCI Cryptographic Coprocessor hardware feature (#4801) and OS/400 Option 35, CCA CSP.
CCA Release 2.54 Contents Notices . Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About This Publication . . Revision History . . . . . Organization . . . . . . . Related Publications . . . . Cryptography Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CCA Release 2.54 Cryptographic_Resource_Deallocate (CSUACRD) Key_Storage_Designate (CSUAKSD) . . . . . . . Key_Storage_Initialization (CSNBKSI) . . . . . . . Logon_Control (CSUALCT) . . . . . . . . . . . . . Master_Key_Distribution (CSUAMKD) . . . . . . . Master_Key_Process (CSNBMKP) . . . . . . . . . Random_Number_Tests (CSUARNT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CCA Release 2.54 Cryptographic_Variable_Encipher (CSNBCVE) Data_Key_Export (CSNBDKX) . . . . . . . . . Data_Key_Import (CSNBDKM) . . . . . . . . . Diversified_Key_Generate (CSNBDKG) . . . . Key_Export (CSNBKEX) . . . . . . . . . . . . . Key_Generate (CSNBKGN) . . . . . . . . . . . Key-Type Specifications . . . . . . . . . . Key-Length Specification . . . . . . . . . Key_Import (CSNBKIM) . . . . . . . . . . . . . Key_Part_Import (CSNBKPI) . . . . . . . . . . Key_Test (CSNBKYT) . . . . . . . . . . . . . .
CCA Release 2.54 Providing Security for PINs . . . . . . . . . . . . . . . . . . . . . . . . Using Specific Key Types and Key-Usage Bits to Help Ensure PIN Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Supporting Multiple PIN-Calculation Methods . . . . . . . . . . . . . . PIN-Calculation Methods . . . . . . . . . . . . . . . . . . . . . . . . Data_Array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CCA Release 2.54 Aggregate Role Structure . . . Access-Control-Point List . . . Default Role Contents . . . . . Profile Structure . . . . . . . . . . Basic Structure of a Profile . . Aggregate Profile Structure . . Authentication Data Structure Examples of the Data Structures Passphrase authentication data User Profile . . . . . . . . . . . Aggregate Profile Structure . . Access-Control-Point List . . . Role Data Structure . . . . . . Aggregate Role Data Structure Master Key Shares Data Formats .
CCA Release 2.54 Triple-DES Ciphering Algorithms . . . . . . . . . . . . MAC Calculation Methods . . . . . . . . . . . . . . . . . . RSA Key-Pair Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access-Control Algorithms Passphrase Verification Protocol . . . . . . . . . . . . Design Criteria . . . . . . . . . . . . . . . . . . . . . Description of the Protocol . . . . . . . . . . . . . . Master-Key-Splitting Algorithm . . . . . . . . . . . . . . .
CCA Release 2.54 Figures 1-1. 2-1. 2-2. 2-3. 3-1. 3-2. 3-3. 3-4. 4-1. 4-2. 5-1. 5-2. 5-3. 5-4. 5-5. 5-6. 5-7. 5-8. 5-9. 5-10. 5-11. 5-12. 5-13. 5-14. 5-15. 5-16. 5-17. 5-18. 6-1. 7-1. 7-2. 7-3. 7-4. 8-1. 8-2. 8-3. 8-4. 8-5. 8-6. 8-7. 8-8. 8-9. 8-10. 8-11. A-1. A-2. Copyright IBM Corp. 1997, 2005 CCA Security API, Access Layer, Cryptographic Engine . . . . . . . CCA Node, Access-Control, and Master-Key Management Verbs . Coprocessor-to-Coprocessor Master-Key Cloning . . . . . . . . . . .
CCA Release 2.54 A-3. A-4. A-5. A-6. B-1. B-2. B-3. B-4. B-5. B-6. B-7. B-8. B-9. B-10. B-11. B-12. B-13. B-14. B-15. B-16. B-17. B-18. B-19. B-20. B-21. B-22. B-23. B-24. B-25. B-26. B-27. B-28. B-29. B-30. B-31. B-32. B-33. B-34. B-35. B-36. B-37. B-38. B-39. B-40. B-41. B-42. B-43. B-44. B-45. B-46. B-47. B-48. B-49. x Reason Codes for Return Code 4 . . . . . . . . . . . . . . . . . . Reason Codes for Return Code 8 . . . . . . . . . . . . . . . . . . Reason Codes for Return Code 12 . . . . . . . . . .
CCA Release 2.54 C-1. C-2. C-3. C-4. C-5. C-6. C-7. C-8. C-9. D-1. D-2. D-3. D-4. D-5. D-6. D-7. D-8. D-9. D-10. D-11. D-12. E-1. E-2. E-3. E-4. E-5. E-6. F-1. G-1. Key Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Type Default Control-Vector Values . . . . . . . . . . . . . Control-Vector-Base Bit Map . . . . . . . . . . . . . . . . . . . . Multiply-Enciphering and Multiply-Deciphering CCA Keys . . . PKA96 Clear DES Key Record . . . . . . . . . . . . . . . . . .
CCA Release 2.54 xii IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Notices References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM’s product, program, or service may be used.
CCA Release 2.54 The following terms, denoted by a double asterisk (**) in this publication, are the trademarks of other companies: Diebold Docutel MasterCard Pentium NCR RSA UNIX VISA SET xiv Diebold Inc. Docutel MasterCard International, Inc. Intel Corporation National Cash Register Corporation RSA Data Security, Inc. UNIX Systems Laboratories, Inc. VISA International Service Association SET Secure Electronic Transaction LLC IBM 4758 CCA Basic Services, Release 2.
Revision History CCA Release 2.54 About This Publication The manual is intended for systems and applications analysts and application programmers who will evaluate or create programs for the IBM 4758 Common Cryptographic Architecture (CCA) support for the IBM 4758 Models 002 and 023 technology used with IBM eServer iSeries (OS/400) Option 35, CCA CSP on OS/400 systems. Please reference the IBM iSeries Web sites for the specific features and supported levels of software related to the IBM 4758 technology.
Revision History CCA Release 2.54 Eleventh Edition, April, 2004, CCA Support Program, Release 2.52 This revision to the February, 2004, edition of the IBM 4758 CCA Basic Services Reference and Guide for the IBM 4758 Models 002 and 023, Release 2.52, replaces the February, 2004, Release 2.51 edition. Incorporated changes include: Addition of a second set of issuer-master key parameters with revised processing in the PIN_Change/Unblock (CSNBPCU) verb.
Revision History CCA Release 2.54 1. Functions in support of EMV-compatible smart-cards. Support of the PIN Change/Unblock function described in the VISA Integrated Circuit Card Specification Manual, Section C.11 Support of the key-generation function used for secure messaging described in the VISA Integrated Circuit Card Specification Manual, Section B.4 Encryption of PINs and keys for inclusion in smart-card transactions with EMV-compatible smart cards.
Revision History CCA Release 2.54 Eighth Edition, Revised, CCA Support Program, Release 2.41 This revised Release 2.41 manual incorporates additional information concerning access controls (see “CCA Access-Control” on page 2-2) and other minor editorial changes. Eighth Edition, CCA Support Program, Release 2.41 The major items changed, extended, or added in Release 2.
Revision History CCA Release 2.54 can create an application to to clone keys having any of the CSS, CSR, and SA keys longer than 1024-bits. See “Establishing Master Keys” on page 2-13. The PKA_Key_Token_Change verb now returns return code 0 and reason code 0 if you request to update a key token that contains only a public key. A key token containing only a public key is legitimate, but the PKA_Key_Token_Change verb will have no effect on such a key token.
Revision History CCA Release 2.54 The PKA_Symmetric_Key_Export, PKA_Symmetric_Key_Generate, and PKA_Symmetric_Key_Import verbs are updated to include support of the “OAEP” key-wrapping technique as specified in the RSA PKCS#1-v2.0 specification. The action associated with the derivation-counter in control vector bits 12-14 in the Diversified_Key_Generate verb when using the TDES-ENC and TDES-DEC keywords is described on page 5-37. Weak-key checking in the Master_Key_Process verb is corrected.
CCA Release 2.54 Fifth Edition, CCA Support Program, Release 2.30 The fifth edition of the IBM 4758 CCA Basic Services Reference and Guide Version 2.30 for the IBM 4758 Models 002 and 023 technology and describes the Common Cryptographic Architecture (CCA) application programming interface (API) that is supported by the CCA Support Program, Release 2.30, for the IBM PCI Cryptographic Coprocessor technology. These items have been changed, extended, or added in Release 2.30: 1.
CCA Release 2.54 Organization This manual includes: Chapter 1, “Introduction to Programming for the IBM CCA” presents an introduction to programming for the CCA application programming interface and products. Chapter 2, “CCA Node-Management and Access-Control” provides a basic explanation of the access-control system implemented within the hardware. The chapter also explains the master-key concept and administration, and introduces CCA DES key-management.
CCA Release 2.54 Related Publications In addition to the manuals listed below, you may wish to refer to other CCA product publications which may be of use with applications and systems you might develop for use with the IBM 4758 product.
CCA Release 2.54 IBM Journal of Research and Development Volume 38 Number 2, 1994, G322-0191 USA Federal Information Processing Standard (FIPS): – Data Encryption Standard, 46-1-1988 – Secure Hash Algorithm, 180-1, May 31, 1994 – Cryptographic Module Security, 140-1. PKCS #1&v2.0: RSA Cryptography Standard, RSA Laboratories, October 1, 1998. Obtain from http://www.rsasecurity.com/rsalabs/pkcs.
CCA Release 2.54 Chapter 1. Introduction to Programming for the IBM CCA This chapter introduces you to the IBM Common Cryptographic Architecture (CCA) application programming interface (API). This chapter explains some basic concepts you use to obtain cryptographic and other services from the PCI Cryptographic Coprocessor and its CCA Support Program feature.
CCA Release 2.54 An Overview of the CCA Environment Figure 1-1 on page 1-3 provides a conceptual framework for positioning the CCA Security API. Application programs make procedure calls to the API to obtain cryptographic and related I/O services. The CCA API is designed so that a call can be issued from essentially any high-level programming language. The call, or request, is forwarded to the cryptographic-services access layer and receives a synchronous response.
CCA Release 2.54 Figure 1-1. CCA Security API, Access Layer, Cryptographic Engine IBM 4758 PCI Cryptographic Coprocessor: The Coprocessor provides a secure programming and hardware environment wherein DES and RSA processes are performed. The CCA support program enables applications to employ a set of DES- and RSA-based cryptographic services utilizing the IBM 4758 hardware.
CCA Release 2.54 Applications employ the CCA security API to obtain services from and to manage the operation of a cryptographic system that meets CCA architecture specifications. Cryptographic Engine: The CCA architecture defines a cryptographic subsystem that contains a cryptographic engine operating within a protected boundary. See Figure 1-1 on page 1-3.
CCA Release 2.54 Establishing a Master Key: To protect working keys, the master key must be generated and initialized in a secure manner. One method uses the internal random-number generator for the source of the master key. In this case, the master key is never external to the node as an entity, and no other node will have the same master key2 unless master-key cloning is authorized and in use.
CCA Release 2.54 The Coprocessor supports multiple logons by different users from different host processes. The Coprocessor also supports requests from multiple threads within a single host process. A user is logged on and off by the Logon_Control verb. During logon, the Logon_Control verb establishes a logon session key. This key is held in user-process memory space and in the cryptographic engine.
CCA Release 2.54 The security server and a directory server manage key storage. Applications can store locally used cryptographic keys in a key-storage facility. This is especially useful for long-life keys. Keys stored in key storage are referenced through the use of a key label.
CCA Release 2.54 The Security API, Programming Fundamentals You obtain CCA cryptographic services from the PCI Cryptographic Coprocessor through procedure calls to the CCA security application programming interface (API). Most of the services provided are considered an implementation of the IBM Common Cryptographic Architecture (CCA). Most of the extensions that differ from other IBM CCA implementations are in the area of the access-control services.
CCA Release 2.54 CSUA Cryptographic-node and hardware-control services. The last three letters in the entry-point name identify the specific service in a group and are often the first letters of the principal words in the verb pseudonym. Supported Environments: At the start of each verb description is a table that describes which CCA implementations support the verb.
CCA Release 2.54 each verb. For descriptions of these parameters, see the definitions with the individual verbs. Variable Direction: The parameter descriptions use the following terms to identify the flow of information: Input The application program sends the variable to the verb (to the called routine) Output The verb returns the variable to the application program In/Output The application program sends the variable to the verb, or the verb returns the variable to the application program, or both.
CCA Release 2.54 Commonly Encountered Parameters Some parameters are common to all verbs, other parameters are used with many of the verbs. This section describes several groups of these parameters: Parameters common to all verbs Rule_array and other keyword parameters Key_identifiers, key_labels, and key_tokens. Parameters Common to All Verbs The first four parameters (return_code, reason_code, exit_data_length, and exit_data) are the same for all verbs.
CCA Release 2.54 Value 0 4 8 12 16 Meaning Indicates normal completion; a few nonzero reason codes are associated with this return code. Indicates the verb processing completed, but without full success. For example, this return code can signal that a supplied PIN was found to be invalid. Indicates that the verb prematurely stopped processing. Generally the application programmer will need to investigate the problem and will need to know the associated reason code.
CCA Release 2.54 External A key that is either in the clear, or is encrypted (wrapped) by some key-encrypting key other than the master key. Generally, when a key is to be transported from place to place, or is to be held for a significant period of time, it is required to encrypt the key with a transport key. A key wrapped by a transport key-encrypting key is designated external.
CCA Release 2.54 commands in the performance of the verb. Each of these commands has to be authorized for use. Access-control administration concerns managing these authorizations. Chapter 3, “RSA Key-Management” explains how you can generate and protect an RSA key-pair. The chapter also explains how you can control the distribution of the RSA private key for backup and archive purposes and to enable multiple cryptographic engines to use the key for performance or availability considerations.
CCA Release 2.54 Chapter 2. CCA Node-Management and Access-Control This chapter discusses: The access-control system that you can use to control who can perform various sensitive operations at what times Controlling the cryptographic facility Multi-Coprocessor support The CCA master-key, what it is, and how you manage the key How you can initialize the cryptographic key-storage that is managed by the support software. The verbs that you use to accomplish these tasks are listed in Figure 2-1.
CCA Release 2.54 CCA Access-Control This section describes these CCA access-control system topics: Understanding access control Role-based access control Initializing and managing the access-control system Logging on and logging off Protecting your transaction information. Understanding Access Control Access control is the process that determines which CCA services or “commands”1 of the IBM 4758 PCI Cryptographic Coprocessor are available to a user at any given time.
CCA Release 2.54 A role-based system is more efficient than one in which the authority is assigned individually for each user. In general, users can be segregated into just a few different categories of access rights. The use of roles allows the administrator to define each of these categories just once, in the form of a role. Understanding Roles Each role defines the permissions and other characteristics associated with users having that role.
CCA Release 2.54 Understanding Profiles Any user who needs to be authenticated to the Coprocessor must have a user profile. Users who only need the capabilities defined in the default role do not need a profile. A user profile defines a specific user to the CCA implementation. Each profile contains the following information: User ID This is the “name” used to identify the user to the Coprocessor. The User ID is an eight-byte value, with no restrictions on its content.
CCA Release 2.54 Initializing and Managing the Access-Control System Before you can use a Coprocessor with newly loaded or initialized CCA support you should initialize roles, profiles, and other data. You may also need to update some of these values from time to time. Access-control initialization and management are the processes you will use to accomplish this.
CCA Release 2.54 Take care to ensure that you define roles that have the authority to perform initialization, including the RQ-TOKEN and RQ-REINT options of the Cryptographic_Facility_Control (CSUACFC) verb. You must also ensure there are active profiles that use these roles. If you configure your Coprocessor so that initialization is not allowed, you can recover by reloading4 the Coprocessor CCA software.
CCA Release 2.54 Notes: 1. During the portions of the year when Daylight Savings Time is not in effect, the time difference between Eastern Standard Time and GMT is 5 hours. 2. In the OS/400 environment, no translation is provided for Role and Profile names. The Coprocessor will initialize the default role name to DEFAULT encoded in ASCII. OS/400 CCA users will need to consider the encoding of Role and Profile names.
CCA Release 2.54 logged on, and frees resources you were using in the host system and in the Coprocessor. Use of Logon Context Information The Logon_Control verb offers the capability to save and restore logon context information through the GET-CNTX and PUT-CNTX rule-array keywords. The GET-CNTX keyword is used to retrieve a copy of your active logon context information, which you can then store for subsequent use. The PUT-CNTX keyword is used to make active previously stored context information.
CCA Release 2.54 Protecting Your Transaction Information When you are logged on to the Coprocessor, the information transmitted to and from the CCA Coprocessor application is cryptographically protected using your session key. A message authentication code is used to ensure that the data was not altered during transmission. Since this code is calculated using your session key, it also verifies that you are the originator of the request, not someone else attempting to impersonate you.
CCA Release 2.54 used to establish the maximum strength of certain cryptographic functions, the environment identifier, and the maximum number of master-key-cloning shares, and the minimum number of shares needed to reconstitute a master key. Reset the intrusion latch. The intrusion latch circuit can be set by breaking an external circuit connected to jack 6 (J6) on the Coprocessor.
CCA Release 2.54 Cryptographic_Resource_Allocate verb will fail if a cryptographic resource is already allocated. To determine the number of CCA Coprocessors installed in a machine, use the Cryptographic_Facility_Query verb with the STATCARD rule-array keyword. The verb returns the number of Coprocessors running CCA software. The count includes any Coprocessors loaded with CCA UDX code. When using multiple CCA Coprocessors, you must consider the implications of the master keys in each of the Coprocessors.
CCA Release 2.54 the Coprocessor device driver.5 The host code then polls each Coprocessor in turn to determine which ones contain the CCA application. As each Coprocessor is evaluated, the CCA host code associates the identifiers CRP01, CRP02, and so forth to the Coprocessors with CCA.6 In the absence of a specific Coprocessor allocation, the host code employs the device designated CRP01 by default. You can alter the default designation by explicitly setting the CSU_DEFAULT_ADAPTER environment variable.
CCA Release 2.54 PKA_Key_Token_Change verbs). Whenever a working key is encrypted for local use, it is encrypted using the current master-key. Symmetric and Asymmetric Master-Keys The CCA Version 2 implementation incorporates a second set of master-key registers. One register set is used to encrypt DES (symmetric) working-keys. The second register set is used to encrypt PKA (asymmetric) private working-keys.
CCA Release 2.54 The verb performs a one-way function on the key-of-interest, the result of which is either returned or compared to a known correct result. Establishing a master key from an internally generated random value. The Master_Key_Process verb can be used to randomly generate a new master-key within the cryptographic engine. The value of the new master-key is not available outside of the cryptographic engine.
CCA Release 2.54 must also have been marked as suitable for operation with the Master_Key_Distribution verb when it was generated. When receiving a share, you must also supply the share-signing key in a certificate to the Master_Key_Distribution verb. The engine validates the certificate, and uses the validated public key to validate the individual master-key share.
CCA Release 2.54 ┌──────────────────────────────────┐ │Share─Administration Control Point│ 3.
CCA Release 2.54 7. In the target node, generate a retained key usable for master-key administration, the Coprocessor Share Receiving (CSR) key, and have this key certified by the SA key. 8. Once a master key has been established in the source node, perhaps through random master-key generation, obtain shares of the master key. Also obtain master-key verification information for use in step 10 using the Key_Test verb.
CCA Release 2.54 AIX and Windows Multi-Coprocessor Master-Key Support: It is a general recommendation that all of the CCA Coprocessors within the system use the same current and old master keys. When setting a new master-key, it is essential that all of the changes are performed by a single program running on a single thread. If the thread-process is ended before all of the Coprocessor master-keys are changed, significant complications can arise.
CCA Release 2.54 When all of the Coprocessors are newly initialized, that is, their current-master-key registers are empty, first install the same master key in each of the new-master-key registers. Then set the master key in each of the Coprocessors. Finally, if you are going to use key storage, initialize key storage.
CCA Release 2.54 Intentionally using different master keys in a set of Coprocessors. This situation becomes very complicated if you are using key storage with a subset of the Coprocessors. The preceding discussion provides information that you can use to manage this case. If you are not using key storage and have not initialized key storage files, then the situation is quite simple. Just load and set the master keys as you would in a single-Coprocessor situation.
Access_Control_Initialization CCA Release 2.54 Access_Control_Initialization (CSUAACI) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Access_Control_Initialization verb is used to initialize or update parameters and tables for the Access-Control system in the 4758 Cryptographic Coprocessor.
Access_Control_Initialization Keyword CCA Release 2.54 Meaning Function to perform (one required) INIT-AC Initializes roles and user profiles. CHGEXPDT Changes the expiration date in a user profile. CHG-AD Changes authentication data in a user profile or changes a user's passphrase. Note: The PROTECTD keyword must also be used whenever you use CHG-AD.
Access_Control_Initialization CCA Release 2.54 verb_data_length_2 The verb_data_length_2 parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data_2 variable. verb_data_2 The verb_data_2 parameter is a pointer to a string variable containing data used by the verb. Authentication data structures are described in “Access-Control Data Structures” on page B-28. This field is used differently depending on the function being performed.
Access_Control_Maintenance CCA Release 2.54 Access_Control_Maintenance (CSUAACM) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Access_Control_Maintenance verb is used to query or control installed roles and user profiles.
Access_Control_Maintenance CCA Release 2.54 Keyword Meaning Function to perform (one required) LSTPROFS Retrieves a list of the user profiles currently installed in the Coprocessor. Keyword Q-NUM-RP shows how to determine how much data this request will return to the application program. LSTROLES Retrieves a list of the roles currently installed in the Coprocessor. Keyword Q-NUM-RP shows how to determine how much data this request will return to the application program.
Access_Control_Maintenance CCA Release 2.54 output_data_length The output_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the output_data variable. The value must be a multiple of four bytes. On input, the output_data_length variable must be set to the total size of the variable pointed to by the output_data parameter. On output, this variable will contain the number of bytes of data returned by the verb in the output_data variable.
Access_Control_Maintenance CCA Release 2.54 Rule-Array Keyword Contents of output_data Variable GET-PROF Contains the non-secret portion of the selected user profile. This includes the following data, in the order listed. Profile version Two bytes containing 2 one-byte integer values, where the first byte contains the major version number and the second byte contains the minor version number. Comment A 20-character field, padded on the right with spaces, which describes the profile.
Access_Control_Maintenance CCA Release 2.54 Rule-Array Keyword Contents of output_data Variable GET-ROLE The field contains the non-secret portion of the selected role. This includes the following data, in the order listed. Role version Two bytes containing integer values, where the first byte contains the major version number and the second byte contains the minor version number. Comment A 20-character field, padded with spaces, containing a comment which describes the role.
Access_Control_Maintenance CCA Release 2.54 Required Commands The Access_Control_Maintenance verb requires the following commands to be enabled in the hardware: Read public access-control information (offset X'0116') with the LSTPROFS, LSTROLES, GET-PROF, GET-ROLE, and Q-NUM-RP keywords Delete a User Profile (offset X'0117') with the DEL-PROF keyword Delete a Role (offset X'0118') with the DEL-ROLE keyword. Chapter 2.
Cryptographic_Facility_Control CCA Release 2.54 Cryptographic_Facility_Control (CSUACFC) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X Use the Cryptographic_Facility_Control verb to perform the following services: Reinitialize the CCA application in the Coprocessor. Set the date and time in the Coprocessor clock.
Cryptographic_Facility_Control CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
Cryptographic_Facility_Control CCA Release 2.54 verb_data_length The verb_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the verb_data variable. On input, specify the size of the variable. The verb updates the variable with the size of the returned data. verb_data The verb_data parameter is a pointer to a string variable containing data used by the verb on input, or generated by the verb on output.
Cryptographic_Facility_Control CCA Release 2.54 For SET-MOFN, verb_data is an input variable. The variable contents establish the minimum and maximum number of “cloning information” shares that are required and that can be used to pass sensitive information from one Coprocessor to another Coprocessor. The verb_data variable contains a two-element array of integers. The first element is the m minimum required number of shares to reconstruct cloned information (see the Master_Key_Distribution verb).
Cryptographic_Facility_Query CCA Release 2.54 Cryptographic_Facility_Query (CSUACFQ) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Cryptographic_Facility_Query verb is used to retrieve information about the Cryptographic Coprocessor and the CCA application program in that Coprocessor.
Cryptographic_Facility_Query CCA Release 2.54 On output, the verb sets the variable to the number of rule-array elements it returns to the application program. Note: With this verb, the number of returned rule-array elements can exceed the rule-array count that you specified on input. Be sure that you allocate adequate memory to receive all of the information elements according to the information class that you select on input with the information-to-return keyword in the rule-array.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 1 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description Output rule-array for option STATCCA 1 NMK Status State of the New Master-Key register: One means the register is clear Two means the register contains a partially complete key Three means the register contains a complete key.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 2 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description Output rule-array for option STATCCAE 1 Symmetric NMK Status State of the Symmetric New Master-Key register: One means the register is clear Two means the register contains a partially complete key Three means the register contains a complete key.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 3 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description Output rule-array for option STATCARD 1 Number of Installed Adapters The number of active Cryptographic Coprocessors installed in the machine. Note that this only includes Coprocessors that have CCA software loaded (including those with CCA UDX software). Non-CCA Coprocessors are not included in this number.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 4 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description 12 Flash Memory Size A numeric character string containing the size of the flash EPROM memory on the Coprocessor, in 64-kilobyte increments. 13 DRAM Memory Size A numeric character string containing the size of the dynamic RAM (DRAM) memory on the Coprocessor, in kilobytes.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 5 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number 5 Name Description Low Voltage Detected A numeric character string containing a value to indicate whether a power supply voltage was below the minimum acceptable level.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 6 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description Output rule-array for option STATEID (Environment Identifier) 1,2 EID The two elements when concatenated provide the 16-byte EID value.
Cryptographic_Facility_Query CCA Release 2.54 Figure 2-3 (Page 7 of 7). Cryptographic_Facility_Query Information Returned in the Rule Array Element Number Name Description Output rule-array for option STATMOFN Elements one and two, and elements three and four, are each treated as a 16-byte string with the high-order 15 bytes having meaningful information and the 16th byte containing a space character. Each byte provides status information about the 'i'th share, 1≤i≤15, of master-key information.
Cryptographic_Facility_Query CCA Release 2.54 of this verb. Its use depends on the options specified by the host application program. The verb_data parameter is not currently used by this verb. Required Commands Cryptographic_Facility_Query is a universally authorized verb. There are no access-control restrictions on its use. Chapter 2.
Cryptographic_Resource_Allocate CCA Release 2.54 Cryptographic_Resource_Allocate (CSUACRA) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Cryptographic_Resource_Allocate verb is used to allocate a specific CCA Coprocessor for use by the thread or process, depending on the scope of the verb. For the OS/400, this verb is scoped to a process; for the other implementations, this verb is scoped to a thread.
Cryptographic_Resource_Allocate CCA Release 2.54 Keyword Meaning Cryptographic resource (required) DEVICE Specifies an (IBM 4758) CCA Coprocessor. resource_name_length The resource_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the resource_name variable. The length must be within the range of 1 to 64. resource_name The resource_name parameter is a pointer to a string variable containing the name of the Coprocessor to be allocated.
Cryptographic_Resource_Deallocate CCA Release 2.54 Cryptographic_Resource_Deallocate (CSUACRD) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Cryptographic_Resource_Deallocate verb is used to deallocate a specific CCA Coprocessor that is currently allocated by the thread or process, depending on the scope of the verb. For the OS/400, this verb is scoped to a process; for the other implementations, this verb is scoped to a thread.
Cryptographic_Resource_Deallocate CCA Release 2.54 Keyword Meaning Cryptographic resource (required) DEVICE Specifies an (IBM 4758) CCA Coprocessor. resource_name_length The resource_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the resource_name variable. The length must be within the range of 1 to 64. resource_name The resource_name parameter is a pointer to a string variable containing the name of the Coprocessor to be deallocated.
Key_Storage_Designate CCA Release 2.54 Key_Storage_Designate (CSUAKSD) Platform/ Product OS/2 AIX Win NT/ 2000 IBM 4758-2/23 OS/400 X The Key_Storage_Designate verb specifies the key-storage file used by the process. You select the type of key storage, for DES keys or for public keys, using a rule-array keyword.
Key_Storage_Designate CCA Release 2.54 key_storage_file_name_length The key_storage_file_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_storage_file_name variable. The length must be within the range of 1 to 64. key_storage_file_name The key_storage_file_name parameter is a pointer to a string variable containing the fully qualified file name of the key-storage file to be selected. Required Commands None Chapter 2.
Key_Storage_Initialization CCA Release 2.54 Key_Storage_Initialization (CSNBKSI) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Key_Storage_Initialization verb initializes a key-storage file using the current symmetric or asymmetric master-key. The initialized key storage will not contain any pre-existing key records. The name and path of the key storage data and index file are established differently in each operating environment.
Key_Storage_Initialization CCA Release 2.54 Keyword Meaning Key-storage selection (one required) DES Initialize DES key-storage. PKA Initialize PKA key-storage. key_storage_file_name_length The key_storage_file_name_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_storage_file_name variable. The length must be within the range of 1 to 64.
Logon_Control CCA Release 2.54 Logon_Control (CSUALCT) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 Use the Logon_Control verb to perform the following services: Log on to the Coprocessor, using your access-control profile Log off of the Coprocessor Save or restore logon content information. Select the service to perform by specifying the corresponding keyword in the input rule-array. Only one service is performed for each call to this verb.
Logon_Control CCA Release 2.54 Keyword Meaning Keywords used to log on LOGON Tells the Coprocessor that you want to log on. When you use the LOGON keyword, you must also use a second keyword, PPHRASE, to indicate how you will identify yourself to the Coprocessor. PPHRASE Specifies that you are going to identify yourself using a passphrase. Keywords used to log off LOGOFF Tells the Coprocessor you want to log off. FORCE Tells the Coprocessor that a specified user is to be logged off.
Logon_Control CCA Release 2.54 On input, this field contains the length (in bytes) of the auth_data variable. When no usage is defined for the auth_data parameter, set the length variable to zero. On output, this field contains the number of bytes of data returned in the auth_data variable. auth_data The auth_data parameter is a pointer to a string variable containing data used in the authentication process. This field is used differently depending on the keywords specified in the rule array.
Master_Key_Distribution CCA Release 2.54 Master_Key_Distribution (CSUAMKD) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Master_Key_Distribution verb is used to perform these operations related to the distribution of shares of the master key: Generate and distribute a share of the current master-key Receive a master-key share. When sufficient shares are received, reconstruct the master key in the new master-key register.
Master_Key_Distribution CCA Release 2.54 – The private_key_name of the Coprocessor-retained key used to decrypt the clone_info_encrypting_key. This key must have the CLONE attribute set at the time of key generation.
Master_Key_Distribution CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
Master_Key_Distribution CCA Release 2.54 clone_info_encrypting_key The clone_info_encrypting_key parameter is a pointer to a string variable containing the encrypted key used to recover the cloning information. clone_info_length The clone_info_length parameter is a pointer to an integer variable containing the number of bytes of data in the clone_info variable. clone_info The clone_info parameter is a pointer to a string variable containing the encrypted cloning information (master-key share).
Master_Key_Process CCA Release 2.54 Master_Key_Process (CSNBMKP) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Master_Key_Process verb operates on the three master-key registers: new, current, and old.
Master_Key_Process CCA Release 2.54 The master-key verification pattern (MKVP) of the new master-key is compared against the MKVP of the current and the old master-keys. If they are the same, the service fails with return code 8, reason code 704. If any of the eight-byte parts of the new master-key compares equal to one of the weak DES-keys, the service fails with return code 8, reason code 703. See page 2-62 for a list of these “weak” keys.
Master_Key_Process CCA Release 2.54 Keyword Meaning Master-key process (one required) CLEAR Specifies to clear the new master-key register. CLR-OLD Specifies to clear the old master-key register and set the status for this register to empty. You can use the CLR-OLD keyword to cause the old master-key register to be cleared. The status response in the Cryptographic_Facility_Query verb, STATCCA, shows the condition of this register. FIRST Specifies to load the first key_part.
Master_Key_Process CCA Release 2.54 – Clear Old PKA Master Key Register command (offset X'0061') with the CLR-OLD keyword – Load First PKA Master Key Part command (offset X'0053') with the FIRST keyword – Combine PKA Master Key Parts command (offset X'0054') with the MIDDLE or LAST keywords – Generate Random PKA Master Key command (offset X'0120') with the RANDOM keyword – Set PKA Master Key command (offset X'0057') with the SET keyword.
Master_Key_Process CCA Release 2.
Random_Number_Tests CCA Release 2.54 Random_Number_Tests (CSUARNT) Platform/ Product OS/2 AIX Win NT/ 2000 X X X IBM 4758-2/23 OS/400 The Random_Number_Tests verb invokes the USA NIST FIPS PUB 140-1 specified cryptographic operational tests. These tests, selected by a rule-array keyword, consist of: For random numbers: monobit test, poker test, runs test, and long run test Known answer tests of DES, RSA, and SHA-1 processes. The tests are performed three times.
Random_Number_Tests CCA Release 2.54 Required Commands None. Chapter 2.
CCA Release 2.54 2-66 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Chapter 3. RSA Key-Management This chapter describes the management of RSA public and private keys and how you can: Generate keys with various characteristics Import keys from other systems Protect and move a private key from one node to another. The verbs listed in Figure 3-1 are used to perform cryptographic functions and assist you in obtaining key-token data structures. Figure 3-1.
CCA Release 2.
CCA Release 2.54 The PKA_Key_Generate verb either retains the generated private key within the Coprocessor, or the verb outputs the generated private key in one of three forms so you can control where the private key is deployed. You can request that the generated private key be retained within the secure cryptographic-engine through the use of the RETAIN keyword on the PKA_Key_Generate verb. In this case, only the public key is returned.
CCA Release 2.54 restricted key usage. These systems can determine if a requesting process has the right to use the particular key name that is cryptographicly bound to the private key. You specify such a key name when you build the skeleton_key_token in the PKA_Key_Token_Build verb. For RSA keys, you decide if the key should be returned in modular-exponent form or in Chinese-Remainder-Theorem (CRT) form. Generally the CRT form performs faster in services that use the private key.
CCA Release 2.54 You provide or identify the operational transport key (key-encrypting key) and the encrypted private key with its associated public key to the import service. The service will return the private key encrypted under the current asymmetric master-key along with the public key. The Coprocessor is designed to generate and employ RSA CRT-form keys having p>q. If you import a private key having q>p, the key will be accepted.
CCA Release 2.54 Using the Private Key at Multiple Nodes You can arrange to use a private key at multiple nodes if the nodes have the same asymmetric master-key, or if you arrange to have the same transport key installed at each of the target nodes. In the latter case, you need to arrange to have the transport key under which the private key is enciphered installed at each target node.
PKA_Key_Generate CCA Release 2.54 PKA_Key_Generate (CSNDPKG) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Key_Generate verb is used to generate a public-private key-pair for use with the RSA algorithm.
PKA_Key_Generate CCA Release 2.54 Note: When using the RETAINED key option, the key label supplied in the skeleton key-token references the key storage within the Coprocessor, and in this case must not reference a record in the host-system key-storage. The rule-array keyword CLONE flags a generated and retained RSA private key as usable in an engine “cloning” process. Cloning is a technique for copying sensitive Coprocessor information from one Coprocessor to another.
PKA_Key_Generate CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
PKA_Key_Generate CCA Release 2.54 skeleton_key_token The skeleton_key_token parameter is a pointer to a string variable containing a skeleton key-token. This information provides the characteristics for the PKA key-pair to be generated. A skeleton key-token can be created using the PKA_Key_Token_Build verb.
PKA_Key_Import CCA Release 2.54 PKA_Key_Import (CSNDPKI) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Key_Import verb is used to import a public-private key-pair. A private key must be accompanied by the associated public key. A source private-key may be in the clear or it may be enciphered. Generally you obtain the key token from the PKA_Key_Generate verb.
PKA_Key_Import CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be zero for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
PKA_Key_Import CCA Release 2.54 Required Commands The PKA_Key_Import verb requires the PKA Key Import command (offset X'0104') to be enabled in the hardware. Chapter 3.
PKA_Key_Token_Build CCA Release 2.54 PKA_Key_Token_Build (CSNDPKB) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Key_Token_Build verb constructs a public-key architecture (PKA) key-token from the supplied information. This verb is used to create the following: A skeleton_key_token for use with the PKA_Key_Generate verb A key token with a public key that has been obtained from another source A key token with a clear private-key and the associated public key.
PKA_Key_Token_Build CCA Release 2.54 Restrictions The RSA-OPT rule-array keyword is not supported with Version 2. Instead, use keyword RSA-CRT to obtain a X'08' private-key section type. The RSA key length is limited to the range of 512 to 2048 bits with specific formats restricted to 1024 bits maximum. When generating a key for use with ANSI X9.31 digital signatures, the modulus-length (key-length) must be one of 1024, 1280, 1536, 1792, or 2048 bits.
PKA_Key_Token_Build CCA Release 2.54 Keyword Meaning Token type (one required) RSA-CRT Create a key token for an RSA public-key and a key in Chinese-Remainder form. RSA-OPT Note: This keyword is not supported with Version 2 software. RSA-PRIV Create a key token for an RSA public and private key pair in modulus-exponent form. RSA-PUBL Create a key token for an RSA public-key in modulus-exponent form.
PKA_Key_Token_Build CCA Release 2.54 Figure Offset (Bytes) 3-3 (Page 1 of 2). PKA_Key_Token_Build Key-Values-Structure Contents Length (Bytes) Description RSA key-values structure, modulus-exponent form (RSA-PRIV or RSA-PUBL) 000 002 Length of the modulus in bits (512 to 1024 for RSA-PRIV, 512 to 2048 for RSA-PUBL) 002 002 Length of the modulus field, n, in bytes, “nnn.” This value must not exceed 256 for a 2048 bit-length key.
PKA_Key_Token_Build CCA Release 2.54 Figure 3-3 (Page 2 of 2). PKA_Key_Token_Build Key-Values-Structure Contents Offset (Bytes) Length (Bytes) Description 018 nnn Modulus, n. 018 +nnn eee Public exponent, e, integer value, 1
PKA_Key_Token_Build CCA Release 2.54 reserved_x(s) The reserved_x parameters are each a pointer to a string variable that is reserved for future use. Each of the reserved_x parameters should contain a null pointer. token_length The token_length parameter is a pointer to an integer variable containing the number of bytes of data in the token variable. On output, the variable contains the length of the token returned in the token variable. The maximum length is 2500 bytes.
PKA_Key_Token_Build Token Type Modulus Length in Bits CCA Release 2.
PKA_Key_Token_Build CCA Release 2.54 Required Commands None Chapter 3.
PKA_Key_Token_Change CCA Release 2.54 PKA_Key_Token_Change (CSNDKTC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Token_Change verb changes RSA private keys from encipherment with the old asymmetric master-key to encipherment with the current asymmetric master-key. You identify the task with the rule-array keyword, and the internal key-token to change with the key_identifier parameter.
PKA_Key_Token_Change CCA Release 2.54 key_identifier_length The key_identifier_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_identifier variable. On output, the variable contains the length of the key token returned by the verb if a key token (not a key label) was specified. The maximum length is 2500 bytes.
PKA_Public_Key_Extract CCA Release 2.54 PKA_Public_Key_Extract (CSNDPKX) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Public_Key_Extract verb is used to extract a public key from a public-private key-pair. The public key is returned in a PKA public-key token. Both the public key and the related private key must be present in the source key token. The source private-key may be in the clear or may be enciphered.
PKA_Public_Key_Extract CCA Release 2.54 target_key_token_length The target_key_token_length parameter is a pointer to an integer variable containing the number of bytes of data in the target_key_token variable. On output, the variable contains the length of the key token returned by the verb. The maximum length is 2500 bytes. target_key_token The target_key_token parameter is a pointer to a string variable containing the PKA96 public-key token returned by the verb. Required Commands None Chapter 3.
PKA_Public_Key_Hash_Register CCA Release 2.54 PKA_Public_Key_Hash_Register (CSNDPKH) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Public_Key_Hash_Register verb is used to register a hash value for a public key in anticipation of verifying the public key offered in a subsequent use of the PKA_Public_Key_Register verb.
PKA_Public_Key_Hash_Register CCA Release 2.54 hash_data_length The hash_data_length parameter is a pointer to an integer variable containing the number of bytes of data in the hash_data variable. hash_data The hash_data parameter is a pointer to a string variable containing the SHA-1 hash of a public-key certificate that will be offered with the use of the PKA_Public_Key_Register verb. The format of the public-key certificate is defined in “RSA Public-Key Certificate Section” on page B-17.
PKA_Public_Key_Register CCA Release 2.54 PKA_Public_Key_Register (CSNDPKR) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Public_Key_Register verb is used to register a public key in the cryptographic engine. Keywords in the rule array designate the subsequent permissible uses of the registered public key. The public key offered for registration must be contained in a token that contains a certificate section.
PKA_Public_Key_Register CCA Release 2.54 public_key_name The public_key_name parameter is a pointer to a string variable containing the name under which the registered public-key will be accessed. public_key_certificate_length The public_key_certificate_length parameter is a pointer to an integer variable containing the number of bytes of data in the public_key_certificate variable.
CCA Release 2.54 3-30 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Chapter 4. Hashing and Digital Signatures This chapter discusses the data hashing and the digital signature techniques you can use to determine data integrity. A digital signature may also be used to establish the non-repudiation security property. (Another approach to data integrity based on DES message authentication codes is discussed in Chapter 6, “Data Confidentiality and Data Integrity.
CCA Release 2.54 The CCA products support the following hash functions: Secure Hash Algorithm-1 (SHA-1) The SHA-1 is defined in FIPS 180-1 and produces a 20-byte, 160-bit hash value. The algorithm performs best on big-endian, general purpose computers. This algorithm is usually preferred over MD5 if the application designers have a choice of algorithms. SHA-1 is also specified for use with the DSS digital signature standard.
CCA Release 2.54 Anyone with access to your public key can verify your information as follows: 1. Hash the data using the same hashing algorithm that you used to create the digital signature. 2. Decrypt the digital signature using your public key. 3. Compare the decrypted results to the hash value obtained from hashing the data. An equal comparison confirms that the data they possess is the same as that which you signed.
Digital_Signature_Generate CCA Release 2.54 Digital_Signature_Generate (CSNDDSG) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Digital_Signature_Generate verb is used to generate a digital signature. You specify: The RSA private key For X9.31, the hash formatting method The hash value The address where the verb returns the digital signature. The hash quantity may be created through use of the One_Way_Hash or the MDC_Generate verbs.
Digital_Signature_Generate CCA Release 2.54 rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below: Keyword Meaning Digital-signature-hash formatting method (one, optional) X9.31 Formats the hash according to the ANSI X9.31 standard and generates the digital signature. PKCS-1.
Digital_Signature_Generate CCA Release 2.54 hash_length The hash_length parameter is a pointer to an integer variable containing the number of bytes of data in the hash variable. hash The hash parameter is a pointer to a string variable containing the information to be signed. Notes: 1. For ISO-9796, the information identified by the hash parameter must be less than or equal to one-half of the number of bytes required to contain the modulus of the RSA key.
Digital_Signature_Verify CCA Release 2.54 Digital_Signature_Verify (CSNDDSV) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Digital_Signature_Verify verb is used to verify a digital signature. Provide the digital signature, the public key, the hash formatting method, and the hash of the data to be validated. The hash quantity may be created through use of the One_Way_Hash or the MDC_Generate verbs.
Digital_Signature_Verify CCA Release 2.54 Keyword Meaning Digital-signature-hash formatting method (one, optional, for RSA) X9.31 Format the hash according to the ANSI X9.31 standard and compare to the digital signature. See “Formatting Hashes and Keys in Public-Key Cryptography” on page D-19. PKCS-1.1 Format the hash as specified in the RSA Data Security, Inc., Public Key Cryptography Standards #1 block type 01 and compare to the digital signature.
Digital_Signature_Verify CCA Release 2.54 Notes: 1. For ISO-9796, the information identified by the hash parameter must be less than or equal to one-half of the number of bytes required to contain the modulus of the RSA key. Although ISO 9796-1 allows messages of arbitrary bit length up to one-half of the modulus length, this verb requires the input text to be a byte multiple up to the correct maximum length. 2. For PKCS-1.0 or PKCS-1.
MDC_Generate CCA Release 2.54 MDC_Generate (CSNBMDG) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X Use the MDC_Generate verb to create a 128-bit (16-byte) hash value on a data string whose integrity you intend to confirm. After using this verb to generate an MDC, you can compare the MDC to a known value or communicate the value to another entity so that they may compare the MDC hash value to one that they calculate.
MDC_Generate CCA Release 2.
MDC_Generate CCA Release 2.54 Figure 4-2 (Page 2 of 2). MDC_Generate Rule_Array Keywords Keyword Meaning Algorithm Mode (one, optional) PADMDC-2 Specifies two encipherments for each eight-byte block using PADMDC procedures. PADMDC-4 Specifies four encipherments for each eight-byte block using PADMDC procedures. MDC-2 Specifies two encipherments for each eight-byte block using MDC procedures. This is the default. Note: Use of the MDC-2 mode is not recommended.
One_Way_Hash CCA Release 2.54 One_Way_Hash (CSNBOWH) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The One_Way_Hash verb obtains a hash value from a text string using the MD5, SHA-1, or RIPEMD-160 hashing methods, as you specify in the rule_array. You can provide all of the data to be hashed in a single call to the verb, or you can provide the data to be hashed using multiple calls. Keywords that you supply in the rule_array inform the verb of your intention.
One_Way_Hash CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
One_Way_Hash CCA Release 2.54 hash_length The hash_length parameter is a pointer to an integer variable containing the number of bytes of data in the hash variable. This value must be at least 16 bytes for MD5, and at least 20 bytes for SHA-1. The maximum length is 128 bytes. hash The hash parameter is a pointer to a string variable containing the hash value returned by the verb. With use of the FIRST or MIDDLE keywords, the hash variable receives intermediate results.
CCA Release 2.54 4-16 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Chapter 5. DES Key-Management This chapter describes verbs to perform basic CCA DES key-management functions. Figure 5-1 lists the verbs covered in this chapter. Introductory material is presented under these topics: Figure Understanding CCA DES Key-Management Control vectors, key types, and key-usage restrictions Key tokens, key labels, and key identifiers Using the key-processing and key-storage verbs Security precautions. 5-1 (Page 1 of 2).
CCA Release 2.54 Figure 5-1 (Page 2 of 2). Basic CCA DES Key-Management Verbs Verb Page Service Entry Point Svc Lcn PKA_Decrypt 5-73 Uses an RSA private-key to decrypt a symmetric key formatted in an RSA DSI PKCS #1 block type 2 structure and return the symmetric key in the clear. CSNDPKD E PKA_Encrypt 5-75 Uses an RSA public-key to encrypt a clear symmetric-key in an RSA DSI PKCS #1 block type 2 structure and return the encrypted key.
CCA Release 2.54 functions in which it can be used. The cryptographic subsystem uses a system of control vectors1 to separate the cryptographic keys into a set of key types and restrict the use of a key. The subsystem enforces the use of a particular key type in each part of a cryptographic command. To control the use of a key, the control vector is combined with the key that is used to encipher the control vector's associated key.
CCA Release 2.54 A key that is multiply-enciphered under the master key is an operational key (OP). The key is operational because a cryptographic facility can use the master key to multiply-decipher it to obtain the original key-value. A key that is multiply-enciphered under a key-encrypting key (other than the master key) is called an external key.
CCA Release 2.54 Checking a Control Vector Before Processing a Cryptographic Command Before a CCA cryptographic facility processes a command that uses a multiply-enciphered key, the facility’s logic checks the control vector associated with the key. The control vector must indicate a valid key type for the requested command, and any control-vector restriction (key-usage) bits must be set appropriately for the command.
CCA Release 2.54 Asymmetric DES keys. An asymmetric DES key is a key in a key pair in which the keys are used as opposites. – ENCIPHER and DECIPHER. Used to only encrypt data versus only to decrypt data. – MAC and MACVER. Used in generating (and verifying) a MAC versus only verifying a MAC. – PINGEN and PINVER. Used in generating (and verifying) a personal identification number (PIN) versus only verifying a PIN. – OPINENC and IPINENC. Used to only encrypt a PIN block versus only to decrypt a PIN block.
CCA Release 2.54 Figure 5-4 on page 5-9 shows the key-type, key subtype, and key-usage keywords that can be combined in the Control_Vector_Generate verb and the Key_Token_Build verb to build a control vector. The left column lists the key types, the middle column lists the subtype keywords, and the right column lists the key-usage keywords that further define a control vector. Figure 5-5 on page 5-10 describes the control-vector-usage keywords.
CCA Release 2.54 Figure 5-3 (Page 2 of 2). Key Types and Verb Usage Key Type Usable with Verbs IKEYXLAT, OKEYXLAT Key_Translate PIN Class These keys are used in the various financial-PIN processing commands. They are double-length keys. In operational form and in external form, these keys are associated with a control vector.
CCA Release 2.54 ├─Key_Type─┤├─Key_Subtype─┤├─Key_Usage──────────────────────────────────────────────────────────────────────┤ ┬─MAC ─────┐ Note: ANY is default ├─MACVER───┴────────────────┬─────────┐ ├─DATA─────┐ ├─ANY─────┤ ├─CIPHER───┤ ├─ANSIX9.
CCA Release 2.54 Figure 5-5 (Page 1 of 3). Control Vector Key-Subtype and Key-Usage Keywords Keyword Meaning Key-Encrypting Keys OPIM IMPORTER keys that have a control vector with this attribute can be used in the Key_Generate verb when the key form is OPIM. IMEX IMPORTER and EXPORTER keys that have a control vector with this attribute can be used in the Key_Generate verb when the key form is IMEX.
CCA Release 2.54 Figure 5-5 (Page 2 of 3). Control Vector Key-Subtype and Key-Usage Keywords Keyword Meaning VISA-PVV Select the VISA-PVV PIN-calculation method. INBK-PIN Select the Interbank PIN-calculation method. NOOFFSET Indicates that a PINGEN or PINVER key cannot participate in the generation or verification of a PIN when an offset or the VISA-PVV process is requested. CPINGEN The key can participate in the Clear_PIN_Generate verb.
CCA Release 2.54 Figure 5-5 (Page 3 of 3). Control Vector Key-Subtype and Key-Usage Keywords Keyword Meaning DKYL5 A DKYGENKY key with this subtype can be used to generate a DKYGENKY key with a subtype of DKYL4. DKYL6 A DKYGENKY key with this subtype can be used to generate a DKYGENKY key with a subtype of DKYL5. DKYL7 A DKYGENKY key with this subtype can be used to generate a DKYGENKY key with a subtype of DKYL6.
CCA Release 2.54 8 16 32 6 63 ┌─────────┬─────────┬──────────────┬──────────────┬──────────────┬───────────┬─────┐ │Key│Flags │Control Infor-│ Internal Key │Control Vector│ │ TVV │ │Token │ │mation for │ or │ │ │ │ │Type │ │Using the Key │ External Key │ │ │ │ └─────────┴─────────┴──────────────┴──────────────┴──────────────┴───────────┴─────┘ Miscellaneous control information: token type (null, internal, or external), token version layout, and other information.
CCA Release 2.54 External Key-Token: An external key-token contains an external key that is multiply-enciphered under a key formed by the exclusive-OR of a key-encrypting key and the control vector that was assigned when the key token was created or updated. An external key-token is specified in a verb call using a key_token parameter. An external key-token resides in application storage.
CCA Release 2.54 Using the Key-Processing and Key-Storage Verbs Figure 5-8 on page 5-16 shows key-processing and key-storage verbs and how they relate to key parts, internal and external key-tokens, and key storage. You can create keys in your application programs by using the Multiple_Clear_Key_Import, Diversified_Key_Generate, Key_Generate, Key_Part_Import, Clear_Key_Import, and Random_Number_Generate verbs.
CCA Release 2.
CCA Release 2.54 master key or a key-encrypting key. If you are generating a DES asymmetric key-type, the verb will multiply-encipher the random number a second time with the “opposite” key-type control-vector. The verb restricts the combination of control vectors used for the two encipherments and also places restrictions on the use of master-key versus EXPORTER and IMPORTER encryption-key-types. This is done to ensure a secure, asymmetric key-distribution system.
CCA Release 2.54 Since the two halves are random numbers, it is unlikely that the result of the DOUBLE keyword will produce two halves with the same 64-bit values. Exporting and Importing Keys, Symmetric Techniques To operate on data with the same key at two different nodes, you must transport the key securely between the nodes. To do this, a transport key or key-encrypting key must be installed at both nodes.
CCA Release 2.
CCA Release 2.54 therefore it is very important to handle the key-generating key with a high degree of security lest the interactions with the whole population of cards be placed in jeopardy. In the current implementation, several methods of diversifying a key are supported: CLR8-ENC, TDES-ENC, TDES-DEC, SESS-XOR, TDES-XOR, and TDESEMV2 and TDESEMV4. The first two methods triple-encrypt data using the generating_key to form the diversified key.
CCA Release 2.54 Security Precautions Be sure to see the “Observations on Secure Operations” chapter in the CCA Support Program Installation Manual. In order to maintain a secure cryptographic environment, each cryptographic node must be audited on a regular basis. This audit should be aimed at preventing inadvertent and malicious breaches of security.
Clear_Key_Import CCA Release 2.54 Clear_Key_Import (CSNBCKI) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Clear_Key_Import verb enciphers a clear, single-length DES key under a symmetric master-key. The resulting key is a DATA key because the service requires that the resulting internal key-token have a DATA control-vector.
Clear_Key_Import CCA Release 2.54 Required Commands The Clear_Key_Import verb requires the Encipher Under Master Key command (command offset X'00C3') to be enabled in the active role. Chapter 5.
Control_Vector_Generate CCA Release 2.54 Control_Vector_Generate (CSNBCVG) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Control_Vector_Generate verb builds a control vector from keywords specified by the key_type and rule_array parameters. For descriptions of the keywords and for valid combinations of these keywords, see Figure 5-4 on page 5-9, “Key Types” on page 5-5, and “Key-Usage Restrictions” on page 5-6.
Control_Vector_Generate CCA Release 2.54 rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. For the valid combinations of keywords for the key type and the rule array, see Figure 5-4 on page 5-9.
Control_Vector_Translate CCA Release 2.54 Control_Vector_Translate (CSNBCVT) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Control_Vector_Translate verb changes the control vector used to encipher an external key. See “Changing Control Vectors with the Control_Vector_Translate Verb” on page C-20 for additional information about this verb.
Control_Vector_Translate CCA Release 2.54 mask_array_left The mask_array_left parameter is a pointer to a string variable containing the mask array enciphered under the left-array key. array_key_right The array_key_right parameter is a pointer to a string variable containing an internal key-token or the key label of an internal key-token record that deciphers the right mask-array. The internal key-token must contain a control vector specifying a CVARXCVR key-type.
Control_Vector_Translate CCA Release 2.54 target_key_token The target_key_token parameter is a pointer to a string variable containing an external key-token with the new control-vector. This key token contains the key halves with the new control-vector. Required Commands The Control_Vector_Translate verb requires the Translate Control Vector command (offset X'00D6') to be enabled in the active role. 5-28 IBM 4758 CCA Basic Services, Release 2.
Cryptographic_Variable_Encipher CCA Release 2.54 Cryptographic_Variable_Encipher (CSNBCVE) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Cryptographic_Variable_Encipher verb uses a CVARENC key to encrypt plaintext to produce ciphertext using the Cipher Block Chaining (CBC) method. The plaintext must be a multiple of eight bytes in length.
Cryptographic_Variable_Encipher CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. c-variable_encrypting_key_identifier The c-variable_encrypting_key_identifier parameter is a pointer to a string variable containing an internal key-token or a key label of an internal key-token record in key storage.
Data_Key_Export CCA Release 2.54 Data_Key_Export (CSNBDKX) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Data_Key_Export verb exports a single-length or double-length internal DATA-key. The verb can export the key from an internal key-token in key storage or application storage.
Data_Key_Export CCA Release 2.54 target_key_token The target_key_token parameter is a pointer to a string variable containing the reencrypted source-key token. Any existing information in this variable will be overwritten. Required Commands The Data_Key_Export verb requires the Data Key Export command (command offset X'010A') to be enabled in the active role.
Data_Key_Import CCA Release 2.54 Data_Key_Import (CSNBDKM) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Data_Key_Import verb imports an encrypted, source DES single-length or double-length DATA key and creates or updates a target internal key-token with the master-key-enciphered source key. The verb can import the key into an internal key-token in application storage or in key storage.
Data_Key_Import CCA Release 2.54 Restrictions Starting with Release 2.41, unless you enable the Unrestrict Data Key Import command (offset X'027C'), an IMPORTER transport key having replicated key-halves is not permitted to import a key having unequal key-halves. (Note that key parity bits are ignored.
Diversified_Key_Generate CCA Release 2.54 Diversified_Key_Generate (CSNBDKG) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Diversified_Key_Generate verb generates a key based on a function of a key-generating key, the process rule, and data that you supply. The key-generating-key key-type enables you to restrict such keys from being used in other verbs that might reveal the value of a diversified key.
Diversified_Key_Generate CCA Release 2.54 Returns the diversified key, multiply-enciphered by the master key modified by the control vector. Restrictions The TDES-XOR rule-array keyword is available starting with Release 2.50. The TDESEMV2 and TDESEMV4 rule-array keywords are available starting with Release 2.51.
Diversified_Key_Generate CCA Release 2.54 Keyword Meaning TDES-ENC Specifies that 8 or 16 bytes of clear (not encrypted) data shall be triple-DES encrypted with the generating key to create the generated key. If the generated_key_identifier variable specifies a single-length key, then 8 bytes of clear data is triple-DES encrypted. If the generated_key_identifier variable specifies a double-length key, then 16 bytes of clear data is triple-DES encrypted in ECB mode.
Diversified_Key_Generate CCA Release 2.54 Keyword Meaning TDESEMV2, TDESEMV4 Note: These options are available starting with Release 2.51. Specifies that 10, 18, 26, or 34 bytes of clear data shall be processed to form an EMV card-unique key and then a session key as specified in the EMV 2000 Integrated Circuit Card Specification for Payment Systems Version 4.0 (EMV4.0) Book 2, Annex A1.3. See “VISA and EMV-Related Smart Card Formats and Processes” on page E-17 for additional details.
Diversified_Key_Generate CCA Release 2.54 Keyword Meaning TDES-XOR Note: This option is available starting with Release 2.50. Specifies that 10 or 18 bytes of clear (not encrypted) data shall be processed as described at “VISA and EMV-Related Smart Card Formats and Processes” on page E-17 to create the generated key. The data variable contains either 8 or 16 bytes of data to be triple-encrypted to which you append a 2-byte Application Transaction Counter value (previously received from the smart card).
Diversified_Key_Generate CCA Release 2.54 generating_key_identifier The generating_key_identifier parameter is a pointer to a string variable containing the key-generating-key key-token or key label of a key-token record. data_length The data_length parameter is a pointer to an integer variable containing the number of bytes of data in the data variable. data The data parameter is a pointer to a string variable containing the information used in the key-generation process.
CCA Release 2.54 Diversified_Key_Generate effective single-length key) by enabling the Enable DKG Single Length Keys and Equal Halves for TDES-ENC, TDES-DEC command (offset X'0044'). Chapter 5.
Key_Export CCA Release 2.54 Key_Export (CSNBKEX) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Export verb exports a source DES internal-key into a target external key-token. Existing information in the target key-token is overwritten. The target key is enciphered by the EXPORTER-key exclusive-ORed with the control vector of the target key. Specify the following: Key_type A keyword for the key type. Use of the TOKEN keyword is the preferred coding style.
Key_Export CCA Release 2.54 Format CSNBKEX return_code reason_code exit_data_length exit_data key_type source_key_identifier exporter_key_identifier target_key_token Output Output In/Output In/Output Input Input Input Output Integer Integer Integer String String String String String exit_data_length bytes 8 bytes 64 bytes 64 bytes 64 bytes Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11.
Key_Generate CCA Release 2.54 Key_Generate (CSNBKGN) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Generate verb generates a random DES key and returns one or two enciphered copies of the key, ready to use or distribute. A control vector associated with each copy of the key defines the type of key and any specific restrictions on the use of the key. Only certain combinations of key types are permitted when you request two copies of a key.
Key_Generate CCA Release 2.
Key_Generate CCA Release 2.54 key_length The key_length parameter is a pointer to an eight-byte string variable, left-justified and padded on the right with space characters, containing the length of the new key or keys. Depending on key type, you can specify a single-length key or a double-length key. A double-length key consists of two eight-byte values.
Key_Generate CCA Release 2.54 unless you are using the TOKEN keyword, you must identify a null key-token on input. Required Commands Depending on your specification of key form, key type, and use of the SINGLE-R key length control, different commands are required to enable operation of the Key_Generate verb.
Key_Generate CCA Release 2.54 can use to generate a single key copy with default control-vectors. Figure 5-12 on page 5-49 shows the key types you can use to generate two copies of a key. An ‘X’ indicates a permissible key type for a given key-form. An E indicates that a special (Extended) command is required as those keys require special handling. You can generate a single-length key with any control vector value9. when you specify SINGLE and OP.
Key_Generate CCA Release 2.54 Figure 5-12.
Key_Generate CCA Release 2.54 key-length the verb uses when you supply eight space characters with the key_length parameter. Figure 5-13.
Key_Import CCA Release 2.54 Key_Import (CSNBKIM) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Import verb imports a source DES key enciphered by the IMPORTER key-encrypting-key into a target internal key-token. The imported target-key is returned enciphered using the symmetric master-key. Specify the following: Key_type A keyword for the key type. Use of the TOKEN keyword is the preferred coding style.
Key_Import CCA Release 2.54 Restrictions Starting with Release 2.41, unless you enable the Unrestrict Reencipher to Master Key command (offset X'027B'), an IMPORTER key-encrypting-key having equal key-halves is not permitted to import a key having unequal key-halves. Note that key parity bits are ignored.
CCA Release 2.54 Key_Import key-halves IMPORTER key-encrypting-key to import a key having unequal key-halves (key parity bits are ignored). Chapter 5.
Key_Part_Import CCA Release 2.54 Key_Part_Import (CSNBKPI) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Part_Import verb is used to accumulate “parts” of a key and store the result as an encrypted partial key or as the final key. Individual key-parts are exclusive-ORed together to form the accumulated key.
Key_Part_Import CCA Release 2.54 of one bits, and there are no other problems, the verb will return reason code 2. Use of the ADD-PART keyword requires that the Add Key Part command be enabled in the access-control system. The key-part bit remains on in the control vector of the updated key token returned from the verb. With the COMPLETE keyword, the key-part bit is set off in the control vector of the updated key token returned from the verb.
Key_Part_Import CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
Key_Part_Import CCA Release 2.54 Required Commands The Key_Part_Import verb requires the following commands to be enabled in the active role: The Load First Key Part command (offset X'001B') with the FIRST keyword. The Combine Key Parts command (offset X'001C') with the MIDDLE and LAST keywords. The Add Key Part command (offset X'0278') with the ADD-PART keyword. The Complete Key Part command (offset X'0279') with the COMPLETE keyword.
Key_Test CCA Release 2.54 Key_Test (CSNBKYT) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X You use the Key_Test verb to verify the value of a key or key-part. Several verification algorithms are supported. The verb supports testing of clear keys, enciphered keys, master keys, and key-parts. The verification pattern and the verification processes do not reveal the value of an encrypted key, other than equivalency of two key values.
Key_Test CCA Release 2.
Key_Test CCA Release 2.54 Keyword Meaning Verification-process rule (one, optional) ENC-ZERO Specifies use of the “encrypt zeros” method. Use only with KEY-CLR, KEY-CLRD, KEY-ENC, or KEY-ENCD keywords. MDC-4 Specifies use of the MDC-4 master-key-verification method. Use only with KEY-NKM, KEY-KM, or KEY-OKM keywords.
Key_Token_Build CCA Release 2.54 Key_Token_Build (CSNBKTB) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Token_Build verb assembles an external or internal key-token in application storage from information you supply. The verb can include a control vector you supply or can build a control vector based on the key type and the control vector related keywords in the rule array. See Figure 5-4 on page 5-9.
Key_Token_Build CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. key_token The key_token parameter is a pointer to a string variable containing the assembled key-token. Note: This variable cannot contain a key label. key_type The key_type parameter is a pointer to a string variable containing a keyword that defines the key type.
Key_Token_Build CCA Release 2.54 Figure 5-15 (Page 2 of 2). Key_Token_Build Rule_Array Keywords Keyword Meaning Control-vector (CV) status (one, optional) Note: If you specify the USE-CV keyword in the key_type parameter, use the CV keyword here. CV Obtain the control vector from the variable identified by the control_vector parameter. NO-CV This keyword indicates that a control vector is to be supplied based on the key type and control-vector-related keywords. This is the default.
Key_Token_Change CCA Release 2.54 Key_Token_Change (CSNBKTC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 Use the Key_Token_Change verb to reencipher a DES key from encryption under the old master-key to encryption under the current master-key and to update the keys in internal DES key-tokens. Note: An application system is responsible for keeping all of its keys in a useable form.
Key_Token_Change CCA Release 2.54 Figure 5-16. Key_Token_Change Rule_Array Keywords Keyword Meaning RTCMK Reenciphers a DES key to the current master-key in an internal key-token in application storage or in key storage If the supplied key is already enciphered under the current master-key the verb returns a positive response (return code, reason code — 0, 0).
Key_Token_Parse CCA Release 2.54 Key_Token_Parse (CSNBKTP) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Key_Token_Parse verb disassembles a key token into separate pieces of information. The verb can disassemble an external key-token or an internal key-token in application storage. Use the key_token parameter to specify the key token to disassemble.
Key_Token_Parse CCA Release 2.54 Note: You cannot use a key label for a key-token record in key storage. The key token must be in application storage. key_type The key_type parameter is a pointer to a string variable containing a keyword defining the key type. The keyword is eight bytes in length, and must be left-justified and padded on the right with space characters.
Key_Token_Parse CCA Release 2.54 key_value The key_value parameter is a pointer to a string variable. If the verb returns the KEY keyword in the rule array, the key-value variable contains the 16-byte enciphered key. MKVP The MKVP parameter is a pointer to an integer variable. The verb writes zero into the variable except when parsing a version X'03' internal key-token. reserved_2/5 The reserved_2 and reserved_5 parameters are either null pointers or pointers to integer variables.
Key_Translate CCA Release 2.54 Key_Translate (CSNBKTR) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Key_Translate verb uses one key-encrypting key to decipher an input key and then enciphers this key using another key-encrypting key within the secure environment. Specify the following key tokens to use this verb: The external (input) key-token containing the key to be reenciphered. The internal key-token containing the IMPORTER or IKEYXLAT key-encrypting-key.
Key_Translate CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. input_key_token The input_key_token parameter is a pointer to a string variable containing an external key-token. The external key-token contains the key to be reenciphered (translated).
Multiple_Clear_Key_Import CCA Release 2.54 Multiple_Clear_Key_Import (CSNBCKM) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Multiple_Clear_Key_Import verb multiply-enciphers a clear, single-length or double-length DES DATA key under a symmetric master-key. You can use this verb to create an internal key-token from a null key token. In this case, the control vector will be set to the value of a single-length or double-length default control-vector.
Multiple_Clear_Key_Import Keyword CCA Release 2.54 Meaning Algorithm (optional) DES The key should be enciphered under the master key as a DES key. This is the default. clear_key_length The clear_key_length parameter is a pointer to an integer variable containing the number of bytes of data in the clear_key variable. clear_key The clear_key parameter is a pointer to a string variable containing the single-length (8-byte) or double-length (16-byte) plaintext DES-key to be imported.
PKA_Decrypt CCA Release 2.54 PKA_Decrypt (CSNDPKD) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Decrypt verb decrypts (unwraps) input data using an RSA private-key. The decrypted data is examined to ensure it meets RSA DSI PKCS #1 block type 2 format specifications. See “PKCS #1 Formats” on page D-19. Restrictions 1. A key-usage flag bit (see offset 050 in the private-key section) must be on to permit use of the private key in the decryption of a symmetric key.
PKA_Decrypt CCA Release 2.54 Keyword Meaning Recovery method (required) PKCS-1.2 Specifies the method found in RSA DSI PKCS #1 block type 02 documentation. In the RSA PKCS #1 v2.0 standard, RSA terminology describes this as the RSAES-PKCS1-v1_5 format. source_encrypted_key_length The source_encrypted_key_length parameter is a pointer to an integer variable containing the number of bytes of data in the source_encrypted_key variable. The maximum size allowed is 256 bytes.
PKA_Encrypt CCA Release 2.54 PKA_Encrypt (CSNDPKE) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Encrypt verb encrypts (wraps) input data using an RSA public key. The data that you encrypt may include: For keys, the encrypted data can be formatted according to RSA DSI PKCS #1 block type 2 format specifications. See “PKCS #1 Formats” on page D-19. Other data, such as a digital signature, can be RSA-ciphered using the public key and the ZERO-PAD option.
PKA_Encrypt CCA Release 2.54 rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below: Keyword Meaning Format method (one required) PKCS-1.2 Specifies the method found in RSA DSI PKCS #1 block type 02 documentation. In the RSA PKCS #1 v2.
PKA_Encrypt CCA Release 2.54 target_data The target_data parameter is a pointer to a string variable containing the encrypted data returned by the verb. The returned encrypted target-data is the same length as the public-key modulus. Required Commands The PKA_Encrypt verb requires the RSA Public-Key Encipher Clear Key-Data command (offset X'011E') to be enabled in the hardware. Chapter 5.
PKA_Symmetric_Key_Export CCA Release 2.54 PKA_Symmetric_Key_Export (CSNDSYX) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Symmetric_Key_Export verb enciphers a symmetric DES or CDMF default DATA-key using an RSA public key. Specify the symmetric key to be exported, the exporting RSA public-key, and a rule-array keyword to define the key-formatting method.
PKA_Symmetric_Key_Export CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
PKA_Symmetric_Key_Export CCA Release 2.54 RSA_enciphered_key The RSA_enciphered_key parameter is a pointer to a string variable containing the exported RSA-enciphered key returned by the verb. Required Commands The PKA_Symmetric_Key_Export verb requires these commands to be enabled in the hardware for exporting various key types: Symmetric Key Export PKCS-1.2/OAEP command (offset X'0105') for DATA keys using the PKCSOAEP and PKCS-1.
PKA_Symmetric_Key_Generate CCA Release 2.54 PKA_Symmetric_Key_Generate (CSNDSYG) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Symmetric_Key_Generate verb generates a random DES-key and enciphers the key value. The key value is enciphered under an RSA public-key for distribution to a remote node (that has the associated private key). The key value is also multiply-enciphered under either the symmetric master-key or a DES key-encrypting-key.
PKA_Symmetric_Key_Generate CCA Release 2.54 Key-encrypting keys, either effective single-length or true double-length, are generated with the details dependent on the keyword you use to control the key formatting technique. PKA92 With this keyword, the verb generates a key-encrypting key and returns two copies of the key. You must specify a pair of complementary control vectors that conform to the rules for an OPEX case as defined for the Key_Generate verb.
PKA_Symmetric_Key_Generate CCA Release 2.
PKA_Symmetric_Key_Generate Keyword CCA Release 2.54 Meaning Key length (optional use with PKCSOAEP, PKCS-1.2, and ZERO-PAD) SINGLE KEYLN8 Specifies that an exported DATA key should be single length. This the default. DOUBLE KEYLN16 Specifies that an exported DATA key should be double length. DES encipherment (optional use with PKCSOAEP, PKCS-1.2, and ZERO-PAD) OP Enciphers one key copy with the symmetric master-key. This is the default.
PKA_Symmetric_Key_Generate CCA Release 2.54 RSA_enciphered_key_token_length The RSA_enciphered_key_token_length parameter is a pointer to an integer variable containing the number of bytes of data in the RSA_enciphered_key_token variable. On output, the variable is updated with the actual length of the RSA_enciphered_key_token variable. The maximum size allowed is 2500 bytes.
PKA_Symmetric_Key_Import CCA Release 2.54 PKA_Symmetric_Key_Import (CSNDSYI) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The PKA_Symmetric_Key_Import verb recovers a symmetric DES (or CDMF) key that is enciphered by an RSA public key. The verb deciphers the RSA-enciphered symmetric-key to be imported by using an RSA private-key, then multiply-enciphers the symmetric DES-key using the master key and a control vector.
PKA_Symmetric_Key_Import CCA Release 2.54 Restrictions 1. Private key key-usage controls can prevent use of specific private keys in this verb. See page 3-7. A key-usage flag bit (see offset 050 in the private-key section) must be on to permit use of the private key in the decryption of a symmetric key. 2. The RSA private-key modulus size (key size) is limited by the Function Control Vector to accommodate potential governmental export and import regulations. 3.
PKA_Symmetric_Key_Import Keyword CCA Release 2.54 Meaning RSA key-encipherment method (one required) PKCSOAEP Specifies the method found in RSA DSI PKCS#1-v2.0 RSAES-OAEP documentation. PKCS-1.2 Specifies the method found in RSA DSI PKCS#1-v2.0 RSAES-PKCS1-v1_5 specification. ZERO-PAD Specifies that a DES (or CDMF) DATA-key can be imported with the key value padded from the left with bits valued to zero. PKA92 Specifies the PKA92 method of key encipherment for key-encrypting keys.
CCA Release 2.54 PKA_Symmetric_Key_Import Symmetric Key Import ZERO-PAD command (command offset X'023D') for DATA keys using the ZERO-PAD methods PKA92 Symmetric Key Import command (command offset X'0235') when importing key-generating keys using the PKA92 method PKA92 Symmetric Key Import command (command offset X'0236') when importing PINGEN, PINVER, IPINENC, or OPINENC keys using the PKA92 method. Chapter 5.
Prohibit_Export CCA Release 2.54 Prohibit_Export (CSNBPEX) Platform/ Product OS/2 AIX NT OS/400 X X X X IBM 4758-2/23 The Prohibit_Export verb modifies an operational key than can be exported so that it can no longer be exported. The verb does the following: Multiply-deciphers the key under a key formed by the exclusive-OR of the master key and the control vector.
Random_Number_Generate CCA Release 2.54 Random_Number_Generate (CSNBRNG) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Random_Number_Generate verb generates a random number for use as an initialization vector, clear key, or clear key-part. You specify whether the random number is 64 bits, or 56 bits with the low-order bit in each of the eight bytes adjusted for even or odd parity. The verb returns the random number in an eight-byte binary field.
Random_Number_Generate CCA Release 2.54 random_number The random_number parameter is a pointer to a string variable containing the random number returned by the verb. Required Commands The Random_Number_Generate verb requires the Generate Key command (offset X'008E') to be enabled in the hardware. 5-92 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Chapter 6. Data Confidentiality and Data Integrity This chapter describes the verbs that use the Data Encryption Standard (DES) algorithm to encrypt and decrypt data and to generate and verify a message authentication code (MAC). Figure 6-1.
CCA Release 2.54 verbs also support the ANSI X9.23 mode of encryption. In X9.23 encryption, at least one byte of data and up to eight bytes of data are always added to the end of your plaintext. The last of the added bytes is a binary value equal to the number of added bytes. The ANSI X9.23 process ensures that the enciphered data is always a multiple of eight bytes as required for CBC encryption. In X9.23 decryption, the padding is removed from the decrypted plaintext.
CCA Release 2.54 Ensuring Data Integrity CCA offers three classes of services for ensuring data integrity: Message authentication code (MAC) techniques based on the DES algorithm Hashing techniques Digital signature techniques. This chapter includes the MAC verbs. For information on using hashing or digital signatures to ensure the integrity of data, see Chapter 4, “Hashing and Digital Signatures.
CCA Release 2.54 In each procedure call, a segmenting-control keyword indicates whether the call contains the first, middle, or last unit of segmented data; the chaining_vector parameter specifies the work area that the verb uses. (The default segmenting-control keyword ONLY specifies that segmenting is not used.) 6-4 IBM 4758 CCA Basic Services, Release 2.
Decipher CCA Release 2.54 Decipher (CSNBDEC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Decipher verb uses the Data Encryption Standard (DES) or the Commercial Data Masking Facility (CDMF) algorithm and a cipher key to decipher data (ciphertext). This verb results in data called plaintext. Performance can be enhanced if you align the start of the plaintext and ciphertext variables on a four-byte boundary.
Decipher CCA Release 2.54 ciphertext The ciphertext parameter is a pointer to a string variable containing the text to be deciphered. initialization_vector The initialization_vector parameter is a pointer to a string variable containing the initialization_vector the verb uses with the input data. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. This value must be zero, one, two, or three for this verb.
Decipher CCA Release 2.54 length of the plaintext when it returns. The length will be different when padding is removed. Required Commands The Decipher verb requires the Decipher command (offset X'000F') to be enabled in the hardware. Chapter 6.
Encipher CCA Release 2.54 Encipher (CSNBENC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Encipher verb uses the DES algorithm and a secret key to encipher data. This verb returns data called ciphertext. The returned ciphertext can be as many as eight bytes longer than the plaintext due to padding. Ensure the ciphertext variable is large enough to receive the returned data.
Encipher CCA Release 2.54 text_length The text_length parameter is a pointer to an integer variable. On input, the text_length variable contains the number of bytes of data in the cleartext variable. On output, the text_length variable contains the number of bytes of data in the ciphertext variable. plaintext The plaintext parameter is a pointer to a string variable containing the text to be enciphered.
Encipher CCA Release 2.54 chaining_vector The chaining_vector parameter is a pointer to a string variable containing a work area that the security server uses to carry segmented data between procedure-calls. Note: The application program must not change the data in this variable. ciphertext The ciphertext parameter is a pointer to a string variable containing the enciphered text returned by the verb. The starting address of the ciphertext variable cannot begin within the plaintext variable.
MAC_Generate CCA Release 2.54 MAC_Generate (CSNBMGN) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The MAC_Generate verb generates a message authentication code (MAC) for a text string that you supply. For additional information about using the MAC generation and verification verbs, see “Ensuring Data Integrity” on page 6-3. Performance can be enhanced by aligning the start of the text variable on a four-byte boundary.
MAC_Generate CCA Release 2.
MAC_Generate CCA Release 2.54 Keyword Meaning Segmenting control (one, optional) ONLY Specifies the application program does not use segmenting. This is the default. FIRST Specifies this is the first segment of data from the application program. MIDDLE Specifies this is an intermediate segment of data from the application program. LAST Specifies this is the last segment of data from the application program. MAC length and presentation (one, optional) MACLEN4 Specifies a four-byte MAC.
MAC_Verify CCA Release 2.54 MAC_Verify (CSNBMVR) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The MAC_Verify verb verifies a message authentication code (MAC) for a text string that you supply. For additional information about using the MAC generation and verification verbs, see “Ensuring Data Integrity” on page 6-3. Performance can be enhanced by aligning the start of the text variable on a four-byte boundary.
MAC_Verify CCA Release 2.
MAC_Verify CCA Release 2.54 Keyword Meaning Segmenting control (one, optional) ONLY Specifies the application program does not use segmenting. This is the default. FIRST Specifies this is the first segment of data from the application program. MIDDLE Specifies this is an intermediate segment of data from the application program. LAST Specifies this is the last segment of data from the application program. MAC length and presentation (one, optional) MACLEN4 Specifies a four-byte MAC.
CCA Release 2.54 Chapter 7. Key-Storage Verbs This chapter describes how you can use key-storage mechanisms and the associated verbs for creating, writing, reading, listing, and deleting records in key storage. Figure 7-1. Key-Storage-Record Services Verb Page Service Entry Point Svc Lcn DES_Key_Record_Create 7-4 Creates a key record in DES key-storage. CSNBKRC S DES_Key_Record_Delete 7-5 Deletes a key record or deletes the key token from a key record in DES key-storage.
CCA Release 2.54 Use the Key_Record_Delete verb to delete a key token from a key record, or to entirely delete the key record from key storage. Use the Key_Record_List verb to determine the existence of key records in key storage. The Key_Record_List verb creates a key-record-list data set with information about select key-records. The wild-card character (*) is used to obtain information about multiple key-records. The data set can be read using conventional workstation-data-management services.
CCA Release 2.54 Some verbs accept a key label containing a “wild card” represented by an asterisk (*). (X'2A' in ASCII; X'5C' in EBCDIC). When a verb permits the use of a wild card, the wild card can appear as the first character, as the last character, or as the only character in a name token. Any of the name tokens can contain a wild card. Examples of valid key labels include the following: A ABCD.2.3.4.5555 ABCDEFGH BANKSYS.XXXXX.43 . PDQ Examples of invalid key labels include the following: A/.
DES_Key_Record_Create CCA Release 2.54 DES_Key_Record_Create (CSNBKRC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The DES_Key_Record_Create verb adds a key record with a null key-token to DES key-storage. It is identified by the key label specified using the key_label parameter.
DES_Key_Record_Delete CCA Release 2.54 DES_Key_Record_Delete (CSNBKRD) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The DES_Key_Record_Delete verb does either of the following tasks: Replaces the token in a key record with a null key-token Deletes an entire key record, including the key label, from key storage. Identify the task with the rule_array keyword, and the key record with the key_label parameter.
DES_Key_Record_Delete CCA Release 2.54 key_label The key_label parameter is a pointer to a string variable containing the key label of a key-token record in key storage. In a key label, use a wild card (*) to identify multiple records in key storage. Required Commands The DES_Key_Record_Delete verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in the access-control system. 7-6 IBM 4758 CCA Basic Services, Release 2.
DES_Key_Record_List CCA Release 2.54 DES_Key_Record_List (CSNBKRL) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The DES_Key_Record_List verb creates a key-record-list data set containing information about specified key records in key storage. Information listed includes whether record validation is correct, the type of key, and the date and time the record was created and last updated. Specify the key records to be listed using the key-label variable.
DES_Key_Record_List CCA Release 2.54 data_set_name_length The data_set_name_length parameter is a pointer to an integer variable containing the number of bytes of data returned by the verb in the data_set_name variable. The maximum returned value is 64 bytes. data_set_name The data_set_name parameter is a pointer to a 64-byte string variable containing the name of the data set returned by the verb. The data set contains the key-record information.
DES_Key_Record_Read CCA Release 2.54 DES_Key_Record_Read (CSNBKRR) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The DES_Key_Record_Read verb copies a key token from DES key-storage to application storage. The returned key-token can be null.
DES_Key_Record_Write CCA Release 2.54 DES_Key_Record_Write (CSNBKRW) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The DES_Key_Record_Write verb copies an internal DES key-token from application storage into DES key-storage. Before you use the DES_Key_Record_Write verb, use DES_Key_Record_Create to create a key record.
PKA_Key_Record_Create CCA Release 2.54 PKA_Key_Record_Create (CSNDKRC) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Record_Create service adds a key record with a null key-token to PKA key-storage. The new key-record may be a null key-token or a valid PKA internal or external key-token. It is identified by the key label specified with the key_label parameter.
PKA_Key_Record_Create CCA Release 2.54 key_token_length The key_token_length parameter is a pointer to an integer variable containing the number of bytes of data in the key_token variable. If the value of the key_token_length variable is zero, a record with a null PKA key-token is created. key_token The key_token parameter is a pointer to a string variable containing the key token being written to PKA key-storage.
PKA_Key_Record_Delete CCA Release 2.54 PKA_Key_Record_Delete (CSNDKRD) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Record_Delete verb does either of the following tasks: Replaces the token in a key record with a null key-token Deletes an entire key-record, including the key label, from key storage. Identify the task with the rule_array keyword, and the key record with the key_label parameter.
PKA_Key_Record_Delete CCA Release 2.54 key_label The key_label parameter is a pointer to a string variable containing the key label of a key-token record in PKA key-storage. Use a wild card (*) in the key_label variable to identify multiple records in key storage. Required Commands The PKA_Key_Record_Delete verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in the access-control system. 7-14 IBM 4758 CCA Basic Services, Release 2.
PKA_Key_Record_List CCA Release 2.54 PKA_Key_Record_List (CSNDKRL) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Record_List verb creates a key-record-list data set containing information about specified key records in PKA key-storage. Information includes whether record validation is correct, the type of key, and the dates and times when the record was created and last updated. Specify the key records to be listed using the key_label variable.
PKA_Key_Record_List CCA Release 2.54 rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be zero for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. Currently this verb does not use keywords and this field is ignored.
PKA_Key_Record_Read CCA Release 2.54 PKA_Key_Record_Read (CSNDKRR) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Record_Read verb copies a key token from PKA key-storage to application storage. The returned key-token may be null. In this event, the key_length variable contains a value of eight and the key-token variable contains eight bytes of X'00' beginning at offset zero (see “Null Key-Token” on page B-2).
PKA_Key_Record_Read CCA Release 2.54 key_token The key_token parameter is a pointer to a string variable containing the key token read from PKA key-storage. This variable must be large enough to hold the PKA key-token being read. On successful completion, the key_token_length variable contains the actual length of the token being returned. Required Commands The PKA_Key_Record_Read verb requires the Compute Verification Pattern command (offset X'001D') to be enabled in the access-control system.
PKA_Key_Record_Write CCA Release 2.54 PKA_Key_Record_Write (CSNDKRW) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The PKA_Key_Record_Write verb copies an internal or external PKA key-token from application storage into PKA key-storage. The verb performs either of these two processing options: Writes the new key-token only if the old token was null Writes the new key-token regardless of content of the old token.
PKA_Key_Record_Write CCA Release 2.54 Figure 7-4. PKA_Key_Record_Write Rule_Array Keywords Keyword Meaning Processing option (one, optional) CHECK Specifies that the record will be written only if a record of the same label in PKA key-storage contains a null key-token. This is the default. OVERLAY Specifies that the record will be overwritten regardless of the current content of the record in PKA key-storage.
Retained_Key_Delete CCA Release 2.54 Retained_Key_Delete (CSNDRKD) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Retained_Key_Delete verb deletes a PKA key that has been retained within the Coprocessor. You can retain both public and private keys within the Coprocessor through the use of verbs such as PKA_Key_Generate and PKA_Public_Key_Register. A list of retained keys can be obtained with the use of the Retained_Key_List verb.
Retained_Key_List CCA Release 2.54 Retained_Key_List (CSNDRKL) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The Retained_Key_List verb lists the key labels of those PKA keys that have been retained within the Coprocessor. You filter the set of key labels returned to your application through the use of the key label mask input variable. Specify the keys to be listed using the key_label_mask variable. To identify multiple keys, use the wild card (*) in a mask.
Retained_Key_List CCA Release 2.54 key_label_mask The key_label_mask parameter points to a string variable containing a key label mask that is used to filter the list of key names returned by the verb. You can use a wild card (*) to identify multiple keys retained within the Coprocessor. retained_keys_count The retained_keys_count parameter points to an integer variable to receive the total number of retained keys stored within the Coprocessor.
CCA Release 2.54 7-24 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Chapter 8. Financial Services Support Verbs There are several classes of verbs described in this chapter: Finance industry PIN processing verbs. Information common to these verbs is described in the next section. Support for changing the acceptable PIN on a smart card based on VISA and EMV design concepts.
CCA Release 2.54 Figure 8-1 (Page 2 of 2). Financial Services Support Verbs Verb Page Service Entry Point Svc Lcn PIN_Change/Unblock 8-52 Calculates a PIN for a smart card based on keys and data you supply according to VISA and EMV specifications. CSNBPCU E Secure_Messaging_for_Keys 8-59 Securely incorporates a key into a text block which is then encrypted (generally for use with EMV smart cards).
CCA Release 2.54 – – – – – – Create encrypted PIN blocks for transmission Generate institution-assigned PINs Generate an offset or a VISA PIN-validation value (PVV) Create encrypted PIN blocks for a PIN-verification database Change the PIN-block encrypting key or the PIN-block format Verify PINs. Normally, a customer inserts a magnetic-stripe card and enters a PIN (a trial PIN) into an automated teller machine to identify himself.
CCA Release 2.
CCA Release 2.54 PIN-Verb Summary The following terms are used for the various “PIN” values: A-PIN The quantity derived from a function of the account number, and PIN-generating key, and other inputs such as a decimalization table. C-PIN The quantity that a customer should use to identify himself. In general, this can be a customer-selected or institution-assigned quantity. O-PIN A quantity, sometimes called an offset, that relates the A-PIN to the C-PIN as permitted by certain calculation methods.
CCA Release 2.54 PIN-Calculation Method and PIN-Block Format Summary As described in the following sections, you can use a variety of PIN calculation methods and a variety of PIN-block formats with the various PIN-processing verbs. Figure 8-3 provides a summary of the supported combinations. Figure 8-3.
CCA Release 2.54 Using Specific Key Types and Key-Usage Bits to Help Ensure PIN Security The control vectors (see Appendix C, “CCA Control-Vector Definitions and Key Encryption” on page C-1) associated with obtaining and verifying PINs enable you to minimize certain security exposures. The class of keys designated PINGEN operates in the verbs that create and validate PIN values, whereas the PINVER class operates only in those verbs that validate a PIN.
CCA Release 2.54 OPINENC (output PIN-block encrypting) key type The PIN verbs that encrypt a PIN block require the encrypting key to have a control vector that specifies an OPINENC key type. KEYGENKY (unique-key-per-transaction base key-generating key) key type The Encrypted_PIN_Translate and Encrypted_PIN_Verify verbs can derive a unique key from the KEYGENKY derivation key and current-key-serial-number to decrypt or encrypt a PIN block.
CCA Release 2.54 Note: To avoid errors when using the IBM 3624 PIN-block format, you should not include in the decimalization table a decimal digit that is also used as a pad digit. For information about a pad digit, see “PIN Profile” on page 8-10. validation_data The second element in the data array for a PIN-calculation method supplies 1 to 16 characters of account data, which can be the customer’s account number or other identifying number.
CCA Release 2.54 – Eleven (rightmost) digits of PAN data, excluding the check digit. For information about a PAN, see “Personal Account Number (PAN)” on page 8-13. – A constant, six. – A one-digit key index selector from one to six. – Three numeric characters of validation data. reserved The second and third elements in the data array for the Interbank calculation method are reserved. These elements point to 16-byte variables in application storage.
CCA Release 2.54 PIN-Block Format Keyword IBM 3624 3624 ISO-0 (equivalent to ANSI X9.8, VISA format 1, and ECI-1 formats) ISO-0 ISO-1 (same as the ECI-4 format) ISO-1 ISO-2 ISO-2 EMV-PIN-change VISAPCU1 VISAPCU2 Format Control Enforcement: The format-control level is the second element in a PIN profile. For the IBM 4758 implementation, this element must be set to NONE followed by four space characters. Pad Digit: The pad digit is the third element in a PIN profile.
CCA Release 2.54 The CKSN is the concatenation of a terminal identifier and a sequence number which together define a unique terminal (within the set of terminals associated with a given base key) and the sequence number of the transaction originated by that terminal. Each time the terminal completes a transaction, it increments the sequence number and modifies the transaction-encryption key retained within the terminal.
CCA Release 2.54 Personal Account Number (PAN) A personal account number (PAN) identifies an individual and relates that individual to an account at the financial institution. The PAN consists of the following: Issuer identification number Customer account number One check digit. For the ISO-0 PIN-block format, the PIN verbs use a PAN to format and extract a PIN. You specify the PAN with a PAN_data parameter for the verb. You must specify the PAN in character format in a 12-byte field.
CCA Release 2.54 The MAC_Generate and MAC_Verify verbs incorporate post-padding a X'80'...X'00' string to a message as required for authenticating messages exchanged with EMV smart cards. 8-14 IBM 4758 CCA Basic Services, Release 2.
Clear_PIN_Encrypt CCA Release 2.54 Clear_PIN_Encrypt (CSNBCPE) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Clear_PIN_Encrypt verb formats a PIN into one of the following PIN-block formats and encrypts the results (see “PIN-Block Formats” on page E-9): IBM 3624 format ISO-0 format (same as the ANSI X9.8, VISA-1, and ECI formats) ISO-1 format (same as the ECI-4 format) ISO-2 format.
Clear_PIN_Encrypt CCA Release 2.
Clear_PIN_Encrypt CCA Release 2.54 PIN_profile The PIN_profile parameter points to a string variable containing three 8-byte elements with: a PIN-block format keyword, a format control keyword (NONE), and a pad digit as required by certain formats. See “PIN Profile” on page 8-10. PAN_data The PAN_data parameter points to a personal account number (PAN) in character format. The verb uses this parameter if the PIN profile specifies the ISO-0 keyword for the PIN-block format.
Clear_PIN_Generate CCA Release 2.54 Clear_PIN_Generate (CSNBPGN) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Clear_PIN_Generate verb generates an A-PIN or an O-PIN by using one of the following calculation methods that you specify with a rule-array keyword (see “PIN-Calculation Methods” on page E-2): IBM 3624 PIN (IBM-PIN) IBM 3624 PIN Offset (IBM-PINO).
Clear_PIN_Generate CCA Release 2.
Clear_PIN_Generate CCA Release 2.54 PIN_check_length The PIN_check_length parameter points to an integer variable in the range from 4 to 16 containing the length of the PIN offset. The verb uses the PIN check length if you specify the IBM-PINO keyword for the calculation method. Otherwise, ensure that this parameter points to a four-byte variable in application storage. The information in this variable will be ignored, but this variable must be declared.
Clear_PIN_Generate_Alternate CCA Release 2.54 Clear_PIN_Generate_Alternate (CSNBCPA) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Clear_PIN_Generate_Alternate verb is used to obtain a value, the “O-PIN” (offset or VISA-PVV), that will relate the institution-assigned PIN to the customer-known PIN. The verb supports these PIN-calculation methods: IBM 3624 PIN Offset (IBM-PINO) Visa PIN Validation Value (VISA-PVV).
Clear_PIN_Generate_Alternate CCA Release 2.54 Calculates the A-PIN. The verb uses the specified calculation method, the data_array variable, and the PIN_check_length variable to calculate the PIN. Calculates the O-PIN Returns the clear O-PIN in the variable identified by the returned_result parameter.
Clear_PIN_Generate_Alternate CCA Release 2.54 Note: When using the ISO-0 format, use the 12 rightmost PAN digits, excluding the check digit. encrypted_PIN_block The encrypted_PIN_block parameter points to a string variable containing the encrypted PIN-block of the (customer-selected) C-PIN value. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one or two for this verb.
Clear_PIN_Generate_Alternate CCA Release 2.54 Figure 8-7. Clear_PIN_Generate_Alternate Rule_Array Keywords (Second Element) PIN-Block Format Keyword PIN-Extraction Method Keyword Meaning 3624 PADDIGIT HEXDIGIT PINLEN04 PINLEN05 .. . PINLEN16 PADEXIST The PIN-extraction method keywords specify a PIN-extraction method for an IBM 3624 PIN-block format. The first keyword, PADDIGIT, is the default PIN-extraction method for the PIN-block format.
Clear_PIN_Generate_Alternate CCA Release 2.54 Element Description decimalization_table This element contains the decimalization table of 16 characters (0 to 9) that are used to convert the hexadecimal digits (X'0' to X'F') of the enciphered validation data to decimal digits (X'0' to X'9'). validation_data This 16-byte element contains 1 to 16 characters of account data. The data must be left-justified and padded on the right with space characters.
Clear_PIN_Generate_Alternate CCA Release 2.54 returned_result The returned_result parameter points to a string variable containing the clear O-PIN returned by the verb. The 16-byte result will be left-justified and padded on the right with space characters. The length of the PIN offset in the returned result will be determined by the value that the PIN_check_length parameter specifies.
CVV_Generate CCA Release 2.54 CVV_Generate (CSNBCSG) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 X X X X IBM 4758-2/23 The CVV_Generate verb supports the VISA card-verification value (CVV) and the MasterCard card-verification code (CVC) process as defined for track 2 by generating a CVV.
CVV_Generate CCA Release 2.54 rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. The rule_array keywords are shown below: Keyword Meaning PAN-data length (one, optional) PAN-13 This keyword specifies that the length of the PAN data is 13 bytes. PAN-13 is the default value.
CVV_Generate CCA Release 2.54 CVV_key-B_identifier The CVV_key-B_identifier parameter points a string variable containing an internal key-token or a key label of an internal key-token record in key storage. The internal key-token contains the key-B key that decrypts information in the CVV process. CVV_value The CVV_value parameter points to a string variable containing the CVV value in character format returned by the verb.
CVV_Verify CCA Release 2.54 CVV_Verify (CSNBCSV) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The CVV_Verify verb supports the VISA card-verification value (CVV) and the MasterCard card-verification code (CVC) process as defined for track 2 by verifying a CVV.
CVV_Verify CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be zero, one, or two for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
CVV_Verify CCA Release 2.54 expiration_date The expiration_date parameter points to a string variable containing the card expiration date. The date is in numeric character format. The application programmer must determine whether the CVV will be calculated as YYMM or MMYY. service_code The service_code parameter points to a string variable containing the service code in character format. The service code is the number that the track-2, magnetic-stripe standards define.
Encrypted_PIN_Generate CCA Release 2.54 Encrypted_PIN_Generate (CSNBEPG) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Encrypted_PIN_Generate verb generates and formats a PIN and encrypts the PIN block. To generate the PIN, the verb uses one of the following PIN calculation methods: IBM 3624 PIN IBM German Bank Pool Institution PIN Interbank PIN. To format the PIN, the verb uses one of the following PIN-block formats: IBM 3624 ISO-0 (same as ANSI X9.
Encrypted_PIN_Generate CCA Release 2.54 – When using the ISO-0 PIN-block format, specify a PAN. For information about a personal account number (PAN), see “Personal Account Number (PAN)” on page 8-13. – When using another PIN-block format, specify a 12-byte variable in application storage. The information in the variable will not be used, but the variable must be declared. With the sequence_number variable specify a four-byte integer variable valued to 99999.
Encrypted_PIN_Generate CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. PIN_generating_key_identifier The PIN_generating_key_identifier parameter points to a string variable containing an internal key-token or a key label of an internal key-token record in key storage.
Encrypted_PIN_Generate CCA Release 2.54 PIN_profile The PIN_profile parameter is a pointer to a string variable containing the PIN profile including the PIN-block format. See “PIN Profile” on page 8-10. PAN_data The PAN_data parameter is a pointer to a string variable containing 12 digits of Personal Account Number (PAN) data. The verb uses this parameter if the PIN profile specifies ISO-0 for the PIN-block format.
Encrypted_PIN_Translate CCA Release 2.54 Encrypted_PIN_Translate (CSNBPTR) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Encrypted_PIN_Translate verb can change PIN block encryption, and optionally format a PIN into a different PIN-block format. You can use this verb in an interchange-network application, or to change the PIN block to conform to the format and encryption key used in a PIN-verification database.
Encrypted_PIN_Translate CCA Release 2.54 key serial number, and then uses ANSI X9.24-specified “special decryption.” Checks the control vector to ensure that for an IPINENC key that the TRANSLAT bit is valued to one for translate mode and/or the REFORMAT bit is valued to one for reformat mode, or for a KEYGENKY key that the UKPT bit is valued to one. Likewise the OPINENC key must have one or both of the TRANSLAT and REFORMAT bits set appropriate to the requested mode.
CCA Release 2.54 Encrypted_PIN_Translate Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. input_PIN_encrypting_key_identifier The input_PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an internal key-token or a key label of an internal key-token record in key storage.
Encrypted_PIN_Translate CCA Release 2.54 rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, and must be left-justified and padded on the right with space characters. Keyword Meaning Mode (one required) TRANSLAT This keyword specifies that only PIN-block encryption is changed. REFORMAT This keyword specifies that either or both the the PIN-block format and the PIN-block encryption are to be changed.
Encrypted_PIN_Translate CCA Release 2.54 and optionally an additional 24 bytes containing the output current key serial number (CKSN). The strings are equivalent to 24-byte or 48-byte strings. For more information about a PIN profile, see “PIN Profile” on page 8-10. output_PAN_data The output_PAN_data parameter is a pointer to a string variable containing the personal account number (PAN) data.
Encrypted_PIN_Verify CCA Release 2.54 Encrypted_PIN_Verify (CSNBPVR) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The Encrypted_PIN_Verify verb extracts a trial PIN (T-PIN) from an encrypted PIN-block and verifies this value by comparing it to an account PIN (A-PIN) calculated by using the specified PIN-calculation method. Certain PIN-calculation methods modify the value of the A-PIN with the clear offset (O-PIN) value prior to the comparison.
Encrypted_PIN_Verify CCA Release 2.54 The verb does the following: Decrypts the input PIN-block by using the supplied IPINENC key in ECB mode, or derives the decryption key using the specified KEYGENKY key and CKSN and uses ANSI X9.24-specified “special decryption.” The EPINVER bit must be valued to one in the IPINENC control vector, or the UKPT bit must be valued to one in the KEYGENKY control vector. See “PIN Profile” on page 8-10 and “UKPT Calculation Methods” on page E-13.
Encrypted_PIN_Verify CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. PIN_encrypting_key_identifier The PIN_encrypting_key_identifier parameter is a pointer to a string variable containing an internal key-token or a key label of an internal key-token record in key storage.
Encrypted_PIN_Verify CCA Release 2.54 Keyword Meaning Calculation method (one required) IBM-PIN This keyword specifies that the IBM 3624 PIN-calculation method is to be used. IBM-PINO This keyword specifies that the IBM 3624 PIN Offset calculation method is to be used. GBP-PIN This keyword specifies that the IBM German Bank Pool Institution PIN-calculation method is to be used. VISA-PVV This keyword specifies that the VISA-PVV PIN-calculation method is to be used.
Encrypted_PIN_Verify CCA Release 2.54 data_array The data_array parameter is a pointer to a string variable containing three 16-byte character strings, which are equivalent to a single 48-byte string. The values you specify in the data array depend on the PIN-calculation method. Each element is not always used, but you must always declare a complete 48-byte data array. When using the IBM-PIN, IBM-PINO or GBP-PIN keyword, identify the following elements in the data array.
Encrypted_PIN_Verify CCA Release 2.54 When using the VISA-PVV or VISAPVV4 keywords, identify the following elements in the data array. For more information about these elements, and transaction security data for the VISA-PVV calculation method, see “VISA PIN Validation Value (PVV) Calculation Method” on page E-7.
Encrypted_PIN_Verify CCA Release 2.54 Required Commands The Encrypted_PIN_Verify verb requires the following commands to be enabled in the hardware, based on the keyword specified for the PIN-calculation methods.
Key_Encryption_Translate CCA Release 2.54 | | | | Key_Encryption_Translate (CSNBKET) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 IBM 4758-2/23 X | The Key_Encryption_Translate verb is used to change the method of key encryption. An input key can be a double-length external CCA DATA key or a double-length CBC-encrypted key. The returned key is encrypted using the other method, CBC encryption or CCA (ECB) encryption. The CCA DATA key must be double-length and have an all-zero control vector.
Key_Encryption_Translate | Format | CSNBKET | | | | | | | | | | | | | | return_code reason_code exit_data_length exit_data rule_array_count rule_array | CCA Release 2.
Key_Encryption_Translate CCA Release 2.54 | | | | | | | | | | | | | | | | key_out_length The key_out_length parameter points to an integer variable. On input, you should set the variable to at least 64 for the CBCTOECB translation or to at least 16 for the ECBTOCBC translation. On successful completion, the verb will set the variable to the length of the returned key_out variable. key_out The key_out parameter points to a string variable.
PIN_Change/Unblock CCA Release 2.54 PIN_Change/Unblock (CSNBPCU) Platform/ Product OS/2 AIX IBM 4758-23 Win NT/ 2000 OS/400 X Use the PIN_Change/Unblock verb to prepare an encrypted message-portion for communicating an original or replacement PIN for an EMV smart-card. The verb embeds the PIN(s) in an encrypted PIN-block from information that you supply. You incorporate the information created with the verb in a message sent to the smart card.
PIN_Change/Unblock CCA Release 2.54 See “VISA and EMV-Related Smart Card Formats and Processes” on page E-17 which explains the derivation processes and PIN-block formation. The diversification_data_length to indicate the sum of the lengths of: – Data, 8 or 16 bytes, encrypted by the verb using the MDK keys – The 2-byte Application Transfer Counter (ATC) (You receive the ATC value from the EMV smart card.) – The optional 16-byte Initial Value used in the TDESEMVn processes.
PIN_Change/Unblock CCA Release 2.54 Restrictions This verb is supported beginning with Release 2.50. Support for the TDESEMV2 and TDESEMV4 keywords begins with Release 2.51.
PIN_Change/Unblock CCA Release 2.54 Keyword Meaning Diversification process (one, optional) TDES-XOR This keyword specifies to diversify the issuer-master-key using triple DES and an exclusive-OR process. This is the default process. TDESEMV2 This keyword specifies to diversify the issuer-master-key using the EMV tree-based function, branch factor 2. See EMV 4.0 Book 2, Annex A1.3.1, and “VISA and EMV-Related Smart Card Formats and Processes” on page E-17.
PIN_Change/Unblock CCA Release 2.54 The first 8 or 16 bytes of data should contain the value used to form the smart-card-specific authentication value and the PIN-block encryption key. The next two bytes of data contain the 16-bit ATC counter used to further diversify the ENC-MDK key to form the session key used to encrypt the output PIN block. The high-order counter bit is in the left-most counter byte.
PIN_Change/Unblock CCA Release 2.54 current_reference_PIN_profile The current_reference_PIN_profile parameter points to an array of three, 8-byte string variables. The contents of the variables are inspected when the VISAPCU2 rule-array keyword is present. The variables define which PIN block format is processed. For more information about a PIN profile, see “PIN Profile” on page 8-10. current_reference_PIN_PAN_data The current_reference_PIN_PAN_data parameter points to a 12-byte string variable.
PIN_Change/Unblock CCA Release 2.54 PIN-block encrypting key-type Command Offset Command Comment OPINENC X'00BC' Generate PIN Change using OPINENC Required if either the new_reference_PIN_key or the current_reference_PIN_key are permitted to be an OPINENC key type. IPINENC X'00BD' Generate PIN Change using IPINENC Required if either the new_reference_PIN_key or the current_reference_PIN_key are permitted to be an IPINENC key type.
Secure_Messaging_for_Keys CCA Release 2.54 Secure_Messaging_for_Keys (CSNBSKY) Platform/ Product OS/2 AIX Win NT/ 2000 IBM 4758-23 OS/400 X Use the Secure_Messaging_for_Keys verb to decrypt a key you supply for incorporation into a text block you also supply. The text block is then encrypted within the verb to preserve the security of the key value. The encrypted text block, normally the “value” field in a TLV2 item, can be incorporated into a message sent to an EMV smart card.
Secure_Messaging_for_Keys CCA Release 2.54 Returns the enciphered text. Restrictions This verb is supported beginning with Release 2.50.
Secure_Messaging_for_Keys CCA Release 2.54 input_key. You may also specify a key label of a key storage record for such a key. For an internal-form input_key, you may specify a null key-token. secmsg_key_identifier The secmsg_key_identifier parameter is a pointer to a string variable containing an internal key-token or the key label of an internal key-token in key storage. The control vector must specify a SECMSG type key with the SMKEY control-vector bit (bit 18) on.
Secure_Messaging_for_PINs CCA Release 2.54 Secure_Messaging_for_PINs (CSNBSPN) Platform/ Product OS/2 AIX Win NT/ 2000 IBM 4758-23 OS/400 X Use the Secure_Messaging_for_PINs verb to decrypt an input PIN-block, optionally reformat the PIN-block, and incorporate the PIN-block into a text block you also supply. The text block is then encrypted within the verb to preserve the security of the PIN value.
Secure_Messaging_for_PINs CCA Release 2.54 The Secure_Messaging_for_PINs verb: Deciphers the input PIN block Reformats the PIN block when the input and output PIN-block formats differ Self-encrypts the output PIN block as specified Places the PIN block within the supplied text at the specified offset Encrypts the updated text.
Secure_Messaging_for_PINs Keyword CCA Release 2.54 Meaning Enciphering mode (one, optional) TDES-CBC Use CBC mode to encipher the clear_text. This is the default. TDES-ECB Use ECB mode to encipher the clear_text. PIN encryption (one, optional) CLEARPIN Do not encrypt the PIN block prior to encrypting the complete text message. This is the default. SELFENC Append the PIN-block self-encrypted to the clear PIN block within the unencrypted output message. See “PIN-Block Self-encryption” on page E-19.
Secure_Messaging_for_PINs CCA Release 2.54 clear_text_length The clear_text_length parameter is a pointer to an integer containing the length of text to be encrypted. This must be a multiple of eight, and less than or equal to 4096. clear_text The clear_text parameter is a pointer to the text string to be updated with a PIN block and encrypted.
SET_Block_Compose CCA Release 2.54 SET_Block_Compose (CSNDSBC) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The SET_Block_Compose verb creates a SET-protocol RSA-OAEP block and DES encrypts the data block in support of the SET protocols. Optionally the verb will compute the SHA-1 hash of the supplied data block and include this in the OAEP block. DES_encrypted_block can be as many as eight bytes longer than the data_to_encrypt due to padding.
SET_Block_Compose CCA Release 2.54 Parameters For the definitions of the return_code, reason_code, exit_data_length, and exit_data parameters, see “Parameters Common to All Verbs” on page 1-11. rule_array_count The rule_array_count parameter is a pointer to an integer variable containing the number of elements in the rule_array variable. The value must be one for this verb. rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords.
SET_Block_Compose CCA Release 2.54 The hash is an optional part of the OAEP block. No hash is computed or inserted into the OAEP block if the data_to_hash_length variable is zero. data_to_hash The data_to_hash parameter is a pointer to a string variable containing the data that is to be hashed and included in the OAEP block. If the data_to_hash_length variable is not zero, a SHA-1 hash of the data_to_hash variable will be included in the OAEP block.
SET_Block_Compose CCA Release 2.54 with the data_to_encrypt variable). The starting address must not fall inside the data_to_encrypt area. Required Commands The SET_Block_Compose verb requires the SET Block Compose command (command offset X'010B') to be enabled in the hardware. Chapter 8.
SET_Block_Decompose CCA Release 2.54 SET_Block_Decompose (CSNDSBD) Platform/ Product IBM 4758-2/23 OS/2 AIX Win NT/ 2000 OS/400 X X X X The SET_Block_Decompose verb decomposes the RSA-OAEP block and DES decrypts the data block in support of the SET protocols. Restrictions The maximum data block that can be supplied for DES decryption is the limit as expressed in the Decipher service (see page 6-5). The DES_key_block_length parameter must point to an integer which has a value of zero, 64, or 128.
SET_Block_Decompose CCA Release 2.
SET_Block_Decompose CCA Release 2.54 RSA-OAEP_block_length The RSA-OAEP_block_length parameter is a pointer to an integer variable containing the number of bytes of data in the RSA-OAEP_block variable. This value must be 128 bytes. RSA-OAEP_block The RSA-OAEP_block parameter is a pointer to a string variable containing the RSA-OAEP block.
CCA Release 2.54 SET_Block_Decompose of a 128-byte buffer. The first 64 bytes of the buffer are reserved for future use, and should be set to X'00'. The PIN encrypting-key token will be returned to the caller in the same buffer on completion of the verb. block_contents_identifier The block_contents_identifier parameter is a pointer to a string variable containing the Block Contents (BC) field of the SET DB data block.
SET_Block_Decompose CCA Release 2.54 Required Commands The SET_Block_Decompose verb requires the SET Block Decompose command (command offset X'010C') to be enabled in the hardware. Two additional commands are used when encrypting PIN data with this verb. When using an IPINENC type key, the verb requires the SET_PIN_encrypt_IPINENC command (command offset X'0121') to be enabled in the hardware.
Transaction_Validation CCA Release 2.54 Transaction_Validation (CSNBTRV) Platform/ Product OS/2 AIX Win NT/ 2000 OS/400 IBM 4758-2 X X X X The Transaction_Validation verb supports the generation and validation of American Express card security codes (CSC). The Transaction_Validation verb generates and verifies transaction values based on information from the transaction and a cryptographic key. You select the validation method, and either the generate or verify mode, through rule-array keywords.
Transaction_Validation CCA Release 2.54 rule_array The rule_array parameter is a pointer to a string variable containing an array of keywords. The keywords are eight bytes in length, left-justified, and padded on the right with space characters, as shown below. Keyword Meaning Operation (one, optional) VERIFY Specifies verification of the value presented in the validation values variable. (This is the default when the CSC-3, CSC-4, or CSC-5 keywords are used.
Transaction_Validation CCA Release 2.
CCA Release 2.54 8-78 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Appendix A. Return Codes and Reason Codes This appendix describes the return codes and the reason codes that a verb uses to report the results of processing. Each return code is associated with a reason code that supplies details about the result of verb processing. A successful result can include return code 0 and reason code 0 or another combination of a return code and a reason code.
CCA Release 2.54 Figure A-2 on page A-2 shows the reason codes, listed in numeric sequence and grouped by their corresponding return code. The return codes appear in decimal form, and the reason codes appear in decimal and hexadecimal (hex) form. Return Code 0 Figure A-2 A-2. Reason Codes for Return Code 0 Return Code Dec Reason Code Dec (Hex) 0 0 0 0 000 002 008 151 0 0 0 701 (2BD) 702 (2BE) 10001 (2711) (000) (002) (008) (097) Meaning The verb completed processing successfully.
CCA Release 2.54 Return Code 4 Figure A-3. Reason Codes for Return Code 4 Return Code Dec Reason Code Dec (Hex) 4 4 001 (001) 013 (00D) 4 016 (010) 4 017 (011) 4 4 019 (013) 158 (09E) 4 166 (0A6) 4 179 (0B3) 4 4 4 283 (11B) 287 (11F) 429 (1AD) 4 1024 (400) 4 4 2039 (7F7) 2042 (7FA) Meaning The verification test failed. The key token has an initialization vector, and the initialization_vector parameter value is nonzero. The verb uses the value in the key token.
CCA Release 2.54 Return Code 8 Figure A-4 A-4 (Page 1 of 6).
CCA Release 2.54 Figure A-4 (Page 2 of 6).
CCA Release 2.54 Figure A-6 A-4 (Page 3 of 6).
CCA Release 2.54 Figure A-4 (Page 4 of 6).
CCA Release 2.54 Figure A-8 A-4 (Page 5 of 6).
CCA Release 2.54 Figure A-4 (Page 6 of 6).
CCA Release 2.54 Return Code 12 Figure A-10 A-5. Reason Codes for Return Code 12 Return Code Dec Reason Code Dec (Hex) 12 097 (061) 12 196 (0C4) 12 12 197 (0C5) 206 (0CE) 12 12 207 (0CF) 324 (144) 12 338 (152) 12 339 (153) 12 764 (2FC) 12 768 (300) 12 2045 (7FD) 12 2046 (7FE) Meaning File space in key storage is insufficient to complete the operation.
CCA Release 2.54 Return Code 16 Figure A-6. Reason Codes for Return Code 16 Return Code Dec Reason Code Dec (Hex) 16 099 (063) 16 336 (150) 16 16 16 16 16 337 444 556 708 709 16 710 (2C6) 16 16 712 (2C8) 769 (301) 16 16 16 16 16 2047 2057 2058 2059 2061 (151) (1BC) (22C) (2C4) (2C5) (7FF) (809) (80A) (80B) (80D) Meaning An unrecoverable error occurred in the security server; contact your IBM service representative. An error occurred in a cryptographic hardware or software component.
CCA Release 2.54 A-12 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Appendix B. Data Structures This appendix describes the following data structures: Key tokens Chaining vector records Key-storage records Key record list data set Access-control data structures Master key shares Distributed function control vector. Key Tokens This section describes the DES and RSA key-tokens used with the product. A “key token” is a data structure that contains information about a key and usually contains a key or keys.
CCA Release 2.54 An IBM 4758 does not permit the introduction of a new master key value that has the same verification value as either the current master-key or as the old master-key. Token-Validation Value and Record-Validation Value The Token-Validation Value (TVV) is a checksum that helps ensure that an application program-provided key token is valid.
CCA Release 2.54 DES Key-Tokens DES key-token data structures are 64 bytes in length, contain an enciphered key, a control vector, various flag bits, version number, and token validation value. An internal key-token contains a key multiply-enciphered by a master key while an external key-token contains a key multiply-enciphered by some key-encrypting key.
CCA Release 2.54 Figure Offset B-4 B-3 (Page 2 of 2). Internal DES Key-Token, Version 3 Format Length 48-59 12 60-63 4 Meaning Reserved, binary zero The token-validation value IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 External DES Key-Token CCA implementations generally use a version X'00' external key-token. See Figure B-4. The IBM 4758 Version 2 CCA Support Program also uses a version X'01' external key-token to hold a double-length DATA key that is associated with a null (all-zero bits) control vector. See Figure B-5. Figure Offset B-4.
CCA Release 2.54 DES Key-Token Flag Byte 1: Figure B-6. Key-Token Flag Byte 1 Bits (MSB...LSB)1 1xxx xxxx 0xxx xxxx x0xx xxxx x1xx xxxx Meaning The encrypted key value and the Master Key Verification Pattern are present An encrypted key is not present The control-vector value is not present The control-vector value is present All other bit combinations are reserved; undefined bits should be zero. DES Key-Token Flag Byte 2: Figure B-7. Key-Token Flag Byte 2 Bits (MSB...
CCA Release 2.54 Coprocessor but your application will encounter a performance penalty with each use of the key. Protection of the private key is provided by encrypting a confounder (a random number) and the private key information exclusive of the modulus. An encrypted private key in an external key-token is protected by a double-length transport key and the EDE2 algorithm. See “CCA RSA Private Key Encryption and Decryption Process” on page C-12.
CCA Release 2.54 – Section identifier X'05' for a CRT-format key up to 1024 bits is accepted as input.
CCA Release 2.54 Figure B-8. RSA Key-Token Header Offset (Bytes) Length (Bytes) 000 001 Description Token identifier (a flag that indicates token type) X'1E' X'1F' External token; the optional private-key is either in cleartext or enciphered by a transport key-encrypting-key. Internal token; the private key is enciphered by the master key.
CCA Release 2.54 Figure B-9. RSA Private Key, 1024-Bit Modulus-Exponent Format Offset (Bytes) Length (Bytes) Description 000 001 X'02' Section identifier, RSA private key, modulus-exponent format (RSA-PRIV). This section type is created by selected IBM 4755 Cryptographic Adapters and the IBM 4758 Version 1 CCA Support Program. Version 2 software uses this format for a clear or an encrypted RSA private key in an external key-token.
CCA Release 2.54 Figure B-10 (Page 1 of 2). Private Key, 2048-Bit Chinese-Remainder Format Offset (Bytes) Length (Bytes) Description 000 001 X'05' Section identifier, RSA private key, CRT (RSA-OPT) format. This section type is created by the IBM 4758 Version 1 CCA Support Program.
CCA Release 2.54 Figure B-10 (Page 2 of 2).
CCA Release 2.54 Figure B-11. RSA Private Key, 1024-Bit Modulus-Exponent Format with OPK Offset (Bytes) Length (Bytes) Description 000 001 X'06' Section identifier, RSA private key, modulus-exponent format (RSA-PRIV). This section type is created by the IBM 4758 Version 2 CCA Support Program. This section type provides compatibility and interchangeability with the CCF hardware in S/390 processors.
CCA Release 2.54 Figure B-12 (Page 1 of 2). RSA Private Key, Chinese-Remainder Format with OPK Offset (Bytes) Length (Bytes) Description 000 001 X'08' Section identifier, RSA private key, CRT format (RSA-CRT). This section type is created by the IBM 4758 Version 2 CCA Support Program.
CCA Release 2.54 Figure Offset (Bytes) 124 B-12 (Page 2 of 2). RSA Private Key, Chinese-Remainder Format with OPK Length (Bytes) Description Start of the (optionally) encrypted subsection. External token: When offset 028 is X'40', the subsection is not encrypted When offset 028 is X'42', the subsection is encrypted by the double-length transport key using the triple-DES CBC process.
CCA Release 2.54 Figure B-13. RSA Public Key Offset (Bytes) Length (Bytes) Description 000 001 X'04', Section identifier, RSA public key 001 001 The version number (X'00') 002 002 Section length, 12+xxx+yyy 004 002 Reserved, binary zero 006 002 RSA public-key exponent field length in bytes, “xxx” 008 002 Public-key modulus length in bits.
CCA Release 2.54 RSA Public-Key Certificate Section: An optional public key certificate(s) section can be included in an RSA key-token. The section consists of: The section header (identifier X'40') A public key subsection (identifier X'41') An optional certificate information subsection (identifier X'42') with any or all of these elements: – User data (identifier X'50') – EID (identifier X'51') – Serial number (identifier X'52') A signature subsection (identifier X'45').
CCA Release 2.54 Figure B-17. RSA Public-Key Certificate(s) Optional Information Subsection Header Offset (Bytes) Length (Bytes) Description 000 001 X'42', Information Subsection Header 001 001 The version number (X'00') 002 002 Subsection length, 4+iii 004 iii The information field that will contain any of the includable TLV entities: User data (Id = 50) EID (Id = 51) Serial number (Id = 52) Note: See “Number Representation in PKA Key-Tokens” on page B-8. Figure B-18.
CCA Release 2.54 Figure B-21.
CCA Release 2.54 RSA Private-Key Blinding Information: Figure B-22. RSA Private-Key Blinding Information Offset (Bytes) Length (Bytes) 000 001 Description X'FF', Section identifier, private-key blinding information. Used with internal key-tokens created by the CCA Support Program, Version 1 (having section identifiers X'02' or X'05').
CCA Release 2.54 Key-Storage Records Key storage exists as an online, Direct Access Storage Device (DASD)-resident data set for the storage of key records. Key records contain a key label, space for a key token, and control information. The stored key tokens are accessed using the key label. DES and PKA key tokens are held in independent key storage data sets.
CCA Release 2.54 Figure Offset B-24. Key-Storage-File Header, Record 1 (not OS/400) Length Meaning 00 04 The total length of this key record. 04 04 The record validation value. 08 64 The key label without separators. $$FORTRESS$REL01$MASTER$KEY$VERIFY$PATTERN . 72 15 The date and time of when this record was created.
CCA Release 2.54 Figure Offset B-25. Key-Storage File Header, Record 2 (not OS/400) Length Meaning 00 04 The total length of this key record. 04 04 The record validation value. 08 64 The key label without separators. For the DES key-storage file the key label is $$FORTRESS$DES$REL01$KEY$STORAGE$FILE$HEADER . For the PKA key-storage file the key label is $$FORTRESS$PKA$REL01$KEY$STORAGE$FILE$HEADER . 72 15 The date and time of when this record was created.
CCA Release 2.54 Figure Offset Length Meaning 00 56 The key label without separators. 56 02 Reserved 58 64 The DES key token. 122 04 The date and time of when this record was created. This field has the same format as the created date in Figure B-24 on page B-21. 126 04 The date and time of when this record was last updated. This field has the same format as the created date in Figure B-24 on page B-21. 130 02 Reserved 132 04 The record validation value.
CCA Release 2.54 Key_Record_List Data Set There are two Key_Record_List verbs, one for the DES key store and one for the PKA key store. Each creates an internal data set that contains information about specified key records in key storage. Both verbs return the list in a data set, KYRLTnnn.LST, where nnn is the numeric portion of the name and nnn starts at 001 and increments to 999 and then wraps back to 001.
CCA Release 2.54 Figure Offset B-29 (Page 2 of 2). Key-Record-List Data Set Format (Other Than OS/400) Length Meaning Detail Record (Part 1) 0 1 This field contains an asterisk (*) if the key-storage record did not have a correct record validation value; this record should be considered to be a potential error. 1 2 This field contains spaces for separation. 3 64 67 8 This field contains the key type.
CCA Release 2.54 Figure Offset B-30 (Page 1 of 2). Key-Record-List Data Set Format (OS/400 only) Length Meaning Header Record 0 24 24 2 26 19 This field contains the installation-configured listing header (the default value for the DES key store is DES KEY-RECORD-LIST and for the PKA key store is PKA KEY-RECORD-LIST). This field contains spaces for separation. This field contains the date and the time when the list was generated.
CCA Release 2.54 Figure Offset B-30 (Page 2 of 2). Key-Record-List Data Set Format (OS/400 only) Length Meaning Detail Record 0 1 This field contains an asterisk (*) if the key-storage record did not have a correct record validation value; this record should be considered to be a potential error. 1 2 This field contains spaces for separation. 3 64 67 8 This field contains the key type.
CCA Release 2.54 Role Structure This section describes the data structures used with roles. Basic Structure of a Role The following figure describes how the Role data is structured. This is the format used when role data is transferred to or from the Coprocessor, using verbs CSUAACI or CSUAACM.
CCA Release 2.54 Aggregate Role Structure A set of zero one or more role definitions are sent in a single data structure. This structure consists of a header, followed by one or more role structures as defined in “Basic Structure of a Role” on page B-29. The header defines the number of roles which follow in the rest of the structure. Its layout is shown in Figure B-32, with three concatenated role structures shown for illustration.
CCA Release 2.54 The entire access-control-point structure is comprised of a header, followed by one or more access-control-point segments. The header indicates how many segments are contained in the entire structure. The layout of this structure is illustrated in Figure B-33.
CCA Release 2.54 Figure B-34 (Page 2 of 2). Functions Permitted in Default Role Code Function Name X'0113' Change the expiration date in a user profile X'0114' Change the authentication data (for example, passphrase) in a user profile X'0115' Reset the logon failure count in a user profile X'0116' Read public access-control information X'0117' Delete a user profile X'0118' Delete a role Profile Structure This section describes the data structures related to user profiles.
CCA Release 2.54 The checksum is defined as the exclusive-OR (XOR) of each byte in the profile structure. The high-order byte of the checksum field is set to zero (X'00'), and the exclusive-OR result is put in the low-order byte. Note: The checksum value is not used in the current profile structure. It may be verified by the Cryptographic Coprocessor with a future version of the profile structure.
CCA Release 2.54 The header is followed by individual sets of authentication data, each containing the data for one authentication mechanism. This layout is shown pictorially in Figure B-38 on page B-34. Figure B-38. Layout of the Authentication Data Field The content of the individual Authentication Data structures is shown in Figure B-39 below. B-34 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Figure B-39 (Page 1 of 2). Authentication Data for Each Authentication Mechanism Field name Length (bytes) Description Length 2 The size of this set of authentication mechanism data, in bytes. The length field includes all bytes of mechanism data following the length field itself. Mechanism ID 2 An identifier which describes the authentication mechanism associated with this set of data.
CCA Release 2.54 Figure B-39 (Page 2 of 2). Authentication Data for Each Authentication Mechanism Field name Length (bytes) Description Mechanism data variable This field contains the data needed to perform the authentication. The size, content, and complexity of this data will vary according to the authentication mechanism.
CCA Release 2.54 1 66 69 7 6 4a 69 74 cd 1 9d 6c 68 c 8 ca Figure 5a 65 2 1f 8 2d 2 41 fb 2 31 44 24 52 53 2 4d fb 9e 61 2d 49 1 f5 e2 6d ab 4e c4 45 7 cd 31 2 84 41 6c 2 75 65 2 1 5f 2 4a 7 1 ba 5 5f cd 8 59 72 53 6 7 6b 6f 6d 1 ce ca ...Z- Sample Pro file 1 -....J_Sm ith ADMIN1 .... ....."... ...... ..........u_.Yk. J....R..EA B-41. User Profile Data Structure This user profile contains the following fields.
CCA Release 2.54 6d ab 4e c4 45 7 cd 31 2 84 41 Figure 6c 2 75 1 65 2 1 5f 2 4a 7 1 ba 5 5f cd 8 59 72 53 6 7 6b 6f 6d 1 ce ca 1 66 69 7 6 4a 69 74 cd 1 9d 6c 68 c 8 ca 5a 65 2 1f 8 2d 2 41 fb 2 31 44 24 52 53 2 4d fb 9e 61 2d 49 1 f5 e2 ...........Z- Sa mple Profile 1 ....J_Smith ADMI N1 .........".. . .............. ..u_.Yk.J....R.. EA B-42.
CCA Release 2.54 00 03 The number of bytes of data in the access-control points for this segment. There are 3 bytes, for the access-control points from 512 through 535. 00 00 A reserved field, which must be filled with zeros. 8F 99 FE This is the second set of access-control points, with one bit corresponding to each point. Thus, the first byte contains bits 512-519, the second byte contains 520-527, and the third byte contains 528-535.
CCA Release 2.54 Aggregate Role Data Structure Figure B-45 shows the an aggregate role data structure, like you would load using the CSUAACI verb. 2 ab 17 f ff ff 64 cd 1e ff ff ff Figure 65 7c ff ff ff 1 66 ff ff 2 61 44 ff ff 75 45 2 ff ff 2 6c 46 ff ff 17 74 41 ff ff 8f 1 2 55 ff ff 99 72 4c ff ff fe 6f 54 1 ff ff 62 6c 2 17 ff ff 2a 65 23 ff ff 4e 2 45 23 ff ff 65 31 1 ff ff 77 2a f ff ff ............
CCA Release 2.54 Master Key Shares Data Formats Master key shares, and potentially other information to be “cloned” from one Coprocessor to another Coprocessor are packed into a data structure as described in Figure B-46. Figure B-46.
CCA Release 2.54 Function Control Vector The export (distribution) of cryptographic implementations by USA companies is controlled under USA Government export regulations. An IBM 4758 becomes a practical cryptographic engine when it accepts and validates digitally signed software. IBM has chosen to export the IBM 4758 as a non-cryptographic product, and to control and report the export of the cryptography-enabling software.
CCA Release 2.54 Figure Offset Decimal (Hex) B-49 (Page 2 of 2).
CCA Release 2.54 B-44 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Appendix C. CCA Control-Vector Definitions and Key Encryption This appendix describes the following: DES control-vector values1 Specifying a control-vector-base value Changing control vectors CCA key encryption and decryption processes. In the Common Cryptographic Architecture (CCA), a control vector is a non-secret quantity that expresses permissible usages for an associated key.
CCA Release 2.54 Figure C-1.
CCA Release 2.54 You can use the default control-vector for a key type, or you can create a more restrictive control-vector. The default control-vector for a key type provides basic key-separation functions. Optional usage restrictions can further tighten the security of the system. The cryptographic subsystem creates a default control vector for a key type when you use the Key_Generate verb and specify a null key token and a key-type in the key_type parameter.
CCA Release 2.54 Figure C-4 C-2 (Page 2 of 2).
CCA Release 2.54 Control─Vector─Base Bits │ │ 1 1 1 │1 1 2 2 │2 2 2 3 │3 3 3 3 │4 4 4 4 │4 5 5 5 │5 5 6 6 │ │ 2 4 6 │8 2 4 │6 8 2 │4 6 8 │2 4 6 8 │ 2 4 6 │8 2 4 │6 8 2 │ │ │ │ │ │ │ │ │ │ │└─Most Significant Bit │ │ │ Least Significant Bit─┘│ │ │ │ │ │ │ │ │ │ │Common Bits │ │ │ │ │ │ │ │ │ │ │ ┌────────┬────Anti─Variant Bits │ │ │ │ │ │ │ │ │ │ │ │ │....uu.P│.......P│.E.....P│...... P│......1P│fff.K..P│.......P│.....u.
CCA Release 2.
CCA Release 2.54 Key-Form Bits, ‘fff’ and ‘FFF’ The key-form bits, 40-42...and for a double-length key, bits 104-106...are designated ‘fff’ and ‘FFF’ in the preceding diagram.
CCA Release 2.54 Bits 12 to 14 Key Subtype PIN Keys 001 PIN-generating key (PINGEN, PINVER) 000 Inbound PIN-block decrypting key (IPINENC) 010 Outbound PIN-block encrypting key (OPINENC) Key-Generating Keys 001 KEYGENKY key-generating keys sss DKYGENKY key-generating keys sss is the count minus one of the number of diversifications used to obtain the final, non-diversification key. See “Diversifying Keys” on page 5-19. (The Key_Token_Build verb can set the sss bits when you supply the DKYL0, ...
CCA Release 2.54 The MAC control bits (bits 20 and 21). For a MAC generation key, set bits 20 and 21 to B'11'. For a MAC verification key, set bits 20 and 21 to B'01'. The key-form bits (fff, bits 40 to 42). For a single-length key, set the bits to B'000'. For a double-length key, set the bits to B'010'. 6. For SECMSG keys, set one or both of the following bits: Set the SMKEY bit (k, bit 18) to enable this key-type to operate in secure message services that imbed a key.
CCA Release 2.54 Verb Allowed Bit Name Bit Clear_PIN_Generate CPINGEN 18 Encrypted_PIN_Generate_Alternate EPINGENA 19 Encrypted_PIN_Generate EPINGEN 20 for PINGEN 19 for OPINENC Clear_PIN_Generate_Alternate CPINGENA 21 for PINGEN 20 for IPINENC Encrypted_Pin_Verify EPINVER 19 Clear_PIN_Encrypt CPINENC 18 9.
CCA Release 2.54 Bits 19 to 22 Keyword To Obtain 0001 DDATA single- or double-length DATA key 0010 DMAC single- or double-length MAC key 0011 DMV single- or double-length MACVER key 0100 DIMP IMPORTER key 0101 DEXP EXPORTER key 0110 DPVR PIN verify key 1000 DMKEY double-length SMKEY SECMSG key 1001 DMPIN double-length SMPIN SECMSG key 1111 DALL any of the above. 13. For all keys, set the following bits: The export bit (E, bit 17).
CCA Release 2.54 CCA Key Encryption and Decryption Processes This section describes the CCA key-encryption processes: CCA DES key encryption CCA RSA private key encryption Encipherment of DES keys under RSA in “PKA92” format Encipherment of a DES key-encrypting key under RSA in “NL-EPP-5” format. CCA DES Key Encryption and Decryption Processes With the CCA, multiple enciphering or multiple deciphering a key is a two-step process.
CCA Release 2.
CCA Release 2.54 PKA92 Key Format and Encryption Process The PKA_Symmetric_Key_Export, PKA_Symmetric_Key_Generate, and the PKA_Symmetric_Key_Import verbs optionally support a PKA92 method of encrypting a DES or CDMF key with an RSA public key. This format is adapted from the IBM Transaction Security System (TSS) 4753 and 4755 product's implementation of “PKA92.” The verbs do not create or accept the complete PKA92 AS key token as defined for the TSS products.
CCA Release 2.54 Decrypting Sub-process: RSA decrypt the AS External Key Block using an RSA private key and call the result of the decryption PKR. The private key must be usable for key management purposes. Validating Sub-process: Verify that the high-order two bits of the PKR record are valued to B'01'. and that the low-order four bits of the PKR record are valued to B'0110'. Unmasking Sub-process: Set IV to the value of the 8 bytes at offset 53 of the PKR record.
CCA Release 2.54 Encrypting a Key_Encrypting Key in the NL-EPP-5 Format The PKA_Symmetric_Key_Generate verb supports a NL-EPP-5 method of encrypting a DES key-encrypting key with an RSA public key. The verb returns an encrypted key block by RSA encrypting a key record formed in the following manner: 1. Format the key and other data per Figure C-6 2. Insert random padding data into the record 3. Insert the count of pad bytes plus one. Figure Offset (Bytes) C-6.
CCA Release 2.54 you can enter another part that is set to the value of the pre-exclusive-OR quantity (which quantity is discussed later). Use the Key_Generate verb to generate an IMPORTER/EXPORTER pair of KEKs, with the KEY-PART control vector bit set on. Then use the Key_Part_Import verb to enter an additional key part that is set to the value of the pre-exclusive-OR quantity.
CCA Release 2.54 Note that if you are processing a double-length key, you almost certainly will have to process the key twice, using the key-encrypting key modified by different values each appropriate to a key half. Then you concatenate the resulting two correct key-halves.
CCA Release 2.54 CVil is the control vector for the left half of the target input PIN-block encrypting key. e*Km⊕CViml(Kt⊕CVir) e*Km⊕CVimr(Kt⊕CVir) where: CVir is the control vector for the right half of the target input PIN-block encrypting key. 2. Use the Key_Token_Build verb to build source (external) and target (internal) key tokens with: eKt(Kp) eKt(Kp) CVil CVil 3. Use Key_Import and the first of the IMPORTER keys to import the left half of the target key (discard the right half). 4.
CCA Release 2.54 Changing Control Vectors with the Control_Vector_Translate Verb Do the following when using the Control_Vector_Translate verb: Provide the control information for testing the control vectors of the source, target, and key-encrypting keys to ensure that only sanctioned changes can be performed Select the key-half processing mode.
CCA Release 2.54 This expression tests whether the control vectors associated with the source key and the target key meet your criteria for the desired translation. Encipher two copies of the mask array, each under a different cryptographic-variable key (key type CVARENC). To encipher each copy of the mask array, use the Cryptographic_Variable_Encipher verb. Use two different keys so that the enciphered-array copies are unique values.
CCA Release 2.54 For expression 1: KEK CV 2: Source CV 3: Target CV A_values Intermediate Result B_values Final Result For Expression 4: Source CV Target CV Intermediate Result B_values Final Result Figure C-22 ┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ Control Vector │ │1│ │1│... │ │1│ │1│... │ Under Test └─┴─┴─┴─┴─────┴─┴─┴─┴─┴───────────────────────────┘ Exclusive-OR ┌─┬─┬─┬─┬─────┬─┬─┬─┬─┬───────────────────────────┐ │ │ │1│1│... │ │ │1│1│...
CCA Release 2.54 Selecting the Key-Half Processing Mode The Control_Vector_Translate verb rule-array keywords determine which key halves are processed in the verb call, as shown in Figure C-9.
CCA Release 2.54 The verb first processes the source and target tokens as with the SINGLE keyword. Then the source token is processed using the single-length enciphered key and the source token right-half control vector to obtain the actual key value. The key value is then enciphered using the KEK and the control vector in the target token for the right-half of the key. This approach is frequently of use when you must obtain a double-length CCA key from a system that only supports a single-length key.
CCA Release 2.54 Appendix D. Algorithms and Processes This appendix provides processing details for the following aspects of the CCA design: Cryptographic key-verification techniques Ciphering methods Triple-DES algorithms, EDE2 and EDE3 MAC calculation methods Access-control algorithms Master-key splitting algorithm RSA key-pair generation.
CCA Release 2.54 S/390 Based Master Key Verification Method When the first and third portions of the symmetric master key have the same value, the master key is effectively a double-length DES key. In this case, the master key verification pattern (MKVP) is based on this algorithm: C = X'4545454545454545' IR = MKfirst-part ⊕ eC(MKfirst-part) MKVP = MKsecond-part ⊕ eIR(MKsecond-part) where: ex(Y) is the DES encoding of Y using x as a key ⊕ represents the bit-wise exclusive-OR function.
CCA Release 2.54 The CCA DES key verification algorithm does the following: 1. 2. 3. 4. 5. 6. Sets Sets Sets Sets Sets Sets KKR′ = KKR exclusive-OR RN K1 = X'4545454545454545' X1 = DES encoding of KKL using key K1 K2 = X1 exclusive-OR KKL X2 = DES encoding of KKR′ using key K2 VP = X2 exclusive-OR KKR′.
CCA Release 2.54 When the keywords PADMDC-2 and PADMDC-4 are used, the supplied text is always padded as follows: If the supplied text is less than 16 bytes in length, pad bytes are appended to make the text length equal to 16 bytes. If the supplied text is at least 16 bytes in length, pad bytes are appended to make the text length equal to the next-higher multiple of eight bytes, pad bytes are always added. All appended pad bytes, other than the last pad byte, are set to X'FF'.
CCA Release 2.54 MDC-2 Calculation The MDC-2 calculation consists of the following procedure: MDC-2 (n, text, KEY1, KEY2, MDC); For i := 1,2,...,n do Call MDC-1(KEY1, KEY2, T8, T8, OUT1, OUT2) Set KEY1 := OUT1 Set KEY2 := OUT2 End do Set output MDC := (KEY1 || KEY2). End procedure MDC-4 Calculation The MDC-4 calculation consists of the following procedure: MDC-4 (n, text, KEY1, KEY2, MDC); For i := 1,2,...
CCA Release 2.54 General Data Encryption Processes Although the fundamental concepts of ciphering (enciphering and deciphering) data are simple, different methods exist to process data strings that are not a multiple of eight bytes in length. Two widely used methods for enciphering general data are defined in these ANSI standards: ANSI X3.106 (CBC) ANSI X9.23. Note: These methods also differ in how they define the initial chaining value (ICV).
CCA Release 2.54 ANSI X3.106 Cipher Block Chaining (CBC) Method ANSI standard X3.106 defines four modes of operation for ciphering. One of these modes, Cipher Block Chaining (CBC), defines the basic method for ciphering multiple eight-byte data strings. Figure D-3 and Figure D-4 on page D-8 show Cipher Block Chaining using the Encipher and the Decipher verbs. A plaintext data string that must be a multiple of eight bytes, is processed as a series of eight-byte blocks.
CCA Release 2.
CCA Release 2.
CCA Release 2.54 Triple-DES Ciphering Algorithms Triple-DES is used to encrypt keys, PIN blocks, and general data. Several techniques are employed: T-DES ECB DES keys, when triple encrypted under a double-length DES key, are ciphered using an e-d-e scheme without feedback. SeeFigure C-4 on page C-13. Triple-DES CBC Encryption of general data, and RSA section type X'08' CRT-format private keys and OPK keys, employs the scheme depicted in Figure D-7 on page D-11 and Figure D-8 on page D-11.
CCA Release 2.
CCA Release 2.
CCA Release 2.54 MAC Calculation Methods With CCA Release 2.51, three variations of DES based message authentication are supported by the MAC_Generate and MAC_Verify verbs: ANSI X9.9 ANSI X9.19 optional Procedure 1 EMV post-padding of X'80'. The Financial Institution (Wholesale) Message Authentication Standard (ANSI X9.9-1986) defines a process for the authentication of messages from originator to recipient. This process is called the Message Authentication Code (MAC) calculation method.
CCA Release 2.54 T1 T2 Tn-1 Tn │ ┌──┴──┐ ┌──┴──┐ ┌──┴──┐ │ │ │ │ │ │ │ │ ┌─ ─┤ XOR │ ┌─ ─┤ XOR │ ┌─ ─┤ XOR │ │ │ │ │ │ │ │ │ │ │ │ │ └──┬──┘ │ └──┬──┘ │ └──┬──┘ │ │ │ │ │ │ │ │ │ │ ┌──┴──┐ │ ┌──┴──┐ │ ┌──┴──┐ │ ┌──┴──┐ │ │ │ │ │ │ │ │ │ │ │ KEY│ Enc │ │KEY│ Enc │ │KEY│ Enc │ │KEY│ Enc │ │ │ │ │ │ │ │ │ │ │ │ └──┬──┘ │ └──┬──┘ │ └──┬──┘ │ └──┬──┘ │O1 │ │O2 │ │On-1 │ │On └───────┘ └────//─────┘ └───────┘ ├─── (OCV) │ ANSI X9.9 MAC (and to decipher and encipher for ANSI X9.
CCA Release 2.54 RSA Key-Pair Generation RSA key-pair generation is determined based on user input of the modulus bit length, public exponent, and key type. The output is based on creating primes p and q in conformance with ANSI X9.31 requirements as follows: prime p bit length = ((modulus_bit_length +1)/2) prime q bit length = modulus_bit_length - p_bit_length p and q are randomly chosen prime numbers p>q The Rabin-Miller Probabilistic Primality Test is iterated eight times for each prime.
CCA Release 2.54 Access-Control Algorithms The following sections describe algorithms and protocols used by the access-control system. Passphrase Verification Protocol This section describes the process used to log a user on to the Cryptographic Coprocessor. Design Criteria The passphrase verification protocol is designed to meet the following criteria. 1. The use of cryptographic algorithms is permitted in the client logon software, but there must be no storage of any long-term cryptographic keys.
CCA Release 2.54 3. The client workstation generates a random number, RN (64 bits). Note: Note: The random-number RN is not used inside the Cryptographic Coprocessor. It is only included in the protocol to guarantee that the cleartext of the logon request is different every time. 4.
CCA Release 2.54 Master-Key-Splitting Algorithm This section describes the mathematical and cryptographic basis for the m-of-n key shares scheme. The key splitting is based on Shamir's secret sharing algorithm: The value to be shared is the master key, Km, which is a triple-DES key and thus 168 bits long. Let P be the first prime number larger than 2168. All operations are carried out modulo P.
CCA Release 2.54 Formatting Hashes and Keys in Public-Key Cryptography The Digital_Signature_Generate and Digital_Signature_Verify verbs support several methods for formatting a hash, and in some cases a descriptor for the hashing method, into a bit-string to be processed by the cryptographic algorithm. This section discusses the ANSI X9.31 and PKCS #1 methods. The ISO 9796-1 method can be found in the ISO standard. This section also describes the PKCS #1, version 1, 1.5, and 2.
CCA Release 2.54 – RSASSA-PKCS1-v1_5, the newer name for the block-type 1 format. In CCA, keyword PKCS-1.1 is used to invoke this formatting technique. – The PKCS #1 specification no longer discusses use of block-type 0. In CCA, keyword PKCS-1.0 is used to invoke this formatting technique. Use of block-type 0 is discouraged. Using the terminology from older versions of the PKCS #1 standard, block types 0 and 1 are used to format a hash and block type 2 is used to format a DES key.
CCA Release 2.54 Appendix E. Financial System Verbs Calculation Methods and Data Formats This appendix describes the following: PIN-calculation methods PIN-block formats Unique-key-per-transaction calculation methods MasterCard and VISA card verification techniques VISA and EMV smart card PIN-related formats and processes. The PIN calculation methods are independent from PIN-block formats. A PIN can be calculated by any method and generally used in any PIN-block format.
CCA Release 2.54 PIN-Calculation Methods The financial PIN verbs support some or all of these PIN-calculation methods, see Figure 8-3 on page 8-6: IBM 3624 PIN (IBM-PIN) IBM 3624 PIN Offset (IBM-PINO) Netherlands PIN-1 (NL-PIN-1).
CCA Release 2.54 IBM 3624 PIN-Calculation Method The IBM 3624 PIN-calculation method calculates a PIN that is from 4 to 16 digits in length. The IBM 3624 PIN-calculation method consists of the following steps to create the A-PIN: 1. Encrypt the hexadecimal validation data with a key that has a control vector that specifies the PINGEN (or PINVER) key type to produce a 64-bit quantity. 2.
CCA Release 2.54 IBM 3624 PIN Offset Calculation Method The IBM 3624 PIN Offset calculation method is the same as the IBM 3624 PIN-calculation method except that a step is added after the A-PIN is calculated to calculate or use an offset, O-PIN: To calculate an O-PIN, the additional step subtracts (digit-by-digit, modulo 10, with no carry) the calculated A-PIN from the customer-selected C-PIN.
CCA Release 2.54 Netherlands PIN-1 Calculation Method The Netherlands PIN-1 (NL-PIN-1) calculation method calculates a PIN that is 4 digits in length. The method consists of the following steps to create the A-PIN: 1. Encrypt the hexadecimal validation data with a key that has a control vector that specifies the PINGEN (or PINVER) key type to produce a 64-bit quantity. 2.
CCA Release 2.54 IBM German Bank Pool Institution PIN-Calculation Method The IBM German Bank Pool Institution PIN calculation method calculates an institution PIN that is 4 digits in length. The German Bank Pool Institution PIN-calculation method consists of the following steps: 1. Encrypt the hexadecimal validation data with an institution key that has a control vector that specifies the PINGEN (or PINVER) key type to get a 64-bit quantity. 2.
CCA Release 2.54 VISA PIN Validation Value (PVV) Calculation Method The VISA-PVV calculation method calculates a VISA-PVV that is 4 digits in length. The VISA PIN Validation Value (PVV) calculation method consists of the following steps: 1. Let X denote the transaction_security_parameter element. This parameter is the result of concatenating the 12-numeric-digit generating data (a portion of the account number) with the 4-numeric-digit customer-entered PIN.
CCA Release 2.54 Interbank PIN-Calculation Method The Interbank PIN-calculation method consists of the following steps: 1. Let X denote the transaction_security_parameter element converted to an array of sixteen 4-bit numeric values. This parameter consists of (in the following sequence) the 11 rightmost digits of the customer PAN (excluding the check digit), a constant of 6, a 1-digit key indicator, and a 3-digit validation field. 2.
CCA Release 2.54 PIN-Block Formats The PIN verbs support one or more of the following PIN-block formats: IBM 3624 format ISO-0 format (same as the ANSI X9.8, VISA-1, and ECI formats). ISO-1 format (same as the ECI-4 format) ISO-2 format 3624 PIN-Block Format The 3624 PIN-block format supports a PIN from 1 to 16 digits in length. A PIN that is longer than 16 digits is truncated on the right.
CCA Release 2.54 ISO-0 PIN-Block Format An ISO-0 PIN-block format is equivalent to the ANSI X9.8, VISA-1, and ECI-1 PIN-block formats. The ISO-0 PIN-block format supports a PIN from 4 to 12 digits in length. A PIN that is longer than 12 digits is truncated on the right.
CCA Release 2.54 ISO-1 PIN-Block Format The ISO-1 PIN-block format is equivalent to an ECI-4 PIN-block format. The ISO-1 PIN-block format supports a PIN from 4 to 12 digits in length. A PIN that is longer than 12 digits is truncated on the right.
CCA Release 2.54 ISO-2 PIN-Block Format The ISO-2 PIN-block format supports a PIN from 4 to 12 digits in length. A PIN that is longer than 12 digits is truncated on the right. The following is the ISO-2 PIN-block format: 1 2 3 4 5 6 7 8 9 1 11 12 13 14 15 16 ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │ 2 │ L │ P │ P │ P │ P │P/F│P/F│P/F│P/F│P/F│P/F│P/F│P/F│ F │ F │ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ Figure E-5.
CCA Release 2.54 UKPT Calculation Methods This section describes the calculation methods for deriving the unique-key-per-transaction (UKPT) key according to ANSI X9.24 and performing the special encryption and special decryption processes.1 Deriving an ANSI X9.24 Unique-Key-Per-Transaction Key To determine the current-transaction encrypting key used by a terminal which is encrypting PIN-blocks under the ANSI X9.24 standard, the ANSI X9.
CCA Release 2.54 a. Move the rightmost 8 bytes of the current key serial number to a work area (Wa). b. Move the rightmost 3 bytes of Wa to another work area (Ca). c. Perform an AND operation with the rightmost 3 bytes of Wa with X'E00000'. This operation clears the encryption counter from Wa. d. Perform an AND operation with Ca and X'1FFFFF'. This operation clears the low-order bits of the initial serial number from the encryption counter. e. Initialize a 3-byte area to X'100000'; name the result Sa. f.
CCA Release 2.54 The following is an example of calculating the current PIN encrypting key: Wa = X'4567 89AB CDE ' Ca = X'1 1' Sa = X'1 ' 1 Ta = X'4567 89AB CDF ' 1 Tb = X'6489 F5A3 1618 2 AB' 1 Tc = X'F9AC C638 1939 44BC' 1 Ka = X'D842 BA3 C2D1 6417' 2. ..
CCA Release 2.54 CVV and CVC Method Figure E-62 shows the method used to generate a card-verification value (CVV) for track 2. Each (decimal) digit is represented as a 4-bit, binary value and packed two digits per byte.
CCA Release 2.54 VISA and EMV-Related Smart Card Formats and Processes The VISA and EMV specifications for performing secure messaging with an EMV compliant smart card are covered in these documents: EMV 2000 Integrated Circuit Card Specification for Payment Systems Version 4.0 (EMV4.0) Book 2 Design VISA Integrated Circuit Card Specification Manual. Book 2, Annex A1.3, describes how a smart-card, card-specific authentication code is derived from a card-issuer-supplied authentication key (MAC-MDK).
CCA Release 2.54 3. Set the second digit of block-2 to the length of the new PIN (4 to 12), followed by the new PIN, and padded to the right with X'F'. 4. Include any current PIN by placing it into the leftmost digits of block-3. 5. Exclusive-OR blocks -1, -2, and -3 to form the 8-byte PIN block. 6. Pad the PIN block with other portions of the message for the smart card: Prepend X'80' Append X'80' Append and additional six bytes of X'00'.
CCA Release 2.54 TDESEMV2 causes processing with a branch factor of 2 and a height of 16. TDESEMV4 causes processing with a branch factor of 4 and a height of 8. PIN-Block Self-encryption In the Secure_Messaging_for_PINs (CSNBSPN) verb, you can use the SELFENC rule-array keyword to specify that the eight-byte PIN block shall be used as a DES key to encrypt the PIN block. The verb appends the self-encrypted PIN block to the clear PIN-block in the output message. Appendix E.
CCA Release 2.54 E-20 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Appendix F. Verb List This appendix lists the verbs supported by the CCA Support Program feature for the IBM 4758 PCI Cryptographic Coprocessor. Figure F-1 lists each verb by the verb’s pseudonym and entry-point name and shows the operating environment under which the verb is supported. A check (√) in the operating environment column means that the verb is available for use in that operating environment. Figure F-1 (Page 1 of 3).
CCA Release 2.54 Figure F-1 (Page 2 of 3).
CCA Release 2.54 Figure F-1 (Page 3 of 3).
CCA Release 2.54 F-4 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Appendix G. Access-Control-Point Codes The table in this appendix lists the CCA access-control commands (“control points”). The role to which a user is assigned determines the commands available to that user. Important: By default, you should disable commands. Do not enable a command unless you know why you are enabling it. The table includes the following columns: Offset The hexadecimal offset for the command; offsets between X'0000' and X'FFFF' not listed in this table are reserved.
CCA Release 2.54 Figure G-1 (Page 1 of 4).
CCA Release 2.54 Figure G-1 (Page 2 of 4).
CCA Release 2.54 Figure G-1 (Page 3 of 4).
CCA Release 2.54 Figure G-1 (Page 4 of 4).
CCA Release 2.54 G-6 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.
CCA Release 2.54 ROM Read-Only Memory SNA Systems Network Architecture RPQ Request for Price Quotation TLV Tag, Length, Value RSA Rivest, Shamir, and Adleman TSS Transaction Security System SAA Systems Application Architecture UKPT Unique-Key-Per-Transaction SAF System Authorization Facility VM Virtual Machine SHA Secure Hashing Algorithm X-2 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Glossary This glossary includes some terms and definitions from the IBM Dictionary of Computing, New York: McGraw Hill, 1994. This glossary also includes some terms and definitions from: The American National Standard Dictionary for Information Systems, ANSI X3.172-1990, copyright 1990 by the American National Standards Institute (ANSI). Copies may be purchased from the American National Standards Institute, 11 West 42 Street, New York, New York 10036.
CCA Release 2.54 B bus. In a processor, a physical facility along which data is transferred. byte. (1) A binary character operated on as a unit and usually shorter than a computer word. (A) (2) A string that consists of a number of bits, treated as a unit, and representing a character. (3) A group of eight adjacent binary digits that represents one EBCDIC character. control vector (CV).
CCA Release 2.54 decipher. (1) To convert enciphered data into clear data. (2) Synonym for decrypt. (3) Contrast with encipher. decode. (1) To convert data by reversing the effect of some previous encoding. (A) (I) (2) In the CCA products, decode and encode relate to the Electronic Code Book mode of the Data Encryption Standard (DES). (3) Contrast with encode and decipher.. decrypt. (1) To decipher or decode. (2) Synonym for decipher. (3) Contrast with encrypt. device driver.
CCA Release 2.54 H host. (1) In this publication, same as host computer or host processor. The machine in which the Coprocessor resides. (2) In a computer network, the computer that usually performs network-control functions and provides end-users with services such as computation and database access. (T) I IMPORTER key. (1) In the CCA implementation, a type of DES Key-Encrypting Key that can decipher a key at a receiving mode. (2) Contrast with EXPORTER key. initialize.
CCA Release 2.54 N National Institute of Science and Technology (NIST). This is the current name for the US National Bureau of Standards. network. (1) A configuration of data-processing devices and software programs connected for information interchange. (2) An arrangement of nodes and connecting branches. (T) Network Security Processor (IBM 4753).
CCA Release 2.54 reason code. (1) A value that provides a specific result as opposed to a general result. (2) Contrast with return code. (2) The period of time during which a user of a terminal can communicate with an interactive system (usually, the elapsed time between logon and logoff). replicated key-half. In the CCA implementation, a double-length DES key where the two halves of the clear-key value are equal. Session-Level Encryption (SLE).
CCA Release 2.54 U Unique Key Per Transaction (UKPT). UKPT is a cryptographic process that can be used to decipher PIN blocks in a transaction. user-exit routine. A user-written routine that receives control at predefined user-exit points. user ID. User identification. computer and its associated devices. Each virtual machine is controlled by a suitable operating system. VM controls concurrent execution of multiple virtual machines on one host computer. VISA.
CCA Release 2.54 X-10 IBM 4758 CCA Basic Services, Release 2.
CCA Release 2.54 Index A Access Control, CCA 2-2 Access_Control_Initialization (CSUAACI) 2-21 Access_Control_Maintenance (CSUAACM) 2-24 American Express transaction validation verb 8-75 American National Standards Institute (ANSI) X3.106 (CBC) method D-7 X9.19 method D-13 X9.23 method D-7 X9.9 method D-13 ANSI X9.24 DUKPT 8-37, 8-42 ANSI X9.
CCA Release 2.
CCA Release 2.
CCA Release 2.
CCA Release 2.
CCA Release 2.
CCA Release 2.
IBM CCA Release 2.
