# vHSM Proxy

vHSM Proxy simplifies application integration with vHSM by acting as an API proxy. It offers authentication, caching, and secure communication to streamline vHSM adoption.

vHSM Proxy provides the following key features:

* **Auto-Auth**: Automatically authenticates to vHSM and manages token renewal.
* **API Proxy**: Acts as a proxy for vHSM's API, optionally enforcing Auto-Auth token usage.
* **Caching**: Enables client-side caching of tokens and leased secrets, managing renewals automatically.

### Features

#### Auto-Auth

vHSM Proxy supports automatic authentication in diverse environments. Auto-Auth functionality is configured using an `auto_auth` stanza. See Auto-Auth documentation for details.

#### API Proxy

vHSM Proxy serves as an API gateway to vHSM, allowing communication via a listener. It can be configured to enforce Auto-Auth token usage. Configure API Proxy behavior using the `api_proxy` stanza. See API Proxy documentation for more details.

#### Caching

vHSM Proxy enables client-side caching of authentication tokens and leased secrets. Configuration is managed via the `cache` stanza. See Caching documentation for details.

### API Endpoints

#### Quit API

Triggers shutdown of the proxy. Disabled by default; enable it using the `proxy_api` stanza.

* **Method:** `POST`
* **Path:** `/proxy/v1/quit`
* **Security Consideration:** Should only be enabled on trusted interfaces as it lacks authentication.

#### Cache API

For cache API details, refer to the Caching documentation.

### Start a vHSM Proxy

1. Install the vHSM binary on the application server (VM, Kubernetes pod, etc.).
2. Create a vHSM Proxy configuration file `proxy-config.hcl` or  `proxy-config.json` . See [Example configuration](#example-configuration).
3. Start vHSM Proxy with the configuration file:

   ```
   vhsm proxy -config=/etc/vhsm/proxy-config.hcl
   ```
4. To display help options:

   ```
   vhsm proxy -h
   ```

#### Command Options

| **Option**                           | **Description**                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-log-level` *(string: "info")*      | Sets the log verbosity level. Supported values (in descending detail): `trace`, `debug`, `info`, `warn`, and `error`. Can also be set via the `VAULT_LOG_LEVEL` environment variable.                                                                                                                                                                                                        |
| `-log-format` *(string: "standard")* | Sets the log format. Supported values: `standard` and `json`. Can also be set via the `VAULT_LOG_FORMAT` environment variable.                                                                                                                                                                                                                                                               |
| `-log-file`                          | Writes all Vault proxy log messages to a file. The value is used as a prefix for the log file name, and the current timestamp is appended. If the path ends with a separator, `vault-proxy` is appended. If no extension is given, `.log` is appended. Example: `/var/log/` becomes `/var/log/vault-proxy-{timestamp}.log`. Can be used with `-log-rotate-bytes` and `-log-rotate-duration`. |
| `-log-rotate-bytes`                  | Specifies the number of bytes to write to a log file before rotation occurs. If not specified, there is no size limit.                                                                                                                                                                                                                                                                       |
| `-log-rotate-duration`               | Specifies the maximum time duration a log file is written to before rotation. Must be a valid duration (e.g., `30s`). Defaults to `24h`.                                                                                                                                                                                                                                                     |
| `-log-rotate-max-files`              | Specifies the maximum number of archived log files to retain. Defaults to `0` (no files are deleted). Set to `-1` to discard old logs when new ones are created.                                                                                                                                                                                                                             |

#### Configuration File Usage

* Provide a single configuration file.
* Specify multiple configuration files (merged at runtime).
* Define a directory of configuration files (merged at runtime).

### Example configuration

```
pid_file = "./pidfile"

vault {
  address = "https://vault.example.com:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }
  sink "file" {
    config = {
      path = "/tmp/token-file"
    }
  }
}

cache {}

api_proxy {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true
  agent_api {
    enable_quit = true
  }
}

listener "tcp" {
  address = "127.0.0.1:8100"
  tls_disable = true
}
```