DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | 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...
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...
OFCondition | setPrivateKeyFile (const char *fileName, DcmKeyFileFormat fileType)
| loads the private key used for authentication of this application from a file. More...
OFCondition | setCertificateFile (const char *fileName, DcmKeyFileFormat fileType, DcmTLSSecurityProfile profile)
| 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...
OFCondition | addTrustedCertificateFile (const char *fileName, DcmKeyFileFormat fileType)
| loads a certificate from a file and adds it to the pool of trusted certificates. More...
OFCondition | 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...
OFCondition | addCertificateRevocationList (const char *fileName, DcmKeyFileFormat fileType)
| loads a certificate revocation list (CRL) in X.509 format from a file and adds it to the pool of trusted certificates and CRLs. More...
OFCondition | setCRLverification (DcmTLSCRLVerification crlmode)
| set the verification mode for certificate revocation lists. More...
OFCondition | addTrustedClientCertificateFile (const char *fileName)
| loads certificates from a file and adds them to the pool of trusted client certificates. More...
OFCondition | addVerificationFlags (unsigned long flags)
| appends the given verification flags to the existing ones in this OpenSSL context (using binary or). More...
OFCondition | verifyClientCertificate (const char *fileName, DcmKeyFileFormat fileType)
| loads a certificate or certificate chain from a file and checks whether it can be verified against the current settings of the trust store. More...
OFCondition | 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...
OFCondition | addCipherSuite (const char *suite)
| adds a ciphersuite to the list of ciphersuites for TLS negotiation. More...
OFCondition | 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...
OFCondition | 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 | setClientSNI (const char *s)
| set SNI server name to be used in outgoing connections More...
void | setServerSNI (const char *s)
| set SNI server name to be expected and checked in incoming connections if the ClientHello message contains an SNI field More...
OFBool | checkServerSNI (const char *s) const
| check if the requested SNI server name s matches the SNI server name defined by a prior call to setServerSNI(). More...
const char * | getServerSNI () const
| get the SNI server name 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 | setBuiltInDHParameters ()
| loads the hard-coded set of Diffie-Hellman parameters from memory. More...
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...
DcmTransportLayer & | operator= (OFrvalue_ref(DcmTransportLayer) rhs)
| move assignment. More...
virtual | ~DcmTransportLayer ()
| destructor

## Static Public Member Functions
static OFCondition | isRootCertificate (const char *fileName, DcmKeyFileFormat fileType)
| loads a certificate file and checks whether it is a valid (e.g. More...
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 * | checkHashKeyIsTooInSecure (X509 *certificate)
| checks for the use of hash keys that are broken and too insecure to permit. More...
static const char * | checkHashKeyIsSecure (X509 *certificate)
| checks the RFC 8325 recommendations that certificates should use SHA-256 (or better) 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...
static OFCondition | convertOpenSSLError (unsigned long errorCode, OFBool logAsError)
| convert an error code as returned by the OpenSSL functions ERR_get_error(), ERR_peek_error() and ERR_peek_last_error() into an OFCondition error code. More...
static OFCondition | convertOpenSSLX509VerificationError (int errorCode, OFBool logAsError)
| convert an error code as returned by the OpenSSL function X509_STORE_CTX_get_error() into an OFCondition error code. More...

## Static Public Attributes
static int | contextStoreIndex
| global variable populated in initializeOpenSSL(). More...

## Private Member Functions
| DcmTLSTransportLayer (const DcmTLSTransportLayer &)
| private undefined copy constructor
DcmTLSTransportLayer & | operator= (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
const char * | clientSNI
| SNI server name to be requested in outgoing connections. More...
const char * | serverSNI
| SNI server name to be expected in incoming connections. More...
OFBool | certificateTypeIsDSA
| flag indicating whether a DSA certificate has been loaded. More...

## 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

  networkRole | network role to be used by the application
  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

## ◆ activateCipherSuites()

OFCondition 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
  EC_Normal if successful, an error code otherwise

## ◆ addCertificateRevocationList()

OFCondition DcmTLSTransportLayer::addCertificateRevocationList | ( | const char * | fileName,
|  | DcmKeyFileFormat | fileType
| ) |  |

loads a certificate revocation list (CRL) in X.509 format from a file and adds it to the pool of trusted certificates and CRLs.

Parameters

  fileName | path to the CRL file
  filetype | file format: X509_FILETYPE_PEM or X509_FILETYPE_ASN1

Returns
  EC_Normal if successful, an error code otherwise

## ◆ addCipherSuite()

OFCondition 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

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

Returns
  EC_Normal 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

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

## ◆ addTrustedCertificateDir()

OFCondition 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

  fileName | path to the directory containing certificate files
  fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1

Returns
  EC_Normal if successful, an error code otherwise

## ◆ addTrustedCertificateFile()

OFCondition DcmTLSTransportLayer::addTrustedCertificateFile | ( | const char * | fileName,
|  | DcmKeyFileFormat | 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
  EC_Normal if successful, an error code otherwise

## ◆ addTrustedClientCertificateFile()

OFCondition 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
  EC_Normal if successful, an error code otherwise

## ◆ addVerificationFlags()

OFCondition 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
  EC_Normal if the flags were appended to the existing ones, an error code otherwise.

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

## ◆ checkHashKeyIsSecure()

static const char* DcmTLSTransportLayer::checkHashKeyIsSecure | ( | X509 * | certificate | ) |
| static

checks the RFC 8325 recommendations that certificates should use SHA-256 (or better) hash keys.

We accept the SHA-2 and SHA-3 family with 256 or more bits.

Parameters

  certificate | X.509 certificate

Returns
  NULL if the hash key algorithm is considered secure, the name of the hash key algorithm used otherwise.

## ◆ checkHashKeyIsTooInSecure()

static const char* DcmTLSTransportLayer::checkHashKeyIsTooInSecure | ( | X509 * | certificate | ) |
| static

checks for the use of hash keys that are broken and too insecure to permit.

Currently MD2, MD4 and MD5 are on our "blacklist".

Parameters

  certificate | X.509 certificate

Returns
  NULL if the hash key algorithm is not on the blacklist, the name of the hash key algorithm used 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.

## ◆ checkServerSNI()

OFBool DcmTLSTransportLayer::checkServerSNI | ( | const char * | s | ) | const

check if the requested SNI server name s matches the SNI server name defined by a prior call to setServerSNI().

Parameters

  s | requested SNI server name

Returns
  OFTrue if server names matches, 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.

## ◆ clearTLSProfile()

void DcmTLSTransportLayer::clearTLSProfile | ( |  | ) |

clear the current list of ciphersuites.

Equivalent to calling setTLSProfile(TSP_Profile_None).

## ◆ convertOpenSSLError()

static OFCondition DcmTLSTransportLayer::convertOpenSSLError | ( | unsigned long | errorCode,
|  | OFBool | logAsError
| ) |  |
| static

convert an error code as returned by the OpenSSL functions ERR_get_error(), ERR_peek_error() and ERR_peek_last_error() into an OFCondition error code.

Parameters

  errorCode | OpenSSL error code
  logAsError | if true, write the error description to the logger with severity ERROR

Returns
  OFCondition object

## ◆ convertOpenSSLX509VerificationError()

static OFCondition DcmTLSTransportLayer::convertOpenSSLX509VerificationError | ( | int | errorCode,
|  | OFBool | logAsError
| ) |  |
| static

convert an error code as returned by the OpenSSL function X509_STORE_CTX_get_error() into an OFCondition error code.

Parameters

  errorCode | OpenSSL error code
  logAsError | if true, write the error description to the logger with severity ERROR

Returns
  OFCondition object

## ◆ 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 established 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

## ◆ getListOfCipherSuitesForOpenSSL()

void DcmTLSTransportLayer::getListOfCipherSuitesForOpenSSL | ( | OFString & | cslist | ) | 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.

## ◆ 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);
...
DcmTLSTransportLayer
factory class which creates secure TLS transport layer connections and maintains the parameters commo...
Definition: tlslayer.h:107

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

  certificate | X.509 certificate

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

## ◆ getServerSNI()

const char* DcmTLSTransportLayer::getServerSNI | ( |  | ) | const

get the SNI server name

Returns
  SNI server name. Never returns NULL.

## ◆ getTLSProfile()

DcmTLSSecurityProfile DcmTLSTransportLayer::getTLSProfile | ( |  | ) | const

return the currently selected TLS profile

Returns
  currently selected TLS profile

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

## ◆ isRootCertificate()

static OFCondition DcmTLSTransportLayer::isRootCertificate | ( | const char * | fileName,
|  | DcmKeyFileFormat | fileType
| ) |  |
| static

loads a certificate file and checks whether it is a valid (e.g.

non-expired), self-signed root certificate that can be verified against itself

Parameters

  fileName | path to the certificate file
  fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1

Returns
  EC_Normal if certificate is a root certificate, an error code otherwise

## ◆ loadCertificateFile()

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

load an X.509 certificate from file.

Parameters

  fileName | path to the certificate file
  fileType | must be 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 | ) |
| static private

look up OpenSSL certificate format constant

Parameters

  fileType | as 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

  rhs | an 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

  os | output 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

  randFile | path of the file containing random data

## ◆ setBuiltInDHParameters()

OFBool DcmTLSTransportLayer::setBuiltInDHParameters | ( |  | ) |

loads the hard-coded set of Diffie-Hellman parameters from memory.

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

Returns
  OFTrue if successful, OFFalse otherwise.

## ◆ setCertificateFile()

OFCondition DcmTLSTransportLayer::setCertificateFile | ( | const char * | fileName,
|  | DcmKeyFileFormat | fileType,
|  | DcmTLSSecurityProfile | profile
| ) |  |

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
  profile | the currently active TLS profile

Returns
  EC_Normal 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()

OFCondition 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

  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
  EC_Normal if successful, an error code otherwise

## ◆ setClientSNI()

void DcmTLSTransportLayer::setClientSNI | ( | const char * | s | ) |
| inline

set SNI server name to be used in outgoing connections

Parameters

  s | server name, NULL to disable SNI

## ◆ setCRLverification()

OFCondition DcmTLSTransportLayer::setCRLverification | ( | DcmTLSCRLVerification | crlmode | ) |

set the verification mode for certificate revocation lists.

When enabled, a CRL is expected to be present either for the leaf certificate, or for the entire certificate chain, and certificate verification will fail if no CRL is found.

Parameters

  crlmode | CRL verification mode

## ◆ setPrivateKeyFile()

OFCondition DcmTLSTransportLayer::setPrivateKeyFile | ( | const char * | fileName,
|  | DcmKeyFileFormat | 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
  EC_Normal 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.

## ◆ setServerSNI()

void DcmTLSTransportLayer::setServerSNI | ( | const char * | s | ) |
| inline

set SNI server name to be expected and checked in incoming connections if the ClientHello message contains an SNI field

Parameters

  s | server name, NULL to disable SNI

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

## ◆ setTLSProfile()

OFCondition DcmTLSTransportLayer::setTLSProfile | ( | DcmTLSSecurityProfile | profile | ) |

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

Parameters

  profile | TLS Security Profile

Returns
  EC_Normal if successful, an error code otherwise

## ◆ verifyClientCertificate()

OFCondition DcmTLSTransportLayer::verifyClientCertificate | ( | const char * | fileName,
|  | DcmKeyFileFormat | fileType
| ) |  |

loads a certificate or certificate chain from a file and checks whether it can be verified against the current settings of the trust store.

Parameters

  fileName | path to the certificate file
  fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1

Returns
  EC_Normal if verification succeeded, an error code 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.

## Member Data Documentation

## ◆ certificateTypeIsDSA

OFBool DcmTLSTransportLayer::certificateTypeIsDSA
| private

flag indicating whether a DSA certificate has been loaded.

In this case, TLS 1.3 cannot be used because it does not support DSA certificates.

## ◆ clientSNI

const char* DcmTLSTransportLayer::clientSNI
| private

SNI server name to be requested in outgoing connections.

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

## ◆ contextStoreIndex

int DcmTLSTransportLayer::contextStoreIndex
| static

global variable populated in initializeOpenSSL().

It contains an index number that is unique for the program lifetime and can be used to store application specific data in an SSL structure.

## ◆ serverSNI

const char* DcmTLSTransportLayer::serverSNI
| private

SNI server name to be expected in incoming connections.

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

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

- dcmtls/include/dcmtk/dcmtls/tlslayer.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1