Skip to content

Mobile ID SDK core concepts

Credentials

Credentials are the core security component of the Mobile ID system.

Project Key: A 16-byte master key shared across a project. This key is used to derive device-specific credentials.

Credential ID: An ASCII string identifier that uniquely identifies a credential within a project (currently only employee ID).

How it works:

  1. The project key and credential ID are used to derive 3 components:

    • keyComm: Communication key (16 bytes)
    • keyInitblock: Initialization block key (16 bytes)
    • credentialBytes: Signed credential with AES-CMAC (variable length)

  2. These derived components are used for secure BLE communication with readers.

Security best practice: Server-side credential derivation

IMPORTANT: For maximum security, credentials should be derived on your backend server, not on the mobile device.

Why?

  • Prevents mobile devices from simulating other device IDs
  • Project key never stored on mobile devices
  • Each device receives unique credentials derived from device ID
  • Compromised device cannot generate credentials for other devices

See server-side credential derivation for implementation details and pseudocode.

Attention: As the app notes do not utilize a server they generate the credential in the app.

BLE protocol overview

The SDK implements a custom BLE protocol for secure communication:

  • Mobile device acts as BLE peripheral
  • Readers act as BLE central devices
  • Encrypted message exchange using derived keys
  • A reader may accept multiple projects (= project keys)
  • A mobile phone can (currently) only be configured with 1 credential

Readers/gates

Reader: Represents a physical smartcard reader connected to an access control system. Supported readers are BALTECH readers with Bluetooth Low Energy (BLE) support, e.g. 10097-6xx, 10119-8xx, 1x115-6xx, or 1x117-8xx. Please refer to reader price lists for all supported article numbers.

Gate: Represents a logical access point (door, gate, turnstile) associated with a reader.

Remote trigger: When a reader is in range and authenticated, it appears in the readers list. You can manually trigger it by calling the trigger() function.

Availability states

The SDK monitors Bluetooth and permission status through availability states:

  • UNDEFINED: Initial/unknown state before initialization
  • UNSUPPORTED: BLE hardware not supported on device
  • DISABLED: Bluetooth is turned off
  • UNAUTHORIZED: App not authorized to use Bluetooth
  • UNKNOWN: Unknown BLE state
  • OK: Ready for operation
  • PERMISSIONS_DENIED: Permissions denied but can be requested again
  • PERMISSIONS_PERMANENTLY_DENIED: Permissions permanently denied, must use settings
  • PERMISSIONS_REQUIRED: Permissions need to be requested
Title