> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify

> OpenTelemetry processor for Verify

# Verify Processor

![Status](https://img.shields.io/badge/status-development-orange)

**Maintainers:** [@hilmarf](https://github.com/hilmarf), [@jmacd](https://github.com/jmacd), [@MJarmo](https://github.com/MJarmo)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/verifyprocessor)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-development-blue)

## Overview

The verify processor verifies cryptographic integrity attributes
that [`signingprocessor`](../signingprocessor) adds to log records.

For each log record it rebuilds the same RFC 8785 (JCS) canonical JSON payload
that `signingprocessor` signed (excluding all `audit.integrity.*` attributes),
then checks the record attribute `audit.integrity.value` against the algorithm
and key material described by the resource attributes
`audit.integrity.algorithm` and (for asymmetric algorithms)
`audit.integrity.certificate`. Supported algorithms match
`signingprocessor`: `RS256`, `RS512`, `ES256`, `EdDSA`, and `HMAC-SHA256`.

Failed records can be annotated in place, cause the whole batch to be rejected,
or be dropped while good records are still exported. Permanent errors identify
failed records by `audit.record.id` when present (`id=<value>`), otherwise by
batch index (`record[resource,scope,record]`), with no other log content.
Verification failures can be written to a dead-letter storage extension.

## Configuration

For complete examples of all supported configurations see
[testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/verifyprocessor/testdata/config.yaml).
For invalid configuration examples used in tests see
[testdata/config\_invalid.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/verifyprocessor/testdata/config_invalid.yaml).

```yaml theme={null}
processors:
  verify:
    # Verification mode. Only "sync" is supported. Default: sync.
    mode: sync

    # How to handle verification failures. Default: strict.
    # - strict: reject the whole batch (export nothing) on verification failure, return a permanent error
    # - drop:   drop failed records, export the rest, return a permanent error
    # - mark:   annotate failed records and continue
    failure_mode: strict

    # Label stamped onto each verified record. Default: default.
    verification_profile: default

    # Key material source (required). Exactly one sub-block must be provided.
    # Same providers as signingprocessor. Each provider uses shared YAML keys
    # certificate or hmac_key (no private-key fields). The meaning of each
    # value depends on the provider (path, expanded secret, secret key, or field).
    key_source:
      # type selects the provider: file | env | k8s_secret | bao
      type: file

      # --- file provider — paths to local files ---
      file:
        certificate: /etc/otelcol/cert.pem
        # hmac_key: /etc/otelcol/hmac.key

      # --- env provider — key material via Collector ${env:} expansion ---
      # env:
      #   certificate: ${env:VERIFY_CERT_PEM}   # PEM or base64-encoded PEM
      #   # hmac_key: ${env:VERIFY_HMAC_KEY}

      # --- Kubernetes Secret provider — keys within the Secret ---
      # k8s_secret:
      #   name:        verify-secret
      #   namespace:   default              # optional, defaults to "default"
      #   certificate: tls.crt
      #   # hmac_key:  hmac.key

      # --- OpenBao / Vault provider (OpenBao API v2 / KVv2) ---
      # bao:
      #   address:     https://bao.example.com   # optional, falls back to BAO_ADDR
      #   token:       s.xxxx                    # optional, falls back to BAO_TOKEN
      #   mount_path:  secret                    # KV v2 mount point; default: "secret"
      #   secret_path: verify                    # path within the mount (no "data/" prefix)
      #   certificate: certificate
      #   # hmac_key:  hmac_key

    # Optional dead-letter queue for verification failures.
    # Note: dead_letter persistence is not yet implemented. Setting
    # enabled: true produces a warning; failures are not written to storage.
    dead_letter:
      enabled: false
      # storage: file_storage
      # key_prefix: audit_verify_dlq/
```

## Key source providers

Same provider set as [`signingprocessor`](../signingprocessor), but every
provider uses the shared YAML keys `certificate` or `hmac_key` (private-key
fields are omitted). Each provider config must supply exactly one material —
either a certificate or an HMAC secret, not both.

| Provider | `certificate` / `hmac_key` mean | Description |
| - | - | - |
| `file` | Local file paths | Reads a PEM certificate or an HMAC secret from disk. HMAC content is standard base64, or the raw secret when that decode fails. Certificates may be plain PEM or base64-encoded PEM. |
| `env` | Key material (usually via `${env:}`) | Holds resolved PEM or HMAC strings from Collector confmap `${env:VAR}` expansion (not env-var names). HMAC content is standard base64, or the raw secret when that decode fails. |
| `k8s_secret` | Keys inside the Secret | Reads a Kubernetes Secret by name/namespace via the in-cluster or kubeconfig client. |
| `bao` | Fields inside the secret | Reads key material from an [OpenBao](https://openbao.org/) KV v2 secrets engine via [`github.com/openbao/openbao/api/v2`](https://pkg.go.dev/github.com/openbao/openbao/api/v2) (`mount_path` default `secret`, `secret_path` relative to that mount). |

> **Note on the `env` key source:** The `certificate` and `hmac_key` fields hold
> the actual PEM text or HMAC secret, **not** environment variable names. The
> collector's confmap layer expands `${env:VAR_NAME}` before the processor starts.
> See [confmap environment variable substitution](https://opentelemetry.io/docs/specs/otel/configuration/data-model/#environment-variable-substitution).

### OpenBao `key_source` (API v2)

Same shape as [`signingprocessor`](../signingprocessor): OpenBao **`api/v2`** client
and **KV version 2**.

| Config field | Role | Example |
| - | - | - |
| `mount_path` | KV secrets-engine mount (default `secret`) | `secret` |
| `secret_path` | Path **inside** that mount (KVv2 helper adds `/data/` itself) | `verify` |
| `certificate` / `hmac_key` | Field names in the secret data map | `certificate`, `hmac_key` |

Equivalent logical read: mount `secret` + path `verify` → HTTP
`.../v1/secret/data/verify`. Do not put `secret/data/...` in `secret_path`.

## Integrity attributes (from `signingprocessor`)

Verification consumes the attributes that `signingprocessor` emits. Layout and
semantics match that processor exactly.

### Per log record

| Attribute | Type | Description |
| - | - | - |
| `audit.integrity.value` | string | Base64-encoded signature (or MAC for HMAC-SHA256) of the JCS-canonical payload, using the configured algorithm. |

### Per Resource (set once per ResourceLogs block)

| Attribute | Type | Description |
| - | - | - |
| `audit.integrity.algorithm` | string | JWA/IANA algorithm identifier matching the signing `algorithm` field (e.g. `RS256`, `ES256`, `EdDSA`, `HMAC-SHA256`). |
| `audit.integrity.certificate` | string | Certificate reference: `sha256:<hex>` fingerprint or full base64 DER, depending on signing `certificate_ref`. Not set for HMAC-SHA256. |

## Signed payload (must match `signingprocessor`)

Verification recomputes the same payload that `signingprocessor` signed. That
processor serialises the following log-record fields into a JSON object,
canonicalises it with RFC 8785 (JCS), and signs the result. All
`audit.integrity.*` attributes are excluded so the signature can be verified
without removing those attributes first.

The verifier also excludes its own `audit.verification.*` output attributes,
so a record can pass through several verify processors. If that check fails
and the record already carries `audit.verification.*` attributes, the payload
is rebuilt once with them included (regardless of `audit.verification.profile`).
This covers pipelines that re-sign a record after an earlier verify step
(sign → verify → sign → verify), where the second signer covered those attributes.

| Field | JSON key | Encoding |
| - | - | - |
| `EventName` | `event_name` | string; omitted if empty |
| `Body` | `body` | any non-empty value (type-tagged object, same encoding as attributes); omitted if empty |
| `Timestamp` | `timestamp` | nanoseconds since Unix epoch as decimal string |
| `ObservedTimestamp` | `observed_timestamp` | nanoseconds since Unix epoch as decimal string |
| `TraceID` | `trace_id` | lowercase hex string; omitted if all-zero |
| `SpanID` | `span_id` | lowercase hex string; omitted if all-zero |
| `Attributes` | `attributes` | object; see scalar encoding below |

### Attribute scalar encoding

Attribute values are encoded as follows to keep every scalar type distinct in the
signed payload. Each scalar is wrapped in a type-tagged single-key object
(e.g. `{"intValue":"123"}`) so that values of different types never produce
identical canonical JSON.

| OTLP type | JSON encoding |
| - | - |
| `string` | `{"stringValue": <string>}` |
| `int` | `{"intValue": "<decimal>"}` — quoted to preserve full int64 range |
| `double` | `{"doubleValue": <number>}` |
| `bool` | `{"boolValue": <boolean>}` |
| `bytes` | `{"bytesValue": "<base64>"}` |
| `slice` | JSON array (elements encoded recursively; max nesting depth 128) |
| `map` | JSON object (values encoded recursively; max nesting depth 128) |
| `empty` | `null` (same as `signingprocessor`) |

Serialization fails with a hard error if the total pre-JCS JSON size exceeds
2 MiB or the attribute nesting depth exceeds 128 levels.

> **Note on certificate expiry:** The verifier does not reject expired certificates.
> Signatures made by an expired certificate still verify successfully, which is
> intentional for long-term audit log verification. Expiry enforcement, if needed,
> must be done outside this processor.

## Output attributes

When `failure_mode` is `mark` or `drop`, verification results are stamped with
the same attribute names at the highest uniform level:

1. All records in a resource agree → stamp the **resource** only.
2. Otherwise, when all records in a scope agree → stamp that **scope** only.
3. Otherwise (mixed success/failure in a scope) → stamp **each log record**.

`strict` does not stamp (failed batches are not forwarded).

| Attribute | Type | Description |
| - | - | - |
| `audit.verification.status` | string | `verified` or `failed`. |
| `audit.verification.reason` | string | Machine-readable failure reason; set only when status is `failed` and all failures share the same reason. |
| `audit.verification.profile` | string | Echo of the configured `verification_profile` (default: `default`). |

Failure reason codes include: `missing_integrity_value`, `missing_algorithm`,
`unsupported_algorithm`, `missing_certificate`, `certificate_mismatch`,
`key_material_mismatch`, `invalid_signature_encoding`, `integrity_mismatch`,
`serialization_error`.

Record-level `audit.verification.*` attributes are excluded from the signed
payload reconstruction (with a one-shot retry that includes them when present)
so re-verification remains stable. Resource- and scope-level stamps are outside
the signed log payload.

## Example pipeline

```yaml theme={null}
receivers:
  otlp:
    protocols:
      grpc:

processors:
  verify:
    mode: sync
    failure_mode: strict
    key_source:
      type: file
      file:
        certificate: /etc/otelcol/cert.pem

exporters:
  otlp:
    endpoint: audit-sink:4317

service:
  pipelines:
    logs:
      receivers:  [otlp]
      processors: [verify]
      exporters:  [otlp]
```

In a real deployment, `signingprocessor` usually runs in a separate collector
(sign at the source/sidecar, verify at the sink). Configure this processor with
the public certificate or HMAC secret that matches the upstream signer.

## Configuration

### Example Configuration

```yaml theme={null}
# Verify processor — file-based HMAC key (minimal config).
# mode, failure_mode, and verification_profile use their defaults
# (sync, strict, default).
verify:
  key_source:
    type: file
    file:
      hmac_key: /etc/otelcol/hmac.key

# Asymmetric certificate verification with mark failure mode.
verify/cert_mark:
  mode: sync
  failure_mode: mark
  verification_profile: default
  key_source:
    type: file
    file:
      certificate: /etc/otelcol/cert.pem

# Drop failed records, export the rest, return permanent error with failed ids.
verify/drop:
  failure_mode: drop
  key_source:
    type: file
    file:
      hmac_key: /etc/otelcol/hmac.key

# Environment-variable key material (via Collector confmap ${env:} expansion).
verify/env:
  key_source:
    type: env
    env:
      certificate: ${env:VERIFY_CERT_PEM}

# Kubernetes Secret key material (values are keys within the Secret).
verify/k8s:
  key_source:
    type: k8s_secret
    k8s_secret:
      name: verify-secret
      namespace: default
      hmac_key: hmac.key

# OpenBao / Vault key material (KVv2 via OpenBao API v2).
# mount_path defaults to "secret"; secret_path is relative to that mount.
verify/bao:
  key_source:
    type: bao
    bao:
      address: https://bao.example.com
      mount_path: secret
      secret_path: verify
      certificate: certificate

# Dead-letter queue for verification failures.
verify/dead_letter:
  failure_mode: mark
  key_source:
    type: file
    file:
      hmac_key: /etc/otelcol/hmac.key
  dead_letter:
    enabled: true
    storage: file_storage
    key_prefix: audit_verify_dlq/
    reasons:
      - integrity_mismatch
      - missing_integrity_value
    partition_by_stream: true
    fail_on_storage_error: true
```

***

*Last generated: 2026-11-09*
