XML - Sign
Declaration
<AMXML ACTIVITY="sign" SESSION="text" KEYCONTAINERNAME="text" KEYCONTAINERLEVEL="user" />
Description
Signs an XML file with the specified key. Signing an XML file provides a means of verification that the file has not been modified. Use the Verify XML Document action XML - Verify activity to verify a previously signed XML file. Signatures can be added using Key Container or Public/Private Key files generated using the Generate Key Files action.
Practical usage
Used to verify if anyone has changed the original XML file.
Parameters
Resource
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Resource | --- | --- | --- | --- | Denotes
where the XML data should originate from. This is a visual mode
parameter used only during design-time, therefore, contains no
properties or markups. The available options are:
|
Session | Text | Yes, if Resource parameter is set to Session | XMLSession1 | SESSIONNAME="myXMLSession" | The name of an existing session in which to associate this activity with. As a safety measure, when a session is created, the XML file bound by that session is saved in memory and the original file is locked. Any modifications by subsequent XML related steps are performed on a copy of the XML data saved to memory. Use the XML - Export or XML - Save activity to output the in-memory representation of the XML session to a file or variable. To end the session, use the XML - End session activity. |
Create XML session from | Text (options) | Yes, if Resource parameter is set to File | Existing file |
|
Specifies
where the XML data should derive from. The XML data will be saved
into memory. Different parameters become active depending on which
option is selected. The available options are:
|
File | Text | Yes, if session created from a new or existing file | (Empty) | FILE="c:\foldername\file.XML" | The path and file name of the new or existing XML file. This parameter is active only if the Create XML session from parameter is set to Existing file or New file. |
Overwrite if file exists | Yes/No | Yes, if XML session derives from a new file | No | OVERWRITEFILE="YES" | If selected, specifies that if an XML file with the same name already exists at the specified location, it will be overwritten with the new file. If disabled (default), the step fails if the file already exists. This parameter is active only if the Create XML session from parameter is set to New file. |
Root node name | Text | Yes, if XML session derives from a new file | (Empty) | ROOTNODENAME="Fortra" | The root node name for new XML file. This parameter is active only if the Create XML session from parameter is set to New file. |
Root node value (optional) | Text | No | (Empty) | NEWVALUE="Value" | The root node value for the new XML file. This parameter is active only if the Create XML session from parameter is set to New file. |
Default namespace prefix (optional) | Text | No | (Empty) | DEFAULTNSPREFIX="edi" | The prefix of the default namespace for the new XML file. A namespace prefix is a text string assigned as an element name prefix to a namespace. When an element name is preceded by the prefix and a colon, then that element is in that assigned namespace. This parameter is active only if the Create XML session from parameter is set to New file. |
Default namespace URI (optional) | Text | No | (Empty) | DEFAULTNAMESPACE="http://net.com/schema" | The default namespace URI for the new XML file. An XML namespace is a collection of element type and attribute names that are uniquely identified by the name of the unique XML namespace of which they are a part. This parameter is active only if the Create XML session from parameter is set to New file. |
Text | Text | Yes, if XML session derives from text | (Empty) | XMLTEXT="theText" | The text that the XML data should originate from. This parameter is active only if the Start XML session from parameter is set to Text. |
Attribute Name | Text | No | (Empty) | Name="AttribName" | The name portion of the attribute name-value pair to insert. Use this parameter to insert attributes into the new node. To enter a new row of values select Click here to add new row. To delete an existing row, click the red "X." This parameter supports insertion of multiple attribute name value pairs. |
Attribute Value | Text | No | (Empty) | Value="AttribValue" | The value portion of the attribute name-value pair to insert. Use this parameter to insert attributes into the new node. To enter a new row of values select Click here to add new row. To delete an existing row, click the red "X." This parameter supports insertion of multiple attribute name value pairs. |
Sign
Property | Type | Required | Default | Markup | Description |
---|---|---|---|---|---|
Sign using | Text (options) | No | Key container |
|
The
method in which to sign the XML document. The available options
are:
|
Key container name | Text | Yes, if signing method is key container | (Empty) | KEYCONTAINERNAME="Automate" | The name of the key container to identify which private or public key to use. Click the Load button to load available key containers. Thereafter, click the down arrow and select the desired key container from the drop-down list. This parameter is available only if the Sign using parameter is set to Key container. |
Key container level | Text | Yes, if signing method is key container | User | KEYCONTAINERLEVEL="Machine" | Specifies
the level in which the keys are stored. This parameter is available
only if the Sign using
parameter is set to Key container.
The available options are:
NOTE:
For more details regarding key container levels, see Comparing machine-level and user-level RSA key containers below. |
Keypair file | Text | Yes, if signing method is key file | (Empty) | KEYPAIRFILE="c:\temp\secret.pri" | The path and file name of the public key (.pfx or .pri) file on your system in which to sign the document with. This parameter is available only if the Sign using parameter is set to Key file. |
Passphrase | Text | Yes, if signing method is key file | (Empty) | PASSWORD="encrypted" | The passphrase used to authenticate the public key. This is normally required during creation of the private key (usually used for .pfx file). This parameter is available only if the Sign using parameter is set to Key file. |
Additional notes
Comparing machine-level and user-level RSA key containers
User-level RSA key containers are stored with the Windows user profile for a particular user and can be used to encrypt and decrypt information for applications that run under that specific user identity. User-level RSA key containers can be useful if you want to ensure that the RSA key information is removed when the Windows user profile is removed. However, because you must be logged in with the specific user account that makes use of the user-level RSA key container in order to encrypt or decrypt protected configuration sections, they are inconvenient to use.
Machine-level RSA key containers are available to all users that can log in to a computer, by default, and are the most useful as you can use them to encrypt or decrypt protected configuration sections while logged in with an administrator account. A machine-level RSA key container can be used to protect information for a single application, all the applications on a server, or a group of applications on a server that run under the same user identity. Although machine-level RSA key containers are available to all users, they can be secured with NTFS Access Control Lists (ACLs) so that only required users can access them.
Examples
- Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
- To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.
Example 1
This sample task signs an XML document using key container (level USER).
<AMXML ACTIVITY="sign" SESSION=" XmlSession1" KEYCONTAINERNAME="myContainer" KEYCONTAINERLEVEL="user" />
Example 2
This sample task signs an XML file using a public/private key pair file.
<AMXML ACTIVITY="sign" SESSION="myXMLSession" SIGNUSING="keyfile" KEYPAIRFILE="C:\Temp\myKey.pri" PASSWORD="AM5WykCKDX0bNVArZePphdR/w==aME" />