SciSslSocket Protocols
Represents an ssl socket and provides a service to create, manage and use the socket.
SciSslSocket has the following methods:
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.
sslGetCurrentCipher
Answers the 'actually used' cipher of a connection established by the ssl handle as an instance of SciSslCipher.
sslGetPeerCertificate
Returns a pointer to the X509 certificate the peer presented or an SslError. If the peer did not present a certificate, nil is returned.
Due to the protocol definition, a TLS/SSL server will always send a certificate, if present. A client will only send a certificate when explicitly requested to do so by the server. If an anonymous cipher is used, no certificates are sent. This method is useful for extracting details of the certificate.
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 (i.e. TLS, TLSv1.1), 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.
sslSetVerify: verifyMode
Set the verification mode for the SSL connection.
verifyMode
Valid modes of operation are...
•SSL_VERIFY_NONE -
Server - the server will not send a client certificate request to the client, so the client will not send a certificate.
Client - if anonymous ciphers are not in use (by default disabled), the server will send a certificate which will be checked.
The result of the certificate verification process can be checked after the TLS/SSL handshake using the sslVerifyCertificate method. The handshake will be continued regardless of the verification result.
•SSL_VERIFY_PEER -
Server - the server sends a client certificate request to the client. The certificate returned (if any) is checked. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. The behavior can be controlled by or-ing the additional SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
Client - the server certificate is verified. If the verification process fails, the TLS/SSL handshake is immediately terminated with an alert message containing the reason for the verification failure. If no server certificate is sent, because an anonymous cipher is used, SSL_VERIFY_PEER is ignored.
•SSL_VERIFY_FAIL_IF_NO_PEER_CERT -
Server - if the client did not return a certificate, the TLS/SSL handshake is immediately terminated with a handshake failure alert. This flag must be used together with SSL_VERIFY_PEER.
Client - ignored
•SSL_VERIFY_CLIENT_ONCE -
Server - only request a client certificate on the initial TLS/SSL handshake. Do not ask for a client certificate again in case of a renegotiation. This flag must be used together with SSL_VERIFY_PEER.
Client - ignored
Note:
Exactly one of the mode flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be set at any time. Verification failure will lead to a termination of the TLS/SSL handshake with an alert message, if SSL_VERIFY_PEER is set.
sslSetVerifyDepth: depth
Set the maximum depth to which the certificate chain will be verified.
depth
Depth to which certificate chain will be verified.
Note:
This depth is only used if SSL_set_verify has previously been set to SSL_VERIFY_PEER
sslVerifyCertificate
Answers the result of peer certificate verification.
If verification mode is not set to SSL_VERIFY_NONE (see sslSetVerify:), sslVerifyCertificate checks the validity of the peer's X509 certificate to the specified verify depth, or 1 level if unspecified. 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.
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.