Device Management
List Connected Devices
This function will list all connected devices and their respective ATRs.
Command Line Tool
To list all the readers with connected cards, use the token-info command:
.\CrescendoCLI.exe token-info --log-level info
An example response to this command might look like this:
[2024-05-31 15:40:50.516][INFO] Log level is set to "INFO".
[2024-05-31 15:40:50.570][INFO] All connected tokens:
- Reader Name: Circle Idaxis SecurePIV 0
- Token: Crescendo 4000
- Token ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
- Assigned number for the "-t" parameter: 0
- Reader Name: VMware Virtual USB CCID 0
- Token: Crescendo Key V3
- Token ATR: 3B-D9-96-FF-81-91-FE-1F-C3-43-34-30-30-30-2D-4B-45-59-BF
- Assigned number for the "-t" parameter: 1
C#
After the initial set-up, you can call the PrintAllAvailableTokens method like this:
PrintAllAvailableTokens();
Python
After the initial set-up, you can call the PrintAllAvailableTokens method like this:
dllMethodsInstance.PrintAllAvailableTokens()
Change PIN
This function will change the PIN on the token and output the newly set PIN.
Important input parameters
--pin - PIN to be used for authentication. String env can be used to read an Environment Variable PIN as a valid key. String interactive can be used to utilize the Windows interactive window for PIN entering.--new-pin - New PIN value. If no value is entered, then a random 6 digit numeric-only number will be used as a new PIN value.
Command Line Tool
Example of pin-change command usage:
.\CrescendoCLI.exe pin-change -p 123456 -n 654321 --log-level info
This will change the PIN from 123456 to 654321. An example response to this command might look like this:
[2024-04-18 15:36:26.659][INFO] Log level is set to "INFO".
[2024-04-18 15:36:26.707][INFO] Connected to:
[2024-04-18 15:36:26.708][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 15:36:26.708][INFO] - Token: "Crescendo 4000"
[2024-04-18 15:36:26.708][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 15:36:26.760][INFO] Trying to change PIN from "123456" to "654321"
[2024-04-18 15:36:26.836][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 15:36:26.891][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 15:36:26.929][INFO] PIN successfully changed to "654321".
654321
C#
After the initial set-up, you can call the ChangePIN method like this:
FunctionResult result = ChangePin("123456");
Python
After the initial set-up, you can call the ChangePIN method like this:
params = {
'newPin': '654321',
}
dllMethodsInstance.ChangePIN(**params)
Reset Token
This function will reset the token to its default state and remove any data, keys or certificates stored on the key.
Command Line Tool
Example of token-reset command usage:
.\CrescendoCLI.exe token-reset -p 123456 --log-level info
This will reset the token. An example response to this command might look like this:
[2024-04-18 15:59:15.989][INFO] Log level is set to "INFO".
[2024-04-18 15:59:16.105][INFO] Connected to:
[2024-04-18 15:59:16.106][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 15:59:16.106][INFO] - Token: "Crescendo 4000"
[2024-04-18 15:59:16.106][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 15:59:16.191][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 15:59:16.192][INFO] Trying to reset the token:
[2024-04-18 15:59:16.930][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 15:59:16.984][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 15:59:17.133][INFO] Token was successfully reset.
C#
After the initial set-up, you can call the ResetToken method like this:
bool result = ResetToken();
Python
After the initial set-up, you can call the ResetToken method like this:
dllMethodsInstance.ResetToken()
PIV Configuration
Generate Key Pair / Retrieve Public Key
This function allows to generate an Asymmetric Key Pair on the token, or retrieve the Public key, if the Key Pair was already generated in the past. It will always return the public key.
Important input parameters
--crypto-mechanism - The desired cryptographic mechanism. Valid options can be found here.--key-reference - Key Reference where the generated Key Pair will be stored.--retrieve-key - If the Key Pair was generated previously, use this to just retrieve it instead of generating a new Key Pair.
Command Line Tool
Example of piv-key-pair-gen command usage:
.\CrescendoCLI.exe piv-key-pair-gen -p 123456 --crypto-mechanism RSA3072 --key-reference B0 --log-level info
This will generate a RSA3072 key pair on the Key Reference B0 and return back the public key (modulus and exponent). An example response to this command might look like this:
[2024-04-18 14:25:44.326][INFO] Log level is set to "INFO".
[2024-04-18 14:25:44.354][INFO] Connected to:
[2024-04-18 14:25:44.355][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 14:25:44.355][INFO] - Token: "Crescendo 4000"
[2024-04-18 14:25:44.355][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 14:25:44.430][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 14:25:44.448][INFO] Trying to generate asymmetric key pair on Key Reference "B0". This will take several seconds.
[2024-04-18 14:26:00.778][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:00.817][INFO] Successful generation of the asymmetric key pair.
MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAvY0hYYpmi3rdNazuKC+jcdldPIrH0rXic2r63GdtIsaQYPEuXtYLMJgkV2VFQgUgAfvAPlIcOtDPwvj3lyJ6V83h1y3JHvRYMpMVQUC2dKQQTKnzHWsoYySFWLoFx+ihGf9lTRf8J6B4PknijejqKrl+51Rf7eJfjkTxe5JfLwmoX4Nr1PDmHPACVL5n0aZ/Z1d30sJV/stanCgfONqdRoetj7zCEnmd/wCxfuYBLBrpUQbXNmTdv5MbGgbgxKCJ9/lT1OS+OW4UV228qbyA4dOpBtXOSaotC6ZYqcM1PYE8oUfepwxgWSwRHdnHF3yq+pP9G4wbb5VGmnFeiLxlNlBXvIguqnRvh0LB1cKzfNbFbM0IoiUm2Fdz24kOTifChf0FYUtOF5tLriMfaP25Ry7+w4bK7cyuREo8gk2jxIF2TiQKelxbsFtJdMGzZV2Qg65bhe3GOCXCz/uOELncJZlRr1BOjaXzOXy1IJ64BHdA+PmaQ4XOkkJA0se9F3btAgMBAAE=
C#
After the initial set-up, you can call the PIVGenerateKeyPair method like this:
FunctionResult result = PIVGenerateKeyPair(PIVCryptographicMechanismIdentifier.RSA3072, "B0");
Python
After the initial set-up, you can call the PIVGenerateKeyPair method like this:
params = {
'cryptoMechanism': PIVCryptographicMechanismIdentifier.RSA3072,
'keyReference': 'B0',
'getExistingPublicKey': False,
}
dllMethodsInstance.PIVGenerateKeyPair(**params)
The CrescendoDLL.PCSC namespace contains Enums relevant to public methods from the main CrescendoDLL ...
Definition APDUEngine.cs:7
Load Key / Certificate
This function allows to put private key, certificate, or both, to the token.
Important input parameters
--input-file - Path to an input file containing either a private key, certificate, or a combination of both. The supported file formats are *.PEM, *.CRT, *.PFX and *.P12. If there are multiple certificates present in the input file, only the first one will be imported. If the --object-type parameter is set to both, then a first certificate that also has a private key will be imported.--input-pass - Password for opening the input file--key-reference - Key Reference where the private key will be stored.--ber-tlv-tag - BER-TLV Tag of the data object where the certificate will be stored.--object-type - Parameter for specifying what type of PKI object should be imported to the token. Valid options can be found here.--key-name - Key Name, that can be stored on the token and later used to identify the key.
Command Line Tool
Example of piv-pki-put command usage:
.\CrescendoCLI.exe piv-pki-put -p 123456 --key-reference 9C --input-file "C:\Temp\ECCCert.p12" --input-pass password --object-type both --key-name MyNewKey --log-level info
This will load both Private Key and a certificate from file located at C:\Temp\ECCCert.p12 to the token. An example response to this command might look like this:
[2024-04-18 14:26:22.120][INFO] Log level is set to "INFO".
[2024-04-18 14:26:22.238][INFO] Connected to:
[2024-04-18 14:26:22.239][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 14:26:22.239][INFO] - Token: "Crescendo 4000"
[2024-04-18 14:26:22.239][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 14:26:22.387][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 14:26:22.441][INFO] Trying to inject RSA key - "p" component.
[2024-04-18 14:26:22.621][INFO] Trying to inject RSA key - "q" component.
[2024-04-18 14:26:22.645][INFO] Trying to inject RSA key - "q^(-1)" component.
[2024-04-18 14:26:22.670][INFO] Trying to inject RSA key - "dP" component.
[2024-04-18 14:26:22.694][INFO] Trying to inject RSA key - "dQ" component.
[2024-04-18 14:26:22.760][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:22.835][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:23.048][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:23.088][INFO] Successful addition of tags and specified data to buffer "5FC10A".
[2024-04-18 14:26:23.089][INFO] Successful injection of private key with name "MyNewKey" to the key reference "9C".
[2024-04-18 14:26:23.128][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:23.484][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:26:23.524][INFO] Successful addition of tags and specified data to buffer "5FC10A".
C#
After the initial set-up, you can call the PIVPutPKIData method like this:
bool result = PIVPutPKIData("C:\\Temp\\ECCCert.p12", "password", PIVObjectType.both, "9C", "", "MyNewKey");
Python
After the initial set-up, you can call the PIVPutPKIData method like this:
params = {
'inputfilePath': 'C:\Temp\ECCCert.p12',
'password': 'password'
'pkiObjectType': PIVObjectType.both,
'keyReference': '9C',
'berTLVtag': ''
'keyName': 'MyNewKey',
}
dllMethodsInstance.PIVPutPKIData(**params)
Sign Data
This function will take data from input file or input string, create a Hash of the data and send it to the token to get the hash signed back using a specified private key.
Important input parameters
--key-reference - Key Reference defining the private key that will be used for signing.--input-file - Path to file that with the data to be hashed and signed.--input-string - Input string that should be hashed and signed.--input-type - Encoding of the input string. Valid options (case-insensitive) are HEX, BASE64, BASE64URL, UTF8 and BIN. BIN does only make sense when using an input file to read all bytes directly.--output-file - Path to an output file that should contain the signature. When left empty, the signature will simply be logged.--output-type - Encoding of the output string containing the signature. Valid options (case-insensitive) are HEX, BASE64, BASE64URL, UTF8 and BIN (to save the signature bytes directly without any encoding).--hash - Hash algorithm to be used for hashing the input data. Valid options (case-insensitive) are: SHA1, SHA256 and SHA512.
Command Line Tool
Example of piv-data-sign command usage:
.\CrescendoCLI.exe piv-data-sign -p 123456 -i "C:\Temp\LoremIpsum.txt" --input-type utf8 --key-reference 9a --log-level info
This will return a signature of data stored in C:\Temp\LoremIpsum.txt using a private key stored on Key Reference 9A. An example response to this command might look like this:
[2024-05-31 15:55:07.135][INFO] Log level is set to "INFO".
[2024-05-31 15:55:07.260][INFO] Connected to:
[2024-05-31 15:55:07.260][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-05-31 15:55:07.260][INFO] - Token: "Crescendo 4000"
[2024-05-31 15:55:07.260][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-05-31 15:55:07.349][INFO] PIN was successfully verified on ACA applet.
[2024-05-31 15:55:07.486][INFO] PIN was successfully verified on PIV applet.
[2024-05-31 15:55:07.984][INFO] Successful signing of the input data.
ZA2XlPJ6r5JJMVhXBA2cvQFJFDc5Ua7RlW53q2HoGKptEav7jYO/lfud82YHldqw0Ln92u2Br2TYjJDhZLLs68j2EmoyifYpt+rj3wL56IkRhAm1r1pLc9B2w69ntL35YEwXjoeDGQEFzho2VwGVpPVeRVm/pb0/vJYTBRHIHe+ZzkN0WbGZ77gW4qpXHIeyM+HMq4CwFIDmNmuQ4l/X4+cgcadYtbs+AthsnrcgXytIp3vEANPul/PoS2w4VloTRIkMSCv9dZRMSJ5qrqHA/An4+x/YGdBR34a3FILTi4XUyy3ZZ7n1LBO0Dwfx1MC1b73auI2p8L9elY8T60+lgDvFPEHA2B6sQjbuF/jWe3j6Opf0yCK+Poz5rBpLx3P0iIQn40vnWK1w7enBXhyS90KG9OH/xpBpMHcFlborrWju8QdrnoivoT/O0dBW9X6bNIxz9ORUVfAttNzVpcxBBahg74sBO00ufkYeTZ6qDgIuS+T92+Xc3e0b+mH8APrsRq1T2bJbtDgTkvP4k6ZzhsSvHdED3tfYEA2IxW1OHiitkosdWDy6ZwvOPlSYw8TU/pwSvqEFm1mJrxirToEtyWddEzL6OCUM8kxGqbUKgh19BzZYI9FAFhs+oWXupHZKmdcNWiWkAQhrGimts7+88mN8nFWa2eSyW792GE/vAsY=
C#
After the initial set-up, you can call the PIVSignData method like this:
FunctionResult result = PIVSignData("9A", DataType.UTF8, "", "C:\\Temp\\LoremIpsum.txt", DataType.BASE64, HashAlgoValues.SHA256);
Python
After the initial set-up, you can call the PIVSignData method like this:
params = {
'keyReference': '9A',
'inputType': DataType.UTF8,
'inputString': '',
'inputFilePath': 'C:\Temp\LoremIpsum.txt',
'outputType': DataType.BASE64,
'hashAlgo': HashAlgoValues.SHA256,
}
dllMethodsInstance.PIVSignData(**params)
OTP Configuration
Configure OTP
This function will configure selected OTP slot, so that it can be used for OTP generation. Various input parameters can be specified. The function will also generate (or update already existing) PKCS file.
Important input parameters
--oath-slot - OATH slot number (case-insensitive). Valid options for V3 applet are: 1-3, valid options for V4 applet are: C0-CF for user slots, 00-0F for managed slots. The parameter --button-press will overrule this one in case both are entered.--button-press - Parameter for identifying OATH button-press slots. With Crescendo Key V1 & V2 (applet V3) you can configure the single button-press slot also by using --oath-slot 1. Valid options are 1 for single press (on both applet V3 and V4) and 2 for double press (applet V4 only).--oath-key - OATH key (secret) to be stored to the token.--mode - OATH mode to be used. Valid options can be found here--pskc-path - Path to a PSKC file. If the PSKC file already exists in the specified path, it will get updated. Otherwise new file will be generated. Without defining explicit path, the file will be stored in .\PSKC under the token CUID and *.pskc extension.--transport-key - Transport key used for creation of the PSKC file content.--friendly-name - Friendly name for description. Must be max 64 bytes (characters) long for applet V3, 32 bytes (characters) for applet V4.
Command Line Tool
Example of otp-slot-configure command usage:
.\CrescendoCLI.exe otp-slot-configure -p 123456 --oath-slot C5 --button-press 1 --oath-key 0910f75fb6 --mode TOTP --friendly-name "OATH TOTP" --pskc-path "c:\Temp\PSKCFile.pskc" --transport-key 12345678123456781234567812345678 --log-level info
This will configure the oath slot C5 to use TOTP on a single button-press and store the secret 0910f75fb6 to the token, so that OTP can be used. An example response to this command might look like this:
[2024-04-18 14:39:44.373][INFO] Log level is set to "INFO".
[2024-04-18 14:39:44.421][INFO] Connected to:
[2024-04-18 14:39:44.422][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 14:39:44.422][INFO] - Token: "Crescendo 4000"
[2024-04-18 14:39:44.422][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 14:39:44.506][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 14:39:44.724][INFO] The OATH configuration was successfully put to slot "C5".
[2024-04-18 14:39:44.764][INFO] The OATH key was successfully put to slot "C5".
[2024-04-18 14:39:44.819][INFO] PIN was successfully verified on PIV applet.
[2024-04-18 14:39:44.978][INFO] Successfully updated the PSKC file located at "c:\Temp\PSKCFile.pskc".
C#
After the initial set-up, you can call the ConfigureOATHSlot method like this:
bool result = ConfigureOATHSlot("C5", 1, "0910f75fb6", 30, OATHModeName.TOTP, "0000000000000000", HashAlgoValues.SHA1, 6, "OATH TOTP", 16, "12345678123456781234567812345678", "c:\\Temp\\PSKCFile.pskc");
Python
After the initial set-up, you can call the ConfigureOATHSlot method like this:
params = {
'oathSlot': 'C5',
'buttonPress': 1,
'oathKey': '0910f75fb6',
'timeStep': 30,
'oathMode': OATHModeName.TOTP,
'oathCounter': '0000000000000000',
'oathHash': HashAlgoValues.SHA1,
'codeDigits': 6,
'friendlyName': 'OATH TOTP',
'truncationOffset': 16,
'pskcPath': 'c:\Temp\PSKCFile.pskc',
'transportKey': '12345678123456781234567812345678',
}
dllMethodsInstance.ConfigureOATHSlot(**params)
Generate OTP
This function will return an OTP generated from the specified OTP slot.
Important input parameters
--oath-slot - OATH slot number (case-insensitive). Valid options for V3 applet are: 1-3, valid options for V4 applet are: C0-CF for user slots, 00-0F for managed slots. The parameter --button-press will overrule this one in case both are entered.--button-press - Parameter for identifying OATH button-press slots. With Crescendo Key V1 & V2 (applet V3) you can configure the single button-press slot also by using --oath-slot 1. Valid options are 1 for single press (on both applet V3 and V4) and 2 for double press (applet V4 only).
Command Line Tool
Example of otp-generate command usage:
.\CrescendoCLI.exe otp-generate --oath-slot C5 -p 123456 --log-level info
This will configure the oath slot C5 to use TOTP and store the secret 0910f75fb6 to the token, so that OTP can be used. An example response to this command might look like this:
[2024-04-18 15:19:47.584][INFO] Log level is set to "INFO".
[2024-04-18 15:19:47.779][INFO] Connected to:
[2024-04-18 15:19:47.780][INFO] - Reader: "Circle Idaxis SecurePIV 0"
[2024-04-18 15:19:47.780][INFO] - Token: "Crescendo 4000"
[2024-04-18 15:19:47.780][INFO] - ATR: 3B-D5-96-FF-81-91-FE-1F-C3-43-34-30-30-30-C9
[2024-04-18 15:19:47.920][INFO] PIN was successfully verified on ACA applet.
[2024-04-18 15:19:47.925][INFO] Trying to generate OTP with key from OATH slot C5.
328482
C#
After the initial set-up, you can call the GenerateOTP method like this:
FunctionResult result = GenerateOTP("C5", 0);
Python
After the initial set-up, you can call the GenerateOTP method like this:
params = {
'oathSlot': 'C5',
'buttonPress': 0,
}
dllMethodsInstance.GenerateOTP(**params)
1.9.8