Release Notes

What's New in Crescendo SDK 2.0

This version provides the following improvements with respect to the previous version:

Warning!

Breaking changes in Crescendo SDK

  • The PIVGetCertificate() function now returns the X509Certificate2 object instead of a string containing the PFX encoding of the certificate.

  • The PIVChangeDataObjectACR() and PIVChangePKISlotACR() functions now have ACRCoding enumeration values as input, instead of the hex-strings used previously.

New Features

  • Added support for macOS, with two limitations:

    • The interactive PIN window inside the CLI (the -p interactive parameter) is replaced with command-line PIN entry.

    • The advanced FIDO functionality on Crescendo Key V3 (any operation using the USB-HID communication protocol, i.e. the functions for registering or managing credentials) is currently not supported on macOS.

  • Added the usage of Access Control Rules (ACRs) for PIV data objects and keys for personalization and usage. All related PIV commands/functions now respect the set ACRs. Added the ACRCoding enumeration to describe all possible ACRs that can be set:

    • The functions PIVChangeDataObjectACR() and PIVChangePKISlotACR() (the piv-data-acr and piv-pki-acr CLI commands) now use the ACRCoding values, instead of string input.

    • The PIVGenerateKeyPair(), PIVPutPKI(), PIVDeleteKey(), PIVPutData(), PIVGetData(), PIVGetPersonalInfo(), PIVDeleteData(), PIVRawCryptoOperation(), PIVSignData(), PIVGetCertificate(), and PIVDeleteCertificate() functions now require authentication via PIN or XAUTH only when a corresponding ACR is set on a given data object or key.

    • The ListPIVProperties() function (the piv-props-get CLI command) now displays the ACRs as human-readable strings.

    • The ACRCoding enumeration also has the Unknown member to accommodate any values previously set on the data objects and keys. If ACRCoding.Unknown is encountered, default ACRs are used for personalization and usage.

  • Added a check that prevents users from generating a one-time password on an OATH slot that is configured with OATHModeName.OCRA, and vice versa; this prevents users from authenticating with OCRA on an OATH slot that is configured with anything else than OATHModeName.OCRA.

  • Added the -h parameter as an additional way to get help in CLI Tool.

  • Added the FIDOMDSMetadata property to PCSC.ReaderInfo that includes the description of the given device in FIDO Alliance Metadata Service (MDS). See the FIDO specification for more details on MDS.

  • Added basic exit codes to the CLI to indicate success or failure of the executed command. The 0 exit code indicates successful execution; any other code indicates failure. All available options are described in the documentation.

  • A Static Password can now be configured only on button-press slots for Crescendo Key V3. A Static Password cannot be programmatically generated on other slots than the button-press slots. This aligns the SDK functionality with the HID Crescendo Manager behavior.

  • Added the keyName parameter to PIVGenerateKeyPair (the piv-key-pair-gen CLI command) to allow specifying a custom key name during key pair generation, instead of the default value. If not specified, the default naming convention will be used (i.e., SDK_generated_key_<GUID>).

  • Added the new SHA224, SHA384, and MD5 hashing algorithms to the HashAlgoValues enumeration. This allows the use of PIVSignData with ECC-384 and the corresponding hash. Added additional checks to the OATH applet to ensure compatibility because OATH still supports only SHA1, SHA256, and SHA512.

  • Modified the return value of PIVGetCertificate—it now returns the X509Certificate2 object directly instead of a base64 encoded PFX representation of the certificate. This should lead to easier certificate handling in the SDK. No changes in CLI Tool were made; the --piv-cert-get command remains unchanged.

  • Fixed several typos in the CLI help and examples; several parameter descriptions were enhanced to provide greater clarity.

Bug Fixes

  • Added high-level parsing of CLI arguments to catch possible incorrect inputs, such as -newPIN instead of --newPIN. The -newPIN argument should not be valid, but previously it was successfully parsed as an -n argument with the value of ewPin. The CLI will now output an error message indicating the usage of an incorrect argument.

  • Fixed an issue in ConfigureOATHSlot (the otp-slot-configure CLI command) that prevented configuring an additional button-press slot on Crescendo Key V3 after one had already been configured.

  • Fixed a bug in DeleteOATHSlot (the otp-slot-delete CLI command) that failed to delete the corresponding section from the PSKC file.

  • Fixed parsing of FIDO properties on Crescendo C4000 FIPS devices. The SELECT response is now parsed correctly.

  • Fix a bug that required the use of SetPinDialog() before calling VerifyPin(). VerifyPin() can now be called anytime without specifying a PIN to check the status of PIN verification or to find out if the PIN is blocked.

  • Fix a bug where the SDK would throw an exception if authentication with either PIN or XAUTH failed. It now returns Result.Failure in a controlled manner.

  • Fixed parsing the AuthenticatorData class inside FIDODataStructures. Previously, the Extensions byte array was always null by mistake. If the Extensions field is present, it will now get correctly parsed and stored in the new Extensions class inside FIDODataStructures to offer a human-readable form of the FIDO extensions in addition to a raw byte array.

New Features

  • Added the ability to store certificate chains on the tokens, for both C2300 and C4000.

  • Enhanced ListFIDOProperties (the fido-props-get command in CLI Tool) to display as much information about FIDO Enterprise Attestation as possible.

  • Added parsing of the PIV Applet Instance Form byte in ListACAProperties (the aca-props-get command in CLI Tool) to decode PIV EP, PIV EP ENTERPRISE and PIV EXT.

Bug Fixes

  • Fixed the Result class output in the SDK, so that in case of any error, the actual error code and message would get passed to the user, instead of a generic message.

  • SDK function GetTokenCUID() - changed the log level of the success message containing the CUID from INFO to DEBUG.

  • Documentation improvements and small fixes. The main improvements can be found in the PIVPutPKIData function description, which now includes all possible import scenarios.

New Features

  • Added proper parsing for the original AuthData byte array structure - AuthenticatorData class inside FIDODataStructures.

  • Added PinUvAuthTokenPermissions Enum structure to easily handle the permissions of the PinUvAuthToken parameter in the ClientPINRequest and ClientPINResponse classes.

  • Added fido-cred-list and --fido-cred-delete commands to the CLI, to allow managing the FIDO credentials directly from the command line. There is also a corresponding FIDOListCredentials() method in the SDK. Credential deleting utilizes the already existing FIDOCredentialManagement() method.

Bug Fixes

  • Modified the ClientPINRequest and ClientPINResponse to properly support CTAP 2.1:

    • Renamed the following variables: PinAuth to PinUvAuthParam, PinProtocol to PinUVAuthProtocol, and PinToken to PinUvAuthToken.

  • Modified the MakeCredentialRequest and MakeCredentialResponse to properly support CTAP 2.1:

    • Added the missing EnterpriseAttestation parameter

    • Added the missing LargeBlobKey parameter

  • Fixed USB HID communication with the Crescendo Key V1 - the keyboard interface and USB HID interface are swapped on Crescendo Key V1 compared to V3. SDK did not reflect that previously.

New Features

  • Entire Codebase migrated to .NET 8.0. Full backward compatibility with previous SDK releases, no changes in the API.

    Note: It is necessary to have .NET 8.0 installed for successful migration from previous SDK releases.

  • Added the USB-HID communication capability to all CTAP 2.0 and 2.1 FIDO commands. This means FIDO can now be used with Crescendo Keys plugged in USB. SDK chooses the communication interface automatically based on the token and communication media type.

  • New Third Party Component introduced - HidSharpCore version 1.3.0 with license Apache-2.0.

  • Updated Third Party Component PCSC-sharp to the latest version.

  • Modification of the live reader/token monitoring - added a CardRemoved event before ReaderRemoved event.

Bug Fixes

  • Refined logging for generating OTP's - waiting for user is no longer considered an error in the logs, plus only the relevant info will get logged based on chosen log level.

  • Corrected the otp-slot-configure command usage example inside the CLI.

  • Fixed getting properties on FIDO applet V3. The expected return message from the applet was wrongly set to 6A80 instead of 6D00.

New Features

  • GetAllAvailableTokens() now returns an empty list if no tokens are available, instead of throwing an exception. CLI also reflects this change and exits gracefully with an error message.

  • Added a new GetAllAvailableReaders() function that lists all connected readers regardless of the connected tokens.

  • Added a new GetAllReaderInfo() function, that returns a list of structured ReaderInfo objects.

  • Removed the unnecessary PrintAllAvailableTokens() method from the SDKCore class.

  • Added FIDOGetChallenge() and FIDOUnblockPIN() to allow the FIDO PIN Unblock functionality for applet V4.1 and higher.

  • Updated Third Party Components (Bouncy Castle and PCSC-Lite) to the latest versions.

  • Added support for FIDO only tokens. All FIDO related functionality is available even if no PIV or ACA applet is present on the token.

  • Added the option for live monitoring of readers and tokens using StartMonitoring and EndMonitoring methods.

  • Fixed log message not appearing for the first operation on FIDO Attestation applet.

  • Documentation improvement and small fixes.

  • Added an Examples folder in the package, that includes complete projects and a solution that can be run directly.

  • Added the CRESCENDO 4000 FIDO contact and contactless ATR to the list of oficially supported tokens.

Bug Fixes

Logs reorganization to print APDU Response before information about time it took to execute the command.

New Features

  • Added authenticatorConfig() and FIDOConfig() (that includes the full authentication flow) methods to enable the CTAP 2.1 authenticatorConfig command.

Bug Fixes

  • FIDOGetAssertion(), FIDOMakeCredential() and FIDOCredentialManagement no longer use hardcoded CTAP 2.1 parameters, so they can be used with CTAP 2.0 as well.

  • Fixed CredentialManagementRequest class - the authentication parameters were wrongly defined as mandatory.

  • Fixed minor mistake in CTAP error logging - the errors should correctly print the CTAP error code and description instead of just the description twice.

New Features

  • Added the CRESCENDO CL FIDO token ATR to the list of supported tokens.

  • Added automatic logout of used applets when disposing of the SDKCore object.

  • Added (and modified the original CTAP1 & CTAP2 FIDO functionality - functions and data structures inside FIDODataStructures class, as well as:

    • SDK methods that implement CTAP1 functions:

      • U2FRegistration()

      • U2FAuthentication()

      • U2FGetVersion()

    • SDK methods that implement CTAP2.x functions: 
      • AuthenticatorClientPIN()
      • AuthenticatorGetAssertion()
      • AuthenticatorGetNextAssertion()
      • AuthenticatorCredentialManagement()
      • AuthenticatorMakeCredential()
      • AuthenticatorReset()
      • AuthenticatorGetInfo()
    • SDK methods that implement CTAP2.x functions with full authentication flow:
      • FIDOSetPIN()
      • FIDOChangePIN()
      • FIDOGetAssertion()
      • FIDOCredentialManagement()
      • FIDOMakeCredential()

  • Added a new method PIVChangePKISlotACR() for modifying the ACR of PKI objects (--piv-pki-acr command in the CLI Tool).

  • Renamed the FIDOTokenReset() function to AuthenticatorReset to align with the FIDO specification.

  • Added GetAllAvailableTokens() that returns a list of all tokens with basic details.

  • Added a requireTouch parameter to:

    • ConfigureStaticPassword
    • ConfigureOATHSlot
    • ConfigureOCRASlot.

    This parameter now allows to configure Crescendo Key V3 to require button touch to generate an OTP (not to be confused with the button-press slots that generate OTP only after pressing the button).

  • Introduced a new return variableResult<T> instead of the FunctionResult structure.

    This allows returning any data type instead of just strings, plus improves error handling (see below).

  • Improved error handling:

    • Added specific error messages for each command/function based on internal documentation.
    • Replaced most of the possible exceptions with structured Error class inside Result<T>.

  • Added a PSKC file creation possibility to the ConfigureOCRASlot() function (--ocra-slot-configure command in the CLI Tool).

  • PSKC file logic is now handled exclusively in the CLI Tool. The SDK now uses only PSKC strings as input/output, instead of handling files directly.

    This allows users to receive a PSCK string from the SDK for further use without the need to handle additional files.

  • Added authentication specifically on the PIV applet before accessing certain PIV data objects (e.g., 5FC109).

  • Modified the logic for storing PKI objects on the token so that when a user uploads both a certificate and a private key to the token, the PKI_CONTAINER_INFO inside the MSCUID keys is correctly updated for EC keys.

  • Added the option to use the PIV discovery object 7E the same way as all the other PIV objects defined by BER-TLV tags.

  • Added option to export the SKI transport key to a PEM file from the CLI Tool.

  • Modified the --piv-pki-put command to support input files (e.g., *.pem or *.pfx) without password protection.

  • Removed the obsolete --ski-key-put command. SKI import can now be done using the existing commands:

    • --piv-pki-put

    • --xauth-key-put

    • --otp-pass-configure

    • --otp-slot-configure

    • --ocra-slot-configure

      Full functionality of these functions/commands is therefore now available for SKI.

  • Enabled static password import using SKI.

  • Modified the SKI JSON file content to match the format used by HID Crescendo Manager.

  • Modified the PIVGetCertificate function (--piv-cert-get command in the CLI Tool) to not require authentication when reading certificates.

  • Added storing public keys into corresponding PIV data objects whenever possible (during SKI, key pair generation, or key import).

  • Reversed the byte order of RSA public keys (modulus) when storing them on the token, to match the format used by HID Crescendo Manager, ActivID ActivClient, and HID Crescendo Minidriver.

  • Removed the possibility of automatic usage of key Reference 9E when storing PKI objects.

    The user must now explicitly specify the Key Reference 9E if they want to use it, because 9E is not PIN-protected as defined in the PIV specification.

  • When using -p interactive in the CLI Tool, the SCard transaction now remains open as long as the PIN window is open. Previously, the transaction timed out after approximately 5 seconds.

Bug Fixes

  • Fixed input parsing in OCRA OCRAAuthenticate() function (--ocra-authenticate command in the CLI Tool):
    • The challenge is now correctly parsed when using hexadecimal or numeric input.
    • The secret is now correctly hashed with specified hashing algorithm.
    • OCRA authenticate now works correctly using Crescendo Key V3 and OTP slots configured with button-press ACR.
    • Fixed the time unit definition - all values are now converted properly to seconds.
  • Fixed Static Password input - it now works with non-hexadecimal strings.
  • Revision of logging messages - they now appear directly before the relevant APDU calls.