SC-HSM-TOOL(1)

    .SH "NAME" sc-hsm-tool - smart card utility for SmartCard-HSM
    .SH "SYNOPSIS"
        .HP u
            sc-hsm-tool
             [OPTIONS]

    .SH ""
        .PP The sc-hsm-tool 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 --initialize, -X

                            Initialize token, removing all existing keys, certificates and files.

                            Use --so-pin to define SO-PIN for first initialization or to verify in subsequent initializations.

                            Use --pin to define the initial user pin value.

                            Use --pin-retry to define the maximum number of wrong user PIN presentations.

                            Use with --dkek-shares to enable key wrap / unwrap.

                            Use with --label to define a token label

                    .RE
                    .PP --create-dkek-share filename, -C filename

                                Create a DKEK share encrypted under a password and save it to the file given as parameter.

                                Use --password to provide a password for encryption rather than prompting for one.

                                Use --pwd-shares-threshold and --pwd-shares-total to randomly generate a password and split is using a (t, n) threshold scheme.

                        .RE

                        .PP --import-dkek-share filename, -I filename

                                    Prompt for user password, read and decrypt DKEK share and import into SmartCard-HSM.

                                    Use --password to provide a password for decryption rather than prompting for one.

                                    Use --pwd-shares-total to specify the number of shares that should be entered to reconstruct the password.

                            .RE

                            .PP --wrap-key filename, -W filename

                                        Wrap the key referenced in --key-reference and save with it together with the key description and certificate to the given file.

                                        Use --pin to provide the user PIN on the command line.

                                .RE

                                .PP --unwrap-key filename, -U filename

                                            Read wrapped key, description and certificate from file and import into SmartCard-HSM under the key reference given in --key-reference.

                                            Determine the key reference using the output of pkcs15-tool -D.

                                            Use --pin to provide a user PIN on the command line.

                                            Use --force to remove any key, key description or certificate in the way.

                                    .RE

                                    .PP --dkek-shares number-of-shares, -s number-of-shares

                                                Define the number of DKEK shares to use for recreating the DKEK.

                                                This is an optional parameter. Using --initialize without --dkek-shares will disable the DKEK completely.

                                                Using --dkek-shares 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.

                                                After using --initialize 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 --so-pin value

                                                    Define SO-PIN for initialization. If set to env:VARIABLE, the value of the environment variable VARIABLE is used.

                                            .RE

                                            .PP --pin value

                                                        Define user PIN for initialization, wrap or unwrap operation. If set to env:VARIABLE, the value of the environment variable VARIABLE is used.

                                                .RE

                                                .PP --pin-retry value

                                                            Define number of PIN retries for user PIN during initialization. Default is 3.

                                                    .RE
                                                    .PP --bio-server1 value

                                                                The hexadecimal AID of of the biometric server for template 1. Switches on the use of the user PIN as session PIN.

                                                        .RE
                                                        .PP --bio-server2 value

                                                                    The hexadecimal AID of of the biometric server for template 2. Switches on the use of the user PIN as session PIN.

                                                            .RE
                                                            .PP --password value

                                                                        Define password for DKEK share encryption. If set to env:VARIABLE, the value of the environment variable VARIABLE is used.

                                                                .RE

                                                                .PP --pwd-shares-threshold value

                                                                            Define threshold for number of password shares required for reconstruction.

                                                                    .RE

                                                                    .PP --pwd-shares-total value

                                                                                Define number of password shares.

                                                                        .RE

                                                                        .PP --force

                                                                                    Force removal of existing key, description and certificate.

                                                                            .RE

                                                                            .PP --label label, -l label

                                                                                    Define the token label to be used in --initialize.
                                                                                .RE

                                                                                .PP --reader arg, -r arg

                                                                                            Number of the reader to use. By default, the first reader with a present card is used. If arg is an ATR, the reader with a matching card will be chosen.

                                                                                    .RE

                                                                                    .PP --wait, -w

                                                                                            Wait for a card to be inserted
                                                                                        .RE

                                                                                        .PP --verbose, -v

                                                                                                Causes sc-hsm-tool 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 sc-hsm-tool --create-dkek-share dkek-share-1.pbe
                                                                                    .PP Create a DKEK share with random password split up using a (3, 5) threshold scheme:
                                                                                    .PP sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5
                                                                                    .PP Initialize SmartCard-HSM to use a single DKEK share:
                                                                                    .PP sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken
                                                                                    .PP Import DKEK share:
                                                                                    .PP sc-hsm-tool --import-dkek-share dkek-share-1.pbe
                                                                                    .PP Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:
                                                                                    .PP sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
                                                                                    .PP Wrap referenced key, description and certificate:
                                                                                    .PP sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
                                                                                    .PP Unwrap key into same or in different SmartCard-HSM with the same DKEK:
                                                                                    .PP sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force

                                                                                .SH "SEE ALSO"

                                                                                    .PP opensc-tool(1)

                                                                                .SH "AUTHORS"

                                                                                    .PP sc-hsm-tool was written by Andreas Schwier <andreas.schwier@cardcontact.de>.