# MsCrypto Application Helpers

**API Group:** `xmlsec_mscrypto_app`

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

Application support functions for MSCrypto.

Common functions for the xmlsec1 command-line utility for MSCrypto.

## Functions

### `xmlSecMSCryptoAppInit`

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

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

Initializes the MSCrypto 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 name of a certificate store other than the default Microsoft certificate store.


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

---

### `xmlSecMSCryptoAppShutdown`

```c
int xmlSecMSCryptoAppShutdown(void);
```

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

Shuts down the MSCrypto 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.

---

### `xmlSecMSCryptoAppGetCertStoreName`

```c
const char * xmlSecMSCryptoAppGetCertStoreName(void);
```

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

Gets the MSCrypto certs store name.

Gets the MS Crypto certs store name set by `xmlSecMSCryptoAppInit` function.

**Returns:** the MS Crypto certs name used by xmlsec-mscrypto.

---

### `xmlSecMSCryptoAppDefaultKeysMngrInit`

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

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

Initializes the default key manager for MSCrypto.

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

**Parameters:**

- `mngr` — the pointer to keys manager.


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrAdoptKey`

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

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

Adds `key` to the keys manager.

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

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrVerifyKey`

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

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

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.

---

### `xmlSecMSCryptoAppDefaultKeysMngrLoad`

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

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

Loads the XML keys file into the keys manager.

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

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrSave`

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

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

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.

---

### `xmlSecMSCryptoAppDefaultKeysMngrPrivateKeyLoad`

```c
int xmlSecMSCryptoAppDefaultKeysMngrPrivateKeyLoad(xmlSecKeysMngrPtr mngr, void *hKey);
```

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

Adds private key `hKey` to the keys manager.

Adds private key `hKey` to the keys manager `mngr`.

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrPublicKeyLoad`

```c
int xmlSecMSCryptoAppDefaultKeysMngrPublicKeyLoad(xmlSecKeysMngrPtr mngr, void *hKey);
```

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

Adds public key `hKey` to the keys manager.

Adds public key `hKey` to the keys manager `mngr`.

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrSymKeyLoad`

```c
int xmlSecMSCryptoAppDefaultKeysMngrSymKeyLoad(xmlSecKeysMngrPtr mngr, void *hKey);
```

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

Adds symmetric key `hKey` to the keys manager.

Adds symmetric key `hKey` to the keys manager `mngr`.

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrAdoptKeyStore`

```c
int xmlSecMSCryptoAppDefaultKeysMngrAdoptKeyStore(xmlSecKeysMngrPtr mngr, void *keyStore);
```

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

Adds `keyStore` to the keys manager.

Adds `keyStore` to the list of key stores in the keys manager `mngr`.

**Parameters:**

- `mngr` — the keys manager.
- `keyStore` — the pointer to keys store.


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrAdoptTrustedStore`

```c
int xmlSecMSCryptoAppDefaultKeysMngrAdoptTrustedStore(xmlSecKeysMngrPtr mngr, void *trustedStore);
```

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

Adds `trustedStore` to the trusted cert stores.

Adds `trustedStore` to the list of trusted cert stores in the keys manager `mngr`.

**Parameters:**

- `mngr` — the keys manager.
- `trustedStore` — the pointer to certs store.


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

---

### `xmlSecMSCryptoAppDefaultKeysMngrAdoptUntrustedStore`

```c
int xmlSecMSCryptoAppDefaultKeysMngrAdoptUntrustedStore(xmlSecKeysMngrPtr mngr, void *untrustedStore);
```

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

Adds `untrustedStore` to the untrusted cert stores.

Adds `untrustedStore` to the list of un-trusted cert stores in the keys manager `mngr`.

**Parameters:**

- `mngr` — the keys manager.
- `untrustedStore` — the pointer to certs store.


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

---

### `xmlSecMSCryptoAppKeysMngrCertLoad`

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

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

Reads a cert from a file and adds to the key store.

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.

---

### `xmlSecMSCryptoAppKeysMngrCertLoadMemory`

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

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

Reads cert from buffer and adds to the key store.

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

**Parameters:**

- `mngr` — the keys manager.
- `data` — the binary certificate.
- `dataSize` — size of binary certificate (data)
- `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.

---

### `xmlSecMSCryptoAppKeysMngrCrlLoad`

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

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

Reads CRLs from a file and adds to the store.

Reads crl 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.

---

### `xmlSecMSCryptoAppKeysMngrCrlLoadMemory`

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

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

Reads CRLs from memory and adds to the store.

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

**Parameters:**

- `mngr` — the keys manager.
- `data` — the binary CRL.
- `dataSize` — size of binary CRL (data)
- `format` — the CRL format.


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

---

### `xmlSecMSCryptoAppKeysMngrCrlLoadAndVerify`

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

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

Loads and verifies a CRL from a file.

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.

---

### `xmlSecMSCryptoAppKeyLoadEx`

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

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

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.

---

### `xmlSecMSCryptoAppKeyLoadMemory`

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

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

Reads a key from the binary `data`.

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppPkcs12Load`

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

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

Reads key and certificates from PKCS12 file.

Reads a key and all associated certificates from the PKCS12 file.

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

---

### `xmlSecMSCryptoAppPkcs12LoadMemory`

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

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

Reads key and certificates from PKCS12 binary.

Reads a key and all associated certificates from the PKCS12 binary.

**Parameters:**

- `data` — the binary PKCS12 key in data.
- `dataSize` — size of binary pkcs12 data
- `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.

---

### `xmlSecMSCryptoAppKeyCertLoad`

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

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

Reads the certificate from a file and adds to key.

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.

---

### `xmlSecMSCryptoAppKeyCertLoadMemory`

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

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

Reads the certificate from memory and adds to key.

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

**Parameters:**

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


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

---

### `xmlSecMSCryptoAppGetDefaultPwdCallback`

```c
void * xmlSecMSCryptoAppGetDefaultPwdCallback(void);
```

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

Gets default password callback.

**Returns:** default password callback.

---