This helper class manages the list of TLS ciphersuites supported by DCMTK, translates DcmTLSSecurityProfile enums into the corresponding sets of ciphersuites, and permits translation between the official TLS ciphersuite names (as used in DCMTK) and the corresponding internal OpenSSL name. More...

Public Member Functions
	DcmTLSCiphersuiteHandler ()
	constructor. More...

virtual	~DcmTLSCiphersuiteHandler ()
	destructor

DcmTransportLayerStatus	setTLSProfile (DcmTLSSecurityProfile profile)
	replace the current list of ciphersuites by the list of ciphersuites for the given profile. More...

DcmTLSSecurityProfile	getTLSProfile () const
	return the currently selected TLS 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...

void	getListOfCipherSuitesForOpenSSL (OFString &cslist, OFBool isServer) const
	returns a string in OpenSSL syntax that contains the currently defined list of TLS ciphersuites. More...

long	getTLSOptions () const
	returns the set of flags that need to be activated in OpenSSL depending on the selected TLS profile. More...

OFBool	cipher3DESsupported () const
	checks if the 3DES ciphersuite TLS_RSA_WITH_3DES_EDE_CBC_SHA is supported by the underlying OpenSSL library (which newer versions only do if compiled with "weak ciphers" enabled). More...

OFBool	cipherNULLsupported () const
	checks if the unencrypted ciphersuite TLS_RSA_WITH_NULL_SHA is supported by the underlying OpenSSL library (which newer versions only do if compiled with "weak ciphers" enabled). More...

OFBool	isTLS13Enabled () const
	checks if TLS 1.3 is enabled (permitted) for the currently selected TLS security profile. More...

void	printSupportedCiphersuites (STD_NAMESPACE ostream &os) const
	print a list of supported ciphersuites to the given output stream More...

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

static size_t	lookupCiphersuite (const char *tlsCipherSuiteName)
	looks up the index of the given ciphersuite by name More...

static size_t	lookupCiphersuiteByOpenSSLName (const char *opensslCipherSuiteName)
	looks up the index of the given ciphersuite by OpenSSL name More...

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

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

static DcmTLSCipherProtocolVersion	getCipherSuiteProtocolVersion (size_t idx)
	returns the minimum SSL/TLS version required for the ciphersuite with the given index More...

static DcmTLSCipherKeyExchange	getCipherSuiteKeyExchange (size_t idx)
	returns the key exchange protocol used by the ciphersuite with the given index More...

static DcmTLSCipherAuthentication	getCipherSuiteAuthentication (size_t idx)
	returns the authentication algorithm used by the ciphersuite with the given index More...

static DcmTLSCipherEncryption	getCipherSuiteEncryption (size_t idx)
	returns the encryption algorithm used by the ciphersuite with the given index More...

static DcmTLSCipherMAC	getCipherSuiteMAC (size_t idx)
	returns the message authentication code (MAC) algorithm used by the ciphersuite with the given index More...

static size_t	getCipherSuiteKeySize (size_t idx)
	returns the symmetric key size used by the ciphersuite with the given index More...

static size_t	getCipherSuiteEffectiveKeySize (size_t idx)
	returns the effective symmetric key size (i.e. More...

static const char *	lookupProfileName (DcmTLSSecurityProfile profile)
	look up the name of the given security profile More...

Static Public Attributes
static const size_t	unknownCipherSuiteIndex
	constant returned by findOpenSSLCipherSuiteName() if ciphersuite name is unknown

Private Member Functions
	DcmTLSCiphersuiteHandler (const DcmTLSCiphersuiteHandler &)
	private undefined copy constructor

DcmTLSCiphersuiteHandler &	operator= (const DcmTLSCiphersuiteHandler &)
	private undefined assignment operator

void	determineSupportedCiphers ()
	determine the set of ciphersuites that are supported both by DCMTK and the OpenSSL library we are currently using

DcmTransportLayerStatus	addRequiredCipherSuite (const char *name)
	add ciphersuite by name, print error if unsupported More...

void	addOptional3DESCipherSuite ()
	add 3DES ciphersuite, print warning if unsupported

Private Attributes
OFVector< size_t >	ciphersuiteList
	current list of ciphersuites

DcmTLSSecurityProfile	currentProfile
	currently selected DICOM TLS security profile

OFBool	tls13_enabled
	indicator whether TLS 1.3 is enabled or disabled for the current profile

OFBool *	ciphersuiteSupported
	an array of booleans indicating which ciphersuites known to DCMTK are actually supported by the OpenSSL library we are using.

Detailed Description

This helper class manages the list of TLS ciphersuites supported by DCMTK, translates DcmTLSSecurityProfile enums into the corresponding sets of ciphersuites, and permits translation between the official TLS ciphersuite names (as used in DCMTK) and the corresponding internal OpenSSL name.

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

Constructor & Destructor Documentation

◆ DcmTLSCiphersuiteHandler()

DcmTLSCiphersuiteHandler::DcmTLSCiphersuiteHandler ( )

constructor.

The constructor assumes that the OpenSSL library has already been initialized. This should be ensured prior to creating any DcmTLSCiphersuiteHandler instance by calling DcmTLSTransportLayer::initializeOpenSSL(). This only needs to be done once.

Member Function Documentation

◆ addCipherSuite()

DcmTransportLayerStatus DcmTLSCiphersuiteHandler::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

suite TLS ciphersuite name, in the official TLS name form.

Returns: TCS_ok if successful, an error code otherwise

◆ addRequiredCipherSuite()

DcmTransportLayerStatus DcmTLSCiphersuiteHandler::addRequiredCipherSuite ( const char * name )

private

add ciphersuite by name, print error if unsupported

Parameters

name	ciphersuite name in RFC 2246 form

Returns: TCS_ok if successful, an error code otherwise

◆ cipher3DESsupported()

OFBool DcmTLSCiphersuiteHandler::cipher3DESsupported ( ) const

checks if the 3DES ciphersuite TLS_RSA_WITH_3DES_EDE_CBC_SHA is supported by the underlying OpenSSL library (which newer versions only do if compiled with "weak ciphers" enabled).

Returns: true if we support 3DES, false otherwise

◆ cipherNULLsupported()

OFBool DcmTLSCiphersuiteHandler::cipherNULLsupported ( ) const

checks if the unencrypted ciphersuite TLS_RSA_WITH_NULL_SHA is supported by the underlying OpenSSL library (which newer versions only do if compiled with "weak ciphers" enabled).

Returns: true if we support unencrypted TLS, false otherwise

◆ clearTLSProfile()

void DcmTLSCiphersuiteHandler::clearTLSProfile ( )

clear the current list of ciphersuites.

Equivalent to calling setTLSProfile(TSP_Profile_None).

◆ getCipherSuiteAuthentication()

static DcmTLSCipherAuthentication DcmTLSCiphersuiteHandler::getCipherSuiteAuthentication ( size_t idx )

static

returns the authentication algorithm used by the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: authentication algorithm

◆ getCipherSuiteEffectiveKeySize()

static size_t DcmTLSCiphersuiteHandler::getCipherSuiteEffectiveKeySize ( size_t idx )

static

returns the effective symmetric key size (i.e.

security level) of the ciphersuite with the given index. BCP 195 (2015) recommends that no ciphersuites with an effective key size of less than 112 bits should be used anymore with TLS.

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: effective symmetric key size, in bits

◆ getCipherSuiteEncryption()

static DcmTLSCipherEncryption DcmTLSCiphersuiteHandler::getCipherSuiteEncryption ( size_t idx )

static

returns the encryption algorithm used by the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: minimum SSL/TLS version required

◆ getCipherSuiteKeyExchange()

static DcmTLSCipherKeyExchange DcmTLSCiphersuiteHandler::getCipherSuiteKeyExchange ( size_t idx )

static

returns the key exchange protocol used by the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: key exchange protocol

◆ getCipherSuiteKeySize()

static size_t DcmTLSCiphersuiteHandler::getCipherSuiteKeySize ( size_t idx )

static

returns the symmetric key size used by the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: symmetric key size, in bits

◆ getCipherSuiteMAC()

static DcmTLSCipherMAC DcmTLSCiphersuiteHandler::getCipherSuiteMAC ( size_t idx )

static

returns the message authentication code (MAC) algorithm used by the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: message authentication code (MAC) algorithm

◆ getCipherSuiteProtocolVersion()

static DcmTLSCipherProtocolVersion DcmTLSCiphersuiteHandler::getCipherSuiteProtocolVersion ( size_t idx )

static

returns the minimum SSL/TLS version required for the ciphersuite with the given index

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: minimum SSL/TLS version required

◆ getListOfCipherSuitesForOpenSSL()

void DcmTLSCiphersuiteHandler::getListOfCipherSuitesForOpenSSL	(	OFString &	cslist,
		OFBool	isServer
	)		const

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

Parameters

cslist	The list of ciphersuites in OpenSSL syntax is written to this string.
isServer	true if the list of cipher suites is intended for a TLS server. In this case, the list of ciphersuites will be reordered from strongest to weakest, as recommended by BCP 195.

◆ getNumberOfCipherSuites()

static size_t DcmTLSCiphersuiteHandler::getNumberOfCipherSuites ( )

static

returns the number of known ciphersuites.

Returns: number of known ciphersuites

◆ getOpenSSLCipherSuiteName()

static const char* DcmTLSCiphersuiteHandler::getOpenSSLCipherSuiteName ( size_t idx )

static

returns a ciphersuite name in OpenSSL form

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: ciphersuite name

◆ getTLSCipherSuiteName()

static const char* DcmTLSCiphersuiteHandler::getTLSCipherSuiteName ( size_t idx )

static

returns a ciphersuite name in RFC 2246 (TLS) form

Parameters

idx	index, must be < getNumberOfCipherSuites()

Returns: ciphersuite name

◆ getTLSOptions()

long DcmTLSCiphersuiteHandler::getTLSOptions ( ) const

returns the set of flags that need to be activated in OpenSSL depending on the selected TLS profile.

Returns: flags for openssl

◆ getTLSProfile()

DcmTLSSecurityProfile DcmTLSCiphersuiteHandler::getTLSProfile ( ) const

inline

return the currently selected TLS profile

Returns: currently selected TLS profile

◆ isTLS13Enabled()

OFBool DcmTLSCiphersuiteHandler::isTLS13Enabled ( ) const

checks if TLS 1.3 is enabled (permitted) for the currently selected TLS security profile.

Note that this does not imply that the underlying OpenSSL library version actually supports TLS 1.3. That is checked elsewhere.

Returns: true if we support TLS 1.3, false otherwise

◆ lookupCiphersuite()

static size_t DcmTLSCiphersuiteHandler::lookupCiphersuite ( const char * tlsCipherSuiteName )

static

looks up the index of the given ciphersuite by name

Parameters

tlsCipherSuiteName ciphersuite name in RFC 2246 form

Returns: index into list of ciphersuites, DcmTLSCiphersuiteHandler::unknownCipherSuiteIndex if ciphersuite unknown

◆ lookupCiphersuiteByOpenSSLName()

static size_t DcmTLSCiphersuiteHandler::lookupCiphersuiteByOpenSSLName ( const char * opensslCipherSuiteName )

static

looks up the index of the given ciphersuite by OpenSSL name

Parameters

tlsCipherSuiteName ciphersuite name in the form used by OpenSSL

Returns: index into list of ciphersuites, DcmTLSCiphersuiteHandler::unknownCipherSuiteIndex if ciphersuite unknown

◆ lookupProfileName()

static const char* DcmTLSCiphersuiteHandler::lookupProfileName ( DcmTLSSecurityProfile profile )

static

look up the name of the given security profile

Returns: name of security profile, never NULL.

◆ printSupportedCiphersuites()

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

print a list of supported ciphersuites to the given output stream

Parameters

os	output stream

◆ setTLSProfile()

DcmTransportLayerStatus DcmTLSCiphersuiteHandler::setTLSProfile ( DcmTLSSecurityProfile profile )

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

Parameters

profile TLS Security Profile

Returns: TCS_ok if successful, an error code otherwise

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

dcmtls/include/dcmtk/dcmtls/tlsciphr.h

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ DcmTLSCiphersuiteHandler()

Member Function Documentation

◆ addCipherSuite()

◆ addRequiredCipherSuite()

◆ cipher3DESsupported()

◆ cipherNULLsupported()

◆ clearTLSProfile()

◆ getCipherSuiteAuthentication()

◆ getCipherSuiteEffectiveKeySize()

◆ getCipherSuiteEncryption()

◆ getCipherSuiteKeyExchange()

◆ getCipherSuiteKeySize()

◆ getCipherSuiteMAC()

◆ getCipherSuiteProtocolVersion()

◆ getListOfCipherSuitesForOpenSSL()

◆ getNumberOfCipherSuites()

◆ getOpenSSLCipherSuiteName()

◆ getTLSCipherSuiteName()

◆ getTLSOptions()

◆ getTLSProfile()

◆ isTLS13Enabled()

◆ lookupCiphersuite()

◆ lookupCiphersuiteByOpenSSLName()

◆ lookupProfileName()

◆ printSupportedCiphersuites()

◆ setTLSProfile()