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

	<refnamediv>
		<refname>westcos-tool</refname>
		<refpurpose>utility for manipulating data structures
			on westcos smart cards</refpurpose>
	</refnamediv>

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

	<refsect1>
		<title>Description</title>
		<para>
			The <command>westcos-tool</command> utility is used to manipulate
			the westcos data structures on 2 Ko smart cards / tokens. Users can create PINs,
			keys and certificates stored on the card / token. User PIN authentication is
			performed for those operations that require it.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<para>
			<variablelist>
				<varlistentry>
					<term>
						<option>--change-pin</option>,
						<option>-n</option>
					</term>
					<listitem><para>Changes a PIN stored on the card.
					User authentication is required for this operation.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--certificate</option> <replaceable>file</replaceable>,
						<option>-t</option> <replaceable>file</replaceable>
					</term>
					<listitem><para>Write certificate file <replaceable>file</replaceable>
					in PEM format to the card.
					User authentication is required for this operation.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--finalize</option>,
						<option>-f</option>
					</term>
					<listitem><para>Finalize the card. Once finalized the default key is
					invalidated, so PIN and PUK cannot be changed anymore without user
					authentication.</para>
					<para>Warning, un-finalized cards are insecure because the PIN can be
					changed without user authentication (knowledge of default key
					is enough).</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--generate-key</option>,
						<option>-g</option>
					</term>
					<listitem><para>Generate a private key on the card. The card must not have
					been finalized and a PIN must be installed (i.e. the file for the PIN must
					have been created, see option <option>-i</option>).
					By default the key length is 1536 bits. User authentication is required for
					this operation. </para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--help</option>,
						<option>-h</option>
					</term>
					<listitem><para>Print help message on screen.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--install-pin</option>,
						<option>-i</option>
					</term>
					<listitem><para>Install PIN file in on the card.
					You must provide a PIN value with <option>-x</option>.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--key-length</option> <replaceable>length</replaceable>,
						<option>-l</option> <replaceable>length</replaceable>
					</term>
					<listitem><para>Change the length of private key.
					Use with <option>-g</option>.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--overwrite-key</option>,
						<option>-o</option>
					</term>
					<listitem><para>Overwrite the key if there is already a key on the card.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--pin-value</option> <replaceable>pin</replaceable>,
						<option>-x</option> <replaceable>pin</replaceable>
						<option>--puk-value</option> <replaceable>puk</replaceable>,
						<option>-y</option> <replaceable>puk</replaceable>
					</term>
					<listitem>
						<para>
							These options can be used to specify the PIN/PUK 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>--read-file</option> <replaceable>filename</replaceable>,
						<option>-j</option> <replaceable>filename</replaceable>
					</term>
					<listitem><para>Read the file <replaceable>filename</replaceable> from the card.
					The file is written on disk with name <replaceable>filename</replaceable>.
					User authentication is required for this operation.</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>--unblock-pin</option>,
						<option>-u</option>
					</term>
					<listitem><para>Unblocks a PIN stored on the card. Knowledge of the
					PIN Unblock Key (PUK) is required for this operation.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<option>--verbose</option>
						<option>-v</option>
					</term>
					<listitem><para>Causes <command>westcos-tool</command> to be more
					verbose. Specify this flag several times to enable debug output
					in the OpenSC library.</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>--write-file</option> <replaceable>filename</replaceable>,
						<option>-k</option> <replaceable>filename</replaceable>
					</term>
					<listitem><para>Put the file with name <replaceable>filename</replaceable>
					from disk to card.
					On the card the file is written in <replaceable>filename</replaceable>.
					User authentication is required for this operation.</para></listitem>
				</varlistentry>

			</variablelist>
		</para>
	</refsect1>

	<refsect1>
		<title>Authors</title>
		<para><command>westcos-tool</command> was written by
		Francois Leblanc <email>francois.leblanc@cev-sa.com</email>.</para>
	</refsect1>

</refentry>
