adulau/ootp
1
0
Fork 0
mirror of https://github.com/adulau/ootp.git synced 2024-11-22 10:07:12 +00:00
Code Issues Projects Releases Packages Wiki Activity
ootp/doc/otp-sca.1

414 lines
16 KiB
Groff
Raw Normal View History

ootp-release-1.02 imported
2017-01-03 11:10:10 +00:00
...\" $Header: /usr/src/docbook-to-man/cmd/RCS/docbook-to-man.sh,v 1.3 1996/06/17 03:36:49 fld Exp $
...\"
...\" transcript compatibility for postscript use.
...\"
...\" synopsis: .P! <file.ps>
...\"
.de P!
\\&.
.fl \" force out current output buffer
\\!%PB
\\!/showpage{}def
...\" the following is from Ken Flowers -- it prevents dictionary overflows
\\!/tempdict 200 dict def tempdict begin
.fl \" prolog
.sy cat \\$1\" bring in postscript file
...\" the following line matches the tempdict above
\\!end % tempdict %
\\!PE
\\!.
.sp \\$2u \" move below the image
..
.de pF
.ie \\*(f1 .ds f1 \\n(.f
.el .ie \\*(f2 .ds f2 \\n(.f
.el .ie \\*(f3 .ds f3 \\n(.f
.el .ie \\*(f4 .ds f4 \\n(.f
.el .tm ? font overflow
.ft \\$1
..
.de fP
.ie !\\*(f4 \{\
. ft \\*(f4
. ds f4\"
' br \}
.el .ie !\\*(f3 \{\
. ft \\*(f3
. ds f3\"
' br \}
.el .ie !\\*(f2 \{\
. ft \\*(f2
. ds f2\"
' br \}
.el .ie !\\*(f1 \{\
. ft \\*(f1
. ds f1\"
' br \}
.el .tm ? font underflow
..
.ds f1\"
.ds f2\"
.ds f3\"
.ds f4\"
.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
.TH "\fBotp-sca\fP" "1"
.SH "NAME"
\fBotp-sca\fP \(em Smart Card Administration for One Time Password package\&.
.SH "SYNOPSIS"
.PP
\fBotp-sca\fP [-?hlp] [-a\fI admin_keyfile\fP] [-c\fI count\fP] [-d\fI debug_level\fP] [-i\fI index\fP] [-m\fI command_mode\fP] [-M\fI modifiers\fP] [-r\fI reader\fP] [-R\fI reader_keyfile\fP] [-u\fI username\fP] [-v\fI card_api_version\fP]
.SH "DESCRIPTION"
.PP
The \fBotp-sca\fP 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
\fBotp-sca\fP\&. Additionally commands implemented on the
smart card such as HOTP generation and PIN maintenance can be executed
with the appropriate administratative key\&.
.SH "OPTIONS"
.IP "-a\fI admin_keyfile\fP" 10
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\&.
.IP "-c\fI count\fP" 10
Configure the count parameter optionally used by the hotp-gen command\&.
.IP "-d\fI debug_level\fP" 10
Set debug level\&.
.IP "-h" 10
Help\&.
.IP "-i\fI index\fP" 10
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\&.
.IP "-l" 10
List SC Readers
.IP "-m\fI command_mode\fP" 10
.PP
.nf
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\&.
.fi
.IP "-M\fI modifiers\fP" 10
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
.IP "-r\fI reader\fP" 10
Set the smart card reader\&. Use -l to list available readers\&.
.IP "-R\fI reader_keyfile\fP" 10
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\&.
.IP "" 10
A key consists of 5 bytes in hexadecimal format\&. The default
key is "00000" or 3030303030\&.
.IP "" 10
This key must match the key set in the reader\&. With the Spyrus
PAR II reader this is set in the PAR II EEProm\&.
.IP "-u\fI username\fP" 10
Set username\&. The username is used with the host-get command and
d modifier\&.
.IP "-v\fI card_api_version\fP" 10
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\&.
.SH "SMART CARD COMMANDS"
.PP
\fBadmin-enable\fP : 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
\fBopenssl rand 160 | openssl sha1\fP\&. The hotp-gen
command will automatically disable admin mode\&.
.PP
\fBadmin-disable\fP : disable administratative mode\&. Using the command hotp-gen will also
disable admin mode\&.
.PP
\fBadminkey-set\fP : set the 160 bit administrative key\&. The default key is
"00000000000000000000" ASCII or "3030303030303030303030303030303030303030" HEX\&.
.PP
\fBbalancecard-set\fP : 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\&.
.PP
\fBcapabilities-get\fP : 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 \fBHOTP\&.DEF\fP:
.PP
.nf
\&' 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
.fi
.PP
\fBhost-get\fP : 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\&.
.PP
.nf
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
.fi
.PP
\fBhost-set\fP : set a host record\&. Multiple host records may be set, one record per
line\&.
.PP
\fBhostname-get\fP : return the hostname for an index, or all hostnames if no index is
specified\&. Hostnames tagged "**" require the reader PIN\&.
.PP
\fBhotp-gen\fP : 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\&.
.PP
\fBpin-set\fP : set a user PIN\&. If the SC is in admin mode the current PIN is not
validated\&.
.PP
\fBpin-test\fP : 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\&.
.PP
\fBreader-key-set\fP : 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\&.
.PP
\fBsc-clear\fP : reset the SC to defaults, erase all host entries\&.
.PP
\fBspyrus-ee-get\fP : 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\&.
.PP
.nf
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 :
.fi
.PP
.nf
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
.fi
.PP
Note this command works with the Spyrus Personalization SC firmware only\&.
.PP
\fBspyrus-ee-set\fP : set spyrus EEProm blocks\&.
.PP
Note this command works with the Spyrus Personalization SC firmware only\&.
.PP
\fBversion\fP : display firmware version of SC\&.
.SH "EXAMPLES"
.PP
Change the administratative key from the default\&. Disable admin mode
when done\&.
.PP
.nf
\fBecho "3030303030303030303030303030303030303030" > default\&.key\fP
\fBotp-sca -a default\&.key -m admin-enable\fP
\f(CWAdminMode: enabled\&.\fP
\fBopenssl rand 160 | openssl sha1 > secret\&.key \fP
\fBotp-sca -a secret\&.key -m adminkey-set\fP
\f(CWSet AdminKey: Done\fP
\fBotp-sca -a secret\&.key -m admin-disable\fP
\f(CWAdminMode: disabled\&.\fP
.fi
.PP
Use \fBotp-control\fP to create a new database for system dev1 with
user test, store the test user database entry to the smart card with
\fBotp-sca\fP\&.
.PP
.nf
# Create a new new OTP database /tmp/otpdb
\fBotp-control -no /tmp/otpdb -m create\fP
\f(CWCreated db /tmp/otpdb\&.\fP
# add user test
\fBotp-control -o /tmp/otpdb -u test -m add\fP
\f(CWAdding user test\&.\fP
# list user test entry in format ready for otp-sca to import\&. Hostname
# of system is dev1
\fBotp-control -o /tmp/otpdb -u test -m list-sc -H dev1 | tail -1 > /tmp/test\&.list\fP
# copy card entry to smart card as index 0
\fBecho -n "00:"| cat - /tmp/test\&.list | \&./otp-sca -m host-set\fP
\f(CWSetHost (0): Done\fP
.fi
.PP
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\&.
.PP
.nf
\fBotp-sca -m host-get\fP\f(CW#index:count:hostname:key
00:00000002:646576312E656E6700000000:E4AACE5EC7291C405ED28949BB6DACA05768319D
01:00000000:646576322E656E6700000000:4120522AAC6B9C32274E2B3D966000D790EFEBFA
02:00000021:646576332E656E6700000000:9CDF3C14792A512FBE0D530E4DCFC726841B21BD
03:00000000:76706E312E656E6700000000:B8A64BE3DDAE4B873683ACE9B9DBF95D72782CBE\fP
.fi
.PP
Reset user PIN for card with secret\&.key as the admin key\&.
.PP
.nf
\fBotp-sca -m admin-enable -a secret\&.key\fP
\f(CWAdminMode: enabled\&.\fP
\fBotp-sca -p -m pin-set\fP
\f(CWNew PIN: 23456
New PIN (again): 23456
SetPIN Good\&.\fP
\fBotp-sca -m admin-disable -a secret\&.key\fP
\f(CWAdminMode: disabled\&.\fP
.fi
.PP
Generate HOTP for dev1\&. Use hostname-get to find the index for dev1\&. Use
the GetHOTPHostCount32 command with count 1 (modifiers c and h)\&.
.PP
.nf
\fBotp-sca -m hostname-get\fP
\f(CWEnter PIN: 23456
00,dev1
01,dev2\&.eng
02,dev3\&.eng
03,vpn1\&.eng
04,base4\&.eng
05,base6\&.eng
06,base7\&.eng\fP
\fBotp-sca -d99 -m hotp-gen -Mch -i 0 -c1\fP
\f(CWEnter PIN: 23456
HOTP: 52DCD05FE5 -- dev1\fP
.fi
.SH "AUTHOR"
.PP
Mark Fullmer maf@splintered\&.net
.SH "SEE ALSO"
.PP
\fBotp-control\fP(1)
\fBotp-sct\fP(1)
\fBpam_otp\fP(1)
\fBhtsoft-downloader\fP(1)
\fBotp-ov-plugin\fP(1)
\fBbcload\fP(1)
\fBurd\fP(1)
spyrus-par2(7)
...\" created by instant / docbook-to-man, Tue 01 Dec 2009, 17:12
Reference in a new issue Copy permalink