scm/README.md

# SCM - SSL Certificate Manager

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, delete, and download 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
- **Certificate Download**: Download certificates and keys as ZIP archives
- **TLS Support**: Configurable HTTPS server with certificate validation
- **Certificate Parsing**: Detailed certificate information extraction
- **File System Storage**: Organized certificate storage in directories
- **Docker Support**: Container deployment with Docker Compose

## Project Structure

```
scm/
├── api/                    # HTTP handlers and API endpoints
│   ├── CertDownload.go    # Certificate download endpoint
│   ├── Certs.go           # Certificate operations router
│   ├── CreateCert.go      # Create certificate endpoint
│   ├── DeleteCert.go      # Delete certificate endpoint
│   ├── GetCerts.go        # List certificates 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
├── certs/                 # Certificate storage directory
├── 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
├── data/                  # Data storage directory
├── model/                 # Data structures and models
│   ├── CreateCertRequest.go         # Server certificate request model
│   ├── CreateRootCertRequest.go     # Root certificate request model
│   └── DeleteCertRequest.go         # Certificate deletion model
├── server/                # Server configuration and setup
│   ├── Configure.go       # Route configuration
│   └── Run.go            # Server startup
├── utils/                 # General utility functions
│   ├── AddFileToZipWithName.go     # ZIP file utilities
│   ├── CheckExistsOrCreateDir.go   # Directory operations
│   ├── CreateDomainZip.go          # Certificate ZIP creation
│   └── LoadEnv.go                   # Environment loading
├── main.go               # Application entry point
├── go.mod               # Go module definition
├── go.sum               # Go module checksums
├── 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

- Go 1.24.5 or higher
- Linux/Unix environment (recommended)
- Docker (optional, for container deployment)

## Installation

### From Source

1. Clone the repository:
```bash
git clone <repository-url>
cd scm
```

2. Install dependencies:
```bash
go mod tidy
```

3. Build the application:
```bash
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

Create a configuration file `scm.conf` in the project root:

```bash
# TLS Configuration
ENABLE_TLS=true
CERT_FILE=/path/to/server/certificate.crt
KEY_FILE=/path/to/server/private.key

# Certificate Storage
CERTS_PATH=/path/to/certificates/directory

# Server Configuration
SERVER_ADDRESS=0.0.0.0
SERVER_PORT=8777
```

### Configuration Parameters

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `ENABLE_TLS` | Enable HTTPS server | `false` | No |
| `CERT_FILE` | Path to server certificate | - | If TLS enabled |
| `KEY_FILE` | Path to server private key | - | If TLS enabled |
| `CERTS_PATH` | Directory for certificate storage | - | Yes |
| `SERVER_ADDRESS` | Server bind address | `0.0.0.0` | No |
| `SERVER_PORT` | Server port | `8080` | No |

## 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.

**Response:**
```json
[
  {
    "id": "uuid-string",
    "domain": "example.com",
    "href": "https://example.com",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN PRIVATE KEY-----...",
    "certinfo": {
      "issuer": "CA Name",
      "subject": "CN=example.com",
      "notBefore": "2024-01-01T00:00:00Z",
      "notAfter": "2025-01-01T00:00:00Z",
      "serialNumber": "123456"
    }
  }
]
```

### POST /api/certs
Create a new SSL certificate signed by the root CA.

**Request Body:**
```json
{
  "commonname": "example.com",
  "organizationname": ["Your Organization"],
  "organizationunit": ["IT Department"],
  "dns": ["example.com", "www.example.com"],
  "password": "ca-private-key-password"
}
```

**Response:**
```json
{
  "status": "success",
  "message": "Certificate created successfully"
}
```

### DELETE /api/certs
Delete an existing certificate.

**Request Body:**
```json
{
  "domain": "example.com"
}
```

### 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 /
Access the web interface for certificate management.

## Usage

### Starting the Server

1. Start the server:
```bash
./scm
```

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/certs/root \
  -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 \
  -H "Content-Type: application/json" \
  -d '{
    "commonname": "example.com",
    "organizationname": ["My Company"],
    "organizationunit": ["IT"],
    "dns": ["example.com", "www.example.com"],
    "password": "your-ca-key-password"
  }'
```

2. List certificates:
```bash
curl http://localhost:8777/api/certs
```

3. Download a certificate:
```bash
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" \
  -d '{"domain": "example.com"}'
```

## Development

### Dependencies

- `github.com/google/uuid` - UUID generation for certificates
- `github.com/joho/godotenv` - Environment variable loading
- `github.com/youmark/pkcs8` - PKCS#8 key handling and encryption
- `golang.org/x/crypto` - Cryptographic operations

### Running in Development

```bash
# Install dependencies
go mod tidy

# Run the application
go run main.go

# Or build and run
go build -o scm && ./scm
```

### Testing

```bash
# Run tests
go test ./...

# Run tests with verbose output
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

- **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 Permissions**: Ensure proper file system permissions for certificate directories

## File Organization

Certificates are stored in the following structure:
```
CERTS_PATH/
├── root/
│   ├── root.crt    # Root CA certificate
│   └── root.key    # Root CA private key (encrypted)
├── example.com/
│   ├── example.com.crt         # Domain certificate
│   └── example.com.key         # Domain private key
└── another-domain.com/
    ├── another-domain.com.crt
    └── another-domain.com.key
```

## Workflow

1. **Initial Setup**: Configure the application and create certificates directory
2. **Create Root CA**: Use `/api/certs/root` endpoint to create a root Certificate Authority
3. **Create Server Certificates**: Use `/api/certs` POST to generate server certificates signed by the CA
4. **Manage Certificates**: List, view, download, and delete certificates as needed
5. **Deploy Certificates**: Use the generated certificates in your applications

## 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
- Certificate download functionality
- 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
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

- **v1.0.0**: Full-featured SSL Certificate Manager with web interface, REST API, and certificate download functionality
- **Previous**: Basic certificate management with REST API