<?xml version="1.0" encoding="UTF-8"?>
<refentry id="sc-hsm-tool">
	<refmeta>
		<refentrytitle>sc-hsm-tool</refentrytitle>
		<manvolnum>1</manvolnum>
		<refmiscinfo class="productname">OpenSC</refmiscinfo>
		<refmiscinfo class="manual">OpenSC Tools</refmiscinfo>
		<refmiscinfo class="source">opensc</refmiscinfo>
	</refmeta>

	<refnamediv>
		<refname>sc-hsm-tool</refname>
		<refpurpose>smart card utility for SmartCard-HSM</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>sc-hsm-tool</command>
			<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<para>
			The <command>sc-hsm-tool</command> 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.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<para>
			<variablelist>
				<varlistentry>
					<term>
						<option>--initialize</option>,
						<option>-X</option>
					</term>
					<listitem>
						<para>Initialize token, removing all existing keys, certificates and files.</para>
						<para>Use <option>--so-pin</option> to define SO-PIN for first initialization or to verify in subsequent
					          initializations.</para>
						<para>Use <option>--pin</option> to define the initial user pin value.</para>
						<para>Use <option>--pin-retry</option> to define the maximum number of wrong user PIN presentations.</para>
						<para>Use with <option>--dkek-shares</option> to enable key wrap / unwrap.</para>
						<para>Use with <option>--label</option> to define a token label</para>
						<para>Use with <option>--public-key-auth</option> and <option>--required-pub-keys</option> to require public key authentication for login</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--create-dkek-share</option> <replaceable>filename</replaceable>,
						<option>-C</option> <replaceable>filename</replaceable>
					</term>
					<listitem>
						<para>Create a DKEK share encrypted under a password and save it to the file
						      given as parameter.</para>
						<para>Use <option>--password</option> to provide a password for encryption rather than prompting for one.</para>
						<para>Use <option>--pwd-shares-threshold</option> and <option>--pwd-shares-total</option> to randomly generate a password and split is using a (t, n) threshold scheme.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--import-dkek-share</option> <replaceable>filename</replaceable>, 
						<option>-I</option> <replaceable>filename</replaceable>
					</term>
					<listitem>
						<para>Prompt for user password, read and decrypt DKEK share and import into SmartCard-HSM.</para>
						<para>Use <option>--password</option> to provide a password for decryption rather than prompting for one.</para>
						<para>Use <option>--pwd-shares-total</option> to specify the number of shares that should be entered to reconstruct the password.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--wrap-key</option> <replaceable>filename</replaceable>, 
						<option>-W</option> <replaceable>filename</replaceable>
					</term>
					<listitem>
						<para>Wrap the key referenced in <option>--key-reference</option> and save with it together with the key description
						and certificate to the given file.</para>
						<para>Use <option>--pin</option> to provide the user PIN on the command line.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--unwrap-key</option> <replaceable>filename</replaceable>, 
						<option>-U</option> <replaceable>filename</replaceable>
					</term>
					<listitem>
						<para>Read wrapped key, description and certificate from file and import into SmartCard-HSM
						     under the key reference given in <option>--key-reference</option>.</para>
						<para>Determine the key reference using the output of <command>pkcs15-tool -D</command>.</para>				     
						<para>Use <option>--pin</option> to provide a user PIN on the command line.</para>
						<para>Use <option>--force</option> to remove any key, key description or certificate in the way.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--dkek-shares</option> <replaceable>number-of-shares</replaceable>, 
						<option>-s</option> <replaceable>number-of-shares</replaceable>
					</term>
					<listitem>
						<para>Define the number of DKEK shares to use for recreating the DKEK.</para>
						<para>This is an optional parameter. Using <option>--initialize</option> without 
						      <option>--dkek-shares</option> will disable the DKEK completely.</para>				     
						<para>Using <option>--dkek-shares</option> 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.</para>		
						<para>After using <option>--initialize</option> 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.</para>		     
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--pin</option> <replaceable>pin</replaceable>,
						<option>--so-pin</option> <replaceable>sopin</replaceable>,
					</term>
					<listitem>
						<para>
							These options can be used to specify the PIN values
							on the command line. If the value is set to
							<literal>env:</literal><replaceable>VARIABLE</replaceable>, the value
							of the specified environment variable is used. By default,
							the code is prompted on the command line if needed.
						</para>
						<para>
							Note that on most operation systems, any user can
							display the command line of any process on the
							system using utilities such as
							<command>ps(1)</command>. Therefore, you should prefer
							passing the codes via an environment variable
							on an unsecured system.
						</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--pin-retry</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>Define number of PIN retries for user PIN during initialization. Default is 3.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--bio-server1</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>The hexadecimal AID of of the biometric server for template 1. Switches on the use of the user PIN as session PIN.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--bio-server2</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>The hexadecimal AID of of the biometric server for template 2. Switches on the use of the user PIN as session PIN.</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--password</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>Define password for DKEK share encryption. If set to
						env:<replaceable>VARIABLE</replaceable>, the value of
						the environment variable
						<replaceable>VARIABLE</replaceable> is used.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--pwd-shares-threshold</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>Define threshold for number of password shares required for reconstruction.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--pwd-shares-total</option> <replaceable>value</replaceable>
					</term>
					<listitem>
						<para>Define number of password shares.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--force</option>
					</term>
					<listitem>
						<para>Force removal of existing key, description and certificate.</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--label</option> <replaceable>label</replaceable>,
						<option>-l</option> <replaceable>label</replaceable>
					</term>
					<listitem><para>Define the token label to be used in --initialize.</para></listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--reader</option> <replaceable>arg</replaceable>,
						<option>-r</option> <replaceable>arg</replaceable>
					</term>
					<listitem>
						<para>
							Number of the reader to use. By default, the first
							reader with a present card is used. If
							<replaceable>arg</replaceable> is an ATR, the
							reader with a matching card will be chosen.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--public-key-auth</option> <replaceable>total-number-of-public-keys</replaceable>,
						<option>-K</option> <replaceable>total-number-of-public-keys</replaceable>
					</term>
					<listitem>
						<para>Define the total number of public keys to use for public key authentication when using <option>--initialize</option>.
							  <option>--public-key-auth</option> is optional, but if it's present, it must be used with <option>--required-pub-keys</option>.
						</para>
						<para>When the SmartCard-HSM is initialized with these options, it will require M-of-N public key authentication to be used, where
							<option>--required-pub-keys</option> sets the M and <option>--public-key-auth</option> sets the N. After the initialization,
							the user should use <option>--register-public-key</option> to register the N public keys before the SmartCard-HSM can be used.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--required-pub-keys</option> <replaceable>required-number-of-public-keys</replaceable>,
						<option>-n</option> <replaceable>required-number-of-public-keys</replaceable>
					</term>
					<listitem>
						<para>Define the required number of public keys to use for public key authentication when using <option>--initialize</option>.
							  This is the M in M-of-N public key authentication. See <option>--public-key-auth</option> for more information.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--register-public-key</option> <replaceable>input-public-key-file</replaceable>,
						<option>-g</option> <replaceable>input-public-key-file</replaceable>
					</term>
					<listitem>
						<para>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 <option>--export-for-pub-key-auth</option>. This can only be used when the
							  SmartCard-HSM has been initialized with <option>--public-key-auth</option> and <option>--required-pub-keys</option>
							  and fewer than N public keys have been registered. Use <option>--public-key-auth-status</option> to check the
							  how many public keys have been registered.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--export-for-pub-key-auth</option> <replaceable>output-public-key-file</replaceable>,
						<option>-e</option> <replaceable>output-public-key-file</replaceable>
					</term>
					<listitem>
						<para>Export a public key to be used for M-of-N public key authentication. This should be used with
							  <option>--key-reference</option> to choose the key to export. The file should be registered on
							  another SmartCard-HSM using <option>--register-public-key</option>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--public-key-auth-status</option>
						<option>-S</option>
					</term>
					<listitem>
						<para>Print the public key authentication status. This is only valid if the SmartCard-HSM was initialized
							  to use M-of-N public key authentication.
						</para>
					</listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--wait</option>,
						<option>-w</option>
					</term>
					<listitem><para>Wait for a card to be inserted</para></listitem>
				</varlistentry>
				
				<varlistentry>
					<term>
						<option>--verbose</option>,
						<option>-v</option>
					</term>
					<listitem><para>Causes <command>sc-hsm-tool</command> to be more verbose.
					Specify this flag several times to enable debug output in the opensc
					library.</para></listitem>
				</varlistentry>
			</variablelist>
		</para>
	</refsect1>

	<refsect1>
		<title>Examples</title>
		<para>Create a DKEK share:</para>
		<para><command>sc-hsm-tool --create-dkek-share dkek-share-1.pbe</command></para>
		<para>Create a DKEK share with random password split up using a (3, 5) threshold scheme:</para>
		<para><command>sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5</command></para>
		<para>Initialize SmartCard-HSM to use a single DKEK share:</para>
		<para><command>sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken</command></para>
		<para>Import DKEK share:</para>
		<para><command>sc-hsm-tool --import-dkek-share dkek-share-1.pbe</command></para>
		<para>Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:</para>
		<para><command>sc-hsm-tool --import-dkek-share dkek-share-1.pbe  --pwd-shares-total 3</command></para>
		<para>Wrap referenced key, description and certificate:</para>
		<para><command>sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219</command></para>
		<para>Unwrap key into same or in different SmartCard-HSM with the same DKEK:</para>
		<para><command>sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force</command></para>
		<para>Initialize SmartCard-HSM to use M-of-N public key authentication with M=2 and N=5</para>
		<para><command>sc-hsm-tool --initialize --required-pub-keys 2 --public-key-auth 5</command></para>
		<para>Export a public key for M-of-N public key authentication to a file</para>
		<para><command>sc-hsm-tool --key-reference 1 --export-for-pub-key-auth ./public_key1.asn1</command></para>
		<para>Register a public key for M-of-N public key authentication from a file</para>
		<para><command>sc-hsm-tool --register-public-key ./public_key1.asn1</command></para>

	</refsect1>
	
	<refsect1>
		<title>See also</title>
		<para>
			<citerefentry>
				<refentrytitle>opensc-tool</refentrytitle>
				<manvolnum>1</manvolnum>
			</citerefentry>
		</para>
	</refsect1>

	<refsect1>
		<title>Authors</title>
		<para><command>sc-hsm-tool</command> was written by
		Andreas Schwier <email>andreas.schwier@cardcontact.de</email>.</para>
	</refsect1>

</refentry>
