Cert Unifier Security Module#

1. Overview
2. Key Features
3. System Requirements
4. Quick Start Guide
5. Installation & Setup
6. Architecture & Components
7. Usage Examples
8. Parameters Reference
9. Technical Considerations
10. License & Acknowledgments

1. Overview#

Cert Unifier (v2.9.0) is a high-performance Bash module designed to automate the assembly, validation, and unification of SSL/TLS certificates and private keys into standardized PEM and PFX bundles. Engineered for DevOps workflows and automated web server deployments (Nginx, Apache, HAProxy), it ensures cryptographic consistency and atomic file operations across diverse certificate structures.

Primary Purpose#

The module streamlines certificate lifecycle management by:

Merging leaf certificates and intermediate chains with matching private keys
Validating RSA/EC modulus matches to prevent deployment of mismatched assets
Automating PKCS#12 (PFX) generation for Windows/IIS environments
Enforcing secure file permissions (0600) on sensitive cryptographic material
Supporting both modern Certbot layouts and legacy directory structures

2. Key Features#

2.1 Unified PEM Assembly#

Atomic Writes: Utilizes temporary buffers to ensure file integrity during assembly
Newline Normalization: Guaranteed proper separation between key and chain components
Auto-Discovery: Intelligent scanning of legacy and modern Certbot layouts

2.2 Advanced Cryptographic Validation#

Modulus Verification: Deep validation of private keys against certificates before unification
Key Integrity: Multi-engine support (RSA/EC) for modulus extraction and comparison
PFX Matching: v2.9.0 introduces auto-discovery of matching key/cert pairs for PKCS#12 creation

2.3 Comprehensive Layout Support#

Certbot Native: Native processing of /etc/letsencrypt/live structures
Legacy Support: Support for leX.crt and leX.key naming conventions
TLD Filtering: Customizable domain processing based on Top-Level Domains (default: .ru, .com)

2.4 Enterprise Deployment Features#

Dry-Run Mode: Full validation of inputs and output paths without filesystem modification
Secure Permissions: Automated application of 0600 permissions to private keys and PFX files
Logging Architecture: Multi-level logging (DEBUG, INFO, WARN, ERROR) with timestamps

3. System Requirements#

3.1 Minimum Requirements#

OS: Linux (any modern distribution), macOS, or WSL
Shell: Bash 4.0 or later
Utilities: openssl, grep, awk, date
Permissions: Read access to source certificates; write access to output directories

3.2 Recommended Configuration#

OpenSSL: 1.1.1+ (supports modern ECC and friendly name attributes)
Filesystem: Standard Linux/Unix permissions model supported
Dependencies: Full openssl toolkit for PFX generation and deep key validation

4. Quick Start Guide#

4.1 Deployment in 3 Steps#

Step 1: Download the Script

wget https://raw.githubusercontent.com/paulmann/cert-unifier/main/cert-unifier.sh
chmod +x cert-unifier.sh

Step 2: Basic Unification

./cert-unifier.sh /var/www/httpd-cert

Step 3: Advanced PFX Generation

./cert-unifier.sh --pfx --pfx-password "your_password" /etc/letsencrypt/live

5. Installation & Setup#

5.1 Manual Installation#

Move the script to a system PATH directory (e.g., /usr/local/bin)
Ensure dependencies are satisfied: apt install openssl grep awk
Configure environment variables if needed:
- ALLOWEDTLDS="ru com org"
- LOGLEVEL="INFO"

5.2 Automated CI/CD Setup#

In corporate environments, integrate via GitLab CI or GitHub Actions:

- name: Unify Certificates
  run: |
    export ALLOWEDTLDS="com net"
    ./cert-unifier.sh --no-key-validation --output-dir ./dist /certs/source

6. Architecture & Components#

6.1 Logic Flow#

Environment Check: Validates OpenSSL version and dependencies
Directory Scanning: Iterates through target root, identifying layouts
Validation: Extracts moduli; compares key-cert pairs
Assembly: Concat(key, chain) -> atomic write to .pem
PFX Generation (Optional): Converts PEM bundle to PKCS#12

7. Usage Examples#

# Dry run with verbose debugging
./cert-unifier.sh --dry-run --verbose /etc/letsencrypt/live

# Process all domains (no TLD filtering)
./cert-unifier.sh --no-tld-filter /var/www/certs

# Generate PFX files and skip mismatches
./cert-unifier.sh --pfx --skip-pfx-on-mismatch /opt/certs

# Override output directory
./cert-unifier.sh -o /tmp/unified_certs /var/www/certs

8. Parameters Reference#

Option	Description	Default
`-d, --dry-run`	Validate without writing files	`false`
`-v, --verbose`	Enable DEBUG level logging	`false`
`-t, --tlds`	List of allowed TLDs	`ru com`
`-o, --output-dir`	Override output path	Input dir
`--no-tld-filter`	Process all domains	`false`
`--pfx`	Generate PKCS12 files	`false`
`--pfx-password`	Set PFX password	Empty

9. Technical Considerations#

9.1 OpenSSL Integration#

The script detects OpenSSL version capabilities at runtime. PFX friendlyname support is automatically enabled for OpenSSL 1.1.x and 3.x, ensuring better UI integration in Windows Certificate Manager.

9.2 Atomic Write Mechanism#

To prevent race conditions where a web server might read a partially written certificate, Cert Unifier writes to *.pem.new and performs an atomic move/rename upon successful validation.

10. License & Acknowledgments#

10.1 License#

Distributed under the PolyForm Noncommercial License 1.0.0. See LICENSE for details.

10.2 Copyright#

Email: mid1977@gmail.com
GitHub: paulmann
Web: deynekin.com