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

List of all members.

Public Member Functions

 DcmSignature ()
 default constructor
virtual ~DcmSignature ()
 destructor
void attach (DcmItem *dataset)
 attaches a DICOM dataset or item to the signature object.
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)
 creates a new digital signature in the current dataset.
unsigned long numberOfSignatures ()
 returns the number of signatures in the dataset.
OFCondition removeSignature (unsigned long i)
 removes a signature from the dataset.
OFCondition selectSignature (unsigned long i)
 selects one of the digital signatures from the attached dataset for reading.
OFCondition verifyCurrent ()
 verifies the current signature.
OFCondition getCurrentMacID (Uint16 &macID)
 returns the MAC ID of the current signature.
OFCondition getCurrentMacXferSyntaxName (OFString &str)
 returns the MAC Calculation Transfer Syntax of the current signature.
OFCondition getCurrentMacName (OFString &str)
 returns the MAC Algorithm Name of the current signature.
OFCondition getCurrentSignatureUID (OFString &str)
 returns the Digital Signature UID of the current signature.
OFCondition getCurrentSignatureDateTime (OFString &str)
 returns the Signature Date/Time of the current signature.
OFCondition getCurrentDataElementsSigned (DcmAttributeTag &desig)
 returns the Data Elements Signed attribute of the current signature if present.
SiCertificate * getCurrentCertificate ()
 returns the certificate of the current signature if present.
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.

Static Public Member Functions

static void initializeLibrary ()
 initializes the dcmsign library including the underlying OpenSSL library.
static DcmItem * findFirstSignatureItem (DcmItem &item, DcmStack &stack)
 recursively browses through the given dataset and searches the first occurence of the DigitalSignaturesSequence.
static DcmItem * findNextSignatureItem (DcmItem &item, DcmStack &stack)
 recursively browses through the given dataset and searches the next occurence of the DigitalSignaturesSequence.

Private Member Functions

 DcmSignature (DcmSignature &arg)
 private undefined copy constructor
DcmSignature & operator= (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.

Static Private Member Functions

static Uint16 getMACIDnumber (DcmItem &item)
 searches a given item for the DCM_MACIDnumber element and returns its value if present, otherwise returns 0.
static void currentDateTime (OFString &str)
 returns the current date and time as a DICOM DT string.

Private Attributes

DcmItem * currentItem
 pointer to current item if attached, NULL otherwise
DcmSequenceOfItems * macParametersSq
 pointer to mac parameters sequence of attached item, may be NULL if not attached or not yet present
DcmSequenceOfItems * signatureSq
 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.
DcmItem * selectedSignatureItem
 pointer to currently selected signature item
DcmItem * selectedMacParametersItem
 pointer to currently selected mac parameters item
SiCertificate * selectedCertificate
 pointer to certificate 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.

Definition at line 64 of file dcsignat.h.

Member Function Documentation

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:
newID upon successful return, new number is passed in this parameter
Returns:
status code

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:
dataset dataset or item to be attached

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

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:
key private key for signature creation
cert certificate with public key
mac MAC algorithm to be used for signature creation
profile security profile for signature creation
xfer transfer syntax to use when serializing DICOM data
tagList pointer 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.
timeStamp pointer to time stamp client used to create timestamps for the digital signature.
Returns:
status code

static void DcmSignature::currentDateTime (  OFString &  str  )  [static, private]
 

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

Parameters:
str date/time returned in this string.

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

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

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

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

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

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

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

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

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.

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:
desig data elements signed returned in this parameter upon success
Returns:
status code

OFCondition DcmSignature::getCurrentMacID (  Uint16 &  macID  ) 
 

returns the MAC ID of the current signature.

Current signature must be selected with selectSignature().

Parameters:
macID MAC ID returned in this parameter upon success
Returns:
status code

OFCondition DcmSignature::getCurrentMacName (  OFString &  str  ) 
 

returns the MAC Algorithm Name of the current signature.

Current signature must be selected with selectSignature().

Parameters:
str MAC algorithm name returned in this parameter upon success
Returns:
status code

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:
str transfer syntax name or UID returned in this parameter upon success
Returns:
status code

OFCondition DcmSignature::getCurrentSignatureDateTime (  OFString &  str  ) 
 

returns the Signature Date/Time of the current signature.

Current signature must be selected with selectSignature().

Parameters:
str signature date/time returned in this parameter upon success
Returns:
status code

OFCondition DcmSignature::getCurrentSignatureUID (  OFString &  str  ) 
 

returns the Digital Signature UID of the current signature.

Current signature must be selected with selectSignature().

Parameters:
str signature UID returned in this parameter upon success
Returns:
status code

static Uint16 DcmSignature::getMACIDnumber (  DcmItem &  item  )  [static, private]
 

searches a given item for the DCM_MACIDnumber element and returns its value if present, otherwise returns 0.

Parameters:
item item to be searched
Returns:
MAC ID number in item or zero if absent.

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.

unsigned long DcmSignature::numberOfSignatures (   ) 
 

returns the number of signatures in the dataset.

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

OFCondition DcmSignature::removeSignature (  unsigned long  i  ) 
 

removes a signature from the dataset.

Parameters:
i index, must be < numberOfSignatures().
Returns:
status code

OFCondition DcmSignature::selectSignature (  unsigned long  i  ) 
 

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

Parameters:
i index, must be < numberOfSignatures()
Returns:
status code

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:
f pointer to file already opened for writing; may be NULL.

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.

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

Generated on 20 Dec 2005 for OFFIS DCMTK Version 3.5.4 by Doxygen 1.4.5