XML Security Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# xmldsig.h

## Name

xmldsig.h -- The XML Digital Signature standard implementation.

## Synopsis

    struct      xmlSecDSigCtx;
    xmlSecDSigCtxPtr xmlSecDSigCtxCreate        (xmlSecKeysMngrPtr keysMngr);
    void        xmlSecDSigCtxDestroy            (xmlSecDSigCtxPtr ctx);
    int         xmlSecDSigValidate              (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlSecKeyPtr key,
                                                 xmlNodePtr signNode,
                                                 xmlSecDSigResultPtr *result);
    int         xmlSecDSigGenerate              (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlSecKeyPtr key,
                                                 xmlNodePtr signNode,
                                                 xmlSecDSigResultPtr *result);
    struct      xmlSecDSigResult;
    struct      xmlSecReferenceResult;
    enum        xmlSecReferenceType;
    xmlSecDSigResultPtr xmlSecDSigResultCreate  (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlNodePtr signNode,
                                                 int sign);
    void        xmlSecDSigResultDestroy         (xmlSecDSigResultPtr result);
    void        xmlSecDSigResultDebugDump       (xmlSecDSigResultPtr result,
                                                 FILE *output);
    xmlNodePtr  xmlSecSignatureCreate           (const xmlChar *id);
    void        xmlSecSignatureDestroy          (xmlNodePtr signNode);
    xmlNodePtr  xmlSecSignatureAddSignedInfo    (xmlNodePtr signNode,
                                                 const xmlChar *id);
    xmlNodePtr  xmlSecSignatureAddKeyInfo       (xmlNodePtr signNode,
                                                 const xmlChar *id);
    xmlNodePtr  xmlSecSignatureAddObject        (xmlNodePtr signNode,
                                                 const xmlChar *id,
                                                 const xmlChar *mimeType,
                                                 const xmlChar *encoding);
    xmlNodePtr  xmlSecSignedInfoAddC14NMethod   (xmlNodePtr signedInfoNode,
                                                 xmlSecTransformId c14nMethod);
    xmlNodePtr  xmlSecSignedInfoAddSignMethod   (xmlNodePtr signedInfoNode,
                                                 xmlSecTransformId signMethod);
    xmlNodePtr  xmlSecSignedInfoAddReference    (xmlNodePtr signedInfoNode,
                                                 const xmlChar *id,
                                                 const xmlChar *uri,
                                                 const xmlChar *type);
    xmlNodePtr  xmlSecReferenceAddDigestMethod  (xmlNodePtr refNode,
                                                 xmlSecTransformId digestMethod);
    xmlNodePtr  xmlSecReferenceAddTransform     (xmlNodePtr refNode,
                                                 xmlSecTransformId transform);
    xmlNodePtr  xmlSecObjectAddSignProperties   (xmlNodePtr objectNode,
                                                 const xmlChar *id,
                                                 const xmlChar *target);
    xmlNodePtr  xmlSecObjectAddManifest         (xmlNodePtr objectNode,
                                                 const xmlChar *id);
    xmlNodePtr  xmlSecManifestAddReference      (xmlNodePtr manifestNode,
                                                 const xmlChar *id,
                                                 const xmlChar *uri,
                                                 const xmlChar *type);

## Description

## Details

### struct xmlSecDSigCtx

    struct xmlSecDSigCtx {
        xmlSecKeysMngrPtr		keysMngr;
        int				processManifests;
        int				storeSignatures;
        int				storeReferences;
        int				storeManifests;
        int				fakeSignatures;
        time_t			certsVerificationTime;
    };

XML DSig context.

xmlSecKeysMngrPtr `keysMngr` | the keys manager xmlSecKeysMngr.
int `processManifests` | if 0 then <dsig:Manifests> nodes are not processed.
int `storeSignatures` | store the signed content just (<dsig:SignedInfo> element) before applying signature.
int `storeReferences` | store the result of processing <dsig:Reference> nodes in <dsig:SignedInfo> nodes just before digesting.
int `storeManifests` | store the result of processing <dsig:Reference> nodes in <dsig:Manifest> nodes just before digesting (ignored if `processManifest` is 0).
int `fakeSignatures` | for performance testing only.
time_t `certsVerificationTime` |

### xmlSecDSigCtxCreate ()

    xmlSecDSigCtxPtr xmlSecDSigCtxCreate        (xmlSecKeysMngrPtr keysMngr);

Creates new xmlSecDSigCtx structure.

`keysMngr` : | the pointer to xmlSecKeysMngr structure
Returns : | pointer to newly allocated xmlSecDSigCtx structure or NULL if an error occurs.

### xmlSecDSigCtxDestroy ()

    void        xmlSecDSigCtxDestroy            (xmlSecDSigCtxPtr ctx);

Destroys xmlSecDSigCtx structure `ctx`.

`ctx` : | the pointer to xmlSecDSigCtx structure.

### xmlSecDSigValidate ()

    int         xmlSecDSigValidate              (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlSecKeyPtr key,
                                                 xmlNodePtr signNode,
                                                 xmlSecDSigResultPtr *result);

Validates the signature in `signNode` and stores the pointer to validation result structure xmlSecDSigResult in the `result`.

`ctx` : | the pointer to xmlSecDSigCtx structure.
`context` : | the pointer to application specific data that will be passed to all callback functions.
`key` : | the key to use (if NULL then the key specified in <dsig:KeyInfo> will be used).
`signNode` : | the pointer to <dsig:Signature> node that will be validated.
`result` : | the pointer where to store validation results.
Returns : | 0 if there were no processing errors during validation or a negative value otherwise. The return value equal to 0 DOES NOT mean that the signature is valid: check the result member of xmlSecDSigResult structure instead.

### xmlSecDSigGenerate ()

    int         xmlSecDSigGenerate              (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlSecKeyPtr key,
                                                 xmlNodePtr signNode,
                                                 xmlSecDSigResultPtr *result);

Signs the data according to the template in `signNode` node.

`ctx` : | the pointer to xmlSecDSigCtx structure.
`context` : | the pointer to application specific data that will be passed to all callback functions.
`key` : | the key to use (if NULL then the key specified in <dsig:KeyInfo> will be used).
`signNode` : | the pointer to <dsig:Signature> node template.
`result` : | the pointer where to store signature results.
Returns : | 0 on success and a negative value otherwise.

### struct xmlSecDSigResult

    struct xmlSecDSigResult {
        xmlSecDSigCtxPtr		ctx;
        void			*context;
        xmlNodePtr			self;
        int				sign;
        xmlSecTransformStatus	result;
        xmlSecTransformId		signMethod;
        xmlSecKeyPtr		key;
        xmlSecReferenceResultPtr	firstSignRef;
        xmlSecReferenceResultPtr	lastSignRef;
        xmlSecReferenceResultPtr	firstManifestRef;
        xmlSecReferenceResultPtr	lastManifestRef;
        xmlBufferPtr		buffer;
    };

XML DSig Result.

xmlSecDSigCtxPtr `ctx` | the DSig context xmlSecDSigCtx.
void *`context` | the pointer to application specific data.
xmlNodePtr `self` | the pointer to <dsig:Signature> node.
int `sign` | the sign/verify flag.
xmlSecTransformStatus `result` | the signature verification/generation status.
xmlSecTransformId `signMethod` | the signature algorithm .
xmlSecKeyPtr `key` | the pointer to signature key.
xmlSecReferenceResultPtr `firstSignRef` | the pointer to the first <dsig:SignedInfo> reference result.
xmlSecReferenceResultPtr `lastSignRef` | the pointer to the last <dsig:SignedInfo> reference result.
xmlSecReferenceResultPtr `firstManifestRef` | the pointer to the first <dsig:Manifest> reference result (valid only if the processManifests flag in `ctx` is set to 1).
xmlSecReferenceResultPtr `lastManifestRef` | the pointer to the last <dsig:Manifest> reference result (valid only if the processManifests flag in `ctx` is set to 1).
xmlBufferPtr `buffer` | the pointer to the signed content - the canonicalization of <dsig:SignedInfo> node (valid only if the storeSignatures flag in ctx structure is set to 1).

### struct xmlSecReferenceResult

    struct xmlSecReferenceResult {
        xmlSecDSigCtxPtr		ctx;
        xmlNodePtr			self;
        xmlSecReferenceType		refType;
        xmlSecTransformStatus	result;
        xmlSecReferenceResultPtr	next;
        xmlSecReferenceResultPtr	prev;
        xmlChar			*uri;
        xmlChar			*id;
        xmlChar			*type;
        xmlSecTransformId		digestMethod;
        xmlBufferPtr		buffer;
    };

The result of <dsig:Reference> processing.

xmlSecDSigCtxPtr `ctx` | the pointer to DSig context.
xmlNodePtr `self` | the pointer to <dsig:Reference> node.
xmlSecReferenceType `refType` | the <dsig:Reference> node location.
xmlSecTransformStatus `result` | the verification/generation result.
xmlSecReferenceResultPtr `next` | the next reference result.
xmlSecReferenceResultPtr `prev` | the prev reference result.
xmlChar *`uri` | the <dsig:Reference> node URI attribute.
xmlChar *`id` | the <dsig:Reference> node Id attribute.
xmlChar *`type` | the <dsig:Reference> node Type attribute.
xmlSecTransformId `digestMethod` | the used digest algorithm id.
xmlBufferPtr `buffer` | the pointer to digested content (valid only if the storeReferences or storeManifests flags in xmlSecDSigCtx).

### enum xmlSecReferenceType

    typedef enum  {
        xmlSecSignedInfoReference,
        xmlSecManifestReference
    } xmlSecReferenceType;

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

`xmlSecSignedInfoReference` | reference in <dsig:SignedInfo> node.
`xmlSecManifestReference` | reference <dsig:Manifest> node.

### xmlSecDSigResultCreate ()

    xmlSecDSigResultPtr xmlSecDSigResultCreate  (xmlSecDSigCtxPtr ctx,
                                                 void *context,
                                                 xmlNodePtr signNode,
                                                 int sign);

Creates new xmlSecDSigResult structure.

`ctx` : | the pointer to xmlSecDSigCtx structure.
`context` : | the pointer to application specific data that will be passed to all callback functions.
`signNode` : | the pointer to <dsig:Signature> node that will be validated.
`sign` : | the sign or verify flag.
Returns : | newly created xmlSecDSigResult structure or NULL if an error occurs.

### xmlSecDSigResultDestroy ()

    void        xmlSecDSigResultDestroy         (xmlSecDSigResultPtr result);

Destroys the xmlSecDSigResult structure `result`.

`result` : | the pointer to xmlSecDSigResult structure.

### xmlSecDSigResultDebugDump ()

    void        xmlSecDSigResultDebugDump       (xmlSecDSigResultPtr result,
                                                 FILE *output);

Prints the xmlSecDSigResult structure `result` to file `output`.

`result` : | the pointer to xmlSecDSigResult structure.
`output` : | the pointer to destination FILE.

### xmlSecSignatureCreate ()

    xmlNodePtr  xmlSecSignatureCreate           (const xmlChar *id);

Creates new <dsig:Signature> node with the mandatory <dsig:SignatureValue> child. The application is responsible for inserting the returned node in the XML document.

`id` : | the node id (may be NULL).
Returns : | the pointer to newly created <dsig:Signature> node or NULL if an error occurs.

### xmlSecSignatureDestroy ()

    void        xmlSecSignatureDestroy          (xmlNodePtr signNode);

Destroys standalone <dsig:Signature> node. You MUST not call this function if the <dsig:Signature> node was inserted in the XML document.

`signNode` : | the pointer to <dsig:Signature> node.

### xmlSecSignatureAddSignedInfo ()

    xmlNodePtr  xmlSecSignatureAddSignedInfo    (xmlNodePtr signNode,
                                                 const xmlChar *id);

Adds <dsig:SignedInfo> node to the <dsig:Signature> node `signNode`.

`signNode` : | the pointer to <dsig:Signature> node.
`id` : | the node id (may be NULL).
Returns : | the pointer to newly created <dsig:SignedInfo> node or NULL if an error occurs.

### xmlSecSignatureAddKeyInfo ()

    xmlNodePtr  xmlSecSignatureAddKeyInfo       (xmlNodePtr signNode,
                                                 const xmlChar *id);

Adds <dsig:KeyInfo> node to the <dsig:Signature> node `signNode`.

`signNode` : | the pointer to <dsig:Signature> node.
`id` : | the node id (may be NULL).
Returns : | the pointer to newly created <dsig:KeyInfo> node or NULL if an error occurs.

### xmlSecSignatureAddObject ()

    xmlNodePtr  xmlSecSignatureAddObject        (xmlNodePtr signNode,
                                                 const xmlChar *id,
                                                 const xmlChar *mimeType,
                                                 const xmlChar *encoding);

Adds <dsig:Object> node to the <dsig:Signature> node `signNode`.

`signNode` : | the pointer to <dsig:Signature> node.
`id` : | the node id (may be NULL).
`mimeType` : | the object mime type (may be NULL).
`encoding` : | the object encoding (may be NULL).
Returns : | the pointer to newly created <dsig:Object> node or NULL if an error occurs.

### xmlSecSignedInfoAddC14NMethod ()

    xmlNodePtr  xmlSecSignedInfoAddC14NMethod   (xmlNodePtr signedInfoNode,
                                                 xmlSecTransformId c14nMethod);

Adds <dsig:CanonicalizationMethod> node with specified C14N algorithm `c14nMethod` to the <dsig:SignedInfo> node `signedInfoNode`.

`signedInfoNode` : | the pointer to <dsig:SignedInfo> node.
`c14nMethod` : | the c14n method id.
Returns : | the pointer to newly created <dsig:CanonicalizationMethod> node or NULL if an error occurs.

### xmlSecSignedInfoAddSignMethod ()

    xmlNodePtr  xmlSecSignedInfoAddSignMethod   (xmlNodePtr signedInfoNode,
                                                 xmlSecTransformId signMethod);

Adds <dsig:SignatureMethod> node with given signature algorithm `signMethod` to the <dsig:SignedInfo> node `signedInfoNode`.

`signedInfoNode` : | the pointer to <dsig:SignedInfo> node.
`signMethod` : | the result method id.
Returns : | the pointer to newly created <dsig:SignatureMethod> node or NULL if an error occurs.

### xmlSecSignedInfoAddReference ()

    xmlNodePtr  xmlSecSignedInfoAddReference    (xmlNodePtr signedInfoNode,
                                                 const xmlChar *id,
                                                 const xmlChar *uri,
                                                 const xmlChar *type);

Adds <dsig:Reference> node with given URI (`uri`), Id (`id`) and Type (`type`) attributes and the required child node <dsig:DigestValue> to the <dsig:SignedInfo> node `signedInfoNode`.

`signedInfoNode` : | the pointer to <dsig:SignedInfo> node.
`id` : | the node id (may be NULL).
`uri` : | the reference node uri (may be NULL).
`type` : | the reference node type (may be NULL).
Returns : | the pointer to newly created <dsig:Reference> node or NULL if an error occurs.

### xmlSecReferenceAddDigestMethod ()

    xmlNodePtr  xmlSecReferenceAddDigestMethod  (xmlNodePtr refNode,
                                                 xmlSecTransformId digestMethod);

Adds <dsig:DigestMethod> node with given digest algorithm (`digestMethod`) to the <dsig:Reference> node `refNode`.

`refNode` : | the pointer to <dsig:Reference> node.
`digestMethod` : | the digest method id.
Returns : | the pointer to newly created <dsig:DigestMethod> node or NULL if an error occurs.

### xmlSecReferenceAddTransform ()

    xmlNodePtr  xmlSecReferenceAddTransform     (xmlNodePtr refNode,
                                                 xmlSecTransformId transform);

Adds <dsig:Transform> node to the <dsig:Reference> node `refNode`.

`refNode` : | the pointer to <dsig:Reference> node.
`transform` : | the transform method id.
Returns : | the pointer to newly created <dsig:Transform> node or NULL if an error occurs.

### xmlSecObjectAddSignProperties ()

    xmlNodePtr  xmlSecObjectAddSignProperties   (xmlNodePtr objectNode,
                                                 const xmlChar *id,
                                                 const xmlChar *target);

Adds <dsig:SignatureProperties> node to the <dsig:Object> node `objectNode`.

`objectNode` : | the pointer to <dsig:Object> node.
`id` : | the node id (may be NULL).
`target` : | the Target (may be NULL).
Returns : | the pointer to newly created <dsig:SignatureProperties> node or NULL if an error occurs.

### xmlSecObjectAddManifest ()

    xmlNodePtr  xmlSecObjectAddManifest         (xmlNodePtr objectNode,
                                                 const xmlChar *id);

Adds <dsig:Manifest> node to the <dsig:Object> node `objectNode`.

`objectNode` : | the pointer to <dsig:Object> node.
`id` : | the node id (may be NULL).
Returns : | the pointer to newly created <dsig:Manifest> node or NULL if an error occurs.

### xmlSecManifestAddReference ()

    xmlNodePtr  xmlSecManifestAddReference      (xmlNodePtr manifestNode,
                                                 const xmlChar *id,
                                                 const xmlChar *uri,
                                                 const xmlChar *type);

Adds <dsig:Reference> node with specified URI (`uri`), Id (`id`) and Type (`type`) attributes and the required child node <dsig:DigestValue> to the <dsig:Manifest> node `manifestNode`:.

`manifestNode` : | the pointer to <dsig:Manifest> node.
`id` : | the node id (may be NULL).
`uri` : | the reference node uri (may be NULL).
`type` : | the reference node type (may be NULL).
Returns : | the pointer to newly created <dsig:Reference> node or NULL if an error occurs.

<<< Previous Page | Home | Up | Next Page >>>
xmlsec.h | xmlenc.h