'\" t
.\"     Title: westcos-tool
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/10/2024
.\"    Manual: OpenSC Tools
.\"    Source: opensc
.\"  Language: English
.\"
.TH "WESTCOS\-TOOL" "1" "03/10/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"
westcos-tool \- utility for manipulating data structures on westcos smart cards
.SH "SYNOPSIS"
.HP \w'\fBwestcos\-tool\fR\ 'u
\fBwestcos\-tool\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.PP
The
\fBwestcos\-tool\fR
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\&.
.SH "OPTIONS"
.PP
.PP
\fB\-\-change\-pin\fR, \fB\-n\fR
.RS 4
Changes a PIN stored on the card\&. User authentication is required for this operation\&.
.RE
.PP
\fB\-\-certificate\fR \fIfile\fR, \fB\-t\fR \fIfile\fR
.RS 4
Write certificate file
\fIfile\fR
in PEM format to the card\&. User authentication is required for this operation\&.
.RE
.PP
\fB\-\-finalize\fR, \fB\-f\fR
.RS 4
Finalize the card\&. Once finalized the default key is invalidated, so PIN and PUK cannot be changed anymore without user authentication\&.
.sp
Warning, un\-finalized cards are insecure because the PIN can be changed without user authentication (knowledge of default key is enough)\&.
.RE
.PP
\fB\-\-generate\-key\fR, \fB\-g\fR
.RS 4
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
\fB\-i\fR)\&. By default the key length is 2048 bits\&. User authentication is required for this operation\&.
.RE
.PP
\fB\-\-help\fR, \fB\-h\fR
.RS 4
Print help message on screen\&.
.RE
.PP
\fB\-\-install\-pin\fR, \fB\-i\fR
.RS 4
Install PIN file in on the card\&. You must provide a PIN value with
\fB\-x\fR\&.
.RE
.PP
\fB\-\-key\-length\fR \fIlength\fR, \fB\-l\fR \fIlength\fR
.RS 4
Change the length of private key\&. Use with
\fB\-g\fR\&.
.RE
.PP
\fB\-\-overwrite\-key\fR, \fB\-o\fR
.RS 4
Overwrite the key if there is already a key on the card\&.
.RE
.PP
\fB\-\-pin\-value\fR \fIpin\fR, \fB\-x\fR \fIpin\fR \fB\-\-puk\-value\fR \fIpuk\fR, \fB\-y\fR \fIpuk\fR
.RS 4
These options can be used to specify the PIN/PUK values on the command line\&. If the value is set to
env:\fIVARIABLE\fR, the value of the specified environment variable is used\&. By default, the code is prompted on the command line if needed\&.
.sp
Note that on most operation systems, any user can display the command line of any process on the system using utilities such as
\fBps(1)\fR\&. Therefore, you should prefer passing the codes via an environment variable on an unsecured system\&.
.RE
.PP
\fB\-\-read\-file\fR \fIfilename\fR, \fB\-j\fR \fIfilename\fR
.RS 4
Read the file
\fIfilename\fR
from the card\&. The file is written on disk with name
\fIfilename\fR\&. User authentication is required for this operation\&.
.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\-\-unblock\-pin\fR, \fB\-u\fR
.RS 4
Unblocks a PIN stored on the card\&. Knowledge of the PIN Unblock Key (PUK) is required for this operation\&.
.RE
.PP
\fB\-\-verbose\fR \fB\-v\fR
.RS 4
Causes
\fBwestcos\-tool\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
.PP
\fB\-\-write\-file\fR \fIfilename\fR, \fB\-k\fR \fIfilename\fR
.RS 4
Put the file with name
\fIfilename\fR
from disk to card\&. On the card the file is written in
\fIfilename\fR\&. User authentication is required for this operation\&.
.RE
.SH "AUTHORS"
.PP
\fBwestcos\-tool\fR
was written by Francois Leblanc
<francois\&.leblanc@cev\-sa\&.com>\&.