gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a secure session

 #include <gskssl.h>
 #include <qsoasync.h>

 int gsk_secure_soc_startInit(gsk_handle my_session_handle,
                              int IOCompletionPort,
                              Qso_OverlappedIO_t * communicationsArea)

        

The gsk_secure_soc_startInit() function is used to initiate an asynchronous negotiation of a secure session, using the attributes set for the SSL environment and the secure session. This API starts the SSL handshake to the remote peer and upon successful completion of QsoWaitForIOCompletion() a secure session is established.

Parameters

my_session_handle (Input)

The handle returned from gsk_secure_soc_open() that will be used to negotiate the secure session.

int IOCompletionPort (Input)

The I/O completion port that should be posted when the operation completes.

Qso_OverlappedIO_t * communicationsArea (Input/Output)

A pointer to a structure that contains the following information:

descriptorHandle	(Input) - The descriptor handle is application specific and is never used by the system. This field is intended to make it easier for the application to keep track of information regarding a given socket connection.
buffer	Not used.
bufferLength	Not used.
postFlag	Not used.
postFlagResult	Not used.
fillBuffer	Not used.
returnValue	(Output) - When the negotiate operation completes asynchronously, this field contains indication of success or failure.
errnoValue	(Output) - When the negotiate operation completes asynchronously and returnValue is GSK_ERROR_IO, this field will contain an errno further defining the failure.
operationCompleted	(Output) - If the operation is posted to the I/O completion port, this field is updated to indicate that the operation was a GSKSECURESOCSTARTINIT.
secureDataTransferSize	Not used.
bytesAvailable	Not used.
operationWaitTime	Not used.
postedDescriptor	Not used - Must be set to zero.
operationId	(Input) - An identifier to uniquely identify this operation or a group of operations. It can be set with the return value from QsoGenerateOperationId() or with an application-defined value. This value is preserved but ignored by all APIs except QsoCancelOperation() and QsoIsOperationPending().
reserved1	(Output) - Must be set to hexadecimal zeroes.
reserved2	(Input) - Must be set to hexadecimal zeroes.

Authorities

Authorization of *R (allow access to the object) to the certificate store file and its associated files is required. Authorization of *X (allow use of the object) to each directory of the path name of the certificate store file and its associated files is required.

Return Values

gsk_secure_soc_startInit() returns an integer. Possible values are:

• GSK_IBMI_ASYNCHRONOUS_SOC_INIT - The function has been started. When the function completes, the Qso_OverlappedIO_t communications structure will be updated with the results and the I/O completion port will be posted.
  
  
• If the function fails, possible values are:
  
  

  [GSK_INVALID_HANDLE]

  The handle specified was not valid.

  [GSK_IBMI_ERROR_NO_INITIALIZE]

  A successful gsk_environment_init() was not previously called with this handle.

  [GSK_IBMI_ERROR_NOT_TCP]

  The socket descriptor type is not SOCK_STREAM or the address family is not AF_INET or AF_INET6.

  [GSK_IBMI_ERROR_ALREADY_SECURE]

  The socket descriptor is already in use by another secure session.

  [GSK_IBMI_ERROR_INVALID_POINTER]

  The my_session_handle pointer is not valid.

  [GSK_INTERNAL_ERROR]

  An unexpected error occurred during SSL processing.

  [GSK_IBMI_ERROR_INVALID_OVERLAPPEDIO_T]

  The Qso_OverLappedIO_t specified was not valid.

  [GSK_IBMI_ERROR_INVALID_IOCOMPLETIONPORT]

  The I/O completion port specified was not valid.

  [GSK_IBMI_ERROR_BAD_SOCKET_DESCRIPTOR]

  The socket descriptor specified within the gsk_handle was not valid.

  [GSK_ERROR_NO_RI_INDICATION]

  GSK_EXTENDED_RENEGOTIATION_CRITICAL_SERVER or GSK_EXTENDED_RENEGOTIATION_CRITICAL_CLIENT was set to GSK_TRUE and the peer did not provide indication that it supports RFC 5746.

  [GSK_ERROR_IO]

  An error occured in SSL processing; check the errno value.

Error Conditions

When gsk_secure_soc_startInit() API fails with return code [GSK_ERROR_IO], errno can be set to:

[EIO]

Input/output error.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

If an errno is returned that is not in this list, see Errno Values for UNIX^®-Type Functions for a description of the errno.

Error Messages

Usage Notes

1. The gsk_secure_soc_startInit() function is valid only on sockets that have an address family of AF_INET or AF_INET6 and a socket type of SOCK_STREAM.
   
   
2. The current implemention of the SSL Protocol does not allow gsk_secure_soc_startInit() to complete synchronously. Use gsk_secure_soc_init() if the synchronous behaviour is needed.
   
   
3. When doing the SSL handshake with a GSK_SESSION_TYPE value of GSK_SERVER_SESSION, GSK_SERVER_SESSION_WITH_CL_AUTH, or GSK_SERVER_SESSION_WITH_CL_AUTH_CRITICAL, the GSK_CONNECT_CIPHER_SPEC_EX value will be the first cipher found in GSK_TLSV12_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, GSK_V3_CIPHER_SPECS_EX, and/or GSK_V2_CIPHER_SPECS based upon the protocol level agreed to that was also found in the cipher list provided by the client during the SSL handshake.
   
   
4. When doing the SSL handshake with a GSK_SESSION_TYPE value of GSK_CLIENT_SESSION, the cipher specification list will be sent to the server in the client hello in the order found in the GSK_TLSV12_CIPHER_SPECS_EX, GSK_TLSV11_CIPHER_SPECS_EX, GSK_TLSV10_CIPHER_SPECS_EX, GSK_V3_CIPHER_SPECS_EX and/or GSK_V2_CIPHER_SPECS list, however the value from that list that is negotiated for GSK_CONNECT_CIPHER_SPEC_EX is determined by the server policy.
   
   
5. If gsk_secure_soc_startInit() fails, GSK_LAST_VALIDATION_ERROR may be set to provide additional information on the cause of the failure.
   
   
6. gsk_secure_soc_startInit() may result in one or more secondary external TCP connections being made if OCSP has been enabled or configured.
   
   

Related Information

• gsk_secure_soc_close()--Close a secure session
  
  
• gsk_secure_soc_init()--Negotiate a secure session
  
  
• gsk_secure_soc_misc()--Perform miscellaneous functions for a secure session
  
  
• gsk_secure_soc_open()--Get a handle for a secure session
  
  
• gsk_secure_soc_read()--Receive data on a secure session
  
  
• gsk_secure_soc_write()--Send data on a secure session
  
  
• gsk_secure_soc_startRecv--Start Asynchronous Recv Operation on a secure session
  
  
• gsk_secure_soc_startSend--Start Asynchronous Send Operation on a secure session
  
  
• QsoCancelOperation()--Cancel an I/O Operation
  
  
• QsoCreateIOCompletionPort()--Create I/O Completion Port
  
  
• QsoDestroyIOCompletionPort()--Destroy I/O Completion Port
  
  
• QsoPostIOCompletionPort()--Post Request on I/O Completion Port
  
  
• QsoWaitForIOCompletion()--Wait for I/O Completion Operation