DCMTK  Version 3.6.6
OFFIS DICOM Toolkit
Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
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:

Public Types

typedef SSL_CTX * native_handle_type
 a type alias for the type of the underlying OpenSSL context handle to be used in conjunction with the getNativeHandle() member function.
 

Public Member Functions

 DcmTLSTransportLayer ()
 constructor. More...
 
 DcmTLSTransportLayer (T_ASC_NetworkRole networkRole, const char *randFile, OFBool initializeOpenSSL)
 constructor. More...
 
 DcmTLSTransportLayer (OFrvalue_ref(DcmTLSTransportLayer) rhs)
 move constructor. More...
 
DcmTLSTransportLayeroperator= (OFrvalue_ref(DcmTLSTransportLayer) rhs)
 move assignment. More...
 
virtual ~DcmTLSTransportLayer ()
 destructor
 
void clear ()
 Free resources, e.g. More...
 
 operator OFBool () const
 Query whether this object has been initialized successfully, i.e. More...
 
OFBool operator! () const
 Query whether this object has not been initialized, e.g. More...
 
virtual DcmTransportConnectioncreateConnection (DcmNativeSocketType openSocket, OFBool useSecureLayer)
 factory method that returns a new transport connection for the given socket. More...
 
DcmTransportLayerStatus setPrivateKeyFile (const char *fileName, DcmKeyFileFormat fileType)
 loads the private key used for authentication of this application from a file. More...
 
DcmTransportLayerStatus setCertificateFile (const char *fileName, DcmKeyFileFormat fileType)
 loads the certificate (public key) used for authentication of this application from a file. More...
 
OFBool checkPrivateKeyMatchesCertificate ()
 checks if the private key and the certificate set using setPrivateKeyFile() and setCertificateFile() match, i.e. More...
 
DcmTransportLayerStatus addTrustedCertificateFile (const char *fileName, DcmKeyFileFormat fileType)
 loads a certificate from a file and adds it to the pool of trusted certificates. More...
 
DcmTransportLayerStatus addTrustedCertificateDir (const char *pathName, DcmKeyFileFormat fileType)
 loads all files as certificates from the specified directory and adds them to the pool of trusted certificates. More...
 
DcmTransportLayerStatus addTrustedClientCertificateFile (const char *fileName)
 loads certificates from a file and adds them to the pool of trusted client certificates. More...
 
DcmTransportLayerStatus addVerificationFlags (unsigned long flags)
 appends the given verification flags to the existing ones in this OpenSSL context (using binary or). More...
 
DcmTransportLayerStatus setTLSProfile (DcmTLSSecurityProfile profile)
 replace the current list of ciphersuites by the list of ciphersuites for the given profile. More...
 
void clearTLSProfile ()
 clear the current list of ciphersuites. More...
 
DcmTransportLayerStatus addCipherSuite (const char *suite)
 adds a ciphersuite to the list of ciphersuites for TLS negotiation. More...
 
DcmTransportLayerStatus activateCipherSuites ()
 activate the current list of ciphersuites by transferring to the OpenSSL layer This method needs to be called once after the list of ciphersuites has been defined used setTLSProfile() and addCipherSuite(). More...
 
DcmTransportLayerStatus setCipherSuites (const char *suites)
 sets the list of ciphersuites to negotiate, in OpenSSL syntax. More...
 
OFBool canWriteRandomSeed ()
 checks if enough entropy data is available to write back a modified random seed file. More...
 
OFBool writeRandomSeed (const char *randFile)
 writes a modified random seed to file. More...
 
void seedPRNG (const char *randFile)
 adds the contents of a file to the seed for the cryptographic pseudo-random number generator. More...
 
void addPRNGseed (void *buf, size_t bufSize)
 modifies the PRNG by adding random data from the given buffer to the PRNG state. More...
 
void setCertificateVerification (DcmCertificateVerification vtype)
 defines how peer certificates should be treated when negotiating a TLS connection. More...
 
void setPrivateKeyPasswd (const char *thePasswd)
 sets the password string to be used when loading an encrypted private key file. More...
 
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. More...
 
void printSupportedCiphersuites (STD_NAMESPACE ostream &os) const
 print a list of supported ciphersuites to the given output stream. More...
 
void getListOfCipherSuitesForOpenSSL (OFString &cslist) const
 returns a string in OpenSSL syntax that contains the currently defined list of TLS ciphersuites. More...
 
native_handle_type getNativeHandle ()
 provides access to the underlying OpenSSL context handle for implementing custom functionality not accessible by the existing member functions of DcmTLSTransportLayer. More...
 
- Public Member Functions inherited from DcmTransportLayer
 DcmTransportLayer ()
 constructor.
 
 DcmTransportLayer (OFrvalue_ref(DcmTransportLayer) rhs)
 move constructor. More...
 
DcmTransportLayeroperator= (OFrvalue_ref(DcmTransportLayer) rhs)
 move assignment. More...
 
virtual ~DcmTransportLayer ()
 destructor
 

Static Public Member Functions

static void initializeOpenSSL ()
 Initialize OpenSSL Library. More...
 
static OFString dumpX509Certificate (X509 *peerCertificate)
 gets the most important attributes of the given X.509 certificate. More...
 
static int getRSAKeySize (X509 *certificate)
 gets the size of the public key of an RSA certificate. More...
 
static const char * checkRSAHashKeyIsSHA2 (X509 *certificate)
 checks the BCP 195 recommendations that RSA certificates should use SHA-256 hash keys. More...
 
static const char * getOpenSSLVersionName ()
 returns the version name of the OpenSSL version used. More...
 
static X509 * loadCertificateFile (const char *fileName, DcmKeyFileFormat fileType)
 load an X.509 certificate from file. More...
 

Private Member Functions

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

Static Private Member Functions

static int lookupOpenSSLCertificateFormat (DcmKeyFileFormat fileType)
 look up OpenSSL certificate format constant More...
 

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
 
DcmTLSCiphersuiteHandler ciphersuites
 ciphersuite handler
 
T_ASC_NetworkRole role
 network role for this TLS layer
 

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.

Remarks
this class is only available if DCMTK is compiled with OpenSSL support enabled.

Constructor & Destructor Documentation

◆ DcmTLSTransportLayer() [1/3]

DcmTLSTransportLayer::DcmTLSTransportLayer ( )

constructor.

Constructs a DcmTLSTransportLayer object without initializing it, e.g. as a placeholder that may or may not be used later depending on user input.

◆ DcmTLSTransportLayer() [2/3]

DcmTLSTransportLayer::DcmTLSTransportLayer ( T_ASC_NetworkRole  networkRole,
const char *  randFile,
OFBool  initializeOpenSSL 
)

constructor.

Parameters
networkRolenetwork role to be used by the application
randFilepath to file used to feed the random generator
initializeOpenSSLDetermines if OpenSSL library should be initialized. Some setups (e.g. multi-threaded environments) may be interested in using more than one TLS transport layer at a time and thus must make sure the library is only initialized once.

◆ DcmTLSTransportLayer() [3/3]

DcmTLSTransportLayer::DcmTLSTransportLayer ( OFrvalue_ref(DcmTLSTransportLayer rhs)

move constructor.

Transfer ownership from another DcmTLSTransportLayer object to the newly constructed object (*this).

Parameters
rhsan rvalue reference to another DcmTLSTransportLayer object.

Member Function Documentation

◆ activateCipherSuites()

DcmTransportLayerStatus DcmTLSTransportLayer::activateCipherSuites ( )

activate the current list of ciphersuites by transferring to the OpenSSL layer This method needs to be called once after the list of ciphersuites has been defined used setTLSProfile() and addCipherSuite().

Returns
TCS_ok if successful, an error code otherwise

◆ addCipherSuite()

DcmTransportLayerStatus DcmTLSTransportLayer::addCipherSuite ( const char *  suite)

adds a ciphersuite to the list of ciphersuites for TLS negotiation.

It is the responsibility of the user to ensure that the added ciphersuite does not break the rules of the selected profile. Use with care!

Parameters
suiteTLS ciphersuite name, in the official TLS name form.
Returns
TCS_ok if successful, an error code otherwise

◆ addPRNGseed()

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

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

Parameters
bufpointer to buffer containing random data @bufSize number of bytes in buffer

◆ addTrustedCertificateDir()

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

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

Parameters
fileNamepath to the directory containing certificate files
fileType,mustbe SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns
TCS_ok if successful, an error code otherwise

◆ addTrustedCertificateFile()

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

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

Parameters
fileNamepath to the certificate file
fileType,mustbe SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns
TCS_ok if successful, an error code otherwise

◆ addTrustedClientCertificateFile()

DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedClientCertificateFile ( const char *  fileName)

loads certificates from a file and adds them to the pool of trusted client certificates.

Parameters
fileNamepath to the certificate file
Returns
TCS_ok if successful, an error code otherwise

◆ addVerificationFlags()

DcmTransportLayerStatus DcmTLSTransportLayer::addVerificationFlags ( unsigned long  flags)

appends the given verification flags to the existing ones in this OpenSSL context (using binary or).

Warning
Documentation for the underlying OpenSSL functions is not available, therefore, these semantics were guessed based on looking at the OpenSSL source code!
Parameters
flagsthe verification flags to append, e. g. X509_V_FLAG_CRL_CHECK.
Returns
TCS_ok if the flags were appended to the existing ones, TCS_unspecifiedError if OpenSSL returns an (unspecified, since the documentation is missing) error.

◆ canWriteRandomSeed()

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.

◆ checkPrivateKeyMatchesCertificate()

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.

◆ checkRSAHashKeyIsSHA2()

static const char* DcmTLSTransportLayer::checkRSAHashKeyIsSHA2 ( X509 *  certificate)
static

checks the BCP 195 recommendations that RSA certificates should use SHA-256 hash keys.

We also accept better SHA-2 hash keys (SHA-384 and SHA-512).

Parameters
certificateX.509 certificate
Returns
NULL if everything is OK (i.e. the certificate is not RSA, or it is RSA and uses SHA-256 or better), the name of the hash key algorithm used otherwise.

◆ clear()

void DcmTLSTransportLayer::clear ( )

Free resources, e.g.

the OpenSSL context used by this object and reset all members to the default values. Will do nothing if this object has not been initialized, e.g. by using the default constructor.

◆ clearTLSProfile()

void DcmTLSTransportLayer::clearTLSProfile ( )

clear the current list of ciphersuites.

Equivalent to calling setTLSProfile(TSP_Profile_None).

◆ createConnection()

virtual DcmTransportConnection* DcmTLSTransportLayer::createConnection ( DcmNativeSocketType  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
openSocketTCP/IP socket to be used for the transport connection. the connection must already be established on socket level. If a non-null pointer is returned, the new connection object takes over control of the socket.
useSecureLayerif 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.

◆ dumpX509Certificate()

static OFString DcmTLSTransportLayer::dumpX509Certificate ( X509 *  peerCertificate)
static

gets the most important attributes of the given X.509 certificate.

Parameters
peerCertificateX.509 certificate, may be NULL
Returns
a string describing the certificate

◆ getListOfCipherSuitesForOpenSSL()

void DcmTLSTransportLayer::getListOfCipherSuitesForOpenSSL ( OFString cslist) const

returns a string in OpenSSL syntax that contains the currently defined list of TLS ciphersuites.

Parameters
cslistThe list of ciphersuites in OpenSSL syntax is written to this string.

◆ getNativeHandle()

native_handle_type DcmTLSTransportLayer::getNativeHandle ( )

provides access to the underlying OpenSSL context handle for implementing custom functionality not accessible by the existing member functions of DcmTLSTransportLayer.

Returns
the underlying OpenSSL context handle.

Usage Example

DcmTLSTransportLayer tLayer(DICOM_APPLICATION_REQUESTOR, "random.dat");
...
DcmTLSTransportLayer::native_handle_type native = tlayer.getNativeHandle();
X509_VERIFY_PARAM* param = SSL_CTX_get0_param(native);
// Enable automatic hostname checks
X509_VERIFY_PARAM_set_hostflags(param, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
X509_VERIFY_PARAM_set1_host(param, "www.example.com", 0);
// Configure a non-zero callback if desired
SSL_CTX_set_verify(native, SSL_VERIFY_PEER, 0);
...

◆ getOpenSSLVersionName()

static const char* DcmTLSTransportLayer::getOpenSSLVersionName ( )
static

returns the version name of the OpenSSL version used.

Returns
OpenSSL version name, never NULL.

◆ getRSAKeySize()

static int DcmTLSTransportLayer::getRSAKeySize ( X509 *  certificate)
static

gets the size of the public key of an RSA certificate.

Parameters
certificateX.509 certificate
Returns
public key size (in bits) if RSA certificate, 0 otherwise.

◆ initializeOpenSSL()

static void DcmTLSTransportLayer::initializeOpenSSL ( )
static

Initialize OpenSSL Library.

This function is THREAD UNSAFE and should only be called once to initialize the OpenSSL library.

◆ loadCertificateFile()

static X509* DcmTLSTransportLayer::loadCertificateFile ( const char *  fileName,
DcmKeyFileFormat  fileType 
)
static

load an X.509 certificate from file.

Parameters
fileNamepath to the certificate file
fileType,mustbe SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns
pointer to X509 object if successful, NULL otherwise. The X509 object must be freed by the caller.

◆ lookupOpenSSLCertificateFormat()

static int DcmTLSTransportLayer::lookupOpenSSLCertificateFormat ( DcmKeyFileFormat  fileType)
staticprivate

look up OpenSSL certificate format constant

Parameters
fileTypeas DcmKeyFileFormat enum
Returns
fileType as OpenSSL integer constant

◆ operator OFBool()

DcmTLSTransportLayer::operator OFBool ( ) const

Query whether this object has been initialized successfully, i.e.

whether it owns a successfully created OpenSSL context.

Returns
OFTrue if *this owns refers to a valid OpenSSL context, OFFalse otherwise.
Note
If C++11 support is available, the conversion operator is marked as explicit, which prevents *this to be interpreted as a boolean value in an inappropriate context. You should use this operator with caution when C++11 support is unavailable, as *this might be converted to a boolean value automatically where it shouldn't.

◆ operator!()

OFBool DcmTLSTransportLayer::operator! ( ) const

Query whether this object has not been initialized, e.g.

has been constructed using the default constructor or the initialization failed.

Returns
OFTrue if *this is not initialized, OFFalse otherwise.

◆ operator=()

DcmTLSTransportLayer& DcmTLSTransportLayer::operator= ( OFrvalue_ref(DcmTLSTransportLayer rhs)

move assignment.

Assign ownership from another DcmTLSTransportLayer object to *this, freeing the existing object first (if any).

Parameters
rhsan rvalue reference to another DcmTLSTransportLayer object.
Returns
*this.

◆ printSupportedCiphersuites()

void DcmTLSTransportLayer::printSupportedCiphersuites ( STD_NAMESPACE ostream &  os) const

print a list of supported ciphersuites to the given output stream.

Parameters
osoutput stream

◆ seedPRNG()

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
randFilepath of the file containing random data

◆ setCertificateFile()

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

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

Parameters
fileNamepath to the certificate file
fileType,mustbe SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns
TCS_ok if successful, an error code otherwise

◆ setCertificateVerification()

void DcmTLSTransportLayer::setCertificateVerification ( DcmCertificateVerification  vtype)

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

Parameters
vtypecertificate verification mode

◆ setCipherSuites()

DcmTransportLayerStatus DcmTLSTransportLayer::setCipherSuites ( const char *  suites)

sets the list of ciphersuites to negotiate, in OpenSSL syntax.

Note
This method is deprecated because it breaks the encapsulation of the underlying TLS library (i.e. the parameter string is OpenSSL specific) and because this method can be used to violate the constraints of the TLS profiles, which other otherwise enforced by this class. The newer methods setTLSProfile() and addCipherSuite(), introduced with DCMTK 3.6.4, offer a cleaner interface that should be preferred.
Parameters
suitesstring 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

◆ setPrivateKeyFile()

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

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

Parameters
fileNamepath to the private key file
fileType,mustbe SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns
TCS_ok if successful, an error code otherwise

◆ setPrivateKeyPasswd()

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
thePasswdpassword string, may be "" or NULL in which case an empty password is assumed.

◆ setTempDHParameters()

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
filenamepath to the DH parameter file
Returns
OFTrue if successful, OFFalse otherwise.

◆ setTLSProfile()

DcmTransportLayerStatus DcmTLSTransportLayer::setTLSProfile ( DcmTLSSecurityProfile  profile)

replace the current list of ciphersuites by the list of ciphersuites for the given profile.

Parameters
profileTLS Security Profile
Returns
TCS_ok if successful, an error code otherwise

◆ writeRandomSeed()

OFBool DcmTLSTransportLayer::writeRandomSeed ( const char *  randFile)

writes a modified random seed to file.

Parameters
randFilepath of file to write
Returns
OFTrue if successful, OFFalse otherwise.

The documentation for this class was generated from the following file:
DcmTLSTransportLayer
factory class which creates secure TLS transport layer connections and maintains the parameters commo...
Definition: tlslayer.h:107


Generated on Thu Jan 14 2021 for DCMTK Version 3.6.6 by Doxygen 1.8.18