From 4cce5754d302afab74dc097bbb3977712e194dd8 Mon Sep 17 00:00:00 2001 From: TolaMironcenko Date: Mon, 21 Jul 2025 22:23:17 +0700 Subject: [PATCH] Update README.md --- README.md | 173 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 131 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index e9d2ba3..2465f47 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ # SCM - SSL Certificate Manager -A Go-based SSL Certificate Manager that provides a REST API for managing SSL certificates. The system allows you to create, view, and delete SSL certificates signed by a Certificate Authority (CA). +A Go-based SSL Certificate Manager that provides a REST API for managing SSL certificates and Certificate Authority (CA) operations. The system allows you to create root certificates, manage SSL certificates, and perform certificate operations through a web interface. ## Features +- **Root CA Management**: Create and manage root Certificate Authority certificates - **Certificate Management**: Create, list, and delete SSL certificates - **CA Integration**: Uses a root Certificate Authority to sign certificates - **REST API**: Simple HTTP endpoints for certificate operations +- **Web Interface**: Frontend for certificate management operations - **TLS Support**: Configurable HTTPS server with certificate validation - **Certificate Parsing**: Detailed certificate information extraction - **File System Storage**: Organized certificate storage in directories @@ -19,28 +21,35 @@ scm/ │ ├── Certs.go # List certificates endpoint │ ├── CreateCert.go # Create certificate endpoint │ ├── DeleteCert.go # Delete certificate endpoint +│ ├── RootCert.go # Root certificate management endpoint │ ├── Spa.go # Single-page application handler │ └── frontend/ # Frontend assets +│ ├── css/ # Stylesheets +│ ├── js/ # JavaScript files +│ └── index.html # Main web interface +├── crt/ # Certificate operations and utilities +│ ├── CreateRootKeyCertificate.go # Root CA creation +│ ├── CreateServerCert.go # Server certificate creation +│ ├── LoadRootCertAndKey.go # CA certificate loading +│ ├── ParseCert.go # Certificate parsing utilities +│ └── SavePEMFile.go # PEM file operations ├── model/ # Data structures and models -│ ├── CreateCertRequest.go -│ └── DeleteCertRequest.go +│ ├── CreateCertRequest.go # Server certificate request model +│ ├── CreateRootCertRequest.go # Root certificate request model +│ └── DeleteCertRequest.go # Certificate deletion model ├── server/ # Server configuration and setup -├── utils/ # Utility functions -│ ├── CheckExistsOrCreateDir.go -│ ├── CreateServerCert.go -│ ├── LoadEnv.go -│ ├── LoadRootCertAndKey.go -│ ├── ParseCert.go -│ └── SavePEMFile.go +├── utils/ # General utility functions +│ ├── CheckExistsOrCreateDir.go # Directory operations +│ └── LoadEnv.go # Environment loading ├── main.go # Application entry point ├── go.mod # Go module definition +├── go.sum # Go module checksums └── scm.conf # Configuration file ``` ## Requirements - Go 1.24.5 or higher -- Root Certificate Authority (CA) certificate and private key - Linux/Unix environment (recommended) ## Installation @@ -90,23 +99,44 @@ SERVER_PORT=8777 | `SERVER_ADDRESS` | Server bind address | `0.0.0.0` | No | | `SERVER_PORT` | Server port | `8080` | No | -## Certificate Authority Setup - -Before using the certificate manager, you need to set up a root CA: - -1. Create a root CA directory: -```bash -mkdir -p /path/to/certificates/root -``` - -2. Place your root CA certificate and private key: -```bash -# Certificate: /path/to/certificates/root/root.crt -# Private Key: /path/to/certificates/root/root.key -``` - ## API Endpoints +### GET /api/certs/root +Check if root certificate exists. + +**Response:** +```json +{ + "status": "ok" +} +``` + +### POST /api/certs/root +Create a new root Certificate Authority certificate. + +**Request Body:** +```json +{ + "CommonName": "My Root CA", + "Organization": ["My Organization"], + "OrganizationalUnit": ["IT Department"], + "Country": ["US"], + "Locality": ["City"], + "Province": ["State"], + "StreetAddress": ["123 Main St"], + "PostalCode": ["12345"], + "ValidityYears": 10, + "KeyPassword": "secure-password" +} +``` + +**Response:** +```json +{ + "status": "ok" +} +``` + ### GET /api/certs List all managed certificates with details. @@ -131,7 +161,7 @@ List all managed certificates with details. ``` ### POST /api/certs/create -Create a new SSL certificate. +Create a new SSL certificate signed by the root CA. **Request Body:** ```json @@ -162,14 +192,40 @@ Delete an existing certificate. } ``` +### GET / +Access the web interface for certificate management. + ## Usage +### Starting the Server + 1. Start the server: ```bash ./scm ``` -2. Create a certificate: +2. Access the web interface at `http://localhost:8777` (or your configured address/port) + +### Creating Root Certificate Authority + +Before creating server certificates, you need to create a root CA: + +```bash +curl -X POST http://localhost:8777/api/rootcert \ + -H "Content-Type: application/json" \ + -d '{ + "CommonName": "My Root CA", + "Organization": ["My Company"], + "OrganizationalUnit": ["IT"], + "Country": ["US"], + "ValidityYears": 10, + "KeyPassword": "secure-ca-password" + }' +``` + +### Managing Server Certificates + +1. Create a certificate: ```bash curl -X POST http://localhost:8777/api/certs/create \ -H "Content-Type: application/json" \ @@ -182,12 +238,12 @@ curl -X POST http://localhost:8777/api/certs/create \ }' ``` -3. List certificates: +2. List certificates: ```bash curl http://localhost:8777/api/certs ``` -4. Delete a certificate: +3. Delete a certificate: ```bash curl -X POST http://localhost:8777/api/certs/delete \ -H "Content-Type: application/json" \ @@ -198,9 +254,9 @@ curl -X POST http://localhost:8777/api/certs/delete \ ### Dependencies -- `github.com/google/uuid` - UUID generation +- `github.com/google/uuid` - UUID generation for certificates - `github.com/joho/godotenv` - Environment variable loading -- `github.com/youmark/pkcs8` - PKCS#8 key handling +- `github.com/youmark/pkcs8` - PKCS#8 key handling and encryption - `golang.org/x/crypto` - Cryptographic operations ### Running in Development @@ -228,12 +284,13 @@ go test -v ./... ## Security Considerations -- Store CA private keys securely and use strong passwords -- Implement proper access controls for the API endpoints -- Use HTTPS in production environments -- Regularly rotate certificates and CA keys -- Validate input data to prevent injection attacks -- Monitor certificate expiration dates +- **Root CA Security**: Store CA private keys securely and use strong passwords +- **Access Control**: Implement proper access controls for API endpoints +- **HTTPS**: Use HTTPS in production environments +- **Key Rotation**: Regularly rotate certificates and CA keys +- **Input Validation**: Validate input data to prevent injection attacks +- **Monitoring**: Monitor certificate expiration dates +- **Password Strength**: Use strong passwords for CA key encryption ## File Organization @@ -242,7 +299,7 @@ Certificates are stored in the following structure: CERTS_PATH/ ├── root/ │ ├── root.crt # Root CA certificate -│ └── root.key # Root CA private key +│ └── root.key # Root CA private key (encrypted) ├── example.com/ │ ├── example.com.crt # Domain certificate │ └── example.com.key # Domain private key @@ -251,14 +308,30 @@ CERTS_PATH/ └── another-domain.com.key ``` +## Workflow + +1. **Initial Setup**: Configure the application and create certificates directory +2. **Create Root CA**: Use `/api/rootcert` endpoint to create a root Certificate Authority +3. **Create Server Certificates**: Use `/api/certs/create` to generate server certificates signed by the CA +4. **Manage Certificates**: List, view, and delete certificates as needed +5. **Deploy Certificates**: Use the generated certificates in your applications + ## Troubleshooting ### Common Issues -1. **"Certificate not found"** - Ensure the CERTS_PATH is correctly configured -2. **"Invalid CA password"** - Verify the CA private key password +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 @@ -267,14 +340,30 @@ The application logs to stdout. For production, consider redirecting logs to a f ./scm >> /var/log/scm.log 2>&1 ``` +## Web Interface + +The application includes a web-based interface accessible at the root URL. The interface provides: + +- Root CA creation and management +- Certificate creation with form validation +- Certificate listing and viewing +- Certificate deletion +- Real-time status updates + ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests for new functionality -5. Submit a pull request +5. Ensure code follows Go best practices +6. Submit a pull request ## License This project is licensed under the MIT License. See LICENSE file for details. + +## Version History + +- **Latest**: Added root certificate management, web interface, and improved project structure +- **Previous**: Basic certificate management with REST API