# XML Digital Signatures

**API Group:** `xmlsec_core_xmldsig`

XML Digital Signature (XMLDSig) implementation.

XML Digital Signature functions. [XML Digital Signature](http://www.w3.org/TR/xmldsig-core/) implementation.

## Macros

### `XMLSEC_DSIG_FLAGS_IGNORE_MANIFESTS`

*Defined as:* `0x00000001`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L64)

If set, dsig:Manifests nodes will not be processed.

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

---

### `XMLSEC_DSIG_FLAGS_STORE_SIGNEDINFO_REFERENCES`

*Defined as:* `0x00000002`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L71)

If set, pre-digest buffer for SignedInfo References is stored in xmlSecDSigCtx.

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_STORE_MANIFEST_REFERENCES`

*Defined as:* `0x00000004`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L78)

If set, pre-digest buffer for Manifest References is stored in xmlSecDSigCtx.

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`

*Defined as:* `0x00000008`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L85)

If set, pre-signature buffer for SignedInfo is stored in xmlSecDSigCtx.

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

---

### `XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK`

*Defined as:* `0x00000010`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L93)

If set, resolve URI ID references without XPointers (Visa3D hack).

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.

---

### `XMLSEC_DSIG_FLAGS_USE_ASN1_SIGNATURE_VALUES`

*Defined as:* `0x00000020`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L101)

If set, use ASN1 encoded ECDSA signature values.

If this flag is set then ASN1 encoded ECDSA signature values will be used (see [https://github.com/lsh123/xmlsec/issues/995](https://github.com/lsh123/xmlsec/issues/995)).

---

### `xmlSecDSigReferenceCtxListId`

*Defined as:* `xmlSecDSigReferenceCtxListGetKlass()`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L226)

The references list klass.

---

## Enumerations

### `xmlSecDSigStatus`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L35)

XML Digital signature processing status.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecDSigStatusUnknown` | `= 0` |  |
| `xmlSecDSigStatusSucceeded` | `` |  |
| `xmlSecDSigStatusInvalid` | `` |  |

---

### `xmlSecDSigFailureReason`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L46)

XML Digital signature processing failure reason.

XML Digital signature processing failure reason. The application should use `xmlSecDSigStatus` to find out the operation status first.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecDSigFailureReasonUnknown` | `= 0` |  |
| `xmlSecDSigFailureReasonReference` | `` |  |
| `xmlSecDSigFailureReasonSignature` | `` |  |
| `xmlSecDSigFailureReasonKeyNotFound` | `` |  |

---

### `xmlSecDSigReferenceOrigin`

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L175)

The possible dsig:Reference node locations (SignedInfo or Manifest).

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

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecDSigReferenceOriginSignedInfo` | `` |  |
| `xmlSecDSigReferenceOriginManifest` | `` |  |

---

## Functions

### `xmlSecDSigCtxCreate`

```c
xmlSecDSigCtxPtr xmlSecDSigCtxCreate(xmlSecKeysMngrPtr keysMngr);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L141)

Creates a dsig:Signature processing context.

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

**Parameters:**

- `keysMngr` — the pointer to keys manager.


**Returns:** pointer to newly allocated context object or NULL if an error occurs.

---

### `xmlSecDSigCtxDestroy`

```c
void xmlSecDSigCtxDestroy(xmlSecDSigCtxPtr dsigCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L142)

Destroys a dsig:Signature processing context.

Destroy context object created with `xmlSecDSigCtxCreate` function. 

**Parameters:**

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

---

### `xmlSecDSigCtxInitialize`

```c
int xmlSecDSigCtxInitialize(xmlSecDSigCtxPtr dsigCtx, xmlSecKeysMngrPtr keysMngr);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L143)

Initializes a dsig:Signature processing context.

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

**Parameters:**

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

---

### `xmlSecDSigCtxFinalize`

```c
void xmlSecDSigCtxFinalize(xmlSecDSigCtxPtr dsigCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L145)

Cleans up a dsig:Signature processing context.

Cleans up `dsigCtx` object initialized with `xmlSecDSigCtxInitialize` function. 

**Parameters:**

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

---

### `xmlSecDSigCtxSign`

```c
int xmlSecDSigCtxSign(xmlSecDSigCtxPtr dsigCtx, xmlNodePtr tmpl);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L146)

Signs the data as described in `tmpl` node.

**Parameters:**

- `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`

```c
int xmlSecDSigCtxVerify(xmlSecDSigCtxPtr dsigCtx, xmlNodePtr node);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L148)

Validates the dsig:Signature in the node.

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

**Parameters:**

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

---

### `xmlSecDSigCtxEnableReferenceTransform`

```c
int xmlSecDSigCtxEnableReferenceTransform(xmlSecDSigCtxPtr dsigCtx, xmlSecTransformId transformId);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L150)

Enables a transform for dsig:Reference processing.

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

**Parameters:**

- `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`

```c
int xmlSecDSigCtxEnableSignatureTransform(xmlSecDSigCtxPtr dsigCtx, xmlSecTransformId transformId);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L152)

Enables a transform for dsig:SignedInfo processing.

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

**Parameters:**

- `dsigCtx` — the pointer to <dsig:Signature/> processing context.
- `transformId` — the transform klass.


**Returns:** 0 on success or a negative value if an error occurs.

---

### `xmlSecDSigCtxGetPreSignBuffer`

```c
xmlSecBufferPtr xmlSecDSigCtxGetPreSignBuffer(xmlSecDSigCtxPtr dsigCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L154)

Gets the pre-signature buffer for the SignedInfo element.

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.

**Parameters:**

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


**Returns:** 0 on success or a negative value if an error occurs.

---

### `xmlSecDSigCtxDebugDump`

```c
void xmlSecDSigCtxDebugDump(xmlSecDSigCtxPtr dsigCtx, FILE *output);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L155)

Prints debug information about the context.

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

**Parameters:**

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

---

### `xmlSecDSigCtxDebugXmlDump`

```c
void xmlSecDSigCtxDebugXmlDump(xmlSecDSigCtxPtr dsigCtx, FILE *output);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L157)

Prints debug information about the context in XML format.

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

**Parameters:**

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

---

### `xmlSecDSigCtxGetStatusString`

```c
const char * xmlSecDSigCtxGetStatusString(xmlSecDSigStatus status);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L161)

Gets status as a string.

**Parameters:**

- `status` — the status.


**Returns:** status as a string.

---

### `xmlSecDSigCtxGetFailureReasonString`

```c
const char * xmlSecDSigCtxGetFailureReasonString(xmlSecDSigFailureReason failureReason);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L162)

Gets failure reason as a string.

**Parameters:**

- `failureReason` — the failure reason.


**Returns:** failure reason as a string.

---

### `xmlSecDSigReferenceCtxCreate`

```c
xmlSecDSigReferenceCtxPtr xmlSecDSigReferenceCtxCreate(xmlSecDSigCtxPtr dsigCtx, xmlSecDSigReferenceOrigin origin);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L202)

Creates a dsig:Reference processing context.

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

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxDestroy`

```c
void xmlSecDSigReferenceCtxDestroy(xmlSecDSigReferenceCtxPtr dsigRefCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L204)

Destroys a dsig:Reference processing context.

Destroy context object created with `xmlSecDSigReferenceCtxCreate` function. 

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxInitialize`

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

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L205)

Initializes a dsig:Reference processing context.

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

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxFinalize`

```c
void xmlSecDSigReferenceCtxFinalize(xmlSecDSigReferenceCtxPtr dsigRefCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L208)

Cleans up a dsig:Reference processing context.

Cleans up context object created with `xmlSecDSigReferenceCtxInitialize` function. 

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxProcessNode`

```c
int xmlSecDSigReferenceCtxProcessNode(xmlSecDSigReferenceCtxPtr dsigRefCtx, xmlNodePtr node);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L209)

Processes a dsig:Reference element.

The Reference Element ([http://www.w3.org/TR/xmldsig-core/#sec-Reference](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.

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxGetPreDigestBuffer`

```c
xmlSecBufferPtr xmlSecDSigReferenceCtxGetPreDigestBuffer(xmlSecDSigReferenceCtxPtr dsigRefCtx);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L211)

Gets the pre-digest buffer for the Reference element.

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

**Parameters:**

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


**Returns:** pointer to the buffer or NULL if an error occurs.

---

### `xmlSecDSigReferenceCtxDebugDump`

```c
void xmlSecDSigReferenceCtxDebugDump(xmlSecDSigReferenceCtxPtr dsigRefCtx, FILE *output);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L213)

Prints debug information about the reference context.

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

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxDebugXmlDump`

```c
void xmlSecDSigReferenceCtxDebugXmlDump(xmlSecDSigReferenceCtxPtr dsigRefCtx, FILE *output);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L215)

Prints debug information about the reference context in XML format.

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

**Parameters:**

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

---

### `xmlSecDSigReferenceCtxListGetKlass`

```c
xmlSecPtrListId xmlSecDSigReferenceCtxListGetKlass(void);
```

*Source:* [include/xmlsec/xmldsig.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/xmldsig.h#L228)

Gets the dsig:Reference processing contexts list klass.

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

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

---
