Base class for a timestamp client. More...

Inheritance diagram for SiTimeStamp:

Public Member Functions
	SiTimeStamp ()
	default constructor

virtual	~SiTimeStamp ()
	destructor

virtual OFCondition	stamp (const unsigned char *inputData, unsigned long inputDataSize)=0
	takes a block of raw data and requests a time stamp for this raw data. More...

virtual OFCondition	read (DcmItem &item)
	reads the current timestamp from an item of the Digital Signatures Sequence and creates a timestamp ticket object. More...

virtual OFCondition	write (DcmItem &item)=0
	writes the current timestamp into an item of the Digital Signatures Sequence and creates the timestamp type information in the item. More...

virtual void	setPolicyOID (const char *oid)
	set the requested policy OID to be included into the time stamp query More...

virtual void	setNonce (OFBool nonce)
	sets the flag controlling whether or not a nonce is included into the timestamp query. More...

virtual void	setCertificateRequested (OFBool creq)
	sets the flag controlling whether the timestamp authority will be requested to include its certificate into the timestamp reply. More...

virtual void	setMAC (E_MACType mac)
	sets the message authentication code to be used for creating the hash value in the timestamp query. More...

virtual OFBool	have_tsinfo () const
	checks if this object contains a timestamp ticket info object More...

virtual long	get_tsinfo_version () const
	returns the timestamp ticket info version number More...

virtual void	get_tsinfo_policy_oid (OFString &oid) const
	returns the timestamp ticket info policy OID More...

virtual void	get_tsinfo_imprint_algorithm_name (OFString &mac) const
	returns the timestamp ticket info MAC algorithm name More...

virtual void	get_tsinfo_serial_number (OFString &serial) const
	returns the timestamp ticket info serial number More...

virtual void	get_tsinfo_nonce (OFString &nonce) const
	returns the timestamp ticket info nonce, if present More...

virtual void	get_tsinfo_tsa_name (OFString &tsa) const
	returns the timestamp ticket info timestamp authority (TSA) name, if present More...

virtual OFBool	get_tsinfo_ordering () const
	returns the timestamp ticket info ordering flag More...

virtual void	get_tsinfo_accuracy (OFString &accuracy) const
	returns the timestamp ticket info accuracy, if present More...

virtual void	get_tsinfo_timestamp (OFString &ts) const
	returns the timestamp date/time information, if present More...

virtual int	get_tsinfo_numextensions () const
	returns the number of extensions in the timestamp ticket More...

virtual void	get_tsinfo_extension (OFString &ext, int idx) const
	returns one timestamp extension, if present More...

virtual OFCondition	verifyTSSignature (SiCertificateVerifier &cv)
	this method performs the following functions: More...

virtual OFCondition	verifyTSToken (SiCertificateVerifier &cv, DcmItem &ditem, SiCertificate &cert)
	Verify the timestamp token by checking that its imprint is indeed a hash of the DICOM signature, that the version number is as expected and that the TSA name, if provided in the timestamp ticket structure, matches the name of the TSA given in the TSA certificate. More...

void	lastError (OFString &err) const
	returns an error string containing a textual description of the result of the last call to verifyTSSignature() or verifyTSToken() if that call returned SI_EC_TimestampSignatureVerificationFailed. More...

Protected Member Functions
virtual OFCondition	create_ts_query (const unsigned char *inputData, unsigned long inputDataSize)
	takes a block of raw data, computes a message digest and creates a time stamp query object. More...

virtual TS_REQ *	getTSQ ()
	return pointer to timestamp query object, may be NULL. More...

virtual TS_RESP *	getTSR ()
	return pointer to timestamp response object, may be NULL. More...

virtual PKCS7 *	getTS ()
	return pointer to timestamp ticket object, may be NULL. More...

virtual TS_TST_INFO *	getTSInfo ()
	return pointer to timestamp ticket info object, may be NULL. More...

virtual OFCondition	load_ts_query (const char *fname)
	load timestamp query from file More...

virtual OFCondition	load_ts_response (const char *fname)
	load timestamp response from file More...

Static Protected Member Functions
static OFCondition	check_ts_response (TS_REQ tsq, TS_RESP tsr, DcmItem &ditem)
	check consistency between timestamp query (if available), timestamp response and DICOM digital signature. More...

static OFCondition	write_ts_token (TS_RESP *tsr, DcmItem &ditem)
	insert timestamp token into DICOM dataset The timestamp response must have been checked prior to this method call. More...

Private Attributes
OFString	tsq_policy_
	time stamping policy OID to be included in the time stamp query. Default is empty.

E_MACType	tsq_mac_
	MAC algorithm for creating the hash key to be timestamped. Default is SHA-256.

OFBool	tsq_use_nonce_
	Use a pseudo-random nonce in the time stamp query. Default is OFTrue.

OFBool	tsq_certificate_requested_
	Request the TSA certificate to be embedded into the time stamp reply. Default is OFTrue.

TS_REQ *	tsq_
	pointer to time stamp request object, may be NULL

TS_RESP *	tsr_
	pointer to time stamp response object, may be NULL

PKCS7 *	ts_
	pointer to time stamp ticket object, may be NULL

TS_TST_INFO *	tsinfo_
	pointer to time stamp ticket info object (extracted from the timestamp ticket), may be NULL

long	errorCode_
	OpenSSL X.509 certificate verification error code for the last operation.

const char *	errorString_
	error string for the last operation, valid if errorCode_ < 0

Detailed Description

Base class for a timestamp client.

Instances of derived classes are able to request timestamps from a timestamp service. This class implements the code needed to create a timestamp request and to insert a timestamp reply into a DICOM dataset, but not the protocol for actually interacting with a timestamp authority.

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

Member Function Documentation

◆ check_ts_response()

static OFCondition SiTimeStamp::check_ts_response	(	TS_REQ *	tsq,
		TS_RESP *	tsr,
		DcmItem &	ditem
	)

staticprotected

check consistency between timestamp query (if available), timestamp response and DICOM digital signature.

Parameters

tsq	pointer to timestamp query, may be NULL
tsr	pointer to timestamp response, must not be NULL
ditem	item of the DigitalSignaturesSequence to which this timestamp belongs

Returns: status code

◆ create_ts_query()

virtual OFCondition SiTimeStamp::create_ts_query	(	const unsigned char *	inputData,
		unsigned long	inputDataSize
	)

protectedvirtual

takes a block of raw data, computes a message digest and creates a time stamp query object.

Parameters

inputData	pointer to raw data
inputDataSize	length of raw data block in bytes

Returns: status code

◆ get_tsinfo_accuracy()

virtual void SiTimeStamp::get_tsinfo_accuracy ( OFString & accuracy ) const

virtual

returns the timestamp ticket info accuracy, if present

Parameters

accuracy upon return, contains the accuracy if available, an empty string otherwise

◆ get_tsinfo_extension()

virtual void SiTimeStamp::get_tsinfo_extension	(	OFString &	ext,
		int	idx
	)		const

virtual

returns one timestamp extension, if present

Parameters

ext	upon return, contains the timestamp extension if present, an empty string otherwise
idx	number of the extension, 0 <= idx < get_tsinfo_numextensions().

◆ get_tsinfo_imprint_algorithm_name()

virtual void SiTimeStamp::get_tsinfo_imprint_algorithm_name ( OFString & mac ) const

virtual

returns the timestamp ticket info MAC algorithm name

Parameters

mac	upon return, contains the MAC algorithm name if available, an empty string otherwise

◆ get_tsinfo_nonce()

virtual void SiTimeStamp::get_tsinfo_nonce ( OFString & nonce ) const

virtual

returns the timestamp ticket info nonce, if present

Parameters

nonce upon return, contains the nonce if available, an empty string otherwise

◆ get_tsinfo_numextensions()

virtual int SiTimeStamp::get_tsinfo_numextensions ( ) const

virtual

returns the number of extensions in the timestamp ticket

Returns: number of extensions in the timestamp ticket

◆ get_tsinfo_ordering()

virtual OFBool SiTimeStamp::get_tsinfo_ordering ( ) const

virtual

returns the timestamp ticket info ordering flag

Returns: OFTrue if timestamp ticket is present and contains an ordering flag with value "true", OFFalse otherwise

◆ get_tsinfo_policy_oid()

virtual void SiTimeStamp::get_tsinfo_policy_oid ( OFString & oid ) const

virtual

returns the timestamp ticket info policy OID

Parameters

oid	upon return, contains the policy OID if available, an empty string otherwise

◆ get_tsinfo_serial_number()

virtual void SiTimeStamp::get_tsinfo_serial_number ( OFString & serial ) const

virtual

returns the timestamp ticket info serial number

Parameters

serial upon return, contains the serial number if available, an empty string otherwise

◆ get_tsinfo_timestamp()

virtual void SiTimeStamp::get_tsinfo_timestamp ( OFString & ts ) const

virtual

returns the timestamp date/time information, if present

Parameters

ts	upon return, contains the timestamp date/time information, an empty string otherwise

◆ get_tsinfo_tsa_name()

virtual void SiTimeStamp::get_tsinfo_tsa_name ( OFString & tsa ) const

virtual

returns the timestamp ticket info timestamp authority (TSA) name, if present

Parameters

tsa	upon return, contains the TSA name if available, an empty string otherwise

◆ get_tsinfo_version()

virtual long SiTimeStamp::get_tsinfo_version ( ) const

virtual

returns the timestamp ticket info version number

Returns: tsinfo version number if available, -1 otherwise

◆ getTS()

virtual PKCS7* SiTimeStamp::getTS ( )

inlineprotectedvirtual

return pointer to timestamp ticket object, may be NULL.

Returns: pointer to timestamp ticket object, may be NULL.

◆ getTSInfo()

virtual TS_TST_INFO* SiTimeStamp::getTSInfo ( )

inlineprotectedvirtual

return pointer to timestamp ticket info object, may be NULL.

Returns: pointer to timestamp ticket info object, may be NULL.

◆ getTSQ()

virtual TS_REQ* SiTimeStamp::getTSQ ( )

inlineprotectedvirtual

return pointer to timestamp query object, may be NULL.

Returns: pointer to timestamp query object, may be NULL.

◆ getTSR()

virtual TS_RESP* SiTimeStamp::getTSR ( )

inlineprotectedvirtual

return pointer to timestamp response object, may be NULL.

Returns: pointer to timestamp response object, may be NULL.

◆ have_tsinfo()

virtual OFBool SiTimeStamp::have_tsinfo ( ) const

virtual

checks if this object contains a timestamp ticket info object

Returns: OFTrue if timestamp ticket info available, OFFalse otherwise

◆ lastError()

void SiTimeStamp::lastError ( OFString & err ) const

returns an error string containing a textual description of the result of the last call to verifyTSSignature() or verifyTSToken() if that call returned SI_EC_TimestampSignatureVerificationFailed.

Parameters

err	text string returned in this parameter

◆ load_ts_query()

virtual OFCondition SiTimeStamp::load_ts_query ( const char * fname )

protectedvirtual

load timestamp query from file

Parameters

fname filename, must not be NULL

Returns: status code

◆ load_ts_response()

virtual OFCondition SiTimeStamp::load_ts_response ( const char * fname )

protectedvirtual

load timestamp response from file

Parameters

fname filename, must not be NULL

Returns: status code

◆ read()

virtual OFCondition SiTimeStamp::read ( DcmItem & item )

virtual

reads the current timestamp from an item of the Digital Signatures Sequence and creates a timestamp ticket object.

Parameters

item	item of the DigitalSignatureSQ from which the timestamp is read

Returns: status code

◆ setCertificateRequested()

virtual void SiTimeStamp::setCertificateRequested ( OFBool creq )

virtual

sets the flag controlling whether the timestamp authority will be requested to include its certificate into the timestamp reply.

A timestamp reply with certificate is easier to verify, as less external key material is required, but somewhat larger. Default is OFTrue;

Parameters

creq	OFTrue if certificate should be requested, OFFalse otherwise

◆ setMAC()

virtual void SiTimeStamp::setMAC ( E_MACType mac )

virtual

sets the message authentication code to be used for creating the hash value in the timestamp query.

Default is SHA256.

Parameters

creq	OFTrue if certificate should be requested, OFFalse otherwise

◆ setNonce()

virtual void SiTimeStamp::setNonce ( OFBool nonce )

virtual

sets the flag controlling whether or not a nonce is included into the timestamp query.

Since a nonce is a protection against replay attack, normally it should be included, and this is also the default.

Parameters

nonce OFTrue if nonce should be included, OFFalse otherwise

◆ setPolicyOID()

virtual void SiTimeStamp::setPolicyOID ( const char * oid )

virtual

set the requested policy OID to be included into the time stamp query

Parameters

oid	policy OID, NULL for no policy (which is the default).

◆ stamp()

virtual OFCondition SiTimeStamp::stamp	(	const unsigned char *	inputData,
		unsigned long	inputDataSize
	)

pure virtual

takes a block of raw data and requests a time stamp for this raw data.

Parameters

inputData	pointer to raw data
inputDataSize	length of raw data block in bytes

Returns: status code

Implemented in SiTimeStampFS.

◆ verifyTSSignature()

virtual OFCondition SiTimeStamp::verifyTSSignature ( SiCertificateVerifier & cv )

virtual

this method performs the following functions:

it checks if there is one and only one signer.
it identifies the signer certificate (which may be embedded in the timestamp, or loaded in the SiCertificateVerifier store)
it checks the extended key usage and key usage fields of the signer certificate
it verifies the certificate path
it checks if the certificate path meets the requirements of the SigningCertificate ESS signed attribute.
it verifies the signature value (against the imprint in the timestamp token
it prints the contents of the signer certificate to the logger
Parameters

cv container for the certificates used during verification

Returns
EC_Normal upon success, an error code otherwise.

◆ verifyTSToken()

virtual OFCondition SiTimeStamp::verifyTSToken	(	SiCertificateVerifier &	cv,
		DcmItem &	ditem,
		SiCertificate &	cert
	)

virtual

Verify the timestamp token by checking that its imprint is indeed a hash of the DICOM signature, that the version number is as expected and that the TSA name, if provided in the timestamp ticket structure, matches the name of the TSA given in the TSA certificate.

Parameters

cv	container for the certificates used during verification
ditem	item of the Digital Signatures Sequence containing the timestamp
cert	certificate of the signer of the DICOM signature, used to check the date/time of the timestamp against the validity period of the certificate

Returns: EC_Normal upon success, an error code otherwise.

◆ write()

virtual OFCondition SiTimeStamp::write ( DcmItem & item )

pure virtual

writes the current timestamp into an item of the Digital Signatures Sequence and creates the timestamp type information in the item.

Parameters

item	item of the DigitalSignatureSQ to which the timestamp is written

Returns: status code

Implemented in SiTimeStampFS.

◆ write_ts_token()

static OFCondition SiTimeStamp::write_ts_token	(	TS_RESP *	tsr,
		DcmItem &	ditem
	)

staticprotected

insert timestamp token into DICOM dataset The timestamp response must have been checked prior to this method call.

Parameters

tsr	pointer to timestamp response, must not be NULL
ditem	item of the DigitalSignaturesSequence to which this timestamp is written

Returns: status code

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

dcmsign/include/dcmtk/dcmsign/sitstamp.h

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Private Attributes

Detailed Description

Member Function Documentation

◆ check_ts_response()

◆ create_ts_query()

◆ get_tsinfo_accuracy()

◆ get_tsinfo_extension()

◆ get_tsinfo_imprint_algorithm_name()

◆ get_tsinfo_nonce()

◆ get_tsinfo_numextensions()

◆ get_tsinfo_ordering()

◆ get_tsinfo_policy_oid()

◆ get_tsinfo_serial_number()

◆ get_tsinfo_timestamp()

◆ get_tsinfo_tsa_name()

◆ get_tsinfo_version()

◆ getTS()

◆ getTSInfo()

◆ getTSQ()

◆ getTSR()

◆ have_tsinfo()

◆ lastError()

◆ load_ts_query()

◆ load_ts_response()

◆ read()

◆ setCertificateRequested()

◆ setMAC()

◆ setNonce()

◆ setPolicyOID()

◆ stamp()

◆ verifyTSSignature()

◆ verifyTSToken()

◆ write()

◆ write_ts_token()