Base class for implementing DICOM TLS-enabled Service Class User functionality. More...

Inheritance diagram for DcmTLSSCU:

Public Member Functions
	DcmTLSSCU ()
	Constructor, just initializes internal class members.

	DcmTLSSCU (const OFString &peerHost, const OFString &peerAETitle, const Uint16 portNum)
	Initialize SCU with connection peer information. More...

virtual	~DcmTLSSCU ()
	Virtual destructor.

virtual OFCondition	initNetwork ()
	Initialize network, i.e. prepare for association negotiation. More...

virtual OFCondition	negotiateAssociation ()
	Negotiates association by using presentation contexts and parameters as defined by earlier function calls. More...

virtual void	closeAssociation (const DcmCloseAssociationType closeType)
	Closes the association of this SCU. More...

virtual void	addTrustedCertFile (const OFString &str)
	Add file with trusted certificate (used if authentication is enabled) More...

virtual void	addTrustedCertDir (const OFString &certDir)
	Add directory to list of directories containing trusted certificates (used if authentication is enabled) More...

virtual void	enableAuthentication (const OFString &privateKey, const OFString &certFile, const char *passphrase=NULL, const DcmKeyFileFormat privKeyFormat=DCF_Filetype_PEM, const DcmKeyFileFormat certFormat=DCF_Filetype_PEM)
	Turn on authentication for TLS. More...

virtual void	disableAuthentication ()
	Disables authentication. More...

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

virtual DcmTransportLayerStatus	addCipherSuite (const OFString &suite)
	adds a ciphersuite to the list of ciphersuites for TLS negotiation. More...

virtual void	setReadSeedFile (const OFString &seedFile)
	Set file to be used as random seed for initializing the Pseudo Random Number Generator (PRNG) More...

virtual void	setWriteSeedFile (const OFString &seedFile)
	Set file to be use to store the updated random seed to store the updated random seed from the Pseudo Random Number Generator (PRNG). More...

virtual void	setPeerCertVerification (const DcmCertificateVerification cert)
	Set whether peer's certificate must be there, only is checked if there or is ignored. More...

virtual void	setDHParam (const OFString &dhParam)
	Set Diffie-Hellman parameters from file. More...

virtual OFBool	getAuthenticationParams (OFString &privKeyFile, OFString &certFile, const char *&passphrase, int &privKeyFormat, int &certFormat) const
	Returns OFTrue if authentication is enabled. More...

virtual void	getTrustedCertFiles (OFList< OFString > &files) const
	Get files considered for trusted certificates. More...

virtual void	getTrustedCertDirs (OFList< OFString > &trustedDirs) const
	Get directories containing considered to contain trusted certificates. More...

virtual OFString	getReadSeedFile () const
	Get random seed file used for initializing Pseudo Random Number Generator (PRNG) More...

virtual OFString	getWriteSeedFile () const
	Get random seed file the PRNG should use to store back updated random seed information. More...

Public Member Functions inherited from DcmSCU
	DcmSCU ()
	Constructor, just initializes internal class members.

virtual	~DcmSCU ()
	Virtual destructor.

OFCondition	addPresentationContext (const OFString &abstractSyntax, const OFList< OFString > &xferSyntaxes, const T_ASC_SC_ROLE role=ASC_SC_ROLE_DEFAULT)
	Add presentation context to be used for association negotiation. More...

T_ASC_PresentationContextID	findPresentationContextID (const OFString &abstractSyntax, const OFString &transferSyntax, const T_ASC_SC_ROLE requestorRole=ASC_SC_ROLE_DEFAULT)
	After negotiation association, this call returns the first usable presentation context given the desired abstract syntax and transfer syntax. More...

T_ASC_PresentationContextID	findAnyPresentationContextID (const OFString &abstractSyntax, const OFString &transferSyntax)
	After a successful association negotiation, this function is called to return the presentation context ID that best matches the desired abstract syntax and transfer syntax (TS). More...

virtual OFCondition	sendECHORequest (const T_ASC_PresentationContextID presID)
	This function sends a C-ECHO command via network to another DICOM application. More...

virtual OFCondition	sendSTORERequest (const T_ASC_PresentationContextID presID, const OFFilename &dicomFile, DcmDataset *dataset, Uint16 &rspStatusCode, const OFString &moveOriginatorAETitle="", const Uint16 moveOriginatorMsgID=0)
	This function sends a C-STORE request on the currently opened association and receives the corresponding response then. More...

virtual OFCondition	sendMOVERequest (const T_ASC_PresentationContextID presID, const OFString &moveDestinationAETitle, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Sends a C-MOVE Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleMOVEResponse (const T_ASC_PresentationContextID presID, RetrieveResponse *response, OFBool &waitForNextResponse)
	This is the standard handler for C-MOVE message responses: It just adds up all responses it receives and prints a DEBUG message. More...

virtual OFCondition	sendCGETRequest (const T_ASC_PresentationContextID presID, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Sends a C-GET Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleCGETSession (const T_ASC_PresentationContextID presID, DcmDataset dataset, OFList< RetrieveResponse > *responses)
	Does the logic for switching between C-GET Response and C-STORE Requests. More...

virtual OFCondition	handleCGETResponse (const T_ASC_PresentationContextID presID, RetrieveResponse *response, OFBool &continueCGETSession)
	Function handling a single C-GET Response. More...

virtual OFCondition	handleSTORERequest (const T_ASC_PresentationContextID presID, DcmDataset *incomingObject, OFBool &continueCGETSession, Uint16 &cStoreReturnStatus)
	Function handling a single C-STORE Request. More...

virtual OFCondition	handleSTORERequestFile (T_ASC_PresentationContextID presID, const OFString &filename, T_DIMSE_C_StoreRQ request)
	Function handling a single C-STORE Request. More...

virtual OFCondition	sendFINDRequest (const T_ASC_PresentationContextID presID, DcmDataset queryKeys, OFList< QRResponse > *responses)
	Sends a C-FIND Request on given presentation context and receives list of responses. More...

virtual OFCondition	handleFINDResponse (const T_ASC_PresentationContextID presID, QRResponse *response, OFBool &waitForNextResponse)
	This is the standard handler for C-FIND message responses: It just adds up all responses it receives and prints a DEBUG message. More...

virtual OFCondition	sendCANCELRequest (const T_ASC_PresentationContextID presID)
	Send C-CANCEL and, therefore, ends the C-FIND -GET or -MOVE session, i.e. no further responses will be handled. More...

virtual OFCondition	sendACTIONRequest (const T_ASC_PresentationContextID presID, const OFString &sopInstanceUID, const Uint16 actionTypeID, DcmDataset *reqDataset, Uint16 &rspStatusCode)
	This function sends a N-ACTION request on the currently opened association and receives the corresponding response then. More...

virtual OFCondition	sendEVENTREPORTRequest (const T_ASC_PresentationContextID presID, const OFString &sopInstanceUID, const Uint16 eventTypeID, DcmDataset *reqDataset, Uint16 &rspStatusCode)
	This function sends N-EVENT-REPORT request and receives the corresponding response. More...

virtual OFCondition	handleEVENTREPORTRequest (DcmDataset *&reqDataset, Uint16 &eventTypeID, const int timeout=0)
	Receives N-EVENT-REPORT request on the currently opened association and sends a corresponding response. More...

virtual OFCondition	handleSessionResponseDefault (const Uint16 dimseStatus, const OFString &message, OFBool &waitForNextResponse)
	Function handling a single C-GET, C-FIND or C-MOVE Response, used by handleCGETResponse(), handleFINDResponse() and handleMOVEResponse(). More...

virtual OFCondition	releaseAssociation ()
	Releases the current association by sending an A-RELEASE request to the SCP. More...

virtual OFCondition	abortAssociation ()
	Aborts the current association by sending an A-ABORT request to the SCP. More...

void	setMaxReceivePDULength (const Uint32 maxRecPDU)
	Set maximum PDU length (to be received by SCU) More...

void	setDIMSEBlockingMode (const T_DIMSE_BlockingMode blockingMode)
	Set whether to send in DIMSE blocking or non-blocking mode. More...

void	setAETitle (const OFString &myAETtitle)
	Set SCU's AE title to be used in association negotiation. More...

void	setPeerHostName (const OFString &peerHostName)
	Set SCP's host (host name or IP address) to talk to in association negotiation. More...

void	setPeerAETitle (const OFString &peerAETitle)
	Set SCP's AE title to talk to in association negotiation. More...

void	setPeerPort (const Uint16 peerPort)
	Set SCP's port number to connect to for association negotiation. More...

void	setDIMSETimeout (const Uint32 dimseTimeout)
	Set timeout for receiving DIMSE messages. More...

void	setACSETimeout (const Uint32 acseTimeout)
	Set timeout for receiving ACSE messages. More...

void	setConnectionTimeout (const Sint32 connectionTimeout)
	Set global timeout for connecting to the SCP. More...

void	setAssocConfigFileAndProfile (const OFString &filename, const OFString &profile)
	Set an association configuration file and profile to be used. More...

void	setStorageDir (const OFString &storeDir)
	Set the directory that should be used by the standard C-GET handler to store objects that come in with the corresponding C-STORE requests. More...

void	setStorageMode (const DcmStorageMode storageMode)
	Set the storage mode to be used. More...

void	setVerbosePCMode (const OFBool mode)
	Set whether to show presentation contexts in verbose or debug mode. More...

void	setDatasetConversionMode (const OFBool mode)
	Set the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission. More...

void	setProgressNotificationMode (const OFBool mode)
	Set the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively. More...

OFBool	isConnected () const
	Get current connection status. More...

Uint32	getMaxReceivePDULength () const
	Returns maximum PDU length configured to be received by SCU. More...

T_DIMSE_BlockingMode	getDIMSEBlockingMode () const
	Returns whether DIMSE messaging is configured to be blocking or unblocking. More...

const OFString &	getAETitle () const
	Returns the SCU's own configured AE title. More...

const OFString &	getPeerHostName () const
	Returns the SCP's (peer's) host configured. More...

const OFString &	getPeerAETitle () const
	Returns the SCP's (peer's) AE title configured. More...

Uint16	getPeerPort () const
	Returns the SCP's (peer's) TCP/IP port configured. More...

Uint32	getDIMSETimeout () const
	Returns DIMSE timeout in seconds for receiving data. More...

Uint32	getACSETimeout () const
	Returns ACSE timeout in seconds used by timer for message timeouts during association negotiation. More...

Sint32	getConnectionTimeout () const
	Returns the timeout configured defining how long SCU will wait for the SCP when requesting an association. More...

OFString	getStorageDir () const
	Returns the storage directory used for storing objects received with C-STORE requests in the context of C-GET sessions. More...

DcmStorageMode	getStorageMode () const
	Returns the storage mode enabled. More...

OFBool	getVerbosePCMode () const
	Returns the verbose presentation context mode configured specifying whether details on the presentation contexts (negotiated during association setup) should be shown in verbose or debug mode. More...

OFBool	getDatasetConversionMode () const
	Returns the mode that specifies whether the transfer syntax of the dataset can be changed for network transmission. More...

OFBool	getProgressNotificationMode () const
	Returns the mode that specifies whether the progress of sending and receiving DIMSE messages is notified by calling notifySENDProgress() and notifyRECEIVEProgress(), respectively. More...

OFBool	getTLSEnabled () const
	Returns whether SCU is configured to create a TLS connection with the SCP. More...

void	freeNetwork ()
	Deletes internal networking structures from memory.

Private Member Functions
	DcmTLSSCU (const DcmTLSSCU &src)
	Private undefined copy-constructor. More...

DcmTLSSCU &	operator= (const DcmTLSSCU &src)
	Private undefined operator=. More...

Private Attributes
DcmTLSTransportLayer *	m_tLayer
	The TLS layer responsible for all encryption/authentication stuff.

OFBool	m_doAuthenticate
	If enabled, authentication of client/server is enabled.

OFList< OFString >	m_trustedCertDirs
	A list of directories containing trusted certificates (if authentication is enabled)

OFList< OFString >	m_trustedCertFiles
	A list of files containing trusted certificates (if authentication is enabled)

OFString	m_privateKeyFile
	The file containing the private key (if authentication is enabled)

DcmKeyFileFormat	m_privateKeyFileFormat
	private key file format

OFString	m_certificateFile
	File containing the certificate the SCU should use for authentication.

DcmKeyFileFormat	m_certKeyFileFormat
	certificate (public key) file format

char *	m_passwd
	password required to open the private key file

OFString	m_readSeedFile
	Random seed file used for initializing Pseudo Random Number Generator (PRNG)

OFString	m_writeSeedFile
	Random seed file used for writing updated seed from Pseudo Random Number Generator back to a file.

DcmCertificateVerification	m_certVerification
	Denotes how certificates are handled, i.e. whether they are required, validated or only validated if present.

Additional Inherited Members
Protected Member Functions inherited from DcmSCU
OFCondition	sendDIMSEMessage (const T_ASC_PresentationContextID presID, T_DIMSE_Message msg, DcmDataset dataObject, DcmDataset **commandSet=NULL)
	Sends a DIMSE command and possibly also a dataset from a data object via network to another DICOM application. More...

OFCondition	getDatasetInfo (DcmDataset *dataset, OFString &sopClassUID, OFString &sopInstanceUID, E_TransferSyntax &transferSyntax)
	Returns SOP Class UID, SOP Instance UID and original transfer syntax for a given dataset. More...

OFCondition	useSecureConnection (DcmTransportLayer *tlayer)
	Tells DcmSCU to use a secure TLS connection described by the given TLS layer. More...

OFCondition	receiveDIMSECommand (T_ASC_PresentationContextID presID, T_DIMSE_Message msg, DcmDataset statusDetail, DcmDataset commandSet=NULL, const Uint32 timeout=0)
	Receive DIMSE command (excluding dataset!) over the currently open association. More...

OFCondition	receiveDIMSEDataset (T_ASC_PresentationContextID presID, DcmDataset *dataObject)
	Receives one dataset (of instance data) via network from another DICOM application. More...

void	clearPresentationContexts ()
	clear list of presentation contexts. More...

void	findPresentationContext (const T_ASC_PresentationContextID presID, OFString &abstractSyntax, OFString &transferSyntax)
	After negotiation association, this call returns the presentation context belonging to the given presentation context ID. More...

virtual void	notifyInstanceStored (const OFString &filename, const OFString &sopClassUID, const OFString &sopInstanceUID) const
	This function is called if an object was received due to a C-GET request and can be overwritten by a user in order to be informed about such an event. More...

virtual void	notifySENDProgress (const unsigned long byteCount)
	This function is called while sending DIMSE messages, i.e. on each PDV of a dataset. More...

virtual void	notifyRECEIVEProgress (const unsigned long byteCount)
	This function is called while receiving DIMSE messages, i.e. on each PDV of a dataset. More...

virtual Uint16	checkEVENTREPORTRequest (T_DIMSE_N_EventReportRQ &request, DcmDataset *reqDataset)
	Check given N-EVENT-REPORT request and dataset for validity. More...

virtual OFCondition	sendSTOREResponse (T_ASC_PresentationContextID presID, Uint16 status, const T_DIMSE_C_StoreRQ &request)
	Sends back a C-STORE response on the given presentation context, with the designated status, fitting the corresponding C-STORE request. More...

virtual OFString	createStorageFilename (DcmDataset *dataset)
	Helper function that generates a storage filename by extracting SOP Class and SOP Instance UID from a dataset and combining that with the configured storage directory. More...

virtual OFCondition	ignoreSTORERequest (T_ASC_PresentationContextID presID, const T_DIMSE_C_StoreRQ &request)
	Receives a DICOM dataset on a given presentation context ID but does not store it in memory or disk, thus ignoring it. More...

Static Protected Member Functions inherited from DcmSCU
static void	callbackSENDProgress (void *callbackContext, unsigned long byteCount)
	Callback function used for sending DIMSE messages. More...

static void	callbackRECEIVEProgress (void *callbackContext, unsigned long byteCount)
	Callback function used for receiving DIMSE messages. More...

Detailed Description

Base class for implementing DICOM TLS-enabled Service Class User functionality.

This class is derived from the general DcmSCU class and just adds the corresponding TLS capabilities.

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

Warning: This class is EXPERIMENTAL. Be careful to use it in production environment. API changes in the future are possible and likely to happen.

Constructor & Destructor Documentation

◆ DcmTLSSCU() [1/2]

DcmTLSSCU::DcmTLSSCU	(	const OFString &	peerHost,
		const OFString &	peerAETitle,
		const Uint16	portNum
	)

Initialize SCU with connection peer information.

Parameters

peerHost	The hostname or IP of the host to talk to
peerAETitle	AETitle of peer host to be used
portNum	TCP/IP port number to talk to

◆ DcmTLSSCU() [2/2]

DcmTLSSCU::DcmTLSSCU ( const DcmTLSSCU & src )

private

Private undefined copy-constructor.

Shall never be called.

Parameters

src	Source object

Member Function Documentation

◆ addCipherSuite()

virtual DcmTransportLayerStatus DcmTLSSCU::addCipherSuite ( const OFString & suite )

virtual

adds a ciphersuite to the list of ciphersuites for TLS negotiation.

Caller must ensure that initNetwork() is executed before this call. 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

◆ addTrustedCertDir()

virtual void DcmTLSSCU::addTrustedCertDir ( const OFString & certDir )

virtual

Add directory to list of directories containing trusted certificates (used if authentication is enabled)

Parameters

certDir Not documented yet

◆ addTrustedCertFile()

virtual void DcmTLSSCU::addTrustedCertFile ( const OFString & str )

virtual

Add file with trusted certificate (used if authentication is enabled)

Parameters

str Filename

◆ closeAssociation()

virtual void DcmTLSSCU::closeAssociation ( const DcmCloseAssociationType closeType )

virtual

Closes the association of this SCU.

Deprecated:: The use of this method is deprecated.

Please use DcmSCU::releaseAssociation() or DcmSCU::abortAssociation() instead.

Parameters

closeType Define whether to release or abort the association

Reimplemented from DcmSCU.

◆ disableAuthentication()

virtual void DcmTLSSCU::disableAuthentication ( )

virtual

Disables authentication.

However, DcmTLSSCU will try to establish secured connection in terms of encrypting data. Default is that authentication is disabled.

◆ enableAuthentication()

virtual void DcmTLSSCU::enableAuthentication	(	const OFString &	privateKey,
		const OFString &	certFile,
		const char *	passphrase = `NULL`,
		const DcmKeyFileFormat	privKeyFormat = `DCF_Filetype_PEM`,
		const DcmKeyFileFormat	certFormat = `DCF_Filetype_PEM`
	)

virtual

Turn on authentication for TLS.

Parameters

privateKey	File with private key to authenticate with
certFile	File with certificate to authenticate with
passphrase	Password to access key. NULL asks user on console. "" will send empty password. Default is asking the user to enter password.
privKeyFormat	Format of private key parameter. Default is SSL_FILETYPE_PEM.
certFormat	Format of certificate file parameter. Default is SSL_FILETYPE_PEM.

◆ getAuthenticationParams()

virtual OFBool DcmTLSSCU::getAuthenticationParams	(	OFString &	privKeyFile,
		OFString &	certFile,
		const char *&	passphrase,
		int &	privKeyFormat,
		int &	certFormat
	)		const

virtual

Returns OFTrue if authentication is enabled.

Parameters

privKeyFile	The file containing the private key used
certFile	The file containing the certificate used
passphrase	The passphrase used for unlocking the private key file. If NULL, password is asked from STDIN. If empty string (""), password is sent empty. All others values are sent as given.
privKeyFormat	Format of the private key in privKeyFile, see documentation of m_privateKeyFileFormat.
certFormat	The certificate format of certificate in certFile. See documentation of m_certKeyFileFormat.

Returns: Returns OFTrue if authentication is enabled, OFFalse otherwise

◆ getReadSeedFile()

virtual OFString DcmTLSSCU::getReadSeedFile ( ) const

virtual

Get random seed file used for initializing Pseudo Random Number Generator (PRNG)

Returns: Random seed file used for reading

◆ getTrustedCertDirs()

virtual void DcmTLSSCU::getTrustedCertDirs ( OFList< OFString > & trustedDirs ) const

virtual

Get directories containing considered to contain trusted certificates.

Parameters

trustedDirs directories considered to contain trusted certificates.

◆ getTrustedCertFiles()

virtual void DcmTLSSCU::getTrustedCertFiles ( OFList< OFString > & files ) const

virtual

Get files considered for trusted certificates.

Parameters

files The file names that are considered as trusted certificates

◆ getWriteSeedFile()

virtual OFString DcmTLSSCU::getWriteSeedFile ( ) const

virtual

Get random seed file the PRNG should use to store back updated random seed information.

Returns: Get random seed file used for writing back updated seed

◆ initNetwork()

virtual OFCondition DcmTLSSCU::initNetwork ( )

virtual

Initialize network, i.e. prepare for association negotiation.

Returns: EC_Normal if initialization was successful, otherwise error code

Reimplemented from DcmSCU.

◆ negotiateAssociation()

virtual OFCondition DcmTLSSCU::negotiateAssociation ( )

virtual

Negotiates association by using presentation contexts and parameters as defined by earlier function calls.

Returns: EC_Normal if negotiation was successful, otherwise error code.

Reimplemented from DcmSCU.

◆ operator=()

DcmTLSSCU& DcmTLSSCU::operator= ( const DcmTLSSCU & src )

private

Private undefined operator=.

Shall never be called.

Parameters

src	Source object

Returns: Reference to this object

◆ setDHParam()

virtual void DcmTLSSCU::setDHParam ( const OFString & dhParam )

virtual

Set Diffie-Hellman parameters from file.

This method should be called after calls to initNetwork() and setTLSProfile().

Parameters

filename of dhParam Diffie-Hellman parameter file to be used.

◆ setPeerCertVerification()

virtual void DcmTLSSCU::setPeerCertVerification ( const DcmCertificateVerification cert )

virtual

Set whether peer's certificate must be there, only is checked if there or is ignored.

Parameters

cert	Peer certificate verification mode. The following values are permitted: DCV_requireCertificate, DCV_checkCertificate, DCV_ignoreCertificate

◆ setReadSeedFile()

virtual void DcmTLSSCU::setReadSeedFile ( const OFString & seedFile )

virtual

Set file to be used as random seed for initializing the Pseudo Random Number Generator (PRNG)

Parameters

seedFile The seed file to be used.

◆ setTLSProfile()

virtual DcmTransportLayerStatus DcmTLSSCU::setTLSProfile ( DcmTLSSecurityProfile profile )

virtual

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

Caller must ensure that initNetwork() is executed before this call.

Parameters

profile TLS Security Profile

Returns: TCS_ok if successful, an error code otherwise

◆ setWriteSeedFile()

virtual void DcmTLSSCU::setWriteSeedFile ( const OFString & seedFile )

virtual

Set file to be use to store the updated random seed to store the updated random seed from the Pseudo Random Number Generator (PRNG).

Parameters

seedFile The seed file to be used for writing back seed info

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

dcmtls/include/dcmtk/dcmtls/tlsscu.h

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DcmTLSSCU() [1/2]

◆ DcmTLSSCU() [2/2]

Member Function Documentation

◆ addCipherSuite()

◆ addTrustedCertDir()

◆ addTrustedCertFile()

◆ closeAssociation()

◆ disableAuthentication()

◆ enableAuthentication()

◆ getAuthenticationParams()

◆ getReadSeedFile()

◆ getTrustedCertDirs()

◆ getTrustedCertFiles()

◆ getWriteSeedFile()

◆ initNetwork()

◆ negotiateAssociation()

◆ operator=()

◆ setDHParam()

◆ setPeerCertVerification()

◆ setReadSeedFile()

◆ setTLSProfile()

◆ setWriteSeedFile()