Developer Guide

Using the library, authoring shims, and extending providers.

Using keyrack-core directly

The crate is not published on crates.io. This example pins a public source revision; it does not require a local KeyRack checkout. Add these dependencies to Cargo.toml and copy a complete Rust example below into src/main.rs. CI compiles and runs these exact blocks.

[dependencies]
keyrack-core = { git = "https://github.com/KeyRack-io/keyrack.git", rev = "70bf446def1cac32881e5e24d36f653551cdc25f" }
tokio = { version = "1", features = ["macros", "rt"] }

Software provider

use keyrack_core::key::KeySpec;
use keyrack_core::provider::software::SoftwareProvider;
use keyrack_core::provider::CryptoProvider;

#[tokio::main(flavor = "current_thread")]
async fn main() -> keyrack_core::error::Result<()> {
    // Development only: this provider loses its keys when the process exits.
    let provider = SoftwareProvider::new();
    let key = provider.generate_key(&KeySpec::Aes256).await?;
    let plaintext = b"secret data";
    let aad = b"example context";
    let ct = provider.encrypt(&key, plaintext, aad).await?;
    let pt = provider.decrypt(&key, &ct.ciphertext, aad).await?;
    assert_eq!(pt.expose().as_slice(), plaintext);
    Ok(())
}

Swap in Pkcs11Provider or KmipProvider for HSM-backed production.

Key hierarchy resolution

use keyrack_core::resolver::{resolve_chain, ResolverConfig};
use keyrack_core::rule::RuleRegistry;
use std::collections::BTreeMap;

fn main() -> keyrack_core::error::Result<()> {
    let yaml = r#"
namespaces:
  - name: example
    routing_rules:
      - match_pattern: { kind: dek, user: "$user" }
        parent: { kind: root }
      - match_pattern: { kind: root }
        parent: null
"#;
    let registry = RuleRegistry::from_yaml(yaml)?;
    let attrs = BTreeMap::from([
        ("kind".to_owned(), "dek".to_owned()),
        ("user".to_owned(), "alice".to_owned()),
    ]);
    // Computes logical identities only; does not provision or wrap keys.
    let chain = resolve_chain(&registry, &attrs, &ResolverConfig::default())?;
    assert_eq!(chain.len(), 2); // [leaf_lid, root_lid]
    Ok(())
}

Writing custom providers

Implement the CryptoProvider trait to add new backends. Existing providers:

• keyrack-pkcs11 — PKCS#11 HSM
• keyrack-kmip — KMIP client
• keyrack-vault — HashiCorp Vault Transit

WASM target

The keyrack-wasm crate compiles to WebAssembly for browser use. No published npm package yet — see TypeScript use case.

REST and gRPC APIs

This version snapshot comes from KeyRack source commit e25310da1e0a. The table is generated from the same operation inventory checked by the public source gate.

REST / gRPC surface availability

This table enumerates KeyService RPCs and registered REST routes in the default build. It describes availability, not identical request fields or behavior. Existing cross-interface lifecycle tests check semantics separately.

crypto-endpoints is enabled by default. Rows marked crypto feature lose the REST route and return gRPC UNIMPLEMENTED when that feature is disabled. Export and import are not controlled by that feature.

RPC	gRPC	REST method and path	Scope / gap reason
AcknowledgeRotationJob	Handler available	—	Existing REST gap: Rotation-job coordination is exposed by this gRPC handler; the REST facade has no corresponding route.
CancelKeyDeletion	Handler available	POST /v1/keys/:key_id/actions-cancel-deletion
CompleteRotationJob	Handler available	—	Existing REST gap: Rotation-job coordination is exposed by this gRPC handler; the REST facade has no corresponding route.
CreateAlias	Handler available	POST /v1/aliases
CreateHsmConnection	Handler available	—	Existing REST gap: HSM connection administration is exposed by this gRPC handler; the REST facade has no corresponding route.
CreateKey	Handler available	POST /v1/keys
Decrypt	Handler available	POST /v1/keys/:key_id/actions-decrypt	crypto feature.
DeleteAlias	Handler available	DELETE /v1/aliases/:alias_name
DeleteHsmConnection	Handler available	—	Existing REST gap: HSM connection administration is exposed by this gRPC handler; the REST facade has no corresponding route.
DescribeKey	Handler available	GET /v1/keys/:key_id/describe
DescribeNamespace	Declared stub; see limitation	—	Unimplemented namespace registry: The handler always returns NotFound; the namespace registry is not implemented.
DisableKey	Handler available	POST /v1/keys/:key_id/actions-disable
DisableKeyRotation	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
EnableKey	Handler available	POST /v1/keys/:key_id/actions-enable
EnableKeyRotation	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
Encrypt	Handler available	POST /v1/keys/:key_id/actions-encrypt	crypto feature.
ExplainRouting	Handler available	POST /v1/routing/explain
FailRotationJob	Handler available	—	Existing REST gap: Rotation-job coordination is exposed by this gRPC handler; the REST facade has no corresponding route.
GenerateDataKey	Handler available	POST /v1/keys/:key_id/actions-generate-data-key	crypto feature.
GenerateDataKeyWithoutPlaintext	Handler available	—	crypto feature. Existing REST gap: The REST GenerateDataKey operation always returns plaintext; no REST operation suppresses it. Use this gRPC RPC for ciphertext-only data keys.
GenerateMac	Handler available	POST /v1/keys/:key_id/actions-generate-mac	crypto feature.
GenerateRandom	Handler available	POST /v1/generate-random	crypto feature.
GetHsmConnection	Handler available	—	Existing REST gap: HSM connection administration is exposed by this gRPC handler; the REST facade has no corresponding route.
GetHsmConnectionStatus	Handler available	—	Existing REST gap: HSM connection administration is exposed by this gRPC handler; the REST facade has no corresponding route.
GetKey	Handler available	GET /v1/keys/:key_id
GetKeyAncestors	Handler available	—	Existing REST gap: Ancestor traversal has a gRPC handler and no REST route.
GetKeyDependents	Handler available	—	Existing REST gap: Dependent-key traversal has a gRPC handler and no REST route.
GetKeyMaterial	Handler available	—	Intentional gap: The 0.4.0 exportability API intentionally exposes this operation only through gRPC (CHANGELOG: key export API, gRPC only).
GetKeyRotationHistory	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
GetKeyRotationPolicy	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
GetKeyRotationStatus	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
GetKeyVersion	Handler available	—	Existing REST gap: Version-specific retrieval has a gRPC handler and no REST route.
ImportKey	Handler available	POST /v1/keys/import
ListAliases	Handler available	GET /v1/aliases
ListHsmConnections	Handler available	—	Existing REST gap: HSM connection administration is exposed by this gRPC handler; the REST facade has no corresponding route.
ListKeyVersions	Handler available	—	Existing REST gap: Dedicated version listing is available through gRPC; REST metadata embeds versions but has no equivalent list operation.
ListKeys	Handler available	GET /v1/keys
ListNamespaces	Declared stub; see limitation	—	Unimplemented namespace registry: The handler always returns an empty list; the namespace registry is not implemented.
ListResourceTags	Handler available	GET /v1/keys/:key_id/tags
ListRotationJobs	Handler available	—	Existing REST gap: Rotation-job coordination is exposed by this gRPC handler; the REST facade has no corresponding route.
MakeKeyExportable	Handler available	—	Intentional gap: The 0.4.0 exportability API intentionally exposes this operation only through gRPC (CHANGELOG: key export API, gRPC only).
ReEncrypt	Handler available	POST /v1/keys/:key_id/actions-re-encrypt	crypto feature.
RegisterNamespace	Declared stub; see limitation	—	Unimplemented namespace registry: The handler logs and echoes the name without storing a namespace. The namespace registry is not implemented.
ReportKeyCompromise	Handler available	POST /v1/keys/:key_id/actions-report-compromise
RevokeKeyExportability	Handler available	—	Intentional gap: The 0.4.0 exportability API intentionally exposes this operation only through gRPC (CHANGELOG: key export API, gRPC only).
RotateKey	Handler available	POST /v1/keys/:key_id/actions-rotate
ScheduleKeyDeletion	Handler available	POST /v1/keys/:key_id/actions-schedule-deletion
SetKeyRotationPolicy	Handler available	—	Existing REST gap: Rotation settings/history are exposed by this gRPC handler; the REST facade has no corresponding route.
Sign	Handler available	POST /v1/keys/:key_id/actions-sign	crypto feature.
TagResource	Handler available	POST /v1/keys/:key_id/tags
UntagResource	Handler available	DELETE /v1/keys/:key_id/tags
UpdateKey	Handler available	PUT /v1/keys/:key_id
Verify	Handler available	POST /v1/keys/:key_id/actions-verify	crypto feature.
VerifyMac	Handler available	POST /v1/keys/:key_id/actions-verify-mac	crypto feature.

REST-only operational endpoints

REST method and path	Reason
GET /healthz	HTTP health metadata endpoint; no corresponding KeyService RPC.
GET /metrics	Prometheus HTTP scrape endpoint; no corresponding KeyService RPC.
GET /readyz	HTTP readiness probe for storage and provider access; no corresponding KeyService RPC.

External protocol contracts

keyrack.v1.PdpService (Authorize, BatchAuthorize, ExplainAuthorization): This is the external PDP protocol consumed by the service, not a service registered on its northbound listener.

REST authentication also depends on deployment configuration. With the peer-certificate-only mTLS authenticator, authenticated REST operations return 501 AuthenticationTransportUnsupported; the table does not claim that a registered route supplies that identity transport.

Repository layout

Crate	Role
keyrack-core	Types, traits, providers, audit
keyrack-service	gRPC + REST service binary
keyrack-cedar-pdp	Standalone Cedar PDP
keyrack-cli	Lint, provision, migrate, admin

Full reference

The complete developer guide lives in the keyrack-oss repository.

See also: Operator guide · Security model