- Home
- Download
- News
- Documentation

- FAQ
- Tutorial
- API reference
- Examples

- XML Digital Signature

- Online Verifier

- XML Encryption
- XML Canonicalization
- Reporting Bugs
- Mailing list
- Related
- Authors

# xmldsig

## Name

xmldsig -- XML Digital Signature support.

## Synopsis

    #define             XMLSEC_DSIG_FLAGS_IGNORE_MANIFESTS
    #define             XMLSEC_DSIG_FLAGS_STORE_MANIFEST_REFERENCES
    #define             XMLSEC_DSIG_FLAGS_STORE_SIGNATURE
    #define             XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES
    #define             XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK
    struct              xmlSecDSigCtx;
    xmlSecDSigCtxPtrxmlSecDSigCtxCreate                 (xmlSecKeysMngrPtr keysMngr);
    voidxmlSecDSigCtxDebugDump              (xmlSecDSigCtxPtr dsigCtx,
                                                             FILE *output);
    voidxmlSecDSigCtxDebugXmlDump           (xmlSecDSigCtxPtr dsigCtx,
                                                             FILE *output);
    voidxmlSecDSigCtxDestroy                (xmlSecDSigCtxPtr dsigCtx);
    intxmlSecDSigCtxEnableReferenceTransform
                                                            (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecTransformId transformId);
    intxmlSecDSigCtxEnableSignatureTransform
                                                            (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecTransformId transformId);
    voidxmlSecDSigCtxFinalize               (xmlSecDSigCtxPtr dsigCtx);
    xmlSecBufferPtrxmlSecDSigCtxGetPreSignBuffer       (xmlSecDSigCtxPtr dsigCtx);
    intxmlSecDSigCtxInitialize             (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecKeysMngrPtr keysMngr);
    intxmlSecDSigCtxSign                   (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlNodePtr tmpl);
    intxmlSecDSigCtxVerify                 (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlNodePtr node);
    struct              xmlSecDSigReferenceCtx;
    xmlSecDSigReferenceCtxPtrxmlSecDSigReferenceCtxCreate  (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecDSigReferenceOrigin origin);
    voidxmlSecDSigReferenceCtxDebugDump     (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             FILE *output);
    voidxmlSecDSigReferenceCtxDebugXmlDump  (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             FILE *output);
    voidxmlSecDSigReferenceCtxDestroy       (xmlSecDSigReferenceCtxPtr dsigRefCtx);
    voidxmlSecDSigReferenceCtxFinalize      (xmlSecDSigReferenceCtxPtr dsigRefCtx);
    xmlSecBufferPtr     xmlSecDSigReferenceCtxGetPreDigestBuffer
                                                            (xmlSecDSigReferenceCtxPtr dsigRefCtx);
    intxmlSecDSigReferenceCtxInitialize    (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecDSigReferenceOrigin origin);
    xmlSecPtrListIdxmlSecDSigReferenceCtxListGetKlass  (void);
    #define             xmlSecDSigReferenceCtxListId
    intxmlSecDSigReferenceCtxProcessNode   (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             xmlNodePtr node);
    enum                xmlSecDSigReferenceOrigin;
    enum                xmlSecDSigStatus;

## Description

XML Digital Signature support.

## Details

### XMLSEC_DSIG_FLAGS_IGNORE_MANIFESTS

    #define XMLSEC_DSIG_FLAGS_IGNORE_MANIFESTS                      0x00000001

If this flag is set then <dsig:Manifests/> nodes will not be processed.

### XMLSEC_DSIG_FLAGS_STORE_MANIFEST_REFERENCES

    #define XMLSEC_DSIG_FLAGS_STORE_MANIFEST_REFERENCES             0x00000004

If this flag is set then pre-digest buffer for <dsig:Reference/> child of <dsig:Manifest/> element will be stored in xmlSecDSigCtx.

### XMLSEC_DSIG_FLAGS_STORE_SIGNATURE

    #define XMLSEC_DSIG_FLAGS_STORE_SIGNATURE                       0x00000008

If this flag is set then pre-signature buffer for <dsig:SignedInfo/> element processing will be stored in xmlSecDSigCtx.

### XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES

    #define XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES           0x00000002

If this flag is set then pre-digest buffer for <dsig:Reference/> child of <dsig:KeyInfo/> element will be stored in xmlSecDSigCtx.

### XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK

    #define XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK                       0x00000010

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 xmlSecDSigCtx

    struct xmlSecDSigCtx {
        /* these data user can set before performing the operation */
        void*                       userData;
        unsigned int                flags;
        unsigned int                flags2;
        xmlSecKeyInfoCtx            keyInfoReadCtx;
        xmlSecKeyInfoCtx            keyInfoWriteCtx;
        xmlSecTransformCtx          transformCtx;
        xmlSecTransformUriType      enabledReferenceUris;
        xmlSecPtrListPtr            enabledReferenceTransforms;
        xmlSecTransformCtxPreExecuteCallback referencePreExecuteCallback;
        xmlSecTransformId           defSignMethodId;
        xmlSecTransformId           defC14NMethodId;
        xmlSecTransformId           defDigestMethodId;

        /* these data are returned */
        xmlSecKeyPtr                signKey;
        xmlSecTransformOperation    operation;
        xmlSecBufferPtr             result;
        xmlSecDSigStatus            status;
        xmlSecTransformPtr          signMethod;
        xmlSecTransformPtr          c14nMethod;
        xmlSecTransformPtr          preSignMemBufMethod;
        xmlNodePtr                  signValueNode;
        xmlChar*                    id;
        xmlSecPtrList               signedInfoReferences;
        xmlSecPtrList               manifestReferences;

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

XML DSig processing context.

void *`userData`; | the pointer to user data (xmlsec and xmlsec-crypto libraries never touches this).
unsigned int `flags`; | the XML Digital Signature processing flags.
unsigned int `flags2`; | the XML Digital Signature processing flags.
xmlSecKeyInfoCtx `keyInfoReadCtx`; | the reading key context.
xmlSecKeyInfoCtx `keyInfoWriteCtx`; | the writing key context (not used for signature verification).
xmlSecTransformCtx `transformCtx`; | the <dsig:SignedInfo/> node processing context.
xmlSecTransformUriType `enabledReferenceUris`; | the URI types allowed for <dsig:Reference/> node.
xmlSecPtrListPtr `enabledReferenceTransforms`; | the list of transforms allowed in <dsig:Reference/> node.
xmlSecTransformCtxPreExecuteCallback `referencePreExecuteCallback`; | the callback for <dsig:Reference/> node processing.
xmlSecTransformId `defSignMethodId`; | the default signing method klass.
xmlSecTransformId `defC14NMethodId`; | the default c14n method klass.
xmlSecTransformId `defDigestMethodId`; | the default digest method klass.
xmlSecKeyPtr `signKey`; | the signature key; application may set signKey before calling xmlSecDSigCtxSign or xmlSecDSigCtxVerify functions.
xmlSecTransformOperation `operation`; | the operation: sign or verify.
xmlSecBufferPtr `result`; | the pointer to signature (not valid for signature verification).
xmlSecDSigStatus `status`; | the <dsig:Signatuire/> processing status.
xmlSecTransformPtr `signMethod`; | the pointer to signature transform.
xmlSecTransformPtr `c14nMethod`; | the pointer to c14n transform.
xmlSecTransformPtr `preSignMemBufMethod`; | the pointer to binary buffer right before signature (valid only if XMLSEC_DSIG_FLAGS_STORE_SIGNATURE flag is set).
xmlNodePtr `signValueNode`; | the pointer to <dsig:SignatureValue/> node.
xmlChar *`id`; | the pointer to Id attribute of <dsig:Signature/> node.
xmlSecPtrList `signedInfoReferences`; | the list of references in <dsig:SignedInfo/> node.
xmlSecPtrList `manifestReferences`; | the list of references in <dsig:Manifest/> nodes.
void *`reserved0`; | reserved for the future.
void *`reserved1`; | reserved for the future.

### xmlSecDSigCtxCreate ()

    xmlSecDSigCtxPtr    xmlSecDSigCtxCreate                 (xmlSecKeysMngrPtr keysMngr);

Creates <dsig:Signature/> element processing context. The caller is responsible for destroying returned object by calling xmlSecDSigCtxDestroy function.

`keysMngr` : | the pointer to keys manager.
Returns : | pointer to newly allocated context object or NULL if an error occurs.

### xmlSecDSigCtxDebugDump ()

    void                xmlSecDSigCtxDebugDump              (xmlSecDSigCtxPtr dsigCtx,
                                                             FILE *output);

Prints the debug information about `dsigCtx` to `output`.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`output` : | the pointer to output FILE.

### xmlSecDSigCtxDebugXmlDump ()

    void                xmlSecDSigCtxDebugXmlDump           (xmlSecDSigCtxPtr dsigCtx,
                                                             FILE *output);

Prints the debug information about `dsigCtx` to `output` in XML format.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`output` : | the pointer to output FILE.

### xmlSecDSigCtxDestroy ()

    void                xmlSecDSigCtxDestroy                (xmlSecDSigCtxPtr dsigCtx);

Destroy context object created with xmlSecDSigCtxCreate function.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.

### xmlSecDSigCtxEnableReferenceTransform ()

    int                 xmlSecDSigCtxEnableReferenceTransform
                                                            (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecTransformId transformId);

Enables `transformId` for <dsig:Reference/> elements processing.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`transformId` : | the transform klass.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecDSigCtxEnableSignatureTransform ()

    int                 xmlSecDSigCtxEnableSignatureTransform
                                                            (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecTransformId transformId);

Enables `transformId` for <dsig:SignedInfo/> element processing.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`transformId` : | the transform klass.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecDSigCtxFinalize ()

    void                xmlSecDSigCtxFinalize               (xmlSecDSigCtxPtr dsigCtx);

Cleans up `dsigCtx` object initialized with xmlSecDSigCtxInitialize function.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.

### xmlSecDSigCtxGetPreSignBuffer ()

    xmlSecBufferPtr     xmlSecDSigCtxGetPreSignBuffer       (xmlSecDSigCtxPtr dsigCtx);

Gets pointer to the buffer with serialized <dsig:SignedInfo/> element just before signature claculation (valid if and only if XMLSEC_DSIG_FLAGS_STORE_SIGNATURE context flag is set.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecDSigCtxInitialize ()

    int                 xmlSecDSigCtxInitialize             (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecKeysMngrPtr keysMngr);

Initializes <dsig:Signature/> element processing context. The caller is responsible for cleaning up returned object by calling xmlSecDSigCtxFinalize function.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`keysMngr` : | the pointer to keys manager.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecDSigCtxSign ()

    int                 xmlSecDSigCtxSign                   (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlNodePtr tmpl);

Signs the data as described in `tmpl` node.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`tmpl` : | the pointer to <dsig:Signature/> node with signature template.
Returns : | 0 on success or a negative value if an error occurs.

### xmlSecDSigCtxVerify ()

    int                 xmlSecDSigCtxVerify                 (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlNodePtr node);

Vaidates signature in the `node`. The verification result is returned in status member of the `dsigCtx` object.

`dsigCtx` : | the pointer to <dsig:Signature/> processing context.
`node` : | the pointer with <dsig:Signature/> node.
Returns : | 0 on success (check status member of `dsigCtx` to get signature verification result) or a negative value if an error occurs.

### struct xmlSecDSigReferenceCtx

    struct xmlSecDSigReferenceCtx {
        void*                       userData;
        xmlSecDSigCtxPtr            dsigCtx;
        xmlSecDSigReferenceOrigin   origin;
        xmlSecTransformCtx          transformCtx;
        xmlSecTransformPtr          digestMethod;

        xmlSecBufferPtr             result;
        xmlSecDSigStatus            status;
        xmlSecTransformPtr          preDigestMemBufMethod;
        xmlChar*                    id;
        xmlChar*                    uri;
        xmlChar*                    type;

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

The <dsig:Reference/> processing context.

void *`userData`; | the pointer to user data (xmlsec and xmlsec-crypto libraries never touches this).
xmlSecDSigCtxPtr `dsigCtx`; | the pointer to "parent" <dsig:Signature/> processing context.
xmlSecDSigReferenceOrigin `origin`; | the signature origin (<dsig:SignedInfo/> or <dsig:Manifest/>).
xmlSecTransformCtx `transformCtx`; | the reference processing transforms context.
xmlSecTransformPtr `digestMethod`; | the pointer to digest transform.
xmlSecBufferPtr `result`; | the pointer to digest result.
xmlSecDSigStatus `status`; | the reference processing status.
xmlSecTransformPtr `preDigestMemBufMethod`; | the pointer to binary buffer right before digest (valid only if either XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES or XMLSEC_DSIG_FLAGS_STORE_MANIFEST_REFERENCES flags are set).
xmlChar *`id`; | the <dsig:Reference/> node ID attribute.
xmlChar *`uri`; | the <dsig:Reference/> node URI attribute.
xmlChar *`type`; | the <dsig:Reference/> node Type attribute.
void *`reserved0`; | reserved for the future.
void *`reserved1`; | reserved for the future.

### xmlSecDSigReferenceCtxCreate ()

    xmlSecDSigReferenceCtxPtr xmlSecDSigReferenceCtxCreate  (xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecDSigReferenceOrigin origin);

Creates new <dsig:Reference/> element processing context. Caller is responsible for destroying the returned context by calling xmlSecDSigReferenceCtxDestroy function.

`dsigCtx` : | the pointer to parent <dsig:Signature/> node processing context.
`origin` : | the reference origin (<dsig:SignedInfo/> or <dsig:Manifest/> node).
Returns : | pointer to newly created context or NULL if an error occurs.

### xmlSecDSigReferenceCtxDebugDump ()

    void                xmlSecDSigReferenceCtxDebugDump     (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             FILE *output);

Prints debug information about `dsigRefCtx` to `output`.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.
`output` : | the pointer to output FILE.

### xmlSecDSigReferenceCtxDebugXmlDump ()

    void                xmlSecDSigReferenceCtxDebugXmlDump  (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             FILE *output);

Prints debug information about `dsigRefCtx` to `output` in output format.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.
`output` : | the pointer to output FILE.

### xmlSecDSigReferenceCtxDestroy ()

    void                xmlSecDSigReferenceCtxDestroy       (xmlSecDSigReferenceCtxPtr dsigRefCtx);

Destroy context object created with xmlSecDSigReferenceCtxCreate function.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.

### xmlSecDSigReferenceCtxFinalize ()

    void                xmlSecDSigReferenceCtxFinalize      (xmlSecDSigReferenceCtxPtr dsigRefCtx);

Cleans up context object created with xmlSecDSigReferenceCtxInitialize function.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.

### xmlSecDSigReferenceCtxGetPreDigestBuffer ()

    xmlSecBufferPtr     xmlSecDSigReferenceCtxGetPreDigestBuffer
                                                            (xmlSecDSigReferenceCtxPtr dsigRefCtx);

Gets the results of <dsig:Reference/> node processing just before digesting (valid only if XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES or XMLSEC_DSIG_FLAGS_STORE_MANIFEST_REFERENCES flas of signature context is set).

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.
Returns : | pointer to the buffer or NULL if an error occurs.

### xmlSecDSigReferenceCtxInitialize ()

    int                 xmlSecDSigReferenceCtxInitialize    (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             xmlSecDSigCtxPtr dsigCtx,
                                                             xmlSecDSigReferenceOrigin origin);

Initializes new <dsig:Reference/> element processing context. Caller is responsible for cleaning up the returned context by calling xmlSecDSigReferenceCtxFinalize function.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.
`dsigCtx` : | the pointer to parent <dsig:Signature/> node processing context.
`origin` : | the reference origin (<dsig:SignedInfo/> or <dsig:Manifest/> node).
Returns : | 0 on succes or aa negative value otherwise.

### xmlSecDSigReferenceCtxListGetKlass ()

    xmlSecPtrListId     xmlSecDSigReferenceCtxListGetKlass  (void);

The <dsig:Reference/> element processing contexts list klass.

Returns : | <dsig:Reference/> element processing context list klass.

### xmlSecDSigReferenceCtxListId

    #define             xmlSecDSigReferenceCtxListId

The references list klass.

### xmlSecDSigReferenceCtxProcessNode ()

    int                 xmlSecDSigReferenceCtxProcessNode   (xmlSecDSigReferenceCtxPtr dsigRefCtx,
                                                             xmlNodePtr node);

The Reference Element (http://www.w3.org/TR/xmldsig-core/sec-Reference)

Reference is an element that may occur one or more times. It specifies a digest algorithm and digest value, and optionally an identifier of the object being signed, the type of the object, and/or a list of transforms to be applied prior to digesting. The identification (URI) and transforms describe how the digested content (i.e., the input to the digest method) was created. The Type attribute facilitates the processing of referenced data. For example, while this specification makes no requirements over external data, an application may wish to signal that the referent is a Manifest. An optional ID attribute permits a Reference to be referenced from elsewhere.

`dsigRefCtx` : | the pointer to <dsig:Reference/> element processing context.
`node` : | the pointer to <dsig:Reference/> node.
Returns : | 0 on succes or aa negative value otherwise.

### enum xmlSecDSigReferenceOrigin

    typedef enum {
        xmlSecDSigReferenceOriginSignedInfo,
        xmlSecDSigReferenceOriginManifest
    } xmlSecDSigReferenceOrigin;

The possible <dsig:Reference/> node locations: in the <dsig:SignedInfo/> node or in the <dsig:Manifest/> node.

`xmlSecDSigReferenceOriginSignedInfo` | reference in <dsig:SignedInfo> node.
`xmlSecDSigReferenceOriginManifest` | reference <dsig:Manifest> node.

### enum xmlSecDSigStatus

    typedef enum {
        xmlSecDSigStatusUnknown = 0,
        xmlSecDSigStatusSucceeded,
        xmlSecDSigStatusInvalid
    } xmlSecDSigStatus;

XML Digital signature processing status.

`xmlSecDSigStatusUnknown` | the status is unknown.
`xmlSecDSigStatusSucceeded` | the processing succeeded.
`xmlSecDSigStatusInvalid` | the processing failed.