xmlenc: XML Security Library Reference Manual

Home Download GitHub News Documentation FAQ Tutorial API reference Examples XML Digital Signature XML Encryption XML Canonicalization Reporting Bugs Mailing list Related Authors
## 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. |