Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SC-HSM-TOOL(1)			 OpenSC	Tools			SC-HSM-TOOL(1)

       sc-hsm-tool - smart card	utility	for SmartCard-HSM

       sc-hsm-tool [OPTIONS]

       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.

       --initialize, -X
	   Initialize token, removing all existing keys, certificates and

	   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

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

	   Use with --label to define a	token label

       --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.

       --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.

       --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

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

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

	   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.

       --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.

       --pin pin, --so-pin sopin,
	   These options can be	used to	specify	the PIN	values on the command
	   line. If the	value is set to	env:VARIABLE, the value	of the
	   specified environment variable is used. By default, the code	is
	   prompted on the command line	if needed.

	   Note	that on	most operation systems,	any user can display the
	   command line	of any process on the system using utilities such as
	   ps(1). Therefore, you should	prefer passing the codes via an
	   environment variable	on an unsecured	system.

       --pin-retry value
	   Define number of PIN	retries	for user PIN during initialization.
	   Default is 3.

       --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.

       --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.

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

       --pwd-shares-threshold value
	   Define threshold for	number of password shares required for

       --pwd-shares-total value
	   Define number of password shares.

	   Force removal of existing key, description and certificate.

       --label label, -l label
	   Define the token label to be	used in	--initialize.

       --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.

       --wait, -w
	   Wait	for a card to be inserted

       --verbose, -v
	   Causes sc-hsm-tool to be more verbose. Specify this flag several
	   times to enable debug output	in the opensc library.

       Create a	DKEK share:

       sc-hsm-tool --create-dkek-share dkek-share-1.pbe

       Create a	DKEK share with	random password	split up using a (3, 5)
       threshold scheme:

       sc-hsm-tool --create-dkek-share dkek-share-1.pbe	--pwd-shares-threshold
       3 --pwd-shares-total 5

       Initialize SmartCard-HSM	to use a single	DKEK share:

       sc-hsm-tool --initialize	--so-pin 3537363231383830 --pin	648219
       --dkek-shares 1 --label mytoken

       Import DKEK share:

       sc-hsm-tool --import-dkek-share dkek-share-1.pbe

       Import DKEK share using a password split	up using a (3, 5) threshold
       scheme for encryption:

       sc-hsm-tool --import-dkek-share dkek-share-1.pbe	--pwd-shares-total 3

       Wrap referenced key, description	and certificate:

       sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219

       Unwrap key into same or in different SmartCard-HSM with the same	DKEK:

       sc-hsm-tool --unwrap-key	wrap-key.bin --key-reference 10	--pin 648219


       sc-hsm-tool was written by Andreas Schwier

opensc				  02/28/2021			SC-HSM-TOOL(1)


Want to link to this manual page? Use this URL:

home | help