mirror of
https://github.com/adulau/ootp.git
synced 2024-12-04 07:57:17 +00:00
431 lines
17 KiB
Groff
431 lines
17 KiB
Groff
...\" $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, --sc-admin-key=\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, --sc-count=\fI count\fP" 10
|
||
Configure the count parameter optionally used by the hotp-gen command\&.
|
||
A count value of 0 indicates the HOTP value is to be calculated with the
|
||
current stored count\&.
|
||
.IP "-d, --debug=\fI debug_level\fP" 10
|
||
Set debug level\&.
|
||
.IP "-h, --help" 10
|
||
Help\&.
|
||
.IP "-i, --sc-index=\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, --list-readers" 10
|
||
List SC Readers
|
||
.IP "-m, --sc-command=\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, --sc-command-modifier=\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\&.
|
||
.IP "-p, --no-pin" 10
|
||
Do not prompt for PIN\&. The Smart Card does not require a PIN when admin
|
||
mode is enabled\&.
|
||
.IP "-r, --reader=\fI reader\fP" 10
|
||
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\&.
|
||
.IP "-R, --sc-reader-key=\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, --sc-username=\fI username\fP" 10
|
||
Set username\&. The username is used with the host-get command and
|
||
d modifier\&.
|
||
.IP "-v, --sc-version=\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\&.
|
||
.IP "--version" 10
|
||
Display software version\&.
|
||
.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 accepting a PIN will not require the PIN to be valid
|
||
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: enable base10 display
|
||
|
||
F3\&.\&.F7: reserved
|
||
|
||
F8-11: FMT3-FMT0\&. 0000=HEX40 0001=HEX40 0010=DEC31\&.6 0011=DEC31\&.7
|
||
0100=DEC31\&.8 0101=DEC31\&.9 0110=DEC31\&.10 0011=DHEX40
|
||
|
||
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, Thu 12 Dec 2013, 10:40
|