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