DI Management Home > SC14N

SC14N, a straightforward XML canonicalization utility


The program SC14N performs the canonicalization (C14N) transformation you need to do when creating signed XML documents using XML-DSIG.

When we say "straightforward", we mean the documents not the procedure. We mean the usual XML documents you come across in practice, not the obscure corner cases using the more arcane parts of the XML specification.

If you're reading this then we assume you understand what canonicalization is and how it is used to sign an XML document. See our related pages on the topic Canonicalization of an XML document and Signing an XML document using XMLDSIG.

Contents

What SC14N does

With SC14N you can canonicalize the entire document (which you'd do for a detached signature), or exclude a given element (e.g. the Signature element for an enveloped signature), or just transform a subset of the document (e.g. the SignedInfo element, or a given Id reference). Please see Notes and Exclusions.

You can output the result to a text file, or compute the SHA-1 or SHA-256 digest value directly. The APIs allow you to work entirely in memory.

SC14N works from the Windows command-line, and has application programming interfaces for programmers using C/C++, C#, VB.NET and Python.

Example using command line

sc14n -x Signature olamundo.xml
<Envelope xmlns="http://example.org/envelope">
  <Body>
    Olá mundo
  </Body>

</Envelope>

sc14n --digest-value --exclude-bytag=Signature olamundo.xml
UWuYTYug10J1k5hKfonxthgrAR8=

Example using C#

// Example 1. Excludes the first element with the tag name <Signature>
r = C14n.ToFile("c14nfile1.txt", "input.xml", "Signature", Tran.ExcludeByTag);

// Example 2. Finds and transforms the first element with the tag name <SignedInfo>
r = C14n.ToFile("c14nfile2.txt", "input.xml", "SignedInfo", Tran.SubsetByTag);

Download

Sorry, SC14N project cancelled due to lack of interest.

Download the Trial Edition of SC14N for Windows now. Use one of

Either unzip the zip file and run the Install.exe program inside it, or download the exe program directly and run it. Minimum required operating system is Windows XP-SP2 and above (that is, XP/Vista/W7/W8/W10) or Windows Server 2003 and above. Last updated 2017-07-18: see Revision History below and the README file.

After installing, test by opening a command line window and typing sc14n --help. See Command-line syntax and examples below.

If you have tried this and are interested, please send suggestions or feedback.

Where are the files?

All reference files are installed in the directory C:\Program Files (x86)\Sc14n unless you chose otherwise during installation. You can find the files by using the menu options
Start > All Programs > Sc14n > Sc14n Reference Files
The reference files sub-folders are
C
Files for C/C++ programmers including diSc14n.h and diSc14n.lib, which you'll need to make an EXE application, and the Reference manual for C/C++ programmers. It includes the C/C++ test programs TestSc14n.c and TestSc14nPKI.c.
DotNet
Files for C# and VB.NET programmers including the .NET library diSc14nNet.dll, which you'll need to make a reference to in a .NET project, and the .NET Help. It includes the C# test programs TestSc14n.cs and TestSc14nPki.cs and their VB.NET equivalents TestSc14n.vb and TestSc14nPki.vb.
TestFiles
See Test files below.
X64
Executables for X64 platforms.

Command-line syntax and examples

sc14n --help
Usage: sc14n [OPTION]... [INFILE]
Performs the C14N transformation of a straightforward XML document.
 Mandatory arguments to long options are mandatory for short options too.
  -o, --output=OUTFILE         output to OUTFILE [default=stdout]
  -x, --exclude-bytag=TAGNAME  exclude element with name TAGNAME
  -s, --subset-bytag=TAGNAME   make subset for element with name TAGNAME
     To specify the N'th element write as `TAGNAME[N]` for N=1,2,3,...
  -X, --exclude-byid=IDVALUE   exclude element with Id="IDVALUE"
  -S, --subset-byid=IDVALUE    make subset for element with Id="IDVALUE"
     For an IDNAME other than `Id` write as `IDNAME=IDVALUE` (no quotes)
  -@, --stdin                  read input from stdin [default=INFILE]
  -d, --digest-value           output base64-encoded digest value, not XML
  -2, --sha256                 use SHA-256 algorithm with -d [default=SHA-1]
  -v, --version                print program version and exit
  -L, --libinfo                print details of core library and exit
  -h, --help                   print this help and exit
  -E, --examples               print examples and exit
The options `-x|-X|-s|-S` are mutually exclusive.
INFILE must be specified unless `--stdin` option is used.
By default the entire input XML document is transformed and output to stdout.
Exit status is 0 on success, 1 if error, or 2 if no matching data found.

For examples type `sc14n --examples`
sc14n --examples
Examples:
sc14n -o out.txt file.xml
  computes C14N transformation of entire XML document `file.xml`
  and writes result to file `out.txt`.
sc14n -x "ds:Signature" file.xml
  computes C14N transformation of XML document EXCLUDING the first
  element with tag name `ds:Signature`.
sc14n -s "ds:SignedInfo" file.xml
  computes C14N transformation of subset with tag name `ds:SignedInfo`.
sc14n -S "ref123" file.xml
  computes C14N transformation of subset with Id="ref123".
sc14n -S "myId=ref456" file.xml
  computes C14N transformation of subset with myId="ref456".
sc14n -s "elemName[3]" file.xml
  computes C14N transformation of subset for the 3rd element found
  with tag name `elemName`.
sc14n -d file.xml
  computes C14N transformation of entire XML document `file.xml`
  and outputs resulting digest value using default SHA-1 algorithm.
sc14n -d --sha256 file.xml
  computes C14N transformation of entire XML document `file.xml`
  and outputs resulting digest value using SHA-256 algorithm.

Notes

Python interface

The Python interface is provided separately. See Python Interface to SC14N.

Limitations

We don't support: We may not handle properly:

Test files

There is a set of test files in the installation directory C:\Program Files (x86)\Sc14n\TestFiles. You should make a copy of these to a less-protected directory for doing tests. Or you can download the zipped files directly.

TestFiles\testcanon
Contains example XML files derived from [XML-C14N] examples, including required DTD and TXT files, together with the "correct" results. More details in the Testcanon Examples README file.
TestFiles\signed
Contains various files that have been signed using "Alice's" signing key and should pass as valid on Aleksey Sanin's Online XML Digital Signature Verifer. We find the best way to test is to open the XML file using NotePad++, select all (Ctrl-A), then copy and paste onto the web page. This seems to prevent character encoding errors when using the clipboard.

These test signed XML documents include the <KeyInfo> as an <RSAKeyValue>. This is required by the Verifier site if you are using a test key like we are. In practice you'd probably be using a <X509Certificate> element instead.

Some examples include inline DTD !ATTLIST instructions which are required if you're using an Id reference like URI="#foo" on the xmldsig-verifier site.

Some of these files can be re-created using the function MakeSignedXml() in TestSc14nPki.cs and TestSc14nPKI.c or the Python function make_signed_xml() in test_sc14n_pki.py. Some may require a bit more cutting-and-pasting - you could easily adapt MakeSignedXml() to cope with these. For a detailed explanation of how this works, see Signing an XML-DSIG document using SC14N.

TestFiles\base
The base files used in MakeSignedXml().

Example Signed XML-DSIG Documents

Example Signed XML-DSIG Documents examined in more detail. Plus Signing an XML-DSIG document using SC14N.

Contact us

For more information about SC14N, please send us a message.

Revision History

This page first published 11 July 2017. Last updated 13 October 2017