docs: add comprehensive README documentation
- Add detailed project overview and features - Include installation and setup instructions - Document all supported certificate types - Add usage examples and API documentation - Include security features and deployment guidelines - Add project structure and testing information - Provide contribution guidelines and support information
This commit is contained in:
Björn Benouarets
326
README.md
Normal file
326
README.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# CertMan - Enterprise Certificate Management System
|
||||
|
||||
CertMan is a comprehensive, enterprise-grade certificate management system built in Go. It provides a robust solution for managing digital certificates, Certificate Authorities (CAs), and certificate lifecycle operations in enterprise environments.
|
||||
|
||||
## 🚀 Features
|
||||
|
||||
### Core Functionality
|
||||
- **Certificate Authority Management**: Create and manage root and intermediate CAs
|
||||
- **Certificate Lifecycle Management**: Generate, validate, revoke, and renew certificates
|
||||
- **Multiple Certificate Types**: Support for web, client, email, code signing, IoT, VPN, and more
|
||||
- **Database Integration**: PostgreSQL and SQLite support with GORM ORM
|
||||
- **Secure Storage**: Encrypted storage for certificates and private keys
|
||||
- **Comprehensive Validation**: Built-in validation for certificate requests and attributes
|
||||
|
||||
### Enterprise Features
|
||||
- **Multi-Organization Support**: Manage certificates across multiple organizations
|
||||
- **User Management**: Role-based access control and user authentication
|
||||
- **Audit Trail**: Complete logging and tracking of certificate operations
|
||||
- **CRL Support**: Certificate Revocation List generation and management
|
||||
- **SAN Support**: Subject Alternative Name extensions for modern certificate requirements
|
||||
- **High Security**: 4096-bit RSA keys and enterprise-grade encryption
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- Go 1.25.1 or later
|
||||
- PostgreSQL 12+ or SQLite 3
|
||||
- Git
|
||||
|
||||
## 🛠️ Installation
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://git.secnex.io/secnex/certman.git
|
||||
cd certman
|
||||
```
|
||||
|
||||
### 2. Install Dependencies
|
||||
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
### 3. Configure Environment Variables
|
||||
|
||||
Create a `.env` file or set the following environment variables:
|
||||
|
||||
```bash
|
||||
# Database Configuration
|
||||
DB_DRIVER=postgres # or "sqlite"
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=your_password
|
||||
DB_NAME=certman
|
||||
DB_SSLMODE=disable
|
||||
|
||||
# For SQLite (simpler setup)
|
||||
DB_DRIVER=sqlite
|
||||
DB_NAME=certman
|
||||
```
|
||||
|
||||
### 4. Run Database Migrations
|
||||
|
||||
The application will automatically run database migrations on startup.
|
||||
|
||||
### 5. Build and Run
|
||||
|
||||
```bash
|
||||
# Build the application
|
||||
go build -o certman main.go
|
||||
|
||||
# Run the application
|
||||
./certman
|
||||
```
|
||||
|
||||
## 🏗️ Project Structure
|
||||
|
||||
```
|
||||
certman/
|
||||
├── certificate/ # Certificate management services
|
||||
│ ├── authority.go # Certificate Authority service
|
||||
│ ├── certificate.go # Certificate service
|
||||
│ └── utils/ # Certificate utilities
|
||||
├── config/ # Configuration management
|
||||
├── database/ # Database connection and migrations
|
||||
├── models/ # Data models and types
|
||||
├── repositories/ # Data access layer
|
||||
├── storage/ # File storage management
|
||||
├── utils/ # Utility functions
|
||||
├── data/ # Certificate and key storage (excluded from git)
|
||||
├── main.go # Application entry point
|
||||
├── go.mod # Go module definition
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🔧 Usage Examples
|
||||
|
||||
### Creating a Root Certificate Authority
|
||||
|
||||
```go
|
||||
caService := certificate.NewCertificateAuthorityService(db, "data/certs/ca", "data/private/ca")
|
||||
|
||||
req := &certificate.CreateRootCARequest{
|
||||
Name: "Enterprise Root CA",
|
||||
CommonName: "Enterprise Root CA",
|
||||
Organization: "Your Company",
|
||||
Country: "US",
|
||||
OrganizationID: orgID,
|
||||
ValidityYears: 50,
|
||||
}
|
||||
|
||||
rootCA, err := caService.CreateRootCA(req)
|
||||
```
|
||||
|
||||
### Creating an Intermediate CA
|
||||
|
||||
```go
|
||||
req := &certificate.CreateIntermediateCARequest{
|
||||
Name: "Enterprise Intermediate CA",
|
||||
CommonName: "Enterprise Intermediate CA",
|
||||
Organization: "Your Company",
|
||||
Country: "US",
|
||||
OrganizationID: orgID,
|
||||
ParentCAID: rootCA.ID,
|
||||
ValidityYears: 30,
|
||||
}
|
||||
|
||||
intermediateCA, err := caService.CreateIntermediateCA(req)
|
||||
```
|
||||
|
||||
### Generating a Web Certificate
|
||||
|
||||
```go
|
||||
certService := certificate.NewCertificateService(db, "data/certs", "data/private", caService)
|
||||
|
||||
req := &certificate.CreateCertificateRequest{
|
||||
Name: "Web Server Certificate",
|
||||
CommonName: "example.com",
|
||||
Organization: "Your Company",
|
||||
Country: "US",
|
||||
Type: models.CertificateTypeWeb,
|
||||
CertificateAuthorityID: intermediateCA.ID,
|
||||
DNSNames: []string{"example.com", "www.example.com"},
|
||||
IPAddresses: []net.IP{net.ParseIP("192.168.1.100")},
|
||||
KeyType: "rsa",
|
||||
KeySize: 4096,
|
||||
ValidityYears: 2,
|
||||
}
|
||||
|
||||
certificate, err := certService.CreateCertificate(req)
|
||||
```
|
||||
|
||||
## 📊 Supported Certificate Types
|
||||
|
||||
CertMan supports a wide range of certificate types for various enterprise use cases:
|
||||
|
||||
### Web & Server Certificates
|
||||
- `web` - HTTPS/TLS web server certificates
|
||||
- `server` - General server certificates
|
||||
|
||||
### Client Certificates
|
||||
- `client` - Client authentication certificates
|
||||
- `user` - User identity certificates
|
||||
|
||||
### Email Certificates
|
||||
- `email` - S/MIME email certificates
|
||||
|
||||
### Code Signing
|
||||
- `code` - Code signing certificates
|
||||
|
||||
### IoT & Devices
|
||||
- `iot` - Internet of Things certificates
|
||||
- `device` - Device certificates
|
||||
- `sensor` - Sensor device certificates
|
||||
|
||||
### VPN Certificates
|
||||
- `vpn` - VPN certificates
|
||||
- `openvpn` - OpenVPN specific certificates
|
||||
- `wireguard` - WireGuard specific certificates
|
||||
|
||||
### Database Certificates
|
||||
- `database` - Database connection certificates
|
||||
- `mysql` - MySQL specific certificates
|
||||
- `postgresql` - PostgreSQL specific certificates
|
||||
- `mongodb` - MongoDB specific certificates
|
||||
|
||||
### API & Services
|
||||
- `api` - API service certificates
|
||||
- `service` - Microservice certificates
|
||||
- `microservice` - Microservice architecture certificates
|
||||
|
||||
### Container & Orchestration
|
||||
- `docker` - Docker container certificates
|
||||
- `kubernetes` - Kubernetes cluster certificates
|
||||
- `container` - Container orchestration certificates
|
||||
|
||||
### Cloud & Infrastructure
|
||||
- `cloud` - Cloud service certificates
|
||||
- `aws` - Amazon Web Services certificates
|
||||
- `azure` - Microsoft Azure certificates
|
||||
- `gcp` - Google Cloud Platform certificates
|
||||
|
||||
### Network & Security
|
||||
- `network` - Network infrastructure certificates
|
||||
- `firewall` - Firewall certificates
|
||||
- `proxy` - Proxy server certificates
|
||||
- `loadbalancer` - Load balancer certificates
|
||||
|
||||
### Mobile & Applications
|
||||
- `mobile` - Mobile application certificates
|
||||
- `android` - Android specific certificates
|
||||
- `ios` - iOS specific certificates
|
||||
- `app` - Application certificates
|
||||
|
||||
### Document & File Signing
|
||||
- `document` - Document signing certificates
|
||||
- `pdf` - PDF signing certificates
|
||||
- `office` - Microsoft Office signing certificates
|
||||
|
||||
### Specialized Certificates
|
||||
- `timestamp` - Time stamping certificates
|
||||
- `ocsp` - OCSP responder certificates
|
||||
- `custom` - Custom certificate types
|
||||
- `special` - Specialized use case certificates
|
||||
|
||||
## 🔒 Security Features
|
||||
|
||||
- **High-Grade Encryption**: 4096-bit RSA keys for maximum security
|
||||
- **Secure Storage**: Encrypted storage for private keys and certificates
|
||||
- **Access Control**: Role-based permissions and user management
|
||||
- **Audit Logging**: Comprehensive logging of all operations
|
||||
- **Certificate Validation**: Built-in validation for certificate integrity
|
||||
- **CRL Support**: Certificate Revocation List management
|
||||
- **SAN Validation**: Subject Alternative Name validation and support
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
Run the test suite:
|
||||
|
||||
```bash
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Run tests with coverage:
|
||||
|
||||
```bash
|
||||
go test -cover ./...
|
||||
```
|
||||
|
||||
## 📝 API Documentation
|
||||
|
||||
The application provides a comprehensive API for certificate management operations. Key endpoints include:
|
||||
|
||||
- **Certificate Authority Management**
|
||||
- Create Root CA
|
||||
- Create Intermediate CA
|
||||
- List CAs
|
||||
- Get CA Details
|
||||
|
||||
- **Certificate Management**
|
||||
- Generate Certificate
|
||||
- Validate Certificate
|
||||
- Revoke Certificate
|
||||
- Renew Certificate
|
||||
- List Certificates
|
||||
|
||||
- **User & Organization Management**
|
||||
- Create User
|
||||
- Create Organization
|
||||
- Manage Permissions
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```dockerfile
|
||||
FROM golang:1.25.1-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY . .
|
||||
RUN go mod download
|
||||
RUN go build -o certman main.go
|
||||
|
||||
FROM alpine:latest
|
||||
RUN apk --no-cache add ca-certificates
|
||||
WORKDIR /root/
|
||||
COPY --from=builder /app/certman .
|
||||
COPY --from=builder /app/data ./data
|
||||
CMD ["./certman"]
|
||||
```
|
||||
|
||||
### Production Considerations
|
||||
|
||||
1. **Database Security**: Use strong passwords and enable SSL
|
||||
2. **File Permissions**: Ensure proper file permissions for certificate storage
|
||||
3. **Backup Strategy**: Implement regular backups of certificates and database
|
||||
4. **Monitoring**: Set up monitoring for certificate expiration
|
||||
5. **Access Control**: Implement proper network security and access controls
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
For support and questions:
|
||||
|
||||
- Create an issue in the repository
|
||||
- Contact: info@secnex.io
|
||||
- Documentation: [SecNex Documentation](https://docs.secnex.io)
|
||||
|
||||
## 🏢 About SecNex
|
||||
|
||||
CertMan is developed by SecNex, a leading provider of enterprise security solutions. For more information about our services and products, visit [secnex.io](https://secnex.io).
|
||||
|
||||
---
|
||||
|
||||
**⚠️ Security Notice**: This software handles sensitive cryptographic material. Always follow security best practices when deploying in production environments. Ensure proper access controls, regular security updates, and comprehensive backup strategies.
|
||||
Reference in New Issue
Block a user