idnits 2.17.1 draft-urien-core-racs-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1087 has weird spacing: '... sid sid...' -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'ISO7816-Response' is mentioned on line 494, but not defined == Missing Reference: 'ISO7816-Request' is mentioned on line 489, but not defined == Missing Reference: 'ISO7816-Request-1' is mentioned on line 521, but not defined == Missing Reference: 'ISO7816-Request-2' is mentioned on line 522, but not defined == Missing Reference: 'ISO7816-Response-2' is mentioned on line 527, but not defined == Missing Reference: 'ISO7816-Response-1' is mentioned on line 526, but not defined == Missing Reference: '1000-2000' is mentioned on line 613, but not defined == Missing Reference: 'WARM' is mentioned on line 624, but not defined Summary: 0 errors (**), 0 flaws (~~), 10 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CORE Working Group P. Urien 3 Internet Draft Telecom ParisTech 4 Intended status: Experimental 6 June 13 2016 7 Expires: December 2016 9 Remote APDU Call Secure (RACS) 10 draft-urien-core-racs-07.txt 12 Abstract 14 This document describes the Remote APDU Call Protocol Secure (RACS) 15 protocol, dedicated to Grid of Secure Elements (GoSE). These servers 16 host Secure Elements (SE), i.e. tamper resistant chips offering 17 secure storage and cryptographic resources. 19 Secure Elements are microcontrollers whose chip area is about 25mm2; 20 they deliver trusted computing services in constrained environments. 22 RACS supports commands for GoSE inventory and data exchange with 23 secure elements. It is designed according to the representational 24 State Transfer (REST) architecture. RACS resources are identified by 25 dedicated URIs. An HTTP interface is also supported. 27 Requirements Language 29 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 30 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 31 document are to be interpreted as described in RFC 2119. 33 Status of this Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six 44 months and may be updated, replaced, or obsoleted by other documents 45 at any time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on December 2016. 50 . 52 Copyright Notice 54 Copyright (c) 2016 IETF Trust and the persons identified as the 55 document authors. All rights reserved. 57 This document is subject to BCP 78 and the IETF Trust's Legal 58 Provisions Relating to IETF Documents 59 (http://trustee.ietf.org/license-info) in effect on the date of 60 publication of this document. Please review these documents 61 carefully, as they describe your rights and restrictions with 62 respect to this document. Code Components extracted from this 63 document must include Simplified BSD License text as described in 64 Section 4.e of the Trust Legal Provisions and are provided without 65 warranty as described in the Simplified BSD License. 67 Table of Contents 68 Abstract........................................................... 1 69 Requirements Language.............................................. 1 70 Status of this Memo................................................ 1 71 Copyright Notice................................................... 2 72 1 Overview......................................................... 5 73 1.1 What is a Secure Element.................................... 5 74 1.2 Grid Of Secure Elements (GoSE).............................. 6 75 1.3 Secure Element Identifier (SEID)............................ 7 76 1.3.1 SlotID example ....................................... 7 77 1.3.2 SEID for Secure Elements ............................. 8 78 1.4 APDUs....................................................... 9 79 1.4.1 ISO7816 APDU request ................................. 9 80 1.4.2 ISO7816 APDU response ................................ 9 81 2 The RACS protocol............................................... 10 82 2.1 Structure of RACS request.................................. 10 83 2.2 Structure of a RACS response............................... 11 84 2.2.1 BEGIN Header ........................................ 11 85 2.2.2 END Header .......................................... 11 86 2.2.3 Status line ......................................... 11 87 2.2.4 Examples of RACS responses: ......................... 12 88 2.3 RACS request commands...................................... 12 89 2.3.1 BEGIN ............................................... 12 90 2.3.2 END ................................................. 12 91 2.3.3 The APPEND parameter ................................ 13 92 2.3.4 GET-VERSION ......................................... 14 93 2.3.5 SET-VERSION ......................................... 14 94 2.3.6 LIST ................................................ 15 95 2.3.7 RESET ............................................... 15 96 2.3.8 APDU ................................................ 16 97 2.3.9 SHUTDOWN ............................................ 19 98 2.3.10 POWERON ............................................ 20 99 2.3.11 ECHO ............................................... 21 100 2.4 Status header encoding..................................... 21 101 2.4.1 Event class ......................................... 22 102 2.4.2 Command class ....................................... 22 103 3 URI for the GoSE................................................ 23 104 4 HTTP interface.................................................. 23 105 4.1 HTTPS Request.............................................. 23 106 4.2 HTTPS response............................................. 24 107 5 Security Considerations......................................... 24 108 5.1 Authorization.............................................. 24 109 5.2 Secure Element access...................................... 24 110 5.3 Applications security policy............................... 25 111 5.3.1 Users-Table ......................................... 25 112 5.3.2 SEID-Table .......................................... 25 113 5.3.3 APDU-Table .......................................... 25 114 5.4 Overview of the security policy............................ 26 115 6 IANA Considerations............................................. 26 116 7 References...................................................... 26 117 7.1 Normative References....................................... 26 118 7.2 Informative References..................................... 26 119 8 Authors' Addresses.............................................. 27 120 1 Overview 122 This document describes the Remote APDU Call Protocol Secure (RACS) 123 protocol, dedicated to Grids of Secure Elements (GoSE). These 124 servers host Secure Elements (SE), i.e. tamper resistant chips 125 offering secure storage and cryptographic resources. 127 Secure Elements are microcontrollers whose chip area is about 25mm2; 128 they deliver trusted computing services in constrained environments. 130 RACS supports commands for GoSE inventory and data exchange with 131 secure elements. 133 RACS is designed according to the representational State Transfer 134 (REST) architecture [REST], which encompasses the following 135 features: 136 - Client-Server architecture. 137 - Stateless interaction. 138 - Cache operation on the client side. 139 - Uniform interface. 140 - Layered system. 141 - Code On Demand. 143 1.1 What is a Secure Element 145 A Secure Element (SE) is a tamper resistant microcontroller equipped 146 with host interfaces such as [ISO7816], SPI (Serial Peripheral 147 Interface) or I2C (Inter Integrated Circuit). 149 The typical area size of these electronic chips is about 25mm2. They 150 comprise CPU (8, 16, 32 bits), ROM (a few hundred KB), nonvolatile 151 memory (EEPROM, FLASH, a few hundred KB) and RAM (a few ten KB). 152 Security is enforced by multiple hardware and logical 153 countermeasures. 155 According to the [EUROSMART] association height billion of such 156 secure devices were shipped in 2013. Secure elements are widely 157 deployed for electronic payment (EMV cards), telecommunication (SIM 158 modules), identity (electronic passports), ticketing, and access 159 control. 161 Most of secure elements include a Java Virtual Machine and therefore 162 are able to execute embedded program written in the JAVACARD 163 language. Because these devices are dedicated to security purposes 164 they support numerous cryptographic resources such as digest 165 functions (MD5, SHA1, SHA2...), symmetric cipher (3xDES, AES) or 166 asymmetric procedures (RSA, ECC). 168 A set of Global Platform [GP] standards control the lifecycle of 169 embedded software, i.e. application downloading, activation and 170 deletion. 172 As an illustration a typical Secure Element has the following 173 characteristics: 175 - JAVACARD operating system; 176 - Compliant with the GP (Global Platform) standards; 177 - 160 KB of ROM; 178 - 72 KB of EEPROM; 179 - 4KB of RAM; 180 - Embedded crypto-processor; 181 - 3xDES, AES, RSA, ECC; 182 - Certification according to Common Criteria (CC) EAL5+ level; 183 - Security Certificates from payment operators. 185 1.2 Grid Of Secure Elements (GoSE) 187 Grid Of Secure Elements 188 +---------------------------------------------+ 189 | SlotID | 190 | Grid +------+ +------+ SEID | 191 | Inventory | |----+ | |----+ | 192 | | | SLOT | SE | | SLOT | SE | | 193 +-+-+-+--|-+ | |----+ | |----+ | 194 |I|T|T| | +------+ +------+ | 195 |P|C|L|RACS| | 196 | |P|S| | +------+ +------+ | 197 +-+-+-+--|-+ | |----+ | |----+ | 198 | | | SLOT | SE | | SLOT | SE | | 199 | | | |--+-+ | |----+ | 200 | | +------+ | +------+ | 201 | +-ISO7816 Requests-+ | 202 +---------------------------------------------+ 204 Figure 1. Architecture of a Grid of Secure Elements 206 +----+----+----+ 207 Vcc->| | |<-Ground 208 +----+ +----+ 209 RESET->| | | | 210 +----+ +----+ 211 Clock->| | | |<-Input/Output 212 +----+ +----+ 213 | | | | 214 +----+----+----+ 216 Figure 2. Illustration of an ISO7816 Secure Element 218 A grid of Secure Elements (GoSE) is a server hosting a set of secure 219 elements. 221 The goal of these platforms is to deliver trusted services over the 222 Internet. These services are available in two functional planes, 223 - The user plane, which provides trusted computing and secure 224 storage. 225 - The management plane, which manages the lifecycle (downloading, 226 activation, deletion) of applications hosted by the Secure Element. 228 A grid of Secure Elements offers services similar to HSM (Hardware 229 Secure Module), but may be managed by a plurality of administrators, 230 dealing with specific secure microcontrollers. 232 According to this draft all accesses to a GoSE require the TCP 233 transport and are secured by the TLS [TLS 1.0] [TLS 1.1] [TLS 2.0] 234 protocol. 236 The RACS protocol provides all the features needed for the remote 237 use of secure elements, i.e. 238 - Inventory of secure elements 239 - Information exchange with the secure elements 241 1.3 Secure Element Identifier (SEID) 243 Every secure element needs a physical slot that provides electrical 244 feeding and communication resources. This electrical interface is 245 for example realized by a socket soldered on an electronic board, or 246 a CAD (Card Acceptance Device, i.e. a reader) supporting host buses 247 such as USB. 249 Within the GoSE each slot is identified by a SlotID (slot 250 identifier) attribute, which may be a socket number or a CAD name. 252 The SEID (Secure Element IDentifier) is a unique identifier 253 indicating that a given SE is hosted by a GoSE. It also implicitly 254 refers the physical slot (SlotID) to which the SE is plugged. 256 The GoSE manages an internal table that establishes the relationship 257 between SlotIDs and SEIDs. 259 Therefore three parameters are needed for remote communication with 260 secure element, the IP address of the GoSE, the associated TCP port, 261 and the SEID. 263 1.3.1 SlotID example 265 According to the PC/SC (Personal Computer/Smart Card) standard 266 [PS/SC], a smart card reader MAY include a serial number. This 267 attribute (VENDOR-IFD-SERIAL) is associated to the tag 0x0103 in the 268 class VENDOR-INFO. 270 1.3.2 SEID for Secure Elements 272 According to the Global Platform standard [GP] the Issuer Security 273 Domain (ISD) manages applications lifecycle (downloading, 274 activation, deletion). The command 'initialize update' is used to 275 start a mutual authentication between the administration entity and 276 the secure element; it collects a set of data whose first ten bytes 277 are called the 'key diversification data'. This information is used 278 to compute symmetric keys, and according for example to [EMV] MAY 279 comprise a serial number. 281 1.4 APDUs 283 According to the [ISO7816] standards secure element process ISO7816 284 request messages and return ISO7816 response messages, named APDUs 285 (application protocol data unit). 287 1.4.1 ISO7816 APDU request 289 An APDU request comprises two parts: a header and an optional body. 291 The header is a set of four or five bytes noted CLA INS P1 P2 P3 293 - CLA indicates the class of the request, and is usually bound to 294 standardization committee (00 for example means ISO request). 295 -INS indicates the type of request, for example B0 for reading or D0 296 for writing. 297 - P1 P2 gives additional information for the request (such index in 298 a file or identifier of cryptographic procedures) 299 - P3 indicates the length of the request body (from P3=01 to P3=FF), 300 or the size of the expected response body (a null value meaning 256 301 bytes). Short ISO7816 requests may comprise only 4 bytes 302 - The body may be empty. Its maximum size is 255 bytes 304 1.4.2 ISO7816 APDU response 306 An APDU response comprises two parts an optional body and a 307 mandatory status word. 309 - The optional body is made of 256 bytes at the most. 311 - The response ends by a two byte status noted SW. SW1 refers the 312 most significant byte and SW2 the less significant byte. 314 An error free operation is usually associated to the 9000 status 315 word. Following are some interpretations of the tuple SW1, SW2 316 according to various standards: 318 - '61' 'xx', indicates that xx bytes (modulus 256) are ready for 319 reading. Operation result MUST be fetched by the ISO 320 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 321 - '9F' 'xx', indicates that xx bytes (modulus 256) are ready for 322 reading. Operation result MUST be fetched by the ISO 323 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 324 - '6C' 'XX', the P3 value is wrong, request must be performed 325 again with the LE parameter value sets to 'XX' 326 - '6E' 'XX', wrong instruction class (CLA) given in the request 327 - '6D' 'XX', unknown instruction code (INS) given in the request 328 - '6B' 'XX', incorrect parameter P1 or P2 329 - '67' 'XX', incorrect parameter P3 330 - '6F' 'XX', technical problem, not implemented... 332 2 The RACS protocol 334 +-----------------+ 335 | RACS | 336 +-----------------+ 337 | TLS | 338 +-----------------+ 339 | TCP | 340 +-----------------+ 341 | IP | 342 +------------- ---+ 344 Figure 2. The RACS stack 346 The RACS protocol works over the TCP transport layer and is secured 347 by the TLS protocol. The TLS client (i.e. the RACS client) MUST be 348 authenticated by a certificate. 350 One of the main targets of the RACS protocol is to efficiently push 351 a set of ISO7816 requests towards a secure element in order to 352 perform cryptographic operations in the user's plane. In that case a 353 RACS request typically comprises a prefix made with multiple ISO7816 354 requests and a suffix that collects the result of a cryptographic 355 procedure. 357 The mandatory use of TLS with mutual authentication based on 358 certificate provides a simple and elegant way to establish the 359 credentials of a RACS client over the GoSE. It also enables an easy 360 splitting between users' and administrators' privileges. 362 2.1 Structure of RACS request 364 A RACS request is a set of command lines, encoded according to the 365 ASCII format. Each line ends by the Cr (carriage return) and line 366 feed (Lf) characters. The RACS protocol is case sensitive. 368 Each command is a set of tokens (i.e. words) separated by space 369 (0x20) character(s). 371 The first token of each line is the command to be executed. 373 A command line MAY comprise other tokens, which are called the 374 command parameters. 376 A RACS request MUST start by a BEGIN command and MUST end by an END 377 command. 379 Each command line is associated to an implicit line number. The 380 BEGIN line is associated to the zero line number. 382 The processing of a RACS request is stopped after the first error. 383 In that case the returned response contained the error status 384 induced by the last executed command. 386 2.2 Structure of a RACS response 388 A RACS response is a set of lines, encoded according to the ASCII 389 format. Each line ends by the Cr (carriage return) and line feed 390 (Lf) characters. The RACS protocol is case sensitive. 392 Each line is a set of tokens (i.e. words) separated by space (0x20) 393 character(s). 395 The first token of each line is the header. 397 The second token of response each line is associated command line 398 number 400 A response line MAY comprise other tokens, which are called the 401 response parameters. 403 Three classes of headers are defined BEGIN, END and Status. 405 A RACS response MUST start by a BEGIN header and MUST end by an END 406 header. It comprises one or several status lines. 408 2.2.1 BEGIN Header 410 This header starts a response message. 412 It comprises an optional parameter, an identifier associated to a 413 previous request message. 415 2.2.2 END Header 417 This header ends a response message. 419 2.2.3 Status line 421 A status header indicates a status line. 423 It begins by the character '+' in case of success or '-' if an error 424 occurred during the RACS request execution. It is followed by an 425 ASCII encoded integer, which is the value of the status. 427 The second mandatory token of a status line is the command line 428 number (starting from zero) 429 A status line MAY comprise other tokens, which are called the 430 response parameters. 432 2.2.4 Examples of RACS responses: 434 BEGIN CrLf 435 +001 000 Success CrLf 436 END CrLf 438 BEGIN moon1969 CrLf 439 -301 007 Illegal command, BEGIN condition not satisfied at line 7 440 END CrLf 442 BEGIN Asterix237 CrLf 443 +006 001 [ISO7816-Response] CrLf 444 END CrLf 446 BEGIN CrLf 447 -100 002 Unknown command at line 2 CrLf 448 END CrLf 450 BEGIN CrLf 451 -606 001 Unauthorized command APDU command at line 1 452 END CrLf 454 BEGIN CrLf 455 -706 001 SEID Already in use, APDU command at line 1 456 END CrLf 458 2.3 RACS request commands 460 2.3.1 BEGIN 462 This command starts a request message. A response message is 463 returned if an error is detected. 465 An optional parameter is the request identifier, which MUST be 466 echoed in the parameter of the first response line (i.e. starting by 467 the BEGIN header). 469 2.3.2 END 471 This command ends a request message. It returns the response message 472 triggered by the last command. 474 Example1 475 ======== 476 Request: 477 BEGIN CrLf 478 END CrLf 480 Response: 481 BEGIN CrLf 482 +001 000 Success CrLf 483 END CrLF 485 Example2 486 ======== 487 Request: 488 BEGIN Marignan1515 CrLf 489 APDU ASTERIX-CRYPTO-MODULE [ISO7816-Request] CrLf 490 END CrLf 492 Response: 493 BEGIN Marignan1515 CrLf 494 +006 001 [ISO7816-Response] CrLf 495 END CrLf 497 2.3.3 The APPEND parameter 499 The APPEND parameter MAY be used in all command lines, excepted 500 BEGIN and END. The APPEND parameter MUST be the last parameter of a 501 command line. 502 By default a response message returns only the last status line. 503 When APPEND is inserted, the command line, if executed, MUST produce 504 a status line. 506 Example 508 Request: 509 BEGIN SanchoPanza CrLf 510 APDU 100 [ISO7816-Request-1] CrLf 511 APDU 100 [ISO7816-Request-2] CrLf 512 END CrLf 514 Response: 515 BEGIN SanchoPanza CrLf 516 +006 002 [ISO7816-Response-2] CrLf 517 END CrLf 519 Request: 520 BEGIN DonQuichotte CrLf 521 APDU 100 [ISO7816-Request-1] APPEND CrLf 522 APDU 100 [ISO7816-Request-2] APPEND CrLf 523 END CrLf 524 Response: 525 BEGIN DonQuichotte CrLf 526 +006 001 [ISO7816-Response-1] CrLf 527 +006 002 [ISO7816-Response-2] CrLf 528 END CrLf 530 2.3.4 GET-VERSION 532 This command requests the current version of the RACS protocol. 533 The returned response is the current version encoded by two integer 534 separated by the '.' character. The first integer indicates the 535 major version and the second integer gives the minor version. 537 This draft version is 0.2 539 Example 540 ======= 541 Request: 542 BEGIN CrLf 543 GET-VERSION CrLf 544 END CrLf 546 Response: 547 BEGIN CrLf 548 +002 001 1.0 CrLf 549 END CrLf 551 2.3.5 SET-VERSION 553 This command sets the version to be used for the RACS request. An 554 error status is returned by the response if an error occurred. 556 Example 1 557 ========= 558 Request: 559 BEGIN CrLf 560 SET-VERSION 2.0 CrLf 561 END CrLf 563 Response: 564 BEGIN CrLf 565 -403 001 Error line 1 RACS 2.0 is not supported CrLf 566 END CrLf 568 Example 2 569 ========= 570 Request: 571 BEGIN CrLf 572 SET-VERSION 1.0 CrLf 573 END CrLf 574 Response: 575 BEGIN CrLf 576 +003 001 RACS 1.0 has been activated CrLf 577 END CrLf 579 2.3.6 LIST 581 This command requests the list of SEID plugged in the GoSE. 583 It returns a list of SEIDs separated by space (0x20) character(s). 585 Some SEID attributes MAY be built from a prefix and an integer 586 suffix (such as SE#100 in which SE# is the suffix and 100 is the 587 integer suffix. A list of non-consecutive SEID MAY be encoded as 588 prefix[i1;i2;..;ip] where i1,i2,ip indicates the integer suffix. A 589 list of consecutive SEID could be encoded as prefix[i1-ip] where 590 i1,i2,ip indicates the integer suffix. 592 Example 1 593 ========= 594 Request: 595 BEGIN CrLf 596 LIST CrLf 597 END CrLf 599 Response: 600 BEGIN CrLf 601 +004 001 SEID1 SEID2 CR LF 602 END CrLf 604 Example 2 605 ========= 606 Request: 607 BEGIN CrLf 608 LIST CrLf 609 END CrLf 611 Response: 612 BEGIN CrLf 613 +004 001 Device[1000-2000] SerialNumber[567;789;243] CrLf 614 END CrLf 616 2.3.7 RESET 618 This command resets a secure element. The first parameter gives the 619 secure element identifier (SEID). An optional second parameter 620 specifies a warm reset. The default behavior is a cold reset. 621 The response status indicates the success or the failure of this 622 operation. 624 Syntax: RESET SEID [WARM] CrLf 626 Example 1 627 ========= 628 Request: 629 BEGIN CrLf 630 RESET device#45 CrLf 631 END CrLf 633 Response: 634 BEGIN CrLf 635 +005 001 device#45 Reset Done 636 END CrLf 638 Example 2 639 ========= 640 Request: 641 BEGIN CrLf 642 RESET device#45 CrLf 643 END CrLf 645 Response: 646 BEGIN CrLf 647 -705 001 error device#45 is already in use 648 END CrLf 650 Example 3 651 ========= 652 Request: 653 BEGIN CrLf 654 RESET device#45 WARM CrLf 655 END CrLf 657 Response: 658 BEGIN CrLf 659 +005 001 device#45 Warm Reset Done CrLf 660 END CrLf 662 2.3.8 APDU 664 This command sends an ISO7816 request to a secure element or a set 665 of ISO7816 commands. 667 The first parameter specifies the SEID. 668 The second parameter is an ISO7816 request. 669 Three optional parameters are available; they MUST be located after 670 the second parameter. 672 - CONTINUE=value, indicates that the next RACS command will be 673 executed only if the ISO7816 status word (SW) is equal to a given 674 value. Otherwise an error status is returned. 675 - MORE=value, indicates that a FETCH request will be performed (i.e. 676 a new ISO7816 request will be sent) if the first byte of the ISO7816 677 status word (SW1) is equal to a given value. 678 - FETCH=value fixes the four bytes of the ISO7816 FETCH request 679 (i.e. CLA INS P1 P2). The default value (when FETCH is omitted) is 680 00C00000 (CLA=00, INS=C0, P1=00, P2=00) 682 When the options CONTINUE and MORE are simultaneously set the SW1 683 byte is first checked. If there is no match then the SW word is 684 afterwards checked. 686 The ISO7816 6Cxx status MUST be autonomously processed by the GoSE. 688 SYNTAX 689 APDU SEID ISO7816-REQUEST [CONTINUE=SW] [MORE=SW1] [FETCH=CMD] CrLf 691 The returned response is the ISO7816 response. If multiple ISO7816 692 requests are executed (due to the MORE option), the bodies are 693 concatenated in the response, which ends by the last ISO7816 status 694 word. 696 The pseudo code of the APDU command is the following : 698 1. BODY = empty; 699 2. SW = empty; 700 3. DoIt = true; 701 3. Do 702 4. { iso7816-response = send(iso7816-request); 703 5. body || sw1 || sw2 = iso7816-response; 704 6. If ( (first request) && (iso7816-request.size==5) && 705 (body==empty) && (sw1==6C) ) 706 8. { iso7816-request.P3 = sw2 ; } 707 6. Else 708 7. { SW = sw1 || sw2 709 8. BODY = BODY || body; 710 9. If (sw1 == MORE) 711 10. { iso7816-request = FETCH || sw2 ; } 712 11. Else 713 12. { DoIt=false;} 714 13. } 715 14. } 716 15. While (DoIt == true) 718 16. iso7816-response = BODY || SW ; 719 17. If (SW != CONTINUE) Error ; 720 18. Else No Error; 721 Example 1 722 ========= 723 Request: 724 BEGIN CrLf 725 APDU SEID ISO7816-REQUEST CrLf 726 END CrLf 728 Response: 729 BEGIN CrLf 730 +006 001 ISO7816-RESPONSE CrLf 731 END CrLf 733 Example 2 734 ========= 735 Request: 736 BEGIN CrLf 737 APDU SEID ISO7816-REQUEST CrLf 738 END CrLf 740 Response: 741 BEGIN CrLf 742 -706 001 error SEID is already used CrLf 743 END CrLf 745 Example 3 746 ========= 747 Request: 748 BEGIN CrLf 749 APDU SEID ISO7816-REQUEST CrLf 750 END CrLf 752 Response: 753 BEGIN CrLf 754 -606 001 error access unauthorized access CrLf 755 END CrLf 757 Example 4 758 ========= 759 BEGIN CrLf 760 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 761 APDU SEID ISO7816-REQUEST-2 CrLf 762 END CrLf 764 Response: 765 BEGIN CrLf 766 +006 002 ISO7816-RESPONSE-2 CrLf 767 END CrLf 768 Example 5 769 ========= 770 BEGIN CrLf 771 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 772 APDU SEID ISO7816-REQUEST-2 CrLf 773 END CrLf 775 Response: 776 BEGIN CrLf 777 -006 001 Request Error line 1 wrong SW CrLf 778 END CrLf 780 Example 6 781 ========= 782 BEGIN CrLf 783 APDU SEID ISO7816-REQ-1 CONTINUE=9000 CrLf 784 APDU SEID ISO7816-REQ-2 CONTINUE=9000 CrLf 785 APDU SEID ISO7816-REQ-3 CONTINUE=9000 MORE=61 FETCH=00C00000 CrLf 786 END CrLf 788 Response: 789 BEGIN CrLf 790 +006 003 ISO7816-RESP-3 CrLf 791 END CrLf 793 Multiple ISO7816 requests have been performed by the third APDU 794 command according to the following scenario : 795 - the ISO7816-REQ-3 request has been forwarded to the secure element 796 (SEID) 797 - the ISO 7816 response comprises a body (body-0) and a status word 798 (SW-0) whose first byte is 0x61, and the second byte is SW2-0 799 - the FETCH command CLA=00, INS=00, P1=00, P2=00, P3=SW2-0 is sent 800 to the secure element 801 - the ISO 7816 response comprises a body (body-1) and a status word 802 (SW-1) set to 9000 804 The RACS response is set to 805 +006 003 body-0 || body-1 || SW-1 CrLf 806 where ||indicates a concatenation operation. 808 2.3.9 SHUTDOWN 810 This command powers down a secure element. The first parameter gives 811 the secure element identifier (SEID). 813 Syntax: SHUTDOWN SEID CrLf 814 Example 815 ========= 816 Request: 817 BEGIN Goodbye CrLf 818 SHUTDOWN device#45 CrLf 819 END CrLf 821 Response: 822 BEGIN Goodbye CrLf 823 +007 001 device#45 has been powered down CrLf 824 END CrLf 826 2.3.10 POWERON 828 This command powers up a secure element. The first parameter gives 829 the secure element identifier (SEID). 831 Syntax: POWERON SEID CrLf 833 Example 1 834 ========= 835 Request: 836 BEGIN CrLf 837 POWERON device#45 CrLf 838 END CrLf 840 Response: 841 BEGIN CrLf 842 +008 001 device#45 Has been powered up CrLf 843 END CrLf 845 Example 2 846 ========= 847 Request: 848 BEGIN CrLf 849 POWERON device#45 CrLf 850 END CrLf 852 Response: 853 BEGIN CrLf 854 -708 001 error device#45 is already in use CrLf 855 END CrLf 857 Example 3 858 ========= 859 Request: 860 BEGIN CrLf 861 POWERON device#45 CrLf 862 END CrLf 863 Response: 864 BEGIN CrLf 865 -608 001 error unauthorized access CrLf 866 END CrLf 868 2.3.11 ECHO 870 This command echoes a token. The first parameter is the token (word) 871 to be echoed by the response. 873 Syntax: ECHO SEID CrLf 875 Example 1 876 ========= 877 Request: 878 BEGIN TestEcho CrLf 879 ECHO Hello CrLf 880 END CrLf 882 Response: 883 BEGIN TestEcho CrLf 884 +009 001 Hello CrLf 885 END CrLf 887 Example 2 888 ========= 889 Request: 890 BEGIN ResetSEID CrLf 891 POWERON device#45 CrLf 892 ECHO Done CrLf 893 END CrLf 895 Response: 896 BEGIN ResetSEID CrLf 897 +009 001 Done CrLf 898 END CrLf 900 2.4 Status header encoding 902 The first token of a response line is the status header. It begins 903 by a '+' or a '-' character, and comprises three decimal digits 904 (xyz). 906 The first digit (x) MUST indicates an event class. 907 The second and third digits (yz) MAY indicate a command class. 909 2.4.1 Event class 911 This draft only defines the meaning of the first digit located at 912 the left most side. 914 +0yz: No error 915 -0yz: Command execution error 916 -1yz: Unknown command, the command is not defined by this draft 917 -2yz: Not implemented command 918 -3yz: Illegal command, the command can't be executed 919 -4yz: Not supported parameter or parameter illegal value 920 -5yz: Parameter syntax error or parameter missing 921 -6yz: Unauthorized command 922 -7yz: Already in use, a session with this SE is already opened 923 -8yz: Hardware error 924 -9yz: System error 926 2.4.2 Command class 928 The second and third digits (yz) MAY indicates the command that 929 trigged the current line status 931 01 BEGIN 932 02 GET-VERSION 933 03 SET-VERSION 934 04 LIST 935 05 RESET 936 06 APDU 937 07 SHUTDOWN 938 08 POWERON 939 09 ECHO 940 3 URI for the GoSE 942 The URI addressing the resources hosted by the GoSE is represented 943 by the string: 945 RACS://GoSE-Name:port/?request 947 where request is the RACS request to be forwarded to a the GoSE. 949 RACS command lines are encoded in a way similar to the INPUT field 950 of an HTML form. Each command is associated to an INPUT name, the 951 remaining of the command line i.e. a set of ASCII characters, is 952 written according to the URL encoding rules. End of line characters, 953 i.e. carriage return (Cr) and line feed (Lf) are omitted. 955 As a consequence a request is written to the following syntax 956 cmd1=cmd1-parameters&cmd2=cmd2-parameters 958 Example: 959 RACS://GoSE-Name:port/?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 961 4 HTTP interface 963 A GoSE SHOULD support an HTTP interface. RACS requests/responses are 964 transported by HTTP messages. The use of TLS is mandatory. 966 4.1 HTTPS Request 968 https://GoSE-Name:port/RACS?request 970 where request is the RACS request to be forwarded to a secure 971 element (SEID) 973 The RACS request is associated to an HTML form whose name is "RACS". 974 The request command lines are encoded as the INPUT field of an HTML 975 form. Each command is associated to an INPUT name, the remaining of 976 the command line i.e. a set of ASCII characters is written according 977 to the URL encoding rules. End of line characters, i.e. carriage 978 return (Cr) and line feed (Lf) are omitted. 980 As a consequence a RACS request is written as 981 https://GoSE-Name/RACS?cmd1=cmd1-parameters&cmd2=cmd2-parameters 983 Example: 985 https://GoSE-Name/RACS?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 986 4.2 HTTPS response 988 The RACS response is returned in an XML document. 990 The root element of the document is 992 The optional parameter of the BEGIN header, is the content of the 993 element. 995 Each status line is the content of the element, which 996 includes the following information : 998 - The status header is the content of the element. 1000 - The line number is the content of the element. 1002 - The other parameters of the status line are the content of the 1003 element. 1005 The END header is associated to the element 1007 End of line, i.e. carriage return (Cr) and line feed (Lf) characters 1008 are omitted. 1010 As a consequence a RACS response is written as : 1011 1012 Optionnal-ID 1013 +000 1015 001 1016 other parameters of the RACS response 1017 1018 1019 1021 5 Security Considerations 1023 5.1 Authorization 1025 A RACS client MUST be authenticated by an X509 certificate. 1027 The GoSE software MUST provide a mean to establish a list of SEIDs 1028 that can be accessed from a client whose identity is the CommonName 1029 (CN) attribute of its certificate. It MAY allocate a UserID (UID), 1030 i.e. an integer index from the certfificate common name. 1032 5.2 Secure Element access 1034 The GoSE MUST manage a unique session identifier (SID) for each TLS 1035 session. The SID is bound to the client's certificate CommonName 1036 (SID(CN)) 1037 A secure element has two states, unlocked and locked. In the locked 1038 state the secure element may be only used by the SID that previously 1039 locked it. 1041 The first authorized command that successfully accesses to a SEID 1042 (either POWERON ,RESET, APDU) locks a secure element (SEID) with the 1043 current session (SID). 1045 The SHUTDOWN command MUST unlock a secure element (SEID). 1047 The end of a TLS session MUST unlock all the secure elements locked 1048 by the session. 1050 5.3 Applications security policy 1052 According to the [ISO7816] standards each Application embedded 1053 within a secure element (associated to a SEID) is identified by an 1054 AID parameter (16 bytes at the most) 1056 The RACS server SHOULD support the following facilities 1058 5.3.1 Users-Table 1060 Each CN (the Users-Table primary key) is associated to a list of 1061 SEIDs whose access is authorized. 1063 5.3.2 SEID-Table 1065 Each AID (the SEID-Table primary key) is associated to a list of CNs 1066 whose access is authorized. 1068 5.3.3 APDU-Table 1070 For a given AID and an authorized CN, an APDU-Table MAY be 1071 available. This table acts as a firewall, which defined a set of 1072 forbidden ISO7816 commands. 1074 For example this filter could be expressed as a set of the four 1075 first bytes of an APDU-Prefix (CLA INS P1 P2) and a four bytes Mask 1076 An ISO7816-Request is firewall if: 1078 ISO7816-Request AND Mask IsEQUAL to APDU-Prefix 1079 5.4 Overview of the security policy 1081 The summary of the security policy is illustrated by the figure 3. 1083 CN(uid) 1084 /\ 1085 TLS-Session / \ 1086 / \ 1087 sid sid 1088 /\ /\ 1089 / \ / \ 1090 aid aid aid aid 1091 /\ 1092 / \ 1093 / \ 1094 APDU APDU 1095 Filter Filter 1097 Figure 3. Summary of the security policy 1099 6 IANA Considerations 1101 This draft does not require any action from IANA. 1103 7 References 1105 7.1 Normative References 1107 [TLS 1.0] Dierks, T., C. Allen, "The TLS Protocol Version 1.0", RFC 1108 2246, January 1999 1110 [TLS 1.1] Dierks, T., Rescorla, E., "The Transport Layer Security 1111 (TLS) Protocol Version 1.1", RFC 4346, April 2006 1113 [TLS 1.2] Dierks, T., Rescorla, E., "The Transport Layer Security 1114 (TLS) Protocol Version 1.1", RFC 5746, August 2008 1116 [ISO7816] ISO 7816, "Cards Identification - Integrated Circuit Cards 1117 with Contacts", The International Organization for Standardization 1118 (ISO) 1120 7.2 Informative References 1122 [REST] Fielding, R., "Architectural Styles and the Design of 1123 Network-based Software Architectures", 2000, 1124 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 1126 [GP] Global Platform Standards, http://www.globalplatform.org 1128 [EUROSMART] The EUROSMART association, http://www.eurosmart.com 1130 [PC/SC] The PC/SC workgroup, http://www.pcscworkgroup.com 1132 [EMV] EMV Card Personalization Specification, Version 1.1, July 2007 1134 8 Authors' Addresses 1136 Pascal Urien 1137 Telecom ParisTech 1138 23 avenue d'Italie 1139 75013 Paris Phone: NA 1140 France Email: Pascal.Urien@telecom-paristech.fr