gsk_secure_soc_startInit()--Start asynchronous operation to negotiate a
secure session
Syntax
#include <gskssl.h>
#include <qsoasync.h>
int gsk_secure_soc_startInit(gsk_handle my_session_handle,
int IOCompletionPort,
Qso_OverlappedIO_t * communicationsArea)
Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
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.
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_OS400_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_OS400_ERROR_NO_INITIALIZE]
A successful gsk_environment_init() was not previously called
with this handle.
[GSK_OS400_ERROR_NOT_TCP]
The socket descriptor type is not SOCK_STREAM or the address family is
not AF_INET or AF_INET6.
[GSK_OS400_ERROR_ALREADY_SECURE]
The socket descriptor is already in use by another secure session.
[GSK_OS400_ERROR_INVALID_POINTER]
The my_session_handle pointer is not valid.
[GSK_INTERNAL_ERROR]
An unexpected error occurred during SSL processing.
[GSK_OS400_ERROR_INVALID_OVERLAPPEDIO_T]
The Qso_OverLappedIO_t specified was not valid.
[GSK_OS400_ERROR_INVALID_IOCOMPLETIONPORT]
The I/O completion port specified was not valid.
[GSK_OS400_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.
Program or service program &1 in library &2
ended. Reason code &3.
CPFA081 E
Unable to set return value or error code.
Usage Notes
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.
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.
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.
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.
If gsk_secure_soc_startInit() fails,
GSK_LAST_VALIDATION_ERROR may be set to provide additional
information on the cause of the failure.
gsk_secure_soc_startInit() may result in one or
more secondary external TCP connections being made if OCSP has been
enabled or configured.
[GSK_ERROR_NO_RI_INDICATION]