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 (int networkRole, const char *randFile, OFBool initializeOpenSSL=OFTrue)
	constructor. More...

	DcmTLSTransportLayer (OFrvalue_ref(DcmTLSTransportLayer) rhs)
	move constructor. More...

DcmTLSTransportLayer &	operator= (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 DcmTransportConnection *	createConnection (DcmNativeSocketType openSocket, OFBool useSecureLayer)
	factory method that returns a new transport connection for the given socket. More...

DcmTransportLayerStatus	setPrivateKeyFile (const char *fileName, int fileType)
	loads the private key used for authentication of this application from a file. More...

DcmTransportLayerStatus	setCertificateFile (const char *fileName, int 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, int fileType)
	loads a certificate from a file and adds it to the pool of trusted certificates. More...

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. 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	setCipherSuites (const char *suites)
	sets the list of ciphersuites to negotiate. 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...

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 (int)
	constructor. More...

	DcmTransportLayer (OFrvalue_ref(DcmTransportLayer) rhs)
	move constructor. More...

DcmTransportLayer &	operator= (OFrvalue_ref(DcmTransportLayer) rhs)
	move assignment. More...

virtual	~DcmTransportLayer ()
	destructor

Static Public Member Functions
static unsigned long	getNumberOfCipherSuites ()
	returns the number of known ciphersuites. More...

static const char *	getTLSCipherSuiteName (unsigned long idx)
	returns a ciphersuite name in RFC 2246 (TLS) form More...

static const char *	getOpenSSLCipherSuiteName (unsigned long idx)
	returns a ciphersuite name in OpenSSL form More...

static const char *	findOpenSSLCipherSuiteName (const char *tlsCipherSuiteName)
	finds the OpenSSL ciphersuite name for a given RFC 2246 ciphersuite name. More...

static OFString	dumpX509Certificate (X509 *peerCertificate)
	gets the most important attributes of the given X.509 certificate. More...

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.

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	(	int	networkRole,
		const char *	randFile,
		OFBool	initializeOpenSSL = `OFTrue`
	)

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
initializeOpenSSL	Determines 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

rhs	an rvalue reference to another DcmTLSTransportLayer object.

Member Function Documentation

◆ 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

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

◆ addTrustedCertificateDir()

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

◆ addTrustedCertificateFile()

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

◆ addTrustedClientCertificateFile()

DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedClientCertificateFile ( const char * fileName )

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

Parameters

fileName path 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

flags the 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.

◆ 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.

◆ 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

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.

◆ dumpX509Certificate()

static OFString DcmTLSTransportLayer::dumpX509Certificate ( X509 * peerCertificate )

static

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

Parameters

peerCertificate X.509 certificate, may be NULL

Returns: a string describing the certificate

◆ findOpenSSLCipherSuiteName()

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.

◆ 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);
...

◆ getNumberOfCipherSuites()

static unsigned long DcmTLSTransportLayer::getNumberOfCipherSuites ( )

static

returns the number of known ciphersuites.

Returns: number of known ciphersuites

◆ getOpenSSLCipherSuiteName()

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

◆ getTLSCipherSuiteName()

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

◆ 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 ist 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

rhs	an rvalue reference to another DcmTLSTransportLayer object.

Returns: *this.

◆ 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

randFile path of the file containing random data

◆ setCertificateFile()

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

◆ setCertificateVerification()

void DcmTLSTransportLayer::setCertificateVerification ( DcmCertificateVerification vtype )

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

Parameters

vtype certificate verification mode

◆ setCipherSuites()

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

◆ setPrivateKeyFile()

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

◆ 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

thePasswd password 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

filename path to the DH parameter file

Returns: OFTrue if successful, OFFalse otherwise.

◆ writeRandomSeed()

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:

dcmtls/include/dcmtk/dcmtls/tlslayer.h

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DcmTLSTransportLayer() [1/3]

◆ DcmTLSTransportLayer() [2/3]

◆ DcmTLSTransportLayer() [3/3]

Member Function Documentation

◆ addPRNGseed()

◆ addTrustedCertificateDir()

◆ addTrustedCertificateFile()

◆ addTrustedClientCertificateFile()

◆ addVerificationFlags()

◆ canWriteRandomSeed()

◆ checkPrivateKeyMatchesCertificate()

◆ clear()

◆ createConnection()

◆ dumpX509Certificate()

◆ findOpenSSLCipherSuiteName()

◆ getNativeHandle()

Usage Example

◆ getNumberOfCipherSuites()

◆ getOpenSSLCipherSuiteName()

◆ getTLSCipherSuiteName()

◆ operator OFBool()

◆ operator!()

◆ operator=()

◆ seedPRNG()

◆ setCertificateFile()

◆ setCertificateVerification()

◆ setCipherSuites()

◆ setPrivateKeyFile()

◆ setPrivateKeyPasswd()

◆ setTempDHParameters()

◆ writeRandomSeed()