# NSS Application Helpers

**API Group:** `xmlsec_nss_app`

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

Application support functions for NSS.

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

## Functions

### `xmlSecNssAppInit`

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

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

Initializes the NSS 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 NSS database files.


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

---

### `xmlSecNssAppShutdown`

```c
int xmlSecNssAppShutdown(void);
```

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

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

---

### `xmlSecNssAppDefaultKeysMngrInit`

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

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

Initializes the default key manager for NSS.

Initializes `mngr` with NSS keys store `xmlSecNssKeysStoreId` and a default NSS crypto key data stores.

**Parameters:**

- `mngr` — the pointer to keys manager.


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

---

### `xmlSecNssAppDefaultKeysMngrAdoptKey`

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

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

Adds `key` to the keys manager.

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

**Parameters:**

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


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

---

### `xmlSecNssAppDefaultKeysMngrVerifyKey`

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

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

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.

---

### `xmlSecNssAppDefaultKeysMngrLoad`

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

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

Loads the XML keys file into the keys manager.

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

**Parameters:**

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


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

---

### `xmlSecNssAppDefaultKeysMngrSave`

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

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

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.

---

### `xmlSecNssAppKeysMngrCertLoad`

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

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

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 pointer to keys manager.
- `filename` — the certificate file.
- `format` — the certificate file format (PEM or DER).
- `type` — the certificate type (trusted/untrusted).


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

---

### `xmlSecNssAppKeysMngrCertLoadMemory`

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

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

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 pointer to keys manager.
- `data` — the certificatedata.
- `dataSize` — the certificate data size.
- `format` — the certificate format (PEM or DER).
- `type` — the certificate type (trusted/untrusted).


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

---

### `xmlSecNssAppKeysMngrCertLoadSECItem`

```c
int xmlSecNssAppKeysMngrCertLoadSECItem(xmlSecKeysMngrPtr mngr, SECItem *secItem, xmlSecKeyDataFormat format, xmlSecKeyDataType type);
```

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

Reads cert from SECItem and adds to the key store.

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

**Parameters:**

- `mngr` — the pointer to keys manager.
- `secItem` — the pointer to SECItem.
- `format` — the certificate format (PEM or DER).
- `type` — the certificate type (trusted/untrusted).


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

---

### `xmlSecNssAppKeysMngrCrlLoad`

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

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

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 pointer to keys manager.
- `filename` — the CRL file.
- `format` — the CRL file format (PEM or DER).


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

---

### `xmlSecNssAppKeysMngrCrlLoadMemory`

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

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

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 pointer to keys manager.
- `data` — the CRL data.
- `dataSize` — the CRL data size.
- `format` — the CRL format (PEM or DER).


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

---

### `xmlSecNssAppKeysMngrCrlLoadAndVerify`

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

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

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.

---

### `xmlSecNssAppKeyLoadEx`

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

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

Reads a key from a file.

**Parameters:**

- `filename` — the key filename.
- `type` — the key type (public / private).
- `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.

---

### `xmlSecNssAppKeyLoadMemory`

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

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

Reads a key from the binary `data`.

**Parameters:**

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


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

---

### `xmlSecNssAppKeyLoadSECItem`

```c
xmlSecKeyPtr xmlSecNssAppKeyLoadSECItem(SECItem *secItem, xmlSecKeyDataFormat format, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

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

Reads a key from a SECItem.

**Parameters:**

- `secItem` — the pointer to sec item.
- `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.

---

### `xmlSecNssAppPkcs12Load`

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

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

Reads key and certificates from PKCS12 file.

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

---

### `xmlSecNssAppPkcs12LoadMemory`

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

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

Reads key and certs from PKCS12 binary data.

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

**Parameters:**

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


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

---

### `xmlSecNssAppPkcs12LoadSECItem`

```c
xmlSecKeyPtr xmlSecNssAppPkcs12LoadSECItem(SECItem *secItem, const char *pwd, void *pwdCallback, void *pwdCallbackCtx);
```

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

Reads key and certs from PKCS12 SECItem.

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

**Parameters:**

- `secItem` — the SECItem object.
- `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.

---

### `xmlSecNssAppKeyCertLoad`

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

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

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.

---

### `xmlSecNssAppKeyCertLoadMemory`

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

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

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 key binary data.
- `dataSize` — the key binary data size.
- `format` — the certificate format.


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

---

### `xmlSecNssAppKeyCertLoadSECItem`

```c
int xmlSecNssAppKeyCertLoadSECItem(xmlSecKeyPtr key, SECItem *secItem, xmlSecKeyDataFormat format);
```

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

Reads a certificate from SECItem and adds to key.

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

**Parameters:**

- `key` — the pointer to key.
- `secItem` — the pointer to SECItem.
- `format` — the certificate format.


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

---

### `xmlSecNssAppKeyFromCertLoadSECItem`

```c
xmlSecKeyPtr xmlSecNssAppKeyFromCertLoadSECItem(SECItem *secItem, xmlSecKeyDataFormat format);
```

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

Loads public key from cert.

**Parameters:**

- `secItem` — the SECItem object.
- `format` — the cert format.


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

---

### `xmlSecNssAppGetDefaultPwdCallback`

```c
void * xmlSecNssAppGetDefaultPwdCallback(void);
```

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

Gets default password callback.

**Returns:** default password callback.

---
