API reference
This appendix describes TCP/IP-related application programming interfaces (APIs) that can be used under z/VSE. We distinguish between the following types of APIs:
•Socket APIs
There are socket functions for IPv4 and for IPv6. Also, there are some stack-dependent differences.
•Secure socket (SSL) APIs
The z/OS compatible GSK interface is supported by CSI’s SSL implementation and by OpenSSL. In addition, native OpenSSL functions can be used with the IJBSLVSE.OBJ file.
 
Socket APIs
z/VSE and the IP stacks that are available for z/VSE provide the following socket application programming interfaces:
•EZA interfaces
These interfaces are widely compatible with the corresponding z/OS interfaces and are supported by TCP/IP for VSE/ESA, IPv6/VSE, and Linux Fast Path (LFP). They are based on the EZASMI macro interface for HLASM programmers and the EZASOKET call interface for COBOL, PL/I, and HLASM programmers.
Update with z/VSE 5.2: With Build 255pre02, IPv6/VSE provides an update to its EZA/GSK API so that an LE environment is automatically and dynamically established. This allows all standard types of batch and CICS applications to use the GSK API (and OpenSSL).
•TCP/IP APIs that use IBM Language Environment for z/VSE
Language Environment based interfaces include the Language Environment/VSE 1.4 C socket interface and the REXX/VSE Socket API support within REXX/VSE.
•TCP/IP for VSE/ESA native APIs
Native TCP/IP for VSE/ESA interfaces include the Assembler SOCKET macro interface, the COBOL and PL/I preprocessor interface, the BSD-C socket interface, and the REXX socket APIs.
For more information about APIs, see these resources:
•z/VSE TCP/IP Support, SC34-2640, which is available at this website:
SSL APIs
This section, we describe the SSL-related API functions that are provided by TCP/IP for VSE/ESA and OpenSSL. Applications must link the IJBSLVSE.OBJ to get access to the API functions. The IJBSLVSE.OBJ file is part of OpenSSL on z/VSE. For more information, see 5.1.1, “What is available on z/VSE” on page 152.
z/OS SSL API
In this topic, we describe the z/OS SSL API. This API is supported by TCP/IP for VSE/ESA by using the $EDCTCPV phase and by OpenSSL by using phase IJBSSL.
For more information about this API, see the following resources:
1. TCP/IP for VSE Programmer’s Guide, which is provided by CSI. This book describes the API from the CSI perspective.
2. z/OS Cryptographic Services, SSL Programming, SC24-5901. This book describes the API from the z/OS perspective and is applicable for OpenSSL.
In this appendix, we describe only the differences of the API functions that are caused by the implementation of the OpenSSL-to-GSK layer.
gsk_free_memory
Releases storage that is allocated by the SSL run time.
No change for z/VSE compared to z/OS.
gsk_get_cipher_info
Returns the supported cipher specifications.
z/VSE features the following changes:
•The list of returned cipher suites differs from what is documented in the z/OS book because some of the ciphers that are used on z/OS are not supported by OpenSSL (for example, “00”). With APAR DY47545 OpenSSL on z/VSE returns the following strings:
"091512060201" // LOW_SECURITY
"C027C014C013C0126B67393316153D3C3B352F0A09" // HIGH_SECURITY
The first four ECDHE-RSA cipher suites have 4-digit names that start with C0. They are followed by the 2-character DHE-RSA ciphers 6B, 67, 39, 33, 16, and 15.
Cipher suites 3D, 3C, and 3B are part of the TLSv1.2 support that is included since OpenSSL 1.0.1e.
For compatibility with an earlier version reasons, the list still returns the older cipher suites 35, 2F, 0A, and 09. However, from today’s perspective, at least 09 and 0A are no longer considered to provide “high security”.
•The version field of the gsk_sec_level struct returns the supported OpenSSL version (for example, 101 = 1.0.1).
gsk_get_dn_by_label
Gets the distinguished name for a certificate.
z/VSE features the following changes:
•The specified key or cert file must be a Librarian member with member type PEM or a VSAM file.
•In z/OS, they return NULL if the key database cannot be accessed. However, in VSE, we do not have enough information to access the keystore.
gsk_initialize
Starts the System SSL runtime environment.
In z/VSE, read and evaluate the JCL variables SSL$DBG and SSL$ICA changed.
gsk_secure_soc_close
Closes a secure socket connection. There was no change for z/VSE.
gsk_secure_soc_init
Starts a secure socket connection. There was no change for z/VSE.
gsk_secure_soc_read
Reads data by using a secure socket connection.
In z/VSE, the changes included the fact that the caller can specify buflen = 0 to check for pending bytes. When buflen = 0, SSL_pending is called and gsk_secure_soc_read returns the return code of SSL_pending.
gsk_secure_soc_reset
Resets the session keys for a secure connection. There was no change for z/VSE.
gsk_secure_soc_write
Writes data by using a secure socket connection. There was no change for z/VSE
gsk_uninitialize
Ends the SSL environment. There was no change for z/VSE
gsk_user_set
Sets an application callback. As of this writing, this is not supported.
OpenSSL API
In this section, we describe the native OpenSSL API functions that are supported on z/VSE, which means that they can be used by a user application with IJBSLVSE.OBJ.
The full OpenSSL API is described at this website:
Therefore, we do not add any API description.
 
Note: The following VSE-specific functions allow switching between the GSK API and the OpenSSL API:
ssl_enable_gsk()
ssl_disable_gsk()
The following native OpenSSL functions are provided by z/VSE 5.1, APAR DY47499:
•AES_encrypt
•AES_set_encrypt_key
•BIO_ctrl
•BIO_ctrl_get_read_request
•BIO_ctrl_get_write_guarantee
•BIO_ctrl_pending
•BIO_f_base64
•BIO_f_ssl
•BIO_free
•BIO_free_all
•BIO_new
•BIO_new_bio_pair
•BIO_new_dgram
•BIO_new_fp
•BIO_new_mem_buf
•BIO_new_socket
•BIO_nread
•BIO_nwrite
•BIO_nwrite0
•BIO_printf
•BIO_push
•BIO_read
•BIO_s_mem
•BIO_set_flags
•BIO_snprintf
•BIO_test_flags
•BIO_write
•BN_CTX_free
•BN_CTX_get
•BN_CTX_new
•BN_CTX_start
•BN_add_word
•BN_bin2bn
•BN_bn2bin
•BN_bn2dec
•BN_clear_free
•BN_cmp
•BN_copy
•BN_dec2bn
•BN_div
•BN_dup
•BN_free
•BN_hex2bn
•BN_is_bit_set
•BN_lshift
•BN_mask_bits
•BN_new
•BN_num_bits
•BN_print_fp
•BN_rand
•BN_set_word
•BN_sub
•BN_value_one
•CRYPTO_cleanup_all_ex_data
•CRYPTO_dbg_set_options
•CRYPTO_free
•CRYPTO_lock
•CRYPTO_mem_ctrl
•CRYPTO_mem_leaks
•CRYPTO_mem_leaks_fp
•CRYPTO_set_locking_callback
•CRYPTO_set_mem_debug_functions
•CRYPTO_set_mem_debug_options
•CRYPTO_thread_id
•DES_is_weak_key
•DH_compute_key
•DH_free
•DH_generate_key
•DH_new
•DH_size
•DHparams_print_fp
•DSA_SIG_free
•DSA_SIG_new
•DSA_do_sign
•DSA_do_verify
•DSA_free
•DSA_generate_key
•DSA_generate_parameters_ex
•DSA_new
•DSA_print_fp
•ECDH_compute_key
•ECDSA_SIG_free
•ECDSA_SIG_new
•ECDSA_do_sign
•ECDSA_do_verify
•EC_GROUP_cmp
•EC_GROUP_free
•EC_GROUP_get_curve_name
•EC_GROUP_get_degree
•EC_GROUP_get_order
•EC_GROUP_method_of
•EC_GROUP_new_by_curve_name
•EC_GROUP_set_asn1_flag
•EC_KEY_free
•EC_KEY_generate_key
•EC_KEY_get0_group
•EC_KEY_get0_private_key
•EC_KEY_get0_public_key
•EC_KEY_new_by_curve_name
•EC_KEY_set_asn1_flag
•EC_KEY_set_group
•EC_KEY_set_public_key
•EC_METHOD_get_field_type
•EC_POINT_clear_free
•EC_POINT_cmp
•EC_POINT_free
•EC_POINT_get_affine_coordinates_GFp
•EC_POINT_is_at_infinity
•EC_POINT_mul
•EC_POINT_new
•EC_POINT_oct2point
•EC_POINT_point2oct
•ENGINE_load_builtin_engines
•ENGINE_register_all_complete
•ERR_clear_error
•ERR_error_string
•ERR_free_strings
•ERR_get_error
•ERR_get_error_line_data
•ERR_load_crypto_strings
•ERR_print_errors
•ERR_print_errors_fp
•ERR_remove_state
•EVP_CIPHER_CTX_cleanup
•EVP_CIPHER_CTX_get_app_data
•EVP_CIPHER_CTX_init
•EVP_CIPHER_CTX_iv_length
•EVP_CIPHER_CTX_key_length
•EVP_CIPHER_CTX_set_app_data
•EVP_CIPHER_CTX_set_key_length
•EVP_CIPHER_CTX_set_padding
•EVP_CIPHER_block_size
•EVP_CIPHER_key_length
•EVP_CIPHER_nid
•EVP_Cipher
•EVP_CipherInit
•EVP_DecryptFinal_ex
•EVP_DecryptInit_ex
•EVP_DecryptUpdate
•EVP_Digest
•EVP_DigestFinal
•EVP_DigestFinal_ex
•EVP_DigestInit
•EVP_DigestInit_ex
•EVP_DigestUpdate
•EVP_EncryptFinal_ex
•EVP_EncryptInit_ex
•EVP_EncryptUpdate
•EVP_MD_CTX_cleanup
•EVP_MD_CTX_init
•EVP_MD_size
•EVP_MD_type
•EVP_PKEY_free
•EVP_PKEY_get1_DSA
•EVP_PKEY_get1_EC_KEY
•EVP_PKEY_get1_RSA
•EVP_aes_128_cbc
•EVP_aes_192_cbc
•EVP_aes_256_cbc
•EVP_bf_cbc
•EVP_cast5_cbc
•EVP_cleanup
•EVP_des_cbc
•EVP_des_ede3_cbc
•EVP_enc_null
•EVP_get_cipherbyname
•EVP_get_digestbyname
•EVP_md5
•EVP_rc4
•EVP_sha1
•EVP_sha256
•EVP_sha512
•GENERAL_NAME_free
•HMAC
•HMAC_CTX_cleanup
•HMAC_CTX_init
•HMAC_Final
•HMAC_Init
•HMAC_Update
•MD5_Final
•MD5_Init
•MD5_Update
•OBJ_cmp
•OBJ_nid2ln
•OBJ_nid2sn
•OBJ_obj2nid
•OPENSSL_add_all_algorithms_noconf
•OpenSSL_add_all_ciphers
•OpenSSL_add_all_digests
•PEM_read_PrivateKey
•PEM_read_X509
•PEM_read_bio_PrivateKey
•PEM_write_bio_DSAPrivateKey
•PEM_write_bio_ECPrivateKey
•PEM_write_bio_RSAPrivateKey
•PKCS7_free
•RAND_bytes
•RAND_seed
•RAND_status
•RC4
•RC4_set_key
•RSA_blinding_on
•RSA_free
•RSA_generate_key_ex
•RSA_new
•RSA_print_fp
•RSA_private_decrypt
•RSA_private_encrypt
•RSA_public_decrypt
•RSA_public_encrypt
•RSA_sign
•RSA_size
•SHA1_Final
•SHA1_Init
•SHA1_Update
•SHA256_Final
•SHA256_Init
•SHA256_Update
•SSL_CIPHER_get_name
•SSL_CIPHER_get_version
•SSL_CTX_callback_ctrl
•SSL_CTX_ctrl
•SSL_CTX_free
•SSL_CTX_get_cert_store
•SSL_CTX_load_verify_locations
•SSL_CTX_new
•SSL_CTX_set_cert_verify_callback
•SSL_CTX_set_cipher_list
•SSL_CTX_set_default_verify_paths
•SSL_CTX_set_info_callback
•SSL_CTX_set_session_id_context
•SSL_CTX_set_tmp_rsa_callback
•SSL_CTX_set_verify
•SSL_CTX_use_PrivateKey_file
•SSL_CTX_use_certificate_file
•SSL_SESSION_get_id
•SSL_ctrl
•SSL_do_handshake
•SSL_free
•SSL_get_current_cipher
•SSL_get_error
•SSL_get_peer_certificate
•SSL_get_servername
•SSL_get_servername_type
•SSL_get_version
•SSL_library_init
•SSL_load_error_strings
•SSL_new
•SSL_pending
•SSL_read
•SSL_set_accept_state
•SSL_set_bio
•SSL_set_connect_state
•SSL_set_session
•SSL_set_verify
•SSL_state
•SSL_state_string
•SSL_state_string_long
•SSL_version
•SSL_write
•SSLeay
•SSLeay_version
•SSLv23_method
•SSLv2_method
•SSLv3_method
•TLSv1_method
•X509_LOOKUP_ctrl
•X509_LOOKUP_file
•X509_LOOKUP_hash_dir
•X509_NAME_add_entry_by_txt
•X509_NAME_entry_count
•X509_NAME_free
•X509_NAME_get_entry
•X509_NAME_new
•X509_NAME_oneline
•X509_NAME_print_ex
•X509_STORE_CTX_free
•X509_STORE_CTX_get_ex_data
•X509_STORE_CTX_get_ex_new_index
•X509_STORE_CTX_init
•X509_STORE_CTX_new
•X509_STORE_CTX_set_ex_data
•X509_STORE_CTX_set_flags
•X509_STORE_add_lookup
•X509_STORE_free
•X509_STORE_new
•X509_STORE_set_flags
•X509_free
•X509_get_ext_d2i
•X509_get_issuer_name
•X509_get_pubkey
•X509_get_serialNumber
•X509_get_subject_name
•X509_print
•X509_verify_cert
•X509_verify_cert_error_string
•apps_ssl_info_callback
•ascii2ebcdic
•d2i_PKCS7
•d2i_PrivateKey
•d2i_X509
•d2i_X509_NAME
•i2d_PrivateKey
•i2d_PublicKey
•i2d_X509
•i2d_X509_NAME
•i2t_ASN1_OBJECT
•load_cert
•load_key
•set_cert_key_stuff
•sk_num
•sk_pop_free
•sk_value
•verify_callback
In addition to these OpenSSL functions, the following z/VSE-specific functions are provided:
•ssl_disable_debug
•ssl_disable_gsk
•ssl_disable_ibmca
•ssl_enable_debug
•ssl_enable_gsk
•ssl_enable_ibmca
 
 
 
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset