# OpenSSL Application Helpers

**API Group:** `xmlsec_openssl_app`

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

Application support functions for OpenSSL.

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

## Functions

### `xmlSecOpenSSLAppInit`

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

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

Initializes the OpenSSL 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 certs.


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

---

### `xmlSecOpenSSLAppShutdown`

```c
int xmlSecOpenSSLAppShutdown(void);
```

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

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

---

### `xmlSecOpenSSLAppDefaultKeysMngrInit`

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

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

Initializes the default key manager for OpenSSL.

Initializes `mngr` with openssl keys store `xmlSecOpenSSLKeysStoreId` and a default OpenSSL crypto key data stores.

**Parameters:**

- `mngr` — the pointer to keys manager.


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

---

### `xmlSecOpenSSLAppDefaultKeysMngrAdoptKey`

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

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

Adds `key` to the keys manager.

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

**Parameters:**

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


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

---

### `xmlSecOpenSSLAppDefaultKeysMngrVerifyKey`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/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.

---

### `xmlSecOpenSSLAppDefaultKeysMngrLoad`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/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 `xmlSecOpenSSLAppDefaultKeysMngrInit` function.

**Parameters:**

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


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

---

### `xmlSecOpenSSLAppDefaultKeysMngrSave`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/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.

---

### `xmlSecOpenSSLAppKeysMngrCertLoad`

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

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

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.

---

### `xmlSecOpenSSLAppKeysMngrCertLoadMemory`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L54)

Reads cert from buffer and adds to the key store.

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.

---

### `xmlSecOpenSSLAppKeysMngrCertLoadBIO`

```c
int xmlSecOpenSSLAppKeysMngrCertLoadBIO(xmlSecKeysMngrPtr mngr, BIO *bio, xmlSecKeyDataFormat format, xmlSecKeyDataType type);
```

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

Reads cert from BIO and adds to the key store.

Reads cert from an OpenSSL BIO object and adds to the list of trusted or known untrusted certs in `store`.

**Parameters:**

- `mngr` — the keys manager.
- `bio` — the certificate BIO.
- `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.

---

### `xmlSecOpenSSLAppKeysMngrCrlLoad`

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

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

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.

---

### `xmlSecOpenSSLAppKeysMngrCrlLoadMemory`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L67)

Reads CRLs from memory and adds to the store.

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

**Parameters:**

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


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

---

### `xmlSecOpenSSLAppKeysMngrCrlLoadBIO`

```c
int xmlSecOpenSSLAppKeysMngrCrlLoadBIO(xmlSecKeysMngrPtr mngr, BIO *bio, xmlSecKeyDataFormat format);
```

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

Reads CRLs from BIO and adds to the store.

Reads crl from an OpenSSL BIO object and adds to the list of crls in `store`.

**Parameters:**

- `mngr` — the keys manager.
- `bio` — the CRL BIO.
- `format` — the CRL file format.


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

---

### `xmlSecOpenSSLAppKeysMngrCrlLoadAndVerify`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L74)

Loads and verifies a CRL from a file.

Atomically loads and verifies a CRL from `filename`. This function eliminates TOCTOU (Time-of-Check/Time-of-Use) vulnerabilities by loading the CRL once into memory, verifying it, and then adopting it to the store.

The CRL is verified by:

1. Checking the signature against the issuer's certificate in the store
2. Validating thisUpdate and nextUpdate times

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

---

### `xmlSecOpenSSLAppKeysMngrAddCertsPath`

```c
int xmlSecOpenSSLAppKeysMngrAddCertsPath(xmlSecKeysMngrPtr mngr, const char *path);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L79)

Reads certs from a path and adds to the store.

Reads cert from `path` and adds to the list of trusted certificates.

**Parameters:**

- `mngr` — the keys manager.
- `path` — the path to trusted certificates.


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

---

### `xmlSecOpenSSLAppKeysMngrAddCertsFile`

```c
int xmlSecOpenSSLAppKeysMngrAddCertsFile(xmlSecKeysMngrPtr mngr, const char *filename);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L81)

Reads certs from file and adds to the store.

Reads certs from the file and adds to the list of trusted certificates. It is possible for the file to contain multiple certs.

**Parameters:**

- `mngr` — the keys manager.
- `filename` — the file containing trusted certificates.


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

---

### `xmlSecOpenSSLAppKeyLoadEx`

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

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

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.

---

### `xmlSecOpenSSLAppKeyLoadMemory`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L98)

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.

---

### `xmlSecOpenSSLAppKeyLoadBIO`

```c
xmlSecKeyPtr xmlSecOpenSSLAppKeyLoadBIO(BIO *bio, xmlSecKeyDataFormat format, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L104)

Reads a key from an OpenSSL BIO object.

**Parameters:**

- `bio` — the key BIO.
- `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.

---

### `xmlSecOpenSSLAppPkcs12Load`

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

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

Reads key and certificates from PKCS12 file.

Reads a key and all associated certificates from the PKCS12 file. For uniformity, call xmlSecOpenSSLAppKeyLoadEx 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.

---

### `xmlSecOpenSSLAppPkcs12LoadMemory`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L115)

Reads key and certs from PKCS12 memory buffer.

Reads a key and all associated certificates from the PKCS12 data in the memory buffer. For uniformity, call `xmlSecOpenSSLAppKeyLoadEx` 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.

---

### `xmlSecOpenSSLAppPkcs12LoadBIO`

```c
xmlSecKeyPtr xmlSecOpenSSLAppPkcs12LoadBIO(BIO *bio, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L120)

Reads key and certs from PKCS12 BIO object.

Reads a key and all associated certificates from the PKCS12 data in an OpenSSL BIO object. For uniformity, call `xmlSecOpenSSLAppKeyLoadEx` instead of this function. Pass in format=xmlSecKeyDataFormatPkcs12.

**Parameters:**

- `bio` — the PKCS12 key bio.
- `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.

---

### `xmlSecOpenSSLAppKeyCertLoad`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L125)

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.

---

### `xmlSecOpenSSLAppKeyCertLoadMemory`

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

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L128)

Reads the certificate from memory and adds to key.

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.

---

### `xmlSecOpenSSLAppKeyCertLoadBIO`

```c
int xmlSecOpenSSLAppKeyCertLoadBIO(xmlSecKeyPtr key, BIO *bio, xmlSecKeyDataFormat format);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L132)

Reads the certificate from a BIO and adds to key.

Reads the certificate from a BIO object and adds it to key.

**Parameters:**

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


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

---

### `xmlSecOpenSSLAppKeyFromCertLoadBIO`

```c
xmlSecKeyPtr xmlSecOpenSSLAppKeyFromCertLoadBIO(BIO *bio, xmlSecKeyDataFormat format);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L135)

Loads public key from cert.

**Parameters:**

- `bio` — the BIO.
- `format` — the cert format.


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

---

### `xmlSecOpenSSLAppGetDefaultPwdCallback`

```c
void * xmlSecOpenSSLAppGetDefaultPwdCallback(void);
```

*Source:* [include/xmlsec/openssl/app.h](https://github.com/lsh123/xmlsec/blob/1.3.12/include/xmlsec/openssl/app.h#L139)

Gets default password callback.

**Returns:** default password callback.

---
