tamga 0.2.0

Official Rust SDK for Tamga. Integrate license activation, offline verification, and machine management into your Rust applications.
Documentation

tamga-rust

Crates.io docs.rs CI License

Official Rust SDK for Tamga. Integrate license activation, offline verification, and machine management into your Rust applications.

Status: Sections A–L implemented and tested (client/transport, license validation/check-in/checkout, machine checkout/management/offline proof, components/processes, entitlements, error model). Sections E, F, and H (all cryptographic code) have each passed a dedicated security-reviewer pass. Not yet done: Section M (CI/release automation hasn't been exercised against a real CI run yet) and capturing real tests/fixtures/*.lic/*.mach files from a live server (current tests generate fixtures in-process against the documented wire format instead).

Install

cargo add tamga

Published on crates.io as the bare name tamga — see docs/sdk.md in tamga-api for the full cross-SDK naming rationale.

Quickstart

See also examples/validate_license.rs for a complete, runnable version of this.

use tamga::transport::AuthTransport;
use tamga::{Client, ClientConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ClientConfig::builder("your-account-id", "api.tamga.sh")
        .auth(AuthTransport::License("YOUR-LICENSE-KEY".to_string()))
        .build();

    let client = Client::new(config)?;

    // Validate a license by its raw key.
    let result = client.validate_by_key("YOUR-LICENSE-KEY", None).await?;

    match result.meta.code {
        tamga::models::validation::ValidationCode::Valid => {
            println!("license is valid");
        }
        other => {
            println!("license is not valid: {other:?}");
        }
    }

    Ok(())
}

Offline verification

The core value proposition of this SDK over hand-rolling HTTP calls is that, once you check out a signed .lic/.mach file and embed the relevant public key in your application, verification works with no network access at all:

let license = tamga::checkout::license_file::verify_license_file(
    &pem_contents,
    &account_ed25519_pubkey,
    Some(license_key),
)?;

Security notes

Two intentional, non-obvious cryptographic choices in this SDK's .lic verifier exist because they replicate exact server behavior — do not "fix" either of them:

  1. Signature covers the base64 string, not decoded bytes. The .lic file's Ed25519 signature is computed over the ASCII/UTF-8 bytes of the enc field's base64-encoded string, not the bytes you get after base64-decoding it. Verifying against the decoded bytes will silently fail against every real server-issued file.
  2. License file encryption key is not a KDF. The AES-256-GCM key for an encrypted .lic file is the raw UTF-8 bytes of the license key string, zero-padded or truncated to exactly 32 bytes — not a hash, not HKDF, not PBKDF2. Machine files (.mach), by contrast, do use a proper HKDF-SHA256 derivation. Don't assume the two formats share a key-derivation strategy.

See src/crypto/naive_key.rs and src/crypto/ed25519.rs for the authoritative doc comments — both crypto sections (E and F) have passed a dedicated security-reviewer pass.

Known Server-Side Gaps (scoped to this SDK)

The full list lives in tamga-api's docs/sdk.md → "Known Server-Side Gaps". Items that affect this SDK's implemented surface:

  • Only 14 of 24 ValidationCode values are reachable today; this crate models all 24 but only the reachable subset is exercised by tests.
  • Auth (Authorization header) is not enforced server-side on license or machine endpoints yet — send real credentials anyway; don't assume a bad credential is rejected today.
  • The server never returns 429 Too Many Requests under the current deployment — this SDK has no client-side backoff logic keyed on it.
  • Freshly-created policies report non-existent enum strings ("DENY_ACCESS", "NO_RESURRECTION") as their defaults; this SDK treats any unrecognized policy-field value as the "no restriction" variant to match actual server behavior rather than the literal string.
  • Auto-update / release-checking (GET /releases/actions/upgrade) is not built into this SDK — it crashes at runtime server-side today.

Documentation

  • docs/sdk.md in tamga-api — the authoritative protocol/feature specification every field name, endpoint, and enum value in this SDK is verified against.
  • docs.rs/tamga — generated API reference (once published).

License

Licensed under the MIT License. See LICENSE.