DCMTK
Version 3.6.7
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... | |
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) |
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... | |
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 | 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... | |
![]() | |
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 * | 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... | |
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... | |
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. |
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().
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.
fileName | path to the CRL file |
filetype | file format: X509_FILETYPE_PEM or X509_FILETYPE_ASN1 |
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!
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 |
bufSize | number of bytes in buffer |
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.
fileName | path to the directory containing certificate files |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
OFCondition 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 |
OFCondition 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 |
OFCondition 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).
|
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.
errorCode | OpenSSL error code |
logAsError | if true, write the error description to the logger with severity ERROR |
|
static |
convert an error code as returned by the OpenSSL function X509_STORE_CTX_get_error() into an OFCondition error code.
errorCode | OpenSSL error code |
logAsError | if true, write the error description to the logger with severity ERROR |
|
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 |
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
fileName | path to the certificate file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
|
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 |
OFBool DcmTLSTransportLayer::setBuiltInDHParameters | ( | ) |
loads the hard-coded set of Diffie-Hellman parameters from memory.
These parameters are required for DH, DHE or DSS ciphersuites.
OFCondition 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 |
OFCondition DcmTLSTransportLayer::setCipherSuites | ( | const char * | suites | ) |
sets the list of ciphersuites to negotiate, in OpenSSL syntax.
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. |
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.
crlmode | CRL verification mode |
OFCondition 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 |
OFCondition DcmTLSTransportLayer::setTLSProfile | ( | DcmTLSSecurityProfile | profile | ) |
replace the current list of ciphersuites by the list of ciphersuites for the given profile.
profile | TLS Security Profile |
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.
fileName | path to the certificate file |
fileType,must | be SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 |
OFBool DcmTLSTransportLayer::writeRandomSeed | ( | const char * | randFile | ) |
writes a modified random seed to file.
randFile | path of file to write |