DCMTK
Version 3.6.4
OFFIS DICOM Toolkit
|
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...
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... | |
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... | |
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... | |
![]() | |
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 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 | |
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 | |
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.
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::DcmTLSTransportLayer | ( | T_ASC_NetworkRole | networkRole, |
const char * | randFile, | ||
OFBool | initializeOpenSSL | ||
) |
constructor.
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::DcmTLSTransportLayer | ( | OFrvalue_ref(DcmTLSTransportLayer) | rhs | ) |
move constructor.
Transfer ownership from another DcmTLSTransportLayer object to the newly constructed object (*this).
rhs | an rvalue reference to another DcmTLSTransportLayer object. |
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().
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!
suite | TLS ciphersuite name, in the official TLS name form. |
void DcmTLSTransportLayer::addPRNGseed | ( | void * | buf, |
size_t | bufSize | ||
) |
modifies the PRNG by adding random data from the given buffer to the PRNG state.
buf | pointer to buffer containing random data number of bytes in buffer |
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.
fileName | path to the directory containing certificate files |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedCertificateFile | ( | const char * | fileName, |
DcmKeyFileFormat | fileType | ||
) |
loads a certificate from a file and adds it to the pool of trusted certificates.
fileName | path to the certificate file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
DcmTransportLayerStatus DcmTLSTransportLayer::addTrustedClientCertificateFile | ( | const char * | fileName | ) |
loads certificates from a file and adds them to the pool of trusted client certificates.
fileName | path to the certificate file |
DcmTransportLayerStatus DcmTLSTransportLayer::addVerificationFlags | ( | unsigned long | flags | ) |
appends the given verification flags to the existing ones in this OpenSSL context (using binary or).
flags | the verification flags to append, e. g. X509_V_FLAG_CRL_CHECK. |
|
inline |
checks if enough entropy data is available to write back a modified random seed file.
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.
|
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).
certificate | X.509 certificate |
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.
void DcmTLSTransportLayer::clearTLSProfile | ( | ) |
clear the current list of ciphersuites.
Equivalent to calling setTLSProfile(TSP_Profile_None).
|
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.
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. |
Reimplemented from DcmTransportLayer.
|
static |
gets the most important attributes of the given X.509 certificate.
peerCertificate | X.509 certificate, may be NULL |
void DcmTLSTransportLayer::getListOfCipherSuitesForOpenSSL | ( | OFString & | cslist | ) | const |
returns a string in OpenSSL syntax that contains the currently defined list of TLS ciphersuites.
cslist | The list of ciphersuites in OpenSSL syntax is written to this string. |
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.
|
static |
returns the version name of the OpenSSL version used.
|
static |
gets the size of the public key of an RSA certificate.
certificate | X.509 certificate |
|
static |
Initialize OpenSSL Library.
This function is THREAD UNSAFE and should only be called once to initialize the OpenSSL library.
|
static |
load an X.509 certificate from file.
fileName | path to the certificate file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
|
staticprivate |
look up OpenSSL certificate format constant
fileType | as DcmKeyFileFormat enum |
DcmTLSTransportLayer::operator OFBool | ( | ) | const |
Query whether this object has been initialized successfully, i.e.
whether it owns a successfully created OpenSSL context.
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. 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.
DcmTLSTransportLayer& DcmTLSTransportLayer::operator= | ( | OFrvalue_ref(DcmTLSTransportLayer) | rhs | ) |
move assignment.
Assign ownership from another DcmTLSTransportLayer object to *this, freeing the existing object first (if any).
rhs | an rvalue reference to another DcmTLSTransportLayer object. |
void DcmTLSTransportLayer::printSupportedCiphersuites | ( | STD_NAMESPACE ostream & | os | ) | const |
print a list of supported ciphersuites to the given output stream.
os | output stream |
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.
randFile | path of the file containing random data |
DcmTransportLayerStatus DcmTLSTransportLayer::setCertificateFile | ( | const char * | fileName, |
DcmKeyFileFormat | fileType | ||
) |
loads the certificate (public key) used for authentication of this application from a file.
fileName | path to the certificate file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
void DcmTLSTransportLayer::setCertificateVerification | ( | DcmCertificateVerification | vtype | ) |
defines how peer certificates should be treated when negotiating a TLS connection.
vtype | certificate verification mode |
DcmTransportLayerStatus DcmTLSTransportLayer::setPrivateKeyFile | ( | const char * | fileName, |
DcmKeyFileFormat | fileType | ||
) |
loads the private key used for authentication of this application from a file.
fileName | path to the private key file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
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.
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.
filename | path to the DH parameter file |
DcmTransportLayerStatus DcmTLSTransportLayer::setTLSProfile | ( | DcmTLSSecurityProfile | profile | ) |
replace the current list of ciphersuites by the list of ciphersuites for the given profile.
profile | TLS Security Profile |
OFBool DcmTLSTransportLayer::writeRandomSeed | ( | const char * | randFile | ) |
writes a modified random seed to file.
randFile | path of file to write |