windows-iac-vm-tooling/docs/02-prerequisites/secrets.md

# 🔐 Secret Management

[![Security](https://img.shields.io/badge/Security-Secrets%20Management-green)](https://forgejo.org/docs/user/actions/secrets/)

## Overview

This document describes how to configure required secrets for the CI/CD pipeline. All secrets should be stored securely in Forgejo and never committed to the repository.

---

## Required Secrets

| Secret Name | Description | Used By | Required |
|-------------|-------------|---------|----------|
| `PFX_PASS` | Code signing certificate password | osslsigncode | ✅ Yes |
| `PM_TOKEN_ID` | Proxmox API token ID | OpenTofu | ✅ Yes |
| `PM_TOKEN_SECRET` | Proxmox API token secret | OpenTofu | ✅ Yes |
| `WIN_ADMIN_PASS` | Windows Administrator password | Ansible | ✅ Yes |

---

## Forgejo Configuration

### Accessing Secrets

1. Navigate to your Forgejo repository
2. Go to **Settings** → **Secrets**
3. Add each secret with the exact names listed below

### Required Secrets List

```mermaid
graph TD
    subgraph Forgejo["Forgejo Settings"]
        Settings["Settings"] --> Secrets["Secrets"]
        Secrets --> Add["Add Secret"]
        Add --> |"Enter Name & Value"| Created[Secret Created]
    end
    
    subgraph CreatedSecrets["Configured Secrets"]
        PFX["🔐 PFX_PASS"]
        PM_ID["🔑 PM_TOKEN_ID"]
        PM_SEC["🔑 PM_TOKEN_SECRET"]
        WIN["🪟 WIN_ADMIN_PASS"]
    end
    
    Created --> PFX
    Created --> PM_ID
    Created --> PM_SEC
    Created --> WIN
    
    style Forgejo fill:#e1f5fe
    style CreatedSecrets fill:#e8f5e9
```

---

## Proxmox API Token

### Create API Token

1. **SSH to Proxmox host:**
   ```bash
   ssh root@la-vmh-07
   ```

2. **Navigate to API Tokens:**
   - Go to **Datacenter** → **API Tokens**
   - Click **Add**

3. **Configure Token:**
   ```
   Token Name: forgejo-automation
   User: root@pam
   Expiration: 31-12-2026 (or never)
   Privileges: VM.Admin (or Administrator)
   ```

4. **Save Credentials:**
   ```
   Token ID: root@pam!forgejo-automation
   Secret: <YOUR_SECRET_VALUE>
   ```

### Set Environment Variables

```bash
# In Forgejo workflow or local environment
export PM_API_TOKEN_ID="root@pam!forgejo-automation"
export PM_API_TOKEN_SECRET="<your-token-secret>"
```

---

## Code Signing Certificate

### Certificate Requirements

| Property | Value |
|----------|-------|
| **Format** | PKCS#12 (.pfx or .p12) |
| **Algorithm** | SHA-256 |
| **Timestamp Server** | http://timestamp.digicert.com |

### Prepare Certificate

```bash
# Verify certificate
openssl pkcs12 -in cert.pfx -info -noout

# Extract for use (if needed)
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -out key.pem
```

### Set Password Secret

```bash
# Set PFX_PASS secret in Forgejo
export PFX_PASS="your-certificate-password"
```

---

## Windows Administrator Password

### Requirements

| Property | Value |
|----------|-------|
| **Account** | Administrator |
| **Complexity** | Windows complexity requirements |
| **Length** | Minimum 12 characters |

### Configuration in Autounattend.xml

The password is configured in [`packer/Autounattend.xml`](../../packer/Autounattend.xml):

```xml
<UserAccounts>
  <AdministratorPassword>
    <Value>PackerPassword123!</Value>
    <PlainText>true</PlainText>
  </AdministratorPassword>
</UserAccounts>
```

### Ansible Integration

```yaml
# ansible/pipeline.yml
- name: Verify Installer
  hosts: windows_vm
  vars:
    ansible_user: Administrator
    ansible_password: "{{ lookup('env', 'WIN_ADMIN_PASS') }}"
```

---

## Security Best Practices

```mermaid
flowchart LR
    subgraph BestPractices["Security Guidelines"]
        direction TB
        NeverCommit["❌ Never commit secrets to git"]
        RotateKeys["🔄 Rotate keys regularly"]
        UseVault["🔐 Use Forgejo Secrets"]
        LimitScopes["📊 Limit token privileges"]
        AuditLogs["📝 Audit access logs"]
    end
    
    NeverCommit --> RotateKeys
    RotateKeys --> UseVault
    UseVault --> LimitScopes
    LimitScopes --> AuditLogs
    
    style BestPractices fill:#ffebee
```

| Practice | Description |
|----------|-------------|
| **Never commit secrets** | Use .gitignore for .pfx, .env files |
| **Rotate keys** | Rotate Proxmox tokens quarterly |
| **Use Forgejo Secrets** | Store all secrets in Forgejo settings |
| **Limit scopes** | Use minimum required privileges |
| **Audit access** | Review Proxmox API access logs |

---

## Environment Variables Mapping

| Secret | Env Var | Usage |
|--------|---------|-------|
| `PFX_PASS` | `PFX_PASS` | osslsigncode command |
| `PM_TOKEN_ID` | `PM_API_TOKEN_ID` | OpenTofu provider |
| `PM_TOKEN_SECRET` | `PM_API_TOKEN_SECRET` | OpenTofu provider |
| `WIN_ADMIN_PASS` | `ANSIBLE_PASSWORD` | Ansible connection |

---

## Troubleshooting

| Issue | Cause | Solution |
|-------|-------|----------|
| Token invalid | Token expired | Create new token in Proxmox |
| Permission denied | Insufficient privileges | Add VM.Admin to token |
| Password rejected | Windows complexity | Use stronger password |
| Certificate invalid | Wrong format | Convert to PKCS#12 |

---

## Next Steps

| Goal | Next Document |
|------|---------------|
| Configure ISOs | [ISO Requirements](isos.md) |
| Build template | [Packer Configuration](../03-packer/configuration.md) |
| View architecture | [Architecture Overview](../01-overview/architecture.md) |

---

[← Documentation Index](../index.md) | [→ ISO Requirements](isos.md) | [← Architecture](../01-overview/architecture.md)