SSL Toothbrush
Relevant source files
The following files were used as context for generating this wiki page:
SSL Toothbrush is a specialized diagnostic utility within the DevUtils suite designed to inspect, validate, and debug SSL/TLS certificates. It provides developers with a streamlined interface to verify certificate expiry, Subject Alternative Names (SANs), chain validation, and hostname coverage, helping to "scrub" certificate issues before deployment.
The tool supports two primary modes of operation: fetching certificates directly from a live host or parsing raw PEM-encoded certificate strings provided by the user. It is integrated into the multi-tab developer tool suite and leverages a dedicated backend API for certificate retrieval and verification.
Sources: README.md:16, components/tools/ssl-toothbrush.tsx:121-125, messages/en.json:444-446
Architecture and Data Flow
The SSL Toothbrush follows a client-server architecture. The frontend component manages user input and displays results, while the backend API (/api/cert-check) handles the network-level certificate fetching and cryptographic parsing.
Verification Flow
The following diagram illustrates the process of performing a certificate check:
The flow begins with the user selecting either the "Live" or "PEM" tab. For live checks, the system requires a host and port (defaulting to 443). For PEM checks, the user provides a raw certificate string and an optional host for coverage verification.
Sources: components/tools/ssl-toothbrush.tsx:128-154, components/tools/ssl-toothbrush.tsx:174-194, messages/en.json:461-469
Core Data Structures
The system uses a standardized CertificateResult interface to pass data between the API and the UI components.
| Field | Type | Description |
|---|---|---|
subject | string | null | The full subject distinguished name of the certificate. |
issuer | string | null | The entity that issued the certificate. |
san | string[] | Array of Subject Alternative Names (DNS names, IPs). |
validTo | string | null | ISO date string indicating expiration. |
daysRemaining | number | null | Calculated days until the certificate expires. |
isExpired | boolean | Flag indicating if current time is past validTo. |
validForHost | boolean | null | Result of the hostname coverage check against the provided host. |
chainValid | boolean | null | Result of the certificate chain validation. |
warnings | WarningKey[] | List of identified issues (e.g., expiresSoon, hostnameMismatch). |
Sources: components/tools/ssl-toothbrush.tsx:32-50
Key Features
1. Live Certificate Fetching
The tool connects to a remote endpoint to inspect the certificate presented during the TLS handshake. This allows developers to verify if the server is correctly configured and serving the expected certificate.
2. PEM Parsing
Users can paste raw PEM blocks to inspect local certificate files without making network requests. This is useful for verifying certificate files before they are installed on a server.
Sources: components/tools/ssl-toothbrush.tsx:174-180, messages/en.json:455-457
3. Validity and Expiry Tracking
The UI provides a visual progress bar and status badges to indicate the remaining lifespan of a certificate.
4. Warning System
The tool automatically identifies critical issues and displays them as descriptive badges.
- Expired: Triggered if the certificate is past its validity date.
- Expires Soon: Triggered based on a threshold of
daysRemaining. - Hostname Mismatch: Triggered if the provided host is not covered by the Subject or SANs.
- Chain Invalid: Triggered if the certificate chain cannot be verified.
Sources: components/tools/ssl-toothbrush.tsx:24-30, components/tools/ssl-toothbrush.tsx:103-118, messages/en.json:480-485
Implementation Details
API Interaction
The frontend uses the fetch API to communicate with the internal /api/cert-check endpoint. It sends a JSON payload containing either the host/port or the raw PEM data.
// Example of a live check request
const response = await fetch("/api/cert-check", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
host: host.trim(),
port: parseInt(port, 10) || 443,
}),
});
Sources: components/tools/ssl-toothbrush.tsx:142-150
Hostname Validation Logic
The UI categorizes hostname coverage into three states:
- Valid: The host is explicitly covered by the certificate.
- Invalid: There is a mismatch between the certificate's SANs/Subject and the requested host.
- Unknown: No host was provided for comparison (common in PEM mode).
Sources: components/tools/ssl-toothbrush.tsx:78-87, messages/en.json:471-479
Technical Summary
SSL Toothbrush serves as a robust debugging layer for TLS configurations within the DevUtils project. By combining backend network capabilities with a React-based frontend using Tailwind CSS and Radix UI components (Tabs, Cards, Badges), it provides immediate feedback on the state of security certificates. It utilizes the jose library and standard Node.js/Tauri-friendly APIs for certificate handling.
Sources: components/tools/ssl-toothbrush.tsx:1-20, package.json:54