Sc14n .NET Class Library 3.1.0

Classes | Methods | Enumerations | Index

Sc14n Namespace

Performs the C14N transformation of a straightforward XML document.

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.

Classes

C14n Class - Performs C14N transformation of XML document.
Err Class - Details of errors returned by the core library.
Gen Class - General info about the core library DLL.

Methods

C14n Class Methods

C14n.ToBytes Method (Byte[], String, Tran, TranMethod, String, AdvOptions)
- Performs C14N transformation of XML document (memory-to-memory with options).
C14n.ToBytes Method (String, String, Tran, TranMethod, String, AdvOptions)
- Performs C14N transformation of XML document.
C14n.ToDigest Method (Byte[], DigAlg)
- Computes digest value of inclusive C14N transformation of entire XML document (memory-to-digest).
C14n.ToDigest Method (Byte[], String, Tran, DigAlg, TranMethod, String, AdvOptions)
- Computes digest value of C14N transformation of XML document (memory-to-digest).
C14n.ToDigest Method (String, DigAlg)
- Computes digest value of inclusive C14N transformation of entire XML document (file-to-digest).
C14n.ToDigest Method (String, String, Tran, DigAlg, TranMethod, String, AdvOptions)
- Computes digest value of C14N transformation of XML document (file-to-digest).
C14n.ToFile Method
- Performs C14N transformation of XML document (file-to-file).

Err Class Methods

Err.ErrorLookup Method
- Looks up description for error code.
Err.LastError Method
- Retrieves the last error message (if available).

Gen Class Methods

Gen.CompileTime Method
- Gets date and time the core DLL module was last compiled.
Gen.LicenceType Method
- Gets licence type.
Gen.ModuleName Method
- Gets full path name of core DLL module.
Gen.Platform Method
- Gets platform on which the core DLL is running.
Gen.Version Method
- Gets version number of core diSc14n DLL.

C14n.ToBytes Method (Byte[], String, Tran, TranMethod, String, AdvOptions)

Performs C14N transformation of XML document (memory-to-memory with options).

Syntax

[C#]

public static byte[] ToBytes(
	byte[] xmlData,
	string nameOrId,
	Tran tranOpt,
	TranMethod tranMethod,
	string exclParams,
	AdvOptions advOpts
)

[VB.NET]

Public Shared Function ToBytes ( _
	xmlData As Byte(), _
	nameOrId As String, _
	tranOpt As Tran, _
	tranMethod As TranMethod, _
	exclParams As String, _
	advOpts As AdvOptions _
) As Byte()

Parameters

xmlData: XML data to be processed.
nameOrId: Tag name or Id to include or omit [optional, default=""]. See remarks for C14n.ToFile.
tranOpt: Type: Tran
Transformation option [optional, default=Tran.Entire].
tranMethod: Type: TranMethod
Transformation method [optional, default=TranMethod.Inclusive].
exclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n [optional, default=""].
advOpts: Type: AdvOptions
Option flags [optional, default=0].

Return Value

UTF-8 encoded byte array

C14n.ToBytes Method (String, String, Tran, TranMethod, String, AdvOptions)

Performs C14N transformation of XML document.

Syntax

[C#]

public static byte[] ToBytes(
	string xmlFile,
	string nameOrId,
	Tran tranOpt,
	TranMethod tranMethod,
	string exclParams,
	AdvOptions advOpts
)

[VB.NET]

Public Shared Function ToBytes ( _
	xmlFile As String, _
	nameOrId As String, _
	tranOpt As Tran, _
	tranMethod As TranMethod, _
	exclParams As String, _
	advOpts As AdvOptions _
) As Byte()

Parameters

xmlFile: Name of input XML file.
nameOrId: Tag name or Id to include or omit [optional, default=""]. See remarks for C14n.ToFile.
tranOpt: Type: Tran
Transformation option [optional, default=Tran.Entire].
tranMethod: Type: TranMethod
Transformation method [optional, default=TranMethod.Inclusive].
exclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n [optional, default=""].
advOpts: Type: AdvOptions
Option flags [optional, default=0].

Return Value

UTF-8 encoded byte array

C14n.ToDigest Method (Byte[], DigAlg)

Computes digest value of inclusive C14N transformation of entire XML document (memory-to-digest).

Syntax

[C#]

public static string ToDigest(
	byte[] xmlData,
	DigAlg digAlg
)

[VB.NET]

Public Shared Function ToDigest ( _
	xmlData As Byte(), _
	digAlg As DigAlg _
) As String

Parameters

xmlData: XML data to be processed
digAlg: Type: DigAlg
Digest algorithm

Return Value

Digest value in base64 encoding or empty string on error (for more details use Err.LastError).

C14n.ToDigest Method (Byte[], String, Tran, DigAlg, TranMethod, String, AdvOptions)

Computes digest value of C14N transformation of XML document (memory-to-digest).

Syntax

[C#]

public static string ToDigest(
	byte[] xmlData,
	string nameOrId,
	Tran tranOpt,
	DigAlg digAlg,
	TranMethod tranMethod,
	string exclParams,
	AdvOptions advOpts
)

[VB.NET]

Public Shared Function ToDigest ( _
	xmlData As Byte(), _
	nameOrId As String, _
	tranOpt As Tran, _
	digAlg As DigAlg, _
	tranMethod As TranMethod, _
	exclParams As String, _
	advOpts As AdvOptions _
) As String

Parameters

xmlData: XML data to be processed
nameOrId: Tag name or Id to include or omit [optional, default=""]. See remarks for C14n.ToFile.
tranOpt: Type: Tran
Transformation option [optional, default=Tran.Entire].
digAlg: Type: DigAlg
Digest algorithm [optional, default=DigAlg.Default SHA-1]
tranMethod: Type: TranMethod
Transformation method [optional, default=TranMethod.Inclusive].
exclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n [optional, default=""].
advOpts: Type: AdvOptions
Option flags [optional, default=0].

Return Value

Digest value in base64 encoding or empty string on error (for more details use Err.LastError).

C14n.ToDigest Method (String, DigAlg)

Computes digest value of inclusive C14N transformation of entire XML document (file-to-digest).

Syntax

[C#]

public static string ToDigest(
	string xmlFile,
	DigAlg digAlg
)

[VB.NET]

Public Shared Function ToDigest ( _
	xmlFile As String, _
	digAlg As DigAlg _
) As String

Parameters

xmlFile: Name of input XML file.
digAlg: Type: DigAlg
Digest algorithm

Return Value

Digest value in base64 encoding or empty string on error (for more details use Err.LastError).

C14n.ToDigest Method (String, String, Tran, DigAlg, TranMethod, String, AdvOptions)

Computes digest value of C14N transformation of XML document (file-to-digest).

Syntax

[C#]

public static string ToDigest(
	string xmlFile,
	string nameOrId,
	Tran tranOpt,
	DigAlg digAlg,
	TranMethod tranMethod,
	string exclParams,
	AdvOptions advOpts
)

[VB.NET]

Public Shared Function ToDigest ( _
	xmlFile As String, _
	nameOrId As String, _
	tranOpt As Tran, _
	digAlg As DigAlg, _
	tranMethod As TranMethod, _
	exclParams As String, _
	advOpts As AdvOptions _
) As String

Parameters

xmlFile: Name of input XML file.
nameOrId: Tag name or Id to include or omit [optional, default=""]. See remarks for C14n.ToFile.
tranOpt: Type: Tran
Transformation option [optional, default=Tran.Entire].
digAlg: Type: DigAlg
Digest algorithm [optional, default=DigAlg.Default SHA-1]
tranMethod: Type: TranMethod
Transformation method [optional, default=TranMethod.Inclusive].
exclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n [optional, default=""].
advOpts: Type: AdvOptions
Option flags [optional, default=0].

Return Value

Digest value in base64 encoding or empty string on error (for more details use Err.LastError).

C14n.ToFile Method

Performs C14N transformation of XML document (file-to-file).

Syntax

[C#]

public static int ToFile(
	string outFile,
	string xmlFile,
	string nameOrId,
	Tran tranOpt,
	TranMethod tranMethod,
	string exclParams,
	AdvOptions advOpts
)

[VB.NET]

Public Shared Function ToFile ( _
	outFile As String, _
	xmlFile As String, _
	nameOrId As String, _
	tranOpt As Tran, _
	tranMethod As TranMethod, _
	exclParams As String, _
	advOpts As AdvOptions _
) As Integer

Parameters

outFile: Name of output file to create.
xmlFile: Name of input XML file.
nameOrId: Tag name or Id to include or omit [optional, default=""] (see remarks below).
tranOpt: Type: Tran
Transformation option [optional, default=Tran.Entire].
tranMethod: Type: TranMethod
Transformation method [optional, default=TranMethod.Inclusive].
exclParams: InclusiveNamespaces PrefixList parameter for exclusive c14n [optional, default=""].
advOpts: Type: AdvOptions
Option flags [optional, default=0].

Return Value

0 if successful or non-zero error code.

Remarks

Use the nameOrId parameter to specify the element of the XML document to include or omit.

With options OmitByTag or SubsetByTag, nameOrId specifies the element's tag name.

By default, the first element with a matching tag name will be chosen.
To specify the Nth element, write as tagname[N] where N=1,2,3,...

With options OmitById or SubsetById, nameOrId specifies the element's Id.

The default Id attribute name is Id, so the argument myvalue will find the element with attribute Id="myvalue".
To use a different attribute name - for example ID - write in the form ID=myvalue with no quotes.

With option Entire, the parameter is ignored, so just use "" or null.

Exactly one element will be omitted or included. Tag names and Id values are case sensitive. It is an error (NO_DATA_ERROR) if no matching element is found.

Example

[C#]

// Example 1. Omits 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);

// Example 3. Finds and transforms the third element with the tag name <Data>
r = C14n.ToFile("c14nfile3.txt", "input.xml", "Data[3]", Tran.SubsetByTag);

// Example 4. Finds and transforms the element with attribute Id="foo"
r = C14n.ToFile("c14nfile4.txt", "input.xml", "foo", Tran.SubsetById);

// Example 5. Finds and transforms the element with attribute ID="bar"
r = C14n.ToFile("c14nfile5.txt", "input.xml", "ID=bar", Tran.SubsetById);

// Example 6. Omits element with attribute Id="thesig"
r = C14n.ToFile("c14nfile6.txt", "input.xml", "thesig", Tran.OmitById);

Err.ErrorLookup Method

Looks up description for error code.

Syntax

[C#]

public static string ErrorLookup(
	int errCode
)

[VB.NET]

Public Shared Function ErrorLookup ( _
	errCode As Integer _
) As String

Parameters

errCode: Value of error code to lookup (may be positive or negative)

Return Value

Corresponding error message

Err.LastError Method

Retrieves the last error message (if available).

Syntax

[C#]

public static string LastError()

[VB.NET]

Public Shared Function LastError As String

Return Value

Error message from last call (may be empty)

Remarks

Call this immediately when an error is indicated. Calling another method will overwrite the message.

Gen.CompileTime Method

Gets date and time the core DLL module was last compiled.

Syntax

[C#]

public static string CompileTime()

[VB.NET]

Public Shared Function CompileTime As String

Return Value

Date and time string

Gen.LicenceType Method

Gets licence type.

Syntax

[C#]

public static char LicenceType()

[VB.NET]

Public Shared Function LicenceType As Char

Return Value

D=Developer T=Trial

Remarks

Note the Australian/English spelling of "Licence".

Gen.ModuleName Method

Gets full path name of core DLL module.

Syntax

[C#]

public static string ModuleName()

[VB.NET]

Public Shared Function ModuleName As String

Return Value

File name

Gen.Platform Method

Gets platform on which the core DLL is running.

Syntax

[C#]

public static string Platform()

[VB.NET]

Public Shared Function Platform As String

Return Value

"Win32" or "Win64"

Gen.Version Method

Gets version number of core diSc14n DLL.

Syntax

[C#]

public static int Version()

[VB.NET]

Public Shared Function Version As Integer

Return Value

Version number in form Major * 10000 + Minor * 100 + Release

Remarks

E.g. version 1.2.3 returns 10203

Enumerations

AdvOptions Enumeration - Advanced option flags
DigAlg Enumeration - Digest Algorithm
Tran Enumeration - Transformation options to specify the document part to be canonicalized.
TranMethod Enumeration - Transformation methods

AdvOptions Enumeration

Advanced option flags

Syntax

[C#]

[FlagsAttribute]
public enum AdvOptions

[VB.NET]

<FlagsAttribute> _
Public Enumeration AdvOptions

Members

	Member name	Description
	Default	Default options.
	Flatten	Flatten the XML - remove all ignorable whitespace between tags.

DigAlg Enumeration

Digest Algorithm

Syntax

[C#]

public enum DigAlg

[VB.NET]

Public Enumeration DigAlg

Members

	Member name	Description
	Default	Use default digest algorithm (SHA-1)
	Sha1	Use SHA-1 digest algorithm (default)
	Sha256	Use SHA-256 digest algorithm
	Sha384	Use SHA-384 digest algorithm
	Sha512	Use SHA-512 digest algorithm

Tran Enumeration

Transformation options to specify the document part to be canonicalized.

Syntax

[C#]

public enum Tran

[VB.NET]

Public Enumeration Tran

Members

	Member name	Description
	Entire	Transform the entire document.
	OmitByTag	Omit the element with the given tag name.
	OmitById	Omit the element with the given Id.
	SubsetByTag	Transform the subset with the given tag name.
	SubsetById	Transform the subset with the given Id.

TranMethod Enumeration

Transformation methods

Syntax

[C#]

public enum TranMethod

[VB.NET]

Public Enumeration TranMethod

Members

	Member name	Description
	Inclusive	Inclusive C14N without comments from RFC 3076.
	Exclusive	Exclusive C14N without comments from RFC 3741.
	InclusiveWithComments	Inclusive C14N with comments from RFC 3076.
	ExclusiveWithComments	Exclusive C14N with comments from RFC 3741.

Err Class
Gen Class
Methods

Sc14n Namespace