Documentation | CodeSign Secure

XML Signing

For XML signing, we use XMLSecTool which is a powerful command-line tool that provides a range of functionalities for securing XML documents. Combining with our PKCS11 Wrapper Tool, you will be easily able to digitally sign XML files and ensure their integrity and authenticity.

For Linux - Ubuntu

To perform XML Signing using XMLSec Tool and our PKCS11 Wrapper in Linux (Ubuntu) machine, you would need to follow the below steps:

Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your Ubuntu machine.

PKCS11 Wrapper Linux

Next we will need to download the latest version of XMLSec Tool (xmlsectool-3.0.0-bin.zip) using this link. You will need to extract the zip file into a directory of your choice.

XMLSec Tool Download

Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper_Ubuntu).

XMLSec Tool Download Directory

Open the "pkcs11properties.cfg" file in a text editor and update it with the correct library path. (ec_pkcs11client.so)

PKCS11 Properties Update

NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

Configuration setup in Luna

Open the "ec_pkcs11client.ini" file in a text editor and update the following fields:

name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
url - verify the server url of your CodeSign Secure portal.
username - provide the username of CodeSign Secure account
passcode - provide the secret passcode which was used to setup CodeSign Secure portal
path - Provide the path location of your SSL Authentication certificate.
passwd - Provide the password of your SSL Authentication certificate.

NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authentication Certificate" option.

Generate Authentication Certificate

The initialization file should look like this with all the correct file paths and settings.

PKCS11 Initialization

Now we need to add the environment variable for the pkcs11 client library.

Run the below command to open the bashrc file:
```
nano ~/.bashrc
```
Now add the EC_INI_FILE_PATH variable with the path of the .ini at the end of the bashrc file, like:
```
export EC_INI_FILE_PATH=/home/administrator/PKCS11_Wrapper-Ubuntu/ec_pkcs11client.ini
                  
```
Press Ctrl+X, then enter Y, and then press Enter to save.

Reload the environment variables
```
source ~/.bashrc
                  
```
Check whether the variable has been set correctly
```
echo $EC_INI_FILE_PATH
                  
```
NOTE: If you can't see the file location from echo commands, open a new terminal and try again.
Now, you would need to download and install Java in your Ubuntu machine.
Open Terminal from interface or press (Ctrl+Alt+T). Run the below commands to install the Amazon corretto 17 java version on your machine.

You can check other supported Java versions with XMLSec Tool here.

wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor -o /usr/share/keyrings/corretto-keyring.gpg && \
echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list

Now install the package using the below command

sudo apt-get update; sudo apt-get install -y java-17-amazon-corretto-jdk

To check whether Java has installed properly or not, run the below command:

java -version

Now, you would need to add a "JAVA_HOME" environment variable in your system. Run the below command to find the correct path of Java in your system.
```
update-alternatives --config java
                
```
It might ask you to choose between paths if you have multiple Java versions installed. Enter the number which corresponds to your Java version.

The path will look something similar to this: /usr/lib/jvm/java-17-amazon-corretto/bin/java
Before you set the JAVA_HOME variable system wide in the environment file, you should take a backup of the environment file.

cp ~/.bashrc ~/.bashrc.bak

NOTE: If you make an error while setting the environment variables, you can restore this backup with:

cp ~/.bashrc.bak ~/.bashrc

NOTE: Alternatively, cp /etc/skel/.bashrc ~/ resets the file to the system default. This discards all customisations, including any environment variables (such as EC_INI_FILE_PATH) you set earlier, not just the JAVA_HOME change.

Replace the path of Java file before running the below command to set the JAVA_HOME variable.
```
echo "export JAVA_HOME=/usr/lib/jvm/java-17-amazon-corretto" >> ~/.bashrc
                  
```
NOTE: Only add the path till the main directory i.e. java-17-amazon-corretto
Check the last 3 lines of the file to verify the change by running the below command
```
tail -3 ~/.bashrc
                  
```
Run the below command to reload the environment variable

source ~/.bashrc

You would also need to install some other pre-requisite packages to perform XML signing.

sudo apt-get install curl
sudo apt-get install liblog4cxx-dev
sudo apt-get install liblog4cxx12

NOTE: If "sudo apt-get install liblog4cxx12" command gives error, run the following steps to install this package

For amd architecture:

wget http://archive.ubuntu.com/ubuntu/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_amd64.deb
sudo dpkg -i liblog4cxx12_0.12.1-4_amd64.deb

For arm architecture:

wget http://ports.ubuntu.com/pool/universe/l/log4cxx/liblog4cxx12_0.12.1-4_arm64.deb
sudo dpkg -i liblog4cxx12_0.12.1-4_arm64.deb

We are now ready with our environment to perform the XML signing using XMLSec tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.

Change Working Directory

Now, run the signing command from this directory.

<Path of xmlsectool.sh file> --sign --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of XML file> --outFile <Path of the signed XML file>

A sample command is provided below:

../xmlsectool-3.0.0-bin/xmlsectool-3.0.0/xmlsectool.sh --sign --pkcs11Config pkcs11properties.cfg --keyAlias DemoCertificate --keyPassword NONE --inFile ../xmlSample.xml --outFile ../out-xmlSample.xml

Verification

For Verification, run the following command:

<Path of xmlsectool.sh file> --verifySignature --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of the signed XML file>

A sample command is provided below:

../xmlsectool-3.0.0-bin/xmlsectool-3.0.0/xmlsectool.sh --verifySignature --pkcs11Config pkcs11properties.cfg --keyAlias DemoCertificate --keyPassword NONE --inFile ../out-xmlSample.xml

For MacOS

To perform XML Signing using XMLSec Tool and our PKCS11 Wrapper in MacOS machine, you would need to follow the below steps:

Download our PKCS11 Wrapper Tool from CodeSign Secure portal in the Signing Tools section in your MacOS.

PKCS11 Wrapper MAC

Go to your PKCS11 Wrapper directory (../PKCS11_Wrapper-Mac) and update the "pkcs11properties.cfg" and "ec_pkcs11client.ini" with the required details.

For "pkcs11properties.cfg", update the library path.

NOTE: When using Luna HSM, add the slot number in the pkcs11properties.cfg file as shown below:

Configuration setup in Luna

For "ec_pkcs11client.ini" file, update the following fields:

name - provide the path location of the Log xml file you downloaded with the PKCS11 Wrapper tool. (EC_PKCS11_CLIENT-LogConfig.xml)
url - verify the server url of your CodeSign Secure portal.
username - provide the username of CodeSign Secure account
passcode - provide the secret passcode which was used to setup CodeSign Secure portal
path - Provide the path location of your SSL Authentication certificate.
passwd - Provide the password of your SSL Authentication certificate.

NOTE: To create the SSL Auth Certificate, go to the CodeSign Secure Portal -> System Setup -> User. From the right drop down, select the "Generate Authentication Certificate" option.

Generate Authentication Certificate

The initialization and configuration files should look like this with all the correct file paths and settings.

PKCS11 Initialization MAC

Next we will need to download the latest version of XMLSec Tool (xmlsectool-3.0.0-bin.zip) using this link. You will need to extract the zip file into a directory of your choice.

XMLSec Tool Download

You will need this shell file to perform the XML signing

XMLSec Tool Directory Mac

Now, you would need to download and install Java in your MacOS machine. Download .pkg file of Amazon corretto 17 java version on your MacOS machine using this link.
You can check other supported Java versions with XMLSec Tool here.
Double-click the downloaded file to begin the installation wizard and follow the steps in the wizard.

XMLSec Java MAC

To check whether Java has installed properly or not, run the below command:

java -version

Now, you would need to add a "JAVA_HOME" environment variable in your system. Run the below command to find the correct path of Java in your system.
First you will need to get the complete installation path using the below command

/usr/libexec/java_home --verbose

XMLSec Java Path

Replace the path of Java file before running the below command to set the JAVA_HOME variable.

echo 'export JAVA_HOME="/Library/Java/JavaVirtualMachines/amazon-corretto-17.jdk/Contents/Home"' >> ~/.zshrc

Run the below command to reload the environment variable

source ~/.zshrc

You would also need to install some other pre-requisite packages to perform XML signing.

brew install log4cxx
brew install curl

We are now ready with our MacOS environment to perform the XML signing using XMLSec tool and PKCS11 Wrapper

Signing

For Signing, change the working directory of the terminal to that folder which contains your "ec_pkcs11client.ini" file.

Now, run the signing command from this directory.

<Path of xmlsectool.sh file> --sign --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of XML file> --outFile <Path of the signed XML file>

A sample command is provided below:

../xmlsectool-3.0.0/xmlsectool.sh --sign --pkcs11Config pkcs11properties.cfg --keyAlias gpg2 --keyPassword NONE --inFile ../sample.xml --outFile  SignedSample.xml

Verification

For Verification, run the following command:

<Path of xmlsectool.sh file> --verifySignature --pkcs11Config <Path of pkcs11properties.cfg> --keyAlias <Key alias of the signing certificate> --keyPassword NONE --inFile <Path of the signed XML file>

A sample command is provided below:

../xmlsectool-3.0.0/xmlsectool.sh --verifySignature --pkcs11Config pkcs11properties.cfg --keyAlias gpg2 --keyPassword NONE --inFile ../SignedSample.xml

On this Page: