gsk_secure_soc_read()--Receive data on a secure session
Syntax
#include <gskssl.h> int gsk_secure_soc_read(gsk_handle my_session_handle, char *readBuffer, int readBufSize, int *amtRead);Service Program Name: QSYS/QSOSSLSR
Default Public Authority: *USE
Threadsafe: Yes
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_IBMI_ERROR_CLOSED]
-
The secure session was closed by another thread before the read completed.
- [GSK_IBMI_ERROR_INVALID_POINTER]
-
The readBuffer or amtRead pointer is not valid.
- [GSK_IBMI_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 264-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
- 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.
- 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.
- 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.
- A FIONREAD ioctl() cannot be used to determine the
amount of data available for reading by using
gsk_secure_soc_read().
- 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.
- 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.
- The partner program has issued a close() for the
socket.
- When the secure session uses a blocking socket and GSK_IBMI_READ_TIMEOUT was set, GSK_IBMI_ERROR_TIMED_OUT will be the return value if no data arrives before the timeout expires.
Error Messages
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
CPFA081 E | Unable to set return value or error code. |
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
API introduced: V5R1
Top | UNIX-Type APIs | APIs by category |