Generating a SOAP Message with an RSA-Signed XML in MATLAB

Step-by-step MATLAB Code to Canonicalize XML, Create a Signature, and Insert It into a SOAP Message

Highlights

Canonicalization & Digest: Ensure the XML is in a consistent state and compute its SHA-256 digest.
RSA Signature: Encrypt the computed digest using the participant’s private key with RSA (SHA256withRSA) and encode the result in Base64.
SOAP Integration: Insert the Base64 signature directly into the SOAP message, ensuring proper XML formatting.

Introduction

This comprehensive guide explains how to generate a SOAP message embedded with an RSA signature generated by encrypting a SHA-256 digest of a canonicalized XML document in MATLAB. The main steps include:

Canonicalizing your XML representation.
Computing the SHA-256 digest of the canonical XML.
Creating an RSA signature using a participant's private key.
Encoding the binary signature into a Base64 string.
Embedding the signature into a properly formatted SOAP message.

The code presented below assumes that you have access to your private key in a PEM file format. Furthermore, note that MATLAB does not offer built-in XML canonicalization, so this example assumes that the provided XML is already in canonical form. In a production environment, you should integrate a proper XML canonicalization method or library.

Step 1: Canonicalization of the XML

Canonicalization Discussion

Canonicalization ensures that any changes in whitespace or attribute ordering do not change the computed digest. This is critical for signature validation later on. For our example, we assume the XML is canonical. If further processing is required, you may implement or call a dedicated canonicalization function (like canonicalizeXML).

Step 2: Generating the SHA-256 Digest

Computing the Hash

MATLAB can leverage Java’s security libraries to compute a SHA-256 digest. By importing the MessageDigest class from Java, you can easily compute the digest. The computed digest represents a fixed-size (256-bit) hash of your canonicalized XML. This digest will later be signed with RSA.

Step 3: RSA Signature Creation Using the Participant’s Private Key

RSA Encryption Overview

Using Java’s cryptographic libraries available in MATLAB, we can create an RSA signature. The key steps include:

Loading the private key from a PEM file. For security, the private key should be kept confidential and loaded securely.
Initializing the RSA signature object.
Signing the digest using the SHA256withRSA algorithm.

This step produces a binary signature, which is the encrypted digest using the private key.

Step 4: Encoding the Signature in Base64

Base64 Encoding Process

Since binary data can be difficult to embed directly in text-based SOAP messages, we encode the binary RSA signature using Base64. MATLAB offers the function matlab.net.base64encode to perform this conversion. This ensures that the signature is in a text-friendly format, suitable for embedding in the SOAP message.

Step 5: Embedding the Signature into the SOAP Message

SOAP Message Construction

The final step is to construct the SOAP message with the original XML document and embed the Base64-encoded signature into it. In our example, a new XML element called <Signature> is added inside the SOAP message’s body (or header, if that is your security standard) that contains the signature.

MATLAB Code Example

The following MATLAB code integrates all the steps discussed above. Make sure you adjust file paths and cryptographic library usage according to your environment.

Complete MATLAB Function

function soapMessage = generateSignedSoapMessage()
    % XML to be signed
    xmlString = '<CsbReport ApplicationType="CSB_REPORT" ParticipantName="PT_400198">'
    xmlString = [xmlString, '<ReportListRequest ReportType="STTL_STATEMENT" MarketName="BALIMB" RunType="INDICATIVE" StartDate="2024-06-09" EndDate="2024-06-09"/>'];
    xmlString = [xmlString, '</CsbReport>'];
    
    % Step 1: Canonicalization
    % Here, we assume the XML is in a canonical form. For production,
    % you may need to call a function: canonicalXML = canonicalizeXML(xmlString);
    canonicalXML = xmlString;
    
    % Step 2: Compute SHA-256 Digest using Java's MessageDigest
    import java.security.MessageDigest;
    md = MessageDigest.getInstance('SHA-256');
    % Convert the canonical XML to a byte array using proper encoding (UTF-8)
    xmlBytes = uint8(canonicalXML);
    digest = md.digest(xmlBytes);
    
    % Step 3: RSA Signature Creation using the participant's private key
    % Load private key from a PEM file. Replace 'your_private_key.pem' with the correct path.
    privateKeyFile = 'your_private_key.pem';
    if ~isfile(privateKeyFile)
        error('Private key file not found: %s', privateKeyFile);
    end
    privateKeyData = fileread(privateKeyFile);
    % Extract the portion of the key between the PEM markers
    privateKeyData = strrep(privateKeyData, '-----BEGIN PRIVATE KEY-----', '');
    privateKeyData = strrep(privateKeyData, '-----END PRIVATE KEY-----', '');
    privateKeyData = strrep(privateKeyData, char(10), ''); % Remove newlines
    
    % Decode the Base64 PEM content to obtain key bytes
    keyBytes = matlab.net.base64decode(privateKeyData);
    
    % Convert to Java byte array
    jKeyBytes = java.lang.String(keyBytes).getBytes();
    % Create a key specification using PKCS8EncodedKeySpec
    import java.security.spec.PKCS8EncodedKeySpec;
    keySpec = PKCS8EncodedKeySpec(jKeyBytes);
    
    % Generate PrivateKey object from the key specification
    import java.security.KeyFactory;
    keyFactory = KeyFactory.getInstance('RSA');
    privateKey = keyFactory.generatePrivate(keySpec);
    
    % Create and initialize the RSA signature object using SHA256withRSA algorithm
    import java.security.Signature;
    rsaSignature = Signature.getInstance('SHA256withRSA');
    rsaSignature.initSign(privateKey);
    rsaSignature.update(xmlBytes);
    
    % Sign the digest (this inherently computes the signature over the provided data)
    signatureBytes = rsaSignature.sign();
    
    % Step 4: Base64 Encode the binary signature
    base64Signature = matlab.net.base64encode(signatureBytes);
    
    % Step 5: Insert the Signature into a SOAP Message
    % Constructing a simple SOAP message with the base64-encoded signature inside <Signature> element.
    soapMessage = sprintf(['<?xml version="1.0" encoding="UTF-8"?>' ...
        '<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">' ...
        '<soap:Header>' ...
        '<Signature>%s</Signature>' ...
        '</soap:Header>' ...
        '<soap:Body>' ...
        '%s' ...
        '</soap:Body>' ...
        '</soap:Envelope>'], base64Signature, xmlString);
    
    % Display message for debugging; in a real application, you might send this message over a network.
    disp(soapMessage);
end

In this comprehensive code:

The original XML is defined in the variable xmlString.
The XML is considered canonical and then converted into a byte array in UTF-8 encoding for digest computation.
The Java MessageDigest class computes the SHA-256 digest.
The private key is loaded from a PEM file. It is then stripped of its markers and newlines, base64-decoded, and converted to a Java byte array. The PKCS8EncodedKeySpec is used to create a PrivateKey object.
The RSA signature is computed using Signature.getInstance('SHA256withRSA') and is initialized with the loaded private key. It signs the XML bytes directly.
The resulting binary signature is encoded to a Base64 string using matlab.net.base64encode.
Finally, a SOAP message is constructed that includes the XML and embeds the signature inside the <Signature> element located in the SOAP header.

Additional Details and Considerations

Error Handling and Security

The provided MATLAB script includes a basic file existence check for the private key file and halts execution with an error message if the file is not found. In a more robust application, you should enhance error handling:

Verify and handle errors during the reading and decoding of the private key file.
Confirm that the private key is in the expected format, and catch exceptions if the RSA signing process fails.
Ensure that sensitive cryptographic material, such as private keys, is managed securely and not hard-coded or exposed in version control.

Security is paramount. The private key must be securely stored, and file permissions should limit access only to authorized processes.

Canonicalization Importance

The canonicalization step, though assumed to be trivial in this example, is critical. In real-world scenarios, variations in whitespace, attribute ordering, or namespace declarations can lead to a different digest value. Implementing robust canonicalization in MATLAB may involve:

Using an external XML canonicalization library.
Employing a custom script that strictly formats and orders the XML content according to the canonical XML standard.
Verifying the canonical form through unit tests against known signatures.

RSA and Java Integration in MATLAB

MATLAB’s capability to interface with Java classes enables the use of sophisticated cryptographic functions without requiring additional toolboxes. The integration process involves:

Importing necessary Java classes directly into MATLAB.
Handling byte arrays and data conversions between MATLAB and Java.
Using the Java Signature class to perform cryptographic signing, which adheres to modern security standards like SHA256withRSA.

The method demonstrated in this code provides a clear pathway to leveraging these functionalities, although adjustments may be necessary based on your specific Java version or MATLAB release.

Table of Key Variables and Their Roles

Variable	Description
xmlString	Original XML content to be signed.
canonicalXML	Canonicalized version of the XML for consistent digest computation.
digest	SHA-256 digest computed from the XML bytes.
privateKey	RSA private key loaded from a PEM file.
signatureBytes	Binary RSA signature of the digest.
base64Signature	Base64-encoded representation of the signature.
soapMessage	Final SOAP message containing the original XML and the signature.

Conclusion

In summary, this guide has provided a detailed MATLAB code example that synthesizes several critical cryptographic processes: canonicalizing an XML document, computing its SHA-256 digest, signing the digest with RSA encryption using a participant’s private key, and embedding the resulting Base64-encoded signature into a SOAP message. Each step is crucial for ensuring that the XML message is verifiable and secure. Although the code assumes a canonical XML input, deploying this solution in a production environment would require a robust canonicalization process, enhanced error handling, and secure management of cryptographic keys. By integrating Java’s rich cryptographic libraries within MATLAB, this methodology leverages both MATLAB’s ease of use and the security features available within Java to achieve a reliable and standards-compliant signing process.