Aliro is an access credential standard developed by the Connectivity Standards Alliance that lets devices present credentials over NFC or BLE + UWB to open doors or authenticate with compatible access systems.

This protocol is based on PKI, with readers and devices performing mutual authentication using public keys and certificates (currently ECDSA), also enabling offline-native credential sharing and revocation.
Endpoints that have recently completed mutual authentication can reuse the persistent secure context to speed up repeated authentications with symmetric cryptography.
To preserve privacy, device endpoints withhold identifying data until a reader is authenticated and a secure channel is established.

Aliro commands use ISO7816 APDUs over NFC and BLE and largely follow UnifiedAccess protocols such as CCC CarKey and Apple HomeKey, but with different cryptography, command parameters, and some expanded capabilities:

Running these commands moves the credential-holder endpoint through the following states:

_{Deselection or Control Flow is possible in all states, so it is not displayed in the diagram.}

Aliro secure messaging uses directional AES-GCM keys and per-direction counters.
Channel keys are derived during authentication and then reused by EXCHANGE, ENVELOPE, and GET RESPONSE.

Aliro uses three secure channels with different keys and independent state:

• NFC Exchange
• BLE Exchange
• StepUp

Each channel uses a reader/device key pair generated as a result of AUTH0 or AUTH1.

• Reader encrypts outbound command payload with the channel's SKReader.
• Endpoint encrypts outbound response payload with the channel's SKDevice.
• Reader decrypts inbound responses with SKDevice; endpoint decrypts inbound commands with SKReader.
• Counters are maintained per direction and incremented after each encrypted message.
• If a response returns 61xx, use GET RESPONSE to collect remaining encrypted chunks before final payload processing.

Example (Python pseudocode):

This is an initial command used to select the Aliro applet and receive capability information from the device endpoint.

Data is formatted as a BER-TLV object:

• Tag 5C is an array of 2-byte values indicating supported protocol versions:
  • 0100 - 1.0;
  • 0009 - 0.9.
• Tag 80 lists the medium type; mobile devices use value 0000;
• Tag 7F66 lists additional capabilities declared by the device endpoint manufacturer as a list of 02 tags.

The full FCI template is used as input for cryptographic operations in later steps to ensure the reader is informed about the device's full capability set.

This command is used to exchange ephemeral keys between the device and the reader, with an optional ability to expedite authentication using persistent context.

Data is formatted as an array of BER-TLV values:

• Tag 41 encodes transaction flags:
  • 00 Skip FAST authentication, proceeding to STANDARD;
  • 01 Attempt FAST authentication;
• Tag 42 encodes transaction code or action:
  • 00 - Unlock;
  • 01 - Lock.
• Tag 87 contains uncompressed reader ephemeral key;
• Tag 4C holds a transaction identifier, which serves as a per-transaction nonce;
• Tag 4D contains the reader identifier, which consists of the reader group identifier (first 16 bytes) and the reader instance identifier (last 16 bytes).

Data is formatted as an array of BER-TLV values:

• Tag 86 contains uncompressed device ephemeral key;
• Tag 9D is present only if FAST authentication flow was indicated in request tag 41 and contains authenticated cryptogram data tied to the context established with this reader during previous communication sessions. In case this context is lost, or it is a first authentication attempt, the device returns bogus data here to preserve privacy.

To validate tag 9D, the reader attempts cryptogram decryption by deriving FAST key material from transaction data for each provisioned endpoint's persistent key in memory, until a match is found, or the list is exhausted.

Cryptogram-verification keying material is derived directly with HKDF-SHA256 using:

• Endpoint persistent key as IKM
• Serialized shared data as salt
• Endpoint ephemeral key X as info.

The output keying material is used to derive the following keys:

• Cryptogram SK
• Exchange SK Reader
• Exchange SK Device
• Bluetooth SK Reader
• Bluetooth SK Device
• UWB Ranging SK

StepUp channel keys are not generated with AUTH0, continuing the auth flow to AUTH1 is required in that case.

Example (Python pseudocode):

Using the derived cryptogram_sk, reader can attempt to decrypt the cryptogram using AES-GCM with zero-IV:

Successful decryption equals successful authentication, thanks to AES-GCM's authenticated encryption mode.

Decrypted cryptogram is formatted as BER-TLV and contains the following tags:

In installations with multiple reader systems, each reader sub-group may be provisioned with a custom key signed by a master reader group key. This command lets the reader provide the device endpoint with a certificate to enable use of a delegated key.

Data is formatted as an ASN.1 object:

For signature validation, the certificate is decompressed into an X.509 DER form by assigning tags to fields in the following fashion:

• serialNumber: 80;
• issuer:
  • commonName: 81.
• validity:
  • notBefore: 82;
  • notAfter: 83.
• subject:
  • commonName: 84.
• subjectPublicKeyInfo: 85;
• signature: 86.

Reader generates a signature over the data exchanged previously and presents it to the device.
In case of a successful verification, a secure context is established between the reader and the device, and the device returns an encrypted response containing its own signature over the common data.

Data is formatted as an array of BER-TLV values:

• Tag 41 encodes transaction flags:
  • 00 Endpoint identifier will be returned in response;
  • 01 Endpoint Public Key will be returned in response.
• Tag 9E contains a signature over the common transaction data.

Reader signature input is constructed as a BER-TLV sequence, then signed with ECDSA over SHA-256.

The reader signs the serialized preimage using ECDSA with SHA-256, encodes the signature as raw r || s (32 + 32 = 64 bytes), and places the resulting 64-byte value into command tag 9E.

Example (Python pseudocode):

To generate secure channel keys, the following shared data is assembled from transaction information:

Shared key is generated by performing ECDH with reader and endpoint ephemeral keys, then an intermediate key is derived with X9.63 KDF using transaction identifier as shared info.

Secure-channel keying material is derived with HKDF-SHA256 using:

• Intermediate key as IKM
• Serialized shared data as salt
• Endpoint ephemeral key X as info.

That keying material is used to derive the following keys:

• Exchange SK Reader
• Exchange SK Device
• StepUp SK Reader
• StepUp SK Device
• Bluetooth SK Reader
• Bluetooth SK Device
• UWB Ranging SK

Example (Python pseudocode):

Based on the exchanged data, a secure context is established between the device and the reader.

Data is formatted as an array of BER-TLV values:

• Tag 4E contains part of the device identifier; it is only sent if requested in tag 41;
• Tag 5A contains the long-term device public key; it is only sent if requested in tag 41;
• Tag 9E contains a signature over the common transaction data;
• Tag 5E contains authentication status;
• Tag 91 contains the credential issuance date.

Device signature verification input is constructed as a BER-TLV sequence:

Example (Python pseudocode):

After AUTH1 response decryption and signature verification succeed, the endpoint persistent key is derived from the AUTH1 intermediate key and stored for subsequent AUTH0 FAST attempts.

Persistent key material is derived with HKDF-SHA256 using:

• AUTH1 intermediate key (derived_key) as IKM
• Serialized shared data as salt
• Endpoint ephemeral key X as info.

If AUTH1 is not run again for a given endpoint, that endpoint's stored persistent key remains unchanged.

Example (Python pseudocode):

Using the secure channel established in AUTH0 or AUTH1, the reader may read arbitrary data from, or write arbitrary data to, the endpoint's mailbox.

Data sent by the reader is wrapped in a single top-level TLV container with tag BA.
The container value is a request object that describes a list of operations to perform with a mailbox:

• Tag 87 - read data, consisting of 4 bytes and returning 2 + [LENGTH] bytes:
  • OFFSET_HI;
  • OFFSET_LO;
  • LENGTH_HI;
  • LENGTH_LO.
• Tag 8A - write data, consisting of 2 + [LENGTH] bytes:
  • OFFSET_HI;
  • OFFSET_LO;
  • [data].
• Tag 95 - set data, which sets all bytes in the range to the given value; consists of 5 bytes:
  • OFFSET_HI;
  • OFFSET_LO;
  • LENGTH_HI;
  • LENGTH_LO;
  • SET_TO_VALUE.
• Tag 8C - indicates whether this is the last command in the atomic session:
  • 00: last command;
  • 01: more commands pending.

After secure-channel decryption, EXCHANGE response plaintext is:

• READ_RESULTS contains zero or more read result entries;
• trailing 00 02 indicates a fixed 2-byte status field length;
• STATUS_HI/STATUS_LO is the operation-batch result code.

Read result entries are appended in request order, each in the following format:

In current implementation, tags 8A (write) and 95 (set) do not append per-operation bytes to the response payload.

When EXCHANGE returns 61 00, the reader should continue with GET RESPONSE and append returned chunks until 90 00.

Observed status codes:

This command allows a reader to notify the device about the state or result of the transaction for UX purposes.

Data is formatted as an array of BER-TLV values:

Tags 41 and 42 mirror the meaning of the same tags in AUTH0 and AUTH1. Tag 43 is optional and provides additional information to the device.

This command is used after the primary flow has completed in order to retrieve attestation or revocation certificates from the device.

FCI template value is similar to the one returned by the SELECT ALIRO PRIMARY APPLET command.

This command is used by the reader to request attestation and revocation certificates from the device using the established secure channel.

Command data is wrapped in a top-level BER-TLV tag 53.
The value of tag 53 is a CBOR object that carries encrypted request bytes in the data field.

When SW1=61, the reader should continue with GET RESPONSE and append returned chunks until SW1=90.

If EXCHANGE or ENVELOPE return 61 XX, this command is used repeatedly until all data is returned.

For ENVELOPE, returned chunks carry BER-TLV with encrypted CBOR payload.
For EXCHANGE, returned chunks carry encrypted EXCHANGE response bytes.

Currently, two protocol versions have been observed in the wild:

• 0.9 - Apple Wallet; Google Wallet;
• 1.0 - Apple Wallet (since 26.4); Samsung Wallet.

Primary protocol commands, including SELECT, AUTH0, AUTH1, and underlying cryptography, seem to be unaffected by the chosen protocol version. The difference is suspected to be present in the command formats for EXCHANGE and ENVELOPE.

To enable use of the "Express Mode" feature with Apple devices, the reader has to send a TCI value that matches the pass.
While the value may be unique for general access installations, Matter-based Aliro locks use a TCI value of 204220.

For Home installations where both HomeKit and Matter locks are present, the Aliro applet co-resides with the HomeKey applet inside the same pass.
At the same time, the Aliro applet is not available when express mode is triggered with the HomeKey TCI 021100, and the HomeKey applet is unavailable when the pass is triggered with the Aliro TCI 204220.

Similar to HomeKey, the last 8 bytes of the ECP frame must contain the reader group identifier so that the device can auto-present the pass when TRA is active or express mode is disabled.

To support automatic credential use on newer Android devices, compatible readers have to broadcast appropriate Polling Loop Annotations.

Considering that Android's Observe Mode feature is compatible with readers that use any annotation format, Samsung and Google Wallet may piggyback on existing formats like ECP, or use a custom one for readers that are Android-only.

• General information:
  • Connectivity Standards Alliance - Aliro;
  • Apple Business Register - Apple Wallet Access Program;
  • Google - Express Mode For an Enhanced User Experience;
  • Samsung - Door Locks on SmartThings x Samsung Wallet.
• Researched Wallet Applications & system modules:
  • Samsung Wallet;
  • Samsung Digital Key Services;
  • Google Wallet;
  • Google Play Services.