tcp::SSL Class Reference

Encapsulates an SSL connection data structure. More...

#include <tcpssl.h>

Collaboration diagram for tcp::SSL:

Public Member Functions
	SSL (DataSocket &owner, SSLContext &context)
	Constructor. More...
virtual	~SSL ()
	Destructor.
void	setOptions (bool verifypeer=false)
	Sets default options for all SSL objects created from this context. More...
bool	setCertificateAndKey (const char *certfile, const char *keyfile)
	Sets the certificate filename and key filename. More...
void	setPrivateKeyPassword (string value)
	Sets the value of the private key password.
virtual int	passwordCallback (char *buf, int size, int rwflag)
	Called when a password to decrypt a private key is required. More...
bool	setfd (int socket)
	Sets the socket file descripter for this SSL object. More...
string &	getSubjectName ()
	Returns the peer certificate subject name or an empty string if none was sent.
bool	verifyResult ()
	Return true if the peer certificate was verified or if no certificate was presented.
bool	connect ()
	Starts the SSL client handshake sequence.
bool	accept ()
	Starts the SSL server handshake sequence.
size_t	read (void *buffer, size_t size)
	Reads and decrypts SSL socket data. More...
size_t	write (const void *buffer, size_t size)
	Encrypts and writes SSL socket data. More...
void	clear ()
	Resets the SSL object for another connection. More...
void	shutdown ()
	Closes the SSL connection gracefully.
void	setHostname (const string value)
	A client/server may store the internal hostname property for certificate post validation.

Public Attributes
bool	requiresCertPostValidation { false }
	If True, the certificate will be checked for validity on the first read/write operation.

Protected Member Functions
bool	performCertPostValidation ()
	Performs a post handshake validation of the peer certificate. More...
virtual bool	validateSubjectName (const string &subjectName, const string &hostName)
	Validate the peer certificate subject name. More...

Protected Attributes
DataSocket &	owner_
	A reference to the socket
SSLMode	mode_
	Either SERVER or CLIENT
::SSL *	ssl_
	The openSSL handle for API calls.

Friends
class	SSLContext

Detailed Description

Encapsulates an SSL connection data structure.

Definition at line 109 of file tcpssl.h.

Constructor & Destructor Documentation

SSL()

tcp::SSL::SSL	(	DataSocket &	owner,
		SSLContext &	context
	)

Constructor.

Parameters

owner	[in] The tcp::Session or tcp::Client this SSL object is for
context	[in] The context object used as defaults for this SSL connection

Definition at line 396 of file tcpssl.cpp.

                                               : owner_(owner)
{
  mode_ = context.mode_;
  ssl_ = SSL_new(context.ctx_);
}

Member Function Documentation

clear()

void tcp::SSL::clear

(

)

Resets the SSL object for another connection.

This method could be used by a client reconnecting to the same server

Definition at line 632 of file tcpssl.cpp.

{
  int res = SSL_clear(ssl_);
  if ( res != 1) {
    unsigned long ssl_err = ERR_get_error();
    print_error_string(ssl_err,"SSL_clear");
  }
}

passwordCallback()

int tcp::SSL::passwordCallback ( char *  buf, int  size, int  rwflag  )

virtual

Called when a password to decrypt a private key is required.

Descendant classes may want to override this to provide a more secure means of storing the private key password. The default behavior is to return the value of keypass_.

Remarks

See the openSSL function SSL_CTX_set_default_passwd_cb for more details

This must be public because it is called from the passwordCallback() function

This password callback function only applies to private keys assigned to this SSL_CTX object, it is not 'inherited' from any SSL objects created from it.

Definition at line 460 of file tcpssl.cpp.

{
  (void)rwflag;
  if (!keypass_.empty()) {
    int lsize = max<int>(size,keypass_.length());
    strncpy(buf,keypass_.c_str(),lsize);
    return lsize;
  } else {
    return 0;
  }
}

performCertPostValidation()

bool tcp::SSL::performCertPostValidation ( )

protected

Performs a post handshake validation of the peer certificate.

The post validation is performed on the first read or write operation If the post validation fails the session is disconnected. This check is only performed if requiresCertPostValidation is true

Definition at line 533 of file tcpssl.cpp.

{
  if (!verifyResult()) {
    cerr << "Peer certificate validation failed" << endl;
    return false;
  } else {
    
    if (!getSubjectName().empty()) {
      requiresCertPostValidation = false;
      if (!validateSubjectName(subjectName_,hostname_)) {
        cerr << "Peer certificate subject name '" << subjectName_ << "' does not match host name '" << hostname_ << "'" << endl;
        return false;
      }
    }
 
  }
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

read()

size_t tcp::SSL::read	(	void *	buffer,
		size_t	size
	)

Reads and decrypts SSL socket data.

Parameters

buffer	[in] Where to place the read data
size	[in] The size of buffer

Returns

The number of bytes actually read

Remarks

Logs error messages to cerr

Definition at line 594 of file tcpssl.cpp.

{
  if (requiresCertPostValidation && !performCertPostValidation())
    owner_.disconnected();
    
  int res = SSL_read(ssl_,buffer,size);
  if (res <= 0) {
    unsigned long ssl_err = SSL_get_error(ssl_,res);
    switch (ssl_err) {
      case SSL_ERROR_NONE: return 0;
      case SSL_ERROR_WANT_READ: return 0; break; 
      case SSL_ERROR_WANT_WRITE: wantsWrite(); return read(buffer,size); break;
      default: print_error_string(ssl_err,"SSL_read"); return 0;
    }
  } else {
    return res;
  }
}

Here is the call graph for this function:

setCertificateAndKey()

bool tcp::SSL::setCertificateAndKey	(	const char *	certfile,
		const char *	keyfile
	)

Sets the certificate filename and key filename.

Sets the certificate and key file for the SSL connection To set this property for all client or server connections, see the corresponding method in the SSLContext class

Parameters

certfile	[in] The filename of a certificate chain in PEM (or CRT) format
keyfile	[in] The filename of a private key in PEM (or CRT) format

Returns

True of the certificate and key were successfully set, false otherwise. Check cerr log for details.

Remarks

If the keyfile requires a password to decrypt, passwordCallback will be called to provide that password.

Definition at line 418 of file tcpssl.cpp.

{
  long res = 1;
  unsigned long ssl_err = 0;
 
  if ((certfile && !keyfile) || (!certfile && keyfile)) {
    cerr << "Error: Both a certificate and a private key file are required" << endl;
    return false;
  }  
 
  if (certfile && keyfile) {
    res = SSL_use_certificate_file(ssl_, certfile,  SSL_FILETYPE_PEM);
    ssl_err = ERR_get_error();
    if ( res != 1) {
      print_error_string(ssl_err,"SSL_use_certificate_file");
      return false;
    }
 
    res = SSL_use_PrivateKey_file(ssl_, keyfile, SSL_FILETYPE_PEM);
    ssl_err = ERR_get_error();
    if (res != 1) {
      print_error_string(ssl_err,"SSL_use_PrivateKey_file");
      return false;
    }
 
    /* Make sure the key and certificate file match. */
    res = SSL_check_private_key(ssl_);
    ssl_err = ERR_get_error();
    if ( res != 1) {
      print_error_string(ssl_err,"SSL_CTX_check_private_key");
      return false;
    }
 
    SSL_set_default_passwd_cb(ssl_,&ssl_password_callback);
    SSL_set_default_passwd_cb_userdata(ssl_,this);
    
    return true;
  } else {
    return false;
  }
}

setfd()

bool tcp::SSL::setfd

(

int

socket

)

Sets the socket file descripter for this SSL object.

An application must set the file descriptor for the socket prior to calling accept() or connect()

Parameters

socket

[in] The linux socket handle

Definition at line 472 of file tcpssl.cpp.

{
  if (socket == 0) {
    cerr << "SSL::setfd: socket is NULL" << endl;
    return false;
  } else {
    int res = SSL_set_fd(ssl_,socket);
    if (res != 1) {
      unsigned long ssl_err = ERR_get_error();
      print_error_string(ssl_err,"SSL::set_fd");
      return false;
    } else {
      return true;
    }
  }
}

setOptions()

void tcp::SSL::setOptions

(

bool

verifypeer = false

)

Sets default options for all SSL objects created from this context.

Additional options can be set in the SSLContext object associated with this SSL object

Parameters

verifypeer

[in] If true, the server/client will validate the peer certificate

Remarks

Logs error information to cerr but does not return error information.

Definition at line 407 of file tcpssl.cpp.

{
  if (verifypeer) {
    SSL_set_verify(ssl_, SSL_VERIFY_PEER, verify_callback);
  } else {
    SSL_set_verify(ssl_, SSL_VERIFY_NONE, NULL);
  }
  
  printSSLErrors();  
}

Here is the call graph for this function:

validateSubjectName()

bool tcp::SSL::validateSubjectName ( const string &  subjectName, const string &  hostName  )

protectedvirtual

Validate the peer certificate subject name.

This function should return true if the subject name is considered valid. It is intended to verify that the hostname matches the certificate subjectname. The default implementation uses whte wildcmp function to perform a wildcard compare. Only called if checkPeerSubjectName is true.

Definition at line 528 of file tcpssl.cpp.

{
  return wildcmp(subjectName.c_str(),hostname.c_str());
}

Here is the call graph for this function:

Here is the caller graph for this function:

write()

size_t tcp::SSL::write	(	const void *	buffer,
		size_t	size
	)

Encrypts and writes SSL socket data.

Parameters

buffer	[in] Where to place the read data
size	[in] The size of buffer

Returns

The number of bytes actually read

Remarks

Logs error messages to cerr

Definition at line 613 of file tcpssl.cpp.

{
  if (requiresCertPostValidation && !performCertPostValidation())
    owner_.disconnected();
 
  int res = SSL_write(ssl_,buffer,size);
  if (res <= 0) {
    unsigned long ssl_err = SSL_get_error(ssl_,res);
    switch (ssl_err) {
      case SSL_ERROR_NONE: return 0;
      case SSL_ERROR_WANT_READ: wantsRead(); return write(buffer,size); break; 
      case SSL_ERROR_WANT_WRITE: return write(buffer,size); break;
      default: print_error_string(ssl_err,"SSL_write"); return 0; break;
    }
  } else {
    return res;
  }
}

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• include/tcpssl.h
• src/tcpssl.cpp