DCMTK Version 3.7.0 OFFIS DICOM Toolkit

Public Member Functions | Static Public Member Functions | Static Private Member Functions | List of all members
DcmSignatureHelper Class Reference

this class provides helper functions for creating and verifying digital signatures. More...

## Public Member Functions
| DcmSignatureHelper ()
| default constructor
virtual | ~DcmSignatureHelper ()
| destructor

## Static Public Member Functions
static DcmItem * | locateItemforSignatureCreation (DcmItem &dataset, const char *location)
| locate a specific item within the given dataset. More...
static int | parseTextFile (const char *filename, DcmAttributeTag &tagList)
| read a list of attributes from a text file. More...
static OFBool | addTag (const char *c, DcmAttributeTag &tagList)
| read an attribute tag in the form "gggg,eeee" and adds it to the given attribute tag list More...
static void | printSignatureItemPosition (DcmStack &stack, OFString &str)
| print the location stack into the given stack. More...
static int | do_sign (DcmItem *dataset, SiPrivateKey &key, SiCertificate &cert, SiMAC *opt_mac, SiSecurityProfile *opt_profile, DcmAttributeTag *opt_tagList, E_TransferSyntax opt_signatureXfer, FILE *dumpFile, SiSignaturePurpose::E_SignaturePurposeType opt_sigPurpose, SiTimeStamp *timeStamp=NULL)
| perform a signature operation on a given dataset More...
static int | do_sign_item (DcmItem *dataset, SiPrivateKey &key, SiCertificate &cert, SiMAC *opt_mac, SiSecurityProfile *opt_profile, DcmAttributeTag *opt_tagList, const char *opt_location, E_TransferSyntax opt_signatureXfer, FILE *dumpFile, SiSignaturePurpose::E_SignaturePurposeType opt_sigPurpose, SiTimeStamp *timeStamp=NULL)
| performs a signature operation on a sub-item within a dataset More...
static int | do_verify (DcmItem *dataset, SiCertificateVerifier &certVerifier, E_SignatureVerificationPolicy verificationPolicy, E_TimestampVerificationPolicy timstampPolicy)
| verify all signatures in the given dataset and print results to stdout. More...
static int | do_insert_ts (DcmItem *dataset, SiTimeStampFS *timeStamp)
| insert certified timestamp from file. More...
static int | do_remove_all (DcmItem *dataset)
| remove all signatures from the given dataset, print action details. More...
static int | do_remove (DcmItem *dataset, const char *opt_location)
| remove the signature with the given UID from the dataset, print action details. More...

## Static Private Member Functions
static int | readNextToken (const char *c, int &pos, DcmTagKey &key, Uint32 &idx)
| scans a token from the given string and returns it. More...
static char * | readTextFile (const char *filename)
| reads a complete text file (max 64K) into a memory block and returns a pointer to the memory block. More...
static void | printSignatureDetails (DcmSignature &sig, DcmStack &stack, int count)
| print the details of the current signature to the logger More...
static void | printTimestampDetails (DcmSignature &sig, E_TimestampVerificationPolicy tsPolicy)
| print the details of the timestamp for the current signature to the logger More...

## Detailed Description

this class provides helper functions for creating and verifying digital signatures.

It encapsulates most of the code that was part of the main command line program "dcmsign" in prior DCMTK releases.

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

## Member Function Documentation

## ◆ addTag()

static OFBool DcmSignatureHelper::addTag | ( | const char * | c,
|  | DcmAttributeTag & | tagList
| ) |  |
| static

read an attribute tag in the form "gggg,eeee" and adds it to the given attribute tag list

Parameters

  c | input string
  tagList | list to be added to

Returns
  true if successful, false otherwise

## ◆ do_insert_ts()

static int DcmSignatureHelper::do_insert_ts | ( | DcmItem * | dataset,
|  | SiTimeStampFS * | timeStamp
| ) |  |
| static

insert certified timestamp from file.

Parameters

  dataset | in which to add timestamp
  timeStamp | handler, must not be NULL

## ◆ do_remove()

static int DcmSignatureHelper::do_remove | ( | DcmItem * | dataset,
|  | const char * | opt_location
| ) |  |
| static

remove the signature with the given UID from the dataset, print action details.

Parameters

  dataset | dataset to modify
  opt_location | Digital Signature UID of the signature to remove

Returns
  0 if successful, a program exit code otherwise

## ◆ do_remove_all()

static int DcmSignatureHelper::do_remove_all | ( | DcmItem * | dataset | ) |
| static

remove all signatures from the given dataset, print action details.

Parameters

  dataset | dataset to modify

Returns
  0 if successful, a program exit code otherwise

## ◆ do_sign()

static int DcmSignatureHelper::do_sign | ( | DcmItem * | dataset,
|  | SiPrivateKey & | key,
|  | SiCertificate & | cert,
|  | SiMAC * | opt_mac,
|  | SiSecurityProfile * | opt_profile,
|  | DcmAttributeTag * | opt_tagList,
|  | E_TransferSyntax | opt_signatureXfer,
|  | FILE * | dumpFile,
|  | SiSignaturePurpose::E_SignaturePurposeType | opt_sigPurpose,
|  | SiTimeStamp * | timeStamp = `NULL`
| ) |  |
| static

perform a signature operation on a given dataset

Parameters

  dataset | to sign
  key | private key for signature
  cert | certificate for signature
  opt_mac | MAC for signature
  opt_profile | security profile for signature
  opt_tagList | list of attribute tags, may be NULL
  opt_signatureXfer | signature transfer syntax
  dumpFile | file to dump the byte stream to
  opt_sigPurpose | signature purpose
  timeStamp | pointer to timestamp client, may be NULL

Returns
  0 if successful, a program exit code otherwise

## ◆ do_sign_item()

static int DcmSignatureHelper::do_sign_item | ( | DcmItem * | dataset,
|  | SiPrivateKey & | key,
|  | SiCertificate & | cert,
|  | SiMAC * | opt_mac,
|  | SiSecurityProfile * | opt_profile,
|  | DcmAttributeTag * | opt_tagList,
|  | const char * | opt_location,
|  | E_TransferSyntax | opt_signatureXfer,
|  | FILE * | dumpFile,
|  | SiSignaturePurpose::E_SignaturePurposeType | opt_sigPurpose,
|  | SiTimeStamp * | timeStamp = `NULL`
| ) |  |
| static

performs a signature operation on a sub-item within a dataset

Parameters

  dataset | in which to sign
  key | private key for signature
  cert | certificate for signature
  opt_mac | MAC for signature
  opt_profile | security profile for signature
  opt_tagList | list of attribute tags, may be NULL
  location | location string. Format is "sequence[item]{.sequence[item]}*" Where sequence can be (gggg,eeee) or a dictionary name and items within sequences are counted from zero.
  opt_signatureXfer | signature transfer syntax
  dumpFile | file to dump the byte stream to
  opt_sigPurpose | signature purpose
  timeStamp | pointer to timestamp client, may be NULL

Returns
  0 if successful, a program exit code otherwise

## ◆ do_verify()

static int DcmSignatureHelper::do_verify | ( | DcmItem * | dataset,
|  | SiCertificateVerifier & | certVerifier,
|  | E_SignatureVerificationPolicy | verificationPolicy,
|  | E_TimestampVerificationPolicy | timstampPolicy
| ) |  |
| static

verify all signatures in the given dataset and print results to stdout.

Parameters

  dataset | dataset to verify
  certVerifier | certification verifier helper object
  verificationPolicy | signature verification policy
  timstampPolicy | timestamp verification policy

Returns
  0 if successful, a program exit code otherwise

## ◆ locateItemforSignatureCreation()

static DcmItem* DcmSignatureHelper::locateItemforSignatureCreation | ( | DcmItem & | dataset,
|  | const char * | location
| ) |  |
| static

locate a specific item within the given dataset.

Parameters

  dataset | dataset to be searched
  location | location string. Format is "sequence[item]{.sequence[item]}*" Where sequence can be (gggg,eeee) or a dictionary name and items within sequences are counted from zero.

Returns
  pointer to the item searched if found, NULL otherwise

## ◆ parseTextFile()

static int DcmSignatureHelper::parseTextFile | ( | const char * | filename,
|  | DcmAttributeTag & | tagList
| ) |  |
| static

read a list of attributes from a text file.

The attributes can be in the form (gggg,eeee) or can be dictionary names, separated by arbitrary whitespace.

Parameters

  filename | file to be read from
  tagList | attribute tags are added to this list

Returns
  0 if successful, a program exit code otherwise

## ◆ printSignatureDetails()

static void DcmSignatureHelper::printSignatureDetails | ( | DcmSignature & | sig,
|  | DcmStack & | stack,
|  | int | count
| ) |  |
| static private

print the details of the current signature to the logger

Parameters

  sig | signature object
  stack | position of the signature object in the dataset
  count | number of the signature (counter)

## ◆ printSignatureItemPosition()

static void DcmSignatureHelper::printSignatureItemPosition | ( | DcmStack & | stack,
|  | OFString & | str
| ) |  |
| static

print the location stack into the given stack.

It is assumed that the stack top is a DigitalSignatureSequence which is not printed and that the stack bottom is the main dataset, which is also not printed.

Parameters

  stack | search stack, as returned by DcmSignature::findFirstSignatureItem() etc.
  str | printable text returned in this string.

## ◆ printTimestampDetails()

static void DcmSignatureHelper::printTimestampDetails | ( | DcmSignature & | sig,
|  | E_TimestampVerificationPolicy | tsPolicy
| ) |  |
| static private

print the details of the timestamp for the current signature to the logger

Parameters

  sig | signature object
  tsPolicy | timestamp verification policy

## ◆ readNextToken()

static int DcmSignatureHelper::readNextToken | ( | const char * | c,
|  | int & | pos,
|  | DcmTagKey & | key,
|  | Uint32 & | idx
| ) |  |
| static private

scans a token from the given string and returns it.

Ignores leading whitespace.

Parameters

  c | string to parse
  pos | position within string, modified after successful scan
  key | tag key returned in this parameter if return value is "tag key".
  idx | index returned in this parameter if return value is "index".

Returns
  -1 for "EOF", 0 for "parse error", 1 for "tag key", 2 for "index", 3 for "period"

## ◆ readTextFile()

static char* DcmSignatureHelper::readTextFile | ( | const char * | filename | ) |
| static private

reads a complete text file (max 64K) into a memory block and returns a pointer to the memory block.

memory must be freed by caller.

Parameters

  filename | file to be read

Returns
  pointer to memory block if successful, NULL otherwise.

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

- dcmsign/include/dcmtk/dcmsign/dcsighlp.h

Generated on Mon Dec 15 2025 for DCMTK Version 3.7.0 by Doxygen 1.9.1