xmlenc: XML Security Library Reference Manual

xmlenc

xmlenc — XML Encryption support.

Stability Level

Stable, unless otherwise indicated

Functions

xmlSecEncCtxPtr	xmlSecEncCtxCreate ()
void	xmlSecEncCtxDestroy ()
int	xmlSecEncCtxInitialize ()
void	xmlSecEncCtxFinalize ()
int	xmlSecEncCtxCopyUserPref ()
void	xmlSecEncCtxReset ()
int	xmlSecEncCtxBinaryEncrypt ()
int	xmlSecEncCtxXmlEncrypt ()
int	xmlSecEncCtxUriEncrypt ()
int	xmlSecEncCtxDecrypt ()
xmlSecBufferPtr	xmlSecEncCtxDecryptToBuffer ()
void	xmlSecEncCtxDebugDump ()
void	xmlSecEncCtxDebugXmlDump ()

Types and Values

enum	xmlEncCtxMode
#define	XMLSEC_ENC_RETURN_REPLACED_NODE
struct	xmlSecEncCtx

Description

XML Encryption implementation.

Functions

xmlSecEncCtxCreate ()

xmlSecEncCtxPtr
xmlSecEncCtxCreate (xmlSecKeysMngrPtr keysMngr);

Creates <enc:EncryptedData/> element processing context. The caller is responsible for destroying returned object by calling xmlSecEncCtxDestroy function.

Parameters

keysMngr

the pointer to keys manager.

Returns

pointer to newly allocated context object or NULL if an error occurs.

xmlSecEncCtxDestroy ()

void
xmlSecEncCtxDestroy (xmlSecEncCtxPtr encCtx);

Destroy context object created with xmlSecEncCtxCreate function.

Parameters

encCtx

the pointer to <enc:EncryptedData/> processing context.

xmlSecEncCtxInitialize ()

int
xmlSecEncCtxInitialize (xmlSecEncCtxPtr encCtx,
                        xmlSecKeysMngrPtr keysMngr);

Initializes <enc:EncryptedData/> element processing context. The caller is responsible for cleaning up returned object by calling xmlSecEncCtxFinalize function.

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
keysMngr	the pointer to keys manager.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxFinalize ()

void
xmlSecEncCtxFinalize (xmlSecEncCtxPtr encCtx);

Cleans up encCtx object.

Parameters

encCtx

the pointer to <enc:EncryptedData/> processing context.

xmlSecEncCtxCopyUserPref ()

int
xmlSecEncCtxCopyUserPref (xmlSecEncCtxPtr dst,
                          xmlSecEncCtxPtr src);

Copies user preference from src context to dst .

Parameters

dst	the pointer to destination context.
src	the pointer to source context.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxReset ()

void
xmlSecEncCtxReset (xmlSecEncCtxPtr encCtx);

Resets encCtx object, user settings are not touched.

Parameters

encCtx

the pointer to <enc:EncryptedData/> processing context.

xmlSecEncCtxBinaryEncrypt ()

int
xmlSecEncCtxBinaryEncrypt (xmlSecEncCtxPtr encCtx,
                           xmlNodePtr tmpl,
                           const xmlSecByte *data,
                           xmlSecSize dataSize);

Encrypts data according to template tmpl .

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
tmpl	the pointer to <enc:EncryptedData/> template node.
data	the pointer for binary buffer.
dataSize	the `data` buffer size.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxXmlEncrypt ()

int
xmlSecEncCtxXmlEncrypt (xmlSecEncCtxPtr encCtx,
                        xmlNodePtr tmpl,
                        xmlNodePtr node);

Encrypts node according to template tmpl . If requested, node is replaced with result <enc:EncryptedData/> node.

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
tmpl	the pointer to <enc:EncryptedData/> template node.
node	the pointer to node for encryption.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxUriEncrypt ()

int
xmlSecEncCtxUriEncrypt (xmlSecEncCtxPtr encCtx,
                        xmlNodePtr tmpl,
                        const xmlChar *uri);

Encrypts data from uri according to template tmpl .

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
tmpl	the pointer to <enc:EncryptedData/> template node.
uri	the URI.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxDecrypt ()

int
xmlSecEncCtxDecrypt (xmlSecEncCtxPtr encCtx,
                     xmlNodePtr node);

Decrypts node and if necessary replaces node with decrypted data.

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
node	the pointer to <enc:EncryptedData/> node.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxDecryptToBuffer ()

xmlSecBufferPtr
xmlSecEncCtxDecryptToBuffer (xmlSecEncCtxPtr encCtx,
                             xmlNodePtr node);

Decrypts node data to the encCtx buffer.

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
node	the pointer to <enc:EncryptedData/> node.

Returns

0 on success or a negative value if an error occurs.

xmlSecEncCtxDebugDump ()

void
xmlSecEncCtxDebugDump (xmlSecEncCtxPtr encCtx,
                       FILE *output);

Prints the debug information about encCtx to output .

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
output	the pointer to output FILE.

xmlSecEncCtxDebugXmlDump ()

void
xmlSecEncCtxDebugXmlDump (xmlSecEncCtxPtr encCtx,
                          FILE *output);

Prints the debug information about encCtx to output in XML format.

Parameters

encCtx	the pointer to <enc:EncryptedData/> processing context.
output	the pointer to output FILE.

Types and Values

enum xmlEncCtxMode

The xmlSecEncCtx mode.

Members

xmlEncCtxModeEncryptedData	the <enc:EncryptedData/> element procesing.
xmlEncCtxModeEncryptedKey	the <enc:EncryptedKey/> element processing.

XMLSEC_ENC_RETURN_REPLACED_NODE

#define XMLSEC_ENC_RETURN_REPLACED_NODE                 0x00000001

If this flag is set, then the replaced node will be returned in the replacedNodeList

struct xmlSecEncCtx

struct xmlSecEncCtx {
    /* these data user can set before performing the operation */
    void*                       userData;
    unsigned int                flags;
    unsigned int                flags2;
    xmlEncCtxMode               mode;
    xmlSecKeyInfoCtx            keyInfoReadCtx;
    xmlSecKeyInfoCtx            keyInfoWriteCtx;
    xmlSecTransformCtx          transformCtx;
    xmlSecTransformId           defEncMethodId;

    /* these data are returned */
    xmlSecKeyPtr                encKey;
    xmlSecTransformOperation    operation;
    xmlSecBufferPtr             result;
    int                         resultBase64Encoded;
    int                         resultReplaced;
    xmlSecTransformPtr          encMethod;

    /* attributes from EncryptedData or EncryptedKey */
    xmlChar*                    id;
    xmlChar*                    type;
    xmlChar*                    mimeType;
    xmlChar*                    encoding;
    xmlChar*                    recipient;
    xmlChar*                    carriedKeyName;

    /* these are internal data, nobody should change that except us */
    xmlNodePtr                  encDataNode;
    xmlNodePtr                  encMethodNode;
    xmlNodePtr                  keyInfoNode;
    xmlNodePtr                  cipherValueNode;

    xmlNodePtr                  replacedNodeList; /* the pointer to the replaced node */
    void*                       reserved1;        /* reserved for future */
};

XML Encryption context.

Members

void *`userData`;	the pointer to user data (xmlsec and xmlsec-crypto libraries never touches this).
unsigned int `flags`;	the XML Encryption processing flags.
unsigned int `flags2`;	the XML Encryption processing flags.
xmlEncCtxMode `mode`;	the mode.
xmlSecKeyInfoCtx `keyInfoReadCtx`;	the reading key context.
xmlSecKeyInfoCtx `keyInfoWriteCtx`;	the writing key context (not used for signature verification).
xmlSecTransformCtx `transformCtx`;	the transforms processing context.
xmlSecTransformId `defEncMethodId`;	the default encryption method (used if <enc:EncryptionMethod/> node is not present).
xmlSecKeyPtr `encKey`;	the signature key; application may set encKey before calling encryption/decryption functions.
xmlSecTransformOperation `operation`;	the operation: encrypt or decrypt.
xmlSecBufferPtr `result`;	the pointer to signature (not valid for signature verification).
int `resultBase64Encoded`;	the flag: if set then result in result is base64 encoded.
int `resultReplaced`;	the flag: if set then resulted <enc:EncryptedData/> or <enc:EncryptedKey/> node is added to the document.
xmlSecTransformPtr `encMethod`;	the pointer to encryption transform.
xmlChar *`id`;	the ID attribute of <enc:EncryptedData/> or <enc:EncryptedKey/> node.
xmlChar *`type`;	the Type attribute of <enc:EncryptedData/> or <enc:EncryptedKey/> node.
xmlChar *`mimeType`;	the MimeType attribute of <enc:EncryptedData/> or <enc:EncryptedKey/> node.
xmlChar *`encoding`;	the Encoding attributeof <enc:EncryptedData/> or <enc:EncryptedKey/> node.
xmlChar *`recipient`;	the Recipient attribute of <enc:EncryptedKey/> node..
xmlChar *`carriedKeyName`;	the CarriedKeyName attribute of <enc:EncryptedKey/> node.
xmlNodePtr `encDataNode`;	the pointer to <enc:EncryptedData/> or <enc:EncryptedKey/> node.
xmlNodePtr `encMethodNode`;	the pointer to <enc:EncryptionMethod/> node.
xmlNodePtr `keyInfoNode`;	the pointer to <enc:KeyInfo/> node.
xmlNodePtr `cipherValueNode`;	the pointer to <enc:CipherValue/> node.
xmlNodePtr `replacedNodeList`;	the first node of the list of replaced nodes depending on the nodeReplacementMode
void *`reserved1`;	reserved for the future.