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 ()
xmlSecKeyPtr	xmlSecEncCtxDerivedKeyGenerate ()
xmlSecKeyPtr	xmlSecEncCtxAgreementMethodGenerate ()
int	xmlSecEncCtxAgreementMethodXmlWrite ()
const char *	xmlSecEncCtxGetFailureReasonString ()

Types and Values

enum	xmlEncCtxMode
enum	xmlSecEncFailureReason
#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 result.

Parameters

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

Returns

a buffer with key on success or NULL 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.

xmlSecEncCtxDerivedKeyGenerate ()

xmlSecKeyPtr
xmlSecEncCtxDerivedKeyGenerate (xmlSecEncCtxPtr encCtx,
                                xmlSecKeyDataId keyId,
                                xmlNodePtr node,
                                xmlSecKeyInfoCtxPtr keyInfoCtx);

Generates (derives) key from node (https://www.w3.org/TR/xmlenc-core1/sec-DerivedKey):

 <element name="DerivedKey" type="xenc11:DerivedKeyType"/>
 <complexType name="DerivedKeyType">
     <sequence>
         <element ref="xenc11:KeyDerivationMethod" minOccurs="0"/>
         <element ref="xenc:ReferenceList" minOccurs="0"/>
         <element name="DerivedKeyName" type="string" minOccurs="0"/>
         <element name="MasterKeyName" type="string" minOccurs="0"/>
     </sequence>
     <attribute name="Recipient" type="string" use="optional"/>
     <attribute name="Id" type="ID" use="optional"/>
     <attribute name="Type" type="anyURI" use="optional"/>
 </complexType>

 <element name="KeyDerivationMethod" type="xenc:KeyDerivationMethodType"/>
 <complexType name="KeyDerivationMethodType">
     <sequence>
         <any namespace="##any" minOccurs="0" maxOccurs="unbounded"/>
     </sequence>
     <attribute name="Algorithm" type="anyURI" use="required"/>
 </complexType>

Parameters

encCtx	the pointer to encryption processing context.
keyId	the expected key id, the actual derived key might have a different id.
node	the pointer to <enc11:DerivedKey/> node.
keyInfoCtx	the pointer to the "parent" key info context.

Returns

the derived key on success or NULL if an error occurs.

xmlSecEncCtxAgreementMethodGenerate ()

xmlSecKeyPtr
xmlSecEncCtxAgreementMethodGenerate (xmlSecEncCtxPtr encCtx,
                                     xmlSecKeyDataId keyId,
                                     xmlNodePtr node,
                                     xmlSecKeyInfoCtxPtr keyInfoCtx);

Generates (derives) key from node (https://www.w3.org/TR/xmlenc-core1/sec-AgreementMethod):

 <element name="AgreementMethod" type="xenc:AgreementMethodType"/>
 <complexType name="AgreementMethodType" mixed="true">
     <sequence>
         <element name="KA-Nonce" minOccurs="0" type="base64Binary"/>
         <!-- <element ref="ds:DigestMethod" minOccurs="0"/> -->
         <any namespace="##other" minOccurs="0" maxOccurs="unbounded"/>
         <element name="OriginatorKeyInfo" minOccurs="0" type="ds:KeyInfoType"/>
         <element name="RecipientKeyInfo" minOccurs="0" type="ds:KeyInfoType"/>
     </sequence>
     <attribute name="Algorithm" type="anyURI" use="required"/>
 </complexType>

Parameters

encCtx	the pointer to encryption processing context.
keyId	the expected key id, the actual derived key might have a different id.
node	the pointer to <enc:AgreementMethod/> node.
keyInfoCtx	the pointer to the "parent" key info context.

Returns

the generated key on success or NULL if an error occurs.

xmlSecEncCtxAgreementMethodXmlWrite ()

int
xmlSecEncCtxAgreementMethodXmlWrite (xmlSecEncCtxPtr encCtx,
                                     xmlNodePtr node,
                                     xmlSecKeyInfoCtxPtr keyInfoCtx);

xmlSecEncCtxGetFailureReasonString ()

const char *
xmlSecEncCtxGetFailureReasonString (xmlSecEncFailureReason failureReason);

Gets failure reason as a string.

Returns failure reason as a string.

Parameters

failureReason

the failure reason.

Types and Values

enum xmlEncCtxMode

The xmlSecEncCtx mode.

Members

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

enum xmlSecEncFailureReason

XML Encryption processing failure reason. The application should use the returned value from the encrypt/decrypt functions first.

Members

xmlSecEncFailureReasonUnknown	the failure reason is unknown.
xmlSecEncFailureReasonKeyNotFound	the key not found.

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;
    xmlSecEncFailureReason      failureReason;

    /* 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.
xmlSecEncFailureReason `failureReason`;	the detailed failure reason.
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.