idnits 2.17.1 draft-urien-core-racs-16.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 : ---------------------------------------------------------------------------- ** 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 1207 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 498, but not defined == Missing Reference: 'ISO7816-Request' is mentioned on line 493, but not defined == Missing Reference: 'ISO7816-Request-1' is mentioned on line 525, but not defined == Missing Reference: 'ISO7816-Request-2' is mentioned on line 526, but not defined == Missing Reference: 'ISO7816-Response-2' is mentioned on line 531, but not defined == Missing Reference: 'ISO7816-Response-1' is mentioned on line 530, but not defined == Missing Reference: '1000-2000' is mentioned on line 617, but not defined == Missing Reference: 'WARM' is mentioned on line 628, but not defined == Missing Reference: 'SEN' is mentioned on line 919, but not defined == Missing Reference: 'AID' is mentioned on line 919, but not defined == Outdated reference: A later version (-08) exists of draft-urien-coinrg-iose-03 Summary: 1 error (**), 0 flaws (~~), 13 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 Paris 4 Intended status: Experimental 6 April 3 2022 7 Expires: October 2022 9 Remote APDU Call Secure (RACS) 10 draft-urien-core-racs-16.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) 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 October 2022. 52 . 54 Copyright Notice 56 Copyright (c) 2022 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.3.12 SEN ................................................ 21 103 2.3.13 GET-SEN ............................................ 23 104 2.4 Status header encoding..................................... 24 105 2.4.1 Event class ......................................... 24 106 2.4.2 Command class ....................................... 24 107 3 URI for the GoSE................................................ 25 108 4 HTTP interface.................................................. 25 109 4.1 HTTPS Request.............................................. 25 110 4.2 HTTPS response............................................. 26 111 5 Security Considerations......................................... 26 112 5.1 Authorization.............................................. 26 113 5.2 Secure Element access...................................... 26 114 5.3 Applications security policy............................... 27 115 5.3.1 Users-Table ......................................... 27 116 5.3.2 SEID-Table .......................................... 27 117 5.3.3 APDU-Table .......................................... 27 118 5.4 Overview of the security policy............................ 28 119 6 IANA Considerations............................................. 28 120 7 References...................................................... 28 121 7.1 Normative References....................................... 28 122 7.2 Informative References..................................... 28 123 8 Authors' Addresses.............................................. 29 124 1 Overview 126 This document describes the Remote APDU Call Protocol Secure (RACS) 127 protocol, dedicated to Grids of Secure Elements (GoSE). These 128 servers host Secure Elements (SE), i.e. tamper resistant chips 129 offering secure storage and cryptographic resources. 131 Secure Elements are microcontrollers whose chip area is about 25mm2; 132 they deliver trusted computing services in constrained environments. 134 RACS supports commands for GoSE inventory and data exchange with 135 secure elements. 137 RACS is designed according to the representational State Transfer 138 (REST) architecture [REST], which encompasses the following 139 features: 140 - Client-Server architecture. 141 - Stateless interaction. 142 - Cache operation on the client side. 143 - Uniform interface. 144 - Layered system. 145 - Code On Demand. 147 1.1 What is a Secure Element 149 A Secure Element (SE) is a tamper resistant microcontroller equipped 150 with host interfaces such as [ISO7816], SPI (Serial Peripheral 151 Interface) or I2C (Inter Integrated Circuit). 153 The typical area size of these electronic chips is about 25mm2. They 154 comprise CPU (8, 16, 32 bits), ROM (a few hundred KB), nonvolatile 155 memory (EEPROM, FLASH, a few hundred KB) and RAM (a few ten KB). 156 Security is enforced by multiple hardware and logical 157 countermeasures. 159 According to the [EUROSMART] association height billion of such 160 secure devices were shipped in 2013. Secure elements are widely 161 deployed for electronic payment (EMV cards), telecommunication (SIM 162 modules), identity (electronic passports), ticketing, and access 163 control. 165 Most of secure elements include a Java Virtual Machine and therefore 166 are able to execute embedded program written in the JAVACARD 167 language. Because these devices are dedicated to security purposes 168 they support numerous cryptographic resources such as digest 169 functions (MD5, SHA1, SHA2...), symmetric cipher (3xDES, AES) or 170 asymmetric procedures (RSA, ECC). 172 A set of Global Platform [GP] standards control the lifecycle of 173 embedded software, i.e. application downloading, activation and 174 deletion. 176 As an illustration a typical Secure Element has the following 177 characteristics: 179 - JAVACARD operating system; 180 - Compliant with the GP (Global Platform) standards; 181 - 160 KB of ROM; 182 - 72 KB of EEPROM; 183 - 4KB of RAM; 184 - Embedded crypto-processor; 185 - 3xDES, AES, RSA, ECC; 186 - Certification according to Common Criteria (CC) EAL5+ level; 187 - Security Certificates from payment operators. 189 1.2 Grid Of Secure Elements (GoSE) 191 Grid Of Secure Elements 192 +---------------------------------------------+ 193 | SlotID | 194 | Grid +------+ +------+ SEID | 195 | Inventory | |----+ | |----+ | 196 | | | SLOT | SE | | SLOT | SE | | 197 +-+-+-+--|-+ | |----+ | |----+ | 198 |I|T|T| | +------+ +------+ | 199 |P|C|L|RACS| | 200 | |P|S| | +------+ +------+ | 201 +-+-+-+--|-+ | |----+ | |----+ | 202 | | | SLOT | SE | | SLOT | SE | | 203 | | | |--+-+ | |----+ | 204 | | +------+ | +------+ | 205 | +-ISO7816 Requests-+ | 206 +---------------------------------------------+ 208 Figure 1. Architecture of a Grid of Secure Elements 210 +----+----+----+ 211 Vcc->| | |<-Ground 212 +----+ +----+ 213 RESET->| | | | 214 +----+ +----+ 215 Clock->| | | |<-Input/Output 216 +----+ +----+ 217 | | | | 218 +----+----+----+ 220 Figure 2. Illustration of an ISO7816 Secure Element 222 A grid of Secure Elements (GoSE) is a server hosting a set of secure 223 elements. 225 The goal of these platforms is to deliver trusted services over the 226 Internet. These services are available in two functional planes, 227 - The user plane, which provides trusted computing and secure 228 storage. 229 - The management plane, which manages the lifecycle (downloading, 230 activation, deletion) of applications hosted by the Secure Element. 232 A grid of Secure Elements offers services similar to HSM (Hardware 233 Secure Module), but may be managed by a plurality of administrators, 234 dealing with specific secure microcontrollers. 236 According to this draft all accesses to a GoSE require the TCP 237 transport and are secured by the TLS [TLS 1.0] [TLS 1.1] [TLS 2.0] 238 protocol. 240 The RACS protocol provides all the features needed for the remote 241 use of secure elements, i.e. 242 - Inventory of secure elements 243 - Information exchange with the secure elements 245 1.3 Secure Element Identifier (SEID) 247 Every secure element needs a physical slot that provides electrical 248 feeding and communication resources. This electrical interface is 249 for example realized by a socket soldered on an electronic board, or 250 a CAD (Card Acceptance Device, i.e. a reader) supporting host buses 251 such as USB. 253 Within the GoSE each slot is identified by a SlotID (slot 254 identifier) attribute, which may be a socket number or a CAD name. 256 The SEID (Secure Element IDentifier) is a unique identifier 257 indicating that a given SE is hosted by a GoSE. It also implicitly 258 refers the physical slot (SlotID) to which the SE is plugged. 260 The GoSE manages an internal table that establishes the relationship 261 between SlotIDs and SEIDs. 263 Therefore three parameters are needed for remote communication with 264 secure element, the IP address of the GoSE, the associated TCP port, 265 and the SEID. 267 1.3.1 SlotID example 269 According to the PC/SC (Personal Computer/Smart Card) standard 270 [PS/SC], a smart card reader MAY include a serial number. This 271 attribute (VENDOR-IFD-SERIAL) is associated to the tag 0x0103 in the 272 class VENDOR-INFO. 274 1.3.2 SEID for Secure Elements 276 According to the Global Platform standard [GP] the Issuer Security 277 Domain (ISD) manages applications lifecycle (downloading, 278 activation, deletion). The command 'initialize update' is used to 279 start a mutual authentication between the administration entity and 280 the secure element; it collects a set of data whose first ten bytes 281 are called the 'key diversification data'. This information is used 282 to compute symmetric keys, and according for example to [EMV] MAY 283 comprise a serial number. 285 1.4 APDUs 287 According to the [ISO7816] standards secure element process ISO7816 288 request messages and return ISO7816 response messages, named APDUs 289 (application protocol data unit). 291 1.4.1 ISO7816 APDU request 293 An APDU request comprises two parts: a header and an optional body. 295 The header is a set of four or five bytes noted CLA INS P1 P2 P3 297 - CLA indicates the class of the request, and is usually bound to 298 standardization committee (00 for example means ISO request). 299 -INS indicates the type of request, for example B0 for reading or D0 300 for writing. 301 - P1 P2 gives additional information for the request (such index in 302 a file or identifier of cryptographic procedures) 303 - P3 indicates the length of the request body (from P3=01 to P3=FF), 304 or the size of the expected response body (a null value meaning 256 305 bytes). Short ISO7816 requests may comprise only 4 bytes 306 - The body may be empty. Its maximum size is 255 bytes 308 1.4.2 ISO7816 APDU response 310 An APDU response comprises two parts an optional body and a 311 mandatory status word. 313 - The optional body is made of 256 bytes at the most. 315 - The response ends by a two byte status noted SW. SW1 refers the 316 most significant byte and SW2 the less significant byte. 318 An error free operation is usually associated to the 9000 status 319 word. Following are some interpretations of the tuple SW1, SW2 320 according to various standards: 322 - '61' 'xx', indicates that xx bytes (modulus 256) are ready for 323 reading. Operation result MUST be fetched by the ISO 324 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 325 - '9F' 'xx', indicates that xx bytes (modulus 256) are ready for 326 reading. Operation result MUST be fetched by the ISO 327 Get Response APDU (CLA=00, INS=C0, P1=P2=00, P3=XX) 328 - '6C' 'XX', the P3 value is wrong, request must be performed 329 again with the LE parameter value sets to 'XX' 330 - '6E' 'XX', wrong instruction class (CLA) given in the request 331 - '6D' 'XX', unknown instruction code (INS) given in the request 332 - '6B' 'XX', incorrect parameter P1 or P2 333 - '67' 'XX', incorrect parameter P3 334 - '6F' 'XX', technical problem, not implemented... 336 2 The RACS protocol 338 +-----------------+ 339 | RACS | 340 +-----------------+ 341 | TLS | 342 +-----------------+ 343 | TCP | 344 +-----------------+ 345 | IP | 346 +------------- ---+ 348 Figure 2. The RACS stack 350 The RACS protocol works over the TCP transport layer and is secured 351 by the TLS protocol. The TLS client (i.e. the RACS client) MUST be 352 authenticated by a certificate. 354 One of the main targets of the RACS protocol is to efficiently push 355 a set of ISO7816 requests towards a secure element in order to 356 perform cryptographic operations in the user's plane. In that case a 357 RACS request typically comprises a prefix made with multiple ISO7816 358 requests and a suffix that collects the result of a cryptographic 359 procedure. 361 The mandatory use of TLS with mutual authentication based on 362 certificate provides a simple and elegant way to establish the 363 credentials of a RACS client over the GoSE. It also enables an easy 364 splitting between users' and administrators' privileges. 366 2.1 Structure of RACS request 368 A RACS request is a set of command lines, encoded according to the 369 ASCII format. Each line ends by the Cr (carriage return) and line 370 feed (Lf) characters. The RACS protocol is case sensitive. 372 Each command is a set of tokens (i.e. words) separated by space 373 (0x20) character(s). 375 The first token of each line is the command to be executed. 377 A command line MAY comprise other tokens, which are called the 378 command parameters. 380 A RACS request MUST start by a BEGIN command and MUST end by an END 381 command. 383 Each command line is associated to an implicit line number. The 384 BEGIN line is associated to the zero line number. 386 The processing of a RACS request is stopped after the first error. 387 In that case the returned response contained the error status 388 induced by the last executed command. 390 2.2 Structure of a RACS response 392 A RACS response is a set of lines, encoded according to the ASCII 393 format. Each line ends by the Cr (carriage return) and line feed 394 (Lf) characters. The RACS protocol is case sensitive. 396 Each line is a set of tokens (i.e. words) separated by space (0x20) 397 character(s). 399 The first token of each line is the header. 401 The second token of response each line is associated command line 402 number 404 A response line MAY comprise other tokens, which are called the 405 response parameters. 407 Three classes of headers are defined BEGIN, END and Status. 409 A RACS response MUST start by a BEGIN header and MUST end by an END 410 header. It comprises one or several status lines. 412 2.2.1 BEGIN Header 414 This header starts a response message. 416 It comprises an optional parameter, an identifier associated to a 417 previous request message. 419 2.2.2 END Header 421 This header ends a response message. 423 2.2.3 Status line 425 A status header indicates a status line. 427 It begins by the character '+' in case of success or '-' if an error 428 occurred during the RACS request execution. It is followed by an 429 ASCII encoded integer, which is the value of the status. 431 The second mandatory token of a status line is the command line 432 number (starting from zero) 433 A status line MAY comprise other tokens, which are called the 434 response parameters. 436 2.2.4 Examples of RACS responses: 438 BEGIN CrLf 439 +001 000 Success CrLf 440 END CrLf 442 BEGIN moon1969 CrLf 443 -301 007 Illegal command, BEGIN condition not satisfied at line 7 444 END CrLf 446 BEGIN Asterix237 CrLf 447 +006 001 [ISO7816-Response] CrLf 448 END CrLf 450 BEGIN CrLf 451 -100 002 Unknown command at line 2 CrLf 452 END CrLf 454 BEGIN CrLf 455 -606 001 Unauthorized command APDU command at line 1 456 END CrLf 458 BEGIN CrLf 459 -706 001 SEID Already in use, APDU command at line 1 460 END CrLf 462 2.3 RACS request commands 464 2.3.1 BEGIN 466 This command starts a request message. A response message is 467 returned if an error is detected. 469 An optional parameter is the request identifier, which MUST be 470 echoed in the parameter of the first response line (i.e. starting by 471 the BEGIN header). 473 2.3.2 END 475 This command ends a request message. It returns the response message 476 triggered by the last command. 478 Example1 479 ======== 480 Request: 481 BEGIN CrLf 482 END CrLf 484 Response: 485 BEGIN CrLf 486 +001 000 Success CrLf 487 END CrLF 489 Example2 490 ======== 491 Request: 492 BEGIN Marignan1515 CrLf 493 APDU ASTERIX-CRYPTO-MODULE [ISO7816-Request] CrLf 494 END CrLf 496 Response: 497 BEGIN Marignan1515 CrLf 498 +006 001 [ISO7816-Response] CrLf 499 END CrLf 501 2.3.3 The APPEND parameter 503 The APPEND parameter MAY be used in all command lines, excepted 504 BEGIN and END. The APPEND parameter MUST be the last parameter of a 505 command line. 506 By default a response message returns only the last status line. 507 When APPEND is inserted, the command line, if executed, MUST produce 508 a status line. 510 Example 512 Request: 513 BEGIN SanchoPanza CrLf 514 APDU 100 [ISO7816-Request-1] CrLf 515 APDU 100 [ISO7816-Request-2] CrLf 516 END CrLf 518 Response: 519 BEGIN SanchoPanza CrLf 520 +006 002 [ISO7816-Response-2] CrLf 521 END CrLf 523 Request: 524 BEGIN DonQuichotte CrLf 525 APDU 100 [ISO7816-Request-1] APPEND CrLf 526 APDU 100 [ISO7816-Request-2] APPEND CrLf 527 END CrLf 528 Response: 529 BEGIN DonQuichotte CrLf 530 +006 001 [ISO7816-Response-1] CrLf 531 +006 002 [ISO7816-Response-2] CrLf 532 END CrLf 534 2.3.4 GET-VERSION 536 This command requests the current version of the RACS protocol. 537 The returned response is the current version encoded by two integer 538 separated by the '.' character. The first integer indicates the 539 major version and the second integer gives the minor version. 541 This draft version is 0.2 543 Example 544 ======= 545 Request: 546 BEGIN CrLf 547 GET-VERSION CrLf 548 END CrLf 550 Response: 551 BEGIN CrLf 552 +002 001 1.0 CrLf 553 END CrLf 555 2.3.5 SET-VERSION 557 This command sets the version to be used for the RACS request. An 558 error status is returned by the response if an error occurred. 560 Example 1 561 ========= 562 Request: 563 BEGIN CrLf 564 SET-VERSION 2.0 CrLf 565 END CrLf 567 Response: 568 BEGIN CrLf 569 -403 001 Error line 1 RACS 2.0 is not supported CrLf 570 END CrLf 572 Example 2 573 ========= 574 Request: 575 BEGIN CrLf 576 SET-VERSION 1.0 CrLf 577 END CrLf 578 Response: 579 BEGIN CrLf 580 +003 001 RACS 1.0 has been activated CrLf 581 END CrLf 583 2.3.6 LIST 585 This command requests the list of SEID plugged in the GoSE. 587 It returns a list of SEIDs separated by space (0x20) character(s). 589 Some SEID attributes MAY be built from a prefix and an integer 590 suffix (such as SE#100 in which SE# is the suffix and 100 is the 591 integer suffix. A list of non-consecutive SEID MAY be encoded as 592 prefix[i1;i2;..;ip] where i1,i2,ip indicates the integer suffix. A 593 list of consecutive SEID could be encoded as prefix[i1-ip] where 594 i1,i2,ip indicates the integer suffix. 596 Example 1 597 ========= 598 Request: 599 BEGIN CrLf 600 LIST CrLf 601 END CrLf 603 Response: 604 BEGIN CrLf 605 +004 001 SEID1 SEID2 CR LF 606 END CrLf 608 Example 2 609 ========= 610 Request: 611 BEGIN CrLf 612 LIST CrLf 613 END CrLf 615 Response: 616 BEGIN CrLf 617 +004 001 Device[1000-2000] SerialNumber[567;789;243] CrLf 618 END CrLf 620 2.3.7 RESET 622 This command resets a secure element. The first parameter gives the 623 secure element identifier (SEID). An optional second parameter 624 specifies a warm reset. The default behavior is a cold reset. 625 The response status indicates the success or the failure of this 626 operation. 628 Syntax: RESET SEID [WARM] CrLf 630 Example 1 631 ========= 632 Request: 633 BEGIN CrLf 634 RESET device#45 CrLf 635 END CrLf 637 Response: 638 BEGIN CrLf 639 +005 001 device#45 Reset Done 640 END CrLf 642 Example 2 643 ========= 644 Request: 645 BEGIN CrLf 646 RESET device#45 CrLf 647 END CrLf 649 Response: 650 BEGIN CrLf 651 -705 001 error device#45 is already in use 652 END CrLf 654 Example 3 655 ========= 656 Request: 657 BEGIN CrLf 658 RESET device#45 WARM CrLf 659 END CrLf 661 Response: 662 BEGIN CrLf 663 +005 001 device#45 Warm Reset Done CrLf 664 END CrLf 666 2.3.8 APDU 668 This command sends an ISO7816 request to a secure element or a set 669 of ISO7816 commands. 671 The first parameter specifies the SEID. 672 The second parameter is an ISO7816 request. 673 Three optional parameters are available; they MUST be located after 674 the second parameter. 676 - CONTINUE=value, indicates that the next RACS command will be 677 executed only if the ISO7816 status word (SW) is equal to a given 678 value. Otherwise an error status is returned. 679 - MORE=value, indicates that a FETCH request will be performed (i.e. 680 a new ISO7816 request will be sent) if the first byte of the ISO7816 681 status word (SW1) is equal to a given value. 682 - FETCH=value fixes the four bytes of the ISO7816 FETCH request 683 (i.e. CLA INS P1 P2). The default value (when FETCH is omitted) is 684 00C00000 (CLA=00, INS=C0, P1=00, P2=00) 686 When the options CONTINUE and MORE are simultaneously set the SW1 687 byte is first checked. If there is no match then the SW word is 688 afterwards checked. 690 The ISO7816 6Cxx status MUST be autonomously processed by the GoSE. 692 SYNTAX 693 APDU SEID ISO7816-REQUEST [CONTINUE=SW] [MORE=SW1] [FETCH=CMD] CrLf 695 The returned response is the ISO7816 response. If multiple ISO7816 696 requests are executed (due to the MORE option), the bodies are 697 concatenated in the response, which ends by the last ISO7816 status 698 word. 700 The pseudo code of the APDU command is the following : 702 1. BODY = empty; 703 2. SW = empty; 704 3. DoIt = true; 705 3. Do 706 4. { iso7816-response = send(iso7816-request); 707 5. body || sw1 || sw2 = iso7816-response; 708 6. If ( (first request) && (iso7816-request.size==5) && 709 (body==empty) && (sw1==6C) ) 710 8. { iso7816-request.P3 = sw2 ; } 711 6. Else 712 7. { SW = sw1 || sw2 713 8. BODY = BODY || body; 714 9. If (sw1 == MORE) 715 10. { iso7816-request = FETCH || sw2 ; } 716 11. Else 717 12. { DoIt=false;} 718 13. } 719 14. } 720 15. While (DoIt == true) 722 16. iso7816-response = BODY || SW ; 723 17. If (SW != CONTINUE) Error ; 724 18. Else No Error; 725 Example 1 726 ========= 727 Request: 728 BEGIN CrLf 729 APDU SEID ISO7816-REQUEST CrLf 730 END CrLf 732 Response: 733 BEGIN CrLf 734 +006 001 ISO7816-RESPONSE CrLf 735 END CrLf 737 Example 2 738 ========= 739 Request: 740 BEGIN CrLf 741 APDU SEID ISO7816-REQUEST CrLf 742 END CrLf 744 Response: 745 BEGIN CrLf 746 -706 001 error SEID is already used CrLf 747 END CrLf 749 Example 3 750 ========= 751 Request: 752 BEGIN CrLf 753 APDU SEID ISO7816-REQUEST CrLf 754 END CrLf 756 Response: 757 BEGIN CrLf 758 -606 001 error access unauthorized access CrLf 759 END CrLf 761 Example 4 762 ========= 763 BEGIN CrLf 764 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 765 APDU SEID ISO7816-REQUEST-2 CrLf 766 END CrLf 768 Response: 769 BEGIN CrLf 770 +006 002 ISO7816-RESPONSE-2 CrLf 771 END CrLf 772 Example 5 773 ========= 774 BEGIN CrLf 775 APDU SEID ISO7816-REQUEST-1 CONTINUE=9000 CrLf 776 APDU SEID ISO7816-REQUEST-2 CrLf 777 END CrLf 779 Response: 780 BEGIN CrLf 781 -006 001 Request Error line 1 wrong SW CrLf 782 END CrLf 784 Example 6 785 ========= 786 BEGIN CrLf 787 APDU SEID ISO7816-REQ-1 CONTINUE=9000 CrLf 788 APDU SEID ISO7816-REQ-2 CONTINUE=9000 CrLf 789 APDU SEID ISO7816-REQ-3 CONTINUE=9000 MORE=61 FETCH=00C00000 CrLf 790 END CrLf 792 Response: 793 BEGIN CrLf 794 +006 003 ISO7816-RESP-3 CrLf 795 END CrLf 797 Multiple ISO7816 requests have been performed by the third APDU 798 command according to the following scenario : 799 - the ISO7816-REQ-3 request has been forwarded to the secure element 800 (SEID) 801 - the ISO 7816 response comprises a body (body-0) and a status word 802 (SW-0) whose first byte is 0x61, and the second byte is SW2-0 803 - the FETCH command CLA=00, INS=00, P1=00, P2=00, P3=SW2-0 is sent 804 to the secure element 805 - the ISO 7816 response comprises a body (body-1) and a status word 806 (SW-1) set to 9000 808 The RACS response is set to 809 +006 003 body-0 || body-1 || SW-1 CrLf 810 where ||indicates a concatenation operation. 812 2.3.9 SHUTDOWN 814 This command powers down a secure element. The first parameter gives 815 the secure element identifier (SEID). 817 Syntax: SHUTDOWN SEID CrLf 818 Example 819 ========= 820 Request: 821 BEGIN Goodbye CrLf 822 SHUTDOWN device#45 CrLf 823 END CrLf 825 Response: 826 BEGIN Goodbye CrLf 827 +007 001 device#45 has been powered down CrLf 828 END CrLf 830 2.3.10 POWERON 832 This command powers up a secure element. The first parameter gives 833 the secure element identifier (SEID). 835 Syntax: POWERON SEID CrLf 837 Example 1 838 ========= 839 Request: 840 BEGIN CrLf 841 POWERON device#45 CrLf 842 END CrLf 844 Response: 845 BEGIN CrLf 846 +008 001 device#45 Has been powered up CrLf 847 END CrLf 849 Example 2 850 ========= 851 Request: 852 BEGIN CrLf 853 POWERON device#45 CrLf 854 END CrLf 856 Response: 857 BEGIN CrLf 858 -708 001 error device#45 is already in use CrLf 859 END CrLf 861 Example 3 862 ========= 863 Request: 864 BEGIN CrLf 865 POWERON device#45 CrLf 866 END CrLf 867 Response: 868 BEGIN CrLf 869 -608 001 error unauthorized access CrLf 870 END CrLf 872 2.3.11 ECHO 874 This command echoes a token. The first parameter is the token (word) 875 to be echoed by the response. 877 Syntax: ECHO SEID CrLf 879 Example 1 880 ========= 881 Request: 882 BEGIN TestEcho CrLf 883 ECHO Hello CrLf 884 END CrLf 886 Response: 887 BEGIN TestEcho CrLf 888 +009 001 Hello CrLf 889 END CrLf 891 Example 2 892 ========= 893 Request: 894 BEGIN ResetSEID CrLf 895 POWERON device#45 CrLf 896 ECHO Done CrLf 897 END CrLf 899 Response: 900 BEGIN ResetSEID CrLf 901 +009 001 Done CrLf 902 END CrLf 904 2.3.12 SEN 906 This command associates Secure Element Name (SEN) to SEID. 907 Secure Element Name are defined in [IOSE] 909 The first parameter (mandatory) is the SEID. By default the SEN is 910 found in the ISO7816 ATR, and the TLS-SE application is the secure 911 element default application. 913 The second parameter (optional) is the SEN. This option sets the 914 SEN, and discards the ATR content. 916 The third parameter (optional) is the TLS-SE Application IDentifier 917 (AID). 919 Syntax: SEN SEID [SEN] [AID] CrLf 921 Example 1 922 ========= 924 Request: 925 BEGIN CrLf 926 SEN mySEID CrLf 927 END CrLf 929 Response: 930 BEGIN CrLf 931 +010 001 SEN= key1.com AID= default 932 END CrLf 934 Example 2 935 ========= 937 Request: 938 BEGIN CrLf 939 SEN mySEID key1.com CrLf 940 END CrLf 942 Response: 943 BEGIN CrLf 944 +010 001 SEN= key1.com AID= default CrLf 945 END CrLf 947 Example 3 948 ========= 950 Request: 951 BEGIN CrLf 952 SEN mySEID key1.com 010203040500 CrLf 953 END CrLf 955 Response: 956 BEGIN CrLf 957 +010 001 SEN= key1.com AID= 010203040500 CrLf 958 END CrLf 960 Example 4 961 ========= 962 Request: 963 BEGIN CrLf 964 SEN wrongSEID key1.com CrLf 965 END CrLf 967 Response: 968 BEGIN CrLf 969 -410 001 SEN invalid SEID (wrongSEID) CrLf 970 END CrLf 972 2.3.13 GET-SEN 974 This command gets Secure Element Name (SEN) associated to SEID. 975 Secure Element Name are defined in [IOSE] 977 Syntax: GET-SEN SEID CrLf 979 Example 1 980 ========= 982 Request: 983 BEGIN CrLf 984 GET-SEN mySEID CrLf 985 END CrLf 987 Response: 988 BEGIN CrLf 989 +011 001 key1.com [AID= default] 990 END CrLf 992 Example 2 993 ========= 995 Request: 996 BEGIN CrLf 997 GET-SEN mySEID CrLf 998 END CrLf 1000 Response: 1001 BEGIN CrLf 1002 +011 001 key1.com [AID= 010203040500] 1003 END CrLf 1005 Example 3 1006 ========= 1008 Request: 1009 BEGIN CrLf 1010 GET-SEN wrongSEID CrLf 1011 END CrLf 1013 Response: 1014 BEGIN CrLf 1015 -511 001 GET-SEN invalid SEID (wrongSEID) 1016 END CrLf 1018 2.4 Status header encoding 1020 The first token of a response line is the status header. It begins 1021 by a '+' or a '-' character, and comprises three decimal digits 1022 (xyz). 1024 The first digit (x) MUST indicates an event class. 1025 The second and third digits (yz) MAY indicate a command class. 1027 2.4.1 Event class 1029 This draft only defines the meaning of the first digit located at 1030 the left most side. 1032 +0yz: No error 1033 -0yz: Command execution error 1034 -1yz: Unknown command, the command is not defined by this draft 1035 -2yz: Not implemented command 1036 -3yz: Illegal command, the command can't be executed 1037 -4yz: Not supported parameter or parameter illegal value 1038 -5yz: Parameter syntax error or parameter missing 1039 -6yz: Unauthorized command 1040 -7yz: Already in use, a session with this SE is already opened 1041 -8yz: Hardware error 1042 -9yz: System error 1044 2.4.2 Command class 1046 The second and third digits (yz) MAY indicates the command that 1047 trigged the current line status 1049 01 BEGIN 1050 02 GET-VERSION 1051 03 SET-VERSION 1052 04 LIST 1053 05 RESET 1054 06 APDU 1055 07 SHUTDOWN 1056 08 POWERON 1057 09 ECHO 1058 10 SEN 1059 11 GET-SEN 1060 3 URI for the GoSE 1062 The URI addressing the resources hosted by the GoSE is represented 1063 by the string: 1065 RACS://GoSE-Name:port/?request 1067 where request is the RACS request to be forwarded to a the GoSE. 1069 RACS command lines are encoded in a way similar to the INPUT field 1070 of an HTML form. Each command is associated to an INPUT name, the 1071 remaining of the command line i.e. a set of ASCII characters, is 1072 written according to the URL encoding rules. End of line characters, 1073 i.e. carriage return (Cr) and line feed (Lf) are omitted. 1075 As a consequence a request is written to the following syntax 1076 cmd1=cmd1-parameters&cmd2=cmd2-parameters 1078 Example: 1079 RACS://GoSE-Name:port/?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 1081 4 HTTP interface 1083 A GoSE SHOULD support an HTTP interface. RACS requests/responses are 1084 transported by HTTP messages. The use of TLS is mandatory. 1086 4.1 HTTPS Request 1088 https://GoSE-Name:port/RACS?request 1090 where request is the RACS request to be forwarded to a secure 1091 element (SEID) 1093 The RACS request is associated to an HTML form whose name is "RACS". 1094 The request command lines are encoded as the INPUT field of an HTML 1095 form. Each command is associated to an INPUT name, the remaining of 1096 the command line i.e. a set of ASCII characters is written according 1097 to the URL encoding rules. End of line characters, i.e. carriage 1098 return (Cr) and line feed (Lf) are omitted. 1100 As a consequence a RACS request is written as 1101 https://GoSE-Name/RACS?cmd1=cmd1-parameters&cmd2=cmd2-parameters 1103 Example: 1105 https://GoSE-Name/RACS?BEGIN=&APDU=SEID%20[ISO7816-REQUEST]&END= 1106 4.2 HTTPS response 1108 The RACS response is returned in an XML document. 1110 The root element of the document is 1112 The optional parameter of the BEGIN header, is the content of the 1113 element. 1115 Each status line is the content of the element, which 1116 includes the following information : 1118 - The status header is the content of the element. 1120 - The line number is the content of the element. 1122 - The other parameters of the status line are the content of the 1123 element. 1125 The END header is associated to the element 1127 End of line, i.e. carriage return (Cr) and line feed (Lf) characters 1128 are omitted. 1130 As a consequence a RACS response is written as : 1131 1132 Optionnal-ID 1133 +000 1135 001 1136 other parameters of the RACS response 1137 1138 1139 1141 5 Security Considerations 1143 5.1 Authorization 1145 A RACS client MUST be authenticated by an X509 certificate. 1147 The GoSE software MUST provide a mean to establish a list of SEIDs 1148 that can be accessed from a client whose identity is the CommonName 1149 (CN) attribute of its certificate. It MAY allocate a UserID (UID), 1150 i.e. an integer index from the certfificate common name. 1152 5.2 Secure Element access 1154 The GoSE MUST manage a unique session identifier (SID) for each TLS 1155 session. The SID is bound to the client's certificate CommonName 1156 (SID(CN)) 1157 A secure element has two states, unlocked and locked. In the locked 1158 state the secure element may be only used by the SID that previously 1159 locked it. 1161 The first authorized command that successfully accesses to a SEID 1162 (either POWERON ,RESET, APDU) locks a secure element (SEID) with the 1163 current session (SID). 1165 The SHUTDOWN command MUST unlock a secure element (SEID). 1167 The end of a TLS session MUST unlock all the secure elements locked 1168 by the session. 1170 5.3 Applications security policy 1172 According to the [ISO7816] standards each Application embedded 1173 within a secure element (associated to a SEID) is identified by an 1174 AID parameter (16 bytes at the most) 1176 The RACS server SHOULD support the following facilities 1178 5.3.1 Users-Table 1180 Each CN (the Users-Table primary key) is associated to a list of 1181 SEIDs whose access is authorized. 1183 5.3.2 SEID-Table 1185 Each AID (the SEID-Table primary key) is associated to a list of CNs 1186 whose access is authorized. 1188 5.3.3 APDU-Table 1190 For a given AID and an authorized CN, an APDU-Table MAY be 1191 available. This table acts as a firewall, which defined a set of 1192 forbidden ISO7816 commands. 1194 For example this filter could be expressed as a set of the four 1195 first bytes of an APDU-Prefix (CLA INS P1 P2) and a four bytes Mask 1196 An ISO7816-Request is firewall if: 1198 ISO7816-Request AND Mask IsEQUAL to APDU-Prefix 1199 5.4 Overview of the security policy 1201 The summary of the security policy is illustrated by the figure 3. 1203 CN(uid) 1204 /\ 1205 TLS-Session / \ 1206 / \ 1207 sid sid 1208 /\ /\ 1209 / \ / \ 1210 aid aid aid aid 1211 /\ 1212 / \ 1213 / \ 1214 APDU APDU 1215 Filter Filter 1217 Figure 3. Summary of the security policy 1219 6 IANA Considerations 1221 This draft does not require any action from IANA. 1223 7 References 1225 7.1 Normative References 1227 [TLS 1.0] Dierks, T., C. Allen, "The TLS Protocol Version 1.0", RFC 1228 2246, January 1999 1230 [TLS 1.1] Dierks, T., Rescorla, E., "The Transport Layer Security 1231 (TLS) Protocol Version 1.1", RFC 4346, April 2006 1233 [TLS 1.2] Dierks, T., Rescorla, E., "The Transport Layer Security 1234 (TLS) Protocol Version 1.2", RFC 5746, August 2008 1236 [TLS 1.3] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1237 Version 1.3", RFC 8446, August 2018 1239 [ISO7816] ISO 7816, "Cards Identification - Integrated Circuit Cards 1240 with Contacts", The International Organization for Standardization 1241 (ISO) 1243 7.2 Informative References 1245 [REST] Fielding, R., "Architectural Styles and the Design of 1246 Network-based Software Architectures", 2000, 1247 http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm 1249 [GP] Global Platform Standards, http://www.globalplatform.org 1251 [EUROSMART] The EUROSMART association, http://www.eurosmart.com 1253 [PC/SC] The PC/SC workgroup, http://www.pcscworkgroup.com 1255 [EMV] EMV Card Personalization Specification, Version 1.1, July 2007 1257 [OPENRACS] https://github.com/purien, open RACS implementation for 1258 Win32, Ubuntu, Raspberrypi 1260 [IOSE] Internet of Secure Elements, draft-urien-coinrg-iose-03.txt, 1261 September 2021 1263 8 Authors' Addresses 1265 Pascal Urien 1266 Telecom Paris 1267 19 place Marguerite Perey 1268 91120 Palaiseau Phone: NA 1269 France Email: Pascal.Urien@telecom-paris.fr