KB_160116: Database Design Considerations for VACMAN Controller Implementations5/15/2017 11:54:49 AM
This paper outlines general recommendations and best practices related to the design of a VACMAN Controller database for client implementations. The intent is to provide a starting point that customers may use to support standard VASCO implementations and as a foundation for further customization to achieve customer data storage requirements.
Problem symptoms / details.
In any VACMAN Controller implementation, there will certainly be a desire to capture and store a variety of details about the authentication state and token information. While this will vary from client to client, there are some common areas related to Vasco token/license data where all implementation can benefit from some bestpractice recommendations and considerations.
In evaluating the data storage requirements, there are several product features sets that must be considered, these include support for single or multiple functions (i.e. token applications) as well as single and multiple device instance support. Token applications include both the distinct independent uses that a token supports (e.g. one-time-password generation, challenge-response support, secure channel and transaction signature), as well as similar applications with different configurations (e.g. 6 digit OTP generation or 7 digit OTP generation). Single device solutions generally involve the use of a hardware token generator, which by definition is unique and assigned to a single user, where multiple device support is directly tied to the use of ‘software’ token generators, which may be installed on multiple different devices for the same user.
Data storage requirements for scenarios from both of these architectures will be examined to determine a common best-practice recommendation that can be used for one or both architectures (a hybrid deployment scenario). This document will attempt to point out where improvements may be gained from alterations that are appropriate for supporting just one architecture.
In generating a database design, the required data elements need to be evaluated against where/when they are required and used during the Vasco implementation process. This process is broken down into four different phases:
- Administration (including provisioning)
1.1 Import processing
During import, the DPX file is read into the system and data stored so that the DPX file can be archived safely and is not required for future processing. This import processing will be required to store DPX file specific information as well as details about the individual token instances that are included in the file.
1.2 Activation processing
There are two aspects of token activation to be considered in the database design
- Token lifecycle support
- Database retrieval performance/simplicity
1.2.1 Token lifecycle support
Since at activation, the BLOB information being stored will be updated during the use1, the ability to return to a pre-use state requires specific design and consideration. This ‘original’ state may be required to support token reuse (after deactivation of a previous activation) without leaving traces of the previous user or activation.
1.2.2 Database performance/simplicity
While database query logic is relatively efficient, requiring multiple table access or additional processing on retrieved data in order to obtain commonly used elements that may be part of a single DPX data element (e.g. details in a BLOB, etc.) may add unnecessary processing. At the same time, some of these elements are stored securely and require the added processing to extract this data without jeopardizing the overall security of the system.
Not part of the DPX file data, but certainly a consideration of the implementation design, is the need for the token storage database design to support additional administrative tasks. This document will not go into details on this other than to recognize that there will be administrative tasks such as user-token association, device tracking, etc. to be addressed. The final recommendation will allow for support of these tasks, but specific administrative requirements may add requirements and/or data elements to the design laid out in this document.
Applies to: VACMAN Controller (version 3.16 and greater)
2 Usage review
Understanding the data use will also help identify and define the design requirements of the stored data. To do this some key SDK APIs can be reviewed. These are broken into import and usage categories
This list identifies most of the commonly used AAL2Wrapper functions used during the import process and their data dependencies.
- AAL2Wrap.AAL2DPXInit() – retrieve values for token/license count2, application count and Application Names3 from the DPX file
- AAL2Wrap.AAL2DPXGetMessageVector() - retrieve the Message Vector from the DPX file
- AAL2Wrapper.AAL2DPXGetStaticVector() - retrieve the Static Vector from the DPX file
- AAL2Wrap.AAL2DPXGetTokenBlobsEx() – extract ‘next’ token data from DPX file
- RespDPXGetTokenBlobsEx.getActivationVector() – retrieve the instance specific Activation Vector
- RespDPXGetTokenBlobsEx.getAuthMode() – retrieve the instance specific Authentication Mode
- RespDPXGetTokenBlobsEx.getPKBlob() – retrieve the instance specific Payload Key
- RespDPXGetTokenBlobsEx.getDPData() – retrieve the instance specific array of Application BLOBs
- RespDPXGetTokenBlobsEx.getSeqNumThreshold() – retrieve the Instance Threshold override (default = 99)
- RespDPXGetTokenBlobsEx.getSerial() – retrieve the instance specific Serial Number4 (SN)
- RespDPXGetTokenBlobsEx.getSerialAppl() – retrieve the instance specific array of Application Names3
- RespDPXGetTokenBlobsEx.getTokenType() – retrieve the instance specific token Type
Usage has a large set of APIs. Most however share the need for a set of common data elements for use in their parameters.
- Application Blob(s)
- Kernel Parameters
- Message Vector
- Static Vector
The following are items not used as input parameters, but data elements that may be useful in administrative processing:
- Application name
- Device Code
- Device ID
- Serial Number
The following database design is a recommended schema based on the previous discussion and considerations. It is not mandatory either in its schema design or in the individual table contents, in fact it is expected that clients, even those that opt to follow these recommendations, will introduce data elements into the final data storage design to support client specific processing requirements.
3.1 Batch table
This contains universal information related the set of tokens delivered to the client in the DPX file. Much of this may be metadata including elements that are specific to the clients desire to track and manage batches (e.g. date received, count, etc.)
- Batch ID – primary key
- Kernel Parameters
- Static Vector
This table is likely only to be updated during the import phase and only read during regular authentication use. The Batch ID should be an index primary key, defined by the client based on client specific needs related to the management of separate collections of Vasco tokens/licenses.
3.2 License table
This table will contain token specific information. Since it supports both the single and multi-device concepts, is should be capable of holding license data as well as explicit hardware token details. This table will also contain license specific details like the Message vector and Activation vector for each license contained in each batch.
Once initialized (during the import process), this table should be read only.
- Batch ID – reference to Batch table
- Entry ID/SN – primary key
- Message Vector
- Activation Vector
- Sequence Threshold
The Entry ID should be provide a unique identifier across all implementations managed in the database. With hardware tokens this may be the Serial Number, however, with software tokens this can be an abstract token ID (generated by the client), in which case the association between the specific serial/license number and the token ID could be stored elsewhere (see Serial Number Associations table). Implementing this token ID for software tokens will increase the query performance of instance data retrieval. The association between the token ID and serial/license number would only really be necessary to use to prevent duplicate import (other options may also be available to accomplish this as well; e.g. DPX checksum, etc.). The use of an abstract ID may be attractive for both hardware and software implementations since this presents the opportunity to introduce an index, which can improve query performance in large implementations.
3.3 Instance table
This table will be the main table used during operational authentication/validation use cases and the DB design minimizes update requirements to this table. With hardware use (single instance), the primary ID may be the same as the license ID (i.e. Serial Number). While the value of the instance table applies mostly to multi-device support, applying the design to both single and multi-instance implementations has no major overhead (redundant IDs).
Entries in the instance table should contain all related applications (flat structure for master application and multiple applications). This allows a single query to retrieve all instance related details, including associated application blob data5.
- License ID – reference to License table
- Entry ID – primary key
- Master Application Blob
- 8 Application Blobs/Names/Mode
- Payload Key Blob
- Activation status
Using the Device ID as the Entry ID/primary key to this table will help improve query retrieval of the specific instance information when receiving requests from the device.
In order to support the administrative ability to ‘refresh’ an instance and reset any previous updates to the application data, implementations may wish to include storage of an optional ‘Master Instance table’. This optional table does not need to include a complete set of instance data elements that are required with activated instances, only the original setting that would be needed if an existing instance needs to be ‘reset’. For implementations that do not need this ‘reset’ functionality, it is sufficient to start create the Instance table entries on import and then update them directly as the instance is activated.
1 BLOB information should always be written back to the data storage after use so that system details stored and updated in these BLOB details is up-to-date in subsequent uses.
2 Token count is often unused since recommended process for loading individual token details is to loop while returnCode != 107 (Success and end of file reached)
3 Instance specific application names (application name with serial number prefix) are also returned by getSerialAppl()
4 Token Serial Numbers (SN) are distributed in the DPX and uniquely identifies each token/license. With hardware tokens, the SN will matches the hardware serial number, with software tokens, this value may be replaced (or mapped) to other unique identifiers in order to improve DB performance and design.
5 several elements are extracted and stored independently in this table that are not used directly by Vasco APIs (this table does not include the instance number, though this may be useful in administrative maintenance
KB 160116– 15/05/2017
© 2017 VASCO Data Security. All rights reserved.