Skip to content

Commit 419a733

Browse files
authored
docs: document verify-sdm-mac usage (#47)
2 parents 7cbd5f1 + c1cc671 commit 419a733

1 file changed

Lines changed: 57 additions & 0 deletions

File tree

README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,63 @@ shell history, terminal logging, or process listings visible to other local
8383
users. Avoid using real production keys this way; prefer a safer secret input
8484
mechanism if one is available in your environment.
8585

86+
Verify an NTAG 424 DNA SDM MAC from mirrored URL data:
87+
88+
```bash
89+
schnee ntag verify-sdm-mac \
90+
--signed-text "example.com/t?uid=044C2F82322190&ctr=250000&mac=" \
91+
--mac 260d8310beb0e062 \
92+
--sdm-key-hex 00112233445566778899aabbccddeeff \
93+
--uid 044C2F82322190 \
94+
--counter 250000
95+
```
96+
97+
When the tag stored the URI record without NDEF URI compression, keep the
98+
default `--ndef-prefix no_prefix` and pass `--signed-text` exactly as it was
99+
mirrored.
100+
101+
When the tag stored the URI record with an NDEF URI Identifier Code such as
102+
`https` (which expands to `https://`), pass that token through
103+
`--ndef-prefix`. The verifier removes the expanded prefix from `signed_text`
104+
before MAC calculation only when both of the following are true:
105+
106+
- the selected `--ndef-prefix` expands to a non-empty prefix such as
107+
`https://`
108+
- `--signed-text` starts with that expanded prefix
109+
110+
This means `signed_text` may include the display prefix copied from the tag
111+
scan, or it may already be prefix-normalized. Both are accepted as long as
112+
`--ndef-prefix` matches the URI Identifier Code used when the URL was stored.
113+
114+
For a tag that used compressed `https://` storage, these two commands verify
115+
the same signed bytes:
116+
117+
```bash
118+
schnee ntag verify-sdm-mac \
119+
--signed-text "https://example.com/t?uid=044C2F82322190&ctr=250000&mac=" \
120+
--mac 260d8310beb0e062 \
121+
--sdm-key-hex 00112233445566778899aabbccddeeff \
122+
--uid 044C2F82322190 \
123+
--counter 250000 \
124+
--ndef-prefix https
125+
```
126+
127+
```bash
128+
schnee ntag verify-sdm-mac \
129+
--signed-text "example.com/t?uid=044C2F82322190&ctr=250000&mac=" \
130+
--mac 260d8310beb0e062 \
131+
--sdm-key-hex 00112233445566778899aabbccddeeff \
132+
--uid 044C2F82322190 \
133+
--counter 250000 \
134+
--ndef-prefix https
135+
```
136+
137+
If you provide `--uid` or `--counter`, those bytes must match the tag's SDM
138+
configuration and the mirrored URL contents. In particular, `--counter` expects
139+
3 mirrored bytes as 6 hex characters in URL order, and the mirrored `ctr=`
140+
value inside `--signed-text` should use that same hex representation. The
141+
verifier handles the NTAG 424 DNA counter byte-order conversion internally.
142+
86143
## Python API
87144

88145
The stable Python entry points currently exposed by the package are the service

0 commit comments

Comments
 (0)