Skip to content

PKI 9 TPS Token Lifecycle

Endi S. Dewata edited this page Feb 2, 2022 · 2 revisions

Overview

This document describes TPS token behavior as implemented in PKI 9.

Token Database

Tokens are stored in TPS database as LDAP entries which contain the following attributes:

LDAP Attribute Example

cn

A00192030405060708C9

tokenUserID

testuser

tokenType

externalRegAddToToken

tokenStatus

uninitialized

tokenReason

tokenAppletID

1.4.52CF1C58

keyInfo

0101

dateOfCreate

20140403112248Z

dateOfModify

20140403112248Z

modified

0

tokenPolicy

RE_ENROLL=YES

extensions

numberOfResets

0

numberOfEnrollments

0

numberOfRenewals

0

numberOfRecoveries

0

userCertificate

See also TPS Database.

Token Database State

Token state is stored in the database in tokenStatus and tokenReason attributes.

The tokenStatus may have the following values:

Name Code Value

STATE_UNINITIALIZED

0

uninitialized

STATE_ACTIVE

1

active

STATE_DISABLED

2

disabled

STATE_LOST

3

lost

STATE_TERMINATED

<undefined>

terminated

The tokenReason attribute may have the following values:

Value Description

<blank>

keyCompromise

destroyed

onHold

Token UI States

The token state is displayed in the UI as follows:

Name Code Label

TOKEN_UNINITIALIZED

0

Uninitialized.

TOKEN_DAMAGED

1

This token has been physically damaged.

TOKEN_PERM_LOST

2

This token has been permanently lost.

TOKEN_TEMP_LOST

3

This token has been temporarily lost.

TOKEN_FOUND

4

This temporarily lost token has been found.

TOKEN_TEMP_LOST_PERM_LOST

5

This temporarily lost token cannot be found (becomes permanently lost).

TOKEN_TERMINATED

6

This token has been terminated.

Token State Conversion

The token database state is translated into token UI state as follows:

tokenStatus tokenReason Token UI State

STATE_UNINITIALIZED

<ignored>

TOKEN_UNINITIALIZED

STATE_ACTIVE

<ignored>

TOKEN_FOUND

STATE_LOST

keyCompromise

TOKEN_PERM_LOST

STATE_LOST

destroyed

TOKEN_DAMAGED

STATE_LOST

onHold

TOKEN_TEMP_LOST

STATE_TERMINATED

<ignored>

TOKEN_TERMINATED

STATE_DISABLED

<ignored>

TOKEN_PERM_LOST

The token UI state is translated into token database state as follows:

Token UI State tokenStatus tokenReason

TOKEN_DAMAGED

STATE_LOST

destroyed

TOKEN_PERM_LOST

STATE_LOST

keyCompromise

TOKEN_TEMP_LOST

STATE_LOST

onHold

TOKEN_FOUND

STATE_ACTIVE

<blank>

TOKEN_TEMP_LOST_PERM_LOST

STATE_LOST

keyCompromise

TOKEN_TERMINATED

STATE_TERMINATED

keyCompromise

Token State Transitions

State transitions via UI/CLI

A TPS agent may change the token state via the UI/CLI. Below is the allowed state transitions:

tokendb._066=# tokendb.allowedTransitions:
tokendb._067=#   - has transitions between the following states
tokendb._068=#     TOKEN_UNINITIALIZED = 0,
tokendb._069=#     TOKEN_DAMAGED =1,
tokendb._070=#     TOKEN_PERM_LOST=2,
tokendb._071=#     TOKEN_TEMP_LOST=3,
tokendb._072=#     TOKEN_FOUND =4,
tokendb._073=#     TOKEN_TEMP_LOST_PERM_LOST =5,
tokendb._074=#     TOKEN_TERMINATED = 6

tokendb.allowedTransitions=0:1,0:2,0:3,0:4,0:5,0:6,3:4,3:5,3:6,4:1,4:2,4:3,4:6
Current State Next State Label

TOKEN_UNINITIALIZED

TOKEN_DAMAGED

This token has been physically damaged.

TOKEN_UNINITIALIZED

TOKEN_PERM_LOST

This token has been permanently lost.

TOKEN_UNINITIALIZED

TOKEN_TEMP_LOST

This token has been temporarily lost.

TOKEN_UNINITIALIZED

TOKEN_FOUND

This temporarily lost token has been found.

TOKEN_UNINITIALIZED

TOKEN_TEMP_LOST_PERM_LOST

This temporarily lost token cannot be found (becomes permanently lost).

TOKEN_UNINITIALIZED

TOKEN_TERMINATED

This token has been terminated.

TOKEN_TEMP_LOST

TOKEN_FOUND

This temporarily lost token has been found.

TOKEN_TEMP_LOST

TOKEN_TEMP_LOST_PERM_LOST

This temporarily lost token cannot be found (becomes permanently lost).

TOKEN_TEMP_LOST

TOKEN_TERMINATED

This token has been terminated.

TOKEN_FOUND

TOKEN_DAMAGED

This token has been physically damaged.

TOKEN_FOUND

TOKEN_PERM_LOST

This token has been permanently lost.

TOKEN_FOUND

TOKEN_TEMP_LOST

This token has been temporarily lost.

TOKEN_FOUND

TOKEN_TERMINATED

This token has been terminated.

State transitions via token operations

A TPS user may change the token state via token operations. Below are the allowed state transitions:

tps._008=# operations.allowedTransitions:
tps._009=#   - token operations, like formatting and enrollment have transitions between the following states
tps._010=#     TOKEN_UNINITIALIZED = 0,
tps._011=#     TOKEN_DAMAGED =1,
tps._012=#     TOKEN_PERM_LOST=2,
tps._013=#     TOKEN_TEMP_LOST=3,
tps._014=#     TOKEN_FOUND =4,
tps._015=#     TOKEN_TEMP_LOST_PERM_LOST =5,
tps._016=#     TOKEN_TERMINATED = 6
tps._017=# Sample: tps.operations.allowedTransitions=0:0,0:4,4:6,6:0

tps.operations.allowedTransitions=0:0,0:4,4:0
Current State Next State Description

TOKEN_UNINITIALIZED

TOKEN_UNINITIALIZED

This allows formatting a blank token or upgrading applet/key of a blank token.

TOKEN_UNINITIALIZED

TOKEN_FOUND

This allows enrolling a token.

TOKEN_FOUND

TOKEN_UNINITIALIZED

This allows formatting an active token.

TOKEN_FOUND

TOKEN_FOUND

This transition is not enabled by default. This allows re-enrolling an active token. Maybe useful for external registration.

Issues

  • TOKEN_UNINITIALIZED to TOKEN_FOUND transition should not be allowed from the UI. A token can only become STATE_ACTIVE through enrollment.

  • TOKEN_UNINITIALIZED to TOKEN_TEMP_LOST_PERM_LOST transition is invalid because it doesn’t go through TOKEN_TEMP_LOST.

  • Both TOKEN_PERM_LOST and TOKEN_TEMP_LOST_PERM_LOST are stored in the database as STATE_LOST with keyCompromise.

  • STATE_DISABLED is never used or stored in the database. A token is considered "disabled" if it is not STATE_ACTIVE and not STATE_UNINITIALIZED.

  • STATE_DISABLED is mapped into TOKEN_PERM_LOST. STATE_DISABLED infers it may become STATE_ACTIVE again, but TOKEN_PERM_LOST is a terminal state.

  • Both STATE_LOST with keyCompromise and STATE_DISABLED are mapped into TOKEN_PERM_LOST. However, TOKEN_PERM_LOST is always mapped into STATE_LOST with keyCompromise.

  • STATE_ACTIVE is mapped into TOKEN_FOUND. An "active" token may be shown as "found" in the UI even if it’s never "lost".

  • The tps.operations.allowedTransitions seems to allow admin to configure transitions between any token UI states. However, the code only supports transitions between TOKEN_UNINITIALIZED and TOKEN_FOUND.

  • The transition from TOKEN_UNINITIALIZED to TOKEN_TEMP_LOST to TOKEN_FOUND bypasses the enrollment operation.

Clone this wiki locally