tamga 0.3.2

Official Rust SDK for Tamga. Integrate license activation, offline verification, and machine management into your Rust applications.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
//! Canonicalise a machine fingerprint before sending it to the server.
//!
//! ## The defect this closes
//!
//! The server stores `fingerprint TEXT NOT NULL` — no length limit, no
//! `CHECK`, no normalisation — unique per `(license_id, fingerprint)`. Every
//! Tamga SDK sent the caller's string through byte-for-byte, so `"ABC-123"`,
//! `"abc-123"` and `" ABC-123 "` were three machines holding three seats on
//! one licence. Trailing whitespace off a config file or a shelled-out
//! `wmic`/`ioreg` read is the common way in.
//!
//! [`compute`] turns caller-chosen, *labelled* components into one stable
//! 64-character lowercase hex string, so re-ordering the components or
//! picking up stray whitespace cannot change the identity.
//!
//! ## What this deliberately does not do
//!
//! It reads **no hardware identifiers**. What identifies a machine is a
//! product decision, not a library's: a cloned VM template shares its
//! machine-id, a container has none, a replaced motherboard changes one. No
//! default is right for both a desktop app and a Kubernetes sidecar, so the
//! choice of components stays with the caller.
//!
//! ## Algorithm
//!
//! ```text
//! canonical    = "tamga-fingerprint-v1" US join(US, sort_bytewise(["label=" + trimmed_value]))
//! fingerprint  = lowercase_hex(SHA-256(UTF-8(canonical)))
//! ```
//!
//! `US` is U+001F, the ASCII unit separator, emitted as the single byte
//! `0x1F`. The literal prefix is a domain separator, so a future v2 rule
//! cannot collide with a v1 fingerprint.
//!
//! Rules, each enforced by [`canonical`]:
//!
//! | Part | Rule |
//! |---|---|
//! | components | at least one |
//! | label | non-empty; ASCII printable `0x21..=0x7E`; no `'='`; no duplicates |
//! | value | ASCII whitespace trimmed from both ends **first**, then no ASCII control character; `'='` allowed; may be empty |
//! | sort | bytewise ascending over the UTF-8 bytes of the whole `label=value` component |
//! | case | preserved — never folded |
//!
//! ## Why there is no Unicode normalisation
//!
//! Values are **not** NFC-normalised, and that is a constraint rather than an
//! oversight. NFC would need a new dependency here
//! (`unicode-normalization`), and in the C11 port it would mean ICU or
//! hand-rolled Unicode tables inside a library whose selling point is having
//! no dependencies at all. A rule that eight ports cannot implement
//! *identically* is worse than no rule: it would hand back two fingerprints
//! for one machine depending on which SDK the application was written in,
//! silently consuming two seats. Everything above is ASCII-only for that
//! reason. A caller whose values can arrive in more than one normal form
//! must normalise before calling.
//!
//! Case folding is absent for a separate reason: lowercasing a base64 or hex
//! identifier corrupts it.
//!
//! ## Example
//!
//! ```
//! use tamga::fingerprint;
//!
//! // Component order is the caller's convenience, not part of the identity.
//! let a = fingerprint::compute([("machine-id", "abc123"), ("disk", "SN-9")])?;
//! let b = fingerprint::compute([("disk", "SN-9"), ("machine-id", "abc123")])?;
//! assert_eq!(a, b);
//! assert_eq!(a.len(), 64);
//! # Ok::<(), tamga::error::FingerprintError>(())
//! ```

use std::collections::BTreeSet;

use sha2::{Digest, Sha256};

use crate::error::FingerprintError;

/// Domain-separation prefix. Bump the suffix, never the shape, if the rule
/// ever changes — a v2 canonical string must not be able to equal a v1 one.
const DOMAIN: &str = "tamga-fingerprint-v1";

/// U+001F, the ASCII unit separator: the single byte `0x1F`.
const UNIT_SEPARATOR: char = '\u{1f}';

/// The spec's ASCII whitespace set: space, tab, CR, LF, vertical tab, form
/// feed.
///
/// Deliberately **not** [`str::trim`], which strips every Unicode
/// `White_Space` code point — U+00A0 and U+3000 among them. Trimming those
/// would be a normalisation rule the C11 port cannot reproduce without
/// Unicode tables, which is exactly what the module doc comment rules out.
const ASCII_WHITESPACE: [char; 6] = [' ', '\t', '\r', '\n', '\u{b}', '\u{c}'];

/// Builds the canonical string that [`compute`] hashes.
///
/// Exposed because it is what makes a fingerprint mismatch debuggable: two
/// machines that should agree and do not differ visibly here, where the hex
/// digest shows nothing. Use [`compute`] for the value you actually send.
///
/// The returned string contains raw `0x1F` bytes between components.
///
/// # Errors
///
/// Returns a [`FingerprintError`] for any component that breaks the rules in
/// the module doc comment. Nothing is ever repaired in place — see
/// [`FingerprintError`] for why silent repair would be the more dangerous
/// behaviour.
pub fn canonical<I, L, V>(components: I) -> Result<String, FingerprintError>
where
    I: IntoIterator<Item = (L, V)>,
    L: AsRef<str>,
    V: AsRef<str>,
{
    let mut seen_labels = BTreeSet::new();
    let mut parts: Vec<String> = Vec::new();

    for (label, value) in components {
        let label = label.as_ref();
        validate_label(label)?;

        if !seen_labels.insert(label.to_owned()) {
            return Err(FingerprintError::DuplicateLabel {
                label: label.to_owned(),
            });
        }

        // Trim BEFORE validating: `"  abc\t\n"` is the footgun this helper
        // exists to absorb, so its tab and newline must not be reported as
        // rejected control characters.
        let value = value
            .as_ref()
            .trim_matches(|c| ASCII_WHITESPACE.contains(&c));
        // `char::is_ascii_control` is exactly the spec's set: 0x00..=0x1F and
        // 0x7F. Non-ASCII is untouched by it, which is the intent.
        if value.chars().any(|c| c.is_ascii_control()) {
            return Err(FingerprintError::ControlCharacterInValue {
                label: label.to_owned(),
            });
        }

        let mut part = String::with_capacity(label.len() + 1 + value.len());
        part.push_str(label);
        part.push('=');
        part.push_str(value);
        parts.push(part);
    }

    if parts.is_empty() {
        return Err(FingerprintError::NoComponents);
    }

    // The spec's "bytewise ascending over the UTF-8 bytes of the whole
    // component". `Ord for String` defers to `Ord for str`, which is `[u8]`
    // lexicographic ordering over the UTF-8 encoding — confirmed, not
    // assumed, by the tests below.
    //
    // Two non-obvious properties, both of which say the same thing: do not
    // spend a test on "bytewise versus code-point order".
    //
    // First, they are the *same* order. UTF-8 is constructed so that byte
    // comparison equals scalar-value comparison, so no input distinguishes
    // them.
    //
    // Second, and more strongly: for any *valid* input a value's bytes can
    // never decide the ordering at all. Labels are unique and ASCII-printable,
    // so when two components are compared the first differing byte is always
    // either inside the two labels or at the `=` terminating one of them —
    // always below 0x80. `non_ascii_value` therefore pins UTF-8 *hashing*,
    // not sorting, and a multi-component non-ASCII vector would prove nothing.
    //
    // The two orderings that genuinely differ from the spec's are sorting
    // case-insensitively, and sorting on the label alone instead of the whole
    // `label=value` component. Both are pinned below, with the expected order
    // derived from the byte values in the spec rather than from this
    // function's own output.
    //
    // A sort, not a set: collapsing equal parts would be the silent dedup
    // that `DuplicateLabel` exists to refuse.
    parts.sort_unstable();

    let mut out =
        String::with_capacity(DOMAIN.len() + parts.iter().map(|p| p.len() + 1).sum::<usize>());
    out.push_str(DOMAIN);
    for part in &parts {
        out.push(UNIT_SEPARATOR);
        out.push_str(part);
    }
    Ok(out)
}

/// The fingerprint to send: `SHA-256` of [`canonical`], lowercase hex, always
/// 64 characters.
///
/// Pass the result as the `fingerprint` of
/// [`crate::Client::activate_machine`],
/// [`crate::Client::find_machine_by_fingerprint`], or a validation scope.
///
/// Feeding the *same* components in a different order, or with leading and
/// trailing ASCII whitespace, yields the same string; changing the case of a
/// value does not.
///
/// # Errors
///
/// As [`canonical`].
pub fn compute<I, L, V>(components: I) -> Result<String, FingerprintError>
where
    I: IntoIterator<Item = (L, V)>,
    L: AsRef<str>,
    V: AsRef<str>,
{
    const HEX: &[u8; 16] = b"0123456789abcdef";

    let canonical = canonical(components)?;
    let digest = Sha256::digest(canonical.as_bytes());

    // Written out rather than `write!`-formatted so there is no `fmt::Result`
    // to discard: a `let _ =` on a `#[must_use]` return is precisely the
    // silenced-error pattern this crate lints against.
    let mut hex = String::with_capacity(digest.len() * 2);
    for byte in digest {
        hex.push(HEX[usize::from(byte >> 4)] as char);
        hex.push(HEX[usize::from(byte & 0x0f)] as char);
    }
    Ok(hex)
}

/// Non-empty, ASCII printable `0x21..=0x7E`, and no `'='`.
///
/// `0x20` (space) is excluded by the range, as is `0x1F`, so a separator or a
/// space inside a label is caught here rather than needing its own check.
fn validate_label(label: &str) -> Result<(), FingerprintError> {
    if label.is_empty() {
        return Err(FingerprintError::EmptyLabel);
    }
    // `char::is_ascii_graphic` is exactly 0x21..=0x7E, so space (0x20) and the
    // unit separator (0x1F) are both excluded by it without their own checks.
    let valid = label.chars().all(|c| c.is_ascii_graphic() && c != '=');
    if !valid {
        return Err(FingerprintError::InvalidLabel {
            label: label.to_owned(),
        });
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    /// The one vector every other property is anchored to.
    const SINGLE: &str = "8edf2aef2de1f97d8c49b093cd789342003cc35132411010328db9c65ae47c21";

    #[test]
    fn canonical_uses_the_real_unit_separator_byte() {
        let c = canonical([("machine-id", "abc123")]).unwrap();
        assert_eq!(c, "tamga-fingerprint-v1\u{1f}machine-id=abc123");
        assert!(c.as_bytes().contains(&0x1f));
        // "<US>" in the fixture is a display placeholder, never literal text.
        assert!(!c.contains("<US>"));
    }

    #[test]
    fn compute_is_64_lowercase_hex_characters() {
        let fp = compute([("machine-id", "abc123")]).unwrap();
        assert_eq!(fp.len(), 64);
        assert!(fp
            .chars()
            .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));
        assert_eq!(fp, SINGLE);
    }

    #[test]
    fn component_order_does_not_change_the_fingerprint() {
        let sorted = compute([("disk", "SN-9"), ("machine-id", "abc123")]).unwrap();
        let unsorted = compute([("machine-id", "abc123"), ("disk", "SN-9")]).unwrap();
        assert_eq!(sorted, unsorted);
    }

    #[test]
    fn surrounding_ascii_whitespace_is_trimmed_not_rejected() {
        // Tab and newline are ASCII control characters; trimming must happen
        // first or this is a ControlCharacterInValue rejection instead.
        let padded = compute([("machine-id", "  abc123\t\n")]).unwrap();
        assert_eq!(padded, SINGLE);
    }

    #[test]
    fn interior_whitespace_is_preserved() {
        // Trimming is ends-only: an interior space is identity material.
        let a = compute([("name", "My Machine")]).unwrap();
        let b = compute([("name", "MyMachine")]).unwrap();
        assert_ne!(a, b);
    }

    #[test]
    fn unicode_whitespace_is_not_trimmed() {
        // `str::trim` would strip U+00A0 and make these equal. `trim_matches`
        // with the explicit ASCII set must not — the C11 port cannot
        // reproduce a Unicode White_Space table.
        let nbsp = compute([("machine-id", "\u{a0}abc123")]).unwrap();
        assert_ne!(nbsp, SINGLE);
    }

    #[test]
    fn case_is_preserved() {
        let upper = compute([("machine-id", "ABC123")]).unwrap();
        assert_ne!(upper, SINGLE);
        assert_eq!(
            upper,
            "d9515717e1662b5e24d33ddbc05839fb9c6a50f4704c537f43127e468cdad82a"
        );
    }

    #[test]
    fn sorts_case_sensitively_not_by_case_insensitive_collation() {
        // Uppercase 'Z' is 0x5A, lowercase 'a' is 0x61, so a byte comparison
        // puts "Z=..." first. Case-insensitive collation — what a
        // locale-aware sort typically does — puts "a" before "Z". That is a
        // real alternative ordering, and this rules it out.
        let c = canonical([("a", "1"), ("Z", "2")]).unwrap();
        assert_eq!(c, "tamga-fingerprint-v1\u{1f}Z=2\u{1f}a=1");
    }

    #[test]
    fn sorts_on_the_whole_component_not_on_the_label_alone() {
        // '-' is 0x2D and '=' is 0x3D, so over the whole `label=value`
        // component "a-b=y" sorts before "a=x". Sorting on the label alone
        // compares "a" against "a-b" and reverses them — the second ordering
        // that genuinely differs from the spec's.
        let c = canonical([("a", "x"), ("a-b", "y")]).unwrap();
        assert_eq!(c, "tamga-fingerprint-v1\u{1f}a-b=y\u{1f}a=x");
    }

    #[test]
    fn an_empty_value_still_contributes_its_label() {
        // A component that exists but reads empty is not an absent component.
        let empty = canonical([("machine-id", "")]).unwrap();
        assert_eq!(empty, "tamga-fingerprint-v1\u{1f}machine-id=");
        assert_ne!(compute([("machine-id", "")]).unwrap(), SINGLE);
    }

    #[test]
    fn equals_is_legal_in_a_value_and_splits_at_the_first_one() {
        let c = canonical([("path", "a=b=c")]).unwrap();
        assert_eq!(c, "tamga-fingerprint-v1\u{1f}path=a=b=c");
    }

    #[test]
    fn non_ascii_values_pass_through_as_utf8_bytes() {
        let c = canonical([("owner", "café")]).unwrap();
        assert_eq!(c, "tamga-fingerprint-v1\u{1f}owner=café");
        assert_eq!(
            compute([("owner", "café")]).unwrap(),
            "8a729bee74af4aeaf886d4584cc61bc8025d4bad3cce72441693e84e5c450739"
        );
    }

    #[test]
    fn nfc_and_nfd_spellings_are_deliberately_different() {
        // "café" precomposed (U+00E9) vs decomposed (e + U+0301). A port that
        // normalised would collapse these; none of the eight may. Documented
        // in the module doc comment, pinned here.
        let precomposed = compute([("owner", "caf\u{e9}")]).unwrap();
        let decomposed = compute([("owner", "cafe\u{301}")]).unwrap();
        assert_ne!(precomposed, decomposed);
    }

    #[test]
    fn accepts_owned_strings_and_borrowed_str_alike() {
        let owned = compute([(String::from("machine-id"), String::from("abc123"))]).unwrap();
        let borrowed = compute([("machine-id", "abc123")]).unwrap();
        assert_eq!(owned, borrowed);

        // A Vec of tuples is the shape a caller assembling components
        // conditionally ends up with.
        let v: Vec<(&str, String)> = vec![("machine-id", "abc123".to_string())];
        assert_eq!(compute(v).unwrap(), borrowed);
    }

    #[test]
    fn rejects_no_components() {
        let none: [(&str, &str); 0] = [];
        assert_eq!(canonical(none), Err(FingerprintError::NoComponents));
    }

    #[test]
    fn rejects_an_empty_label() {
        assert_eq!(canonical([("", "x")]), Err(FingerprintError::EmptyLabel));
    }

    #[test]
    fn rejects_a_duplicate_label() {
        assert_eq!(
            canonical([("id", "a"), ("id", "b")]),
            Err(FingerprintError::DuplicateLabel {
                label: "id".to_string()
            })
        );
    }

    #[test]
    fn rejects_a_duplicate_label_even_when_the_values_are_equal() {
        // Same value twice is still two components for one label; the set of
        // parts would silently collapse to one without the explicit check.
        assert!(matches!(
            canonical([("id", "a"), ("id", "a")]),
            Err(FingerprintError::DuplicateLabel { .. })
        ));
    }

    #[test]
    fn rejects_equals_in_a_label() {
        assert_eq!(
            canonical([("a=b", "x")]),
            Err(FingerprintError::InvalidLabel {
                label: "a=b".to_string()
            })
        );
    }

    #[test]
    fn rejects_the_separator_in_a_label() {
        assert!(matches!(
            canonical([("a\u{1f}b", "x")]),
            Err(FingerprintError::InvalidLabel { .. })
        ));
    }

    #[test]
    fn rejects_a_non_ascii_label() {
        assert!(matches!(
            canonical([("café", "x")]),
            Err(FingerprintError::InvalidLabel { .. })
        ));
    }

    #[test]
    fn rejects_a_space_in_a_label() {
        // 0x20 sits below the 0x21 floor, so it is caught by the range.
        assert!(matches!(
            canonical([("a b", "x")]),
            Err(FingerprintError::InvalidLabel { .. })
        ));
    }

    #[test]
    fn rejects_the_separator_in_a_value() {
        assert_eq!(
            canonical([("id", "a\u{1f}b")]),
            Err(FingerprintError::ControlCharacterInValue {
                label: "id".to_string()
            })
        );
    }

    #[test]
    fn rejects_a_control_character_in_a_value_rather_than_stripping_it() {
        assert!(matches!(
            canonical([("id", "a\u{7}b")]),
            Err(FingerprintError::ControlCharacterInValue { .. })
        ));
        // Had it been stripped, this would equal the clean spelling — two
        // different inputs on one seat.
        assert!(canonical([("id", "ab")]).is_ok());
    }

    #[test]
    fn rejects_del_in_a_value() {
        // 0x7F is a control character but sits above the 0x1F range.
        assert!(matches!(
            canonical([("id", "a\u{7f}b")]),
            Err(FingerprintError::ControlCharacterInValue { .. })
        ));
    }

    #[test]
    fn a_value_of_only_whitespace_trims_to_empty_and_is_accepted() {
        assert_eq!(
            canonical([("id", " \t\r\n")]).unwrap(),
            "tamga-fingerprint-v1\u{1f}id="
        );
    }

    #[test]
    fn error_display_escapes_a_control_character_in_the_label() {
        // Debug formatting, so a raw byte cannot be injected into a log line.
        let err = canonical([("a\u{1f}b", "x")]).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("\\u{1f}"), "{msg}");
        assert!(!msg.contains('\u{1f}'), "{msg}");
    }

    #[test]
    fn control_character_error_does_not_echo_the_value() {
        // The value is machine identity material; only the label is named.
        let err = canonical([("id", "secret\u{7}stuff")]).unwrap_err();
        let msg = err.to_string();
        assert!(msg.contains("id"));
        assert!(!msg.contains("secret"), "{msg}");
    }
}