'\" t
.\"     Title: sc-hsm-tool
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/10/2024
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "SC\-HSM\-TOOL" "1" "03/10/2024" "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
.sp
Use with
\fB\-\-public\-key\-auth\fR
and
\fB\-\-required\-pub\-keys\fR
to require public key authentication for login
.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\-\-pin\fR \fIpin\fR, \fB\-\-so\-pin\fR \fIsopin\fR,
.RS 4
These options can be used to specify the PIN values on the command line\&. If the value is set to
env:\fIVARIABLE\fR, the value of the specified environment variable is used\&. By default, the code is prompted on the command line if needed\&.
.sp
Note that on most operation systems, any user can display the command line of any process on the system using utilities such as
\fBps(1)\fR\&. Therefore, you should prefer passing the codes via an environment variable on an unsecured system\&.
.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\-\-bio\-server1\fR \fIvalue\fR
.RS 4
The hexadecimal AID of of the biometric server for template 1\&. Switches on the use of the user PIN as session PIN\&.
.RE
.PP
\fB\-\-bio\-server2\fR \fIvalue\fR
.RS 4
The hexadecimal AID of of the biometric server for template 2\&. Switches on the use of the user PIN as session PIN\&.
.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 \fIarg\fR, \fB\-r\fR \fIarg\fR
.RS 4
Number of the reader to use\&. By default, the first reader with a present card is used\&. If
\fIarg\fR
is an ATR, the reader with a matching card will be chosen\&.
.RE
.PP
\fB\-\-public\-key\-auth\fR \fItotal\-number\-of\-public\-keys\fR, \fB\-K\fR \fItotal\-number\-of\-public\-keys\fR
.RS 4
Define the total number of public keys to use for public key authentication when using
\fB\-\-initialize\fR\&.
\fB\-\-public\-key\-auth\fR
is optional, but if it\*(Aqs present, it must be used with
\fB\-\-required\-pub\-keys\fR\&.
.sp
When the SmartCard\-HSM is initialized with these options, it will require M\-of\-N public key authentication to be used, where
\fB\-\-required\-pub\-keys\fR
sets the M and
\fB\-\-public\-key\-auth\fR
sets the N\&. After the initialization, the user should use
\fB\-\-register\-public\-key\fR
to register the N public keys before the SmartCard\-HSM can be used\&.
.RE
.PP
\fB\-\-required\-pub\-keys\fR \fIrequired\-number\-of\-public\-keys\fR, \fB\-n\fR \fIrequired\-number\-of\-public\-keys\fR
.RS 4
Define the required number of public keys to use for public key authentication when using
\fB\-\-initialize\fR\&. This is the M in M\-of\-N public key authentication\&. See
\fB\-\-public\-key\-auth\fR
for more information\&.
.RE
.PP
\fB\-\-register\-public\-key\fR \fIinput\-public\-key\-file\fR, \fB\-g\fR \fIinput\-public\-key\-file\fR
.RS 4
Register a public key to be used for M\-of\-N public key authentication\&. The file can be exported from a different SmartCard\-HSM with
\fB\-\-export\-for\-pub\-key\-auth\fR\&. This can only be used when the SmartCard\-HSM has been initialized with
\fB\-\-public\-key\-auth\fR
and
\fB\-\-required\-pub\-keys\fR
and fewer than N public keys have been registered\&. Use
\fB\-\-public\-key\-auth\-status\fR
to check the how many public keys have been registered\&.
.RE
.PP
\fB\-\-export\-for\-pub\-key\-auth\fR \fIoutput\-public\-key\-file\fR, \fB\-e\fR \fIoutput\-public\-key\-file\fR
.RS 4
Export a public key to be used for M\-of\-N public key authentication\&. This should be used with
\fB\-\-key\-reference\fR
to choose the key to export\&. The file should be registered on another SmartCard\-HSM using
\fB\-\-register\-public\-key\fR\&.
.RE
.PP
\fB\-\-public\-key\-auth\-status\fR \fB\-S\fR
.RS 4
Print the public key authentication status\&. This is only valid if the SmartCard\-HSM was initialized to use M\-of\-N public key authentication\&.
.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
.PP
Initialize SmartCard\-HSM to use M\-of\-N public key authentication with M=2 and N=5
.PP
\fBsc\-hsm\-tool \-\-initialize \-\-required\-pub\-keys 2 \-\-public\-key\-auth 5\fR
.PP
Export a public key for M\-of\-N public key authentication to a file
.PP
\fBsc\-hsm\-tool \-\-key\-reference 1 \-\-export\-for\-pub\-key\-auth \&./public_key1\&.asn1\fR
.PP
Register a public key for M\-of\-N public key authentication from a file
.PP
\fBsc\-hsm\-tool \-\-register\-public\-key \&./public_key1\&.asn1\fR
.SH "SEE ALSO"
.PP
\fBopensc-tool\fR(1)
.SH "AUTHORS"
.PP
\fBsc\-hsm\-tool\fR
was written by Andreas Schwier
<andreas\&.schwier@cardcontact\&.de>\&.