# GCrypt Application Helpers

**API Group:** `xmlsec_gcrypt_app`

High-level application helpers for the GCrypt back-end.

Application support functions for GCrypt.

## Functions

### `xmlSecGCryptAppInit`

```c
int xmlSecGCryptAppInit(const char *config);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L26)

Initializes the GCrypt crypto engine.

General crypto engine initialization. This function is used by the XMLSec command-line utility and is called before the `xmlSecInit` function.

**Parameters:**

- `config` — the path to GCrypt configuration (unused).


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppShutdown`

```c
int xmlSecGCryptAppShutdown(void);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L27)

Shuts down the GCrypt crypto engine.

General crypto engine shutdown. This function is used by the XMLSec command-line utility and is called after the `xmlSecShutdown` function.

**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppDefaultKeysMngrInit`

```c
int xmlSecGCryptAppDefaultKeysMngrInit(xmlSecKeysMngrPtr mngr);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L34)

Initializes the default key manager for GCrypt.

Initializes `mngr` with simple keys store `xmlSecSimpleKeysStoreId` and a default GCrypt crypto key data stores.

**Parameters:**

- `mngr` — the pointer to keys manager.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppDefaultKeysMngrAdoptKey`

```c
int xmlSecGCryptAppDefaultKeysMngrAdoptKey(xmlSecKeysMngrPtr mngr, xmlSecKeyPtr key);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L35)

Adds `key` to the keys manager.

Adds `key` to the keys manager `mngr` created with `xmlSecGCryptAppDefaultKeysMngrInit` function.

**Parameters:**

- `mngr` — the pointer to keys manager.
- `key` — the pointer to key.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppDefaultKeysMngrVerifyKey`

```c
int xmlSecGCryptAppDefaultKeysMngrVerifyKey(xmlSecKeysMngrPtr mngr, xmlSecKeyPtr key, xmlSecKeyInfoCtxPtr keyInfoCtx);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L37)

Verifies `key` using the keys manager.

Verifies `key` with the keys manager `mngr` created with `xmlSecCryptoAppDefaultKeysMngrInit` function:

- Checks that key certificate is present
- Checks that key certificate is valid

Adds `key` to the keys manager `mngr` created with `xmlSecCryptoAppDefaultKeysMngrInit` function.

**Parameters:**

- `mngr` — the pointer to keys manager.
- `key` — the pointer to key.
- `keyInfoCtx` — the key info context for verification.


**Returns:** 1 if key is verified, 0 otherwise, or a negative value if an error occurs.

---

### `xmlSecGCryptAppDefaultKeysMngrLoad`

```c
int xmlSecGCryptAppDefaultKeysMngrLoad(xmlSecKeysMngrPtr mngr, const char *uri);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L40)

Loads the XML keys file into the keys manager.

Loads XML keys file from `uri` to the keys manager `mngr` created with `xmlSecGCryptAppDefaultKeysMngrInit` function.

**Parameters:**

- `mngr` — the pointer to keys manager.
- `uri` — the uri.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppDefaultKeysMngrSave`

```c
int xmlSecGCryptAppDefaultKeysMngrSave(xmlSecKeysMngrPtr mngr, const char *filename, xmlSecKeyDataType type);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L42)

Saves keys from `mngr` to XML keys file.

**Parameters:**

- `mngr` — the pointer to keys manager.
- `filename` — the destination filename.
- `type` — the type of keys to save (public/private/symmetric).


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeysMngrCertLoad`

```c
int xmlSecGCryptAppKeysMngrCertLoad(xmlSecKeysMngrPtr mngr, const char *filename, xmlSecKeyDataFormat format, xmlSecKeyDataType type);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L46)

GCrypt does not support X509 certificates.

Reads cert from `filename` and adds to the list of trusted or known untrusted certs in `store`.

**Parameters:**

- `mngr` — the keys manager.
- `filename` — the certificate file.
- `format` — the certificate file format.
- `type` — the flag that indicates is the certificate in `filename` trusted or not.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeysMngrCrlLoad`

```c
int xmlSecGCryptAppKeysMngrCrlLoad(xmlSecKeysMngrPtr mngr, const char *filename, xmlSecKeyDataFormat format);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L50)

GCrypt does not support X509 certificates.

Reads crls from `filename` and adds to the list of crls in `store`.

**Parameters:**

- `mngr` — the keys manager.
- `filename` — the CRL file.
- `format` — the CRL file format.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeysMngrCrlLoadAndVerify`

```c
int xmlSecGCryptAppKeysMngrCrlLoadAndVerify(xmlSecKeysMngrPtr mngr, const char *filename, xmlSecKeyDataFormat format, xmlSecKeyInfoCtxPtr keyInfoCtx);
```

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

GCrypt does not support X509 certificates.

Atomically loads and verifies a CRL from `filename`.

**Parameters:**

- `mngr` — the keys manager.
- `filename` — the CRL filename.
- `format` — the CRL format (PEM or DER).
- `keyInfoCtx` — the key info context for verification parameters.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeysMngrCertLoadMemory`

```c
int xmlSecGCryptAppKeysMngrCertLoadMemory(xmlSecKeysMngrPtr mngr, const xmlSecByte *data, xmlSecSize dataSize, xmlSecKeyDataFormat format, xmlSecKeyDataType type);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L57)

GCrypt does not support X509 certificates.

Reads cert from binary buffer `data` and adds to the list of trusted or known untrusted certs in `store`.

**Parameters:**

- `mngr` — the keys manager.
- `data` — the certificate binary data.
- `dataSize` — the certificate binary data size.
- `format` — the certificate file format.
- `type` — the flag that indicates is the certificate trusted or not.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeyLoadEx`

```c
xmlSecKeyPtr xmlSecGCryptAppKeyLoadEx(const char *filename, xmlSecKeyDataType type, xmlSecKeyDataFormat format, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L70)

Reads a key from a file.

**Parameters:**

- `filename` — the key filename.
- `type` — the expected key type.
- `format` — the key file format.
- `pwd` — the key file password.
- `pwdCallback` — the key password callback.
- `pwdCallbackCtx` — the user context for password callback.


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

---

### `xmlSecGCryptAppKeyLoadMemory`

```c
xmlSecKeyPtr xmlSecGCryptAppKeyLoadMemory(const xmlSecByte *data, xmlSecSize dataSize, xmlSecKeyDataFormat format, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L76)

Reads a key from the memory buffer.

**Parameters:**

- `data` — the binary key data.
- `dataSize` — the size of binary key.
- `format` — the key file format.
- `pwd` — the key file password.
- `pwdCallback` — the key password callback.
- `pwdCallbackCtx` — the user context for password callback.


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

---

### `xmlSecGCryptAppPkcs12Load`

```c
xmlSecKeyPtr xmlSecGCryptAppPkcs12Load(const char *filename, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L83)

GCrypt does not support X509 certificates.

Reads a key and all associated certificates from the PKCS12 file. For uniformity, call `xmlSecGCryptAppKeyLoadEx` instead of this function. Pass in format=xmlSecKeyDataFormatPkcs12.

**Parameters:**

- `filename` — the PKCS12 key filename.
- `pwd` — the PKCS12 file password.
- `pwdCallback` — the password callback.
- `pwdCallbackCtx` — the user context for password callback.


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

---

### `xmlSecGCryptAppPkcs12LoadMemory`

```c
xmlSecKeyPtr xmlSecGCryptAppPkcs12LoadMemory(const xmlSecByte *data, xmlSecSize dataSize, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L87)

GCrypt does not support X509 certificates.

Reads a key and all associated certificates from the PKCS12 data in the memory buffer. For uniformity, call xmlSecGCryptAppKeyLoadMemory instead of this function. Pass in format=xmlSecKeyDataFormatPkcs12.

**Parameters:**

- `data` — the PKCS12 binary data.
- `dataSize` — the PKCS12 binary data size.
- `pwd` — the PKCS12 file password.
- `pwdCallback` — the password callback.
- `pwdCallbackCtx` — the user context for password callback.


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

---

### `xmlSecGCryptAppKeyCertLoad`

```c
int xmlSecGCryptAppKeyCertLoad(xmlSecKeyPtr key, const char *filename, xmlSecKeyDataFormat format);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L92)

GCrypt does not support X509 certificates.

Reads the certificate from `filename` and adds it to key.

**Parameters:**

- `key` — the pointer to key.
- `filename` — the certificate filename.
- `format` — the certificate file format.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppKeyCertLoadMemory`

```c
int xmlSecGCryptAppKeyCertLoadMemory(xmlSecKeyPtr key, const xmlSecByte *data, xmlSecSize dataSize, xmlSecKeyDataFormat format);
```

*Source:* [include/xmlsec/gcrypt/app.h](https://github.com/lsh123/xmlsec/blob/1.3.11/include/xmlsec/gcrypt/app.h#L95)

GCrypt does not support X509 certificates.

Reads the certificate from memory buffer and adds it to key.

**Parameters:**

- `key` — the pointer to key.
- `data` — the certificate binary data.
- `dataSize` — the certificate binary data size.
- `format` — the certificate file format.


**Returns:** 0 on success or a negative value otherwise.

---

### `xmlSecGCryptAppGetDefaultPwdCallback`

```c
void * xmlSecGCryptAppGetDefaultPwdCallback(void);
```

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

Gets default password callback.

**Returns:** default password callback.

---