### List Public Keys in NSS Database using keyutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

This command lists the public keys stored within the specified NSS certificate database. The `-L` flag is used for listing keys. Users are prompted for a password or PIN to access the database. The output displays the RSA public keys, and unique starting characters can be used to identify specific keys.

```bash
C:\nss11\winnt>keyutil -L -d server_db 
Enter Password or Pin for "Communicator Certificate DB":   
RSA Public-Key:   
   modulus:   
      00:f7:c1:1f:a2:c1:cb:12:cc:08:91:60:48:e4:00:43:17:f1:   
      fc:b1:88:4b:54:47:2d:11:64:ec:c3:15:d7:5b:68:32:93:f9:   
      86:71:ce:c9:cc:f0:e0:a6:28:80:86:cc:88:29:70:67:81:1d:   
      4f:86:04:38:52:0f:b0:aa:83:36:1b:27:06:b9:99:08:0c:3b:   
      d8:98:53:16:08:09:20:44:c7:8a:72:da:a2:b5:7b:71:b7:ce:   
      ab:48:fc:31:1e:61:09:31:0c:ef:00:05:f2:de:09:7f:f7:af:   
      d6:24:3e:29:09:ba:d3:98:31:12:9e:d9:b9:b4:7e:ef:01:81:   
      cc:92:79 
RSA Public-Key:   
   modulus:   
   00:b6:2b:e8:71:6e:a5:e3:90:51:00:9d:7a:00:3b:50:eb:9e:   
   78:33:d8:ac:1d:95:a9:21:47:25:d0:39:ad:22:0f:d9:81:ed:   
   60:be:4d:db:20:f5:91:15:76:bf:5f:6c:06:aa:d1:08:8c:f9:   
   7c:79:b7:cd:f0:76:da:2d:5f:42:21:40:3b:92:86:b3:df:4e:   
   42:b8:92:18:01:91:48:c1:9d:ee:ae:03:55:c0:a1:74:69:9b:   
   86:f8:c0:9a:47:0a:52:30:d9:53:40:24:54:15:19:a6:92:c8:   
   7f:1f:3b:e4:0e:4c:09:73:ad:1e:16:00:e7:f4:3d:5f:f4:22:   
   f4:dd:7f 
```

--------------------------------

### SEC_ERROR_TOKEN_NOT_LOGGED_IN Error

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslerr

Indicates that NSS (Network Security Services) is not initialized. This error must be resolved before any NSS functions can be successfully called, as it signifies a fundamental setup failure.

```c
#define SEC_ERROR_TOKEN_NOT_LOGGED_IN       -8038
```

--------------------------------

### Get Default Key Database Handle (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslkey

Retrieves a handle to the default key database that was opened by NSS_Init. This function is essential for interacting with key stores managed by NSS.

```c
#include <key.h>
#include <keyt.h>

SECKEYKeyDBHandle *SECKEY_GetDefaultKeyDB(void);
```

--------------------------------

### Get Certificate Nicknames

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt

Retrieves the nicknames of certificates within a specified certificate database, categorized by type.

```APIDOC
## CERT_GetCertNicknames

### Description
Returns the nicknames of the certificates in a specified certificate database. `CERT_GetCertNicknames` must call one or more PK11 functions to obtain the services of a PKCS #11 module. Some of the PK11 functions require a PIN argument (see `SSL_SetPKCS11PinArg` for details), which must be specified in the `wincx` parameter. To obtain the value to pass in the `wincx` parameter, call `SSL_RevealPinArg`.

### Method
CERTCertNicknames *CERT_GetCertNicknames (
    CERTCertDBHandle *handle,
    int what,
    void *wincx);

### Parameters
#### Path Parameters
- **handle** (CERTCertDBHandle *) - A pointer to the certificate database handle.
- **what** (int) - One of these values:
  * `SEC_CERT_NICKNAMES_ALL`
  * `SEC_CERT_NICKNAMES_USER`
  * `SEC_CERT_NICKNAMES_SERVER`
  * `SEC_CERT_NICKNAMES_CA`
- **wincx** (void *) - The PIN argument value to pass to PK11 functions. See description below for more information.

### Returns
The function returns a `CERTCertNicknames` object containing the requested nicknames.
```

--------------------------------

### Socket Initialization and Import

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

This section covers the initial steps of creating and importing NSPR sockets into the SSL environment.

```APIDOC
## Socket Initialization and Import

### Description
This section covers the initial steps of creating and importing NSPR sockets into the SSL environment. This typically involves opening a new socket and then importing it into the SSL environment.

### Functions

*   **PR_NewTCPSocket**
    *   **Description**: Opens a new socket. A legal NSPR socket is required to be passed to `SSL_ImportFD`, whether it is created with this function or by another method.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

*   **SSL_ImportFD**
    *   **Description**: Makes an NSPR socket into an SSL socket. Required. Brings an ordinary NSPR socket into the SSL library, returning a new NSPR socket that can be used to make SSL calls. You can pass this function a _model_ file descriptor to create the new SSL socket with the same configuration state as the model.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

### Usage Notes
It is also possible for an application to import a socket into SSL after the TCP connection on that socket has already been established. In this case, initial configuration takes place in the same way: pass the existing NSPR file descriptor to `SSL_ImportFD` and perform any additional configuration that has not already been determined by the model file descriptor.
```

--------------------------------

### Create Client Certificate Database (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Creates a new certificate database for client-side operations in the specified directory.

```bash
C:\nss11\winnt>certutil -N -d client_db
```

--------------------------------

### Get Default Certificate Database Handle (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt

Retrieves a handle to the default certificate database. This function is useful for checking if the default database has been opened and returns a pointer to CERTCertDBHandle.

```C
#include <cert.h>

CERTCertDBHandle *CERT_GetDefaultCertDB(void);
```

--------------------------------

### Create and Sign Server Certificate (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Creates a server certificate from a request and signs it using the CA's private key. It specifies the certificate request file, output certificate file, serial number, and the nickname of the issuing CA. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -C -c "MyCo's Root CA" -i server_db\server.req -o server_db\server.crt -m 1222 -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Create and Sign Client Certificate using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Creates a new certificate from a request and signs it with the CA's private key. This step requires access to the CA's key database.

```bash
C:\nss11\winnt>certutil -C -c "MyCo's Root CA" -i client_db\client.req -o client_db\client.crt -m 3434 -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### SSL Initialization Functions

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

Overview of essential functions for initializing an SSL application, including NSPR initialization, password functions, NSS initialization, and setting default options.

```APIDOC
## Initialization Functions

### Description
Functions used in the initialization part of an SSL application.

### Method
N/A (Documentation of functions)

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
None

### Functions
- `PR_Init`
  - Description: Initializes NSPR. Must be called before any other NSS functions.
  - Required: Yes
- `PK11_SetPasswordFunc`
  - Description: Sets the global callback function to obtain passwords for PKCS #11 modules.
  - Required: Yes
- `NSS_Init`
  - Description: Sets up configuration files and performs other tasks required to run Network Security Services. Not idempotent, call only once.
  - Required: Yes
- `SSL_OptionSetDefault`
  - Description: Changes default values for all subsequently opened sockets. Must be called once for each default value that needs to be changed.
  - Required: Optional
- `NSS_SetDomesticPolicy`, `NSS_SetExportPolicy`, `NSS_SetFrancePolicy`, or `SSL_CipherPolicySet`
  - Description: These functions tell the library which cipher suites are permitted by policy. One must be called before any cryptographic operations can be performed.
  - Required: Yes
- `SSL_CipherPrefSetDefault`
  - Description: Enables all ciphers chosen by user preference.
  - Required: Optional
```

--------------------------------

### SSL_ResetHandshake

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Resets the SSL handshake protocol to start from the beginning on the next I/O operation. This is useful when importing an already connected socket into SSL to specify client or server behavior.

```APIDOC
## SSL_ResetHandshake

### Description
Calling `SSL_ResetHandshake` causes the SSL handshake protocol to start from the beginning on the next I/O operation. That is, the handshake starts with no cipher suite already in use, just as it does on the first handshake on a new socket.

When an application imports a socket into SSL after the TCP connection on that socket has already been established, it must call `SSL_ResetHandshake` to determine whether SSL should behave like an SSL client or an SSL server. Note that this step would not be necessary if the socket weren't already connected. For an SSL socket that is configured before it is connected, SSL figures this out when the application calls `PR_Connect` or `PR_Accept`. If the socket is already connected before SSL gets involved, you must provide this extra hint.

### Method
[HTTP method not applicable, this is a function call]

### Endpoint
[Endpoint not applicable]

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
SECStatus SSL_ResetHandshake(PRFileDesc *fd, PRBool asServer);
```

### Response
#### Success Response
- **SECSuccess** (SECStatus) - Indicates successful reset.

#### Response Example
`SECSuccess`
```

--------------------------------

### Get Certificate Nicknames (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslcrt

Retrieves nicknames for certificates in a specified database, categorized by type (all, user, server, CA). It requires a handle, a type specifier, and a window context for PKCS #11 PIN arguments.

```c
#include <cert.h>
#include <certt.h>

CERTCertNicknames *CERT_GetCertNicknames (
   CERTCertDBHandle *handle,
   int what,
   void *wincx);

```

--------------------------------

### List Client Public Key (keyutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Lists the public key information stored within the client's certificate database. Requires the password for the certificate database.

```bash
C:\nss11\winnt>keyutil -L -d client_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Get Default Cipher Suite Preference (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Retrieves the current default preference setting for a specified SSL2 or SSL3 cipher suite. If no preference has been set by the application, it returns the factory default. This function complements SSL_CipherPrefSetDefault.

```c
#include "ssl.h"

SECStatus SSL_CipherPrefGetDefault(PRInt32 cipher, PRBool *enabled);
```

--------------------------------

### Generate Client Key Pairs (keyutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Generates key pairs for client-side operations within the specified certificate database. The tool automatically creates the key database directory if it doesn't exist.

```bash
C:\nss11\winnt>keyutil -G -d client_db
```

--------------------------------

### Create Client Certificate Request using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Generates a client certificate request, specifying the subject name and key. This is the first step in creating a client certificate.

```bash
C:\nss11\winnt>certutil -R -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k d87e -o client_db\client.req -d client_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Get Slot Name (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/pkfnc

Retrieves the name associated with a specific PKCS #11 slot. The returned string should not be freed by the caller, as it may be freed when the slot itself is freed. It's recommended to copy the string if it needs to be preserved.

```c
#include <pk11func.h>

char *PK11_GetSlotName(PK11SlotInfo *slot);

```

--------------------------------

### SECStatus Enum Definition and Usage

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/ssltyp

Defines the SECStatus enumeration, which is the return value for many SSL functions. It indicates whether an operation succeeded, failed, or would block. Includes usage examples and error handling with PR_GetError.

```c
#include <seccomon.h>

typedef enum {
    SECWouldBlock = -2,
    SECFailure = -1,
    SECSuccess = 0
} SECStatus;
```

--------------------------------

### Get Default SSL Option Value (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Retrieves the current default setting for a specified SSL option. This function is the counterpart to SSL_OptionSetDefault. It takes an option identifier and a pointer to a boolean to store the result. Returns SECSuccess on success or SECFailure on failure.

```c
#include "ssl.h"

SECStatus SSL_OptionGetDefault(PRInt32 option, PRBool *on)
```

--------------------------------

### Add Client Certificate to Database using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Adds the newly created client certificate to the certificate database with specified trust flags and a nickname.

```bash
C:\nss11\winnt>certutil -A -n myco.mcom.org -i client_db\client.crt -t "u,u,u" -d client_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Create NSS Certificate Database using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

This command creates a new certificate database in the specified directory. It is a prerequisite for generating keys and certificates within that database. The `-N` flag indicates the creation of a new database.

```bash
C:\nss11\winnt>certutil -N -d server_db 
```

--------------------------------

### Get Token Name (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/pkfnc

Obtains the name of the token associated with a given PKCS #11 slot. Similar to PK11_GetSlotName, the caller should not free the returned string directly. If the slot is freed, the token name string may also be invalidated.

```c
#include <pk11func.h>

char *PK11_GetTokenName(PK11SlotInfo *slot);

```

--------------------------------

### Get SSL Security Status

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

The SSL_SecurityStatus function retrieves information about the current SSL connection's security parameters. It populates output parameters with details such as whether security is enabled, the cipher suite, key sizes, and the issuer and subject of the SSL certificate.

```c
#include "ssl.h"

SECStatus SSL_SecurityStatus(
 PRFileDesc *fd,
 int *on,
 char **cipher,
 int *keysize,
 int *secretKeySize,
 char **issuer,
 char **subject
);
```

--------------------------------

### NSS Initialization and Policy Functions

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/bklast

This section covers functions for initializing NSS and configuring security policies, including export and domestic policies.

```APIDOC
## NSS Initialization and Policy Functions

### Description
Functions for initializing the NSS library and setting security policies.

### Functions
- `NSS_Init`: Initializes the NSS library.
- `NSS_InitReadWrite`: Initializes the NSS library for read/write operations.
- `NSS_NoDB_Init`: Initializes NSS without a database.
- `NSS_SetDomesticPolicy`: Sets the domestic security policy.
- `NSS_SetExportPolicy`: Sets the export security policy.
- `NSS_SetFrancePolicy`: Sets the French security policy.
- `NSS_Shutdown`: Shuts down the NSS library.
```

--------------------------------

### Get SSL Session ID - C

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Retrieves the SSL session ID associated with a given file descriptor. It returns a SECItem structure containing the session ID on success, or NULL on failure. The caller is responsible for freeing the returned SECItem structure using SECITEM_FreeItem.

```c
#include "ssl.h"

SECItem *SSL_GetSessionID(PRFileDesc *fd);
```

--------------------------------

### Cleanup Procedures

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

Steps for properly shutting down SSL-enabled applications and cleaning up resources.

```APIDOC
## Cleanup

Proper cleanup involves closing sockets, freeing memory, and shutting down NSS and NSPR.

### Steps
1. **Close Socket**: Ensure the communication socket is closed.
2. **Free Memory**: Release any dynamically allocated memory.
3. **Shutdown NSS**: Call `NSS_Shutdown` to close certificate and key databases opened by `NSS_Init`.
4. **Shutdown NSPR**: Call `PR_Cleanup` to initiate a graceful shutdown of the NSPR library.
```

--------------------------------

### Add Server Certificate to Database (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Adds a server certificate to the certificate database. It specifies the certificate file, trust flags (indicating its usability for SSL, email, and object signing), and a nickname. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -A -n myco.mcom.org -i server_db\server.crt -t "u,u,u" -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Get SSL Option Status - C

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

The SSL_OptionGet function retrieves the current status (on or off) of a specified SSL option for a given SSL socket. It requires a file descriptor, the option identifier, and a pointer to a boolean to store the result. The function returns SECSuccess on success or SECFailure on error.

```c
#include "ssl.h"

SECStatus SSL_OptionGet(
    PRFileDesc *fd,
    PRInt32 option,
    PRBool *on
);
```

--------------------------------

### Get SSL Cipher Policy

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

The SSL_CipherPolicyGet function retrieves the current policy setting for a specified cipher suite. This function serves as the complementary operation to SSL_CipherPolicySet, allowing developers to query the established policy for a given cipher. It requires the cipher suite identifier and returns the policy through a pointer.

```c
#include "ssl.h"
#include "proto.h"

SECStatus SSL_CipherPolicyGet(PRInt32 cipher, PRInt32 *policy);
```

--------------------------------

### SSL Configuration and Option Functions

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/bklast

This section details functions for configuring SSL connections, including cipher preferences, options, and session caching.

```APIDOC
## SSL Configuration and Option Functions

### Description
Functions for configuring SSL connections, managing cipher suites, and handling session data.

### Functions
- `SSL_CipherPolicyGet`: Retrieves the current cipher policy.
- `SSL_CipherPolicySet`: Sets the cipher policy.
- `SSL_CipherPrefGet`: Gets the preferred cipher list.
- `SSL_CipherPrefGetDefault`: Gets the default preferred cipher list.
- `SSL_CipherPrefSet`: Sets the preferred cipher list.
- `SSL_CipherPrefSetDefault`: Sets the default preferred cipher list.
- `SSL_ClearSessionCache`: Clears the SSL session cache.
- `SSL_ConfigMPServerSessionSIDCache`: Configures multi-process server session ID cache.
- `SSL_ConfigSecureServer`: Configures a secure server.
- `SSL_ConfigServerSessionIDCache`: Configures server session ID cache.
- `SSL_Enable`: Enables SSL functionality.
- `SSL_EnableCipher`: Enables a specific cipher.
- `SSL_EnableDefault`: Enables default SSL options.
- `SSL_OptionGet`: Retrieves an SSL option.
- `SSL_OptionGetDefault`: Retrieves the default SSL option.
- `SSL_OptionSet`: Sets an SSL option.
- `SSL_OptionSetDefault`: Sets the default SSL option.
- `SSL_SetPolicy`: Sets the SSL policy.
- `SSL_SetURL`: Sets the URL for SSL context.
```

--------------------------------

### Get Peer Certificate in SSL Connection (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Retrieves the certificate structure of the remote peer in an SSL connection. This function is useful in callback functions for certificate authentication. It returns a pointer to the certificate structure on success or NULL on failure. The application must manage the lifecycle of the returned certificate structure.

```c
#include "ssl.h"

CERTCertificate *SSL_PeerCertificate(PRFileDesc *fd);
```

--------------------------------

### Verify Server Certificate using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Verifies the validity of the server certificate using the certutil command with the '-V' flag and appropriate trust options.

```bash
C:\nss11\winnt>certutil -V -u V -n myco.mcom.org -d server_db 
Certificate:'myco.mcom.org' is valid!
```

--------------------------------

### Get SSL Cipher Preferences for a Socket

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

SSL_CipherPrefGet retrieves the current preference setting for a specified SSL2 or SSL3 cipher suite on a given socket. This function is the complement to SSL_CipherPrefSet. If no preference has been set for the socket, it returns the process default or inherited value. Dependencies include the ssl.h and proto.h headers.

```c
#include "ssl.h"
#include "proto.h"

SECStatus SSL_CipherPrefGet(
    PRFileDesc *fd,
    PRInt32 cipher,
    PRBool *enabled);

```

--------------------------------

### SSL Session Cache Initialization

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

Details on initializing and configuring SSL session caches for both client and server applications to improve connection performance.

```APIDOC
## Initializing Caches

### Description
Functions for managing SSL session caches to avoid the overhead of full SSL handshakes for reconnecting peers.

### Method
N/A (Documentation of functions)

### Endpoint
N/A

### Parameters
None

### Request Example
None

### Response
None

### Functions
- `SSL_ClearSessionCache`
  - Description: Clears all sessions from the client session cache.
  - Required: Optional (for client cache)
- `SSL_ConfigServerSessionIDCache`
  - Description: Sets up parameters for a server session cache for a single-process application.
  - Required: Yes (for single-process server applications)
- `SSL_ConfigMPServerSIDCache`
  - Description: Sets up parameters for a server cache for a multi-process application. Use either this or `SSL_ConfigServerSessionIDCache`, not both.
  - Required: Yes (for multi-process server applications)
```

--------------------------------

### Create Server Certificate Request (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Generates a Certificate Signing Request (CSR) for a server certificate. It requires the common name (CN) to match the server's hostname, specifies the key to use, and the output file. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -R -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k b62b -o server_db\server.req -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Get Server Domain Name from SSL Connection (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Obtains the domain name of the target SSL server as a newly allocated string. This function is typically used within certificate authentication callbacks to compare the server's presented domain name against the actual intended domain. The caller is responsible for freeing the returned string using PR_Free.

```c
#include "ssl.h"

char *SSL_RevealURL(PRFileDesc *fd);
```

--------------------------------

### Verify Client Certificate using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Verifies the validity of the client certificate using the certutil command with the '-V' flag and appropriate trust options for client verification.

```bash
C:\nss11\winnt>certutil -V -u C -n myco.mcom.org -d client_db 
Certificate:'myco.mcom.org' is valid!
```

--------------------------------

### Initialize NSS for Read-Write Database Access (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Sets up configuration files and performs tasks for Network Security Services with both read and write access to database files. It opens certificate, key, and security module databases with write permissions. This function is not idempotent and requires PR_Init to be called beforehand. Cipher suites are disabled by default, requiring explicit policy configuration.

```c
#include "nss.h"

SECStatus NSS_InitReadWrite(char *configdir);
```

--------------------------------

### Callbacks and Helper Functions

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

Callbacks and helper functions enable customization of authentication mechanisms and error handling during SSL operations.

```APIDOC
## Callbacks and Helper Functions

### Description
Callbacks and helper functions allow you to specify such things as how authentication is accomplished and what happens if it fails.

### Functions

*   **SSL_SetPKCS11PinArg**
    *   **Description**: Sets the argument passed to the PKCS #11 password callback function. Required.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

*   **SSL_AuthCertificateHook**
    *   **Description**: Specifies a callback function used to authenticate an incoming certificate (optional for servers, necessary for clients to avoid "man-in-the-middle" attacks). Optional. If not specified, SSL uses the default callback function, `SSL_AuthCertificate`.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

*   **SSL_BadCertHook**
    *   **Description**: Specifies a callback function to deal with a situation where authentication has failed. Optional.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

*   **SSL_GetClientAuthDataHook**
    *   **Description**: Specifies a callback function for SSL to use when the server asks for client authentication information. This callback is required if you want to do client authentication. You can set the callback function to a standard one that is provided, `NSS_GetClientAuthData`.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A

*   **SSL_HandshakeCallback**
    *   **Description**: Specifies a callback function that will be used by SSL to inform either a client application or a server application when the SSL handshake is completed. Optional.
    *   **Method**: N/A (Function call)
    *   **Endpoint**: N/A
```

--------------------------------

### Create and Self-Sign CA Certificate (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Creates a new CA certificate from a certificate request and self-signs it. It uses the specified request file, output file, key, and serial number. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -C -i server_db\rootca.req -o server_db\rootca.crt -k f7c1 -x -m 1234 -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Add CA Certificate to Client Database using certutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Adds the CA certificate to the client database, enabling the client to authenticate the server's certificate. Trust flags are set for CA authentication.

```bash
C:\nss11\winnt>certutil -A -n "MyCo's Root CA" -i server_db\rootca.crt -t "CT,CT,CT" -d client_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Generate Key Pairs using keyutil

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

This command generates new key pairs within the specified NSS certificate database. The `-G` flag signifies key generation. The Certificate Database Tool automatically creates the key and security module databases if they do not already exist when the first key pair is generated.

```bash
C:\nss11\winnt>keyutil -G -d server_db 
C:\nss11\winnt>keyutil -G -d server_db 
```

--------------------------------

### Add CA Certificate to Database (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Adds a CA certificate to the certificate database. It specifies the certificate file, trust flags (indicating its CA role and trust for client/server SSL, email, and object signing), and a nickname for easy identification. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -A -n "MyCo's Root CA" -i server_db\rootca.crt -t "CTu,CTu,CTu" -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### Initialize NSS Without Database Files (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

NSS_NoDB_Init initializes Network Security Services without requiring configuration files, opening only temporary databases and internal PKCS #112 modules. It's suitable for applications needing raw crypto, hashing, and certificate functions without persistent storage. This function is not idempotent and requires PR_Init to be called beforehand. It does not enable cipher suites by default.

```c
#include "nss.h"

SECStatus NSS_NoDB_Init(char *reserved);

```

--------------------------------

### SSL Communication Overview

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslintro

Details on initiating and managing SSL communication, including automatic handshakes and explicit control.

```APIDOC
## SSL Communication

SSL communication begins with an SSL handshake, which can occur automatically or be forced explicitly.

### Automatic Handshake
The handshake occurs automatically upon the first read/write or send/receive call on an SSL socket.

### Explicit Handshake Control
- `SSL_ForceHandshake`: Explicitly forces the handshake process.
- `SSL_ReHandshake`: Explicitly repeats the handshake process.

### Server Connection Functions
- `PR_Bind`
- `PR_Listen`
- `PR_Accept`
- `PR_GetSockName`

### Client Connection Functions
- `PR_GetHostByName`
- `PR_EnumerateHostEnt`
- `PR_Connect`
- `PR_GetConnectStatus`

### Handling Pre-established Connections
If a socket is already connected before SSL involvement, `SSL_ResetHandshake` must be called to specify client or server role. For sockets configured before connection, `PR_Connect` or `PR_Accept` determines the role.

### General Communication Functions
- `PR_Send` or `PR_Write`: Send data over the socket.
- `PR_Read` or `PR_Recv`: Receive data from the socket.
- `PR_GetError`: Retrieve the last error code.
- `PR_GetPeerName`: Get the name of the remote peer.
- `PR_Sleep`: Pause execution.
- `PR_Malloc`: Allocate memory.
- `PR_Free`: Free allocated memory.
- `PR_Poll`: Monitor file descriptors for readiness.
- `PR_Now`: Get the current time.
- `PR_IntervalToMilliseconds`: Convert interval to milliseconds.
- `PR_MillisecondsToInterval`: Convert milliseconds to interval.
- `PR_Shutdown`: Shut down the socket connection.
- `PR_Close`: Close the socket.
- `SSL_InvalidateSession`: Invalidate the current SSL session.

### Initiating Communication After Handshake
After connection, use `PR_Send`, `PR_Recv`, `PR_Read`, `PR_Write`, or `SSL_ForceHandshake` to start communication. The protocol dictates which end speaks first, typically using `PR_Send`/`PR_Write` for the first sender and `PR_Read`/`PR_Recv` for the receiver.

### Use Case for `SSL_ForceHandshake`
Used when a handshake is needed but neither end has immediate data to send, such as an HTTPS server needing a client certificate before responding to a request. It involves calling `SSL_ReHandshake` followed by `SSL_ForceHandshake`.
```

--------------------------------

### Initialize NSS for Read-Only Database Access (C)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/sslfnc

Sets up configuration files and performs tasks for Network Security Services with read-only access to database files. It opens certificate, key, and security module databases. This function is not idempotent and requires PR_Init to be called beforehand. Cipher suites are disabled by default, requiring explicit policy configuration.

```c
#include "nss.h"

SECStatus NSS_Init(char *configdir);
```

--------------------------------

### Create CA Certificate Request (certutil)

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/gtstd

Generates a Certificate Signing Request (CSR) for a Certificate Authority (CA) certificate. It specifies the subject name, the key to use, and output file. Requires password for the certificate database.

```bash
C:\nss11\winnt>certutil -R -s "CN=myco.mcom.org,O=MyCo,ST=California,C=US" -k f7c1 -o server_db\rootca.req -d server_db 
Enter Password or Pin for "Communicator Certificate DB":
```

--------------------------------

### PKCS#11 Key and Certificate Functions

Source: https://www-archive.mozilla.org/projects/security/pki/nss/ref/ssl/bklast

This section details functions for interacting with PKCS#11 tokens for key and certificate management.

```APIDOC
## PKCS#11 Key and Certificate Functions

### Description
Functions for managing keys and certificates using PKCS#11 hardware security modules.

### Functions
- `PK11_FindCertFromNickname`: Finds a certificate from a nickname.
- `PK11_FindKeyByAnyCert`: Finds a private key associated with any certificate.
- `PK11_GetSlotName`: Gets the name of a PKCS#11 slot.
- `PK11_GetTokenName`: Gets the name of a PKCS#11 token.
- `PK11_IsHW`: Checks if a PKCS#11 token is hardware-based.
- `PK11_IsPresent`: Checks if a PKCS#11 token is present.
- `PK11_IsReadOnly`: Checks if a PKCS#11 token is read-only.
- `PK11_SetPasswordFunc`: Sets a password function for PKCS#11 operations.
```