Skip to main content

Crate ntag424

Crate ntag424 

Source
Expand description

A transport-agnostic crate for communicating with NTAG 424 DNA NFC tags.

An opinionated use case is provided through the high_level module. This provides a convenient abstraction for tag provisioning and SDM verification, without needing to work with low-level commands directly.

§High level hardware overview

The NTAG 424 DNA is a NFC chip that can generate cryptographically signed or encrypted identifiers on the fly, readable by standard NFC readers. This allows to uniquely identify a tag while verifying its authenticity, which is useful for anti-counterfeiting and authentication where it is important to not just have a tag with a unique identifier, but also to be able to verify that the tag is genuine and not a clone. The cryptography is based on AES-128 operations and has preventions against side-channel and replay attacks.

The chip utilizes a file system with configurable access permissions through keys stored on chip. It stores three files:

  1. The NFC Capability Container (CC) file, which describes the tag’s capabilities. This file is mostly static.
  2. A 256 byte long file containing data using the NFC Data Exchange Format (NDEF). This file can have dynamically computed data inserted by the tag and is read by standard NFC readers.
  3. A 128 byte long file, called proprietary file, containing raw data free for an application to use.

Furthermore, the tag stores a set of five application defined AES-128 keys1, numbered 0 to 4, with the key 0 being the Application Master Key. The master key is needed to change any of the keys and to configure the tag.

For each file one can configure read and write permissions, either using a key or allowing free, unauthenticated access.

Default access permissions out of the factory:

FileRead OnlyWrite OnlyRead / WriteChange file settings
CCUnauthenticatedMaster KeyMaster KeyMaster Key
NDEFUnauthenticatedUnauthenticatedUnauthenticatedMaster Key
ProprietaryKey 2Key 3Key 3Master Key

Default keys out of the factory: all keys are set to constant zero.

§Secure Unique NFC (SUN) using Secure Dynamic Messaging (SDM)

The NDEF file can define placeholders that are dynamically filled by the tag when read. This is called Secure Dynamic Messaging (SDM) and is configured through the file settings of the NDEF file. Typically the NDEF encodes a URL with placeholders for the tag’s unique identifier, and counter, usually encrypted and signed using one of the application keys, as well as a MAC.

This allows the tag to provide a Secure Unique NFC (SUN) identifier that can be used for cases where a identifier fulfilling cryptographic properties is needed, e.g. for anti-counterfeiting, authentication, or access control.

By default the NDEF file is readable without authentication through standard NFC Type 4 commands allowing many NFC readers to read the SUN identifier without special support for the tag’s cryptographic features. However, the NDEF file can also be configured to require authentication through one of the AES keys for reading.

§Example: what a reader sees

The snippet below builds an NDEF file from a URL template and shows the bytes written to the tag. Requires the sdm and alloc features.

use ntag424::types::file_settings::CryptoMode;

let (ndef, _sdm) = ntag424::sdm_url_config!(
    "https://example.com/?p={picc}&m={mac}",
    CryptoMode::Aes,
);

// The first 7 bytes are the NDEF Type 4 wrapper (2-byte NLEN + short record
// header for a URI payload with the "https://" prefix code 0x04). The URI
// body follows, with `{picc}` filled with 32 ASCII zeros (placeholder for
// 16 bytes of encrypted PICCData, ASCII-doubled) and `{mac}` with 16 ASCII
// zeros (placeholder for the 8-byte truncated CMAC).
assert_eq!(&ndef[..7], &[0x00, 0x47, 0xD1, 0x01, 0x43, 0x55, 0x04]);
assert_eq!(
    &ndef[7..],
    b"example.com/?p=00000000000000000000000000000000&m=0000000000000000",
);

When a standard NFC reader performs an unauthenticated read, the tag returns the same bytes but with the placeholders replaced by freshly computed values2, e.g.:

https://example.com/?p=EF963FF7828658A599F3041510671E88&m=94EED9EE65337086

§Provisioning

All keys should be replaced before deployment and the NDEF file should be locked down with appropriate permissions. Check the provisioning example in the repository.

The implementation of the tag’s initial setup should be carefully designed to match the application’s needs. The following list contains steps that should be considered for a secure setup of the tag.

  • Generate and store strong random keys for all five application keys. You may use key diversification to derive keys from a single master key if needed. Access to those keys should be carefully controlled.
  • Review the tag configuration.
  • If SUN identifiers are needed, prepare the NDEF file:
    • Write the NDEF file with the desired template, e.g. a URL with placeholders. Maybe the sdm_url_config! macro can be used.
    • Enable SDM via the file settings for the NDEF file, also configure the file permissions and cryptographic settings in this step.
  • Prepare the proprietary file if needed, write an initial content, and configure the file’s permissions.

For a complete, runnable provisioning tool using a real PC/SC transport, see examples/provision/ in the repository. examples/verification/ is a companion that reads the provisioned config and verifies SDM-signed tag taps against it.

§Binary size

Recommendations if binary size is a concern:

  1. Skip originality verification. The Session::verify_originality function pulls in p224 + crypto-bigint + sha2 (~150 KB pre-link). If you do not need to verify originality, simply do not call this function and the linker has a chance to remove the related code.

  2. Enable LTO. Add to your .cargo/config.toml or Cargo.toml:

    [profile.release]
lto = true
opt-level = "s"   # or "z" for smallest
codegen-units = 1

    These settings are what make dead-code elimination effective across crate boundaries.

  3. Disable the alloc feature if you have no heap. The feature only gates Vec-returning wrappers; all core protocol logic and the *_into in-place variants remain available.

§Sources

The following sources were used to implement this crate. Section numbers cited throughout the docstrings (e.g. “§5.16”, “§8.2.3.2”) are anchors into these PDFs, so you can jump straight to the relevant passage.

Integration tests use a mock transport that simulates the tag’s responses, and are based on the above sources, using either test vectors or collected responses from real hardware tags. Unit tests use the same sources.

No tags were harmed during development of this crate.

  1. There are also the NDA protected originality keys used for originality verification. ↩

  2. The p= value contains the encrypted tag identity and m= is the truncated CMAC. A server can decrypt and verify these values; see sdm::Verifier. ↩

Re-exports§

pub use types::Access;
pub use types::AccessRights;
pub use types::CommMode;
pub use types::Configuration;
pub use types::File;
pub use types::FileSettingsUpdate;
pub use types::FileSettingsView;
pub use types::KeyNumber;
pub use types::NonMasterKeyNumber;
pub use types::TagTamperStatus;
pub use types::TagTamperStatusReadout;
pub use types::Uid;
pub use types::Version;

Modules§

high_levelhigh-level-api
High-level, opinionated API for provisioning and using the NTAG 424 DNA.
key_diversificationkey-diversification
AES-128 key diversification per AN10922 §2.2.
sdmsdm
Secure Dynamic Messaging (SDM) server-side verification (§9.3).
types
Types encoding information sent to or received from NTAG 424 DNA tags.

Macros§

sdm_url_configsdm
Create SDM configuration from a URL template string.

Structs§

Response
A response to an APDU command, containing the data and the status words.
Session
An NTAG 424 DNA session.

Enums§

EncryptedSession
A session in an authenticated state, with the session suite erased.
SessionError

Traits§

AuthenticatedSession
Value semantics and command-counter safety
SessionSuite
Post-authentication cipher suite driving NT4H2421Gx Secure Messaging.
Transport
A raw APDU-level transport. The implementor handles framing, the NFC layer, USB HID (e.g. ACR1252U), or any other physical channel.

Type Aliases§

UnauthenticatedSession