The C/C++ interface to the diSc14n.dll library. More...

Macros
#define	SC14N_DIG_DEFAULT 0
	Use default digest algorithm (SHA-1)

#define	SC14N_DIG_SHA1 0
	Use SHA-1 digest algorithm (default)

#define	SC14N_DIG_SHA256 0x2000
	Use SHA-256 digest algorithm.

#define	SC14N_DIG_SHA384 0x3000
	Use SHA-384 digest algorithm.

#define	SC14N_DIG_SHA512 0x5000
	Use SHA-512 digest algorithm.

#define	SC14N_MAX_DIGEST_CHARS 88
	Maximum number of characters in base64-encoded hash digest value.

#define	SC14N_MAX_ERROR_CHARS 4073
	Maximum number of characters in an error message.

#define	SC14N_METHOD_EXCLUSIVE 0x100
	Use exclusive c14n method [RFC 3741].

#define	SC14N_METHOD_INCLUSIVE 0
	Use inclusive c14n method [RFC 3076] (default)

#define	SC14N_METHOD_WITHCOMMENTS 0x800
	Include comments in c14n form (`#WithComments`)

#define	SC14N_OPT_FLATTEN 0x10000
	Flatten the XML - remove all ignorable whitespace between tags.

#define	SC14N_TRAN_ENTIRE 0
	Transform the entire document (default)

#define	SC14N_TRAN_OMITBYID 0x11
	Omit the element with the given Id.

#define	SC14N_TRAN_OMITBYTAG 0x01
	Omit the element with the given tag name.

#define	SC14N_TRAN_SUBSETBYID 0x12
	Transform the subset with the given Id.

#define	SC14N_TRAN_SUBSETBYTAG 0x02
	Transform the subset with the given tag name.

Functions
long	C14N_File2Digest (char szOut, long nOutChars, const char szInputFile, const char szNameOrId, const char szParams, long nOptions)
	Computes digest value of C14N transformation (file-to-digest). More...

long	C14N_File2File (const char szOutputFile, const char szInputFile, const char szNameOrId, const char szParams, long nOptions)
	Performs C14N transformation of XML document (file-to-file). More...

long	C14N_File2String (char szOut, long nOutChars, const char szInputFile, const char szNameOrId, const char szParams, long nOptions)
	Performs C14N transformation of XML document (file-to-memory). More...

long	C14N_String2Digest (char szOut, long nOutChars, const void lpDataIn, long nDataLen, const char szNameOrId, const char szParams, long nOptions)
	Computes digest value of C14N transformation (memory-to-digest). More...

long	C14N_String2String (char szOut, long nOutChars, const void lpDataIn, long nDataLen, const char szNameOrId, const char szParams, long nOptions)
	Performs C14N transformation of XML document (memory-to-memory). More...

long	SC14N_Err_ErrorLookup (char *szOut, long nOutChars, long nErrCode)
	Looks up description for error code. More...

long	SC14N_Err_LastError (char *szOut, long nOutChars)
	Retrieves the last error message (if available). More...

long	SC14N_Gen_CompileTime (char *szOut, long nOutChars)
	Gets date and time the core DLL module was last compiled. More...

long	SC14N_Gen_LicenceType (void)
	Gets licence type. More...

long	SC14N_Gen_ModuleName (char *szOut, long nOutChars, long nOptions)
	Gets full path name of core DLL module. More...

long	SC14N_Gen_Platform (char *szOut, long nOutChars)
	Gets platform on which the core DLL is running ("Win32" or "Win64"). More...

long	SC14N_Gen_Version (void)
	Gets version number of the core DLL. More...

long	SC14N_Utf8FromWide (char szOut, long nOutChars, const wchar_t wstr)
	Maps a UTF-16 (wide character) string to a UTF-8-encoded string. More...

Detailed Description

The C/C++ interface to the diSc14n.dll library.

Supported XML Canonicalization Transformations

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 Canonicalization 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

I

dentifier	nOptions
`http://www.w3.org/TR/2001/REC-xml-c14n-20010315`	`0`
`http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments`	`#SC14N_METHOD_WITHCOMMENTS`
`http://www.w3.org/2001/10/xml-exc-c14n#`	`#SC14N_METHOD_EXCLUSIVE`
`http://www.w3.org/2001/10/xml-exc-c14n#WithComments`	`#SC14N_METHOD_EXCLUSIVE` \| `#SC14N_METHOD_WITHCOMMENTS`

Supported XML encodings: Input is expected to be a well-formed XML document. Supported XML encodings are UTF-8, ISO-8859-1 and US-ASCII.

Output to szOut buffer: Functions that provide output in szOut require the buffer to be pre-dimensioned (i.e. allocated) to at least the specified length nOutChars PLUS one extra for the null-terminating byte. These functions always return the total length in bytes of the string they tried to create. To find the required length, pass a NULL szOut or zero nOutChars argument, then add one to the result for the required buffer size.

For example:

char *xmlfile = "test.xml";
long nchars;
char *lpszOut;
// Find out how many bytes we need
nchars = C14N_File2String(NULL, 0, xmlfile, "", 0);
if (nchars <= 0) error();
// Pre-dimension, i.e allocate memory for string buffer
lpszOut = malloc(nchars+1);  // NB +1
if (!lpszOut) error();
nchars = C14N_File2String(lpszOut, nchars, xmlfile, "", 0);
// ...
// do something with lpszOut...
// ...
free(lpszOut);

or, for an output buffer of a known length:

char digval[SC14N_MAX_DIGEST_CHARS + 1];
long r = C14N_File2Digest(digval, sizeof(digval) - 1, "input.xml", "Signature", "", SC14N_TRAN_OMITBYTAG);
printf("DIG1=%s\n", digval);

Specifying the tag name or Id with szNameOrId: Use the szNameOrId parameter to specify the element of the XML document to include or omit.

With options SC14N_TRAN_OMITBYTAG or SC14N_TRAN_SUBSETBYTAG, szNameOrId specifies the element's tag name.
- By default, the first element with a matching tag name will be chosen.
- To specify the N'th element, write as tagname[N] where N=1,2,3,...
With options SC14N_TRAN_OMITBYID or SC14N_TRAN_SUBSETBYID, szNameOrId specifies the element's Id
- The default Id attribute name is Id, so the argument myvalue will find the element with Id="myvalue".
- To use a different attribute name – for example ID – write in the form ID=myvalue with no quotes.
With option SC14N_TRAN_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 1. Omits the first element with the tag name <Signature>
r = C14N_File2File("c14nfile1.txt", "input.xml", "Signature", "", SC14N_TRAN_OMITBYTAG);
 
// Example 2. Finds and transforms the first element with the tag name <SignedInfo>
r = C14N_File2File("c14nfile2.txt", "input.xml", "SignedInfo", "", SC14N_TRAN_SUBSETBYTAG);
 
// Example 3. Finds and transforms the third element with the tag name <Data>
r = C14N_File2File("c14nfile3.txt", "input.xml", "Data[3]", "", SC14N_TRAN_SUBSETBYTAG);
 
// Example 4. Finds and transforms the element with attribute Id="foo"
r = C14N_File2File("c14nfile4.txt", "input.xml", "foo", "", SC14N_TRAN_SUBSETBYID);
 
// Example 5. Finds and transforms the element with attribute ID="bar"
r = C14N_File2File("c14nfile5.txt", "input.xml", "ID=bar", "", SC14N_TRAN_SUBSETBYID);
 
// Example 6. Omits element with attribute Id="thesig"
r = C14N_File2File("c14nfile6.txt", "input.xml", "thesig", "", SC14N_TRAN_OMITBYID);

Function Documentation

◆ C14N_File2Digest()

long C14N_File2Digest	(	char *	szOut,
		long	nOutChars,
		const char *	szInputFile,
		const char *	szNameOrId,
		const char *	szParams,
		long	nOptions
	)

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

Parameters

[out]	szOut	Buffer to receive digest value output
[in]	nOutChars	Length of output buffer in bytes
[in]	szInputFile	Name of input file containing XML document to be processed
[in]	szNameOrId	To specify the tag name or Id. See Specifying the tag name or Id.
[in]	szParams	InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use `""` or `NULL` to ignore.
[in]	nOptions	Option flags. Select exactly one of: `#SC14N_TRAN_ENTIRE` (0) to transform the entire document (default) `#SC14N_TRAN_OMITBYTAG` to omit the element with tag name specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYTAG` to transform subset with tag name specified in `szNameOrId` `#SC14N_TRAN_OMITBYID` to omit the element with Id specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYID` to transform subset with Id specified in `szNameOrId` and add one of: `#SC14N_DIG_SHA1` (0) to use SHA-1 algorithm (default) or `#SC14N_DIG_SHA256` to use SHA-256. and optionally add any of the following. Use the `\|` operator to combine: `#SC14N_METHOD_EXCLUSIVE` to use exclusive c14n method (default is inclusive c14n method) `#SC14N_METHOD_WITHCOMMENTS` to include comments in c14n form (`#WithComments`) `#SC14N_OPT_FLATTEN` to remove all ignorable whitespace between tags

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The output is always encoded in base64. The maximum length is SC14N_MAX_DIGEST_CHARS.

◆ C14N_File2File()

long C14N_File2File	(	const char *	szOutputFile,
		const char *	szInputFile,
		const char *	szNameOrId,
		const char *	szParams,
		long	nOptions
	)

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

Parameters

[in]	szOutputFile	Name of output file to create (will be overwritten if exists)
[in]	szInputFile	Name of input file containing XML document to be processed
[in]	szNameOrId	To specify the tag name or Id. See Specifying the tag name or Id.
[in]	szParams	InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use `""` or `NULL` to ignore.
[in]	nOptions	Option flags. Select exactly one of: `#SC14N_TRAN_ENTIRE` (0) to transform the entire document (default) `#SC14N_TRAN_OMITBYTAG` to omit the element with tag name specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYTAG` to transform subset with tag name specified in `szNameOrId` `#SC14N_TRAN_OMITBYID` to omit the element with Id specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYID` to transform subset with Id specified in `szNameOrId` and optionally add any of the following. Use the `\|` operator to combine: `#SC14N_METHOD_EXCLUSIVE` to use exclusive c14n method (default is inclusive c14n method) `#SC14N_METHOD_WITHCOMMENTS` to include comments in c14n form (`#WithComments`) `#SC14N_OPT_FLATTEN` to remove all ignorable whitespace between tags

Returns: Zero (0) on success or a negative error code .

◆ C14N_File2String()

long C14N_File2String	(	char *	szOut,
		long	nOutChars,
		const char *	szInputFile,
		const char *	szNameOrId,
		const char *	szParams,
		long	nOptions
	)

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

Parameters

[out]	szOut	Buffer to receive output as UTF-8 encoded bytes
[in]	nOutChars	Length of output buffer in bytes
[in]	szInputFile	Name of input file containing XML document to be processed
[in]	szNameOrId	To specify the tag name or Id. See Specifying the tag name or Id.
[in]	szParams	InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use `""` or `NULL` to ignore.
[in]	nOptions	Option flags. Select exactly one of: `#SC14N_TRAN_ENTIRE` (0) to transform the entire document (default) `#SC14N_TRAN_OMITBYTAG` to omit the element with tag name specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYTAG` to transform subset with tag name specified in `szNameOrId` `#SC14N_TRAN_OMITBYID` to omit the element with Id specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYID` to transform subset with Id specified in `szNameOrId` and optionally add any of the following. Use the `\|` operator to combine: `#SC14N_METHOD_EXCLUSIVE` to use exclusive c14n method (default is inclusive c14n method) `#SC14N_METHOD_WITHCOMMENTS` to include comments in c14n form (`#WithComments`) `#SC14N_OPT_FLATTEN` to remove all ignorable whitespace between tags

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The output is always UTF-8-encoded.

◆ C14N_String2Digest()

long C14N_String2Digest	(	char *	szOut,
		long	nOutChars,
		const void *	lpDataIn,
		long	nDataLen,
		const char *	szNameOrId,
		const char *	szParams,
		long	nOptions
	)

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

Parameters

[out]	szOut	Buffer to receive digest value output
[in]	nOutChars	Length of output buffer in bytes
[in]	lpDataIn	Pointer to XML data to be processed
[in]	nDataLen	Length of input data in bytes
[in]	szNameOrId	To specify the tag name or Id. See Specifying the tag name or Id.
[in]	szParams	InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use `""` or `NULL` to ignore.
[in]	nOptions	Option flags. Select exactly one of: `#SC14N_TRAN_ENTIRE` (0) to transform the entire document (default) `#SC14N_TRAN_OMITBYTAG` to omit the element with tag name specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYTAG` to transform subset with tag name specified in `szNameOrId` `#SC14N_TRAN_OMITBYID` to omit the element with Id specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYID` to transform subset with Id specified in `szNameOrId` and add one of: `#SC14N_DIG_SHA1` (0) to use SHA-1 algorithm (default) or `#SC14N_DIG_SHA256` to use SHA-256. and optionally add any of the following. Use the `\|` operator to combine: `#SC14N_METHOD_EXCLUSIVE` to use exclusive c14n method (default is inclusive c14n method) `#SC14N_METHOD_WITHCOMMENTS` to include comments in c14n form (`#WithComments`) `#SC14N_OPT_FLATTEN` to remove all ignorable whitespace between tags

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: The output is always encoded in base64. The maximum length is SC14N_MAX_DIGEST_CHARS.

◆ C14N_String2String()

long C14N_String2String	(	char *	szOut,
		long	nOutChars,
		const void *	lpDataIn,
		long	nDataLen,
		const char *	szNameOrId,
		const char *	szParams,
		long	nOptions
	)

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

Parameters

[out]	szOut	Buffer to receive output as UTF-8 encoded bytes
[in]	nOutChars	Length of output buffer in bytes
[in]	lpDataIn	Pointer to XML data to be processed
[in]	nDataLen	Length of input data in bytes
[in]	szNameOrId	To specify the tag name or Id. See Specifying the tag name or Id.
[in]	szParams	InclusiveNamespaces PrefixList parameter (exclusive C14n only). Use `""` or `NULL` to ignore.
[in]	nOptions	Option flags. Select exactly one of: `#SC14N_TRAN_ENTIRE` (0) to transform the entire document (default) `#SC14N_TRAN_OMITBYTAG` to omit the element with tag name specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYTAG` to transform subset with tag name specified in `szNameOrId` `#SC14N_TRAN_OMITBYID` to omit the element with Id specified in `szNameOrId` `#SC14N_TRAN_SUBSETBYID` to transform subset with Id specified in `szNameOrId` and optionally add any of the following. Use the `\|` operator to combine: `#SC14N_METHOD_EXCLUSIVE` to use exclusive c14n method (default is inclusive c14n method) `#SC14N_METHOD_WITHCOMMENTS` to include comments in c14n form (`#WithComments`) `#SC14N_OPT_FLATTEN` to remove all ignorable whitespace between tags

Returns: Zero (0) on success or a negative error code .

Remarks: The output is always UTF-8-encoded.

◆ SC14N_Err_ErrorLookup()

long SC14N_Err_ErrorLookup	(	char *	szOut,
		long	nOutChars,
		long	nErrCode
	)

Looks up description for error code.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes
[in]	nErrCode	Value of error code to lookup (may be positive or negative)

Returns: Number of characters in or required for output string; or a negative error code .

◆ SC14N_Err_LastError()

long SC14N_Err_LastError	(	char *	szOut,
		long	nOutChars
	)

Retrieves the last error message (if available).

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes. Will not exceed `SC14N_MAX_ERROR_CHARS`.

Returns: Number of characters in or required for output string; or a negative error code .

Remarks: Call this function to find out more information about the last error. Not all functions set this.

◆ SC14N_Gen_CompileTime()

long SC14N_Gen_CompileTime	(	char *	szOut,
		long	nOutChars
	)

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

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes

Returns: Number of characters in or required for output string; or a negative error code .

◆ SC14N_Gen_LicenceType()

long SC14N_Gen_LicenceType ( void )

Gets licence type.

Returns: ASCII value of the licence type: 'D'=Developer, 'T'=Trial

Remarks: Note the Australian/English spelling of "Licence".

◆ SC14N_Gen_ModuleName()

long SC14N_Gen_ModuleName	(	char *	szOut,
		long	nOutChars,
		long	nOptions
	)

Gets full path name of core DLL module.

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes.
[in]	nOptions	Not used. Specify zero.

Returns: Number of characters in or required for output string; or a negative error code

◆ SC14N_Gen_Platform()

long SC14N_Gen_Platform	(	char *	szOut,
		long	nOutChars
	)

Gets platform on which the core DLL is running ("Win32" or "Win64").

Parameters

[out]	szOut	Buffer to receive output string
[in]	nOutChars	Maximum length of output string in bytes

Returns: Number of characters in or required for output string; or a negative error code .

◆ SC14N_Gen_Version()

long SC14N_Gen_Version ( void )

Gets version number of the core DLL.

Returns: Version number as an integer in the form major*10000+minor*100+revision e.g. DLL file version 1.2.x.3 will return 10203

◆ SC14N_Utf8FromWide()

long SC14N_Utf8FromWide	(	char *	szOut,
		long	nOutChars,
		const wchar_t *	wstr
	)

Maps a UTF-16 (wide character) string to a UTF-8-encoded string.

Parameters

[out]	szOut	Buffer to receive null-terminated UTF-8-encoded string.
[in]	nOutChars	Maximum length of output string in bytes (excluding the terminating null).
[in]	wstr	String of wide characters to be processed.

Returns: Number of characters (bytes) in or required for the output string; or a negative error code .

Remarks: Pass a NULL szOut or zero nOutChars to find the required output length in bytes. Allocate one extra byte for the terminating null.; long nchars;

char *buf = NULL;

wchar_t *wstr = L"áéíñóü"

// Find required output length (12 in this case)

nchars = SC14N_Utf8FromWide(NULL, 0, wstr);

printf("SC14N_Utf8FromWide returns %ld\n", nchars);

assert(nchars >= 0);

buf = malloc(nchars + 1); // NB one extra byte

nchars = SC14N_Utf8FromWide(buf, nchars, wstr);

assert(nchars >= 0);

// Assumes console codepage is set to UTF-8

printf("[%s]\n", buf);

free(buf);

SC14N_Utf8FromWide
long SC14N_Utf8FromWide(char *szOut, long nOutChars, const wchar_t *wstr)
Maps a UTF-16 (wide character) string to a UTF-8-encoded string.

Macros

Functions

Detailed Description

Function Documentation

◆ C14N_File2Digest()

◆ C14N_File2File()

◆ C14N_File2String()

◆ C14N_String2Digest()

◆ C14N_String2String()

◆ SC14N_Err_ErrorLookup()

◆ SC14N_Err_LastError()

◆ SC14N_Gen_CompileTime()

◆ SC14N_Gen_LicenceType()

◆ SC14N_Gen_ModuleName()

◆ SC14N_Gen_Platform()

◆ SC14N_Gen_Version()

◆ SC14N_Utf8FromWide()