Table of Contents (exploded view)
Abstract for Cryptographic Services System Secure Sockets Layer Programming
Summary of changes
Summary of changes for z/OS Version 2 Release 2 (V2R2)
Summary of changes for z/OS Version 2 Release 1
Introduction
Software dependencies
Installation information
System SSL parts shipped in the UNIX System Services file system
System SSL parts shipped in PDS and PDSE
How System SSL works for secure socket communication
Using System SSL on z/OS
System SSL application overview
Using cryptographic features with System SSL
Guidelines for using hardware cryptographic features
Overview of hardware cryptographic features and System SSL
Random byte generation support
Elliptic Curve Cryptography support
Diffie-Hellman key agreement
RACF CSFSERV resource requirements
PKCS #11 and setting CLEARKEY resource within CRYPTOZ class
PKCS #11 Cryptographic operations using ICSF handles
System SSL and FIPS 140-2
Algorithms and key sizes
Random byte generation
Diffie-Hellman key agreement
Certificates
SSL/TLS protocol
System SSL module verification setup
Performance guideline
Certificate stores
SAF key rings and PKCS #11 tokens
Key database files
PKCS #12 files
Application changes
SSL started task
Sysplex session ID cache
Writing and building a z/OS System SSL application
Writing a System SSL source program
Create an SSL environment
System SSL server program
System SSL client program
Building a z/OS System SSL application
Running a z/OS System SSL application
System SSL application programming considerations
Non-Blocking I/O
Non-Blocking socket primer
Affected SSL functions
Enable/disable non-blocking mode
Differences in SSL and unsecured non-blocking mode
Client authentication certificate selection
I/O routine replacement
Callback routine for I/O
Use of user data
Session ID (SID) cache
Session ID (SID)
Session ID cache replacement
Format
Callbacks
Parameters
Session renegotiation notification
TLS extensions
Setting server side extensions
Setting client side extensions
Suite B cryptography support
SSL/TLS partner certificate revocation checking
Enabling OCSP support
Enabling HTTP CDP support
Enabling LDAP CRL support
Revocation source checking (order of precedence)
Revocation security enforcement
Revocation examples
Migrating from deprecated SSL interfaces
API reference
gsk_attribute_get_buffer()
gsk_attribute_get_cert_info()
gsk_attribute_get_data()
gsk_attribute_get_enum()
gsk_attribute_get_numeric_value()
gsk_attribute_set_buffer()
gsk_attribute_set_callback()
gsk_attribute_set_enum()
gsk_attribute_set_numeric_value()
gsk_attribute_set_tls_extension()
gsk_environment_close()
gsk_environment_init()
gsk_environment_open()
gsk_free_cert_data()
gsk_get_all_cipher_suites()
gsk_get_cert_by_label()
gsk_get_cipher_suites()
gsk_get_ssl_vector()
gsk_get_update()
gsk_list_free()
gsk_secure_socket_close()
gsk_secure_socket_init()
gsk_secure_socket_misc()
gsk_secure_socket_open()
gsk_secure_socket_read()
gsk_secure_socket_shutdown()
gsk_secure_socket_write()
gsk_strerror()
Certificate Management Services (CMS) API reference
gsk_add_record()
gsk_change_database_password()
gsk_change_database_record_length()
gsk_close_database()
gsk_close_directory()
gsk_construct_certificate()
gsk_construct_private_key()
gsk_construct_private_key_rsa()
gsk_construct_public_key()
gsk_construct_public_key_rsa()
gsk_construct_renewal_request()
gsk_construct_self_signed_certificate()
gsk_construct_signed_certificate()
gsk_copy_attributes_signers()
gsk_copy_buffer()
gsk_copy_certificate()
gsk_copy_certificate_extension()
gsk_copy_certification_request()
gsk_copy_content_info()
gsk_copy_crl()
gsk_copy_name()
gsk_copy_private_key_info()
gsk_copy_public_key_info()
gsk_copy_record()
gsk_create_certification_request()
gsk_create_database()
gsk_create_database_renewal_request()
gsk_create_database_signed_certificate()
gsk_create_renewal_request()
gsk_create_revocation_source()
gsk_create_self_signed_certificate()
gsk_create_signed_certificate()
gsk_create_signed_certificate_record()
gsk_create_signed_certificate_set()
gsk_create_signed_crl()
gsk_create_signed_crl_record()
gsk_decode_base64()
gsk_decode_certificate()
gsk_decode_certificate_extension()
gsk_decode_certification_request()
gsk_decode_crl()
gsk_decode_import_certificate()
gsk_decode_import_key()
gsk_decode_issuer_and_serial_number()
gsk_decode_name()
gsk_decode_private key()
gsk_decode_public key()
gsk_decode_signer_identifier()
gsk_delete_record()
gsk_dn_to_name()
gsk_encode_base64()
gsk_encode_certificate_extension()
gsk_encode_ec_parameters()
gsk_encode_export_certificate()
gsk_encode_export_key()
gsk_encode_export_request()
gsk_encode_issuer_and_serial_number()
gsk_encode_name()
gsk_encode_private_key()
gsk_encode_public_key()
gsk_encode_signature()
gsk_encode_signer_identifier()
gsk_export_certificate()
gsk_export_certification_request()
gsk_export_key()
gsk_factor_private_key()
gsk_factor_private_key_rsa()
gsk_factor_public_key()
gsk_factor_public_key_rsa()
gsk_fips_state_query()
gsk_fips_state_set()
gsk_free_attributes_signers()
gsk_free_buffer()
gsk_free_certificate()
gsk_free_certificates()
gsk_free_certificate_extension()
gsk_free_certification_request()
gsk_free_content_info()
gsk_free_crl()
gsk_free_crls()
gsk_free_decoded_extension()
gsk_free_issuer_and_serial_number()
gsk_free_name()
gsk_free_oid()
gsk_free_private_key()
gsk_free_private_key_info()
gsk_free_public_key()
gsk_free_public_key_info()
gsk_free_record()
gsk_free_records()
gsk_free_revocation_source()
gsk_free_signer_identifier()
gsk_free_string()
gsk_free_strings()
gsk_generate_key_agreement_pair()
gsk_generate_key_pair()
gsk_generate_key_parameters()
gsk_generate_random_bytes()
gsk_generate_secret()
gsk_get_certificate_algorithms()
gsk_get_certificate_info()
gsk_get_cms_vector()
gsk_get_content_type_and_cms_version()
gsk_get_default_key()
gsk_get_default_label()
gsk_get_directory_certificates()
gsk_get_directory_crls()
gsk_get_directory_enum()
gsk_get_directory_numeric_value()
gsk_get_ec_parameters_info()
gsk_get_record_by_id()
gsk_get_record_by_index()
gsk_get_record_by_label()
gsk_get_record_by_subject()
gsk_get_record_labels()
gsk_get_update_code()
gsk_import_certificate()
gsk_import_key()
gsk_make_content_msg()
gsk_make_data_content()
gsk_make_data_msg()
gsk_make_encrypted_data_content()
gsk_make_encrypted_data_msg()
gsk_make_enveloped_data_content()
gsk_make_enveloped_data_content_extended()
gsk_make_enveloped_data_msg()
gsk_make_enveloped_data_msg_extended()
gsk_make_enveloped_private_key_msg()
gsk_make_signed_data_content()
gsk_make_signed_data_content_extended()
gsk_make_signed_data_msg()
gsk_make_signed_data_msg_extended()
gsk_make_wrapped_content()
gsk_mktime()
gsk_modify_pkcs11_key_label()
gsk_name_compare()
gsk_name_to_dn()
gsk_open_database()
gsk_open_database_using_stash_file()
gsk_open_directory()
gsk_open_keyring()
gsk_perform_kat()
gsk_query_crypto_level()
gsk_query_database_label()
gsk_query_database_record_length()
gsk_rdtime()
gsk_read_content_msg()
gsk_read_data_content()
gsk_read_data_msg()
gsk_read_encrypted_data_content()
gsk_read_encrypted_data_msg()
gsk_read_enveloped_data_content()
gsk_read_enveloped_data_content_extended()
gsk_read_enveloped_data_msg()
gsk_read_enveloped_data_msg_extended()
gsk_read_signed_data_content()
gsk_read_signed_data_content_extended()
gsk_read_signed_data_msg()
gsk_read_signed_data_msg_extended()
gsk_read_wrapped_content()
gsk_receive_certificate()
gsk_replace_record()
gsk_set_default_key()
gsk_set_directory_enum()
gsk_set_directory_numeric_value()
gsk_sign_certificate()
gsk_sign_crl()
gsk_sign_data()
gsk_validate_certificate()
gsk_validate_certificate_mode()
gsk_validate_extended_key_usage()
gsk_validate_hostname()
gsk_validate_server()
gsk_verify_certificate_signature()
gsk_verify_crl_signature()
gsk_verify_data_signature()
Deprecated Secure Socket Layer (SSL) APIs
gsk_free_memory()
gsk_get_cipher_info()
gsk_get_dn_by_label()
gsk_initialize()
gsk_secure_soc_close()
gsk_secure_soc_init()
gsk_secure_soc_read()
gsk_secure_soc_reset()
gsk_secure_soc_write()
gsk_srb_initialize()
GSKSRBRD
GSKSRBWT
gsk_uninitialize()
gsk_user_set()
Certificate/Key management
Introduction
x.509 certificate revocation
gskkyman Overview
Setting up the environment to run gskkyman
Key database files
z/OS PKCS #11 tokens
gskkyman interactive mode descriptions
Database menu
Key/Token management
Key Management menu/Token management menu
Manage Keys and Certificates
Manage certificates
Manage certificate requests
Create new certificate request
Receive requested certificate or a renewal certificate
Create a self-signed certificate
Import a certificate
Import a certificate and a private key
Show the default key
Store database password
Show database record length
gskkyman interactive mode examples
Starting gskkyman
Creating, opening, and deleting a key database file
Changing a key database password
Storing an encrypted key database password
Creating, opening, and deleting a z/OS PKCS #11 token
Creating a self-signed server or client certificate
Creating a certificate request
Sending the certificate request
Receiving the signed certificate or renewal certificate
Managing keys and certificates
Showing certificate/key information
Marking a certificate (and private key) as the default certificate
Copying a certificate (and private key) to a different key database or z/OS PKCS #11 token
Copying a certificate without its private key
Copying a certificate with its private key
Copying a certificate and its private key from a key database on the same system
Copying a certificate and its private key from a z/OS PKCS #11 token on the same system
Removing a certificate (and private key)
Changing a certificate label
Creating a signed certificate and key
Creating a signed ECC certificate and key
Creating a certificate to be used with a fixed Diffie-Hellman key exchange
Creating a certificate renewal request
Importing a certificate from a file as a trusted CA certificate
Importing a certificate from a file with its private key
Using gskkyman to be your own certificate authority (CA)
Migrating from key database files to z/OS PKCS #11 token
Migrating key database files to RACF key rings
gskkyman command line mode syntax
gskkyman
gskkyman command line mode examples
gskkyman command line mode displays
SSL started task
GSKSRVR environment variables
Configuring the SSL started task
Server operator commands
Sysplex session cache support
Component trace support
Hardware cryptography failure notification
Obtaining diagnostic information
Obtaining System SSL trace information
Capturing trace data through environment variables
Component trace support
Capturing component trace data
Displaying the trace data
Event trace records for System SSL
Capturing component trace data without an external writer
Messages and codes
SSL function return codes
1
3
4
5
6
7
8
9
10
11
12
13
14
102
103
106
109
201
202
203
204
302
401
402
403
405
406
407
408
410
411
412
413
414
415
416
417
420
421
422
427
428
429
431
432
433
434
435
436
437
438
439
440
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
501
502
503
504
505
601
602
603
604
701
702
703
704
705
706
707
708
Deprecated SSL function return codes
1
2
3
4
9
12
13
16
17
18
19
70
71
72
100
102
103
104
-1
-2
-3
-5
-6
-7
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-25
-26
-27
-28
-30
-34
-35
-36
-37
-38
-39
-40
-41
-42
-43
-44
-46
-47
-48
-51
-53
-54
-55
-56
-57
-70
-71
-72
-73
-99
-100
-101
-104
-105
-106
-107
-108
-109
-110
-111
-112
-124
-125
ASN.1 status codes (014CExxx)
014CE001
014CE002
014CE003
014CE004
014CE005
014CE006
014CE007
014CE008
014CE009
014CE00A
014CE00B
014CE00C
014CE00D
014CE00E
014CE00F
014CE010
014CE011
014CE012
014CE013
014CE014
014CE015
014CE016
014CE017
014CE018
014CE019
014CE01A
014CE01B
014CE01C
014CE01D
014CE01E
014CE01F
014CE020
014CE021
014CE022
CMS status codes (03353xxx)
03353001
03353002
03353003
03353004
03353005
03353006
03353007
03353008
03353009
0335300A
0335300B
0335300C
0335300D
0335300E
0335300F
03353010
03353011
03353012
03353013
03353014
03353015
03353016
03353017
03353018
03353019
0335301A
0335301B
0335301C
0335301D
0335301E
0335301F
03353020
03353021
03353022
03353023
03353024
03353025
03353026
03353027
03353028
03353029
0335302A
0335302B
0335302C
0335302D
0335302E
0335302F
03353030
03353031
03353032
03353033
03353034
03353035
03353036
03353037
03353038
03353039
0335303A
0335303B
0335303C
0335303D
0335303E
0335303F
03353040
03353041
03353042
03353043
03353044
03353045
03353046
03353047
03353048
03353049
0335304A
0335304B
0335304C
0335304D
0335304E
0335304F
03353050
03353051
03353052
03353053
03353054
03353055
03353056
03353057
03353058
03353059
0335305A
0335305B
0335305C
0335305D
0335305E
0335305F
03353060
03353061
03353062
03353064
03353065
03353066
03353067
03353068
03353069
0335306A
0335306B
0335306C
0335306D
0335306E
0335306F
03353070
03353071
03353072
03353073
03353074
03353076
03353077
03353078
03353079
0335307A
0335307B
0335307C
0335307D
0335307E
0335307F
03353080
03353081
03353082
03353083
03353084
03353085
03353086
03353087
03353088
03353089
0335308A
0335308B
0335308C
0335308D
0335308E
0335308F
03353090
03353093
03353094
03353095
03353096
03353097
03353098
03353099
0335309A
0335309B
0335309C
0335309D
0335309E
0335309F
033530A0
033530A1
033530A2
033530A3
033530A4
033530A5
033530A6
033530A7
033530A8
033530A9
033530AA
033530AB
033530AC
033530AD
033530AE
033530AF
033530B0
033530B1
033530B2
SSL started task messages (GSK01nnn)
GSK01001I
GSK01002E
GSK01003I
GSK01004I
GSK01005E
GSK01006E
GSK01007E
GSK01008I
GSK01009I
GSK01010A
GSK01011A
GSK01012A
GSK01013I
GSK01014I
GSK01015E
GSK01016E
GSK01017I
GSK01018I
GSK01019E
GSK01020E
GSK01021E
GSK01022E
GSK01023E
GSK01024E
GSK01025I
GSK01026I
GSK01027I
GSK01028E
GSK01029I
GSK01030I
GSK01031I
GSK01032I
GSK01033E
GSK01034E
GSK01035E
GSK01036E
GSK01037E
GSK01038E
GSK01039E
GSK01040I
GSK01041I
GSK01042E
GSK01043E
GSK01044E
GSK01045E
GSK01046I
GSK01047I
GSK01048W
GSK01049A
GSK01050I
GSK01051E
GSK01052W
GSK01053E
GSK01054E
GSK01057I
GSK01064I
Utility messages (GSK00nnn)
GSK00001E
GSK00002E
GSK00003E
GSK00004R
GSK00005R
GSK00006E
GSK00007R
GSK00008E
GSK00009E
Environment variables
Sample C++ SSL files
Cipher suite definitions
Object identifiers