Signing Processor

Maintainers: @hilmarf, @jmacd Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

The signing processor adds cryptographic integrity attributes to log records. For each log record it computes a canonical JSON hash (RFC 8785 / JCS) over the full record and signs it with an RSA private key. The resulting signature is stored as audit.integrity.value attribute on the record, and the JWA algorithm identifier plus a certificate reference are stored as audit.integrity.algorithm and audit.integrity.certificate on the enclosing Resource. The processor is designed for use with the OpenTelemetry Audit Logging signal and satisfies the Tier-2 Collector integrity-verification requirements defined there.

Configuration

For complete examples of all supported configurations see testdata/config.yaml. For invalid configuration examples used in tests see testdata/config_invalid.yaml.

processors:
  signing:
    # JWA signing algorithm. Default: RS256.
    # Valid values: RS256, RS512, ES256, EdDSA, HMAC-SHA256
    algorithm: RS256

    # How to encode the signing certificate in the audit.integrity.certificate
    # resource attribute. Default: fingerprint.
    # - fingerprint: "sha256:<hex>" of the DER-encoded certificate
    # - full:        standard-base64 of the DER-encoded certificate
    certificate_ref: fingerprint

    # Key material source (required). Exactly one sub-block must be provided.
    key_source:
      # type selects the provider: file | env | k8s_secret | bao
      type: file

      # --- file provider ---
      file:
        certificate: /etc/otelcol/signing-cert.pem
        private_key: /etc/otelcol/signing-key.pem

      # --- file provider — HMAC-SHA256 ---
      # file:
      #   hmac_key: /etc/otelcol/hmac.key  # file content must be standard base64-encoded

      # --- env provider — asymmetric ---
      # env:
      #   certificate: ${env:SIGNING_CERT_PEM}   # PEM or base64-encoded PEM
      #   private_key: ${env:SIGNING_KEY_PEM}

      # --- env provider — HMAC-SHA256 ---
      # env:
      #   hmac_key: ${env:SIGNING_HMAC_KEY}

      # --- Kubernetes Secret provider — asymmetric ---
      # k8s_secret:
      #   name:        signing-secret
      #   namespace:   default              # optional, defaults to "default"
      #   certificate: tls.crt
      #   private_key: tls.key

      # --- Kubernetes Secret provider — HMAC-SHA256 ---
      # k8s_secret:
      #   name:     signing-secret
      #   namespace: default
      #   hmac_key: hmac.key                  # store the raw key bytes in the Secret data field
      #                                       # (Kubernetes base64-encodes Secret data internally;
      #                                       #  the processor receives decoded bytes directly)

      # --- OpenBao / Vault provider — asymmetric ---
      # 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: signing                   # path within the mount
      #   certificate: certificate
      #   private_key: private_key

      # --- OpenBao / Vault provider — HMAC-SHA256 ---
      # bao:
      #   mount_path:  secret
      #   secret_path: signing
      #   hmac_key:    hmac_key             # field value must be standard base64-encoded

Key source providers

Provider	Description
`file`	Reads PEM-encoded certificate and private key (RSA, ECDSA, or Ed25519) from local files, or a raw HMAC secret. Supports plain PEM and base64-encoded PEM.
`env`	Holds key material resolved by the collector’s confmap layer. Field values must be the actual PEM text or base64-encoded key, typically supplied via `${env:VAR_NAME}` substitution in the collector config. Useful for container deployments where secrets are injected via environment variables.
`k8s_secret`	Reads a Kubernetes Secret by name/namespace via the in-cluster or kubeconfig client.
`bao`	Reads key material from an OpenBao (Vault-compatible) secret engine.

Note on the env key source: The certificate, private_key, and hmac_key fields hold the actual PEM text or base64-encoded key material, not environment variable names. The collector’s confmap layer expands ${env:VAR_NAME} references before the processor starts, so the processor always receives resolved values. See confmap environment variable substitution for details. Configs that previously passed bare variable names (e.g. certificate: SIGNING_CERT_PEM) will fail at provider construction time.

Output attributes

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.
`audit.integrity.signer`	string	Always `"collector"` — identifies that the Collector signing processor added the integrity value.

Per Resource (set once per ResourceLogs block)

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

Signed payload

The 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 before those attributes are removed.

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)

Serialization fails with a hard error if the total pre-JCS JSON size exceeds 2 MiB, if the attribute nesting depth exceeds 128 levels, or if the event name, an attribute key, a map key, or a string value is not valid UTF-8. The check exists because json.Marshal would otherwise replace each invalid byte with U+FFFD, and two records differing only in such bytes would share a signature.

Example pipeline

receivers:
  otlp:
    protocols:
      grpc:

processors:
  signing:
    algorithm: RS256
    certificate_ref: fingerprint
    key_source:
      type: file
      file:
        certificate: /etc/otelcol/cert.pem
        private_key: /etc/otelcol/key.pem

exporters:
  otlp:
    endpoint: audit-sink:4317

service:
  pipelines:
    logs:
      receivers:  [otlp]
      processors: [signing]
      exporters:  [otlp]

Configuration

Example Configuration

# Signing processor — file-based key material (minimal config).
# algorithm and certificate_ref use their defaults (RS256, fingerprint).
signing:
  key_source:
    type: file
    file:
      certificate: /etc/otelcol/signing-cert.pem
      private_key: /etc/otelcol/signing-key.pem

# RS512 variant with full certificate reference.
signing/sha512_full:
  algorithm: RS512
  certificate_ref: full
  key_source:
    type: file
    file:
      certificate: /etc/otelcol/signing-cert.pem
      private_key: /etc/otelcol/signing-key.pem

# Environment-variable key material (confmap ${env:VAR} expansion).
signing/env:
  key_source:
    type: env
    env:
      certificate: ${env:SIGNING_CERT_PEM}
      private_key: ${env:SIGNING_KEY_PEM}

# Kubernetes Secret key material.
signing/k8s:
  key_source:
    type: k8s_secret
    k8s_secret:
      name:        signing-secret
      namespace:   default
      certificate: tls.crt
      private_key: tls.key

# OpenBao / Vault key material.
signing/bao:
  key_source:
    type: bao
    bao:
      address:     https://bao.example.com
      mount_path:  secret
      secret_path: signing
      certificate: certificate
      private_key: private_key

# HMAC-SHA256 with key from environment variable (confmap ${env:VAR} expansion).
signing/hmac:
  algorithm: HMAC-SHA256
  certificate_ref: ""
  key_source:
    type: env
    env:
      hmac_key: ${env:SIGNING_HMAC_KEY}

Last generated: 2026-10-05

​Signing Processor

​Supported Telemetry

​Overview

​Configuration

​Key source providers

​Output attributes

​Per log record

​Per Resource (set once per ResourceLogs block)

​Signed payload

​Attribute scalar encoding

​Example pipeline

​Configuration

​Example Configuration

Signing Processor

Supported Telemetry

Overview

Configuration

Key source providers

Output attributes

Per log record

Per Resource (set once per ResourceLogs block)

Signed payload

Attribute scalar encoding

Example pipeline

Configuration

Example Configuration