DcmTLSTransportLayer Class Reference

factory class which creates secure TLS transport layer connections and maintains the parameters common to all TLS transport connections in one application (e.g. More...

Inheritance diagram for DcmTLSTransportLayer:

DcmTransportLayer List of all members.

Public Member Functions

 DcmTLSTransportLayer (int networkRole, const char *randFile)
 constructor.
virtual ~DcmTLSTransportLayer ()
 destructor
virtual DcmTransportConnection * createConnection (int openSocket, OFBool useSecureLayer)
 factory method that returns a new transport connection for the given socket.
DcmTransportLayerStatus setPrivateKeyFile (const char *fileName, int fileType)
 loads the private key used for authentication of this application from a file.
DcmTransportLayerStatus setCertificateFile (const char *fileName, int fileType)
 loads the certificate (public key) used for authentication of this application from a file.
OFBool checkPrivateKeyMatchesCertificate ()
 checks if the private key and the certificate set using setPrivateKeyFile() and setCertificateFile() match, i.e.
DcmTransportLayerStatus addTrustedCertificateFile (const char *fileName, int fileType)
 loads a certificate from a file and adds it to the pool of trusted certificates.
DcmTransportLayerStatus addTrustedCertificateDir (const char *pathName, int fileType)
 loads all files as certificates from the specified directory and adds them to the pool of trusted certificates.
DcmTransportLayerStatus setCipherSuites (const char *suites)
 sets the list of ciphersuites to negotiate.
OFBool canWriteRandomSeed ()
 checks if enough entropy data is available to write back a modified random seed file.
OFBool writeRandomSeed (const char *randFile)
 writes a modified random seed to file.
void seedPRNG (const char *randFile)
 adds the contents of a file to the seed for the cryptographic pseudo-random number generator.
void addPRNGseed (void *buf, size_t bufSize)
 modifies the PRNG by adding random data from the given buffer to the PRNG state.
void setCertificateVerification (DcmCertificateVerification vtype)
 defines how peer certificates should be treated when negotiating a TLS connection.
void setPrivateKeyPasswd (const char *thePasswd)
 sets the password string to be used when loading an encrypted private key file.
void setPrivateKeyPasswdFromConsole ()
 sets the password string to be used when loading an encrypted private key file to be read from the console stdin.
OFBool setTempDHParameters (const char *filename)
 loads a set of Diffie-Hellman parameters from file.

Static Public Member Functions

static unsigned long getNumberOfCipherSuites ()
 returns the number of known ciphersuites.
static const char * getTLSCipherSuiteName (unsigned long idx)
 returns a ciphersuite name in RFC 2246 (TLS) form
static const char * getOpenSSLCipherSuiteName (unsigned long idx)
 returns a ciphersuite name in OpenSSL form
static const char * findOpenSSLCipherSuiteName (const char *tlsCipherSuiteName)
 finds the OpenSSL ciphersuite name for a given RFC 2246 ciphersuite name.
static void printX509Certificate (ostream &out, X509 *peerCertificate)
 prints the most important attributes of the given X.509 certificate to the given output stream.

Private Member Functions

 DcmTLSTransportLayer (const DcmTLSTransportLayer &)
 private undefined copy constructor
DcmTLSTransportLayer & operator= (const DcmTLSTransportLayer &)
 private undefined assignment operator

Private Attributes

SSL_CTX * transportLayerContext
 OpenSSL context data, needed only once per application.
OFBool canWriteRandseed
 true if there is enough random data to write a new random seed file
OFString privateKeyPasswd
 contains the password for the private key if set on command line

Detailed Description

factory class which creates secure TLS transport layer connections and maintains the parameters common to all TLS transport connections in one application (e.g.

the pool of trusted certificates, the key and certificate to be used for authentication and the list of ciphersuite to be used for association negotiation.

Definition at line 73 of file tlslayer.h.

Constructor & Destructor Documentation

DcmTLSTransportLayer::DcmTLSTransportLayer (  int  networkRole,
const char *  randFile
) 
 

constructor.

Parameters:
networkRole network role to be used by the application, influences the choice of the secure transport layer code.
randFile path to file used to feed the random generator

Member Function Documentation

void DcmTLSTransportLayer::addPRNGseed (  void *  buf,
size_t  bufSize
) 
 

modifies the PRNG by adding random data from the given buffer to the PRNG state.

Parameters:
buf pointer to buffer containing random data number of bytes in buffer

DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedCertificateDir (  const char *  pathName,
int  fileType
) 
 

loads all files as certificates from the specified directory and adds them to the pool of trusted certificates.

Parameters:
fileName path to the directory containing certificate files
fileType,must be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
TCS_ok if successful, an error code otherwise

DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedCertificateFile (  const char *  fileName,
int  fileType
) 
 

loads a certificate from a file and adds it to the pool of trusted certificates.

Parameters:
fileName path to the certificate file
fileType,must be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
TCS_ok if successful, an error code otherwise

OFBool DcmTLSTransportLayer::canWriteRandomSeed (   )  [inline]
 

checks if enough entropy data is available to write back a modified random seed file.

Returns:
OFTrue if random seed file can be written, OFFalse otherwise.

Definition at line 171 of file tlslayer.h.

References canWriteRandseed.

OFBool DcmTLSTransportLayer::checkPrivateKeyMatchesCertificate (   ) 
 

checks if the private key and the certificate set using setPrivateKeyFile() and setCertificateFile() match, i.e.

if they establish a private/public key pair.

Returns:
OFTrue if private key and certificate match, OFFalse otherwise.

virtual DcmTransportConnection* DcmTLSTransportLayer::createConnection (  int  openSocket,
OFBool  useSecureLayer
)  [virtual]
 

factory method that returns a new transport connection for the given socket.

Depending on the second parameter, either a transparent or a secure connection is established. If the object cannot be created (e. g. because no secure layer is available), returns NULL.

Parameters:
openSocket TCP/IP socket to be used for the transport connection. the connection must already be establised on socket level. If a non-null pointer is returned, the new connection object takes over control of the socket.
useSecureLayer if true, a secure layer is used. If false, a transparent layer is used.
Returns:
pointer to new connection object if successful, NULL otherwise.

Reimplemented from DcmTransportLayer.

static const char* DcmTLSTransportLayer::findOpenSSLCipherSuiteName (  const char *  tlsCipherSuiteName  )  [static]
 

finds the OpenSSL ciphersuite name for a given RFC 2246 ciphersuite name.

Parameters:
tlsCipherSuiteName ciphersuite name in RFC 2246 form
Returns:
ciphersuite name in OpenSSL form, NULL if unknown.

static unsigned long DcmTLSTransportLayer::getNumberOfCipherSuites (   )  [static]
 

returns the number of known ciphersuites.

Returns:
number of known ciphersuites

static const char* DcmTLSTransportLayer::getOpenSSLCipherSuiteName (  unsigned long  idx  )  [static]
 

returns a ciphersuite name in OpenSSL form

Parameters:
idx index, must be < getNumberOfCipherSuites()
Returns:
ciphersuite name

static const char* DcmTLSTransportLayer::getTLSCipherSuiteName (  unsigned long  idx  )  [static]
 

returns a ciphersuite name in RFC 2246 (TLS) form

Parameters:
idx index, must be < getNumberOfCipherSuites()
Returns:
ciphersuite name

static void DcmTLSTransportLayer::printX509Certificate (  ostream &  out,
X509 *  peerCertificate
)  [static]
 

prints the most important attributes of the given X.509 certificate to the given output stream.

Parameters:
out output stream
peerCertificate X.509 certificate, may be NULL

void DcmTLSTransportLayer::seedPRNG (  const char *  randFile  ) 
 

adds the contents of a file to the seed for the cryptographic pseudo-random number generator.

The file should contain real random entropy data gathered from keystrokes, system events, /dev/random (on Linux) or something similar. If the TLS layer object is not initialized with sufficient random data, negotiation of TLS connections may fail.

Parameters:
randFile path of the file containing random data

DcmTransportLayerStatus DcmTLSTransportLayer::setCertificateFile (  const char *  fileName,
int  fileType
) 
 

loads the certificate (public key) used for authentication of this application from a file.

Parameters:
fileName path to the certificate file
fileType,must be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
TCS_ok if successful, an error code otherwise

void DcmTLSTransportLayer::setCertificateVerification (  DcmCertificateVerification  vtype  ) 
 

defines how peer certificates should be treated when negotiating a TLS connection.

Parameters:
vtype certificate verification mode

DcmTransportLayerStatus DcmTLSTransportLayer::setCipherSuites (  const char *  suites  ) 
 

sets the list of ciphersuites to negotiate.

Parameters:
suites string containing the list of ciphersuites. The list must be in OpenSSL syntax (use findOpenSSLCipherSuiteName to convert from RFC 2246 ciphersuite names to OpenSSL names), with ciphersuites separated by ':' characters.
Returns:
TCS_ok if successful, an error code otherwise

DcmTransportLayerStatus DcmTLSTransportLayer::setPrivateKeyFile (  const char *  fileName,
int  fileType
) 
 

loads the private key used for authentication of this application from a file.

Parameters:
fileName path to the private key file
fileType,must be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
TCS_ok if successful, an error code otherwise

void DcmTLSTransportLayer::setPrivateKeyPasswd (  const char *  thePasswd  ) 
 

sets the password string to be used when loading an encrypted private key file.

Must be called prior to setPrivateKeyFile() in order to be effective.

Parameters:
thePasswd password string, may be "" or NULL in which case an empty password is assumed.

OFBool DcmTLSTransportLayer::setTempDHParameters (  const char *  filename  ) 
 

loads a set of Diffie-Hellman parameters from file.

These parameters are required for DH, DHE or DSS ciphersuites.

Parameters:
filename path to the DH parameter file
Returns:
OFTrue if successful, OFFalse otherwise.

OFBool DcmTLSTransportLayer::writeRandomSeed (  const char *  randFile  ) 
 

writes a modified random seed to file.

Parameters:
randFile path of file to write
Returns:
OFTrue if successful, OFFalse otherwise.

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

Generated on 20 Dec 2005 for OFFIS DCMTK Version 3.5.4 by Doxygen 1.4.5