SC14N, a straightforward XML canonicalization utility

The program SC14N performs the canonicalization (C14N) transformations you need to do when creating signed XML documents using XML-DSIG. It takes an input XML file and outputs the canonicalized transformation or its digest value.

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.

SC14N carries out both inclusive and exclusive canonicalization (see Notes). You can canonicalize the entire document (which you'd do for a detached signature), or omit 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).

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

You can use SC14N from the Windows command-line or use one of the programming interfaces using C#, VB.NET, C, C++, VBA, VB6 or Python.

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

2022-04-05: Released new version 3.1 of SC14N. See New in the latest version.
2021-08-03: Released new version 3.0 of SC14N.
2019-12-28: Released version 2.1.1 of Sc14n Py updated from Python 2 to Python 3.
2019-12-14: Released new version 2.1 of SC14N.
2018-11-28: Added page on exclusive C14N. See Exclusive C14N examples.
2018-11-19: Released version 2.0 of SC14N with support for exclusive c14n.

See also our new free utility xmlsq, XML Simple Query. xmlsq is a simple lightweight utility to query XML documents using XPath 1.0 and an ideal companion for SC14N. Use xmlsq to query your XML files and use SC14N to canonicalize it.

Here are two quick examples.

Example using command line

This example transforms the input XML document excluding the <Signature> element. This is the transformation used for an enveloped-signature.

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=

For the full command-line syntax see Using Sc14n from the command line.

Example using C#

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

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

For more details on using C# (and other programming languages) see Programming interfaces to SC14N.

A tip to check XML well-formedness

To check if your XML document is well-formed, just c14n the entire document and check the error message. new New in v3.0: use the --check (-k) option.

> sc14n --check notxml.xml
Error code -9: Invalid XML structure:
Error: Invalid at the top level of the document (Line: 1)

> sc14n -k olamundo-bad.xml
Error code -9: Invalid XML structure:
Error: Tag 'Envelope' was not closed (Line: 35)

> sc14n -k olamundo.xml
OK

Download

Download the Trial Edition of SC14N for Windows now. The Trial Edition is fully-functional and expires after 60 days. Please read the licence conditions for the Trial Edition and the Notes and Limitations below.

Licensed users can download the latest licensed version here.

Most recent production version 3.1.0 compiled 5 April 2022 with updated v3.1.0.1 of sc14n.exe 13 August 2023. Use either

sc14n-trial.exe (489 kB) or
sc14n-trial.zip (461 kB)

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.

Please note it is a breach of copyright to put a copy of these installation files on another server or to distribute them in any manner except by providing a link to this page.

Trouble installing: If Microsoft Defender Smartscreen gives you a warning, see Unrecognized app error. (TL;DR Click "More info" then "Run anyway"). Check that you see "Publisher: D.I. MANAGEMENT SERVICES PTY LIMITED".

After installing, test by opening a command line window and typing sc14n --help. See Command-line syntax for more details.

Check out our free XML companion utility xmlsq

Our free XML Simple Query utility xmlsq makes an ideal companion tool for SC14N. Use xmlsq to query your XML files and use SC14N to canonicalize it. xmlsq is lightweight, free and does not expire. Download now.

Buy now

You can purchase a licenced version here. (Please make sure you have tested the Trial Edition before purchase and make sure it does what you require.)

Existing licence holders can download the latest Developer Version here.

Documentation

See the documentation page

Notes

The following C14N transformations are supported:
- "inclusive canonicalization" from Canonical XML Version 1.0 (reproduced as RFC 3076) with identifiers
  http://www.w3.org/TR/2001/REC-xml-c14n-20010315
  http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments
- "exclusive canonicalization" from Exclusive XML Canonical Version 1.0 (reproduced as RFC 3741) with identifiers
  http://www.w3.org/2001/10/xml-exc-c14n#
  http://www.w3.org/2001/10/xml-exc-c14n#WithComments
Input is expected to be a well-formed XML document.
Supported XML encodings are UTF-8, ISO-8859-1 and US-ASCII.
Element and attribute names are limited to 512 characters.
Note that this program only carries out the c14n transformation on an XML document. It does not parse it to find out the transformation method or parameters. That's up to you.

Limitations

We don't support:

XSD schemas or XSLT transforms.
XPath expressions.
Xpointers (except barename/shorthand XPointer)
The C14N rules for "character references to whitespace characters other than space (#x20)" in ID and NMREF attributes (you'd never do this in practice and we don't expect this to be an issue).

Microsoft .NET incompatibility:

Microsoft made a mistake back in the early 2000s when implementing the W3C inclusive c14n algorithm. They refuse to correct their deviation from the W3C standard because, er, "backward compatibility". Go figure. See A warning about .NET.
So if you need to send signed documents to a server using MS .NET with inclusive c14n, we can't help you. (We think the bad version actually uses exclusive C14n to process the SignedData, even though it's meant to be inclusive). You'll just have to use the MS-CR*P software to reproduce the deliberate error. It should be OK with exclusive c14n, though.

New in the latest version

Changes in v3.1 (April 2022)

Added digest algorithms SHA-384 and SHA-512.
Made improvements to command-line option to deal better with redirection.

Changes in v3.0 (August 2021)

Improved command-line interface (CLI) to accept strings directly on the command line and handle UTF-8-encoded text properly in the Windows console.
Added a --check (-k) option to the CLI.
Added a new C++ (STL) interface for C++ programmers using STL (see documentation).
Improved the VBA/VB6 interface with new, improved "~2" functions using proper enumerations and more logical default arguments, plus inbuilt UTF-8 handling.
Added new documentation for VBA/VB6 interface.
Rationalised default options in the .NET interface for C# and VB.NET programmers, and removed redundant methods and deprecated options.
Added simplified documentation for .NET programmers.

Changes in v2.1 (December 2019)

Added option to compute C14N of a "flattened" XML document. See Flattening an XML document.
Fixed issues with incorrect handling of processing instructions inside a subset.

Changes in v2.0 (November 2018)

Added "exclusive canonicalization". See Notes for list of supported identifiers.
Added option to include comments in output ("#WithComments").
Fixed issues with propogation of xml:space and xml:lang attributes in a subset.
Processing instructions inside an XML document now handled correctly.
DotNET interface (C#, VB.NET) now uses optional parameters and so requires at least NET Framework 4.0.
Deprecated SC14N_TRAN_EXCLUDEBY option flags in favour of SC14N_TRAN_OMITBY. This is to help avoid confusion (!) with the new SC14N_METHOD_EXCLUSIVE flag.

References

[XML-C14N] Canonical XML Version 1.0, W3C Recommendation 15 March 2001, <http://www.w3.org/TR/2001/REC-xml-c14n-20010315/>. Republished as:
- [RFC3076] Boyer, J., Canonical XML Version 1.0, RFC 3076, March 2001.
[XML-EXC-C14N] Exclusive XML Canonicalization Version 1.0, W3C Recommendation 18 July 2002, <http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/> with errata. Republished as:
- [RFC3741] Boyer, J., D. Eastlake, J. Reagle, Exclusive XML Canonicalization, Version 1.0, RFC 3741, March 2004 with errata.

Contact us

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

Revision History

This page first published 11 July 2017. Last updated 13 August 2023

13 August 2023: Updated version 3.1.0.1 of sc14n.exe
5 April 2022: Released SC14N version 3.1.
3 August 2021: Released SC14N version 3.0.
28 December 2019: Released Sc14n Py version 2.1.1 updated from Python 2 to Python 3.
14 December 2019: Released SC14N version 2.1.
9 December 2018: Updated Sc14n Py version 2.0.0.
19 November 2018: Released SC14N version 2.0.
9 August 2018: Released SC14N version 1.0.0.
11 July 2017: First published SC14N beta version 0.9.0.

[Go to top]