HashiCorp Vault Setup Guide for NEAR Protocol Accounts

This guide walks you through setting up a HashiCorp Vault server to securely store NEAR Protocol accounts. Before starting, ensure you have:

• A server with Ubuntu/Debian
• Domain name configured
• SSL certificates ready
• Root or sudo access

Initial Setup and Installation

1. Install Vault

First, add the HashiCorp repository and install Vault:

# Add HashiCorp GPG key
wget -O- https://apt.releases.hashicorp.com/gpg | gpg --dearmor | \
    sudo tee /usr/share/keyrings/hashicorp-archive-keyring.gpg

# Add HashiCorp repository
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
    https://apt.releases.hashicorp.com $(lsb_release -cs) main" | \
    sudo tee /etc/apt/sources.list.d/hashicorp.list

# Install Vault
sudo apt update && sudo apt install vault

2. Configure Vault Server

Create the Vault configuration file:

sudo tee /etc/vault.d/vault.hcl << 'EOF'
ui = true
disable_mlock = true

storage "file" {
  path = "/opt/vault/data"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = false
  tls_cert_file = "/etc/vault.d/vault.crt"
  tls_key_file  = "/etc/vault.d/vault.key"
}

api_addr = "https://your-vault-domain:8200"
cluster_addr = "https://your-vault-domain:8201"

telemetry {
  disable_hostname = true
  prometheus_retention_time = "24h"
}
EOF

3. SSL/TLS Configuration

Place your SSL certificates in /etc/vault.d/:

• vault.crt: Your SSL certificate
• vault.key: Your private key

Note: If you need to generate certificates, follow our guide on generating Let's Encrypt certificates. Ensure your DNS is properly configured and your server is set up correctly.

4. Set File Permissions

Configure proper ownership and permissions:

# Set ownership
sudo chown vault:vault /etc/vault.d/vault.hcl
sudo chown vault:vault /etc/vault.d/vault.key
sudo chown vault:vault /etc/vault.d/vault.crt

# Set permissions
sudo chmod 640 /etc/vault.d/vault.hcl
sudo chmod 640 /etc/vault.d/vault.key
sudo chmod 640 /etc/vault.d/vault.crt

5. Create Systemd Service

Set up Vault as a system service:

sudo tee /etc/systemd/system/vault.service << 'EOF'
[Unit]
Description="HashiCorp Vault - A tool for managing secrets"
Documentation=https://www.vaultproject.io/docs/
Requires=network-online.target
After=network-online.target
ConditionFileNotEmpty=/etc/vault.d/vault.hcl

[Service]
User=vault
Group=vault
ProtectSystem=full
ProtectHome=read-only
PrivateTmp=yes
PrivateDevices=yes
SecureBits=keep-caps
AmbientCapabilities=CAP_IPC_LOCK
Capabilities=CAP_IPC_LOCK+ep
CapabilityBoundingSet=CAP_IPC_LOCK
NoNewPrivileges=yes
ExecStart=/usr/bin/vault server -config=/etc/vault.d/vault.hcl
ExecReload=/bin/kill --signal HUP $MAINPID
KillMode=process
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
LimitNOFILE=65536
LimitMEMLOCK=infinity

[Install]
WantedBy=multi-user.target
EOF

Vault Initialization and Configuration

6. Initialize and Unseal

Start the Vault service and perform initial setup:

# Start Vault service
sudo systemctl daemon-reload
sudo systemctl enable vault
sudo systemctl start vault

# Configure Vault address
export VAULT_ADDR='https://your-vault-domain:8200'

# Initialize Vault
vault operator init

# Unseal Vault (requires 3 of 5 keys)
vault operator unseal  # First key
vault operator unseal  # Second key
vault operator unseal  # Third key

# Verify status
vault status

7. Configure Access Policies

Set up the following policies for different access levels:

Admin Policy

sudo tee signing-admin-policy.hcl << 'EOF'
path "sys/auth/*" {
  capabilities = ["create", "update", "delete", "sudo"]
}

path "sys/auth" {
  capabilities = ["read"]
}

path "auth/approle/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

Operator Policy

sudo tee signing-operator-policy.hcl << 'EOF'
path "secret/data/signing-keys/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
  allowed_parameters = {
    "data" = []
    "options" = []
  }
}
path "secret/metadata/signing-keys/*" {
  capabilities = ["read", "list"]
}
path "secret/metadata/signing-keys" {
  capabilities = ["read", "list"]
}
path "secret/data/signing-keys" {
  capabilities = ["create", "read", "update", "list"]
}
EOF

General Signing Policy

sudo tee signing-policy.hcl << 'EOF'
# Allow managing auth methods
path "sys/auth/*" {
  capabilities = ["create", "update", "delete", "sudo"]
}

# Allow listing auth methods
path "sys/auth" {
  capabilities = ["read"]
}

# Allow managing roles
path "auth/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Existing podman-keys permissions
path "secret/data/signing-keys/*" {
  capabilities = ["create", "read", "update", "delete"]
}

# Allow listing secrets
path "secret/metadata/*" {
  capabilities = ["list"]
}

# Allow managing AppRole auth configuration
path "auth/approle/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

Reader Policy

sudo tee signing-reader-policy.hcl << 'EOF'
path "secret/data/signing-keys/*" {
  capabilities = ["read"]
}
path "secret/metadata/signing-keys/*" {
  capabilities = ["read", "list"]
}
EOF

Apply all policies:

vault policy write signing-admin-policy signing-admin-policy.hcl
vault policy write signing-operator-policy signing-operator-policy.hcl
vault policy write signing-policy signing-policy.hcl
vault policy write signing-reader-policy signing-reader-policy.hcl

8. Enable Key-Value Store

Enable the KV secrets engine:

vault secrets enable -path=secret kv-v2

9. Configure AppRole Authentication

Set up authentication for automated access:

# Enable AppRole
vault auth enable approle

# Create role
vault write auth/approle/role/NEAR-MANAGER-ROLE \
    token_policies="near-operator-policy" \
    token_ttl=0 \
    token_max_ttl=0 \
    token_type="service" \
    period="768h"

Retrieve role credentials:

# Get Role ID
vault read -format=json auth/approle/role/NEAR-MANAGER-ROLE/role-id | jq -r '.data.role_id'

# Get Secret ID
vault write -f -format=json auth/approle/role/NEAR-MANAGER-ROLE/secret-id | jq -r '.data.secret_id'

10. Store NEAR Protocol Accounts

On each server that needs to access the Vault:

# Set Vault address
export VAULT_ADDR='VAULT_SERVER_URL'

# Configure credentials
ROLE_ID='your-role-id'
SECRET_ID='your-secret-id'

# Login
vault write auth/approle/login \
    role_id=$ROLE_ID \
    secret_id=$SECRET_ID

# Store NEAR account
vault kv put -mount=secret near-accounts/my-account \
    account_json=@/path/to/near-credentials/mainnet/account.json

Security Considerations

Unsealing Process

The Vault uses a threshold unsealing process:

• Requires 3 of 5 keys by default
• Vault starts in a sealed state
• Cannot decrypt storage until unsealed
• Multiple operators must provide keys
• Never store unseal keys on the Vault server
• Unsealing required after maintenance/restarts