Identity Management

A unique identity of each Application instance (e.g. mobile Application installed on the particular device) is based on the private and public keys. This key pair is generated locally on the device by SeaCat SDK during a first launch of the Application and it is bound with particular Application instance. We call it Client. After Client is authorized on SeaCat Gateway, Client receives Client Certificate signed by Certificate Authority from SeaCat Gateway.

For more details regarding Client onboarding procedure go to Workflows chapter. Certification authority functions and deployment scenarios are described in Certificate Authority chapter.

The protection of Client private key is up to SeaCat SDK. If operating system version has Secure Enclave or Android Keystore integrated Client private key can be protected by these technologies. Optionally, additional User protection of Client private key is available by use of advanced cryptographic techniques (e.g. Password/PIN protection, NFC HW tokens, etc.)

For more details about private key protection go to Key Management chapter.

SeaCat Gateway checks Client identity during establishing of Client Connection. SeaCat Gateway mediates access between Client and respective Application Backend. It refuses or grants access to Application Backend based on a whitelist of the Client Certificates. Admin Panel manages Client authorization (presence of Client Certificate in the whitelist).

Client Authorization

Client ID

Client identification is a SHA-384 hash of Client public key. It is called Client ID. Client ID provides a globally unique identification of a Client. Client ID is represented by 96 characters long hexadecimal string (allowed characters are a-f0-9), a binary form of Client ID is 48 bytes long. The Client ID is used by SeaCat for all internal processes.

Client ID example: 4ffe3b6cc5a5340fbac48345e7582aab1af8400e4838c9a97018809915ba1c1b9060006e6dbe4b597c612a854807e212

Special value of "empty" client id

Client ID 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 means empty client id (uninitialized or anonymous).

Handles

Every Client has multiple handles of different types.

Client Tag

Client Tag is one of the handles. It is BASE32-encoded first ten (10) bytes of Client ID (which is a SHA-384 hash of Client public key). The value is typically presented in square brackets, it has always 16 characters plus two for brackets. Allowed characters are A-Z2-7, 0 and 1 are skipped due to their similarity with the letters O and I. Management of Clients (Admin Panel) uses Client Tag as the primary handle to simplify the administration.

Client Tag example: [GMYDQMRQGIYGCMBS]

Special value of "empty" client tag

Client Tag [AAAAAAAAAAAAAAAA] means empty client tag (uninitialized or anonymous). It is derived from empty Client ID.

Other Handles

SeaCat Gateway has other handles than Client Tag. For example the following:

  • IPv4 address
  • IPv6 address
  • Username
  • Specific identifier used by Application
  • Phone number

User Identity and Access Management (IAM)

SeaCat identification process uses Clients as an end entity. Thanks to unique Client ID, SeaCat Gateway has detailed information of every single communicating Client even if the User provide no credential or Application requires no credential. Client identification is made immediately after Application starts communication with the SeaCat Gateway and Application Backend. Thanks to this approach, SeaCat Gateway provides the following:

  • Unique time-independent Application identification;
  • Application User behavior and workflows trace;
  • Statistics of Application usage;
  • Automatic actions (e.g. refuse access to Application Backend for particular User) in a case of suspicious activity is detected;
  • Remote access to every Client.

SeaCat identification is invisible to Application and it can coexist with any built-in authentication method. By SeaCat SDK integration existed built-in User authentication mechanism is not altered. Application developers have absolute freedom regarding built-in User authentication mechanism inside the Application.

Client identification in cooperation with Client authentication on SeaCat Gateway can extend or replace built-in User authentication mechanism. It can be the only User authentication mechanism if Application has no built-in authentication implemented.

SeaCat Identification Integration

Integration of SeaCat identification to Application varies for Applications contain built-in authentication or without it.

Application with Built-in Authentication

Integration of SeaCat identification to Application enhances the information about Client/User ID provided by SeaCat Gateway. For single-User Application (e.g. Application for the personalized digital access card, Instant messaging Application linked with phone number), Client identity is directly linked with User. Every Client than represents the particular User which results in the following functionalities:

  • Client is extended by User identity in the access management;
  • A list of User devices is created.

For multi-User Application it results in the following functionalities:

  • A list of User devices is created.
  • A list of devices shared by more than one User is created.

To ensure the functionalities, SeaCat Gateway need to know which User works with Application. Pair User with the Client can be done by:

  • SeaCat SDK
  • SeaCat Gateway
  • integration with internal systems (e.g. identity management) via an API

SeaCat Gateway maintains the pair list regardless Client/User ID pair origin. Description of Client/User ID pair processes regarding origin follows:

SeaCat SDK

For a User/Client ID pair, any unique User identifier (e.g. User name, some ID, etc.) need to be passed from Application to SeaCat SDK. SeaCat SDK is responsible for manipulating with Client Certificate Signing Request, so after Application pass the unique User identifier to SeaCat SDK, SeaCat SDK added User identifier to Client Certificate Signing Request and send it to SeaCat Gateway. Dedicated Client Certificate field reserved for TeskaLabs purposes is used for that, so all other fields are available for developers for any purpose.

SeaCat Gateway

SeaCat Gateway can be used as an origin of User/Client ID pair only if Application requests contains unique User identifier. Than, User identification is gathered by SeaCat Gateway from Application request syntax. Client ID is available to SeaCat Gateway naturally. User/Client ID pair is done by combination of Client ID and unique identifier from the Application request.

Internal Systems Integration

SeaCat Gateway can forward Client ID string to Application Backend for future processing in XFF header. Afterwards, Application Backend has knowledge about both User and Client ID for the future pairing. User/Client ID pairs are available to SeaCat Gateway via Application Backend API or by any other API which have available User/_Client_ID pairs (e.g. Identity management).

Application without Built-in Authentication

For Application without built-in authentication, Client ID represents one and only identification created by SeaCat SDK automatically with all the benefits described in User Identity and Access Management paragraph.

Collisions

Client ID Collisions

SHA-384 offers space allowing 2^384 combinations. In fact, the strength of all hash functions is half because of Birthday attack. SHA-384 offers the same strength as AES192 symmetric cipher: 2^192 or approximately 6.277×10^57.

We could compare it to IPv6 address space. IPv6 uses a 128-bit address, allowing 2^128, or approximately 3.403×10^38 addresses. The actual number is slightly smaller because of reservation of multiple ranges for special use.

SHA-386 offers 1.845×10^19 times bigger space than IPv6. Every IPv6 address could have more than 18 quintillions Client ID associated with it.

Client Tag Collisions

Every Client Tag is calculated from the first ten hexadecimal characters of a Client public key, which offers 16^10 of combinations per one Application. It is more than one trillion managed Clients without any collision.

Found a mistake? Please contact us.