gsk_secure_soc_read()--Receive data on a secure session

 #include <gskssl.h>

 int gsk_secure_soc_read(gsk_handle my_session_handle,
                         char *readBuffer,
                         int readBufSize,
                         int *amtRead);

The gsk_secure_soc_read() function is used by a program to receive data from a secure session.

Parameters

my_session_handle (Input) 

The handle, returned from gsk_secure_soc_open() and used on the gsk_secure_soc_init() API call that initialized the secure session over which data is to be read.

readBuffer (Output) 

The pointer to the user-supplied buffer in which the data is to be stored.

readBufSize (Input) 

The number of bytes to be read.

amtRead (Output) 

The number of bytes that were read as a result of this API call.

Authorities

No authorization is required.

Return Value

gsk_secure_soc_read() returns an integer. Possible values are:

[GSK_OK]

gsk_secure_soc_read() was successful.

[GSK_INVALID_HANDLE]

The handle specified was not valid.

[GSK_INVALID_STATE]

The handle is not in the correct state for this operation.

[GSK_INVALID_BUFFER_SIZE]

The readBufSize is less than 1.

[GSK_WOULD_BLOCK]

Operation would have caused the process to be suspended.

[GSK_ERROR_BAD_MESSAGE]

SSL received a badly formatted message.

[GSK_ERROR_BAD_MAC]

A bad message authentication code was received.

[GSK_OS400_ERROR_CLOSED]

The secure session was closed by another thread before the read completed.

[GSK_OS400_ERROR_INVALID_POINTER]

The readBuffer or amtRead pointer is not valid.

[GSK_OS400_ERROR_TIMED_OUT]

The value specified for the receive timeout expired before the read completed.

[GSK_ERROR_SOCKET_CLOSED]

A close() was done on the socket descriptor for this secure session.

[GSK_INTERNAL_ERROR]

An unexpected error occurred during SSL processing.

[GSK_ERROR_SEQNUM_EXHAUSTED]

A secure connection using TLSv1.1 or higher protocol has sent or received more than 2⁶⁴-1 SSL records. To prevent this error perform a gsk_secure_soc_misc(GSK_RESET_CIPHER) operation before the record limit is reached. A general guideline would be once a day for long lived secure connections.

[GSK_ERROR_IO]

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

Error Conditions

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

[ECONNRESET]

A connection with a remote socket was reset by that socket.

[EIO]

Input/output error.

[ENOTCONN]

Requested operation requires a connection.

[EUNATCH]

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

Any errno that can be returned by recv() can be returned by this API. See Sockets APIs for a description of the errno values it can return.

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

Usage Notes

1. The maximum length of data typically returned will not exceed 16 KB. This is because SSL is a record level protocol and the largest record allowed is 32 KB minus the necessary SSL record headers.
   
   
2. It is strongly suggested that you do not mix the gsk_secure_soc_read() API with any of the sockets read functions. SSL and socket reads and writes can be mixed, but they must be performed in matched sets. If a client application writes 100 bytes of data using one or more of the socket send() calls, then the server application must read exactly 100 bytes of data using one or more of the socket recv() calls. This is also true for gsk_secure_soc_read() API.
   
   
3. Since SSL is a record-oriented protocol, SSL must receive an entire record before it can be decrypted and any data returned to the application. Thus, a select() may indicate that data is available to be read, but a subsequent gsk_secure_soc_read() may hang waiting for the remainder of the SSL record to be received when using blocking I/O.
   
   
4. A FIONREAD ioctl() cannot be used to determine the amount of data available for reading by using gsk_secure_soc_read().
   
   
5. SSL will ignore the out-of-band (OOB) data indicator. OOB will not affect the SSL application. OOB will just be data to the SSL protocol.
   
6. For an SSL enabled socket, which must use a connection-oriented transport service (that is, TCP), a returned value of zero in the amtRead field indicates one of the following:
   • The partner program has issued a close() for the socket.
     
     
   • The partner program has issued a secure close for the secure session. For example, if the partner program was coded using the GSKit APIs, the partner issued gsk_secure_soc_close().
     
     
   • The partner program has issued a shutdown() to disable writing to the socket.
     
     
   • The connection is broken and the error was returned on a previously issued socket function.
     
     
   • A shutdown() to disable reading was previously done on the socket.
   
   
7. When the secure session uses a blocking socket and GSK_OS400_READ_TIMEOUT was set, GSK_OS400_ERROR_TIMED_OUT will be the return value if no data arrives before the timeout expires.

Error Messages

Related Information

• gsk_secure_soc_close()--Close a secure session
  
  
• gsk_secure_soc_init()--Negotiate a 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_write()--Send data on a secure session
  
  
• gsk_strerror()--Retrieve GSK runtime error message