https://github.com/fkemser/scwrapper
A collection of shell scripts to interactively initialize and manage certain smartcards, USB tokens, and hardware security modules (HSMs).
https://github.com/fkemser/scwrapper
hsm opensc piv pkcs11 pkcs15 security smartcard yubico yubikey
Last synced: 7 months ago
JSON representation
A collection of shell scripts to interactively initialize and manage certain smartcards, USB tokens, and hardware security modules (HSMs).
- Host: GitHub
- URL: https://github.com/fkemser/scwrapper
- Owner: fkemser
- License: gpl-3.0
- Created: 2024-02-25T20:23:52.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-07-31T21:36:49.000Z (10 months ago)
- Last Synced: 2025-08-01T00:05:02.228Z (10 months ago)
- Topics: hsm, opensc, piv, pkcs11, pkcs15, security, smartcard, yubico, yubikey
- Language: Shell
- Homepage:
- Size: 14.5 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![GNU GPL v3.0 License][license-shield]][license-url]
SCwrapper
A collection of shell scripts to initialize and manage certain smartcards, USB tokens, and hardware security modules (HSMs), either interactively or via command line.
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
- TL;DR
-
About The Project
-
Getting Started
- Prerequisites
- Mandatory
- Interactive Mode (optional)
- OpenSC PKCS#11 and SmartCard-HSM / Nitrokey HSM 2
- OpenSC PKCS#15
- Yubico YubiKey PIV
- PIN/PUK Letter (optional)
- Installation
- Usage
- Examples (Script Mode)
- Help (Script Mode)
- Roadmap
- Contributing
- License
- Contact
- Acknowledgments
## TL;DR
### 1. Install dependencies
To install all (necessary and optional) packages on your system, simply run:
#### Debian
```sh
sudo apt install dialog gnutls-bin opensc opensc-pkcs11 openssl \
pcscd libccid ykcs11 yubikey-manager
```
Depending on your token type not all packages may be needed. For more information please have a look at the [prerequisites](#prerequisites) section below.
This project provides a [customizable LaTeX letter template](#pinpuk-letter-optional) that can be used to print token-related secrets like PIN, PUK, etc.
### 2. Clone the repo and run the script
```sh
git clone --recurse-submodules https://github.com/fkemser/SCwrapper.git && \
chmod +x ./SCwrapper/src/sc.sh && \
./SCwrapper/src/sc.sh
```
For more information please have a look at the [usage](#usage) and [examples](#examples-script-mode) section below.
## About The Project
This project provides a shell script to
- initialize a security token including setting secrets (PIN, PUK, etc.),
- print initial secrets by using a customizable letter template,
- import/export/delete certificates, keys, data objects from/to the token,
- generate public-private key pairs,
- change/reset/unblock PIN,
- and much more.
The script can be controlled either via command-line switches or via an interactive, `dialog`-based interface.
So far, this project supports the following security token:
- Smartcards and token that that are supported by [OpenSC (PKCS#11/PKCS#15)](https://github.com/OpenSC/OpenSC/wiki/Supported-hardware-%28smart-cards-and-USB-tokens%29)
- [SmartCard-HSM / Nitrokey HSM 2](https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM)
- [Yubico YubiKey PIV](https://developers.yubico.com/PIV/Introduction/)
> :information_source: Please note that this project cannot cover all token-specific actions and options. For very specific use cases you should use the tools provided by your token manufacturer.
### Built With
[![Shell Script][Shell Script-shield]][Shell Script-url]
[![LaTeX][LaTeX-shield]][LaTeX-url]
### Related Projects
This work includes or is based on other projects:
* [SHtemplate](https://github.com/fkemser/SHtemplate), a template for POSIX-/Bourne-Shell(sh) projects.
* [CUPSwrapper](https://github.com/fkemser/CUPSwrapper), a collection of shell scripts to interactively print and manage printers for local usage.
* [GerLaTeXLetter](https://github.com/fkemser/GerLaTeXLetter), a LaTeX template for business letters (mostly) following German DIN 5008 standard, based on KOMA-Script class `scrlttr2`.
* [TeXLetterCreator](https://github.com/fkemser/TeXLetterCreator), a collection of shell scripts to interactively create and print TeX-based form letters.
### Testing Environment
The project has been developed and tested on the following system:
| Info | Description
---: | ---
OS | Debian GNU/Linux 12 (bookworm)
Kernel | 5.15.133.1-microsoft-standard-WSL2
Packages | [coreutils (9.1-1)](https://packages.debian.org/bookworm/coreutils)
|| [dash (0.5.12-2)](https://packages.debian.org/bookworm/dash)
|| [dialog (1.3-20230209-1)](https://packages.debian.org/bookworm/dialog)
|| [libc-bin (2.36-9+deb12u3)](https://packages.debian.org/bookworm/libc-bin)
|| [gnutls-bin (3.7.9-2+deb12u2)](https://packages.debian.org/bookworm/gnutls-bin)
|| [libccid (1.5.2-1)](https://packages.debian.org/bookworm/libccid)
|| [opensc (0.23.0-0.3+deb12u1)](https://packages.debian.org/bookworm/opensc)
|| [opensc-pkcs11 (0.23.0-0.3+deb12u1)](https://packages.debian.org/bookworm/opensc-pkcs11)
|| [openssl (3.0.11-1~deb12u2)](https://packages.debian.org/bookworm/openssl)
|| [pcscd (1.9.9-2)](https://packages.debian.org/bookworm/pcscd)
|| [ykcs11 (2.2.0-1.1)](https://packages.debian.org/bookworm/ykcs11)
|| [yubikey-manager (4.0.9-1)](https://packages.debian.org/bookworm/yubikey-manager)
## Getting Started
### Prerequisites
Please make sure that the following dependencies are installed:
* [PCSClite](https://pcsclite.apdu.fr/)
* [USB PC/SC CCID driver](https://ccid.apdu.fr/)
Additionally, there are some use-case specific dependencies (see sections below):
* [Dialog](https://invisible-island.net/dialog/dialog.html)
* [GnuTLS](https://www.gnutls.org/)
* [OpenSC](https://github.com/OpenSC/OpenSC)
* [OpenSC (PKCS#11 module)](https://github.com/OpenSC/libp11)
* [OpenSSL](https://www.openssl.org/)
* [Yubico PIV tool (PKCS#11 module)](https://developers.yubico.com/yubico-piv-tool/)
* [YubiKey Manager](https://developers.yubico.com/yubikey-manager/)
### Mandatory
```
Packages: PCSClite, USB PC/SC CCID driver
Debian: > sudo apt install pcscd libccid
```
### Interactive Mode (optional)
In case you run this script interactively your terminal window must have a size of <100x30> or bigger.
````
Packages: Dialog
Debian: > sudo apt install dialog
````
### OpenSC PKCS#11 and SmartCard-HSM / Nitrokey HSM 2
````
Packages: GnuTLS, OpenSC, OpenSC (PKCS#11 module)
Debian: > sudo apt install gnutls-bin opensc opensc-pkcs11
````
### OpenSC PKCS#15
````
Packages: OpenSC
Debian: > sudo apt install opensc
````
### SmartCard-HSM / Nitrokey HSM 2
````
Packages: OpenSSL
Debian: > sudo apt install openssl
````
### Yubico YubiKey PIV
[PIV PIN-only mode](https://docs.yubico.com/yesdk/users-manual/application-piv/pin-only.html) is currently not supported.
````
Packages: GnuTLS, Yubico PIV tool (PKCS#11 module), YubiKey Manager
Debian: > sudo apt install gnutls-bin ykcs11 yubikey-manager
````
### PIN/PUK Letter (optional)
This project provides a **LaTeX letter template** (`/tex/sc.tex`), a modified version of [GerLaTeXLetter](https://github.com/fkemser/GerLaTeXLetter).
You can use this template for **priting token-related secrets like PIN, PUK, etc.**.
:warning: To use this feature **please follow all of the following setup instructions before continuing** :warning:
* [CUPSwrapper](https://github.com/fkemser/CUPSwrapper#prerequisites)
* [GerLaTeXLetter](https://github.com/fkemser/GerLaTeXLetter#prerequisites)
* [TeXLetterCreator](https://github.com/fkemser/TeXLetterCreator#prerequisites)
Afterwards, please install some **additional but required CTAN packages**
```sh
tlmgr install environ microtype pgf tcolorbox tikzfill trimspaces
```
**To customize the template** please edit the files within the `/tex` folder. For more information please have a look at [GerLaTeXLetter](https://github.com/fkemser/GerLaTeXLetter#customization). The instructions for `letter.tex` also apply to `sc.tex`.
### Installation
1. Make sure that your environment meets the [requirements](#prerequisites).
2. Clone the repo
```sh
git clone --recurse-submodules https://github.com/fkemser/SCwrapper.git
```
2. Edit the repository configuration file. In case it is empty just keep it as it is, **do not delete it**.
```sh
nano ./SCwrapper/etc/sc.cfg.sh
```
## Usage
To call the script **interactively**, run `/src/sc.sh` (without further arguments) from your terminal.
For **script mode** run `/src/sc.sh` followed by a list of arguments `--arg1 [] --arg2 [] ...`, see also [help](#help-script-mode) section below.
## Examples (Script Mode)
[1. Initialize token](#1-initialize-token)
[2. Generate public-private key pair](#2-generate-public-private-key-pair)
[3. Import certificate / key / data object](#3-import-certificate--key--data-object)
[4. Export certificate / data object](#4-export-certificate--data-object)
[5. Delete certificate / key / data object](#5-delete-certificate--key--data-object)
[6. PIN Management (Change/Reset/Unblock)](#6-pin-management-changeresetunblock)
[7. Backup and restore private key (SmartCard-HSM / Nitrokey HSM 2 only)](#7-backup-and-restore-private-key-smartcard-hsm--nitrokey-hsm-2-only)
### 1. Initialize token
```sh
export pin="1111"
export puk="123456"
export sopin="123456"
export sopuk="123456"
export password="secret"
export mgmtkey="010203040506070801020304050607080102030405060708"
```
#### OpenSC PKCS#11 ('-T opensc-p11')
```sh
./sc.sh -T opensc-p11 --initialize --label mytoken --pin env:pin --so-pin env:sopin
```
#### OpenSC PKCS#15 ('-T opensc-p15')
```sh
# Step 1 - Erase PKCS#15 structure (certain models only)
./sc.sh -T opensc-p15 --erase-card
# Step 2 - Initialize token (all models)
# Token supports a separate SO-PIN/SO-PUK pair
./sc.sh -T opensc-p15 --initialize --pin env:pin --puk env:puk --so-pin env:sopin --so-puk env:sopuk
# Token only supports one PIN/PUK pair
./sc.sh -T opensc-p15 --initialize --opensc-p15-profile pkcs15+onepin --pin env:pin --puk env:puk
# Step 3 - Finish initialization (certain models only)
./sc.sh -T opensc-p15 --finalize
```
#### SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
```sh
# Initialize without any DKEK (= key backup/restore disabled)
./sc.sh -T schsm --initialize --pin env:pin --so-pin env:sopin
# Initialize with 1 DKEK share, with a single password (no threshold scheme)
./sc.sh -T schsm --initialize --pin env:pin --so-pin env:sopin --schsm-dkek-shares 1
./sc.sh -T schsm --schsm-dkek-share-create dkek-share-1.pbe --password env:password
./sc.sh -T schsm --schsm-dkek-share-import dkek-share-1.pbe
# Initialize with 1 DKEK share and a 2-of-4 threshold scheme
./sc.sh -T schsm --initialize --pin env:pin --so-pin env:sopin --schsm-dkek-shares 1
./sc.sh -T schsm --schsm-dkek-share-create dkek-share-1.pbe --schsm-pwd-shares-threshold 2 --schsm-pwd-shares-total 4
./sc.sh -T schsm --schsm-dkek-share-import dkek-share-1.pbe --schsm-pwd-shares-total 2
```
#### Yubico YubiKey PIV ('-T yubico')
```sh
./sc.sh -T yubico --initialize --pin env:pin --puk env:puk --yubico-management-key env:mgmtkey
```
### 2. Generate public-private key pair
#### OpenSC PKCS#11 ('-T opensc-p11') and SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
```sh
./sc.sh -T <...> --keypairgen --id 10 --key-type rsa:2048
./sc.sh -T <...> --keypairgen --label mykey --key-type rsa:2048
```
#### OpenSC PKCS#15 ('-T opensc-p15')
```sh
./sc.sh -T opensc-p15 --keypairgen --id 10 --key-type rsa/2048
./sc.sh -T opensc-p15 --keypairgen --label mykey --key-type rsa/2048
```
#### Yubico YubiKey PIV ('-T yubico')
```sh
./sc.sh -T yubico --keypairgen "pubkey.pem" --format pem --piv-slot 9A --key-type RSA2048
```
### 3. Import certificate / key / data object
#### OpenSC PKCS#11 ('-T opensc-p11') and SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
```sh
./sc.sh -T <...> --import cert.der --type cert --id 10 --label mycert
./sc.sh -T <...> --import key.der --type privkey --id 20 --label mykey
./sc.sh -T <...> --import data.file --type data --id 30 --label mydata
```
#### OpenSC PKCS#15 ('-T opensc-p15')
```sh
./sc.sh -T opensc-p15 --import cert.pem --type cert --id 10 --label mycert
./sc.sh -T opensc-p15 --import cert.der --type cert --id 10 --label mycert --format der
./sc.sh -T opensc-p15 --import key.pem --type privkey --id 20 --label mykey
./sc.sh -T opensc-p15 --import key.p12 --type privkey --id 20 --label mykey --format pkcs12
./sc.sh -T opensc-p15 --import data.file --type data --label mydata
```
#### Yubico YubiKey PIV ('-T yubico')
```sh
./sc.sh -T yubico --import cert.pem --type cert --piv-slot 9A --format pem
./sc.sh -T yubico --import key.der --type privkey --piv-slot 9A --format der
./sc.sh -T yubico --import data.file --type data --piv-id 5FC108
```
### 4. Export certificate / data object
#### OpenSC PKCS#11 ('-T opensc-p11') and SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
```sh
./sc.sh -T <...> --export cert.der --type cert ( --id 10 | --label mycert )
./sc.sh -T <...> --export data.file --type data --label mydata
```
#### OpenSC PKCS#15 ('-T opensc-p15')
```sh
./sc.sh -T opensc-p15 --export cert.der --type cert --id 10
./sc.sh -T opensc-p15 --export data.file --type data --label mydata
```
#### Yubico YubiKey PIV ('-T yubico')
```sh
./sc.sh -T yubico --export cert.der --type cert --piv-slot 9A --format der
./sc.sh -T yubico --export cert.pem --type cert --piv-slot 9A --format pem
./sc.sh -T yubico --export data.file --type data --piv-id 5FC108
```
### 5. Delete certificate / key / data object
#### OpenSC PKCS#11 ('-T opensc-p11') and SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
```sh
./sc.sh -T <...> --delete --type cert ( --id 10 | --label mycert )
./sc.sh -T <...> --delete --type privkey ( --id 20 | --label mykey )
./sc.sh -T <...> --delete --type data --label mydata --data-application-name
./sc.sh -T <...> --delete --type data --data-oid
```
#### OpenSC PKCS#15 ('-T opensc-p15')
```sh
./sc.sh -T opensc-p15 --delete --type cert --id 10
./sc.sh -T opensc-p15 --delete --type privkey --id 20
./sc.sh -T opensc-p15 --delete --type data --label mydata --data-application-name
./sc.sh -T opensc-p15 --delete --type data --data-oid
```
#### Yubico YubiKey PIV ('-T yubico')
```sh
./sc.sh -T yubico --delete --type cert --piv-slot 9A
```
### 6. PIN Management (Change/Reset/Unblock)
```sh
export oldpin="1111"
export newpin="2222"
export puk="123456"
export sopin="123456"
./sc.sh -T <...> --change-pin --pin env:oldpin --new-pin env:newpin
./sc.sh -T <...> --reset-pin --so-pin env:sopin --new-pin env:newpin
./sc.sh -T <...> --unblock-pin --puk env:puk --new-pin env:newpin
```
### 7. Backup and restore private key (SmartCard-HSM / Nitrokey HSM 2 only)
```sh
./sc.sh -T schsm --schsm-backup wrap-key.bin --schsm-key-reference 1
./sc.sh -T schsm --schsm-restore wrap-key.bin --schsm-key-reference 10
```
## Help (Script Mode)
To get help, run `./SCwrapper/src/sc.sh -h`.
```sh
================================================================================
=============================== SYNOPSIS ===============================
================================================================================
There are multiple ways to run this script:
Interactive mode (without any args):
> ./sc.sh
Classic (script) mode:
> ./sc.sh [ OPTION ]... ACTION
OpenSC PKCS#11 ./sc.sh [ -T opensc-p11 ] [ OPTION ]... ACTION
(default)
ACTION := { -h|--help | --change-pin | --change-so-pin |
--connect | --delete | --export | --get |
--import | --initialize | --keypairgen [] |
--list | --p11-get-uri | --reset-pin }
OPTION := { [--data-application-name ] |
[--data-oid ] | [-f|--format ] | [-i|--id
] | [--key-type ] | [-l|--label ] |
[-n|--new-pin|--new-puk| --new-so-pin ] |
[--password ] | [-p|--pin ] | [-P|--puk ]
| [-r|--reader ] | [-s|--so-pin ] |
[-S|--so-puk ] | [-t|--type ] }
OpenSC PKCS#15 ./sc.sh -T opensc-p15 [ OPTION ]... ACTION
ACTION := { -h|--help | --change-pin | --change-puk |
--change-so-pin | --connect | --delete |
--erase-application | --erase-card | --export
| --finalize | --get | --import |
--initialize | --keypairgen [] | --list |
--store-pin | --unblock-pin }
OPTION := { [--data-application-name ] |
[--data-oid ] | [-f|--format ] | [-i|--id
] | [--key-type ] | [-l|--label ] |
[-n|--new-pin|--new-puk| --new-so-pin ] |
[--opensc-p15-profile ] | [--p15-aid ] |
[--p15-auth-id ] | [--password ] | [-p|--pin
] | [-P|--puk ] | [-r|--reader ] |
[-s|--so-pin ] | [-S|--so-puk ] |
[-t|--type ] }
SmartCard-HSM / ./sc.sh -T schsm [ OPTION ]... ACTION
Nitrokey HSM 2
ACTION := { -h|--help | --change-pin | --change-so-pin |
--connect | --delete | --export | --get |
--import | --initialize | --keypairgen [] |
--list | --p11-get-uri | --reset-pin |
--schsm-backup | --schsm-dkek-share-create
| --schsm-dkek-share-import | --schsm-restore
}
OPTION := { [-F|--force] | [-f|--format ] |
[-i|--id ] | [--key-type ] | [-l|--label
] | [-n|--new-pin|--new-puk| --new-so-pin ]
| [--password ] | [-p|--pin ] | [-P|--puk
] | [-r|--reader ] | [--schsm-dkek-shares
] | [--schsm-key-reference ] |
[--schsm-pwd-shares-threshold ] |
[--schsm-pwd-shares-total ] | [-s|--so-pin ] | [-S|--so-puk ] | [-t|--type ] }
Yubico YubiKey PIV ./sc.sh -T yubico [ OPTION ]... ACTION
ACTION := { -h|--help | --change-management-key |
--change-pin | --change-puk | --connect | --delete |
--export | --get | --import |
--initialize | --keypairgen [] | --list |
--p11-get-uri | --unblock-pin }
OPTION := { [-F|--force] | [-f|--format ] |
[--key-type ] | [-n|--new-pin|--new-puk|
--new-so-pin ] | [--password ] | [-p|--pin
] | [--piv-id ] | [--piv-slot ] | [-P|--puk
] | [--serial ] | [-s|--so-pin ]
| [-S|--so-puk ] | [-t|--type ] |
[--yubico-management-key ] |
[--yubico-new-management-key ] |
[--yubico-pin-policy ] | [--yubico-touch-policy
] }
--------------------------------------------------------------------------------
-------------------------------- ACTION --------------------------------
--------------------------------------------------------------------------------
__________________________ Miscellaneous Token Types ___________________________
Some actions are only allowed with certain token types, see type-specific action lists above.
--change-pin Change user PIN (requires user PIN). See also
'-p|--pin ' and '-n|--new-pin|--new-puk|
--new-so-pin '.
--change-puk Change user PUK. Only with '-T opensc-p15' or '-T
yubico'. See also '-P|--puk ' and
'-n|--new-pin|--new-puk|
--new-so-pin '.
--change-so-pin Change security officer PIN (SO-PIN). Only with '-T
opensc-p11', '-T opensc-p15', or '-T schsm'. See also
'-s|--so-pin ' and '-n|--new-pin|--new-puk|
--new-so-pin '.
--connect Prompt the user interactively to connect a token.
Returns '0' (token connected) or '1' (no token found).
--delete Delete a certificate, key, or data object on the
token. Object type must be specified using '-t|--type
'.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
***** OpenSC PKCS#15 ('-T opensc-p15') *****
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
Use '-p|--pin ' or '-s|--so-pin ' to
specify the PIN or SO-PIN to use.
= data
Use '--data-oid ' or '--data-application-name
' and '-l|--label ' to specify the data
object to delete.
!= data
Use '-i|--id ' and/or '-l|--label ' (not
with '-T opensc-p15') to specify the object to delete.
= { cert | data | privkey | pubkey | secrkey }
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Use '--p15-aid ' to specify the target
application when using multi-application cards.
= { cert | chain | data | privkey | pubkey |
secrkey }
***** Yubico YubiKey PIV ('-T yubico') *****
Use '--piv-slot ' to specify the PIV slot to
operate on. Use '--yubico-management-key ' to
specify the current management key.
= { cert }
--export Export a certificate, public key, or data object from
the token to a . Object type must be specified
using '-t|--type '.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
***** OpenSC PKCS#15 ('-T opensc-p15') *****
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
= data
Use '-l|--label ', '--data-oid ' or
'--data-application-name ' to specify the data
object to export.
!= data
Use '-i|--id ' and/or '-l|--label ' (not
with '-T opensc-p15') to specify the object to export.
= { cert | data | pubkey }
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Use '-p|--pin ' or '-s|--so-pin ' to
specify the PIN or SO-PIN to use (only if =
data). Use '--p15-aid ' to specify the target
application when using multi-application cards.
= { cert | data | pubkey | sshkey |
sshkey-rfc4716 }
***** Yubico YubiKey PIV ('-T yubico') *****
Use '-f|--format ' to specify the
certificate/key format. Use '--piv-slot ' to
specify the PIV slot to operate on (only if =
{ cert | pubkey }). Use '--piv-id ' to specify
the PIV object id (BER-TLV tag) to use (only if
= data). Use '-p|--pin ' to specify the
PIN to use (only if = { data | pubkey }).
= { cert | data | pubkey }
--get Get information about the smartcard or its reader.
Exactly one (1) token must be connected at that time.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
***** Yubico YubiKey PIV ('-T yubico') *****
= { reader | smartcard |
smartcard-manufacturer | smartcard-model |
smartcard-serial }
***** OpenSC PKCS#15 ('-T opensc-p15') *****
= { reader | smartcard | smartcard-model |
smartcard-serial }
--import Import a certificate, key, or data object from a
to the token. Object type must be specified
using '-t|--type '. For password-protected
files use '--password ' to specify/set the
password.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
Object must be specified via '-i|--id ' and/or
'-l|--label '. must be DER-encoded. To
convert from PEM to DER format, just run 'openssl
x509 -in .pem -out .der -outform
der'. Use '-p|--pin ' to specify the PIN to use.
= data
Optionally use '--data-oid ' to specify the data
object's identifier (OID). Optionally use
'--data-application-name ' to specify the data
object's application name.
= { cert | data | privkey | pubkey | secrkey }
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Use '-p|--pin ' or '-s|--so-pin ' to
specify the PIN or SO-PIN to use. Use '--p15-aid
' to specify the target application when using
multi-application cards.
= data
Optionally use '-l|--label ' to specify object
label (name). Optionally use '--data-oid ' to
specify the data object's identifier (OID).
Optionally use '--data-application-name ' to
specify the data object's application name.
!= data
Optionally use '-i|--id ' and/or '-l|--label
' to specify an object. Use '-f|--format
' to specify the certificate/key format.
= { cert | data | privkey | pubkey | secrkey }
***** Yubico YubiKey PIV ('-T yubico') *****
Use '-f|--format ' to specify the
certificate/key format. Use '--piv-slot ' to
specify the PIV slot to operate on (only if =
{ cert | privkey }). Use '--piv-id ' to specify
the PIV object id (BER-TLV tag) to use (only if
= data). Use '--yubico-management-key '
to specify the current management key.
= { cert | data | privkey }
--initialize Initialize token
***** OpenSC PKCS#11 ('-T opensc-p11') *****
Set token label, SO-PIN, and PIN. Object to create or
operate on must be specified via '-l|--label '.
Use '-p|--pin ' and '-s|--so-pin ' to
set PIN and SO-PIN.
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Create initial PKCS#15 data structure. Optionally use
'-l|--label ' to specify object label (name).
Use '-p|--pin ', '-P|--puk ', '-s|--so-pin
', and '-S|--so-puk ' to set PIN,
PUK, SO-PIN, and SO-PUK. Please note that certain
models only support one PIN/PUK pair but no
additional SO-PIN/SO-PUK.
Use '--opensc-p15-profile ' to specify the
OpenSC PKCS#15 profile to load during initialization,
e.g. 'pkcs15+onepin' in case your token only supports
one user PIN/PUK pair but no additional SO-PIN/SO-PUK.
With certain models it is necessary to run './sc.sh
--erase-card' before and/or './sc.sh --finalize'
after initialization.
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
Remove all existing keys, certificates and files. Use
it with '--schsm-dkek-shares ' to enable private
key backup/restore, this can not(!) be done at a
later stage.
Use '-p|--pin ' and '-s|--so-pin ' to
set PIN and SO-PIN.
***** Yubico YubiKey PIV ('-T yubico') *****
Wipe all PIV-related data and restore PIV application
to factory settings.
Use '-p|--pin ', '-P|--puk ', and
'--yubico-management-key ' to set PIN, PUK, and
management key.
--keypairgen [] Generate a public-private key pair. is only
possible (and mandatory) with '-T yubico'. Optionally
use '--key-type ' to specify key type/length.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
Object must be specified via '-i|--id ' and/or
'-l|--label '. Use '-p|--pin ' to specify
the PIN to use.
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Optionally use '-i|--id ' and/or '-l|--label
' to specify an object. Use '-p|--pin '
or '-s|--so-pin ' to specify the PIN or
SO-PIN to use. Use '--p15-aid ' to specify the
target application when using multi-application cards.
***** Yubico YubiKey PIV ('-T yubico') *****
It is mandatory to set to specify where the
(generated) public key should be saved to. Use
'-f|--format ' to specify the certificate/key
format. Use '--piv-slot ' to specify the PIV slot
to operate on. Use '--yubico-management-key ' to
specify the current management key.
--list List available objects, supported mechanisms, etc.
***** OpenSC PKCS#11 ('-T opensc-p11') *****
= { algorithm | object | reader }
***** OpenSC PKCS#15 ('-T opensc-p15') *****
Use '--p15-aid ' to specify the target
application when using multi-application cards.
= { algorithm | cert | data | info | object |
privkey | pubkey | reader | secrkey | p15-application
| p15-pin }
= { data | privkey | secrkey }
Use '-p|--pin ' or '-s|--so-pin ' to
specify the PIN or SO-PIN to use (certain models
only).
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm')
*****
= { algorithm | object | reader }
***** Yubico YubiKey PIV ('-T yubico') *****
= { algorithm | data | info | reader }
--p11-get-uri Interactively select a token object and get its
PKCS#11 URI. Only with '-T opensc-p11', '-T schsm',
or '-T yubico'. acts as an object filter,
possible values are:
all : All available objects
all-certs : All available certificates
certs : Only certificates that
have an associated
private key
privkeys : All available private keys
(default: 'all')
--reset-pin Reset user PIN (requires SO-PIN). Only with '-T
opensc-p11' or '-T schsm'. See also
'-n|--new-pin|--new-puk|
--new-so-pin ' and '-s|--so-pin '.
--unblock-pin Reset user PIN (requires user PUK). Only with '-T
opensc-p11', '-T opensc-p15', or '-T yubico'. See
also '-n|--new-pin|--new-puk|
--new-so-pin ' and '-P|--puk '.
________________________________ OpenSC PKCS#15 ________________________________
--erase-application Erase PKCS#15 application with the (hexadecimal)
application identifier , see also '--p15-aid
'. Use '-p|--pin ' or '-s|--so-pin ' to specify the PIN or SO-PIN to use.
--erase-card Erase PKCS#15 structure (certain models only).
Use '-p|--pin ' or '-s|--so-pin ' to
specify the PIN or SO-PIN to use.
--finalize Finish initialization (certain models only).
Depending on the model this may prevent you from
adding new private/secret keys and/or PIN/PUK
pairs. For further information please have a look
at OpenSC's model-specific wiki pages:
https://github.com/OpenSC/OpenSC/wiki
--store-pin Add another user PIN/PUK pair. Use '-p|--pin
' and '-P|--puk ' to set PIN and PUK.
Use '--p15-auth-id ' to specify the
hexadecimal auth id of PIN/PUK pair to
use/create. Optionally use '-l|--label '
to specify object label (name).
________________________ SmartCard-HSM / Nitrokey HSM 2 ________________________
--schsm-backup Export private key and store it in
(DKEK-encrypted). Use it with
'--schsm-key-reference ' to specify
the key (identifier) to use. Use '-p|--pin
' to specify the PIN to use.
--schsm-dkek-share-create Create an encrypted DKEK share and save it
into . Please print the file's
content on paper in case the file gets
corrupted. To get a printable version, run
'openssl base64 -in '.
Use '--password ' to specify an
encryption password, otherwise you will be
prompted for one.
Use '--schsm-pwd-shares-threshold '
and '--schsm-pwd-shares-total ' to
establish an n-of-m threshold scheme. Do
not(!) use '--password ' in this
case, you will be prompted for the
password shares. See also:
https://github.com/OpenSC/OpenSC/wiki/Smart
CardHSM#using-a-n-of-m-threshold-scheme
--schsm-dkek-share-import Decrypt and write DKEK share from
to the HSM.
Use '--password ' to specify the
decryption password, otherwise you will be
prompted for one.
Use it with '--schsm-pwd-shares-total
' in case your DKEK share requires
password shares to restore it. Do
not(!) use '--password ' in this
case, you will be prompted for the
password shares. See also:
https://github.com/OpenSC/OpenSC/wiki/Smart
CardHSM#using-a-n-of-m-threshold-scheme
--schsm-restore Restore private key from
(DKEK-encrypted). Use it with
'--schsm-key-reference ' to specify
the key reference to use. This mode
requires running './sc.sh --initialize
--schsm-dkek-shares