Update From Dev To Main #1
@@ -1,69 +1,239 @@
|
||||
## OpenSSL Command Reference for Self-Signed Certificate Generation
|
||||
# OpenSSL Command Reference for Self-Signed Certificate Generation
|
||||
|
||||
This document provides an overview of the `openssl` command-line tool and details the steps for generating a self-signed SSL/TLS certificate using specific commands.
|
||||
This document explains the OpenSSL command-line tool and provides a structured, DevOps-friendly guide for generating self-signed SSL/TLS certificates. These certificates are commonly used for internal services, development environments, testing, or private infrastructure components such as Gitea, Jenkins, internal APIs, or Kubernetes ingress controllers.
|
||||
|
||||
---
|
||||
|
||||
### What is OpenSSL?
|
||||
## 1. What is OpenSSL?
|
||||
|
||||
**OpenSSL** is a powerful, open-source command-line toolkit implementing the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols. It is widely used for generating private keys, creating Certificate Signing Requests (CSRs), managing certificates, and performing cryptographic operations.
|
||||
**OpenSSL** is a widely used, open-source cryptographic toolkit that implements the SSL and TLS protocols. It provides utilities for:
|
||||
|
||||
* Generating private and public key pairs
|
||||
* Creating Certificate Signing Requests (CSRs)
|
||||
* Issuing and managing X.509 certificates
|
||||
* Encrypting and decrypting data
|
||||
* Inspecting and troubleshooting TLS connections
|
||||
|
||||
OpenSSL is available on most Linux distributions by default and is commonly used in DevOps and SRE workflows.
|
||||
|
||||
Check installed version:
|
||||
|
||||
```bash
|
||||
openssl version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Generating a Self-Signed Certificate (Example: For Gitea)
|
||||
## 2. When to Use Self-Signed Certificates
|
||||
|
||||
The following sequence generates a private key, creates a CSR, and then uses the key and CSR to sign and create a self-signed certificate.
|
||||
Self-signed certificates are suitable for:
|
||||
|
||||
#### Step 1: Generate a Private Key
|
||||
* Internal services
|
||||
* Development and staging environments
|
||||
* Private networks
|
||||
* Lab and proof-of-concept setups
|
||||
|
||||
This command creates an RSA private key of 2048 bits and saves it to a file named `gitea.key`.
|
||||
They are **not recommended for public-facing production systems**, because they are not trusted by browsers or external clients without manual trust configuration.
|
||||
|
||||
---
|
||||
|
||||
## 3. Generating a Self-Signed Certificate (Example: Gitea)
|
||||
|
||||
This process consists of three logical steps:
|
||||
|
||||
1. Generate a private key
|
||||
2. Create a Certificate Signing Request (CSR)
|
||||
3. Sign the CSR using the same key to produce a self-signed certificate
|
||||
|
||||
---
|
||||
|
||||
## 4. Step 1: Generate a Private Key
|
||||
|
||||
Generate a 2048-bit RSA private key:
|
||||
|
||||
```bash
|
||||
openssl genrsa -out gitea.key 2048
|
||||
```
|
||||
|
||||
| Component | Description |
|
||||
| :--- | :--- |
|
||||
| `genrsa` | Subcommand to generate an RSA private key. |
|
||||
| `-out gitea.key` | Specifies the output file for the private key. |
|
||||
| `2048` | Defines the key length in bits (2048 is a common standard). |
|
||||
### Explanation
|
||||
|
||||
#### Step 2: Create a Certificate Signing Request (CSR)
|
||||
| Component | Description |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `genrsa` | Generates an RSA private key |
|
||||
| `-out gitea.key` | Output file for the private key |
|
||||
| `2048` | Key size in bits (2048 is the recommended minimum) |
|
||||
|
||||
This command uses the generated private key (`gitea.key`) to create a Certificate Signing Request (`gitea.csr`). The CSR contains your public key and identity information (like Common Name, Organization) that a Certificate Authority (CA) would normally use to issue a trusted certificate.
|
||||
Security note:
|
||||
|
||||
* The private key must be kept secret
|
||||
* Restrict file permissions:
|
||||
|
||||
```bash
|
||||
chmod 600 gitea.key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Step 2: Create a Certificate Signing Request (CSR)
|
||||
|
||||
Generate a CSR using the private key:
|
||||
|
||||
```bash
|
||||
openssl req -new -key gitea.key -out gitea.csr
|
||||
```
|
||||
|
||||
| Component | Description |
|
||||
| :--- | :--- |
|
||||
| `req` | Subcommand used for CSR management and certificate requests. |
|
||||
| `-new` | Indicates that a new CSR is being created. |
|
||||
| `-key gitea.key` | Specifies the private key to be associated with this request. |
|
||||
| `-out gitea.csr` | Specifies the output file for the CSR. |
|
||||
| *Interactive Prompt* | OpenSSL will prompt you to enter certificate details (Country Name, Common Name, etc.). **The Common Name (CN) should usually match the domain name** where the service (e.g., Gitea) will be hosted. |
|
||||
### Explanation
|
||||
|
||||
#### Step 3: Create the Self-Signed Certificate
|
||||
| Component | Description |
|
||||
| ---------------- | ---------------------------------------- |
|
||||
| `req` | Certificate request management command |
|
||||
| `-new` | Creates a new CSR |
|
||||
| `-key gitea.key` | Private key used to generate the request |
|
||||
| `-out gitea.csr` | Output file for the CSR |
|
||||
|
||||
This command takes the CSR and the private key and signs the request with the key itself, creating a certificate (`gitea.crt`) that is valid immediately but *not* trusted by default by web browsers or clients (since it's not signed by a recognized CA).
|
||||
### Interactive Fields
|
||||
|
||||
During execution, OpenSSL prompts for certificate metadata:
|
||||
|
||||
* Country Name (C)
|
||||
* State or Province (ST)
|
||||
* Locality (L)
|
||||
* Organization (O)
|
||||
* Organizational Unit (OU)
|
||||
* **Common Name (CN)**
|
||||
|
||||
Important:
|
||||
|
||||
* The **Common Name (CN)** should match the service hostname or domain name
|
||||
Example:
|
||||
|
||||
```
|
||||
gitea.example.com
|
||||
```
|
||||
|
||||
For automation or CI/CD pipelines, this step can be made non-interactive (see section 8).
|
||||
|
||||
---
|
||||
|
||||
## 6. Step 3: Create the Self-Signed Certificate
|
||||
|
||||
Sign the CSR using the same private key:
|
||||
|
||||
```bash
|
||||
openssl x509 -req -in gitea.csr -signkey gitea.key -out gitea.crt
|
||||
```
|
||||
|
||||
| Component | Description |
|
||||
| :--- | :--- |
|
||||
| `x509` | Subcommand used for X.509 certificate management (like viewing, signing, testing). |
|
||||
| `-req` | Specifies that the input file is a CSR. |
|
||||
| `-in gitea.csr` | Specifies the input CSR file. |
|
||||
| `-signkey gitea.key` | Uses the private key to sign the certificate request, making it self-signed. |
|
||||
| `-out gitea.crt` | Specifies the output file for the final certificate. |
|
||||
### Explanation
|
||||
|
||||
| Component | Description |
|
||||
| -------------------- | ------------------------------------------ |
|
||||
| `x509` | X.509 certificate management |
|
||||
| `-req` | Indicates the input is a CSR |
|
||||
| `-in gitea.csr` | Input CSR file |
|
||||
| `-signkey gitea.key` | Signs the certificate with the private key |
|
||||
| `-out gitea.crt` | Output certificate file |
|
||||
|
||||
Default behavior:
|
||||
|
||||
* Certificate is valid immediately
|
||||
* Validity is typically 30 days unless specified
|
||||
|
||||
To set validity explicitly (example: 365 days):
|
||||
|
||||
```bash
|
||||
openssl x509 -req -days 365 -in gitea.csr -signkey gitea.key -out gitea.crt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Summary of Generated Files
|
||||
## 7. Verify the Certificate
|
||||
|
||||
1. **`gitea.key`**: The **Private Key**. Must be kept secret and secure. Used by the server (e.g., Gitea) to decrypt incoming traffic.
|
||||
2. **`gitea.csr`**: The **Certificate Signing Request**. Contains identifying information and the public key. (Not strictly needed after Step 3).
|
||||
3. **`gitea.crt`**: The **Self-Signed Certificate**. Contains the public key and identity details, signed by your private key. This is what the server presents to clients.
|
||||
Inspect certificate details:
|
||||
|
||||
```bash
|
||||
openssl x509 -in gitea.crt -text -noout
|
||||
```
|
||||
|
||||
Verify key and certificate match:
|
||||
|
||||
```bash
|
||||
openssl rsa -noout -modulus -in gitea.key | openssl md5
|
||||
openssl x509 -noout -modulus -in gitea.crt | openssl md5
|
||||
```
|
||||
|
||||
Matching hashes confirm correctness.
|
||||
|
||||
---
|
||||
|
||||
## 8. Non-Interactive Certificate Generation (Recommended for Automation)
|
||||
|
||||
Generate key and certificate in one command:
|
||||
|
||||
```bash
|
||||
openssl req -x509 -newkey rsa:2048 \
|
||||
-keyout gitea.key \
|
||||
-out gitea.crt \
|
||||
-days 365 \
|
||||
-nodes \
|
||||
-subj "/C=US/ST=State/L=City/O=Company/OU=DevOps/CN=gitea.example.com"
|
||||
```
|
||||
|
||||
Options explained:
|
||||
|
||||
* `-x509`: Generate a self-signed certificate
|
||||
* `-newkey`: Create a new private key
|
||||
* `-nodes`: Do not encrypt the private key (required for services)
|
||||
* `-subj`: Certificate subject (non-interactive)
|
||||
|
||||
This approach is ideal for:
|
||||
|
||||
* CI/CD pipelines
|
||||
* Docker images
|
||||
* Infrastructure as Code workflows
|
||||
|
||||
---
|
||||
|
||||
## 9. Subject Alternative Name (SAN) Consideration
|
||||
|
||||
Modern TLS clients require **SAN** instead of CN.
|
||||
|
||||
Example OpenSSL config snippet:
|
||||
|
||||
```
|
||||
subjectAltName = DNS:gitea.example.com,DNS:gitea.internal
|
||||
```
|
||||
|
||||
Without SAN:
|
||||
|
||||
* Browsers may reject the certificate
|
||||
* TLS warnings may appear even if CN matches
|
||||
|
||||
---
|
||||
|
||||
## 10. Summary of Generated Files
|
||||
|
||||
| File | Description |
|
||||
| ----------- | ---------------------------------------------------- |
|
||||
| `gitea.key` | Private key (keep secure, server-side only) |
|
||||
| `gitea.csr` | Certificate Signing Request (optional after signing) |
|
||||
| `gitea.crt` | Self-signed certificate presented to clients |
|
||||
|
||||
---
|
||||
|
||||
## 11. Best Practices
|
||||
|
||||
* Never commit private keys to Git
|
||||
* Store secrets securely (Vault, SSM, Kubernetes secrets)
|
||||
* Rotate certificates regularly
|
||||
* Use Let’s Encrypt or internal CA for production
|
||||
* Prefer SAN over CN
|
||||
* Automate certificate generation where possible
|
||||
|
||||
---
|
||||
|
||||
If you want, I can:
|
||||
|
||||
* Add an OpenSSL SAN configuration example
|
||||
* Provide Kubernetes, Nginx, or Gitea-specific TLS configs
|
||||
* Convert this into a reusable internal PKI guide
|
||||
* Add troubleshooting and common TLS errors
|
||||
|
||||
Reference in New Issue
Block a user