Programmer's Reference

Instance Methods

close
Close the receiver (SSL socket).

Closes and releases the SSL socket by shutting down the SSL connection that the receiver has opened with a peer. It then calls SciSocket>>close on the no-longer secure socket. For detailed information, see Socket Communications Interface.

getSession
Answers an SSL session.

An SSL session is created as a result of an SSL handshake between two peers, normally a client and a server. During the handshake, the set of algorithms used to encrypt data passing over the connection, and the generation of secret keys is performed. Since these are computationally intense operations, a session is a virtual construct used to store such information for later reuse. Therefore, multiple connections can use the same session (and so use the same algorithms and secret key generator, called a master_secret) while each connection will have separate encryption keys.

isSecure
Answers whether the receiver is an SSL socket.

An SSL socket adds security protocol to a regular BSD style socket, such as those created and manager by the Socket Communications Interface. Until the completion of the SSL handshake, an SSL socket is not considered secure.

setSession: aSession
Sets the session for the current connection.

aSession
Specifies the session to use for the current connection. A session is an OSSslSession object that provides an interface to an underlying SSL session object.

Due to the large amount of overhead resulting from a full handshake between an SSL client and SSL server, the information from a previous connection between a given client and server can be used for the establishment of subsequent connections.

sslAccept
Waits for an SSL/TLS client to initiate an SSL/TLS handshake.

After a TCP/IP connection has been established between a client and server, sslAccept allows the server to wait for and accept a client request for a secure connection. The success of this call depends on an already established communication channel between the client and server and the initialization of an SSL structure (see ***) that captures the state of the connection.

If the underlying socket is blocking, then sslAccept will only return once the handshake has been finished or an error has occurred. If an error occurs, an instance of SciSslError is returned with the error information generated by the underlying OpenSSL code.

If the underlying socket is non-blocking, which is usually the case by default, then sslAccept may also return when the handshake cannot be completed. In this case, a call to sslGetError: with the return value of sslAccept will yield SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process then must repeat the call after taking appropriate action to satisfy the needs of sslAccept. If an error occurs, an instance of SciSslError is generated and returned to the caller.

sslBytesAvailableToRead
Answers the number of bytes that have been pulled out of the operating systems network buffer but still exist in the SSL buffer.

Data is received in blocks from an SSL peer. Therefore, data may be buffered inside the SSL structure and available for immediate retrieval.

sslConnect
Initiate the SSL/TLS handshake with an SSL/TLS server.

Called by an SSL client to initiate a secure connection with an SSL server. This call initiates the handshake used to negotiate the algorithms and keys used to encrypt data passed between the peers. An underlying communication channel must already be established before this call can succeed.

If the underlying socket is blocking, sslConnect will only return once the handshake has been completed or an error has occurred. If the underlying socket in non-blocking, sslConnect will also return when the handshake cannot be completed. This allows the calling process to take appropriate measures and repeat the call as needed.

sslInitialize: anSciSslSocketConfiguration
Creates a new SSL structure for a connection and sets the file descriptor as the input/output facility for the encrypted connection.

anSciSslSocketConfiguration
Specifies the configuration parameters of the new connection including the SciSslContext.

The sslInitialize method creates a new SSL structure required to hold the data for the SSL/TLS connection. The new structure inherits the settings of the underlying SciSslContext instance which specifies the connection method (SSLv2/SSLv3/TLSv1), options, verification settings and timeout settings.

Once the new structure is successfully created, and a pointer to the SSL structure is obtained, the file descriptor for the socket is set, typically the socket file descriptor of a network connection.

sslVerifyCertificate
Answers the result of peer certificate verification.

Checks the validity of the peer's X509 certificate. Although there are many ways the verification of a certificate can fail (expired, revoked, invalid, etc.), the only error code that is returned is the last error that occurred during processing. This call is only useful when used in connection with sslGetPeerCertificate.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]