DCMTK: SiTimeStamp Class Reference

DCMTK Version 3.6.9 OFFIS DICOM Toolkit

Loading...
Searching...
No Matches
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Private Attributes | List of all members
SiTimeStamp Class Referenceabstract

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.
virtual OFCondition | read (DcmItem &item)
| reads the current timestamp from an item of the Digital Signatures Sequence and creates a timestamp ticket object.
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.
virtual void | setPolicyOID (const char *oid)
| set the requested policy OID to be included into the time stamp query
virtual void | setNonce (OFBool nonce)
| sets the flag controlling whether or not a nonce is included into the timestamp query.
virtual void | setCertificateRequested (OFBool creq)
| sets the flag controlling whether the timestamp authority will be requested to include its certificate into the timestamp reply.
virtual void | setMAC (E_MACType mac)
| sets the message authentication code to be used for creating the hash value in the timestamp query.
virtual OFBool | have_tsinfo () const
| checks if this object contains a timestamp ticket info object
virtual long | get_tsinfo_version () const
| returns the timestamp ticket info version number
virtual void | get_tsinfo_policy_oid (OFString &oid) const
| returns the timestamp ticket info policy OID
virtual void | get_tsinfo_imprint_algorithm_name (OFString &mac) const
| returns the timestamp ticket info MAC algorithm name
virtual void | get_tsinfo_serial_number (OFString &serial) const
| returns the timestamp ticket info serial number
virtual void | get_tsinfo_nonce (OFString &nonce) const
| returns the timestamp ticket info nonce, if present
virtual void | get_tsinfo_tsa_name (OFString &tsa) const
| returns the timestamp ticket info timestamp authority (TSA) name, if present
virtual OFBool | get_tsinfo_ordering () const
| returns the timestamp ticket info ordering flag
virtual void | get_tsinfo_accuracy (OFString &accuracy) const
| returns the timestamp ticket info accuracy, if present
virtual void | get_tsinfo_timestamp (OFString &ts) const
| returns the timestamp date/time information, if present
virtual int | get_tsinfo_numextensions () const
| returns the number of extensions in the timestamp ticket
virtual void | get_tsinfo_extension (OFString &ext, int idx) const
| returns one timestamp extension, if present
virtual OFCondition | verifyTSSignature (SiCertificateVerifier &cv)
| this method performs the following functions:
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.
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.

## 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.
virtual TS_REQ * | getTSQ ()
| return pointer to timestamp query object, may be NULL.
virtual TS_RESP * | getTSR ()
| return pointer to timestamp response object, may be NULL.
virtual PKCS7 * | getTS ()
| return pointer to timestamp ticket object, may be NULL.
virtual TS_TST_INFO * | getTSInfo ()
| return pointer to timestamp ticket info object, may be NULL.
virtual OFCondition | load_ts_query (const char *fname)
| load timestamp query from file
virtual OFCondition | load_ts_response (const char *fname)
| load timestamp response from file

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

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

References ts_.

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

References tsinfo_.

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

References tsq_.

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

References tsr_.

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

Generated on Wed Apr 30 2025 for DCMTK Version 3.6.9 by Doxygen 1.13.2