Skip to content

Pre Build Configuration

Jump to bottom
Philip Wendland edited this page Jul 31, 2016 · 1 revision

There are several options to configure the IsoApplet by modifying the source files prior to compilation. If you are satisfied with the default configuration, there is no need to compile the applet itself.

IsoApplet.java

PIN

  • PIN_MAX_TRIES (default: 3): This option determines how many failed attempts to verify the PIN are necessary to block the PIN. If the PIN is blocked, it has to be unlocked again using the PUK. If you change this option and use OpenSC with the Applet, update src/pkcs15init/isoApplet.profile as well to reflect the changes and reinstall OpenSC. You can also configure the isoApplet.profile directly (typical location: /usr/local/share/opensc/isoApplet.profile).
  • PIN_MIN_LENGTH (default: 4): This option determines the minimum allowed length of the PIN. If you change this option and use OpenSC with the Applet, update src/pkcs15init/isoApplet.profile as well to reflect the changes and reinstall OpenSC. You can also configure the isoApplet.profile directly (typical location: /usr/local/share/opensc/isoApplet.profile).
  • PIN_MAX_LENGTH (default: 16): This option determines the maximum allowed length of the PIN. If you change this option and use OpenSC with the Applet, update src/pkcs15init/isoApplet.profile as well to reflect the changes and reinstall OpenSC. You can also configure the isoApplet.profile directly (typical location: /usr/local/share/opensc/isoApplet.profile).

PUK (unblock PIN)

  • PUK_MUST_BE_SET (default: false, older versions: true): Configure whether the PUK must be set to successfully initialize the applet. If a PUK is not necessary, you can skip the PUK input while initializing the applet with pkcs15init --create-pkcs15 by just pressing Enter. Attention! If you do not set a PUK and the PIN had been blocked, the installed applet will become close to useless, you would have to reinstall the applet and your private keys are lost as well!
  • PUK_MAX_TRIES (default: 5): This option determines how many failed attempts to verify the PUK are necessary to block the PUK. If the PUK is blocked and the PIN is blocked or unknown, the installed applet is close to useless. You would have to reinstall the applet and use new private keys. If you change this option and use OpenSC with the Applet, update src/pkcs15init/isoApplet.profile as well to reflect the changes and reinstall OpenSC.
  • PUK_LENGTH (default: 16): This option determines the length of the PUK. The PUK has a fixed length. If you change this option and use OpenSC with the Applet, update src/pkcs15init/isoApplet.profile as well to reflect the changes and reinstall OpenSC. You can also configure the isoApplet.profile directly (typical location: /usr/local/share/opensc/isoApplet.profile).

Keys

  • KEY_MAX_COUNT (default: 16): The maximum amount of private keys generated on the smartcard (i.e. the size of the keys[]-array). 16 should be fairly enough. If you plan on using a large amount of keys, it could be necessary to increase the file sizes in isoApplet.profile before initialization.

Extended APDUs

  • DEF_EXT_APDU (default: false): Configure whether to use extended APDUs or command chaining/GET RESPONSE. Extended APDUs is a experimental feature. I recommend to keep this at its default value (false) or to run extensive tests on your hardware (readers, smartcards) and software. I would say, performance increases by using extended APDUs are negligible at the moment. The OpenSC driver automatically adapts to the extended APDU feature of the applet.

Private key import

  • DEF_PRIVATE_KEY_IMPORT_ALLOWED (default: false): Configure whether it is allowed to import usable private keys. If allowed, you can use pkcs15-tool --import-key to import any off-card created private key to your smartcard.

Attention! Importing private keys is not recommended. The key generation process is the weakness of asymmetric cryptography. The data transmission channel to your smartcard is not encrypted. In some circumstances, an attacker could sniff your private key while you import it to your smartcard. An attacker could also read your private key even before it is imported to the smartcard. For that reason I recommend to use the on-card key pair generation feature of the applet. If the key is generated on the card, and never leaves your card (because cryptographic operations using that key are performed directly on the smartcard - that is the reason for smartcards!), chances are lower that the key is compromised. However, there are circumstances that could require you to safely keep a copy of the private key in order safeguard yourself from locking of the applet or destruction of the card. In this case, you can use the private key import feature, and I presume you know what you are doing.

DedicatedFile.java

  • CHILDREN_COUNT_START (default: 10): The start size of the children[]-array of any DedicatedFile. If the size is reached, the array doubled/increased until CHILDREN_COUNT_MAX is reached. Tests have shown that the following requestObjectDeletion()-Call takes up to 2.5 seconds on slow Java Card 2.2.2 cards and up to 0.6 seconds on newer Java Card 3 cards. As this is quite high, it might be a good idea to set CHILDREN_COUNT_START to the same as CHILDREN_COUNT_MAX for slower smartcards. Note however that the number should not be lower than 20. A typical PKCS#15 file structure only has 2 Dedicated Files (the AppDF and the MF), so it should not affect memory usage that much. It is normally not necessary to change this value.
  • CHILDREN_COUNT_MAX (default: 30): The maximum amount of direct children of a file.

Finally, you can proceed with building the applet. There are several options to configure the IsoApplet by modifying the source files prior to compilation. If you are satisfied with the default configuration, there is no need to compile the applet itself.

Clone this wiki locally