SDKs · ServerIn developmentView source

Ruby

Ruby 3.1+. Depends only on faraday.

In development

This SDK is implemented but not yet published to its package registry. Until it ships, collect an opaque evidence blob on the device and appraise it server-side with @rootherald/node (or any available server SDK). The API shown below is the planned surface and may change before release.

Gemfileruby
gem "rootherald"

The calls

  • RootHerald::Client.new(secret_key:, base_url:)
  • issue_challenge(ask: %w[identity posture], policy:, key_purpose:) → Challenge with challenge_id, challenge.
  • verify(evidence, challenge_id:, policy:) → AttestResult: verdict (:allow | :warn | :deny), device, enrollment_required, assurance_claims_met, key.
  • relay_enroll(blob, challenge_id:) / relay_activate(activation).
  • RootHerald::KeySignatures.verify(jwk, message, signature) — OpenSSL, raw or DER.
  • Errors: InvalidSecretKeyError, ChallengeError, InvalidEvidenceError, UnknownPolicyError, PolicyDowngradeError, AdmissionRefusedError, QuotaExceededError; base RootHerald::HttpError.

Example

attest_controller.rbruby
RH = RootHerald::Client.new(secret_key: ENV.fetch("RH_SECRET_KEY"))

def challenge
  c = RH.issue_challenge(ask: %w[identity posture], policy: "rootherald:builtin:strict-hardware")
  render json: { challengeId: c.challenge_id, challenge: c.challenge }   # relay challenge verbatim
end

def verify
  result = RH.verify(params[:evidence], challenge_id: params[:challengeId])
rescue RootHerald::QuotaExceededError
  head :too_many_requests
else
  return head(:conflict)   if result.enrollment_required
  return head(:forbidden)  unless result.verdict == RootHerald::Verdict::ALLOW

  device_id = result.device["ueid"]
  keys.put(device_id, result.key.jwk) if result.key      # only for a key ask, only on pass
  render json: { deviceId: device_id }
end

A Rails sample is at sdk-ruby/samples/rails-demo.

Challenges and verdicts
Every field on device.