SIOCSHSNOTIFY IOCTL

C and C++ applications that use IBM® Cryptographic Services System SSL APIs can use the SIOCSHSNOTIFY ioctl in special cases to notify the z/OS® Encryption Readiness Technology (zERT) in the TCP/IP stack to prepare to observe a TLS or SSL handshake over the associated TCP socket connection. This ioctl provides the proper context under which zERT can properly observe the new TLS or SSL handshake.

The SIOCSHSNOTIFY ioctl is called using the socket descriptor (returned by the socket() call) of the connection over which the TLS handshake will occur, and it should only be called when both of the following conditions are true:
  1. The application program invokes System SSL APIs directly to initiate the TLS/SSL handshake.
    • Applications that use a TLS/SSL provider other than System SSL do not need to use this ioctl. If they do, the ioctl will have no functional effect.
    • If the SIOCSHSNOTIFY ioctl is called on a socket that is protected by AT-TLS, it will be ignored by the TCP/IP stack.
  2. The application sends or receives one or more bytes of application-specific data over the subject socket prior to invoking the gsk_secure_socket_init() or the gsk_secure_soc_init() (deprecated) function to initiate the TLS or SSL handshake. Applications that initiate the TLS or SSL handshake immediately after establishing the socket connection (before any application data is sent or received), do not need to use this ioctl. If the ioctl is called before any application data has flowed over the connection, it does not have any functional effect.

Since the SIOCSHSNOTIFY ioctl is only intended for use by System SSL applications, which must be coded in C or C++, it is only supported by those programming languates. Both 31-bit and 64-bit addressing modes are supported.

SIOCSHSNOTIFY requires an input parameter list. The C language parameter list mapping is defined in the EZBZHSNC header file (ezbzhsnc.h), which is installed in SEZANMAC and in the file system directory /usr/include.