Skip to content

Latest commit

 

History

History
511 lines (383 loc) · 20.4 KB

openpgp.md

File metadata and controls

511 lines (383 loc) · 20.4 KB

OpenPGP SmartCard Implementation

Based on the Functional Specification of the OpenPGP Application on ISO Smart Card Operating Systems v3.4.1 (The Functional Specification).

Nomenclature

This document assumes a familiarity with The Specification and as such uses terms and abbreviations from The Specification without further explanation.

ASN.1

BER-TLV - Tag-Length-Value

Tag Length Value
1 or more bytes 1 or more bytes encoded as an integer 0 or more bytes, depending on the length

Length

While ASN.1 has a variety of length encodings, the OpenPGP application uses the following:

Length Encoding
0-127 1 byte; short form
0-255 2 bytes; 81 nn
0-65535 3 bytes; 82 nn nn

Compact-TLV

Tag and length share the first byte.

Bits Description
8-5 Tag
4-1 Length; simple 4-bit integer

Interpreting SW1/SW2

The implementation shall correctly interpret the SW1 and SW2 bytes in order to correctly process responses from the card.

Minimal Use-Cases

  • Required to achieve minimally functional OpenPGP operations.
  • Based on the basic flow charts in section 9 of The Functional Specification.
  • Do not support logical channels.
    • Uses CLA=X0 for all commands.
  • Do not support extended length APDUs.
  • Do not support KDF.

Application Selection

Command CLA INS P1 P2 Lc Data Le
SELECT 00 A4 04 00 06 D2 76 00 01 24 01 00
Response Body Tag Description
FCI 6F When P2=00 none returned; SW1/SW2=9000
FCP 62 When P2=04 none returned; SW1/SW2=6D00
FMD 64 When P2=08 none returned; SW1/SW2=6D00
Status SW1 SW2 Description
90 00 Success - no other information
62 83 Selceted file invalidated
84 FCI not formatted according to ISO 7816-4
6A 81 Function not supported
82 File not found
86 Incorrect parameters P1-P2
87 Lc inconsistent with P1-P2
6D 00 Instruction code not supported or invalid

Reading main DOs

Application Related Data - Tag 6E

Command CLA INS P1 P2 Lc Data Le
GET DATA 00 CA 00 6E - - 00
Response Body Tag Size Description
Application related data 6E sz Followed by any of,
Application identifier (AID) 4F sz Full application identifier.
Historical bytes 5F52 See sections below.
Extended length information 7F66 08
General feature management data 7F74 03
Discretionary data objects 73 sz Followed by any of,
Extended Capabilities C0 0A
Algorithm attributes signature C1 sz
Algorithm attributes decryption C2 sz
Algorithm attributes authentication C3 sz
PW status bytes C4 07
Fingerprints C5 3C 3x20 bytes; signature, decryption, authentication in that order. Zero bytes indicates not present.
CA-Fingerprints C6 3C 3x20 bytes; signature, decryption, authentication in that order. Zero bytes indicates not present.
Key generation date CD 0C 3x4 bytes; UNIX epoch time. Zero bytes indicates not specified.
Key information DE 06 3x2 bytes; <key ref> <status>
UIF signature D6 02 {00=disabled,01=enabled,02=permanently enabled,03/04=reserved} {20=button/keypad}
UIF decryption D7 02 {00=disabled,01=enabled,02=permanently enabled,03/04=reserved} {20=button/keypad}
UIF authentication D8 02 {00=disabled,01=enabled,02=permanently enabled,03/04=reserved} {20=button/keypad}
Reserved UIF attestation D9 02 Reserved

Historical bytes - Tag 5F52

  • Category indicator byte. The OpenPGP application assumes 00.
  • Card capabilities (see below).
  • Card service data (see below).
  • Status indicator byte.
    • 00: No information given. TERMINATE and ACTIVATE are not supported.
    • 03: Initialization state. The OpenPGP application can be reset to default values with an ACTIVATE command.
    • 05: Operational state (activated). TERMINATE and ACTIVATE are supported.
  • Processing status bytes SW1 and SW2.

Card Capabilities - Historical bytes - Compact-TL 73

Bytes Description
1 Selection methods supported by the card
2 the data coding byte
3 support for command chaining, extended length Lc and Le, logical channels

Card service data - Historical bytes - Compact-TL 31

  • Application selection by full DF name supported.
  • Application selection by partial DF name supported.
  • DOs in EF.ATR/INFO.
    • 1 if Extended length supported.
  • EF.DIR and EF.ATR/INFO access services by the GET DATA command (BER-TLV).
    • Should be 010 if extended length supported.
  • Card with(out) MF.

Extended legnth information - Tag 7F66

Single DO

  • In the case that it is not provided in the 6E response.
Command CLA INS P1 P2 Lc Data Le
GET DATA 00 CA 7F 66 - - 00
Response Body Tag Size Description
Extended length information 0202 <nn> <nn> 0202 <nn> <nn> Maximum number of bytes in command APDU. Maximum number of bytes in response APDU. Both big-endian.

General Feature Management Data - Tag 7F74

Single DO

  • In the case that it is not provided in the 6E response.
Command CLA INS P1 P2 Lc Data Le
GET DATA 00 CA 7F 74 - - 00
Response Body Tag Size Description
General feature management data sz <nn> Bitmask of supported features. The OpenPGP application defines only the the behavior for <nn>=20 (Button).

PW Authentication

The following minimal use-cases require authentication of PW1 or PW3. Minimal use-cases shall support only passwords in plain format.

Verification

Command CLA INS P1 P2 Lc Data Le Description
Verify PW1 00 20 00 81 06 xx xx xx xx xx xx - Verifies PW1 for a PSO:CDS command only. Valid for one or serveral attempts based on PW1 status byte in extended capabilities.
Verify PW1 00 20 00 82 06 xx xx xx xx xx xx - Verifies PW1 for other functions and remains valid until the next reset or SELECT of another application.
Query PW1 00 20 00 81 - - - Access status returned in SW1/SW2. YUBIKEY RETURNS 6A80.
Unverify PW1 00 20 FF 81 - - - YUBIKEY RETURNS 6A80.
Verify PW3 00 20 00 83 08 xx xx xx xx xx xx xx xx - Verifies PW3.
Query PW3 00 20 00 83 - - - Access status returned in SW1/SW2. YUBIKEY RETURNS 6A80.
Unverify PW3 00 20 FF 83 - - - YUBIKEY RETURNS 6A80.
Response SW1 SW2 Description
90 00 Success - no other information
63 CX Not verified. X denotes number of allowed retries.
69 82 Security status not satisified. PW wrong. PW not checked (command not allowed).
69 83 Authentication method blocked. PW blocked (error counter zero).
6A 80 Incorrect parameters in command data field.
86 Incorrect parameteres P1-P2.
88 Referenced data not found.
6B 00 Wrong parameters P1-P2.

Query and Unverify - GNUPG Handling

  • gnupg
    • For "query", handles 6A80 as ISO7816_VERIFY_NO_PIN.
    • For "unverify", doesn't seem to support this at all. I cannot find any APDU for CLA=00,INS=20,P1=FF in the codebase.

Compute Digital Signature

Command CLA INS P1 P2 Lc Data Le
PSO:CDS 00 2A 9E 9A xx xx xx xx xx xx xx 00
Response SW1 SW2 Description
90 00 Success - no other information
69 82 Security status not satisified. PW wrong. PW not checked (command not allowed).

Data field

  • DigestInfo created using a hash algorithm of the supported algorithms specified in the algorithm attributes for the signature key. The digest itself is taken from the contents of the signature packet.

RSA DigestInfo

Using SHA-256
Hash-code length
32 (decimal)
Tag Length Value
30 31
30 0D
06 09 608648016503040201
05 00 -
04 20 32-byte hash-code
Using SHA-384
Hash-code length
48 (decimal)
Tag Length Value
30 41
30 0D
06 09 608648016503040202
05 00 -
04 30 48-byte hash-code
Using SHA-512
Hash-code length
64 (decimal)
Tag Length Value
30 51
30 0D
06 09 608648016503040203
05 00 -
04 40 64-byte hash-code

Decrypt Message

Command CLA INS P1 P2 Lc Data Le
PSO:DEC 00 2A 80 86 xx xx xx xx xx xx xx 00

RSA

  • Data field is padded with 00 padding indicator byte.
  • Some questions regarding the section 7.2.11 PSO:DECIPHER statement

In case of the RSA algorithm the command input (except padding indicator byte) shall be formatted according to PCKS#1 before encryption.

Description Length Value
Start byte 1 00
Block type 1 02
Padding string (PS) N -3 - L Non-zero random bytes
Separator 1 00
Data L Message

...The card decrypts all bytes after the padding indicator byte, checks the conformance of correct PKCS#1 padding and returns the plain text (length = message) in the response.

I'm unsure if this means that the above table is how content must be provided to PSO:DECIPHER, or what?

Minimal API

YKFOpenPGPSession

YKFOpenPGPLimits
maxChallengeLength : UInt16 
typedef NS_ENUM(NSUInteger, YKFOpenPGPPINFormat) {
  YKFOpenPGPPINFormatUTF8,
  YKFOpenPGPPINFormatKDF,
  YKFOpenPGPPINFormatPINBlockFormat2
};

typedef NS_ENUM(NSUInteger, YKFOpenPGPPINSelector) {
  YKFOpenPGPPW1,
  YKFOpenPGPPW3,
  YKFOpenPGPPW1ResetCode,
};

typedef NS_ENUM(NSUInteger, YKFOpenPGPHashAlgorithm) {
  YKFOpenPGPHashAlgorithmSHA256,
  YKFOpenPGPHashAlgorithmSHA384,
  YKFOpenPGPHashAlgorithmSHA512,
  YKFOpenPGPHashAlgorithmECDSA
};

Initializer

  • init
    • Selects the OpenPGP application.
    • Reads the application related data.
    • Reads the card capabilities.
    • Reads the card service data.

Properties

Property Type Description
version YKFVersion AID bytes 7-8.
aid NSString Full application identifier formatted as a UTF-8 string.
serialNumber NSString AID bytes 9-16 formatted as a UTF-8 string.
limits YKFOpenPGPLimits Limits of the OpenPGP application.
pinFormat YKFOpenPGPPINFormat Internal format expected by the card.

Methods

typedef void (^YKFPINVerifyCompletion)(NSError * _Nullable error);
Method Description
verifyPW1(pin : NSString, isMultishot : BOOL, completion : YKFPINVerifyCompletion) : void Verifies the PW1 from a basic UTF-8 string, e.g. '123456'.
verifyPW3(pin : NSString, completion : YKFPINVerifyCompletion) : void Verifies the PW3 from a basic UTF-8 string, e.g. '12345678'.
computeDigitalSignature(contentToSign : NSData *, hashAlgorithm : YKFOpenPGPHashAlgorithm, completion : YKFOpenPGPCDSCompletion) : void Computes a digital signature.
`decipherMessage()

Expanded Use-Cases

PW Authentication

Expanded use-cases shall support authentication of PW1 and PW3 using S2K depending on the key's KDF configuration.

Interpreting Extended Capabilities for KDF capabilities

Command CLA INS P1 P2 Lc Data Le
GET DATA 00 CA 00 6E - - 00
Response Body Tag Size Description
Discretionary data objects 73 'sz' Followed by
Extended capabilities C0 0A
Bit Description
0 KDF-DO (Tag F9) and related functionality available.

KDF-DO - Tag F9

Read the KDF-DO to determine the KDF configuration.

Command CLA INS P1 P2 Lc Data Le
GET DATA 00 CA 00 F9 - - 00
Response Body Tag Size Description
KDF-DO F9 sz Followed by
KDF algorithm 81 01 00 for no KDF, 03 for OpenPGP S2K.
Hash algorithm 82 01 08 for SHA-256, 0A for SHA-512.
Iteration count 83 04 long integer. Big-endian.
Salt - PW1 84 xx
Salt - reset PW1 85 xx
Salt - PW3 86 xx
Initial hash PW1 87 xx
Initial hash PW3 88 xx

PW Authentication using OpenPGP S2K Function

Section 4.3.2 of The Specification specifies RFC-4880 for the S2K function. At the time of authoring, RFC-4880 has obseleted by RFC-9580.

Extended Length APDUs

  • 2F01 contains *Extended lengthh information" if extended length is announced in the Historical bytes 5F52.
  • 7F66 contains Extended length information if extended length is announced in the Historical bytes 5F52.

Reading optional DOs

Cardholder related data - Tag 65

  • Name

Public keys URL - Tag 5F50

Generate Private Key

Client/Server Authentication

Using OpenPGP Certificate

Using X.509 Certificate - Cardholder Certificate (CHC - 7F21)

Expanded API

YKFOpenPGPLimits
maxChallengeLength : UInt16
YKFOpenPGPPINFormatKDF
kdfAlgorithm : YKFOpenPGPKDFAlgorithm
hashAlgorithm : YKFOpenPGPHashAlgorithm
iterationCount : UInt32
saltPW1 : Data
saltResetPW1 : Data
saltPW3 : Data
initialHashPW1 : Data
initialHashPW3 : Data 
typedef NS_ENUM(NSUInteger, YKFOpenPGPKDFAlgorithm) {
  YKFOpenPGPKDFAlgorithmNone,
  YKFOpenPGPKDFAlgorithmOpenPGPS2K
};

PIN Handling Abstraction

  • @protocol YKFOpenPGPPINFormat
    • YKFOpenPGPPINFormatUTF8
    • YKFOpenPGPPINFormatKDF
    • YKFOpenPGPPINFormatPINBlockFormat2

Properties

Property Type Description
pinHandler YKFOpenPGPPINFormat Abstraction for handling variations of the PIN.

Methods