transforms

XMLSEC_TRANSFORM_BINARY_CHUNK

#define XMLSEC_TRANSFORM_BINARY_CHUNK			64

The binary data chunks size. XMLSec processes binary data one chunk at a time. Changing this impacts xmlsec memory usage and performance.

xmlSecTransformIdsGet ()

xmlSecPtrListPtr xmlSecTransformIdsGet      (void);

Gets global registered transform klasses list.

xmlSecTransformIdsInit ()

int         xmlSecTransformIdsInit          (void);

Initializes the transform klasses. This function is called from the xmlSecInit function and the application should not call it directly.

xmlSecTransformIdsShutdown ()

void        xmlSecTransformIdsShutdown      (void);

Shuts down the keys data klasses. This function is called from the xmlSecShutdown function and the application should not call it directly.

xmlSecTransformIdsRegisterDefault ()

int         xmlSecTransformIdsRegisterDefault
                                            (void);

Registers default (implemented by XML Security Library) transform klasses: XPath transform, Base64 transform, ...

xmlSecTransformIdsRegister ()

int         xmlSecTransformIdsRegister      (xmlSecTransformId id);

Registers id in the global list of transform klasses.

enum xmlSecTransformStatus

typedef enum  {
    xmlSecTransformStatusNone = 0,
    xmlSecTransformStatusWorking,
    xmlSecTransformStatusFinished,
    xmlSecTransformStatusOk,
    xmlSecTransformStatusFail
} xmlSecTransformStatus;

The transform execution status.

enum xmlSecTransformMode

typedef enum  {
    xmlSecTransformModeNone = 0,
    xmlSecTransformModePush,
    xmlSecTransformModePop
} xmlSecTransformMode;

The transform operation mode

enum xmlSecTransformOperation

typedef enum  {
    xmlSecTransformOperationNone = 0,
    xmlSecTransformOperationEncode,
    xmlSecTransformOperationDecode,
    xmlSecTransformOperationSign,
    xmlSecTransformOperationVerify,
    xmlSecTransformOperationEncrypt,
    xmlSecTransformOperationDecrypt
} xmlSecTransformOperation;

The transform operation.

xmlSecTransformUriType

typedef unsigned int				xmlSecTransformUriType;

URI transform type bit mask.

xmlSecTransformUriTypeNone

#define xmlSecTransformUriTypeNone		0x0000

The URI type is unknown or not set.

xmlSecTransformUriTypeEmpty

#define xmlSecTransformUriTypeEmpty		0x0001

The empty URI ("") type.

xmlSecTransformUriTypeSameDocument

#define xmlSecTransformUriTypeSameDocument	0x0002		

The smae document ("#...") but not empty ("") URI type.

xmlSecTransformUriTypeLocal

#define xmlSecTransformUriTypeLocal		0x0004

The local URI ("file:///....") type.

xmlSecTransformUriTypeRemote

#define xmlSecTransformUriTypeRemote		0x0008

The remote URI type.

xmlSecTransformUriTypeAny

#define xmlSecTransformUriTypeAny		0xFFFF

Any URI type.

xmlSecTransformUriTypeCheck ()

int         xmlSecTransformUriTypeCheck     (xmlSecTransformUriType type,
                                             const xmlChar *uri);

Checks if uri matches expected type type.

xmlSecTransformDataType

typedef xmlSecByte				xmlSecTransformDataType;

Transform data type bit mask.

xmlSecTransformDataTypeUnknown

#define xmlSecTransformDataTypeUnknown		0x0000

The transform data type is unknown or nor data expected.

xmlSecTransformDataTypeBin

#define xmlSecTransformDataTypeBin		0x0001

The binary transform data.

xmlSecTransformDataTypeXml

#define xmlSecTransformDataTypeXml		0x0002

The xml transform data.

xmlSecTransformUsage

typedef unsigned int				xmlSecTransformUsage;

The transform usage bit mask.

xmlSecTransformUsageUnknown

#define xmlSecTransformUsageUnknown		0x0000

Transforms usage is unknown or undefined.

xmlSecTransformUsageDSigTransform

#define xmlSecTransformUsageDSigTransform	0x0001

Transform could be used in <dsig:Transform>.

xmlSecTransformUsageC14NMethod

#define xmlSecTransformUsageC14NMethod		0x0002

Transform could be used in <dsig:CanonicalizationMethod>.

xmlSecTransformUsageDigestMethod

#define xmlSecTransformUsageDigestMethod	0x0004

Transform could be used in <dsig:DigestMethod>.

xmlSecTransformUsageSignatureMethod

#define xmlSecTransformUsageSignatureMethod	0x0008

Transform could be used in <dsig:SignatureMethod>.

xmlSecTransformUsageEncryptionMethod

#define xmlSecTransformUsageEncryptionMethod	0x0010

Transform could be used in <enc:EncryptionMethod>.

xmlSecTransformUsageAny

#define xmlSecTransformUsageAny			0xFFFF

Transform could be used for operation.

xmlSecTransformCtxPreExecuteCallback ()

int         (*xmlSecTransformCtxPreExecuteCallback)
                                            (xmlSecTransformCtxPtr transformCtx);

The callback called after creating transforms chain but before starting data processing. Application can use this callback to do additional transforms chain verification or modification and aborting transforms execution (if necessary).

XMLSEC_TRANSFORMCTX_FLAGS_USE_VISA3D_HACK

#define XMLSEC_TRANSFORMCTX_FLAGS_USE_VISA3D_HACK		0x00000001

If this flag is set then URI ID references are resolved directly without using XPointers. This allows one to sign/verify Visa3D documents that don't follow XML, XPointer and XML DSig specifications.

struct xmlSecTransformCtx

struct xmlSecTransformCtx {

    /* user settings */
    void*					userData;
    unsigned int				flags;
    unsigned int				flags2;
    xmlSecTransformUriType			enabledUris;
    xmlSecPtrList				enabledTransforms;
    xmlSecTransformCtxPreExecuteCallback	preExecCallback;
    
    /* results */
    xmlSecBufferPtr				result;
    xmlSecTransformStatus			status;
    xmlChar*					uri;
    xmlChar*					xptrExpr;
    xmlSecTransformPtr				first;
    xmlSecTransformPtr				last;

    /* for the future */
    void*					reserved0;
    void*					reserved1;
};

The transform execution context.

xmlSecTransformCtxCreate ()

xmlSecTransformCtxPtr xmlSecTransformCtxCreate
                                            (void);

Creates transforms chain processing context. The caller is responsible for destroying returend object by calling xmlSecTransformCtxDestroy function.

xmlSecTransformCtxDestroy ()

void        xmlSecTransformCtxDestroy       (xmlSecTransformCtxPtr ctx);

Destroy context object created with xmlSecTransformCtxCreate function.

xmlSecTransformCtxInitialize ()

int         xmlSecTransformCtxInitialize    (xmlSecTransformCtxPtr ctx);

Initializes transforms chain processing context. The caller is responsible for cleaing up returend object by calling xmlSecTransformCtxFinalize function.

xmlSecTransformCtxFinalize ()

void        xmlSecTransformCtxFinalize      (xmlSecTransformCtxPtr ctx);

Cleans up ctx object initialized with xmlSecTransformCtxInitialize function.

xmlSecTransformCtxReset ()

void        xmlSecTransformCtxReset         (xmlSecTransformCtxPtr ctx);

Resets transfroms context for new processing.

xmlSecTransformCtxCopyUserPref ()

int         xmlSecTransformCtxCopyUserPref  (xmlSecTransformCtxPtr dst,
                                             xmlSecTransformCtxPtr src);

Copies user settings from src context to dst.

xmlSecTransformCtxSetUri ()

int         xmlSecTransformCtxSetUri        (xmlSecTransformCtxPtr ctx,
                                             const xmlChar *uri,
                                             xmlNodePtr hereNode);

Parses uri and adds xpointer transforms if required.

The following examples demonstrate what the URI attribute identifies and how it is dereferenced (http://www.w3.org/TR/xmldsig-core/sec-ReferenceProcessingModel):

- URI="http://example.com/bar.xml" identifies the octets that represent the external resource 'http://example.com/bar.xml', that is probably an XML document given its file extension.

- URI="http://example.com/bar.xmlchapter1" identifies the element with ID attribute value 'chapter1' of the external XML resource 'http://example.com/bar.xml', provided as an octet stream. Again, for the sake of interoperability, the element identified as 'chapter1' should be obtained using an XPath transform rather than a URI fragment (barename XPointer resolution in external resources is not REQUIRED in this specification).

- URI="" identifies the node-set (minus any comment nodes) of the XML resource containing the signature

- URI="chapter1" identifies a node-set containing the element with ID attribute value 'chapter1' of the XML resource containing the signature. XML Signature (and its applications) modify this node-set to include the element plus all descendents including namespaces and attributes -- but not comments.

xmlSecTransformCtxAppend ()

int         xmlSecTransformCtxAppend        (xmlSecTransformCtxPtr ctx,
                                             xmlSecTransformPtr transform);

Connects the transform to the end of the chain of transforms in the ctx (see xmlSecTransformConnect function for details).

xmlSecTransformCtxPrepend ()

int         xmlSecTransformCtxPrepend       (xmlSecTransformCtxPtr ctx,
                                             xmlSecTransformPtr transform);

Connects the transform to the beggining of the chain of transforms in the ctx (see xmlSecTransformConnect function for details).

xmlSecTransformCtxCreateAndAppend ()

xmlSecTransformPtr xmlSecTransformCtxCreateAndAppend
                                            (xmlSecTransformCtxPtr ctx,
                                             xmlSecTransformId id);

Creaeates new transform and connects it to the end of the chain of transforms in the ctx (see xmlSecTransformConnect function for details).

xmlSecTransformCtxCreateAndPrepend ()

xmlSecTransformPtr xmlSecTransformCtxCreateAndPrepend
                                            (xmlSecTransformCtxPtr ctx,
                                             xmlSecTransformId id);

Creaeates new transform and connects it to the end of the chain of transforms in the ctx (see xmlSecTransformConnect function for details).

xmlSecTransformCtxNodeRead ()

xmlSecTransformPtr xmlSecTransformCtxNodeRead
                                            (xmlSecTransformCtxPtr ctx,
                                             xmlNodePtr node,
                                             xmlSecTransformUsage usage);

Reads the transform from the node and appends it to the current chain of transforms in ctx.

xmlSecTransformCtxNodesListRead ()

int         xmlSecTransformCtxNodesListRead (xmlSecTransformCtxPtr ctx,
                                             xmlNodePtr node,
                                             xmlSecTransformUsage usage);

Reads transforms from the <dsig:Transform/> children of the node and appends them to the current transforms chain in ctx object.

xmlSecTransformCtxPrepare ()

int         xmlSecTransformCtxPrepare       (xmlSecTransformCtxPtr ctx,
                                             xmlSecTransformDataType inputDataType);

Prepares the transform context for processing data of inputDataType.

xmlSecTransformCtxBinaryExecute ()

int         xmlSecTransformCtxBinaryExecute (xmlSecTransformCtxPtr ctx,
                                             const xmlSecByte *data,
                                             xmlSecSize dataSize);

Processes binary data using transforms chain in the ctx.

xmlSecTransformCtxUriExecute ()

int         xmlSecTransformCtxUriExecute    (xmlSecTransformCtxPtr ctx,
                                             const xmlChar *uri);

Process binary data from the URI using transforms chain in ctx.

xmlSecTransformCtxXmlExecute ()

int         xmlSecTransformCtxXmlExecute    (xmlSecTransformCtxPtr ctx,
                                             xmlSecNodeSetPtr nodes);

Process nodes using transforms in the transforms chain in ctx.

xmlSecTransformCtxExecute ()

int         xmlSecTransformCtxExecute       (xmlSecTransformCtxPtr ctx,
                                             xmlDocPtr doc);

Executes transforms chain in ctx.

xmlSecTransformCtxDebugDump ()

void        xmlSecTransformCtxDebugDump     (xmlSecTransformCtxPtr ctx,
                                             FILE *output);

Prints transforms context debug information to output.

xmlSecTransformCtxDebugXmlDump ()

void        xmlSecTransformCtxDebugXmlDump  (xmlSecTransformCtxPtr ctx,
                                             FILE *output);

Prints transforms context debug information to output in XML format.

struct xmlSecTransform

struct xmlSecTransform {

    xmlSecTransformId 			id; 
    xmlSecTransformOperation		operation;
    xmlSecTransformStatus		status;
    xmlNodePtr				hereNode;

    /* transforms chain */
    xmlSecTransformPtr			next;
    xmlSecTransformPtr			prev;

    /* binary data */
    xmlSecBuffer			inBuf;
    xmlSecBuffer			outBuf;
        
    /* xml data */
    xmlSecNodeSetPtr			inNodes;
    xmlSecNodeSetPtr			outNodes;

    /* reserved for the future */    
    void*				reserved0;
    void*				reserved1;
};

The transform structure.

xmlSecTransformCreate ()

xmlSecTransformPtr xmlSecTransformCreate    (xmlSecTransformId id);

Creates new transform of the id klass. The caller is responsible for destroying returned tansform using xmlSecTransformDestroy function.

xmlSecTransformDestroy ()

void        xmlSecTransformDestroy          (xmlSecTransformPtr transform);

Destroys transform created with xmlSecTransformCreate function.

xmlSecTransformNodeRead ()

xmlSecTransformPtr xmlSecTransformNodeRead  (xmlNodePtr node,
                                             xmlSecTransformUsage usage,
                                             xmlSecTransformCtxPtr transformCtx);

Reads transform from the node as follows:

1) reads "Algorithm" attribute;

2) checks the lists of known and allowed transforms;

3) calls transform's create method;

4) calls transform's read transform node method.

xmlSecTransformPump ()

int         xmlSecTransformPump             (xmlSecTransformPtr left,
                                             xmlSecTransformPtr right,
                                             xmlSecTransformCtxPtr transformCtx);

Pops data from left transform and pushes to right transform until no more data is available.

xmlSecTransformSetKey ()

int         xmlSecTransformSetKey           (xmlSecTransformPtr transform,
                                             xmlSecKeyPtr key);

Sets the transform's key.

xmlSecTransformSetKeyReq ()

int         xmlSecTransformSetKeyReq        (xmlSecTransformPtr transform,
                                             xmlSecKeyReqPtr keyReq);

Sets the key requirements for transform in the keyReq.

xmlSecTransformVerify ()

int         xmlSecTransformVerify           (xmlSecTransformPtr transform,
                                             const xmlSecByte *data,
                                             xmlSecSize dataSize,
                                             xmlSecTransformCtxPtr transformCtx);

Verifies the data with transform's processing results (for digest, HMAC and signature transforms). The verification result is stored in the status member of xmlSecTransform object.

xmlSecTransformVerifyNodeContent ()

int         xmlSecTransformVerifyNodeContent
                                            (xmlSecTransformPtr transform,
                                             xmlNodePtr node,
                                             xmlSecTransformCtxPtr transformCtx);

Gets the node content, base64 decodes it and calls xmlSecTransformVerify function to verify binary results.

xmlSecTransformGetDataType ()

xmlSecTransformDataType xmlSecTransformGetDataType
                                            (xmlSecTransformPtr transform,
                                             xmlSecTransformMode mode,
                                             xmlSecTransformCtxPtr transformCtx);

Gets transform input (mode is "push") or output (mode is "pop") data type (binary or XML).

xmlSecTransformPushBin ()

int         xmlSecTransformPushBin          (xmlSecTransformPtr transform,
                                             const xmlSecByte *data,
                                             xmlSecSize dataSize,
                                             int final,
                                             xmlSecTransformCtxPtr transformCtx);

Process binary data and pushes results to next transform.

xmlSecTransformPopBin ()

int         xmlSecTransformPopBin           (xmlSecTransformPtr transform,
                                             xmlSecByte *data,
                                             xmlSecSize maxDataSize,
                                             xmlSecSize *dataSize,
                                             xmlSecTransformCtxPtr transformCtx);

Pops data from previous transform in the chain, processes data and returns result in the data buffer. The size of returned data is placed in the dataSize.

xmlSecTransformPushXml ()

int         xmlSecTransformPushXml          (xmlSecTransformPtr transform,
                                             xmlSecNodeSetPtr nodes,
                                             xmlSecTransformCtxPtr transformCtx);

Processes nodes and pushes result to the next transform in the chain.

xmlSecTransformPopXml ()

int         xmlSecTransformPopXml           (xmlSecTransformPtr transform,
                                             xmlSecNodeSetPtr *nodes,
                                             xmlSecTransformCtxPtr transformCtx);

Pops data from previous transform in the chain, processes the data and returns result in nodes.

xmlSecTransformExecute ()

int         xmlSecTransformExecute          (xmlSecTransformPtr transform,
                                             int last,
                                             xmlSecTransformCtxPtr transformCtx);

Executes transform (used by default popBin/pushBin/popXml/pushXml methods).

xmlSecTransformDebugDump ()

void        xmlSecTransformDebugDump        (xmlSecTransformPtr transform,
                                             FILE *output);

Prints transform's debug information to output.

xmlSecTransformDebugXmlDump ()

void        xmlSecTransformDebugXmlDump     (xmlSecTransformPtr transform,
                                             FILE *output);

Prints transform's debug information to output in XML format.

xmlSecTransformGetName()

#define     xmlSecTransformGetName(transform)

Macro. Returns transform name.

xmlSecTransformIsValid()

#define     xmlSecTransformIsValid(transform)

Macro. Returns 1 if the transform is valid or 0 otherwise.

xmlSecTransformCheckType()

#define     xmlSecTransformCheckType(transform, t)

Macro. Returns 1 if the transform is valid and has specified type t or 0 otherwise.

xmlSecTransformCheckId()

#define     xmlSecTransformCheckId(transform, i)

Macro. Returns 1 if the transform is valid and has specified id i or 0 otherwise.

xmlSecTransformCheckSize()

#define     xmlSecTransformCheckSize(transform, size)

Macro. Returns 1 if the transform is valid and has at least size bytes or 0 otherwise.

xmlSecTransformConnect ()

int         xmlSecTransformConnect          (xmlSecTransformPtr left,
                                             xmlSecTransformPtr right,
                                             xmlSecTransformCtxPtr transformCtx);

If the data object is a node-set and the next transform requires octets, the signature application MUST attempt to convert the node-set to an octet stream using Canonical XML [XML-C14N].

The story is different if the right transform is base64 decode (http://www.w3.org/TR/xmldsig-core/sec-Base-64):

This transform requires an octet stream for input. If an XPath node-set (or sufficiently functional alternative) is given as input, then it is converted to an octet stream by performing operations logically equivalent to 1) applying an XPath transform with expression self::text(), then 2) taking the string-value of the node-set. Thus, if an XML element is identified by a barename XPointer in the Reference URI, and its content consists solely of base64 encoded character data, then this transform automatically strips away the start and end tags of the identified element and any of its descendant elements as well as any descendant comments and processing instructions. The output of this transform is an octet stream.

xmlSecTransformRemove ()

void        xmlSecTransformRemove           (xmlSecTransformPtr transform);

Removes transform from the chain.

xmlSecTransformDefaultGetDataType ()

xmlSecTransformDataType xmlSecTransformDefaultGetDataType
                                            (xmlSecTransformPtr transform,
                                             xmlSecTransformMode mode,
                                             xmlSecTransformCtxPtr transformCtx);

Gets transform input (mode is "push") or output (mode is "pop") data type (binary or XML) by analyzing available pushBin/popBin/pushXml/popXml methods.

xmlSecTransformDefaultPushBin ()

int         xmlSecTransformDefaultPushBin   (xmlSecTransformPtr transform,