Linux for System z: Secure Key Solution with the Common ... · Cryptographic Architecture...

Linux for System z

Secure Key Solution with the CommonCryptographic Architecture ApplicationProgrammer's GuideVersion 4.2.10

SC33-8294-04

NoteBefore using this information and the product it supports, read the information in Notices on page 781.

Fifth Edition (January 2014)

This edition applies to the Common Cryptographic Architecture (CCA) API, Release 4.2.10, 4.2.0, 4.1.0, 4.0.0, and3.60 for Linux on IBM System z, and to all subsequent releases and modifications until otherwise indicated in neweditions.

This edition replaces SC33-8294-03.

This book is for planning and programming purposes only.

IBM welcomes your comments. A form for readers' comments may be provided at the back of this document, oryou may address your comments to the following address:

IBM Deutschland Research & Development GmbHInformation DevelopmentDepartment 3248Schoenaicher Strasse 22071032 BoeblingenGermany

Internet e-mail: [email protected]

If you would like a reply, be sure to include your name, address, telephone number, or FAX number.

Make sure to include the following in your comment or note:v Title and order number of this documentv Page number or topic related to your commentWhen you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

Copyright IBM Corporation 2007, 2014.US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . xi

About this document . . . . . . . . xvRevision history . . . . . . . . . . . . . xv

Fifth edition, January 2014, CCA SupportProgram Release 4.2.10 . . . . . . . . . xvFourth edition, February 2012, CCA SupportProgram Release 4.2 . . . . . . . . . . xvThird edition, March 2011, CCA SupportProgram Release 4.1.0 . . . . . . . . . xviiSecond edition, April 2010, CCA SupportProgram Release 4.0.0 . . . . . . . . . xviii

Who should use this document . . . . . . . xixDistribution-specific information . . . . . . . xixRestrictions . . . . . . . . . . . . . . xxTerminology . . . . . . . . . . . . . . xxiHardware requirements . . . . . . . . . . xxiHow to use this document . . . . . . . . . xxiiWhere to find more information . . . . . . . xxiv

Cryptography publications . . . . . . . . xxvDo you have problems, comments, orsuggestions? . . . . . . . . . . . . . xxvii

Part 1. IBM CCA programming . . . . 1

Chapter 1. Introduction to programmingfor the IBM Common CryptographicArchitecture . . . . . . . . . . . . . 3Available Common Cryptographic Architecture verbs 3Common Cryptographic Architecture functionaloverview . . . . . . . . . . . . . . . 4

How application programs obtain service. . . . 8Overlapped processing and load balancing . . . 8

Host-side key caching . . . . . . . . . 9Multi-coprocessor capabilities. . . . . . . . 9

AUTOSELECT option . . . . . . . . . 9CPACF support . . . . . . . . . . . . . 12

Environment variables that affect CPACF usage 13CSU_HCPUACLR . . . . . . . . . . 13CSU_HCPUAPRT . . . . . . . . . . 13

Access control points that affect CPACF protectedkey operations . . . . . . . . . . . . 14CPACF operation (protected key) . . . . . . 14

Important note about CPACF service actionsand running applications . . . . . . . . 15Using keys with CPACF, protected key . . . 16Using keys with CPACF, clear key or no key 16

CCA library CPACF preparation at startup . . . 16Interaction between the 'default card' and use ofProtected Key CPACF . . . . . . . . . . 17Using the AUTOSELECT option and the use ofProtected Key CPACF . . . . . . . . . . 17

Security API programming fundamentals . . . . 17Verbs, variables, and parameters . . . . . . 18Commonly encountered parameters . . . . . 20

Parameters common to all verbs . . . . . 20Return code and reason code overview . . 21

The rule_array and other keyword parameters 21Key tokens, key labels, and key identifiers . . 21

How to compile and link CCA application programs 22Using the Master Key Process (CSNBMKP) verb 23Building C applications to use with the CCAlibraries . . . . . . . . . . . . . . 24Using the CCA JNI . . . . . . . . . . . 24

Methods for calling the CCA JNI . . . . . 24Method using the Java packageinfrastructure . . . . . . . . . . . 24Deprecated method used with prior CCAversions . . . . . . . . . . . . 24

Entry points and data types used in the JNI 24JNI sample modules and sample code . . . 25Preparing your Java environment . . . . . 25Building Java applications to use with theCCA JNI . . . . . . . . . . . . . 26

Building the Java Byte code . . . . . . 26Running the Java Byte code . . . . . . 26

Building Java applications to use with theCCA JNI (deprecated method) . . . . . . 27

Building the Java Byte code . . . . . . 27Running the Java Byte code . . . . . . 27

Chapter 2. Using AES, DES, and HMACcryptography and verbs . . . . . . . 29Functions of the AES, DES and HMACcryptographic keys . . . . . . . . . . . . 29

Key separation . . . . . . . . . . . . 29Master key variant for fixed-length tokens . . . 30Transport key variant for fixed-length tokens . . 30Key forms . . . . . . . . . . . . . . 30

Symmetric key (DES, AES) flow . . . . . 31Key token . . . . . . . . . . . . . . 31Key wrapping . . . . . . . . . . . . 33

AES key wrapping . . . . . . . . . . 33DES key wrapping . . . . . . . . . . 33ECB wrapping of DES keys (Original method) 33Enhanced CBC wrapping of DES keys(Enhanced method). . . . . . . . . . 34

Wrapping key derivation for enhancedwrapping of DES keys. . . . . . . . 34

Variable length token (AESKW method) . . . 36Control vector . . . . . . . . . . . . 36Types of keys . . . . . . . . . . . . . 36

Clear keys . . . . . . . . . . . . . 44Verbs for managing AES and DES key storage files 44Verbs for managing the PKA key storage file andPKA keys in the cryptographic engine . . . . . 44EC Diffie-Hellman key agreement models . . . . 44

Token agreement scheme . . . . . . . . . 44

Copyright IBM Corp. 2007, 2014 iii

|

||||

|||

Obtaining the raw "Z" value . . . . . . . . 45Improved remote key distribution . . . . . . . 45

Remote key loading . . . . . . . . . . 46Old remote key loading example . . . . . 47New remote key loading methods . . . . . 47

Verbs that support Secure Sockets Layer (SSL) . . . 47Enciphering and deciphering data . . . . . . . 48Managing data integrity and message authentication 48

Message authentication code processing . . . . 48Hashing functions . . . . . . . . . . . 49

Processing personal identification numbers . . . . 49Verifying credit card data. . . . . . . . . 50

Secure messaging . . . . . . . . . . . . 50Trusted Key Entry support . . . . . . . . . 51Typical sequences of CCA verbs . . . . . . . 51Using the CCA node and master key managementverbs . . . . . . . . . . . . . . . . 52Summary of the CCA nodes and resource controlverbs . . . . . . . . . . . . . . . . 53Summary of the AES, DES, and HMAC verbs . . . 54

Chapter 3. Introducing PKAcryptography and using PKA verbs . . 63PKA key algorithms . . . . . . . . . . . 63PKA master keys . . . . . . . . . . . . 63

Operational private keys . . . . . . . . . 64PKA verbs . . . . . . . . . . . . . . . 64Verbs supporting digital signatures . . . . . . 64Verbs for PKA key management . . . . . . . 65PKA key tokens . . . . . . . . . . . . . 65PKA key management . . . . . . . . . . . 66Key identifier for PKA key token . . . . . . . 67

Key label . . . . . . . . . . . . . . 67Key token . . . . . . . . . . . . . . 68

Internal key token . . . . . . . . . . 68External key token . . . . . . . . . . 68Null key token . . . . . . . . . . . 69

Summary of the PKA verbs . . . . . . . . . 69

Chapter 4. TR-31 symmetric-keymanagement . . . . . . . . . . . . 71

Part 2. CCA verbs . . . . . . . . . 75

Chapter 5. Using the CCA nodes andresource control verbs . . . . . . . . 77Cryptographic Facility Query (CSUACFQ) . . . . 77Cryptographic Facility Version (CSUACFV) . . . 108Cryptographic Resource Allocate (CSUACRA) . . 110Cryptographic Resource Deallocate (CSUACRD) 113Key Storage Initialization (CSNBKSI) . . . . . 116Master Key Process (CSNBMKP) . . . . . . . 119Random Number Tests (CSUARNT) . . . . . . 124

Chapter 6. Managing AES and DEScryptographic keys . . . . . . . . . 127Clear Key Import (CSNBCKI) . . . . . . . . 129Multiple Clear Key Import (CSNBCKM) . . . . 131Control Vector Generate (CSNBCVG) . . . . . 134

Control Vector Translate (CSNBCVT) . . . . . 137Cryptographic Variable Encipher (CSNBCVE) . . 141Data Key Export (CSNBDKX) . . . . . . . . 144Data Key Import (CSNBDKM). . . . . . . . 146Diversified Key Generate (CSNBDKG) . . . . . 148EC Diffie-Hellman (CSNDEDH) . . . . . . . 153Key Export (CSNBKEX) . . . . . . . . . . 164Key Generate (CSNBKGN) . . . . . . . . . 167Key Generate2 (CSNBKGN2) . . . . . . . . 176Key Import (CSNBKIM) . . . . . . . . . . 184Key Part Import (CSNBKPI) . . . . . . . . 187Key Part Import2 (CSNBKPI2). . . . . . . . 191Key Test (CSNBKYT) . . . . . . . . . . . 195Key Test2 (CSNBKYT2) . . . . . . . . . . 200Key Test Extended (CSNBKYTX) . . . . . . . 204Key Token Build (CSNBKTB) . . . . . . . . 209Key Token Build2 (CSNBKTB2) . . . . . . . 214Key Token Change (CSNBKTC) . . . . . . . 218Key Token Change2 (CSNBKTC2) . . . . . . 221Key Token Parse (CSNBKTP) . . . . . . . . 224Key Token Parse2 (CSNBKTP2) . . . . . . . 229Key Translate (CSNBKTR) . . . . . . . . . 239Key Translate2 (CSNBKTR2) . . . . . . . . 241PKA Decrypt (CSNDPKD) . . . . . . . . . 245PKA Encrypt (CSNDPKE) . . . . . . . . . 248Prohibit Export (CSNBPEX) . . . . . . . . 252Prohibit Export Extended (CSNBPEXX). . . . . 254Restrict Key Attribute (CSNBRKA) . . . . . . 256Random Number Generate (CSNBRNG) . . . . 260Random Number Generate Long (CSNBRNGL) 262Symmetric Key Export (CSNDSYX) . . . . . . 265Symmetric Key Generate (CSNDSYG) . . . . . 271Symmetric Key Import (CSNDSYI) . . . . . . 276Symmetric Key Import2 (CSNDSYI2) . . . . . 280

Chapter 7. Protecting data . . . . . . 285Modes of operation . . . . . . . . . . . 285

Cipher Block Chaining (CBC) mode . . . . . 285Electronic Code Book (ECB) mode . . . . . 285Processing rules . . . . . . . . . . . 286Triple-DES encryption . . . . . . . . . 286

Decipher (CSNBDEC) . . . . . . . . . . 288Encipher (CSNBENC) . . . . . . . . . . 293Symmetric Algorithm Decipher (CSNBSAD) . . . 298Symmetric Algorithm Encipher (CSNBSAE) . . . 305

Chapter 8. Verifying data integrity andauthenticating messages . . . . . . 313How MACs are used . . . . . . . . . . . 313How hashing functions and MDCs are used . . . 314HMAC Generate (CSNBHMG) . . . . . . . 315HMAC Verify (CSNBHMV) . . . . . . . . 319MAC Generate (CSNBMGN) . . . . . . . . 323MAC Verify (CSNBMVR) . . . . . . . . . 327MDC Generate (CSNBMDG) . . . . . . . . 332One-Way Hash (CSNBOWH) . . . . . . . . 342

Chapter 9. Key storage mechanisms 345Key labels and key-storage management . . . . 345

iv Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

Key storage with Linux for IBM System z, incontrast to z/OS for IBM System z . . . . . . 348AES Key Record Create (CSNBAKRC) . . . . . 352AES Key Record Delete (CSNBAKRD) . . . . . 355AES Key Record List (CSNBAKRL) . . . . . . 357AES Key Record Read (CSNBAKRR) . . . . . 360AES Key Record Write (CSNBAKRW) . . . . . 362DES Key Record Create (CSNBKRC) . . . . . 365DES Key Record Delete (CSNBKRD) . . . . . 367DES Key Record List (CSNBKRL) . . . . . . 369DES Key Record Read (CSNBKRR) . . . . . . 372DES Key Record Write (CSNBKRW) . . . . . . 374PKA Key Record Create (CSNDKRC) . . . . . 376PKA Key Record Delete (CSNDKRD) . . . . . 378PKA Key Record List (CSNDKRL) . . . . . . 380PKA Key Record Read (CSNDKRR) . . . . . . 383PKA Key Record Write (CSNDKRW) . . . . . 385Retained Key Delete (CSNDRKD) . . . . . . 387Retained Key List (CSNDRKL) . . . . . . . 390

Chapter 10. Financial services . . . . 393How personal identification numbers (PINs) areused . . . . . . . . . . . . . . . . 393How VISA card verification values are used . . . 393Translating data and PINs in networks . . . . . 394Working with Europay-Mastercard-Visa Smartcards . . . . . . . . . . . . . . . . 394PIN verbs . . . . . . . . . . . . . . 395ANSI X9.8 PIN restrictions . . . . . . . . . 397The PIN profile. . . . . . . . . . . . . 399Clear PIN Encrypt (CSNBCPE) . . . . . . . 405Clear PIN Generate (CSNBPGN) . . . . . . . 408Clear PIN Generate Alternate (CSNBCPA) . . . . 412CVV Generate (CSNBCSG) . . . . . . . . . 417CVV Key Combine (CSNBCKC) . . . . . . . 421CVV Verify (CSNBCSV) . . . . . . . . . . 426Encrypted PIN Generate (CSNBEPG) . . . . . 430Encrypted PIN Translate (CSNBPTR) . . . . . 435Encrypted PIN Verify (CSNBPVR) . . . . . . 441PIN Change/Unblock (CSNBPCU) . . . . . . 446Secure Messaging for Keys (CSNBSKY). . . . . 453Secure Messaging for PINs (CSNBSPN) . . . . 457Transaction Validation (CSNBTRV) . . . . . . 462

Chapter 11. Using digital signatures 467Digital Signature Generate (CSNDDSG) . . . . 468Digital Signature Verify (CSNDDSV) . . . . . 473

Chapter 12. Managing PKAcryptographic keys . . . . . . . . . 477PKA Key Generate (CSNDPKG) . . . . . . . 478PKA Key Import (CSNDPKI) . . . . . . . . 484PKA Key Token Build (CSNDPKB) . . . . . . 488PKA Key Token Change (CSNDKTC) . . . . . 497PKA Key Translate (CSNDPKT) . . . . . . . 500PKA Public Key Extract (CSNDPKX) . . . . . 504Remote Key Export (CSNDRKX) . . . . . . . 506Trusted Block Create (CSNDTBC) . . . . . . 517

Chapter 13. TR-31 symmetric keymanagement verbs . . . . . . . . . 523Key Export to TR31 (CSNBT31X) . . . . . . . 524TR31 Key Import (CSNBT31I) . . . . . . . . 553TR31 Key Token Parse (CSNBT31P) . . . . . . 578TR31 Optional Data Build (CSNBT31O) . . . . 583TR31 Optional Data Read (CSNBT31R) . . . . . 587

Part 3. Appendixes . . . . . . . . 591

Appendix A. Return codes and reasoncodes. . . . . . . . . . . . . . . 593Return codes . . . . . . . . . . . . . 593Reason codes . . . . . . . . . . . . . 593

Reason codes that accompany return code 0 . . 594Reason codes that accompany return code 4 . . 595Reason codes that accompany return code 8 . . 595Reason codes that accompany return code 12 606Reason codes that accompany return code 16 607

Appendix B. Key token formats . . . 609AES internal key token . . . . . . . . . . 609

Token Validation Value . . . . . . . . . 610DES internal key token . . . . . . . . . . 612DES external key token . . . . . . . . . . 613External RKX DES key tokens . . . . . . . . 613DES null key token . . . . . . . . . . . 615RSA public key token . . . . . . . . . . 615RSA private external key token . . . . . . . 616

RSA private key token, 4096-bitModulus-Exponent external form. . . . . . 618RSA private key, 4096-bit Modulus-Exponentformat with AES encrypted OPK sectionexternal form . . . . . . . . . . . . 619RSA private key, 4096-bit Chinese RemainderTheorem format with AES encrypted OPKsection external form . . . . . . . . . . 621RSA Private Key Token, 4096-bit ChineseRemainder Theorem External Form . . . . . 623

RSA private internal key token . . . . . . . 624RSA private key token, 4096-bitModulus-Exponent internal format . . . . . 628RSA private key, 4096-bit Modulus-Exponentformat with AES encrypted OPK sectioninternal form . . . . . . . . . . . . 630RSA private key, 4096-bit Chinese RemainderTheorem format with AES encrypted OPKsection internal form . . . . . . . . . . 632RSA Private Key Token, 4096-bit ChineseRemainder Theorem Internal Form . . . . . 634

ECC key token . . . . . . . . . . . . . 636PKA null key token . . . . . . . . . . . 640HMAC key token . . . . . . . . . . . . 640

HMAC variable-length symmetric key token 640HMAC symmetric null key token . . . . . 646

TR-31 optional block data . . . . . . . . . 646Trusted blocks . . . . . . . . . . . . . 647

Trusted block organization . . . . . . . . 648

Contents v

||||||||||||||

|||||||||||

Appendix C. Key forms and typesused in the Key Generate verb . . . . 663Generating an operational key. . . . . . . . 663Generating an importable key . . . . . . . . 663Generating an exportable key . . . . . . . . 663Examples of single-length keys in one form only 663Examples of OPIM single-length, double-length,and triple-length keys in two forms . . . . . . 664Examples of OPEX single-length, double-length,and triple-length keys in two forms . . . . . . 664Examples of IMEX single-length and double-lengthkeys in two forms . . . . . . . . . . . . 665Examples of EXEX single-length and double-lengthkeys in two forms . . . . . . . . . . . . 665

Appendix D. Control vectors andchanging control vectors with theControl Vector Translate verb . . . . 667Control vector table . . . . . . . . . . . 667

Control-vector-base bit maps . . . . . . . 669Key Form Bits, 'fff' . . . . . . . . . . 673Specifying a control-vector-base value . . . . 673

Changing control vectors with the Control VectorTranslate verb . . . . . . . . . . . . . 678

Providing the control information for testing thecontrol vectors . . . . . . . . . . . . 678Mask array preparation . . . . . . . . . 678Selecting the key-half processing mode . . . . 680When the target key-token CV is null . . . . 682Control vector translate example . . . . . . 682

Appendix E. PIN formats andalgorithms. . . . . . . . . . . . . 683PIN notation . . . . . . . . . . . . . 683PIN block formats . . . . . . . . . . . . 683PIN extraction rules . . . . . . . . . . . 686IBM PIN algorithms . . . . . . . . . . . 687VISA PIN algorithms . . . . . . . . . . . 693

Appendix F. Cryptographic algorithmsand processes . . . . . . . . . . . 697Cryptographic key-verification techniques . . . . 697Modification Detection Code calculation . . . . 700Ciphering methods . . . . . . . . . . . 702MAC calculation methods . . . . . . . . . 709

Keyed-hash MAC (HMAC) . . . . . . . . 711RSA key-pair generation. . . . . . . . . . 711Multiple decipherment and encipherment . . . . 712PKA92 key format and encryption process . . . 718Formatting hashes and keys in public-keycryptography . . . . . . . . . . . . . 720

Appendix G. Access control pointsand verbs . . . . . . . . . . . . . 723TKE Version 6.0 and higher . . . . . . . . 739

Appendix H. Sample verb call routines 743Sample program in C. . . . . . . . . . . 743

Sample program in Java . . . . . . . . . . 747

Appendix I. Initial system set up tips 753Installing and loading the cryptographic devicedriver . . . . . . . . . . . . . . . . 753Unloading the cryptographic device driver . . . 754Confirming your cryptographic devices . . . . 754Checking the adapter settings . . . . . . . . 754Performance tuning . . . . . . . . . . . 755Running secure key under a z/VM guest . . . . 755

Appendix J. CCA installationinstructions . . . . . . . . . . . . 757Before you begin . . . . . . . . . . . . 757Default installation directory . . . . . . . . 757Download and install the RPM . . . . . . . 758

Files in the RPM . . . . . . . . . . . 758Samples in the RPM . . . . . . . . . . 760Groups in the RPM . . . . . . . . . . 760Install and configure the RPM . . . . . . . 760

Uninstall the RPM. . . . . . . . . . . . 765

Appendix K. Coexistence of CEX3C orlater and CEX2C features . . . . . . 767Legacy support . . . . . . . . . . . . . 767

Concurrent installations . . . . . . . . . 767CEX3C or later and CEX2C co-installationtoleration . . . . . . . . . . . . . 768

Installing the csulcca RPM over anexisting xcryptolinz RPM . . . . . . 768Temporary toleration approach to avoidre-linking applications . . . . . . . 768Uninstalling the xcryptolinz RPM . . . 769Re-installing the xcryptolinz RPM withthe csulcca RPM installed . . . . . . 769Fixing the csulcca RPM install afterinstalling xcryptolinzGA on top of it . . 769Caveats . . . . . . . . . . . . 770

Dual Support: Key storage interactions . . . . 770Solution . . . . . . . . . . . . . 770

Dual Support: TKE catcher can run in only oneinstance . . . . . . . . . . . . . . 771

Appendix L. Utilities . . . . . . . . 773The panel.exe utility . . . . . . . . . . . 773

panel.exe syntax . . . . . . . . . . . 773panel.exe functions . . . . . . . . . . 774Using panel.exe for key storage initialization 775Using panel.exe for key storage reencipherwhen changing the master key . . . . . . 777

Accessibility . . . . . . . . . . . . 779

Notices . . . . . . . . . . . . . . 781Programming interface information . . . . . . 782Trademarks . . . . . . . . . . . . . . 782

vi Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

||

List of abbreviations . . . . . . . . 783

Glossary . . . . . . . . . . . . . 789

Index . . . . . . . . . . . . . . . 801

Contents vii

viii Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

Figures

1. CCA security API, access layer, andcryptographic engine. . . . . . . . . . 4

2. CPACF . . . . . . . . . . . . . . 153. Control Vector Generate and Key Token Build

CV keyword combinations for fixed-lengthDES key tokens . . . . . . . . . . . 43

4. PKA key management . . . . . . . . . 665. Control vector base bit map (common bits

and key-encrypting keys) . . . . . . . 6706. Control vector base bit map (data operation

keys) . . . . . . . . . . . . . . 6717. Control vector base bit map (PIN processing

keys and cryptographic variable-encryptingkeys) . . . . . . . . . . . . . . 672

8. Control vector base bit map (key generatingkeys) . . . . . . . . . . . . . . 673

9. Control Vector Translate verb mask_arrayprocessing . . . . . . . . . . . . 680

10. Control Vector Translate verb . . . . . . 68111. ISO-3 PIN-block format . . . . . . . . 68412. 3624 PIN generation algorithm. . . . . . 68813. GBP PIN generation algorithm . . . . . . 68914. PIN-Offset generation algorithm . . . . . 690

15. PIN verification algorithm . . . . . . . 69116. GBP PIN verification algorithm . . . . . 69317. PVV generation algorithm . . . . . . . 69418. Triple-DES data encryption and decryption 70319. Enciphering using the ANSI X3.106 CBC

method . . . . . . . . . . . . . 70420. Deciphering using the CBC method . . . . 70421. Enciphering using the ANSI X9.23 method 70522. Deciphering using the ANSI X9.23 method 70623. Triple-DES CBC encryption process . . . . 70724. Triple-DES CBC decryption process . . . . 70725. EDE algorithm . . . . . . . . . . . 70826. DED process . . . . . . . . . . . . 70927. MAC calculation method . . . . . . . 71028. Multiple encipherment of single-length keys 71329. Multiple decipherment of single-length keys 71430. Multiple encipherment of double-length keys 71531. Multiple decipherment of double-length keys 71632. Multiple encipherment of triple-length keys 71733. Multiple decipherment of triple-length keys 71834. Syntax, sample routine in C. . . . . . . 74335. Syntax, sample routine in Java . . . . . . 748

Copyright IBM Corp. 2007, 2014 ix

x Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

Tables

1. Verbs that ignore AUTOSELECT . . . . . 102. Key types . . . . . . . . . . . . . 403. Key subtypes specified by the rule_array

keyword . . . . . . . . . . . . . 414. Access Control Points Used by ATM remote

key loading . . . . . . . . . . . . 465. Summary of CCA nodes and resource control

verbs. . . . . . . . . . . . . . . 536. Summary of CCA AES, DES, and HMAC verbs 547. Summary of PKA key token sections . . . . 658. Summary of PKA verbs . . . . . . . . 699. TR-31 symmetric key management verbs 72

10. Keywords for Cryptographic Facility Querycontrol information . . . . . . . . . . 79

11. Cryptographic Facility Query informationreturned in the rule_array . . . . . . . . 81

12. Output data format for the STATDECTkeyword . . . . . . . . . . . . . 93

13. Output data format for STATICSA operationalkey parts . . . . . . . . . . . . . 94

14. Output data format for STATICSB operationalkey parts . . . . . . . . . . . . . 96

15. Output data format for STATICSE operationalkey parts . . . . . . . . . . . . . 99

16. Output data format for STATICSX operationalkey parts . . . . . . . . . . . . . 101

17. Output data format for STATKPR operationalkey parts . . . . . . . . . . . . . 104

18. Output data format for STATVKPRoperational key parts . . . . . . . . . 105

19. Keywords for Cryptographic ResourceAllocate control information. . . . . . . 111

20. Keywords for Cryptographic ResourceDeallocate control information . . . . . . 114

21. Keywords for Key Storage Initializationcontrol information . . . . . . . . . 116

22. Keywords for Master Key Process controlinformation . . . . . . . . . . . . 120

23. Keywords for Random Number Tests controlinformation . . . . . . . . . . . . 124

24. Keywords for Multiple Clear Key Importcontrol information . . . . . . . . . 131

25. Keywords for Control Vector Translate controlinformation . . . . . . . . . . . . 138

26. Keywords for Diversified Key Generatecontrol information . . . . . . . . . 149

27. Skeleton key-tokens . . . . . . . . . 15428. Keywords for EC Diffie-Hellman control

information . . . . . . . . . . . . 15629. Keywords for the Key Generate verb

key_form parameter . . . . . . . . . 16830. Key length values for the Key Generate verb 16931. Key Generate - key lengths for each key type 17032. Keywords for Key Generate, valid key types

and key forms for a single key . . . . . . 174

33. Keywords for Key Generate, valid key typesand key forms for a key pair . . . . . . 174

34. Keywords for Key Generate2 controlinformation . . . . . . . . . . . . 177

35. Keywords and associated algorithms forkey_type_1 parameter. . . . . . . . . 178

36. Keywords and associated algorithms forkey_type_2 parameter. . . . . . . . . 178

37. Key Generate2 valid key type and key formfor one key . . . . . . . . . . . . 182

38. Key Generate2 valid key type and key formsfor two keys . . . . . . . . . . . . 182

39. AES KEK strength required for generating anHMAC key under an AES KEK . . . . . 182

40. Keywords for Key Part Import controlinformation . . . . . . . . . . . . 188

41. Keywords for Key Part Import2 controlinformation . . . . . . . . . . . . 192

42. Key Test parameter changes. . . . . . . 19543. Key Test GENERATE outputs and VERIFY

inputs . . . . . . . . . . . . . . 19544. Keywords for Key Test control information 19645. Keywords for Key Test2 control information 20146. Keywords for Key Test Extended control

information . . . . . . . . . . . . 20647. Keywords for Key Token Build control

information . . . . . . . . . . . . 21048. Keywords for Key Token Build2 control

information . . . . . . . . . . . . 21549. Keywords for Key Token Change control

information . . . . . . . . . . . . 21850. Keywords for Key Token Change2 control

information . . . . . . . . . . . . 22151. Keywords for Key Token Parse control

information . . . . . . . . . . . . 22552. Keywords for Key Token Parse2 control

information . . . . . . . . . . . . 23153. Keywords for Key Translate2 control

information . . . . . . . . . . . . 24254. Keywords for PKA Decrypt control

information . . . . . . . . . . . . 24555. Keywords for PKA Encrypt control

information . . . . . . . . . . . . 24856. Keywords for Restrict Key Attribute control

information . . . . . . . . . . . . 25657. Keywords for Random Number Generate

form parameter . . . . . . . . . . . 26058. Keywords for Random Number Generate

Long control information . . . . . . . 26259. Keywords for Symmetric Key Export control

information . . . . . . . . . . . . 26660. AES EXPORTER strength required for

exporting an HMAC key under an AESEXPORTER . . . . . . . . . . . . 269

Copyright IBM Corp. 2007, 2014 xi

||

61. Minimum RSA modulus strength required tocontain a PKOAEP2 block when exporting anAES key . . . . . . . . . . . . . 269

62. Minimum RSA modulus length to adequatelyprotect an AES key . . . . . . . . . 269

63. Keywords for Symmetric Key Generatecontrol information . . . . . . . . . 272

64. Keywords for Symmetric Key Import controlinformation . . . . . . . . . . . . 276

65. Keywords for Symmetric Key Import2 controlinformation . . . . . . . . . . . . 280

66. PKCS#1 OAEP encoded message layout(PKOAEP2) . . . . . . . . . . . . 283

67. Keywords for Decipher control information 29068. Keywords for Encipher control information 29569. Keywords for Symmetric Algorithm Decipher

control information . . . . . . . . . 30070. Keywords for Symmetric Algorithm Encipher

control information . . . . . . . . . 30771. Keywords for HMAC Generate control

information . . . . . . . . . . . . 31672. Keywords for HMAC Verify control

information . . . . . . . . . . . . 31973. Keywords for MAC Generate control

information . . . . . . . . . . . . 32474. Keywords for MAC Verify control

information . . . . . . . . . . . . 32875. Keywords for MDC Generate control

information . . . . . . . . . . . . 33476. Keywords for One-Way Hash control

information . . . . . . . . . . . . 34277. Valid symbols for the name token. . . . . 34778. Key labels that are not valid . . . . . . 34779. Keywords for AES Key Record Delete control

information . . . . . . . . . . . . 35580. Keywords for AES Key Record Write control

information . . . . . . . . . . . . 36281. Keywords for DES Key Record Delete control

information . . . . . . . . . . . . 36782. Keywords for PKA Key Record Delete control

information . . . . . . . . . . . . 37883. Keywords for PKA Key Record Write control

information . . . . . . . . . . . . 38584. ANSI X9.8 PIN - Allow only ANSI PIN blocks 39885. Format of a PIN profile . . . . . . . . 39986. Format values of PIN blocks . . . . . . 40087. PIN block format and PIN extraction method

keywords . . . . . . . . . . . . . 40088. Verbs affected by enhanced PIN security

mode . . . . . . . . . . . . . . 40289. Format of a pad digit . . . . . . . . . 40290. Pad digits for PIN block formats . . . . . 40291. Format of the Current Key Serial Number

Field . . . . . . . . . . . . . . 40392. Keywords for Clear PIN Encrypt control

information . . . . . . . . . . . . 40693. Keywords for Clear PIN Generate control

information . . . . . . . . . . . . 40994. Array elements for the Clear PIN Generate

verb . . . . . . . . . . . . . . 40995. Array elements for Clear PIN Generate 410

96. Keywords for Clear PIN Generate Alternatecontrol information . . . . . . . . . 413

97. Array elements for Clear PIN GenerateAlternate, data_array (IBM-PINO). . . . . 414

98. Array elements for Clear PIN GenerateAlternate, data_array (VISA-PVV). . . . . 415

99. Keywords for CVV Generate controlinformation . . . . . . . . . . . . 418

100. Key-wrapping matrix for the CVV KeyCombine verb . . . . . . . . . . . 423

101. Keywords for CVV Verify control information 426102. Keywords for Encrypted PIN Generate

control information . . . . . . . . . 431103. Array elements for Encrypted PIN Generate

data_array parameter . . . . . . . . . 432104. Keywords for Encrypted PIN Generate

control information . . . . . . . . . 432105. Keywords for Encrypted PIN Translate

control information . . . . . . . . . 437106. Additional names for PIN formats . . . . 440107. Keywords for Encrypted PIN Verify control

information . . . . . . . . . . . . 443108. Array elements for Encrypted PIN Verify

data_array parameter . . . . . . . . . 444109. Array elements required by the process rule 444110. Keywords for PIN Change/Unblock control

information . . . . . . . . . . . . 447111. Keywords for Secure Messaging for Keys

control information . . . . . . . . . 453112. Keywords for Secure Messaging for PINs

control information . . . . . . . . . 458113. Keywords for Transaction Validation control

information . . . . . . . . . . . . 462114. Values for Transaction Validation

validation_values parameter . . . . . . 464115. Keywords for Digital Signature Generate

control information . . . . . . . . . 469116. Keywords for Digital Signature Verify control

information . . . . . . . . . . . . 474117. Keywords for PKA Key Generate control

information . . . . . . . . . . . . 479118. Keywords for PKA Key Import control

information . . . . . . . . . . . . 485119. Keywords for PKA Key Token Build control

information . . . . . . . . . . . . 489120. PKA Key Token Build - Key value structure

length maximum values . . . . . . . . 490121. PKA Key Token Build - Key value structure

elements . . . . . . . . . . . . . 490122. Keywords for PKA Key Token Change control

information . . . . . . . . . . . . 498123. Keywords for PKA Key Translate control

information . . . . . . . . . . . . 501124. Keywords for Remote Key Export

certificate_parms parameter . . . . . . . 510125. Keywords for Trusted Block Create control

information . . . . . . . . . . . . 519126. Export translation table for a TR-31 BDK base

derivation key (BDK) . . . . . . . . . 531127. Export translation table for a TR-31 CVK card

verification key (CVK) . . . . . . . . 533

xii Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

128. Export translation table for a TR-31 dataencryption key (ENC). . . . . . . . . 534

129. Export translation table for a TR-31 keyencryption or wrapping, or key blockprotection key (KEK or KEK-WRAP). . . . 535

130. Export translation table for a TR-31 ISO MACalgorithm key (ISOMACn) . . . . . . . 536

131. Commands . . . . . . . . . . . . 537132. Export translation table for a TR-31 PIN

encryption or PIN verification key (PINENC,PINVO, PINV3624, VISAPVV) . . . . . . 540

133. Export translation table for a TR-31EMV/chip issuer master-key key(DKYGENKY, DATA) . . . . . . . . . 543

134. Import translation table for a TR-31 BDK basederivation key (usage "B0") . . . . . . . 558

135. Import translation table for a TR-31 CVK cardverification key (usage "C0") . . . . . . 558

136. Import translation table for a TR-31 dataencryption key (usage "D0"). . . . . . . 560

137. Import translation table for a TR-31 keyencryption or wrapping, or key blockprotection key (usages "K0", "K1"). . . . . 560

138. Import translation table for a TR-31 ISO MACalgorithm key (usages "M0", "M1", "M3") . . 562

139. Import translation table for a TR-31 PINencryption or PIN verification key (usages"P0", "V0", "V1", "V2") . . . . . . . . . 563

140. Commands . . . . . . . . . . . . 566141. Import translation table for a TR-31

EMV/chip issuer master-key key (usages"E0", "E1", "E2", "E3", "E4", "E5") . . . . . 568

142. TR31 Key Import CV sources . . . . . . 572143. TR31 Key Import protection methods 573144. Return code values . . . . . . . . . 593145. Reason codes for return code 0 . . . . . 594146. Reason codes for return code 4 . . . . . 595147. Reason codes for return code 8 . . . . . 595148. Reason codes for return code 12 . . . . . 606149. Reason codes for return code 16 . . . . . 607150. AES Internal key token format, version X'04' 609151. AES internal key-token flag byte . . . . . 610152. Internal clear key token format. . . . . . 611153. DES internal key token format . . . . . . 612154. DES external key token format. . . . . . 613155. External RKX DES key-token format, version

X'10' . . . . . . . . . . . . . . 614156. DES null key token format . . . . . . . 615157. RSA Public Key Token format . . . . . . 615158. RSA private external key token basic record

format . . . . . . . . . . . . . . 616159. RSA private key token, 1024-bit

Modulus-Exponent external format . . . . 617160. RSA Private Key Token, 4096-bit

Modulus-Exponent External Format . . . . 618161. RSA private key, 4096-bit Modulus-Exponent

format with AES encrypted OPK section(X'30') external form . . . . . . . . . 619

162. RSA private key, 4096-bit Chinese RemainderTheorem format with AES encrypted OPKsection (X'31') external form. . . . . . . 621

163. RSA Private Key Token, 4096-bit ChineseRemainder Theorem External Format . . . 623

164. RSA private internal key token basic recordformat . . . . . . . . . . . . . . 625

165. RSA private internal key token, 1024-bitModulus-Exponent format for cryptographiccoprocessor feature . . . . . . . . . 626

166. RSA private internal key token, 1024-bitModulus-Exponent starting with CEX3C . . 627

167. Private key, 4096-bit Modulus-Exponentformat section (X'09') . . . . . . . . . 629

168. RSA private key, 4096-bit Modulus-Exponentformat with AES encrypted OPK section(X'30') internal form . . . . . . . . . 630

169. RSA private key, 4096-bit Chinese RemainderTheorem format with AES encrypted OPKsection (X'31') internal form . . . . . . . 632

170. RSA Private Internal Key Token, 4096-bitChinese Remainder Theorem Internal Format . 634

171. RSA variable Modulus-Exponent token format 636172. Supported Prime elliptic curves by size,

name, and object identifier . . . . . . . 637173. Supported Brainpool elliptic curves by size,

name, and object identifier . . . . . . . 637174. ECC private-key section . . . . . . . . 637175. ECC public-key section . . . . . . . . 639176. PKA null key token format . . . . . . . 640177. HMAC variable-length symmetric key-token,

version X'05' (CCA 4.1.0 or later) . . . . . 640178. HMAC symmetric null key token format 646179. IBM optional block data in a TR-31 key block 647180. Trusted block sections and their use . . . . 648181. Trusted block header format . . . . . . 650182. Trusted block trusted RSA public key section

(X'11') . . . . . . . . . . . . . . 651183. Trusted block rule section (X'12') . . . . . 652184. Summary of trusted block X'12' subsections 653185. Transport key variant subsection (X'0001') of

trusted block rule section (X'12') . . . . . 654186. Transport key rule reference subsection

(X'0002') of trusted block rule section (X'12') . 655187. Common export key parameters subsection

(X'0003') of trusted block rule section (X'12') . 655188. Source key rule reference subsection (X'0004')

of trusted block rule section (X'12') . . . . 657189. Export key CCA token parameters subsection

(X'0005') of trusted block rule section (X'12') . 657190. Trusted block key label (name) section (X'13') 659191. Trusted block information section (X'14') 659192. Summary of trusted block information

subsections . . . . . . . . . . . . 660193. Protection information subsection (X'0001') of

trusted block information section (X'14') . . 660194. Activation and expiration dates subsection

(X'0002') of trusted block information section(X'14') . . . . . . . . . . . . . . 661

195. Trusted block application-defined data section(X'15') . . . . . . . . . . . . . . 662

196. Default control vector values . . . . . . 667197. Main key type bits . . . . . . . . . . 674198. Key subtype bits . . . . . . . . . . 674

Tables xiii

|||||||||||

|||

|

|||||||||||

199. Calculation method keyword bits . . . . . 675200. INGEN, IPINENC, and OPINENC key bits 676201. Generic key type bits . . . . . . . . . 676202. DKYGENKY key type bits . . . . . . . 677203. Versions of the MDC calculation method 701204. MDC calculation procedures . . . . . . 701

205. PKA96 clear DES key record . . . . . . 718206. Access Control Points and corresponding

CCA verbs . . . . . . . . . . . . 724207. Verbs called by the sample routines . . . . 743208. CCA groups . . . . . . . . . . . . 764

xiv Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

About this document

This document describes how to use the verbs provided in the CommonCryptographic Architecture (CCA) Release 4.2.10, 4.2.0, 4.1.0, 4.0.0, and 3.60 APIsfor Linux on IBM System z.

See Terminology on page xxi for the correct CCA feature terminology.

The CCA functions perform cryptographic operations using the following incoprocessor mode:v IBM 4765 Crypto Express4 feature (CEX4C)v IBM 4765 Crypto Express3 feature (CEX3C)v IBM 4764 Crypto Express2 feature (CEX2C)See Concurrent installations on page 767 for details.

This book is for planning and programming purposes only.

The CCA host software provides an application programming interface throughwhich applications request secure, high-speed cryptographic services from thehardware cryptographic features.

Where CCA Release 4.2.10 has been changed or enhanced from CCA Release 4.2.0,these changes have been noted.

Revision historyRevision history for this document for each CCA Support Program release.

Fifth edition, January 2014, CCA Support Program Release4.2.10

This edition describes the IBM CCA Basic Services API for Release 4.2.10.

For the supported environments and product ordering information, see:

http://www.ibm.com/security/cryptocards

For Linux for IBM System z, Release 4.2.10, changes to the CCA API include thefollowing added support:v DEV-ANY (AUTOSELECT) support added via CSUACRA, CSUACRD,

environment variable CSU_DEFAULT_ADAPTER, for automatic (simple) loadbalancing. See AUTOSELECT option on page 9.

v CCA key storage support for DES key tokens with Zero CVs.v CEX4C support and recognition for all verbs and utilities.

Fourth edition, February 2012, CCA Support Program Release4.2

This edition describes the IBM CCA Basic Services API for Release 4.2.


Copyright IBM Corp. 2007, 2014 xv

|||

||

|

|

|

|

||

||

|||

|

|



IMPORTANT

Two problems have been discovered with the CCA microcode related to the reencipheringof master keys. Although similar, the two problems are slightly different and exist indifferent levels of the microcode. These problems could lead to a loss of operational privatekeys after a master key change. Symmetric keys are not affected. Although it is expectedfew customers will be impacted this document describes the problems and how to recover.

For details, see http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/FLASH10764.

The PKA Key Token Change (CSNDKTC) verb has been changed to not permit the use ofthe RTNMK keyword for processor firmware levels that have this problem.

For Linux for IBM System z, Release 4.2, changes to the CCA API include:v These new verbs:

CVV Key Combine (CSNBCKC) EC Diffie-Hellman (CSNDEDH) Key Export to TR31 (CSNBT31X) Key Token Parse2 (CSNBKTP2) TR31 Key Import (CSNBT31I) TR31 Key Token Parse (CSNBT31P) TR31 Optional Data Build (CSNBT31O) TR31 Optional Data Read (CSNBT31R)

v Added support to improve security and control for PIN decimalization tables,and changes to the required access control points for these verbs: Clear PIN Generate (CSNBPGN) Clear PIN Generate Alternate (CSNBCPA) Encrypted PIN Generate (CSNBEPG) Encrypted PIN Verify (CSNBPVR)

v Added support for double-length keys to these verbs: CVV Generate (CSNBCSG) CVV Verify (CSNBCSV)

v Added support for variable-length AES keys to these verbs: Symmetric Algorithm Decipher (CSNBSAD) Symmetric Algorithm Encipher (CSNBSAE)

v Added rule-array keywords SHA-1 and SHA-256 to these verbs: Symmetric Key Generate (CSNDSYG) Symmetric Key Import (CSNDSYI)

v Added key usage NOT31XPT and T31XPTOK to this verb: Control Vector Generate (CSNBCVG)

v Updated control vector key combinations for fixed-length DES key tokens, forthese verbs: Control Vector Generate (CSNBCVG) Key Token Build (CSNBKTB)

v Added new rule-array keyword AES to these verbs: Key Part Import2 (CSNBKPI2)

xvi Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

http://www.ibm.com/security/cryptocardshttp://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/FLASH10764http://www.ibm.com/support/techdocs/atsmastr.nsf/WebIndex/FLASH10764

Key Token Change2 (CSNBKTC2) Symmetric Key Import2 (CSNDSYI2)

v Added new rule-array keyword AESKW to these verbs: Symmetric Key Export (CSNDSYX) Symmetric Key Import2 (CSNDSYI2)

v Added support for AES keys, and many other changes to this verb: Key Generate2 (CSNBKGN2)

v Added new rule-array keywords CLONE, OKEK-AES, and OKEK-DES to thisverb: PKA Key Generate (CSNDPKG)

v Added new keywords STATCRD2, NUM-DECT, STATDECT, STATVKPL, andSTATVKPR to this verb: Cryptographic Facility Query (CSUACFQ)

v Put an important warning in this verb: PKA Key Token Change (CSNDKTC)

v Added rule-array keywords AES, DES, ENC-ZERO, SHA-256, TR-31,IKEK-PKA, IKEK-DES, and IKEK-AES to this verb: Key Test2 (CSNBKYT2)

v Added rule-array keywords AES, DES, NOEX-AES, NOEX-DES, NOEX-RAW,NOEX-RSA, NOT31XPT, IKEK-AES, IKEK-DES, and IKEK-PKA to this verb: Restrict Key Attribute (CSNBRKA)

Third edition, March 2011, CCA Support Program Release 4.1.0This edition describes the IBM CCA Basic Services API for Release 4.1.0.



For Linux for IBM System z, Release 4.1.0 changes to the CCA API include:v Enhanced PIN security with the addition of ANSI X9.8 restriction capabilities

Three new access control points are added to enhance PIN security by blockingPIN attacks. See the Required commands sections of the Clear PIN GenerateAlternate (CSNBCPA), Encrypted PIN Translate (CSNBPTR), and SecureMessaging for PINs (CSNBSPN) verbs.

v Wrap CCA keys in Cipher-Block Chaining (CBC) modeA second key-wrapping method is added for DES that is a more secure versionof Triple-DES ECB mode currently used by CCA. The enhanced version of keywrapping complies with current cryptographic standards that require keybundling. This new key-wrapping method can coexist with the CCA legacy ECBmode of wrapping Triple-DES keys. The two methods can coexist on the same ormultiple systems.

v Elliptic Curve Cryptography (ECC) supportNew Elliptic Curve Cryptography (ECC) key generation, along with support fordigital signature generation and verification using the Elliptic Curve DigitalSignature Algorithm (ECDSA). This enhancement includes a new PKA key-tokenfor housing ECC public-key cryptographic keys and a new asymmetric APKAmaster-key (32-byte AES key) for wrapping an ECC key-token, along with addedsupport to the Master Key Process verb.

About this document xvii


v Hashed Message Authentication Code (HMAC) support for key generation andprocessing, but not for key storage.

v These new verbs: HMAC Generate (CSNBHMG) HMAC Verify (CSNBHMV) Key Generate2 (CSNBKGN2) Key Part Import2 (CSNBKPI2) Key Test2 (CSNBKYT2) Key Token Build2 (CSNBKTB2) Key Token Change2 (CSNBKTC2) Key Translate2 (CSNBKTR2) Restrict Key Attribute (CSNBRKA) Symmetric Key Import2 (CSNDSYI2)

Second edition, April 2010, CCA Support Program Release4.0.0

This edition describes the IBM CCA Basic Services API for Release 4.0.0. For thesupported environments and product ordering information.

See: http://www.ibm.com/security/cryptocards

For Linux for IBM System z, release 4.0.0 changes to the CCA API include:v Support for the IBM Crypto Express3 feature (CEX3C) in coprocessor modev A Java Native Interface (JNI) form for most of the verbsv Central Processor Assist for Cryptographic Functions (CPACF) supportv These new verbs:

AES Key Record Create (CSNBAKRC) AES Key Record Delete (CSNBAKRD) AES Key Record List (CSNBAKRL) AES Key Record Read (CSNBAKRR) AES Key Record Write (CSNBAKRW) Control Vector Translate (CSNBCVT) Cryptographic Facility Version (CSUACFV) Cryptographic Variable Encipher (CSNBCVE) Key Test Extended (CSNBKYTX) MDC Generate (CSNBMDG) PKA Key Translate (CSNDPKT) Prohibit Export Extended (CSNBPEXX) Random Number Generate Long (CSNBRNGL) Remote Key Export (CSNDRKX) Retained Key Delete (CSNDRKD) Retained Key List (CSNDRKL) Symmetric Algorithm Decipher (CSNBSAD) Symmetric Algorithm Encipher (CSNBSAE) Trusted Block Create (CSNDTBC)

xviii Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide


Who should use this documentThis document is intended for application programmers who are responsible forwriting application programs that use the security application programminginterface (API) to access cryptographic functions.

Distribution-specific informationIn order to use the full set of CCA Release 4.2.0 and later functions, a Linux onSystem z distribution with support for the CEX*C feature is required.v CCA Linux on System z maintenance Release 4.2.10 adds support for CEX4C.

These distributions introduced CEX4C exploitation: SUSE Linux Enterprise Server 11 SP3 (SLES 11 SP3) 64-bit only Red Hat Enterprise Linux 6 Update 4 (64-bit only)

v SUSE Linux Enterprise Server 11 SP2 (SLES 11 SP2) 64-bit onlyv SUSE Linux Enterprise Server 10 SP4 (SLES 10 SP4) 64-bit onlyv Red Hat Enterprise Linux 5 Update 7 (64-bit only)v Red Hat Enterprise Linux 6 Update 2 (64-bit only)v Distributions listed for CCA 4.1.0 below

The following Linux on System z distributions support CCA Release 4.1.0 hostsoftware for use with CEXC3. Support also extends to CEX2C within the functionalscope of the CEX2C feature:v SUSE Linux Enterprise Server 11 SP1 (SLES 11 SP1)v SUSE Linux Enterprise Server 10 SP3 (SLES 10 SP3)v Red Hat Enterprise Linux 5 Update 6v Red Hat Enterprise Linux 6

Note:

1. With the addition of CEX4C support, the name of the default install path(/opt/IBM/CEX3C/) has changed. For Release 4.2.10, a new default install path iscreated at /opt/IBM/CCA/. The former install path /opt/IBM/CEX3C/ is linked tothe new path to assist migration. If upgrading, note that the 4.2.10 rpm willcopy your key storage files from the old default location to the new defaultlocation. The old directory will also be renamed to be /opt/IBM/CEX3C-old/.

2. CEX*C can be loaded with firmware newer than release 4.2.10. This hostpackage supports the newer firmware, up to the verbs and keywords that it isaware of, consistent with firmware as of 4.2.10.

3. Applications linked with prior CCA host software will continue to function ifthe CCA host software is upgraded in place, however IBM always recommendsfull testing of upgrades before implementing production roll-out.

4. CCA 4.2 host software supports all prior levels of CEX3C adapter firmware andmay also be used for support of the CEX2C subset of functionality. Full CEX2Csupport is included in CCA Release 4.2.0 and 4.1.0. However, note that becauseof limits in the CEX2C hardware and firmware available, this is a limitedsubset of the CEX*C functions described in this document.

5. For current restrictions and recommendations about the usage of CCA 4.2.0 andlater releases with Linux on System z distributions, refer tohttp://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml.For a summary, see Restrictions on page xx.

About this document xix

|

||

|

|

|||

||||||

|

|

|

http://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml

6. Only 64-bit versions of this software are provided. 31-bit support is notprovided.

RestrictionsThis topic preserves known restrictions for current and prior releases to assistsystem administrators.

CCA 4.2 and later releases on Linux on System z:

Linux distribution applicabilityRefer to http://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml for current information about usage of CCA4.2.0 and later releases with specific Linux on System zdistributions.

General noteThe CCA host library (libcsulccas.so) was changed to allow moreflexible preparation of requests to be sent to the adapter. Thechange allows very large key block support, among other changes.The z90crypt device driver as it exists in currently available Linuxdistributions has the same limitation as older CCA host librarycode, and so a patch was prepared and submitted for maintenancereleases to 'in-service' Linux distributions.

IBM is working with our distribution partners to include a patch toremove these noted restrictions in future distributions.

General description of the restrictionVerbs that may send or return a lot of data (of certain types, suchas lists of key labels or key tokens) or large key tokens are limitedby an issue in the current version of the z90crypt device driverbuffer handling to a smaller amount of data or key token size thanwould normally be allowed.

The following scenarios clarify what to avoid to prevent thisrestriction from leading to errors.

Restriction scenario: Sending or requesting a large amount of certaintypes of data

CSNDRKLThis verb returns a list of labels or tokens for a specifiedset of retained keys. Specifying a large number for thekey_labels_count or retained_keys_count parameter canresult in more return data than the cryptographic devicedriver can handle. Because a key label is 64 bytes, do notspecify key_labels_count values greater than 75.

Crossing this limit results in return code 8 reason code1106 error, indicating the data is too large to be returned (itwould be truncated).

CSNDRKXThis verb has the potential to send large objects forparameters certificate, certificate_parms and extra_data.Avoid using a combined value for these parameters thatgreatly exceeds 4096 Bytes. The actual value of thethreshold varies with the size of other parameters and socannot be specified exactly.

xx Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

|

|

http://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtmlhttp://www.ibm.com/security/cryptocards/pciecc/ordersoftware.shtml

Crossing this limit results in error return code 8 reasoncode 343.

Restriction scenario: Processing extremely large key tokens

CSNBT31I, CSNBT31X, CSNBKYT2These verbs handle TR-31 key blocks, which can be up to9992 Bytes (if 9 KB or more of optional block sections havebeen added). Due to the z90crypt restriction, TR-31 keyblocks should be built specifying no more than 4096 Bytesof optional block sections.

Crossing this limit results in error return code 8 reasoncode 343.

TerminologyThe following terms are used in this document for CCA releases and features.

CCA 4.2CCA Release 4.2.0 and later releases

CEX2CAn IBM 4764 Crypto Express2 feature, configured in CCA coprocessormode.



CEX3C or CEX4CEither the CEX3C or the CEX4C.

CEX*CEither the CEX2C, CEX3C, CEX4C, or (if plural) any combination of these.

Hardware requirementsIn order to make use of the verbs provided in the Common CryptographicArchitecture (CCA) API for Linux on IBMSystem z, your hardware must meetcertain minimum requirements.

These minimum requirements are as follows:v IBM System z10 with the CEX3C support that became available in March 2010.v One CEXC3 feature, with one CEXC3 adapter mapped to the z/VM image or

LPAR that uses it. The CEXC3 must have CCA 4.2.0z or greater firmware loaded(in order to have available all of the CCA 4.2.0z function). Older levels offirmware are supported with reduced function available.

v If you plan to use a Trusted Key Entry (TKE) workstation, you must have a TKEV6.0 or higher workstation in order to see supported CEXC3s. They are not seenwhen using TKE V5 or earlier workstations.

This is the maximum supported hardware configuration:v IBM zEnterprise EC12v A maximum of eight CEX3Cs (each with two cryptographic processors), or

About this document xxi

||

||

|

|

|

|

|

|

|

v A maximum of 16 CEX4Ss (each with one cryptographic processor), orv Any combination of CEX3Cs and CEX4Cs, as long as the total does not exceed

16 processors.

This hardware configuration is also supported:v IBM System z10 with the CEX3C support that became available in March 2010.v One or more CEX*Cs, with CCA 4.2.0z or CCA 4.0.3z firmware loaded.v One or more CEX2Cs, with a supported level of CCA 3.x firmware loaded. See

Legacy support on page 767 for details.

See Concurrent installations on page 767 for details about a mixed environmentof CEX2C and CEX*C. Note that CEX4Cs are only supported by TKE 7.2 or later ifICSF reports them as CEX4s. If you are running in toleration mode, and ICSFreports them as CEX3Cs, then TKE 6.0 will be able to manage them as CEX3Cs.

To determine if a card is a CEX2C, a CEX3C, or a CEX4C, see Listing CCAcoprocessors on page 11.

In order to use the CEXC3 feature under z/VM Versions 6.1, and 5.4, you need toapply these APAR fixes:

VM64656Introduces CEXC3 support.

VM64727Fixes problem with shared coprocessors.

VM64793Introduces protected key CPACF support.

In order to use the CEX4C feature under z/VM Versions 5.4, 6.1 or 6.2, you mustapply this APAR fix:

VM65007Introduces CEX4C support.

How to use this documentAn overview of the information in each section of this document.

For encryption, CCA supports Advanced Encryption Standard (AES), DataEncryption Standard (DES), public key cryptography (PKA or RSA), and EllipticCurve Cryptography (ECC). These are very different cryptographic systems.Additionally, CCA provides APIs for generating and verifying MessageAuthentication Codes (MACs), Hashed Message Authentication Codes (HMACs),hashes, and PINS, as well as other cryptographic functions.

Part 1, IBM CCA programming, on page 1 focuses on IBM CCA programming. Itincludes the following chapters:v Chapter 1, Introduction to programming for the IBM Common Cryptographic

Architecture, on page 3 describes the programming considerations for using theCCA verbs. It also explains the syntax and parameter definitions used in verbs.Information about concurrency is also provided.

v Chapter 2, Using AES, DES, and HMAC cryptography and verbs, on page 29gives an overview of AES, DES, and HMAC cryptography, and provides generalguidance information on how these verbs use different key types and key forms.

xxii Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

|

||

|

|

|

|

||

||

v Chapter 3, Introducing PKA cryptography and using PKA verbs, on page 63introduces Public Key Algorithm (PKA) support and describes programmingconsiderations for using the CCA PKA and ECC verbs, such as the PKA keytoken structure and key management.

v Chapter 4, TR-31 symmetric-key management, on page 71 introduces TR-31support and how CCA uses an IBM-defined optional block in a TR-31 key block.

Part 2, CCA verbs, on page 75 focuses on CCA verbs and includes the followingchapters:v Chapter 5, Using the CCA nodes and resource control verbs, on page 77

describes using the CCA resource control verbs.v Chapter 9, Key storage mechanisms, on page 345 describes the use of key

storage, key tokens, and associated verbs.v Chapter 6, Managing AES and DES cryptographic keys, on page 127 describes

the verbs for generating and maintaining DES and AES cryptographic keys, theRandom Number Generate verb (which generates 8-byte random numbers), theRandom Number Generate Long verb (which generates up to 8192 bytes ofrandom content), and the Secure Sockets Layer (SSL) security protocol. Thischapter also describes utilities to build DES and AES tokens, generate andtranslate control vectors, and describes the PKA verbs that support DES and AESkey distribution.

v Chapter 7, Protecting data, on page 285 describes the verbs for encipheringand deciphering data.

v Chapter 8, Verifying data integrity and authenticating messages, on page 313describes the verbs for generating and verifying Message Authentication Codes(MACs), generating and verifying Hashed Message Authentication Codes(HMACs), generating Modification Detection Codes (MDCs), and generatinghashes (SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, MD5, RIPEMD-160).

v Chapter 10, Financial services, on page 393 describes the verbs for use insupport of finance-industry applications. This includes several categories. Verbs for generating, verifying, and translating personal identification

numbers (PINS). Verbs that generate and verify VISA card verification values and American

Express card security codes. Verbs to support smart card applications using the EMV (Europay

MasterCard Visa) standards.v Chapter 11, Using digital signatures, on page 467 describes the verbs that

support using digital signatures to authenticate messages.v Chapter 12, Managing PKA cryptographic keys, on page 477 describes the

verbs that generate and manage PKA keys.v Chapter 13, TR-31 symmetric key management verbs, on page 523 describes

the verbs used to manage TR-31 key blocks and TR-31 functions.

The appendixes include the following information:v Appendix A, Return codes and reason codes, on page 593 explains the return

and reason codes returned by the verbs.v Appendix B, Key token formats, on page 609 describes the formats for AES,

DES internal, external, and null key tokens, for PKA public, private external, andprivate internal key tokens containing Rivest-Shamir-Adleman (RSA)information, PKA null key tokens, ECC key tokens, HMAC key tokens,Transaction Validation Values (TVVs), and trusted blocks.

About this document xxiii

v Appendix C, Key forms and types used in the Key Generate verb, on page 663describes the key forms and types used by the Key Generate verb.

v Appendix D, Control vectors and changing control vectors with the ControlVector Translate verb, on page 667 contains a table of the default control vectorvalues that are associated with each key type and describes the controlinformation for testing control vectors, mask array preparation, selecting thekey-half processing mode, and an example of using the Control Vector Translateverb.

v Appendix E, PIN formats and algorithms, on page 683 describes the PINnotation, formats, extraction rules, and algorithms.

v Appendix F, Cryptographic algorithms and processes, on page 697 describesvarious ciphering and key verification algorithms, as well as the formatting ofhashes and keys.

v Appendix G, Access control points and verbs, on page 723 lists the accesscontrol points and their corresponding verbs.

v Appendix H, Sample verb call routines, on page 743 contains sample verb callroutines, both in C and Java, that illustrates the practical application of CCAverb calls.

v Appendix I, Initial system set up tips, on page 753 includes tips to help youset up your system for the first time.

v Appendix J, CCA installation instructions, on page 757 includes RPMinstallation, configuration, and uninstallation instructions.

v Appendix K, Coexistence of CEX3C or later and CEX2C features, on page 767includes information about using CEX2C and CEX*C features in the samesystem, and other restrictions.

v Appendix L, Utilities, on page 773 describes the ivp.e and panel.exe utilities.v Notices on page 781 contains notices, programming interface information, and

trademarks.v List of abbreviations on page 783 contains definitions of abbreviations used.v Glossary on page 789 contains definitions of terms used.

Where to find more informationIn addition to the documents listed in this topic, you might want to refer to otherCCA product publications.

These publications might be of use with applications and systems you mightdevelop for use with the IBM 4765 and IBM 4764. While there is substantialcommonality in the API supported by the CCA products, and while this documentseeks to guide you to a common subset supported by all CCA products, otherindividual product publications might provide further insight into potential issuesof compatibility.

IBM 4765 PCIe and IBM 4764 PCI-X Cryptographic CoprocessorsAll of the IBM 4765-related and 4764-related publications can be obtainedfrom the Library page that you can reach from the product Web site athttp://www.ibm.com/security/cryptocards

IBM 4765 PCIe Cryptographic Coprocessor CCA Support Program InstallationManual and the IBM 4764 PCI-X Cryptographic Coprocessor CCA SupportProgram Installation Manual

Describe the installation of the CCA Support Program and theoperation of the Cryptographic Node Management utility.

xxiv Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

|


IBM 4765 PCIe Cryptographic Coprocessor Installation Manual and the IBM4764 PCI-X Cryptographic Coprocessor Installation Manual

Describe the physical installation of the IBM 4765 and the IBM4764, and also the battery-changing procedure.

Custom Programming for the IBM 4765 and the IBM 4764The Library portion of the product Web site also includes programminginformation for creating applications that perform within the IBM 4765 andthe IBM 4764. See the reference to custom programming. The product Website is located at http://www.ibm.com/security/cryptocards

Other documents referenced in this book are:v IBM CCA Basic Services Reference and Guide for the IBM 4765 PCIe and IBM 4764

PCI-X Cryptographic Coprocessors

v IBM Common Cryptographic Architecture: Cryptographic Application ProgrammingInterface Reference, SC40-1675

v z/OS Cryptographic Services ICSF: Trusted Key Entry PCIX Workstation Users Guide,SA23-2211-05

v For Linux on IBM System z: Device Drivers, Features, and Commands, SC33-8411

See one of these Web Sites for the version of this book that is correct for yourdistribution of Linux:- http://www.ibm.com/developerworks/linux/linux390/

documentation_suse.htmlhttp://www.ibm.com/developerworks/linux/linux390/

documentation_red_hat.html

Cryptography publicationsThe following publications describe cryptographic standards, research, andpractices relevant to the coprocessor.v Accredited Standards Committee X9, Inc.: X9 TR-31 2010: Interoperable Secure Key

Exchange Block Specification for Symmetric Algorithms

v American National Standards Institute (ANSI). ANSI is the official U.S.representative to the International Organization for Standardization (ISO) and,via the U.S. National Committee, the International Electrotechnical Commission(IEC). ANSI is also a member of the International Accreditation Forum (IAF). ANSI X9.8-1:2003 Banking -- Personal Identification Number Management and

Security -- Part 1: PIN Protection Principles and Techniques for Online PINVerification in ATM & POS Systems.

ANSI X9.9:1986 Financial Institution Message Authentication (Wholesale). ANSI X9.19:1998 Financial Institution Retail Message Authentication. ANSI X9.23:1998 Financial Institution Encryption of Wholesale Financial Messages. ANSI X9.24-1:2004 Retail Financial Services Symmetric Key Management -- Part 1:

Using Symmetric Techniques.

ANSI X9.24-2:2006 Retail Financial Services Symmetric Key Management -- Part 2:Using Asymmetric Techniques for the Distribution of Symmetric Keys.

ANSI X9.31:1998 Digital Signature Using Reversible Public Key Cryptography forthe Financial Services Industry.

ANSI X9.52:1998 Triple Data Encryption Algorithm Modes of Operation. ANSI X9.62:2005 Public Key Cryptography for the Financial Services Industry: The

Elliptic Curve Digital Signature Algorithm (ECDSA).

About this document xxv

||

||

http://www.ibm.com/security/cryptocardshttp://www.ibm.com/developerworks/linux/linux390/documentation_novell_suse.htmlhttp://www.ibm.com/developerworks/linux/linux390/documentation_novell_suse.htmlhttp://www.ibm.com/developerworks/linux/linux390/documentation_red_hat.htmlhttp://www.ibm.com/developerworks/linux/linux390/documentation_red_hat.html

ANSI X9.63:2001 Public Key Cryptography for the Financial Services Industry: KeyAgreement and Key Transport Using Elliptic Curve Cryptography.

v Applied Cryptography: Protocols, Algorithms, and Source Code in C, Second Edition,Bruce Schneier, John Wiley & Sons, Inc., 1996, ISBN 0-471-12845-7 or ISBN0-471-11709-9

v ECC Brainpool Standard Curves and Curve Generation, v.1.0, October 19, 2005Available at http://www.ecc-brainpool.org/download/Domain-parameters.pdf.

v Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation(RFC 5639), Manfred Lochter and Johannes Merkle, IETF Trust, March 2010.Available at http://www.rfc-editor.org/rfc/rfc5639.txt

v EMV 2000 Integrated Circuit Card Specifications for Payment Systems, Book 2 --Security and Key Management, Version 4.0, EMVCo, LLC, December 2000.

v Federal Information Processing Standards (FIPS), issued by the U.S. NationalInstitute of Standards and Technology (S). FIPS PUB 46-3 Data Encryption Standard (DES), October 25, 1999. Available at

http://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf. FIPS PUB 81 DES Modes of Operation, December 2, 1980. Available at

http://www.itl.nist.gov/fipspubs/fip81.htm. FIPS PUB 140-1 Security Requirements for Cryptographic Modules, January 11,

1994. Available at http://csrc.nist.gov/publications/fips/fips1401.htm. FIPS PUB 140-2 Security Requirements for Cryptographic Modules, May 25, 2001.

Available at http://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdf. FIPS PUB 180-2 Secure Hash Standard (SHS), August 1, 2002. Available at

http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf. FIPS PUB 186-2 Digital Signature Standard (DSS), January 27, 2000. Available at

http://csrc.nist.gov/publications/fips/archive/fips186-2/fips186-2.pdf. FIPS PUB 186-3 Digital Signature Standard (DSS), June, 2009. Available at

http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf. FIPS PUB 197 Advanced Encryption Standard (AES), November 26, 2001.

Available at http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf. FIPS PUB 198-1 The Keyed-Hash Message Authentication Code (HMAC), July,

2008. Available at http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf.

v International Organization for Standardization (ISO). ISO is the world's largestdeveloper and publisher of International Standards. ISO is a network of thenational standards institutes of many countries, one member per country, with aCentral Secretariat in Geneva, Switzerland, that coordinates the system. ISO 16609:2004 Banking -- Requirements for Message Authentication Using

Symmetric Techniques.

ISO/DIS 9564-1 Financial Services -- Personal Identification Number (PIN)Management and Security -- Part 1: Basic Principles and Requirements for PINs inCard-Based Systems.

v International Organization for Standardization/International ElectrotechnicalCommission (ISO/IEC) ISO/IEC 9796-1:1997 Information Technology -- Security Techniques -- Digital

Signature Schemes Giving Message Recovery -- Part 1: Mechanisms UsingRedundancy.

ISO/IEC 9796-2:2002 Information Technology -- Security Techniques -- DigitalSignature Schemes Giving Message Recovery -- Part 2: Integer Factorization BasedMechanisms.

xxvi Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

http://www.ecc-brainpool.org/download/Domain-parameters.pdfhttp://www.rfc-editor.org/rfc/rfc5639.txthttp://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdfhttp://www.itl.nist.gov/fipspubs/fip81.htmhttp://csrc.nist.gov/publications/fips/fips1401.htmhttp://csrc.nist.gov/publications/fips/fips140-2/fips1402.pdfhttp://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdfhttp://csrc.nist.gov/publications/fips/archive/fips186-2/fips186-2.pdfhttp://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdfhttp://csrc.nist.gov/publications/fips/fips197/fips-197.pdfhttp://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdfhttp://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf

ISO/IEC 9797-1:1999 Information technology -- Security techniques -- MessageAuthentication Codes (MACs) -- Part 1: Mechanisms Using a Block Cipher.

ISO/IEC 11770-3:2008 Information Technology -- Security Techniques -- KeyManagement -- Part 3: Mechanisms Using Asymmetric Techniques.

v National Institute of Standards and Technology (NIST) Special Publications (SP),U.S. Dept. of Commerce NIST SP 800-38A Recommendation for Block Cipher Modes of Operations: Methods

and Techniques, 2001 Edition. Available at http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdf.

NIST SP 800-56A Recommendation for Pair-Wise Key Establishment SchemesUsing Discrete Logarithm Cryptography (Revised), March 2007 EditionAvailable at http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf.

v RSA Laboratories (http://www.rsa.com/rsalabs/pkcs). PKCS #1: RSA Encryption Standard, Version 1.5, November 1, 1993. PKCS #1 v2.0: RSA Cryptography Standard, October 1, 1998. PKCS #1 v2.1: RSA Cryptography Standard, June 14, 2002. PKCS #10 v1.7: Certification Request Syntax Standard, May 26, 2000.

v SET Secure Electronic Transaction, Version 1.0, May 31, 1997, Secure ElectronicTransaction LLC.

v Standards for Efficient Cryptography 2 (SEC 2): Recommended Elliptic Curve DomainParameters Version 2.0, Standards for Efficient Cryptography Group (SECG),Certicom Research, January 27, 2010. Available at http://www.secg.org/download/aid-784/sec2-v2.pdf

v The MD5 Message-Digest Algorithm, Internet Engineering Task Force Request forComments (RFC) 1321, MIT Laboratory for Computer Science and RSA DataSecurity, Inc., April 1992. Available at http://www.ietf.org/rfc/rfc1321.txt.

v Visa Integrated Circuit Card Specification, Version 1.4.0, Visa International, October31, 2001.

v Visa Integrated Circuit Card Specification (VIS) 1.4.0 Corrections and Updates, VisaInternational.

Do you have problems, comments, or suggestions?Your suggestions and ideas can contribute to the quality and the usability of thisdocument.

If you have problems using this document, or if you have suggestions forimproving it, complete and mail the Reader's Comment Form found at the back ofthe document.

About this document xxvii

http://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdfhttp://csrc.nist.gov/publications/nistpubs/800-38a/sp800-38a.pdfhttp://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdfhttp://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdfhttp://www.rsa.com/rsalabs/pkcshttp://www.secg.org/download/aid-784/sec2-v2.pdf sec2recdphttp://www.secg.org/download/aid-784/sec2-v2.pdf sec2recdphttp://www.ietf.org/rfc/rfc1321.txt

xxviii Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

Part 1. IBM CCA programming

This part of the document introduces programming for the IBM CCA, AES, DES,and PKA cryptography.

The topics in this part explain how to use CCA nodes and AES, DES and PKAverbs.v Chapter 1, Introduction to programming for the IBM Common Cryptographic

Architecture, on page 3 describes the programming considerations for using theCCA verbs. It also explains the syntax and parameter definitions used in theverbs. Information about concurrency is also provided.

v Chapter 2, Using AES, DES, and HMAC cryptography and verbs, on page 29gives an overview of AES, DES, and ECC cryptography and provides generalguidance information on how these verbs use different key types and key forms.

v Chapter 3, Introducing PKA cryptography and using PKA verbs, on page 63introduces Public Key Algorithm (PKA) and Elliptic Curve Cryptography (ECC)support, and describes programming considerations for using the CCA PKAverbs, such as the PKA key token structure and key management.

v Chapter 4, TR-31 symmetric-key management, on page 71 introduces X9 TR-31(Technical Report 31) support, and provides details about the TR-31 key block.

Copyright IBM Corp. 2007, 2014 1

2 Linux for System z: Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide

Chapter 1. Introduction to programming for the IBM CommonCryptographic Architecture

This topic introduces the IBM CCA application programming interface (API).

The topic explains basic concepts and describes how you can obtain cryptographicand other services from the CEX*C feature and CCA. It includes the followingtopics:v Available Common Cryptographic Architecture verbsv Common Cryptographic Architecture functional overview on page 4v CPACF support on page 12v Security API programming fundamentals on page 17v How to compile and link CCA application programs on page 22

Available Common Cryptographic Architecture verbsCCA products provide a variety of cryptographic processes and data-securitytechniques.

Your application program can call verbs (sometimes called services) to perform thefollowing functions:

Data confidentialityEncrypt and decrypt information, typically using the AES or DESalgorithms in Cipher Block Chaining (CBC) mode to enable dataconfidentiality.

Data integrityHash data to obtain a digest, or process the data to obtain a MessageAuthentication Code (MAC) or keyed hash MAC (HMAC), that is useful indemonstrating data integrity.

NonrepudiationGenerate and verify digital signatures using either the RSA algorithm orthe ECDSA algorithm, to demonstrate data integrity and form the basis fornonrepudiation.

AuthenticationGenerate, encrypt, translate, and verify finance industry personalidentification numbers (PINs) and American Express, MasterCard, and Visacard security codes with a comprehensive set of finance-industry-specificservices.

Key managementManage the various AES, DES, ECC, and RSA keys necessary to performthe above operations.

Java interactionInteract with the Java Native Interface (JNI). Some of the CCA verbs have aspecific version that can be used for JNI work.

CCA managementControl the initialization and operation of CCA.

Copyright IBM Corp. 2007, 2014 3

|

Subsequent sections group the many available verbs by topic. Each section lists theverbs in alphabetical order by verb pseudonym.

The remainder of this section provides an overview of the structure of a CCAcryptographic framework and introduces some important concepts and terms.

Common Cryptographic Architecture functional overviewThis topic provides conceptual information about the framework for positioningthe CCA security API.

Figure 1 provides a conceptual framework for positioning the CCA security API,which you use to access a common cryptographic architecture. Applicationprograms make procedure calls to the CCA security API to obtain cryptographicand related I/O services. The CCA security API is designed so that a call can beissued from essentially any high-level programming language. The call, or request,is forwarded to the cryptographic services access layer and receives a synchronousresponse; that is, your application program loses control until the access layerreturns a response after processing your request.

The products that implement the CCA security API consist of both hardware andsoftware components.

CCA software support: The software consists of application development andruntime software components.

Figure 1. CCA security API, access layer, and cryptographic engine


v The application development software primarily consists of language bindingsthat can be included in new applications to assist in accessing services availableat the API. Language bindings are provided for the C and Java programminglanguages.

v The runtime software can be divided into the following categories: Service-requesting programs, including application and utility programs. The security API, an agent function that is logically part of the calling

application program or utility. The cryptographic services access layer: an environment-dependent request

routing function, key-storage support services, and device driver to access oneor more hardware cryptographic engines.

The cryptographic engine software that gives access to the cryptographicengine hardware.The cryptographic engine is implemented in the hardware of the CEX*Ccoprocessor. Security-sensitive portions of CCA are implemented in thecryptographic engine software running in the protected coprocessorenvironment.

Utility programs and tools provide support for administering CCA secretkeys, interacting with CCA managed symmetric and public key cryptographykey storage, and configuring the software support.

You can create application programs that employ the CCA security API or you canpurchase applications from IBM or other sources that use the products. Thisdocument is the primary source of information for designing systems andapplication programs that use the CCA security API with the cryptographiccoprocessors.

Cryptographic engine: The CCA architecture defines a cryptographic subsystemthat contains a cryptographic engine operating within a protected boundary. Thecoprocessor's tamper-resistant, tamper-responding environment provides physicalsecurity for this boundary and the CCA architecture provides the logical securityneeded for the full protection of critical information.

CEX2C Coprocessor: The coprocessor provides a secure programming andhardware environment wherein AES, DES and RSA processes are performed. Eachcryptographic coprocessor includes a general-purpose processor, non-volatilestorage, and specialized cryptographic electronics. These components areencapsulated in a protective environment to enhance security. The IBM CCASupport Program enables applications to employ a set of AES, DES and RSA-basedcryptographic services utilizing the coprocessor hardware. Services include:v DES key and RSA key-pair generationv DES and RSA host-based key record managementv Digital signature generation and verificationv Cryptographic key wrapping and unwrappingv Data encryption, decryption and MAC generation/verificationv PIN processing for the financial services industryv Other services, including DES key-management based on CCA's

control-vector-enforced key separation

CEX*C Coprocessor: The coprocessor provides a secure programming andhardware environment wherein AES, DES, RSA, Elliptic Curve, and HMACprocesses are performed. Each cryptographic coprocessor includes a

Chapter 1. Introduction to programming for the IBM Common Cryptographic Architecture 5

|

|

general-purpose processor, non-volatile storage, and specialized cryptographicelectronics. These components are encapsulated in a protective environment toenhance security. The IBM CCA Support Program enables applications to employ aset of AES, DES, RSA, Elliptic Curve, and HMAC-based cryptographic servicesutilizing the coprocessor hardware. Services include:v DES, AES, RSA, Elliptic Curve, and HMAC key-pair generationv DES, AES, RSA, Elliptic Curve, and HMAC host-based key record managementv Digital signature generation and verificationv Cryptographic key wrapping and unwrappingv Data encryption, decryption and MAC generation/verificationv PIN processing for the financial services industryv Other services, including DES key-management based on CCA's

control-vector-enforced key separation

CEX4C Coprocessor: The coprocessor provides the same cryptographic functions asthe CEX3C coprocessor.

CCA: Common Cryptographic Architecture (CCA) is the basis for a consistentcryptographic product family. Applications employ the CCA security API to obtainservices from, and to manage the operation of, a cryptographic system that meetsCCA architecture specifications.

CCA access control: Each CCA node has an access-control system enforced by thehardware and protected software. The robust UNIX style access controls integratedinto the Linux operating system are used to protect the integrity of the underlyingCCA hardware environment. The specialized processing environment provided bythe cryptographic engine can be kept secure because selected services are providedonly when certain requirements are met or a Trusted Key-Entry console is used toenable access. The access-control decisions are performed within the securedenvironment of the cryptographic engine and cannot be subverted by rogue codethat might run on the main computing platform.

Coprocessor certification: After quality checking a newly manufacturedcoprocessor, IBM loads and certifies the embedded software. Following the loadingof basic, authenticated software, the coprocessor generates an RSA key-pair andretains the private key within the cryptographic engine. The associated public keyis signed by a certification key securely held at the manufacturing facility and thenthe certified device key is stored within the coprocessor. The manufacturing facilitykey has itself been certified by a securely held key unique to the CEX*C productline.

The private key within the coprocessor, known as the device private key, isretained in the coprocessor. From this time on, if tampering is detected or if thecoprocessor batteries are removed or lose power in the absence of bus power, thecoprocessor sets all security-relevant keys and data items to zero. This process isirreversible and results in the permanent loss of the factory-certified device key, thedevice private key, and all other data stored in battery-protected memory.Security-sensitive data stored in the coprocessor flash memory is encrypted. Thekey used to encrypt such data is itself retained in the battery-protected memory.

CCA master key: When using the CCA architecture, working keys, includingsession keys and the RSA and ECC private keys used at a node to form digitalsignatures or to unwrap other keys, are generally stored outside thecryptographic-engine protected environment. These working keys are wrapped


||

|

(DES triple-encrypted or AES encrypted) by the CCA master key. The master key isheld in the clear (not enciphered) within the cryptographic engine.

The number of keys usable with a CCA subsystem is thus restricted only by thehost server storage, not by the finite amount of storage within the coprocessorsecure module. In addition, the working keys can be used by additional CCAcryptographic engines which have the same master key. This CCA characteristic isuseful in high-availability and high-throughput environments where multiplecryptographic processors must function in parallel.

Establishing a CCA master key: To protect working keys, the master key must begenerated and initialized in a secure manner. One method uses the internalrandom-number generator for the source of the master key. In this case, the masterkey is never exte

Date post:	01-Apr-2018
Category:	Documents
Upload:	lamnhi
View:	269 times
Download:	13 times

Linux for System z: Secure Key Solution with the Common ... · Cryptographic Architecture...

Documents