PKCS15-INITPKCS15-(1)

📦
version 0.27.1 · 17 versions
, in fedora 43, fedora 44

💖 pkcs15-init — smart card personalization utility 💖

okay bestie, welcome to pkcs15-init, part of the OpenSC Tools set. this is the glow-up page for your smart card. let's get into it ✨

✨ SYNOPSIS ✨

pkcs15-init [OPTIONS]

🦋 DESCRIPTION 🦋

so like, the pkcs15-init utility is your little fairy godmother for creating a PKCS #15 structure on a smart card, and for adding key or certificate objects to it. the details of the structure that will be created? all controlled via profiles bestie.

the profile used by default is pkcs15. want a different one? no problem, just specify it via the -p switch. slay 💅

🔐 PIN USAGE 🔐

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 whole process is also called personalization. periodt.

an OpenSC card can have one security officer PIN, and zero or more user PINs. PIN stands for Personal Identification Number, and it's a secret code you need to present to the card before being allowed to do certain operations — like using one of the stored RSA keys to sign a document, or modifying the card itself. it's giving ✨gatekeeping✨ but make it cryptography.

usually, PINs are a sequence of decimal digits, but some cards will accept arbitrary ASCII characters. be aware however that using characters other than digits will make the card unusable with PIN pad readers, because those usually have keys for entering digits only. 😭 so like, think before you get creative.

the security officer (SO) PIN is special; it is used to protect meta data information on the card, such as the PKCS #15 structure itself. setting the SO PIN is optional, because the worst that can usually happen is that someone finding your card can mess it up. to extract any of your secret keys stored on the card, an attacker will still need your user PIN, at least for the default OpenSC profiles. however, it is possible to create card profiles that will allow the security officer to override user PINs. 🫣 not that.

for each PIN, you can specify a PUK (also called unblock PIN). the PUK can be used to overwrite or unlock a PIN if too many incorrect values have been entered in a row. it's the "oops bestie let me back in" key 🎀

for some cards that use the PKCS#15 emulation, the attributes of private objects 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.

🌈 MODES OF OPERATION 🌈

🧚 Initialization 🧚

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

pkcs15-init --create-pkcs15

you will then be asked for the security officer PIN and PUK. simply pressing return at the SO PIN prompt will skip installation of an SO PIN. no SO PIN, no problem 💜

if the card supports it, you should erase the contents of the card with pkcs15-init --erase-card before creating the PKCS#15 structure. clean slate energy ✨

🎀 User PIN Installation 🎀

before installing any user objects such as private keys, you need at least one PIN to protect these objects. you can do this using

pkcs15-init --store-pin --id " nn

where nn is a PKCS #15 ID in hexadecimal notation. common values are 01, 02, etc.

entering the command above will ask you for the user's PIN and PUK. if you do not wish to install an unblock PIN, simply press return at the PUK prompt. bye unblock PIN 👋

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. so cute, so useful.

🔑 Key generation 🔑

pkcs15-init lets you generate a new key and store it on the card. you can do this using:

pkcs15-init --generate-key "keyspec" --auth-id "nn"

where keyspec describes the algorithm and the parameters of the key to be created. for example, rsa:2048 generates a RSA key with 2048-bit modulus, default is 3072. if you are generating an EC key, the curve designation must be specified, for example ec:prime256v1. the following curves do not need parameters: Edwards 25519 curves use one of these equivalent names: Ed25519(preferred), ed25519 or edwards25519 and for the 448 curve use: Ed448. for Montgomery 25519 curves use one of these equivalent names: X25519(preferred), cv25519 or curve25519 and for the 448 curve use: X448. for symmetric key, the length of key is specified in bytes, for example AES:32 or DES3:24. 🔥

nn is the ID of a user PIN installed previously, e.g. 01.

in addition to storing the private portion of the key on the card, pkcs15-init will also store the public portion of the key as a PKCS #15 public key object. it's giving overachiever, and we love that 💅

🗝️ Private Key Upload 🗝️

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

pkcs15-init --store-private-key okir.pem --id 45 --auth-id 01

in addition to storing the private portion of the key on the card, pkcs15-init will also store the public portion of the key as a PKCS #15 public key object.

note that usage of --id option in the pkcs15-init commands to generate or to import a new key is deprecated. better practice is to let the middleware to derive the identifier from the key material. (SHA1(modulus) for RSA, ...). this allows easily set up relation between 'related' objects (private/public keys and certificates). so like, let the middleware do its thing, bestie 🫶

in addition to the PEM key file format, pkcs15-init also supports DER encoded keys, and PKCS #12 files. the latter is the file format used by Netscape Navigator (among others) when exporting certificates to 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. iconic behaviour honestly ✨

🌸 Public Key Upload 🌸

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 specify a key file format using the --format option, pkcs15-init will assume PEM format. the only other supported public key file format is DER.

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. lowkey a background character option 🙈

🏅 Certificate Upload 🏅

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. simple as that, gorgeous 💜

🎁 Uploading PKCS #12 bags 🎁

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 card in a single operation. this works just like storing a private key, except that you need to specify the file format:

pkcs15-init --store-private-key okir.p12 --format pkcs12 --auth-id 01

this will install the private key contained in the file okir.p12, 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. one command, whole bundle, main character energy 👑

🤫 Secret Key Upload 🤫

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

pkcs15-init --store-secret-key /dev/urandom --secret-key-algorithm
aes:256 --auth-id 01

by default a random ID is generated for the secret key. you may specify an ID with the --id if needed. 🍓

✨ OPTIONS ✨

okay bestie, this is the big one — the whole menu of what you can make pkcs15-init do. buckle up 💖

  • --version — prints the OpenSC package release version. that's it, that's the whole job 🌸
  • --card-profile name, -c name — tells pkcs15-init to load that specific card profile option. ngl you will rarely need this one, it's giving "deep lore" energy 💅
  • --create-pkcs15, -C — this tells pkcs15-init to create a PKCS #15 structure on the card, and to initialize any PINs. the main character move 🫶
  • --serial SERIAL — specify the serial number of the card. gotta know which one you're talking to, fr fr
  • --erase-card, -E — wipes the card before creating the PKCS #15 structure, if the card supports it. > if your card does not support erasing, pkcs15-init will straight up fail. no cap. 💀
  • --erase-application AID — erases the application with the application identifier AID. yeet that specific app, iconic ✨
  • --generate-key keyspec, -G keyspec — tells the card to generate a new key and store it on the card. keyspec is an algorithm name, optionally followed by a colon :, slash / or hyphen - and the parameters of the key to be created. it is a good idea to specify the key ID along with this command, using the id option, otherwise an intrinsic ID will be calculated from the key material. look at the description of the 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details about the algorithm used to calculate intrinsic ID. for the multi-application cards the target PKCS#15 application can be specified by the hexadecimal AID value of the aid option 🔑
  • --pin pin, --puk puk, --so-pin sopin, --so-puk sopuk — these options let you specify the PIN/PUK values right on the command line. if the value is set to env:VARIABLE, the value of the specified environment variable is used. by default, the code is prompted on the command line if needed.
note that on most operation systems, any user can display the command line of any process on the system using utilities such as ps(1). therefore, you should prefer passing the codes via an environment variable on an unsecured system. bestie, protect your secrets, okay? 🙈
  • --no-so-pin — do not install a SO PIN, and do not prompt for it. skip the whole thing, we love an efficient queen 💅
  • --profile name, -p name — tells pkcs15-init to load the specified general profile. currently, the only application profile defined is pkcs15, but you can write your own profiles and specify them using this option.

the profile name can be combined with one or more profile options, which slightly modify the profile's behavior. for instance, the default OpenSC profile supports the openpin option, which installs a single PIN during card initialization. this PIN is then used both as the SO PIN as well as the user PIN for all keys stored on the card.

profile name and options are separated by a + character, as in pkcs15+onepin. cute little plus sign doing the lord's work 🌸

  • --secret-key-algorithm keyspec — keyspec describes the algorithm and length of the key to be created or downloaded, such as aes:256. this will create a 256 bit AES key. slay 🔥
  • --store-certificate filename, -X filename — tells pkcs15-init to store the certificate given in filename on the card, creating a certificate object with the ID specified via the --id option. without a supplied ID, an intrinsic ID will be calculated from the certificate's public key. look at the description of the 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details about the algorithm used to calculate intrinsic ID. the file is assumed to contain the PEM encoded certificate. for the multi-application cards the target application can be specified by the hexadecimal AID value of the aid option 🎀
  • --store-pin, -P — store a new PIN/PUK on the card. new credentials, new era ✨
  • --store-public-key filename — tells pkcs15-init to download the specified public key to the card and create a public key object with the key ID specified via the --id. by default, the file is assumed to contain the key in PEM format. alternative formats can be specified using --format.
  • --store-private-key filename, -S filename — tells pkcs15-init to download the specified private key to the card. this command will also create a public key object containing the public key portion. by default, the file is assumed to contain the key in PEM format. alternative formats can be specified using --format. it is a good idea to specify the key ID along with this command, using the --id option, otherwise an intrinsic ID will be calculated from the key material. look at the description of the 'pkcs15-id-style' attribute in the 'pkcs15.profile' for the details about the algorithm used to calculate intrinsic ID. for the multi-application cards the target PKCS#15 application can be specified by the hexadecimal AID value of the aid option 💜
  • --store-secret-key filename — tells pkcs15-init to download the specified secret key to the card. the file is assumed to contain the raw key. the key type should be specified with the --secret-key-algorithm option.

you may additionally specify the key ID along with this command, using the --id option, otherwise a random ID is generated. for the multi-application cards the target PKCS#15 application can be specified by the hexadecimal AID value of the aid option 🔐

  • --store-data filename, -W filename — store a data object. straightforward, we respect it 🫶
  • --update-certificate filename, -U filename — tells pkcs15-init to update the certificate object with the ID specified via the --id option with the certificate in filename. the file is assumed to contain a PEM encoded certificate.
pay extra attention when updating mail decryption certificates, as missing certificates can render e-mail messages unreadable! 😭 bestie this one is not a drill, do not lose those certs
  • --delete-objects arg, -D arg — tells pkcs15-init to delete the specified object. arg is a comma-separated list containing any of privkey, pubkey, secrkey, cert, chain or data.

when data is specified, an ---application-id must also be specified, in the other cases an --id must also be specified.

when chain is specified, the certificate chain starting with the cert with specified ID will be deleted, until there's a CA certificate that certifies another cert on the card 🗑️

  • --change-attributes arg, -A arg — tells pkcs15-init to change the specified attribute. arg is either privkey, pubkey, secrkey, cert or data. you also have to specify the --id of the object. for now, you can only change the --label, e.g:
pkcs15-init -A cert --id 45 -a 1 --label Jim
  • --use-default-transport-keys, -T — tells pkcs15-init to not ask for the transport keys and use default keys, as known by the card driver. no questions asked, we trust the driver 💅
  • --sanity-check — tells pkcs15-init to perform a card specific sanity check and possibly update procedure. a lil wellness check for your card 🌸
  • --reader arg, -r arg — number of the reader to use. by default, the first reader with a present card is used. if arg is an ATR, the reader with a matching card will be chosen 🦋
  • --verbose, -v — causes pkcs15-init to be more verbose. specify this flag several times to enable debug output in the OpenSC library. more -v = more tea ☕
  • --wait, -w — causes pkcs15-init to wait for a card insertion. patience, bestie, it's coming 🧚
  • --use-pinpad — do not prompt the user; if no PINs supplied, pinpad will be used.
  • --auth-id filename, -a filename — specify ID of PIN to use/create.
  • --puk-id ID — specify ID of PUK to use/create.
  • --label LABEL — specify label for a PIN, key, certificate or data object when creating new objects. when deleting objects, this can be used to delete object by label 🏷️
  • --puk-label LABEL — specify label of PUK.
  • --public-key-label LABEL — specify public key label (use with --generate-key).
  • --cert-label LABEL — specify user cert label (use with --store-private-key).
  • --application-name arg — specify application name of data object (use with --store-data-object).
  • --aid AID — specify AID of the on-card PKCS#15 application to be binded to (in hexadecimal form).
  • --output-file filename, -o filename — output public portion of generated key to file.
  • --passphrase PASSPHRASE — specify passphrase for unlocking secret key 🔓
  • --authority — mark certificate as a CA certificate. crown it 👑
  • --key-usage arg, -u arg — specifies the X.509 key usage. arg is a comma-separated list containing any of digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign. abbreviated names are allowed if unique (e.g. dataEnc).

the alias sign is equivalent to digitalSignature,keyCertSign,cRLSign.

the alias decrypt is equivalent to keyEncipherment,dataEncipherment 🔥

  • --finalize, -F — finish initialization phase of the smart card. the finale, the moment, the glow up ✨
  • --update-last-update — update 'lastUpdate' attribute of tokenInfo.
  • --ignore-ca-certificates — when storing PKCS#12 ignore CA certificates.
  • --update-existing — store or update existing certificate.
  • --extractable — private key stored as an extractable key.
  • --user-consent arg — specify user-consent. arg is an integer value. if > 0, the value specifies how many times the object can be accessed before a new authentication is required. if zero, the object does not require re-authentication 🙈
  • --insecure — insecure mode: do not require a PIN for private key.
bestie. it's literally called --insecure. just so we're all on the same page here 💀
  • --md-container-guid GUID — for a new key specify GUID for a MD container.
  • --help, -h — display help message. when in doubt, ask for help, always valid 🌈

🌟 SEE ALSO 🌟

👑 AUTHORS 👑

pkcs15-init was written by Olaf Kirch <okir@suse.de>. thank you legend, we owe you everything 💖

and that's the whole page bestie!! you ate that. this is from the openscopensc source, version dated 04/19/2026, page PKCS15-INITPKCS15-(1) — go forth and initialize those cards, periodt 💅✨🎀

📦 where this page comes from