tamga
Official Rust SDK for Tamga. Integrate license activation, offline verification, and machine management into your Rust applications.
Install
The crate is published under the bare name tamga. It targets Rust 1.75 or
later (rust-version in Cargo.toml, pinned by a dedicated MSRV job in CI).
TLS backend is selectable: rustls-tls is on by default, native-tls is
available instead.
[]
= { = "0.2", = false, = ["native-tls"] }
Quickstart
use ValidationCode;
use AuthTransport;
use ;
async
ClientConfig::builder takes the account ID and the API host; auth is
required and build panics without it. examples/validate_license.rs is a
runnable version of the above, and examples/verify_license_file.rs covers
the offline path.
Activating a machine is a create-then-validate flow, because no seat limit is
checked at creation time — Client::activate_machine composes it and deletes
the machine row again if validation comes back over the limit:
use CreateMachineOptions;
let result = client
.activate_machine
.await?;
println!;
Auth transports
AuthTransport covers four of the server's five accepted transports
(src/transport.rs). Cookie: Tamga-Session=<uuid> is deliberately not
implemented — it is browser/portal-only and needs a matching Origin header.
use ;
// Authorization: License <key> — primary transport for embedded/client apps.
let license = License;
// Authorization: Bearer <token> — default for server-side and CI callers.
let bearer = Bearer;
// Authorization: Basic <base64>, in three sub-forms.
let basic = Basic;
let basic_email = Basic;
let basic_license = Basic;
// ?token=<token> — for callers that cannot set a header.
let query = Query;
Every request also carries a sanitized Tamga-Version header
(src/transport.rs::sanitize_version), and the validate methods take an
optional otp argument that becomes Tamga-OTP for 2FA-enabled accounts.
Offline verification
Check out a signed .lic (or .mach) file once, embed your account's public
key in the application, and every later verification runs with no network
access at all.
use verify_license_file_with_claims;
use public_key_from_base64;
// Embedded at build time; `pem` came from `client.check_out_license(..)`.
let pubkey = public_key_from_base64?;
let verified = verify_license_file_with_claims?;
println!;
verify_license_file returns just the licence resource if the claims are not
needed, and verify_license_file_at takes the current time from the caller —
use it to pass a server-derived timestamp rather than a local clock a user can
wind back.
Machine files verify the same way through
tamga::checkout::machine_file::verify_machine_file, with two differences:
the signature scheme comes from the licence's own scheme field rather than
being fixed to Ed25519, and decrypting one needs both the licence key and
the machine fingerprint. Lighter-weight machine proofs
("v1x0.<base64 signature>", always RSA-2048 PKCS#1 v1.5 / SHA-256) verify
through tamga::proof::verify_offline_proof.
Compatibility warning: licence files are format v2 only
alg must end in +v2, and the signed meta claims (iat, exp, jti,
kid) live inside the signature. A v1-issued .lic file is rejected
outright — there is no fallback path
(src/checkout/license_file.rs::verify_license_file_at), so any caller
holding a v1 file must check out a fresh one. This is a real behavioural
break, and it is the point of v2: in v1 the requested TTL lived only in the
unsigned JSON:API envelope around the certificate, so a 24-hour trial file
stayed cryptographically valid forever.
Security notes
- License-file keys are HKDF-SHA256 derived.
salt = "tamga:license-file-key-v1",ikm = <license key>,info = "license-file"(src/crypto/hkdf.rs::derive_license_file_key). Machine files usesalt = "tamga:machine-file-key-v1",ikm = <license key>,info = <fingerprint>(src/crypto/hkdf.rs::derive_machine_file_key). The distinct salts mean one licence key never yields the same AES key for both formats. The pre-v2 zero-pad/truncate transform was deleted, not deprecated — no caller can opt back into it. - Derived keys are wiped on drop. Both derivation functions return
Zeroizing<[u8; 32]>(src/crypto/hkdf.rs), so key material does not sit in freed-but-unzeroed memory. - Signed expiry is enforced, with a 60-second skew tolerance.
CLOCK_SKEW_TOLERANCE_SECSinsrc/checkout/license_file.rs::verify_license_file_atcovers ordinary NTP drift and nothing more — the clock belongs to the attacker, so a generous allowance would just extend every expired file. - The signature covers the base64 string, not the decoded bytes. The
Ed25519 signature is verified over the ASCII/UTF-8 bytes of the
encfield's base64 string (src/checkout/license_file.rspassescert.enc.as_bytes()tosrc/crypto/ed25519.rs::verify). This replicates the server's signing behaviour exactly; verifying against decoded bytes rejects every genuine file. - Machine-file algorithm selection never trusts the file. The signature
scheme comes from the caller-supplied
scheme, because the self-declaredalgstring cannot disambiguateRSA_2048_PKCS1_SIGNfromRSA_2048_JWT_RS256— and letting untrusted input pick a crypto primitive is an algorithm-confusion risk regardless (src/checkout/machine_file.rs::verify_machine_file). 429is handled, with capped and jittered backoff.Retry-Afteris parsed as delta-seconds (src/client.rs::Client::parse_retry_after) and clamped to 60 seconds so a hostile or misconfigured proxy cannot park the caller (src/client.rs::Client::retry_delay); without it the client falls back to exponential backoff plus jitter (src/transport.rs::jitter_millis). Auto-retry is scoped to everyGETplus five safePOSTactions —validate,validate-key,check-in,check-out,ping— and creates are deliberately excluded, since repeatingPOST /machinesrisks burning a second seat (src/client.rs::Client::is_retryable). SetClientConfigBuilder::max_retries(0)to handle it yourself; the exhausted case surfaces asTamgaError::RateLimited { retry_after }.- Verification errors are deliberately coarse. "Wrong key" and "tampered
ciphertext" both surface as
CryptoError::DecryptionFailed(src/error.rs::CryptoError) — a finer-grained error would be an oracle. - The
rsacrate is banned. RUSTSEC-2023-0071 (Marvin timing attack) is unpatched, so all RSA verification goes throughaws-lc-rs(src/crypto/rsa.rs); the ban is enforced in CI bydeny.toml.
Known gaps
- Only 14 of the 24
ValidationCodevariants are reachable server-side today; all 24 are modelled, with anUnknown(String)fallback for future additions (src/models/validation.rs). ScopeObject'sentitlements,fingerprint,versionandchecksumfields are sent and parsed but not enforced server-side yet — do not treat them as working constraints (src/models/validation.rs).- Auth is not enforced server-side on the licence/machine validate and
check-in endpoints yet, so
TamgaError::Unauthorizedis not reachable there (src/error.rs). The SDK always sends the configured credentials anyway; don't assume a bad credential is rejected today. - Freshly created policies report
"DENY_ACCESS"and"NO_RESURRECTION"as defaults, neither of which is a real variant. This crate treats any unrecognized policy-field value as the "no restriction" variant, matching actual server behaviour rather than the literal string (src/models/policy.rs). - The two raw-PEM checkout helpers,
Client::check_out_licenseandClient::check_out_machine, send without the retry wrapper — a429on those surfaces immediately asTamgaError::RateLimitedinstead of being retried (src/client.rs). The JSON:API variants (check_out_license_json,check_out_machine_json) do retry. - The
blockingcargo feature is declared but has no code behind it yet; there is no synchronous wrapper aroundClienttoday. - Release / auto-update checking is not part of this crate's surface.
tests/fixtures/is still empty: the checkout tests build fixtures in-process against the documented wire format rather than replaying captured server output.
Documentation
- docs.rs/tamga — generated API reference.
- tamga.sh — product and API documentation.
SECURITY.md— threat model, what counts as a vulnerability here, and how to report one privately.CONTRIBUTING.md— dev setup, commands, MSRV policy.
License
Dual-licensed under either of
- MIT (LICENSE-MIT)
- Apache License, Version 2.0 (LICENSE-APACHE)
at your option.