vault-hier/README.md

Hierarchical Document Signing with HashiCorp Vault

This project implements a hierarchical document signing system using HashiCorp Vault. It allows for secure document signing with a requirement of a specific number of signatures from different departmental groups.

Features

• Hierarchical Signing: Requires 3 of 5 signatures to validate a document, with at least 1 signature from each department
• Department Structure: Two departments (Legal and Finance) with 5 users each
• Document API: Upload, sign, and verify documents through a RESTful API
• CLI Client: Interact with the system through command-line interface
• Vault Integration: Leverages HashiCorp Vault's Transit engine for cryptographic operations

System Architecture

The system consists of:

1. Vault Server: Provides secure storage and cryptographic operations
2. Rust Application: Initializes Vault and provides a REST API for document operations
3. User Hierarchy: 10 users organized into 2 departments
4. Signature Requirements: 3 of 5 signatures needed, with at least 1 from each department

API Endpoints

• POST /api/login: Authenticate with username/password and get a token
• POST /api/documents: Upload a new document for signing
• GET /api/documents/:id: Retrieve document metadata
• POST /api/documents/:id/sign: Sign a document with your user credentials
• GET /api/documents/:id/verify: Check if a document has sufficient signatures

Getting Started

Prerequisites

• Docker and Docker Compose
• Rust development environment (if building from source)

Running with Docker

1. Start the Vault server and initialization program:

   docker-compose up -d
   

2. The service will automatically:

   • Initialize Vault (if needed)
   • Unseal Vault
   • Create 10 users in a hierarchical structure
   • Start the API server on port 3000

3. User credentials:

   • Legal department: legal1/legal1pass through legal5/legal5pass
   • Finance department: finance1/finance1pass through finance5/finance5pass

CLI Commands

The project includes a command-line interface to interact with the API:

1. Start the Server:

   cargo run server [--vault-addr URL] [--api-port PORT]
   

2. Login:

   cargo run login --username USER --password PASS [--api-url URL]
   

3. Upload Document:

   cargo run upload --name NAME --file PATH [--api-url URL]
   

4. Sign Document:

   cargo run sign --document-id ID --username USER --token TOKEN [--api-url URL]
   

5. Verify Document:

   cargo run verify --document-id ID [--api-url URL]
   

6. List Documents:

   cargo run list [--api-url URL]
   

7. Get Document Details:

   cargo run get --document-id ID [--api-url URL]
   

API Usage Examples (curl)

1. Login:

   curl -X POST http://localhost:3000/api/login \
     -H "Content-Type: application/json" \
     -d '{"username":"legal1","password":"legal1pass"}'
   

2. Upload Document:

   curl -X POST http://localhost:3000/api/documents \
     -F "name=Contract" \
     -F "file=@/path/to/document.pdf"
   

3. Sign Document:

   curl -X POST http://localhost:3000/api/documents/DOCUMENT_ID/sign \
     -H "Content-Type: application/json" \
     -d '{"username":"legal1","token":"USER_TOKEN"}'
   

4. Verify Document:

   curl -X GET http://localhost:3000/api/documents/DOCUMENT_ID/verify
   

Security Considerations

• All cryptographic operations are performed by Vault's Transit engine
• Each user has their own signing key
• Root token should be secured in production environments
• Consider adding TLS for production deployments

License

MIT