digests.h

Name

digests.h -- The digests transform.

Synopsis



struct      xmlSecDigestTransform;
typedef     xmlSecDigestTransformId;
int         (*xmlSecDigestUpdateMethod)     (xmlSecDigestTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);
int         (*xmlSecDigestSignMethod)       (xmlSecDigestTransformPtr transform,
                                             unsigned char **buffer,
                                             size_t *size);
int         (*xmlSecDigestVerifyMethod)     (xmlSecDigestTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);
int         xmlSecDigestSignNode            (xmlSecTransformPtr transform,
                                             xmlNodePtr valueNode,
                                             int removeOldContent);
int         xmlSecDigestVerifyNode          (xmlSecTransformPtr transform,
                                             const xmlNodePtr valueNode);
void        xmlSecDigestSetPushMode         (xmlSecTransformPtr transform,
                                             int enabled);
int         xmlSecDigestUpdate              (xmlSecTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);
int         xmlSecDigestSign                (xmlSecTransformPtr transform,
                                             unsigned char **buffer,
                                             size_t *size);
int         xmlSecDigestVerify              (xmlSecTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);
int         xmlSecDigestTransformRead       (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         xmlSecDigestTransformWrite      (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);
int         xmlSecDigestTransformFlush      (xmlSecBinTransformPtr transform);

Description

Details

struct xmlSecDigestTransform

struct xmlSecDigestTransform {	
    /* same as for xmlSecTransform but id type changed */
    xmlSecDigestTransformId		id;    
    xmlSecTransformStatus		status;
    int					dontDestroy;
    void				*data;
    
    /* xmlSecBinTransform specific */
    int					encode;
    xmlSecDigestTransformPtr		next;
    xmlSecDigestTransformPtr		prev;   
    void				*binData;
    
    /* xmlSecDigestTransform specific */
    int					pushModeEnabled;
    unsigned char			*digest;
    size_t				digestSize;
    unsigned char			digestLastByteMask;
    void 				*digestData;
};

The digests transform.

xmlSecDigestTransformId id the transform id (pointer to xmlSecBinTransformId).
xmlSecTransformStatus status the transform status (ok/fail/unknown).
int dontDestroy the don't automatically destroy flag.
void *data the pointer to transform specific data.
int encode encode/decode (encrypt/decrypt) flag.
xmlSecDigestTransformPtr next next binary transform in the chain.
xmlSecDigestTransformPtr prev previous binary transform in the chain.
void *binData the pointer to binary transform speific data.
int pushModeEnabled if 1 then the data are sent to next transform, otherwise we are keeping data for sign or verify call.
unsigned char *digest the internal digest buffer.
size_t digestSize the internal digest buffer size.
unsigned char digestLastByteMask 
void *digestData the pointer to digest transform specific data.


xmlSecDigestTransformId

typedef const struct _xmlSecDigestTransformIdStruct	*xmlSecDigestTransformId;

The digest transform id (xmlSecTransformTypeBinary type).


xmlSecDigestUpdateMethod ()

int         (*xmlSecDigestUpdateMethod)     (xmlSecDigestTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);

Updates digest with new chunk of data.

transform : the pointer to digests transform xmlSecDigestTransform.
buffer : the input data.
size : the input data size.
Returns :0 on success or a negative value otherwise.


xmlSecDigestSignMethod ()

int         (*xmlSecDigestSignMethod)       (xmlSecDigestTransformPtr transform,
                                             unsigned char **buffer,
                                             size_t *size);

Finalizes digest and returns result in allocated buffer (buffer, size). The caller is responsible for freeing returned buffer with xmlFree() function.

transform : the pointer to digests transform xmlSecDigestTransform.
buffer : the pointer to pointer to the output data.
size : the pointer to outut data size.
Returns :0 on success or a negative value otherwise.


xmlSecDigestVerifyMethod ()

int         (*xmlSecDigestVerifyMethod)     (xmlSecDigestTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);

Verifies digest with new chunk of data. The actual verification status is set in status member of xmlSecDigestTransform structure.

transform : the pointer to digests transform xmlSecDigestTransform.
buffer : the input data.
size : the input data size.
Returns :1 on success or a negative value otherwise.


xmlSecDigestSignNode ()

int         xmlSecDigestSignNode            (xmlSecTransformPtr transform,
                                             xmlNodePtr valueNode,
                                             int removeOldContent);

Finalizes the digest result, signs it (if necessary), base64 encodes and puts in the given node.

transform : the pointer to a digest transform.
valueNode : the pointer to <dsig:DigestValue> node.
removeOldContent : the flag that indicates whether the previous node content will be removed or not.
Returns :0 on success or a negative value if an error occurs.


xmlSecDigestVerifyNode ()

int         xmlSecDigestVerifyNode          (xmlSecTransformPtr transform,
                                             const xmlNodePtr valueNode);

Reads the node content, base64 decodes it, finalizes the digest result and verifies that it does match with the content of the node.

transform : the pointer to a digest transform.
valueNode : the pointer to a <dsig:DigestValue> node.
Returns :0 on success or a negative value if an error occurs.


xmlSecDigestSetPushMode ()

void        xmlSecDigestSetPushMode         (xmlSecTransformPtr transform,
                                             int enabled);

Sets the push more flag. If push mode is enabled then the digest is finalized and send to next transform when 1) read from previous transform returned 0 2) flush called

transform : the pointer to a digests transform.
enabled : the new "push mode" flag.


xmlSecDigestUpdate ()

int         xmlSecDigestUpdate              (xmlSecTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);

Updates data with the new chunk of data (wrapper for xmlSecDigestTransformId::digestUpdate method).

transform : the pointer to a digests transform.
buffer : the input data.
size : the input data size.
Returns :0 on success or a negative value otherwise.


xmlSecDigestSign ()

int         xmlSecDigestSign                (xmlSecTransformPtr transform,
                                             unsigned char **buffer,
                                             size_t *size);

Finalizes digest and writes the result into the allocated buffer (wrapper for xmlSecDigestTransformId::digestSign function). Caller is responsble for freeing allocated buffer with xmlFree() function.

transform : the pointer to a digests transform.
buffer : the pointer to the pointer to the output buffer.
size : the pointer to the output buffer size.
Returns :0 on success or a negative value otherwise.


xmlSecDigestVerify ()

int         xmlSecDigestVerify              (xmlSecTransformPtr transform,
                                             unsigned char *buffer,
                                             size_t size);

Checks the computed digest and the data in the input buffer (wrapper for xmlSecDigestTransformId::digestVerify function).

transform : the pointer to a digests transform.
buffer : the input buffer.
size : the input buffer size.
Returns :0 on success or a negative value otherwise.


xmlSecDigestTransformRead ()

int         xmlSecDigestTransformRead       (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

Reads all data from previos transform and digests it. If the push mode enabled then the result is finalized and returned to the caller, otherwise we return 0

transform : the pointer to a digest transform.
buf : the output buffer.
size : the output buffer size.
Returns :the number of bytes in the buffer or negative value if an error occurs.


xmlSecDigestTransformWrite ()

int         xmlSecDigestTransformWrite      (xmlSecBinTransformPtr transform,
                                             unsigned char *buf,
                                             size_t size);

Adds new chunk of data to the digest.

transform : the poiter to a digests transform.
buf : the input data buffer.
size : the input data size.
Returns :0 if success or a negative value otherwise.


xmlSecDigestTransformFlush ()

int         xmlSecDigestTransformFlush      (xmlSecBinTransformPtr transform);

If the push mode enabled then the function finalizes the result, writes it to the next transform and calls flush for it. Otherwise, it just calls flush for next transform

transform : the pointer to a digests transform.
Returns :0 if success or negative value otherwise.