otp-sca [-?hlp] [-a admin_keyfile] [-c count] [-d debug_level] [-i index] [-m command_mode] [-M modifiers] [-r reader] [-R reader_keyfile] [-u username] [-v card_api_version]
The otp-sca command implements a terminal for an MCU based Smart Card loaded with the OTP firmware (HOTPC.IMG). Host entries consisting of {hostname,count,shared_key} are downloaded to the Smart Card using otp-sca. Additionally commands implemented on the Smart Card such as HOTP generation and PIN maintenance can be executed with the appropriate administratative key.
Smart Card administratative key. The admin-enable command and administratative key are used to toggle the Smart Card into admin mode. Once in admin mode commands admin-disable, adminkey-set, balancecard-set, host-get, host-set, pin-set, and sc-clear can be executed. The default admin key, "3030303030303030303030303030303030303030" (HEX), should be changed to restrict access to the above commands.
Configure the count parameter optionally used by the hotp-gen command.
Set debug level.
Help.
Set the 8 bit index. The Smart Card contains numerically indexed records for each host of the form {hostname,count,shared_key}. The firmware will support indexes in the range 0..254. 255 is reserved. Memory capacity on the Smart Card may further restrict the index range. The ZC3.9 BasicCard with firmware revision 3 supports up to 85 records.
List SC Readers
Command Mode Description Notes Modifiers
---------------------------------------------------------------
admin-enable - Enable Admin Mode 1
admin-disable - Disable Admin Mode
adminkey-set - Set Admin Key 1
balancecard-set - Set Balance Card Index 1
capabilities-get - Get Capabilities
host-get - Get host entry 1,2,4 d
host-set - Set host entry 1,4
hostname-get - Get Hostname for Index 2,3
hotp-gen - Generate HOTP for Index 3 chr
pin-set - Set PIN 3
pin-test - Test/Verify PIN 3
reader-key-set - Set Reader Key 1
sc-clear - Clear all SC data 1
spyrus-ee-get - Spyrus EEProm read 5
spyrus-ee-set - Spyrus EEProm write 5
version - Firmware version
Notes (*):
1 Admin Enable required.
2 Iterate over all if no index specified.
3 PIN or Admin Enable required.
4 version 3 firmware supports 32 bit count, version 2 16 bit count.
5 Spyrus customization SC firmware
Modifiers: (version 3+ SC firmware)
c pass count to SC.
h return hostname from SC.
d output in otpdb load friendly format.
r include reader key in request.
Configure command_mode modifiers. Modifier d applied to the host-get command will generate output in otpdb format. Count (c) and Host (h) used with hotp-gen allow passing the Count and Host parameters respectively. The Smart Card may not be configured to support all variations of a command. variations
Set Smart Card reader. Use -l to list available readers. A reader is defined as class:reader:[option]. PCSC and embedded are the two available classes. The embedded class contains the acr30s driver which is specified as embedded:acr30s:[serial_port]. If pcscd is running the first PC/SC reader will be the default followed by the embedded acr30s driver. Use PCSC: for the first available PC/SC reader. Use embedded:acr30s:/dev/cuaU0 for the embedded acr30s driver with serial port /dev/cuaU0.
Smart Card Reader key. The reader-key-set command can be used to set this key in the Smart Card. To emulate the behavior of a reader using the key the r modifier may be used with this option and the hotp-gen command to pass the key to the Smart Card.
A key consists of 5 bytes in hexadecimal format. The default key is "00000" or 3030303030.
This key must match the key set in the reader. With the Spyrus PAR II reader this is set in the PAR II EEProm.
Set username. The username is used with the host-get command and d modifier.
Set the Smart Card API version. The binary API between the terminal and Smart Card changed between version 2 and 3. See command_mode notes above. The default version is 3. Configuring version 2 will allow maintenance of Smart Card with version 2 firmware.
admin-enable : enable administrative mode. The commands admin-disable, admin-key-set, balancecard-set, host-get, and sc-clear require admin mode to be enabled. pin-set and commands requiring a PIN will not require a valid PIN while the SC is in admin mode. A new key can be generated with openssl rand 160 | openssl sha1. The hotp-gen command will automatically disable admin mode.
admin-disable : disable administratative mode. Using the command hotp-gen will also disable admin mode.
adminkey-set : set the 160 bit administrative key. The default key is "00000000000000000000" ASCII or "3030303030303030303030303030303030303030" HEX.
balancecard-set : set host index for balance card reader, 0-254. 255 will disable this command. Using a balance reader to generate a HOTP does not require the use of a PIN, and is disabled by default.
capabilities-get : each command on the Smart Card is represented by a capabilities bit and conditionally compiled into HOTPC.IMG. capabilities-get will return the available, compiled-in commands. Commands are defined in HOTP.DEF:
' ZC commands CLA=80 ' b = Byte Idx,Mode,Version ' i = Integer Count ' l = Long Count32,Capabilities ' sn = String length n Hostname(12),ZCKey(20),*PIN(5),HOTP(5), ' AdminKey(20), eeBlock(16), readerKey(5) ' INS Name Format CapabilityID '------------------------------------------------------------------------ ' 00 PRDisplay (CLA=C8) - 00000001 ' RecordNumber(byte), DataFormat(byte), DigitCount(byte) ' DecimalPoint(byte), Delay(byte), MoreData(byte), ' Data(String) ' 40 SetHost Idx,Count,Hostname,HOTPKey 00000002 ' 42 GetHost Idx,Count,Hostname,HOTPKey 00000004 ' 44 GetHostName Idx,myPIN,Hostname 00000008 ' 46 GetHOTP Idx,myPIN,HOTP 00000010 ' 48 SetAdminMode Mode,AdminKey 00000020 ' 4A SetBalanceCardIndex Idx 00000040 ' 4C SetPIN myPIN,newPIN 00000080 ' 4E TestPIN myPIN 00000100 ' 50 GetVersion Version 00000200 ' 52 SetAdminKey AdminKey 00000400 ' 54 SetHost32 Idx,Count32,Hostname,HOTPKey 00000800 ' 56 GetHost32 Idx,Count32,Hostname,HOTPKey 00001000 ' 58 GetHOTPCount32 Idx,myPIN,Count32,HOTP 00002000 ' 5A GetHOTPHost Idx,myPIN,HOTP,Hostname 00004000 ' 5C GetHOTPHostCount32 Idx,myPIN,Count,HOTP,Hostname 00008000 ' 5E ClearAll 00010000 ' 60 SetReaderKey readerKey 00020000 ' 90 GetCapabilities Capabilities XXXXXXXX ' A0 GetEEBlock P1=Idx,eeBlock XXXXXXXX ' A1 SetEEBlock P1=Idx,eeBlock XXXXXXXX
host-get : retrieve a host record, or all host records if the index is not set. Fields {index,count,hostname,key} are : separated and represented in HEX. An index up to 254 may be specified if the SC EEPROM is sufficient. Count (32 bits) and key (160 bits) are used for generating a HOTP. The hostname field (12 bytes) can be displayed on readers such as the Spyrus PAR II. The high bit of each hostname character serve as 12 flag bits, F0..F11.
F0: challenge (count) input is required by the user.
F1: enable reader authentication by the SC for the GetHOTP* commands.
F2..F11: reserved
Example host record with index=0, count=7, hostname=dev1.eng,
key=E4AACE5EC7291C405ED28949BB6DACA05768319D
#index:count:hostname:key
00:00000007:646576312E656E6700000000:E4AACE5EC7291C405ED28949BB6DACA05768319D
host-set : set a host record. Multiple host records may be set, one record per line.
hostname-get : return the hostname for an index, or all hostnames if no index is specified. Hostnames tagged "**" require the reader PIN.
hotp-gen : generate an HOTP for an index. Index is 0 if not specified. There are four versions of this command, GetHOTP, GetHOTPHost, GetHOTPCount32, GetHOTPHostCount32 which can be selected with the Modifiers option. The default SC build includes the GetHOTPHostCount32 (-Mch), and GetHOTPCount32 (-Mc) commands. Executing this command will disable administratative mode if set.
pin-set : set a user PIN. If the SC is in admin mode the current PIN is not validated.
pin-test : test a user PIN. Specifing a PIN incorrectly more than ten times in succession will lock the SC. Use the pin-test command in admin mode to unlock a SC.
reader-key-set : set the 40 bit SC reader key. A reader will present this key to the SC when executing the GetHOTP* commands. If the F1 (flag 1) bit of the hostname is set, this key must match the key provided by the reader. This functionality allows the reader to weakly authenticate itself to the Smart Card and may be used to restrict HOTP generation to a Spyrus PAR II reader.
sc-clear : reset the SC to defaults, erase all host entries.
spyrus-ee-get : get spyrus EEProm blocks. The HOTP firmware for the Spyrus Reader will load run-time strings from the on-board EEProm programmable from a SC loaded with the Spyrus Personalization firmware. The spyrus-ee-get command will read these strings from a SC. The 256K Byte EEProm is read organized into 16 byte blocks. The high bit of the index serves as a last block flag indicator for the Spyrus reader, allowing for example only block 0 to be overwritten.
Spyrus EEProm Memory map and flash defaults: Note the field length is defined by the number of characters between :'s. The field length for EE_MAGIC is 3, EE_READER_KEY 5, and EE_CALC_MSG 12. Symbol Contents/Length --------------------------------------- EE_MAGIC :maf: EE_READER_KEY :00000: EE_CALC_MSG :OARnet:2009 : EE_L1GREET : OARnet : EE_L2GREET :PIN: : EE_L1MAIN : OARnet : EE_L2MAIN : Verified : EE_CHALLENGE :Challenge: : EE_L1LOCKED :10 Failures : EE_L2LOCKED :Card Locked : EE_L1ACCESS_DENY : Access : EE_L2ACCESS_DENY : Denied : EE_NOHOSTS : No Hosts : EE_L1NEWPIN :Set New PIN : EE_L2NEWPIN :NewPIN: : EE_L3NEWPIN :Again: : EE_PINCHANGED :PIN Changed : EE_NOCARD :No Card : EE_TRYHARDER :Try Harder :
00:6D616630303030304F41526E65743A32 01:303039202020204F41526E6574202020 02:50494E3A20202020202020202020204F 03:41526E65742020202020566572696669 04:656420204368616C6C656E67653A2020 05:3130204661696C757265732043617264 06:204C6F636B6564202020204163636573 07:7320202020202044656E696564202020 08:20204E6F20486F737473202053657420 09:4E65772050494E204E657750494E3A20 0A:20202020416761696E3A202020202020 0B:50494E204368616E676564204E6F2043 0C:61726420202020205472792048617264 8D:65722020000000000000000000000000
Note this command works with the Spyrus Personalization SC firmware only.
spyrus-ee-set : set spyrus EEProm blocks.
Note this command works with the Spyrus Personalization SC firmware only.
version : display firmware version of SC.
Change the administratative key from the default. Disable admin mode when done.
echo "3030303030303030303030303030303030303030" > default.key otp-sca -a default.key -m admin-enable AdminMode: enabled. openssl rand 160 | openssl sha1 > secret.key otp-sca -a secret.key -m adminkey-set Set AdminKey: Done otp-sca -a secret.key -m admin-disable AdminMode: disabled.
Use otp-control to create a new database for system dev1 with user test, store the test user database entry to the Smart Card with otp-sca.
# Create a new new OTP database /tmp/otpdb otp-control -no /tmp/otpdb -m create Created db /tmp/otpdb. # add user test otp-control -o /tmp/otpdb -u test -m add Adding user test. # list user test entry in format ready for otp-sca to import. Hostname # of system is dev1 otp-control -o /tmp/otpdb -u test -m list-sc -H dev1 | tail -1 > /tmp/test.list # copy card entry to Smart Card as index 0 echo -n "00:"| cat - /tmp/test.list | ./otp-sca -m host-set SetHost (0): Done
Dump card contents to stdout. Note fields are encoded in HEX including the hostname. A high bit set on the first character in the hostname signals the terminal to prompt for a count.
otp-sca -m host-get #index:count:hostname:key 00:00000002:646576312E656E6700000000:E4AACE5EC7291C405ED28949BB6DACA05768319D 01:00000000:646576322E656E6700000000:4120522AAC6B9C32274E2B3D966000D790EFEBFA 02:00000021:646576332E656E6700000000:9CDF3C14792A512FBE0D530E4DCFC726841B21BD 03:00000000:76706E312E656E6700000000:B8A64BE3DDAE4B873683ACE9B9DBF95D72782CBE
Reset user PIN for card with secret.key as the admin key.
otp-sca -m admin-enable -a secret.key AdminMode: enabled. otp-sca -p -m pin-set New PIN: 23456 New PIN (again): 23456 SetPIN Good. otp-sca -m admin-disable -a secret.key AdminMode: disabled.
Generate HOTP for dev1. Use hostname-get to find the index for dev1. Use the GetHOTPHostCount32 command with count 1 (modifiers c and h).
otp-sca -m hostname-get Enter PIN: 23456 00,dev1 01,dev2.eng 02,dev3.eng 03,vpn1.eng 04,base4.eng 05,base6.eng 06,base7.eng otp-sca -d99 -m hotp-gen -Mch -i 0 -c1 Enter PIN: 23456 HOTP: 52DCD05FE5 -- dev1