PKCS15-PROFILE(5)

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

🎀 PKCS15-PROFILE(5) 🎀

okay bestie, welcome to pkcs15-profile(5), straight outta the OpenSC File Formats section of the manual. it's giving documentation, it's giving profiles, it's giving we're about to personalize some smart cards. let's go 💅

✨ NAME ✨

pkcs15-profile — the format of the profile files that pkcs15-init runs on 💖

🌸 DESCRIPTION 🌸

The pkcs15-init utility — that's the one that does PKCS #15 smart card personalization — is controlled via profiles. When it starts up, it reads 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, like the path of the application DF, the 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. iconic, honestly 👑

The card specific profile contains additional information required during card initialization, like the location of PIN files, key references, etc. Profiles currently reside in /usr/share/opensc. noted 📝

Basic PKCS#15 terminology, for the girlies keeping score:

  1. MF (Master File) is root of the filesystem hierarchy
  2. DF(PKCS#15) is directory containing the PKCS#15 files and directories
  3. EF(ODF) (Object Directory File) is elementary file containing pointers to other elementary files (PrKDFs, PuKDFs, SKDFs, CDFs, DODFs, AODFs)
  4. PrKDF (Private Key Directory File) is elementary file containing pointers to the private keys and additional information about the private keys
  5. PubKDF (Public Key Directory File) is elementary file containing pointers to the public keys and additional information about the public keys
  6. CDF (Certificate Directory File) is elementary file containing pointers to the certificates and additional information about the certificates
  7. EF(TokenInfo) is elementary file with generic information about the card

🦋 SYNTAX AND SEMANTICS 🦋

The block syntax of profile files is in general similar to the configuration file. The profile file is composed of blocks, which, in general, have the following format:

key [, name...] {
     block_contents
}

block_contents is one or more block_items, where a block_item is one of

  • # comment string
  • key[, name...] = value;
  • block

At the root level, the profile contains several configuration blocks. The block keys are as follows:

  • cardinfo: Configuration for general information about card.
  • pkcs15: Control for some of the general aspects of the PKCS#15 put onto the card.
  • option: Profile options to modify the behavior of profile.
  • PIN: Configuration and limits for particular PIN type.
  • filesystem: Specification for filesystem that is to be created on the card.
  • macros

💖 Profile file configuration 💖

Configuration of Card Information

cardinfo { block_contents }

Configuration for general information about card:

  • label = name; — Card label (Default: OpenSC Card).
  • manufacturer = name; — Card manufacturer (Default: OpenSC Project).
  • min-pin-length = int; — Minimal length of PIN (Default: 4).
  • max-pin-length = int; — Maximal length of PIN, should be overridden in the per-card profile (Default: 8).
  • pin-encoding = value; — Encoding type of PIN. Known parameters:
    • BCD: binary-coded decimal
    • ascii-numeric: ASCII numerical values
    • utf8
    • half-nibble-bcd
    • iso9564-1

(Default: ascii-numeric).

  • pin-pad-char = value; — Character used for padding the PIN when needed (Default: 0x00).
  • pin-domains = bool; — Some cards need to keep all their PINs in separate directories. The particular keys in that domain will be put below the DF of the specified PIN. (Default: no)

Configuration of PKCS#15

pkcs15 { block_contents }

Control for some of the general aspects of the PKCS#15 put onto the card. Parameters in this block are:

  • direct-certificates = bool; — The PKCS#15 system must contain at least one CDF, it contains the certificates directly or references to certificates. This option defines whether the certificates should be put directly in the CDF itself or not (Default: no).
  • encode-df-length = bool; — Save length of DF into ODF file. Useful if we store certificates directly in the CDF for better better performance and robustness (Default: no). (their doubled word, not mine, i'm just the messenger 💀)
  • do-last-update = value; — Store information about last update in the EF(TokenInfo) (Default: yes).
  • pkcs15-id-style = value; — Method to calculate ID of the crypto objects. Known parameters:
    • native: 'E' + number_of_present_objects_of_the_same_type
    • mozilla: SHA1(modulus) for RSA
    • rfc2459 SHA1(SequenceASN1 of public key components as ASN1 integers)

(Default: native)

  • minidriver-support-style = value; — Style of pkcs15-init support of minidriver. Known parameters:
    • none
    • gemalto

(Default: none)

Configuration of Profile Option

option name { block_contents }

The name specifies profile options to modify the behavior of profile, it can be (the list of names that lived here got eaten before it reached us, sorry bestie 😭)

  • macros { block_contents } — Macros are specified in form of name = value; pairs.
  • pkcs15 { block_contents } — Inner block for configuration of PKCS#15 structure.

Configuration of PINs

PIN name { block_contents }

The name specifies PIN type, it can be (same situation as above, the list is just gone 🙈)

Known parameters are:

  • attempts = int; — Defines number of attempts for the given PIN (Default: 3).
  • flags = value...; — Flags define properties of the PIN. Possible flags:
    • case-sensitive
    • local
    • change-disabled
    • unblock-disabled
    • initialized
    • needs-padding
    • unblockingPin
    • soPin
    • disable-allowed
    • integrity-protected
    • confidentiality-protected
    • exchangeRefData

(Default: local,initialized,needs-padding).

  • auth-id = value; — Value used for auth ID (Default: 0).
  • min-length = int; — Minimal length of PIN (Default: value min-pin-length set in cardinfo block).
  • max-length = int; — Maximal length of PIN (Default: value max-pin-length set in cardinfo block).
  • reference = int; — Value of reference of the PIN (Default: set in particular card driver).
  • file = name; — File with PIN, obsolete option (Default: None).
  • offset = int; — Offset of PIN in PIN file, obsolete option (Default: 0).
  • encoding = value; — Encoding type of PIN. Possible values:
    • BCD
    • ascii-numeric
    • utf8
    • half-nibble-bcd
    • iso9564-1

(Default: value pin-encoding set in cardinfo block).

  • stored-length = int; — (Default: value max-pin-length set in cardinfo block).
  • max-unlocks = int; — (Default: 0).

Values in this block can be set by macros. That allows to specify the particular values with the usage of option. 🫶

Configuration of Filesystem

filesystem { block_contents }

This block contains the specification for filesystem that is to be created on the card. The filesystem consists of several nested blocks representing DF and EF files. When the DFs or EFs are specified in card specific profile, this is added to the file system info specified in the main profile.

EF name { block_contents }

This block defines elementary file in PKCS#15 file hierarchy. The name can be one of: (yep, list's missing again 💀)

  • type = EF; — Type must match type of file.
  • acl = value; — Value of ACL (Access Control List) (Default: NONE)
  • file-id = EF; — File ID, relative path.
  • structure = value; — File structure is one of:
    • TRANSPARENT
    • LINEAR-FIXED
    • LINEAR-FIXED-TLV
    • LINEAR-VARIABLE
    • LINEAR-VARIABLE-TLV
    • CYCLIC
    • CYCLIC-TLV
DF name { block_contents }

This block defines directory file in PKCS#15 file hierarchy. The name can be one of: (...you know the drill 🌸)

  • type = DF; — Type must match type of file.
  • path = value; — Specification of path of the directory file.
  • file-id = value; — File ID, relative path.
  • aid = value; — Value of AID, in XX:XX:XX:...:XX:XX:XX notation.
  • acl = value; — Type must match type of file.
  • size = int; — Size of the file in bytes.
  • EF name { block_contents } — Block specifying nested elementary file.

Typically, the root DF is MF.

It is mandatory that profile file contains DF entry for MF (Master File). Otherwise the profile file is incomplete and cannot be used. no cap, it just will not run 😤

The DF can contain other DF or MF blocks. For examples how the filesystem structure may look like, please refer to pkcs15.profile or any other present profile file. go peek, it's educational 💅

🌈 SEE ALSO 🌈

pkcs15-init(1), pkcs15-crypt(1)

and that's the whole page, bestie — opensc, dated 04/19/2026, dropping PKCS15-PROFILE(5) knowledge and slaying the entire time. mwah 💋🎀✨

📦 where this page comes from