LDicomDS::CreateSignature

#include "ltdic.h"

L_UINT16 LDicomDS::CreateSignature(pItem, pszPrivateKeyFile, pszCertificateFile, pszPassword, ppSignatureItem = NULL, pszMacTransferSyntax = NULL, uMacAlgorithm = DICOM_MAC_ALGORITHM_RIPEMD160, pElementsToSign = NULL, uCount = 0, uSecurityProfile = DICOM_SECURITY_PROFILE_NONE, uReserved = 0)

pDICOMELEMENT pItem;

/* pointer to an Item in the Data Set */

const L_TCHAR* pszPrivateKeyFile;

/* character string that contains the private key file name */

const L_TCHAR* pszCertificateFile;

/* character string that contains the digital certificate file name */

const L_TCHAR* pszPassword;

/* character string that contains the password */

pDICOMELEMENT * ppSignatureItem;

/* pointer to a pointer to the new Digital Signatures Sequence Item */

const L_TCHAR* pszMacTransferSyntax;

/* character string that contains the Message Authentication Code (MAC) Calculation Transfer Syntax UID */

L_UINT16 uMacAlgorithm;

/* value that specifies the MAC Algorithm */

L_UINT32* pElementsToSign;

/* pointer to the Data Elements to be signed */

L_UINT32 uCount;

/* value that specifies the number of Data Elements to be signed */

L_UINT16 uSecurityProfile;

/* value that specifies the Digital Signature Security Profile */

L_UINT16 uReserved;

/* reserved */

Creates a Digital Signature in the Data Set.

Parameter

Description

pItem

Pointer to a DICOMELEMENT structure that specifies an Item of a Sequence of Items in the Data Set. The Digital Signature will be created in this Item. If this parameter is set to NULL, the Digital Signature will be created in the main Data Set.

pszPrivateKeyFile

Character string that contains the name of the file that stores the private key which will be used to encrypt the Message Authentication Code (MAC). The function accepts private keys from files in any of the following formats:

 

Privacy Enhanced Mail (PEM)

 

Distinguished Encoding Rules (DER)

 

Public Key Cryptography Standard (PKCS) #8 PEM

 

PKCS#8 DER

 

PKCS#12

 

Use the parameter pszPassword to specify the password if the private key is stored encrypted.

pszCertificateFile

Character string that contains the name of the file that stores the digital certificate of the signer. This will be the Certificate of Signer (0400,0115). The function accepts X.509 digital certificates from files in any of the following formats:

 

PEM

(usually .pem, .cer, or .crt)

 

DER

(usually .cer or .crt)

 

PKCS#7 PEM

(usually .pem)

 

PKCS#7 DER

(usually .p7b or .spc)

 

PKCS#12

(usually .pfx or .p12)

 

If more than one digital certificate is stored in the file, the first one will be used.

 

For the last format (PKCS#12), use the parameter pszPassword to specify the password if the digital certificate is stored encrypted. This parameter is ignored for the rest of the formats.

 

The function will fail if the specified private key doesnt match the public key of the digital certificate.

pszPassword

Character string that contains the password to be used if the private key is stored encrypted. The password will also be used for the PKCS#12 digital certificates. Set this parameter to NULL if no password is required.

ppSignatureItem

Pointer to a pointer to a DICOMELEMENT structure. In case of success, *ppSignatureItem is updated with a pointer to the new Digital Signatures Sequence Item that corresponds to the newly created Digital Signature. This parameter can be set to NULL.

pszMacTransferSyntax

Character string that contains the MAC Calculation Transfer Syntax UID (0400,0010). This is the Transfer Syntax in which the Data Elements included in the MAC calculation should be encoded. This parameter can be set to NULL. See the Comments for more details.

uMacAlgorithm

Value that specifies the MAC Algorithm (0400,0015). This is the algorithm that should be used to generate the MAC. Possible values are:

 

 

Value

Meaning

 

DICOM_MAC_ALGORITHM_RIPEMD160

[0] Use the RACE Integrity Primitives Evaluation (RIPEMD-160) hash function (recommended).

 

DICOM_MAC_ALGORITHM_SHA1

[1] Use the Secure Hash Algorithm (SHA-1) hash function.

 

DICOM_MAC_ALGORITHM_MD5

[2] Use the Message Digest 5 (MD5) hash function.

pElementsToSign

Pointer to an array that contains the Tags of the Data Elements to be signed. The number of Tags in the array is given by the parameter uCount. If the Digital Signature is being created in the main Data Set (pItem is NULL), only Data Elements on the root of the Data Set may be referenced by the Tags. Similarly, if the Digital Signature is being created in an Item of a Sequence of Items, only Data Elements under this Item may be referenced by the Tags. This parameter can be set to NULL. See the Comments for more details.

uCount

Value that specifies the number of Tags in the array specified by the parameter pElementsToSign.

uSecurityProfile

Value that specifies the Digital Signature Security Profile with which to conform when creating the Digital Signature. Possible values are:

 

 

Value

Meaning

 

DICOM_SECURITY_PROFILE_NONE

[0] Dont conform to any Digital Signature Security Profile.

 

DICOM_SECURITY_PROFILE_BASE_RSA

[1] Conform to the Base Rivest-Shamir-Adleman (RSA) Digital Signature Profile.

 

DICOM_SECURITY_PROFILE_CREATOR_RSA

[2] Conform to the Creator RSA Digital Signature Profile.

 

DICOM_SECURITY_PROFILE_AUTHORIZATION_RSA

[3] Conform to the Authorization RSA Digital Signature Profile.

 

See the Comments for more details.

uReserved

Reserved for future use. This must be set to 0.

Returns

DICOM_SUCCESS

The function was successful.

<> DICOM_SUCCESS

An error occurred. Refer to Return Codes.

Comments

A Digital Signature can be created in the main Data Set as well as in an Item of a Sequence of Items. Pass NULL for the parameter pItem if you want to create the Digital Signature in the main Data Set or specify an Item in the Data Set to create the Digital Signature in that Item.

The parameter pszMacTransferSyntax specifies the Transfer Syntax in which the Data Elements included in the Message Authentication Code (MAC) calculation should be encoded. This Transfer Syntax must explicitly include the Value Representation (Explicit VR) and it must use the Little Endian Byte ordering. If the specified Transfer Syntax doesnt fulfill this condition, the function will behave as if the parameter were set to NULL.

If pszMacTransferSyntax is set to NULL, the function will use the Transfer Syntax in which the Data Set is currently encoded if this Transfer Syntax fulfills the condition mentioned in the previous paragraph. If it doesnt, the function will use the Explicit VR Little Endian Transfer Syntax.

You can use the parameters pElementsToSign and uCount to specify the Data Elements to be covered by the new Digital Signature. These Data Elements, which are indicated by their Tags, must be on the root of the Data Set if pItem is set to NULL. If pItem specifies an Item, then they must be located immediately under that Item. Any Tag that doesnt specify an existing Data Element in the expected location will be ignored. Also, any Tag that specifies a Data Element that cannot be signed according to the standard will be ignored as well.

If pElementsToSign is set to NULL, or if uCount is set to 0, the function will sign all the Data Elements that can be signed according to the standard and that exist on the root of the Data Set, if pItem is set to NULL, or immediately under the Item specified by pItem.

Digital Signature Security Profiles put restrictions and add specifications. For example, the Rivest-Shamir-Adleman (RSA) Security Profiles require the use of RSA encryption. Therefore, the function will fail if one of these Security Profiles is used while the specified keys are DSA keys. Another example is that the Creator and Authorization RSA Digital Signature Profiles require that, as a minimum, certain Data Elements must be signed if they exist. Therefore, if one of these Security Profiles is used, the function will sign any existing Data Element that is required, even if this Data Element is not included in the array specified by pElementsToSign.

Required DLLs and Libraries

LTDIC

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application

Platforms

Win32, x64

See Also

Functions:

LDicomDS::VerifySignature, LDicomDS::DeleteSignature, LDicomDS::GetSignatureUID, LDicomDS::GetSignatureDateTime, LDicomDS::GetSignedElement, LDicomDS::GetMacTransferSyntax, LDicomDS::GetSignature, Class Members

Topics:

Working with Digital Signatures

 

How to Disable the Automatic Loading of the default DICOM IOD Table

Example

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName
L_INT LDicomDS_CreateSignatureExample(LDicomDS& DataSet) 
{
   L_INT          nRet;
   pDICOMELEMENT  pSignatureItem; 
   // Create a Digital Signature in the main Data Set
   nRet = DataSet.CreateSignature(NULL, 
                                  MAKE_IMAGE_PATH(TEXT("PrivateKey")),
                                  MAKE_IMAGE_PATH(TEXT("Certificate.cer")),
                                  NULL, 
                                  &pSignatureItem); 
   if (nRet == DICOM_SUCCESS) 
   {
      ::MessageBox(NULL, 
                   TEXT("The Digital Signature was created successfully."), 
                   TEXT("Sample"),
                   MB_OK); 
   }
   else
   {
      L_TCHAR szMsg[64]; 
      wsprintf(szMsg, TEXT("An error occurred [Error: %hu]."), nRet); 
      ::MessageBox(NULL, szMsg, TEXT("Sample"), MB_OK); 
      return nRet; 
   }
   // Save the signed Data Set
   nRet = DataSet.SaveDS(MAKE_IMAGE_PATH(TEXT("Signed.dcm")), 0); 
   if(nRet != DICOM_SUCCESS)
      return nRet;
   // Examine the Digital Signature we just created
   // Refer to the example of LDicomDS::VerifySignature for the
   // function ExamineSignature
   ExamineSignature(DataSet, pSignatureItem); 
   return DICOM_SUCCESS;
}