CrypTagEncoder

Main CrypTagEncoder class providing high-level API for NTAG424 DNA operations. All operations are independent and do not cross-link, making the API simple and predictable.

Constructors

Constructor

new CrypTagEncoder(): CrypTagEncoder;

Create a new CrypTagEncoder instance. Initializes core components and operation handlers for NTAG424 DNA communication.

Returns

CrypTagEncoder

Properties

_connected

_connected: boolean;

---

_discovered

_discovered: boolean;

---

factory

factory: Factory;

---

keyManager

keyManager: KeyManager;

---

session

session: Session;

---

transport

transport: Transport;

Methods

authenticate()

authenticate(keyNo): Promise<EncoderResult<AuthenticateData>>;

Authenticate with tag using specified key number. Automatically detects EV2/LRP mode and retrieves key from KeyManager.

Parameters

keyNo

number

Key number to authenticate with (0-4)

Returns

Promise<EncoderResult<AuthenticateData>>

Result whose data holds the key number used, the authentication mode, and whether NonFirst auth was used.

---

changeFileSettings()

changeFileSettings(fileNo, options): Promise<EncoderResult<ChangeFileSettingsData>>;

Change file settings (access rights and communication mode). Supports both simple options and advanced configuration with optional SDM preservation.

Parameters

fileNo

number

File number: 1, 2, or 3

options

Settings options

changeAccess?

string | number

Change access: 0-4, ‘free’, or ‘never’

commMode?

string

Communication mode: ‘plain’, ‘mac’, or ‘full’

preserveSDM?

boolean

Preserve existing SDM configuration

rawHex?

string

Pre-built file-settings payload as a hex string; bypasses all other options when present

readAccess?

string | number

Read access: 0-4, ‘free’, or ‘never’

readWriteAccess?

string | number

Read/Write access: 0-4, ‘free’, or ‘never’

writeAccess?

string | number

Write access: 0-4, ‘free’, or ‘never’

Returns

Promise<EncoderResult<ChangeFileSettingsData>>

Result whose data holds the modified file number and the applied settings.

---

changeKeys()

changeKeys(): Promise<EncoderResult<ChangeKeysData>>;

Change all keys according to KeyManager configuration. Automatically compares and changes keys in sequence (keys 1-4 first, then Key 0).

Returns

Promise<EncoderResult<ChangeKeysData>>

Result whose data holds the per-key change results, the number of keys changed, and (unless there were none) an allSuccess flag.

---

clearFile()

clearFile(fileNo): Promise<EncoderResult<ClearFileData>>;

Clear a file by writing zeros with proper formatting. Automatically applies correct structure for each file type.

Parameters

fileNo

number

File number: 1=CC, 2=NDEF, 3=Proprietary

Returns

Promise<EncoderResult<ClearFileData>>

Result whose data holds a status message and the cleared file number.

---

configureFailedAuthLimit()

configureFailedAuthLimit(options?): Promise<EncoderResult<ConfigureFailedAuthLimitData>>;

Configure authentication failure counter limits. Protects against brute-force attacks by limiting failed authentication attempts (requires Key 0).

Parameters

options?

Authentication limit configuration

decreaseOnSuccess?

number

Counter decrement on success (1-65535)

enabled?

boolean

Enable or disable the feature

totalFailureLimit?

number

Max failures before blocking (1-65535)

Returns

Promise<EncoderResult<ConfigureFailedAuthLimitData>>

Result whose data holds the applied limit configuration.

---

configureTagTamper()

configureTagTamper(ttStatusKey?): Promise<EncoderResult<ConfigureTagTamperData>>;

Configure TagTamper feature (only on TagTamper variant tags). Sets up tamper detection access key (requires Key 0 authentication).

Parameters

ttStatusKey?

string | number

Key for GetTTStatus (0-4, or ‘free’ for free access)

Returns

Promise<EncoderResult<ConfigureTagTamperData>>

Result whose data holds the configured TagTamper status key.

---

connect()

connect(readerName?): Promise<EncoderResult<ConnectData>>;

Connect to NFC reader and card. Initializes communication with the reader and establishes connection to the NTAG424 DNA card.

Parameters

readerName?

string = null

Optional specific reader name to connect to.

Returns

Promise<EncoderResult<ConnectData>>

Result with the connected reader name and protocol.

---

createNDEFText()

createNDEFText(text, language?): Buffer;

Create NDEF message with text record.

Parameters

text

string

Text content to encode in NDEF format

language?

string = 'en'

Language code for the record

Returns

Buffer

Encoded NDEF message buffer with text record

Throws

E400 if text/language are not non-empty strings. (A local builder that returns a raw Buffer rather than a result object, so it throws on invalid input.)

---

createNDEFUrl()

createNDEFUrl(url): Buffer;

Create NDEF message with URL record.

Parameters

url

string

Complete URL to encode in NDEF format

Returns

Buffer

Encoded NDEF message buffer ready to write to tag

Throws

E400 if url is not a non-empty string. (A local builder that returns a raw Buffer rather than a result object, so it throws on invalid input.)

---

disableSDM()

disableSDM(fileNo?): Promise<EncoderResult<DisableSDMData>>;

Disable SDM (Secure Dynamic Messaging) on a file. Resets file to plain mode with default access rights and resets counter to zero.

Parameters

fileNo?

number = File.NDEF.FILE_NO

File number (default: 2 for NDEF)

Returns

Promise<EncoderResult<DisableSDMData>>

Result whose data holds the SDM state after the call ({ enabled: false }).

---

disconnect()

disconnect(): Promise<EncoderResult<DisconnectData>>;

Disconnect from card and reader. Ends authentication session, closes transport, and resets internal state.

Returns

Promise<EncoderResult<DisconnectData>>

Result whose data confirms the connection is closed (connected: false, reader/protocol null).

---

discoverTag()

discoverTag(): Promise<EncoderResult<DiscoverTagData>>;

Discover tag configuration and capabilities. Retrieves version info, file settings, access rights, and SDM configuration with results cached.

Returns

Promise<EncoderResult<DiscoverTagData>>

Result whose data holds the UID, randomUID flag, variant, version details, file settings, access rights, and SDM configuration.

---

enableLRP()

enableLRP(): Promise<EncoderResult<EnableLRPData>>;

Enable LRP (Leakage Resilient Primitive) authentication mode. LRP provides enhanced security against side-channel attacks (requires Key 0 in EV2 mode).

Returns

Promise<EncoderResult<EnableLRPData>>

Result whose data confirms LRP mode was enabled ({ configured: true }).

---

enableRandomUID()

enableRandomUID(): Promise<EncoderResult<EnableRandomUIDData>>;

Enable random UID generation mode. Tag generates a new random UID on each power-up; real UID requires GetCardUID with authentication.

Returns

Promise<EncoderResult<EnableRandomUIDData>>

Result whose data confirms Random UID was enabled ({ configured: true }).

---

encodeTag()

encodeTag(profile, params?): Promise<EncoderResult<EncodeTagData>>;

Encode tag with a specific SDM security profile. High-level method that configures the tag for Secure Dynamic Messaging (plain/encrypted/full).

Parameters

profile

string

SDM profile: ‘plain’, ‘encrypted’, or ‘full’

params?

Encoding parameters

compressed?

boolean

Use compressed URL format without parameter names (shorter URLs)

counterLimit?

number

Counter limit after which SDM stops incrementing (1-16777215)

enableTTStatus?

boolean

Enable TagTamper status mirroring (full profile only, TagTamper variant only)

encSize?

number

Encrypted file-data field length in hex chars (32, 64, or 128 → 16/32/64 bytes of file data)

fileData?

string

Static data for the ‘full’ profile: a plain (UTF-8) string, space-padded to encSize/2 bytes before encryption

ndefType?

string

NDEF type: ‘url’ or ‘text’

resetCounter?

boolean

Reset SDM counter to zero before encoding

sdmSettings?

SDMSettingsOverride

Custom SDM access rights override (advanced)

url?

string

URL for NDEF (required if ndefType=‘url’; ignored for ‘text’, which builds its own JSON)

Returns

Promise<EncoderResult<EncodeTagData>>

Result whose data holds the applied SDM profile, compression flag, placeholder pattern, counter limit, and custom SDM settings.

---

exportKeyConfig()

exportKeyConfig(fileName): Promise<EncoderResult<ExportKeyConfigData>>;

Export complete KeyManager configuration to JSON file. Exports all current and target keys with master keys, diversification settings, and key versions.

Parameters

fileName

string

Filename for the export (e.g., ‘keys’)

Returns

Promise<EncoderResult<ExportKeyConfigData>>

Result whose data holds a status message, the exported file path, filename, location, and file size.

---

formatTag()

formatTag(): Promise<EncoderResult<FormatTagData>>;

Format tag to factory defaults. Clears all files, disables SDM, restores default settings, and resets all keys to 00…00.

Returns

Promise<EncoderResult<FormatTagData>>

Result whose data holds the detailed operation list.

---

generateRandomKey()

generateRandomKey(): string;

Generate a cryptographically secure random 128-bit AES key. Uses Node.js crypto.randomBytes for high-quality randomness.

Returns

string

Random key in uppercase hex format (32 characters = 16 bytes)

---

generateRandomKeySet()

generateRandomKeySet(): object;

Generate complete set of 5 random 128-bit AES keys. Useful for provisioning new tags with unique keys.

Returns

object

Object with 5 random keys: { 0: ’…’, 1: ’…’, …, 4: ’…’ }

---

getApplicationId()

getApplicationId(): string;

Get global application ID.

Returns

string

Global application ID

---

getCardUID()

getCardUID(): Promise<EncoderResult<GetCardUIDData>>;

Get card UID (Unique Identifier). Returns the real 7-byte UID, even if random UID mode is enabled.

Returns

Promise<EncoderResult<GetCardUIDData>>

Result whose data holds the tag’s real 7-byte UID in hex.

---

getCounter()

getCounter(): Promise<EncoderResult<GetCounterData>>;

Get SDM counter value. Requires SDM to be enabled and configured, handling authentication automatically.

Returns

Promise<EncoderResult<GetCounterData>>

Result whose data holds the SDM counter value and the queried file number.

---

getCurrentKey()

getCurrentKey(keyNo): Promise<string | EncoderResult<any>>;

Get current key in hex format (key on tag). Applies diversification if configured and UID provided.

Parameters

keyNo

number

Key number (0-4)

Returns

Promise<string | EncoderResult<any>>

Key hex (32 chars), null if not set, or a failure result ({ success:false, error:{ code, message, details? } }) — E400 if keyNo is invalid, or the connection/discovery error if the tag is not connected/discovered.

---

getCurrentKeys()

getCurrentKeys(): object;

Get current keys.

Returns

object

Current keys object

---

getFileSettings()

getFileSettings(fileNo): Promise<EncoderResult<GetFileSettingsData>>;

Get file settings and configuration. Returns communication mode, access rights, and SDM configuration.

Parameters

fileNo

number

File number (1, 2, or 3)

Returns

Promise<EncoderResult<GetFileSettingsData>>

Result whose data holds the file’s configuration (access rights, communication mode, and SDM settings).

---

getKeyChangePlan()

getKeyChangePlan(uid?): Promise<EncoderResult<GetKeyChangePlanData>>;

Get key change plan showing which keys need changing. Compares current and target keys and returns detailed change plan.

Parameters

uid?

string = null

Tag UID for diversified keys (14 hex characters)

Returns

Promise<EncoderResult<GetKeyChangePlanData>>

Result whose data holds the per-key change plan comparing current and target keys with willChange flags.

---

getKeyVersion()

getKeyVersion(keyNo?): Promise<EncoderResult<GetKeyVersionData>>;

Get key version for a specific key. Returns the version byte (0-255) of the specified key, requiring authentication with Key 0.

Parameters

keyNo?

number = AccessRight.KEY_0

Key number to query (0-4)

Returns

Promise<EncoderResult<GetKeyVersionData>>

Result whose data holds the queried key number and its version byte.

---

getReaders()

getReaders(): Promise<EncoderResult<GetReadersData>>;

Get the list of available NFC readers. Scans for connected PC/SC readers and checks for card presence.

Returns

Promise<EncoderResult<GetReadersData>>

Result with the list of detected readers.

---

getStatus()

getStatus(): GetStatusData;

Get comprehensive status of all SDK components. Provides complete snapshot of connection, authentication, and configuration state.

Returns

GetStatusData

Status object containing:

• connected: Boolean - PC/SC connection active
• discovered: Boolean - Tag discovery completed
• authenticated: Boolean - Authentication session active
• authKey: Number|null - Currently authenticated key number
• transport: Object - Transport layer status (reader info, protocol)
• session: Object - Session status (mode, counters, cache)
• keyManager: Object - KeyManager status (key config, diversification)

---

getSystemIdentifier()

getSystemIdentifier(): string;

Get global system identifier.

Returns

string

Global system identifier

---

getTargetKey()

getTargetKey(keyNo): Promise<string | EncoderResult<any>>;

Get target key in hex format (desired key after change). Applies diversification if configured and UID provided.

Parameters

keyNo

number

Key number (0-4)

Returns

Promise<string | EncoderResult<any>>

Target key hex (32 chars), null if not set, or a failure result ({ success:false, error:{ code, message, details? } }) — E400 if keyNo is invalid, or the connection/discovery error if the tag is not connected/discovered.

---

getTargetKeys()

getTargetKeys(): object;

Get target keys.

Returns

object

Target keys object

---

getTTStatus()

getTTStatus(keyNo?): Promise<EncoderResult<GetTTStatusData>>;

Get TagTamper status (only on TagTamper variant tags). Returns current and permanent tamper detection states.

Parameters

keyNo?

number = AccessRight.KEY_0

Key number to authenticate with

Returns

Promise<EncoderResult<GetTTStatusData>>

Result whose data holds the permanent and current tamper states, the tamperDetected and featureConfigured flags, and the raw status bytes.

---

importKeyConfig()

importKeyConfig(fileName): Promise<EncoderResult<ImportKeyConfigData>>;

Import KeyManager configuration from JSON file. Loads configuration from exported JSON file and validates structure.

Parameters

fileName

string

Filename to import (e.g., ‘keys’)

Returns

Promise<EncoderResult<ImportKeyConfigData>>

Result whose data holds a status message, the imported file path, filename, location, file metadata, and configuration status.

---

isAuthenticated()

isAuthenticated(): boolean;

Check if authenticated with the tag. Returns true if an active authentication session exists.

Returns

boolean

True if authenticated (session keys valid)

---

isConnected()

isConnected(): boolean;

Check if currently connected to a card.

Returns

boolean

True if PC/SC connection established and card present

---

isDiscovered()

isDiscovered(): boolean;

Check if tag discovery has been completed. Discovery reads version, file settings, and access rights.

Returns

boolean

True if discovery completed and cached

---

loadFactoryDefaults()

loadFactoryDefaults(): EncoderResult<LoadFactoryDefaultsData>;

Load factory default keys (all 00…00). Resets KeyManager to factory defaults for all 5 keys.

Returns

EncoderResult<LoadFactoryDefaultsData>

Result confirming the KeyManager was reset to factory defaults, with a status message.

---

loadKeyConfig()

loadKeyConfig(config): EncoderResult<LoadKeyConfigData>;

Load complete key configuration. Sets up current keys (on tag) and target keys (desired) for all 5 keys.

Parameters

config

Configuration object

applicationId?

string

Global application ID

currentKeys?

{ }

Current keys on tag {keyNo: {masterKey, diversify, …}}

systemIdentifier?

string

Global system ID for diversification

targetKeys?

{ }

Target keys for key change {keyNo: {masterKey, diversify, keyVersion, …}}

Returns

EncoderResult<LoadKeyConfigData>

Result whose data holds the loaded key configuration (currentKeys, targetKeys, systemIdentifier, applicationId).

---

readCapabilityContainer()

readCapabilityContainer(): Promise<EncoderResult<ReadCapabilityContainerData>>;

Get and parse Capability Container (CC) from file 1. Returns detailed information about NDEF and Proprietary file access rights.

Returns

Promise<EncoderResult<ReadCapabilityContainerData>>

Result whose data holds the raw CC data, length, mapping version, max read/write sizes, and the NDEF and proprietary file configurations.

---

readFile()

readFile(
   fileNo,
   offset?,
length?): Promise<EncoderResult<ReadFileData>>;

Read raw file data at specified offset and length. Lower-level method for direct file access with automatic authentication.

Parameters

fileNo

number

File number (1=CC, 2=NDEF, 3=Proprietary)

offset?

number = 0

Byte offset to start reading from (0-based)

length?

number = 256

Number of bytes to read (max 256 per operation)

Returns

Promise<EncoderResult<ReadFileData>>

Result whose data holds the raw file data buffer, file number, offset, length read, and read mode.

---

readNDEF()

readNDEF(): Promise<EncoderResult<ReadNDEFData>>;

Read NDEF content from file 2. Automatically handles authentication and parses NDEF records.

Returns

Promise<EncoderResult<ReadNDEFData>>

Result whose data holds the empty flag, raw and parsed NDEF message data, record list and count, length, extracted URL/text, and any SDM parameters.

---

readProprietary()

readProprietary(): Promise<EncoderResult<ReadProprietaryData>>;

Read proprietary data from file 3. Handles authentication and parses the proprietary file format.

Returns

Promise<EncoderResult<ReadProprietaryData>>

Result whose data holds the data buffer, decoded text, hex representation, length, empty flag, and complete raw file data.

---

readTag()

readTag(): Promise<EncoderResult<ReadTagData>>;

Read comprehensive tag information. Performs discovery, NDEF read, counter read, and returns complete tag state.

Returns

Promise<EncoderResult<ReadTagData>>

Result whose data holds complete tag state including UID, variant, tamper status, capabilities, authentication info, version, file settings, access rights, SDM config, counter, and NDEF content.

---

refreshReaders()

refreshReaders(): Promise<EncoderResult<RefreshReadersData>>;

Refresh reader list and update card presence status. Useful for detecting newly inserted/removed cards or readers.

Returns

Promise<EncoderResult<RefreshReadersData>>

Result whose data holds the updated list of detected readers.

---

resetSession()

resetSession(): void;

Reset session state (authentication and discovery cache). Call when a tag is removed or swapped to ensure the next operation starts with a fresh discovery cycle.

Returns

void

---

setApplicationId()

setApplicationId(applicationId): EncoderResult<any>;

Set global application ID for diversified keys.

Parameters

applicationId

string

Application ID (6 hex chars, 3 bytes)

Returns

EncoderResult<any>

Result confirming the global application ID was set.

---

setCurrentKey()

setCurrentKey(keyNo, config): EncoderResult<SetCurrentKeyData>;

Set current key directly in hex format. Updates the key that’s currently stored on the tag for authentication operations.

Parameters

keyNo

number

Key number (0-4)

config

KeyConfigInput

Key configuration { masterKey, diversify, … }

Returns

EncoderResult<SetCurrentKeyData>

Result whose data holds the key type, key number, and full key configuration.

---

setKeysetsFolder()

setKeysetsFolder(folderPath): EncoderResult<any>;

Set the base folder for keyset import/export files. Pass an absolute path to decouple keyset persistence from the process CWD (recommended for desktop apps, e.g. an Electron userData directory).

Parameters

folderPath

string

Base folder for keyset files

Returns

EncoderResult<any>

Result confirming the keyset import/export base folder was set.

---

setSystemIdentifier()

setSystemIdentifier(systemIdentifier): EncoderResult<any>;

Set global system identifier for diversified keys.

Parameters

systemIdentifier

string

System ID (ASCII string, max 8 characters)

Returns

EncoderResult<any>

Result confirming the global system identifier was set.

---

setTargetKey()

setTargetKey(keyNo, config): EncoderResult<SetTargetKeyData>;

Set target key for key change operation. Defines the desired key after changeKeys() is called.

Parameters

keyNo

number

Key number (0-4)

config

KeyConfigInput

Key configuration { masterKey, diversify, keyVersion, … }

Returns

EncoderResult<SetTargetKeyData>

Result whose data holds the key type, key number, and full key configuration.

---

verifyKeys()

verifyKeys(): Promise<EncoderResult<VerifyKeysData>>;

Verify the current key configuration by authenticating all keys. Tests authentication with all 5 keys and reports which keys work.

Returns

Promise<EncoderResult<VerifyKeysData>>

Result whose data holds the per-key authentication results (keys 0-4 with success and key version) and the authentication mode used.

---

verifySignature()

verifySignature(): Promise<EncoderResult<VerifySignatureData>>;

Read and verify NTAG424 DNA originality signature. Proves the chip is genuine NXP hardware using ECDSA secp224r1 cryptography.

Returns

Promise<EncoderResult<VerifySignatureData>>

Result whose data holds the verified flag and the full ECDSA signature (hex).

---

writeCapabilityContainer()

writeCapabilityContainer(options?): Promise<EncoderResult<WriteCapabilityContainerData>>;

Set Capability Container (CC) with custom access rights. Defines access requirements for NDEF and Proprietary files (NFC Forum Type 4 Tag compliance).

Parameters

options?

Access rights configuration

ndefRead?

string | number

NDEF read access (0-4, ‘free’, ‘never’)

ndefWrite?

string | number

NDEF write access (0-4, ‘free’, ‘never’)

proprietaryRead?

string | number

Proprietary read access (0-4, ‘free’, ‘never’)

proprietaryWrite?

string | number

Proprietary write access (0-4, ‘free’, ‘never’)

Returns

Promise<EncoderResult<WriteCapabilityContainerData>>

Result whose data holds the file number written and the applied NDEF and proprietary access rights.

---

writeNDEF()

writeNDEF(ndefData): Promise<EncoderResult<WriteNDEFData>>;

Write NDEF data directly to file 2 (without SDM encoding). Supports both Buffer and string input, requiring appropriate authentication.

Parameters

ndefData

any

NDEF message data to write

Returns

Promise<EncoderResult<WriteNDEFData>>

Result whose data holds the file number written, offset, bytes written, write mode, and chunking details.

---

writeProprietary()

writeProprietary(proprietaryData): Promise<EncoderResult<WriteProprietaryData>>;

Write proprietary data to file 3. Formats as UTF-8 text with an automatic 2-byte length prefix (no padding).

Parameters

proprietaryData

any

Text data to write (max 126 bytes)

Returns

Promise<EncoderResult<WriteProprietaryData>>

Result whose data holds the file number written, offset, bytes written, and write mode.