transformsInternal.h

Name

transformsInternal.h -- The internal transform's functions.

Synopsis



enum        xmlSecTransformType;
typedef     xmlSecTransformUsage;
#define     xmlSecUsageAny
#define     xmlSecUsageDSigC14N
#define     xmlSecUsageDSigTransform
#define     xmlSecUsageDSigDigest
#define     xmlSecUsageDSigSignature
#define     xmlSecUsageEncryptionMethod
enum        xmlSecTransformResult;
struct      xmlSecTransform;
void        xmlSecTransformsInit            (void);
int         xmlSecTransformsNodeRead        (xmlSecTransformStatePtr state,
                                             xmlNodePtr transformsNode);
xmlSecTransformId xmlSecTransformFind       (const xmlChar *href);
xmlSecTransformPtr xmlSecTransformNodeRead  (xmlNodePtr transformNode,
                                             xmlSecTransformUsage usage,
                                             int dontDestroy);
int         xmlSecTransformNodeWrite        (xmlNodePtr transformNode,
                                             xmlSecTransformId id);
#define     xmlSecTransformIsValid          (transform)
#define     xmlSecTransformCheckType        (transform, t)
#define     xmlSecTransformCheckId          (transform, i)
xmlSecTransformPtr xmlSecTransformCreate    (xmlSecTransformId id,
                                             xmlSecTransformUsage usage,
                                             int dontDestroy);
void        xmlSecTransformDestroy          (xmlSecTransformPtr transform,
                                             int forceDestroy);
int         xmlSecTransformRead             (xmlSecTransformPtr transform,
                                             xmlNodePtr transformNode);
xmlSecTransformPtr (*xmlSecTransformCreateMethod)
                                            (xmlSecTransformId id);
void        (*xmlSecTransformDestroyMethod) (xmlSecTransformPtr transform);
int         (*xmlSecTransformReadNodeMethod)
                                            (xmlSecTransformPtr transform,
                                             xmlNodePtr transformNode);
typedef     xmlSecBinTransformId;
struct      xmlSecBinTransform;
enum        xmlSecBinTransformSubType;
#define     xmlSecBinTransformIdCheckKeyId  (id, kId)
#define     xmlSecBinTransformIdGetKeyId    (id)
#define     xmlSecBinTransformCheckSubType  (transform, t)
#define     xmlSecBinTransformIdGetEncKeyType(id)
#define     xmlSecBinTransformIdGetDecKeyType(id)
int         xmlSecBinTransformAddKey        (xmlSecTransformPtr transform,
                                             xmlSecKeyPtr key);
int         xmlSecBinTransformRead          (xmlSecTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         xmlSecBinTransformWrite         (xmlSecTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         xmlSecBinTransformFlush         (xmlSecTransformPtr transform);
xmlSecTransformPtr xmlSecBinTransformAddAfter
                                            (xmlSecTransformPtr curTransform,
                                             xmlSecTransformPtr newTransform);
xmlSecTransformPtr xmlSecBinTransformAddBefore
                                            (xmlSecTransformPtr curTransform,
                                             xmlSecTransformPtr newTransform);
void        xmlSecBinTransformRemove        (xmlSecTransformPtr transform);
void        xmlSecBinTransformDestroyAll    (xmlSecTransformPtr transform);
void        xmlSecBinTransformSetEncrypt    (xmlSecTransformPtr transform,
                                             int encrypt);
int         (*xmlSecBinTransformAddKeyMethod)
                                            (xmlSecBinTransformPtr transform,
                                             xmlSecKeyPtr key);
int         (*xmlSecBinTransformReadMethod) (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         (*xmlSecBinTransformWriteMethod)
                                            (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         (*xmlSecBinTransformFlushMethod)
                                            (xmlSecBinTransformPtr transform);
typedef     xmlSecXmlTransformId;
struct      xmlSecXmlTransform;
int         (*xmlSecXmlTransformExecuteMethod)
                                            (xmlSecXmlTransformPtr transform,
                                             xmlDocPtr ctxDoc,
                                             xmlDocPtr *doc,
                                             xmlSecNodeSetPtr *nodes);
int         xmlSecXmlTransformExecute       (xmlSecTransformPtr transform,
                                             xmlDocPtr ctxDoc,
                                             xmlDocPtr *doc,
                                             xmlSecNodeSetPtr *nodes);
typedef     xmlSecC14NTransformId;
struct      xmlSecC14NTransform;
int         (*xmlSecC14NTransformExecuteMethod)
                                            (xmlSecC14NTransformPtr transform,
                                             xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodes,
                                             xmlOutputBufferPtr buffer);
int         xmlSecC14NTransformExecute      (xmlSecTransformPtr transform,
                                             xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodes,
                                             xmlOutputBufferPtr buffer);
struct      xmlSecTransformState;
xmlSecTransformStatePtr xmlSecTransformStateCreate
                                            (xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodeSet,
                                             const char *uri);
void        xmlSecTransformStateDestroy     (xmlSecTransformStatePtr state);
int         xmlSecTransformStateUpdate      (xmlSecTransformStatePtr state,
                                             xmlSecTransformPtr transform);
int         xmlSecTransformStateFinal       (xmlSecTransformStatePtr state,
                                             xmlSecTransformResult type);

Description

Details

enum xmlSecTransformType

typedef enum  {
    xmlSecTransformTypeBinary,
    xmlSecTransformTypeXml,
    xmlSecTransformTypeC14N
} xmlSecTransformType;

The transform input/output types.


xmlSecTransformUsage

typedef unsigned long 				xmlSecTransformUsage;

The transform usage bits mask.


xmlSecUsageAny

#define xmlSecUsageAny				0

Transform could be used for operation.


xmlSecUsageDSigC14N

#define xmlSecUsageDSigC14N			1

Transform could be used for C14N.


xmlSecUsageDSigTransform

#define xmlSecUsageDSigTransform		2

Transform could be used as a transform in XML DSig.


xmlSecUsageDSigDigest

#define xmlSecUsageDSigDigest			4

Transform could be used for digests.


xmlSecUsageDSigSignature

#define xmlSecUsageDSigSignature		8

Transform could be used for generating signatures.


xmlSecUsageEncryptionMethod

#define xmlSecUsageEncryptionMethod		16

Transform could be used for encryption.


enum xmlSecTransformResult

typedef enum {
    xmlSecTransformResultBinary,
    xmlSecTransformResultXml
} xmlSecTransformResult;

The transform result types.


struct xmlSecTransform

struct xmlSecTransform {
    xmlSecTransformId 			id; 
    xmlSecTransformStatus		status;
    int					dontDestroy;
    void				*data;
};

The transform structure.


xmlSecTransformsInit ()

void        xmlSecTransformsInit            (void);

Trnasforms engine initialization (called from xmlSecInit() function). The applications should not call this function directly.


xmlSecTransformsNodeRead ()

int         xmlSecTransformsNodeRead        (xmlSecTransformStatePtr state,
                                             xmlNodePtr transformsNode);

Reads the transform node and updates state,


xmlSecTransformFind ()

xmlSecTransformId xmlSecTransformFind       (const xmlChar *href);

Searches the list of known transforms for transform with given href


xmlSecTransformNodeRead ()

xmlSecTransformPtr xmlSecTransformNodeRead  (xmlNodePtr transformNode,
                                             xmlSecTransformUsage usage,
                                             int dontDestroy);

Reads transform from the transformNode as follows: 1) reads "Algorithm" attribute; 2) checks the list of known algorithms; 3) calls transform create method; 4) calls transform read transform node method.


xmlSecTransformNodeWrite ()

int         xmlSecTransformNodeWrite        (xmlNodePtr transformNode,
                                             xmlSecTransformId id);

Writes Agorithm attribute in the transform node.


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.


xmlSecTransformCreate ()

xmlSecTransformPtr xmlSecTransformCreate    (xmlSecTransformId id,
                                             xmlSecTransformUsage usage,
                                             int dontDestroy);

Creates new transform from the transform id object.


xmlSecTransformDestroy ()

void        xmlSecTransformDestroy          (xmlSecTransformPtr transform,
                                             int forceDestroy);

Destroys transform by calling appropriate transform specific function.


xmlSecTransformRead ()

int         xmlSecTransformRead             (xmlSecTransformPtr transform,
                                             xmlNodePtr transformNode);

Reads transform information from the transformNode using transform specific function.


xmlSecTransformCreateMethod ()

xmlSecTransformPtr (*xmlSecTransformCreateMethod)
                                            (xmlSecTransformId id);

The transform specific creation method.


xmlSecTransformDestroyMethod ()

void        (*xmlSecTransformDestroyMethod) (xmlSecTransformPtr transform);

The transform specific destroy method.


xmlSecTransformReadNodeMethod ()

int         (*xmlSecTransformReadNodeMethod)
                                            (xmlSecTransformPtr transform,
                                             xmlNodePtr transformNode);

The transfomr specific method to read the transform data from the transformNode.


xmlSecBinTransformId

typedef const struct _xmlSecBinTransformIdStruct *xmlSecBinTransformId;

The binary transform id (xmlSecTransformTypeBinary type).


struct xmlSecBinTransform

struct xmlSecBinTransform {	
    /* same as for xmlSecTransform but id type changed */
    xmlSecBinTransformId 		id; 
    xmlSecTransformStatus		status;
    int					dontDestroy;
    void				*data;

    /* xmlSecBinTransform specific */
    int					encode;
    xmlSecBinTransformPtr		next;
    xmlSecBinTransformPtr		prev;
    void				*binData;
};

Binary transforms are very similar to BIO from OpenSSL. However,there is one big difference. In OpenSSL BIO writing operation *always* encrypts data and read operation *always* decrypts data. We do not want to have this restriction.


enum xmlSecBinTransformSubType

typedef enum {
    xmlSecBinTransformSubTypeNone = 0,
    xmlSecBinTransformSubTypeDigest,
    xmlSecBinTransformSubTypeCipher,
    xmlSecBinTransformSubTypeBuffered
} xmlSecBinTransformSubType;

Binary transform sub-types.


xmlSecBinTransformIdCheckKeyId()

#define     xmlSecBinTransformIdCheckKeyId(id, kId)

Macro. Returns 1 if the transform id has xmlSecTransformTypeBinary type and the transform's keyId matches specified kId or 0 otherwise.


xmlSecBinTransformIdGetKeyId()

#define     xmlSecBinTransformIdGetKeyId(id)

Macro. Returns the key id required by the transform or NULL if an error occurs.


xmlSecBinTransformCheckSubType()

#define     xmlSecBinTransformCheckSubType(transform, t)

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


xmlSecBinTransformIdGetEncKeyType()

#define     xmlSecBinTransformIdGetEncKeyType(id)

Macro. Returns the encryption key type by the transform or NULL if an error occurs.


xmlSecBinTransformIdGetDecKeyType()

#define     xmlSecBinTransformIdGetDecKeyType(id)

Macro. Returns the decryption key type by the transform or NULL if an error occurs.


xmlSecBinTransformAddKey ()

int         xmlSecBinTransformAddKey        (xmlSecTransformPtr transform,
                                             xmlSecKeyPtr key);

Sets the key for binary transform (wrapper for transform specific addBinKey() method).


xmlSecBinTransformRead ()

int         xmlSecBinTransformRead          (xmlSecTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

Reads chunk of data from the transform (wrapper transform specific readBin() function).


xmlSecBinTransformWrite ()

int         xmlSecBinTransformWrite         (xmlSecTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

Writes data to the transform (wrapper to the transform specific writeBin() function).


xmlSecBinTransformFlush ()

int         xmlSecBinTransformFlush         (xmlSecTransformPtr transform);

Finalizes writing (wrapper for transform specific flushBin() method).


xmlSecBinTransformAddAfter ()

xmlSecTransformPtr xmlSecBinTransformAddAfter
                                            (xmlSecTransformPtr curTransform,
                                             xmlSecTransformPtr newTransform);

Adds newTransform after the curTransform.


xmlSecBinTransformAddBefore ()

xmlSecTransformPtr xmlSecBinTransformAddBefore
                                            (xmlSecTransformPtr curTransform,
                                             xmlSecTransformPtr newTransform);

Adds newTransform before the curTransform.


xmlSecBinTransformRemove ()

void        xmlSecBinTransformRemove        (xmlSecTransformPtr transform);

Removes transform from the chain. This method MUST be called by any bin transform id destructor.


xmlSecBinTransformDestroyAll ()

void        xmlSecBinTransformDestroyAll    (xmlSecTransformPtr transform);

Destroys all transforms in the chain.


xmlSecBinTransformSetEncrypt ()

void        xmlSecBinTransformSetEncrypt    (xmlSecTransformPtr transform,
                                             int encrypt);

Sets the transform direction - encrypt/decrypt (or encode/decode).


xmlSecBinTransformAddKeyMethod ()

int         (*xmlSecBinTransformAddKeyMethod)
                                            (xmlSecBinTransformPtr transform,
                                             xmlSecKeyPtr key);

The transform specific method to set key for use.


xmlSecBinTransformReadMethod ()

int         (*xmlSecBinTransformReadMethod) (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

The transform specific method to read next chunk of binary data into buf.


xmlSecBinTransformWriteMethod ()

int         (*xmlSecBinTransformWriteMethod)
                                            (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

The transform specific method to write next chunk of binary data from buf.


xmlSecBinTransformFlushMethod ()

int         (*xmlSecBinTransformFlushMethod)
                                            (xmlSecBinTransformPtr transform);

The transform specific method to finalize writing.


xmlSecXmlTransformId

typedef const struct _xmlSecXmlTransformIdStruct *xmlSecXmlTransformId;

The xml transform id (xmlSecTransformTypeXml type).


struct xmlSecXmlTransform

struct xmlSecXmlTransform {
    /* same as for xmlSecTransform but id type changed */
    xmlSecXmlTransformId 		id; 
    xmlSecTransformStatus		status;
    int					dontDestroy;
    void				*data;

    /* xmlSecXmlTransform specific */
    xmlNodePtr				here;
    void				*xmlData;
};

The XML transform structure.


xmlSecXmlTransformExecuteMethod ()

int         (*xmlSecXmlTransformExecuteMethod)
                                            (xmlSecXmlTransformPtr transform,
                                             xmlDocPtr ctxDoc,
                                             xmlDocPtr *doc,
                                             xmlSecNodeSetPtr *nodes);

Transform specific execute method. Returns result nodes set in nodes.


xmlSecXmlTransformExecute ()

int         xmlSecXmlTransformExecute       (xmlSecTransformPtr transform,
                                             xmlDocPtr ctxDoc,
                                             xmlDocPtr *doc,
                                             xmlSecNodeSetPtr *nodes);

Executes the XML transform and returns result nodes set in nodes (wrapper for transform specific executeXml() method).


xmlSecC14NTransformId

typedef const struct _xmlSecC14NTransformIdStruct *xmlSecC14NTransformId;

The C14N transform id structure (xmlSecTransformTypeC14N type).


struct xmlSecC14NTransform

struct xmlSecC14NTransform {
    /* same as for xmlSecTransform but id type changed */
    xmlSecC14NTransformId 		id; 
    xmlSecTransformStatus		status;
    int					dontDestroy;
    void				*data;
    
    /* xmlSecC14NTransform specific */ 
    void				*c14nData;
};

The C14N transform structure.


xmlSecC14NTransformExecuteMethod ()

int         (*xmlSecC14NTransformExecuteMethod)
                                            (xmlSecC14NTransformPtr transform,
                                             xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodes,
                                             xmlOutputBufferPtr buffer);

Transform specific execute method. returns result in the buffer.


xmlSecC14NTransformExecute ()

int         xmlSecC14NTransformExecute      (xmlSecTransformPtr transform,
                                             xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodes,
                                             xmlOutputBufferPtr buffer);

Executes the C14N transform and returns result in the buffer (wrapper for transform specific executeC14n() method). If the trnaform is NULL then the default xmlSecC14NInclusive transform is executed.


struct xmlSecTransformState

struct xmlSecTransformState {
    /* initial state */
    xmlDocPtr				initDoc;
    xmlSecNodeSetPtr			initNodeSet;
    char				*initUri;

    /* current state: xml */    
    xmlDocPtr				curDoc;	
    xmlSecNodeSetPtr			curNodeSet;
    
    /* current state: binary */
    xmlBufferPtr			curBuf;	
    xmlSecTransformPtr			curFirstBinTransform; 
    xmlSecTransformPtr			curLastBinTransform; 

    /*  optimization: special case for c14n transforms */
    xmlSecTransformPtr			curC14NTransform; 
};

The current transforms state.


xmlSecTransformStateCreate ()

xmlSecTransformStatePtr xmlSecTransformStateCreate
                                            (xmlDocPtr doc,
                                             xmlSecNodeSetPtr nodeSet,
                                             const char *uri);

Creates new transform state.


xmlSecTransformStateDestroy ()

void        xmlSecTransformStateDestroy     (xmlSecTransformStatePtr state);

Destroys the transform state.


xmlSecTransformStateUpdate ()

int         xmlSecTransformStateUpdate      (xmlSecTransformStatePtr state,
                                             xmlSecTransformPtr transform);

Updates the current state with transform. Note all transforms are applied immidiatelly.


xmlSecTransformStateFinal ()

int         xmlSecTransformStateFinal       (xmlSecTransformStatePtr state,
                                             xmlSecTransformResult type);

Finalazies transforms state (applies all pending transforms) and creates a result of the desired type.