/* * Copyright (c) 2004-2007 Apple Inc. All Rights Reserved. * * @APPLE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ */ /* * PIVDefines.h * TokendPIV */ #ifndef _PIVDEFINES_H_ #define _PIVDEFINES_H_ /* For the PIV tokend, refer to NIST Specical Publication 800-73-1, "Interfaces for Personal Identity Verification". The define for CLA_STANDARD comes from 2.3.3.1.1. [SP800731] See Appendix A for useful codes. Object identifiers: 4.2 OIDs and Tags of PIV Card Application Data Objects [SP800731] The other publication referenced here is NIST IR 6887 - 2003 Edition (GSC-IS Version 2.1) [NISTIR6887] Also useful is NIST Special Publication 800-85A [SP80085A] P1 - Reference Control Parameter See "Table 1. SP 800-73 Data Model Containers" for RID and object IDs for data objects (p 5) See "Appendix A - PIV Data Model" for object IDs (p 45) */ #pragma mark ---------- PIV defines ---------- #define PIV_CLA_STANDARD 0x00 #define PIV_CLA_CHAIN 0x10 #define PIV_INS_SELECT_FILE 0xA4 #define PIV_INS_VERIFY_APDU 0x20 // SP800731 Section 2.3.3.2.1 #define PIV_INS_CHANGE_REFERENCE_DATA 0x24 // [SP800731 7.2.2] #define PIV_INS_GET_DATA 0xCB // [SP800731 7.1.2] #define PIV_INS_GENERAL_AUTHENTICATE 0x87 // [SP800731 7.2.4] // Placeholders for fields in the APDU to be filled in programmatically #define TBD_ZERO 0x00 #define TBD_FF 0xFF // These are from NISTIR6887 5.1.1.4 Select File APDU // They are the values for the P1 field #define SELECT_P1_EXPLICIT 0x00 #define SELECT_P1_CHILDDF 0x01 #define SELECT_P1_CHILDEF 0x02 #define SELECT_P1_PARENTDF 0x03 /* Reference: [SP800731] Appendix A PIV Data Model (data sizes) Name ID Size Card Capabilities Container 0xDB00 266 Card Holder Unique Identifier 0x3000 3377 X.509 Certificates ------ 1651 Card Holder Fingerprints 0x6010 7768 Printed Information 0x3001 106 Card Holder Facial Image 0x6030 12704 Security Object 0x9000 1000 */ #define PIV_MAX_DATA_SIZE (12704+1024) // plus some extra #pragma mark ---------- Object IDs on Token ---------- /* Object IDs for objects on token. All currently 3 hex bytes. See 4.2 OIDs and Tags of PIV Card Application Data Objects [SP800731] 4.1 PIV Card Application Data Objects [SP800731] A PIV Card Application shall contain six mandatory data objects and five optional data object for interoperable use. The six mandatory data objects for interoperable use are as follows: 1. Card Capability Container 2. Card Holder Unique Identifier 3. X.509 Certificate for PIV Authentication 4. Card Holder Fingerprint I 5. Card Holder Fingerprint II2 6. Security Object The five optional data objects for interoperable use are as follows: 1. Card Holder Facial Image 2. Printed Information 3. X.509 Certificate for PIV Digital Signature 4. X.509 Certificate for PIV Key Management 5. X.509 Certificate for Card Authentication */ // Card Capability Container 2.16.840.1.101.3.7.1.219.0 '5FC107' M #define PIV_OBJECT_ID_CARD_CAPABILITY_CONTAINER 0x5F, 0xC1, 0x07 // Card Holder Unique Identifier 2.16.840.1.101.3.7.2.48.0 '5FC102' M [CHUID] #define PIV_OBJECT_ID_CARDHOLDER_UNIQUEID 0x5F, 0xC1, 0x02 // Card Holder Fingerprints 2.16.840.1.101.3.7.2.96.16 '5FC103' M #define PIV_OBJECT_ID_CARDHOLDER_FINGERPRINTS 0x5F, 0xC1, 0x03 // Printed Information 2.16.840.1.101.3.7.2.48.1 '5FC109' O #define PIV_OBJECT_ID_PRINTED_INFORMATION 0x5F, 0xC1, 0x09 // Card Holder Facial Image 2.16.840.1.101.3.7.2.96.48 '5FC108' O #define PIV_OBJECT_ID_CARDHOLDER_FACIAL_IMAGE 0x5F, 0xC1, 0x08 // X.509 Certificate for PIV Authentication 2.16.840.1.101.3.7.2.1.1 '5FC105' M #define PIV_OBJECT_ID_X509_CERTIFICATE_PIV_AUTHENTICATION 0x5F, 0xC1, 0x05 // X.509 Certificate for Digital Signature 2.16.840.1.101.3.7.2.1.0 '5FC10A' O #define PIV_OBJECT_ID_X509_CERTIFICATE_DIGITAL_SIGNATURE 0x5F, 0xC1, 0x0A // X.509 Certificate for Key Management 2.16.840.1.101.3.7.2.1.2 '5FC10B' O #define PIV_OBJECT_ID_X509_CERTIFICATE_KEY_MANAGEMENT 0x5F, 0xC1, 0x0B // X.509 Certificate for Card Authentication 2.16.840.1.101.3.7.2.5.0 '5FC101' O #define PIV_OBJECT_ID_X509_CERTIFICATE_CARD_AUTHENTICATION 0x5F, 0xC1, 0x01 // ---------------------------------------------------------------------------- /* Verify APDU [NISTIR6887 5.1.2.4] Function Code 0x08 CLA 0x00 INS 0x20 P1 0x00 P2 0x00 for default key, 0x01 to 0x30 for key number Lc Length of data field Data Field Authentication data (i.e., password or PIN) Le Empty Note: If the Lc is 0x00 and the Data Field is empty, VERIFY returns the number of tries remaining on the referenced PIN. NB: "empty" in these documents seems to mean "not present", as opposed to zeros */ // 0x00 0x20 P1 P2 #define PIV_VERIFY_APDU PIV_CLA_STANDARD, PIV_INS_VERIFY_APDU, 0x00, TBD_ZERO // Template for supplying a PIN to be verified // Lc #define PIV_VERIFY_APDU_TEMPLATE PIV_VERIFY_APDU, 0x08, TBD_FF, TBD_FF, TBD_FF, TBD_FF, \ TBD_FF, TBD_FF, TBD_FF, TBD_FF // Template used to check on the lock state only #define PIV_VERIFY_APDU_STATUS PIV_VERIFY_APDU, 0x00 #define PIV_VERIFY_APDU_INDEX_KEY 3 // Index into APDU for PIN number (i.e. which PIN) #define PIV_VERIFY_APDU_INDEX_LEN 4 // Index into APDU for data length (always 8) #define PIV_VERIFY_APDU_INDEX_DATA 5 // Index into APDU for PIN data // Allowable values for P2 in VERIFY APDU // P2 0x00 for default key, 0x01 to 0x30 for key number #define PIV_VERIFY_KEY_NUMBER_DEFAULT 0x00 #define PIV_VERIFY_KEY_NUMBER_MAX 0x30 #define PIV_VERIFY_PIN_LENGTH_MIN 4 #define PIV_VERIFY_PIN_LENGTH_MAX 8 // ---------------------------------------------------------------------------- /* CHANGE REFERENCE DATA Card Command (i.e. change PIN) [SP800731 7.2.2] Function Code 0x08 CLA 0x00 INS 0x24 P1 0x00 P2 0x00 for default key, 0x01 to 0x30 for key number Lc Length of data field (always 0x10) Data Field Current PIN reference data concatenated without delimitation with the new PIN reference data, both PINs as described in 3.5.3 Le Empty */ #define PIV_CHANGE_REFERENCE_DATA_APDU PIV_CLA_STANDARD, PIV_INS_CHANGE_REFERENCE_DATA, 0x00, TBD_ZERO, TBD_ZERO // Template for supplying a PIN to be changed // similar to PIV_VERIFY_APDU_TEMPLATE except with space for 2 PINs #define PIV_CHANGE_REFERENCE_DATA_APDU_TEMPLATE \ PIV_CHANGE_REFERENCE_DATA_APDU, \ TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, \ TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, TBD_FF, \ 0x00 // Index into APDU for new PIN data #define PIV_CHANGE_REFERENCE_DATA_APDU_INDEX_DATA2 (PIV_VERIFY_APDU_INDEX_DATA + PIV_VERIFY_PIN_LENGTH_MAX) // ---------------------------------------------------------------------------- /* Reference: [SP800731] 7.1.2 GET DATA Card Command The GET DATA card command retrieves the data content of the single data object whose tag is given in the data field. Command Syntax CLA 0x00 INS 0xCB P1 0x3F P2 0xFF Lc 0x10 Data Field See Table 16. Le Number of data content bytes to be retrieved. Table 16. Data Objects in the Data Field of the GET DATA Card Command Name Tag M/O Comment Tag list 0x5C M BER-TLV tag of the data object to be retrieved. See Table 6. Response Syntax Data Field BER-TLV with the tag '53' containing in the value field the requested data object. SW1-SW2 Status word SW1 SW2 Meaning '61' 'xx' Successful execution where SW2 encodes the number of response data bytes still available '69' '82' Security status not satisfied '6A' '82' Data object not found '90' '00' Successful execution Reference: Get Cert APDU: 00 CB 3F FF 05 5C 03 5F C1 05 APDU: 61 00 Get Printed Data APDU: 00 CB 3F FF 05 5C 03 5F C1 09 APDU: 61 44 */ // 0x00 0xCB #define PIV_GETDATA_APDU PIV_CLA_STANDARD, PIV_INS_GET_DATA, 0x3F, 0xFF // Template for getting data // 00 CB 3F FF Lc Tag Len OID1 OID2 OID3 #define PIV_GETDATA_APDU_TEMPLATE PIV_GETDATA_APDU, TBD_ZERO, 0x5C, TBD_ZERO, TBD_FF, TBD_FF, TBD_FF #define PIV_GETDATA_APDU_INDEX_LEN 4 // Index into APDU for APDU data length (this is TLV<OID>) [Lc] #define PIV_GETDATA_APDU_INDEX_OIDLEN 6 // Index into APDU for requested length of data #define PIV_GETDATA_APDU_INDEX_OID 7 // Index into APDU for object ID #define PIV_GETDATA_CONT_APDU_TEMPLATE 0x00, 0xC0, 0x00, 0x00, TBD_ZERO #define PIV_GETDATA_CONT_APDU_INDEX_LEN 4 // Index into CONT APDU for requested length of data #define PIV_GETDATA_RESPONSE_TAG 0x53 #define PIV_GETDATA_TAG_CERTIFICATE 0x70 #define PIV_GETDATA_TAG_CERTINFO 0x71 #define PIV_GETDATA_TAG_MSCUID 0x72 #define PIV_GETDATA_TAG_ERRORDETECTION 0xFE /* Reference: [SP800731] Appendix A PIV Data Model CertInfo::= BIT STRING { CompressionTypeMsb(0), // 0 = no compression and 1 = gzip compression. CompressionTypeLsb(1), // shall be set to "0" for PIV Applications IsX509(2), // shall be set to "0" for PIV Applications RFU3(3), RFU4(4), RFU5(5), RFU6(6), RFU7(7) } Note: the compression mask below should only be 0x80, but NASA cards use 0x01 (??) */ #define PIV_GETDATA_COMPRESSION_MASK 0x81 // ---------------------------------------------------------------------------- /* Card Identifier 0xF0 Fixed 21 Capability Container version number 0xF1 Fixed 1 Capability Grammar version number 0xF2 Fixed 1 Applications CardURL 0xF3 Variable 128 PKCS#15 0xF4 Fixed 1 Registered Data Model number 0xF5 Fixed 1 Access Control Rule Table 0xF6 Fixed 17 CARD APDUs 0xF7 Fixed 0 Redirection Tag 0xFA Fixed 0 Capability Tuples (CTs) 0xFB Fixed 0 Status Tuples (STs) 0xFC Fixed 0 */ #define PIV_CCC_TAG_CARD_IDENTIFIER 0xF0 #define PIV_CCC_TAG_CARD_CONTAINER_VERS 0xF1 #define PIV_CCC_TAG_CARD_GRAMMAR_VERS 0xF2 #define PIV_CCC_TAG_APPS_URL 0xF3 #define PIV_CCC_TAG_IS_PKCS15 0xF4 #define PIV_CCC_TAG_DATA_MODEL_NUMBER 0xF5 #define PIV_CCC_TAG_ACL_RULE_TABLE 0xF6 #define PIV_CCC_TAG_CARD_APDUS 0xF7 #define PIV_CCC_TAG_REDIRECTION 0xFA #define PIV_CCC_TAG_CAPABILITY_TUPLES 0xFB #define PIV_CCC_TAG_STATUS_TUPLES 0xFC #define PIV_CCC_TAG_NEXT_CCC 0xFD #define PIV_CCC_TAG_EXTENDED_APP_URL 0xE3 #define PIV_CCC_TAG_SEC_OBJECT_BUFFER 0xB4 #define PIV_CCC_TAG_ERROR_DETECTION 0xFE #define PIV_CCC_SZ_CARD_IDENTIFIER 21 // ---------------------------------------------------------------------------- /* Reference: [SP800-78-1] 6. Identifiers for PIV Card Interfaces Key References: */ #define PIV_KEYREF_PIV_AUTHENTICATION 0x9A #define PIV_KEYREF_PIV_CARD_MANAGEMENT 0x9B #define PIV_KEYREF_PIV_DIGITAL_SIGNATURE 0x9C #define PIV_KEYREF_PIV_KEY_MANAGEMENT 0x9D #define PIV_KEYREF_PIV_CARD_AUTHENTICATION 0x9E /* Algorithm Identifiers: (Listing Only RSA) */ /* NOTE: After 2008/12/31 user keys will no longer be issued as 1024 */ #define PIV_KEYALG_RSA_1024 0x06 #define PIV_KEYALG_RSA_2048 0x07 /* Reference: [SP800-73-1] 7.2.4 General Authenticate Command The GENERAL AUTHENTICATE card command performs a cryptographic operation such as an authentication protocol using the data provided in the data field of the command and returns the result of the cryptographic operation in the response data field. The GENERAL AUTHENTICATE command shall be used to authenticate the card or a card application to the client-application (INTERNAL AUTHENTICATE), to authenticate an entity to the card (EXTERNAL AUTHENTICATE), and to perform a mutual authentication between the card and an entity external to the card (MUTUAL AUTHENTICATE). The GENERAL AUTHENTICATE command shall be used to realize the signing functionality on the PIV client-application programming interface. Data sent to the card is expected to be hashed off-card. The GENERAL AUTHENTICATE command supports command chaining to permit the uninterrupted transmission of long command data fields to the PIV Card Application. If a card command other than the GENERAL AUTHENTICATICATE command is received by the PIV Card Application before the termination of a GENERAL AUTHENTICATE chain, the PIV Card Application shall rollback to the state it was in immediately prior to the reception of the first command in the interrupted chain. In other words, an interrupted GENERAL AUTHENTICATE chain has no effect on the PIV Card Application. Command Syntax CLA '00' or '10' indicating command chaining. INS '87' P1 Algorithm reference P2 Key reference Lc Length of data field Data Field See Table 17. Le Absent or length of expected response Table 17. Data Objects in the Dynamic Authentication Template (Tag '7C') Name Tag M/O Description Witness '80' C Demonstration of knowledge of a fact without revealing the fact. An empty witness is a request for a witness. Challenge '81' C One or more random numbers or byte sequences to be used in the authentication protocol. Response '82' C A sequence of bytes encoding a response step in an authentication protocol. Committed '83' C Hash-code of a large random number including one or challenge more challenges Authentication '84' C Hash-code of one or more data fields and a witness data code object. The data objects that appear in the dynamic authentication template (tag '7C') in the data field of the GENERAL AUTHENTICATE card command depend on the authentication protocol being executed. Response Syntax Data Field Absent or authentication-related data SW1-SW2 Status word == How to use for signing/decrypting == Build output data structure: 0x7C BER-LENGTH // Dynamic Auth Template 0x82 0x00 // Request for Response 0x81 BER-LENGTH // 'Challenge' the card for crypto data Assuming 256-bytes sendable each time while remaining data left if there will be more after this SEND 0x10 0x87 ALG KEY LEN (data chunk) else SEND 0x00 0x87 ALG KEY LEN (data chunk) */ // ---------------------------------------------------------------------------- #endif /* !_PIVDEFINES_H_ */