'\" t .\" Title: sc-hsm-tool .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] .\" Generator: DocBook XSL Stylesheets v1.79.1 .\" Date: 09/30/2018 .\" Manual: OpenSC Tools .\" Source: opensc .\" Language: English .\" .TH "SC\-HSM\-TOOL" "1" "09/30/2018" "opensc" "OpenSC Tools" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" sc-hsm-tool \- smart card utility for SmartCard\-HSM .SH "SYNOPSIS" .HP \w'\fBsc\-hsm\-tool\fR\ 'u \fBsc\-hsm\-tool\fR [\fIOPTIONS\fR] .SH "" .PP The \fBsc\-hsm\-tool\fR utility can be used from the command line to perform extended maintenance tasks not available via PKCS#11 or other tools in the OpenSC package\&. It can be used to query the status of a SmartCard\-HSM, initialize a device, generate and import Device Key Encryption Key (DKEK) shares and to wrap and unwrap keys\&. .SH "OPTIONS" .PP .PP \fB\-\-initialize\fR, \fB\-X\fR .RS 4 Initialize token, removing all existing keys, certificates and files\&. .sp Use \fB\-\-so\-pin\fR to define SO\-PIN for first initialization or to verify in subsequent initializations\&. .sp Use \fB\-\-pin\fR to define the initial user pin value\&. .sp Use \fB\-\-pin\-retry\fR to define the maximum number of wrong user PIN presentations\&. .sp Use with \fB\-\-dkek\-shares\fR to enable key wrap / unwrap\&. .sp Use with \fB\-\-label\fR to define a token label .RE .PP \fB\-\-create\-dkek\-share\fR \fIfilename\fR, \fB\-C\fR \fIfilename\fR .RS 4 Create a DKEK share encrypted under a password and save it to the file given as parameter\&. .sp Use \fB\-\-password\fR to provide a password for encryption rather than prompting for one\&. .sp Use \fB\-\-pwd\-shares\-threshold\fR and \fB\-\-pwd\-shares\-total\fR to randomly generate a password and split is using a (t, n) threshold scheme\&. .RE .PP \fB\-\-import\-dkek\-share\fR \fIfilename\fR, \fB\-I\fR \fIfilename\fR .RS 4 Prompt for user password, read and decrypt DKEK share and import into SmartCard\-HSM\&. .sp Use \fB\-\-password\fR to provide a password for decryption rather than prompting for one\&. .sp Use \fB\-\-pwd\-shares\-total\fR to specify the number of shares that should be entered to reconstruct the password\&. .RE .PP \fB\-\-wrap\-key\fR \fIfilename\fR, \fB\-W\fR \fIfilename\fR .RS 4 Wrap the key referenced in \fB\-\-key\-reference\fR and save with it together with the key description and certificate to the given file\&. .sp Use \fB\-\-pin\fR to provide the user PIN on the command line\&. .RE .PP \fB\-\-unwrap\-key\fR \fIfilename\fR, \fB\-U\fR \fIfilename\fR .RS 4 Read wrapped key, description and certificate from file and import into SmartCard\-HSM under the key reference given in \fB\-\-key\-reference\fR\&. .sp Determine the key reference using the output of \fBpkcs15\-tool \-D\fR\&. .sp Use \fB\-\-pin\fR to provide a user PIN on the command line\&. .sp Use \fB\-\-force\fR to remove any key, key description or certificate in the way\&. .RE .PP \fB\-\-dkek\-shares\fR \fInumber\-of\-shares\fR, \fB\-s\fR \fInumber\-of\-shares\fR .RS 4 Define the number of DKEK shares to use for recreating the DKEK\&. .sp This is an optional parameter\&. Using \fB\-\-initialize\fR without \fB\-\-dkek\-shares\fR will disable the DKEK completely\&. .sp Using \fB\-\-dkek\-shares\fR with 0 shares requests the SmartCard\-HSM to generate a random DKEK\&. Keys wrapped with this DKEK can only be unwrapped in the same SmartCard\-HSM\&. .sp After using \fB\-\-initialize\fR with one or more DKEK shares, the SmartCard\-HSM will remain in the initialized state until all DKEK shares have been imported\&. During this phase no new keys can be generated or imported\&. .RE .PP \fB\-\-so\-pin\fR \fIvalue\fR .RS 4 Define SO\-PIN for initialization\&. If set to env:\fIVARIABLE\fR, the value of the environment variable \fIVARIABLE\fR is used\&. .RE .PP \fB\-\-pin\fR \fIvalue\fR .RS 4 Define user PIN for initialization, wrap or unwrap operation\&. If set to env:\fIVARIABLE\fR, the value of the environment variable \fIVARIABLE\fR is used\&. .RE .PP \fB\-\-pin\-retry\fR \fIvalue\fR .RS 4 Define number of PIN retries for user PIN during initialization\&. Default is 3\&. .RE .PP \fB\-\-password\fR \fIvalue\fR .RS 4 Define password for DKEK share encryption\&. If set to env:\fIVARIABLE\fR, the value of the environment variable \fIVARIABLE\fR is used\&. .RE .PP \fB\-\-pwd\-shares\-threshold\fR \fIvalue\fR .RS 4 Define threshold for number of password shares required for reconstruction\&. .RE .PP \fB\-\-pwd\-shares\-total\fR \fIvalue\fR .RS 4 Define number of password shares\&. .RE .PP \fB\-\-force\fR .RS 4 Force removal of existing key, description and certificate\&. .RE .PP \fB\-\-label\fR \fIlabel\fR, \fB\-l\fR \fIlabel\fR .RS 4 Define the token label to be used in \-\-initialize\&. .RE .PP \fB\-\-reader\fR \fInum\fR, \fB\-r\fR \fInum\fR .RS 4 Use the given reader number\&. The default is 0, the first reader in the system\&. .RE .PP \fB\-\-wait\fR, \fB\-w\fR .RS 4 Wait for a card to be inserted .RE .PP \fB\-\-verbose\fR, \fB\-v\fR .RS 4 Causes \fBsc\-hsm\-tool\fR to be more verbose\&. Specify this flag several times to enable debug output in the opensc library\&. .RE .SH "EXAMPLES" .PP Create a DKEK share: .PP \fBsc\-hsm\-tool \-\-create\-dkek\-share dkek\-share\-1\&.pbe\fR .PP Create a DKEK share with random password split up using a (3, 5) threshold scheme: .PP \fBsc\-hsm\-tool \-\-create\-dkek\-share dkek\-share\-1\&.pbe \-\-pwd\-shares\-threshold 3 \-\-pwd\-shares\-total 5\fR .PP Initialize SmartCard\-HSM to use a single DKEK share: .PP \fBsc\-hsm\-tool \-\-initialize \-\-so\-pin 3537363231383830 \-\-pin 648219 \-\-dkek\-shares 1 \-\-label mytoken\fR .PP Import DKEK share: .PP \fBsc\-hsm\-tool \-\-import\-dkek\-share dkek\-share\-1\&.pbe\fR .PP Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption: .PP \fBsc\-hsm\-tool \-\-import\-dkek\-share dkek\-share\-1\&.pbe \-\-pwd\-shares\-total 3\fR .PP Wrap referenced key, description and certificate: .PP \fBsc\-hsm\-tool \-\-wrap\-key wrap\-key\&.bin \-\-key\-reference 1 \-\-pin 648219\fR .PP Unwrap key into same or in different SmartCard\-HSM with the same DKEK: .PP \fBsc\-hsm\-tool \-\-unwrap\-key wrap\-key\&.bin \-\-key\-reference 10 \-\-pin 648219 \-\-force\fR .SH "SEE ALSO" .PP \fBopensc-tool\fR(1)