Permalink
Browse files

Add man-pages.

  • Loading branch information...
1 parent 6ce15a5 commit 69051b545f9a84c942aa8634a9fd553d757a0d5b @fredrikt fredrikt committed Dec 21, 2011
@@ -0,0 +1,71 @@
+.\" Copyright (c) 2011 Yubico AB
+.\" See the file COPYING for license statement.
+.\"
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH yhsm-keystore-unlock "1" "December 2011" "python-pyhsm"
+
+.SH NAME
+yhsm-keystore-unlock \(hy Unlock the keystore in a YubiHSM
+
+.SH SYNOPSIS
+.B yhsm-keystore-unlock
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+In versions of the YubiHSM before 1.0, the YubiHSM could be protected
+using a 'HSM password'. The YubiHSM would unlock it's cryptographic functions
+if the correct password was given, but it was a simple comparision test.
+
+In YubiHSM 1.0, the password was changed into an actual key that was used to
+decrypt the contents of the YubiHSM internal key store, which was then AES-256
+encrypted using the new 'Master key' when stored in the device.
+
+In YubiHSM 1.0, the option to also require an YubiKey OTP to unlock the
+keystore was also added. One or more 'Admin YubiKeys' can be configured
+in the YubiHSM, and an OTP from one of these must also be provided before the
+YubiHSM will enable it's cryptographic functions.
+
+The OTP is simply validated against the non-encrypted internal database
+(not key store) in the YubiHSM though, but together with a 'Master key' not
+stored on the server with the YubiHSM, it provides enhanced security by being
+a second factor that an attacker can't just intercept even if the server is
+compromised.
+
+.SH OPTIONS
+.PP
+.TP
+\fB\-D\fR, \fB\-\-device\fR
+device file name (default: /dev/ttyACM0).
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+enable verbose operation.
+.TP
+\fB\-\-debug\fR
+enable debug printout, including all data sent to/from YubiHSM.
+.TP
+\fB\-\-no-otp\fR
+skip the prompt for an OTP. For use by scripts where no OTP
+is required and the Master Key is stored on the server with the YubiHSM.
+
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+.IP "\fB0\fR" 4
+.IX Item "0"
+YubiHSM keystore successfully unlocked.
+.IP "\fB1\fR" 4
+.IX Item "1"
+Failed to unlock keystore.
+
+.SH BUGS
+Report python-pyhsm/yhsm-keystore-unlock bugs in
+.URL "https://github.com/Yubico/python-pyhsm/issues/" "the issue tracker"
+
+.SH "SEE ALSO"
+The
+.URL "https://github.com/Yubico/python-pyhsm/" "python-yubico home page"
+.PP
+YubiHSMs can be obtained from
+.URL "http://www.yubico.com/" "Yubico" "."
@@ -0,0 +1,69 @@
+.\" Copyright (c) 2011 Yubico AB
+.\" See the file COPYING for license statement.
+.\"
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH yhsm-linux-add-entropy "1" "December 2011" "python-pyhsm"
+
+.SH NAME
+yhsm-linux-add-entropy \(hy Seed the Linux entropy pool with data from YubiHSM TRNG
+
+.SH SYNOPSIS
+.B yhsm-linux-add-entropy
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+The YubiHSM uses "Avalanche Noise" TRNG together with USB SOF jitter sampling
+to feed a DRBG_CTR algorithm (NIST publication SP800-90). The result has been
+verified as being random data of good quality by at least one third party
+cryptographer.
+.URL "http://sartryck.idg.se/Art/Yubihsm_1_TW072011.html"
+
+Use this program to add random data from the YubiHSM to the entropy pool of
+your Linux operating system. This is useful whenever lots of random data is needed,
+such as when generating chryptographic keys (GPG-keys), on a server terminating SSL
+sessions etc.
+
+You may run this script from cron, or in a while-loop. Make sure it does not run
+at the same time as something else accessing the YubiHSM though, or the two tasks
+may interrupt each other \(hy probably making both fail.
+
+.SH OPTIONS
+.PP
+.TP
+\fB\-D\fR, \fB\-\-device\fR
+device file name (default: /dev/ttyACM0).
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+enable verbose operation.
+.TP
+\fB\-c\fR, \fB\-\-count\fR
+number of iterations to run (default: 100).
+.TP
+\fB\-r\fR, \fB\-\-ratio\fR
+bits per byte read to use. 8 is probably fine, but as a conservative default 2 is used.
+.TP
+\fB\-\-debug\fR
+enable debug printout, including all data sent to/from YubiHSM.
+
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+.IP "\fB0\fR" 4
+.IX Item "0"
+Entropy added successfully
+.IP "\fB1\fR" 4
+.IX Item "1"
+Failure
+
+.SH BUGS
+Report python-pyhsm/yhsm-linux-add-entropy bugs in
+.URL "https://github.com/Yubico/python-pyhsm/issues/" "the issue tracker"
+
+.SH "SEE ALSO"
+The
+.URL "https://github.com/Yubico/python-pyhsm/" "python-yubico home page"
+.PP
+YubiHSMs can be obtained from
+.URL "http://www.yubico.com/" "Yubico" "."
@@ -0,0 +1,78 @@
+.\" Copyright (c) 2011 Yubico AB
+.\" See the file COPYING for license statement.
+.\"
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH yhsm-init-oath-token "1" "December 2011" "python-pyhsm"
+
+.SH NAME
+yhsm-init-oath-token \(hy Tool to add an OATH token to the \fIyhsm-validation-server\fR\|(1) database.
+
+.SH SYNOPSIS
+.B yhsm-init-oath-token \fI--key-handle kh\fR \fI--uid name\fR
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+Use this tool to add OATH token entrys to the \fIyhsm-validation-server\fR\|(1) database.
+
+.SH OPTIONS
+.PP
+.TP
+\fB\-D\fR, \fB\-\-device\fR
+device file name (default: /dev/ttyACM0)
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+enable verbose operation
+.TP
+\fB\-\-debug\fR
+enable debug printout, including all data sent to/from YubiHSM
+.TP
+\fB\-\-force\fR
+overwrite any present entry
+.TP
+\fB\-\-key-handle\fR kh
+key handle to create AEAD. Examples : "1", "0xabcd".
+.TP
+\fB\-\-uid\fR name
+user id (lookup key in token database)
+.TP
+\fB\-\-oath-c\fR num
+initial OATH counter value (integer)
+.TP
+\fB\-\-test-oath-window\fR num
+number of codes to search with \-\-test-code
+.TP
+\fB\-\-test-code\fR digits
+optional OTP from token for verification
+.TP
+\fB\-\-oath-k\fR str
+secret HMAC-SHA-1 key of the token, hex encoded
+.TP
+\fB\-\-db-file\fR fn
+db file for storing AEADs for later use by the \fIyhsm-validation-server\fR\|(1) (default: /var/yubico/yhsm-validation-server.db)
+
+
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+.IP "\fB0\fR" 4
+.IX Item "0"
+YubiHSM keystore successfully unlocked
+.IP "\fB1\fR" 4
+.IX Item "1"
+Failed to unlock keystore
+.IP "\fB255\fR" 4
+.IX Item "255"
+Client ID not found in internal database
+
+.SH BUGS
+Report python-pyhsm/yhsm-init-oath-token bugs in
+.URL "https://github.com/Yubico/python-pyhsm/issues/" "the issue tracker"
+
+.SH "SEE ALSO"
+The
+.URL "https://github.com/Yubico/python-pyhsm/" "python-yubico home page"
+.PP
+YubiHSMs can be obtained from
+.URL "http://www.yubico.com/" "Yubico" "."
@@ -0,0 +1,65 @@
+.\" Copyright (c) 2011 Yubico AB
+.\" See the file COPYING for license statement.
+.\"
+.de URL
+\\$2 \(laURL: \\$1 \(ra\\$3
+..
+.if \n[.g] .mso www.tmac
+.TH yhsm-validate-otp "1" "December 2011" "python-pyhsm"
+
+.SH NAME
+yhsm-validate-otp \(hy Validate an OTP using a YubiHSM.
+
+.SH SYNOPSIS
+.B yhsm-validate-otp
+\fImode\fR
+[\fIoptions\fR]
+
+.SH DESCRIPTION
+This tool allows simple validation of YubiKey OTP from shell scripts.
+
+.SH OPTIONS
+.PP
+.TP
+\fB\-D\fR, \fB\-\-device\fR
+device file name (default: /dev/ttyACM0).
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+enable verbose operation.
+.TP
+\fB\-\-debug\fR
+enable debug printout, including all data sent to/from YubiHSM.
+
+.SH MODES
+\fB\-\-otp\fR
+Validate YubiKey OTP against entry in the YubiHSM internal database.
+
+.\"\fB\-\-oath\fR
+.\"\fBNot implemented yet.\fR
+.\"Validate an OATH code using HMAC-SHA-1 in the YubiHSM. The OATH counter
+.\"database must be initialized using \fIyhsm-init-oath-token\fR\|(1) first.
+
+
+
+.SH "EXIT STATUS"
+.IX Header "EXIT STATUS"
+.IP "\fB0\fR" 4
+.IX Item "0"
+YubiHSM keystore successfully unlocked
+.IP "\fB1\fR" 4
+.IX Item "1"
+Failed to unlock keystore
+.IP "\fB255\fR" 4
+.IX Item "255"
+Client ID not found in internal database
+
+.SH BUGS
+Report python-pyhsm/yhsm-validate-otp bugs in
+.URL "https://github.com/Yubico/python-pyhsm/issues/" "the issue tracker"
+
+.SH "SEE ALSO"
+The
+.URL "https://github.com/Yubico/python-pyhsm/" "python-yubico home page"
+.PP
+YubiHSMs can be obtained from
+.URL "http://www.yubico.com/" "Yubico" "."
Oops, something went wrong.

0 comments on commit 69051b5

Please sign in to comment.