Update README.md

2025-07-21 22:23:17 +07:00
parent d5da23849f
commit 4cce5754d3
1 changed files with 131 additions and 42 deletions
@@ -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