(mozilla-projects-nss-ssl-functions-sslkey)=

# sslkey

::::{container}

:::{note}

- This page is part of the {ref}`mozilla_projects_nss_ssl_functions_old_ssl_reference` that
  we are migrating into the format described in the [MDN Style
  Guide](https://developer.mozilla.org/en-US/docs/MDN/Guidelines). If you are inclined to
  help with this migration, your help would be very much appreciated.
- Upgraded documentation may be found in the {ref}`mozilla_projects_nss_reference`
:::

```{rubric} Key Functions
:name: Key_Functions
```

::::

[Chapter 6](#chapter_6_key_functions) Key Functions

______________________________________________________________________

:::{container}
This chapter describes two functions used to manipulate private keys and key databases such as
the `key3.db` database provided with Communicator.

`` `SECKEY_GetDefaultKeyDB ``

 \<#1051479>\`\_\_

`` `SECKEY_DestroyPrivateKey ``

 \<#1051017>\`\_\_

```{rubric} SECKEY_GetDefaultKeyDB
```

Returns a handle to the default key database opened by
{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1067601`.

```{rubric} Syntax
```

```{code}
#include <key.h>
#include <keyt.h>
```

```{code}
SECKEYKeyDBHandle *SECKEY_GetDefaultKeyDB(void);
```

```{rubric} Returns
```

The function returns a handle of type `SECKEYKeyDBHandle`.

```{rubric} Description
```

{ref}`mozilla_projects_nss_ssl_functions_sslfnc#1067601` opens the certificate, key, and security
module databases that you specify for use with NSS. `SECKEYKeyDBHandle` returns a handle to the
key database opened by `NSS_Init`.

```{rubric} SECKEY_DestroyPrivateKey
```

Destroys a private key structure.

```{rubric} Syntax
```

```{code}
#include <key.h>
#include <keyt.h>
```

```{code}
void SECKEY_DestroyPrivateKey(SECKEYPrivateKey *key);
```

```{rubric} Parameter
```

This function has the following parameter:

```{eval-rst}
+-------------------------------------------------+-------------------------------------------------+
| .. code::                                       | A pointer to the private key structure to       |
|                                                 | destroy.                                        |
|    key                                          |                                                 |
+-------------------------------------------------+-------------------------------------------------+
```

```{rubric} Description
```

Certificate and key structures are shared objects. When an application makes a copy of a
particular certificate or key structure that already exists in memory, SSL makes a *shallow*
copy--that is, it increments the reference count for that object rather than making a whole new
copy. When you call `` `CERT_DestroyCertificate `` \<sslcrt.html#1050532>\`\_\_ or
`` `SECKEY_DestroyPrivateKey `` \<#1051017>\`\_\_, the function decrements the reference count and, if
the reference count reaches zero as a result, both frees the memory and sets all the bits to
zero. The use of the word "destroy" in function names or in the description of a function implies
reference counting.

Never alter the contents of a certificate or key structure. If you attempt to do so, the change
affects all the shallow copies of that structure and can cause severe problems.
:::