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

# 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.

<<< Previous Page | Home | Up | Next Page >>>
ciphers.h | io.h