DCMTK  Version 3.6.6
OFFIS DICOM Toolkit
Public Member Functions | Static Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | List of all members
DcmSignature Class Reference

this class provides the main interface to the dcmsign module - it allows to create, examine and verify digital signatures in DICOM datasets or items. More...

Public Member Functions

 DcmSignature ()
 default constructor
 
virtual ~DcmSignature ()
 destructor
 
void attach (DcmItem *dataset)
 attaches a DICOM dataset or item to the signature object. More...
 
void detach ()
 detaches an attached DICOM dataset from the signature object.
 
OFCondition createSignature (SiPrivateKey &key, SiCertificate &cert, SiMAC &mac, SiSecurityProfile &profile, E_TransferSyntax xfer=EXS_LittleEndianExplicit, const DcmAttributeTag *tagList=NULL, SiTimeStamp *timeStamp=NULL, SiSignaturePurpose::E_SignaturePurposeType sigPurpose=SiSignaturePurpose::ESP_none)
 creates a new digital signature in the current dataset. More...
 
unsigned long numberOfSignatures ()
 returns the number of signatures in the dataset. More...
 
OFCondition removeSignature (unsigned long i)
 removes a signature from the dataset. More...
 
OFCondition selectSignature (unsigned long i)
 selects one of the digital signatures from the attached dataset for reading. More...
 
OFCondition verifyCurrent ()
 verifies the current signature. More...
 
OFCondition getCurrentMacID (Uint16 &macID)
 returns the MAC ID of the current signature. More...
 
OFCondition getCurrentMacXferSyntaxName (OFString &str)
 returns the MAC Calculation Transfer Syntax of the current signature. More...
 
OFCondition getCurrentMacName (OFString &str)
 returns the MAC Algorithm Name of the current signature. More...
 
OFCondition getCurrentSignatureUID (OFString &str)
 returns the Digital Signature UID of the current signature. More...
 
OFCondition getCurrentSignatureDateTime (OFString &str)
 returns the Signature Date/Time of the current signature. More...
 
DcmDateTimegetCurrentSignatureDateTime ()
 returns a pointer to the object representing Signature Date/Time of the current signature. More...
 
OFCondition getCurrentDataElementsSigned (DcmAttributeTag &desig)
 returns the Data Elements Signed attribute of the current signature if present. More...
 
OFCondition getCurrentSignaturePurpose (OFString &codeValue, OFString &codeMeaning, OFString &codingSchemeDesignator)
 returns the signature purpose code of the current signature if present. More...
 
OFCondition verifySignatureProfile (SiSecurityProfile &sprof)
 verifies whether the currently selected signature within the currently attached dataset matches the requirements of the given signature profile. More...
 
SiCertificategetCurrentCertificate ()
 returns the certificate of the current signature if present. More...
 
SiTimeStampgetCurrentTimestamp ()
 returns the certified timestamp of the current signature if present. More...
 
DcmItemgetSelectedSignatureItem ()
 returns the item of the DigitalSignaturesSequence selected by the last call to selectSignature(), or NULL if no signature has been selected. More...
 
void setDumpFile (FILE *f)
 dump all data that is fed into the MAC algorithm into the given file, which must be opened and closed by caller. More...
 

Static Public Member Functions

static void initializeLibrary ()
 initializes the dcmsign library including the underlying OpenSSL library. More...
 
static DcmItemfindFirstSignatureItem (DcmItem &item, DcmStack &stack)
 recursively browses through the given dataset and searches the first occurrence of the DigitalSignaturesSequence. More...
 
static DcmItemfindNextSignatureItem (DcmItem &item, DcmStack &stack)
 recursively browses through the given dataset and searches the next occurrence of the DigitalSignaturesSequence. More...
 
static void adjustASN1SequenceLength (const unsigned char *buf, unsigned long &buflen)
 check a DER encoded ASN.1 SEQUENCE structure for a possible pad byte and, if a pad byte is detected, remove it by decreasing buflen. More...
 

Private Member Functions

 DcmSignature (DcmSignature &arg)
 private undefined copy constructor
 
DcmSignatureoperator= (DcmSignature &arg)
 private undefined copy assignment operator
 
void deselect ()
 removes the selection of a current signature if present
 
OFCondition allocateMACID (Uint16 &newID)
 allocates a new mac ID number for a new signature. More...
 

Static Private Member Functions

static OFCondition getMACIDnumber (DcmItem &item, Uint16 &macid)
 searches a given item for the DCM_MACIDnumber element and returns its value if present More...
 
static OFCondition checkListOfSignedTags (const DcmAttributeTag *tagList, const DcmAttributeTag *tagListOut)
 checks if all tags from tagList are present in tagListOut, which is the list of attribute tags actually included in a signature, including tags added due to a signature profile, and without tags that were absent in the dataset. More...
 
static OFBool inTagList (const DcmTagKey &tag, const DcmAttributeTag &tagList)
 checks if the given tag key is present in tagList More...
 
static void currentDateTime (OFString &str)
 returns the current date and time as a DICOM DT string. More...
 

Private Attributes

DcmItemcurrentItem
 pointer to current item if attached, NULL otherwise
 
DcmSequenceOfItemsmacParametersSq
 pointer to mac parameters sequence of attached item, may be NULL if not attached or not yet present
 
DcmSequenceOfItemssignatureSq
 pointer to digital signatures sequence of attached item, may be NULL if not attached or not yet present
 
FILE * dumpFile
 if nonzero, the data fed to the MAC algorithm is also stored in this file.
 
DcmItemselectedSignatureItem
 pointer to currently selected signature item
 
DcmItemselectedMacParametersItem
 pointer to currently selected mac parameters item
 
SiCertificateselectedCertificate
 pointer to certificate for currently selected signature item
 
SiTimeStampselectedTimestamp
 pointer to certified timestamp for currently selected signature item
 

Detailed Description

this class provides the main interface to the dcmsign module - it allows to create, examine and verify digital signatures in DICOM datasets or items.

The methods in this class do not handle digital signatures embedded in sequence items within the dataset, other than providing helper functions that allow to locate and attach the sub-items separately.

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

Member Function Documentation

◆ adjustASN1SequenceLength()

static void DcmSignature::adjustASN1SequenceLength ( const unsigned char *  buf,
unsigned long &  buflen 
)
static

check a DER encoded ASN.1 SEQUENCE structure for a possible pad byte and, if a pad byte is detected, remove it by decreasing buflen.

This will work for SEQUENCEs with one byte and two byte encoding (i.e. max 64 kBytes).

Parameters
bufpointer to DER encoded ASN.1 data
buflenlength of buffer pointed to, in bytes. The variable is decreased by one if a pad byte is detected.

◆ allocateMACID()

OFCondition DcmSignature::allocateMACID ( Uint16 &  newID)
private

allocates a new mac ID number for a new signature.

examines all mac ID numbers in the digital signatures sequence and in the mac parameters sequence and returns an unused number.

Parameters
newIDupon successful return, new number is passed in this parameter
Returns
status code

◆ attach()

void DcmSignature::attach ( DcmItem dataset)

attaches a DICOM dataset or item to the signature object.

The dataset is detached by a call to detach() or by destruction of the signature object. This object may modify but never deletes an attached dataset.

Parameters
datasetdataset or item to be attached

◆ checkListOfSignedTags()

static OFCondition DcmSignature::checkListOfSignedTags ( const DcmAttributeTag tagList,
const DcmAttributeTag tagListOut 
)
staticprivate

checks if all tags from tagList are present in tagListOut, which is the list of attribute tags actually included in a signature, including tags added due to a signature profile, and without tags that were absent in the dataset.

Parameters
tagListlist of attribute tags that should be present in the signature, may be NULL
tagListOutlist of attribute tags actually present in the signature, must not be NULL
Returns
EC_Normal if check succeeds, an error code otherwise

◆ createSignature()

OFCondition DcmSignature::createSignature ( SiPrivateKey key,
SiCertificate cert,
SiMAC mac,
SiSecurityProfile profile,
E_TransferSyntax  xfer = EXS_LittleEndianExplicit,
const DcmAttributeTag tagList = NULL,
SiTimeStamp timeStamp = NULL,
SiSignaturePurpose::E_SignaturePurposeType  sigPurpose = SiSignaturePurpose::ESP_none 
)

creates a new digital signature in the current dataset.

Checks whether private and public key match and whether all requirements of the given security profile are fulfilled.

Parameters
keyprivate key for signature creation
certcertificate with public key
macMAC algorithm to be used for signature creation
profilesecurity profile for signature creation
xfertransfer syntax to use when serializing DICOM data
tagListpointer to list of attribute tags to sign, may be NULL. If this parameter is nonzero, it contains a list of attribute sign. The real list of attributes signed is derived from this parameter plus the requirements of the security profile. If NULL, a universal match is assumed, i.e. all signable attributes in the data set are signed.
timeStamppointer to time stamp client used to create timestamps for the digital signature.
sigPurposedigital signature purpose
Returns
status code

◆ currentDateTime()

static void DcmSignature::currentDateTime ( OFString str)
staticprivate

returns the current date and time as a DICOM DT string.

Parameters
strdate/time returned in this string.

◆ findFirstSignatureItem()

static DcmItem* DcmSignature::findFirstSignatureItem ( DcmItem item,
DcmStack stack 
)
static

recursively browses through the given dataset and searches the first occurrence of the DigitalSignaturesSequence.

If found, returns a pointer to the Item in which the sequence is contained.

Parameters
itemdataset to be browsed
stacksearch stack, must be passed to findNextSignatureItem() later on.
Returns
pointer to Item containing a DigitalSignatureSequence if found, NULL otherwise.

◆ findNextSignatureItem()

static DcmItem* DcmSignature::findNextSignatureItem ( DcmItem item,
DcmStack stack 
)
static

recursively browses through the given dataset and searches the next occurrence of the DigitalSignaturesSequence.

If found, returns a pointer to the Item in which the sequence is contained.

Parameters
itemdataset to be browsed
stacksearch stack as returned by findFirstSignatureItem() or the last call to this method.
Returns
pointer to Item containing a DigitalSignatureSequence if found, NULL otherwise.

◆ getCurrentCertificate()

SiCertificate* DcmSignature::getCurrentCertificate ( )

returns the certificate of the current signature if present.

Current signature must be selected with selectSignature(). May return NULL if certificate is unavailable.

Returns
pointer to current certificate, NULL if unavailable.

◆ getCurrentDataElementsSigned()

OFCondition DcmSignature::getCurrentDataElementsSigned ( DcmAttributeTag desig)

returns the Data Elements Signed attribute of the current signature if present.

Current signature must be selected with selectSignature(). If a valid signature is selected but the signature does not contain the Data Elements Signed element (i.e. all attributes are signed), this method returns an error code.

Parameters
desigdata elements signed returned in this parameter upon success
Returns
status code

◆ getCurrentMacID()

OFCondition DcmSignature::getCurrentMacID ( Uint16 &  macID)

returns the MAC ID of the current signature.

Current signature must be selected with selectSignature().

Parameters
macIDMAC ID returned in this parameter upon success
Returns
status code

◆ getCurrentMacName()

OFCondition DcmSignature::getCurrentMacName ( OFString str)

returns the MAC Algorithm Name of the current signature.

Current signature must be selected with selectSignature().

Parameters
strMAC algorithm name returned in this parameter upon success
Returns
status code

◆ getCurrentMacXferSyntaxName()

OFCondition DcmSignature::getCurrentMacXferSyntaxName ( OFString str)

returns the MAC Calculation Transfer Syntax of the current signature.

If the transfer syntax is well-known, the UID is replaced by the transfer syntax name preceded by '='. Current signature must be selected with selectSignature().

Parameters
strtransfer syntax name or UID returned in this parameter upon success
Returns
status code

◆ getCurrentSignatureDateTime() [1/2]

DcmDateTime* DcmSignature::getCurrentSignatureDateTime ( )

returns a pointer to the object representing Signature Date/Time of the current signature.

Current signature must be selected with selectSignature().

Returns
pointer to signature datetime if present, NULL otherwise

◆ getCurrentSignatureDateTime() [2/2]

OFCondition DcmSignature::getCurrentSignatureDateTime ( OFString str)

returns the Signature Date/Time of the current signature.

Current signature must be selected with selectSignature().

Parameters
strsignature date/time returned in this parameter upon success
Returns
status code

◆ getCurrentSignaturePurpose()

OFCondition DcmSignature::getCurrentSignaturePurpose ( OFString codeValue,
OFString codeMeaning,
OFString codingSchemeDesignator 
)

returns the signature purpose code of the current signature if present.

Current signature must be selected with selectSignature(). If a valid signature is selected but the signature does not contain a valid SignaturePurposeCodeSequence, this method returns an error code.

Parameters
codeValuesignature purpose code value returned in this parameter upon success
codeMeaningsignature purpose code meaning returned in this parameter upon success
codingSchemeDesignatorsignature purpose coding scheme designator returned in this parameter upon success
Returns
status code

◆ getCurrentSignatureUID()

OFCondition DcmSignature::getCurrentSignatureUID ( OFString str)

returns the Digital Signature UID of the current signature.

Current signature must be selected with selectSignature().

Parameters
strsignature UID returned in this parameter upon success
Returns
status code

◆ getCurrentTimestamp()

SiTimeStamp* DcmSignature::getCurrentTimestamp ( )

returns the certified timestamp of the current signature if present.

Current signature must be selected with selectSignature(). May return NULL if timestamp is unavailable.

Returns
pointer to current timestamp, NULL if unavailable.

◆ getMACIDnumber()

static OFCondition DcmSignature::getMACIDnumber ( DcmItem item,
Uint16 &  macid 
)
staticprivate

searches a given item for the DCM_MACIDnumber element and returns its value if present

Parameters
itemitem to be searched
macidMAC ID returned in this parameter upon success
Returns
EC_Normal if successful, an error code otherwise

◆ getSelectedSignatureItem()

DcmItem* DcmSignature::getSelectedSignatureItem ( )

returns the item of the DigitalSignaturesSequence selected by the last call to selectSignature(), or NULL if no signature has been selected.

Returns
pointer to current signature item, may be NULL

◆ initializeLibrary()

static void DcmSignature::initializeLibrary ( )
static

initializes the dcmsign library including the underlying OpenSSL library.

this method should be called by main() before any object of the dcmsign library is created or used.

◆ inTagList()

static OFBool DcmSignature::inTagList ( const DcmTagKey tag,
const DcmAttributeTag tagList 
)
staticprivate

checks if the given tag key is present in tagList

Parameters
tagtag key
tagListlist of tag keys
Returns
OFTrue of tag is present in tagList, OFFalse otherwise

◆ numberOfSignatures()

unsigned long DcmSignature::numberOfSignatures ( )

returns the number of signatures in the dataset.

Does not count signatures embedded in sequence items within the dataset.

◆ removeSignature()

OFCondition DcmSignature::removeSignature ( unsigned long  i)

removes a signature from the dataset.

Parameters
iindex, must be < numberOfSignatures().
Returns
status code

◆ selectSignature()

OFCondition DcmSignature::selectSignature ( unsigned long  i)

selects one of the digital signatures from the attached dataset for reading.

Parameters
iindex, must be < numberOfSignatures()
Returns
status code

◆ setDumpFile()

void DcmSignature::setDumpFile ( FILE *  f)

dump all data that is fed into the MAC algorithm into the given file, which must be opened and closed by caller.

Parameters
fpointer to file already opened for writing; may be NULL.

◆ verifyCurrent()

OFCondition DcmSignature::verifyCurrent ( )

verifies the current signature.

Current signature must be selected with selectSignature().

Returns
SI_EC_Normal if signature is complete and valid, an error code describing the type of verification failure otherwise.

◆ verifySignatureProfile()

OFCondition DcmSignature::verifySignatureProfile ( SiSecurityProfile sprof)

verifies whether the currently selected signature within the currently attached dataset matches the requirements of the given signature profile.

Parameters
sprofsecurity profile
Returns
EC_Normal if signature matches, an error code otherwise

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


Generated on Thu Jan 14 2021 for DCMTK Version 3.6.6 by Doxygen 1.8.18