Version 2 Release 4 z/OS - IBM - United States · This edition applies to Version 2 Release 4 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated

z/OSVersion 2 Release 4

Cryptographic Services System SecureSockets Layer Programming

IBM

SC14-7495-40

Note

Before using this information and the product it supports, read the information in “Notices” on page767.

This edition applies to Version 2 Release 4 of z/OS (5650-ZOS) and to all subsequent releases and modifications untilotherwise indicated in new editions.

Last updated: 2019-11-20© Copyright International Business Machines Corporation 1999, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Figures................................................................................................................. xi

Tables................................................................................................................. xv

About this document.......................................................................................... xviiWho should use this document................................................................................................................ xviiHow to use this document........................................................................................................................xviiConventions used in this information .....................................................................................................xviiiWhere to find more information................................................................................................................ xix

How to send your comments to IBM.....................................................................xxiIf you have a technical problem................................................................................................................xxi

Summary of changes......................................................................................... xxiiiSummary of changes for z/OS Version 2 Release 4 (V2R4)................................................................... xxiiiSummary of changes for z/OS Version 2 Release 3 (V2R3)................................................................... xxviSummary of changes for z/OS Version 2 Release 2 (V2R2).................................................................... xxx

Chapter 1. Introduction......................................................................................... 1Software dependencies............................................................................................................................... 1Installation information............................................................................................................................... 1

Chapter 2. How System SSL works for secure socket communication...................... 5Using System SSL on z/OS........................................................................................................................... 5System SSL application overview................................................................................................................ 6

Chapter 3. Using cryptographic features with System SSL...................................... 9Guidelines for using hardware cryptographic features...............................................................................9Overview of hardware cryptographic features and System SSL.............................................................. 10Random byte generation support..............................................................................................................11Elliptic Curve Cryptography support......................................................................................................... 11RSASSA-PSS signature support................................................................................................................ 13Diffie-Hellman key agreement.................................................................................................................. 14RACF CSFSERV resource requirements.................................................................................................... 15PKCS #11 and setting CLEARKEY resource within CRYPTOZ class.........................................................17PKCS #11 Cryptographic operations using ICSF handles........................................................................17

Chapter 4. System SSL and FIPS 140-2................................................................ 19Algorithms and key sizes........................................................................................................................... 19Random byte generation........................................................................................................................... 21RSA digital signature verification, encryption, and decryption................................................................ 21Diffie-Hellman key agreement.................................................................................................................. 22Certificates ................................................................................................................................................ 22SSL/TLS protocol....................................................................................................................................... 22System SSL module verification setup......................................................................................................23Certificate stores........................................................................................................................................25Application changes...................................................................................................................................26SSL started task......................................................................................................................................... 27

iii

Chapter 5. Writing and building a z/OS System SSL application............................ 29Writing a System SSL source program...................................................................................................... 29Building a z/OS System SSL application ...................................................................................................35Running a z/OS System SSL application................................................................................................... 35

Chapter 6. System SSL application programming considerations.......................... 37Non-Blocking I/O....................................................................................................................................... 38Client authentication certificate selection................................................................................................ 40I/O routine replacement............................................................................................................................41Use of user data......................................................................................................................................... 41Session ID (SID) and session ticket cache................................................................................................41Session renegotiation notification (SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2)..................................... 44TLS extensions........................................................................................................................................... 44Suite B cryptography support....................................................................................................................47SSL/TLS partner certificate revocation checking......................................................................................50Enabling OCSP server stapling.................................................................................................................. 55Using server multiple key label support....................................................................................................57TLS V1.3 protocol support.........................................................................................................................59Upgrading to TLS V1.2 from earlier SSL and TLS protocols......................................................................62Upgrading from TLS V1.2 to TLS V1.2 and TLS V1.3 protocols................................................................ 64

Chapter 7. API reference..................................................................................... 67gsk_attribute_get_buffer()........................................................................................................................ 70gsk_attribute_get_cert_info()................................................................................................................... 75gsk_attribute_get_data()...........................................................................................................................80gsk_attribute_get_enum().........................................................................................................................82gsk_attribute_get_numeric_value()..........................................................................................................90gsk_attribute_set_buffer()........................................................................................................................ 93gsk_attribute_set_callback().....................................................................................................................99gsk_attribute_set_enum().......................................................................................................................103gsk_attribute_set_numeric_value()........................................................................................................113gsk_attribute_set_tls_extension().......................................................................................................... 119gsk_environment_close()........................................................................................................................ 122gsk_environment_init()........................................................................................................................... 123gsk_environment_open().........................................................................................................................125gsk_free_cert_data()............................................................................................................................... 133gsk_get_all_cipher_suites().................................................................................................................... 134gsk_get_cert_by_label()..........................................................................................................................136gsk_get_cipher_suites().......................................................................................................................... 140gsk_get_ssl_vector()............................................................................................................................... 141gsk_get_update().....................................................................................................................................142gsk_list_free()..........................................................................................................................................143gsk_secure_socket_close()..................................................................................................................... 144gsk_secure_socket_init()........................................................................................................................ 145gsk_secure_socket_misc()......................................................................................................................157gsk_secure_socket_open()..................................................................................................................... 160gsk_secure_socket_read()...................................................................................................................... 161gsk_secure_socket_shutdown()............................................................................................................. 163gsk_secure_socket_write()..................................................................................................................... 165gsk_strerror()........................................................................................................................................... 167

Chapter 8. Certificate Management Services (CMS) API reference.......................169gsk_add_record().................................................................................................................................... 174gsk_change_database_password()........................................................................................................ 177gsk_change_database_record_length()................................................................................................. 179gsk_close_database()..............................................................................................................................180

iv

gsk_close_directory().............................................................................................................................. 181gsk_construct_certificate()..................................................................................................................... 182gsk_construct_private_key()...................................................................................................................186gsk_construct_private_key_rsa()........................................................................................................... 188gsk_construct_public_key()....................................................................................................................189gsk_construct_public_key_rsa().............................................................................................................191gsk_construct_renewal_request()..........................................................................................................192gsk_construct_self_signed_certificate().................................................................................................195gsk_construct_signed_certificate().........................................................................................................198gsk_construct_signed_crl()..................................................................................................................... 202gsk_copy_attributes_signers()................................................................................................................206gsk_copy_buffer()....................................................................................................................................207gsk_copy_certificate()............................................................................................................................. 208gsk_copy_certificate_extension()........................................................................................................... 209gsk_copy_certification_request()........................................................................................................... 210gsk_copy_content_info().........................................................................................................................211gsk_copy_crl()..........................................................................................................................................212gsk_copy_name().................................................................................................................................... 213gsk_copy_private_key_info().................................................................................................................. 214gsk_copy_public_key_info()................................................................................................................... 215gsk_copy_record()...................................................................................................................................216gsk_create_certification_request().........................................................................................................217gsk_create_database()............................................................................................................................ 221gsk_create_database_renewal_request().............................................................................................. 223gsk_create_database_signed_certificate().............................................................................................226gsk_create_renewal_request()............................................................................................................... 232gsk_create_revocation_source().............................................................................................................235gsk_create_self_signed_certificate()......................................................................................................241gsk_create_signed_certificate()..............................................................................................................245gsk_create_signed_certificate_record()................................................................................................. 248gsk_create_signed_certificate_set().......................................................................................................252gsk_create_signed_crl().......................................................................................................................... 257gsk_create_signed_crl_record()............................................................................................................. 260gsk_decode_base64()............................................................................................................................. 264gsk_decode_certificate()......................................................................................................................... 265gsk_decode_certificate_extension()....................................................................................................... 266gsk_decode_certification_request()....................................................................................................... 268gsk_decode_crl()..................................................................................................................................... 269gsk_decode_import_certificate()............................................................................................................270gsk_decode_import_key().......................................................................................................................271gsk_decode_issuer_and_serial_number()............................................................................................. 273gsk_decode_name()................................................................................................................................ 274gsk_decode_private key()....................................................................................................................... 275gsk_decode_public key().........................................................................................................................276gsk_decode_signer_identifier().............................................................................................................. 277gsk_delete_record()................................................................................................................................ 278gsk_dn_to_name()...................................................................................................................................279gsk_encode_base64()............................................................................................................................. 282gsk_encode_certificate_extension()....................................................................................................... 283gsk_encode_ec_parameters().................................................................................................................285gsk_encode_export_certificate()............................................................................................................ 286gsk_encode_export_key()....................................................................................................................... 288gsk_encode_export_request()................................................................................................................ 291gsk_encode_issuer_and_serial_number()............................................................................................. 292gsk_encode_name()................................................................................................................................ 293gsk_encode_private_key()...................................................................................................................... 294gsk_encode_public_key()....................................................................................................................... 295gsk_encode_signature().......................................................................................................................... 296

v

gsk_encode_signer_identifier()...............................................................................................................297gsk_export_certificate().......................................................................................................................... 298gsk_export_certification_request().........................................................................................................300gsk_export_key()..................................................................................................................................... 301gsk_factor_private_key()........................................................................................................................ 304gsk_factor_private_key_rsa()................................................................................................................. 305gsk_factor_public_key()..........................................................................................................................306gsk_factor_public_key_rsa()...................................................................................................................307gsk_fips_state_query()............................................................................................................................308gsk_fips_state_set()................................................................................................................................ 309gsk_format_time()................................................................................................................................... 311gsk_free_attributes_signers()................................................................................................................. 313gsk_free_buffer().....................................................................................................................................314gsk_free_certificate().............................................................................................................................. 315gsk_free_certificates().............................................................................................................................316gsk_free_certificate_extension()............................................................................................................ 317gsk_free_certification_request().............................................................................................................318gsk_free_content_info().......................................................................................................................... 319gsk_free_crl()...........................................................................................................................................320gsk_free_crls()......................................................................................................................................... 321gsk_free_decoded_extension()...............................................................................................................322gsk_free_issuer_and_serial_number()...................................................................................................323gsk_free_name()......................................................................................................................................324gsk_free_oid().......................................................................................................................................... 325gsk_free_private_key()............................................................................................................................326gsk_free_private_key_info()................................................................................................................... 327gsk_free_public_key().............................................................................................................................328gsk_free_public_key_info().................................................................................................................... 329gsk_free_record().................................................................................................................................... 330gsk_free_records().................................................................................................................................. 331gsk_free_revocation_source()................................................................................................................ 332gsk_free_signer_identifier().................................................................................................................... 333gsk_free_string()......................................................................................................................................334gsk_free_strings()....................................................................................................................................335gsk_generate_key_agreement_pair().................................................................................................... 336gsk_generate_key_pair()........................................................................................................................ 337gsk_generate_key_parameters()............................................................................................................340gsk_generate_random_bytes()...............................................................................................................342gsk_generate_secret()............................................................................................................................ 343gsk_get_certificate_algorithms()............................................................................................................ 344gsk_get_certificate_info() ...................................................................................................................... 345gsk_get_cms_vector()............................................................................................................................. 346gsk_get_content_type_and_cms_version()............................................................................................348gsk_get_default_key().............................................................................................................................349gsk_get_default_label().......................................................................................................................... 350gsk_get_directory_certificates()............................................................................................................. 351gsk_get_directory_crls()..........................................................................................................................353gsk_get_directory_enum()...................................................................................................................... 355gsk_get_directory_numeric_value()....................................................................................................... 357gsk_get_ec_parameters_info()...............................................................................................................358gsk_get_record_by_id().......................................................................................................................... 359gsk_get_record_by_index().................................................................................................................... 360gsk_get_record_by_label()..................................................................................................................... 361gsk_get_record_by_subject()................................................................................................................. 362gsk_get_record_labels()......................................................................................................................... 363gsk_get_update_code()...........................................................................................................................364gsk_import_certificate().......................................................................................................................... 365gsk_import_key().....................................................................................................................................368

vi

gsk_make_content_msg().......................................................................................................................371gsk_make_data_content().......................................................................................................................372gsk_make_data_msg()............................................................................................................................ 373gsk_make_encrypted_data_content().................................................................................................... 374gsk_make_encrypted_data_msg()......................................................................................................... 376gsk_make_enveloped_data_content()................................................................................................... 378gsk_make_enveloped_data_content_extended().................................................................................. 381gsk_make_enveloped_data_msg()......................................................................................................... 384gsk_make_enveloped_data_msg_extended()........................................................................................387gsk_make_enveloped_private_key_msg().............................................................................................390gsk_make_signed_data_content()..........................................................................................................392gsk_make_signed_data_content_extended()........................................................................................ 395gsk_make_signed_data_msg()............................................................................................................... 399gsk_make_signed_data_msg_extended()..............................................................................................402gsk_make_wrapped_content()............................................................................................................... 406gsk_mktime()...........................................................................................................................................407gsk_modify_pkcs11_key_label()............................................................................................................408gsk_name_compare()..............................................................................................................................409gsk_name_to_dn()...................................................................................................................................410gsk_open_database().............................................................................................................................. 412gsk_open_database_using_stash_file()................................................................................................. 414gsk_open_directory()...............................................................................................................................416gsk_open_keyring()................................................................................................................................. 417gsk_perform_kat()...................................................................................................................................419gsk_query_crypto_level()........................................................................................................................ 420gsk_query_database_label()................................................................................................................... 421gsk_query_database_record_length()....................................................................................................422gsk_rdtime().............................................................................................................................................423gsk_read_content_msg()........................................................................................................................ 424gsk_read_data_content()........................................................................................................................ 425gsk_read_data_msg()..............................................................................................................................426gsk_read_encrypted_data_content()......................................................................................................427gsk_read_encrypted_data_msg()........................................................................................................... 429gsk_read_enveloped_data_content()..................................................................................................... 431gsk_read_enveloped_data_content_extended()....................................................................................433gsk_read_enveloped_data_msg()...........................................................................................................435gsk_read_enveloped_data_msg_extended()......................................................................................... 437gsk_read_signed_data_content()........................................................................................................... 439gsk_read_signed_data_content_extended().......................................................................................... 442gsk_read_signed_data_msg().................................................................................................................445gsk_read_signed_data_msg_extended()............................................................................................... 448gsk_read_wrapped_content()................................................................................................................. 451gsk_receive_certificate()......................................................................................................................... 452gsk_replace_record().............................................................................................................................. 453gsk_set_default_key()............................................................................................................................. 456gsk_set_directory_enum().......................................................................................................................458gsk_set_directory_numeric_value()........................................................................................................460gsk_sign_certificate().............................................................................................................................. 461gsk_sign_crl()...........................................................................................................................................464gsk_sign_data()........................................................................................................................................467gsk_validate_certificate()........................................................................................................................ 470gsk_validate_certificate_mode().............................................................................................................475gsk_validate_extended_key_usage()......................................................................................................482gsk_validate_hostname()........................................................................................................................ 484gsk_validate_server().............................................................................................................................. 486gsk_verify_certificate_signature()...........................................................................................................487gsk_verify_crl_signature()....................................................................................................................... 490gsk_verify_data_signature().................................................................................................................... 493

vii

Chapter 9. Deprecated Secure Socket Layer (SSL) APIs...................................... 497gsk_free_memory()................................................................................................................................. 498gsk_get_cipher_info()..............................................................................................................................499gsk_get_dn_by_label()............................................................................................................................500gsk_initialize()..........................................................................................................................................501gsk_secure_soc_close().......................................................................................................................... 506gsk_secure_soc_init()............................................................................................................................. 507gsk_secure_soc_read()........................................................................................................................... 514gsk_secure_soc_reset().......................................................................................................................... 516gsk_secure_soc_write().......................................................................................................................... 517gsk_srb_initialize().................................................................................................................................. 519GSKSRBRD...............................................................................................................................................520GSKSRBWT.............................................................................................................................................. 521gsk_uninitialize()......................................................................................................................................522gsk_user_set()......................................................................................................................................... 523

Chapter 10. Certificate/Key management...........................................................525Introduction............................................................................................................................................. 525x.509 certificate revocation.................................................................................................................... 526gskkyman overview................................................................................................................................. 527Setting up the environment to run gskkyman.........................................................................................528Key database files....................................................................................................................................529z/OS PKCS #11 tokens............................................................................................................................ 529gskkyman interactive mode descriptions............................................................................................... 530gskkyman interactive mode examples................................................................................................... 542gskkyman command line mode syntax...................................................................................................585

Chapter 11. SSL started task..............................................................................595GSKSRVR environment variables............................................................................................................ 595Configuring the SSL started task............................................................................................................. 595Server operator commands.....................................................................................................................596Sysplex session cache support............................................................................................................... 597Component trace support....................................................................................................................... 598Hardware cryptography failure notification............................................................................................598

Chapter 12. Obtaining diagnostic information.....................................................599Obtaining System SSL trace information................................................................................................ 599Component trace support....................................................................................................................... 600Capturing component trace data............................................................................................................ 600Displaying the trace data.........................................................................................................................602Event trace records for System SSL........................................................................................................ 602Capturing component trace data without an external writer................................................................. 604

Chapter 13. Messages and codes........................................................................605SSL function return codes....................................................................................................................... 605Deprecated SSL function return codes................................................................................................... 644ASN.1 status codes (014CExxx)..............................................................................................................661CMS status codes (03353xxx)................................................................................................................ 667SSL started task messages (GSK01nnn).................................................................................................706Utility messages (GSK00nnn)................................................................................................................. 719

Appendix A. Environment variables....................................................................721

Appendix B. Sample C++ SSL files...................................................................... 743

viii

Appendix C. Cipher suite definitions...................................................................747

Appendix D. Object identifiers............................................................................759

Appendix E. Migrating from deprecated SSL interfaces....................................... 761

Appendix F. Accessibility................................................................................... 763Accessibility features.............................................................................................................................. 763Consult assistive technologies................................................................................................................763Keyboard navigation of the user interface..............................................................................................763Dotted decimal syntax diagrams.............................................................................................................763

Notices..............................................................................................................767Terms and conditions for product documentation.................................................................................768IBM Online Privacy Statement................................................................................................................ 769Policy for unsupported hardware............................................................................................................769Minimum supported hardware................................................................................................................770Trademarks..............................................................................................................................................770

Index................................................................................................................ 771

ix

Figures

1. Sockets programming model using System SSL.......................................................................................... 8

2. Database menu......................................................................................................................................... 531

3. Key Management Menu............................................................................................................................ 533

4. Token Management Menu........................................................................................................................ 534

5. Key and Certificate Menu..........................................................................................................................534

6. Token Key and Certificate Menu...............................................................................................................535

7. Certificate Menu........................................................................................................................................ 537

8. Token Certificate Menu.............................................................................................................................537

9. Request Menu 1........................................................................................................................................ 538

10. Request Menu 2...................................................................................................................................... 538

11. Starting Menu for gskkyman...................................................................................................................543

12. Creating a New Key Database................................................................................................................ 543

13. Key Management Menu for gskkyman................................................................................................... 544

14. Opening an Existing Key Database File.................................................................................................. 545

15. Key Management Menu.......................................................................................................................... 545

16. Deleting an Existing Key Database.........................................................................................................546

17. Changing a Key Database Password...................................................................................................... 547


19. Creating a z/OS PKCS #11 token............................................................................................................548

20. Opening a z/OS PKCS #11 token from token name.............................................................................. 549

21. Opening a z/OS PKCS #11 token from token list...................................................................................549

22. Token Management Menu...................................................................................................................... 550

23. Deleting an existing z/OS PKCS #11 Token........................................................................................... 550

xi

24. Deleting an existing z/OS PKCS #11 token............................................................................................551



27. Creating a Self-Signed Certificate.......................................................................................................... 553

28. Creating a certificate request-Key Management Menu......................................................................... 554

29. Creating a certificate request-Key Management Menu......................................................................... 554

30. Creating a Certificate Request................................................................................................................556

31. Specifying subject alternate names....................................................................................................... 557

32. Contents of certreq.arm after Certificate Request Generation............................................................. 558

33. Key information for certificate request.................................................................................................. 558



36. Key and Certificate List........................................................................................................................... 561

37. Token Key and Certificate List................................................................................................................561

38. Key and Certificate Menu........................................................................................................................561

39. Token Key and Certificate Menu.............................................................................................................562

40. Certificate Information........................................................................................................................... 562

41. Certificate extensions list....................................................................................................................... 563

42. Key usage information............................................................................................................................ 563

43. Key information menu............................................................................................................................ 563

44. Token key information menu of a certificate with a secure private key................................................563

45. Token key information menu of a certificate with a clear private key.................................................. 564

46. Marking a certificate (and private key) as the default certificate-Key and Certificate Menu............... 564

47. Marking a certificate (and private key) as the default certificate-Token Key and Certificate Menu.... 565

48. Copying a Certificate Without its Private Key.........................................................................................565

xii

49. Copying a Certificate and Private key to a Different Key Database-Export File Format....................... 566

50. Copying a Certificate and Private key to a Different Key Database-Export File Format....................... 567

51. Copying a Certificate with its Private Key to a Key Database on the Same System............................. 568

52. Copying a Certificate with its Private Key to a z/OS PKCS #11 Token on the Same System............... 569

53. Delete Certificate and Key-Key and Certificate Menu........................................................................... 570

54. Delete Certificate and Key-Token Key and Certificate Menu................................................................ 570

55. Changing a Certificate Label-Key and Certificate Menu........................................................................ 571

56. Changing a Certificate Label-Token and Certificate Menu.................................................................... 571

57. Select 10 to Create a Signed Certificate and Key-Key and Certificate Menu........................................572

58. Select 10 to Create a Signed Certificate and Key-Token Key and Certificate Menu.............................572

59. Enter Certificate Details..........................................................................................................................573

60. Subject Alternate Name Type.................................................................................................................573

61. Selecting the ECC Key Type ...................................................................................................................574

62. Selecting the ECC Curve Type ................................................................................................................575

63. Creating a key parameter file to be used with Diffie-Hellman.............................................................. 576

64. Creating a certificate to be used with Diffie_Hellman........................................................................... 577

65. Select 11 to Create a Certificate Renewal Request-Key and Certificate Menu.................................... 578

66. Select 11 to Create a Certificate Renewal Request-Token Key and Certificate Menu......................... 578

67. Certificate List......................................................................................................................................... 579

68. Importing a Certificate from a File-Key Management Menu................................................................. 580

69. Importing a Certificate from a File-Token Management Menu............................................................. 580

70. Importing a Certificate and Private Key from a File-Key Management Menu.......................................581

71. Importing a Certificate and Private Key from a File-Token Management Menu...................................582

xiii

Tables

1. Hardware cryptographic functions used by System SSL........................................................................... 10

2. Recommended digest sizes for ECDSA signature key sizes...................................................................... 12

3. Default EC named curves for specified key sizes.......................................................................................13

4. RSASSA-PSS key algorithm recommendations..........................................................................................14

5. CSFSERV resources required for hardware support through ICSF callable services............................... 15

6. CSFSERV resources required for ICSF PKCS #11 callable services support............................................ 16

7. Algorithm support: FIPS and non-FIPS...................................................................................................... 19

8. Algorithm support sizes: FIPS States ON and LEVEL1 thru LEVEL3..........................................................20

9. Server communicating with clients by way of a socket............................................................................. 38

10. Using the select() routine..........................................................................................................................39

11. Suite B supported cipher suites................................................................................................................47

12. Supported curves...................................................................................................................................... 48

13. Signature and hash algorithms................................................................................................................. 48

14. TLS V1.3 preferred signature algorithm to use for signing handshake messages based uponcertificate types..........................................................................................................................................61

15. Version value and name..........................................................................................................................134

16. Version value and name..........................................................................................................................140

17. gskdb_extended_directory_source parameters....................................................................................236

18. gskdb_cdp_source structure parameters..............................................................................................237

19. gskdb_ocsp_source structure parameters............................................................................................ 238

20. DN attribute names.................................................................................................................................280

21. Certificate types (key algorithms and key size)..................................................................................... 525

22. SAF access levels....................................................................................................................................530

xv

23. SSL-Specific environment variables.......................................................................................................721

24. System environment variables used by SSL.......................................................................................... 742

25. Cipher suite definitions for SSL V2......................................................................................................... 747

26. 2-character and 4-character cipher suite definitions for SSL V3, TLS V1.0, TLS V1.1, TLS V1.2,and TLS V1.3............................................................................................................................................ 747

27. Cipher suite definitions for SSL V3, TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 by supportedprotocol, symmetric algorithm, and message authentication algorithm............................................... 751

28. Cipher suite definitions for SSL V3, TLS V1.0, TLS V1.1, and TLS V1.2 by key-exchange methodand signing certificate..............................................................................................................................754

29. Supported elliptic curve (group) definitions for TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3 andsupported key share definitions for TLS V1.3......................................................................................... 756

30. Signature algorithm pair and certificate signature algorithm pair definitions for TLS V1.2 and TLSV1.3.......................................................................................................................................................... 756

31. Signature algorithm pair definitions for OCSP request signing and OCSP response signing............... 757

32. System SSL supported object identifiers (OIDS)................................................................................... 759

xvi

About this document

This information supports z/OS® (5650-ZOS) and contains information about the system Secure SocketsLayer (SSL) component of the z/OS Cryptographic Services element. This information consists of primarilytwo sets of APIs and a Certificate Management utility. The first set of APIs support the Secure SocketsLayer protocols (SSL V2.0, SSL 3.0, TLS V1.0, TLS V1.1, TLS V1.2, and TLS V1.3) which can be used by C/C++ applications to communicate securely across an open communications network. The other set of APIs(Certificate Management) provide the ability to use function other than the SSL protocols. These functionsinclude the ability to create/manage key database files in a similar function to the SSL CertificateManagement utility, use certificates stored in a key database file, SAF key ring or z/OS PKCS #11 tokenfor purposes other than SSL and basic PKCS #7 message support to provide application writers amechanism to communicate with another application through the PKCS #7 standard.

This information also provides guidance on how to write a client and server secure sockets layerapplication. The client and server may both reside on z/OS™ systems or reside on different systems.

Who should use this documentThis document is intended to assist system administrators in setting up the system to use System SSLsupport and for application programmers in writing System SSL applications.

How to use this documentThe format and organization of this information:

Chapter 1, “Introduction,” on page 1 describes Secure Sockets Layer (SSL) and lists the softwaredependencies and installation information you need to use the System SSL support.

Chapter 2, “How System SSL works for secure socket communication,” on page 5 provides a generaloverview of System SSL and the basic structure of a z/OS application using System SSL.

Chapter 3, “Using cryptographic features with System SSL,” on page 9 describes System SSLs use ofcryptographic features on z/OS.

Chapter 4, “System SSL and FIPS 140-2,” on page 19 describes how to execute System SSL securely ina mode designed to meet FIPS 140-2 criteria.

Chapter 5, “Writing and building a z/OS System SSL application,” on page 29 describes how to write aSystem SSL source program and build the System SSL application.

Chapter 6, “System SSL application programming considerations,” on page 37 describes theconsiderations to think about when designing a System SSL application as well as considerations whenupgrading to the TLS V1.2 and TLS V1.3 protocols.

Chapter 7, “API reference,” on page 67 describes the System SSL program interfaces.

Chapter 8, “Certificate Management Services (CMS) API reference,” on page 169 describes the CertificateManagement Services (CMS) program interfaces.

Chapter 9, “Deprecated Secure Socket Layer (SSL) APIs,” on page 497 describes the deprecated SystemSSL program interfaces.

Chapter 10, “Certificate/Key management,” on page 525 describes how to use the gskkyman utility tocreate a key database file, a z/OS PKCS #11 token, a public/private key pair, a certificate request, andother tasks.

Chapter 11, “SSL started task,” on page 595 provides sysplex session cache support and dynamic tracesupport.

© Copyright IBM Corp. 1999, 2019 xvii

Chapter 12, “Obtaining diagnostic information,” on page 599 provides debugging information.

Chapter 13, “Messages and codes,” on page 605 contains various messages and codes you mightencounter using System SSL.

Appendix A, “Environment variables,” on page 721 lists the environment variables used by System SSL.

Appendix B, “Sample C++ SSL files,” on page 743 describes the sample set of files shipped to provide anexample of what is needed to build a C++ System SSL application.

Appendix C, “Cipher suite definitions,” on page 747 describes supported cipher suite definitions.

Appendix D, “Object identifiers,” on page 759 describes object identifiers (OIDS) supported by SystemSSL.

Appendix E, “Migrating from deprecated SSL interfaces,” on page 761 describes how to migrate anexisting application which uses the deprecated SSL interfaces to the latest SSL interfaces.

Conventions used in this informationThis information uses these typographic conventions:Bold

Bold words or charactersHighlighting1

Words or characters highlighted in this manner represent system elements that you must enter intothe system literally, such as commands, options, or path names.

ItalicItalic words or characters

Highlighting2Words or characters highlighted in this manner represent values for variables that you must supply.

Example fontExamples and information displayed by the system appear in constant width type style.

[ ]Brackets enclose optional items in format and syntax descriptions.

{ }Braces enclose a list from which you must choose an item in format and syntax descriptions.

|A vertical bar separates items in a list of choices.

< >Angle brackets enclose the name of a key on the keyboard.

…Horizontal ellipsis points indicate that you can repeat the preceding item one or more times.

\A backslash is used as a continuation character when entering commands from the shell that exceedone line (255 characters). If the command exceeds one line, use the backslash character \ as the lastnon blank character on the line to be continued, and continue the command on the next line.

This information uses these keying conventions:

The notation followed by the name of a key indicates a control character sequence.

The notation refers to the key on your keyboard that is labeled with the word Return orEnter, or with a left arrow.

Entering commandsWhen instructed to enter a command, type the command name and then press .

xviii About this document

Where to find more informationWhen possible, this information uses cross-document links that go directly to the topic in reference usingshortened versions of the document title. For complete titles and order numbers of the documents for allproducts that are part of z/OS, see z/OS Information Roadmap.

To find the complete z/OS library, see z/OS Internet library (www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibrary).

Internet sourcesThe following resources are available through the internet to provide additional information about thez/OS library and other security-related topics:

• z/OS Internet library (www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibrary)• IBM Redbooks (www.ibm.com/redbooks)

About this document xix

http://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/servers/resourcelink/svc00100.nsf/pages/zosInternetLibraryhttp://www.ibm.com/redbooks

xx z/OS: z/OS System SSL Programming

How to send your comments to IBM

We invite you to submit comments about the z/OS product documentation. Your valuable feedback helpsto ensure accurate and high-quality information.

Important: If your comment regards a technical question or problem, see instead “If you have a technicalproblem” on page xxi.

Submit your feedback by using the appropriate method for your type of comment or question:Feedback on z/OS function

If your comment or question is about z/OS itself, submit a request through the IBM RFE Community(www.ibm.com/developerworks/rfe/).

Feedback on IBM® Knowledge Center functionIf your comment or question is about the IBM Knowledge Center functionality, for example searchcapabilities or how to arrange the browser view, send a detailed email to IBM Knowledge CenterSupport at [email protected].

Feedback on the z/OS product documentation and contentIf your comment is about the information that is provided in the z/OS product documentation library,send a detailed email to [email protected]. We welcome any feedback that you have, includingcomments on the clarity, accuracy, or completeness of the information.

To help us better process your submission, include the following information:

• Your name, company/university/institution name, and email address• The following deliverable title and order number: z/OS System SSL Programming, SC14-7495-40• The section title of the specific information to which your comment relates• The text of your comment.

When you send comments to IBM, you grant IBM a nonexclusive authority to use or distribute thecomments in any way appropriate without incurring any obligation to you.

IBM or any other organizations use the personal information that you supply to contact you only about theissues that you submit.

If you have a technical problemIf you have a technical problem or question, do not use the feedback methods that are provided forsending documentation comments. Instead, take one or more of the following actions:

• Go to the IBM Support Portal (support.ibm.com).• Contact your IBM service representative.• Call IBM technical support.

© Copyright IBM Corp. 1999, 2019 xxi

http://www.ibm.com/developerworks/rfe/http://www.ibm.com/developerworks/rfe/mailto:[email protected]:[email protected]://support.ibm.com

xxii z/OS: z/OS System SSL Programming

Summary of changes

This information includes terminology, maintenance, and editorial changes. Technical changes oradditions to the text and illustrations for the current edition are indicated by a vertical line to the left ofthe change.

Summary of changes for z/OS Version 2 Release 4 (V2R4)The following changes are made for z/OS Version 2 Release 4 (V2R4). The most recent updates are listedat the top of each section.

New

• “Upgrading to TLS V1.2 from earlier SSL and TLS protocols” on page 62• “Upgrading from TLS V1.2 to TLS V1.2 and TLS V1.3 protocols” on page 64• “RSASSA-PSS signature support” on page 13• “TLS V1.3 protocol support” on page 59• The following SSL function return codes are added (See “SSL function return codes” on page 605):

– 441– 514– 515– 516– 517– 518– 519– 520– 521– 522– 523– 524– 525– 526– 527– 528– 529– 530– 531– 532– 533– 534– 535– 536– 537– 538

© Copyright IBM Corp. 1999, 2019 xxiii

– 539– 540– 541– 542– 543– 605

• The following CMS status codes (03353xxx) are added (See “CMS status codes (03353xxx)” on page667):

– 033530BF– 033530C0– 033530C1– 033530C2

Changed

• Chapter 1, “Introduction,” on page 1• “RACF CSFSERV resource requirements” on page 15.• “Algorithms and key sizes” on page 19.• “Create an SSL environment” on page 29• Chapter 6, “System SSL application programming considerations,” on page 37• “Session ID (SID) and session ticket cache” on page 41• “Suite B cryptography support” on page 47• “Enabling OCSP server stapling” on page 55• “Using server multiple key label support” on page 57• Chapter 7, “API reference,” on page 67• The following SSL APIs are modified:

– “gsk_attribute_get_buffer()” on page 70– “gsk_attribute_get_data()” on page 80– “gsk_attribute_get_enum()” on page 82– “gsk_attribute_get_numeric_value()” on page 90– “gsk_attribute_set_buffer()” on page 93– “gsk_attribute_set_callback()” on page 99– “gsk_attribute_set_enum()” on page 103– “gsk_attribute_set_numeric_value()” on page 113– “gsk_attribute_set_tls_extension()” on page 119– “gsk_environment_init()” on page 123– “gsk_environment_open()” on page 125– “gsk_secure_socket_init()” on page 145– “gsk_secure_socket_misc()” on page 157

• The following Certificate Management Services (CMS) APIs are modified:

– “gsk_add_record()” on page 174– “gsk_construct_certificate()” on page 182– “gsk_construct_self_signed_certificate()” on page 195– “gsk_construct_signed_certificate()” on page 198

xxiv z/OS: z/OS System SSL Programming

– “gsk_create_database_signed_certificate()” on page 226– “gsk_create_self_signed_certificate()” on page 241– “gsk_create_signed_certificate()” on page 245– “gsk_create_signed_certificate_record()” on page 248– “gsk_create_signed_certificate_set()” on page 252– “gsk_create_signed_crl()” on page 257– “gsk_create_signed_crl_record()” on page 260– “gsk_format_time()” on page 311– “gsk_import_certificate()” on page 365– “gsk_import_key()” on page 368– “gsk_make_signed_data_content_extended()” on page 395– “gsk_make_signed_data_msg_extended()” on page 402– “gsk_mktime()” on page 407– “gsk_read_signed_data_content()” on page 439– “gsk_read_signed_data_content_extended()” on page 442– “gsk_read_signed_data_msg()” on page 445– “gsk_read_signed_data_msg_extended()” on page 448– “gsk_replace_record()” on page 453– “gsk_sign_certificate()” on page 461– “gsk_sign_crl()” on page 464– “gsk_sign_data()” on page 467– “gsk_validate_certificate()” on page 470– “gsk_validate_certificate_mode()” on page 475– “gsk_verify_certificate_signature()” on page 487– “gsk_verify_crl_signature()” on page 490– “gsk_verify_data_signature()” on page 493

• “gskkyman interactive mode descriptions” on page 530:

– “Database menu” on page 531– “Create a self-signed certificate” on page 539

• “Creating a self-signed server or client certificate” on page 551• “Creating a signed certificate and key” on page 571• “Creating a certificate to be used with a fixed Diffie-Hellman key exchange” on page 575• “Using gskkyman to be your own certificate authority (CA)” on page 582• “gskkyman” on page 585• The following SSL function return codes are modified (See “SSL function return codes” on page 605):

– 8– 402– 405– 414– 466– 467– 476– 477

Summary of changes xxv

– 478– 479– 480– 508– 510– 512– 601

• The following CMS status codes (03353xxx) are modified (See “CMS status codes (03353xxx)” on page667):

– 03353030– 03353034– 03353088

• Appendix A, “Environment variables,” on page 721• Appendix B, “Sample C++ SSL files,” on page 743• Appendix C, “Cipher suite definitions,” on page 747• Appendix D, “Object identifiers,” on page 759

Deleted

No content was removed from this information.

Summary of changes for z/OS Version 2 Release 3 (V2R3)The following changes are made for z/OS Version 2 Release 3 (V2R3). The most recent updates are listedat the top of each section.

New

• “Using server multiple key label support” on page 57• “Enabling OCSP server stapling” on page 55• “gsk_construct_signed_crl()” on page 202• “gsk_format_time()” on page 311• “Displaying a newly created certificate request” on page 558• The following SSL function return codes are added (See “SSL function return codes” on page 605):

– 496– 497– 498– 499– 500– 507– 508– 509– 510– 511– 512– 513

xxvi z/OS: z/OS System SSL Programming

• The following deprecated SSL function return codes are added (See “Deprecated SSL function returncodes” on page 644):

– -126– -127– -128


– 033530B3– 033530B4– 033530B5– 033530B6– 033530B7– 033530B8– 033530B9– 033530BA– 033530BB– 033530BC– 033530BD– 033530BE

• New environment variables have been added to Appendix A, “Environment variables,” on page 721.

Changed

• “gsk_strerror()” on page 167• Chapter 13, “Messages and codes,” on page 605• “Installation information” on page 1 (APAR OA54127 Allow strong SSL/TLS ciphers in non-FIPS

mode to be used when CPACF feature 3863 is installed)• “gsk_environment_open()” on page 125 (APAR OA54127 Allow strong SSL/TLS ciphers in non-FIPS

mode to be used when CPACF feature 3863 is installed)• “gsk_make_signed_data_content_extended()” on page 395 (APAR OA54821 Support creation of PKCS

#7 SignedData detached signature messages)• “gsk_make_signed_data_msg_extended()” on page 402 (APAR OA54821 Support creation of PKCS #7

SignedData detached signature messages)• “gsk_get_cipher_info()” on page 499 (APAR OA54127 Allow strong SSL/TLS ciphers in non-FIPS mode

to be used when CPACF feature 3863 is installed)• “gsk_secure_soc_init()” on page 507 (APAR OA54127 Allow strong SSL/TLS ciphers in non-FIPS mode

to be used when CPACF feature 3863 is installed)• Appendix A, “Environment variables,” on page 721 (APAR OA54127 Allow strong SSL/TLS ciphers in

non-FIPS mode to be used when CPACF feature 3863 is installed)• Appendix C, “Cipher suite definitions,” on page 747 (APAR OA54127 Allow strong SSL/TLS ciphers in

non-FIPS mode to be used when CPACF feature 3863 is installed)• “Overview of hardware cryptographic features and System SSL” on page 10• Chapter 4, “System SSL and FIPS 140-2,” on page 19• “Algorithms and key sizes” on page 19• “Diffie-Hellman key agreement” on page 22• “Certificate stores” on page 25• “Key database files” on page 26

Summary of changes xxvii

• “Suite B cryptography support” on page 47• The following SSL APIs are modified:

– “gsk_attribute_get_buffer()” on page 70– “gsk_attribute_get_enum()” on page 82– “gsk_attribute_get_numeric_value()” on page 90– “gsk_attribute_set_buffer()” on page 93– “gsk_attribute_set_enum()” on page 103– “gsk_attribute_set_numeric_value()” on page 113– “gsk_environment_init()” on page 123– “gsk_environment_open()” on page 125– “gsk_secure_socket_init()” on page 145– “gsk_secure_socket_read()” on page 161


– “gsk_add_record()” on page 174– “gsk_change_database_password()” on page 177– “gsk_construct_certificate()” on page 182– “gsk_construct_renewal_request()” on page 192– “gsk_construct_self_signed_certificate()” on page 195– “gsk_construct_signed_certificate()” on page 198– “gsk_create_certification_request()” on page 217– “gsk_create_database()” on page 221– “gsk_create_database_renewal_request()” on page 223– “gsk_create_database_signed_certificate()” on page 226– “gsk_create_renewal_request()” on page 232– “gsk_create_revocation_source()” on page 235– “gsk_create_self_signed_certificate()” on page 241– “gsk_create_signed_certificate()” on page 245– “gsk_create_signed_certificate_record()” on page 248– “gsk_create_signed_certificate_set()” on page 252– “gsk_create_signed_crl()” on page 257– “gsk_create_signed_crl_record()” on page 260– “gsk_encode_export_key()” on page 288– “gsk_export_key()” on page 301– “gsk_fips_state_query()” on page 308– “gsk_fips_state_set()” on page 309– “gsk_generate_key_pair()” on page 337– “gsk_generate_key_parameters()” on page 340– “gsk_get_default_key()” on page 349– “gsk_get_record_by_id()” on page 359– “gsk_get_record_by_index()” on page 360– “gsk_get_record_by_label()” on page 361– “gsk_get_record_by_subject()” on page 362– “gsk_import_key()” on page 368

xxviii z/OS: z/OS System SSL Programming

– “gsk_make_encrypted_data_content()” on page 374– “gsk_make_enveloped_data_content()” on page 378– “gsk_make_enveloped_data_content_extended()” on page 381– “gsk_make_enveloped_data_msg()” on page 384– “gsk_make_enveloped_data_msg_extended()” on page 387– “gsk_make_signed_data_content()” on page 392– “gsk_make_signed_data_content_extended()” on page 395– “gsk_make_signed_data_msg()” on page 399– “gsk_make_signed_data_msg_extended()” on page 402– “gsk_open_database()” on page 412– “gsk_open_database_using_stash_file()” on page 414– “gsk_open_keyring()” on page 417– “gsk_read_enveloped_data_content()” on page 431– “gsk_read_enveloped_data_content_extended()” on page 433– “gsk_read_enveloped_data_msg()” on page 435– “gsk_read_enveloped_data_msg_extended()” on page 437– “gsk_read_signed_data_content()” on page 439– “gsk_read_signed_data_content_extended()” on page 442– “gsk_read_signed_data_msg()” on page 445– “gsk_read_signed_data_msg_extended()” on page 448– “gsk_replace_record()” on page 453– “gsk_set_default_key()” on page 456– “gsk_sign_certificate()” on page 461– “gsk_sign_crl()” on page 464– “gsk_sign_data()” on page 467– “gsk_validate_certificate()” on page 470– “gsk_validate_certificate_mode()” on page 475– “gsk_verify_certificate_signature()” on page 487– “gsk_verify_data_signature()” on page 493

• The following Deprecated Secure Socket Layer (SSL) APIs are modified:

– “gsk_initialize()” on page 501– “gsk_secure_soc_init()” on page 507

• Chapter 10, “Certificate/Key management,” on page 525• “Database menu” on page 531 was updated.• “Starting gskkyman” on page 542 was updated.• “gskkyman” on page 585 was updated.• The following SSL function return codes were modified (See “SSL function return codes” on page 605):

– 8– 466– 475

• The following deprecated SSL function return code is modified (See “Deprecated SSL function returncodes” on page 644):

– -35

Summary of changes xxix

• The following CMS status codes (03353xxx) were modified (See “CMS status codes (03353xxx)” onpage 667):

– 03353027– 03353034– 03353096– 03353099

• The following SSL started task messages (GSK01nnn) are modified (See “SSL started task messages(GSK01nnn)” on page 706 ):

– GSK01051E– GSK01052W

• Appendix A, “Environment variables,” on page 721• Appendix C, “Cipher suite definitions,” on page 747

Deleted

No content was removed from this information.

Summary of changes for z/OS Version 2 Release 2 (V2R2)The following changes are made for z/OS Version 2 Release 2 (V2R2).

New

• The following Certificate Management Services (CMS) APIs are added:

– “gsk_create_revocation_source()” on page 235– “gsk_decode_issuer_and_serial_number()” on page 273– “gsk_decode_signer_identifier()” on page 277– “gsk_encode_issuer_and_serial_number()” on page 292– “gsk_encode_signer_identifier()” on page 297– “gsk_free_issuer_and_serial_number()” on page 323– “gsk_free_oid()” on page 325– “gsk_free_revocation_source()” on page 332– “gsk_free_signer_identifier()” on page 333– “gsk_get_content_type_and_cms_version()” on page 348– “gsk_get_directory_numeric_value()” on page 357– “gsk_set_directory_numeric_value()” on page 460– “gsk_validate_extended_key_usage()” on page 482

• “x.509 certificate revocation” on page 526 is added.• The following SSL function return codes are added (See “SSL function return codes” on page 605):

– 473– 474– 475– 476– 477– 478– 479

xxx z/OS: z/OS System SSL Programming

– 480– 481– 482– 484– 485– 486– 487– 488– 489– 491– 492– 493– 494– 495

• The following deprecated SSL function return codes are added (See “Deprecated SSL function returncodes” on page 644):

– -112– -125


– 03353094– 03353095– 03353096– 03353097– 03353098– 03353099– 0335309A– 0335309B– 0335309C– 0335309D– 0335309E– 0335309F– 033530A0– 033530A1– 033530A2– 033530A3– 033530A4– 033530A5– 033530A6– 033530A7– 033530A8– 033530AA– 033530AB– 033530AC

Summary of changes xxxi

– 033530AD– 033530AE– 033530AF– 033530B0– 033530B1– 033530B2

• New environment variables have been added to Appendix A, “Environment variables,” on page 721.

Changed

• The following SSL APIs are modified:

– “gsk_attribute_get_buffer()” on page 70– “gsk_attribute_get_enum()” on page 82– “gsk_attribute_get_numeric_value()” on page 90– “gsk_attribute_set_buffer()” on page 93– “gsk_attribute_set_enum()” on page 103– “gsk_attribute_set_numeric_value()” on page 113– “gsk_environment_open()” on page 125– “gsk_secure_socket_init()” on page 145– “gsk_secure_socket_misc()” on page 157


– “gsk_decode_certificate_extension()” on page 266– “gsk_encode_certificate_extension()” on page 283– “gsk_get_cms_vector()” on page 346– “gsk_get_directory_certificates()” on page 351– “gsk_get_directory_crls()” on page 353– “gsk_get_directory_enum()” on page 355– “gsk_make_enveloped_data_content()” on page 378– “gsk_make_enveloped_data_content_extended()” on page 381– “gsk_make_enveloped_data_msg()” on page 384– “gsk_make_enveloped_data_msg_extended()” on page 387– “gsk_make_signed_data_conten

Documents

Version 2 Release 4 z/OS - IBM - United States · This edition applies to Version 2 Release 4 of z/OS (5650-ZOS) and to all subsequent releases and modifications until otherwise indicated