pkcs15-profile - Man Page
format of profile for pkcs15-init
Description
The pkcs15-init utility for PKCS #15 smart card personalization is controlled via profiles. When starting, it will read two such profiles at the moment, a generic application profile, and a card specific profile. The generic profile must be specified on the command line, while the card-specific file is selected based on the type of card detected.
The generic application profile defines general information about the card layout, such as the path of the application DF, various PKCS #15 files within that directory, and the access conditions on these files. It also defines general information about PIN, key and certificate objects. Currently, there is only one such generic profile, pkcs15.profile.
The card specific profile contains additional information required during card initialization, such as location of PIN files, key references etc. Profiles currently reside in /usr/share/opensc
Basic PKCS#15 terminology:
- MF (Master File) is root of the filesystem hierarchy
- DF(PKCS#15) is directory containing the PKCS#15 files and directories
- EF(ODF) (Object Directory File) is elementary file containing pointers to other elementary files (PrKDFs, PuKDFs, SKDFs, CDFs, DODFs, AODFs)
- PrKDF (Private Key Directory File) is elementary file containing pointers to the private keys and additional information about the private keys
- PubKDF (Public Key Directory File) is elementary file containing pointers to the public keys and additional information about the public keys
- CDF (Certificate Directory File) is elementary file containing pointers to the certificates and additional information about the certificates
- 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 options 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).
- 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) .sp
- 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 } .PP The name specifies profile options to modify the behavior of profile, it can be .PP .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . default: option specifies default settings and this block with option is always processed, .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . onepin: option for using 1 user PIN, creation/deletion/generation is controlled by the user PIN and thus by the user (as a result, only 1 user PIN is possible), .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . small option suitable for cards with small memory. .RE .sp .PP The options are used by pkcs15-init tool by --profile name, -p name: .PP .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . pkcs15+default: the default (not needed to specify it) .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . pkcs15+onepin: for the onepin profile option .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . pkcs15+small for the small profile option .RE .sp .PP The option block can contain following sub-blocks:
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 } .PP The name specifies PIN type, it can be .PP .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . pin or user-pin (no need to set file path or reference as it is done dynamically) .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . puk or user-puk .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . sopin or so-pin .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . sopuk or so-puk .RE .sp
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 } .PP 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 } .PP This block defines elementary file in PKCS#15 file hierarchy. The name can be one of: .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-TokenInfo .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-ODF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-UnusedSpace .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-PRKDF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-PUKDF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-PUKDF-TRUSTED .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-SKDF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-CDF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-CDF-TRUSTED .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-CDF-USEFUL .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-DODF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-AODF .RE .sp .PP The EF block can contain:
- 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 } .PP This block defines directory file in PKCS#15 file hierarchy. The name can be one of: .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . MF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . PKCS15-AppDF .RE .sp .RS 4 .ie n · c . .el .sp -1 .IP · 2.3 . Special cases for those DFs handled separately by the PKCS15 logic .RE .sp .PP The DF block can contain:
- 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.
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.