'\" t
.\"     Title: opensc-explorer
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/30/2018
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "OPENSC\-EXPLORER" "1" "09/30/2018" "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 interactively to perform miscellaneous operations such as exploring the contents of or sending arbitrary APDU commands to a smart card or similar security token\&.
.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 auto\-detected\&.
.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 \fInum\fR, \fB\-r\fR \fInum\fR
.RS 4
Use the given reader number\&. The default is 0, the first reader in the system\&.
.RE
.PP
\fB\-\-verbose\fR, \fB\-v\fR
.RS 4
Causes
\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
The following commands are supported at
\fBopensc\-explorer\fR\*(Aqs interactive prompt or in script files passed via the command line parameter
\fISCRIPT\fR\&.
.PP
\fBapdu\fR \fIhex\-data\fR
.RS 4
Send a custom APDU command
\fIhex\-data\fR\&.
.RE
.PP
\fBasn1\fR \fIfile\-id\fR
.RS 4
Parse and print the ASN\&.1 encoded content of the file specified by
\fIfile\-id\fR\&.
.RE
.PP
\fBcat\fR [\fIfile\-id\fR | sfi:\fIshort\-id\fR]
.RS 4
Print the contents of the currently selected EF or the contents of a file specified by
\fIfile\-id\fR
or the short file id
\fIshort\-id\fR\&.
.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
\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 a PIN, where
\fIpin\-ref\fR
is the PIN reference\&.
.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 id number and
\fIsize\fR
is the size of the new file\&.
.RE
.PP
\fBdebug\fR [\fIlevel\fR]
.RS 4
Set OpenSC debug level to
\fIlevel\fR\&.
.sp
If
\fIlevel\fR
is omitted the current debug level will be shown\&.
.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 internal card\*(Aqs \*(Aqtagged\*(Aq data into the local file\&.
.sp
The local file is specified by
\fIoutput\fR
while the tag of the card\*(Aqs data is specified by
\fIhex\-tag\fR\&.
.sp
If
\fIoutput\fR
is omitted, the name of the output file will be derived from
\fIhex\-tag\fR\&.
.RE
.PP
\fBdo_put\fR \fIhex\-tag\fR \fIinput\fR
.RS 4
Update internal card\*(Aqs \*(Aqtagged\*(Aq data\&.
.sp
\fIhex\-tag\fR
is the tag of the card\*(Aqs data\&.
\fIinput\fR
is the filename of the source file or the literal data presented as a sequence of hexadecimal values or
"
enclosed string\&.
.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
\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 printed\&.
.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 ore 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
(by default from 0000 to 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
\fIstart\-tag\fR
to
\fIend\-tag\fR
(by default from 0000 to FFFF)\&.
.RE
.PP
\fBmkdir\fR \fIfile\-id\fR \fIsize\fR
.RS 4
Create a DF\&.
\fIfile\-id\fR
specifies the id number and
\fIsize\fR
is the size of the new file\&.
.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
.RS 4
Generate random sequence of
\fIcount\fR
bytes\&.
.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 set potentially change its value to
\fInew pin\fR\&.
.sp
PUK and PIN values can be a sequence of hexadecimal values,
"\-enclosed strings, empty (""), or absent\&. If they are 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 sequencer of the hex values or as a
"
enclosed string\&.
.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 the hex values or as a
"
enclosed string\&.
.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 list of hex values or a
"
enclosed string\&.
.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 CHV0 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 \fI[open]\fR|\fI[close]\fR
.RS 4
Calls the card\*(Aqs
\fIopen\fR
or
\fIclose\fR
Secure Messaging handler\&.
.RE
.SH "SEE ALSO"
.PP
\fBopensc-tool\fR(1)