diff --git a/.gitignore b/.gitignore index 2e106fa3..8d91981e 100644 --- a/.gitignore +++ b/.gitignore @@ -49,7 +49,6 @@ tags *.gz *.bz2 *.[0-9] -*.html *.gif *.css *.out @@ -77,6 +76,11 @@ doc/tools/pkcs15-tool doc/tools/sc-hsm-tool doc/tools/westcos-tool doc/tools/dnie-tool +doc/tools/egk-tool +doc/tools/npa-tool +doc/tools/opensc-asn1 +doc/tools/opensc-notify +doc/files/opensc.conf.5.xml etc/opensc.conf.win etc/opensc.conf diff --git a/configure.ac b/configure.ac index 03517a73..c655e764 100644 --- a/configure.ac +++ b/configure.ac @@ -1057,6 +1057,7 @@ AC_CONFIG_FILES([ Makefile doc/Makefile doc/tools/Makefile + doc/files/Makefile etc/Makefile src/Makefile src/common/Makefile diff --git a/doc/Makefile.am b/doc/Makefile.am index d572f429..754720a9 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ MAINTAINERCLEANFILES = $(srcdir)/Makefile.in -SUBDIRS = tools +SUBDIRS = tools files dist_noinst_SCRIPTS = html.xsl man.xsl dist_noinst_DATA = api.css diff --git a/doc/files/Makefile.am b/doc/files/Makefile.am new file mode 100644 index 00000000..fe245247 --- /dev/null +++ b/doc/files/Makefile.am @@ -0,0 +1,32 @@ +MAINTAINERCLEANFILES = $(srcdir)/Makefile.in + +dist_noinst_DATA = pkcs15-profile.5.xml opensc.conf.5.xml.in +if ENABLE_DOC +html_DATA = files.html +endif + +if ENABLE_MAN +man5_MANS = pkcs15-profile.5 opensc.conf.5 +endif + +opensc.conf.5: $(srcdir)/opensc.conf.5.xml.in + sed \ + -e 's|@sysconfdir[@]|$(sysconfdir)|g' \ + -e 's|@docdir[@]|$(docdir)|g' \ + -e 's|@libdir[@]|$(libdir)|g' \ + -e 's|@DYN_LIB_EXT[@]|$(DYN_LIB_EXT)|g' \ + -e 's|@DEFAULT_PCSC_PROVIDER[@]|$(DEFAULT_PCSC_PROVIDER)|g' \ + -e 's|@PROFILE_DIR_DEFAULT[@]|$(PROFILE_DIR_DEFAULT)|g' \ + -e 's|@DEFAULT_SM_MODULE[@]|$(DEFAULT_SM_MODULE)|g' \ + < $< > opensc.conf.5.xml + $(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/manpages" --xinclude -o $@ man.xsl opensc.conf.5.xml + +files.html: $(srcdir)/files.xml $(wildcard $(srcdir)/*.5.xml) opensc.conf.5.xml + $(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/html" --xinclude -o $@ html.xsl $< + +%.5: $(srcdir)/%.5.xml + sed -e 's|@pkgdatadir[@]|$(pkgdatadir)|g' < $< \ + | $(XSLTPROC) --nonet --path "$(srcdir)/..:$(xslstylesheetsdir)/manpages" --xinclude -o $@ man.xsl $< + +clean-local: + -rm -rf $(html_DATA) $(man5_MANS) opensc.conf.5.xml diff --git a/doc/files/files.html b/doc/files/files.html new file mode 100644 index 00000000..362535db --- /dev/null +++ b/doc/files/files.html @@ -0,0 +1,1105 @@ +
Table of Contents
opensc.conf — configuration file for OpenSC
+ OpenSC obtains configuration data from the following sources in the following order +
+ command-line options +
+ environment variables +
+ Windows registry (if available) +
+ system-wide configuration file
+ (/home/fm/.local/etc/opensc.conf
)
+
+
+ The configuration file, opensc.conf
, is composed
+ of block
s, which, in general, have the
+ following format:
+
+key
[,name
...] { +block_contents
+} +
+ block_contents
is one or more
+ block_item
s where a
+ block_item
is one of
+
+ # comment string
+
+ key
[, name
...] = value
;
+
+ block
+
+
+ At the root level, opensc.conf
should contain
+ one or more application specific configuration blocks:
+
+appapplication
{ +block_contents
+} +
+ application
+ specifies one of:
+
+ default
: The fall-back configuration block for all applications
+
+ opensc-pkcs11
: Configuration block for the PKCS#11 module (opensc-pkcs11.so
)
+
+ onepin-opensc-pkcs11
: Configuration block for the PKCS#11 one-PIN-module (onepin-opensc-pkcs11.so
)
+
+ cardmod
: Configuration block for Windows' minidriver (opensc-minidriver.dll
)
+
+ tokend
: Configuration block for macOS' tokend (OpenSC.tokend)
+
+ cardos-tool
,
+ cryptoflex-tool
,
+ dnie-tool
,
+ egk-tool
,
+ eidenv
,
+ gids-tool
,
+ iasecc-tool
,
+ netkey-tool
,
+ npa-tool
,
+ openpgp-tool
,
+ opensc-asn1
,
+ opensc-explorer
,
+ opensc-notify
,
+ opensc-tool
,
+ piv-tool
,
+ pkcs11-tool
,
+ pkcs15-crypt
,
+ pkcs15-init
,
+ pkcs15-tool
,
+ sc-hsm-tool
,
+ westcos-tool
:
+ Configuration block for OpenSC tools
+
+
debug = num
;
+
+ Amount of debug info to print (Default:
+ 0
). A greater value means more
+ debug info.
+
+ The environment variable
+ OPENSC_DEBUG
overwrites this
+ setting.
+
debug_file = filename
;
+
+ The file to which debug output will be written
+ (Default: stderr
). Special
+ values stdout
and
+ stderr
are recognized.
+
profile_dir = filename
;
+
+ PKCS#15 initialization/personalization profiles
+ directory for
+ pkcs15-init(1).
+
+ (Default: /home/fm/.local/share/opensc
).
+
+ If this configuration value is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\ProfileDir
is
+ checked.
+
disable_popups = bool
;
+
+ Disable pop-ups of built-in GUI (Default: false
).
+
enable_default_driver = bool
;
+
+ Enable default card driver (Default:
+ false
). Default card driver is
+ explicitly enabled for
+ opensc-explorer(1).
+
+ and
+ opensc-tool(1).
+
+
card_drivers = name
... ;
+
+ Whitelist of card drivers to load at start-up.
+ The special value internal
(the
+ default) will load all statically linked drivers.
+
+ If an unknown (i.e. not internal or old) driver is
+ supplied, a separate configuration configuration
+ block has to be written for the driver. A special
+ value old
will load all
+ statically linked drivers that may be removed in
+ the future.
+
+ The list of supported card driver names can be + retrieved from the output of opensc-tool + --list-drivers. +
+ The environment variable
+ OPENSC_DRIVER
overwrites this
+ setting.
+
ignored_readers = name
... ;
+ + List of readers to ignore (Default: empty). If any + of the comma separated strings listed is matched in + a reader name (case sensitive, partial matching + possible), the reader is ignored by OpenSC. Use + opensc-tool --list-readers to + see all currently connected readers. +
reader_driver name
{
+ block_contents
+ }
+
+
+ Configuration of the smart card reader driver where name
is one of:
+
+ ctapi
: See the section called “Configuration of CT-API Readers”
+
+ pcsc
: See the section called “Configuration of PC/SC Readers”
+
+ openct
: See the section called “Configuration of OpenCT Readers”
+
+ cryptotokenkit
: Configuration block for CryptoTokenKit readers
+
+
+ See the section called “Configuration of Smart Card Reader Driver”. +
card_driver name
{
+ block_contents
+ }
+
+
+ Configuration of the card driver where name
is one of:
+
+ npa
: See the section called “Configuration Options for German ID Card”
+
+ dnie
: See the section called “Configuration Options for DNIe”
+
+ Any other value: Configuration block for an externally loaded card driver +
+
card_atr hexstring
{
+ block_contents
+ }
+
+
+ In addition to the built-in list of known cards in
+ the card driver, you can configure a new card for
+ the driver using the card_atr
+ block.
+
+ For details see the section called “Configuration based on ATR”. +
secure_messaging name
{
+ block_contents
+ }
+
+
+ Configuration options for the secure messaging profile name
:
+
module_name = filename
;
+ + Name of external SM module (Default: libsmm-local.so). +
module_path = filename
;
+ + Directory with external SM module + (Default: /home/fm/.local/lib). +
+ If this configuration value is not
+ found on Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\SmDir
is
+ checked.
+
module_data = value
;
+ + Specific data to tune the module initialization. +
mode = value
;
+ + Secure messaging mode. Known parameters: +
+ transmit
:
+ In this mode the
+ procedure to securize
+ an APDU is called by
+ the OpenSC general APDU
+ transmit procedure. In
+ this mode all APDUs,
+ except the ones
+ filtered by the card
+ specific procedure, are
+ securized.
+
+ acl
:
+ In this mode APDU are
+ securized only if
+ needed by the ACLs of
+ the command to be
+ executed.
+
+
flags = value
;
+ + Secure messaging type specific flags. +
kmc = hexstring
;
+ + Default KMC of the GP Card Manager for the Oberthur's Java cards. +
ifd_serial = hexstring
;
+ keyset[_aid
]_num
_enc =
+ value
;
+ keyset[_aid
]_num
_mac =
+ value
;
+ + Keyset values from IAM profiles of + the Gemalto IAS/ECC cards with an + optional application identifier +
framework name
{
+ block_contents
+ }
+
+
+ Internal configuration options where name
is one of:
+
+ pkcs15
: See the section called “Configuration of PKCS#15 Framework”
+
+ tokend
: See the section called “Configuration of Tokend”
+
+
pkcs11 {
+ block_contents
+ }
+
+ + Parameters for the OpenSC PKCS11 module. +
+ For details see the section called “Configuration of PKCS#11”. +
max_send_size = num
;
+ max_recv_size = num
;
+
+ Limit command and response sizes
+ (Default:
+ max_send_size
+ = 255
,
+ max_recv_size
+ = 256
) . Some
+ Readers don't propagate their
+ transceive capabilities correctly.
+ max_send_size and max_recv_size
+ allow setting the limits manually,
+ for example to enable extended
+ length capabilities.
+
enable_escape bool
;
+
+ Detect reader capabilities with
+ escape commands (wrapped APDUs with
+ CLA=0xFF as defined by PC/SC pt. 3
+ and BSI TR-03119, e.g. for getting
+ the UID, escaped PIN commands and
+ the reader's firmware version,
+ Default: false
)
+
module filename
{
+ ports = nums
;
+ }
+
+ + Load the specified CT-API module with the specified number of ports. +
connect_exclusive = bool
;
+
+ Connect to reader in exclusive mode
+ (Default: false
)?
+ This option has no effect in Windows' minidriver.
+
disconnect_action = action
;
+
+ What to do when disconnecting from
+ a card (SCardDisconnect). Valid
+ values are
+ leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
transaction_end_action = action
;
+
+ What to do at the end of a
+ transaction (SCardEndTransaction).
+ Valid values
+ are leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
reconnect_action = action
;
+
+ What to do when reconnection to a
+ card (SCardReconnect). Valid values
+ are leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
enable_pinpad = bool
;
+
+ Enable pinpad if detected (PC/SC
+ v2.0.2 Part 10, Default:
+ true
)
+
fixed_pinlength = num
;
+
+ Some pinpad readers can only handle
+ one exact length of the PIN.
+ fixed_pinlength
+ sets this value so that OpenSC
+ expands the padding to this length
+ (Default: 0
,
+ i.e. not fixed).
+
provider_library = filename
;
+
+ Use specific PC/SC provider
+ (Default:
+ libpcsclite.so.1
).
+
can = value
;
+ + German ID card requires the CAN to + be verified before QES PIN. This, + however, is not part of the PKCS#15 + profile of the card. So for + verifying the QES PIN we actually + need both. The CAN may be given + here. If the CAN is not given here, + it will be prompted on the command + line or on the reader (depending on + the reader's capabilities). +
st_dv_certificate = filename
;
+ st_certificate = filename
;
+ st_key = filename
;
+ + QES is only possible with a Comfort + Reader (CAT-K), which holds a + cryptographic key to authenticate + itself as signature terminal (ST). + We usually will use the reader's + capability to sign the data. + However, during developement you + may specify soft certificates and + keys for a ST. +
+ An example PKI can be found in the + example data for the + German + ID card emulator +
user_consent_enabled = bool
;
+
+ Configure the warning message when
+ performing a signature operation
+ with the DNIe. Only used if
+ compiled with
+ --enable-dnie-ui
+
user_consent_app = filename
;
+
+ Specify the pinentry application to
+ use if warning is configured to be
+ displayed using pinentry (Default:
+ /usr/bin/pinentry
).
+ Only used if compiled with
+ --enable-dnie-ui
+
+
atrmask = hexstring
;
+ + The mask is logically AND'd with an + card ATR prior to comparison with + the ATR reference value above. + Using this mask allows identifying + and configuring multiple ATRs as + the same card model. +
driver = name
;
+ + When enabled, overrides all + possible settings from the card + drivers built-in card configuration + list. +
name = name
;
+ + Set card name for card drivers that + allows it. +
type = num
;
+
+ Allows setting the exact type of
+ the card internally used by the
+ card driver. Allowed values can be
+ found in the source code of
+ cards.h
.
+
flags = value
... ;
+ + Card flags as an hex value. + Multiple values are OR'd together. + Depending on card driver, this + allows fine-tuning the capabilities + in the card driver for your card. +
+ Optionally, some known parameters + can be specified as strings: +
+ rng
:
+ On-board random number
+ source
+
+ keep_alive
:
+ Request the card driver
+ to send a "keep alive"
+ command before each
+ transaction to make
+ sure that the required
+ applet is still
+ selected.
+
+
pkcs15emu = name
;
+ + When using PKCS#15 emulation, force + the emulation driver for specific + cards. Required for external + drivers, but can be used with + built-in drivers, too. +
force_protocol = value
;
+ + Force protocol selection for + specific cards. Known parameters: +
+ t0
+
+ t1
+
+ raw
+
+
md_read_only = bool
;
+
+ Mark card as read/only card in
+ Minidriver/BaseCSP interface
+ (Default: false
).
+
md_supports_X509_enrollment = bool
;
+
+ Indicate X509 enrollment support at
+ Minidriver/BaseCSP interface
+ (Default: false
).
+
md_guid_as_id = bool
;
+
+ Use the GUID generated for the key
+ as id in the PKCS#15 structure
+ (Default: false
, i.e. auto generated)
+
md_guid_as_label = bool
;
+
+ Use the GUID generated for the key
+ as label in the PKCS#15 structure
+ (Default: false
,
+ i.e. no label set).
+
md_supports_container_key_gen = bool
;
+
+ Card allows generating key pairs on the card (Default: false
).
+
md_supports_container_key_import = bool
;
+
+ Card allows importing private keys
+ (Default: false
).
+
md_pinpad_dlg_title = value
;
+
+ Window title of the PIN pad dialog
+ (Default: "Windows
+ Security"
).
+
md_pinpad_dlg_icon = filename
;
+
+ Filename of the icon for the PIN
+ pad dialog; use
+ ""
for no icon
+ (Default: Built-in smart card icon).
+
md_pinpad_dlg_main = value
;
+
+ Main instruction of the PIN pad
+ dialog (Default: "OpenSC
+ Smart Card Provider"
).
+
md_pinpad_dlg_content_user = value
;
+
+ Content of the PIN pad dialog for
+ role "user" (Default:
+ "Please verify your
+ fingerprint or PIN on the
+ card."
).
+
md_pinpad_dlg_content_user_sign = value
;
+
+ Content of the PIN pad dialog for
+ role "user+signature" (Default:
+ "Please verify your
+ fingerprint or PIN for the
+ digital signature PIN on the
+ card."
).
+
md_pinpad_dlg_content_user_sign = name
;
+
+ Content of the PIN pad dialog for
+ role "user+signature" (Default:
+ "Please verify your
+ fingerprint or PIN for the
+ digital signature PIN on the
+ card."
).
+
md_pinpad_dlg_content_admin = value
;
+
+ Content of the PIN pad dialog for
+ role "admin" (Default:
+ "Please enter your PIN to
+ unblock the user PIN on the
+ PINPAD."
)
+
md_pinpad_dlg_content_cancel = value
;
+ + Content of the PIN pad dialog after + pressing "Cancel", when the reader + doesn't respond to SCardCancel +
md_pinpad_dlg_expanded = value
;
+
+ Expanded information of the PIN pad
+ dialog (Default: "This
+ window will be closed
+ automatically after the PIN has
+ been submitted on the PINPAD
+ (timeout typically after 30
+ seconds)."
)
+
md_pinpad_dlg_expanded_cancel = value
;
+
+ Expanded information of the PIN pad
+ dialog after pressing "Cancel",
+ when the reader doesn't respond to
+ SCardCancel (Default:
+ "Some readers only support
+ canceling the operation on the
+ PIN pad. Press Cancel or remove
+ the card."
).
+
md_pinpad_dlg_enable_cancel = bool
;
+
+ Allow the user to cancel the PIN
+ pad dialog (Default:
+ false
)
+
md_pinpad_dlg_timeout = num
;
+
+ Time in seconds for the progress
+ bar of the PIN pad dialog to tick.
+ 0
removes the
+ progress bar (Default:
+ 30
).
+
notify_card_inserted = value
;
+ notify_card_inserted_text = value
;
+
+ Notification title and text when
+ card was inserted (Default:
+ "Smart card
+ detected"
, ATR of
+ the card).
+
notify_card_removed = value
;
+ notify_card_removed_text = value
;
+
+ Notification title and text when
+ card was removed (Default:
+ "Smart card
+ removed"
, name of
+ smart card reader).
+
notify_pin_good = value
;
+ notify_pin_good_text = value
;
+
+ Notification title and text when
+ PIN was verified (Default:
+ "PIN verified"
,
+ "Smart card is
+ unlocked"
).
+
notify_pin_bad = value
;
+ notify_pin_bad_text = value
;
+
+ Notification title and text when
+ PIN was wrong (Default:
+ "PIN not
+ verified"
,
+ "Smart card is
+ locked"
).
+
+
use_file_caching = bool
;
+
+ Whether to cache the card's files (e.g.
+ certificates) on disk in
+ file_cache_dir
(Default:
+ false
).
+
+ If caching is done by a system process, the + cached files may be placed inaccessible from + the user account. Use a globally readable and + writable location if you wish to share the + cached information. Note that the cached files + may contain personal data such as name and mail + address. +
file_cache_dir = filename
;
+ + Where to cache the card's files. The default values are: +
+
(Unix)
+ HOME
/.eid/cache/
+
(Windows)
+ USERPROFILE
\.eid-cache\
+
+ If caching is done by a system process, the + cached files may be placed inaccessible from + a user account. Use a globally readable and + writable location if you wish to share the + cached information. Note that the cached files + may contain personal data such as name and mail + address. +
use_pin_caching = bool
;
+
+ Use PIN caching (Default: true
)?
+
pin_cache_counter = num
;
+
+ How many times to use a PIN from cache before
+ re-authenticating it (Default:
+ 10
)?
+
pin_cache_ignore_user_consent = bool
;
+
+ Older PKCS#11 applications not supporting
+ CKA_ALWAYS_AUTHENTICATE
may
+ need to set this to get signatures to work with
+ some cards (Default: false
).
+
enable_pkcs15_emulation = bool
;
+
+ Enable pkcs15 emulation (Default:
+ true
).
+
try_emulation_first = bool
;
+
+ Prefer pkcs15 emulation code before the normal
+ pkcs15 processing (Default:
+ no
). Some cards work in
+ emu-only mode, and do not depend on this
+ option.
+
enable_builtin_emulation = bool
;
+
+ Enable builtin emulators (Default:
+ true
).
+
builtin_emulators = emulators
;
+
+ List of the builtin pkcs15 emulators to test
+ (Default: esteid, openpgp, tcos,
+ starcert, itacns, infocamere, postecert,
+ actalis, atrust-acos, gemsafeGPK,
+ gemsafeV1, tccardos, PIV-II
)
+
pkcs11_enable_InitToken = bool
;
+
+ Enable initialization and card recognition
+ (Default: false
).
+
emulate name
{
+ block_contents
+ }
+
+
+ Configuration options for a PKCS#15 emulator
+ where name
is a
+ short name for an external card driver.
+
module = filename
;
+ + For pkcs15 emulators loaded from an + external shared library/DLL, you need to + specify the path name of the module and + customize the card_atr example above + correctly. +
function = name
;
+
+ Get the init function name of the
+ emulator (Default:
+ sc_pkcs15_init_func_ex
)
+
application hexstring
{
+ block_contents
+ }
+
+
+ Configuration of the on-card-application where
+ hexstring
is the
+ application identifier (AID).
+
type = name
;
+
+ Type of application where
+ name
is one
+ of:
+
+ generic
+
+ protected
+
+
+ Used to distinguish the common access + application and application for which + authentication to perform some + operation cannot be obtained with the + common procedures (ex. object creation + protected by secure messaging). Used + by PKCS#11 module configured to expose + restricted number of slots. (for ex. + configured to expose only User PIN + slot, User and Sign PINs slots, ...) +
model = name
;
+ disable = bool
;
+
+ Do not expose application in PKCS#15
+ framework (Default:
+ false
)
+
score = num
;
+
+ Score for OpenSC.tokend
+ (Default: 300
). The tokend with
+ the highest score shall be used.
+
ignore_private_certificate = bool
;
+
+ Tokend ignore to read PIN protected certificate
+ that is set
+ SC_PKCS15_CO_FLAG_PRIVATE
flag
+ (Default: true
).
+
max_virtual_slots = num
;
+
+ Maximum Number of virtual slots (Default:
+ 16
). If there are more slots
+ than defined here, the remaining slots will be
+ hidden from PKCS#11.
+
slots_per_card = num
;
+
+ Maximum number of slots per smart card (Default:
+ 4
). If the card has fewer keys
+ than defined here, the remaining number of slots
+ will be empty.
+
lock_login = bool
;
+
+ By default, the OpenSC PKCS#11 module will not lock
+ your card once you authenticate to the card via
+ C_Login
(Default:
+ false
).
+
+ Thus the other users or other applications is not
+ prevented from connecting to the card and perform
+ crypto operations (which may be possible because
+ you have already authenticated with the card). This
+ setting is not very secure.
+
+ Also, if your card is not locked, you can enconter + problems due to limitation of the OpenSC framework, + that still is not thoroughly tested in the multi + threads environment. +
+ Your settings will be more secure if you choose to
+ lock your card. Nevertheless this behavior is a
+ known violation of PKCS#11 specification. Now once
+ one application has started using your card with
+ C_Login
, no other application
+ can use it, until the first is done and calls
+ C_Logout
or
+ C_Finalize
. In the case of many
+ PKCS#11 application this does not happen until you
+ exit the application.
+
+ Thus it is impossible to use several smart card + aware applications at the same time, e.g. you + cannot run both Firefox + and Thunderbird at the + same time, if both are configured to use your smart + card. +
atomic = bool
;
+
+ By default, interacting with the OpenSC PKCS#11
+ module may change the state of the token, e.g.
+ whether a user is logged in or not (Default:
+ false
).
+
+ Thus other users or other applications may change + or use the state of the token unknowingly. Other + applications may create signatures abusing an + existing login or they may logout unnoticed. +
+ With this setting enabled the login state of the
+ token is tracked and cached (including the PIN).
+ Every transaction is preceded by restoring the
+ login state. After every transaction a logout is
+ performed. This setting by default also enables
+ lock_login
to disable access for
+ other applications during the atomic transactions.
+
+ Please note that any PIN-pad should be disabled
+ (see enable_pinpad
), because the
+ user would have to input his PIN for every
+ transaction.
+
init_sloppy = bool
;
+
+ With this setting disabled, the OpenSC PKCS#11
+ module will initialize the slots available when the
+ application calls C_GetSlotList
.
+ With this setting enabled, the slots will also get
+ initialized when C_GetSlotInfo
+ is called (Default: true
).
+
+ This setting is a workaround for
+ Java which does not call
+ C_GetSlotList
when configured
+ with a static slot
instead of
+ slotListIndex
.
+
user_pin_unblock_style = mode
;
+
+ User PIN unblock style mode
+ is one of:
+
+ none
(Default): PIN
+ unblock is not possible with PKCS#11 API
+
+ set_pin_in_unlogged_session
:
+ C_SetPIN
in unlogged
+ session: PUK is passed as the
+ OldPin
argument of the
+ C_SetPIN
call.
+
+ set_pin_in_specific_context
:
+ C_SetPIN
in the
+ CKU_SPECIFIC_CONTEXT
+ logged session: PUK is passed as the
+ OldPin
argument of the
+ C_SetPIN
call.
+
+ init_pin_in_so_session
:
+ C_InitPIN
in
+ CKU_SO
logged session:
+ User PIN 'UNBLOCK' is protected by SOPIN.
+ (PUK == SOPIN).
+
+
create_puk_slot = bool
;
+
+ Create slot for unblocking PIN with PUK (Default:
+ false
). This way PKCS#11 API can
+ be used to login with PUK and change a PIN. May
+ cause problems with some applications like
+ Firefox and
+ Thunderbird.
+
create_slots_for_pins = mode
... ;
+
+ Symbolic names of PINs for which slots are created
+ where mode
is a list of:
+
+ all
(Default): All
+ non-SO-PIN, non-unblocking PINs
+
+ user
: The first
+ global or first local PIN
+
+ sign
: The second PIN
+ (first local, second global or second
+ local)
+
+
+ Card can contain more then one PINs or more then + one on-card application with its own PINs. + Normally, to access all of them with the PKCS#11 + API a slot has to be created for all of them. Many + slots could be annoying for some of widely used + application, like FireFox. This configuration + parameter allows to select the PIN(s) for which + PKCS#11 slot will be created. +
+ Only PINs initialised, non-SO-PIN, non-unblocking + are associated with symbolic name. +
+ For the module to simulate the opensc-onepin module
+ behavior the following option
+ create_slots_for_pins = "user";
+
OPENSC_CONF
+ + Filename for a user defined configuration file +
+ If this environment variable is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\ConfigFile
is
+ checked.
+
OPENSC_DEBUG
+
+ See
+ debug =
+
+ num
;
OPENSC_DRIVER
+
+ See
+ card_drivers =
+
+ name
... ;
CARDMOD_LOW_LEVEL_DEBUG
+
+ Write minidriver debug information to
+ C:\tmp\md.log
, if set to
+ 1
.
+
+ If this environment variable is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\MiniDriverDebug
is
+ checked.
+
PIV_EXT_AUTH_KEY
,
+ PIV_9A_KEY
,
+ PIV_9C_KEY
,
+ PIV_9D_KEY
,
+ PIV_9E_KEY
+ + PIV configuration during initialization with + piv-tool. +
pkcs15-profile — format of profile for pkcs15-init
+ The pkcs15-init utility for PKCS #15 smart card + personalization is controlled via profiles. When starting, it will read two + such profiles at the moment, a generic application profile, and a card + specific profile. The generic profile must be specified on the command line, + while the card-specific file is selected based on the type of card detected. +
+ The generic application profile defines general information about the card
+ layout, such as the path of the application DF, various PKCS #15 files within
+ that directory, and the access conditions on these files. It also defines
+ general information about PIN, key and certificate objects. Currently, there
+ is only one such generic profile, pkcs15.profile
.
+
+ The card specific profile contains additional information required during
+ card initialization, such as location of PIN files, key references etc.
+ Profiles currently reside in @pkgdatadir@
+
Table of Contents
opensc.conf — configuration file for OpenSC
+ OpenSC obtains configuration data from the following sources in the following order +
+ command-line options +
+ environment variables +
+ Windows registry (if available) +
+ system-wide configuration file
+ (/home/fm/.local/etc/opensc.conf
)
+
+
+ The configuration file, opensc.conf
, is composed
+ of block
s, which, in general, have the
+ following format:
+
+key
[,name
...] { +block_contents
+} +
+ block_contents
is one or more
+ block_item
s where a
+ block_item
is one of
+
+ # comment string
+
+ key
[, name
...] = value
;
+
+ block
+
+
+ At the root level, opensc.conf
should contain
+ one or more application specific configuration blocks:
+
+appapplication
{ +block_contents
+} +
+ application
+ specifies one of:
+
+ default
: The fall-back configuration block for all applications
+
+ opensc-pkcs11
: Configuration block for the PKCS#11 module (opensc-pkcs11.so
)
+
+ onepin-opensc-pkcs11
: Configuration block for the PKCS#11 one-PIN-module (onepin-opensc-pkcs11.so
)
+
+ cardmod
: Configuration block for Windows' minidriver (opensc-minidriver.dll
)
+
+ tokend
: Configuration block for macOS' tokend (OpenSC.tokend)
+
+ cardos-tool
,
+ cryptoflex-tool
,
+ dnie-tool
,
+ egk-tool
,
+ eidenv
,
+ gids-tool
,
+ iasecc-tool
,
+ netkey-tool
,
+ npa-tool
,
+ openpgp-tool
,
+ opensc-asn1
,
+ opensc-explorer
,
+ opensc-notify
,
+ opensc-tool
,
+ piv-tool
,
+ pkcs11-tool
,
+ pkcs15-crypt
,
+ pkcs15-init
,
+ pkcs15-tool
,
+ sc-hsm-tool
,
+ westcos-tool
:
+ Configuration block for OpenSC tools
+
+
debug = num
;
+
+ Amount of debug info to print (Default:
+ 0
). A greater value means more
+ debug info.
+
+ The environment variable
+ OPENSC_DEBUG
overwrites this
+ setting.
+
debug_file = filename
;
+
+ The file to which debug output will be written
+ (Default: stderr
). Special
+ values stdout
and
+ stderr
are recognized.
+
profile_dir = filename
;
+
+ PKCS#15 initialization/personalization profiles
+ directory for
+ pkcs15-init(1).
+
+ (Default: /home/fm/.local/share/opensc
).
+
+ If this configuration value is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\ProfileDir
is
+ checked.
+
disable_popups = bool
;
+
+ Disable pop-ups of built-in GUI (Default: false
).
+
enable_default_driver = bool
;
+
+ Enable default card driver (Default:
+ false
). Default card driver is
+ explicitly enabled for
+ opensc-explorer(1).
+
+ and
+ opensc-tool(1).
+
+
card_drivers = name
... ;
+
+ Whitelist of card drivers to load at start-up.
+ The special value internal
(the
+ default) will load all statically linked drivers.
+
+ If an unknown (i.e. not internal or old) driver is
+ supplied, a separate configuration configuration
+ block has to be written for the driver. A special
+ value old
will load all
+ statically linked drivers that may be removed in
+ the future.
+
+ The list of supported card driver names can be + retrieved from the output of opensc-tool + --list-drivers. +
+ The environment variable
+ OPENSC_DRIVER
overwrites this
+ setting.
+
ignored_readers = name
... ;
+ + List of readers to ignore (Default: empty). If any + of the comma separated strings listed is matched in + a reader name (case sensitive, partial matching + possible), the reader is ignored by OpenSC. Use + opensc-tool --list-readers to + see all currently connected readers. +
reader_driver name
{
+ block_contents
+ }
+
+
+ Configuration of the card reader driver where name
is one of:
+
+ ctapi
: See the section called “Special Configuration Option for CT-API Readers”
+
+ pcsc
: See the section called “Special Configuration Option for CT-API Readers”
+
+ openct
: See the section called “Special Configuration Option for OpenCT Readers”
+
+ cryptotokenkit
: Configuration block for macOS' CryptoTokenKit readers
+
+
+ For details see the section called “reader_driver
Configuration Block”.
+
card_driver name
{
+ block_contents
+ }
+
+
+ Configuration of the card driver where name
is one of:
+
+ npa
: See the section called “Special Configuration Options for German ID Card”
+
+ dnie
: See the section called “Special Configuration Options for DNIe”
+
+ Any other value: Configuration block for an externally loaded card driver +
+
card_atr hexstring
{
+ block_contents
+ }
+
+
+ In addition to the built-in list of known cards in
+ the card driver, you can configure a new card for
+ the driver using the card_atr
+ block.
+
+ For details see the section called “card_atr
Configuration Block”.
+
secure_messaging name
{
+ block_contents
+ }
+
+
+ Configuration options for the secure messaging profile name
:
+
module_name = filename
;
+ + Name of external SM module (Default: libsmm-local.so). +
module_path = filename
;
+ + Directory with external SM module + (Default: /home/fm/.local/lib). +
+ If this configuration value is not
+ found on Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\SmDir
is
+ checked.
+
module_data = value
;
+ + Specific data to tune the module initialization. +
mode = value
;
+ + Secure messaging mode. Known parameters: +
+ transmit
:
+ In this mode the
+ procedure to securize
+ an APDU is called by
+ the OpenSC general APDU
+ transmit procedure. In
+ this mode all APDUs,
+ except the ones
+ filtered by the card
+ specific procedure, are
+ securized.
+
+ acl
:
+ In this mode APDU are
+ securized only if
+ needed by the ACLs of
+ the command to be
+ executed.
+
+
flags = value
;
+ + Secure messaging type specific flags. +
kmc = hexstring
;
+ + Default KMC of the GP Card Manager for the Oberthur's Java cards. +
ifd_serial = hexstring
;
+ keyset[_aid
]_num
_enc =
+ value
;
+ keyset[_aid
]_num
_mac =
+ value
;
+ + Keyset values from IAM profiles of + the Gemalto IAS/ECC cards with an + optional application identifier +
framework name
{
+ block_contents
+ }
+
+
+ Internal configuration options where name
is one of:
+
+ pkcs15
: See the section called “framework pkcs15
Configuration Block”
+
+ tokend
: See the section called “framework tokend
Configuration Block”
+
+
pkcs11 {
+ block_contents
+ }
+
+ + Parameters for the OpenSC PKCS11 module. +
+ For details see the section called “pkcs11
Configuration Block”.
+
reader_driver
Configuration Blockmax_send_size = num
;
+ max_recv_size = num
;
+
+ Limit command and response sizes
+ (Default:
+ max_send_size
+ = 255
,
+ max_recv_size
+ = 256
) . Some
+ Readers don't propagate their
+ transceive capabilities correctly.
+ max_send_size and max_recv_size
+ allow setting the limits manually,
+ for example to enable extended
+ length capabilities.
+
enable_escape bool
;
+
+ Detect reader capabilities with
+ escape commands (wrapped APDUs with
+ CLA=0xFF as defined by PC/SC pt. 3
+ and BSI TR-03119, e.g. for getting
+ the UID, escaped PIN commands and
+ the reader's firmware version,
+ Default: false
)
+
module filename
{
+ ports = nums
;
+ }
+
+ + Load the specified CT-API module with the specified number of ports. +
connect_exclusive = bool
;
+
+ Connect to reader in exclusive mode
+ (Default: false
)?
+ This option has no effect in Windows' minidriver.
+
disconnect_action = action
;
+
+ What to do when disconnecting from
+ a card (SCardDisconnect). Valid
+ values are
+ leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
transaction_end_action = action
;
+
+ What to do at the end of a
+ transaction (SCardEndTransaction).
+ Valid values
+ are leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
reconnect_action = action
;
+
+ What to do when reconnection to a
+ card (SCardReconnect). Valid values
+ are leave
,
+ reset
,
+ unpower
(Default:
+ leave
).
+ This option has no effect in Windows' minidriver.
+
enable_pinpad = bool
;
+
+ Enable pinpad if detected (PC/SC
+ v2.0.2 Part 10, Default:
+ true
)
+
fixed_pinlength = num
;
+
+ Some pinpad readers can only handle
+ one exact length of the PIN.
+ fixed_pinlength
+ sets this value so that OpenSC
+ expands the padding to this length
+ (Default: 0
,
+ i.e. not fixed).
+
provider_library = filename
;
+
+ Use specific PC/SC provider
+ (Default:
+ libpcsclite.so.1
).
+
can = value
;
+ + German ID card requires the CAN to + be verified before QES PIN. This, + however, is not part of the PKCS#15 + profile of the card. So for + verifying the QES PIN we actually + need both. The CAN may be given + here. If the CAN is not given here, + it will be prompted on the command + line or on the reader (depending on + the reader's capabilities). +
st_dv_certificate = filename
;
+ st_certificate = filename
;
+ st_key = filename
;
+ + QES is only possible with a Comfort + Reader (CAT-K), which holds a + cryptographic key to authenticate + itself as signature terminal (ST). + We usually will use the reader's + capability to sign the data. + However, during developement you + may specify soft certificates and + keys for a ST. +
+ An example PKI can be found in the + example data for the + German + ID card emulator +
user_consent_enabled = bool
;
+
+ Configure the warning message when
+ performing a signature operation
+ with the DNIe. Only used if
+ compiled with
+ --enable-dnie-ui
+
user_consent_app = filename
;
+
+ Specify the pinentry application to
+ use if warning is configured to be
+ displayed using pinentry (Default:
+ /usr/bin/pinentry
).
+ Only used if compiled with
+ --enable-dnie-ui
+
card_atr
Configuration Block+
+ Configuration options specified by the card's ATR: +
atrmask = hexstring
;
+ + The mask is logically AND'd with an + card ATR prior to comparison with + the ATR reference value above. + Using this mask allows identifying + and configuring multiple ATRs as + the same card model. +
driver = name
;
+ + When enabled, overrides all + possible settings from the card + drivers built-in card configuration + list. +
name = name
;
+ + Set card name for card drivers that + allows it. +
type = num
;
+
+ Allows setting the exact type of
+ the card internally used by the
+ card driver. Allowed values can be
+ found in the source code of
+ cards.h
.
+
flags = value
... ;
+ + Card flags as an hex value. + Multiple values are OR'd together. + Depending on card driver, this + allows fine-tuning the capabilities + in the card driver for your card. +
+ Optionally, some known parameters + can be specified as strings: +
+ rng
:
+ On-board random number
+ source
+
+ keep_alive
:
+ Request the card driver
+ to send a "keep alive"
+ command before each
+ transaction to make
+ sure that the required
+ applet is still
+ selected.
+
+
pkcs15emu = name
;
+ + When using PKCS#15 emulation, force + the emulation driver for specific + cards. Required for external + drivers, but can be used with + built-in drivers, too. +
force_protocol = value
;
+ + Force protocol selection for + specific cards. Known parameters: +
+ t0
+
+ t1
+
+ raw
+
+
md_read_only = bool
;
+
+ Mark card as read/only card in
+ Minidriver/BaseCSP interface
+ (Default: false
).
+
md_supports_X509_enrollment = bool
;
+
+ Indicate X509 enrollment support at
+ Minidriver/BaseCSP interface
+ (Default: false
).
+
md_guid_as_id = bool
;
+
+ Use the GUID generated for the key
+ as id in the PKCS#15 structure
+ (Default: false
, i.e. auto generated)
+
md_guid_as_label = bool
;
+
+ Use the GUID generated for the key
+ as label in the PKCS#15 structure
+ (Default: false
,
+ i.e. no label set).
+
md_supports_container_key_gen = bool
;
+
+ Card allows generating key pairs on the card (Default: false
).
+
md_supports_container_key_import = bool
;
+
+ Card allows importing private keys
+ (Default: false
).
+
md_pinpad_dlg_title = value
;
+
+ Window title of the PIN pad dialog
+ (Default: "Windows
+ Security"
).
+
md_pinpad_dlg_icon = filename
;
+
+ Filename of the icon for the PIN
+ pad dialog; use
+ ""
for no icon
+ (Default: Built-in smart card icon).
+
md_pinpad_dlg_main = value
;
+
+ Main instruction of the PIN pad
+ dialog (Default: "OpenSC
+ Smart Card Provider"
).
+
md_pinpad_dlg_content_user = value
;
+
+ Content of the PIN pad dialog for
+ role "user" (Default:
+ "Please verify your
+ fingerprint or PIN on the
+ card."
).
+
md_pinpad_dlg_content_user_sign = value
;
+
+ Content of the PIN pad dialog for
+ role "user+signature" (Default:
+ "Please verify your
+ fingerprint or PIN for the
+ digital signature PIN on the
+ card."
).
+
md_pinpad_dlg_content_user_sign = name
;
+
+ Content of the PIN pad dialog for
+ role "user+signature" (Default:
+ "Please verify your
+ fingerprint or PIN for the
+ digital signature PIN on the
+ card."
).
+
md_pinpad_dlg_content_admin = value
;
+
+ Content of the PIN pad dialog for
+ role "admin" (Default:
+ "Please enter your PIN to
+ unblock the user PIN on the
+ PINPAD."
)
+
md_pinpad_dlg_content_cancel = value
;
+ + Content of the PIN pad dialog after + pressing "Cancel", when the reader + doesn't respond to SCardCancel +
md_pinpad_dlg_expanded = value
;
+
+ Expanded information of the PIN pad
+ dialog (Default: "This
+ window will be closed
+ automatically after the PIN has
+ been submitted on the PINPAD
+ (timeout typically after 30
+ seconds)."
)
+
md_pinpad_dlg_expanded_cancel = value
;
+
+ Expanded information of the PIN pad
+ dialog after pressing "Cancel",
+ when the reader doesn't respond to
+ SCardCancel (Default:
+ "Some readers only support
+ canceling the operation on the
+ PIN pad. Press Cancel or remove
+ the card."
).
+
md_pinpad_dlg_enable_cancel = bool
;
+
+ Allow the user to cancel the PIN
+ pad dialog (Default:
+ false
)
+
md_pinpad_dlg_timeout = num
;
+
+ Time in seconds for the progress
+ bar of the PIN pad dialog to tick.
+ 0
removes the
+ progress bar (Default:
+ 30
).
+
notify_card_inserted = value
;
+ notify_card_inserted_text = value
;
+
+ Notification title and text when
+ card was inserted (Default:
+ "Smart card
+ detected"
, ATR of
+ the card).
+
notify_card_removed = value
;
+ notify_card_removed_text = value
;
+
+ Notification title and text when
+ card was removed (Default:
+ "Smart card
+ removed"
, name of
+ smart card reader).
+
notify_pin_good = value
;
+ notify_pin_good_text = value
;
+
+ Notification title and text when
+ PIN was verified (Default:
+ "PIN verified"
,
+ "Smart card is
+ unlocked"
).
+
notify_pin_bad = value
;
+ notify_pin_bad_text = value
;
+
+ Notification title and text when
+ PIN was wrong (Default:
+ "PIN not
+ verified"
,
+ "Smart card is
+ locked"
).
+
+
framework pkcs15
Configuration Blockuse_file_caching = bool
;
+
+ Whether to cache the card's files (e.g.
+ certificates) on disk in
+ file_cache_dir
(Default:
+ false
).
+
+ If caching is done by a system process, the + cached files may be placed inaccessible from + the user account. Use a globally readable and + writable location if you wish to share the + cached information. Note that the cached files + may contain personal data such as name and mail + address. +
file_cache_dir = filename
;
+ + Where to cache the card's files. The default values are: +
+
(Unix)
+ HOME
/.eid/cache/
+
(Windows)
+ USERPROFILE
\.eid-cache\
+
+ If caching is done by a system process, the + cached files may be placed inaccessible from + a user account. Use a globally readable and + writable location if you wish to share the + cached information. Note that the cached files + may contain personal data such as name and mail + address. +
use_pin_caching = bool
;
+
+ Use PIN caching (Default: true
)?
+
pin_cache_counter = num
;
+
+ How many times to use a PIN from cache before
+ re-authenticating it (Default:
+ 10
)?
+
pin_cache_ignore_user_consent = bool
;
+
+ Older PKCS#11 applications not supporting
+ CKA_ALWAYS_AUTHENTICATE
may
+ need to set this to get signatures to work with
+ some cards (Default: false
).
+
enable_pkcs15_emulation = bool
;
+
+ Enable pkcs15 emulation (Default:
+ true
).
+
try_emulation_first = bool
;
+
+ Prefer pkcs15 emulation code before the normal
+ pkcs15 processing (Default:
+ no
). Some cards work in
+ emu-only mode, and do not depend on this
+ option.
+
enable_builtin_emulation = bool
;
+
+ Enable builtin emulators (Default:
+ true
).
+
builtin_emulators = emulators
;
+
+ List of the builtin pkcs15 emulators to test
+ (Default: esteid, openpgp, tcos,
+ starcert, itacns, infocamere, postecert,
+ actalis, atrust-acos, gemsafeGPK,
+ gemsafeV1, tccardos, PIV-II
)
+
pkcs11_enable_InitToken = bool
;
+
+ Enable initialization and card recognition in
+ PKCS#11 layer (Default:
+ false
).
+
emulate name
{
+ block_contents
+ }
+
+
+ Configuration options for a PKCS#15 emulator
+ where name
is a
+ short name for an external card driver.
+
module = filename
;
+ + For pkcs15 emulators loaded from an + external shared library/DLL, you need to + specify the path name of the module and + customize the card_atr example above + correctly. +
function = name
;
+
+ Get the init function name of the
+ emulator (Default:
+ sc_pkcs15_init_func_ex
)
+
application hexstring
{
+ block_contents
+ }
+
+
+ Configuration of the on-card-application where
+ hexstring
is the
+ application identifier (AID).
+
type = name
;
+
+ Type of application where
+ name
is one
+ of:
+
+ generic
+
+ protected
+
+
+ Used to distinguish the common access + application and application for which + authentication to perform some + operation cannot be obtained with the + common procedures (ex. object creation + protected by secure messaging). Used + by PKCS#11 module configured to expose + restricted number of slots. (for ex. + configured to expose only User PIN + slot, User and Sign PINs slots, ...) +
model = name
;
+ disable = bool
;
+
+ Do not expose application in PKCS#15
+ framework (Default:
+ false
)
+
framework tokend
Configuration Blockscore = num
;
+
+ Score for OpenSC.tokend
+ (Default: 300
). The tokend with
+ the highest score shall be used.
+
ignore_private_certificate = bool
;
+
+ Tokend ignore to read PIN protected certificate
+ that is set
+ SC_PKCS15_CO_FLAG_PRIVATE
flag
+ (Default: true
).
+
pkcs11
Configuration Blockmax_virtual_slots = num
;
+
+ Maximum Number of virtual slots (Default:
+ 16
). If there are more slots
+ than defined here, the remaining slots will be
+ hidden from PKCS#11.
+
slots_per_card = num
;
+
+ Maximum number of slots per smart card (Default:
+ 4
). If the card has fewer keys
+ than defined here, the remaining number of slots
+ will be empty.
+
lock_login = bool
;
+
+ By default, the OpenSC PKCS#11 module will not lock
+ your card once you authenticate to the card via
+ C_Login
(Default:
+ false
).
+
+ Thus the other users or other applications is not
+ prevented from connecting to the card and perform
+ crypto operations (which may be possible because
+ you have already authenticated with the card). This
+ setting is not very secure.
+
+ Also, if your card is not locked, you can enconter + problems due to limitation of the OpenSC framework, + that still is not thoroughly tested in the multi + threads environment. +
+ Your settings will be more secure if you choose to
+ lock your card. Nevertheless this behavior is a
+ known violation of PKCS#11 specification. Now once
+ one application has started using your card with
+ C_Login
, no other application
+ can use it, until the first is done and calls
+ C_Logout
or
+ C_Finalize
. In the case of many
+ PKCS#11 application this does not happen until you
+ exit the application.
+
+ Thus it is impossible to use several smart card + aware applications at the same time, e.g. you + cannot run both Firefox + and Thunderbird at the + same time, if both are configured to use your smart + card. +
atomic = bool
;
+
+ By default, interacting with the OpenSC PKCS#11
+ module may change the state of the token, e.g.
+ whether a user is logged in or not (Default:
+ false
).
+
+ Thus other users or other applications may change + or use the state of the token unknowingly. Other + applications may create signatures abusing an + existing login or they may logout unnoticed. +
+ With this setting enabled the login state of the
+ token is tracked and cached (including the PIN).
+ Every transaction is preceded by restoring the
+ login state. After every transaction a logout is
+ performed. This setting by default also enables
+ lock_login
to disable access for
+ other applications during the atomic transactions.
+
+ Please note that any PIN-pad should be disabled
+ (see enable_pinpad
), because the
+ user would have to input his PIN for every
+ transaction.
+
init_sloppy = bool
;
+
+ With this setting disabled, the OpenSC PKCS#11
+ module will initialize the slots available when the
+ application calls C_GetSlotList
.
+ With this setting enabled, the slots will also get
+ initialized when C_GetSlotInfo
+ is called (Default: true
).
+
+ This setting is a workaround for
+ Java which does not call
+ C_GetSlotList
when configured
+ with a static slot
instead of
+ slotListIndex
.
+
user_pin_unblock_style = mode
;
+
+ User PIN unblock style mode
+ is one of:
+
+ none
(Default): PIN
+ unblock is not possible with PKCS#11 API
+
+ set_pin_in_unlogged_session
:
+ C_SetPIN
in unlogged
+ session: PUK is passed as the
+ OldPin
argument of the
+ C_SetPIN
call.
+
+ set_pin_in_specific_context
:
+ C_SetPIN
in the
+ CKU_SPECIFIC_CONTEXT
+ logged session: PUK is passed as the
+ OldPin
argument of the
+ C_SetPIN
call.
+
+ init_pin_in_so_session
:
+ C_InitPIN
in
+ CKU_SO
logged session:
+ User PIN 'UNBLOCK' is protected by SOPIN.
+ (PUK == SOPIN).
+
+
create_puk_slot = bool
;
+
+ Create slot for unblocking PIN with PUK (Default:
+ false
). This way PKCS#11 API can
+ be used to login with PUK and change a PIN. May
+ cause problems with some applications like
+ Firefox and
+ Thunderbird.
+
create_slots_for_pins = mode
... ;
+
+ Symbolic names of PINs for which slots are created
+ where mode
is a list of:
+
+ all
(Default): All
+ non-SO-PIN, non-unblocking PINs
+
+ user
: The first
+ global or first local PIN
+
+ sign
: The second PIN
+ (first local, second global or second
+ local)
+
+
+ Card can contain more then one PINs or more then + one on-card application with its own PINs. + Normally, to access all of them with the PKCS#11 + API a slot has to be created for all of them. Many + slots could be ennoying for some of widely used + application, like FireFox. This configuration + parameter allows to select the PIN(s) for which + PKCS#11 slot will be created. +
+ Only PINs initialised, non-SO-PIN, non-unblocking + are associated with symbolic name. +
+ For the module to simulate the opensc-onepin module
+ behavior the following option
+ create_slots_for_pins = "user";
+
OPENSC_CONF
+ + Filename for a user defined configuration file +
+ If this environment variable is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\ConfigFile
is
+ checked.
+
CARDMOD_LOW_LEVEL_DEBUG
+
+ Write minidriver debug information to
+ C:\tmp\md.log
, if set to
+ 1
.
+
+ If this environment variable is not found on
+ Windows, the registry key
+ HKLM\Software\OpenSC
+ Project\OpenSC\MiniDriverDebug
is
+ checked.
+
PIV_EXT_AUTH_KEY
,
+ PIV_9A_KEY
,
+ PIV_9C_KEY
,
+ PIV_9D_KEY
,
+ PIV_9E_KEY
+ + PIV configuration during initialization with + piv-tool. +
pkcs15-profile — format of profile for pkcs15-init
+ The pkcs15-init utility for PKCS #15 smart card + personalization is controlled via profiles. When starting, it will read two + such profiles at the moment, a generic application profile, and a card + specific profile. The generic profile must be specified on the command line, + while the card-specific file is selected based on the type of card detected. +
+ The generic application profile defines general information about the card + layout, such as the path of the application DF, various PKCS #15 files within + that directory, and the access conditions on these files. It also defines + general information about PIN, key and certificate objects. Currently, there + is only one such generic profile, pkcs15.profile. +
+ The card specific profile contains additional information required during + card initialization, such as location of PIN files, key references etc. + Profiles currently reside in @pkgdatadir@ +
Table of Contents
Table of Contents
Table of Contents
cardos-tool — displays information about Card OS-based security tokens or format them -
cardos-tool
[OPTIONS
]
cardos-tool
[OPTIONS
]
The cardos-tool utility is used to display information about smart cards and similar security tokens based on Siemens Card/OS M4. -
--card-driver
name
,
-c
name
Use the card driver specified by name
.
@@ -65,17 +68,26 @@ smart cards and similar security tokens based on Siemens Card/OS M4.
--format
,
-f
Format the card or token.
--help
,
+ -h
+ Print help message on screen.
--info
,
-i
Display information about the card or token.
--reader
number
,
- -r
number
+ --reader
num
,
+ -r
num
Specify the reader to use. By default, the first
reader with a present card is used. If
num
is an ATR, the
reader with a matching card will be chosen.
--startkey
arg
,
+ -s
arg
+ Specify startkey for format.
--change-startkey
arg
,
+ -S
arg
+ Change Startkey with given APDU command.
--verbose
,
-v
Causes cardos-tool to be more verbose.
@@ -84,13 +96,13 @@ smart cards and similar security tokens based on Siemens Card/OS M4.
-w
Causes cardos-tool to wait for the token to be inserted into reader.
-
cryptoflex-tool — utility for manipulating Schlumberger Cryptoflex data structures
cryptoflex-tool
[OPTIONS
]
cryptoflex-tool — utility for manipulating Schlumberger Cryptoflex data structures
cryptoflex-tool
[OPTIONS
]
cryptoflex-tool is used to manipulate PKCS data structures on Schlumberger Cryptoflex smart cards. Users can create, list and read PINs and keys stored on the smart card. User PIN authentication is performed for those operations that require it. -
dnie-tool — displays information about DNIe based security tokens
dnie-tool
[OPTIONS
]
The dnie-tool utility is used to display additional information about DNIe, the Spanish National eID card. -
--idesp
,
-i
@@ -185,8 +197,8 @@ smart cards and similar security tokens based on Siemens Card/OS M4.
value of the environment variable
VARIABLE
is used.
The default is do not enter pin--reader
number
,
- -r
number
+ --reader
num
,
+ -r
num
Specify the reader to use. By default, the first reader with a present card is used. If @@ -205,16 +217,48 @@ smart cards and similar security tokens based on Siemens Card/OS M4.
Causes dnie-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
-
eidenv — utility for accessing visible data from - electronic identity cards
eidenv
[OPTIONS
]
egk-tool — displays information on the German electronic health card (elektronische Gesundheitskarte, eGK) +
egk-tool
[OPTIONS
]
+ The egk-tool utility is used to display information stored on the German elektronic health card (elektronische Gesundheitskarte, eGK). +
+
--help
,
+ -h
Print help and exit.
--version
,
+ -V
Print version and exit.
--reader
arg
,
+ -r
arg
+
+ Specify the reader to use.
+ Use -1
as arg
+ to automatically detect the reader to use.
+ By default, the first reader with a present card is used.
+
--verbose
,
+ -v
+ + Causes egk-tool to be more verbose. + Specify this flag several times to be more verbose. +
+
eidenv — utility for accessing visible data from + electronic identity cards
eidenv
[OPTIONS
]
The eidenv utility is used for accessing data from electronic identity cards (like national eID cards) which might not be present in PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables. -
--exec
prog
,
-x
prog
@@ -247,11 +291,11 @@ to enable debug output in the opensc library.
--wait
,
-w
Wait for a card to be inserted
-
gids-tool — smart card utility for GIDS cards
gids-tool
[OPTIONS
]
The gids-tool utility can be used from the command line to perform miscellaneous smart card operations on a GIDS smart card. -
-X
,
--initialize
@@ -286,96 +330,15 @@ to enable debug output in the opensc library.
--verbose
Verbose operation. Use several times to enable debug output.
-
netkey-tool — administrative utility for Netkey E4 cards
netkey-tool
[OPTIONS
] [COMMAND
]
The netkey-tool utility can be used from the - command line to perform some smart card operations with NetKey E4 cards - that cannot be done easily with other OpenSC-tools, such as changing local - PINs, storing certificates into empty NetKey E4 cert-files or displaying - the initial PUK-value.
-
--help
,
- -h
- Displays a short help message.
--pin
pin-value
,
- -p
pin-value
- Specifies the current value of the global PIN.
--puk
pin-value
,
- -u
pin-value
- Specifies the current value of the global PUK.
--pin0
pin-value
,
- -0
pin-value
- Specifies the current value of the local PIN0 (aka local PIN).
--pin1
pin-value
,
- -1
pin-value
- Specifies the current value of the local PIN1 (aka local PUK).
--reader
number
,
- -r
number
-
- Specify the reader to use. By default, the first
- reader with a present card is used. If
- num
is an ATR, the
- reader with a matching card will be chosen.
-
-v
- Causes netkey-tool to be more verbose. This - options may be specified multiple times to increase verbosity.
-
With the -p
, -u
, -0
or the -1
- one of the cards pins may be specified. You may use plain ascii-strings (i.e. 123456) or a hex-string
- (i.e. 31:32:33:34:35:36). A hex-string must consist of exactly n 2-digit hexnumbers separated by n-1 colons.
- Otherwise it will be interpreted as an ascii string. For example :12:34: and 1:2:3:4 are both pins of
- length 7, while 12:34 and 01:02:03:04 are pins of length 2 and 4.
When used without any options or commands, netkey-tool will - display information about the smart cards pins and certificates. This will not change - your card in any aspect (assumed there are no bugs in netkey-tool). - In particular the tries-left counters of the pins are investigated without doing - actual pin-verifications.
If you specify the global PIN via the --pin
option,
- netkey-tool will also display the initial value of the cards
- global PUK. If your global PUK was changed netkey-tool will still
- display its initial value. There's no way to recover a lost global PUK once it was changed.
- There's also no way to display the initial value of your global PUK without knowing the
- current value of your global PIN.
For most of the commands that netkey-tool can execute, you have - to specify one pin. One notable exception is the nullpin command, but - this command can only be executed once in the lifetime of a NetKey E4 card.
-
number
filename
- This command will read one of your cards certificates (as specified by
- number
) and save this certificate into file filename
- in PEM-format. Certificates on a NetKey E4 card are readable without a pin, so you don't
- have to specify one.
filename
number
- This command will read the first PEM-encoded certificate from file
- filename
and store this into your smart cards certificate file
- number
. Some of your smart cards certificate files might be readonly, so
- this will not work with all values of number
. If a certificate file is
- writable you must specify a pin in order to change it. If you try to use this command
- without specifying a pin, netkey-tool will tell you which one is
- needed.
pin
| puk
|
- pin0
| pin1
} new-pin
- This changes the value of the specified pin to the given new value. - You must specify either the current value of the pin or another pin to be able to do - this and if you don't specify a correct one, netkey-tool will tell - you which one is needed.
initial-pin
- This command can be executed only if the global PIN of your card is - in nullpin-state. There's no way to return back to nullpin-state once you have changed - your global PIN. You don't need a pin to execute the nullpin-command. After a successful - nullpin-command netkey-tool will display your cards initial - PUK-value.
pin
| pin0
| pin1
}
- This unblocks the specified pin. You must specify another pin - to be able to do this and if you don't specify a correct one, - netkey-tool will tell you which one is needed.
-
iasecc-tool — displays information about IAS/ECC card +
iasecc-tool
[OPTIONS
]
The iasecc-tool utility is used to display information about IAS/ECC v1.0.1 smart cards. -
--reader
number
,
+ --reader
num
,
Specify the reader to use. By default, the first reader with a present card is used. If @@ -397,91 +360,12 @@ to enable debug output in the opensc library.
-w
Causes iasecc-tool to wait for the token to be inserted into reader.
-
openpgp-tool — utility for accessing visible data OpenPGP smart cards - and compatible tokens
openpgp-tool
[OPTIONS
]
- The openpgp-tool utility is used for - accessing data from the OpenPGP v1.1 and v2.0 smart cards - and compatible tokens like e.g. GPF CryptoStick v1.x, - which might not be present in - PKCS#15 objects but available in custom files on the - card. The data can be printed on screen or used by - other programs via environment variables. -
-
--exec
prog
,
- -x
prog
- - Execute the given program with data in environment variables. -
--help
,
- -h
- - Print help message on screen. -
--raw
- - Print values in raw format, as they are stored on the card. -
--pretty
- - Print values in pretty format. -
--user-info
,
- -U
- - Show card holder information. -
--reader
num
,
- -r
num
-
- Specify the reader to use. By default, the first
- reader with a present card is used. If
- num
is an ATR, the
- reader with a matching card will be chosen.
-
--verify
pintype
- - Verify PIN (CHV1, CHV2 or CHV3). -
--pin
string
-
- The PIN text to verify. If set to
- env:VARIABLE
, the value of
- the environment variable
- VARIABLE
is used.
-
--gen-key
ID
,
- -G
ID
- - Generate key. Specify key ID (1, 2 or 3) to generate. -
--key-length
bitlength
,
- -L
bitlength
- - Length (default 2048 bit) of the key to be generated. -
--version
,
- -V
- - Print the version of the utility and exit. -
--verbose
,
- -v
- - Verbose operation. Use several times to enable debug output. -
--wait
,
- -w
- - Wait for a card to be inserted. -
-
netkey-tool — administrative utility for Netkey E4 cards
netkey-tool
[OPTIONS
] [COMMAND
]
The netkey-tool utility can be used from the command line to perform some smart card operations with NetKey E4 cards that cannot be done easily with other OpenSC-tools, such as changing local PINs, storing certificates into empty NetKey E4 cert-files or displaying - the initial PUK-value.
--help
,
-h
@@ -498,8 +382,8 @@ to enable debug output in the opensc library.
--pin1
pin-value
,
-1
pin-value
Specifies the current value of the local PIN1 (aka local PUK).
--reader
number
,
- -r
number
+ --reader
num
,
+ -r
num
Specify the reader to use. By default, the first reader with a present card is used. If @@ -509,11 +393,11 @@ to enable debug output in the opensc library.
-v
Causes netkey-tool to be more verbose. This options may be specified multiple times to increase verbosity.
-
With the -p
, -u
, -0
or the -1
one of the cards pins may be specified. You may use plain ascii-strings (i.e. 123456) or a hex-string
(i.e. 31:32:33:34:35:36). A hex-string must consist of exactly n 2-digit hexnumbers separated by n-1 colons.
Otherwise it will be interpreted as an ascii string. For example :12:34: and 1:2:3:4 are both pins of
- length 7, while 12:34 and 01:02:03:04 are pins of length 2 and 4.
When used without any options or commands, netkey-tool will + length 7, while 12:34 and 01:02:03:04 are pins of length 2 and 4.
When used without any options or commands, netkey-tool will display information about the smart cards pins and certificates. This will not change your card in any aspect (assumed there are no bugs in netkey-tool). In particular the tries-left counters of the pins are investigated without doing @@ -539,8 +423,9 @@ to enable debug output in the opensc library.
writable you must specify a pin in order to change it. If you try to use this command without specifying a pin, netkey-tool will tell you which one is needed.
pin
| puk
|
- pin0
| pin1
} new-pin
+ change
+ { pin | puk | pin0 | pin1 }
+ new-pin
This changes the value of the specified pin to the given new value. You must specify either the current value of the pin or another pin to be able to do this and if you don't specify a correct one, netkey-tool will tell @@ -551,15 +436,159 @@ to enable debug output in the opensc library.
your global PIN. You don't need a pin to execute the nullpin-command. After a successful nullpin-command netkey-tool will display your cards initial PUK-value.
pin
| pin0
| pin1
}
+ unblock
+ { pin | pin0 | pin1 }
This unblocks the specified pin. You must specify another pin to be able to do this and if you don't specify a correct one, netkey-tool will tell you which one is needed.
-
openpgp-tool — utility for accessing visible data OpenPGP smart cards - and compatible tokens
openpgp-tool
[OPTIONS
]
npa-tool — displays information on the German eID card (neuer Personalausweis, nPA). +
npa-tool
[OPTIONS
]
+ The npa-tool utility is used to display information + stored on the German eID card (neuer Personalausweis, nPA), + and to perform some write and verification operations. +
+
--help
,
+ -h
Print help and exit.
--version
,
+ -V
Print version and exit.
--reader
arg
,
+ -r
arg
+
+ Specify the reader to use.
+ Use -1
as arg
+ to automatically detect the reader to use.
+ By default, the first reader with a present card is used.
+
--verbose
,
+ -v
+ + Causes npa-tool to be more verbose. + Specify this flag several times to be more verbose. +
+
--pin
[STRING
],
+ -p
[STRING
]
+ + Run PACE with (transport) eID-PIN. +
--puk
[STRING
],
+ -u
[STRING
]
+ + Run PACE with PUK. +
--can
[STRING
],
+ -c
[STRING
]
+ + Run PACE with Card Access Number (CAN). +
--mrz
[STRING
],
+ -m
[STRING
]
+ + Run PACE with Machine Readable Zone (MRZ). + Enter the MRZ without newlines. +
--env
+ Specify whether to use environment variables PIN
,
+ PUK
, CAN
, MRZ
,
+ and NEWPIN
.
+ You may want to clean your environment before enabling this.
+ (default=off)
+
--new-pin
[STRING
],
+ -N
[STRING
]
+ + Install a new PIN. +
--resume
,
+ -R
+ + Resume eID-PIN (uses CAN to activate last retry). + (default=off) +
--unblock
,
+ -U
+ + Unblock PIN (uses PUK to activate three more retries). + (default=off) +
--cv-certificate
FILENAME
,
+ -C
FILENAME
+ + Specify Card Verifiable (CV) certificate + to create a certificate chain. + The option can be given multiple times, in which case the + order is important. +
--cert-desc
HEX_STRING
+ Certificate description to show for Terminal Authentication. +
--chat
HEX_STRING
+ Specify the Card Holder Authorization Template
+ (CHAT) to use.
+ If not given, it defaults to the terminal's CHAT.
+ Use 7F4C0E060904007F000703010203530103
+ to trigger EAC on the CAT-C (Komfortleser).
+
--auxiliary-data
HEX_STRING
,
+ -A
HEX_STRING
+ + Specify the terminal's auxiliary data. + If not given, the default is determined by verification + of validity, age and community ID. +
--private-key
FILENAME
,
+ -P
FILENAME
+ + Specify the terminal's private key. +
--cvc-dir
DIRECTORY
+ Specify where to look for the certificate of the
+ Country Verifying Certification Authority
+ (CVCA).
+ If not given, it defaults to
+ /home/fm/.local/etc/eac/cvc
.
+
--x509-dir
DIRECTORY
+ Specify where to look for the X.509 certificate.
+ If not given, it defaults to
+ /home/fm/.local/etc/eac/x509
.
+
--disable-ta-checks
+ Disable checking the validity period of CV certificates. + (default=off) +
--disable-ca-checks
+ Disable passive authentication. (default=off) +
--read-dg1
Read data group 1: Document Type.
--read-dg2
Read data group 2: Issuing State.
--read-dg3
Read data group 3: Date of Expiry.
--read-dg4
Read data group 4: Given Name(s).
--read-dg5
Read data group 5: Family Name.
--read-dg6
Read data group 6: Religious/Artistic Name.
--read-dg7
Read data group 7: Academic Title.
--read-dg8
Read data group 8: Date of Birth.
--read-dg9
Read data group 9: Place of Birth.
--read-dg10
Read data group 10: Nationality.
--read-dg11
Read data group 11: Sex.
--read-dg12
Read data group 12: Optional Data.
--read-dg13
Read data group 13: Birth Name.
--read-dg14
Read data group 14.
--read-dg15
Read data group 15.
--read-dg16
Read data group 16.
--read-dg17
Read data group 17: Normal Place of Residence.
--read-dg18
Read data group 18: Community ID.
--read-dg19
Read data group 19: Residence Permit I.
--read-dg20
Read data group 20: Residence Permit II.
--read-dg21
Read data group 21: Optional Data.
--write-dg17
HEX_STRING
Write data group 17: Normal Place of Residence.
--write-dg18
HEX_STRING
Write data group 18: Community ID.
--write-dg19
HEX_STRING
Write data group 19: Residence Permit I.
--write-dg20
HEX_STRING
Write data group 20: Residence Permit II.
--write-dg21
HEX_STRING
Write data group 21: Optional Data.
--verify-validity
YYYYMMDD
+ Verify chip's validity with a reference date. +
--older-than
YYYYMMDD
+ Verify age with a reference date. +
--verify-community
HEX_STRING
+ Verify community ID with a reference ID. +
--break
,
+ -b
+
+ Brute force PIN, CAN or PUK.
+ Use together with options -p
,
+ -a
, or -u
.
+ (default=off)
+
--translate
FILENAME
,
+ -t
FILENAME
+ + Specify the file with APDUs of HEX_STRINGs to send + through the secure channel. + (default=`stdin') +
--tr-03110v201
+ Force compliance to BSI TR-03110 version 2.01. (default=off) +
--disable-all-checks
+ Disable all checking of fly-by-data. (default=off) +
openpgp-tool — utility for accessing visible data OpenPGP smart cards + and compatible tokens
openpgp-tool
[OPTIONS
]
The openpgp-tool utility is used for accessing data from the OpenPGP v1.1 and v2.0 smart cards and compatible tokens like e.g. GPF CryptoStick v1.x, @@ -567,30 +596,141 @@ to enable debug output in the opensc library.
PKCS#15 objects but available in custom files on the card. The data can be printed on screen or used by other programs via environment variables. -
--del-key
arg
+
+ Delete key indicated by arg
.
+ arg
can be 1
,
+ 2
, 3
, or
+ all
.
+
--do
arg
,
+ -d
arg
+
+ Dump private data object (DO)
+ indicated by arg
.
+ arg
can be in the form
+ x
,
+ 10
x
, or
+ 010
x
+ to access DO 010
x
,
+ where x
is 1
,
+ 2
, 3
, or
+ 4
.
+
--erase
,
+ -E
+ + Erase (i.e. reset) the card. +
--exec
prog
,
-x
prog
- Execute the given program with data in environment variables. + Execute the given program with data in environment variables. +
--gen-key
arg
,
+ -G
arg
+
+ Generate key with the ID given as arg
.
+ arg
can be one of 1
,
+ 2
, or 3
.
--help
,
-h
- Print help message on screen. + Print help message on screen.
--raw
+ --key-length
bitlength
,
+ -L
bitlength
- Print values in raw format, as they are stored on the card. + Specify the length of the key to be generated. + If not given, it defaults to 2048 bit. +
--pin
string
+
+ The PIN text to verify. If set to
+ env:VARIABLE
, the value of
+ the environment variable
+ VARIABLE
is used.
--pretty
- Print values in pretty format. + Print values in pretty format. +
--raw
+ + Print values in raw format, as they are stored on the card. +
--reader
num
,
+ -r
num
+
+ Specify the reader to use. By default, the first
+ reader with a present card is used. If
+ num
is an ATR, the
+ reader with a matching card will be chosen.
--user-info
,
-U
- Show card holder information. + Show card holder information. +
--verify
pintype
+ + Verify PIN (CHV1, CHV2 or CHV3). +
--version
,
+ -V
+ + Print the version of the utility and exit. +
--verbose
,
+ -v
+ + Verbose operation. Use several times to enable debug output. +
--wait
,
+ -w
+ + Wait for a card to be inserted. +
+
opensc-explorer — + generic interactive utility for accessing smart card + and similar security token functions +
opensc-explorer
[OPTIONS
] [SCRIPT
]
+ The opensc-explorer 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. +
+ The following are the command-line options for + opensc-explorer. There are additional + interactive commands available once it is running. +
--card-driver
driver
,
+ -c
driver
+ + Use the given card driver. The default is + auto-detected. +
--mf
path
,
+ -m
path
+
+ Select the file referenced by the given path on
+ startup. The default is the path to the standard master file,
+ 3F00. If path
is empty (e.g. opensc-explorer
+ --mf ""), then no file is explicitly selected.
--reader
num
,
-r
num
@@ -600,48 +740,293 @@ to enable debug output in the opensc library.
num
is an ATR, the
reader with a matching card will be chosen.
--verify
pintype
+ --verbose
, -v
- Verify PIN (CHV1, CHV2 or CHV3). -
--pin
string
+ Causes opensc-explorer to be more
+ verbose. Specify this flag several times to enable
+ debug output in the opensc library.
+ --wait
, -w
+ Wait for a card to be inserted
+
+ The following commands are supported at opensc-explorer's
+ interactive prompt or in script files passed via the command line parameter
+ SCRIPT
.
+
hex-data
+ Send a custom APDU command hex-data
.
file-id
+ Parse and print the ASN.1 encoded content of the file specified by
+ file-id
.
file-id
| sfi:
short-id
]
+ Print the contents of the currently selected EF or the contents
+ of a file specified by file-id
or the short file id
+ short-id
.
+
..
| file-id
| aid:
DF-name
}
- The PIN text to verify. If set to
- env:VARIABLE
, the value of
- the environment variable
- VARIABLE
is used.
+ 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 file-id
,
+ which must be a DF directly
+ beneath the current DF, then change to that DF.
+ If it is an application identifier given as
+ aid:
DF-name
,
+ then jump to the MF of the application denoted by
+ DF-name
.
+
CHV
pin-ref
+ [
+ [old-pin
]
+ new-pin
+ ]
+ Change a PIN, where pin-ref
is the PIN reference.
+ Examples: +
change CHV2 00:00:00:00:00:00 "foobar"
+ Change PIN CHV2
+ to the new value foobar
,
+ giving the old value 00:00:00:00:00:00
.
+
change CHV2 "foobar"
+ Set PIN CHV2
+ to the new value foobar
.
+
change CHV2
+ Change PIN CHV2
using the card reader's pinpad.
+
--gen-key
ID
,
- -G
ID
+ create
+ file-id
+ size
+ Create a new EF. file-id
specifies the
+ id number and size
is the size of the new file.
+
level
]
+ Set OpenSC debug level to level
.
If level
is omitted the current debug level will be shown.
file-id
+ Remove the EF or DF specified by file-id
hex-tag
+ [output
]
+ Copy the internal card's 'tagged' data into the local file.
The local file is specified by output
while the tag of
+ the card's data is specified by hex-tag
.
+
+ If output
is omitted, the name of the output file will be
+ derived from hex-tag
.
+
hex-tag
+ input
+ Update internal card's 'tagged' data.
hex-tag
is the tag of the card's data.
+ input
is the filename of the source file or the literal data presented as
+ a sequence of hexadecimal values or "
enclosed string.
+
string
...
+ Print the string
s given.
Erase the card, if the card supports it.
file-id
+ [output
]
+ Copy an EF to a local file. The local file is specified
+ by output
while the card file is specified by file-id
.
+
+ If output
is omitted, the name of the output file will be
+ derived from the full card path to file-id
.
+
file-id
]
+ Display attributes of a file specified by file-id
.
+ If file-id
is not supplied,
+ the attributes of the current file are printed.
pattern
...]
+ List files in the current DF.
+ If no pattern
is given, then all files are listed.
+ If one ore more pattern
s are given, only files matching
+ at least one pattern
are listed.
start-id
+ [end-id
]
+ ]
+ Find all files in the current DF.
+ Files are found by selecting all file identifiers in the range from start-fid
to end-fid
(by default from 0000 to FFFF).
start-tag
+ [end-tag
]
+ ]
+ Find all tags of data objects in the current context.
+ Tags are found by using GET DATA in the range from start-tag
to end-tag
(by default from 0000 to FFFF).
file-id
+ size
+ Create a DF. file-id
specifies the id number
+ and size
is the size of the new file.
file-id
+ input
+ Copy a local file to the card. The local file is specified
+ by input
while the card file is specified by file-id
.
+
Exit the program.
count
+ Generate random sequence of count
bytes.
file-id
+ Remove the EF or DF specified by file-id
CHV
pin-ref
+ [
+ puk
+ [new-pin
]
+ ]
- Generate key. Specify key ID (1, 2 or 3) to generate.
+ Unblock the PIN denoted by pin-ref
+ using the PUK puk
, and set potentially
+ change its value to new-pin
.
+
+ 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's pin pad.
+
+ Examples: +
unblock CHV2 00:00:00:00:00:00 "foobar"
+ Unblock PIN CHV2
using PUK
+ 00:00:00:00:00:00
+ and set it to the new value foobar
.
+
unblock CHV2 00:00:00:00:00:00 ""
+ Unblock PIN CHV2
using PUK
+ 00:00:00:00:00:00
keeping the old value.
+
unblock CHV2 "" "foobar"
+ Set new value of PIN CHV2
+ to foobar
.
+
unblock CHV2 00:00:00:00:00:00
+ Unblock PIN CHV2
using PUK
+ 00:00:00:00:00:00
.
+ The new PIN value is prompted by pinpad.
+
unblock CHV2 ""
+ Set PIN CHV2
.
+ The new PIN value is prompted by pinpad.
+
unblock CHV2
+ Unblock PIN CHV2
.
+ The unblock code and new PIN value are prompted by pinpad.
+
--key-length
bitlength
,
- -L
bitlength
-
- Length (default 2048 bit) of the key to be generated.
+ update_binary
+ file-id
+ offs
+ data
+
Binary update of the file specified by
+ file-id
with the literal data
+ data
starting from offset specified
+ by offs
.
data
can be supplied as a sequencer
+ of the hex values or as a "
enclosed string.
file-id
+ rec-nr
+ rec-offs
+ data
+ Update record specified by rec-nr
of the file
+ specified by file-id
with the literal data
+ data
starting from offset specified by
+ rec-offs
.
data
can be supplied as a sequence of the hex values or
+ as a "
enclosed string.
key-type
key-id
+ [key
]
+ Present a PIN or key to the card, where
+ key-type
can be one of CHV
,
+ KEY
, AUT
or PRO
.
+ key-id
is a number representing the key or PIN reference.
+ key
is the key or PIN to be verified, formatted as a
+ colon-separated list of hex values or a "
enclosed string.
+
+ If key
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.
+
+ Examples: +
verify CHV0 31:32:33:34:00:00:00:00
+ Verify CHV2
using the hex value
+ 31:32:33:34:00:00:00:00
+
verify CHV1 "secret"
+ Verify CHV1
+ using the string value secret
.
+
verify KEY2
+ Verify KEY2
,
+ get the value from the card reader's pin pad.
+
open
| close
}
+ Calls the card's open
or close
Secure Messaging handler.
+
opensc-notify — monitor smart card events and send notifications +
opensc-notify
[OPTIONS
]
+ The opensc-notify utility is used to + monitor smart card events and send the appropriate notification. +
+
--help
,
+ -h
Print help and exit.
--version
,
- -V
+ -V
Print version and exit.
+
+ Send customized notifications. +
--title
[STRING
],
+ -t
[STRING
]
- Print the version of the utility and exit. + Specify the title of the notification.
--verbose
,
- -v
+ --message
[STRING
],
+ -m
[STRING
]
- Verbose operation. Use several times to enable debug output. + Specify the main text of the notification. +
opensc-tool — generic smart card utility
opensc-tool
[OPTIONS
]
The opensc-tool utility can be used from the command line to perform miscellaneous smart card operations such as getting the card ATR or sending arbitrary APDU commands to a card. -
--version
,
Print the OpenSC package release version.
num
is an ATR, the
reader with a matching card will be chosen.
--reset
[=type
],
+ --reset
[type
],
Resets the card in reader.
- The default reset type is cold
, but warm reset is also possible.
cold
,
+ but warm
reset is also possible.--send-apdu
apdu
,
-s
apdu
Sends an arbitrary APDU to the card in the format @@ -701,236 +1087,16 @@ to enable debug output in the opensc library.
--wait
,
-w
Wait for a card to be inserted.
-
opensc-explorer — - generic interactive utility for accessing smart card - and similar security token functions -
opensc-explorer
[OPTIONS
] [SCRIPT
]
- The opensc-explorer 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. -
- The following are the command-line options for - opensc-explorer. There are additional - interactive commands available once it is running. -
--card-driver
driver
,
- -c
driver
- - Use the given card driver. The default is - auto-detected. -
--mf
path
,
- -m
path
-
- Select the file referenced by the given path on
- startup. The default is the path to the standard master file,
- 3F00. If path
is empty (e.g. opensc-explorer
- --mf ""), then no file is explicitly selected.
-
--reader
num
,
- -r
num
-
- Specify the reader to use. By default, the first
- reader with a present card is used. If
- num
is an ATR, the
- reader with a matching card will be chosen.
-
--verbose
, -v
- - Causes opensc-explorer to be more - verbose. Specify this flag several times to enable - debug output in the opensc library. -
--wait
, -w
- Wait for a card to be inserted
-
- The following commands are supported at opensc-explorer's
- interactive prompt or in script files passed via the command line parameter
- SCRIPT
.
-
hex-data
- Send a custom APDU command hex-data
.
file-id
- Parse and print the ASN.1 encoded content of the file specified by
- file-id
.
file-id
| sfi:short-id
]
- Print the contents of the currently selected EF or the contents
- of a file specified by file-id
or the short file id
- short-id
.
-
file-id
| aid:DF-name
}
-
- 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 file-id
, which must be a DF directly
- beneath the current DF, then change to that DF.
- If it is an application identifier given as
- aid:
DF-name
,
- then jump to the MF of the application denoted by
- DF-name
.
-
pin-ref
[[old-pin
] new-pin
]
- Change a PIN, where pin-ref
is the PIN reference.
- Examples: -
change CHV2 00:00:00:00:00:00 "foobar"
- Change PIN CHV2
- to the new value foobar
,
- giving the old value 00:00:00:00:00:00
.
-
change CHV2 "foobar"
- Set PIN CHV2
- to the new value foobar
.
-
change CHV2
- Change PIN CHV2
using the card reader's pinpad.
-
-
file-id
size
- Create a new EF. file-id
specifies the
- id number and size
is the size of the new file.
-
level
]
- Set OpenSC debug level to level
.
If level
is omitted the current debug level will be shown.
file-id
- Remove the EF or DF specified by file-id
hex-tag
[output
]
- Copy the internal card's 'tagged' data into the local file.
The local file is specified by output
while the tag of
- the card's data is specified by hex-tag
.
-
- If output
is omitted, the name of the output file will be
- derived from hex-tag
.
-
hex-tag
input
- Update internal card's 'tagged' data.
hex-tag
is the tag of the card's data.
- input
is the filename of the source file or the literal data presented as
- a sequence of hexadecimal values or "
enclosed string.
-
string
...
- Print the string
s given.
Erase the card, if the card supports it.
file-id
[output
]
- Copy an EF to a local file. The local file is specified
- by output
while the card file is specified by file-id
.
-
- If output
is omitted, the name of the output file will be
- derived from the full card path to file-id
.
-
file-id
]
- Display attributes of a file specified by file-id
.
- If file-id
is not supplied,
- the attributes of the current file are printed.
pattern
...]
- List files in the current DF.
- If no pattern
is given, then all files are listed.
- If one ore more pattern
s are given, only files matching
- at least one pattern
are listed.
start-id
[end-id
]]
- Find all files in the current DF.
- Files are found by selecting all file identifiers in the range from start-fid
to end-fid
(by default from 0000 to FFFF).
start-tag
[end-tag
]]
- Find all tags of data objects in the current context.
- Tags are found by using GET DATA in the range from start-tag
to end-tag
(by default from 0000 to FFFF).
file-id
size
- Create a DF. file-id
specifies the id number
- and size
is the size of the new file.
file-id
input
- Copy a local file to the card. The local file is specified
- by input
while the card file is specified by file-id
.
-
Exit the program.
count
- Generate random sequence of count
bytes.
file-id
- Remove the EF or DF specified by file-id
pin-ref
[puk
[new pin
]]
-
- Unblock the PIN denoted by pin-ref
- using the PUK puk
, and set potentially
- change its value to new pin
.
-
- 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's pin pad.
-
- Examples: -
unblock CHV2 00:00:00:00:00:00 "foobar"
- Unblock PIN CHV2
using PUK
- 00:00:00:00:00:00
- and set it to the new value foobar
.
-
unblock CHV2 00:00:00:00:00:00 ""
- Unblock PIN CHV2
using PUK
- 00:00:00:00:00:00
keeping the old value.
-
unblock CHV2 "" "foobar"
- Set new value of PIN CHV2
- to foobar
.
-
unblock CHV2 00:00:00:00:00:00
- Unblock PIN CHV2
using PUK
- 00:00:00:00:00:00
.
- The new PIN value is prompted by pinpad.
-
unblock CHV2 ""
- Set PIN CHV2
.
- The new PIN value is prompted by pinpad.
-
unblock CHV2
- Unblock PIN CHV2
.
- The unblock code and new PIN value are prompted by pinpad.
-
-
file-id
offs
data
- Binary update of the file specified by
- file-id
with the literal data
- data
starting from offset specified
- by offs
.
data
can be supplied as a sequencer
- of the hex values or as a "
enclosed string.
file-id
rec-nr
rec-offs
data
- Update record specified by rec-nr
of the file
- specified by file-id
with the literal data
- data
starting from offset specified by
- rec-offs
.
data
can be supplied as a sequence of the hex values or
- as a "
enclosed string.
key-type
key-id
[key
]
- Present a PIN or key to the card, where
- key-type
can be one of CHV
,
- KEY
, AUT
or PRO
.
- key-id
is a number representing the key or PIN reference.
- key
is the key or PIN to be verified, formatted as a
- colon-separated list of hex values or a "
enclosed string.
-
- If key
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.
-
- Examples: -
verify CHV0 31:32:33:34:00:00:00:00
- Verify CHV2
using the hex value
- 31:32:33:34:00:00:00:00
-
verify CHV1 "secret"
- Verify CHV1
- using the string value secret
.
-
verify KEY2
- Verify KEY2
,
- get the value from the card reader's pin pad.
-
-
[open]
|[close]
- Calls the card's open
or close
Secure Messaging handler.
-
piv-tool — smart card utility for HSPD-12 PIV cards
piv-tool
[OPTIONS
]
The piv-tool utility can be used from the command line to perform miscellaneous smart card operations on a HSPD-12 PIV smart card as defined in NIST 800-73-3. It is intended for use with test cards only. It can be used to load objects, and generate key pairs, as well as send arbitrary APDU commands to a card after having authenticated to the card using the card key provided by the card vendor. -
--serial
Print the card serial number derived from the CHUID object, @@ -1016,16 +1182,16 @@ to enable debug output in the opensc library.
Causes piv-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
-
pkcs11-tool — utility for managing and using PKCS #11 security tokens
pkcs11-tool
[OPTIONS
]
pkcs11-tool — utility for managing and using PKCS #11 security tokens
pkcs11-tool
[OPTIONS
]
The pkcs11-tool utility is used to manage the data objects on smart cards and similar PKCS #11 security tokens. Users can list and read PINs, keys and certificates stored on the token. User PIN authentication is performed for those operations that require it. -
--attr-from
filename
Extract information from filename
@@ -1250,7 +1416,7 @@ to enable debug output in the opensc library.
--generate-random
num
Get num
bytes of random data.
-
To list all certificates on the smart card:
pkcs11-tool --list-objects --type cert
@@ -1266,13 +1432,13 @@ to enable debug output in the opensc library.
using the private key with ID ID
and
using the RSA-PKCS mechanism:
pkcs11-tool --sign --id ID --mechanism RSA-PKCS --input-file data --output-file data.sig
-
pkcs15-crypt — perform crypto operations using PKCS#15 smart cards
pkcs15-crypt
[OPTIONS
]
pkcs15-crypt — perform crypto operations using PKCS#15 smart cards
pkcs15-crypt
[OPTIONS
]
The pkcs15-crypt utility can be used from the command line to perform cryptographic operations such as computing digital signatures or decrypting data, using keys stored on a PKCS#15 compliant smart card. -
--version
,
Print the OpenSC package release version.
Causes pkcs15-crypt to be more verbose. Specify this flag several times to enable debug output in the OpenSC library.
-
pkcs15-init — smart card personalization utility
pkcs15-init
[OPTIONS
]
The pkcs15-init utility can be used to create a PKCS #15 structure on a smart card, and add key or certificate objects. Details of the structure that will be created are controlled via profiles.
The profile used by default is pkcs15. Alternative
profiles can be specified via the -p
switch.
-
pkcs15-init can be used to create a PKCS #15 structure on
your smart card, create PINs, and install keys and certificates on the card.
This process is also called personalization
.
@@ -1412,7 +1578,7 @@ to enable debug output in the opensc library.
are protected and cannot be parsed without authentication (usually with User PIN).
This authentication need to be done immediately after the card binding.
In such cases --verify-pin
has to be used.
-
This is the first step during card personalization, and will create the basic files on the card. To create the initial PKCS #15 structure, invoke the utility as
@@ -1422,7 +1588,7 @@ to enable debug output in the opensc library.
If the card supports it, you should erase the contents of the card with pkcs15-init --erase-card before creating the PKCS#15 structure. -
Before installing any user objects such as private keys, you need at least one PIN to protect these objects. you can do this using
@@ -1436,7 +1602,7 @@ to enable debug output in the opensc library.
To set a label for this PIN object (which can be used by applications to display
a meaningful prompt to the user), use the --label
command line option.
-
pkcs15-init lets you generate a new key and store it on the card. You can do this using:
@@ -1454,7 +1620,7 @@ to enable debug output in the opensc library.
In addition to storing the private portion of the key on the card, pkcs15-init will also store the the public portion of the key as a PKCS #15 public key object. -
You can use a private key generated by other means and upload it to the card.
For instance, to upload a private key contained in a file named
okir.pem
, which is in PEM format, you would use
@@ -1478,7 +1644,7 @@ to enable debug output in the opensc library.
a file. A PKCS #12 file usually contains the X.509 certificate corresponding to the private key. If that is the case, pkcs15-init will store the certificate instead of the public key portion. -
You can also upload individual public keys to the card using the
--store-public-key
option, which takes a filename as an
argument. This file is supposed to contain the public key. If you don't
@@ -1489,12 +1655,12 @@ to enable debug output in the opensc library.
Since the corresponding public keys are always uploaded automatically when generating a new key, or when uploading a private key, you will probably use this option only very rarely. -
You can upload certificates to the card using the
--store-certificate
option, which takes a filename as
an argument. This file is supposed to contain the PEM encoded X.509
certificate.
-
Most browsers nowadays use PKCS #12 format files when you ask them to export your key and certificate to a file. pkcs15-init is capable of parsing these files, and storing their contents on the @@ -1508,7 +1674,7 @@ to enable debug output in the opensc library.
and protect it with the PIN referenced by authentication ID 01
.
It will also store any X.509 certificates contained in the file, which is
usually the user certificate that goes with the key, as well as the CA certificate.
-
You can use a secret key generated by other means and upload it to the card. For instance, to upload an AES-secret key generated by the system random generator you would use @@ -1517,7 +1683,7 @@ to enable debug output in the opensc library.
By default a random ID is generated for the secret key. You may specify an ID
with the --id
if needed.
-
--version
,
Print the OpenSC package release version.
Display help message
-
pkcs15-tool — utility for manipulating PKCS #15 data structures - on smart cards and similar security tokens
pkcs15-tool
[OPTIONS
]
pkcs15-tool
[OPTIONS
]
The pkcs15-tool utility is used to manipulate the PKCS #15 data structures on smart cards and similar security tokens. Users can list and read PINs, keys and certificates stored on the token. User PIN authentication is performed for those operations that require it. -
sc-hsm-tool — smart card utility for SmartCard-HSM
sc-hsm-tool
[OPTIONS
]
The sc-hsm-tool utility can be used from the command line to perform extended maintenance tasks not available via PKCS#11 or other tools in the OpenSC package. It can be used to query the status of a SmartCard-HSM, initialize a device, generate and import Device Key Encryption Key (DKEK) shares and to wrap and unwrap keys. -
--initialize
,
-X
@@ -2086,16 +2252,16 @@ puk 87654321
Causes sc-hsm-tool to be more verbose. Specify this flag several times to enable debug output in the opensc library.
-
Create a DKEK share:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe
Create a DKEK share with random password split up using a (3, 5) threshold scheme:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5
Initialize SmartCard-HSM to use a single DKEK share:
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken
Import DKEK share:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
Wrap referenced key, description and certificate:
sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
Unwrap key into same or in different SmartCard-HSM with the same DKEK:
sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force
Create a DKEK share:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe
Create a DKEK share with random password split up using a (3, 5) threshold scheme:
sc-hsm-tool --create-dkek-share dkek-share-1.pbe --pwd-shares-threshold 3 --pwd-shares-total 5
Initialize SmartCard-HSM to use a single DKEK share:
sc-hsm-tool --initialize --so-pin 3537363231383830 --pin 648219 --dkek-shares 1 --label mytoken
Import DKEK share:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe
Import DKEK share using a password split up using a (3, 5) threshold scheme for encryption:
sc-hsm-tool --import-dkek-share dkek-share-1.pbe --pwd-shares-total 3
Wrap referenced key, description and certificate:
sc-hsm-tool --wrap-key wrap-key.bin --key-reference 1 --pin 648219
Unwrap key into same or in different SmartCard-HSM with the same DKEK:
sc-hsm-tool --unwrap-key wrap-key.bin --key-reference 10 --pin 648219 --force
westcos-tool — utility for manipulating data structures - on westcos smart cards
westcos-tool
[OPTIONS
]
westcos-tool
[OPTIONS
]
The westcos-tool 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. -
--change-pin
,
-n
@@ -2164,6 +2330,7 @@ puk 87654321
-u
Unblocks a PIN stored on the card. Knowledge of the PIN Unblock Key (PUK) is required for this operation.
--verbose
-v
Causes westcos-tool to be more
verbose. Specify this flag several times to enable debug output
@@ -2177,27 +2344,5 @@ puk 87654321
from disk to card.
On the card the file is written in filename
.
User authentication is required for this operation.
-
Table of Contents
pkcs15-profile — format of profile for pkcs15-init
- The pkcs15-init utility for PKCS #15 smart card - personalization is controlled via profiles. When starting, it will read two - such profiles at the moment, a generic application profile, and a card - specific profile. The generic profile must be specified on the command line, - while the card-specific file is selected based on the type of card detected. -
- The generic application profile defines general information about the card - layout, such as the path of the application DF, various PKCS #15 files within - that directory, and the access conditions on these files. It also defines - general information about PIN, key and certificate objects. Currently, there - is only one such generic profile, pkcs15.profile. -
- The card specific profile contains additional information required during - card initialization, such as location of PIN files, key references etc. - Profiles currently reside in @pkgdatadir@ -