idnits 2.17.00 (12 Aug 2021) /tmp/idnits31453/draft-ietf-keyprov-portable-symmetric-key-container-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 3001. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 3012. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 3019. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 3025. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Too long document name: The document name (without revision number), 'draft-ietf-keyprov-portable-symmetric-key-container', is 51 characters long, but may be at most 50 characters Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 2254 has weird spacing: '...inition http:...' == Line 2270 has weird spacing: '...inition http:...' == Line 2287 has weird spacing: '...inition http:...' == Line 2304 has weird spacing: '...inition http:...' == Line 2322 has weird spacing: '...inition http:...' == (2 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o (OPTIONAL), the start date of the key, it MUST not be possible to use this key before this date. MUST be expressed in UTC form, with no time zone component. Implementations SHOULD NOT rely on time resolution finer than milliseconds and MUST NOT generate time instants that specify leap seconds. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o (OPTIONAL), the expiry date of the key, it MUST not be possible to use this key after this date. MUST be expressed in UTC form, with no time zone component. Implementations SHOULD NOT rely on time resolution finer than milliseconds and MUST NOT generate time instants that specify leap seconds. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o (OPTIONAL), the maximum number of times the PIN can be entered wrongly before it MUST not be possible to use the key anymore == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o (OPTIONAL), the minimum lenght of a PIN that can be set to protect this key. It MUST not be possible to set a PIN shorter than this value. If the Format element is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters. If the Format attribute is 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o (OPTIONAL), the maximum lenght of a PIN that can be set to protect this key. It MUST not be possible to set a PIN longer than this value. If the Format element is 'DECIMAL', 'HEXADECIMAL' or 'ALPHANUMERIC' this value indicates the number of digits/characters. If the Format attribute is 'BASE64' or 'BINARY', this value indicates the number of bytes of the unencoded value. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 14, 2008) is 5058 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'PKCS1' is defined on line 2875, but no explicit reference was found in the text == Unused Reference: 'OATH' is defined on line 2938, but no explicit reference was found in the text == Unused Reference: 'OCRA' is defined on line 2941, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2437 (ref. 'PKCS1') (Obsoleted by RFC 3447) -- Possible downref: Non-RFC (?) normative reference: ref. 'PKCS5' ** Obsolete normative reference: RFC 2434 (Obsoleted by RFC 5226) ** Obsolete normative reference: RFC 3023 (Obsoleted by RFC 7303) ** Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838) -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLDSIG' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLENC' == Outdated reference: draft-mraihi-mutual-oath-hotp-variants has been published as RFC 6287 Summary: 6 errors (**), 0 flaws (~~), 16 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 keyprov P. Hoyer 3 Internet-Draft ActivIdentity 4 Intended status: Standards Track M. Pei 5 Expires: January 15, 2009 VeriSign 6 S. Machani 7 Diversinet 8 July 14, 2008 10 Portable Symmetric Key Container 11 draft-ietf-keyprov-portable-symmetric-key-container-05.txt 13 Status of this Memo 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on January 15, 2009. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2008). 42 Abstract 44 This document specifies a symmetric key format for transport and 45 provisioning of symmetric keys (for example One Time Password (OTP) 46 shared secrets or symmetric cryptographic keys) to different types of 47 crypto modules such as a strong authentication device. The standard 48 key transport format enables enterprises to deploy best-of-breed 49 solutions combining components from different vendors into the same 50 infrastructure. 52 This work is a joint effort by the members of OATH (Initiative for 53 Open AuTHentication) to specify a format that can be freely 54 distributed to the technical community. The authors believe that a 55 common and shared specification will facilitate adoption of two- 56 factor authentication on the Internet by enabling interoperability 57 between commercial and open-source implementations. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 63 2.1. Key Words . . . . . . . . . . . . . . . . . . . . . . . . 6 64 2.2. Definitions . . . . . . . . . . . . . . . . . . . . . . . 6 65 3. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 3.1. Online Use Cases . . . . . . . . . . . . . . . . . . . . . 8 67 3.1.1. Transport of keys from Server to Cryptomodule . . . . 8 68 3.1.2. Transport of keys from Cryptomodule to Cryptomodule . 8 69 3.1.3. Transport of keys from Cryptomodule to Server . . . . 9 70 3.1.4. Server to server Bulk import/export of keys . . . . . 9 71 3.2. Offline Use Cases . . . . . . . . . . . . . . . . . . . . 9 72 3.2.1. Server to server Bulk import/export of keys . . . . . 9 73 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 11 74 5. Portable Key container definition . . . . . . . . . . . . . . 13 75 5.1. KeyContainer . . . . . . . . . . . . . . . . . . . . . . . 14 76 5.2. KeyProperties . . . . . . . . . . . . . . . . . . . . . . 16 77 5.3. Device . . . . . . . . . . . . . . . . . . . . . . . . . . 17 78 5.3.1. DeviceInfo . . . . . . . . . . . . . . . . . . . . . . 18 79 5.4. Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 80 5.4.1. KeyData . . . . . . . . . . . . . . . . . . . . . . . 23 81 5.4.2. Usage . . . . . . . . . . . . . . . . . . . . . . . . 25 82 5.4.3. ValueFormat . . . . . . . . . . . . . . . . . . . . . 29 83 5.4.4. PINPolicy . . . . . . . . . . . . . . . . . . . . . . 29 84 6. Usage and profile of algorithms for the portable symmetric 85 key container . . . . . . . . . . . . . . . . . . . . . . . . 33 86 6.1. Usage of EncryptionKey to protect keys in transit . . . . 33 87 6.1.1. Protecting keys using a pre-shared key via 88 symmetric algorithms . . . . . . . . . . . . . . . . . 33 89 6.1.2. Protecting keys using passphrase based encryption 90 keys . . . . . . . . . . . . . . . . . . . . . . . . . 34 91 6.2. Protecting keys using asymmetric algorithms . . . . . . . 36 92 6.3. Profile of Key Algorithm . . . . . . . . . . . . . . . . . 37 93 6.3.1. OTP Key Algorithm Identifiers . . . . . . . . . . . . 38 94 6.3.2. PIN key value compare algorithm identifier . . . . . . 38 95 7. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 39 96 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 97 8.1. Content-type registration for 'application/pskc+xml' . . . 46 98 8.2. XML Schema Registration . . . . . . . . . . . . . . . . . 47 99 8.3. URN Sub-Namespace Registration for 100 urn:ietf:params:xml:ns:keyprov:pskc:1.0 . . . . . . . . . 47 101 8.4. Symmetric Key Algorithm Identifier Registry . . . . . . . 48 102 8.4.1. Applicability . . . . . . . . . . . . . . . . . . . . 48 103 8.4.2. Registerable Algorithms . . . . . . . . . . . . . . . 49 104 8.4.3. Registration Procedures . . . . . . . . . . . . . . . 50 105 8.4.4. Initial Values . . . . . . . . . . . . . . . . . . . . 52 106 9. Security Considerations . . . . . . . . . . . . . . . . . . . 57 107 9.1. Payload confidentiality . . . . . . . . . . . . . . . . . 57 108 9.2. Payload integrity . . . . . . . . . . . . . . . . . . . . 58 109 9.3. Payload authenticity . . . . . . . . . . . . . . . . . . . 58 110 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 59 111 11. Appendix A - Example Symmetric Key Containers . . . . . . . . 60 112 11.1. Symmetric Key Container with a single Non-Encrypted 113 HOTP Secret Key . . . . . . . . . . . . . . . . . . . . . 60 114 11.2. Symmetric Key Container with a single PIN protected 115 Non-Encrypted HOTP Secret Key . . . . . . . . . . . . . . 60 116 11.3. Symmetric Key Container with a single AES-256-CBC 117 Encrypted HOTP Secret Key and non-encrypted counter 118 value . . . . . . . . . . . . . . . . . . . . . . . . . . 62 119 11.4. Symmetric Key Container with signature and a single 120 Password-based Encrypted HOTP Secret Key . . . . . . . . . 63 121 11.5. Symmetric Key Container with a single RSA 1.5 122 Encrypted HOTP Secret Key . . . . . . . . . . . . . . . . 65 123 11.6. Symmetric Key Container with a single AES-256-CBC 124 Encrypted OCRA Secret Key and non-encrypted counter 125 value . . . . . . . . . . . . . . . . . . . . . . . . . . 66 126 11.7. Symmetric Key Container with a single AES-256-CBC 127 Encrypted TOTP Secret Key and non-encrypted time values . 68 128 11.8. Symmetric Key Container with two devices containing a 129 Non-Encrypted HOTP Secret Key each sharing common 130 KeyProperties . . . . . . . . . . . . . . . . . . . . . . 69 131 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 71 132 12.1. Normative References . . . . . . . . . . . . . . . . . . . 71 133 12.2. Informative References . . . . . . . . . . . . . . . . . . 71 134 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 73 135 Intellectual Property and Copyright Statements . . . . . . . . . . 74 137 1. Introduction 139 With increasing use of symmetric key based authentication systems 140 such as systems based one time password (OTP) and challenge response 141 mechanisms, there is a need for vendor interoperability and a 142 standard format for importing, exporting or provisioning symmetric 143 keys from one system to another. Traditionally authentication server 144 vendors and service providers have used proprietary formats for 145 importing, exporting and provisioning these keys into their systems 146 making it hard to use tokens from vendor A with a server from vendor 147 B. 149 This Internet draft describes a standard format for serializing 150 symmetric keys such as OTP shared secrets for system import, export 151 or network/protocol transport. The goal is that the format will 152 facilitate dynamic provisioning and transfer of symmetric keys such 153 as OTP shared secrets or encryption keys of different types. In the 154 case of OTP shared secrets, the format will facilitate dynamic 155 provisioning using an online provisioning protocol to different 156 flavors of embedded tokens or allow customers to import new or 157 existing tokens in batch or single instances into a compliant system. 159 This draft also specifies the key attributes required for computation 160 such as the initial event counter used in the HOTP algorithm [HOTP]. 161 It is also applicable for other time-based or proprietary algorithms. 163 To provide an analogy, in public key environments the PKCS#12 format 164 [PKCS12] is commonly used for importing and exporting private keys 165 and certificates between systems. In the environments outlined in 166 this document where OTP keys may be transported directly down to 167 smartcards or devices with limited computing capabilities, a format 168 with small (size in bytes) and explicit shared secret configuration 169 attribute information is desirable, avoiding complexity of PKCS#12. 170 For example, one would have to use opaque data within PKCS#12 to 171 carry shared secret attributes used for OTP calculations, whereas a 172 more explicit attribute schema definition is better for 173 interoperability and efficiency. 175 2. Terminology 177 2.1. Key Words 179 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 180 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 181 document are to be interpreted as described in [RFC2119]. 183 2.2. Definitions 185 This section defines terms used in this document. The same terms may 186 be defined differently in other documents. 188 Authentication Token: A physical device that an authorized user of 189 computer services is given to aid in authentication. The term may 190 also refer to software tokens. 192 Bulk Provisioning: Transferring multiple keys linked to multiple 193 devices in a single execution step within one single PSKC 194 KeyContainer 196 Cryptographic Module: A component of an application, which enables 197 symmetric key cryptographic functionality 199 Cryptographic Key: A parameter used in conjunction with a 200 cryptographic algorithm that determines its operation in such a 201 way that an entity with knowledge of the key can reproduce or 202 reverse the operation, while an entity without knowledge of the 203 key cannot (see [NIST-SP800-57]) 205 Cryptographic Token: See Authentication Token 207 Device: A physical piece of hardware, or a software framework, that 208 hosts symmetric keys 210 DeviceInfo: A set of elements whose values combined uniquely 211 identify a device e.g. Manufacture 'Manufacturer and Serialnumber 212 '12345678' 214 Dynamic Provisioning: Usage of a protocol, such as DSKPP, to make a 215 key container available to a recipient 217 Encryption Key: A key used to encrypt key 219 Key: See Cryptographic Key 220 Hardware Token: See Authentication Token 222 Key Algorithm: A well-defined computational procedure that takes 223 variable inputs including a cryptographic key and produces an 224 output. 226 Key Container: An object that encapsulates symmetric keys and their 227 attributes for set of devices 229 Key ID (KeyID): A unique identifier for the symmetric key 231 Key Issuer: An organization that issues symmetric keys to end-users 233 Key Type: The type of symmetric key cryptographic methods for which 234 the key will be used (e.g., OATH HOTP or RSA SecurID 235 authentication, AES encryption, etc.) 237 Secret Key: The symmetric key data 239 Software Token: A type of authentication token that is stored on a 240 general-purpose electronic device such as a desktop computer, 241 laptop, PDA, or mobile phone 243 Token: See Authentication Token 245 User: The person or client to whom devices are issued 247 User ID: A unique identifier for the user or client 249 3. Use Cases 251 This section describes a comprehensive list of use cases that 252 inspired the development of this specification. These requirements 253 were used to derive the primary requirement that drove the design. 254 These requirements are covered in the next section. 256 These use cases also help in understanding the applicability of this 257 specification to real world situations. 259 3.1. Online Use Cases 261 This section describes the use cases related to provisioning the keys 262 using an online provisioning protocol such as [DSKPP] 264 3.1.1. Transport of keys from Server to Cryptomodule 266 For example, a mobile device user wants to obtain a symmetric key for 267 use with a cryptomodule on the device. The cryptomodule client from 268 vendor A initiates the provisioning process against a provisioning 269 system from vendor B using a standards-based provisioning protocol 270 such as [DSKPP]. The provisioning entity delivers one or more keys 271 in a standard format that can be processed by the mobile device. 273 For example, in a variation of the above, instead of the user's 274 mobile phone, a key is provisioned in the user's soft token 275 application on a laptop using a network-based online protocol. As 276 before, the provisioning system delivers a key in a standard format 277 that can be processed by the soft token on the PC. 279 For example, the end-user or the key issuer wants to update or 280 configure an existing key in the cryptomodule and requests a 281 replacement key container. The container may or may not include a 282 new key and may include new or updated key attributes such as a new 283 counter value in HOTP key case, a modified response format or length, 284 a new friendly name, etc. 286 3.1.2. Transport of keys from Cryptomodule to Cryptomodule 288 For example, a user wants to transport a key from one cryptomodule to 289 another. There may be two cryptographic modules, one on a computer 290 one on a mobile phone, and the user wants to transport a key from the 291 computer to the mobile phone. The user can export the key and 292 related data in a standard format for input into the other 293 cryptomodule. 295 3.1.3. Transport of keys from Cryptomodule to Server 297 For example, a user wants to activate and use a new key and related 298 data against a validation system that is not aware of this key. This 299 key may be embedded in the cryptomodule (e.g. SD card, USB drive) 300 that the user has purchased at the local electronics retailer. Along 301 with the cryptomodule, the user may get the key on a CD or a floppy 302 in a standard format. The user can now upload via a secure online 303 channel or import this key and related data into the new validation 304 system and start using the key. 306 3.1.4. Server to server Bulk import/export of keys 308 From time to time, a key management system may be required to import 309 or export keys in bulk from one entity to another. 311 For example, instead of importing keys from a manufacturer using a 312 file, a validation server may download the keys using an online 313 protocol. The keys can be downloaded in a standard format that can 314 be processed by a validation system. 316 For example, in a variation of the above, an OTA key provisioning 317 gateway that provisions keys to mobile phones may obtain key material 318 from a key issuer using an online protocol. The keys are delivered 319 in a standard format that can be processed by the key provisioning 320 gateway and subsequently sent to the end-user's mobile phone. 322 3.2. Offline Use Cases 324 This section describes the use cases relating to offline transport of 325 keys from one system to another, using some form of export and import 326 model. 328 3.2.1. Server to server Bulk import/export of keys 330 For example, cryptomodules such as OTP authentication tokens, may 331 have their symmetric keys initialized during the manufacturing 332 process in bulk, requiring copies of the keys and algorithm data to 333 be loaded into the authentication system through a file on portable 334 media. The manufacturer provides the keys and related data in the 335 form of a file containing records in standard format, typically on a 336 CD. Note that the token manufacturer and the vendor for the 337 validation system may be the same or different. Some crypto modules 338 will allow local PIN management (the device will have a PIN pad) 339 hence random initial PINs set at manufacturing should be transmitted 340 together with the respective keys they protect. 342 For example, an enterprise wants to port keys and related data from 343 an existing validation system A into a different validation system B. 344 The existing validation system provides the enterprise with a 345 functionality that enables export of keys and related data (e.g. for 346 OTP authentication tokens) in a standard format. Since the OTP 347 tokens are in the standard format, the enterprise can import the 348 token records into the new validation system B and start using the 349 existing tokens. Note that the vendors for the two validation 350 systems may be the same or different. 352 4. Requirements 354 This section outlines the most relevant requirements that are the 355 basis of this work. Several of the requirements were derived from 356 use cases described above. 358 R1: The format MUST support transport of multiple types of 359 symmetric keys and related attributes for algorithms including 360 HOTP, other OTP, challenge-response, etc. 362 R2: The format MUST handle the symmetric key itself as well of 363 attributes that are typically associated with symmetric keys. 364 Some of these attributes may be 366 * Unique Key Identifier 368 * Issuer information 370 * Algorithm ID 372 * Algorithm mode 374 * Issuer Name 376 * Key friendly name 378 * Event counter value (moving factor for OTP algorithms) 380 * Time value 382 R3: The format SHOULD support both offline and online scenarios. 383 That is it should be serializable to a file as well as it 384 should be possible to use this format in online provisioning 385 protocols such as [DSKPP] 387 R4: The format SHOULD allow bulk representation of symmetric keys 389 R5: The format SHOULD allow bulk representation of PINs related to 390 specific keys 392 R6: The format SHOULD be portable to various platforms. 393 Furthermore, it SHOULD be computationally efficient to process. 395 R7: The format MUST provide appropriate level of security in terms 396 of data encryption and data integrity. 398 R8: For online scenarios the format SHOULD NOT rely on transport 399 level security (e.g., SSL/TLS) for core security requirements. 401 R9: The format SHOULD be extensible. It SHOULD enable extension 402 points allowing vendors to specify additional attributes in the 403 future. 405 R10: The format SHOULD allow for distribution of key derivation data 406 without the actual symmetric key itself. This is to support 407 symmetric key management schemes that rely on key derivation 408 algorithms based on a pre-placed master key. The key 409 derivation data typically consists of a reference to the key, 410 rather than the key value itself. 412 R11: The format SHOULD allow for additional lifecycle management 413 operations such as counter resynchronization. Such processes 414 require confidentiality between client and server, thus could 415 use a common secure container format, without the transfer of 416 key material. 418 R12: The format MUST support the use of pre-shared symmetric keys to 419 ensure confidentiality of sensitive data elements. 421 R13: The format MUST support a password-based encryption (PBE) 422 [PKCS5] scheme to ensure security of sensitive data elements. 423 This is a widely used method for various provisioning 424 scenarios. 426 R14: The format SHOULD support asymmetric encryption algorithms such 427 as RSA to ensure end-to-end security of sensitive data 428 elements. This is to support scenarios where a pre-set shared 429 encryption key is difficult to use. 431 5. Portable Key container definition 433 The portable key container is based on an XML schema definition and 434 contains the following main entities: 436 1. KeyContainer entity as defined in Section 5.1 438 2. KeyProperties entity as defined in Section 5.2 440 3. Device entity as defined in Section 5.3 442 4. Key entity as defined in Section 5.4 444 Additionally other XML schema types have been defined and are 445 detailed in the relevant subsections of this document 447 A KeyContainer MAY contain one or more Device entities. A Device MAY 448 contain one or more Key entities 450 The figure below indicates a possible relationship diagram of a 451 container. 453 -------------------------------------------- 454 | KeyContainer | 455 | | 456 | -------------------- | 457 | | Keyproperties 1 | | 458 | | | | 459 | -------------------- | 460 | ------------------ ----------------- | 461 | | Device 1 | | Device n | | 462 | | | | | | 463 | | ------------ | | ------------ | | 464 | | | Key 1 | | | | Key n | | | 465 | | ------------ | | ------------ | | 466 | | | | | | 467 | | | | | | 468 | | ------------ | | ------------ | | 469 | | | Key m | | | | Key p | | | 470 | | ------------ | | ------------ | | 471 | ------------------ ----------------- | 472 | | 473 -------------------------------------------- 475 The following sections describe in detail all the entities and 476 related XML schema elements and attributes: 478 5.1. KeyContainer 480 The KeyContainer represents the key container entity. A Container 481 MAY contain more than one Device entity; each Device entity MAY 482 contain more than one Key entity. 484 The KeyContainer is defined as follows: 486 487 488 490 492 495 498 500 503 504 506 508 510 The attributes of the KeyContainer have the following meanings: 512 o Version (MANDATORY), the version number for the portable key 513 container format (the XML schema defined in this document). 515 o ID (OPTIONAL), the unique ID for this container in case an XML 516 document contains more than one container and wants to refer to 517 them uniquely. 519 The elements of the KeyContainer have the following meanings: 521 o (OPTIONAL), Identifies the encryption key, 522 algorithm and possible parameters used to protect the Secret Key 523 data in the container. Please see Section 6.1 for detailed 524 description of how to protect key data in transit and the usage of 525 this element. 527 o (OPTIONAL), Identifies the algorithm used to 528 generate a keyed digest of the Secret Key data values when 529 protection algorithms are used that do not have integrity checks. 530 The digest guarantees the integrity and the authenticity of the 531 key data. for profile and usage please see Section 6.1.1 533 o (OPTIONAL), key property entities containing key 534 related properties that are common for keys within this container. 535 Please see Section 5.2 for detailed description of this 536 element.The KeyContainer MAY contain multiple KeyProperties 537 elements each containing a set of properties related to one or 538 more keys transported within the container. 540 o (MANDATORY), the host Device for one or more Keys as 541 defined in Section 5.3 The KeyContainer MAY contain multiple 542 Device data elements, allowing for bulk provisioning of multiple 543 devices each containing multiple keys. 545 o (OPTIONAL), the signature value of the Container. 546 When the signature is applied to the entire container, it MUST use 547 XML Signature methods as defined in [XMLDSIG]. It MAY be omitted 548 when application layer provisioning or transport layer 549 provisioning protocols provide the integrity and authenticity of 550 the payload between the sender and the recipient of the container. 551 When required, this specification recommends using a symmetric key 552 based signature with the same key used in the encryption of the 553 secret key data. The signature is enveloped. 555 o (OPTIONAL), is the extension point for this entity. 556 All extensions are grouped under this element and will be of type 557 pskc:ExtensionType, which contains an optional attribute 558 'defintion' that can have a URI pointing at the defintion of the 559 extension. In this way groups of extension can be bundled under a 560 subelement. For example: 562 563 blah 565 blahblah 566 568 5.2. KeyProperties 570 The KeyProperties represents common properties shared by more than 571 one key held in the container. If a value is set in the properties 572 the Key element can refer to it via ID attribute. Values that are 573 present in the Key element itself MUST take precedence over values 574 set in KeyProperties. The KeyProperties is defined as follows: 576 577 578 580 582 584 586 588 590 592 594 597 598 600 602 604 The attributes of the KeyProperties entity have the following 605 meanings: 607 o ID (MANDATORY), a unique and global identifier of set of 608 KeyProperties. The identifier is defined as a string of 609 alphanumeric characters. 611 o KeyAlgorithm (OPTIONAL), the unique URI of the type of algorithm 612 to use with a secret key for the profiles described in Section 6.3 614 Since KeyProperties are a method to group element values that are 615 common to multiple keys transported, please refer to Section 5.4 for 616 detailed description of all elements. 618 5.3. Device 620 The Device represents an extensible Device entity in the Container. 621 A Device MAY be bound to a user and MAY contain more than one key. A 622 key SHOULD be bound to only one Device. 624 The Device is defined as follows: 626 627 628 630 632 633 636 637 639 The elements of the Device have the following meanings: 641 o (OPTIONAL), a set of elements containing information 642 about the device, whose values uniquely identify the device, 643 defined in Section 5.3.1 645 o (MANDATORY), represents the key entity as defined in 646 Section 5.4 648 o (OPTIONAL), identifies the owner or the user of the Device, 649 a string representation of a Distinguished Name as defined in 650 [RFC4514]. For example UID=jsmith,DC=example,DC=net. In systems 651 where unique user Ids are used the string representation 652 'UID=[uniqueId]' SHOULD be used. 654 o (OPTIONAL), is the extension point for this entity. 655 All extensions are grouped under this element and will be of type 656 pskc:ExtensionType, which contains an optional attribute 657 'defintion' that can have a URI pointing at the defintion of the 658 extension. In this way groups of extension can be bundled under a 659 subelement. For example: 661 662 blah 664 blahblah 665 667 5.3.1. DeviceInfo 669 The DeviceInfo represents an extensible set of elements that form the 670 identifying criteria to uniquely identify the device that contains 671 the associated keys. Since devices can come in different form 672 factors such as hardware tokens, smart-cards, soft tokens in a mobile 673 phone or PC etc this element allows different criteria to be used. 674 Combined though the criteria MUST uniquely identify the device. For 675 example for hardware tokens the combination of SerialNo and 676 Manufacturer will uniquely identify a device but not SerialNo alone 677 since two different token manufacturers might issue devices with the 678 same serial number (similar to the IssuerDN and serial number of a 679 certificate). Symmetric Keys used in the payment industry are 680 usually stored on Integrated Circuit Smart Cards. These cards are 681 uniquely identified via the Primary Account Number (PAN, the long 682 number printed on the front of the card) and an expiry date of the 683 card. DeviceInfo is an extensible type that allows all these 684 different ways to uniquely identify a specific key containing device. 686 The DeviceInfo is defined as follows: 688 689 690 691 692 693 694 695 696 697 700 701 703 The elements of DeviceInfo have the following meanings: 705 o (MANDATORY), the manufacturer of the device. 707 o (MANDATORY), the serial number of the device or the PAN 708 (primary account number) in case of payment smart cards. 710 o (OPTIONAL), the model of the device (e.g. one-button-HOTP- 711 token-V1) 713 o (OPTIONAL), the issue number in case of smart cards with 714 the same PAN, equivalent to a PSN (PAN Sequence Number). 716 o (OPTIONAL), the identifier that can be used to 717 bind keys to the device or class of device. When loading keys 718 into a device, this identifier can be checked against information 719 obtained from the device to ensure that the correct device or 720 class of device is being used. 722 o (OPTIONAL), the start date of a device (such as the 723 one on a payment card, used when issue numbers are not printed on 724 cards). MUST be expressed in UTC form, with no time zone 725 component. Implementations SHOULD NOT rely on time resolution 726 finer than milliseconds and MUST NOT generate time instants that 727 specify leap seconds. 729 o (OPTIONAL), the expiry date of a device (such as the 730 one on a payment card, used when issue numbers are not printed on 731 cards). MUST be expressed in UTC form, with no time zone 732 component. Implementations SHOULD NOT rely on time resolution 733 finer than milliseconds and MUST NOT generate time instants that 734 specify leap seconds. 736 o (OPTIONAL), is the extension point for this entity. 737 All extensions are grouped under this element and will be of type 738 pskc:ExtensionType, which contains an optional attribute 739 'defintion' that can have a URI pointing at the defintion of the 740 extension. In this way groups of extension can be bundled under a 741 subelement. For example: 743 744 blah 746 blahblah 747 749 5.4. Key 751 The Key represents the key entity in the KeyContainer. The Key is 752 defined as follows: 754 755 756 758 760 762 764 766 768 770 772 774 776 779 780 782 784 786 788 The attributes of the Key entity have the following meanings: 790 o KeyId (MANDATORY), a unique and global identifier of the symmetric 791 key. The identifier is defined as a string of alphanumeric 792 characters. This identifier SHOULD be valid globally and outside 793 of the instance document of the container. 795 o KeyAlgorithm (OPTIONAL), the unique URI of the type of algorithm 796 to use with the secret key, for profiles are described in 797 Section 6.3 799 o KeyProperties (OPTIONAL), the references to the unique id of the 800 KeyProperties whose value the instance of this key inherits. If 801 this value is set implementation MUST lookup the Keyproperties 802 element referred to by this unique Id and this instance of key 803 will inherit all values from the KeyProperties. Values held in 804 the key instance MUST take precedence over values inherited from 805 KeyProperties."/> 807 The elements of the Key entity have the following meanings: 809 o (OPTIONAL), The key issuer name, this is normally the 810 name of the organization that issues the key to the end user of 811 the key. For example MyBank issuing hardware tokens to their 812 retail banking users 'MyBank' would be the issuer. The Issuer is 813 defined as a String. 815 o (OPTIONAL), defines the intended usage of the key and 816 related metadata as defined in Section 5.4.2 818 o (OPTIONAL), A unique identifier used between the 819 sending and receiving party of the container to establish a set of 820 constant values related to a key that are not transmitted via the 821 container. For example a smart card application personalisation 822 profile id related to attributes present on a smart card 823 application that have influence when computing a response. An 824 example could be an EMV MasterCard CAP [CAP] application on a card 825 personalised with data for a specific batch of cards such as: 827 IAF Internet authentication flag 829 CVN Cryptogram version number, for example (MCHIP2, MCHIP4, 830 VISA 13, VISA14) 832 AIP (Application Interchange Profile), 2 bytes 834 TVR Terminal Verification Result, 5 bytes 836 CVR The card verification result 838 AmountOther 840 TransactionDate 842 TerminalCountryCode 844 TransactionCurrencyCode 845 AmountAuthorised 847 IIPB 849 These values are not contained within attributes in the container 850 but are shared between the manufacturing and the validation 851 service through this unique KeyProfileId. The KeyProfileId is 852 defined as a String. 854 o (OPTIONAL), The unique reference to an external 855 master key when key derivation schemes are used and no specific 856 key is transported but only the reference to the master key used 857 to derive a specific key and some derivation data (e.g. the 858 PKCS#11 key label in an HSM). 860 o (OPTIONAL), The user friendly name that is assigned 861 to the secret key for easy reference. The FriendlyName is defined 862 as a String. 864 o (OPTIONAL), the element carrying the data related to the 865 key as defined in Section 5.4.1 867 o (OPTIONAL), the policy of the PIN relating to the 868 usage of this key as defined in Section 5.4.4 870 o (OPTIONAL), the start date of the key, it MUST not be 871 possible to use this key before this date. MUST be expressed in 872 UTC form, with no time zone component. Implementations SHOULD NOT 873 rely on time resolution finer than milliseconds and MUST NOT 874 generate time instants that specify leap seconds. 876 o (OPTIONAL), the expiry date of the key, it MUST not 877 be possible to use this key after this date. MUST be expressed in 878 UTC form, with no time zone component. Implementations SHOULD NOT 879 rely on time resolution finer than milliseconds and MUST NOT 880 generate time instants that specify leap seconds. 882 o (OPTIONAL), identifies the user account (e.g. username or 883 user id) to which the key is assigned. The value MAY be a string 884 representation of a Distinguished Name as defined in [RFC4514]. 885 For example "UID=jsmith,DC=example,DC=net". In systems where 886 unique user Ids are used the string representation 887 'UID=[uniqueId]' SHOULD be used. 889 o (OPTIONAL), is the extension point for this entity. 890 All extensions are grouped under this element and will be of type 891 pskc:ExtensionType, which contains an optional attribute 892 'defintion' that can have a URI pointing at the defintion of the 893 extension. In this way groups of extension can be bundled under a 894 subelement. For example: 896 897 blah 899 blahblah 900 902 5.4.1. KeyData 904 Defines an extensible set of data elements relating to a key 905 including the key value itself (secret). After considerable 906 discussions in forums and at IETF the authors needed a mean to convey 907 data related to a key in an extensible form. The requirements were 908 that the data elements could be encrypted but not via XML encryption 909 which was deemed to complex because of canonicalization. Hence 910 earlier drafts made use of a list of name value pairs. This was not 911 considered to be very XML like and also lacked inbuilt support for 912 typing. Hence the current apporach is to have within KeyData a set 913 of elements that have both typing and can be encrypted. 915 All elements within Data hence obey a simple structure in that they 916 MUST have: 918 a choice between: 920 A element that is typed to the specific type (e.g. 921 xs:integer) 923 An element that is of type xenc:EncryptedDataType 924 where the value of the specific element is placed in case it is 925 encrypted 927 an optional element that is populated with a MAC in case 928 the encryption algorithm does not support integrity checks 930 For example the pskc:intDataType is defined as follows: 932 933 934 935 937 939 940 942 943 945 The following typed base types have been defined within the current 946 schema of the PSKC spec with the naming convention DataType 947 (e.g. intDataType) to be able to cater transmission of key data 948 elements: 950 pskc:intDataType - to carry data elements of type integer, 951 PlainValue sub element is of type xs:integer. When encrypted the 952 binary value MUST be 4 bytes unsigned integer in big endian (i.e. 953 network byte order) form 955 pskc:longDataType - to carry data elements of type long, 956 PlainValue sub element is of type xs:long. When encrypted the 957 binary value MUST be 8 bytes unsigned integer in big endian (i.e. 958 network byte order) form 960 pskc:binaryDataType - to carry data elements of type binary, 961 PlainValue sub element is of type xs:Base64Binary 963 pskc:stringDataType - to carry data elements of type string, 964 PlainValue sub element is of type xs:string. When encrypted the 965 binary value MUST UTF-8 encoded string in binary form 967 Therefore the KeyData element is defined as follows and contains sub 968 ements to convey the values required by algorithms considered during 969 the definition of this specification: 971 972 973 975 977 979 981 983 985 986 988 The elements of the Data element have the following meanings: 990 o (OPTIONAL), the value of the key itself in binary. 992 o (OPTIONAL), the event counter for event based OTP 993 algorithms. 995 o