---
title: "Certificates Module Documentation"
description: "Documentation for Certificates"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Security Governance](#5-architectural-flow--security-governance)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#9-glossary)

---

## 1. Module Overview (Technical)

The **Certificates** module (`public.certificates`) manages public key infrastructure (PKI), TLS/SSL certificates, private key storage, and ACME automated renewals for **Ring2All Billing**. In modern telecommunications and billing architectures, robust cryptographic authentication is mandatory across customer self-care portals, carrier REST APIs, payment gateway webhooks, and secure SIP/WebRTC signaling.

This module supports three primary certificate acquisition models:
1. **Self-Signed Certificates:** Generated dynamically on-server using OpenSSL with customizable RSA key sizes (2048/4096-bit) and validity periods for lab and private interconnect testing.
2. **Let's Encrypt / ACME:** Fully automated domain verification, certificate issuance, and recurring 60-day renewal via HTTP-01 challenges.
3. **Custom Commercial Certificates:** Secure upload of third-party X.509 PEM certificates, intermediate CA bundles, and encrypted private keys issued by established Certificate Authorities (e.g., DigiCert, Sectigo).

### Data Model & System Linkage

```
 ┌────────────────────────────────────────────────────────────────────────┐
 │                   Certificate Entity (public.certificates)             │
 │  • id: bigint (Primary Key)                                            │
 │  • name: VARCHAR(100) (e.g., 'Billing Production TLS (*.ring2all.com)')│
 │  • cert_type: 'SELF_SIGNED' | 'LETS_ENCRYPT' | 'CUSTOM'                │
 │  • common_name: VARCHAR(255) (e.g., 'bss.ring2all.com')                │
 │  • sans: text[] (Subject Alternative Names Array)                      │
 │  • certificate_pem: text (Public X.509 Base64 Certificate)             │
 │  • private_key_pem: text (AES-256 Encrypted Private Key)               │
 │  • chain_pem: text (Intermediate CA Trust Bundle)                      │
 │  • issuer: VARCHAR(255) (e.g., 'Lets Encrypt Authority R3')           │
 │  • valid_from: timestamptz                                             │
 │  • valid_until: timestamptz                                           │
 │  • auto_renew: boolean                                                 │
 │  • status: 'active' | 'expired' | 'revoked'                            │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┼─────────────────────────┐
           ▼                         ▼                         ▼
 ┌───────────────────┐     ┌───────────────────┐     ┌───────────────────┐
 │ NGINX SSL Binding │     │ OpenVPN Server CA │     │ Fastify HTTPS API │
 │ • Web Admin UI    │     │ • Root CA & Server│     │ • Client Webhooks │
 │ • Customer Portal │     │   X.509 Cert      │     │ • REST Endpoints  │
 └───────────────────┘     └───────────────────┘     └───────────────────┘
```

### PostgreSQL Schema Architecture

* **`public.certificates`**:
  * `id`: Numeric primary key (`bigserial`).
  * `name`: Descriptive label indicating the domain scope and purpose.
  * `cert_type`: Origin category (`'SELF_SIGNED'`, `'LETS_ENCRYPT'`, `'CUSTOM'`).
  * `common_name`: Primary Fully Qualified Domain Name (FQDN) or IP.
  * `sans`: PostgreSQL array of alternative domain names (`VARCHAR[]`).
  * `certificate_pem`: Standard ASCII PEM-encoded public certificate block (`-----BEGIN CERTIFICATE-----`).
  * `private_key_pem`: Encrypted PEM private key block, secured using system master keys.
  * `issuer`: Organization or authority that signed the certificate.
  * `valid_until`: Expiration timestamp used for automated renewal triggering and proactive UI alerts.
  * `status`: Operational state (`'active'`, `'expired'`, `'revoked'`).

---

## 2. Module Overview (Commercial & Business Value)

* **Elimination of Browser Security Warnings:** Providing valid CA-signed TLS certificates ensures enterprise customers and prospective clients experience frictionless, trusted access without alarming browser warnings.
* **PCI-DSS & SOC 2 Compliance:** Enforces modern cryptographic ciphers (TLS 1.2 / TLS 1.3 with AES-256-GCM), protecting customer credit card numbers, billing addresses, and authentication tokens in transit.
* **Automated Expiration Risk Mitigation:** Proactive visual countdown badges (e.g., "81 days left") and automated ACME renewal daemons prevent catastrophic service interruptions caused by forgotten SSL expirations.

---

## 3. 🎯 User Roles & Key Capabilities

| User Role | Key Permissions | Core Responsibilities & Workflows |
| :--- | :--- | :--- |
| **Super Administrator** | Full Control (`CRUD` on Certificates & Keys) | Issues new certificates, uploads commercial CA bundles, configures ACME automated renewals, and deletes deprecated certificates. |
| **Security Officer / SecOps** | Cryptographic Audit | Audits key lengths (ensuring minimum 2048-bit RSA or P-256 ECC), inspects certificate chains for weak hashing (SHA-1 deprecation), and tracks expiration dates. |
| **DevOps / SysAdmin** | Read & Binding | Binds active certificates to NGINX virtual hosts in **Server Settings** and configures OpenVPN server TLS parameters. |

---

## 4. Visual Interface & Form Structure

### Level 1 — Certificates List View
The catalog lists all installed SSL/TLS credentials, displaying certificate names, types (Let's Encrypt, Self-Signed, Custom), status badges, issuers, and precise expiration dates with remaining day counters.

![Certificates List View](/screenshots/billing/admin/network/certificates/certificates-list.png)

### Level 2 — Certificate Provisioning Form
The creation view features a clean 4-column layout (`[Label 1] [Control 1] [Label 2] [Control 2]`) organized into **General Certificate Information** and **Self-Signed Parameters** (or manual upload blocks).

![Certificate Provisioning Form](/screenshots/billing/admin/network/certificates/certificates-form.png)

#### Fields & Parameters Reference
* **General Certificate Information:**
  * *Certificate Name:* Meaningful label (e.g., `Billing Production TLS (*.ring2all.com)`).
  * *Certificate Type:* Dropdown selecting `Self-Signed`, `Let's Encrypt`, or `Custom (Upload)`.
  * *Common Name (FQDN / IP):* Target domain (e.g., `bss.ring2all.com`).
  * *Subject Alternative Names (SANs):* Comma-delimited additional hostnames (e.g., `ring2all.com, *.ring2all.com`).
* **Self-Signed Parameters:**
  * *Key Size (RSA):* Cryptographic key length (`2048 bits` or `4096 bits`).
  * *Validity Period:* Certificate lifespan (`1 year`, `2 years`, `5 years`).
* **Custom Certificate Parameters (when Custom is selected):**
  * *Certificate PEM:* Public certificate block.
  * *Private Key PEM:* Matching private key block.
  * *CA Chain PEM:* Optional intermediate and root CA bundle.

---

## 5. Architectural Flow & Security Governance

```
  ┌──────────────┐       1. POST /api/v1/settings/certificates    ┌────────────────────────┐
  │ Administrator├───────────────────────────────────────────────►│  Fastify 5 API Route   │
  └──────────────┘                                                └───────────┬────────────┘
                                                                              │
                                               2. Generate OpenSSL Key Pair   │ 3. Store Encrypted in
                                                  or Request ACME Challenge   │    ss_billing
                                                                              ▼
  ┌──────────────┐       5. NGINX SSL Reload (Zero Downtime)      ┌────────────────────────┐
  │ NGINX Daemon ◄────────────────────────────────────────────────┤ Certificate Synchronizer│
  └──────────────┘                                                └────────────────────────┘
                                                                              │
                                                                 4. Write to File System:
                                                                    /etc/ssl/ring2all/
```

1. **Initiation:** The administrator selects the certificate type, enters domain parameters, and clicks **Save**.
2. **Generation / Verification:**
   * *Self-Signed:* OpenSSL generates the private key and self-signs the certificate directly.
   * *Let's Encrypt:* The ACME agent provisions an HTTP-01 challenge under `/.well-known/acme-challenge/`, verifies domain ownership with Let's Encrypt, and receives signed certificates.
   * *Custom:* The server validates that the public certificate matches the provided private key modulus.
3. **Database Storage:** Certificate assets are written to `public.certificates`.
4. **File System Deployment:** PEM files are written with strict `0600` permissions to `/etc/ssl/ring2all/certs/`.
5. **Web Server Reload:** NGINX executes a seamless configuration reload.

---

## 6. Common Scenarios & Operational Playbooks

### Playbook 1: Generating a Self-Signed Certificate for Lab Testing
1. Navigate to **ADMIN > Network > Certificates**.
2. Click **+ Add** in the top-right toolbar.
3. Enter **Certificate Name:** `Billing Lab Test TLS`.
4. Select **Certificate Type:** `Self-Signed`.
5. In **Common Name (FQDN / IP)**, enter the server's local IP or internal hostname: `192.168.10.29`.
6. Select **Key Size (RSA):** `2048 bits` and **Validity Period:** `1 year`.
7. Click **Save** in the bottom-right action bar.
8. Navigate to **ADMIN > Network > Server Settings** and bind the newly generated certificate to the web portal.

### Playbook 2: Installing a Commercial Wildcard SSL Certificate
1. Procure a wildcard certificate (`*.yourdomain.com`) from a trusted Certificate Authority.
2. Navigate to **ADMIN > Network > Certificates** and click **+ Add**.
3. Enter **Certificate Name:** `Commercial Wildcard TLS 2026`.
4. Set **Certificate Type:** `Custom (Upload)`.
5. In **Common Name**, enter `*.yourdomain.com`.
6. Paste the contents of your certificate into **Certificate PEM**, the private key into **Private Key PEM**, and the intermediate bundle into **CA Chain PEM**.
7. Click **Save**.
8. Verify in the list view that the status displays `Active` and the issuer matches your CA.

---

## 7. Troubleshooting & Diagnostic Commands

### Validating Certificate Modulus Match
```bash
# Verify that a public certificate and private key match identically
openssl x509 -noout -modulus -in /etc/ssl/ring2all/certs/bundle.crt | openssl md5
openssl rsa -noout -modulus -in /etc/ssl/ring2all/certs/private.key | openssl md5
# Both MD5 checksums must be identical
```

### Inspecting Certificate Details from Database
```bash
sudo -u postgres psql -d ss_billing -c \
  "SELECT id, name, cert_type, common_name, issuer, valid_until, status \
   FROM certificates ORDER BY id DESC;"
```

### Verifying TLS Handshake from Remote Terminal
```bash
# Test remote SSL connection and inspect served certificate chain
openssl s_client -connect 192.168.10.29:8443 -servername bss.example.com
```

---

## 8. Model Context Protocol (MCP) AI Integration

The **Certificates** module connects directly to the **Ring2All BSS MCP Server**, providing SSL administrators and security automation agents with tools to audit TLS certificate expiration windows and common names programmatically.

### Available MCP Tools

| Tool Name | Access Role | Description & Primary Function | Example Arguments |
| :--- | :--- | :--- | :--- |
| `list_ssl_certificates` | `Super Administrator` | Lists SSL/TLS certificates, domain names, issuers, expiration dates, and active flags. | `{}` |

### Sample MCP Tool Execution: `list_ssl_certificates`

#### Request Payload
```json
{
  "name": "list_ssl_certificates",
  "arguments": {}
}
```

#### Response Payload
```json
[
  {
    "id": 1,
    "name": "Production Wildcard SSL",
    "commonName": "*.ring2all.com",
    "certType": "custom",
    "issuer": "Let's Encrypt Authority X3",
    "validUntil": "2026-11-30T00:00:00Z",
    "status": "valid",
    "isActive": true
  }
]
```

### Conversational AI Prompts for Copilot
* *"Check if any SSL/TLS certificates will expire in the next 30 days."*
* *"List all active certificates and their associated domain names."*
* *"Verify the issuer and expiration date of our wildcard certificate."*

---

## 9. Glossary

* **ACME (Automated Certificate Management Environment):** A communications protocol for automating interactions between certificate authorities and web servers.
* **SAN (Subject Alternative Name):** An extension to X.509 that allows multiple domain names to be protected by a single SSL certificate.
* **Modulus:** The mathematical product of two prime numbers used in RSA key generation; the certificate and private key must share the exact same modulus.
* **Intermediate CA:** A certificate issued by a root authority used to sign end-user certificates, establishing an unbroken chain of trust.
* **Model Context Protocol (MCP):** Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.