SDK Structure

The API is natively built upon .NET 6.0 (and works without issues on all higher .NET versions). The CLI Tool is built on top of the API, directly calling the API functions. You can therefore use the CLI Tool without any additional work, or directly call the API methods from other applications using C# or Python.

SDK structure

API Structure

The API is designed to be relatively straightforward to use. It contains one main namespace called CrescendoDLL. Inside the CrescendoDLL namespace there is one main class called SDKCore. All the functionality of the API if performed on an instance of the SDKCore class.

After an instance of the SDKCore class was created, user has the option to set the desired Log level (and when working with C# directly, also a specific logging function).

When working with C# directly, user also needs to specify his own function for PIN and XAUTH retrieval using the SetPINDialog and SetXAUTHDialog respectively.

Initial Set-up

Command Line Tool

No need for initial set-up, the Command Line Tool is ready to be used without any prerequisites.

C#

Add a reference to the CrescendoDLL.dll file into your existing project.
(Optional) Set the desired log level by using the SetLogLevel function and the values from LogLevel. The default value is LogLevel.SILENT.
(Optional) Set the log function of your choice by using the SetLogAction function. The default value is Console.Error.WriteLine, to separate the actual output (STDOUT) from the logging data (STDERR).
Create an instance of the main class SDKCore with the token of your choice. The string value can be either the name of the reader with token, or just a token index obtained by using GetAllAvailableTokens.
Set a method to provide the PIN or XAUTH by using the SetPINDialog or SetXAUTHDialog respectively.
Open an actual SCard transaction to the token using StartTransaction method.
Note
This transaction stays open only for a limited amount of time, so either call it directly before you want to call some token operation, or use MaintainTransactionAsync to keep the transaction open. This however prevents all other threads to communicate with the token.
At the end of your operation, call the Dispose method to log out of any used applets, close the SCard transaction and disconnect from the reader.

Code Example:

using CrescendoDLL;
 
SDKCore.SetLogLevel(LogLevel.INFO);
// LOG data should go to STDERR
SDKCore.SetLogAction(Console.Error.WriteLine);
 
// Get all available tokens
List<(string ReaderName, byte[] TokenATR, string TokenName, int TokenIndex)> tokenList = SDKCore.GetAllAvailableTokens();
 
SDKCore transaction = new(tokenList[0].ReaderName);
// SDKCore transaction = new(tokenList[0].TokenIndex.ToString());
// SDKCore transaction = new("0");
// SDKCore transaction = new("Circle Idaxis SecurePIV 0");
 
transaction.SetPINDialog((pinType) =>
{
    //Code to provide a string "pin"
    return pin;
});
 
transaction.SetXAUTHDialog((xauthType) =>
{
    //Code to provide a string "xauth"
    return xauth;
});
 
// Open the SCardTransaction
transaction.Engine.StartTransaction();
 
...
 
// Close the SCardTransaction, disconnect from the reader and dispose of the `transaction` object
transaction.Dispose();

Python

Download and Install Python 3.10 or newer from the official website.
Install the pythonnet package by running the command pip install pythonnet from the folder where your instance of Python.exe is located.
Load the correct .NET core clr coreclr and import it.
Import the main API file - CrescendoDLL.dll
Import the SDKCore class.
(Optional) Import the LogLevel Enum and set the desired Log level by using the SetLogLevel function and the values from LogLevel. The default value is LogLevel.SILENT.
Create an instance of the main class SDKCore with the token of your choice. The string value can be either the name of the reader with token, or just a token index obtained by using GetAllAvailableTokens.
Set PIN or XAUTH by using the SetPINForPythonWrapper or SetXAUTHForPythonWrapper respectively.
Open an actual SCard transaction to the token using StartTransaction method.
Note
This transaction stays open only for a limited amount of time, so either call it directly before you want to call some token operation, or use MaintainTransactionAsync to keep the transaction open. This however prevents all other threads to communicate with the token.
At the end of your operation, call the Dispose method to log out of any used applets, close the SCard transaction and disconnect from the reader.

Code Example:

from pythonnet import load
load("coreclr")
import clr
 
# Import the main DLL
clr.AddReference(r'c:\Temp\CrescendoDLL.dll')
 
from CrescendoDLL import SDKCore
from CrescendoDLL import LogLevel
 
SDKCore.SetLogLevel(LogLevel.INFO)
 
# Get all available tokens
readerList = SDKCore.GetAllAvailableTokens()
 
# Create an instance of the base class with chosen token
transactionInstance = SDKCore(readerList[0].Item1)  # Item1 = ReaderName (string)
# transactionInstance = SDKCore(str(readerList[0].Item4))  # Item4 = TokenIndex (int)
# transactionInstance = SDKCore('0'))
# transactionInstance = SDKCore('Circle Idaxis SecurePIV 0')
 
# Call the SetPINForPythonWrapper method
transactionInstance.SetPINForPythonWrapper('123456')
 
# Open the SCardTransaction
transactionInstance.Engine.StartTransaction();
 
...
 
# Close the SCardTransaction, disconnect from the reader and dispose of the `transactionInstance` object
transactionInstance.Dispose();

Useful SDK functions

MaintainTransactionAsync

The function MaintainTransactionAsync can be used to keep the SCard Transaction open for longer the the default amount of time (on Windows, that seems to be approximately 5 seconds). This can be useful for example when waiting for user input, or some other time consuming logic takes place on the user side of things, but they don't want to loose the transaction with the card (and therefore authentication status, FIDO shared secret, etc.) An example of how to use MaintainTransactionAsync can be found below:

// Open the SCardTransaction
transaction.Engine.StartTransaction();
 
// Start keep-alive cancellation token source and a asynchronous task that will keep the transaction alive
CancellationTokenSource _keepAliveCts = new();
Task keepAliveTask = methods.Engine.MaintainTransactionAsync(_keepAliveCts.Token);
 
// Do the required operation
try
{
    // Wait for user input
    ...
}
finally
{
    // Send the Cancel command to the CancellationTokenSource, and Wait for the task to finish
    _keepAliveCts.Cancel();
    keepAliveTask.Wait();
}
 
// Take the user input and continue with normal logic here
...