# About process hash attestation

> Learn about Process Hash Attestation, a feature that enables strong workload attestation by including the SHA-256 hash of a workload's binary in token claims for zero-trust security enforcement

Process hash attestation enables strong workload (process) attestation. It’s for those who require verification of a client workload’s executable binary. This feature allows the SHA-256 hash of the workload’s binary in the subject claim of tokens. These tokens include JWT-SVID, OIDC ID Token, or Vault Client Token. This enables organizations to apply strong zero-trust controls. Only approved binaries can access protected services.

## Key concepts

* **Runtime hash collection** - Aembit dynamically collects the hash and inserts it into the token at runtime.

* **Process Hash Attestation** - Aembit calculates the SHA-256 hash of the workload binary at runtime. It includes this hash in the token claims, allowing policies to enforce access only for known, approved binaries.

* **Dynamic Claims** - Configure Credential Providers (JWT-SVID, OIDC ID Token, Vault Client Token) to include the process hash in dynamic subject or custom claims, for example:

  ```shell
  spiffe://trust-domain-name/path/${client.executable.hash.sha256}
  ```

* **SPIFFE Integration** - Aembit embeds the process hash in the SPIFFE ID. This supports integration with Entra ID and other SPIFFE-aware systems.

## How process hash attestation works

1. **Configuration** - An administrator configures a Credential Provider to use a dynamic claim. This claim references the process hash variable.
2. **Policy Directive** - Aembit Cloud instructs the Agent Proxy to collect the process hash.
3. **Hash Collection** - The Agent Proxy locates the binary for the proxied process. It calculates the SHA-256 hash and sends it to Aembit Cloud.
4. **Token Issuance** - Aembit Cloud generates a token. It inserts the hash value into the configured claim (subject or custom claim).
5. **Verification** - Downstream services or identity providers (for example, Entra ID) verify the hash. They check against an approved list, enforcing zero-trust access.

## Supported Credential Providers

* [JWT-SVID Token](/user-guide/access-policies/credential-providers/spiffe-jwt-svid/)
* [OIDC ID Token](/user-guide/access-policies/credential-providers/oidc-id-token/)
* [Vault Client Token](/user-guide/access-policies/credential-providers/vault-client-token/)

## Example

A dynamic subject claim might look like:

```shell
spiffe://trust-domain-name/path/${client.executable.hash.sha256}
```

If the hash is `e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`, the resulting claim would be:

```shell
spiffe://trust-domain-name/path/e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

> **Dynamic vs literal subjects**
>
> You can use either a dynamic subject with the process hash variable or a literal (static) subject:
>
> * **Dynamic subject** - `spiffe://<TENANTID>.aembit.io/azure/<APP-CLIENT-ID>/${client.executable.hash.sha256}`
> * **Literal subject** - `spiffe://example.com` (must match what you configure in Azure Entra ID)
>
> Dynamic subjects provide stronger security by binding credentials to a specific executable.

## Pre-calculating the executable hash

To verify your configuration or troubleshoot issues, you can manually calculate an executable’s SHA-256 hash. The Agent Proxy always provides the hash in **lowercase**, which matters for systems like Azure Entra ID that consume it.

* PowerShell

  Use `Get-FileHash` and convert to lowercase:

  ```powershell
  $hash = (Get-FileHash <path-to-executable>).Hash.ToLower()
  Write-Output $hash
  # Output: aca992dba6da014cd5baaa739624e68362c8930337f3a547114afdbd708d06a4
  ```

* Linux/macOS

  Use `sha256sum`:

  ```shell
  sha256sum $(which <executable>)
  # Output: aca992dba6da014cd5baaa739624e68362c8930337f3a547114afdbd708d06a4  /path/to/executable
  ```

> **Use lowercase hashes**
>
> When entering a SPIFFE subject in Azure Entra ID, you must use the lowercase hash. PowerShell’s `Get-FileHash` returns uppercase by default, so always convert it with `.ToLower()`.

## Implementation flow

* Admin configures a JWT-SVID, OIDC ID Token, or Vault Client Token Credential Provider. Use a dynamic subject or dynamic custom claim containing `${client.executable.hash.sha256}`.

* Aembit Cloud instructs the Agent Proxy to collect the process hash.

* The Agent Proxy sends the hash to Aembit Cloud.

* Aembit Cloud generates the token and inserts the `${client.executable.hash.sha256}` value. This results in a claim like:

  ```plaintext
  spiffe://trust-domain-name/path/ABC123456
  ```

### Diagram

The following diagram illustrates the process hash attestation workflow:

![Process hash attestation workflow](/d2/docs/user-guide/deploy-install/virtual-envs/process-hash-attestation-0.svg)

## Limitations

* **Supported Binaries** - Only native compiled binaries (for example, C++, Go) work in this release. Interpreted scripts (Python, Bash, etc.) and VM-based applications (Java, .NET) aren’t yet supported.
* **Platform Support** - Process assessment gathering isn’t supported on Windows VMs.
* **Hash Algorithm** - Aembit uses SHA-256 initially.
* **Caching** - Aembit performs hash calculation at runtime for security. If Aembit introduces caching, it documents its limitations.

## Security and compliance

* **Zero-Trust Enforcement** - Only binaries with approved hashes can access protected resources.
* **Runtime Attestation** - Aembit calculates hashes at runtime to prevent tampering.
* **Auditing** - Aembit logs process hash-based attestation events for compliance and auditing.