idnits 2.17.1 draft-urien-core-racs-10.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 6 characters in excess of 72. ** The abstract seems to contain references ([OPENRACS]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1137 has weird spacing: '... sid sid...' -- The document date (December 2017) is 2296 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Missing Reference: 'ISO7816-Response' is mentioned on line 518, but not defined == Missing Reference: 'ISO7816-Request' is mentioned on line 513, but not defined == Missing Reference: 'ISO7816-Request-1' is mentioned on line 545, but not defined == Missing Reference: 'ISO7816-Request-2' is mentioned on line 546, but not defined == Missing Reference: 'ISO7816-Response-2' is mentioned on line 553, but not defined == Missing Reference: 'ISO7816-Response-1' is mentioned on line 552, but not defined == Missing Reference: '1000-2000' is mentioned on line 641, but not defined == Missing Reference: 'WARM' is mentioned on line 654, but not defined Summary: 2 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 December 2017 7 Expires: June 2018 9 Remote APDU Call Secure (RACS) 10 draft-urien-core-racs-10.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 [OPENRACS] is available 28 (https://github.com/purien/racs_0_1) 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 June 2018. 52 . 54 Copyright Notice 56 Copyright (c) 2017 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 RACS December 2017 71 Table of Contents 72 Abstract........................................................... 1 73 Requirements Language.............................................. 1 74 Status of this Memo................................................ 1 75 Copyright Notice................................................... 2 76 1 Overview......................................................... 5 77 1.1 What is a Secure Element.................................... 5 78 1.2 Grid Of Secure Elements (GoSE).............................. 6 79 1.3 Secure Element Identifier (SEID)............................ 7 80 1.3.1 SlotID example ....................................... 7 81 1.3.2 SEID for Secure Elements ............................. 8 82 1.4 APDUs....................................................... 9 83 1.4.1 ISO7816 APDU request ................................. 9 84 1.4.2 ISO7816 APDU response ................................ 9 85 2 The RACS protocol............................................... 10 86 2.1 Structure of RACS request.................................. 10 87 2.2 Structure of a RACS response............................... 11 88 2.2.1 BEGIN Header ........................................ 11 89 2.2.2 END Header .......................................... 11 90 2.2.3 Status line ......................................... 11 91 2.2.4 Examples of RACS responses: ......................... 12 92 2.3 RACS request commands...................................... 12 93 2.3.1 BEGIN ............................................... 12 94 2.3.2 END ................................................. 12 95 2.3.3 The APPEND parameter ................................ 13 96 2.3.4 GET-VERSION ......................................... 14 97 2.3.5 SET-VERSION ......................................... 14 98 2.3.6 LIST ................................................ 15 99 2.3.7 RESET ............................................... 15 100 2.3.8 APDU ................................................ 16 101 2.3.9 SHUTDOWN ............................................ 19 102 2.3.10 POWERON ............................................ 20 103 2.3.11 ECHO ............................................... 21 104 2.4 Status header encoding..................................... 21 105 2.4.1 Event class ......................................... 22 106 2.4.2 Command class ....................................... 22 107 3 URI for the GoSE................................................ 23 108 4 HTTP interface.................................................. 23 109 4.1 HTTPS Request.............................................. 23 110 4.2 HTTPS response............................................. 24 111 5 Security Considerations......................................... 24 112 5.1 Authorization.............................................. 24 113 5.2 Secure Element access...................................... 24 114 5.3 Applications security policy............................... 25 115 5.3.1 Users-Table ......................................... 25 116 5.3.2 SEID-Table .......................................... 25 117 5.3.3 APDU-Table .......................................... 25 118 5.4 Overview of the security policy............................ 26 119 6 IANA Considerations............................................. 26 120 7 References...................................................... 26 121 7.1 Normative References....................................... 26 122 RACS December 2017 124 7.2 Informative References..................................... 26 125 8 Authors' Addresses.............................................. 27 126 RACS December 2017 128 1 Overview 130 This document describes the Remote APDU Call Protocol Secure (RACS) 131 protocol, dedicated to Grids of Secure Elements (GoSE). These 132 servers host Secure Elements (SE), i.e. tamper resistant chips 133 offering secure storage and cryptographic resources. 135 Secure Elements are microcontrollers whose chip area is about 25mm2; 136 they deliver trusted computing services in constrained environments. 138 RACS supports commands for GoSE inventory and data exchange with 139 secure elements. 141 RACS is designed according to the representational State Transfer 142 (REST) architecture [REST], which encompasses the following 143 features: 144 - Client-Server architecture. 145 - Stateless interaction. 146 - Cache operation on the client side. 147 - Uniform interface. 148 - Layered system. 149 - Code On Demand. 151 1.1 What is a Secure Element 153 A Secure Element (SE) is a tamper resistant microcontroller equipped 154 with host interfaces such as [ISO7816], SPI (Serial Peripheral 155 Interface) or I2C (Inter Integrated Circuit). 157 The typical area size of these electronic chips is about 25mm2. They 158 comprise CPU (8, 16, 32 bits), ROM (a few hundred KB), nonvolatile 159 memory (EEPROM, FLASH, a few hundred KB) and RAM (a few ten KB). 160 Security is enforced by multiple hardware and logical 161 countermeasures. 163 According to the [EUROSMART] association height billion of such 164 secure devices were shipped in 2013. Secure elements are widely 165 deployed for electronic payment (EMV cards), telecommunication (SIM 166 modules), identity (electronic passports), ticketing, and access 167 control. 169 Most of secure elements include a Java Virtual Machine and therefore 170 are able to execute embedded program written in the JAVACARD 171 language. Because these devices are dedicated to security purposes 172 they support numerous cryptographic resources such as digest 173 functions (MD5, SHA1, SHA2...), symmetric cipher (3xDES, AES) or 174 asymmetric procedures (RSA, ECC). 176 A set of Global Platform [GP] standards control the lifecycle of 177 embedded software, i.e. application downloading, activation and 178 deletion. 180 RACS December 2017 182 As an illustration a typical Secure Element has the following 183 characteristics: 185 - JAVACARD operating system; 186 - Compliant with the GP (Global Platform) standards; 187 - 160 KB of ROM; 188 - 72 KB of EEPROM; 189 - 4KB of RAM; 190 - Embedded crypto-processor; 191 - 3xDES, AES, RSA, ECC; 192 - Certification according to Common Criteria (CC) EAL5+ level; 193 - Security Certificates from payment operators. 195 1.2 Grid Of Secure Elements (GoSE) 197 Grid Of Secure Elements 198 +---------------------------------------------+ 199 | SlotID | 200 | Grid +------+ +------+ SEID | 201 | Inventory | |----+ | |----+ | 202 | | | SLOT | SE | | SLOT | SE | | 203 +-+-+-+--|-+ | |----+ | |----+ | 204 |I|T|T| | +------+ +------+ | 205 |P|C|L|RACS| | 206 | |P|S| | +------+ +------+ | 207 +-+-+-+--|-+ | |----+ | |----+ | 208 | | | SLOT | SE | | SLOT | SE | | 209 | | | |--+-+ | |----+ | 210 | | +------+ | +------+ | 211 | +-ISO7816 Requests-+ | 212 +---------------------------------------------+ 214 Figure 1. Architecture of a Grid of Secure Elements 216 +----+----+----+ 217 Vcc->| | |<-Ground 218 +----+ +----+ 219 RESET->| | | | 220 +----+ +----+ 221 Clock->| | | |<-Input/Output 222 +----+ +----+ 223 | | | | 224 +----+----+----+ 226 Figure 2. Illustration of an ISO7816 Secure Element 228 A grid of Secure Elements (GoSE) is a server hosting a set of secure 229 elements. 231 RACS December 2017 233 The goal of these platforms is to deliver trusted services over the 234 Internet. These services are available in two functional planes, 235 - The user plane, which provides trusted computing and secure 236 storage. 237 - The management plane, which manages the lifecycle (downloading, 238 activation, deletion) of applications hosted by the Secure Element. 240 A grid of Secure Elements offers services similar to HSM (Hardware 241 Secure Module), but may be managed by a plurality of administrators, 242 dealing with specific secure microcontrollers. 244 According to this draft all accesses to a GoSE require the TCP 245 transport and are secured by the TLS [TLS 1.0] [TLS 1.1] [TLS 2.0] 246 protocol. 248 The RACS protocol provides all the features needed for the remote 249 use of secure elements, i.e. 250 - Inventory of secure elements 251 - Information exchange with the secure elements 253 1.3 Secure Element Identifier (SEID) 255 Every secure element needs a physical slot that provides electrical 256 feeding and communication resources. This electrical interface is 257 for example realized by a socket soldered on an electronic board, or 258 a CAD (Card Acceptance Device, i.e. a reader) supporting host buses 259 such as USB. 261 Within the GoSE each slot is identified by a SlotID (slot 262 identifier) attribute, which may be a socket number or a CAD name. 264 The SEID (Secure Element IDentifier) is a unique identifier 265 indicating that a given SE is hosted by a GoSE. It also implicitly 266 refers the physical slot (SlotID) to which the SE is plugged. 268 The GoSE manages an internal table that establishes the relationship 269 between SlotIDs and SEIDs. 271 Therefore three parameters are needed for remote communication with 272 secure element, the IP address of the GoSE, the associated TCP port, 273 and the SEID. 275 1.3.1 SlotID example 277 According to the PC/SC (Personal Computer/Smart Card) standard 278 [PS/SC], a smart card reader MAY include a serial number. This 279 attribute (VENDOR-IFD-SERIAL) is associated to the tag 0x0103 in the 280 class VENDOR-INFO. 282 RACS December 2017 284 1.3.2 SEID for Secure Elements 286 According to the Global Platform standard [GP] the Issuer Security 287 Domain (ISD) manages applications lifecycle (downloading, 288 activation, deletion). The command 'initialize update' is used to 289 start a mutual authentication between the administration entity and 290 the secure element; it collects a set of data whose first ten bytes 291 are called the 'key diversification data'. This information is used 292 to compute symmetric keys, and according for example to [EMV] MAY 293 comprise a serial number. 295 RACS December 2017 297 1.4 APDUs 299 According to the [ISO7816] standards secure element process ISO7816 300 request messages and return ISO7816 response messages, named APDUs 301 (application protocol data unit). 303 1.4.1 ISO7816 APDU request 305 An APDU request comprises two parts: a header and an optional body. 307 The header is a set of four or five bytes noted CLA INS P1 P2 P3 309 - CLA indicates the class of the request, and is usually bound to 310 standardization committee (00 for example means ISO request). 311 -INS indicates the type of request, for example B0 for reading or D0 312 for writing. 313 - P1 P2 gives additional information for the request (such index in 314 a file or identifier of cryptographic procedures) 315 - P3 indicates the length of the request body (from P3=01 to P3=FF), 316 or the size of the expected response body (a null value meaning 256 317 bytes). Short ISO7816 requests may comprise only 4 bytes 318 - The body may be empty. Its maximum size is 255 bytes 320 1.4.2 ISO7816 APDU response 322 An APDU response comprises two parts an optional body and a 323 mandatory status word. 325 - The optional body is made of 256 bytes at the most. 327 - The response ends by a two byte status noted SW. SW1 refers the 328 most significant byte and SW2 the less significant byte. 330 An error free operation is usually associated to the 9000 status 331 word. Following are some interpretations of the tuple SW1, SW2 332 according to various standards: 334 - '61' 'xx', indicates that xx bytes (modulus 256) are ready for 335 reading. Operation result MUST be fetched by the ISO 336 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 337 - '9F' 'xx', indicates that xx bytes (modulus 256) are ready for 338 reading. Operation result MUST be fetched by the ISO 339 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 340 - '6C' 'XX', the P3 value is wrong, request must be performed 341 again with the LE parameter value sets to 'XX' 342 - '6E' 'XX', wrong instruction class (CLA) given in the request 343 - '6D' 'XX', unknown instruction code (INS) given in the request 344 - '6B' 'XX', incorrect parameter P1 or P2 345 - '67' 'XX', incorrect parameter P3 346 - '6F' 'XX', technical problem, not implemented... 348 RACS December 2017 350 2 The RACS protocol 352 +-----------------+ 353 | RACS | 354 +-----------------+ 355 | TLS | 356 +-----------------+ 357 | TCP | 358 +-----------------+ 359 | IP | 360 +------------- ---+ 362 Figure 2. The RACS stack 364 The RACS protocol works over the TCP transport layer and is secured 365 by the TLS protocol. The TLS client (i.e. the RACS client) MUST be 366 authenticated by a certificate. 368 One of the main targets of the RACS protocol is to efficiently push 369 a set of ISO7816 requests towards a secure element in order to 370 perform cryptographic operations in the user's plane. In that case a 371 RACS request typically comprises a prefix made with multiple ISO7816 372 requests and a suffix that collects the result of a cryptographic 373 procedure. 375 The mandatory use of TLS with mutual authentication based on 376 certificate provides a simple and elegant way to establish the 377 credentials of a RACS client over the GoSE. It also enables an easy 378 splitting between users' and administrators' privileges. 380 2.1 Structure of RACS request 382 A RACS request is a set of command lines, encoded according to the 383 ASCII format. Each line ends by the Cr (carriage return) and line 384 feed (Lf) characters. The RACS protocol is case sensitive. 386 Each command is a set of tokens (i.e. words) separated by space 387 (0x20) character(s). 389 The first token of each line is the command to be executed. 391 A command line MAY comprise other tokens, which are called the 392 command parameters. 394 A RACS request MUST start by a BEGIN command and MUST end by an END 395 command. 397 Each command line is associated to an implicit line number. The 398 BEGIN line is associated to the zero line number. 400 RACS December 2017 402 The processing of a RACS request is stopped after the first error. 403 In that case the returned response contained the error status 404 induced by the last executed command. 406 2.2 Structure of a RACS response 408 A RACS response is a set of lines, encoded according to the ASCII 409 format. Each line ends by the Cr (carriage return) and line feed 410 (Lf) characters. The RACS protocol is case sensitive. 412 Each line is a set of tokens (i.e. words) separated by space (0x20) 413 character(s). 415 The first token of each line is the header. 417 The second token of response each line is associated command line 418 number 420 A response line MAY comprise other tokens, which are called the 421 response parameters. 423 Three classes of headers are defined BEGIN, END and Status. 425 A RACS response MUST start by a BEGIN header and MUST end by an END 426 header. It comprises one or several status lines. 428 2.2.1 BEGIN Header 430 This header starts a response message. 432 It comprises an optional parameter, an identifier associated to a 433 previous request message. 435 2.2.2 END Header 437 This header ends a response message. 439 2.2.3 Status line 441 A status header indicates a status line. 443 It begins by the character '+' in case of success or '-' if an error 444 occurred during the RACS request execution. It is followed by an 445 ASCII encoded integer, which is the value of the status. 447 The second mandatory token of a status line is the command line 448 number (starting from zero) 449 RACS December 2017 451 A status line MAY comprise other tokens, which are called the 452 response parameters. 454 2.2.4 Examples of RACS responses: 456 BEGIN CrLf 457 +001 000 Success CrLf 458 END CrLf 460 BEGIN moon1969 CrLf 461 -301 007 Illegal command, BEGIN condition not satisfied at line 7 462 END CrLf 464 BEGIN Asterix237 CrLf 465 +006 001 [ISO7816-Response] CrLf 466 END CrLf 468 BEGIN CrLf 469 -100 002 Unknown command at line 2 CrLf 470 END CrLf 472 BEGIN CrLf 473 -606 001 Unauthorized command APDU command at line 1 474 END CrLf 476 BEGIN CrLf 477 -706 001 SEID Already in use, APDU command at line 1 478 END CrLf 480 2.3 RACS request commands 482 2.3.1 BEGIN 484 This command starts a request message. A response message is 485 returned if an error is detected. 487 An optional parameter is the request identifier, which MUST be 488 echoed in the parameter of the first response line (i.e. starting by 489 the BEGIN header). 491 2.3.2 END 493 This command ends a request message. It returns the response message 494 triggered by the last command. 496 RACS December 2017 498 Example1 499 ======== 500 Request: 501 BEGIN CrLf 502 END CrLf 504 Response: 505 BEGIN CrLf 506 +001 000 Success CrLf 507 END CrLF 509 Example2 510 ======== 511 Request: 512 BEGIN Marignan1515 CrLf 513 APDU ASTERIX-CRYPTO-MODULE [ISO7816-Request] CrLf 514 END CrLf 516 Response: 517 BEGIN Marignan1515 CrLf 518 +006 001 [ISO7816-Response] CrLf 519 END CrLf 521 2.3.3 The APPEND parameter 523 The APPEND parameter MAY be used in all command lines, excepted 524 BEGIN and END. The APPEND parameter MUST be the last parameter of a 525 command line. 526 By default a response message returns only the last status line. 527 When APPEND is inserted, the command line, if executed, MUST produce 528 a status line. 530 Example 532 Request: 533 BEGIN SanchoPanza CrLf 534 APDU 100 [ISO7816-Request-1] CrLf 535 APDU 100 [ISO7816-Request-2] CrLf 536 END CrLf 538 Response: 539 BEGIN SanchoPanza CrLf 540 +006 002 [ISO7816-Response-2] CrLf 541 END CrLf 543 Request: 544 BEGIN DonQuichotte CrLf 545 APDU 100 [ISO7816-Request-1] APPEND CrLf 546 APDU 100 [ISO7816-Request-2] APPEND CrLf 547 END CrLf 548 RACS December 2017 550 Response: 551 BEGIN DonQuichotte CrLf 552 +006 001 [ISO7816-Response-1] CrLf 553 +006 002 [ISO7816-Response-2] CrLf 554 END CrLf 556 2.3.4 GET-VERSION 558 This command requests the current version of the RACS protocol. 559 The returned response is the current version encoded by two integer 560 separated by the '.' character. The first integer indicates the 561 major version and the second integer gives the minor version. 563 This draft version is 0.2 565 Example 566 ======= 567 Request: 568 BEGIN CrLf 569 GET-VERSION CrLf 570 END CrLf 572 Response: 573 BEGIN CrLf 574 +002 001 1.0 CrLf 575 END CrLf 577 2.3.5 SET-VERSION 579 This command sets the version to be used for the RACS request. An 580 error status is returned by the response if an error occurred. 582 Example 1 583 ========= 584 Request: 585 BEGIN CrLf 586 SET-VERSION 2.0 CrLf 587 END CrLf 589 Response: 590 BEGIN CrLf 591 -403 001 Error line 1 RACS 2.0 is not supported CrLf 592 END CrLf 594 Example 2 595 ========= 596 Request: 597 BEGIN CrLf 598 SET-VERSION 1.0 CrLf 599 END CrLf 600 RACS December 2017 602 Response: 603 BEGIN CrLf 604 +003 001 RACS 1.0 has been activated CrLf 605 END CrLf 607 2.3.6 LIST 609 This command requests the list of SEID plugged in the GoSE. 611 It returns a list of SEIDs separated by space (0x20) character(s). 613 Some SEID attributes MAY be built from a prefix and an integer 614 suffix (such as SE#100 in which SE# is the suffix and 100 is the 615 integer suffix. A list of non-consecutive SEID MAY be encoded as 616 prefix[i1;i2;..;ip] where i1,i2,ip indicates the integer suffix. A 617 list of consecutive SEID could be encoded as prefix[i1-ip] where 618 i1,i2,ip indicates the integer suffix. 620 Example 1 621 ========= 622 Request: 623 BEGIN CrLf 624 LIST CrLf 625 END CrLf 627 Response: 628 BEGIN CrLf 629 +004 001 SEID1 SEID2 CR LF 630 END CrLf 632 Example 2 633 ========= 634 Request: 635 BEGIN CrLf 636 LIST CrLf 637 END CrLf 639 Response: 640 BEGIN CrLf 641 +004 001 Device[1000-2000] SerialNumber[567;789;243] CrLf 642 END CrLf 644 2.3.7 RESET 646 This command resets a secure element. The first parameter gives the 647 secure element identifier (SEID). An optional second parameter 648 specifies a warm reset. The default behavior is a cold reset. 649 The response status indicates the success or the failure of this 650 operation. 652 RACS December 2017 654 Syntax: RESET SEID [WARM] CrLf 656 Example 1 657 ========= 658 Request: 659 BEGIN CrLf 660 RESET device#45 CrLf 661 END CrLf 663 Response: 664 BEGIN CrLf 665 +005 001 device#45 Reset Done 666 END CrLf 668 Example 2 669 ========= 670 Request: 671 BEGIN CrLf 672 RESET device#45 CrLf 673 END CrLf 675 Response: 676 BEGIN CrLf 677 -705 001 error device#45 is already in use 678 END CrLf 680 Example 3 681 ========= 682 Request: 683 BEGIN CrLf 684 RESET device#45 WARM CrLf 685 END CrLf 687 Response: 688 BEGIN CrLf 689 +005 001 device#45 Warm Reset Done CrLf 690 END CrLf 692 2.3.8 APDU 694 This command sends an ISO7816 request to a secure element or a set 695 of ISO7816 commands. 697 The first parameter specifies the SEID. 698 The second parameter is an ISO7816 request. 699 Three optional parameters are available; they MUST be located after 700 the second parameter. 702 RACS December 2017 704 - CONTINUE=value, indicates that the next RACS command will be 705 executed only if the ISO7816 status word (SW) is equal to a given 706 value. Otherwise an error status is returned. 707 - MORE=value, indicates that a FETCH request will be performed (i.e. 708 a new ISO7816 request will be sent) if the first byte of the ISO7816 709 status word (SW1) is equal to a given value. 710 - FETCH=value fixes the four bytes of the ISO7816 FETCH request 711 (i.e. CLA INS P1 P2). The default value (when FETCH is omitted) is 712 00C00000 (CLA=00, INS=C0, P1=00, P2=00) 714 When the options CONTINUE and MORE are simultaneously set the SW1 715 byte is first checked. If there is no match then the SW word is 716 afterwards checked. 718 The ISO7816 6Cxx status MUST be autonomously processed by the GoSE. 720 SYNTAX 721 APDU SEID ISO7816-REQUEST [CONTINUE=SW] [MORE=SW1] [FETCH=CMD] CrLf 723 The returned response is the ISO7816 response. If multiple ISO7816 724 requests are executed (due to the MORE option), the bodies are 725 concatenated in the response, which ends by the last ISO7816 status 726 word. 728 The pseudo code of the APDU command is the following : 730 1. BODY = empty; 731 2. SW = empty; 732 3. DoIt = true; 733 3. Do 734 4. { iso7816-response = send(iso7816-request); 735 5. body || sw1 || sw2 = iso7816-response; 736 6. If ( (first request) && (iso7816-request.size==5) && 737 (body==empty) && (sw1==6C) ) 738 8. { iso7816-request.P3 = sw2 ; } 739 6. Else 740 7. { SW = sw1 || sw2 741 8. BODY = BODY || body; 742 9. If (sw1 == MORE) 743 10. { iso7816-request = FETCH || sw2 ; } 744 11. Else 745 12. { DoIt=false;} 746 13. } 747 14. } 748 15. While (DoIt == true) 750 16. iso7816-response = BODY || SW ; 751 17. If (SW != CONTINUE) Error ; 752 18. Else No Error; 753 RACS December 2017 755 Example 1 756 ========= 757 Request: 758 BEGIN CrLf 759 APDU SEID ISO7816-REQUEST CrLf 760 END CrLf 762 Response: 763 BEGIN CrLf 764 +006 001 ISO7816-RESPONSE CrLf 765 END CrLf 767 Example 2 768 ========= 769 Request: 770 BEGIN CrLf 771 APDU SEID ISO7816-REQUEST CrLf 772 END CrLf 774 Response: 775 BEGIN CrLf 776 -706 001 error SEID is already used CrLf 777 END CrLf 779 Example 3 780 ========= 781 Request: 782 BEGIN CrLf 783 APDU SEID ISO7816-REQUEST CrLf 784 END CrLf 786 Response: 787 BEGIN CrLf 788 -606 001 error access unauthorized access CrLf 789 END CrLf 791 Example 4 792 ========= 793 BEGIN CrLf 794 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 795 APDU SEID ISO7816-REQUEST-2 CrLf 796 END CrLf 798 Response: 799 BEGIN CrLf 800 +006 002 ISO7816-RESPONSE-2 CrLf 801 END CrLf 802 RACS December 2017 804 Example 5 805 ========= 806 BEGIN CrLf 807 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 808 APDU SEID ISO7816-REQUEST-2 CrLf 809 END CrLf 811 Response: 812 BEGIN CrLf 813 -006 001 Request Error line 1 wrong SW CrLf 814 END CrLf 816 Example 6 817 ========= 818 BEGIN CrLf 819 APDU SEID ISO7816-REQ-1 CONTINUE=9000 CrLf 820 APDU SEID ISO7816-REQ-2 CONTINUE=9000 CrLf 821 APDU SEID ISO7816-REQ-3 CONTINUE=9000 MORE=61 FETCH=00C00000 CrLf 822 END CrLf 824 Response: 825 BEGIN CrLf 826 +006 003 ISO7816-RESP-3 CrLf 827 END CrLf 829 Multiple ISO7816 requests have been performed by the third APDU 830 command according to the following scenario : 831 - the ISO7816-REQ-3 request has been forwarded to the secure element 832 (SEID) 833 - the ISO 7816 response comprises a body (body-0) and a status word 834 (SW-0) whose first byte is 0x61, and the second byte is SW2-0 835 - the FETCH command CLA=00, INS=00, P1=00, P2=00, P3=SW2-0 is sent 836 to the secure element 837 - the ISO 7816 response comprises a body (body-1) and a status word 838 (SW-1) set to 9000 840 The RACS response is set to 841 +006 003 body-0 || body-1 || SW-1 CrLf 842 where ||indicates a concatenation operation. 844 2.3.9 SHUTDOWN 846 This command powers down a secure element. The first parameter gives 847 the secure element identifier (SEID). 849 Syntax: SHUTDOWN SEID CrLf 850 RACS December 2017 852 Example 853 ========= 854 Request: 855 BEGIN Goodbye CrLf 856 SHUTDOWN device#45 CrLf 857 END CrLf 859 Response: 860 BEGIN Goodbye CrLf 861 +007 001 device#45 has been powered down CrLf 862 END CrLf 864 2.3.10 POWERON 866 This command powers up a secure element. The first parameter gives 867 the secure element identifier (SEID). 869 Syntax: POWERON SEID CrLf 871 Example 1 872 ========= 873 Request: 874 BEGIN CrLf 875 POWERON device#45 CrLf 876 END CrLf 878 Response: 879 BEGIN CrLf 880 +008 001 device#45 Has been powered up CrLf 881 END CrLf 883 Example 2 884 ========= 885 Request: 886 BEGIN CrLf 887 POWERON device#45 CrLf 888 END CrLf 890 Response: 891 BEGIN CrLf 892 -708 001 error device#45 is already in use CrLf 893 END CrLf 895 Example 3 896 ========= 897 Request: 898 BEGIN CrLf 899 POWERON device#45 CrLf 900 END CrLf 901 RACS December 2017 903 Response: 904 BEGIN CrLf 905 -608 001 error unauthorized access CrLf 906 END CrLf 908 2.3.11 ECHO 910 This command echoes a token. The first parameter is the token (word) 911 to be echoed by the response. 913 Syntax: ECHO SEID CrLf 915 Example 1 916 ========= 917 Request: 918 BEGIN TestEcho CrLf 919 ECHO Hello CrLf 920 END CrLf 922 Response: 923 BEGIN TestEcho CrLf 924 +009 001 Hello CrLf 925 END CrLf 927 Example 2 928 ========= 929 Request: 930 BEGIN ResetSEID CrLf 931 POWERON device#45 CrLf 932 ECHO Done CrLf 933 END CrLf 935 Response: 936 BEGIN ResetSEID CrLf 937 +009 001 Done CrLf 938 END CrLf 940 2.4 Status header encoding 942 The first token of a response line is the status header. It begins 943 by a '+' or a '-' character, and comprises three decimal digits 944 (xyz). 946 The first digit (x) MUST indicates an event class. 947 The second and third digits (yz) MAY indicate a command class. 949 RACS December 2017 951 2.4.1 Event class 953 This draft only defines the meaning of the first digit located at 954 the left most side. 956 +0yz: No error 957 -0yz: Command execution error 958 -1yz: Unknown command, the command is not defined by this draft 959 -2yz: Not implemented command 960 -3yz: Illegal command, the command can't be executed 961 -4yz: Not supported parameter or parameter illegal value 962 -5yz: Parameter syntax error or parameter missing 963 -6yz: Unauthorized command 964 -7yz: Already in use, a session with this SE is already opened 965 -8yz: Hardware error 966 -9yz: System error 968 2.4.2 Command class 970 The second and third digits (yz) MAY indicates the command that 971 trigged the current line status 973 01 BEGIN 974 02 GET-VERSION 975 03 SET-VERSION 976 04 LIST 977 05 RESET 978 06 APDU 979 07 SHUTDOWN 980 08 POWERON 981 09 ECHO 982 RACS December 2017 984 3 URI for the GoSE 986 The URI addressing the resources hosted by the GoSE is represented 987 by the string: 989 RACS://GoSE-Name:port/?request 991 where request is the RACS request to be forwarded to a the GoSE. 993 RACS command lines are encoded in a way similar to the INPUT field 994 of an HTML form. Each command is associated to an INPUT name, the 995 remaining of the command line i.e. a set of ASCII characters, is 996 written according to the URL encoding rules. End of line characters, 997 i.e. carriage return (Cr) and line feed (Lf) are omitted. 999 As a consequence a request is written to the following syntax 1000 cmd1=cmd1-parameters&cmd2=cmd2-parameters 1002 Example: 1003 RACS://GoSE-Name:port/?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 1005 4 HTTP interface 1007 A GoSE SHOULD support an HTTP interface. RACS requests/responses are 1008 transported by HTTP messages. The use of TLS is mandatory. 1010 4.1 HTTPS Request 1012 https://GoSE-Name:port/RACS?request 1014 where request is the RACS request to be forwarded to a secure 1015 element (SEID) 1017 The RACS request is associated to an HTML form whose name is "RACS". 1018 The request command lines are encoded as the INPUT field of an HTML 1019 form. Each command is associated to an INPUT name, the remaining of 1020 the command line i.e. a set of ASCII characters is written according 1021 to the URL encoding rules. End of line characters, i.e. carriage 1022 return (Cr) and line feed (Lf) are omitted. 1024 As a consequence a RACS request is written as 1025 https://GoSE-Name/RACS?cmd1=cmd1-parameters&cmd2=cmd2-parameters 1027 Example: 1029 https://GoSE-Name/RACS?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 1030 RACS December 2017 1032 4.2 HTTPS response 1034 The RACS response is returned in an XML document. 1036 The root element of the document is 1038 The optional parameter of the BEGIN header, is the content of the 1039 element. 1041 Each status line is the content of the element, which 1042 includes the following information : 1044 - The status header is the content of the element. 1046 - The line number is the content of the element. 1048 - The other parameters of the status line are the content of the 1049 element. 1051 The END header is associated to the element 1053 End of line, i.e. carriage return (Cr) and line feed (Lf) characters 1054 are omitted. 1056 As a consequence a RACS response is written as : 1057 1058 Optionnal-ID 1059 +000 1061 001 1062 other parameters of the RACS response 1063 1064 1065 1067 5 Security Considerations 1069 5.1 Authorization 1071 A RACS client MUST be authenticated by an X509 certificate. 1073 The GoSE software MUST provide a mean to establish a list of SEIDs 1074 that can be accessed from a client whose identity is the CommonName 1075 (CN) attribute of its certificate. It MAY allocate a UserID (UID), 1076 i.e. an integer index from the certfificate common name. 1078 5.2 Secure Element access 1080 The GoSE MUST manage a unique session identifier (SID) for each TLS 1081 session. The SID is bound to the client's certificate CommonName 1082 (SID(CN)) 1083 RACS December 2017 1085 A secure element has two states, unlocked and locked. In the locked 1086 state the secure element may be only used by the SID that previously 1087 locked it. 1089 The first authorized command that successfully accesses to a SEID 1090 (either POWERON ,RESET, APDU) locks a secure element (SEID) with the 1091 current session (SID). 1093 The SHUTDOWN command MUST unlock a secure element (SEID). 1095 The end of a TLS session MUST unlock all the secure elements locked 1096 by the session. 1098 5.3 Applications security policy 1100 According to the [ISO7816] standards each Application embedded 1101 within a secure element (associated to a SEID) is identified by an 1102 AID parameter (16 bytes at the most) 1104 The RACS server SHOULD support the following facilities 1106 5.3.1 Users-Table 1108 Each CN (the Users-Table primary key) is associated to a list of 1109 SEIDs whose access is authorized. 1111 5.3.2 SEID-Table 1113 Each AID (the SEID-Table primary key) is associated to a list of CNs 1114 whose access is authorized. 1116 5.3.3 APDU-Table 1118 For a given AID and an authorized CN, an APDU-Table MAY be 1119 available. This table acts as a firewall, which defined a set of 1120 forbidden ISO7816 commands. 1122 For example this filter could be expressed as a set of the four 1123 first bytes of an APDU-Prefix (CLA INS P1 P2) and a four bytes Mask 1124 An ISO7816-Request is firewall if: 1126 ISO7816-Request AND Mask IsEQUAL to APDU-Prefix 1127 RACS December 2017 1129 5.4 Overview of the security policy 1131 The summary of the security policy is illustrated by the figure 3. 1133 CN(uid) 1134 /\ 1135 TLS-Session / \ 1136 / \ 1137 sid sid 1138 /\ /\ 1139 / \ / \ 1140 aid aid aid aid 1141 /\ 1142 / \ 1143 / \ 1144 APDU APDU 1145 Filter Filter 1147 Figure 3. Summary of the security policy 1149 6 IANA Considerations 1151 This draft does not require any action from IANA. 1153 7 References 1155 7.1 Normative References 1157 [TLS 1.0] Dierks, T., C. Allen, "The TLS Protocol Version 1.0", RFC 1158 2246, January 1999 1160 [TLS 1.1] Dierks, T., Rescorla, E., "The Transport Layer Security 1161 (TLS) Protocol Version 1.1", RFC 4346, April 2006 1163 [TLS 1.2] Dierks, T., Rescorla, E., "The Transport Layer Security 1164 (TLS) Protocol Version 1.1", RFC 5746, August 2008 1166 [ISO7816] ISO 7816, "Cards Identification - Integrated Circuit Cards 1167 with Contacts", The International Organization for Standardization 1168 (ISO) 1170 7.2 Informative References 1172 [REST] Fielding, R., "Architectural Styles and the Design of 1173 Network-based Software Architectures", 2000, 1174 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 1176 [GP] Global Platform Standards, http://www.globalplatform.org 1178 [EUROSMART] The EUROSMART association, http://www.eurosmart.com 1179 RACS December 2017 1181 [PC/SC] The PC/SC workgroup, http://www.pcscworkgroup.com 1183 [EMV] EMV Card Personalization Specification, Version 1.1, July 2007 1185 [OPENRACS] https://github.com/purien/racs_0_1, open RACS implementation for 1186 Win32, Ubuntu, Raspberrypi 1188 8 Authors' Addresses 1190 Pascal Urien 1191 Telecom ParisTech 1192 23 avenue d'Italie 1193 75013 Paris Phone: NA 1194 France Email: Pascal.Urien@telecom-paristech.fr