API Description
The Linux Token Management API is written in C++. It uses the OIDC interface, also available in C++ using Qt environment.
The maximum connected virtual smart cards at the same time is fixed to 5.
Every API function returns an sResultTokenManager structure to indicate whether the requested operation succeeds or fails.
To know the list of error values, refer to Error Codes.
Commands
The following commands are used for the Linux client:
Set JWT Handler
This command is used to set JWT handler. The following points give information about the JWT handler:
-
OIDC JWT retrieval procedure is implemented by the idpv_systray application (3rd party/Customer’s Application).
-
The IDPV Linux Client libraries know when to trigger the JWT retrieval procedure.
-
The idpv_systray application must implement a JWT Handler callback to allow the idpvTokenManager library to obtain/refresh its JWT when needed.
-
The idpvTokenManager library calls the
jwtHandlercallback
duringbeginUserSession
and when JWT is about to expire. -
The library calls the external application to refresh the JWT. Library is responsible for requesting a valid JWT when necessary.
-
Input parameter is UserID.
Parameter
Input | Output |
---|---|
JWT handler callback | RV |
For example, setJwtHandler(JWTHandler);
Begin User Session
This command is used to list its whole virtual cards for a User ID, extracted from the JWT internal parameter managed by the OIDC.
Parameters
Input | Output |
---|---|
Url, Tenant | RV |
Where,
- Url is a string identifying the Server url.
- Tenant is a string identifying the associated Tenant, GUID based format.
For example, BeginUserSession("https://x.y.z.t/”, "xxxxxxxx-yyyy-zzzz-tttt-uuuuuuuuuuuu");
End User Session
This command is used to terminate the existing user session.
Parameters
Input | Output |
---|---|
None | RV |
For example, EndUserSession();
List Tokens
This command is used to list the tokens belonging to the selected UserID.
Parameters
Input | Output |
---|---|
None | Token list information in JSON format. |
For example, list = listTokens(ref TokenList);
Output,
The TokenID is the information required to manage token connection and disconnection.
Connect Token
This command connects the selected TokenID. Once connected, the corresponding virtual smart card is used to perform cryptographic operations.
Parameters
Input | Output |
---|---|
TokenID | RV |
For example, connectToken(TokenID);
Disconnect Token
This command disconnects the selected TokenID. Once disconnected, the corresponding virtual smart card is not able to perform cryptographic operations.
Parameters
Input | Output |
---|---|
TokenID | RV |
For example, disconnectToken(TokenID);
Error Codes
The sResultTokenManager
structure is defined as:
typedef struct
{
int status;
std::string API_name;
std::string error_details;
}sResultTokenManager;
The API returns the following values in sResultTokenManager::status field:
-
#define APP_NO_ERROR : 0
-
#define APP_NONE_EMPTY_SLOT : 100
-
#define APP_KEY_MISMATCH : 101
-
#define APP_EMPTY_TOKEN_LIST : 102