# XML Encryption

**API Group:** `xmlsec_core_xmlenc`

XML Encryption (XMLEnc) implementation.

XML Encryption support. [XML Encryption](http://www.w3.org/TR/xmlenc-core) implementation.

## Macros

### `XMLSEC_ENC_RETURN_REPLACED_NODE`

*Defined as:* `0x00000001`

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L53)

If set, the replaced node will be returned in replacedNodeList.

If this flag is set, then the replaced node will be returned in the replacedNodeList

---

## Enumerations

### `xmlEncCtxMode`

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L33)

The xmlSecEncCtx mode.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlEncCtxModeEncryptedData` | `= 0` |  |
| `xmlEncCtxModeEncryptedKey` | `` |  |

---

### `xmlSecEncFailureReason`

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L44)

XML Encryption processing failure reason.

XML Encryption processing failure reason. The application should use the returned value from the encrypt/decrypt functions first.

| Value | Initializer | Description |
|-------|-------------|-------------|
| `xmlSecEncFailureReasonUnknown` | `= 0` |  |
| `xmlSecEncFailureReasonKeyNotFound` | `` |  |

---

## Functions

### `xmlSecEncCtxCreate`

```c
xmlSecEncCtxPtr xmlSecEncCtxCreate(xmlSecKeysMngrPtr keysMngr);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L96)

Creates an enc:EncryptedData processing context.

Creates <enc:EncryptedData/> element processing context. The caller is responsible for destroying returned object by calling `xmlSecEncCtxDestroy` function.

**Parameters:**

- `keysMngr` — the pointer to keys manager.


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

---

### `xmlSecEncCtxDestroy`

```c
void xmlSecEncCtxDestroy(xmlSecEncCtxPtr encCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L97)

Destroys an enc:EncryptedData processing context.

Destroy context object created with `xmlSecEncCtxCreate` function. 

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.

---

### `xmlSecEncCtxInitialize`

```c
int xmlSecEncCtxInitialize(xmlSecEncCtxPtr encCtx, xmlSecKeysMngrPtr keysMngr);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L98)

Initializes an enc:EncryptedData processing context.

Initializes <enc:EncryptedData/> element processing context. The caller is responsible for cleaning up returned object by calling `xmlSecEncCtxFinalize` function.

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `keysMngr` — the pointer to keys manager.


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

---

### `xmlSecEncCtxFinalize`

```c
void xmlSecEncCtxFinalize(xmlSecEncCtxPtr encCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L100)

Cleans up `encCtx` object.

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.

---

### `xmlSecEncCtxCopyUserPref`

```c
int xmlSecEncCtxCopyUserPref(xmlSecEncCtxPtr dst, xmlSecEncCtxPtr src);
```

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

Copies user preferences from src to dst context.

Copies user preference from `src` context to `dst`. 

**Parameters:**

- `dst` — the pointer to destination context.
- `src` — the pointer to source context.


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

---

### `xmlSecEncCtxReset`

```c
void xmlSecEncCtxReset(xmlSecEncCtxPtr encCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L103)

Resets the context, keeping user settings.

Resets `encCtx` object, user settings are not touched. 

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.

---

### `xmlSecEncCtxBinaryEncrypt`

```c
int xmlSecEncCtxBinaryEncrypt(xmlSecEncCtxPtr encCtx, xmlNodePtr tmpl, const xmlSecByte *data, xmlSecSize dataSize);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L104)

Encrypts `data` according to template `tmpl`.

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `tmpl` — the pointer to <enc:EncryptedData/> template node.
- `data` — the pointer for binary buffer.
- `dataSize` — the `data` buffer size.


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

---

### `xmlSecEncCtxXmlEncrypt`

```c
int xmlSecEncCtxXmlEncrypt(xmlSecEncCtxPtr encCtx, xmlNodePtr tmpl, xmlNodePtr node);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L108)

Encrypts a node according to the template.

Encrypts `node` according to template `tmpl`. If requested, `node` is replaced with result <enc:EncryptedData/> node.

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `tmpl` — the pointer to <enc:EncryptedData/> template node.
- `node` — the pointer to node for encryption.


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

---

### `xmlSecEncCtxUriEncrypt`

```c
int xmlSecEncCtxUriEncrypt(xmlSecEncCtxPtr encCtx, xmlNodePtr tmpl, const xmlChar *uri);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L111)

Encrypts data from a URI according to the template.

Encrypts data from `uri` according to template `tmpl`. 

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `tmpl` — the pointer to <enc:EncryptedData/> template node.
- `uri` — the URI.


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

---

### `xmlSecEncCtxDecrypt`

```c
int xmlSecEncCtxDecrypt(xmlSecEncCtxPtr encCtx, xmlNodePtr node);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L114)

Decrypts a node, replacing it if necessary.

Decrypts `node` and if necessary replaces `node` with decrypted data. 

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `node` — the pointer to <enc:EncryptedData/> node.


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

---

### `xmlSecEncCtxDecryptToBuffer`

```c
xmlSecBufferPtr xmlSecEncCtxDecryptToBuffer(xmlSecEncCtxPtr encCtx, xmlNodePtr node);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L116)

Decrypts `node` data to the result.

**Parameters:**

- `encCtx` — the pointer to encryption processing context.
- `node` — the pointer to <enc:EncryptedData/> node.


**Returns:** a buffer with key on success or NULL if an error occurs.

---

### `xmlSecEncCtxDebugDump`

```c
void xmlSecEncCtxDebugDump(xmlSecEncCtxPtr encCtx, FILE *output);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L118)

Prints debug information about the context.

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

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `output` — the pointer to output FILE.

---

### `xmlSecEncCtxDebugXmlDump`

```c
void xmlSecEncCtxDebugXmlDump(xmlSecEncCtxPtr encCtx, FILE *output);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L120)

Prints debug information about the context in XML format.

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

**Parameters:**

- `encCtx` — the pointer to <enc:EncryptedData/> processing context.
- `output` — the pointer to output FILE.

---

### `xmlSecEncCtxDerivedKeyGenerate`

```c
xmlSecKeyPtr xmlSecEncCtxDerivedKeyGenerate(xmlSecEncCtxPtr encCtx, xmlSecKeyDataId keyId, xmlNodePtr node, xmlSecKeyInfoCtxPtr keyInfoCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L123)

Generates (derives) a key from the DerivedKey node.

Generates (derives) key from `node` ([https://www.w3.org/TR/xmlenc-core1/#sec-DerivedKey](https://www.w3.org/TR/xmlenc-core1/#sec-DerivedKey)): 

```c
<elementname="DerivedKey"type="xenc11:DerivedKeyType"/>
<complexTypename="DerivedKeyType">
<sequence>
<elementref="xenc11:KeyDerivationMethod"minOccurs="0"/>
<elementref="xenc:ReferenceList"minOccurs="0"/>
<elementname="DerivedKeyName"type="string"minOccurs="0"/>
<elementname="MasterKeyName"type="string"minOccurs="0"/>
</sequence>
<attributename="Recipient"type="string"use="optional"/>
<attributename=&quot;Id&quot;type="ID"use="optional"/>
<attributename="Type"type="anyURI"use="optional"/>
</complexType>

<elementname="KeyDerivationMethod"type="xenc:KeyDerivationMethodType"/>
<complexTypename="KeyDerivationMethodType">
<sequence>
<anynamespace="##any"minOccurs="0"maxOccurs="unbounded"/>
</sequence>
<attributename="Algorithm"type="anyURI"use="required"/>
</complexType>
```

**Parameters:**

- `encCtx` — the pointer to encryption processing context.
- `keyId` — the expected key id, the actual derived key might have a different id.
- `node` — the pointer to <enc11:DerivedKey/> node.
- `keyInfoCtx` — the pointer to the "parent" key info context.


**Returns:** the derived key on success or NULL if an error occurs.

---

### `xmlSecEncCtxAgreementMethodGenerate`

```c
xmlSecKeyPtr xmlSecEncCtxAgreementMethodGenerate(xmlSecEncCtxPtr encCtx, xmlSecKeyDataId keyId, xmlNodePtr node, xmlSecKeyInfoCtxPtr keyInfoCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L129)

Generates a key from the AgreementMethod node.

Generates (derives) key from `node` ([https://www.w3.org/TR/xmlenc-core1/#sec-AgreementMethod](https://www.w3.org/TR/xmlenc-core1/#sec-AgreementMethod)):

```c
<elementname="AgreementMethod"type="xenc:AgreementMethodType"/>
<complexTypename="AgreementMethodType"mixed="true">
<sequence>
<elementname="KA-Nonce"minOccurs="0"type="base64Binary"/>
<!--<elementref="ds:DigestMethod"minOccurs="0"/>-->
<anynamespace="##other"minOccurs="0"maxOccurs="unbounded"/>
<elementname="OriginatorKeyInfo"minOccurs="0"type="ds:KeyInfoType"/>
<elementname="RecipientKeyInfo"minOccurs="0"type="ds:KeyInfoType"/>
</sequence>
<attributename="Algorithm"type="anyURI"use="required"/>
</complexType>
```

**Parameters:**

- `encCtx` — the pointer to encryption processing context.
- `keyId` — the expected key id, the actual derived key might have a different id.
- `node` — the pointer to <enc:AgreementMethod/> node.
- `keyInfoCtx` — the pointer to the "parent" key info context.


**Returns:** the generated key on success or NULL if an error occurs.

---

### `xmlSecEncCtxAgreementMethodXmlWrite`

```c
int xmlSecEncCtxAgreementMethodXmlWrite(xmlSecEncCtxPtr encCtx, xmlNodePtr node, xmlSecKeyInfoCtxPtr keyInfoCtx);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L134)

Writes the AgreementMethod XML content into the node.

Writes the AgreementMethod XML content for the given `encCtx` into `node`. 

**Parameters:**

- `encCtx` — the pointer to encryption context.
- `node` — the pointer to the AgreementMethod XML node.
- `keyInfoCtx` — the pointer to key info context.


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

---

### `xmlSecEncCtxGetFailureReasonString`

```c
const char * xmlSecEncCtxGetFailureReasonString(xmlSecEncFailureReason failureReason);
```

*Source:* [include/xmlsec/xmlenc.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/xmlenc.h#L138)

Gets failure reason as a string.

**Parameters:**

- `failureReason` — the failure reason.


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

---
