RWSecureSocket
Module: Secure Communication Module Package: Secure Sockets
Does not inherit
- Local Index
- Header File
- Description
- Enum
- Typedef
- Public Constructors
- Destructor
- Public Operators
- Public Member Functions
Local Index
Members
Header File
#include <rw/secsock/RWSecureSocket.h>
Description
RWSecureSocket is an abstraction of a TCP socket using the SSL/TLS protocols for secure communication. It was designed to operate similarly to the non-secure RWSocket class.
Enum
enum RWSSLShutdownMode
{ RW_SSL_SHUTDOWN_NORMAL, RW_SSL_SHUTDOWN_QUIET };
Specifies whether SSL/TLS connections wait for or ignore the CloseVerify message when shutting down. See setShutdownMode().
Typedef
extern "C" typedef void(*RWInfoCallback)(SSL*, int, int);
Public Constructors
RWSecureSocket();
Sets the socket to an invalid state. You must initialize the instance with a call to connect() or bind() before it can be used.
RWSecureSocket(const RWSecureSocket& context);
Performs a shallow copy -- new memory is not allocated, only the pointer addresses are copied.
RWSecureSocket(const RWSecureSocketContext& context);
Creates an RWSecureSocket from an existing secure socket context. Throws RWSecureSocketUnderlyingAllocationError if the cryptographic library cannot allocate memory.
RWSecureSocket(const RWSecureSocketContext& context,
const RWSecureSocketSession& session);
Creates an RWSecureSocket from an existing session and secure socket context. Throws RWSecureSocketUnderlyingAllocationError if the cryptographic library cannot allocate memory.
Destructor
~RWSecureSocket();
Destructor.
Public Operators
RWSecureSocket& operator=(const RWSecureSocket& second);
Assignment operator.
bool operator==(const RWSecureSocket& s) const;
Returns true if the two sockets refer to the same underlying communications channel.
bool operator<(const RWSecureSocket& s) const;
Does nothing; declared but not defined. Causes a linker error if the call is attempted. Included to accommodate compilers that resolve all template instantiation at compile time.
Public Member Functions
RWSecureSocket accept(RWSockAddr *addr =0) const;
Accepts a connection that is waiting at this socket. A queue for incoming connections must first be created using listen(). If addr is non-null, returns the peer's address in addr. You can also get the peer's address by calling getpeername() on the returned RWSecureSocket.
If the socket is set to block (the default), accept() blocks until a connection request arrives. If the socket is set to be non-blocking, accept() returns directly. If no connections were available, the returned socket is invalid and *addr is unchanged. Use isValid() to check the returned socket.
Throws RWSecureSocketUnderlyingAllocationError if the underlying cryptographic library is unsuccessful in allocating memory.
void
bind(const RWSockAddrBase& address);
void
bind(const RWSockAddrBase& address,
const RWSecureSocketContext& context);
Assigns an address to an as-yet unnamed socket. Used primarily by servers, which need to specify the port on which they wait for connections.
bool checkPrivateKey() const;
Checks that the certificate and the private key set against the SSL connection match. Returns true if the keys match, false otherwise.
void close(); void closesocket();
Terminates this connection and removes the socket. If an SSL connection was ever established, close() blocks until the SSL connection is shut down. The underlying socket is then set to an invalid state. If this is the only file descriptor on the machine using this socket, the resources used to maintain the socket are deallocated and any unread data is discarded.
close() and closesocket() are synonyms. The function throws RWSocketError, RWSecureSocketShutdownError, and RWSecureSocketError.
void
connect(const RWSockAddrBase& addr);
void
connect(const RWSockAddrBase& addr,
const RWSecureSocketContext& context);
void
connect(const RWSockAddrBase& addr,
const RWSecureSocketSession& session);
void
connect(const RWSockAddrBase& addr,
const RWSecureSocketSession& session,
const RWSecureSocketContext& context);
Connects this socket to the remote address addr; using context if specified, and attempting to reuse session if specified. If the socket has not been initialized, connect() initializes it. Throws RWSecureSocketUnderlyingAllocationError if the cryptographic library is unsuccessful in allocating memory.
RWX509Certificate getCertificate() const;
After establishing a connection, returns the certificate presented by the application at the other end of the SSL connection. Throws RWSecureSocketNullCertificateError when the underlying function fails.
RWSecureSocketConnectionRep getConnection() const;
Returns the connection pointer.
RWSecureSocketContext getContext() const;
Returns a reference to the context used to create the secure socket connection. Throws RWSecureSocketInvalidSocketError when the socket is invalid.
RWInfoCallback getInfoCallback() const;
Returns the current information callback for the current connection.
RWX509Certificate getPeerCertificate() const;
If a connection is established, returns the certificate the peer is using. A peer certificate does not exist if the process is a server and is not performing client authentication. Throws RWSecureSocketNullCertificateError when the underlying function fails.
RWSockAddr getpeername() const;
Returns the address of the peer connected to this socket.
RWSecureSocketSession getSession() const;
Returns one of the following:
If an SSL connection is active (connect has been called), getSession(), returns the active session associated with this RWSecureSocket.
If an SSL connection is not active and this RWSecureSocket has never been connected, getSession(), returns an invalid session.
If an SSL connection is not active but this RWSecureSocket has been connected before, getSession(), returns the session used for the previous connection.
Applications should check the returned RWSecureSocketSession for validity using RWSecureSocketSession::isValid().
RWSSLShutdownMode getShutdownMode() const;
Gets the current shutdown mode for this RWSecureSocket.
SOCKET getSocket() const;
Returns the C API socket descriptor encapsulated by this RWSecureSocket.
RWSockAddr getsockname() const;
Returns the address that the socket is bound to.
void
getsockopt(int level, int option, void *optval,
RWSockLenType *optlen) const;
int
getsockopt(int option) const;
Returns the socket option setting. The single-argument version is intended for the usual case, which is the SOL_SOCKET level and an integer option.
RWSockType getsocktype() const;
Returns the type of this socket.
RWCString id(unsigned level=0) const;
Returns a string identifying the local and (if applicable) foreign addresses of this socket. Increasing level increases the amount of detail in the output. The returned string format depends on the underlying address types.
void ioctl(long cmd, void *arg) const; void ioctl(long cmd, int arg) const; int ioctl(long cmd) const; void ioctlsocket(long cmd, void *arg) const; void ioctlsocket(long cmd, int arg) const; int ioctlsocket(long cmd) const;
Gets or retrieves socket operating parameters.
The versions that return an integer are useful with commands that return ints (such as FIONREAD or SIOCATMARK).
The versions that take an integer argument are useful with commands that expect an integer argument and return nothing (such as FIONBIO).
The ioctlsocket functions are aliases for ioctl. Most Windows users prefer ioctlsocket(), and most Unix users prefer ioctl.
These functions are commonly used to set blocking or non-blocking status on a socket. To set a socket to non-blocking, use ioctl(FIONBIO,1). To set to blocking, use ioctl(FIONBIO,0).
bool
isValid() const;
Checks if the socket is ready for use. Returns true if ready, false if otherwise.void
listen(int backlog=5) const;
void
listen(const RWSockAddrBase& addr, int backlog=5);
void
listen(const RWSockAddrBase& addr,
const RWSecureSocketContext& context, int backlog=5);
Prepares a socket to accept incoming connections. The backlog parameter sets the number of incoming connection requests that the protocol software will enqueue while a connection is being processed.
The version that does not take an addr argument expects the application to use bind() to set the address on which to wait.
RWNetBuf
recv(int flags=0) const;
int
recv(char *buf, int len, int flags=0,
RWNetBuf::State* s=0) const;
Reads data from a connected socket. The flags parameter must be either 0 or MSG_PEEK; other flags do not apply to secure sockets. If the flags parameter is set to something other than 0 or MSG_PEEK, throws RWSecureSocketError.
The variant using an explicit buffer, or buf, returns the number of bytes actually received, which may be 0 for a non-blocking socket with no data waiting or for an end of file. The optional state parameter is set to RWNetBuf::eof when end of file is detected, RWNetBuf::normal otherwise. You must use this parameter to detect end of file when using an explicit buffer. You can only "return" in a return value, not a parameter.
RWNetBuf
recvAtLeast(int n) const;
int
recvAtLeast(char *buf, int len, int n,
RWNetBuf::State* s=0) const;
Guaranteed either to receive n characters or throw an exception. This call is only valid for stream sockets. Implemented as a loop calling recv() until all of the data has been received. If an error is returned from the underlying recv() call, a RWSecureSocketError is thrown. If no data is read, a RWNeTCantRecvError is thrown.
int send(const RWCString& buf) const; int send(const char *buf, int len) const;
Sends data from a connected socket, and returns the number of bytes sent. The number of bytes is 0 if the socket is non-blocking and the internal buffer for the socket is full.
void sendAtLeast(const RWCString& buf) const; int sendAtLeast(const RWCString& buf, int n) const; void sendAtLeast(const char* buf, int len) const; int sendAtLeast(const char* buf, int bufLen, int min) const;
Guaranteed to send at least n characters or the entire buffer, if your application does not specify n. This call is only valid for stream sockets. Implemented as a loop calling send() to send the data.
void setCertificate(const RWX509Certificate& cert);
Binds a certificate to the secure socket connection. A certificate loaded via this function is used to identify the owner of the secure socket connection. The certificate must be loaded before the SSL connection can successfully respond to a certificate request. Throws an RWSecureSocketUseCertificateError exception when the underlying call fails.
NOTE -- If the setCertificate() function is called before setPrivateKey(), the cryptographic library automatically compares the key and the certificate. If the key does not match the certificate, setPrivateKey() throws RWSecureSocketUsePrivateKeyError. This exception is not thrown if setPrivateKey() is called before setCertificate(), even if the key does not match the certificate. In any case, if the key does not match the certificate, checkPrivateKey() returns false.
void setCertificateVerifyMode(int mode);
Sets the certificate verify mode. Options may be combined with the bitwise-or operator. Allowable values for the mode parameter are shown inTable 1.
Table 1: SSL/TLS Certificate Verify Modes
| Value | Description |
SSL_VERIFY_NONE | Ignores results of certificate verification (Not Recommended) |
SSL_VERIFY_PEER | Verify the other end of the connection |
SSL_VERIFY_CLIENT_ONCE | Ensures that when attempting to reuse a session, a client certificate will not be re-requested if one has previously been sent to the server. |
SSL_VERIFY_FAIL_IF_NO_PEER_CERT | Ensures that the verification fails if the peer does not provide a certificate. (This option is most often used by servers requesting client verification) |
void setContext(const RWSecureSocketContext& context);
Sets the secure socket context for the socket. A socket must be associated with a context before it can be used. Throws RWSecureSocketUnderlyingAllocationError if the cryptographic library is unsuccessful in allocating memory.
void
setIdentity(const RWX509Certificate& cert,
const RWPrivateKey& pkey);
A convenience function that should be used by the side of the SSL/TLS protocol that is being authenticated. Normally this function is called by the server. If client authentication is used, this function is also called by the client to establish its own identity. Calling setIdentity() is equivalent to calling setPrivateKey(pkey), setCertificate(cert), and checkPrivateKey(). Throws RWCertificateKeyMismatchError if checkPrivateKey()returns false.
void setInfoCallback(RWInfoCallback fun);
Sets the current information callback for the current connection. For more information, see the Secure Communication Module User's Guide.
void setPrivateKey(const RWPrivateKey& pkey);
Sets the private key to use for a given secure socket connection.
NOTE -- If the setCertificate() function is called before setPrivateKey(), the cryptographic library automatically compares the key and the certificate. If the key does not match the certificate, setPrivateKey() throws RWSecureSocketUsePrivateKeyError. This exception is not thrown if setPrivateKey() is called before setCertificate(), even if the key does not match the certificate. In any case, if the key does not match the certificate, checkPrivateKey() returns false.
void setSession(const RWSecureSocketSession& session);
Sets the current session.
void setShutdownMode(RWSSLShutdownMode mode);
Sets the shutdown mode. When an SSL/TLS connection is about to be shut down and the shutdown mode is normal (the default), the side of the protocol initiating the shutdown sends a CloseVerify message to its peer and waits for the peer to respond with a CloseVerify message. See the enum RWShutdownMode.
Some SSL/TLS libraries incorrectly implement the shutdown protocol. To enable interoperability with these libraries, set the shutdown mode to quiet. This mode instructs the libraries to ignore the CloseVerify portion of the protocol.
The shutdown mode set with this function applies to all sockets and portals created with this RWSecureSocket.
NOTE -- Security issues related to this function are described in the Security Issues section of the Secure Communication Module User's Guide.
void
setsockopt(int level, int option, void *optval,
int optlen) const;
void
setsockopt(int option, int optval) const;
Sets a socket option setting. The two-argument function is intended for the usual case, which is the SOL_SOCKET level and an integer option.
void shutdown() const;
Shuts down the SSL connection and the underlying TCP socket. The socket resources are not deallocated. Use close() or closesocket() to deallocate these resources after shutting down the socket.
Throws RWSecureSocketShutdownError, RWSocketError, RWSecureSocketError.
© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.