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
To install all (necessary and optional) packages on your system, simply run:
sudo apt install dialog gnutls-bin opensc opensc-pkcs11 openssl \
pcscd libccid ykcs11 yubikey-managerDepending on your token type not all packages may be needed. For more information please have a look at the prerequisites section below.
This project provides a customizable LaTeX letter template that can be used to print token-related secrets like PIN, PUK, etc.
git clone --recurse-submodules https://github.com/fkemser/SCwrapper.git && \
chmod +x ./SCwrapper/src/sc.sh && \
./SCwrapper/src/sc.shFor more information please have a look at the usage and examples section below.
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)
- SmartCard-HSM / Nitrokey HSM 2
- Yubico YubiKey PIV
ℹ️ 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.
This work includes or is based on other projects:
- SHtemplate, a template for POSIX-/Bourne-Shell(sh) projects.
- CUPSwrapper, a collection of shell scripts to interactively print and manage printers for local usage.
- GerLaTeXLetter, a LaTeX template for business letters (mostly) following German DIN 5008 standard, based on KOMA-Script class
scrlttr2. - TeXLetterCreator, a collection of shell scripts to interactively create and print TeX-based form letters.
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) |
| dash (0.5.12-2) | |
| dialog (1.3-20230209-1) | |
| libc-bin (2.36-9+deb12u3) | |
| gnutls-bin (3.7.9-2+deb12u2) | |
| libccid (1.5.2-1) | |
| opensc (0.23.0-0.3+deb12u1) | |
| opensc-pkcs11 (0.23.0-0.3+deb12u1) | |
| openssl (3.0.11-1~deb12u2) | |
| pcscd (1.9.9-2) | |
| ykcs11 (2.2.0-1.1) | |
| yubikey-manager (4.0.9-1) |
Please make sure that the following dependencies are installed:
Additionally, there are some use-case specific dependencies (see sections below):
Packages: PCSClite, USB PC/SC CCID driver
Debian: > sudo apt install pcscd libccid
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
Packages: GnuTLS, OpenSC, OpenSC (PKCS#11 module)
Debian: > sudo apt install gnutls-bin opensc opensc-pkcs11
Packages: OpenSC
Debian: > sudo apt install opensc
Packages: OpenSSL
Debian: > sudo apt install openssl
PIV PIN-only mode is currently not supported.
Packages: GnuTLS, Yubico PIV tool (PKCS#11 module), YubiKey Manager
Debian: > sudo apt install gnutls-bin ykcs11 yubikey-manager
This project provides a LaTeX letter template (/tex/sc.tex), a modified version of GerLaTeXLetter.
You can use this template for priting token-related secrets like PIN, PUK, etc..
Afterwards, please install some additional but required CTAN packages
tlmgr install environ microtype pgf tcolorbox tikzfill trimspacesTo customize the template please edit the files within the /tex folder. For more information please have a look at GerLaTeXLetter. The instructions for letter.tex also apply to sc.tex.
Make sure that your environment meets the requirements.
Clone the repo
git clone --recurse-submodules https://github.com/fkemser/SCwrapper.git
Edit the repository configuration file. In case it is empty just keep it as it is, do not delete it.
nano ./SCwrapper/etc/sc.cfg.sh
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 [<val1>] --arg2 [<val2>] ..., see also help section below.
1. Initialize token
2. Generate public-private key pair
3. Import certificate / key / data object
4. Export certificate / data object
5. Delete certificate / key / data object
6. PIN Management (Change/Reset/Unblock)
7. Backup and restore private key (SmartCard-HSM / Nitrokey HSM 2 only)
export pin="1111"export puk="123456"export sopin="123456"export sopuk="123456"export password="secret"export mgmtkey="010203040506070801020304050607080102030405060708"./sc.sh -T opensc-p11 --initialize --label mytoken --pin env:pin --so-pin env:sopin# 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# 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./sc.sh -T yubico --initialize --pin env:pin --puk env:puk --yubico-management-key env:mgmtkey./sc.sh -T <...> --keypairgen --id 10 --key-type rsa:2048
./sc.sh -T <...> --keypairgen --label mykey --key-type rsa:2048./sc.sh -T opensc-p15 --keypairgen --id 10 --key-type rsa/2048
./sc.sh -T opensc-p15 --keypairgen --label mykey --key-type rsa/2048./sc.sh -T yubico --keypairgen "pubkey.pem" --format pem --piv-slot 9A --key-type RSA2048./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./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./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./sc.sh -T <...> --export cert.der --type cert ( --id 10 | --label mycert )
./sc.sh -T <...> --export data.file --type data --label mydata./sc.sh -T opensc-p15 --export cert.der --type cert --id 10
./sc.sh -T opensc-p15 --export data.file --type data --label mydata./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./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 <name>
./sc.sh -T <...> --delete --type data --data-oid <oid>./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 <name>
./sc.sh -T opensc-p15 --delete --type data --data-oid <oid>./sc.sh -T yubico --delete --type cert --piv-slot 9Aexport 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./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 10To get help, run ./SCwrapper/src/sc.sh -h.
================================================================================
=============================== 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 <file>| --get <type>| --import <file>| --initialize | --keypairgen [<file>] | --list <type>| --p11-get-uri <type>| --reset-pin } OPTION := { [--data-application-name <name>] | [--data-oid <oid>] | [-f|--format <format>] | [-i|--id <id>] | [--key-type <type>] | [-l|--label <label>] | [-n|--new-pin|--new-puk| --new-so-pin <val>] | [--password <pwd>] | [-p|--pin <pin>] | [-P|--puk <puk>] | [-r|--reader <id>] | [-s|--so-pin <so pin>] | [-S|--so-puk <so puk>] | [-t|--type <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 <aid>| --erase-card | --export <file>| --finalize | --get <type>| --import <file>| --initialize | --keypairgen [<file>] | --list <type>| --store-pin | --unblock-pin } OPTION := { [--data-application-name <name>] | [--data-oid <oid>] | [-f|--format <format>] | [-i|--id <id>] | [--key-type <type>] | [-l|--label <label>] | [-n|--new-pin|--new-puk| --new-so-pin <val>] | [--opensc-p15-profile <profile>] | [--p15-aid <id>] | [--p15-auth-id <id>] | [--password <pwd>] | [-p|--pin <pin>] | [-P|--puk <puk>] | [-r|--reader <id>] | [-s|--so-pin <so pin>] | [-S|--so-puk <so puk>] | [-t|--type <type>] } SmartCard-HSM / ./sc.sh -T schsm [ OPTION ]... ACTION Nitrokey HSM 2 ACTION := { -h|--help | --change-pin | --change-so-pin | --connect | --delete | --export <file>| --get <type>| --import <file>| --initialize | --keypairgen [<file>] | --list <type>| --p11-get-uri <type>| --reset-pin | --schsm-backup <file>| --schsm-dkek-share-create <file>| --schsm-dkek-share-import <file>| --schsm-restore <file> } OPTION := { [-F|--force] | [-f|--format <format>] | [-i|--id <id>] | [--key-type <type>] | [-l|--label <label>] | [-n|--new-pin|--new-puk| --new-so-pin <val>] | [--password <pwd>] | [-p|--pin <pin>] | [-P|--puk <puk>] | [-r|--reader <id>] | [--schsm-dkek-shares <int>] | [--schsm-key-reference <id>] | [--schsm-pwd-shares-threshold <int>] | [--schsm-pwd-shares-total <int>] | [-s|--so-pin <so pin>] | [-S|--so-puk <so puk>] | [-t|--type <type>] } Yubico YubiKey PIV ./sc.sh -T yubico [ OPTION ]... ACTION ACTION := { -h|--help | --change-management-key | --change-pin | --change-puk | --connect | --delete | --export <file>| --get <type>| --import <file>| --initialize | --keypairgen [<file>] | --list <type>| --p11-get-uri <type>| --unblock-pin } OPTION := { [-F|--force] | [-f|--format <format>] | [--key-type <type>] | [-n|--new-pin|--new-puk| --new-so-pin <val>] | [--password <pwd>] | [-p|--pin <pin>] | [--piv-id <id>] | [--piv-slot <id>] | [-P|--puk <puk>] | [--serial <serial no>] | [-s|--so-pin <so pin>] | [-S|--so-puk <so puk>] | [-t|--type <type>] | [--yubico-management-key <key>] | [--yubico-new-management-key <key>] | [--yubico-pin-policy <pol>] | [--yubico-touch-policy <pol>] } --------------------------------------------------------------------------------
-------------------------------- 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 <pin>' and '-n|--new-pin|--new-puk| --new-so-pin <val>'. --change-puk Change user PUK. Only with '-T opensc-p15' or '-T yubico'. See also '-P|--puk <puk>' and '-n|--new-pin|--new-puk| --new-so-pin <val>'. --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 <so pin>' and '-n|--new-pin|--new-puk| --new-so-pin <val>'. --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 <type>'. ***** OpenSC PKCS#11 ('-T opensc-p11') ********** OpenSC PKCS#15 ('-T opensc-p15') ********** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm') ***** Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use. <type> = data Use '--data-oid <oid>' or '--data-application-name <name>' and '-l|--label <label>' to specify the data object to delete. <type>!= data Use '-i|--id <id>' and/or '-l|--label <label>' (not with '-T opensc-p15') to specify the object to delete.
<type> = { cert | data | privkey | pubkey | secrkey } ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-aid <id>' to specify the target application when using multi-application cards. <type> = { cert | chain | data | privkey | pubkey | secrkey } ***** Yubico YubiKey PIV ('-T yubico') ***** Use '--piv-slot <id>' to specify the PIV slot to operate on. Use '--yubico-management-key <key>' to specify the current management key. <type> = { cert } --export <file> Export a certificate, public key, or data object from the token to a <file>. Object type must be specified using '-t|--type <type>'. ***** OpenSC PKCS#11 ('-T opensc-p11') ********** OpenSC PKCS#15 ('-T opensc-p15') ********** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm') *****<type> = data Use '-l|--label <label>', '--data-oid <oid>' or '--data-application-name <name>' to specify the data object to export. <type>!= data Use '-i|--id <id>' and/or '-l|--label <label>' (not with '-T opensc-p15') to specify the object to export.
<type> = { cert | data | pubkey } ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use (only if<type> = data). Use '--p15-aid <id>' to specify the target application when using multi-application cards. <type> = { cert | data | pubkey | sshkey | sshkey-rfc4716 } ***** Yubico YubiKey PIV ('-T yubico') ***** Use '-f|--format <format>' to specify the certificate/key format. Use '--piv-slot <id>' to specify the PIV slot to operate on (only if<type> = { cert | pubkey }). Use '--piv-id <id>' to specify the PIV object id (BER-TLV tag) to use (only if<type> = data). Use '-p|--pin <pin>' to specify the PIN to use (only if<type> = { data | pubkey }). <type> = { cert | data | pubkey } --get <type> 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') *****<type> = { reader | smartcard | smartcard-manufacturer | smartcard-model | smartcard-serial } ***** OpenSC PKCS#15 ('-T opensc-p15') *****<type> = { reader | smartcard | smartcard-model | smartcard-serial } --import <file> Import a certificate, key, or data object from a <file> to the token. Object type must be specified using '-t|--type <type>'. For password-protected files use '--password <pwd>' 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 <id>' and/or '-l|--label <label>'. <file> must be DER-encoded. To convert from PEM to DER format, just run 'openssl x509 -in <file_in>.pem -out <file_out>.der -outform der'. Use '-p|--pin <pin>' to specify the PIN to use. <type> = data Optionally use '--data-oid <oid>' to specify the data object's identifier (OID). Optionally use '--data-application-name <name>' to specify the data object's application name. <type> = { cert | data | privkey | pubkey | secrkey } ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use. Use '--p15-aid <id>' to specify the target application when using multi-application cards. <type> = data Optionally use '-l|--label <label>' to specify object label (name). Optionally use '--data-oid <oid>' to specify the data object's identifier (OID). Optionally use '--data-application-name <name>' to specify the data object's application name. <type>!= data Optionally use '-i|--id <id>' and/or '-l|--label <label>' to specify an object. Use '-f|--format <format>' to specify the certificate/key format. <type> = { cert | data | privkey | pubkey | secrkey } ***** Yubico YubiKey PIV ('-T yubico') ***** Use '-f|--format <format>' to specify the certificate/key format. Use '--piv-slot <id>' to specify the PIV slot to operate on (only if<type> = { cert | privkey }). Use '--piv-id <id>' to specify the PIV object id (BER-TLV tag) to use (only if<type> = data). Use '--yubico-management-key <key>' to specify the current management key. <type> = { 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 <label>'.
Use '-p|--pin <pin>' and '-s|--so-pin <so pin>' to set PIN and SO-PIN. ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Create initial PKCS#15 data structure. Optionally use '-l|--label <label>' to specify object label (name). Use '-p|--pin <pin>', '-P|--puk <puk>', '-s|--so-pin <so pin>', and '-S|--so-puk <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 <profile>' to specify the OpenSC PKCS#15 profile to load during initialization, e.g. 'pkcs15+onepin'incase 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 <int>' to enable private key backup/restore, this can not(!) be done at a later stage. Use '-p|--pin <pin>' and '-s|--so-pin <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 <pin>', '-P|--puk <puk>', and '--yubico-management-key <key>' to set PIN, PUK, and management key. --keypairgen [<file>] Generate a public-private key pair. <file> is only possible (and mandatory) with '-T yubico'. Optionally use '--key-type <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 <id>' and/or '-l|--label <label>'. Use '-p|--pin <pin>' to specify the PIN to use. ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Optionally use '-i|--id <id>' and/or '-l|--label <label>' to specify an object. Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use. Use '--p15-aid <id>' to specify the target application when using multi-application cards.
***** Yubico YubiKey PIV ('-T yubico') ***** It is mandatory to set<file> to specify where the (generated) public key should be saved to. Use '-f|--format <format>' to specify the certificate/key format. Use '--piv-slot <id>' to specify the PIV slot to operate on. Use '--yubico-management-key <key>' to specify the current management key. --list <type> List available objects, supported mechanisms, etc. ***** OpenSC PKCS#11 ('-T opensc-p11') *****<type> = { algorithm | object | reader } ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-aid <id>' to specify the target application when using multi-application cards. <type> = { algorithm | cert | data | info | object | privkey | pubkey | reader | secrkey | p15-application | p15-pin } <type> = { data | privkey | secrkey } Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use (certain models only). ***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm') *****<type> = { algorithm | object | reader } ***** Yubico YubiKey PIV ('-T yubico') *****<type> = { algorithm | data | info | reader } --p11-get-uri <type> Interactively selecta token object and get its PKCS#11 URI. Only with '-T opensc-p11', '-T schsm', or '-T yubico'. <type> 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 <val>' and '-s|--so-pin <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 <val>' and '-P|--puk <puk>'. ________________________________ OpenSC PKCS#15 ________________________________
--erase-application <aid> Erase PKCS#15 application with the (hexadecimal) application identifier <aid>, see also '--p15-aid <id>'. Use '-p|--pin <pin>' or '-s|--so-pin <so pin>' to specify the PIN or SO-PIN to use. --erase-card Erase PKCS#15 structure (certain models only). Use '-p|--pin <pin>' or '-s|--so-pin <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 <pin>' and '-P|--puk <puk>' to set PIN and PUK. Use '--p15-auth-id <id>' to specify the hexadecimal auth id of PIN/PUK pair to use/create. Optionally use '-l|--label <label>' to specify object label (name). ________________________ SmartCard-HSM / Nitrokey HSM 2 ________________________--schsm-backup <file> Export private key and store it in <file> (DKEK-encrypted). Use it with '--schsm-key-reference <id>' to specify the key (identifier) to use. Use '-p|--pin <pin>' to specify the PIN to use. --schsm-dkek-share-create <file> Create an encrypted DKEK share and save it into <file>. Please print the file's content on paper incase the file gets corrupted. To get a printable version, run 'openssl base64 -in <file>'. Use '--password <pwd>' to specify an encryption password, otherwise you will be prompted for one. Use '--schsm-pwd-shares-threshold <int>' and '--schsm-pwd-shares-total <int>' to establish an n-of-m threshold scheme. Do not(!) use '--password <pwd>'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 <file> Decrypt and write DKEK share from <file> to the HSM. Use '--password <pwd>' to specify the decryption password, otherwise you will be prompted for one. Use it with '--schsm-pwd-shares-total <int>' in case your DKEK share requires <int> password shares to restore it. Do not(!) use '--password <pwd>'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 <file> Restore private key from <file> (DKEK-encrypted). Use it with '--schsm-key-reference <id>' to specify the key reference to use. This mode requires running './sc.sh --initialize --schsm-dkek-shares <int>' and './sc.sh --schsm-dkek-share-import <file>' beforehand. Use '-p|--pin <pin>' to specify the PIN to use. ______________________________ Yubico YubiKey PIV ______________________________
--change-management-key Change management key. Use '--yubico-management-key <key>' to specify the current management key. Use '--yubico-new-management-key <key>' to specify the new management key. --------------------------------------------------------------------------------
-------------------------------- OPTION --------------------------------
--------------------------------------------------------------------------------
__________________________ Miscellaneous Token Types ___________________________
Some options are only allowed with certain token types, see type-specific option lists above.
-T|--token-type <type> Select the token type to use <type> = { opensc-p11 | opensc-p15 | schsm | yubico } (default: 'opensc-p11') --data-application-name <name> Specify the application name of the data object to import. Only with '-T opensc-p11' or '-T opensc-p15'. Run './sc.sh --list data' to list all available data objects. --data-oid <oid> Specify the data object's identifier (OID). Run './sc.sh --list data' to list all available data objects. -F|--force Perform action without any further user interaction. Only with '-T schsm --schsm-restore <file>' or '-T yubico (--initialize|--change-management-key)'. -f|--format <format> Certificate or key format to use. 'pkcs12' is only possible with '-T opensc-p15 --import <file> --type privkey'. <format> = { pem | der | pkcs12 } (default: 'pem') -i|--id <id> ID of the object to create or operate on. Run './sc.sh --list object' to list all available objects. --key-type <type> Type and length of the key to create. Run './sc.sh --list algorithm' to get a list of algorithms supported by the token. Depending on the token type this value must follow one of the following forms (without ''): ***** OpenSC PKCS#11 ('-T opensc-p11') ***** ***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm') ***** '<type>:<length>', e.g. 'rsa:4096' or 'EC:prime256v1' ***** OpenSC PKCS#15 ('-T opensc-p15') ***** '<type>/<length>', e.g. 'rsa/2048' or 'ec/prime256v1' ***** Yubico YubiKey PIV ('-T yubico') ***** '<TYPE><length>', e.g. 'RSA2048' or 'ECCP384'. Only the following values are allowed: Private Key <type> = { RSA2048 | RSA1024 | ECCP256 | ECCP384 } Management Key <type> = { AES256 | AES192 | AES128 | TDES } (default: 'rsa:2048') -l|--label <label> Label (name) of the object to operate on (or the token label when '--initialize' is used). Run './sc.sh --list object' to list all available objects. -n|--new-pin|--new-puk| New user PIN, PUK, or security officer PIN. --new-so-pin <val> Use this option only in case you change an Use this option only in case you change an existing value. With '--initialize' or '--store-pin' please use other options, e.g. '-p|--pin <pin>'. See also (1) and (2). --p15-aid <id> Set the hexadecimal application id (AID) of the PKCS#15 application to bind to. Run './sc.sh -T opensc-p15 --list p15-application' to list all available PKCS#15 applications. --p15-auth-id <id> Specify the hexadecimal auth id of the PIN/PUK pair to use/create. Run './sc.sh -T opensc-p15 --list p15-pin' to list all available PKCS#15 PINs. --piv-id <id> PIV object identifier (BER-TLV Tag) <id> = { 5FC107 | 5FC102 | 5FC105 | 5FC103 | 5FC106 | 5FC108 | 5FC101 | 5FC10A | 5FC10B | 5FC109 | 7E | 5FC10C | 5FC10D | 5FC10E | 5FC10F | 5FC110 | 5FC111 | 5FC112 | 5FC113 | 5FC114 | 5FC115 | 5FC116 | 5FC117 | 5FC118 | 5FC119 | 5FC11A | 5FC11B | 5FC11C | 5FC11D | 5FC11E | 5FC11F | 5FC120 | 5FC121 | 7F61 | 5FC122 | 5FC123 } See also: NIST SP 800-73-4 (Section 4.3 "Object Identifiers") https://doi.org/10.6028/NIST.SP.800-73-4 Yubico https://developers.yubico.com/yubico-piv-tool /Actions/read_write_objects.html --piv-slot <id> PIV slot (key reference value) <id> = { 04 | 9A | 9C | 9D | 9E | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 8A | 8B | 8C | 8D | 8E | 8F | 90 | 91 | 92 | 93 | 94 | 95 | F9 } See also: NIST SP 800-73-4 (Section 5.1 "Key References") https://doi.org/10.6028/NIST.SP.800-73-4 Yubico https://developers.yubico.com/PIV/Introductio n/Certificate_slots.html --password <pwd> Password for exporting/importing password-protected files. See also (1) and (2). -p|--pin <pin> (Current or initial) user PIN. See also (1) and (2). ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-auth-id <id>' to specify the hexadecimal auth id of PIN/PUK pair to use/create. -P|--puk <puk> (Current or initial) user PUK. See also (1) and (2). ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-auth-id <id>' to specify the hexadecimal auth id of PIN/PUK pair to use/create. -r|--reader <id> Specify slot/reader to use by its decimal ID/index <id>. Run './sc.sh --list reader' to list all available slots/readers. --serial <serial no> ***** Yubico YubiKey PIV ('-T yubico') ***** Specify token to use by its serial number. Run './sc.sh --list reader' to list all available tokens. -s|--so-pin <so pin> (Current or initial) security officer PIN (SO-PIN). See also (1) and (2). ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-auth-id <id>' to specify the hexadecimal auth id of PIN/PUK pair to use/create. -S|--so-puk <so puk> (Current or initial) security officer PUK (SO-PUK). See also (1) and (2). ***** OpenSC PKCS#15 ('-T opensc-p15') ***** Use '--p15-auth-id <id>' to specify the hexadecimal auth id of PIN/PUK pair to use/create. -t|--type <type> Specify object type. Some types are only available with certain token types. cert : Certificate data : Data Object object : (All) Objects privkey : Private Key pubkey : Public Key secrkey : Secret Key chain : Certificate Chain sshkey : SSH Key sshkey-rfc4716 : SSH Key (RFC4716) algorithm : Supported Mechanisms (algorithms, key lengths, ...) info : General Information reader : Available Reader/Slots p15-application : PKCS#15 Application p15-pin : PKCS#15 PIN ________________________________ OpenSC PKCS#15 ________________________________--opensc-p15-profile <profile> Specify OpenSC PKCS#15 profile to load during initialization in the form of '<profile>[+<option>]...', e.g. 'pkcs15+onepin' in case your token only supports one user PIN/PUK pair but no separate SO-PIN/SO-PUK. For more information please have a look at the manpage by running 'man pkcs15-init', parameter "--profile". (default: 'pkcs15') ________________________ SmartCard-HSM / Nitrokey HSM 2 ________________________--schsm-dkek-shares <int> Specify number of DKEK shares (files) that are necessary to recreate the Device Key Encryption Key (DKEK). All DKEK shares are needed to backup/restore the keys. Usually you set <int> to '1'. Leave this parameter out or set <int> to '' to disable DKEK creation and the key backup/restore feature. Set <int> to '0' to create a random DKEK meaning that keys backed up with this DKEK can only be restored in the same HSM. Please do not confuse this with DKEK password n-of-m threshold scheme. Use './sc.sh --schsm-dkek-share-create <file>' to create the DKEK share(s). (default: '') --schsm-key-reference <id> Specify key (identifier) to backup/restore. Run 'pkcs15-tool --dump' to show available keys to backup or free reference ids to use for restore (in the command's output the relevant value is the 'Key ref' field). (default: '1') --schsm-pwd-shares-threshold <int> Threshold (minimum) number of password shares required for deciphering the DKEK share (default: '') --schsm-pwd-shares-total <int> Total number of password shares used to encipher the DKEK share (default: '') ______________________________ Yubico YubiKey PIV ______________________________
--yubico-management-key <key> Specify current management key in hex form (without '0x'). Length depends on '--key-type <type>', e.g. 32 bytes for AES256. See also (1) and (2). --yubico-new-management-key <key> Specify new management key in hex form (without '0x'). Length depends on '--key-type <type>', e.g. 32 bytes for AES256. See also (1) and (2). --yubico-pin-policy <pol> PIN policy, defines if or how often a user must confirm key-related operations by entering the user PIN. See also: https://docs.yubico.com/yesdk/users-manual
/application-piv/pin-touch-policies.html Possible values are: default : Default always : Always once : Once (per session) never : Never (default: 'default') --yubico-touch-policy <pol> Touch policy, defines if or how often a user must confirm key-related operations by pushing YubiKey's button. See also: https://docs.yubico.com/yesdk/users-manual /application-piv/pin-touch-policies.html Possible values are: default : Default always : Always cached : Cached (A touch is not needed if the YubiKey had been touched within the last 15 seconds.) never : Never (default: 'default') ================================================================================================================ NOTES =================================================================================================================_____________________________________ (1) ______________________________________Minimum/Maximum length and allowed characters depend on the token type and model. For more information please also consult your token's data sheet or manual.
***** OpenSC PKCS#11 ('-T opensc-p11') ********** OpenSC PKCS#15 ('-T opensc-p15') *****
PIN: 6 - 8 characters, digits (0-9) only
PUK: Exactly 8 characters, digits only
SO-PIN: 6 - 8 characters, digits only
***** OpenSC PKCS#15 ('-T opensc-p15') *****
PUK: 8 - 16 (*) characters, digits only
SO-PUK: 8 - 16 (*) characters, digits only
(*) To conform with 'FIPS-201 (PIV Card)' standard it must be exactly 8 characters long.
***** SmartCard-HSM / Nitrokey HSM 2 ('-T schsm') *****
PIN: 6 - 15 bytes, ASCII characters only
PUK: (not available)
SO-PIN: Exactly 16 hexadecimal (0-9 a-f) characters
Password (DKEK Share): >= 10 characters, any
Firmware versions before 1.0 have some restrictions, e.g.
- Device has to be reinitialized to reset the user PIN,
losing all certs/data/keys.
- Security Officer PIN (SO-PIN) can only be set once(!)
during first initialization.
See also:
https://github.com/OpenSC/OpenSC/wiki/SmartCardHSM#using-pkcs11-tool
https://raymii.org/s/articles/Get_Started_With_The_Nitrokey_HSM.html
***** Yubico YubiKey PIV ('-T yubico') *****
PIN: 6 - 8 bytes, ASCII characters only
PUK: 6 - 8 bytes, any value (ASCII characters only recommended)
Management Key:
Length depends on the key type ('--key-type <type>').
Exactly 32 (AES128), 48 (AES192, TDES), 64 (AES256)
characters, hexadecimal (0-9 a-f) only.
See also:
https://docs.yubico.com/yesdk/users-manual/application-piv/pin-puk-mgmt-key.html
***** FIPS 201 (PIV Card) *****
PIN: 6 - 8 bytes, only ASCII numbers 0-9 ('0x30' - '0x39')
PUK: 8 bytes, any binary value ('0x00' - '0xFF')
See also:
NIST SP 800-73-4 (Section "2.4.3 Authentication of an Individual")
https://doi.org/10.6028/NIST.SP.800-73-4
_____________________________________ (2) ______________________________________
It is highly recommended to pass credentials only via environment variables. To do so, just set this value to 'env:<VAR>' (without ''<>) where <VAR> is your environment variable's name.Please note that passing credentials in clear-text form can be highly insecure as any other user/process could display the command line of this application by using system utilities like 'ps'.Example: You would like to pass the password '123456'. Via an environment variable (preferred) > export mypwd="123456" > ... "env:mypwd" Directly, in clear-text form (NOT recommended) > ... "123456"See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the GNU General Public License v3.0 (or later). See LICENSE for more information.
⚠️ The license above does not apply to the files and folders within the library directory/lib. Please have a look at theLICENSEfile located in the root directory of each library to get more information.
⚠️ The license above may not apply to some files within the TeX letter directory/tex. Please have a look at theSPDX-FileCopyrightTextandSPDX-License-Identifierheaders in each file to get more information.
⚠️ The license above does not apply to the sample logo file/tex/logo.png. For more information please have a look at Logoipsum's terms of license.
Project Link: https://github.com/fkemser/SCwrapper