'\" t
.\"     Title: opensc-explorer
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 04/05/2024
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "OPENSC\-EXPLORER" "1" "04/05/2024" "opensc" "OpenSC Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
opensc-explorer \- generic interactive utility for accessing smart card and similar security token functions
.SH "SYNOPSIS"
.HP \w'\fBopensc\-explorer\fR\ 'u
\fBopensc\-explorer\fR [\fIOPTIONS\fR] [\fISCRIPT\fR]
.SH "DESCRIPTION"
.PP
The
\fBopensc\-explorer\fR
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\&.
.PP
If a
\fISCRIPT\fR
is given,
\fBopensc\-explorer\fR
runs in non\-interactive mode, reading the commands from
\fISCRIPT\fR, one command per line\&. If no script is given,
\fBopensc\-explorer\fR
runs in interactive mode, reading commands from standard input\&.
.SH "OPTIONS"
.PP
The following are the command\-line options for
\fBopensc\-explorer\fR\&. There are additional interactive commands available once it is running\&.
.PP
\fB\-\-card\-driver\fR \fIdriver\fR, \fB\-c\fR \fIdriver\fR
.RS 4
Use the given card driver\&. The default is to auto\-detect the correct card driver\&. The literal value
?
lists all available card drivers and terminates
\fBopensc\-explorer\fR\&.
.RE
.PP
\fB\-\-mf\fR \fIpath\fR, \fB\-m\fR \fIpath\fR
.RS 4
Select the file referenced by the given path on startup\&. The default is the path to the standard master file,
3F00\&. If
\fIpath\fR
is empty (e\&.g\&.
\fBopensc\-explorer \-\-mf ""\fR), then no file is explicitly selected\&.
.RE
.PP
\fB\-\-reader\fR \fIarg\fR, \fB\-r\fR \fIarg\fR
.RS 4
Number of the reader to use\&. By default, the first reader with a present card is used\&. If
\fIarg\fR
is an ATR, the reader with a matching card will be chosen\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Cause
\fBopensc\-explorer\fR
to be more verbose\&. Specify this flag several times to enable debug output in the opensc library\&.
.RE
.PP
\fB\-\-wait\fR, \fB\-w\fR
.RS 4
Wait for a card to be inserted\&.
.RE
.SH "COMMANDS"
.PP
\fBopensc\-explorer\fR
supports commands with arguments at its interactive prompt or in script files passed via the command line parameter
\fISCRIPT\fR\&.
.PP
Similar to a command shell like e\&.g\&.
bash, 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\&.
.PP
The following commands are supported:
.PP
\fB#\fR ...
.RS 4
Treat line as a comment\&. Ignore anything until the end of the line introduced by
#\&.
.RE
.PP
\fBapdu\fR \fIdata\fR...
.RS 4
Send a custom APDU command to the card\&.
\fIdata\fR
is a series of sequences of hexadecimal values and strings enclosed in double quotes ("\&.\&.\&.")\&.
.RE
.PP
\fBasn1\fR \fIfile\-id\fR [\fIrec\-no\fR] [\fIoffs\fR]
.RS 4
Parse and print the ASN\&.1 encoded content of the working EF specified by
\fIfile\-id\fR\&. If the optional parameter
\fIrec\-no\fR
is given and the file is a record\-oriented EF, parse and print only the record indicated by this parameter\&. If the optional parameter
\fIoffs\fR
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
0\&.
.RE
.PP
\fBcat\fR [\fIfile\-id\fR | sfi:\fIshort\-id\fR] [\fIrec\-no\fR]
.RS 4
Print the contents of the working EF specified by
\fIfile\-id\fR
or the short file id
\fIshort\-id\fR\&. If the optional second parameter
\fIrec\-no\fR
is given, only print the record indicated by this parameter\&. If no argument is given, print the the contents of the currently selected EF\&.
.RE
.PP
\fBcd\fR {\&.\&. | \fIfile\-id\fR | aid:\fIDF\-name\fR}
.RS 4
Change to another DF specified by the argument passed\&. If the argument given is
\&.\&., then move up one level in the file system hierarchy\&. If it is a
\fIfile\-id\fR, which must be a DF directly beneath the current DF, then change to that DF\&. If it is an application identifier given as
aid:\fIDF\-name\fR, then jump to the MF of the application denoted by
\fIDF\-name\fR\&.
.RE
.PP
\fBchange\fR CHV\fIpin\-ref\fR [[\fIold\-pin\fR]\ \fInew\-pin\fR]
.RS 4
Change the PIN specified by
\fIpin\-ref\fR
from the value given by
\fIold\-pin\fR
and change its value to
\fInew\-pin\fR\&.
.sp
\fIold\-pin\fR
and
\fInew\-pin\fR
can be sequences of hexadecimal values, strings enclosed in double quotes ("\&.\&.\&."), empty (""), or absent\&. If absent, the values are read from the card reader\*(Aqs pin pad\&.
.sp
Examples:
.PP
change CHV2 00:00:00:00:00:00 "foobar"
.RS 4
Change PIN
CHV2
to the new value
foobar, giving the old value
00:00:00:00:00:00\&.
.RE
.PP
change CHV2 "foobar"
.RS 4
Set PIN
CHV2
to the new value
foobar\&.
.RE
.PP
change CHV2
.RS 4
Change PIN
CHV2
using the card reader\*(Aqs pinpad\&.
.RE
.sp
.RE
.PP
\fBcreate\fR \fIfile\-id\fR \fIsize\fR
.RS 4
Create a new EF\&.
\fIfile\-id\fR
specifies the numeric id, and
\fIsize\fR
the size of the EF to create\&.
.RE
.PP
\fBdebug\fR [\fIlevel\fR]
.RS 4
Set OpenSC debug level to
\fIlevel\fR\&.
.sp
If
\fIlevel\fR
is omitted, show the current debug level\&.
.RE
.PP
\fBdelete\fR \fIfile\-id\fR
.RS 4
Remove the EF or DF specified by
\fIfile\-id\fR\&.
.RE
.PP
\fBdo_get\fR \fIhex\-tag\fR [\fIoutput\fR]
.RS 4
Copy the contents of the card\*(Aqs data object (DO) specified by
\fIhex\-tag\fR
to the local host computer\*(Aqs file named
\fIoutput\fR\&.
.sp
If
\fIoutput\fR
is not given, the contents of
\fIhex\-tag\fR
will be displayed as hex\-dump\&.
.RE
.PP
\fBdo_put\fR \fIhex\-tag\fR \fIdata\fR
.RS 4
Change the contents of the card\*(Aqs data object (DO) specified by
\fIhex\-tag\fR
to
\fIdata\fR\&.
.sp
\fIdata\fR
is either a sequence of hexadecimal values or a string enclosed in double quotes ("\&.\&.\&.")\&.
.RE
.PP
\fBecho\fR \fIstring\fR...
.RS 4
Print the
\fIstring\fRs given\&.
.RE
.PP
\fBerase\fR
.RS 4
Erase the card, if the card supports it\&.
.RE
.PP
\fBget\fR \fIfile\-id\fR [\fIoutput\fR]
.RS 4
Copy an EF to a local file\&. The local file is specified by
\fIoutput\fR
while the card file is specified by
\fIfile\-id\fR\&.
.sp
If
\fIoutput\fR
is omitted, the name of the output file will be derived from the full card path to
\fIfile\-id\fR\&.
.RE
.PP
\fBget_record\fR \fIfile\-id\fR \fIrec\-no\fR [\fIoutput\fR]
.RS 4
Copy a record of a record\-oriented EF to a local file\&. The local file is specified by
\fIoutput\fR
while the card file and the record are specified by
\fIfile\-id\fR
and
\fIrec\-no\fR,
.sp
If
\fIoutput\fR
is omitted, the name of the output file will be derived from the full card path to
\fIfile\-id\fR\&. and the
\fIrec\-no\fR\&.
.RE
.PP
\fBhelp\fR [\fIpattern\fR]
.RS 4
Display the list of available commands, their options and parameters together with a short help text\&. If
\fIpattern\fR
is given, the commands shown are limited to those matching
\fIpattern\fR\&.
.RE
.PP
\fBinfo\fR [\fIfile\-id\fR]
.RS 4
Display attributes of a file specified by
\fIfile\-id\fR\&. If
\fIfile\-id\fR
is not supplied, the attributes of the current file are displayed\&.
.RE
.PP
\fBls\fR [\fIpattern\fR...]
.RS 4
List files in the current DF\&. If no
\fIpattern\fR
is given, then all files are listed\&. If one or more
\fIpattern\fRs are given, only files matching at least one
\fIpattern\fR
are listed\&.
.RE
.PP
\fBfind\fR [\fIstart\-id\fR\ [\fIend\-id\fR]]
.RS 4
Find all files in the current DF\&. Files are found by selecting all file identifiers in the range from
\fIstart\-fid\fR
to
\fIend\-fid\fR\&.
.sp
If not given, the default value for
\fIstart\-fid\fR
is
0000, while the default for
\fIend\-fid\fR
is
FFFF\&.
.RE
.PP
\fBfind_tags\fR [\fIstart\-tag\fR\ [\fIend\-tag\fR]]
.RS 4
Find all tags of data objects in the current context\&. Tags are found by using GET DATA in the range from from
\fIstart\-tag\fR
to
\fIend\-tag\fR\&.
.sp
If not given, the default value for
\fIstart\-tag\fR
is
0000, while the default for
\fIend\-tag\fR
is
FFFF\&.
.RE
.PP
\fBmkdir\fR \fIfile\-id\fR \fIsize\fR
.RS 4
Create a DF\&.
\fIfile\-id\fR
specifies the numeric id, and
\fIsize\fR
the size of the DF to create\&.
.RE
.PP
\fBpin_info\fR \fIkey\-type\fR\fIkey\-id\fR
.RS 4
Get information on a PIN or key from the card, where
\fIkey\-type\fR
can be one of
CHV,
KEY,
AUT
or
PRO\&.
\fIkey\-id\fR
is a number representing the key or PIN reference\&.
.RE
.PP
\fBput\fR \fIfile\-id\fR \fIinput\fR
.RS 4
Copy a local file to the card\&. The local file is specified by
\fIinput\fR
while the card file is specified by
\fIfile\-id\fR\&.
.RE
.PP
\fBquit\fR
.RS 4
Exit the program\&.
.RE
.PP
\fBrandom\fR \fIcount\fR [\fIoutput\-file\fR]
.RS 4
Generate
\fIcount\fR
bytes of random data\&. If
\fIoutput\-file\fR
is given, write the data to the host computer\*(Aqs file denoted by it, otherwise show the data as hex dump\&.
.RE
.PP
\fBrm\fR \fIfile\-id\fR
.RS 4
Remove the EF or DF specified by
\fIfile\-id\fR\&.
.RE
.PP
\fBunblock\fR CHV\fIpin\-ref\fR [\fIpuk\fR\ [\fInew\-pin\fR]]
.RS 4
Unblock the PIN denoted by
\fIpin\-ref\fR
using the PUK
\fIpuk\fR, and potentially change its value to
\fInew\-pin\fR\&.
.sp
\fIpuk\fR
and
\fInew\-pin\fR
can be sequences of hexadecimal values, strings enclosed in double quotes ("\&.\&.\&."), empty (""), or absent\&. If absent, the values are read from the card reader\*(Aqs pin pad\&.
.sp
Examples:
.PP
unblock CHV2 00:00:00:00:00:00 "foobar"
.RS 4
Unblock PIN
CHV2
using PUK
00:00:00:00:00:00
and set it to the new value
foobar\&.
.RE
.PP
unblock CHV2 00:00:00:00:00:00 ""
.RS 4
Unblock PIN
CHV2
using PUK
00:00:00:00:00:00
keeping the old value\&.
.RE
.PP
unblock CHV2 "" "foobar"
.RS 4
Set new value of PIN
CHV2
to
foobar\&.
.RE
.PP
unblock CHV2 00:00:00:00:00:00
.RS 4
Unblock PIN
CHV2
using PUK
00:00:00:00:00:00\&. The new PIN value is prompted by pinpad\&.
.RE
.PP
unblock CHV2 ""
.RS 4
Set PIN
CHV2\&. The new PIN value is prompted by pinpad\&.
.RE
.PP
unblock CHV2
.RS 4
Unblock PIN
CHV2\&. The unblock code and new PIN value are prompted by pinpad\&.
.RE
.sp
.RE
.PP
\fBupdate_binary\fR \fIfile\-id\fR \fIoffs\fR \fIdata\fR
.RS 4
Binary update of the file specified by
\fIfile\-id\fR
with the literal data
\fIdata\fR
starting from offset specified by
\fIoffs\fR\&.
.sp
\fIdata\fR
can be supplied as a sequence of hexadecimal values or as a string enclosed in double quotes ("\&.\&.\&.")\&.
.RE
.PP
\fBupdate_record\fR \fIfile\-id\fR \fIrec\-nr\fR \fIrec\-offs\fR \fIdata\fR
.RS 4
Update record specified by
\fIrec\-nr\fR
of the file specified by
\fIfile\-id\fR
with the literal data
\fIdata\fR
starting from offset specified by
\fIrec\-offs\fR\&.
.sp
\fIdata\fR
can be supplied as a sequence of hexadecimal values or as a string enclosed in double quotes ("\&.\&.\&.")\&.
.RE
.PP
\fBverify\fR \fIkey\-type\fR\fIkey\-id\fR [\fIkey\fR]
.RS 4
Present a PIN or key to the card, where
\fIkey\-type\fR
can be one of
CHV,
KEY,
AUT
or
PRO\&.
\fIkey\-id\fR
is a number representing the key or PIN reference\&.
\fIkey\fR
is the key or PIN to be verified, formatted as a colon\-separated sequence of hexadecimal values or a string enclosed in double quotes ("\&.\&.\&.")\&.
.sp
If
\fIkey\fR
is omitted, the exact action depends on the card reader\*(Aqs features: if the card readers supports PIN input via a pin pad, then the PIN will be verified using the card reader\*(Aqs pin pad\&. If the card reader does not support PIN input, then the PIN will be asked interactively\&.
.sp
Examples:
.PP
verify CHV2 31:32:33:34:00:00:00:00
.RS 4
Verify
CHV2
using the hex value
31:32:33:34:00:00:00:00
.RE
.PP
verify CHV1 "secret"
.RS 4
Verify
CHV1
using the string value
secret\&.
.RE
.PP
verify KEY2
.RS 4
Verify
KEY2, get the value from the card reader\*(Aqs pin pad\&.
.RE
.sp
.RE
.PP
\fBsm\fR {open | close}
.RS 4
Call the card\*(Aqs
open
or
close
Secure Messaging handler\&.
.RE
.SH "SEE ALSO"
.PP
\fBopensc-tool\fR(1)
.SH "AUTHORS"
.PP
\fBopensc\-explorer\fR
was written by Juha Yrjölä
<juha\&.yrjola@iki\&.fi>\&.