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

	<refnamediv>
		<refname>opensc-explorer</refname>
		<refpurpose>
			generic interactive utility for accessing smart card
			and similar security token functions
		</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>opensc-explorer</command>
			<arg choice="opt"><replaceable class="option">OPTIONS</replaceable></arg>
			<arg choice="opt"><replaceable class="parameter">SCRIPT</replaceable></arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>
		<para>
			The <command>opensc-explorer</command> utility can be
			used to perform miscellaneous operations
			such as exploring the contents of or sending arbitrary
			APDU commands to a smart card or similar security token.
		</para>
		<para>
			If a <replaceable class="parameter">SCRIPT</replaceable> is given,
			<command>opensc-explorer</command> runs in non-interactive mode,
			reading the commands from <replaceable class="parameter">SCRIPT</replaceable>,
			one command per line.
			If no script is given, <command>opensc-explorer</command>
			runs in interactive mode, reading commands from standard input.
		</para>
	</refsect1>

	<refsect1>
		<title>Options</title>
		<para>
			The following are the command-line options for
			<command>opensc-explorer</command>.  There are additional
			interactive commands available once it is running.
			<variablelist>
				<varlistentry>
					<term>
						<option>--card-driver</option> <replaceable>driver</replaceable>,
						<option>-c</option> <replaceable>driver</replaceable>
					</term>
					<listitem><para>
						Use the given card driver.
						The default is to auto-detect the correct card driver.
						The literal value <literal>?</literal> lists
						all available card drivers and terminates
						<command>opensc-explorer</command>.
					</para></listitem>
				</varlistentry>
				<varlistentry>
					<term>
						<option>--mf</option> <replaceable>path</replaceable>,
						<option>-m</option> <replaceable>path</replaceable>
					</term>
					<listitem>
						<para>
							Select the file referenced by the given path on startup.
							The default is the path to the standard master file,
							<literal>3F00</literal>. If <replaceable>path</replaceable>
							is empty (e.g. <command>opensc-explorer --mf ""</command>),
							then no file is explicitly selected.
						</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>--verbose</option>, <option>-v</option>
					</term>
					<listitem>
						<para>
							Cause <command>opensc-explorer</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>
			</variablelist>
		</para>
	</refsect1>

	<refsect1>
		<title>Commands</title>
		<para>
			<command>opensc-explorer</command> supports commands with arguments
			at its interactive prompt or in script files passed via the command line
			parameter <replaceable class="parameter">SCRIPT</replaceable>.
		</para>
		<para>
			Similar to a command shell like e.g. <code>bash</code>,
			each input line is split into white-space separated words.
			Of these words, the first one is used as the command,
			while the remaining ones are treated as arguments to that command.
		</para>
		<para>
			The following commands are supported:
			<variablelist>
				<varlistentry>
					<term>
						<command>#</command>
						<arg choice="plain" rep="repeat"><replaceable></replaceable></arg>
					</term>
					<listitem>
						<para>
							Treat line as a comment.
							Ignore anything until the end of the line introduced by
							<literal>#</literal>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>apdu</command>
						<arg choice="plain" rep="repeat"><replaceable>data</replaceable></arg>
					</term>
					<listitem>
						<para>
							Send a custom APDU command to the card.
							<replaceable>data</replaceable> is a series of
							sequences of hexadecimal values and strings enclosed
							in double quotes (<literal>"..."</literal>).
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>asn1</command>
						<replaceable>file-id</replaceable>
						<arg choice="opt"><replaceable>rec-no</replaceable></arg>
						<arg choice="opt"><replaceable>offs</replaceable></arg>
					</term>
					<listitem>
						<para>
							Parse and print the ASN.1 encoded content of the working EF
							specified by <replaceable>file-id</replaceable>.
							If the optional parameter
							<replaceable>rec-no</replaceable> is given and the file is
							a record-oriented EF, parse and print only the record
							indicated by this parameter.
							If the optional parameter
							<replaceable>offs</replaceable> is given, start parsing
							and printing the file or record at the offset indicated
							by the value given.
							If this parameter is not given, the default offset is
							<literal>0</literal>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>cat</command>
						<group choice="opt">
							<arg choice="plain"><replaceable>file-id</replaceable></arg>
							<arg choice="plain"><literal>sfi:</literal><replaceable>short-id</replaceable></arg>
						</group>
						<arg choice="opt"><replaceable>rec-no</replaceable></arg>
					</term>
					<listitem>
						<para>
							Print the contents of the working EF specified by
							<replaceable>file-id</replaceable> or the short file id
							<replaceable>short-id</replaceable>.
							If the optional second parameter
							<replaceable>rec-no</replaceable> is given,
							only print the record indicated by this parameter.
							If no argument is given, print the the contents
							of the currently selected EF.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>cd</command>
						<group choice="req">
							<arg choice="plain"><literal>..</literal></arg>
							<arg choice="plain"><replaceable>file-id</replaceable></arg>
							<arg choice="plain"><literal>aid:</literal><replaceable>DF-name</replaceable></arg>
						</group>
					</term>
					<listitem>
						<para>
							Change to another DF specified by the argument passed.
							If the argument given is <literal>..</literal>,
							then move up one level in the file system hierarchy.
							If it is a <replaceable>file-id</replaceable>,
							which must be a DF directly
							beneath the current DF, then change to that DF.
							If it is an application identifier given as
							<literal>aid:</literal><replaceable>DF-name</replaceable>,
							then jump to the MF of the application denoted by
							<replaceable>DF-name</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>change</command>
						<arg choice="plain"><literal>CHV</literal><replaceable>pin-ref</replaceable></arg>
						<arg choice="opt">
							<arg choice="opt"><replaceable>old-pin</replaceable></arg>
							<replaceable>new-pin</replaceable>
						</arg>
					</term>
					<listitem>
						<para>
							Change the PIN specified by <replaceable>pin-ref</replaceable>
							from the value given by <replaceable>old-pin</replaceable> and
							change its value to <replaceable>new-pin</replaceable>.
						</para>
						<para>
							<replaceable>old-pin</replaceable> and
							<replaceable>new-pin</replaceable> can be
							sequences of hexadecimal values,
							strings enclosed in double quotes (<literal>"..."</literal>),
							empty (<literal>""</literal>), or absent.
							If absent, the values are read from the card reader's pin pad.
						</para>
						<para>
							Examples:
							<variablelist>
								<varlistentry>
									<term><code>change CHV2 00:00:00:00:00:00 "foobar"</code></term>
									<listitem><para>
											Change PIN <literal>CHV2</literal>
											to the new value <literal>foobar</literal>,
											giving the old value <literal>00:00:00:00:00:00</literal>.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>change CHV2 "foobar"</code></term>
									<listitem><para>
											Set PIN <literal>CHV2</literal>
											to the new value <literal>foobar</literal>.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>change CHV2</code></term>
									<listitem><para>
											Change PIN <literal>CHV2</literal> using the card reader's pinpad.
									</para></listitem>
								</varlistentry>
							</variablelist>
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>create</command>
						<replaceable>file-id</replaceable>
						<replaceable>size</replaceable>
					</term>
					<listitem>
						<para>
							Create a new EF.
							<replaceable>file-id</replaceable> specifies the numeric id, and
							<replaceable>size</replaceable> the size of the EF to create.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>debug</command>
						<arg choice="opt"><replaceable>level</replaceable></arg>
					</term>
					<listitem>
						<para>
							Set OpenSC debug level to <replaceable>level</replaceable>.
						</para>
						<para>
							If <replaceable>level</replaceable> is omitted,
							show the current debug level.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>delete</command>
						<replaceable>file-id</replaceable>
					</term>
					<listitem>
						<para>
							Remove the EF or DF specified by
							<replaceable>file-id</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>do_get</command>
						<replaceable>hex-tag</replaceable>
						<arg choice="opt"><replaceable>output</replaceable></arg>
					</term>
					<listitem>
						<para>
							Copy the contents of the card's data object
							(<acronym>DO</acronym>)
							specified by <replaceable>hex-tag</replaceable>
							to the local host computer's file named
							<replaceable>output</replaceable>.
						</para>
						<para>
							If <replaceable>output</replaceable> is not given,
							the contents of <replaceable>hex-tag</replaceable>
							will be displayed as hex-dump.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>do_put</command>
						<replaceable>hex-tag</replaceable>
						<replaceable>data</replaceable>
					</term>
					<listitem>
						<para>
							Change the contents of the card's data object
							(<acronym>DO</acronym>)
							specified by <replaceable>hex-tag</replaceable>
							to <replaceable>data</replaceable>.
						</para>
						<para>
							<replaceable>data</replaceable> is either a
							sequence of hexadecimal values or a string enclosed
							in double quotes (<literal>"..."</literal>).
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>echo</command>
						<arg choice="plain" rep="repeat"><replaceable>string</replaceable></arg>
					</term>
					<listitem>
						<para>
							Print the <replaceable>string</replaceable>s given.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>erase</command>
					</term>
					<listitem>
						<para>
							Erase the card, if the card supports it.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>get</command>
						<replaceable>file-id</replaceable>
						<arg choice="opt"><replaceable>output</replaceable></arg>
					</term>
					<listitem>
						<para>
							Copy an EF to a local file.
							The local file is specified by
							<replaceable>output</replaceable>
							while the card file is specified by
							<replaceable>file-id</replaceable>.
						</para>
						<para>
							If <replaceable>output</replaceable> is omitted,
							the name of the output file will be derived from the
							full card path to <replaceable>file-id</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>get_record</command>
						<replaceable>file-id</replaceable>
						<replaceable>rec-no</replaceable>
						<arg choice="opt"><replaceable>output</replaceable></arg>
					</term>
					<listitem>
						<para>
							Copy a record of a record-oriented EF to a local file.
							The local file is specified by
							<replaceable>output</replaceable>
							while the card file and the record are specified by
							<replaceable>file-id</replaceable> and
							<replaceable>rec-no</replaceable>,
						</para>
						<para>
							If <replaceable>output</replaceable> is omitted,
							the name of the output file will be derived from the
							full card path to <replaceable>file-id</replaceable>.
							and the <replaceable>rec-no</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>help</command>
						<arg choice="opt"><replaceable>pattern</replaceable></arg>
					</term>
					<listitem>
						<para>
							Display the list of available commands, their options
							and parameters together with a short help text.
							If <replaceable>pattern</replaceable> is given,
							the commands shown are limited to those matching
							<replaceable>pattern</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>info</command>
						<arg choice="opt"><replaceable>file-id</replaceable></arg>
					</term>
					<listitem>
						<para>
							Display attributes of a file specified by
							<replaceable>file-id</replaceable>.
							If <replaceable>file-id</replaceable> is not supplied,
							the attributes of the current file are displayed.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>ls</command>
						<arg choice="opt" rep="repeat"><replaceable>pattern</replaceable></arg>
					</term>
					<listitem>
						<para>
							List files in the current DF.
							If no <replaceable>pattern</replaceable> is given,
							then all files are listed.
							If one ore more <replaceable>pattern</replaceable>s are given,
							only files matching at least one
							<replaceable>pattern</replaceable> are listed.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>find</command>
						<arg choice="opt">
							<replaceable>start-id</replaceable>
							<arg choice="opt"><replaceable>end-id</replaceable></arg>
						</arg>
					</term>
					<listitem>
						<para>
							Find all files in the current DF.
							Files are found by selecting all file identifiers in the range
							from <replaceable>start-fid</replaceable>
							to <replaceable>end-fid</replaceable>.
						</para>
						<para>
							If not given, the default value for
							<replaceable>start-fid</replaceable> is <literal>0000</literal>,
							while the default for <replaceable>end-fid</replaceable> is
							<literal>FFFF</literal>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>find_tags</command>
						<arg choice="opt">
							<replaceable>start-tag</replaceable>
							<arg choice="opt"><replaceable>end-tag</replaceable></arg>
						</arg>
					</term>
					<listitem>
						<para>
							Find all tags of data objects in the current context.
							Tags are found by using GET DATA in the range from
							from <replaceable>start-tag</replaceable>
							to <replaceable>end-tag</replaceable>.
						</para>
						<para>
							If not given, the default value for
							<replaceable>start-tag</replaceable> is <literal>0000</literal>,
							while the default for <replaceable>end-tag</replaceable> is
							<literal>FFFF</literal>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>mkdir</command>
						<replaceable>file-id</replaceable>
						<replaceable>size</replaceable>
					</term>
					<listitem>
						<para>
							Create a DF.
							<replaceable>file-id</replaceable> specifies the numeric id,
							and <replaceable>size</replaceable> the size of the DF to create.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>pin_info</command>
						<replaceable>key-type</replaceable><replaceable>key-id</replaceable>
					</term>
					<listitem>
						<para>
							Get information on a PIN or key from the card, where
							<replaceable>key-type</replaceable> can be one of
							<literal>CHV</literal>, <literal>KEY</literal>,
							<literal>AUT</literal> or <literal>PRO</literal>.
							<replaceable>key-id</replaceable> is a number
							representing the key or PIN reference.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>put</command>
						<replaceable>file-id</replaceable>
						<replaceable>input</replaceable>
					</term>
					<listitem>
						<para>
							Copy a local file to the card.
							The local file is specified by <replaceable>input</replaceable>
							while the card file is specified by
							<replaceable>file-id</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>quit</command>
					</term>
					<listitem><para>Exit the program.</para></listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>random</command>
						<replaceable>count</replaceable>
						<arg choice="opt"><replaceable>output-file</replaceable></arg>
					</term>
					<listitem>
						<para>
							Generate <replaceable>count</replaceable> bytes
							of random data.
							If <replaceable>output-file</replaceable> is given,
							write the data to the host computer's file denoted
							by it, otherwise show the data as hex dump.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>rm</command>
						<replaceable>file-id</replaceable>
					</term>
					<listitem>
						<para>
							Remove the EF or DF specified by
							<replaceable>file-id</replaceable>.
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>unblock</command>
						<literal>CHV</literal><replaceable>pin-ref</replaceable>
						<arg choice="opt">
							<replaceable>puk</replaceable>
							<arg choice="opt"><replaceable>new-pin</replaceable></arg>
						</arg>
					</term>
					<listitem>
						<para>
							Unblock the PIN denoted by <replaceable>pin-ref</replaceable>
							using the PUK <replaceable>puk</replaceable>, and potentially
							change its value to <replaceable>new-pin</replaceable>.
						</para>
						<para>
							<replaceable>puk</replaceable> and
							<replaceable>new-pin</replaceable> can be
							sequences of hexadecimal values,
							strings enclosed in double quotes (<literal>"..."</literal>),
							empty (<literal>""</literal>), or absent.
							If absent, the values are read from the card reader's pin pad.
						</para>
						<para>
							Examples:
							<variablelist>
								<varlistentry>
									<term><code>unblock CHV2 00:00:00:00:00:00 "foobar"</code></term>
									<listitem><para>
											Unblock PIN <literal>CHV2</literal> using PUK
											<literal>00:00:00:00:00:00</literal>
											and set it to the new value <literal>foobar</literal>.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>unblock CHV2 00:00:00:00:00:00 ""</code></term>
									<listitem><para>
											Unblock PIN <literal>CHV2</literal> using PUK
											<literal>00:00:00:00:00:00</literal> keeping the old value.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>unblock CHV2 "" "foobar"</code></term>
									<listitem><para>
											Set new value of PIN <literal>CHV2</literal>
											to <literal>foobar</literal>.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>unblock CHV2 00:00:00:00:00:00</code></term>
									<listitem><para>
											Unblock PIN <literal>CHV2</literal> using PUK
											<literal>00:00:00:00:00:00</literal>.
											The new PIN value is prompted by pinpad.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>unblock CHV2 ""</code></term>
									<listitem><para>
											Set PIN <literal>CHV2</literal>.
											The new PIN value is prompted by pinpad.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>unblock CHV2</code></term>
									<listitem><para>
											Unblock PIN <literal>CHV2</literal>.
											The unblock code and new PIN value are prompted by pinpad.
									</para></listitem>
								</varlistentry>
							</variablelist>
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>update_binary</command>
						<replaceable>file-id</replaceable>
						<replaceable>offs</replaceable>
						<replaceable>data</replaceable>
					</term>
					<listitem>
						<para>
							Binary update of the file specified by
							<replaceable>file-id</replaceable> with the literal data
							<replaceable>data</replaceable> starting from offset specified
							by <replaceable>offs</replaceable>.
						</para>
						<para>
							<replaceable>data</replaceable> can be supplied as a sequence
							of hexadecimal values or as a string enclosed in double quotes
							(<literal>"..."</literal>).
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>update_record</command>
						<replaceable>file-id</replaceable>
						<replaceable>rec-nr</replaceable>
						<replaceable>rec-offs</replaceable>
						<replaceable>data</replaceable>
					</term>
					<listitem>
						<para>
							Update record specified by <replaceable>rec-nr</replaceable>
							of the file specified by <replaceable>file-id</replaceable>
							with the literal data <replaceable>data</replaceable>
							starting from offset specified by
							<replaceable>rec-offs</replaceable>.
						</para>
						<para>
							<replaceable>data</replaceable> can be supplied as a sequence
							of hexadecimal values or as a string enclosed in double quotes
							(<literal>"..."</literal>).
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>verify</command>
						<replaceable>key-type</replaceable><replaceable>key-id</replaceable>
						<arg choice="opt"><replaceable>key</replaceable></arg>
					</term>
					<listitem>
						<para>
							Present a PIN or key to the card, where
							<replaceable>key-type</replaceable> can be one of
							<literal>CHV</literal>,	<literal>KEY</literal>,
							<literal>AUT</literal> or <literal>PRO</literal>.
							<replaceable>key-id</replaceable> is a number representing
							the key or PIN reference.
							<replaceable>key</replaceable> is the key or PIN to be verified,
							formatted as a colon-separated sequence of hexadecimal values
							or a string enclosed in double quotes (<literal>"..."</literal>).
						</para>
						<para>
							If <replaceable>key</replaceable> is omitted, the exact action
							depends on the card reader's features:
							if the card readers supports PIN input via a pin pad,
							then the PIN will be verified using the card reader's pin pad.
							If the card reader does not support PIN input,
							then the PIN will be asked interactively.
						</para>
						<para>
							Examples:
							<variablelist>
								<varlistentry>
									<term><code>verify CHV2 31:32:33:34:00:00:00:00</code></term>
									<listitem><para>
											Verify <literal>CHV2</literal> using the hex value
											<literal>31:32:33:34:00:00:00:00</literal>
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>verify CHV1 "secret"</code></term>
									<listitem><para>
											Verify <literal>CHV1</literal>
											using the string value <literal>secret</literal>.
									</para></listitem>
								</varlistentry>
								<varlistentry>
									<term><code>verify KEY2</code></term>
									<listitem><para>
											Verify <literal>KEY2</literal>,
											get the value from the card reader's pin pad.
									</para></listitem>
								</varlistentry>
							</variablelist>
						</para>
					</listitem>
				</varlistentry>

				<varlistentry>
					<term>
						<command>sm</command>
						<group choice="req">
							<arg choice="plain"><literal>open</literal></arg>
							<arg choice="plain"><literal>close</literal></arg>
						</group>
					</term>
					<listitem>
						<para>
							Call the card's <literal>open</literal> or
							<literal>close</literal> Secure Messaging handler.
						</para>
					</listitem>
				</varlistentry>

			</variablelist>
		</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>opensc-explorer</command> was written by
		Juha Yrjölä <email>juha.yrjola@iki.fi</email>.</para>
	</refsect1>

</refentry>
