Update README.md
Build / Build (push) Successful in 14s
Build / Build-And-Push-Docker-Image (push) Successful in 20s

This commit is contained in:
wt committed 2025-07-25 18:51:04 +07:00
1 parent f05ebf2ae7
commit af76bd57ba
1 file changed
+116 -39
+116 -39
View File
@@ -5,55 +5,72 @@ A Go-based SSL Certificate Manager that provides a REST API for managing SSL cer
## Features ## Features
- **Root CA Management**: Create and manage root Certificate Authority certificates - **Root CA Management**: Create and manage root Certificate Authority certificates
- **Certificate Management**: Create, list, and delete SSL certificates - **Certificate Management**: Create, list, delete, and download SSL certificates
- **CA Integration**: Uses a root Certificate Authority to sign certificates - **CA Integration**: Uses a root Certificate Authority to sign certificates
- **REST API**: Simple HTTP endpoints for certificate operations - **REST API**: Simple HTTP endpoints for certificate operations
- **Web Interface**: Frontend for certificate management operations - **Web Interface**: Frontend for certificate management operations
- **Certificate Download**: Download certificates and keys as ZIP archives
- **TLS Support**: Configurable HTTPS server with certificate validation - **TLS Support**: Configurable HTTPS server with certificate validation
- **Certificate Parsing**: Detailed certificate information extraction - **Certificate Parsing**: Detailed certificate information extraction
- **File System Storage**: Organized certificate storage in directories - **File System Storage**: Organized certificate storage in directories
- **Docker Support**: Container deployment with Docker Compose
## Project Structure ## Project Structure
``` ```
scm/ scm/
├── api/ # HTTP handlers and API endpoints ├── api/ # HTTP handlers and API endpoints
│ ├── Certs.go # List certificates endpoint │ ├── CertDownload.go # Certificate download endpoint
│ ├── Certs.go # Certificate operations router
│ ├── CreateCert.go # Create certificate endpoint │ ├── CreateCert.go # Create certificate endpoint
│ ├── DeleteCert.go # Delete certificate endpoint │ ├── DeleteCert.go # Delete certificate endpoint
│ ├── GetCerts.go # List certificates endpoint
│ ├── RootCert.go # Root certificate management endpoint │ ├── RootCert.go # Root certificate management endpoint
│ ├── Spa.go # Single-page application handler │ ├── Spa.go # Single-page application handler
│ └── frontend/ # Frontend assets │ └── frontend/ # Frontend assets
│ ├── css/ # Stylesheets │ ├── css/ # Stylesheets
│ ├── js/ # JavaScript files │ ├── js/ # JavaScript files
│ └── index.html # Main web interface │ └── index.html # Main web interface
├── certs/ # Certificate storage directory
├── crt/ # Certificate operations and utilities ├── crt/ # Certificate operations and utilities
│ ├── CreateRootKeyCertificate.go # Root CA creation │ ├── CreateRootKeyCertificate.go # Root CA creation
│ ├── CreateServerCert.go # Server certificate creation │ ├── CreateServerCert.go # Server certificate creation
│ ├── LoadRootCertAndKey.go # CA certificate loading │ ├── LoadRootCertAndKey.go # CA certificate loading
│ ├── ParseCert.go # Certificate parsing utilities │ ├── ParseCert.go # Certificate parsing utilities
│ └── SavePEMFile.go # PEM file operations │ └── SavePEMFile.go # PEM file operations
├── data/ # Data storage directory
├── model/ # Data structures and models ├── model/ # Data structures and models
│ ├── CreateCertRequest.go # Server certificate request model │ ├── CreateCertRequest.go # Server certificate request model
│ ├── CreateRootCertRequest.go # Root certificate request model │ ├── CreateRootCertRequest.go # Root certificate request model
│ └── DeleteCertRequest.go # Certificate deletion model │ └── DeleteCertRequest.go # Certificate deletion model
├── server/ # Server configuration and setup ├── server/ # Server configuration and setup
│ ├── Configure.go # Route configuration
│ └── Run.go # Server startup
├── utils/ # General utility functions ├── utils/ # General utility functions
│ ├── CheckExistsOrCreateDir.go # Directory operations │ ├── AddFileToZipWithName.go # ZIP file utilities
│ ├── CheckExistsOrCreateDir.go # Directory operations
│ ├── CreateDomainZip.go # Certificate ZIP creation
│ └── LoadEnv.go # Environment loading │ └── LoadEnv.go # Environment loading
├── main.go # Application entry point ├── main.go # Application entry point
├── go.mod # Go module definition ├── go.mod # Go module definition
├── go.sum # Go module checksums ├── go.sum # Go module checksums
└── scm.conf # Configuration file ├── scm.conf # Configuration file
├── scm.conf.docker # Docker configuration file
├── Dockerfile # Docker build configuration
├── docker-compose.yml # Docker Compose setup
└── scm.sh # Shell script for operations
``` ```
## Requirements ## Requirements
- Go 1.24.5 or higher - Go 1.24.5 or higher
- Linux/Unix environment (recommended) - Linux/Unix environment (recommended)
- Docker (optional, for container deployment)
## Installation ## Installation
### From Source
1. Clone the repository: 1. Clone the repository:
```bash ```bash
git clone <repository-url> git clone <repository-url>
@@ -70,6 +87,19 @@ go mod tidy
go build -o scm go build -o scm
``` ```
### Docker Deployment
1. Using Docker Compose:
```bash
docker-compose up -d
```
2. Using Docker directly:
```bash
docker build -t scm .
docker run -d -p 8777:8777 -v ./certs:/certs scm
```
## Configuration ## Configuration
Create a configuration file `scm.conf` in the project root: Create a configuration file `scm.conf` in the project root:
@@ -160,7 +190,7 @@ List all managed certificates with details.
] ]
``` ```
### POST /api/certs/create ### POST /api/certs
Create a new SSL certificate signed by the root CA. Create a new SSL certificate signed by the root CA.
**Request Body:** **Request Body:**
@@ -182,7 +212,7 @@ Create a new SSL certificate signed by the root CA.
} }
``` ```
### POST /api/certs/delete ### DELETE /api/certs
Delete an existing certificate. Delete an existing certificate.
**Request Body:** **Request Body:**
@@ -192,6 +222,15 @@ Delete an existing certificate.
} }
``` ```
### GET /api/certs/download/?domain=example.com
Download certificate and private key as a ZIP archive.
**Query Parameters:**
- `domain` (required): Domain name of the certificate to download
**Response:**
- ZIP file containing `domain.crt` and `domain.key`
### GET / ### GET /
Access the web interface for certificate management. Access the web interface for certificate management.
@@ -211,7 +250,7 @@ Access the web interface for certificate management.
Before creating server certificates, you need to create a root CA: Before creating server certificates, you need to create a root CA:
```bash ```bash
curl -X POST http://localhost:8777/api/rootcert \ curl -X POST http://localhost:8777/api/certs/root \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"CommonName": "My Root CA", "CommonName": "My Root CA",
@@ -227,7 +266,7 @@ curl -X POST http://localhost:8777/api/rootcert \
1. Create a certificate: 1. Create a certificate:
```bash ```bash
curl -X POST http://localhost:8777/api/certs/create \ curl -X POST http://localhost:8777/api/certs \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{ -d '{
"commonname": "example.com", "commonname": "example.com",
@@ -243,9 +282,14 @@ curl -X POST http://localhost:8777/api/certs/create \
curl http://localhost:8777/api/certs curl http://localhost:8777/api/certs
``` ```
3. Delete a certificate: 3. Download a certificate:
```bash ```bash
curl -X POST http://localhost:8777/api/certs/delete \ curl -O "http://localhost:8777/api/certs/download/?domain=example.com"
```
4. Delete a certificate:
```bash
curl -X DELETE http://localhost:8777/api/certs \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
-d '{"domain": "example.com"}' -d '{"domain": "example.com"}'
``` ```
@@ -282,6 +326,35 @@ go test ./...
go test -v ./... go test -v ./...
``` ```
## Docker Deployment
### Using Docker Compose
```yaml
version: '3.8'
services:
scm:
build: .
ports:
- "8777:8777"
volumes:
- ./certs:/certs
- ./data:/data
environment:
- CERTS_PATH=/certs
```
### Environment Variables for Docker
The Docker configuration uses `scm.conf.docker` which should contain:
```bash
ENABLE_TLS=false
CERTS_PATH=/certs
SERVER_ADDRESS=0.0.0.0
SERVER_PORT=8777
```
## Security Considerations ## Security Considerations
- **Root CA Security**: Store CA private keys securely and use strong passwords - **Root CA Security**: Store CA private keys securely and use strong passwords
@@ -291,6 +364,7 @@ go test -v ./...
- **Input Validation**: Validate input data to prevent injection attacks - **Input Validation**: Validate input data to prevent injection attacks
- **Monitoring**: Monitor certificate expiration dates - **Monitoring**: Monitor certificate expiration dates
- **Password Strength**: Use strong passwords for CA key encryption - **Password Strength**: Use strong passwords for CA key encryption
- **File Permissions**: Ensure proper file system permissions for certificate directories
## File Organization ## File Organization
@@ -311,35 +385,11 @@ CERTS_PATH/
## Workflow ## Workflow
1. **Initial Setup**: Configure the application and create certificates directory 1. **Initial Setup**: Configure the application and create certificates directory
2. **Create Root CA**: Use `/api/rootcert` endpoint to create a root Certificate Authority 2. **Create Root CA**: Use `/api/certs/root` endpoint to create a root Certificate Authority
3. **Create Server Certificates**: Use `/api/certs/create` to generate server certificates signed by the CA 3. **Create Server Certificates**: Use `/api/certs` POST to generate server certificates signed by the CA
4. **Manage Certificates**: List, view, and delete certificates as needed 4. **Manage Certificates**: List, view, download, and delete certificates as needed
5. **Deploy Certificates**: Use the generated certificates in your applications 5. **Deploy Certificates**: Use the generated certificates in your applications
## Troubleshooting
### Common Issues
1. **"Certificate not found"** - Ensure the CERTS_PATH is correctly configured and accessible
2. **"Invalid CA password"** - Verify the CA private key password is correct
3. **"Permission denied"** - Check file system permissions for certificate directories
4. **"Port already in use"** - Change the SERVER_PORT in configuration
5. **"Root certificate not found"** - Create a root CA first using the `/api/rootcert` endpoint
### Debugging Tips
- Check application logs for detailed error messages
- Verify certificate directory permissions
- Ensure the configuration file is properly formatted
- Test API endpoints individually to isolate issues
### Logs
The application logs to stdout. For production, consider redirecting logs to a file:
```bash
./scm >> /var/log/scm.log 2>&1
```
## Web Interface ## Web Interface
The application includes a web-based interface accessible at the root URL. The interface provides: The application includes a web-based interface accessible at the root URL. The interface provides:
@@ -348,8 +398,35 @@ The application includes a web-based interface accessible at the root URL. The i
- Certificate creation with form validation - Certificate creation with form validation
- Certificate listing and viewing - Certificate listing and viewing
- Certificate deletion - Certificate deletion
- Certificate download functionality
- Real-time status updates - Real-time status updates
## Troubleshooting
### Common Issues
1. **"Certificate not found"** - Ensure the CERTS_PATH is correctly configured and accessible
2. **"Invalid CA password"** - Verify the CA private key password is correct
3. **"Permission denied"** - Check file system permissions for certificate directories
4. **"Port already in use"** - Change the SERVER_PORT in configuration
5. **"Root certificate not found"** - Create a root CA first using the `/api/certs/root` endpoint
6. **"domain parameter is required"** - Ensure the domain parameter is provided for download requests
### Debugging Tips
- Check application logs for detailed error messages
- Verify certificate directory permissions
- Ensure the configuration file is properly formatted
- Test API endpoints individually to isolate issues
- Use the web interface for easier debugging
### Logs
The application logs to stdout. For production, consider redirecting logs to a file:
```bash
./scm >> /var/log/scm.log 2>&1
```
## Contributing ## Contributing
1. Fork the repository 1. Fork the repository
@@ -365,5 +442,5 @@ This project is licensed under the MIT License. See LICENSE file for details.
## Version History ## Version History
- **Latest**: Added root certificate management, web interface, and improved project structure - **v1.0.0**: Full-featured SSL Certificate Manager with web interface, REST API, and certificate download functionality
- **Previous**: Basic certificate management with REST API - **Previous**: Basic certificate management with REST API