The SDKCore class contains all fundamental methods that can be used by the user to communicate with the SmartCard. More...

Inheritance diagram for CrescendoDLL.SDKCore:

Classes
class	Result
	Represents the outcome of an operation, which can either be successful or a failure. More...

Public Types
enum	SecretType { PIN , XAUTH }
	Representing types of secrets that can be used or authentication. More...

Public Member Functions
Result	AuthenticateWithXAUTH (string? xauthKey, string? challenge=default!, XAUTHKeyType? xauthKeyType=null)
	Authenticates on the ACA applet using an XAUTH key.

Result< CrescendoDLL.PCSC.FIDODataStructures.ClientPINResponse >	AuthenticatorClientPIN (CrescendoDLL.PCSC.FIDODataStructures.ClientPINRequest request)
	Sends a FIDO CTAP2 `authenticatorClientPIN` command to manage PIN operations on the authenticator.

Result	AuthenticatorConfig (CrescendoDLL.PCSC.FIDODataStructures.ConfigRequest request)
	Sends a FIDO CTAP2 `authenticatorConfig` command to reset the authenticator to its default state.

Result< CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse >	AuthenticatorCredentialManagement (CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementRequest credentialManagementRequest)
	Sends a FIDO CTAP2 `authenticatorCredentialManagement` command to manage discoverable credentials on the authenticator.

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse >	AuthenticatorGetAssertion (CrescendoDLL.PCSC.FIDODataStructures.GetAssertionRequest getAssertionRequest)
	Sends a FIDO CTAP2 `authenticatorGetAssertion` command to retrieve an assertion from the authenticator.

Result< CrescendoDLL.PCSC.FIDODataStructures.AuthenticatorInfo >	AuthenticatorGetInfo ()
	Sends a FIDO CTAP2 `authenticatorGetInfo` command to retrieve information about the FIDO Authenticator's capabilities. Elevated privileges are required on Windows.

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse >	AuthenticatorGetNextAssertion ()
	Sends a FIDO CTAP2 `authenticatorGetNextAssertion` command to retrieve the next assertion from the authenticator.

Result< CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialResponse >	AuthenticatorMakeCredential (CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialRequest makeCredentialRequest)
	Sends a FIDO CTAP2 `authenticatorMakeCredential` command to create a new public key credential on the authenticator.

Result	AuthenticatorReset ()
	Sends a FIDO CTAP2 `authenticatorReset` command to reset the authenticator to its default state.

Result< string >	ChangePIN (string? newPin)
	This function changes the PIN based on the provided parameters.

Result	ChangeXAUTHMode (XAUTHChallengeType xauthMode)
	This function changes the `XAUTH` mode based on the provided parameter.

Result< string >	ConfigureOATHSlot (string? oathSlot, int buttonPress, string? oathKey, string? jsonInputPath, int timeStep, OATHModeName oathMode, string oathCounter, HashAlgoValues oathHash, int codeDigits, string friendlyName, int truncationOffset, string transportKey, string? pskcString, bool requireTouch=false)
	This function configures the OATH slot based on the provided parameters.

Result< string >	ConfigureOCRASlot (string? oathSlot, int buttonPress, string ocraSuite, string? oathKey, string? jsonInputPath, string? friendlyName, string transportKey, string? pskcString, bool requireTouch=false)
	This function configures the OCRA OATH slot based on the provided parameters.

Result	ConfigureStaticPassword (string? password, string? jsonInputPath, KeyboardEncodings encoding, string? oathSlot, int buttonPress, string friendlyName, bool requireTouch=false)
	This function configures the Static Password on specified OATH slot based on the provided parameters. Only works with Applet version V4.

Result< string >	DeleteOATHSlot (string? oathSlot, int buttonPress, string? pskcString)
	This function deletes the oathSlot configuration and key based on the provided parameters.

Result	DeleteXAUTHKey (XAUTHKeyType xauthKeyType)
	This function deletes a Symmetric `XAUTH` key of a specified type from the token.

void	Dispose ()
	Releases all resources used by the CrescendoDLL.SDKCore instance.

Result< string >	EncryptKEKAndDataWithKEK (AsymmetricKeyParameter publicKey, object inputData, KeyTypeToBeTransferredWithSKI dataType, KeyboardEncodings encoding=KeyboardEncodings.US)
	Encrypts the Key Encryption Key (KEK) and another input data (either `PIV`, `XAUTH`, `OATH` keys, or a `STATICPASS` static password) with the KEK.

record	Error (string Code, string Message)
	Represents an error with a code and a message.

Result< string >	FIDOChangePIN (string? newPin)
	Performs a PIN-authenticated FIDO2 CTAP ChangePIN operation with full authentication flow. Elevated privileges are required on Windows.

Result	FIDOConfig (CrescendoDLL.PCSC.FIDODataStructures.ConfigRequest configRequest)
	Performs a PIN-authenticated FIDO2 CTAP Authenticator Configuration operation with full authentication flow. Elevated privileges are required on Windows.

Result< CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse >	FIDOCredentialManagement (CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementRequest credentialManagementRequest)
	Performs a PIN-authenticated FIDO2 CTAP CredentialManagement operation with full authentication flow. Elevated privileges are required on Windows.

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse >	FIDOGetAssertion (CrescendoDLL.PCSC.FIDODataStructures.GetAssertionRequest getAssertionRequest)
	Performs a PIN-authenticated FIDO2 CTAP GetAssertion operation with full authentication flow. Elevated privileges are required on Windows.

Result< CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialResponse >	FIDOMakeCredential (CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialRequest makeCredentialRequest)
	Performs a PIN-authenticated FIDO2 CTAP MakeCredential operation with full authentication flow. Elevated privileges are required on Windows.

Result< string >	FIDOSetPIN (string? newPin)
	Performs initial FIDO2 CTAP PIN setup operation with full authentication flow. Elevated privileges are required on Windows.

Result< string >	GenerateOTP (string? oathSlot, int buttonPress)
	This function generates an OTP (One-Time Password) based on the provided parameters.

Result< string >	GetChallenge ()
	Retrieves a XAUTH challenge.

Result< string >	GetSKITransportKey ()
	This function retrieves the Secure Key Injection (SKI) RSA3072 transport key.

Result< string >	ListACAProperties ()
	This function lists the properties of the ACA applet.

Result< string >	ListFIDOProperties ()
	This function lists the properties of the FIDO Attestation Applet, as well as the basic parameters of the FIDO Authenticator when used with elevated privileges.

Result< string >	ListOATHProperties ()
	Lists the OATH properties of the OATH applet.

Result< string >	ListPIVProperties ()
	Prints the properties of the PIV applet.

Result	Logout ()
	Logs out of the ACA applet and clears the cache.

Result< string >	NewToken (string? newPin)
	Personalizes a new token with newPin , generates and returns a new `PUK` and personalizes the PIV Personal info (CHUID).

Result< string >	OCRAAuthenticate (string? oathSlot, int buttonPress, string challenge, string? secret, string? session)
	This function performs an OCRA Challenge Response or Digital Signature operation with previously configured OCRA slot.

Result	PIVAddDataToDataObject (string berTLVTag, List<(string tag, byte[] data)> tagsData)
	This function adds one or multiple data items to a PIV data object on a token.

Result	PIVChangeDataObjectACR (string berTLVTag, string personalizationACR, string contactUsageACR, string contactlessUsageACR)
	This function changes the Access Control Rules (ACR) of a given PIV data object on a token.

Result	PIVChangePKISlotACR (string keyReference, string personalizationACR, string contactUsageACR, string contactlessUsageACR)
	This function puts the PKI (Public Key Infrastructure) data to the token based on the provided parameters.

Result	PIVDeleteCertificate (string berTLVTag)
	This function deletes a certificate identified by the berTLVTag from a token.

Result	PIVDeleteDataFromDataObject (string berTLVTag, string tag)
	This function deletes data identified by a tag from a PIV data object on a token.

Result	PIVDeleteKey (string keyReference)
	This function deletes a PIV key from the provided key reference.

Result< string >	PIVGenerateKeyPair (PIVCryptographicMechanismIdentifier cryptoMechanism, string keyReference, bool getExistingPublicKey=false)
	Generates an asymmetric key pair on the ACA applet or retrieves the public key and the public exponent of a previously generated key pair, if possible.

Result< string >	PIVGetCertificate (string berTLVTag)
	This function retrieves a certificate defined by the berTLVTag from a token and exports it as a PFX file.

Result< string >	PIVGetDataObjectContent (string berTLVTag)
	This function retrieves a PIV data object from a token and returns its content as a `JSON` string.

Result< string >	PIVGetPersonalInfo ()
	Retrieves personal information from a PIV (Personal Identity Verification) card.

Result	PIVPutPKIData (string inputFilePath, string? password, PIVObjectType pkiObjectType, string? keyReference, string? berTLVTag, string? keyName)
	This function puts the PKI (Public Key Infrastructure) data to the token based on the provided parameters.

Result< string >	PIVRawCryptoOperation (string keyReference, DataType inputType, string? inputString, string? inputFilePath, DataType outputType)
	This function performs a raw cryptographic operation using a private key stored on the token. This is primarily meant for RSA keys, though it is possible to use ECC key as well.

Result< string >	PIVSignData (string keyReference, DataType inputType, string? inputString, string? inputFilePath, DataType outputType, HashAlgoValues hashAlgo, DataType hashType=DataType.BASE64)
	This function signs data using a defined PIV key.

Result< string >	PUKPut (string? puk, bool storePukToPIVDataObjects=true)
	Puts a PUK on the token. If no PUK is provided, a random 8 byte PUK is generated.

Result	PutXAUTHKey (string? xauthKey, XAUTHKeyType? xauthKeyType, string? jsonInputPath)
	This function puts a Symmetric `XAUTH` key of a specified type onto the token.

Result< string >	ReadCacheFreshness ()
	Reads the cache freshness.

Result	ResetPINTries (string newPin, string puk)
	This function resets the PIN tries based on the provided parameters.

Result	ResetToken ()
	Resets the token to its default state.

	SDKCore (string token)
	Initializes a new instance of the CrescendoDLL.SDKCore class.

void	SetPINDialog (Func< SecretType, string > userDialog)
	Sets the method to gather the `PIN` from the user.

void	SetPINForPythonWrapper (string pin)
	Sets the `PIN` for the Python wrapper.

void	SetXAUTHDialog (Func< SecretType, string > userDialog)
	Sets the method to gather the `XAUTH` from the user.

void	SetXAUTHForPythonWrapper (string xauth)
	Sets the `XAUTH` for the Python wrapper.

Result< CrescendoDLL.PCSC.FIDODataStructures.U2FAuthenticationResponse >	U2FAuthentication (CrescendoDLL.PCSC.FIDODataStructures.U2FAuthenticationRequest authenticationRequest)
	Performs a FIDO U2F (CTAP 1) authentication operation to verify a credential.

Result< string >	U2FGetVersion ()
	Retrieves the supported U2F protocol version from the authenticator.

Result< CrescendoDLL.PCSC.FIDODataStructures.U2FRegistrationResponse >	U2FRegistration (CrescendoDLL.PCSC.FIDODataStructures.U2FRegistrationRequest registrationRequest)
	Performs a FIDO U2F (CTAP 1) registration operation to create a new credential.

Result	UpdatePINProperties (int? maxPinTryCounter, int? maxPinUnlockCounter, int? maxContactlessPinCounter, int? minPinLength, int? maxPinLength, int weakPinControl, int changePinAfterFirstUse, int pinNumericOnly)
	Updates the PIN properties on the ACA applet.

Result	VerifyPin ()
	Authenticates on the ACA using `PIN`, or verifies the authentication status in no `PIN is provided`.

Static Public Member Functions
static List<(string ReaderName, byte[] TokenATR, string TokenName, int TokenIndex)>	GetAllAvailableTokens ()
	This function returns all available tokens and their ATRs in a list.

static void	PrintAllAvailableTokens ()
	This function prints all available tokens and their ATRs to the log.

static void	SetLogAction (CrescendoDLL.Logger.LogActionDelegate logAction)
	Sets the action to be performed when a log message is generated.

static void	SetLogLevel (LogLevel severity)
	Sets the severity level for logging.

Public Attributes
APDUEngine	Engine
	The `Engine` object contains references to applet objects, their current properties and all the necessary internal methods to allow PCSC communication with the SmartCard.

Detailed Description

The SDKCore class contains all fundamental methods that can be used by the user to communicate with the SmartCard.

Member Enumeration Documentation

◆ SecretType

enum CrescendoDLL.SDKCore.SecretType

Representing types of secrets that can be used or authentication.

Enumerator
PIN	PIN: Personal Identification Number. A type of secret used for authentication.
XAUTH	XAUTH: External Authentication Key. A type of secret used for providing additional security.

Constructor & Destructor Documentation

◆ SDKCore()

CrescendoDLL.SDKCore.SDKCore ( string token )

inline

Initializes a new instance of the CrescendoDLL.SDKCore class.

Parameters

token The token to be used for initialization. This can be either the index or the name of the reader with the token.

This constructor begins by calling the Initialize method with the provided token parameter. The Initialize method lists the readers, and then checks if the token parameter is a number or a name. Depending on the type of the token parameter, it finds the index of the token in the list of all the readers accordingly. If the index is valid, it retrieves the reader name and creates a new CrescendoDLL.PCSC.APDUEngine object with the reader name. It also sets the TokenATR and TokenName properties of the CrescendoDLL.PCSC.APDUEngine object. After setting up the CrescendoDLL.PCSC.APDUEngine object, it logs the connection details and assigns the CrescendoDLL.PCSC.APDUEngine object to the Engine property of the CrescendoDLL.SDKCore instance.

References CrescendoDLL.SDKCore.Engine.

Member Function Documentation

◆ AuthenticateWithXAUTH()

Result CrescendoDLL.SDKCore.AuthenticateWithXAUTH	(	string?	xauthKey,
		string?	challenge = `default!`,
		XAUTHKeyType?	xauthKeyType = `null`
	)

inline

Authenticates on the ACA applet using an XAUTH key.

Parameters

xauthKey	The `XAUTH` key to be used for authentication. If this parameter is null or empty, a default `XAUTH` key will be used based on the xauthKeyType .
challenge	The Encrypted challenge to be used for the authentication. If this parameter is null or empty, a fresh challenge will be retrieved from the ACA applet.
xauthKeyType	The type of the `XAUTH` key to be put onto the token. Valid options are `AES` and `TDES`. If this parameter is null, the `XAUTH` key type will be determined based on the length of xauthKey

Returns: A Result object, where IsSuccess indicates successful authentication with the provided XAUTH key.
See documentation for Result for more details.

This function attempts to authenticate on the ACA applet using the provided xauthKey .

The function calls the Authenticate method on the ACA applet with the provided xauthKey and the XAUTH type read from the token (Static or Dynamic).

The Authenticate method then performs either static or dynamic External Authentication. For static authentication, it uses a fixed challenge string. For dynamic authentication, it either retrieves a fresh challenge using the GetChallenge method or uses the challenge , if provided.

When working with the fresh challenge, the challenge is encrypted with xauthKey and the appropriate encryption method (AES or TDES) based either on the key length or on the xauthKeyType . Either The encrypted challenge or the provided challenge is then used to perform the actual authentication on the ACA applet.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ AuthenticatorClientPIN()

Result< CrescendoDLL.PCSC.FIDODataStructures.ClientPINResponse > CrescendoDLL.SDKCore.AuthenticatorClientPIN ( CrescendoDLL::PCSC::FIDODataStructures::ClientPINRequest request )

inline

Sends a FIDO CTAP2 authenticatorClientPIN command to manage PIN operations on the authenticator.

Parameters

request The PIN operation request containing subcommand and cryptographic parameters.

Returns: A Result{T} object, where Value is a CrescendoDLL.PCSC.FIDODataStructures.ClientPINResponse object containing the getNextAssertionResponse from the authenticator.
See documentation for Result{T} for more details.

This method handles various PIN operations (set/change/verify) based on request subcommand. The request will be converted to CBOR format and sent to the token. Prior establishment of shared secret through key agreement is required.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

Referenced by CrescendoDLL.SDKCore.FIDOChangePIN(), CrescendoDLL.SDKCore.FIDOConfig(), CrescendoDLL.SDKCore.FIDOCredentialManagement(), CrescendoDLL.SDKCore.FIDOGetAssertion(), CrescendoDLL.SDKCore.FIDOMakeCredential(), and CrescendoDLL.SDKCore.FIDOSetPIN().

◆ AuthenticatorConfig()

Result CrescendoDLL.SDKCore.AuthenticatorConfig ( CrescendoDLL::PCSC::FIDODataStructures::ConfigRequest request )

inline

Sends a FIDO CTAP2 authenticatorConfig command to reset the authenticator to its default state.

Returns: A Result object, where IsSuccess indicates successful configuration of the FIDO token.
See documentation for Result for more details.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

Referenced by CrescendoDLL.SDKCore.FIDOConfig().

◆ AuthenticatorCredentialManagement()

Result< CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse > CrescendoDLL.SDKCore.AuthenticatorCredentialManagement ( CrescendoDLL::PCSC::FIDODataStructures::CredentialManagementRequest credentialManagementRequest )

inline

Sends a FIDO CTAP2 authenticatorCredentialManagement command to manage discoverable credentials on the authenticator.

Parameters

credentialManagementRequest The credential management operation request (enumerate/delete/update).

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse.
See documentation for Result{T} for more details.

This method converts request to CTAP-compliant CBOR encoding and sends multiple APDU's to the token in case the CBOR encoded data is longer than 256 bytes. Requires CTAP2.1 support for credential management operations. Used for operations like:

Enumerating credentials
Deleting discoverable credentials
Updating user information

Failures during any APDU transmission immediately abort the operation.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.FIDOCredentialManagement().

◆ AuthenticatorGetAssertion()

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse > CrescendoDLL.SDKCore.AuthenticatorGetAssertion ( CrescendoDLL::PCSC::FIDODataStructures::GetAssertionRequest getAssertionRequest )

inline

Sends a FIDO CTAP2 authenticatorGetAssertion command to retrieve an assertion from the authenticator.

Parameters

getAssertionRequest The request parameters for generating the assertion.

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse.
See documentation for Result{T} for more details.

This method converts the getAssertionRequest input parameter into CBOR and sends it to the token. Multiple APDU's will be used in case the CBOR encoded data would be longer than 256 bytes. Prior establishment of shared secret through key agreement is required.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.FIDOGetAssertion().

◆ AuthenticatorGetInfo()

Result< CrescendoDLL.PCSC.FIDODataStructures.AuthenticatorInfo > CrescendoDLL.SDKCore.AuthenticatorGetInfo ( )

inline

Sends a FIDO CTAP2 authenticatorGetInfo command to retrieve information about the FIDO Authenticator's capabilities. Elevated privileges are required on Windows.

Returns: A Result{T} object, where Value is the CrescendoDLL.PCSC.FIDODataStructures.AuthenticatorInfo object containing the authenticator's information.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.FIDOChangePIN(), CrescendoDLL.SDKCore.FIDOConfig(), CrescendoDLL.SDKCore.FIDOCredentialManagement(), CrescendoDLL.SDKCore.FIDOGetAssertion(), CrescendoDLL.SDKCore.FIDOMakeCredential(), CrescendoDLL.SDKCore.FIDOSetPIN(), and CrescendoDLL.SDKCore.ListFIDOProperties().

◆ AuthenticatorGetNextAssertion()

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse > CrescendoDLL.SDKCore.AuthenticatorGetNextAssertion ( )

inline

Sends a FIDO CTAP2 authenticatorGetNextAssertion command to retrieve the next assertion from the authenticator.

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse. See documentation for Result{T} for more details.

This method is used to retrieve subsequent assertions when multiple credentials match the criteria specified in a previous authenticatorGetAssertion request. It does not require additional parameters as it uses the state from the previous authenticatorGetAssertion command.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), and CrescendoDLL.SDKCore.Result< T >.IsFailure.

◆ AuthenticatorMakeCredential()

Result< CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialResponse > CrescendoDLL.SDKCore.AuthenticatorMakeCredential ( CrescendoDLL::PCSC::FIDODataStructures::MakeCredentialRequest makeCredentialRequest )

inline

Sends a FIDO CTAP2 authenticatorMakeCredential command to create a new public key credential on the authenticator.

Parameters

makeCredentialRequest The credential creation request containing user and relying party information.

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialResponse.
See documentation for Result{T} for more details.

This method converts request to CTAP-compliant CBOR encoding and sends multiple APDU's to the token in case the CBOR encoded data is longer than 256 bytes. It is used during FIDO2 registration to create discoverable credentials. Requires prior:

PIN authentication if configured
User verification if required by policy

Failures during any APDU transmission immediately abort the operation.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.FIDOMakeCredential().

◆ AuthenticatorReset()

Result CrescendoDLL.SDKCore.AuthenticatorReset ( )

inline

Sends a FIDO CTAP2 authenticatorReset command to reset the authenticator to its default state.

Returns: A Result object, where IsSuccess indicates successful FIDO configuration reset.
See documentation for Result for more details.

This method:

Removes all discoverable credentials
Resets PIN and other authenticator configurations
Returns the authenticator to factory default state

Important considerations:

Destructive operation - cannot be undone
May require recent PIN authentication depending on authenticator policy
Typically used during device recycling or troubleshooting

Failed attempts are logged with error context.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

◆ ChangePIN()

Result< string > CrescendoDLL.SDKCore.ChangePIN ( string? newPin )

inline

This function changes the PIN based on the provided parameters.

Parameters

newPin The new PIN to be set. If not provided, a random 6-digit PIN is generated.

Returns: A Result{T} object, where Value is the new PIN value.
See documentation for Result{T} for more details.

If the newPin is not provided, a random 6-digit PIN is generated. If the newPin does not meet the length requirements stored on the token, an exception is thrown.

The function then tries to change the PIN to either the newPin , or the randomly generated value.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.NewToken().

◆ ChangeXAUTHMode()

Result CrescendoDLL.SDKCore.ChangeXAUTHMode ( XAUTHChallengeType xauthMode )

inline

This function changes the XAUTH mode based on the provided parameter.

Parameters

xauthMode XAUTH challenge type. Valid options are Static and Dynamic.

Returns: A Result object, where IsSuccess indicates successful change of the XAUTH mode.
See documentation for Result for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ ConfigureOATHSlot()

Result< string > CrescendoDLL.SDKCore.ConfigureOATHSlot	(	string?	oathSlot,
		int	buttonPress,
		string?	oathKey,
		string?	jsonInputPath,
		int	timeStep,
		OATHModeName	oathMode,
		string	oathCounter,
		HashAlgoValues	oathHash,
		int	codeDigits,
		string	friendlyName,
		int	truncationOffset,
		string	transportKey,
		string?	pskcString,
		bool	requireTouch = `false`
	)

inline

This function configures the OATH slot based on the provided parameters.

Parameters

oathSlot	The OATH slot to be configured.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only 0, 1 (on all Applet versions) or 2 (on Applet V4 version)
oathKey	The OATH key to be set.
jsonInputPath	The path to a JSON file containing encrypted `OATH` key as a part of Secure Key Injection. If this parameter is provided, the function will use the `OATH` key from the JSON file.
timeStep	The time step for the TOTP OATH algorithm in seconds.
oathMode	The OATH mode to be set. Valid options are `HOTP`, `TOTP`.
oathCounter	The OATH counter to be set.
oathHash	The hash algorithm to be used by the OATH algorithm. Valid options are `SHA1`, `SHA256` and `SHA512`.
codeDigits	The number of digits in the OATH code.
friendlyName	The friendly name for the slot.
transportKey	The transport key to be used. Has to be 16 bytes (32 digits) long.
pskcString	The current PSKC string, that should be updated. If left empty, completely new PSKC string will be created.
truncationOffset	Truncation Offset Value. Valid options are `0` and `16`
requireTouch	Indicates whether touch (button press) will be required to generate the OTP on the oathSlot . This parameter is valid only for Crescendo Keys V3, it will be ignored with any other device type.

Returns: A Result{T} object, where Value is the PSKC string.
See documentation for Result{T} for more details.

The function puts the OATH configuration to the token and then puts the OATH key to the token. The OATH key can be provided directly, or encrypted in a JSON file stored at jsonInputPath .

When working with V4 FIPS token, the OATH key will get transferred to the token using Secure Key Injection.

The function then updates (or creates new) PSKC string containing all necessary details and returns it.

References CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.GetSKITransportKey(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), CrescendoDLL.PCSC.APDUEngine.TokenName, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ ConfigureOCRASlot()

Result< string > CrescendoDLL.SDKCore.ConfigureOCRASlot	(	string?	oathSlot,
		int	buttonPress,
		string	ocraSuite,
		string?	oathKey,
		string?	jsonInputPath,
		string?	friendlyName,
		string	transportKey,
		string?	pskcString,
		bool	requireTouch = `false`
	)

inline

This function configures the OCRA OATH slot based on the provided parameters.

Parameters

oathSlot	The OATH slot to be configured.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only 0, 1 (on all Applet versions) or 2 (on Applet V4 version)
ocraSuite	The OCRA Suite string value in the format of `Algorithm:CryptoFunction:DataInput`, as described in RFC6287.
oathKey	The OATH key to be set.
jsonInputPath	The path to a JSON file containing encrypted `OATH` key as a part of Secure Key Injection. If this parameter is provided, the function will use the `OATH` key from the JSON file.
friendlyName	The friendly name for the slot.
transportKey	The transport key to be used. Has to be 16 bytes (32 digits) long.
pskcString	The current pskc string, that should be updated. If left empty, completely new pskc string will be created.
requireTouch	Indicates whether touch (button press) will be required to generate the OTP on the oathSlot . This parameter is valid only for Crescendo Keys V3, it will be ignored with any other device type.

Returns: A Result{T} object, where Value is the PSKC string.
See documentation for Result{T} for more details.

The function puts an OCRA OATH configuration to the token and then puts the OATH key to the token. The OATH key can be provided directly, or encrypted in a JSON file stored at jsonInputPath .

When working with V4 FIPS token, the OATH key will get transferred to the token using Secure Key Injection.

References CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.GetSKITransportKey(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), CrescendoDLL.PCSC.APDUEngine.TokenName, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ ConfigureStaticPassword()

Result CrescendoDLL.SDKCore.ConfigureStaticPassword	(	string?	password,
		string?	jsonInputPath,
		KeyboardEncodings	encoding,
		string?	oathSlot,
		int	buttonPress,
		string	friendlyName,
		bool	requireTouch = `false`
	)

inline

This function configures the Static Password on specified OATH slot based on the provided parameters. Only works with Applet version V4.

Parameters

password	The password to be stored to the token.
encoding	The keyboard encoding used to store the static password. Valid options are `US` and `FR`.
jsonInputPath	The path to a JSON file containing encrypted static password as a part of Secure Key Injection. If this parameter is provided, the function will use the static password from the JSON file.
oathSlot	The OATH slot to be configured.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only `1` or `2`
friendlyName	The friendly name for the slot.
requireTouch	Indicates whether touch (button press) will be required to generate the OTP on the oathSlot . This parameter is valid only for Crescendo Keys V3, it will be ignored with any other device type.

Returns: A Result object, where IsSuccess indicates successful static password configuration.
See documentation for Result for more details.

The function first puts the Static Password OATH configuration to the token and then puts password itself in given encoding to the token.

References CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.GetSKITransportKey(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), CrescendoDLL.PCSC.APDUEngine.TokenName, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ DeleteOATHSlot()

Result< string > CrescendoDLL.SDKCore.DeleteOATHSlot	(	string?	oathSlot,
		int	buttonPress,
		string?	pskcString
	)

inline

This function deletes the oathSlot configuration and key based on the provided parameters.

Parameters

oathSlot	The OATH slot to be deleted.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only 0, 1 (on all Applet versions) or 2 (on Applet V4 version)
pskcString	Optional pskc string, that should be updated. If left empty, completely new pskc string will be created.

Returns

A Result object, where IsSuccess indicates successful OATH slot configuration + key removal.
See documentation for Result for more details.

A Result{T} object, where Value is the updated PSKC string (if it was provided as in pskcString ).
See documentation for Result{T} for more details.

The function deletes the OATH key using the DeleteOATHKey method on applet V3, or deletes the entire OATH configuration using the DeleteOATHConf method on applet V4.

If parameter pskcString is provided, the function removes the existing KeyPackage with the same Slot ID from the XML content, and returns the updated PSKC XML structure as a string.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ DeleteXAUTHKey()

Result CrescendoDLL.SDKCore.DeleteXAUTHKey ( XAUTHKeyType xauthKeyType )

inline

This function deletes a Symmetric XAUTH key of a specified type from the token.

Parameters

xauthKeyType The type of the XAUTH key to be deleted. Possible options are TDES and AES.

Returns: A Result object, where IsSuccess indicates successful XAUTH key deletion.
See documentation for Result for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ Dispose()

void CrescendoDLL.SDKCore.Dispose ( )

inline

Releases all resources used by the CrescendoDLL.SDKCore instance.

It logs out any applet user might be logged into. It also disposes the CardContext object and disconnects and disposes the Reader object. Finally, it suppresses the finalization of the CrescendoDLL.SDKCore instance to prevent the garbage collector from calling the finalizer if it was overridden.

References CrescendoDLL.PCSC.APDUEngine.Dispose(), CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Logout().

◆ EncryptKEKAndDataWithKEK()

Result< string > CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK	(	AsymmetricKeyParameter	publicKey,
		object	inputData,
		KeyTypeToBeTransferredWithSKI	dataType,
		KeyboardEncodings	encoding = `KeyboardEncodings::US`
	)

inline

Encrypts the Key Encryption Key (KEK) and another input data (either PIV, XAUTH, OATH keys, or a STATICPASS static password) with the KEK.

Parameters

publicKey	The Secure Key Injection (SKI) RSA3072 public (transport) key.
inputData	The input data to be encrypted. This can be either `XAUTH` or `OATH` key (direct hex string representation), or `PIV` key (`AsymmetricKeyParameter` object).
dataType	The type of the key to be transferred with SKI.
encoding	The encoding of the input static password, if used. Default is `US`. Irrelevant for all the other input data types.

Returns: A Result{T} object, where Value is a string containing the encrypted data in JSON format.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.ConfigureOATHSlot(), CrescendoDLL.SDKCore.ConfigureOCRASlot(), CrescendoDLL.SDKCore.ConfigureStaticPassword(), CrescendoDLL.SDKCore.PIVPutPKIData(), and CrescendoDLL.SDKCore.PutXAUTHKey().

◆ Error()

record CrescendoDLL.SDKCore.Error	(	string	Code,
		string	Message
	)

inline

Represents an error with a code and a message.

Parameters

Code	The error code as a string.
Message	The error Message as a string

Represents no error.

Returns: An CrescendoDLL.SDKCore.Error instance with empty code and message.

Represents an error for a null value.

Returns: An CrescendoDLL.SDKCore.Error instance with code "Error.NullValue" and a null value message.

References CrescendoDLL.SDKCore.Error().

◆ FIDOChangePIN()

Result< string > CrescendoDLL.SDKCore.FIDOChangePIN ( string? newPin )

inline

Performs a PIN-authenticated FIDO2 CTAP ChangePIN operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

newPin The new PIN to set (6+ digits). If null/empty, generates a random 6-digit PIN.

Returns: A Result{T} object, where Value contains the new PIN string.
See documentation for Result{T} for more details.

This method implements the complete PIN change flow:

Generates random PIN if none provided
Retrieves authenticator capabilities via CrescendoDLL.SDKCore.AuthenticatorGetInfo
Performs key agreement.
Encrypts both old and new PIN hashes using shared secret
Verifies PIN length meets authenticator's minimum requirements (default 4)
Constructs and sends CTAP CrescendoDLL.SDKCore.AuthenticatorClientPIN request with changePIN subcommand

The operation automatically handles PIN padding and FIDO protocol version-specific encryption. Errors at any stage immediately abort the flow and return the first encountered error.

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA256, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ FIDOConfig()

Result CrescendoDLL.SDKCore.FIDOConfig ( CrescendoDLL::PCSC::FIDODataStructures::ConfigRequest configRequest )

inline

Performs a PIN-authenticated FIDO2 CTAP Authenticator Configuration operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

configRequest The Authenticator Configuration operation request (enable Enterprise Attestation, toggle AlwaysUV, set min PIN length and vendor specific).

Returns: A Result object, where IsSuccess indicates successful configuration of the FIDO token.
See documentation for Result{T} for more details.

This method implements the complete Authenticator Configuration flow:

Verifies CTAP 2.1 support through CrescendoDLL.SDKCore.AuthenticatorGetInfo
Performs key agreement.
Requests PIN token with Authenticator Configuration permission (0x20)
Constructs authenticated request using PIN token and command-specific data
Converts configRequest to CTAP-compliant CBOR encoding and sends it to the token using CrescendoDLL.SDKCore.AuthenticatorConfig

The operation requires valid PIN authentication with Authenticator Configuration permission. Errors at any stage immediately abort the flow and return the first encountered error.

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorConfig(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA256, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ FIDOCredentialManagement()

Result< CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse > CrescendoDLL.SDKCore.FIDOCredentialManagement ( CrescendoDLL::PCSC::FIDODataStructures::CredentialManagementRequest credentialManagementRequest )

inline

Performs a PIN-authenticated FIDO2 CTAP CredentialManagement operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

credentialManagementRequest The credential management operation request (enumerate/delete/update).

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.CredentialManagementResponse.
See documentation for Result{T} for more details.

This method implements the complete credential management flow:

Verifies CTAP 2.1 support through CrescendoDLL.SDKCore.AuthenticatorGetInfo
Performs key agreement.
Requests PIN token with CredentialManagement permission (0x04)
Constructs authenticated request using PIN token and command-specific data
Converts credentialManagementRequest to CTAP-compliant CBOR encoding and sends it to the token using CrescendoDLL.SDKCore.AuthenticatorCredentialManagement

The operation requires valid PIN authentication with CredentialManagement permission. Errors at any stage immediately abort the flow and return the first encountered error.

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorCredentialManagement(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA256, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ FIDOGetAssertion()

Result< CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse > CrescendoDLL.SDKCore.FIDOGetAssertion ( CrescendoDLL::PCSC::FIDODataStructures::GetAssertionRequest getAssertionRequest )

inline

Performs a PIN-authenticated FIDO2 CTAP GetAssertion operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

getAssertionRequest The assertion request parameters containing RP ID and client data hash.

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.GetAssertionResponse.
See documentation for Result{T} for more details.

This method implements the complete PIN authentication flow:

Retrieves authenticator capabilities via CrescendoDLL.SDKCore.AuthenticatorGetInfo
Performs key agreement.
Encrypts PIN hash using established shared secret
Requests PIN token with permissions (MakeCredential + GetAssertion for FIDO 2.1)
Constructs final assertion request with PIN authentication parameters

The operation automatically handles FIDO 2.1 specific permissions and PIN protocol version negotiation. Errors at any stage immediately abort the flow and return the first encountered error.

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorGetAssertion(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA256, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ FIDOMakeCredential()

Result< CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialResponse > CrescendoDLL.SDKCore.FIDOMakeCredential ( CrescendoDLL::PCSC::FIDODataStructures::MakeCredentialRequest makeCredentialRequest )

inline

Performs a PIN-authenticated FIDO2 CTAP MakeCredential operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

makeCredentialRequest The credential creation request containing relying party and user parameters.

Returns: A Result{T} object, where Value contains the CrescendoDLL.PCSC.FIDODataStructures.MakeCredentialRequest.
See documentation for Result{T} for more details.

This method implements the complete credential registration flow:

Retrieves authenticator capabilities via CrescendoDLL.SDKCore.AuthenticatorGetInfo
Performs key agreement.
Requests PIN token with permissions (MakeCredential + GetAssertion for FIDO 2.1)
Constructs authenticated request using PIN token and client data hash
Handles chunked APDU transmission through CrescendoDLL.SDKCore.AuthenticatorMakeCredential

Errors at any stage immediately abort the flow and return the first encountered error.

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.AuthenticatorMakeCredential(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA256, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ FIDOSetPIN()

Result< string > CrescendoDLL.SDKCore.FIDOSetPIN ( string? newPin )

inline

Performs initial FIDO2 CTAP PIN setup operation with full authentication flow. Elevated privileges are required on Windows.

Parameters

newPin The new PIN to set (6+ digits). If null/empty, generates a random 6-digit PIN.

Returns: A Result{T} object, where Value contains the new PIN string.
See documentation for Result{T} for more details.

This method implements the initial PIN setup flow:

Generates random PIN if none provided
Verifies no existing PIN is configured (checks authenticator's clientPin option)
Performs key agreement.
Encrypts new PIN using shared secret with CTAP PIN padding requirements
Constructs and sends CTAP CrescendoDLL.SDKCore.AuthenticatorClientPIN request with setPIN subcommand

The operation will fail if:

Authenticator already has PIN configured
New PIN doesn't meet minimum length requirements
Any cryptographic verification fails

References CrescendoDLL.SDKCore.AuthenticatorClientPIN(), CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ GenerateOTP()

Result< string > CrescendoDLL.SDKCore.GenerateOTP	(	string?	oathSlot,
		int	buttonPress
	)

inline

This function generates an OTP (One-Time Password) based on the provided parameters.

Parameters

oathSlot	The OATH slot to be used for generating the OTP.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only 0, 1 (on all Applet versions) or 2 (on Applet V4 version)

Returns: A Result{T} object, where Value is the generated OTP as a string.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ GetAllAvailableTokens()

static List<(string ReaderName, byte[] TokenATR, string TokenName, int TokenIndex)> CrescendoDLL.SDKCore.GetAllAvailableTokens ( )

inlinestatic

This function returns all available tokens and their ATRs in a list.

Returns: A List list with the reader's name, token name, token ATR (Answer To Reset), and the assigned index for the -t parameter, formatted like this: List<(string ReaderName, byte[] TokenATR, string TokenName, int TokenIndex)>.

Referenced by CrescendoDLL.SDKCore.PrintAllAvailableTokens().

◆ GetChallenge()

Result< string > CrescendoDLL.SDKCore.GetChallenge ( )

inline

Retrieves a XAUTH challenge.

Returns: A Result{T} object, where Value is the challenge that was retrieved from the ACA applet as a string.
See documentation for Result{T} for more details.

This function calls the GetChallenge method of the ACA applet to retrieve the XAUTH challenge, and returns it as a string.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ GetSKITransportKey()

Result< string > CrescendoDLL.SDKCore.GetSKITransportKey ( )

inline

This function retrieves the Secure Key Injection (SKI) RSA3072 transport key.

Returns: A Result{T} object, where Value is a base64 string containing the RSA3072 transport key.
See documentation for Result{T} for more details.

The function checks if a public / private Key pair exists on Key Reference 0xF0 and that the applet version is higher then 4.0. If both public and private keys are initialized, it reads the public key value (modulus and exponent). Otherwise, it generates a new key pair and gets the corresponding public key value.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.PIVGenerateKeyPair().

Referenced by CrescendoDLL.SDKCore.ConfigureOATHSlot(), CrescendoDLL.SDKCore.ConfigureOCRASlot(), CrescendoDLL.SDKCore.ConfigureStaticPassword(), CrescendoDLL.SDKCore.PIVPutPKIData(), and CrescendoDLL.SDKCore.PutXAUTHKey().

◆ ListACAProperties()

Result< string > CrescendoDLL.SDKCore.ListACAProperties ( )

inline

This function lists the properties of the ACA applet.

Returns: A Result{T} object, where Value is a string representation of the ACA applet properties in JSON format.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ ListFIDOProperties()

Result< string > CrescendoDLL.SDKCore.ListFIDOProperties ( )

inline

This function lists the properties of the FIDO Attestation Applet, as well as the basic parameters of the FIDO Authenticator when used with elevated privileges.

Returns: A Result{T} object, where Value is a string representation of the FIDO applet properties in JSON format.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.AuthenticatorGetInfo(), CrescendoDLL.PCSC.cert, CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.IsSuccess, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ ListOATHProperties()

Result< string > CrescendoDLL.SDKCore.ListOATHProperties ( )

inline

Lists the OATH properties of the OATH applet.

Returns: A Result{T} object, where Value is a string representation of the OATH applet properties in JSON format.
See documentation for Result{T} for more details.

This function gets OATH applet properties for each possible AID and stores them into an array.

The function then serializes the array into a JSON string using the JsonConvert.SerializeObject method.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), and CrescendoDLL.SDKCore.Result< T >.Success().

◆ ListPIVProperties()

Result< string > CrescendoDLL.SDKCore.ListPIVProperties ( )

inline

Prints the properties of the PIV applet.

Returns: A Result{T} object, where Value is a string representation of the PIV applet properties in JSON format.
See documentation for Result{T} for more details.

This function gets PIV applet properties and serializes them into a JSON string using the JsonConvert.SerializeObject method.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ Logout()

Result CrescendoDLL.SDKCore.Logout ( )

inline

Logs out of the ACA applet and clears the cache.

Returns: A Result object, where IsSuccess indicates successful logout from the ACA applet.
See documentation for Result for more details.

This function attempts to log out of the ACA applet. If the logout is successful, it clears the authentication cache.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.Dispose().

◆ NewToken()

Result< string > CrescendoDLL.SDKCore.NewToken ( string? newPin )

inline

Personalizes a new token with newPin , generates and returns a new PUK and personalizes the PIV Personal info (CHUID).

Parameters

newPin The new PIN to be set on the token. If left empty, PIN will not change from the default value.

Returns: A Result{T} object, where Value is the PUK that was put on the token as a string.
See documentation for Result{T} for more details.

This function attempts to personalize a new token.

It first resets the token and updates the PIN properties to default values.

After that, if newPin is provided, it changes the PIN from the default value to newPin .

A random PUK is generated and put on the token. It also uploads the PUK relevant data to the PIV Data objects.

Finally, it uploads the PIV Personal info (CHUID) and Card Capability Container to the token.

References CrescendoDLL.SDKCore.ChangePIN(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.PIVAddDataToDataObject(), CrescendoDLL.SDKCore.PUKPut(), CrescendoDLL.SDKCore.ResetToken(), CrescendoDLL.SDKCore.Result< T >.Success(), CrescendoDLL.SDKCore.UpdatePINProperties(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ OCRAAuthenticate()

Result< string > CrescendoDLL.SDKCore.OCRAAuthenticate	(	string?	oathSlot,
		int	buttonPress,
		string	challenge,
		string?	secret,
		string?	session
	)

inline

This function performs an OCRA Challenge Response or Digital Signature operation with previously configured OCRA slot.

Parameters

oathSlot	The OATH slot to be configured.
buttonPress	The number of button presses required to activate the slot, when working with Crescendo Keys. This can be only 0, 1 (on all Applet versions) or 2 (on Applet V4 version)
challenge	The challenge to be used for the OCRA operation - this corresponds to `Q` in the RFC6287.
secret	The secret (PIN/Password) to be Hashed and used for the OCRA operation - this corresponds to `P` in the RFC6287 before the hashing operation.
session	The session information to be used for the OCRA operation - this corresponds to `S` in the RFC6287.

Returns: A Result{T} object, where Value is the result of the OCRA operation as a string.
See documentation for Result{T} for more details.

The function reads the OCRA configuration from specified OATH slot, and processes the input data accordingly. If secret or session are required but not entered, it throws an exception.

The function then constructs the OCRA message and sends it to the token for processing. The OCRA authentication result is then returned as a string.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA1, CrescendoDLL.PCSC.SHA256, CrescendoDLL.PCSC.SHA512, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVAddDataToDataObject()

Result CrescendoDLL.SDKCore.PIVAddDataToDataObject	(	string	berTLVTag,
		List<(string tag, byte[] data)>	tagsData
	)

inline

This function adds one or multiple data items to a PIV data object on a token.

Parameters

berTLVTag	The BER-TLV tag of the data object to which data is to be added.
tagsData	A list of tuples, where each tuple contains a tag (string) and its corresponding data (byte array) to be added.

Returns: A Result object, where IsSuccess indicates successful data addition.
See documentation for Result for more details.

This function first retrieves the PIV data object from the token using the specified berTLVTag . The function then tries to add each specified tagsData to the PIV data object.

If the same tag already exists in the PIV data object, it gets rewritten.

References CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.NewToken(), and CrescendoDLL.SDKCore.PIVGenerateKeyPair().

◆ PIVChangeDataObjectACR()

Result CrescendoDLL.SDKCore.PIVChangeDataObjectACR	(	string	berTLVTag,
		string	personalizationACR,
		string	contactUsageACR,
		string	contactlessUsageACR
	)

inline

This function changes the Access Control Rules (ACR) of a given PIV data object on a token.

Parameters

berTLVTag	The BER-TLV tag of the data object whose ACR is to be changed.
personalizationACR	The personalization ACR to be set.
contactUsageACR	The contact usage ACR to be set.
contactlessUsageACR	The contactless usage ACR to be set.

Returns: A Result object, where IsSuccess indicates successful ACR change on the specified data object.
See documentation for Result for more details.

This function first checks the applet version (ACR can be modified only on applet V4). It then checks if the Data object identified by berTLVTag is empty. If it is, the function stores the ACR on the specified PIV data object using the provided ACR values.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.PIVPutPKIData().

◆ PIVChangePKISlotACR()

Result CrescendoDLL.SDKCore.PIVChangePKISlotACR	(	string	keyReference,
		string	personalizationACR,
		string	contactUsageACR,
		string	contactlessUsageACR
	)

inline

This function puts the PKI (Public Key Infrastructure) data to the token based on the provided parameters.

Parameters

keyReference	The PIV Key reference to be used for private key storage.
personalizationACR	The personalization ACR to be set.
contactUsageACR	The contact usage ACR to be set.
contactlessUsageACR	The contactless usage ACR to be set.

Returns: A Result object, where IsSuccess indicates successful PKI slot ACR change.
See documentation for Result for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVDeleteCertificate()

Result CrescendoDLL.SDKCore.PIVDeleteCertificate ( string berTLVTag )

inline

This function deletes a certificate identified by the berTLVTag from a token.

Parameters

berTLVTag The BER-TLV tag of the certificate to be deleted.

Returns: A Result object, where IsSuccess indicates successful certificate deletion.
See documentation for Result for more details.

The Function first retrieves the data object from the token using the berTLVTag and extracts the certificate from the data object.

If the public key stored under tag 0x68 does not correspond to the public key from the certificate (or if there is no tag 0x68 in the PIV Data Object), it adds the public key from the certificate to the dataObject.

It then removes both tags connected to the certificate from the PIV Data Object.

References CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVDeleteDataFromDataObject()

Result CrescendoDLL.SDKCore.PIVDeleteDataFromDataObject	(	string	berTLVTag,
		string	tag
	)

inline

This function deletes data identified by a tag from a PIV data object on a token.

Parameters

berTLVTag	The BER-TLV tag of the data object from which data is to be deleted.
tag	The tag of the data to be deleted. If set to `all`, all data from the data object will be deleted.

Returns: A Result object, where IsSuccess indicates successful data deletion.
See documentation for Result for more details.

This function retrieves the PIV data object from the token using the specified berTLVTag and removes the specified tag from the PIV data object. If the parameter tag is all, it removes all content from the PIV data object.

It then constructs a new data field from the updated PIV data object and updates the PIV data object on the token.

References CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVDeleteKey()

Result CrescendoDLL.SDKCore.PIVDeleteKey ( string keyReference )

inline

This function deletes a PIV key from the provided key reference.

Parameters

keyReference The key reference to the key that needs to be deleted.

Returns: A Result object, where IsSuccess indicates successful key deletion.
See documentation for Result for more details.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVGenerateKeyPair()

Result< string > CrescendoDLL.SDKCore.PIVGenerateKeyPair	(	PIVCryptographicMechanismIdentifier	cryptoMechanism,
		string	keyReference,
		bool	getExistingPublicKey = `false`
	)

inline

Generates an asymmetric key pair on the ACA applet or retrieves the public key and the public exponent of a previously generated key pair, if possible.

Parameters

cryptoMechanism	The cryptographic mechanism identifier to be used for key pair generation. Possible options are `RSA2048`, `RSA3072`, `RSA4096`, `CURVEP256` and `CURVEP384`.
keyReference	The key reference for the key pair.
getExistingPublicKey	A boolean indicating whether to retrieve the public key and the public exponent of a previously generated key pair. If false, a new key pair is generated.

Returns: A Result{T} object, where Value is the public key encoded in base64 string.
See documentation for Result{T} for more details.

This function attempts to generate an asymmetric key pair on the ACA applet or retrieve the public key and the public exponent of a previously generated key pair based on the getExistingPublicKey parameter.

If getExistingPublicKey is true, it checks if the input key reference exists and has an initialized public key. If not, it throws an exception. If getExistingPublicKey is false, it tries to generate an asymmetric key pair on the specified keyReference with the specified cryptoMechanism .

If getExistingPublicKey is true, it logs a success message indicating the successful retrieval of the asymmetric key pair. If getExistingPublicKey is false, it updates the cache freshness and logs a success message indicating the successful generation of the asymmetric key pair.

The function then constructs and returns the public key parameters based on the cryptographic mechanism identifier.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.PIV, CrescendoDLL.SDKCore.PIVAddDataToDataObject(), CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

Referenced by CrescendoDLL.SDKCore.GetSKITransportKey().

◆ PIVGetCertificate()

Result< string > CrescendoDLL.SDKCore.PIVGetCertificate ( string berTLVTag )

inline

This function retrieves a certificate defined by the berTLVTag from a token and exports it as a PFX file.

Parameters

berTLVTag The BER-TLV tag of the certificate to be retrieved.

Returns: A Result{T} object, where Value is the content of the PFX file encoded in base64 string.
See documentation for Result{T} for more details.

The function first retrieves the data object from the token using the berTLVTag tag and extracts the certificate from the data object. It then exports the certificate to a base64 string.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVGetDataObjectContent()

Result< string > CrescendoDLL.SDKCore.PIVGetDataObjectContent ( string berTLVTag )

inline

This function retrieves a PIV data object from a token and returns its content as a JSON string.

Parameters

berTLVTag The BER-TLV tag of the data object to be retrieved.

Returns: A Result{T} object, where Value is the content of the retrieved PIV data object as a JSON string.
See documentation for Result{T} for more details.

This function retrieves a PIV data object from the token using the specified berTLVTag . It then serializes the data object into a JSON string.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVGetPersonalInfo()

Result< string > CrescendoDLL.SDKCore.PIVGetPersonalInfo ( )

inline

Retrieves personal information from a PIV (Personal Identity Verification) card.

The function retrieves the personal information from the PIV card by reading the Card Holder Unique Identifier and Printed Information data objects. The data is then serialized into a JSON string.

Returns: A Result{T} object, where Value is the JSON representation of the PIV Personal Data.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.PIV, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVPutPKIData()

Result CrescendoDLL.SDKCore.PIVPutPKIData	(	string	inputFilePath,
		string?	password,
		PIVObjectType	pkiObjectType,
		string?	keyReference,
		string?	berTLVTag,
		string?	keyName
	)

inline

This function puts the PKI (Public Key Infrastructure) data to the token based on the provided parameters.

Parameters

inputFilePath	The path to the input file containing the PKI data. This can be either `P12`, `PFX`, `PEM`, or `JSON` file.
password	Optional password for the input file. Used for `P12` of `PFX` files.
pkiObjectType	The type of the PKI object to be imported to the token (private key, certificate, both, or SKI wrapped secret).
keyReference	The PIV Key reference to be used for private key storage.
berTLVTag	The BER-TLV tag of a PIV Data object where a certificate should be stored.
keyName	Optional name of the PIV key. Can be any string max. 32 characters long.

Returns: A Result object, where IsSuccess indicates successful import of the PKI data to the token.
See documentation for Result for more details.

Depending on the pkiObjectType , the function either puts the private key to the token, puts the certificate to the token, or puts both the private key and the certificate to the token. If the pkiObjectType is unknown, it throws an exception.

For each PKI object type, the function determines the action based on the user input of keyReference and berTLVTag . It either puts the key or certificate to the token using the provided keyReference or berTLVTag , or finds the first key reference with an uninitialized private key and puts the key to the token using that key reference.

If none of the parameters keyReference and berTLVTag are entered and the pkiObjectType is cert, the function also checks if the public key from the certificate matches any BER-TLV buffer with a public key and an initialized private key in the corresponding key reference. If it does not find any match, it throws an exception.

References CrescendoDLL.PCSC.cert, CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.GetSKITransportKey(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.PIV, CrescendoDLL.SDKCore.PIVChangeDataObjectACR(), CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVRawCryptoOperation()

Result< string > CrescendoDLL.SDKCore.PIVRawCryptoOperation	(	string	keyReference,
		DataType	inputType,
		string?	inputString,
		string?	inputFilePath,
		DataType	outputType
	)

inline

This function performs a raw cryptographic operation using a private key stored on the token. This is primarily meant for RSA keys, though it is possible to use ECC key as well.

Parameters

keyReference	The reference to the private key that will be used for the cryptographic operation.
inputType	The encoding type of the input string. Valid options are `HEX`, `BASE64`, `BASE64URL` and `UTF8`. If the input is read from a file, another option `BIN` (read bytes directly) is available.
inputString	The input data to be used in the cryptographic operation.
inputFilePath	The path to the file containing the data to be used in the cryptographic operation.
outputType	The encoding type of the output string. Valid options are `HEX`, `BASE64`, `BASE64URL` and `UTF8`. If the output is read from a file, another option `BIN` (write bytes directly) is available.

Returns: A Result{T} object, where Value is the result of the cryptographic operation as a outputType encoded string.
See documentation for Result{T} for more details.

This function starts by reading the data in specified format inputType from the file specified by inputFilePath , or directly as a inputFilePath .

No padding is applied to the input data. You are fully responsible for the proper length and encoding of the input data.

Cryptographic operation using the private key defined by it's keyReference is then performed on the input data. Result of the cryptographic operation in defined format outputType is then returned.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PIVSignData()

Result< string > CrescendoDLL.SDKCore.PIVSignData	(	string	keyReference,
		DataType	inputType,
		string?	inputString,
		string?	inputFilePath,
		DataType	outputType,
		HashAlgoValues	hashAlgo,
		DataType	hashType = `DataType::BASE64`
	)

inline

This function signs data using a defined PIV key.

Parameters

keyReference	The reference to the key that will be used for signing.
inputType	The encoding type of the input string. Valid options are `HEX`, `BASE64`, `BASE64URL` and `UTF8`. If the input is read from a file, another option `BIN` (read bytes directly) is available.
inputString	The input string to be signed.
inputFilePath	The path to the file containing the data to be signed.
outputType	The encoding type of the output string. Valid options are `HEX`, `BASE64`, `BASE64URL` and `UTF8`. If the output is read from a file, another option `BIN` (write bytes directly) is available.
hashAlgo	Hash algorithm to be used for input data hashing. Valid options are `SHA1`, `SHA256` and `SHA512`
hashType	The encoding type of the hash string. Valid options are `HEX`, `BASE64`, `BASE64URL` and `UTF8`. If the hash is to be saved to a file, another option `BIN` (write bytes directly) is available

Returns: A Result{T} object, where Value is the signed data as a outputType encoded string..
See documentation for Result{T} for more details.

This function starts by reading the data in specified format inputType from the file specified by inputFilePath , or directly as a inputFilePath . It then hashes it using the hashAlgo algorithm.

Depending on the cryptographic mechanism of the Key, the function prepares the data for signing. For RSA mechanisms, the function pads the data to the appropriate length according to the PKCS1 padding scheme. For ECC mechanisms, the function uses the hash directly.

The prepared hashed data is then signed by the private key defined by it's keyReference . Signature in defined format outputType is then returned.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.PCSC.SHA1, CrescendoDLL.PCSC.SHA256, CrescendoDLL.PCSC.SHA512, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ PrintAllAvailableTokens()

static void CrescendoDLL.SDKCore.PrintAllAvailableTokens ( )

inlinestatic

This function prints all available tokens and their ATRs to the log.

For each reader with a token, The function adds an item to a list with the reader's name, token name, token ATR (Answer To Reset), and the assigned number for the -t parameter. Finally, it prints the list to the log.

References CrescendoDLL.SDKCore.GetAllAvailableTokens().

◆ PUKPut()

Result< string > CrescendoDLL.SDKCore.PUKPut	(	string?	puk,
		bool	storePukToPIVDataObjects = `true`
	)

inline

Puts a PUK on the token. If no PUK is provided, a random 8 byte PUK is generated.

Parameters

puk	The PUK to be put on the token. If this is null or empty, a random PUK is generated.
storePukToPIVDataObjects	Default value is `true`. If set to false the PUK value will not be stored in the corresponding PIV data objects, meaning it will not be retrievable later.

Returns: A Result{T} object, where Value is the PUK that was put on the token as a string.
See documentation for Result{T} for more details.

This function begins by checking if the puk parameter is null or empty.

If puk is null or empty, it generates a random 8 byte PUK.

The function then calls the ChangeReferenceData method of the ACA applet with the PUK (either the one provided or the one it generated) to change or create the PUK on the token.

If the PUK putting process is successful, it updates the cache freshness.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.NewToken().

◆ PutXAUTHKey()

Result CrescendoDLL.SDKCore.PutXAUTHKey	(	string?	xauthKey,
		XAUTHKeyType?	xauthKeyType,
		string?	jsonInputPath
	)

inline

This function puts a Symmetric XAUTH key of a specified type onto the token.

Parameters

xauthKey	The `XAUTH` key to be put onto the token. If this parameter is null or empty, a default `XAUTH` key will be used based on the xauthKeyType .
xauthKeyType	The type of the `XAUTH` key to be put onto the token. Valid options are `AES` and `TDES`. If this parameter is null, the `XAUTH` key type will be determined based on the length of xauthKey
jsonInputPath	The path to a JSON file containing encrypted `XAUTH` key as a part of Secure Key Injection. If this parameter is provided, the function will use the `XAUTH` key from the JSON file.

Returns: A Result object, where IsSuccess indicates successful XAUTH key storage.
See documentation for Result for more details.

Only one of the input parameters xauthKey , xauthKeyType or jsonInputPath should be provided.

The function then uses either provided XAUTH key, a default XAUTH key (in case xauthKeyType is provided) or the encryptedSecret from the JSON file and configures it onto the token.

When working with V4 FIPS token, the XAUTH key will get transferred to the token using Secure Key Injection by default.

References CrescendoDLL.SDKCore.EncryptKEKAndDataWithKEK(), CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.GetSKITransportKey(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Value.

◆ ReadCacheFreshness()

Result< string > CrescendoDLL.SDKCore.ReadCacheFreshness ( )

inline

Reads the cache freshness.

Returns: A Result{T} object, where Value is the content of the cache as a string.
See documentation for Result{T} for more details.

This function checks the applet version and throws an InvalidDataException if the applet version is less than 4.0.

It then gets a cache freshness data object from the token. If the data object is empty, it logs a warning message.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, CrescendoDLL.SDKCore.Result< T >.Success(), and CrescendoDLL.SDKCore.Result< T >.Value.

◆ ResetPINTries()

Result CrescendoDLL.SDKCore.ResetPINTries	(	string	newPin,
		string	puk
	)

inline

This function resets the PIN tries based on the provided parameters.

Parameters

newPin	The new PIN to be set.
puk	The PUK (Personal Unblocking Key) used for resetting the PIN tries.

Returns: A Result object, where IsSuccess indicates successful reset of the PIN try number.
See documentation for Result for more details.

If the puk is not empty, the function resets the PIN tries using the ACAApplet's ResetPINTries method and stores the new PIN in cache.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

◆ ResetToken()

Result CrescendoDLL.SDKCore.ResetToken ( )

inline

Resets the token to its default state.

Returns: A Result object, where IsSuccess indicates successful reset of the token.
See documentation for Result for more details.

This function attempts to reset the token to its default state. It first checks if authentication is necessary and performs it if needed. If the authentication fails, it throws an exception. The function then attempts to reset the token, store the default PIN in the cache, and update the cache freshness. Each of these operations returns a boolean indicating its success. If any operation fails, the function will return false.

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.NewToken().

◆ SetLogAction()

static void CrescendoDLL.SDKCore.SetLogAction ( CrescendoDLL::Logger::LogActionDelegate logAction )

inlinestatic

Sets the action to be performed when a log message is generated.

Parameters

logAction The action to be performed when a log message is generated.

◆ SetLogLevel()

static void CrescendoDLL.SDKCore.SetLogLevel ( LogLevel severity )

inlinestatic

Sets the severity level for logging.

Parameters

severity The severity level for logging. Valid options are DEBUG, INFO, WARN, ERROR and SILENT

◆ SetPINDialog()

void CrescendoDLL.SDKCore.SetPINDialog ( Func< SecretType, string > userDialog )

inline

Sets the method to gather the PIN from the user.

Parameters

userDialog The method to gather the PIN from the user.

Referenced by CrescendoDLL.SDKCore.SetPINForPythonWrapper().

◆ SetPINForPythonWrapper()

void CrescendoDLL.SDKCore.SetPINForPythonWrapper ( string pin )

inline

Sets the PIN for the Python wrapper.

Parameters

pin	The `PIN` to be set.

This function is an override specifically for the Python wrapper. It uses the SetPINDialog function to set the method for gathering the PIN as just passing the pin .

References CrescendoDLL.SDKCore.SetPINDialog().

◆ SetXAUTHDialog()

void CrescendoDLL.SDKCore.SetXAUTHDialog ( Func< SecretType, string > userDialog )

inline

Sets the method to gather the XAUTH from the user.

Parameters

userDialog The method to gather the XAUTH from the user.

Referenced by CrescendoDLL.SDKCore.SetXAUTHForPythonWrapper().

◆ SetXAUTHForPythonWrapper()

void CrescendoDLL.SDKCore.SetXAUTHForPythonWrapper ( string xauth )

inline

Sets the XAUTH for the Python wrapper.

Parameters

xauth The XAUTH to be set.

This function is an override specifically for the Python wrapper. It uses the SetXAUTHDialog function to set the method for gathering the PIN as just passing the xauth .

References CrescendoDLL.SDKCore.SetXAUTHDialog().

◆ U2FAuthentication()

Result< CrescendoDLL.PCSC.FIDODataStructures.U2FAuthenticationResponse > CrescendoDLL.SDKCore.U2FAuthentication ( CrescendoDLL::PCSC::FIDODataStructures::U2FAuthenticationRequest authenticationRequest )

inline

Performs a FIDO U2F (CTAP 1) authentication operation to verify a credential.

Parameters

authenticationRequest Authentication parameters including key handle and user presence requirements

Returns: A Result{T} object, where Value contains the contains the CrescendoDLL.PCSC.FIDODataStructures.U2FAuthenticationResponse.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

◆ U2FGetVersion()

Result< string > CrescendoDLL.SDKCore.U2FGetVersion ( )

inline

Retrieves the supported U2F protocol version from the authenticator.

Returns: A Result{T} object, where Value contains the version string (e.g., "U2F_V2").
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

◆ U2FRegistration()

Result< CrescendoDLL.PCSC.FIDODataStructures.U2FRegistrationResponse > CrescendoDLL.SDKCore.U2FRegistration ( CrescendoDLL::PCSC::FIDODataStructures::U2FRegistrationRequest registrationRequest )

inline

Performs a FIDO U2F (CTAP 1) registration operation to create a new credential.

Parameters

registrationRequest Registration parameters containing challenge and application data

Returns: A Result{T} object, where Value contains the contains the CrescendoDLL.PCSC.FIDODataStructures.U2FRegistrationResponse.
See documentation for Result{T} for more details.

References CrescendoDLL.SDKCore.Engine, and CrescendoDLL.SDKCore.Result< T >.IsFailure.

◆ UpdatePINProperties()

Result CrescendoDLL.SDKCore.UpdatePINProperties	(	int?	maxPinTryCounter,
		int?	maxPinUnlockCounter,
		int?	maxContactlessPinCounter,
		int?	minPinLength,
		int?	maxPinLength,
		int	weakPinControl,
		int	changePinAfterFirstUse,
		int	pinNumericOnly
	)

inline

Updates the PIN properties on the ACA applet.

Parameters

maxPinTryCounter	The maximum number of PIN tries allowed on contact interface.
maxPinUnlockCounter	The maximum number of PIN unlock tries allowed.
maxContactlessPinCounter	The maximum number of PIN tries allowed on contactless interface.
minPinLength	The minimum length of the PIN.
maxPinLength	The maximum length of the PIN.
weakPinControl	The weak PIN control parameter. True means weak Pin control enabled, false means weak pin control disabled
changePinAfterFirstUse	The parameter indicating whether to change the PIN after first use.
pinNumericOnly	The parameter indicating whether the PIN is numeric only.

Returns: A Result object, where IsSuccess indicates successful PIN properties update.
See documentation for Result for more details.

This function attempts to update the PIN properties on the ACA applet. If the ACA applet version is less than 4.0 and any of the maxPinTryCounter , maxPinUnlockCounter , or maxContactlessPinCounter parameters are not null, it logs a warning message indicating that these values cannot be modified on applets with a version less than 4.0.

The function then attempts to update the PIN properties on the ACA applet. If the applet version is 4.0 or higher, it updates the PIN properties separately for changePinAfterFirstUse and weakPinControl (separate APDUs are needed).

References CrescendoDLL.SDKCore.Engine, CrescendoDLL.SDKCore.Result< T >.Error, CrescendoDLL.SDKCore.Error(), CrescendoDLL.SDKCore.Result< T >.Failure(), CrescendoDLL.SDKCore.Result< T >.IsFailure, and CrescendoDLL.SDKCore.Result< T >.Success().

Referenced by CrescendoDLL.SDKCore.NewToken().

◆ VerifyPin()

Result CrescendoDLL.SDKCore.VerifyPin ( )

inline

Authenticates on the ACA using PIN, or verifies the authentication status in no PIN is provided.

Returns: A Result object, where IsSuccess indicates successful verification of provided PIN.
See documentation for Result for more details.

This function determines PIN gathered from CrescendoDLL.SDKCore.SetPINDialog(), and tries to authenticate with it on the ACA applet. If no PIN is provided, the function simply verifies whether the user is already authenticated or not.

Member Data Documentation

◆ Engine

APDUEngine CrescendoDLL.SDKCore.Engine

The Engine object contains references to applet objects, their current properties and all the necessary internal methods to allow PCSC communication with the SmartCard.

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ SecretType

Constructor & Destructor Documentation

◆ SDKCore()

Member Function Documentation

◆ AuthenticateWithXAUTH()

◆ AuthenticatorClientPIN()

◆ AuthenticatorConfig()

◆ AuthenticatorCredentialManagement()

◆ AuthenticatorGetAssertion()

◆ AuthenticatorGetInfo()

◆ AuthenticatorGetNextAssertion()

◆ AuthenticatorMakeCredential()

◆ AuthenticatorReset()

◆ ChangePIN()

◆ ChangeXAUTHMode()

◆ ConfigureOATHSlot()

◆ ConfigureOCRASlot()

◆ ConfigureStaticPassword()

◆ DeleteOATHSlot()

◆ DeleteXAUTHKey()

◆ Dispose()

◆ EncryptKEKAndDataWithKEK()

◆ Error()

◆ FIDOChangePIN()

◆ FIDOConfig()

◆ FIDOCredentialManagement()

◆ FIDOGetAssertion()

◆ FIDOMakeCredential()

◆ FIDOSetPIN()

◆ GenerateOTP()

◆ GetAllAvailableTokens()

◆ GetChallenge()

◆ GetSKITransportKey()

◆ ListACAProperties()

◆ ListFIDOProperties()

◆ ListOATHProperties()

◆ ListPIVProperties()

◆ Logout()

◆ NewToken()

◆ OCRAAuthenticate()

◆ PIVAddDataToDataObject()

◆ PIVChangeDataObjectACR()

◆ PIVChangePKISlotACR()

◆ PIVDeleteCertificate()

◆ PIVDeleteDataFromDataObject()

◆ PIVDeleteKey()

◆ PIVGenerateKeyPair()

◆ PIVGetCertificate()

◆ PIVGetDataObjectContent()

◆ PIVGetPersonalInfo()

◆ PIVPutPKIData()

◆ PIVRawCryptoOperation()

◆ PIVSignData()

◆ PrintAllAvailableTokens()

◆ PUKPut()

◆ PutXAUTHKey()

◆ ReadCacheFreshness()

◆ ResetPINTries()

◆ ResetToken()

◆ SetLogAction()

◆ SetLogLevel()

◆ SetPINDialog()

◆ SetPINForPythonWrapper()

◆ SetXAUTHDialog()

◆ SetXAUTHForPythonWrapper()

◆ U2FAuthentication()

◆ U2FGetVersion()

◆ U2FRegistration()

◆ UpdatePINProperties()

◆ VerifyPin()

Member Data Documentation

◆ Engine