Leadtools.Dicom Requires Medical product license | Send comments on this topic. | Back to Introduction - All Topics | Help Version 16.5.9.25
CreateSignature Method
See Also  Example
Leadtools.Dicom Namespace > DicomDataSet Class : CreateSignature Method



item
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.
privateKeyFile
The name of the file that stores the private key which will be used to encrypt the Message Authentication Code (MAC). The method 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 password to specify the password if the private key is stored encrypted.

certificateFile
The name of the file that stores the digital certificate of the signer. This will be the Certificate of Signer (0400,0115). The method 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 to specify the password if the digital certificate is stored encrypted. This parameter is ignored for the rest of the formats.

The method will fail if the specified private key does not match the public key of the digital certificate.

password
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.
macTransferSyntax
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 Remarks for more details.
macAlgorithm
The MAC Algorithm (0400,0015). This is the algorithm that should be used to generate the MAC.
elementsToSign
An array that contains the Tags of the Data Elements to be signed. If the Digital Signature is being created in the main Data Set (item 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 Remarks for more details.
securityProfile
The Digital Signature Security Profile with which to conform when creating the Digital Signature.
item
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.
privateKeyFile
The name of the file that stores the private key which will be used to encrypt the Message Authentication Code (MAC). The method 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 password to specify the password if the private key is stored encrypted.

certificateFile
The name of the file that stores the digital certificate of the signer. This will be the Certificate of Signer (0400,0115). The method 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 to specify the password if the digital certificate is stored encrypted. This parameter is ignored for the rest of the formats.

The method will fail if the specified private key does not match the public key of the digital certificate.

password
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.
macTransferSyntax
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 Remarks for more details.
macAlgorithm
The MAC Algorithm (0400,0015). This is the algorithm that should be used to generate the MAC.
elementsToSign
An array that contains the Tags of the Data Elements to be signed. If the Digital Signature is being created in the main Data Set (item 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 Remarks for more details.
securityProfile
The Digital Signature Security Profile with which to conform when creating the Digital Signature.
Creates a Digital Signature in the Data Set.

Syntax

Visual Basic (Declaration) 
Public Function CreateSignature( _
   ByVal item As DicomElement, _
   ByVal privateKeyFile As String, _
   ByVal certificateFile As String, _
   ByVal password As String, _
   ByVal macTransferSyntax As String, _
   ByVal macAlgorithm As DicomMacAlgorithm, _
   ByVal elementsToSign() As Long, _
   ByVal securityProfile As DicomSecurityProfile _
) As DicomElement
Visual Basic (Usage)Copy Code
Dim instance As DicomDataSet
Dim item As DicomElement
Dim privateKeyFile As String
Dim certificateFile As String
Dim password As String
Dim macTransferSyntax As String
Dim macAlgorithm As DicomMacAlgorithm
Dim elementsToSign() As Long
Dim securityProfile As DicomSecurityProfile
Dim value As DicomElement
 
value = instance.CreateSignature(item, privateKeyFile, certificateFile, password, macTransferSyntax, macAlgorithm, elementsToSign, securityProfile)

Parameters

item
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.
privateKeyFile
The name of the file that stores the private key which will be used to encrypt the Message Authentication Code (MAC). The method 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 password to specify the password if the private key is stored encrypted.

certificateFile
The name of the file that stores the digital certificate of the signer. This will be the Certificate of Signer (0400,0115). The method 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 to specify the password if the digital certificate is stored encrypted. This parameter is ignored for the rest of the formats.

The method will fail if the specified private key does not match the public key of the digital certificate.

password
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.
macTransferSyntax
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 Remarks for more details.
macAlgorithm
The MAC Algorithm (0400,0015). This is the algorithm that should be used to generate the MAC.
elementsToSign
An array that contains the Tags of the Data Elements to be signed. If the Digital Signature is being created in the main Data Set (item 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 Remarks for more details.
securityProfile
The Digital Signature Security Profile with which to conform when creating the Digital Signature.

Return Value

The new Digital Signatures Sequence Item that corresponds to the newly created Digital Signature.

Example

This example will create a new digital signature.

Visual BasicCopy Code
Public Sub CreateSignature()
   Dim dicomFileName As String = LeadtoolsExamples.Common.ImagesPath.Path + "IMAGE3.dic"
   'Make sure to initialize the DICOM engine, this needs to be done only once
   'In the whole application
   DicomEngine.Startup()

   Dim ds As DicomDataSet = New DicomDataSet()
   Using (ds)
      'Load DICOM File
      ds.Load(dicomFileName, DicomDataSetLoadFlags.None)
      ds.CreateSignature(Nothing, LeadtoolsExamples.Common.ImagesPath.Path + "PrivateKey", LeadtoolsExamples.Common.ImagesPath.Path + "Certificate.cer", Nothing, Nothing, DicomMacAlgorithm.Ripemd160, Nothing, DicomSecurityProfile.None)
      ' Save the signed Data Set
      ds.Save(LeadtoolsExamples.Common.ImagesPath.Path + "Signed.dic", DicomDataSetSaveFlags.None)
   End Using

   DicomEngine.Shutdown()
End Sub
C#Copy Code
public void CreateSignature() 

   string dicomFileName = LeadtoolsExamples.Common.ImagesPath.Path + "IMAGE3.dic"; 
   //Make sure to initialize the DICOM engine, this needs to be done only once  
   //In the whole application 
   DicomEngine.Startup(); 
   using (DicomDataSet ds = new DicomDataSet()) 
   { 
      //Load DICOM File 
      ds.Load(dicomFileName, DicomDataSetLoadFlags.None); 
      ds.CreateSignature(null, 
                                       LeadtoolsExamples.Common.ImagesPath.Path + "PrivateKey", 
                                       LeadtoolsExamples.Common.ImagesPath.Path + "Certificate.cer", 
                                       null, 
                                       null, 
                                       DicomMacAlgorithm.Ripemd160, 
                                       null, 
                                       DicomSecurityProfile.None); 
      // Save the signed Data Set 
      ds.Save(LeadtoolsExamples.Common.ImagesPath.Path + "Signed.dic", DicomDataSetSaveFlags.None); 
   } 
   DicomEngine.Shutdown(); 
}

Remarks

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 item 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 macTransferSyntax 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 does not fulfill this condition, the method will behave as if the parameter were set to null.

If macTransferSyntax is set to null, the method 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 does not, the method will use the Explicit VR Little Endian Transfer Syntax.

You can use the parameter elementsToSign 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 item is set to null. If item specifies an Item, then they must be located immediately under that Item. Any Tag that doesn't 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 elementsToSign is set to null, the method 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 item is set to null, or immediately under the Item specified by item.

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 method 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 method will sign any existing Data Element that is required, even if this Data Element is not included in the array specified by elementsToSign.

Requirements

Target Platforms: Microsoft .NET Framework 3.0, Windows XP, Windows Server 2003 family, Windows Server 2008 family

See Also

Leadtools.Dicom requires a Medical toolkit server license and unlock key. For more information, refer to: Imaging Pro/Document/Medical Features