idnits 2.17.1 draft-hallambaker-json-web-service-08.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 ([1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 13 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 714 has weird spacing: '...egistry jose-...' -- The document date (September 18, 2017) is 2410 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 805 -- Looks like a reference, but probably isn't: '2' on line 808 == Missing Reference: 'RFC2119' is mentioned on line 203, but not defined ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 7540 (Obsoleted by RFC 9113) Summary: 4 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Hallam-Baker 3 Internet-Draft Comodo Group Inc. 4 Intended status: Informational September 18, 2017 5 Expires: March 22, 2018 7 JSON Web Service Binding Version 1.0 8 draft-hallambaker-json-web-service-08 10 Abstract 12 The JSON Web Binding (JWB) describes a standardized approach to 13 implementing Web Services. Services are advertised using the DNS SRV 14 and HTTP Well Known Service conventions. Messages may be 15 authenticated or authenticated and encrypted at the message layer in 16 addition to any transport and/or network layer security. Service 17 messages are encoded in JSON using Internet time format for Date-Time 18 fields and Base64urlencoding for binary objects. 20 This document specifies Version 1.0 of JWB which uses HTTP/1.1 for 21 transport. Use of the multiple stream capabilities of HTTP/2 or QUIC 22 is outside the scope of this document. 24 This document is also available online at 25 http://prismproof.org/Documents/draft-hallambaker-json-web- 26 service.html [1] . 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at https://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on March 22, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (https://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 2.1. Requirements Language . . . . . . . . . . . . . . . . . . 5 65 2.2. Defined Terms . . . . . . . . . . . . . . . . . . . . . . 5 66 2.3. Related Specifications . . . . . . . . . . . . . . . . . 5 67 2.4. Implementation Status . . . . . . . . . . . . . . . . . . 5 68 3. Service Discovery . . . . . . . . . . . . . . . . . . . . . . 5 69 3.1. Host Identification . . . . . . . . . . . . . . . . . . . 5 70 3.1.1. SRV Host discovery . . . . . . . . . . . . . . . . . 6 71 3.1.2. DNS Fallback . . . . . . . . . . . . . . . . . . . . 6 72 3.1.3. TXT Service Description . . . . . . . . . . . . . . . 6 73 3.2. HTTP host processing . . . . . . . . . . . . . . . . . . 7 74 3.2.1. Use of TLS transport . . . . . . . . . . . . . . . . 7 75 3.2.2. Fallback Processing Rules . . . . . . . . . . . . . . 7 76 3.2.3. Service Continuation . . . . . . . . . . . . . . . . 7 77 3.3. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 78 4. HTTP Messages . . . . . . . . . . . . . . . . . . . . . . . . 9 79 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 4.2. Response . . . . . . . . . . . . . . . . . . . . . . . . 11 81 5. Error handling and response codes . . . . . . . . . . . . . . 11 82 6. Content Encoding . . . . . . . . . . . . . . . . . . . . . . 12 83 6.1. Direct Encoding . . . . . . . . . . . . . . . . . . . . . 12 84 6.2. Content-Encoding: jose-jwb . . . . . . . . . . . . . . . 12 85 6.3. Authenticated . . . . . . . . . . . . . . . . . . . . . . 13 86 6.4. Authenticated Encryption . . . . . . . . . . . . . . . . 13 87 7. Content Type . . . . . . . . . . . . . . . . . . . . . . . . 13 88 8. JSON Data Bindings . . . . . . . . . . . . . . . . . . . . . 13 89 8.1. Request Message . . . . . . . . . . . . . . . . . . . . . 14 90 8.2. Response Message . . . . . . . . . . . . . . . . . . . . 14 91 8.3. Data Fields . . . . . . . . . . . . . . . . . . . . . . . 14 92 9. Security Considerations . . . . . . . . . . . . . . . . . . . 15 93 9.1. Integrity . . . . . . . . . . . . . . . . . . . . . . . . 15 94 9.1.1. DNS Spoofing . . . . . . . . . . . . . . . . . . . . 15 95 9.1.2. TLS Downgrade . . . . . . . . . . . . . . . . . . . . 15 96 9.1.3. TLS Service Impersonation . . . . . . . . . . . . . . 15 97 9.1.4. Request Replay Attack . . . . . . . . . . . . . . . . 15 98 9.1.5. Response Replay Attack . . . . . . . . . . . . . . . 15 99 9.2. Confidentiality . . . . . . . . . . . . . . . . . . . . . 15 100 9.2.1. Side Channel Attack . . . . . . . . . . . . . . . . . 15 101 9.2.2. Session Key Leakage . . . . . . . . . . . . . . . . . 15 102 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 103 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 104 11.1. Normative References . . . . . . . . . . . . . . . . . . 16 105 11.2. Informative References . . . . . . . . . . . . . . . . . 17 106 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 17 107 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 18 109 1. Introduction 111 The JSON Web Binding (JWB) specifies one approach to using DNS 112 Discovery [RFC1035] , the HTTP [RFC7230] protocol and the JSON data 113 encoding [RFC7159] in a Web Service. 115 JWB is not the only approach possible, but developing a standard 116 means making choices that don?t matter to developers that build on 117 it. While there are infinitely many ways that a Web Service might 118 employ HTTP and JSON to implement a Web Service, a client and a 119 server can only interoperate if they both agree to use the same one. 121 Discovery Beginning with a DNS address of the service (e.g. 122 example.com), the client identifies a specific HTTP URL at which 123 to access the service. DNS-Based Service Discovery [RFC6763] 124 using the TXT and SRV records [RFC2782] and the HTTP Well Known 125 Service [RFC5785] mechanisms are used for this purpose. 127 Authentication and Encryption Web Services MAY require 128 authentication and encryption services at the message level even 129 if transport layer security (e.g. TLS [RFC5264] ) is used. Use 130 of such enhancements is signaled using the HTTP Content-Encoding 131 header. 133 Content Mapping The mapping of data types described in the 134 specification (integer, string, etc.) to JSON data types. 135 [RFC3339] Date time encoding and BASE64-url encoding [RFC4648] are 136 used to map date-time and binary data types to JSON encoding 137 values. 139 JWB establishes an intermediate layer between the Web Service and the 140 network layer (Figure 1). 142 [[This figure is not viewable in this format. The figure is 143 available at http://prismproof.org/Documents/draft-hallambaker-json- 144 web-service.html [2].]] 146 JWB Defines Presentation and Encoding Layers. 148 A key architectural principle that guides the design of JWB is that 149 the Web Service implementation should be as independent of the HTTP 150 presentation layer as is possible. Thus: 152 Message semantics are not affected by HTTP headers or the request 153 line URL. 155 The use of HTTP response codes is limited to reporting errors and 156 warnings that arise from the HTTP transport. 158 If message layer authentication or authenticated encryption are used, 159 this is applied within the HTTP content payload and not through a 160 combination of payload and header data. 162 This specification describes a mechanism for accessing a collection 163 of hosts as a single undifferentiated service with provision for load 164 balancing and fault tolerance. This has important consequences for 165 state management. Web Services typically involve some form of 166 stateful interaction or real world side effect. Otherwise, it is 167 likely that the Web Service would be better written as a traditional 168 Web interaction mapping the stateless resources to URIs. 170 The mechanism described in this specification is intended for the 171 initial discovery of a host with which to engage in a Web Service 172 transaction which may or may not consist of a series of message 173 exchanges. Since sharing state between hosts supporting a virtual 174 service requires resources and typically introduces latency, a 175 service specification MAY require that a transaction begun on one 176 host be completed with the same host and the time period in which a 177 transaction that is accepted by one host will be regarded as ?final? 178 by the virtual service. 180 For example, a file upload protocol for a photograph sharing service 181 might have separate messages for checking that there is space to 182 store the photograph ?Check?, uploading the file ?Store? and 183 reporting that the data is safely stored at multiple locations. When 184 responding to the Check command, the host is reporting that there is 185 space at that local node. It is obviously undesirable for a client 186 to verify that host1 has enough space to store the file and then 187 attempt to upload the file to host2. Equally, having uploaded the 188 file to host1, it might be minutes, hours or even days before the 189 photograph could be retrieved through host2. Such questions are left 190 for the Web Service protocol designer to address. 192 2. Definitions 194 This section presents the related specifications and standard, the 195 terms that are used as terms of art within the documents and the 196 terms used as requirements language. 198 2.1. Requirements Language 200 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 201 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 202 document are to be interpreted as described in [RFC2119]. 204 2.2. Defined Terms 206 No terms of art are defined. 208 2.3. Related Specifications 210 JSON Web Service Binding is used extensively in the Mathematical Mesh 211 and related protocols [draft-hallambaker-mesh-architecture] . 213 2.4. Implementation Status 215 The implementation status of the reference code base is described in 216 the companion document [draft-hallambaker-mesh-developer] . 218 3. Service Discovery 220 Service discovery is the process of resolving the address of a Web 221 Service to a Web Service Endpoint, a URI [RFC3986] at which the 222 service is provided. 224 A JWB Web Service is specified by giving the DNS Address of the 225 service , and Well Known Service name . 227 3.1. Host Identification 229 The first step in service discovery is to resolve the and 230 identifiers to the IP address of a host that provides that 231 service. 233 3.1.1. SRV Host discovery 235 A client attempting to connect to the service first attempts to 236 locate an SRV record [RFC2782] for the specified service: 238 _._tcp._ SRV 240 Figure 1 242 Where and are the SRV priority and weight 243 parameters specified in [RFC2782] , is the TCP port number and 244 is the DNS name of the host for which the service 245 advertisement is made. Standard A/AAAA/CNAME resolution is used to 246 obtain the IP address of the host from . 248 If a match is found, the client uses the mechanism specified in 249 [RFC2782] to choose hosts and attempts to contact each host in turn 250 until a successful HTTP connection is established or the maximum 251 number of attempts threshold is reached. 253 3.1.2. DNS Fallback 255 Despite the fact that SRV records have been a part of the DNS 256 standard for 20 years, it is not uncommon for network intermediaries 257 to implement SRV record resolution incorrectly or block it entirely. 259 If no SRV record is found, a client MAY perform fallback discovery if 260 explicitly authorized to do so by the corresponding Web Service 261 protocol specification. The client attempts to connect to the host 262 . using the standard A/AAAA/CNAME resolution rules 263 to obtain the IP address of the host. 265 3.1.3. TXT Service Description 267 A service MAY advertise service and/or host description information 268 using TXT records as described in DNS-Based Service Discovery 269 [RFC6763] . These have the following format: 271 _._tcp._ TXT "= [=]*" 272 _._tcp._ TXT "= [=]*" 274 Figure 2 276 Service descriptions specified under the domain address of the 277 service apply to all host instances of the service. Descriptions 278 specified under the domain address of a host instance apply only to 279 that host instance and take precedence over values specified at the 280 service level. 282 The following tags are defined: 284 path The path to use to construct the Web Service Endpoint. 286 version The service version(s) supported in the format - 288 3.2. HTTP host processing 290 Having identified the IP address, the client performs a HTTP or HTTPS 291 Web Service POST request at the default Web Service Endpoint 292 specified by the Well Known Service name and the DNS address of the 293 host instance. 295 http://:/.well-known/ 297 Figure 3 299 Note that a given host MAY provide multiple instances of a Web 300 Service under different discovery addresses. Therefore it is 301 essential to use the original value rather than the 302 returned in the SRV record. 304 3.2.1. Use of TLS transport 306 This document does not describe a mechanism for mandating use of TLS. 308 If TLS is used, the Web Service client MUST use the service address 309 () as the basis for certificate subjectAltName validation. 311 3.2.2. Fallback Processing Rules 313 If a client?s attempt to connect to a host selected from an SRV 314 connection redirection results in a HTTP (3xx), Client error (4xx) or 315 Server error (5xx) code, the client MUST process the HTTP error 316 response and not simply attempt a connection to a different host. If 317 a client request is rejected for lack of authentication (511) or 318 because the request is too large (413) at one host, the client should 319 assume that the request will be rejected for the same reason at 320 another. If the attempt to create a TCP connection fails or the 321 server returns Service Unavailable (503), the client MAY use the SRV 322 fallback rules to select an alternative host. 324 3.2.3. Service Continuation 326 Once the initial service discovery mechanism has been used to 327 establish contact with a host, the service protocol MAY specify that 328 further interactions be directed to another host and/or using a 329 different protocol. Such mechanisms are outside the scope of this 330 specification. 332 3.3. Example 334 The Mathematical Mesh has the Well Known Service name of ?MMM'. 335 Accounts used in the Mathematical Mesh follow the [RFC5322] format of 336 @. 338 Alice has the account alice@example.com and the DNS configuration 339 file for example.com has the following entries: 341 _mmm._tcp.example.com SRV host1.example.com 0 10 80 host1.example.com 342 _mmm._tcp.example.com SRV host2.example.com 0 40 80 host2.example.com 343 _mmm._tcp.example.com TXT "version=1.0-2.0" 344 mmm.example.com CNAME host3.example.com 345 host1.example.com A 10.0.1.1 346 host2.example.com A 10.0.1.2 347 _mmm._tcp.host2.example.com TXT "path=/service" 348 host3.example.com A 10.0.1.1 349 host3.example.com A 10.0.1.2 351 Figure 4 353 The client attempts to resolve the address alice@example.com as 354 follows: 356 1. Client attempts to resolve SRV and TXT records for 357 _mmm._tcp.example.com 359 2. DNS resolver returns two SRV entries and one TXT entry 361 3. Client makes a random selection between host1 (20% weighting) 362 and host2 (80% weighting). Chooses host1. 364 4. Client resolves A/AAAA for host1.example.com and TXT for 365 _mmm._tcp.host1.example.com 367 5. DNS resolver returns A=10.0.1.1 and TXT=none 369 6. Client attempts to POST Web Service request to 370 http://host1example.com/.well-known/mmm at host address 10.0.1.1 372 7. The host at 10.0.1.1 returns 503 Service Unavailable 374 8. Client resolves A/AAAA for host2.example.com and TXT for 375 _mmm._tcp.host2.example.com 377 9. DNS resolver returns A=10.0.1.2 and TXT "path=/service" 379 10. Client attempts to POST Web Service request to 380 http://host2example.com/service at host address 10.0.1.2 382 11. Request succeeds, session proceeds. 384 If the same client is used in a network location where the SRV record 385 resolution fails due to a faulty firewall configuration, the 386 resolution proceeds as follows: 388 1. Client attempts to resolve SRV record for _mmm._tcp.example.com 390 2. DNS resolver returns ?not found? 392 3. Client attempts to resolve A and AAAA record 394 4. DNS resolver returns 10.0.1.1, 10.0.1.2 396 5. Client makes a random selection between 10.0.1.1 (50% weighting) 397 and 10.0.1.2 (50% weighting). Chooses host1. 399 6. Client attempts to POST Web Service request to 400 http://example.com/.well-known/mmm at host address 10.0.1.1 402 7. The host at 10.0.1.1 returns 503 Service Unavailable 404 8. Client attempts to POST Web Service request to 405 http://example.com/.well-known/mmm at host address 10.0.1.2 407 9. Request succeeds, session proceeds. 409 Note that the main differences between these two scenarios is that 410 the use of the SRV record allows the service configuration to account 411 for load balancing with tiers of fallback support and use of service 412 description information while the use of round robin A/AAAA records 413 does not. 415 4. HTTP Messages 417 JWB messages are exchanged as HTTP POST transactions. Support for 418 and use of HTTP/1.1 [RFC7230] is REQUIRED unless otherwise specified 419 by the Web Service Specification. 421 While the use of HTTP/2 [RFC7540] offers the potential benefit of 422 multiple concurrent transaction streams, the means of making use of 423 such capabilities is outside the scope of JWB v1.0 but is likely to 424 be the main incentive for defining a revision. 426 In contrast to other approaches to the design of Web Services, the 427 only use made of the HTTP transport is to distinguish between 428 different services on the same host using the Host header and .well- 429 known convention and for message framing. 431 No use is made of the URI request line to identify commands, nor are 432 the caching or proxy capabilities of HTTP relied on. One of the main 433 design objectives of JWB is to enable message level authentication. 434 Since HTTP headers are mutable and may be changed by intermediaries, 435 any attempt to make use of HTTP features requires a mechanism to 436 canonicalize or duplicate the headers. Furthermore, the 437 implementation of authentication and encryption features at the 438 message level is liable to be incompatible with the HTTP caching 439 model and any attempt to implement caching is moot when TLS is in 440 use. 442 4.1. Request 444 The HTTP request MAY contain any valid HTTP header specified in 445 [RFC7230] . 447 Request Line URI /well-known/ (unless overridden using a 448 TXT path attribute) 450 Request Line Method POST 452 Host: Header 454 Content-Encoding As specified in section yy below. 456 Content-Type As specified in section zz below. 458 Content-Length or Transfer-Encoding As specified in [RFC7230] . 460 Payload The content payload as specified in section XX below. 462 Example: The HTTP request for the mmm service in the previous example 463 would be: 465 POST /.well-known/mmm HTTP/1.1 466 Host: example.com 467 Content-Type: application/json 468 Content-Length: 16 470 { ?hello? : {} } 472 Figure 5 474 4.2. Response 476 The response MAY contain any HTTP response header but since JWB 477 services do not make use of HTTP caching and messages are not 478 intended to be modified by HTTP intermediaries, only a limited number 479 of headers have significance: 481 Response Code The HTTP response code. This is processed as 482 described in section zz below. 484 Content-Type As specified in section zz below. 486 Content-Length or Transfer-Encoding As specified in [RFC7230] . 488 Cache-Control Since the only valid HTTP method for a JWB request is 489 POST, JWB responses are not cacheable. The use of the cache- 490 control header is therefore unnecessary. However, experience 491 suggests that reviewers find it easier to understand protocol 492 specifications if they are reminded of the fact that caching is 493 neither supported nor desired. 495 Example: The HTTP response for the mmm service in the previous 496 example would be: 498 HTTP/1.1 200 OK 499 Content-Type: application/json 500 Connection: keep-alive 501 Cache-Control: no-store 502 Content-Length: 43 504 { ?hello-response? : { ?Version? : ?1.0? }} 506 Figure 6 508 5. Error handling and response codes 510 A JWB Web Service is effectively using a three layer protocol stack 511 with the potential for an error to occur at any of the three layers: 513 Transport Layer 515 HTTP Layer 517 Web Service Layer 519 Services SHOULD always attempt to return error codes at the highest 520 level possible. However, it is clearly impossible for a connection 521 that is refused at the Transport layer to return an error code at the 522 HTTP layer. It is however possible for a HTTP layer error response 523 to contain a content body. 525 In the case that a JWB response contains both a HTTP response code 526 and a well formed JWB payload containing a response, the JWB payload 527 response SHALL have precedence. 529 6. Content Encoding 531 The HTTP Content-Encoding header specifies transformations performed 532 on the content before the HTTP Transfer encoding was applied. This 533 is commonly used for specifying compression. In JWB the Content- 534 Encoding header MAY be used to specify that the content that follows 535 contains a payload that is either authenticated [RFC7515] or 536 authenticated and encrypted [RFC7516] using the JOSE specification. 538 6.1. Direct Encoding 540 If the Content-Encoding header is absent or empty, the HTTP content 541 is the message payload as specified by the Content-Type header. 543 6.2. Content-Encoding: jose-jwb 545 The Content-Encoding type jose-jwb is a serialization format for JSON 546 Web Signature and JSON Web Encryption objects. Each message consists 547 of the following sequence: 549 Preamble: A JSON object in UTF-8 encoding 551 ASCII Record Separator Character (%x1E) 553 Payload 555 ASCII Record Separator Character (%x1E) 557 Postscript: A JSON object in UTF-8 encoding 559 The payload data consists of all the data that appears between the 560 first and the last occurrence of the record separator character %x1E 561 in the HTTP content. Since the UTF-8 encoding does not permit the 562 octet %0x1E to occur within a well formed JSON object, the use of 563 this character as a record separator is unambiguous even if the 564 character occurs within the payload (as is possible with a binary 565 content-type or if the payload is encrypted). 567 The contents of the Preamble, Payload and Postscript vary according 568 to whether the message is authenticated or authenticated and 569 encrypted. 571 6.3. Authenticated 573 Authenticated messages are signed using Jose Web Signature [RFC7515] 574 . The Preamble, Payload and Postscript are formed as follows: 576 Preamble A JSON Object containing the JWS Protected Header 578 Payload The binary data over which the signature value is calculated 580 Postscript The JWS Signature header 582 Note that a jose-jwb message is only permitted to have a single 583 header and there is no provision for providing data that is not 584 integrity protected. 586 6.4. Authenticated Encryption 588 Encrypted messages are signed using Jose Web Signature [RFC7516] . 589 The Preamble, Payload and Postscript are formed as follows: 591 Preamble A JSON Object containing the JWS Protected Header 593 Payload The binary data over which the signature value is calculated 595 Postscript The JWS Encryption header 597 Note that a jose-jwb message is only permitted to have a single 598 header and there is no provision for providing data that is not 599 integrity protected. 601 7. Content Type 603 The Content Type header specifies the plaintext payload media type as 604 specified in [RFC6838] . 606 For version1.0 of this specification, the only supported payload 607 media type is application/json as specified in [RFC7159] . 609 Future versions of this specification may include support for binary 610 encodings such as JSON-B [draft-hallambaker-jsonbcd] and/or CBOR 611 [RFC7049] . 613 8. JSON Data Bindings 615 Note that this is the only part of this specification that is 616 strictly limited to JSON encoding. The rest of the specification is 617 equally applicable to Web Services using XML and/or CBOR encoding. 619 8.1. Request Message 621 Each JWBv1.0 request contains exactly one Web Service Command. 622 [Future versions MAY specify a mechanism that permits multiple 623 commands to be sent in parallel] 625 The request payload contains a JSON object that contains exactly one 626 member whose name is the name of the command that is requested and 627 whose value is an object that contains the command parameters (if 628 any). 630 { ?hello? : {} } 632 Figure 7 634 8.2. Response Message 636 The response payload contains a JSON object that contains the members 637 specified by the Web Service specification. 639 Future versions of this specification MAY reserve particular fields 640 in the response payload for particular purposes (e.g. returning 641 status values). 643 { ?hello-response? : { ?Version? : ?1.0? }} 645 Figure 8 647 8.3. Data Fields 649 JSON was originally developed to provide a serialization format for 650 the JavaScript programming language [ECMA-262] . While this approach 651 is generally applicable to the type systems of scripting programming 652 languages, it is less well matched to the richer type systems of 653 modern object oriented programming languages such as Java and C#. 655 Working within a subset of the capabilities of JSON allows a Web 656 Service protocol to be accessed with equal ease from either platform 657 type. The following capabilities of JSON are avoided: 659 The ability to use arbitrary strings as field names. 661 The use of JSON objects to define maps directly 663 The following data field types are used: 665 Integer Integer values are encoded as JSON number values. 667 String Test strings are encoded as JSON text strings. 669 Boolean Boolean values are encoded as JSON ?false?, ?true? or ?null? 670 tokens according to value. 672 Sequence Sequences of data items that are encoded as JSON arrays 674 Object of known type Objects whose type is known to the receiver are 675 encoded as JSON objects 677 Object of variable type Objects whose type is not known to the 678 receiver are encoded as JSON objects containing a single field 679 whose name describes the type of the object value and whose value 680 contains the value. 682 Binary Data Byte sequences are converted to BASE64-url encoding 683 [RFC4648] and encoded as JSON string values. 685 Date Time Date Time values are converted to Internet time format as 686 described in [RFC3339] and encoded as JSON string values. 688 9. Security Considerations 690 A fuller treatment of the security considerations will follow. 692 9.1. Integrity 694 9.1.1. DNS Spoofing 696 9.1.2. TLS Downgrade 698 9.1.3. TLS Service Impersonation 700 9.1.4. Request Replay Attack 702 9.1.5. Response Replay Attack 704 9.2. Confidentiality 706 9.2.1. Side Channel Attack 708 9.2.2. Session Key Leakage 710 10. IANA Considerations 712 The following registrations are required: 714 HTTP Content Coding Registry jose-jwb 715 Well-Known URIs /.well-known/srv/ 717 [Or change registry to FCFS] 719 11. References 721 11.1. Normative References 723 [draft-hallambaker-mesh-architecture] 724 Hallam-Baker, P., "Mathematical Mesh: Architecture", 725 draft-hallambaker-mesh-architecture-03 (work in progress), 726 May 2017. 728 [RFC1035] Mockapetris, P., "Domain names - implementation and 729 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 730 November 1987. 732 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 733 specifying the location of services (DNS SRV)", RFC 2782, 734 DOI 10.17487/RFC2782, February 2000. 736 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 737 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. 739 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 740 Resource Identifier (URI): Generic Syntax", STD 66, 741 RFC 3986, DOI 10.17487/RFC3986, January 2005. 743 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 744 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006. 746 [RFC5264] Niemi, A., Lonnfors, M., and E. Leppanen, "Publication of 747 Partial Presence Information", RFC 5264, 748 DOI 10.17487/RFC5264, September 2008. 750 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 751 Uniform Resource Identifiers (URIs)", RFC 5785, 752 DOI 10.17487/RFC5785, April 2010. 754 [RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service 755 Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013. 757 [RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type 758 Specifications and Registration Procedures", BCP 13, 759 RFC 6838, DOI 10.17487/RFC6838, January 2013. 761 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 762 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 763 2014. 765 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 766 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 767 DOI 10.17487/RFC7230, June 2014. 769 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 770 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 771 2015. 773 [RFC7516] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 774 RFC 7516, DOI 10.17487/RFC7516, May 2015. 776 11.2. Informative References 778 [draft-hallambaker-jsonbcd] 779 Hallam-Baker, P., "Binary Encodings for JavaScript Object 780 Notation: JSON-B, JSON-C, JSON-D", draft-hallambaker- 781 jsonbcd-08 (work in progress), September 2017. 783 [draft-hallambaker-mesh-developer] 784 Hallam-Baker, P., "Mathematical Mesh: Reference 785 Implementation", draft-hallambaker-mesh-developer-04 (work 786 in progress), September 2017. 788 [ECMA-262] 789 Ecma International, "ECMAScript? 2017 Language 790 Specification", June 2017. 792 [RFC5322] Resnick, P., "Internet Message Format", RFC 5322, 793 DOI 10.17487/RFC5322, October 2008. 795 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 796 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 797 October 2013. 799 [RFC7540] Belshe, M., Peon, R., and M. Thomson, "Hypertext Transfer 800 Protocol Version 2 (HTTP/2)", RFC 7540, 801 DOI 10.17487/RFC7540, May 2015. 803 11.3. URIs 805 [1] http://prismproof.org/Documents/draft-hallambaker-json-web- 806 service.html 808 [2] http://prismproof.org/Documents/draft-hallambaker-json-web- 809 service.html 811 Author's Address 813 Phillip Hallam-Baker 814 Comodo Group Inc. 816 Email: philliph@comodo.com