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.