DNS Stateful Operations
draft-ietf-dnsop-session-signal-10
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft that was ultimately published as RFC 8490.
|
|
|---|---|---|---|
| Authors | Ray Bellis , Stuart Cheshire , John Dickinson , Sara Dickinson , Ted Lemon , Tom Pusateri | ||
| Last updated | 2018-06-25 (Latest revision 2018-06-07) | ||
| Replaces | draft-bellis-dnsop-session-signal | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews |
GENART Telechat review
(of
-11)
by Joel Halpern
Ready w/nits
GENART Last Call review
by Joel Halpern
Ready w/issues
|
||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | Submitted to IESG for Publication | |
| Document shepherd | Tim Wicinski | ||
| Shepherd write-up | Show Last changed 2018-05-15 | ||
| IESG | IESG state | Became RFC 8490 (Proposed Standard) | |
| Consensus boilerplate | Yes | ||
| Telechat date | (None) | ||
| Responsible AD | Warren "Ace" Kumari | ||
| Send notices to | "Tim Wicinski" <tjw.ietf@gmail.com> | ||
| IANA | IANA review state | IANA OK - Actions Needed |
draft-ietf-dnsop-session-signal-10
DNSOP Working Group R. Bellis
Internet-Draft ISC
Updates: 1035, 7766 (if approved) S. Cheshire
Intended status: Standards Track Apple Inc.
Expires: December 9, 2018 J. Dickinson
S. Dickinson
Sinodun
T. Lemon
Barefoot Consulting
T. Pusateri
Unaffiliated
June 07, 2018
DNS Stateful Operations
draft-ietf-dnsop-session-signal-10
Abstract
This document defines a new DNS OPCODE for DNS Stateful Operations
(DSO). DSO messages communicate operations within persistent
stateful sessions, using type-length-value (TLV) syntax. Three TLVs
are defined that manage session timeouts, termination, and encryption
padding, and a framework is defined for extensions to enable new
stateful operations. This document updates RFC 1035 by adding a new
DNS header opcode and result code which has different message
semantics. This document updates RFC 7766 by redefining a session,
providing new guidance on connection re-use, and providing a new
mechanism for handling session idle timeouts.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 9, 2018.
Bellis, et al. Expires December 9, 2018 [Page 1]
Internet-Draft DNS Stateful Operations June 2018
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Requirements Language . . . . . . . . . . . . . . . . . . . . 5
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Protocol Details . . . . . . . . . . . . . . . . . . . . . . 10
5.1. DSO Session Establishment . . . . . . . . . . . . . . . . 10
5.1.1. Connection Sharing . . . . . . . . . . . . . . . . . 12
5.1.2. Zero Round-Trip Operation . . . . . . . . . . . . . . 12
5.1.3. Middlebox Considerations . . . . . . . . . . . . . . 13
5.2. Message Format . . . . . . . . . . . . . . . . . . . . . 14
5.2.1. DNS Header Fields in DSO Messages . . . . . . . . . . 15
5.2.2. DSO Data . . . . . . . . . . . . . . . . . . . . . . 17
5.2.3. EDNS(0) and TSIG . . . . . . . . . . . . . . . . . . 22
5.3. Message Handling . . . . . . . . . . . . . . . . . . . . 23
5.3.1. Error Responses . . . . . . . . . . . . . . . . . . . 24
5.4. DSO Response Generation . . . . . . . . . . . . . . . . . 25
5.5. Responder-Initiated Operation Cancellation . . . . . . . 26
6. DSO Session Lifecycle and Timers . . . . . . . . . . . . . . 27
6.1. DSO Session Initiation . . . . . . . . . . . . . . . . . 27
6.2. DSO Session Timeouts . . . . . . . . . . . . . . . . . . 27
6.3. Inactive DSO Sessions . . . . . . . . . . . . . . . . . . 28
6.4. The Inactivity Timeout . . . . . . . . . . . . . . . . . 29
6.4.1. Closing Inactive DSO Sessions . . . . . . . . . . . . 29
6.4.2. Values for the Inactivity Timeout . . . . . . . . . . 30
6.5. The Keepalive Interval . . . . . . . . . . . . . . . . . 31
6.5.1. Keepalive Interval Expiry . . . . . . . . . . . . . . 31
6.5.2. Values for the Keepalive Interval . . . . . . . . . . 31
6.6. Server-Initiated Session Termination . . . . . . . . . . 33
6.6.1. Server-Initiated Retry Delay Message . . . . . . . . 34
7. Base TLVs for DNS Stateful Operations . . . . . . . . . . . . 37
7.1. Keepalive TLV . . . . . . . . . . . . . . . . . . . . . . 37
Bellis, et al. Expires December 9, 2018 [Page 2]
Internet-Draft DNS Stateful Operations June 2018
7.1.1. Client handling of received Session Timeout values . 39
7.1.2. Relation to EDNS(0) TCP Keepalive Option . . . . . . 41
7.2. Retry Delay TLV . . . . . . . . . . . . . . . . . . . . . 42
7.2.1. Retry Delay TLV used as a Primary TLV . . . . . . . . 42
7.2.2. Retry Delay TLV used as a Response Additional TLV . . 44
7.3. Encryption Padding TLV . . . . . . . . . . . . . . . . . 44
8. Summary Highlights . . . . . . . . . . . . . . . . . . . . . 45
8.1. QR bit and MESSAGE ID . . . . . . . . . . . . . . . . . . 45
8.2. TLV Usage . . . . . . . . . . . . . . . . . . . . . . . . 46
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
9.1. DSO OPCODE Registration . . . . . . . . . . . . . . . . . 48
9.2. DSO RCODE Registration . . . . . . . . . . . . . . . . . 48
9.3. DSO Type Code Registry . . . . . . . . . . . . . . . . . 48
10. Security Considerations . . . . . . . . . . . . . . . . . . . 49
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 49
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
12.1. Normative References . . . . . . . . . . . . . . . . . . 50
12.2. Informative References . . . . . . . . . . . . . . . . . 51
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52
1. Introduction
The use of transports for DNS other than UDP is being increasingly
specified, for example, DNS over TCP [RFC1035] [RFC7766] and DNS over
TLS [RFC7858]. Such transports can offer persistent, long-lived
sessions and therefore when using them for transporting DNS messages
it is of benefit to have a mechanism that can establish parameters
associated with those sessions, such as timeouts. In such situations
it is also advantageous to support server-initiated messages.
The existing EDNS(0) Extension Mechanism for DNS [RFC6891] is
explicitly defined to only have "per-message" semantics. While
EDNS(0) has been used to signal at least one session-related
parameter (the EDNS(0) TCP Keepalive option [RFC7828]) the result is
less than optimal due to the restrictions imposed by the EDNS(0)
semantics and the lack of server-initiated signalling. For example,
a server cannot arbitrarily instruct a client to close a connection
because the server can only send EDNS(0) options in responses to
queries that contained EDNS(0) options.
This document defines a new DNS OPCODE, DSO ([TBA1], tentatively 6),
for DNS Stateful Operations. DSO messages are used to communicate
operations within persistent stateful sessions, expressed using type-
length-value (TLV) syntax. This document defines an initial set of
three TLVs, used to manage session timeouts, termination, and
encryption padding.
Bellis, et al. Expires December 9, 2018 [Page 3]
Internet-Draft DNS Stateful Operations June 2018
The three TLVs defined here are all mandatory for all implementations
of DSO. Further TLVs may be defined in additional specifications.
The format for DSO messages (Section 5.2) differs somewhat from the
traditional DNS message format used for standard queries and
responses. The standard twelve-byte header is used, but the four
count fields (QDCOUNT, ANCOUNT, NSCOUNT, ARCOUNT) are set to zero and
accordingly their corresponding sections are not present. The actual
data pertaining to DNS Stateful Operations (expressed in TLV syntax)
is appended to the end of the DNS message header. When displayed
using packet analyzer tools that have not been updated to recognize
the DSO format, this will result in the DSO data being displayed as
unknown additional data after the end of the DNS message. It is
likely that future updates to these tools will add the ability to
recognize, decode, and display the DSO data.
This new format has distinct advantages over an RR-based format
because it is more explicit and more compact. Each TLV definition is
specific to its use case, and as a result contains no redundant or
overloaded fields. Importantly, it completely avoids conflating DNS
Stateful Operations in any way with normal DNS operations or with
existing EDNS(0)-based functionality. A goal of this approach is to
avoid the operational issues that have befallen EDNS(0), particularly
relating to middlebox behaviour.
With EDNS(0), multiple options may be packed into a single OPT
pseudo-RR, and there is no generalized mechanism for a client to be
able to tell whether a server has processed or otherwise acted upon
each individual option within the combined OPT pseudo-RR. The
specifications for each individual option need to define how each
different option is to be acknowledged, if necessary.
In contrast to EDNS(0), with DSO there is no compelling motivation to
pack multiple operations into a single message for efficiency
reasons, because DSO always operates using a connection-oriented
transport protocol. Each DSO operation is communicated in its own
separate DNS message, and the transport protocol can take care of
packing several DNS messages into a single IP packet if appropriate.
For example, TCP can pack multiple small DNS messages into a single
TCP segment. This simplification allows for clearer semantics. Each
DSO request message communicates just one primary operation, and the
RCODE in the corresponding response message indicates the success or
failure of that operation.
Bellis, et al. Expires December 9, 2018 [Page 4]
Internet-Draft DNS Stateful Operations June 2018
2. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Terminology
"DSO" is used to mean DNS Stateful Operation.
The term "connection" means a bidirectional byte (or message) stream,
where the bytes (or messages) are delivered reliably and in-order,
such as provided by using DNS over TCP [RFC1035] [RFC7766] or DNS
over TLS [RFC7858].
The unqualified term "session" in the context of this document means
the exchange of DNS messages over a connection where:
o The connection between client and server is persistent and
relatively long-lived (i.e., minutes or hours, rather than
seconds).
o Either end of the connection may initiate messages to the other.
In this document the term "session" is used exclusively as described
above. The term has no relationship to the "session layer" of the
OSI "seven-layer model".
A "DSO Session" is established between two endpoints that acknowledge
persistent DNS state via the exchange of DSO messages over the
connection. This is distinct from a DNS-over-TCP session as
described in the previous specification for DNS over TCP [RFC7766].
A "DSO Session" is terminated when the underlying connection is
closed. The underlying connection can be closed in two ways:
Where this specification says, "close gracefully," that means sending
a TLS close_notify (if TLS is in use) followed by a TCP FIN, or the
equivalents for other protocols. Where this specification requires a
connection to be closed gracefully, the requirement to initiate that
graceful close is placed on the client, to place the burden of TCP's
TIME-WAIT state on the client rather than the server.
Where this specification says, "forcibly abort," that means sending a
TCP RST, or the equivalent for other protocols. In the BSD Sockets
Bellis, et al. Expires December 9, 2018 [Page 5]
Internet-Draft DNS Stateful Operations June 2018
API this is achieved by setting the SO_LINGER option to zero before
closing the socket.
The term "server" means the software with a listening socket,
awaiting incoming connection requests.
The term "client" means the software which initiates a connection to
the server's listening socket.
The terms "initiator" and "responder" correspond respectively to the
initial sender and subsequent receiver of a DSO request message or
unacknowledged message, regardless of which was the "client" and
"server" in the usual DNS sense.
The term "sender" may apply to either an initiator (when sending a
DSO request message or unacknowledged message) or a responder (when
sending a DSO response message).
Likewise, the term "receiver" may apply to either a responder (when
receiving a DSO request message or unacknowledged message) or an
initiator (when receiving a DSO response message).
In protocol implementation there are generally two kinds of errors
that software writers have to deal with. The first is situations
that arise due to factors in the environment, such as temporary loss
of connectivity. While undesirable, these situations do not indicate
a flaw in the software, and they are situations that software should
generally be able to recover from. The second is situations that
should never happen when communicating with a correctly-implemented
peer. If they do happen, they indicate a serious flaw in the
protocol implementation, beyond what it is reasonable to expect
software to recover from. This document describes this latter form
of error condition as a "fatal error" and specifies that an
implementation encountering a fatal error condition "MUST forcibly
abort the connection immediately". Given that these fatal error
conditions signify defective software, and given that defective
software is likely to remain defective for some time until it is
fixed, after forcibly aborting a connection, a client SHOULD refrain
from automatically reconnecting to that same service instance for at
least one hour.
This document uses the term "same service instance" as follows:
o In cases where a server is specified or configured using an IP
address and TCP port number, two different configurations are
referring to the same service instance if they contain the same IP
address and TCP port number.
Bellis, et al. Expires December 9, 2018 [Page 6]
Internet-Draft DNS Stateful Operations June 2018
o In cases where a server is specified or configured using a
hostname and TCP port number, such as in the content of a DNS SRV
record [RFC2782], two different configurations (or DNS SRV
records) are considered to be referring to the same service
instance if they contain the same hostname (subject to the usual
case insensitive DNS name matching rules [RFC1034] [RFC1035]) and
TCP port number. In these cases, configurations with different
hostnames are considered to be referring to different service
instances, even if those different hostnames happen to be aliases,
or happen to resolve to the same IP address(es). Implementations
SHOULD NOT resolve hostnames and then perform matching of IP
address(es) in order to evaluate whether two entities should be
determined to be the "same service instance".
When an anycast service is configured on a particular IP address and
port, it must be the case that although there is more than one
physical server responding on that IP address, each such server can
be treated as equivalent. If a change in network topology causes
packets in a particular TCP connection to be sent to an anycast
server instance that does not know about the connection, the normal
keepalive and TCP connection timeout process will allow for recovery.
If after the connection is, the client's assumption that it is
connected to the same service is violated in some way, that would be
considered to be incorrect behavior in this context. It is however
out of the possible scope for this specification to make specific
recommendations in this regard; that would be up to follow-on
documents that describe specific uses of DNS stateful operations.
The term "long-lived operations" refers to operations such as Push
Notification subscriptions [I-D.ietf-dnssd-push], Discovery Relay
interface subscriptions [I-D.ietf-dnssd-mdns-relay], and other future
long-lived DNS operations that choose to use DSO as their basis.
These operations establish state that persists beyond the lifetime of
a traditional brief request/response transaction. This document, the
base specification for DNS Stateful Operations, defines a framework
for supporting long-lived operations, but does not itself define any
long-lived operations. Nonetheless, to appreciate the design
rationale behind DNS Stateful Operations, it is helpful to understand
the kind of long-lived operations that it is intended to support.
DNS Stateful Operations uses three kinds of message: "DSO request
messages", "DSO response messages", and "DSO unacknowledged
messages". A DSO request message elicits a DSO response message.
DSO unacknowledged messages are unidirectional messages and do not
generate any response.
Both DSO request messages and DSO unacknowledged messages are
formatted as DNS request messages (the header QR bit is set to zero,
Bellis, et al. Expires December 9, 2018 [Page 7]
Internet-Draft DNS Stateful Operations June 2018
as described in Section 5.2). One difference is that in DSO request
messages the MESSAGE ID field is nonzero; in DSO unacknowledged
messages it is zero.
The content of DSO messages is expressed using type-length-value
(TLV) syntax.
In a DSO request message or DSO unacknowledged message the first TLV
is referred to as the "Primary TLV" and determines the nature of the
operation being performed, including whether it is an acknowledged or
unacknowledged operation; any other TLVs in a DSO request message or
unacknowledged message are referred to as "Additional TLVs" and serve
additional non-primary purposes, which may be related to the primary
purpose, or not, as in the case of the encryption padding TLV.
A DSO response message may contain no TLVs, or it may contain one or
more TLVs as appropriate to the information being communicated. In
the context of DSO response messages, one or more TLVs with the same
DSO-TYPE as the Primary TLV in the corresponding DSO request message
are referred to as "Response Primary TLVs". Any other TLVs with
different DSO-TYPEs are referred to as "Response Additional TLVs".
The Response Primary TLV(s), if present, MUST occur first in the
response message, before any Response Additional TLVs.
Two timers (elapsed time since an event) are defined in this
document:
o an inactivity timer (see Section 6.4 and Section 7.1)
o a keepalive timer (see Section 6.5 and Section 7.1)
The timeouts associated with these timers are called the inactivity
timeout and the keepalive interval, respectively. The term "Session
Timeouts" is used to refer to this pair of timeout values.
Resetting a timer means resetting the timer value to zero and
starting the timer again. Clearing a timer means resetting the timer
value to zero but NOT starting the timer again.
Bellis, et al. Expires December 9, 2018 [Page 8]
Internet-Draft DNS Stateful Operations June 2018
4. Discussion
There are several use cases for DNS Stateful operations that can be
described here.
Firstly, establishing session parameters such as server-defined
timeouts is of great use in the general management of persistent
connections. For example, using DSO sessions for stub-to-recursive
DNS-over-TLS [RFC7858] is more flexible for both the client and the
server than attempting to manage sessions using just the EDNS(0) TCP
Keepalive option [RFC7828]. The simple set of TLVs defined in this
document is sufficient to greatly enhance connection management for
this use case.
Secondly, DNS-SD [RFC6763] has evolved into a naturally session-based
mechanism where, for example, long-lived subscriptions lend
themselves to 'push' mechanisms as opposed to polling. Long-lived
stateful connections and server-initiated messages align with this
use case [I-D.ietf-dnssd-push].
A general use case is that DNS traffic is often bursty but session
establishment can be expensive. One challenge with long-lived
connections is to maintain sufficient traffic to maintain NAT and
firewall state. To mitigate this issue this document introduces a
new concept for the DNS, that is DSO "Keepalive traffic". This
traffic carries no DNS data and is not considered 'activity' in the
classic DNS sense, but serves to maintain state in middleboxes, and
to assure client and server that they still have connectivity to each
other.
Bellis, et al. Expires December 9, 2018 [Page 9]
Internet-Draft DNS Stateful Operations June 2018
5. Protocol Details
5.1. DSO Session Establishment
DSO messages MUST be carried in only protocols and in environments
where a session may be established according to the definition given
above in the Terminology section (Section 3).
DNS over plain UDP [RFC0768] is not appropriate since it fails on the
requirement for in-order message delivery, and, in the presence of
NAT gateways and firewalls with short UDP timeouts, it fails to
provide a persistent bi-directional communication channel unless an
excessive amount of keepalive traffic is used.
At the time of publication, DSO is specified only for DNS over TCP
[RFC1035] [RFC7766], and for DNS over TLS over TCP [RFC7858]. Any
use of DSO over some other connection technology needs to be
specified in an appropriate future document.
Determining whether a given connection is using DNS over TCP, or DNS
over TLS over TCP, is outside the scope of this specification, and
must be determined using some out-of-band configuration information.
There is no provision within the DSO specification to turn TLS on or
off during the lifetime of a connection. For service types where the
service instance is discovered using a DNS SRV record [RFC2782], the
specification for that service type SRV name [RFC6335] will state
whether the connection uses plain TCP, or TLS over TCP. For example,
the specification for the "_dns-push-tls._tcp" service
[I-D.ietf-dnssd-push], states that it uses TLS. It is a common
convention that protocols specified to run over TLS are given IANA
service type names ending in "-tls".
In some environments it may be known in advance by external means
that both client and server support DSO, and in these cases either
client or server may initiate DSO messages at any time.
However, in the typical case a server will not know in advance
whether a client supports DSO, so in general, unless it is known in
advance by other means that a client does support DSO, a server MUST
NOT initiate DSO request messages or DSO unacknowledged messages
until a DSO Session has been mutually established by at least one
successful DSO request/response exchange initiated by the client, as
described below. Similarly, unless it is known in advance by other
means that a server does support DSO, a client MUST NOT initiate DSO
unacknowledged messages until after a DSO Session has been mutually
established.
Bellis, et al. Expires December 9, 2018 [Page 10]
Internet-Draft DNS Stateful Operations June 2018
A DSO Session is established over a connection by the client sending
a DSO request message, such as a DSO Keepalive request message
(Section 7.1), and receiving a response, with matching MESSAGE ID,
and RCODE set to NOERROR (0), indicating that the DSO request was
successful.
If the RCODE in the response is set to DSOTYPENI ("DSO-TYPE Not
Implemented", [TBA2] tentatively RCODE 11) this indicates that the
server does support DSO, but does not implement the DSO-TYPE of the
primary TLV in this DSO request message. A server implementing DSO
MUST NOT return DSOTYPENI for a DSO Keepalive request message,
because the Keepalive TLV is mandatory to implement. But in the
future, if a client attempts to establish a DSO Session using a
response-requiring DSO request message using some newly-defined DSO-
TYPE that the server does not understand, that would result in a
DSOTYPENI response. If the server returns DSOTYPENI then a DSO
Session is not considered established, but the client is permitted to
continue sending DNS messages on the connection, including other DSO
messages such as the DSO Keepalive, which may result in a successful
NOERROR response, yielding the establishment of a DSO Session.
If the RCODE is set to any value other than NOERROR (0) or DSOTYPENI
([TBA2] tentatively 11), then the client MUST assume that the server
does not implement DSO at all. In this case the client is permitted
to continue sending DNS messages on that connection, but the client
SHOULD NOT issue further DSO messages on that connection.
When the server receives a DSO request message from a client, and
transmits a successful NOERROR response to that request, the server
considers the DSO Session established.
When the client receives the server's NOERROR response to its DSO
request message, the client considers the DSO Session established.
Once a DSO Session has been established, either end may unilaterally
send appropriate DSO messages at any time, and therefore either
client or server may be the initiator of a message.
Once a DSO Session has been established, clients and servers should
behave as described in this specification with regard to inactivity
timeouts and session termination, not as previously prescribed in the
earlier specification for DNS over TCP [RFC7766].
Note that for clients that implement only the DSO-TYPEs defined in
this base specification, sending a DSO Keepalive TLV is the only DSO
request message they have available to initiate a DSO Session. Even
for clients that do implement other future DSO-TYPEs, for simplicity
they MAY elect to always send an initial DSO Keepalive request
Bellis, et al. Expires December 9, 2018 [Page 11]
Internet-Draft DNS Stateful Operations June 2018
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1. Conventions Used in this Document . . . . . . . . . . . . 5
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. JSON Web Key Examples . . . . . . . . . . . . . . . . . . . . 6
3.1. EC Public Key . . . . . . . . . . . . . . . . . . . . . . 6
3.2. EC Private Key . . . . . . . . . . . . . . . . . . . . . 7
3.3. RSA Public Key . . . . . . . . . . . . . . . . . . . . . 7
3.4. RSA Private Key . . . . . . . . . . . . . . . . . . . . . 8
3.5. Octet Key (MAC Computation) . . . . . . . . . . . . . . . 10
3.6. Octet Key (Encryption) . . . . . . . . . . . . . . . . . 10
4. JSON Web Signature Examples . . . . . . . . . . . . . . . . . 11
4.1. RSA v1.5 Signature . . . . . . . . . . . . . . . . . . . 11
4.1.1. Input Factors . . . . . . . . . . . . . . . . . . . . 12
4.1.2. Signing Operation . . . . . . . . . . . . . . . . . . 12
4.1.3. Output Results . . . . . . . . . . . . . . . . . . . 13
4.2. RSA-PSS Signature . . . . . . . . . . . . . . . . . . . . 15
4.2.1. Input Factors . . . . . . . . . . . . . . . . . . . . 15
4.2.2. Signing Operation . . . . . . . . . . . . . . . . . . 15
4.2.3. Output Results . . . . . . . . . . . . . . . . . . . 16
4.3. ECDSA Signature . . . . . . . . . . . . . . . . . . . . . 18
4.3.1. Input Factors . . . . . . . . . . . . . . . . . . . . 18
4.3.2. Signing Operation . . . . . . . . . . . . . . . . . . 18
4.3.3. Output Results . . . . . . . . . . . . . . . . . . . 19
4.4. HMAC-SHA2 Integrity Protection . . . . . . . . . . . . . 21
4.4.1. Input Factors . . . . . . . . . . . . . . . . . . . . 21
4.4.2. Signing Operation . . . . . . . . . . . . . . . . . . 21
4.4.3. Output Results . . . . . . . . . . . . . . . . . . . 22
4.5. Signature with Detached Content . . . . . . . . . . . . . 24
4.5.1. Input Factors . . . . . . . . . . . . . . . . . . . . 24
4.5.2. Signing Operation . . . . . . . . . . . . . . . . . . 24
4.5.3. Output Results . . . . . . . . . . . . . . . . . . . 25
4.6. Protecting Specific Header Fields . . . . . . . . . . . . 26
4.6.1. Input Factors . . . . . . . . . . . . . . . . . . . . 26
4.6.2. Signing Operation . . . . . . . . . . . . . . . . . . 27
4.6.3. Output Results . . . . . . . . . . . . . . . . . . . 28
4.7. Protecting Content Only . . . . . . . . . . . . . . . . . 29
4.7.1. Input Factors . . . . . . . . . . . . . . . . . . . . 29
4.7.2. Signing Operation . . . . . . . . . . . . . . . . . . 29
4.7.3. Output Results . . . . . . . . . . . . . . . . . . . 30
4.8. Multiple Signatures . . . . . . . . . . . . . . . . . . . 31
4.8.1. Input Factors . . . . . . . . . . . . . . . . . . . . 32
4.8.2. First Signing Operation . . . . . . . . . . . . . . . 32
4.8.3. Second Signing Operation . . . . . . . . . . . . . . 34
Miller Expires May 17, 2015 [Page 2]
Internet-Draft JOSE Cookbook November 2014
4.8.4. Third Signing Operation . . . . . . . . . . . . . . . 35
4.8.5. Output Results . . . . . . . . . . . . . . . . . . . 36
5. JSON Web Encryption Examples . . . . . . . . . . . . . . . . 37
5.1. Key Encryption using RSA v1.5 and AES-HMAC-SHA2 . . . . . 38
5.1.1. Input Factors . . . . . . . . . . . . . . . . . . . . 38
5.1.2. Generated Factors . . . . . . . . . . . . . . . . . . 40
5.1.3. Encrypting the Key . . . . . . . . . . . . . . . . . 40
5.1.4. Encrypting the Content . . . . . . . . . . . . . . . 40
5.1.5. Output Results . . . . . . . . . . . . . . . . . . . 41
5.2. Key Encryption using RSA-OAEP with A256GCM . . . . . . . 44
5.2.1. Input Factors . . . . . . . . . . . . . . . . . . . . 44
5.2.2. Generated Factors . . . . . . . . . . . . . . . . . . 46
5.2.3. Encrypting the Key . . . . . . . . . . . . . . . . . 47
5.2.4. Encrypting the Content . . . . . . . . . . . . . . . 47
5.2.5. Output Results . . . . . . . . . . . . . . . . . . . 48
5.3. Key Wrap using PBES2-AES-KeyWrap with AES-CBC-HMAC-SHA2 . 51
5.3.1. Input Factors . . . . . . . . . . . . . . . . . . . . 51
5.3.2. Generated Factors . . . . . . . . . . . . . . . . . . 52
5.3.3. Encrypting the Key . . . . . . . . . . . . . . . . . 53
5.3.4. Encrypting the Content . . . . . . . . . . . . . . . 53
5.3.5. Output Results . . . . . . . . . . . . . . . . . . . 55
5.4. Key Agreement with Key Wrapping using ECDH-ES and AES-
KeyWrap with AES-GCM . . . . . . . . . . . . . . . . . . 57
5.4.1. Input Factors . . . . . . . . . . . . . . . . . . . . 57
5.4.2. Generated Factors . . . . . . . . . . . . . . . . . . 58
5.4.3. Encrypting the Key . . . . . . . . . . . . . . . . . 58
5.4.4. Encrypting the Content . . . . . . . . . . . . . . . 59
5.4.5. Output Results . . . . . . . . . . . . . . . . . . . 60
5.5. Key Agreement using ECDH-ES with AES-CBC-HMAC-SHA2 . . . 63
5.5.1. Input Factors . . . . . . . . . . . . . . . . . . . . 63
5.5.2. Generated Factors . . . . . . . . . . . . . . . . . . 64
5.5.3. Key Agreement . . . . . . . . . . . . . . . . . . . . 64
5.5.4. Encrypting the Content . . . . . . . . . . . . . . . 65
5.5.5. Output Results . . . . . . . . . . . . . . . . . . . 66
5.6. Direct Encryption using AES-GCM . . . . . . . . . . . . . 68
5.6.1. Input Factors . . . . . . . . . . . . . . . . . . . . 68
5.6.2. Generated Factors . . . . . . . . . . . . . . . . . . 68
5.6.3. Encrypting the Content . . . . . . . . . . . . . . . 68
5.6.4. Output Results . . . . . . . . . . . . . . . . . . . 70
5.7. Key Wrap using AES-GCM KeyWrap with AES-CBC-HMAC-SHA2 . . 71
5.7.1. Input Factors . . . . . . . . . . . . . . . . . . . . 71
5.7.2. Generated Factors . . . . . . . . . . . . . . . . . . 72
5.7.3. Encrypting the Key . . . . . . . . . . . . . . . . . 72
5.7.4. Encrypting the Content . . . . . . . . . . . . . . . 73
5.7.5. Output Results . . . . . . . . . . . . . . . . . . . 74
5.8. Key Wrap using AES-KeyWrap with AES-GCM . . . . . . . . . 76
5.8.1. Input Factors . . . . . . . . . . . . . . . . . . . . 76
5.8.2. Generated Factors . . . . . . . . . . . . . . . . . . 77
Miller Expires May 17, 2015 [Page 3]
Internet-Draft JOSE Cookbook November 2014
5.8.3. Encrypting the Key . . . . . . . . . . . . . . . . . 77
5.8.4. Encrypting the Content . . . . . . . . . . . . . . . 77
5.8.5. Output Results . . . . . . . . . . . . . . . . . . . 78
5.9. Compressed Content . . . . . . . . . . . . . . . . . . . 80
5.9.1. Input Factors . . . . . . . . . . . . . . . . . . . . 81
5.9.2. Generated Factors . . . . . . . . . . . . . . . . . . 81
5.9.3. Encrypting the Key . . . . . . . . . . . . . . . . . 82
5.9.4. Encrypting the Content . . . . . . . . . . . . . . . 82
5.9.5. Output Results . . . . . . . . . . . . . . . . . . . 83
5.10. Including Additional Authenticated Data . . . . . . . . . 84
5.10.1. Input Factors . . . . . . . . . . . . . . . . . . . 85
5.10.2. Generated Factors . . . . . . . . . . . . . . . . . 85
5.10.3. Encrypting the Key . . . . . . . . . . . . . . . . . 86
5.10.4. Encrypting the Content . . . . . . . . . . . . . . . 86
5.10.5. Output Results . . . . . . . . . . . . . . . . . . . 87
5.11. Protecting Specific Header Fields . . . . . . . . . . . . 89
5.11.1. Input Factors . . . . . . . . . . . . . . . . . . . 89
5.11.2. Generated Factors . . . . . . . . . . . . . . . . . 90
5.11.3. Encrypting the Key . . . . . . . . . . . . . . . . . 90
5.11.4. Encrypting the Content . . . . . . . . . . . . . . . 90
5.11.5. Output Results . . . . . . . . . . . . . . . . . . . 91
5.12. Protecting Content Only . . . . . . . . . . . . . . . . . 93
5.12.1. Input Factors . . . . . . . . . . . . . . . . . . . 93
5.12.2. Generated Factors . . . . . . . . . . . . . . . . . 93
5.12.3. Encrypting the Key . . . . . . . . . . . . . . . . . 94
5.12.4. Encrypting the Content . . . . . . . . . . . . . . . 94
5.12.5. Output Results . . . . . . . . . . . . . . . . . . . 95
5.13. Encrypting to Multiple Recipients . . . . . . . . . . . . 97
5.13.1. Input Factors . . . . . . . . . . . . . . . . . . . 97
5.13.2. Generated Factors . . . . . . . . . . . . . . . . . 97
5.13.3. Encrypting the Key to the First Recipient . . . . . 98
5.13.4. Encrypting the Key to the Second Recipient . . . . . 99
5.13.5. Encrypting the Key to the Third Recipient . . . . . 101
5.13.6. Encrypting the Content . . . . . . . . . . . . . . . 102
5.13.7. Output Results . . . . . . . . . . . . . . . . . . . 103
6. Nesting Signatures and Encryption . . . . . . . . . . . . . . 105
6.1. Signing Input Factors . . . . . . . . . . . . . . . . . . 105
6.2. Signing Operation . . . . . . . . . . . . . . . . . . . . 106
6.3. Signing Output . . . . . . . . . . . . . . . . . . . . . 107
6.4. Encryption Input Factors . . . . . . . . . . . . . . . . 108
6.5. Encryption Generated Factors . . . . . . . . . . . . . . 108
6.6. Encrypting the Key . . . . . . . . . . . . . . . . . . . 108
6.7. Encrypting the Content . . . . . . . . . . . . . . . . . 109
6.8. Encryption Output . . . . . . . . . . . . . . . . . . . . 110
7. Security Considerations . . . . . . . . . . . . . . . . . . . 113
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 114
9. Informative References . . . . . . . . . . . . . . . . . . . 114
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 115
Miller Expires May 17, 2015 [Page 4]
Internet-Draft JOSE Cookbook November 2014
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 115
1. Introduction
The JavaScript Object Signing and Encryption (JOSE) technologies -
JSON Web Signature (JWS) [I-D.ietf-jose-json-web-signature], JSON Web
Encryption (JWE) [I-D.ietf-jose-json-web-encryption], JSON Web Key
(JWK) [I-D.ietf-jose-json-web-key], and JSON Web Algorithms (JWA)
[I-D.ietf-jose-json-web-algorithms] - collectively can be used to
encrypt and/or sign content using a variety of algorithms. While the
full set of permutations is extremely large, and might be daunting to
some, it is expected that most applications will only use a small set
of algorithms to meet their needs.
This document provides a number of examples of signing or encrypting
content using JOSE. While not exhaustive, it does compile a
representative sample of JOSE features. As much as possible, the
same signature payload or encryption plaintext content is used to
illustrate differences in various signing and encryption results.
This document also provides a number of example JWK objects. These
examples illustrate the distinguishing properties of various key
types, and emphasize important characteristics. Most of the JWK
examples are then used in the signature or encryption examples that
follow.
1.1. Conventions Used in this Document
This document separates data that are expected to be input to an
implementation of JOSE from data that are expected to be generated by
an implementation of JOSE. Each example, wherever possible, provides
enough information to both replicate the results of this document or
to validate the results by running its inverse operation (e.g.,
signature results can be validated by performing the JWS verify).
However, some algorithms inherently use random data and therefore
computations employing them cannot be exactly replicated; such cases
are explicitly stated in the relevant sections.
All instances of binary octet strings are represented using [RFC4648]
base64url encoding.
Wherever possible and unless otherwise noted, the examples include
the Compact serialization, JSON General Serialization, and JSON
Flattened Serialization.
All of the examples in this document have whitespace added to improve
formatting and readability. Except for JWE plaintext or JWS payload
Miller Expires May 17, 2015 [Page 5]
Internet-Draft JOSE Cookbook November 2014
content, whitespace is not part of the cryptographic operations nor
the exchange results.
Unless otherwise noted, the JWE plaintext or JWS payload content does
include " " (U+0020 SPACE) characters. Line breaks (U+000A LINE
FEED) replace " " (U+0020 SPACE) characters to improve readability
but are not present in the JWE plaintext or JWS payload.
2. Terminology
This document inherits terminology regarding JSON Web Signature (JWS)
technology from [I-D.ietf-jose-json-web-signature], terminology
regarding JSON Web Encryption (JWE) technology from
[I-D.ietf-jose-json-web-encryption], terminology regarding JSON Web
Key (JWK) technology from [I-D.ietf-jose-json-web-key], and
terminology regarding algorithms from
[I-D.ietf-jose-json-web-algorithms].
3. JSON Web Key Examples
The following sections demonstrate how to represent various JWK and
JWK-set objects.
3.1. EC Public Key
This example illustrates an Elliptic Curve public key. This example
is the corollary to Figure 2.
Note that whitespace is added for readability as described in
Section 1.1.
{
"kty": "EC",
"kid": "bilbo.baggins@hobbiton.example",
"use": "sig",
"crv": "P-521",
"x": "AHKZLLOsCOzz5cY97ewNUajB957y-C-U88c3v13nmGZx6sYl_oJXu9
A5RkTKqjqvjyekWF-7ytDyRXYgCF5cj0Kt",
"y": "AdymlHvOiLxXkEhayXQnNCvDX4h9htZaCJN34kfmC6pV5OhQHiraVy
SsUdaQkAgDPrwQrJmbnX9cwlGfP-HqHZR1"
}
Figure 1: Elliptic Curve P-521 Public Key
The field "kty" value of "EC" identifies this as an elliptic curve
key. The field "crv" identifies the curve, which is curve P-521 for
this example. The fields "x" and "y" values are the base64url-
encoded X and Y coordinates (respectively).
Miller Expires May 17, 2015 [Page 6]
Internet-Draft JOSE Cookbook November 2014
The values of the fields "x" and "y" decoded are the octets necessary
to represent each full coordinate to the order of the curve. For a
key over curve P-521, the values of the fields "x" and "y" are
exactly 66 octets in length when decoded, padded with leading zero
(0x00) octets to reach the expected length.
3.2. EC Private Key
This example illustrates an Elliptic Curve private key. This example
is the progenitor to Figure 1.
Note that whitespace is added for readability as described in
Section 1.1.
{
"kty": "EC",
"kid": "bilbo.baggins@hobbiton.example",
"use": "sig",
"crv": "P-521",
"x": "AHKZLLOsCOzz5cY97ewNUajB957y-C-U88c3v13nmGZx6sYl_oJXu9
A5RkTKqjqvjyekWF-7ytDyRXYgCF5cj0Kt",
"y": "AdymlHvOiLxXkEhayXQnNCvDX4h9htZaCJN34kfmC6pV5OhQHiraVy
SsUdaQkAgDPrwQrJmbnX9cwlGfP-HqHZR1",
"d": "AAhRON2r9cqXX1hg-RoI6R1tX5p2rUAYdmpHZoC1XNM56KtscrX6zb
KipQrCW9CGZH3T4ubpnoTKLDYJ_fF3_rJt"
}
Figure 2: Elliptic Curve P-521 Private Key
The field "kty" value of "EC" identifies this as an elliptic curve
key. The field "crv" identifies the curve, which is curve P-521
(also known as SECG curve secp521r1) for this example. The fields
"x" and "y" values are the base64url-encoded X and Y coordiates
(respectively). The field "d" value is the base64url-encoded private
key.
The values of the fields "d", "x", and "y" decoded are the octets
necessary to represent the private key or each full coordinate
(respectively) to the order of the curve. For a key over curve
"P-521", the values of the "d", "x", and "y" fields are each exactly
66 octets in length when decoded, padded with leading zero (0x00)
octets to reach the expected length.
3.3. RSA Public Key
This example illustrates an RSA private key. This example is the
corollary to Figure 4.
Miller Expires May 17, 2015 [Page 7]
Internet-Draft JOSE Cookbook November 2014
Note that whitespace is added for readability as described in
Section 1.1.
{
"kty": "RSA",
"kid": "bilbo.baggins@hobbiton.example",
"use": "sig",
"n": "n4EPtAOCc9AlkeQHPzHStgAbgs7bTZLwUBZdR8_KuKPEHLd4rHVTeT
-O-XV2jRojdNhxJWTDvNd7nqQ0VEiZQHz_AJmSCpMaJMRBSFKrKb2wqV
wGU_NsYOYL-QtiWN2lbzcEe6XC0dApr5ydQLrHqkHHig3RBordaZ6Aj-
oBHqFEHYpPe7Tpe-OfVfHd1E6cS6M1FZcD1NNLYD5lFHpPI9bTwJlsde
3uhGqC0ZCuEHg8lhzwOHrtIQbS0FVbb9k3-tVTU4fg_3L_vniUFAKwuC
LqKnS2BYwdq_mzSnbLY7h_qixoR7jig3__kRhuaxwUkRz5iaiQkqgc5g
HdrNP5zw",
"e": "AQAB"
}
Figure 3: RSA 2048-bit Public Key
The field "kty" value of "RSA" identifies this as a RSA key. The
fields "n" and "e" values are the modulus and (public) exponent
(respectively) using the minimum octets necessary.
For a 2048-bit key, the field "n" value is 256 octets in length when
decoded.
3.4. RSA Private Key
This example illustrates an RSA private key. This example is the
progenitor to Figure 3.
Note that whitespace is added for readability as described in
Section 1.1.
Miller Expires May 17, 2015 [Page 8]
Internet-Draft JOSE Cookbook November 2014
{
"kty": "RSA",
"kid": "bilbo.baggins@hobbiton.example",
"use": "sig",
"n": "n4EPtAOCc9AlkeQHPzHStgAbgs7bTZLwUBZdR8_KuKPEHLd4rHVTeT
-O-XV2jRojdNhxJWTDvNd7nqQ0VEiZQHz_AJmSCpMaJMRBSFKrKb2wqV
wGU_NsYOYL-QtiWN2lbzcEe6XC0dApr5ydQLrHqkHHig3RBordaZ6Aj-
oBHqFEHYpPe7Tpe-OfVfHd1E6cS6M1FZcD1NNLYD5lFHpPI9bTwJlsde
3uhGqC0ZCuEHg8lhzwOHrtIQbS0FVbb9k3-tVTU4fg_3L_vniUFAKwuC
LqKnS2BYwdq_mzSnbLY7h_qixoR7jig3__kRhuaxwUkRz5iaiQkqgc5g
HdrNP5zw",
"e": "AQAB",
"d": "bWUC9B-EFRIo8kpGfh0ZuyGPvMNKvYWNtB_ikiH9k20eT-O1q_I78e
iZkpXxXQ0UTEs2LsNRS-8uJbvQ-A1irkwMSMkK1J3XTGgdrhCku9gRld
Y7sNA_AKZGh-Q661_42rINLRCe8W-nZ34ui_qOfkLnK9QWDDqpaIsA-b
MwWWSDFu2MUBYwkHTMEzLYGqOe04noqeq1hExBTHBOBdkMXiuFhUq1BU
6l-DqEiWxqg82sXt2h-LMnT3046AOYJoRioz75tSUQfGCshWTBnP5uDj
d18kKhyv07lhfSJdrPdM5Plyl21hsFf4L_mHCuoFau7gdsPfHPxxjVOc
OpBrQzwQ",
"p": "3Slxg_DwTXJcb6095RoXygQCAZ5RnAvZlno1yhHtnUex_fp7AZ_9nR
aO7HX_-SFfGQeutao2TDjDAWU4Vupk8rw9JR0AzZ0N2fvuIAmr_WCsmG
peNqQnev1T7IyEsnh8UMt-n5CafhkikzhEsrmndH6LxOrvRJlsPp6Zv8
bUq0k",
"q": "uKE2dh-cTf6ERF4k4e_jy78GfPYUIaUyoSSJuBzp3Cubk3OCqs6grT
8bR_cu0Dm1MZwWmtdqDyI95HrUeq3MP15vMMON8lHTeZu2lmKvwqW7an
V5UzhM1iZ7z4yMkuUwFWoBvyY898EXvRD-hdqRxHlSqAZ192zB3pVFJ0
s7pFc",
"dp": "B8PVvXkvJrj2L-GYQ7v3y9r6Kw5g9SahXBwsWUzp19TVlgI-YV85q
1NIb1rxQtD-IsXXR3-TanevuRPRt5OBOdiMGQp8pbt26gljYfKU_E9xn
-RULHz0-ed9E9gXLKD4VGngpz-PfQ_q29pk5xWHoJp009Qf1HvChixRX
59ehik",
"dq": &message as their way of initiating a DSO Session. A future
definition of a new response-requiring DSO-TYPE gives implementers
the option of using that new DSO-TYPE if they wish, but does not
change the fact that sending a DSO Keepalive TLV remains a valid way
of initiating a DSO Session.
5.1.1. Connection Sharing
As previously specified for DNS over TCP [RFC7766]:
To mitigate the risk of unintentional server overload, DNS
clients MUST take care to minimize the number of concurrent
TCP connections made to any individual server. It is RECOMMENDED
that for any given client/server interaction there SHOULD be
no more than one connection for regular queries, one for zone
transfers, and one for each protocol that is being used on top
of TCP (for example, if the resolver was using TLS). However,
it is noted that certain primary/secondary configurations
with many busy zones might need to use more than one TCP
connection for zone transfers for operational reasons (for
example, to support concurrent transfers of multiple zones).
A single server may support multiple services, including DNS Updates
[RFC2136], DNS Push Notifications [I-D.ietf-dnssd-push], and other
services, for one or more DNS zones. When a client discovers that
the target server for several different operations is the same target
hostname and port, the client SHOULD use a single shared DSO Session
for all those operations. A client SHOULD NOT open multiple
connections to the same target host and port just because the names
being operated on are different or happen to fall within different
zones. This requirement is to reduce unnecessary connection load on
the DNS server.
However, server implementers and operators should be aware that
connection sharing may not be possible in all cases. A single host
device may be home to multiple independent client software instances
that don't coordinate with each other. Similarly, multiple
independent client devices behind the same NAT gateway will also
typically appear to the DNS server as different source ports on the
same client IP address. Because of these constraints, a DNS server
MUST be prepared to accept multiple connections from different source
ports on the same client IP address.
5.1.2. Zero Round-Trip Operation
There is increased awareness today of the performance benefits of
eliminating round trips in session establishment. Technologies like
TCP Fast Open [RFC7413] and TLS 1.3 [I-D.ietf-tls-tls13] provide
Bellis, et al. Expires December 9, 2018 [Page 12]
Internet-Draft DNS Stateful Operations June 2018
mechanisms to reduce or eliminate round trips in session
establishment.
Similarly, DSO supports zero round-trip operation.
Having initiated a connection to a server, possibly using zero round-
trip TCP Fast Open and/or zero round-trip TLS 1.3, a client MAY send
multiple response-requiring DSO request messages to the server in
succession without having to wait for a response to the first request
message to confirm successful establishment of a DSO session.
However, a client MUST NOT send non-response-requiring DSO request
messages until after a DSO Session has been mutually established.
Similarly, a server MUST NOT send DSO request messages until it has
received a response-requiring DSO request message from a client and
transmitted a successful NOERROR response for that request.
Caution must be taken to ensure that DSO messages sent before the
first round-trip is completed are idempotent, or are otherwise immune
to any problems that could be result from the inadvertent replay that
can occur with zero round-trip operation.
5.1.3. Middlebox Considerations
Where an application-layer middlebox (e.g., a DNS proxy, forwarder,
or session multiplexer) is in the path, the middlebox MUST NOT
blindly forward DSO messages in either direction, and MUST treat the
inbound and outbound connections as separate sessions. This does not
preclude the use of DSO messages in the presence of an IP-layer
middlebox, such as a NAT that rewrites IP-layer and/or transport-
layer headers but otherwise preserves the effect of a single session
between the client and the server.
To illustrate the above, consider a network where a middlebox
terminates one or more TCP connections from clients and multiplexes
the queries therein over a single TCP connection to an upstream
server. The DSO messages and any associated state are specific to
the individual TCP connections. A DSO-aware middlebox MAY in some
circumstances be able to retain associated state and pass it between
the client and server (or vice versa) but this would be highly TLV-
specific. For example, the middlebox may be able to maintain a list
of which clients have made Push Notification subscriptions
[I-D.ietf-dnssd-push] and make its own subscription(s) on their
behalf, relaying any subsequent notifications to the client (or
clients) that have subscribed to that particular notification.
Bellis, et al. Expires December 9, 2018 [Page 13]
Internet-Draft DNS Stateful Operations June 2018
5.2. Message Format
A DSO message begins with the standard twelve-byte DNS message header
[RFC1035] with the OPCODE field set to the DSO OPCODE ([TBA1]
tentatively 6). However, unlike standard DNS messages, the question
section, answer section, authority records section and additional
records sections are not present. The corresponding count fields
(QDCOUNT, ANCOUNT, NSCOUNT, ARCOUNT) MUST be set to zero on
transmission.
If a DSO message is received where any of the count fields are not
zero, then a FORMERR MUST be returned, unless a future IETF Standard
specifies otherwise.
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| MESSAGE ID |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|QR | OPCODE | Z | RCODE |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| QDCOUNT (MUST be zero) |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| ANCOUNT (MUST be zero) |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| NSCOUNT (MUST be zero) |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| ARCOUNT (MUST be zero) |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| |
/ DSO Data /
/ /
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
Bellis, et al. Expires December 9, 2018 [Page 14]
Internet-Draft DNS Stateful Operations June 2018
5.2.1. DNS Header Fields in DSO Messages
In an unacknowledged message the MESSAGE ID field MUST be set to
zero. In an acknowledged request message the MESSAGE ID field MUST
be set to a unique nonzero value, that the initiator is not currently
using for any other active operation on this connection. For the
purposes here, a MESSAGE ID is in use in this DSO Session if the
initiator has used it in a request for which it is still awaiting a
response, or if the client has used it to set up a long-lived
operation that has not yet been cancelled. For example, a long-lived
operation could be a Push Notification subscription
[I-D.ietf-dnssd-push] or a Discovery Relay interface subscription
[I-D.ietf-dnssd-mdns-relay].
Whether a message is acknowledged or unacknowledged is determined
only by the specification for the Primary TLV. An acknowledgment
cannot be requested by including a nonzero message ID in a message
the primary TLV of which is specified to be unacknowledged, nor can
an acknowledgment be prevented by sending a message ID of zero in a
message with a primary TLV that is specified to be acknowledged. A
responder that receives either such malformed message MUST treat it
as a fatal error and forcibly abort the connection immediately.
In a request or unacknowledged message the DNS Header QR bit MUST be
zero (QR=0). If the QR bit is not zero the message is not a request
or unacknowledged message.
In a response message the DNS Header QR bit MUST be one (QR=1).
If the QR bit is not one the message is not a response message.
In a response message (QR=1) the MESSAGE ID field MUST contain a copy
of the value of the MESSAGE ID field in the request message being
responded to. In a response message (QR=1) the MESSAGE ID field MUST
NOT be zero. If a response message (QR=1) is received where the
MESSAGE ID is zero this is a fatal error and the recipient MUST
forcibly abort the connection immediately.
The DNS Header OPCODE field holds the DSO OPCODE value ([TBA1]
tentatively 6).
The Z bits are currently unused in DSO messages, and in both DSO
requests and DSO responses the Z bits MUST be set to zero (0) on
transmission and MUST be silently ignored on reception, unless a
future IETF Standard specifies otherwise.
Bellis, et al. Expires December 9, 2018 [Page 15]
Internet-Draft DNS Stateful Operations June 2018
In a DNS request message (QR=0) the RCODE is set according to the
definition of the request. For example, in a Retry Delay message
(Section 6.6.1) the RCODE indicates the reason for termination.
However, in most cases, except where clearly specified otherwise, in
a DNS request message (QR=0) the RCODE is set to zero on
transmission, and silently ignored on reception.
The RCODE value in a response message (QR=1) may be one of the
following values:
+---------+-----------+---------------------------------------------+
| Code | Mnemonic | Description |
+---------+-----------+---------------------------------------------+
| 0 | NOERROR | Operation processed successfully |
| | | |
| 1 | FORMERR | Format error |
| | | |
| 2 | SERVFAIL | Server failed to process request due to a |
| | | problem with the server |
| | | |
| 3 | NXDOMAIN | Name Error -- Named entity does not exist |
| | | (TLV-dependent) |
| | | |
| 4 | NOTIMP | DSO not supported |
| | | |
| 5 | REFUSED | Operation declined for policy reasons |
| | | |
| 9 | NOTAUTH | Not Authoritative (TLV-dependent) |
| | | |
| [TBA2] | DSOTYPENI | Primary TLV's DSO-Type is not implemented |
| 11 | | |
+---------+-----------+---------------------------------------------+
Use of the above RCODEs is likely to be common in DSO but does not
preclude the definition and use of other codes in future documents
that make use of DSO.
If a document defining a new DSO-TYPE makes use of NXDOMAIN (Name
Error) or NOTAUTH (Not Authoritative) then that document MUST specify
the specific interpretation of these RCODE values in the context of
that new DSO TLV.
Bellis, et al. Expires December 9, 2018 [Page 16]
Internet-Draft DNS Stateful Operations June 2018
5.2.2. DSO Data
The standard twelve-byte DNS message header with its zero-valued
count fields is followed by the DSO Data, expressed using TLV syntax,
as described below Section 5.2.2.1.
A DSO message may be a request message, a response message, or an
unacknowledged message.
A DSO request message or DSO unacknowledged message MUST contain at
least one TLV. The first TLV in a DSO request message or DSO
unacknowledged message is referred to as the "Primary TLV" and
determines the nature of the operation being performed, including
whether it is an acknowledged or unacknowledged operation. In some
cases it may be appropriate to include other TLVs in a request
message or unacknowledged message, such as the Encryption Padding TLV
(Section 7.3), and these extra TLVs are referred to as the
"Additional TLVs".
A DSO response message may contain no TLVs, or it may be specified to
contain one or more TLVs appropriate to the information being
communicated.
A DSO response message may contain one or more TLVs with DSO-TYPE the
same as the Primary TLV from the corresponding DSO request message,
in which case those TLV(s) are referred to as "Response Primary
TLVs". A DSO response message is not required to carry Response
Primary TLVs. The MESSAGE ID field in the DNS message header is
sufficient to identify the DSO request message to which this response
message relates.
A DSO response message may contain one or more TLVs with DSO-TYPEs
different from the Primary TLV from the corresponding DSO request
message, in which case those TLV(s) are referred to as "Response
Additional TLVs".
Response Primary TLV(s), if present, MUST occur first in the response
message, before any Response Additional TLVs.
It is anticipated that most DSO operations will be specified to use
request messages, which generate corresponding responses. In some
specialized high-traffic use cases, it may be appropriate to specify
unacknowledged messages. Unacknowledged messages can be more
efficient on the network, because they don't generate a stream of
corresponding reply messages. Using unacknowledged messages can also
simplify software in some cases, by removing need for an initiator to
maintain state while it waits to receive replies it doesn't care
about. When the specification for a particular TLV states that, when
Bellis, et al. Expires December 9, 2018 [Page 17]
Internet-Draft DNS Stateful Operations June 2018
used as a Primary TLV (i.e., first) in an outgoing DNS request
message (i.e., QR=0), that message is to be unacknowledged, the
MESSAGE ID field MUST be set to zero and the receiver MUST NOT
generate any response message corresponding to this unacknowledged
message.
The previous point, that the receiver MUST NOT generate responses to
unacknowledged messages, applies even in the case of errors. When a
DSO message is received where both the QR bit and the MESSAGE ID
field are zero, the receiver MUST NOT generate any response. For
example, if the DSO-TYPE in the Primary TLV is unrecognized, then a
DSOTYPENI error MUST NOT be returned; instead the receiver MUST
forcibly abort the connection immediately.
Unacknowledged messages MUST NOT be used "speculatively" in cases
where the sender doesn't know if the receiver supports the Primary
TLV in the message, because there is no way to receive any response
to indicate success or failure of the request message (the request
message does not contain a unique MESSAGE ID with which to associate
a response with its corresponding request). Unacknowledged messages
are only appropriate in cases where the sender already knows that the
receiver supports, and wishes to receive, these messages.
For example, after a client has subscribed for Push Notifications
[I-D.ietf-dnssd-push], the subsequent event notifications are then
sent as unacknowledged messages, and this is appropriate because the
client initiated the message stream by virtue of its Push
Notification subscription, thereby indicating its support of Push
Notifications, and its desire to receive those notifications.
Similarly, after an Discovery Relay client has subscribed to receive
inbound mDNS (multicast DNS, [RFC6762]) traffic from an Discovery
Relay, the subsequent stream of received packets is then sent using
unacknowledged messages, and this is appropriate because the client
initiated the message stream by virtue of its Discovery Relay link
subscription, thereby indicating its support of Discovery Relay, and
its desire to receive inbound mDNS packets over that DSO session
[I-D.ietf-dnssd-mdns-relay].
Bellis, et al. Expires December 9, 2018 [Page 18]
Internet-Draft DNS Stateful Operations June 2018
5.2.2.1. TLV Syntax
All TLVs, whether used as "Primary", "Additional", "Response
Primary", or "Response Additional", use the same encoding syntax.
The specification for a TLV states whether that DSO-TYPE may be used
in "Primary", "Additional", "Response Primary", or "Response
Additional" TLVs. The specification for a TLV also states whether,
when used as the Primary (i.e., first) TLV in a DNS request message
(i.e., QR=0), that DSO message is to be acknowledged. If the DSO
message is to be acknowledged, the specification also states which
TLVs, if any, are to be included in the response. The Primary TLV
may or may not be contained in the response, depending on what is
stated in the specification for that TLV.
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| DSO-TYPE |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| DSO-LENGTH |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| |
/ DSO-DATA /
/ /
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
DSO-TYPE: A 16-bit unsigned integer, in network (big endian) byte
order, giving the DSO-TYPE of the current DSO TLV per the IANA DSO
Type Code Registry.
DSO-LENGTH: A 16-bit unsigned integer, in network (big endian) byte
order, giving the size in bytes of the DSO-DATA.
DSO-DATA: Type-code specific format. The generic DSO machinery
treats the DSO-DATA as an opaque "blob" without attempting to
interpret it. Interpretation of the meaning of the DSO-DATA for a
particular DSO-TYPE is the responsibility of the software that
implements that DSO-TYPE.
Bellis, et al. Expires December 9, 2018 [Page 19]
Internet-Draft DNS Stateful Operations June 2018
5.2.2.2. Request TLVs
The first TLV in a DSO request message or unacknowledged message is
the "Primary TLV" and indicates the operation to be performed. A DSO
request message or unacknowledged message MUST contain at at least
one TLV, the Primary TLV.
Immediately following the Primary TLV, a DSO request message or
unacknowledged message MAY contain one or more "Additional TLVs",
which specify additional parameters relating to the operation.
5.2.2.3. Response TLVs
Depending on the operation, a DSO response message MAY contain no
TLVs, because it is simply a response to a previous request message,
and the MESSAGE ID in the header is sufficient to identify the
request in question. Or it may contain a single response TLV, with
the same DSO-TYPE as the Primary TLV in the request message.
Alternatively it may contain one or more TLVs of other types, or a
combination of the above, as appropriate for the information that
needs to be communicated. The specification for each DSO TLV
determines what TLVs are required in a response to a request using
that TLV.
If a DSO response is received for an operation where the
specification requires that the response carry a particular TLV or
TLVs, and the required TLV(s) are not present, then this is a fatal
error and the recipient of the defective response message MUST
forcibly abort the connection immediately.
Bellis, et al. Expires December 9, 2018 [Page 20]
Internet-Draft DNS Stateful Operations June 2018
5.2.2.4. Unrecognized TLVs
If DSO request message is received containing an unrecognized Primary
TLV, with a nonzero MESSAGE ID (indicating that a response is
expected), then the receiver MUST send an error response with
matching MESSAGE ID, and RCODE DSOTYPENI ([TBA2] tentatively 11).
The error response MUST NOT contain a copy of the unrecognized
Primary TLV.
If DSO unacknowledged message is received containing an unrecognized
Primary TLV, with a zero MESSAGE ID (indicating that no response is
expected), then this is a fatal error and the recipient MUST forcibly
abort the connection immediately.
If a DSO request message or unacknowledged message is received where
the Primary TLV is recognized, containing one or more unrecognized
Additional TLVs, the unrecognized Additional TLVs MUST be silently
ignored, and the remainder of the message is interpreted and handled
as if the unrecognized parts were not present.
Similarly, if a DSO response message is received containing one or
more unrecognized TLVs, the unrecognized TLVs MUST be silently
ignored, and the remainder of the message is interpreted and handled
as if the unrecognized parts were not present.
Bellis, et al. Expires December 9, 2018 [Page 21]
Internet-Draft DNS Stateful Operations June 2018
5.2.3. EDNS(0) and TSIG
Since the ARCOUNT field MUST be zero, a DSO message MUST NOT contain
an EDNS(0) option in the additional records section. If
functionality provided by current or future EDNS(0) options is
desired for DSO messages, one or more new DSO TLVs need to be defined
to carry the necessary information.
For example, the EDNS(0) Padding Option [RFC7830] used for security
purposes is not permitted in a DSO message, so if message padding is
desired for DSO messages then the Encryption Padding TLV described in
Section 7.3 MUST be used.
Similarly, a DSO message MUST NOT contain a TSIG record. A TSIG
record in a conventional DNS message is added as the last record in
the additional records section, and carries a signature computed over
the preceding message content. Since DSO data appears *after* the
additional records section, it would not be included in the signature
calculation. If use of signatures with DSO messages becomes
necessary in the future, a new DSO TLV needs to be defined to perform
this function.
Note however that, while DSO *messages* cannot include EDNS(0) or
TSIG records, a DSO *session* is typically used to carry a whole
series of DNS messages of different kinds, including DSO messages,
and other DNS message types like Query [RFC1034] [RFC1035] and Update
[RFC2136], and those messages can carry EDNS(0) and TSIG records.
Although messages may contain other EDNS(0) options as appropriate,
this specification explicitly prohibits use of the EDNS(0) TCP
Keepalive Option [RFC7828] in *any* messages sent on a DSO Session
(because it is obsoleted by the functionality provided by the DSO
Keepalive operation). If any message sent on a DSO Session contains
an EDNS(0) TCP Keepalive Option this is a fatal error and the
recipient of the defective message MUST forcibly abort the connection
immediately.
Bellis, et al. Expires December 9, 2018 [Page 22]
Internet-Draft DNS Stateful Operations June 2018
5.3. Message Handling
The initiator MUST set the value of the QR bit in the DNS header to
zero (0), and the responder MUST set it to one (1).
As described above in Section 5.2.1 whether an outgoing message with
QR=0 is unacknowledged or acknowledged is determined by the
specification for the Primary TLV, which in turn determines whether
the MESSAGE ID field in that outgoing message will be zero or
nonzero.
A DSO unacknowledged message has both the QR bit and the MESSAGE ID
field set to zero, and MUST NOT elicit a response.
Every DSO request message (QR=0) with a nonzero MESSAGE ID field is
an acknowledged DSO request, and MUST elicit a corresponding response
(QR=1), which MUST have the same MESSAGE ID in the DNS message header
as in the corresponding request.
Valid DSO request messages sent by the client with a nonzero MESSAGE
ID field elicit a response from the server, and Valid DSO request
messages sent by the server with a nonzero MESSAGE ID field elicit a
response from the client.
The namespaces of 16-bit MESSAGE IDs are independent in each
direction. This means it is *not* an error for both client and
server to send request messages at the same time as each other, using
the same MESSAGE ID, in different directions. This simplification is
necessary in order for the protocol to be implementable. It would be
infeasible to require the client and server to coordinate with each
other regarding allocation of new unique MESSAGE IDs. It is also not
necessary to require the client and server to coordinate with each
other regarding allocation of new unique MESSAGE IDs. The value of
the 16-bit MESSAGE ID combined with the identity of the initiator
(client or server) is sufficient to unambiguously identify the
operation in question. This can be thought of as a 17-bit message
identifier space, using message identifiers 0x00001-0x0FFFF for
client-to-server DSO request messages, and message identifiers
0x10001-0x1FFFF for server-to-client DSO request messages. The
least-significant 16 bits are stored explicitly in the MESSAGE ID
field of the DSO message, and the most-significant bit is implicit
from the direction of the message.
As described above in Section 5.2.1, an initiator MUST NOT reuse a
MESSAGE ID that it already has in use for an outstanding request
(unless specified otherwise by the relevant specification for the
DSO-TYPE in question). At the very least, this means that a MESSAGE
ID MUST NOT be reused in a particular direction on a particular DSO
Bellis, et al. Expires December 9, 2018 [Page 23]
Internet-Draft DNS Stateful Operations June 2018
Session while the initiator is waiting for a response to a previous
request using that MESSAGE ID on that DSO Session (unless specified
otherwise by the relevant specification for the DSO-TYPE in
question), and for a long-lived operation the MESSAGE ID for the
operation MUST NOT be reused while that operation remains active.
If a client or server receives a response (QR=1) where the MESSAGE ID
is zero, or is any other value that does not match the MESSAGE ID of
any of its outstanding operations, this is a fatal error and the
recipient MUST forcibly abort the connection immediately.
5.3.1. Error Responses
When a DSO unacknowledged message is unsuccessful for some reason,
the responder immediately aborts the connection.
When a DSO request message is unsuccessful for some reason, the
responder returns an error code to the initiator.
In the case of a server returning an error code to a client in
response to an unsuccessful DSO request message, the server MAY
choose to end the DSO Session, or MAY choose to allow the DSO Session
to remain open. For error conditions that only affect the single
operation in question, the server SHOULD return an error response to
the client and leave the DSO Session open for further operations.
For error conditions that are likely to make all operations
unsuccessful in the immediate future, the server SHOULD return an
error response to the client and then end the DSO Session by sending
a Retry Delay message, as described in Section 6.6.1.
Upon receiving an error response from the server, a client SHOULD NOT
automatically close the DSO Session. An error relating to one
particular operation on a DSO Session does not necessarily imply that
all other operations on that DSO Session have also failed, or that
future operations will fail. The client should assume that the
server will make its own decision about whether or not to end the DSO
Session, based on the server's determination of whether the error
condition pertains to this particular operation, or would also apply
to any subsequent operations. If the server does not end the DSO
Session by sending the client a Retry Delay message (Section 6.6.1)
then the client SHOULD continue to use that DSO Session for
subsequent operations.
Bellis, et al. Expires December 9, 2018 [Page 24]
Internet-Draft DNS Stateful Operations June 2018
5.4. DSO Response Generation
With most TCP implementations, for DSO requests that generate a
response, the TCP data acknowledgement (generated because data has
been received by TCP), the TCP window update (generated because TCP
has delivered that data to the receiving software), and the DSO
response (generated by the receiving application-layer software
itself) are all combined into a single IP packet. Combining these
three elements into a single IP packet can give a significant
improvement in network efficiency.
For DSO requests that do not generate a response, the TCP
implementation generally doesn't have any way to know that no
response will be forthcoming, so it waits fruitlessly for the
application-layer software to generate a response, until the Delayed
ACK timer fires [RFC1122] (typically 200 milliseconds) and only then
does it send the TCP ACK and window update. In conjunction with
Nagle's Algorithm at the sender, this can delay the sender's
transmission of its next (non-full-sized) TCP segment, while the
sender is waiting for its previous (non-full-sized) TCP segment to be
acknowledged, which won't happen until the Delayed ACK timer fires.
Nagle's Algorithm exists to combine multiple small application writes
into more-efficient large TCP segments, to guard against wasteful use
of the network by applications that would otherwise transmit a stream
of small TCP segments, but in this case Nagle's Algorithm (created to
improve network efficiency) can interact badly with TCP's Delayed ACK
feature (also created to improve network efficiency) [NagleDA] with
the result of delaying some messages by up to 200 milliseconds.
Possible mitigations for this problem include:
o Disable Nagle's Algorithm at the sender. This is not great,
because it results in less efficient use of the network.
o Disable Delayed ACK at the receiver. This is not great,
because it results in less efficient use of the network.
o Adding padding data to fill the segment. This is not great,
because it uses additional bandwidth.
o Use a networking API that lets the receiver signal to the TCP
implementation that the receiver has received and processed a
client request for which it will not be generating any immediate
response. This allows the TCP implementation to operate
efficiently in both cases; for requests that generate a response,
the TCP ACK, window update, and DSO response are transmitted
together in a single TCP segment, and for requests that do not
generate a response, the application-layer software informs the
Bellis, et al. Expires December 9, 2018 [Page 25]
Internet-Draft DNS Stateful Operations June 2018
TCP implementation that it should go ahead and send the TCP ACK
and window update immediately, without waiting for the Delayed ACK
timer. Unfortunately it is not known at this time which (if any)
of the widely-available networking APIs currently include this
capability.
5.5. Responder-Initiated Operation Cancellation
This document, the base specification for DNS Stateful Operations,
does not itself define any long-lived operations, but it defines a
framework for supporting long-lived operations, such as Push
Notification subscriptions [I-D.ietf-dnssd-push] and Discovery Relay
interface subscriptions [I-D.ietf-dnssd-mdns-relay].
Generally speaking, a long-lived operation is initiated by the
initiator, and, if successful, remains active until the initiator
terminates the operation.
However, it is possible that a long-lived operation may be valid at
the time it was initiated, but then a later change of circumstances
may render that previously valid operation invalid.
For example, a long-lived client operation may pertain to a name that
the server is authoritative for, but then the server configuration is
changed such that it is no longer authoritative for that name.
In such cases, instead of terminating the entire session it may be
desirable for the responder to be able to cancel selectively only
those operations that have become invalid.
The responder performs this selective cancellation by sending a new
response message, with the MESSAGE ID field containing the MESSAGE ID
of the long-lived operation that is to be terminated (that it had
previously acknowledged with a NOERROR RCODE), and the RCODE field of
the new response message giving the reason for cancellation.
After a response message with nonzero RCODE has been sent, that
operation has been terminated from the responder's point of view, and
the responder sends no more messages relating to that operation.
After a response message with nonzero RCODE has been received by the
initiator, that operation has been terminated from the initiator's
point of view, and the cancelled operation's MESSAGE ID is now free
for reuse.
Bellis, et al. Expires December 9, 2018 [Page 26]
Internet-Draft DNS Stateful Operations June 2018
6. DSO Session Lifecycle and Timers
6.1. DSO Session Initiation
A DSO Session begins as described in Section 5.1.
The client may perform as many DNS operations as it wishes using the
newly created DSO Session. Operations SHOULD be pipelined (i.e., the
client doesn't need wait for a response before sending the next
message). The server MUST act on messages in the order they are
transmitted, but responses to those messages SHOULD be sent out of
order when appropriate.
6.2. DSO Session Timeouts
Two timeout values are associated with a DSO Session: the inactivity
timeout, and the keepalive interval. Both values are communicated in
the same TLV, the DSO Keepalive TLV (Section 7.1).
The first timeout value, the inactivity timeout, is the maximum time
for which a client may speculatively keep a DSO Session open in the
expectation that it may have future requests to send to that server.
The second timeout value, the keepalive interval, is the maximum
permitted interval between messages if the client wishes to keep the
DSO Session alive.
The two timeout values are independent. The inactivity timeout may
be lower, the same, or higher than the keepalive interval, though in
most cases the inactivity timeout is expected to be shorter than the
keepalive interval.
A shorter inactivity timeout with a longer keepalive interval signals
to the client that it should not speculatively keep an inactive DSO
Session open for very long without reason, but when it does have an
active reason to keep a DSO Session open, it doesn't need to be
sending an aggressive level of keepalive traffic to maintain that
session.
A longer inactivity timeout with a shorter keepalive interval signals
to the client that it may speculatively keep an inactive DSO Session
open for a long time, but to maintain that inactive DSO Session it
should be sending a lot of keepalive traffic. This configuration is
expected to be less common.
In the usual case where the inactivity timeout is shorter than the
keepalive interval, it is only when a client has a very long-lived,
low-traffic, operation that the keepalive interval comes into play,
Bellis, et al. Expires December 9, 2018 [Page 27]
Internet-Draft DNS Stateful Operations June 2018
to ensure that a sufficient residual amount of traffic is generated
to maintain NAT and firewall state and to assure client and server
that they still have connectivity to each other.
On a new DSO Session, if no explicit DSO Keepalive message exchange
has taken place, the default value for both timeouts is 15 seconds.
For both timeouts, lower values of the timeout result in higher
network traffic and higher CPU load on the server.
6.3. Inactive DSO Sessions
At both servers and clients, the generation or reception of any
complete DNS message, including DNS requests, responses, updates, or
DSO messages, resets both timers for that DSO Session, with the
exception that a DSO Keepalive message resets only the keepalive
timer, not the inactivity timeout timer.
In addition, for as long as the client has an outstanding operation
in progress, the inactivity timer remains cleared, and an inactivity
timeout cannot occur.
For short-lived DNS operations like traditional queries and updates,
an operation is considered in progress for the time between request
and response, typically a period of a few hundred milliseconds at
most. At the client, the inactivity timer is cleared upon
transmission of a request and remains cleared until reception of the
corresponding response. At the server, the inactivity timer is
cleared upon reception of a request and remains cleared until
transmission of the corresponding response.
For long-lived DNS Stateful operations (such as a Push Notification
subscription [I-D.ietf-dnssd-push] or a Discovery Relay interface
subscription [I-D.ietf-dnssd-mdns-relay]), an operation is considered
in progress for as long as the operation is active, until it is
cancelled. This means that a DSO Session can exist, with active
operations, with no messages flowing in either direction, for far
longer than the inactivity timeout, and this is not an error. This
is why there are two separate timers: the inactivity timeout, and the
keepalive interval. Just because a DSO Session has no traffic for an
extended period of time does not automatically make that DSO Session
"inactive", if it has an active operation that is awaiting events.
Bellis, et al. Expires December 9, 2018 [Page 28]
Internet-Draft DNS Stateful Operations June 2018
quot;CLDmDGduhylc9o7r84rEUVn7pzQ6PF83Y-iBZx5NT-TpnOZKF1pEr
AMVeKzFEl41DlHHqqBLSM0W1sOFbwTxYWZDm6sI6og5iTbwQGIC3gnJK
bi_7k_vJgGHwHxgPaX2PnvP-zyEkDERuf-ry4c_Z11Cq9AqC2yeL6kdK
T1cYF8",
"qi": "3PiqvXQN0zwMeE-sBvZgi289XP9XCQF3VWqPzMKnIgQp7_Tugo6-N
ZBKCQsMf3HaEGBjTVJs_jcK8-TRXvaKe-7ZMaQj8VfBdYkssbu0NKDDh
jJ-GtiseaDVWt7dcH0cfwxgFUHpQh7FoCrjFJ6h6ZEpMF6xmujs4qMpP
z8aaI4"
}
Figure 4: RSA 2048-bit Private Key
The field "kty" value of "RSA" identifies this as a RSA key. The
fields "n" and "e" values are the base64url-encoded modulus and
(public) exponent (respectively) using the minimum number of octets
necessary. The field "d" value is the base64url-encoded private
exponent using the minimum number of octets necessary. The fields
Miller Expires May 17, 2015 [Page 9]
Internet-Draft JOSE Cookbook November 2014
"p", "q", "dp", "dq", and "qi" are the base64url-encoded additional
private information using the minimum number of octets necessary.
For a 2048-bit key, the fields "n" and "d" values are 256 octets in
length when decoded.
3.5. Octet Key (MAC Computation)
This example illustrates a symmetric octet key used for computing
MACs.
Note that whitespace is added for readability as described in
Section 1.1.
{
"kty": "oct",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037",
"use": "sig",
"alg": "HS256",
"k": "hJtXIZ2uSN5kbQfbtTNWbpdmhkV8FJG-Onbc6mxCcYg"
}
Figure 5: AES 256-bit symmetric signing key
The field "kty" value of "oct" identifies this as a symmetric key.
The field "k" value is the symmetric key.
When used for the signing algorithm "HS256" (HMAC-SHA256), the field
"k" value is 32 octets (or more) in length when decoded, padded with
leading zero (0x00) octets to reach the minimum expected length.
3.6. Octet Key (Encryption)
This example illustrates a symmetric octet key used for encryption.
Note that whitespace is added for readability as described in
Section 1.1.
{
"kty": "oct",
"kid": "1e571774-2e08-40da-8308-e8d68773842d",
"use": "enc",
"alg": "A256GCM",
"k": "AAPapAv4LbFbiVawEjagUBluYqN5rhna-8nuldDvOx8"
}
Figure 6: AES 256-bit symmetric encryption key
Miller Expires May 17, 2015 [Page 10]
Internet-Draft JOSE Cookbook November 2014
The field "kty" value of "oct" identifies this as a symmetric key.
The field "k" value is the symmetric key.
For the content encryption algorithm "A256GCM", the field "k" value
is exactly 32 octets in length when decoded, padded with leading zero
(0x00) octets to reach the expected length.
4. JSON Web Signature Examples
The following sections demonstrate how to generate various JWS
objects.
All of the succeeding examples use the following payload plaintext
(an abridged quote from "The Fellowship of the Ring"
[LOTR-FELLOWSHIP]), serialized as UTF-8. The sequence "\xe2\x80\x99"
is substituted for (U+2019 RIGHT SINGLE QUOTATION MARK), and line
breaks (U+000A LINE FEED) replace some instances " " (U+0020 SPACE)
to improve readability:
It\xe2\x80\x99s a dangerous business, Frodo, going out your
door. You step onto the road, and if you don't keep your feet,
there\xe2\x80\x99s no knowing where you might be swept off
to.
Figure 7: Payload content plaintext
The Payload - with the sequence "\xe2\x80\x99" replaced with (U+2019
RIGHT SINGLE QUOTATION MARK) and line breaks (U+000A LINE FEED)
replaced with " " (U+0020 SPACE) - encoded as UTF-8 then as [RFC4648]
base64url:
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 8: Payload content, base64url-encoded
4.1. RSA v1.5 Signature
This example illustrates signing content using the "RS256" (RSASSA-
PKCS1-v1_5 with SHA-256) algorithm.
Note that whitespace is added for readability as described in
Section 1.1.
Miller Expires May 17, 2015 [Page 11]
Internet-Draft JOSE Cookbook November 2014
4.1.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o RSA private key; this example uses the key from Figure 4.
o "alg" parameter of "RS256".
4.1.2. Signing Operation
The following are generated to complete the signing operation:
o JWS Protected Header; this example uses the header from Figure 9,
encoded using [RFC4648] base64url to produce Figure 10.
{
"alg": "RS256",
"kid": "bilbo.baggins@hobbiton.example"
}
Figure 9: JWS Protected Header JSON
eyJhbGciOiJSUzI1NiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
Figure 10: JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 10) and Payload content (Figure 8)
are combined as described in section 5.1 of
[I-D.ietf-jose-json-web-signature] to produce the JWS Signing Input
Figure 11.
eyJhbGciOiJSUzI1NiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 11: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 11) produces the JWS Signature (Figure 12).
Miller Expires May 17, 2015 [Page 12]
Internet-Draft JOSE Cookbook November 2014
MRjdkly7_-oTPTS3AXP41iQIGKa80A0ZmTuV5MEaHoxnW2e5CZ5NlKtainoFmK
ZopdHM1O2U4mwzJdQx996ivp83xuglII7PNDi84wnB-BDkoBwA78185hX-Es4J
IwmDLJK3lfWRa-XtL0RnltuYv746iYTh_qHRD68BNt1uSNCrUCTJDt5aAE6x8w
W1Kt9eRo4QPocSadnHXFxnt8Is9UzpERV0ePPQdLuW3IS_de3xyIrDaLGdjluP
xUAhb6L2aXic1U12podGU0KLUQSE_oI-ZnmKJ3F4uOZDnd6QZWJushZ41Axf_f
cIe8u9ipH84ogoree7vjbU5y18kDquDg
Figure 12: JWS Signature, base64url-encoded
4.1.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 9)
o Payload content (Figure 8)
o Signature (Figure 12)
The resulting JWS object using the Compact serialization:
eyJhbGciOiJSUzI1NiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
.
MRjdkly7_-oTPTS3AXP41iQIGKa80A0ZmTuV5MEaHoxnW2e5CZ5NlKtainoFmK
ZopdHM1O2U4mwzJdQx996ivp83xuglII7PNDi84wnB-BDkoBwA78185hX-Es4J
IwmDLJK3lfWRa-XtL0RnltuYv746iYTh_qHRD68BNt1uSNCrUCTJDt5aAE6x8w
W1Kt9eRo4QPocSadnHXFxnt8Is9UzpERV0ePPQdLuW3IS_de3xyIrDaLGdjluP
xUAhb6L2aXic1U12podGU0KLUQSE_oI-ZnmKJ3F4uOZDnd6QZWJushZ41Axf_f
cIe8u9ipH84ogoree7vjbU5y18kDquDg
Figure 13: Compact Serialization
The resulting JWS object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 13]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImJpbGJvLmJhZ2
dpbnNAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "MRjdkly7_-oTPTS3AXP41iQIGKa80A0ZmTuV5MEaHo
xnW2e5CZ5NlKtainoFmKZopdHM1O2U4mwzJdQx996ivp83xuglII
7PNDi84wnB-BDkoBwA78185hX-Es4JIwmDLJK3lfWRa-XtL0Rnlt
uYv746iYTh_qHRD68BNt1uSNCrUCTJDt5aAE6x8wW1Kt9eRo4QPo
cSadnHXFxnt8Is9UzpERV0ePPQdLuW3IS_de3xyIrDaLGdjluPxU
Ahb6L2aXic1U12podGU0KLUQSE_oI-ZnmKJ3F4uOZDnd6QZWJush
Z41Axf_fcIe8u9ipH84ogoree7vjbU5y18kDquDg"
}
]
}
Figure 14: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"protected": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImJpbGJvLmJhZ2dpbn
NAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "MRjdkly7_-oTPTS3AXP41iQIGKa80A0ZmTuV5MEaHoxnW2
e5CZ5NlKtainoFmKZopdHM1O2U4mwzJdQx996ivp83xuglII7PNDi84w
nB-BDkoBwA78185hX-Es4JIwmDLJK3lfWRa-XtL0RnltuYv746iYTh_q
HRD68BNt1uSNCrUCTJDt5aAE6x8wW1Kt9eRo4QPocSadnHXFxnt8Is9U
zpERV0ePPQdLuW3IS_de3xyIrDaLGdjluPxUAhb6L2aXic1U12podGU0
KLUQSE_oI-ZnmKJ3F4uOZDnd6QZWJushZ41Axf_fcIe8u9ipH84ogore
e7vjbU5y18kDquDg"
}
Figure 15: JSON Flattened Serialization
Miller Expires May 17, 2015 [Page 14]
Internet-Draft JOSE Cookbook November 2014
4.2. RSA-PSS Signature
This example illustrates signing content using the "PS256" (RSASSA-
PSS with SHA-256) algorithm.
Note that RSASSA-PSS uses random data to generate the signature; it
might not be possible to exactly replicate the results in this
section.
Note that whitespace is added for readability as described in
Section 1.1.
4.2.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o RSA private key; this example uses the key from Figure 4.
o "alg" parameter of "PS384".
4.2.2. Signing Operation
The following are generated to complete the signing operation:
o JWS Protected Header; this example uses the header from Figure 16,
encoded using [RFC4648] base64url to produce Figure 17.
{
"alg": "PS384",
"kid": "bilbo.baggins@hobbiton.example"
}
Figure 16: JWS Protected Header JSON
eyJhbGciOiJQUzM4NCIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
Figure 17: JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 17) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 18.
Miller Expires May 17, 2015 [Page 15]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJQUzM4NCIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 18: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 18) produces the JWS Signature (Figure 19).
cu22eBqkYDKgIlTpzDXGvaFfz6WGoz7fUDcfT0kkOy42miAh2qyBzk1xEsnk2I
pN6-tPid6VrklHkqsGqDqHCdP6O8TTB5dDDItllVo6_1OLPpcbUrhiUSMxbbXU
vdvWXzg-UD8biiReQFlfz28zGWVsdiNAUf8ZnyPEgVFn442ZdNqiVJRmBqrYRX
e8P_ijQ7p8Vdz0TTrxUeT3lm8d9shnr2lfJT8ImUjvAA2Xez2Mlp8cBE5awDzT
0qI0n6uiP1aCN_2_jLAeQTlqRHtfa64QQSUmFAAjVKPbByi7xho0uTOcbH510a
6GYmJUAfmWjwZ6oD4ifKo8DYM-X72Eaw
Figure 19: JWS Signature, base64url-encoded
4.2.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 17)
o Payload content (Figure 8)
o Signature (Figure 19)
The resulting JWS object using the Compact serialization:
Miller Expires May 17, 2015 [Page 16]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJQUzM4NCIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
.
cu22eBqkYDKgIlTpzDXGvaFfz6WGoz7fUDcfT0kkOy42miAh2qyBzk1xEsnk2I
pN6-tPid6VrklHkqsGqDqHCdP6O8TTB5dDDItllVo6_1OLPpcbUrhiUSMxbbXU
vdvWXzg-UD8biiReQFlfz28zGWVsdiNAUf8ZnyPEgVFn442ZdNqiVJRmBqrYRX
e8P_ijQ7p8Vdz0TTrxUeT3lm8d9shnr2lfJT8ImUjvAA2Xez2Mlp8cBE5awDzT
0qI0n6uiP1aCN_2_jLAeQTlqRHtfa64QQSUmFAAjVKPbByi7xho0uTOcbH510a
6GYmJUAfmWjwZ6oD4ifKo8DYM-X72Eaw
Figure 20: Compact Serialization
The resulting JWS object using the JSON General Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJQUzM4NCIsImtpZCI6ImJpbGJvLmJhZ2
dpbnNAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "cu22eBqkYDKgIlTpzDXGvaFfz6WGoz7fUDcfT0kkOy
42miAh2qyBzk1xEsnk2IpN6-tPid6VrklHkqsGqDqHCdP6O8TTB5
dDDItllVo6_1OLPpcbUrhiUSMxbbXUvdvWXzg-UD8biiReQFlfz2
8zGWVsdiNAUf8ZnyPEgVFn442ZdNqiVJRmBqrYRXe8P_ijQ7p8Vd
z0TTrxUeT3lm8d9shnr2lfJT8ImUjvAA2Xez2Mlp8cBE5awDzT0q
I0n6uiP1aCN_2_jLAeQTlqRHtfa64QQSUmFAAjVKPbByi7xho0uT
OcbH510a6GYmJUAfmWjwZ6oD4ifKo8DYM-X72Eaw"
}
]
}
Figure 21: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 17]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"protected": "eyJhbGciOiJQUzM4NCIsImtpZCI6ImJpbGJvLmJhZ2dpbn
NAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "cu22eBqkYDKgIlTpzDXGvaFfz6WGoz7fUDcfT0kkOy42mi
Ah2qyBzk1xEsnk2IpN6-tPid6VrklHkqsGqDqHCdP6O8TTB5dDDItllV
o6_1OLPpcbUrhiUSMxbbXUvdvWXzg-UD8biiReQFlfz28zGWVsdiNAUf
8ZnyPEgVFn442ZdNqiVJRmBqrYRXe8P_ijQ7p8Vdz0TTrxUeT3lm8d9s
hnr2lfJT8ImUjvAA2Xez2Mlp8cBE5awDzT0qI0n6uiP1aCN_2_jLAeQT
lqRHtfa64QQSUmFAAjVKPbByi7xho0uTOcbH510a6GYmJUAfmWjwZ6oD
4ifKo8DYM-X72Eaw"
}
Figure 22: JSON Flattened Serialization
4.3. ECDSA Signature
This example illustrates signing content using the "ES512" (ECDSA
with curve P-521 and SHA-512) algorithm.
Note that ECDSA uses random data to generate the signature; it might
not be possible to exactly replicate the results in this section.
Note that whitespace is added for readability as described in
Section 1.1.
4.3.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o EC private key on the curve P-521; this example uses the key from
Figure 2.
o "alg" parameter of "ES512"
4.3.2. Signing Operation
The following are generated before beginning the signature process:
o JWS Protected Header; this example uses the header from Figure 23,
encoded using [RFC4648] base64url to produce Figure 24.
Miller Expires May 17, 2015 [Page 18]
Internet-Draft JOSE Cookbook November 2014
{
"alg": "ES512",
"kid": "bilbo.baggins@hobbiton.example"
}
Figure 23: JWS Protected Header JSON
eyJhbGciOiJFUzUxMiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
Figure 24: JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 24) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 25.
eyJhbGciOiJFUzUxMiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 25: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 25) produces the JWS Signature (Figure 26).
AE_R_YZCChjn4791jSQCrdPZCNYqHXCTZH0-JZGYNlaAjP2kqaluUIIUnC9qvb
u9Plon7KRTzoNEuT4Va2cmL1eJAQy3mtPBu_u_sDDyYjnAMDxXPn7XrT0lw-kv
AD890jl8e2puQens_IEKBpHABlsbEPX6sFY8OcGDqoRuBomu9xQ2
Figure 26: JWS Signature, base64url-encoded
4.3.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 24)
o Payload content (Figure 8)
o Signature (Figure 26)
The resulting JWS object using the Compact serialization:
Miller Expires May 17, 2015 [Page 19]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJFUzUxMiIsImtpZCI6ImJpbGJvLmJhZ2dpbnNAaG9iYml0b24uZX
hhbXBsZSJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
.
AE_R_YZCChjn4791jSQCrdPZCNYqHXCTZH0-JZGYNlaAjP2kqaluUIIUnC9qvb
u9Plon7KRTzoNEuT4Va2cmL1eJAQy3mtPBu_u_sDDyYjnAMDxXPn7XrT0lw-kv
AD890jl8e2puQens_IEKBpHABlsbEPX6sFY8OcGDqoRuBomu9xQ2
Figure 27: Compact Serialization
The resulting JWS object using the JSON General Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJFUzUxMiIsImtpZCI6ImJpbGJvLmJhZ2
dpbnNAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "AE_R_YZCChjn4791jSQCrdPZCNYqHXCTZH0-JZGYNl
aAjP2kqaluUIIUnC9qvbu9Plon7KRTzoNEuT4Va2cmL1eJAQy3mt
PBu_u_sDDyYjnAMDxXPn7XrT0lw-kvAD890jl8e2puQens_IEKBp
HABlsbEPX6sFY8OcGDqoRuBomu9xQ2"
}
]
}
Figure 28: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 20]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"protected": "eyJhbGciOiJFUzUxMiIsImtpZCI6ImJpbGJvLmJhZ2dpbn
NAaG9iYml0b24uZXhhbXBsZSJ9",
"signature": "AE_R_YZCChjn4791jSQCrdPZCNYqHXCTZH0-JZGYNlaAjP
2kqaluUIIUnC9qvbu9Plon7KRTzoNEuT4Va2cmL1eJAQy3mtPBu_u_sD
DyYjnAMDxXPn7XrT0lw-kvAD890jl8e2puQens_IEKBpHABlsbEPX6sF
Y8OcGDqoRuBomu9xQ2"
}
Figure 29: JSON Flattened Serialization
4.4. HMAC-SHA2 Integrity Protection
This example illustrates integrity protecting content using the
"HS256" (HMAC-SHA-256) algorithm.
Note that whitespace is added for readability as described in
Section 1.1.
4.4.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o HMAC symmetric key; this example uses the key from Figure 5.
o "alg" parameter of "HS256".
4.4.2. Signing Operation
The following are generated before completing the signing operation:
o JWS Protected Header; this example uses the header from Figure 30,
encoded using [RFC4648] base64url to produce Figure 31.
{
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
}
Figure 30: JWS Protected Header JSON
Miller Expires May 17, 2015 [Page 21]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
Figure 31: JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 31) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 32.
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 32: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 32) produces the JWS Signature (Figure 33).
s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0
Figure 33: JWS Signature, base64url-encoded
4.4.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 31)
o Payload content (Figure 8)
o Signature (Figure 33)
The resulting JWS object using the Compact serialization:
Miller Expires May 17, 2015 [Page 22]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
.
s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0
Figure 34: Compact Serialization
The resulting JWS object using the JSON General Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LT
RkOWItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p
0"
}
]
}
Figure 35: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOW
ItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0"
}
Figure 36: JSON Flattened Serialization
Miller Expires May 17, 2015 [Page 23]
Internet-Draft JOSE Cookbook November 2014
4.5. Signature with Detached Content
This example illustrates a signature with detached content. This
example is identical others, except the resulting JWS objects do not
include the Payload field. Instead, the application is expected to
locate it elsewhere. For example, the signature might be in a meta-
data section, with the payload being the content.
Note that whitespace is added for readability as described in
Section 1.1.
4.5.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o Signing key; this example uses the AES symmetric key from
Figure 5.
o Signing algorithm; this example uses "HS256".
4.5.2. Signing Operation
The following are generated before completing the signing operation:
o JWS Protected Header; this example uses the header from Figure 37,
encoded using [RFC4648] base64url to produce Figure 38.
The JWS Protected Header parameters:
{
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
}
Figure 37: JWS Protected Header JSON
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
Figure 38: JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 38) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 39.
Miller Expires May 17, 2015 [Page 24]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 39: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 39) produces the JWS Signature (Figure 40).
s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0
Figure 40: JWS Signature, base64url-encoded
4.5.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 38)
o Signature (Figure 40)
The resulting JWS object using the Compact serialization:
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
.
.
s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0
Figure 41: JSON General Serialization
The resulting JWS object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 25]
Internet-Draft JOSE Cookbook November 2014
{
"signatures": [
{
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LT
RkOWItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p
0"
}
]
}
Figure 42: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
{
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOW
ItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0"
}
Figure 43: JSON Flattened Serialization
4.6. Protecting Specific Header Fields
This example illustrates a signature where only certain header
parameters are protected. Since this example contains both
unprotected and protected header parameters, only the JSON
serialization is possible.
Note that whitespace is added for readability as described in
Section 1.1.
4.6.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o Signing key; this example uses the AES symmetric key from
Figure 5.
o Signing algorithm; this example uses "HS256".
Miller Expires May 17, 2015 [Page 26]
Internet-Draft JOSE Cookbook November 2014
4.6.2. Signing Operation
The following are generated before completing the signing operation:
o JWS Protected Header; this example uses the header from Figure 44,
encoded using [RFC4648] base64url to produce Figure 45.
o JWS unprotected Header; this example uses the header from
Figure 46.
The JWS Protected Header parameters:
{
"alg": "HS256"
}
Figure 44: JWS Protected Header JSON
eyJhbGciOiJIUzI1NiJ9
Figure 45: JWS Protected Header, base64url-encoded
{
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
}
Figure 46: JWS Unprotected Header JSON
The JWS Protected Header (Figure 45) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 47.
eyJhbGciOiJIUzI1NiJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 47: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 47) produces the JWS Signature (Figure 48).
bWUSVaxorn7bEF1djytBd0kHv70Ly5pvbomzMWSOr20
Figure 48: JWS Signature, base64url-encoded
Miller Expires May 17, 2015 [Page 27]
Internet-Draft JOSE Cookbook November 2014
4.6.3. Output Results
The following compose the resulting JWS object:
o JWS Protected Header (Figure 45)
o JWS Unprotected Header (Figure 46)
o Payload content (Figure 8)
o Signature (Figure 48)
The Compact Serialization is not presented because it does not
support this use case.
The resulting JWS object using the JSON General Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJIUzI1NiJ9",
"header": {
"kid": 6.4. The Inactivity Timeout
The purpose of the inactivity timeout is for the server to balance
its trade off between the costs of setting up new DSO Sessions and
the costs of maintaining inactive DSO Sessions. A server with
abundant DSO Session capacity can offer a high inactivity timeout, to
permit clients to keep a speculative DSO Session open for a long
time, to save the cost of establishing a new DSO Session for future
communications with that server. A server with scarce memory
resources can offer a low inactivity timeout, to cause clients to
promptly close DSO Sessions whenever they have no outstanding
operations with that server, and then create a new DSO Session later
when needed.
6.4.1. Closing Inactive DSO Sessions
When a connection's inactivity timeout is reached the client MUST
begin closing the idle connection, but a client is not required to
keep an idle connection open until the inactivity timeout is reached.
A client MAY close a DSO Session at any time, at the client's
discretion. If a client determines that it has no current or
reasonably anticipated future need for a currently inactive DSO
Session, then the client SHOULD gracefully close that connection.
If, at any time during the life of the DSO Session, the inactivity
timeout value (i.e., 15 seconds by default) elapses without there
being any operation active on the DSO Session, the client MUST close
the connection gracefully.
If, at any time during the life of the DSO Session, twice the
inactivity timeout value (i.e., 30 seconds by default), or five
seconds, if twice the inactivity timeout value is less than five
seconds, elapses without there being any operation active on the DSO
Session, the server SHOULD consider the client delinquent, and SHOULD
forcibly abort the DSO Session.
In this context, an operation being active on a DSO Session includes
a query waiting for a response, an update waiting for a response, or
an active long-lived operation, but not a DSO Keepalive message
exchange itself. A DSO Keepalive message exchange resets only the
keepalive interval timer, not the inactivity timeout timer.
If the client wishes to keep an inactive DSO Session open for longer
than the default duration then it uses the DSO Keepalive message to
request longer timeout values, as described in Section 7.1.
Bellis, et al. Expires December 9, 2018 [Page 29]
Internet-Draft DNS Stateful Operations June 2018
6.4.2. Values for the Inactivity Timeout
For the inactivity timeout value, lower values result in more
frequent DSO Session teardown and re-establishment. Higher values
result in lower traffic and lower CPU load on the server, but higher
memory burden to maintain state for inactive DSO Sessions.
A server may dictate any value it chooses for the inactivity timeout
(either in a response to a client-initiated request, or in a server-
initiated message) including values under one second, or even zero.
An inactivity timeout of zero informs the client that it should not
speculatively maintain idle connections at all, and as soon as the
client has completed the operation or operations relating to this
server, the client should immediately begin closing this session.
A server will abort an idle client session after twice the inactivity
timeout value, or five seconds, whichever is greater. In the case of
a zero inactivity timeout value, this means that if a client fails to
close an idle client session then the server will forcibly abort the
idle session after five seconds.
An inactivity timeout of 0xFFFFFFFF represents "infinity" and informs
the client that it may keep an idle connection open as long as it
wishes. Note that after granting an unlimited inactivity timeout in
this way, at any point the server may revise that inactivity timeout
by sending a new Keepalive message dictating new Session Timeout
values to the client.
The largest *finite* inactivity timeout supported by the current DSO
Keepalive TLV is 0xFFFFFFFE (2^32-2 milliseconds, approximately 49.7
days).
Bellis, et al. Expires December 9, 2018 [Page 30]
Internet-Draft DNS Stateful Operations June 2018
6.5. The Keepalive Interval
The purpose of the keepalive interval is to manage the generation of
sufficient messages to maintain state in middleboxes (such at NAT
gateways or firewalls) and for the client and server to periodically
verify that they still have connectivity to each other. This allows
them to clean up state when connectivity is lost, and to establish a
new session if appropriate.
6.5.1. Keepalive Interval Expiry
If, at any time during the life of the DSO Session, the keepalive
interval value (i.e., 15 seconds by default) elapses without any DNS
messages being sent or received on a DSO Session, the client MUST
take action to keep the DSO Session alive, by sending a DSO Keepalive
message (Section 7.1). A DSO Keepalive message exchange resets only
the keepalive timer, not the inactivity timer.
If a client disconnects from the network abruptly, without cleanly
closing its DSO Session, perhaps leaving a long-lived operation
uncancelled, the server learns of this after failing to receive the
required keepalive traffic from that client. If, at any time during
the life of the DSO Session, twice the keepalive interval value
(i.e., 30 seconds by default) elapses without any DNS messages being
sent or received on a DSO Session, the server SHOULD consider the
client delinquent, and SHOULD forcibly abort the DSO Session.
6.5.2. Values for the Keepalive Interval
For the keepalive interval value, lower values result in a higher
volume of keepalive traffic. Higher values of the keepalive interval
reduce traffic and CPU load, but have minimal effect on the memory
burden at the server, because clients keep a DSO Session open for the
same length of time (determined by the inactivity timeout) regardless
of the level of keepalive traffic required.
It may be appropriate for clients and servers to select different
keepalive interval values depending on the nature of the network they
are on.
A corporate DNS server that knows it is serving only clients on the
internal network, with no intervening NAT gateways or firewalls, can
impose a higher keepalive interval, because frequent keepalive
traffic is not required.
A public DNS server that is serving primarily residential consumer
clients, where it is likely there will be a NAT gateway on the path,
Bellis, et al. Expires December 9, 2018 [Page 31]
Internet-Draft DNS Stateful Operations June 2018
may impose a lower keepalive interval, to generate more frequent
keepalive traffic.
A smart client may be adaptive to its environment. A client using a
private IPv4 address [RFC1918] to communicate with a DNS server at an
address outside that IPv4 private address block, may conclude that
there is likely to be a NAT gateway on the path, and accordingly
request a lower keepalive interval.
By default it is RECOMMENDED that clients request, and servers grant,
a keepalive interval of 60 minutes. This keepalive interval provides
for reasonably timely detection if a client abruptly disconnects
without cleanly closing the session, and is sufficient to maintain
state in firewalls and NAT gateways that follow the IETF recommended
Best Current Practice that the "established connection idle-timeout"
used by middleboxes be at least 2 hours 4 minutes [RFC5382].
Note that the lower the keepalive interval value, the higher the load
on client and server. For example, a hypothetical keepalive interval
value of 100ms would result in a continuous stream of at least ten
messages per second, in both directions, to keep the DSO Session
alive. And, in this extreme example, a single packet loss and
retransmission over a long path could introduce a momentary pause in
the stream of messages, long enough to cause the server to
overzealously abort the connection.
Because of this concern, the server MUST NOT send a Keepalive message
(either a response to a client-initiated request, or a server-
initiated message) with a keepalive interval value less than ten
seconds. If a client receives a Keepalive message specifying a
keepalive interval value less than ten seconds this is a fatal error
and the client MUST forcibly abort the connection immediately.
A keepalive interval value of 0xFFFFFFFF represents "infinity" and
informs the client that it should generate no keepalive traffic.
Note that after signaling that the client should generate no
keepalive traffic in this way, at any point the server may revise
that keepalive traffic requirement by sending a new Keepalive message
dictating new Session Timeout values to the client.
The largest *finite* keepalive interval supported by the current DSO
Keepalive TLV is 0xFFFFFFFE (2^32-2 milliseconds, approximately 49.7
days).
Bellis, et al. Expires December 9, 2018 [Page 32]
Internet-Draft DNS Stateful Operations June 2018
6.6. Server-Initiated Session Termination
In addition to cancelling individual long-lived operations
selectively (Section 5.5) there are also occasions where a server may
need to terminate one or more entire sessions. An entire session may
need to be terminated if the client is defective in some way, or
departs from the network without closing its session. Sessions may
also need to be terminated if the server becomes overloaded, or if
the server is reconfigured and lacks the ability to be selective
about which operations need to be cancelled.
This section discusses various reasons a session may be terminated,
and the mechanisms for doing so.
Normally a server MUST NOT close a DSO Session with a client. A
server only causes a DSO Session to be ended in the exceptional
circumstances outlined below. In normal operation, closing a DSO
Session is the client's responsibility. The client makes the
determination of when to close a DSO Session based on an evaluation
of both its own needs, and the inactivity timeout value dictated by
the server.
Some of the exceptional situations in which a server may terminate a
DSO Session include:
o The server application software or underlying operating system is
shutting down or restarting.
o The server application software terminates unexpectedly (perhaps
due to a bug that makes it crash).
o The server is undergoing a reconfiguration or maintenance
procedure, that, due to the way the server software is
implemented, requires clients to be disconnected. For example,
some software is implemented such that it reads a configuration
file at startup, and changing the server's configuration entails
modifying the configuration file and then killing and restarting
the server software, which generally entails a loss of network
connections.
o The client fails to meets its obligation to generate the required
keepalive traffic, or to close an inactive session by the
prescribed time (twice the time interval dictated by the server,
or five seconds, whichever is greater, as described in
Section 6.2).
o The client sends a grossly invalid or malformed request that is
indicative of a seriously defective client implementation.
Bellis, et al. Expires December 9, 2018 [Page 33]
Internet-Draft DNS Stateful Operations June 2018
o The server is over capacity and needs to shed some load.
6.6.1. Server-Initiated Retry Delay Message
In the cases described above where a server elects to terminate a DSO
Session, it could do so simply by forcibly aborting the connection.
However, if it did this the likely behavior of the client might be
simply to to treat this as a network failure and reconnect
immediately, putting more burden on the server.
Therefore, to avoid this reconnection implosion, a server SHOULD
instead choose to shed client load by sending a Retry Delay message,
with an appropriate RCODE value informing the client of the reason
the DSO Session needs to be terminated. The format of the Retry
Delay TLV, and the interpretations of the various RCODE values, are
described in Section 7.2. After sending a Retry Delay message, the
server MUST NOT send any further messages on that DSO Session.
Upon receipt of a Retry Delay message from the server, the client
MUST make note of the reconnect delay for this server, and then
immediately close the connection gracefully.
After sending a Retry Delay message the server SHOULD allow the
client five seconds to close the connection, and if the client has
not closed the connection after five seconds then the server SHOULD
forcibly abort the connection.
A Retry Delay message MUST NOT be initiated by a client. If a server
receives a Retry Delay message this is a fatal error and the server
MUST forcibly abort the connection immediately.
Bellis, et al. Expires December 9, 2018 [Page 34]
Internet-Draft DNS Stateful Operations June 2018
6.6.1.1. Outstanding Operations
At the instant a server chooses to initiate a Retry Delay message
there may be DNS requests already in flight from client to server on
this DSO Session, which will arrive at the server after its Retry
Delay message has been sent. The server MUST silently ignore such
incoming requests, and MUST NOT generate any response messages for
them. When the Retry Delay message from the server arrives at the
client, the client will determine that any DNS requests it previously
sent on this DSO Session, that have not yet received a response, now
will certainly not be receiving any response. Such requests should
be considered failed, and should be retried at a later time, as
appropriate.
In the case where some, but not all, of the existing operations on a
DSO Session have become invalid (perhaps because the server has been
reconfigured and is no longer authoritative for some of the names),
but the server is terminating all affected DSO Sessions en masse by
sending them all a Retry Delay message, the RECONNECT DELAY MAY be
zero, indicating that the clients SHOULD immediately attempt to re-
establish operations.
It is likely that some of the attempts will be successful and some
will not, depending on the nature of the reconfiguration.
In the case where a server is terminating a large number of DSO
Sessions at once (e.g., if the system is restarting) and the server
doesn't want to be inundated with a flood of simultaneous retries, it
SHOULD send different RECONNECT delay values to each client. These
adjustments MAY be selected randomly, pseudorandomly, or
deterministically (e.g., incrementing the time value by one tenth of
a second for each successive client, yielding a post-restart
reconnection rate of ten clients per second).
Bellis, et al. Expires December 9, 2018 [Page 35]
Internet-Draft DNS Stateful Operations June 2018
6.6.1.2. Client Reconnection
After a DSO Session is ended by the server (either by sending the
client a Retry Delay message, or by forcibly aborting the underlying
transport connection) the client SHOULD try to reconnect, to that
service instance, or to another suitable service instance, if more
than one is available. If reconnecting to the same service instance,
the client MUST respect the indicated delay, if available, before
attempting to reconnect.
If the service instance will only be out of service for a short
maintenance period, it should use a value a little longer that the
expected maintenance window. It should not default to a very large
delay value, or clients may not attempt to reconnect after it resumes
service.
If a particular service instance does not want a client to reconnect
ever (perhaps the service instance is being de-commissioned), it
SHOULD set the retry delay to the maximum value 0xFFFFFFFF (2^32-1
milliseconds, approximately 49.7 days). It is not possible to
instruct a client to stay away for longer than 49.7 days. If, after
49.7 days, the DNS or other configuration information still indicates
that this is the valid service instance for a particular service,
then clients MAY attempt to reconnect. In reality, if a client is
rebooted or otherwise lose state, it may well attempt to reconnect
before 49.7 days elapses, for as long as the DNS or other
configuration information continues to indicate that this is the
service instance the client should use.
Bellis, et al. Expires December 9, 2018 [Page 36]
Internet-Draft DNS Stateful Operations June 2018
7. Base TLVs for DNS Stateful Operations
This section describes the three base TLVs for DNS Stateful
Operations: Keepalive, Retry Delay, and Encryption Padding.
7.1. Keepalive TLV
The Keepalive TLV (DSO-TYPE=1) performs two functions: to reset the
keepalive timer for the DSO Session, and to establish the values for
the Session Timeouts.
The DSO-DATA for the the Keepalive TLV is as follows:
1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| INACTIVITY TIMEOUT (32 bits) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| KEEPALIVE INTERVAL (32 bits) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
INACTIVITY TIMEOUT: The inactivity timeout for the current DSO
Session, specified as a 32-bit unsigned integer, in network (big
endian) byte order, in units of milliseconds. This is the timeout
at which the client MUST begin closing an inactive DSO Session.
The inactivity timeout can be any value of the server's choosing.
If the client does not gracefully close an inactive DSO Session,
then after twice this interval, or five seconds, whichever is
greater, the server will forcibly abort the connection.
KEEPALIVE INTERVAL: The keepalive interval for the current DSO
Session, specified as a 32-bit unsigned integer, in network (big
endian) byte order, in units of milliseconds. This is the
interval at which a client MUST generate keepalive traffic to
maintain connection state. The keepalive interval MUST NOT be
less than ten seconds. If the client does not generate the
mandated keepalive traffic, then after twice this interval the
server will forcibly abort the connection. Since the minimum
allowed keepalive interval is ten seconds, the minimum time at
which a server will forcibly disconnect a client for failing to
generate the mandated keepalive traffic is twenty seconds.
The transmission or reception of DSO Keepalive messages (i.e.,
messages where the Keepalive TLV is the first TLV) reset only the
keepalive timer, not the inactivity timer. The reason for this is
that periodic Keepalive messages are sent for the sole purpose of
keeping a DSO Session alive, when that DSO Session has current or
recent non-maintenance activity that warrants keeping that DSO
Bellis, et al. Expires December 9, 2018 [Page 37]
Internet-Draft DNS Stateful Operations June 2018
Session alive. Sending keepalive traffic itself is not considered a
client activity; it is considered a maintenance activity that is
performed in service of other client activities. If keepalive
traffic itself were to reset the inactivity timer, then that would
create a circular livelock where keepalive traffic would be sent
indefinitely to keep a DSO Session alive, where the only activity on
that DSO Session would be the keepalive traffic keeping the DSO
Session alive so that further keepalive traffic can be sent. For a
DSO Session to be considered active, it must be carrying something
more than just keepalive traffic. This is why merely sending or
receiving a Keepalive message does not reset the inactivity timer.
When sent by a client, the Keepalive request message MUST be sent as
an acknowledged request, with a nonzero MESSAGE ID. If a server
receives a Keepalive DSO message with a zero MESSAGE ID then this is
a fatal error and the server MUST forcibly abort the connection
immediately. The Keepalive request message resets a DSO Session's
keepalive timer, and at the same time communicates to the server the
the client's requested Session Timeout values. In a server response
to a client-initiated Keepalive request message, the Session Timeouts
contain the server's chosen values from this point forward in the DSO
Session, which the client MUST respect. This is modeled after the
DHCP protocol, where the client requests a certain lease lifetime
using DHCP option 51 [RFC2132], but the server is the ultimate
authority for deciding what lease lifetime is actually granted.
When a client is sending its second and subsequent Keepalive DSO
requests to the server, the client SHOULD continue to request its
preferred values each time. This allows flexibility, so that if
conditions change during the lifetime of a DSO Session, the server
can adapt its responses to better fit the client's needs.
Once a DSO Session is in progress (Section 5.1) a Keepalive message
MAY be initiated by a server. When sent by a server, the Keepalive
message MUST be sent as an unacknowledged message, with the MESSAGE
ID set to zero. The client MUST NOT generate a response to a server-
initiated DSO Keepalive message. If a client receives a Keepalive
request message with a nonzero MESSAGE ID then this is a fatal error
and the client MUST forcibly abort the connection immediately. The
Keepalive unacknowledged message from the server resets a DSO
Session's keepalive timer, and at the same time unilaterally informs
the client of the new Session Timeout values to use from this point
forward in this DSO Session. No client DSO response message to this
unilateral declaration is required or allowed.
The Keepalive TLV is not used as an Additional TLV.
Bellis, et al. Expires December 9, 2018 [Page 38]
Internet-Draft DNS Stateful Operations June 2018
In response messages the Keepalive TLV is used only as a Response
Primary TLV, replying to a Keepalive request message from the client.
A Keepalive TLV MUST NOT be added as to other responses a Response
Additional TLV. If the server wishes to update a client's Session
Timeout values other than in response to a Keepalive request message
from the client, then it does so by sending an unacknowledged
Keepalive message of its own, as described above.
It is not required that the Keepalive TLV be used in every DSO
Session. While many DNS Stateful operations will be used in
conjunction with a long-lived session state, not all DNS Stateful
operations require long-lived session state, and in some cases the
default 15-second value for both the inactivity timeout and keepalive
interval may be perfectly appropriate. However, note that for
clients that implement only the DSO-TYPEs defined in this document, a
Keepalive request message is the only way for a client to initiate a
DSO Session.
7.1.1. Client handling of received Session Timeout values
When a client receives a response to its client-initiated DSO
Keepalive message, or receives a server-initiated DSO Keepalive
message, the client has then received Session Timeout values dictated
by the server. The two timeout values contained in the DSO Keepalive
TLV from the server may each be higher, lower, or the same as the
respective Session Timeout values the client previously had for this
DSO Session.
In the case of the keepalive timer, the handling of the received
value is straightforward. The act of receiving the message
containing the DSO Keepalive TLV itself resets the keepalive timer
and updates the keepalive interval for the DSO Session. The new
keepalive interval indicates the maximum time that may elapse before
another message must be sent or received on this DSO Session, if the
DSO Session is to remain alive.
Bellis, et al. Expires December 9, 2018 [Page 39]
Internet-Draft DNS Stateful Operations June 2018
In the case of the inactivity timeout, the handling of the received
value is a little more subtle, though the meaning of the inactivity
timeout remains as specified -- it still indicates the maximum
permissible time allowed without useful activity on a DSO Session.
The act of receiving the message containing the DSO Keepalive TLV
does not itself reset the inactivity timer. The time elapsed since
the last useful activity on this DSO Session is unaffected by
exchange of DSO Keepalive messages. The new inactivity timeout value
in the DSO Keepalive TLV in the received message does update the
timeout associated with the running inactivity timer; that becomes
the new maximum permissible time without activity on a DSO Session.
o If the current inactivity timer value is less than the new
inactivity timeout, then the DSO Session may remain open for now.
When the inactivity timer value reaches the new inactivity
timeout, the client MUST then begin closing the DSO Session, as
described above.
o If the current inactivity timer value is equal to the new
inactivity timeout, then this DSO Session has been inactive for
exactly as long as the server will permit, and now the client MUST
immediately begin closing this DSO Session.
o If the current inactivity timer value is already greater than the
new inactivity timeout, then this DSO Session has already been
inactive for longer than the server permits, and the client MUST
immediately begin closing this DSO Session.
o If the current inactivity timer value is already more than twice
the new inactivity timeout, then the client is immediately
considered delinquent (this DSO Session is immediately eligible to
be forcibly terminated by the server) and the client MUST
immediately begin closing this DSO Session. However if a server
abruptly reduces the inactivity timeout in this way, then, to give
the client time to close the connection gracefully before the
server resorts to forcibly aborting it, the server SHOULD give the
client an additional grace period of one quarter of the new
inactivity timeout, or five seconds, whichever is greater.
Bellis, et al. Expires December 9, 2018 [Page 40]
Internet-Draft DNS Stateful Operations June 2018
7.1.2. Relation to EDNS(0) TCP Keepalive Option
The inactivity timeout value in the Keepalive TLV (DSO-TYPE=1) has
similar intent to the EDNS(0) TCP Keepalive Option [RFC7828]. A
client/server pair that supports DSO MUST NOT use the EDNS(0) TCP
KeepAlive option within any message after a DSO Session has been
established. Once a DSO Session has been established, if either
client or server receives a DNS message over the DSO Session that
contains an EDNS(0) TCP Keepalive option, this is a fatal error and
the receiver of the EDNS(0) TCP Keepalive option MUST forcibly abort
the connection immediately.
Bellis, et al. Expires December 9, 2018 [Page 41]
Internet-Draft DNS Stateful Operations June 2018
7.2. Retry Delay TLV
The Retry Delay TLV (DSO-TYPE=2) can be used as a Primary TLV
(unacknowledged) in a server-to-client message, or as a Response
Additional TLV in either direction.
The DSO-DATA for the the Retry Delay TLV is as follows:
1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2 2 2 3 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| RETRY DELAY (32 bits) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
RETRY DELAY: A time value, specified as a 32-bit unsigned integer,
in network (big endian) byte order, in units of milliseconds,
within which the initiator MUST NOT retry this operation, or retry
connecting to this server. Recommendations for the RETRY DELAY
value are given in Section 6.6.1.
7.2.1. Retry Delay TLV used as a Primary TLV
When sent from server to client, the Retry Delay TLV is used as the
Primary TLV in an unacknowledged message. It is used by a server to
instruct a client to close the DSO Session and underlying connection,
and not to reconnect for the indicated time interval.
In this case it applies to the DSO Session as a whole, and the client
MUST begin closing the DSO Session, as described in Section 6.6.1.
The RCODE in the message header SHOULD indicate the principal reason
for the termination:
o NOERROR indicates a routine shutdown or restart.
o FORMERR indicates that the client requests are too badly malformed
for the session to continue.
o SERVFAIL indicates that the server is overloaded due to resource
exhaustion and needs to shed load.
o REFUSED indicates that the server has been reconfigured, and at
this time it is now unable to perform one or more of the long-
lived client operations that were previously being performed on
this DSO Session.
o NOTAUTH indicates that the server has been reconfigured and at
this time it is now unable to perform one or more of the long-
lived client operations that were previously being performed on
Bellis, et al. Expires December 9, 2018 [Page 42]
Internet-Draft DNS Stateful Operations June 2018
this DSO Session because it does not have authority over the names
in question (for example, a DNS Push Notification server could be
reconfigured such that is is no longer accepting DNS Push
Notification requests for one or more of the currently subscribed
names).
This document specifies only these RCODE values for Retry Delay
message. Servers sending Retry Delay messages SHOULD use one of
these values. However, future circumstances may create situations
where other RCODE values are appropriate in Retry Delay messages, so
clients MUST be prepared to accept Retry Delay messages with any
RCODE value.
In some cases, when a server sends a Retry Delay message to a client,
there may be more than one reason for the server wanting to end the
session. Possibly the configuration could have been changed such
that some long-lived client operations can no longer be continued due
to policy (REFUSED), and other long-lived client operations can no
longer be performed due to the server no longer being authoritative
for those names (NOTAUTH). In such cases the server MAY use any of
the applicable RCODE values, or RCODE=NOERROR (routine shutdown or
restart).
Note that the selection of RCODE value in a Retry Delay message is
not critical, since the RCODE value is generally used only for
information purposes, such as writing to a log file for future human
analysis regarding the nature of the disconnection. Generally
clients do not modify their behavior depending on the RCODE value.
The RETRY DELAY in the message tells the client how long it should
wait before attempting a new connection to this service instance.
For clients that do in some way modify their behavior depending on
the RCODE value, they should treat unknown RCODE values the same as
RCODE=NOERROR (routine shutdown or restart).
A Retry Delay message from server to client is an unacknowledged
message; the MESSAGE ID MUST be set to zero in the outgoing message
and the client MUST NOT send a response.
A client MUST NOT send a Retry Delay DSO request message or DSO
unacknowledged message to a server. If a server receives a DNS
request message (i.e., QR=0) where the Primary TLV is the Retry Delay
TLV, this is a fatal error and the server MUST forcibly abort the
connection immediately.
Bellis, et al. Expires December 9, 2018 [Page 43]
"018c0ae5-4d9b-471b-bfd6-eef314bc7037"
},
"signature": "bWUSVaxorn7bEF1djytBd0kHv70Ly5pvbomzMWSOr2
0"
}
]
}
Figure 49: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 28]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"protected": "eyJhbGciOiJIUzI1NiJ9",
"header": {
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
},
"signature": "bWUSVaxorn7bEF1djytBd0kHv70Ly5pvbomzMWSOr20"
}
Figure 50: JSON Flattened Serialization
4.7. Protecting Content Only
This example illustrates a signature where none of the header
parameters are protected. Since this example contains only
unprotected header parameters, only the JSON serialization is
possible.
Note that whitespace is added for readability as described in
Section 1.1.
4.7.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o Signing key; this example uses the AES key from Figure 5.
o Signing algorithm; this example uses "HS256"
4.7.2. Signing Operation
The following are generated before completing the signing operation:
o JWS Unprotected Header; this example uses the header from
Figure 51.
Miller Expires May 17, 2015 [Page 29]
Internet-Draft JOSE Cookbook November 2014
{
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
}
Figure 51: JWS Unprotected Header JSON
The empty string (as there is no JWS Protected Header) and Payload
content (Figure 8) are combined as described in
[I-D.ietf-jose-json-web-signature] to produce the JWS Signing Input
Figure 52.
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 52: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 52) produces the JWS Signature (Figure 53).
xuLifqLGiblpv9zBpuZczWhNj1gARaLV3UxvxhJxZuk
Figure 53: JWS Signature, base64url-encoded
4.7.3. Output Results
The following compose the resulting JWS object:
o JWS Unprotected Header (Figure 51)
o Payload content (Figure 8)
o Signature (Figure 53)
The Compact Serialization is not presented because it does not
support this use case.
The resulting JWS object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 30]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"header": {
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
},
"signature": "xuLifqLGiblpv9zBpuZczWhNj1gARaLV3UxvxhJxZu
k"
}
]
}
Figure 54: JSON General Serialization
The resulting JWS object using the JSON Flattened Serialization:
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"header": {
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
},
"signature": "xuLifqLGiblpv9zBpuZczWhNj1gARaLV3UxvxhJxZuk"
}
Figure 55: JSON Flattened Serialization
4.8. Multiple Signatures
This example illustrates multiple signatures applied to the same
payload. Since this example contains more than one signature, only
the JSON serialization is possible.
Note that whitespace is added for readability as described in
Section 1.1.
Miller Expires May 17, 2015 [Page 31]
Internet-Draft JOSE Cookbook November 2014
4.8.1. Input Factors
The following are supplied before beginning the signing operation:
o Payload content; this example uses the content from Figure 7,
encoded using [RFC4648] base64url to produce Figure 8.
o Signing keys; this example uses the following:
* RSA private key from Figure 4 for the first signature
* EC private key from Figure 2 for the second signature
* AES symmetric key from Figure 5 for the third signature
o Signing algorithms; this example uses the following:
* "RS256" for the first signature
* "ES512" for the second signature
* "HS256" for the third signature
4.8.2. First Signing Operation
The following are generated before completing the first signing
operation:
o JWS Protected Header; this example uses the header from Figure 56,
encoded using [RFC4648] base64url to produce Figure 57.
o JWS Unprotected Header; this example uses the header from
Figure 58.
{
"alg": "RS256"
}
Figure 56: Signature #1 JWS Protected Header JSON
eyJhbGciOiJSUzI1NiJ9
Figure 57: Signature #1 JWS Protected Header, base64url-encoded
Miller Expires May 17, 2015 [Page 32]
Internet-Draft JOSE Cookbook November 2014
{
"kid": "bilbo.baggins@hobbiton.example"
}
Figure 58: Signature #1 JWS Unprotected Header JSON
The JWS Protected Header (Figure 57) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 59.
eyJhbGciOiJSUzI1NiJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 59: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 59) produces the JWS Signature (Figure 60).
MIsjqtVlOpa71KE-Mss8_Nq2YH4FGhiocsqrgi5NvyG53uoimic1tcMdSg-qpt
rzZc7CG6Svw2Y13TDIqHzTUrL_lR2ZFcryNFiHkSw129EghGpwkpxaTn_THJTC
glNbADko1MZBCdwzJxwqZc-1RlpO2HibUYyXSwO97BSe0_evZKdjvvKSgsIqjy
tKSeAMbhMBdMma622_BG5t4sdbuCHtFjp9iJmkio47AIwqkZV1aIZsv33uPUqB
BCXbYoQJwt7mxPftHmNlGoOSMxR_3thmXTCm4US-xiNOyhbm8afKK64jU6_TPt
QHiJeQJxz9G3Tx-083B745_AfYOnlC9w
Figure 60: JWS Signature #1, base64url-encoded
The following is the assembled first signature serialized as JSON:
{
"protected": "eyJhbGciOiJSUzI1NiJ9",
"header": {
"kid": "bilbo.baggins@hobbiton.example"
},
"signature": "MIsjqtVlOpa71KE-Mss8_Nq2YH4FGhiocsqrgi5NvyG53u
oimic1tcMdSg-qptrzZc7CG6Svw2Y13TDIqHzTUrL_lR2ZFcryNFiHkS
w129EghGpwkpxaTn_THJTCglNbADko1MZBCdwzJxwqZc-1RlpO2HibUY
yXSwO97BSe0_evZKdjvvKSgsIqjytKSeAMbhMBdMma622_BG5t4sdbuC
HtFjp9iJmkio47AIwqkZV1aIZsv33uPUqBBCXbYoQJwt7mxPftHmNlGo
OSMxR_3thmXTCm4US-xiNOyhbm8afKK64jU6_TPtQHiJeQJxz9G3Tx-0
83B745_AfYOnlC9w"
}
Figure 61: Signature #1 JSON
Miller Expires May 17, 2015 [Page 33]
Internet-Draft JOSE Cookbook November 2014
4.8.3. Second Signing Operation
The following are generated before completing the second signing
operation:
o JWS Unprotected Header; this example uses the header from
Figure 62.
{
"alg": "ES512",
"kid": "bilbo.baggins@hobbiton.example"
}
Figure 62: Signature #2 JWS Unprotected Header JSON
The empty string (as there is no JWS Protected Header) and Payload
content (Figure 8) are combined as described in
[I-D.ietf-jose-json-web-signature] to produce the JWS Signing Input
Figure 63.
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 63: JWS Signing Input
Performing the signature operation over the JWS Signing Input
(Figure 63) produces the JWS Signature (Figure 64).
ARcVLnaJJaUWG8fG-8t5BREVAuTY8n8YHjwDO1muhcdCoFZFFjfISu0Cdkn9Yb
dlmi54ho0x924DUz8sK7ZXkhc7AFM8ObLfTvNCrqcI3Jkl2U5IX3utNhODH6v7
xgy1Qahsn0fyb4zSAkje8bAWz4vIfj5pCMYxxm4fgV3q7ZYhm5eD
Figure 64: JWS Signature #2, base64url-encoded
The following is the assembled second signature serialized as JSON:
Miller Expires May 17, 2015 [Page 34]
Internet-Draft JOSE Cookbook November 2014
{
"header": {
"alg": "ES512",
"kid": "bilbo.baggins@hobbiton.example"
},
"signature": "ARcVLnaJJaUWG8fG-8t5BREVAuTY8n8YHjwDO1muhcdCoF
ZFFjfISu0Cdkn9Ybdlmi54ho0x924DUz8sK7ZXkhc7AFM8ObLfTvNCrq
cI3Jkl2U5IX3utNhODH6v7xgy1Qahsn0fyb4zSAkje8bAWz4vIfj5pCM
Yxxm4fgV3q7ZYhm5eD"
}
Figure 65: Signature #2 JSON
4.8.4. Third Signing Operation
The following are generated before completing the third signing
operation:
o JWS Protected Header; this example uses the header from Figure 66,
encoded using [RFC4648] base64url to produce Figure 67.
{
"alg": "HS256",
"kid": "018c0ae5-4d9b-471b-bfd6-eef314bc7037"
}
Figure 66: Signature #3 JWS Protected Header JSON
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
Figure 67: Signature #3 JWS Protected Header, base64url-encoded
The JWS Protected Header (Figure 67) and Payload content (Figure 8)
are combined as described in [I-D.ietf-jose-json-web-signature] to
produce the JWS Signing Input Figure 68.
eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOWItNDcxYi1iZmQ2LW
VlZjMxNGJjNzAzNyJ9
.
SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywgZ29pbmcgb3V0IH
lvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9hZCwgYW5kIGlmIHlvdSBk
b24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXigJlzIG5vIGtub3dpbmcgd2hlcm
UgeW91IG1pZ2h0IGJlIHN3ZXB0IG9mZiB0by4
Figure 68: JWS Signing Input
Miller Expires May 17, 2015 [Page 35]
Internet-Draft JOSE Cookbook November 2014
Performing the signature operation over the JWS Signing Input
(Figure 68) produces the JWS Signature (Figure 69).
s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0
Figure 69: JWS Signature #3, base64url-encoded
The following is the assembled third signature serialized as JSON:
{
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LTRkOW
ItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p0"
}
Figure 70: Signature #3 JSON
4.8.5. Output Results
The following compose the resulting JWS object:
o Payload content (Figure 8)
o Signature #1 JSON (Figure 61)
o Signature #2 JSON (Figure 65)
o Signature #3 JSON (Figure 70)
The Compact Serialization is not presented because it does not
support this use case; the JSON Flattened Serialization is not
presented because there is more than one signature.
The resulting JWS object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 36]
Internet-Draft JOSE Cookbook November 2014
{
"payload": "SXTigJlzIGEgZGFuZ2Vyb3VzIGJ1c2luZXNzLCBGcm9kbywg
Z29pbmcgb3V0IHlvdXIgZG9vci4gWW91IHN0ZXAgb250byB0aGUgcm9h
ZCwgYW5kIGlmIHlvdSBkb24ndCBrZWVwIHlvdXIgZmVldCwgdGhlcmXi
gJlzIG5vIGtub3dpbmcgd2hlcmUgeW91IG1pZ2h0IGJlIHN3ZXB0IG9m
ZiB0by4",
"signatures": [
{
"protected": "eyJhbGciOiJSUzI1NiJ9",
"header": {
"kid": "bilbo.baggins@hobbiton.example"
},
"signature": "MIsjqtVlOpa71KE-Mss8_Nq2YH4FGhiocsqrgi5Nvy
G53uoimic1tcMdSg-qptrzZc7CG6Svw2Y13TDIqHzTUrL_lR2ZFc
ryNFiHkSw129EghGpwkpxaTn_THJTCglNbADko1MZBCdwzJxwqZc
-1RlpO2HibUYyXSwO97BSe0_evZKdjvvKSgsIqjytKSeAMbhMBdM
ma622_BG5t4sdbuCHtFjp9iJmkio47AIwqkZV1aIZsv33uPUqBBC
XbYoQJwt7mxPftHmNlGoOSMxR_3thmXTCm4US-xiNOyhbm8afKK6
4jU6_TPtQHiJeQJxz9G3Tx-083B745_AfYOnlC9w"
},
{
"header": {
"alg": "ES512",
"kid": "bilbo.baggins@hobbiton.example"
},
"signature": "ARcVLnaJJaUWG8fG-8t5BREVAuTY8n8YHjwDO1muhc
dCoFZFFjfISu0Cdkn9Ybdlmi54ho0x924DUz8sK7ZXkhc7AFM8Ob
LfTvNCrqcI3Jkl2U5IX3utNhODH6v7xgy1Qahsn0fyb4zSAkje8b
AWz4vIfj5pCMYxxm4fgV3q7ZYhm5eD"
},
{
"protected": "eyJhbGciOiJIUzI1NiIsImtpZCI6IjAxOGMwYWU1LT
RkOWItNDcxYi1iZmQ2LWVlZjMxNGJjNzAzNyJ9",
"signature": "s0h6KThzkfBBBkLspW1h84VsJZFTsPPqMDA7g1Md7p
0"
}
]
}
Figure 71: JSON General Serialization
5. JSON Web Encryption Examples
The following sections demonstrate how to generate various JWE
objects.
All of the succeeding examples (unless otherwise noted) use the
following plaintext content (an abridged quote from "The Fellowship
Miller Expires May 17, 2015 [Page 37]
Internet-Draft JOSE Cookbook November 2014
of the Ring" [LOTR-FELLOWSHIP]), serialized as UTF-8. The sequence
"\xe2\x80\x93" is substituted for (U+2013 EN DASH), and line breaks
(U+000A LINE FEED) replace some instances of " " (U+0020 SPACE)
characters to improve formatting:
You can trust us to stick with you through thick and
thin\xe2\x80\x93to the bitter end. And you can trust us to
keep any secret of yours\xe2\x80\x93closer than you keep it
yourself. But you cannot trust us to let you face trouble
alone, and go off without a word. We are your friends, Frodo.
Figure 72: Plaintext content
5.1. Key Encryption using RSA v1.5 and AES-HMAC-SHA2
This example illustrates encrypting content using the "RSA1_5"
(RSAES-PKCS1-v1_5) key encryption algorithm and the "A128CBC-HS256"
(AES-128-CBC-HMAC-SHA-256) content encryption algorithm.
Note that RSAES-PKCS1-v1_5 uses random data to generate the
ciphertext; it might not be possible to exactly replicate the results
in this section.
Note that whitespace is added for readability as described in
Section 1.1.
5.1.1. Input Factors
The following are supplied before beginning the encryption process:
o Plaintext content; this example uses the content from Figure 72.
o RSA public key; this example uses the key from Figure 73.
o "alg" parameter of "RSA1_5".
o "enc" parameter of "A128CBC-HS256".
Miller Expires May 17, 2015 [Page 38]
Internet-Draft JOSE Cookbook November 2014
{
"kty": "RSA",
"kid": "frodo.baggins@hobbiton.example",
"use": "enc",
"n": "maxhbsmBtdQ3CNrKvprUE6n9lYcregDMLYNeTAWcLj8NnPU9XIYegT
HVHQjxKDSHP2l-F5jS7sppG1wgdAqZyhnWvXhYNvcM7RfgKxqNx_xAHx
6f3yy7s-M9PSNCwPC2lh6UAkR4I00EhV9lrypM9Pi4lBUop9t5fS9W5U
NwaAllhrd-osQGPjIeI1deHTwx-ZTHu3C60Pu_LJIl6hKn9wbwaUmA4c
R5Bd2pgbaY7ASgsjCUbtYJaNIHSoHXprUdJZKUMAzV0WOKPfA6OPI4oy
pBadjvMZ4ZAj3BnXaSYsEZhaueTXvZB4eZOAjIyh2e_VOIKVMsnDrJYA
VotGlvMQ",
"e": "AQAB",
"d": "Kn9tgoHfiTVi8uPu5b9TnwyHwG5dK6RE0uFdlpCGnJN7ZEi963R7wy
bQ1PLAHmpIbNTztfrheoAniRV1NCIqXaW_qS461xiDTp4ntEPnqcKsyO
5jMAji7-CL8vhpYYowNFvIesgMoVaPRYMYT9TW63hNM0aWs7USZ_hLg6
Oe1mY0vHTI3FucjSM86Nff4oIENt43r2fspgEPGRrdE6fpLc9Oaq-qeP
1GFULimrRdndm-P8q8kvN3KHlNAtEgrQAgTTgz80S-3VD0FgWfgnb1PN
miuPUxO8OpI9KDIfu_acc6fg14nsNaJqXe6RESvhGPH2afjHqSy_Fd2v
pzj85bQQ",
"p": "2DwQmZ43FoTnQ8IkUj3BmKRf5Eh2mizZA5xEJ2MinUE3sdTYKSLtaE
oekX9vbBZuWxHdVhM6UnKCJ_2iNk8Z0ayLYHL0_G21aXf9-unynEpUsH
7HHTklLpYAzOOx1ZgVljoxAdWNn3hiEFrjZLZGS7lOH-a3QQlDDQoJOJ
2VFmU",
"q": "te8LY4-W7IyaqH1ExujjMqkTAlTeRbv0VLQnfLY2xINnrWdwiQ93_V
F099aP1ESeLja2nw-6iKIe-qT7mtCPozKfVtUYfz5HrJ_XY2kfexJINb
9lhZHMv5p1skZpeIS-GPHCC6gRlKo1q-idn_qxyusfWv7WAxlSVfQfk8
d6Et0",
"dp": "UfYKcL_or492vVc0PzwLSplbg4L3-Z5wL48mwiswbpzOyIgd2xHTH
QmjJpFAIZ8q-zf9RmgJXkDrFs9rkdxPtAsL1WYdeCT5c125Fkdg317JV
RDo1inX7x2Kdh8ERCreW8_4zXItuTl_KiXZNU5lvMQjWbIw2eTx1lpsf
lo0rYU",
"dq": "iEgcO-QfpepdH8FWd7mUFyrXdnOkXJBCogChY6YKuIHGc_p8Le9Mb
pFKESzEaLlN1Ehf3B6oGBl5Iz_ayUlZj2IoQZ82znoUrpa9fVYNot87A
CfzIG7q9Mv7RiPAderZi03tkVXAdaBau_9vs5rS-7HMtxkVrxSUvJY14
TkXlHE",
"qi": "kC-lzZOqoFaZCr5l0tOVtREKoVqaAYhQiqIRGL-MzS4sCmRkxm5vZ
lXYx6RtE1n_AagjqajlkjieGlxTTThHD8Iga6foGBMaAr5uR1hGQpSc7
Gl7CF1DZkBJMTQN6EshYzZfxW08mIO8M6Rzuh0beL6fG9mkDcIyPrBXx
2bQ_mM"
}
Figure 73: RSA 2048-bit Key, in JWK format
(*NOTE*: While the key includes the private parameters, only the
public parameters "e" and "n" are necessary for the encryption
operation.)
Miller Expires May 17, 2015 [Page 39]
Internet-Draft JOSE Cookbook November 2014
5.1.2. Generated Factors
The following are generated before encrypting:
o AES symmetric key as the Content Encryption Key (CEK); this
example uses the key from Figure 74
o Initialization vector/nonce; this example uses the initialization
vector from Figure 75
3qyTVhIWt5juqZUCpfRqpvauwB956MEJL2Rt-8qXKSo
Figure 74: Content Encryption Key, base64url-encoded
bbd5sTkYwhAIqfHsx8DayA
Figure 75: Initialization Vector, base64url-encoded
5.1.3. Encrypting the Key
Performing the key encryption operation over the CEK (Figure 74) with
the RSA key (Figure 73) results in the following encrypted key:
laLxI0j-nLH-_BgLOXMozKxmy9gffy2gTdvqzfTihJBuuzxg0V7yk1WClnQePF
vG2K-pvSlWc9BRIazDrn50RcRai__3TDON395H3c62tIouJJ4XaRvYHFjZTZ2G
Xfz8YAImcc91Tfk0WXC2F5Xbb71ClQ1DDH151tlpH77f2ff7xiSxh9oSewYrcG
TSLUeeCt36r1Kt3OSj7EyBQXoZlN7IxbyhMAfgIe7Mv1rOTOI5I8NQqeXXW8Vl
zNmoxaGMny3YnGir5Wf6Qt2nBq4qDaPdnaAuuGUGEecelIO1wx1BpyIfgvfjOh
MBs9M8XL223Fg47xlGsMXdfuY-4jaqVw
Figure 76: Encrypted Key, base64url-encoded
5.1.4. Encrypting the Content
The following are generated before encrypting the plaintext:
o JWE Protected Header; this example uses the header from Figure 77,
encoded using [RFC4648] base64url to produce Figure 78.
{
"alg": "RSA1_5",
"kid": "frodo.baggins@hobbiton.example",
"enc": "A128CBC-HS256"
}
Figure 77: JWE Protected Header JSON
Miller Expires May 17, 2015 [Page 40]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJSU0ExXzUiLCJraWQiOiJmcm9kby5iYWdnaW5zQGhvYmJpdG9uLm
V4YW1wbGUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
Figure 78: JWE Protected Header, base64url-encoded
Performing the content encryption operation on the Plaintext
(Figure 72) using the following:
o CEK (Figure 74);
o Initialization vector/nonce (Figure 75); and
o JWE Protected Header (Figure 77) as authenticated data
produces the following:
o Ciphertext from Figure 79.
o Authentication tag from Figure 80.
0fys_TY_na7f8dwSfXLiYdHaA2DxUjD67ieF7fcVbIR62JhJvGZ4_FNVSiGc_r
aa0HnLQ6s1P2sv3Xzl1p1l_o5wR_RsSzrS8Z-wnI3Jvo0mkpEEnlDmZvDu_k8O
WzJv7eZVEqiWKdyVzFhPpiyQU28GLOpRc2VbVbK4dQKPdNTjPPEmRqcaGeTWZV
yeSUvf5k59yJZxRuSvWFf6KrNtmRdZ8R4mDOjHSrM_s8uwIFcqt4r5GX8TKaI0
zT5CbL5Qlw3sRc7u_hg0yKVOiRytEAEs3vZkcfLkP6nbXdC_PkMdNS-ohP78T2
O6_7uInMGhFeX4ctHG7VelHGiT93JfWDEQi5_V9UN1rhXNrYu-0fVMkZAKX3VW
i7lzA6BP430m
Figure 79: Ciphertext, base64url-encoded
kvKuFBXHe5mQr4lqgobAUg
Figure 80: Authentication Tag, base64url-encoded
5.1.5. Output Results
The following compose the resulting JWE object:
o JWE Protected Header (Figure 78).
o Encrypted Key (Figure 76).
o Initialization vector/nonce (Figure 75).
o Ciphertext (Figure 79).
o Authentication Tag (Figure 80).
Miller Expires May 17, 2015 [Page 41]
Internet-Draft JOSE Cookbook November 2014
The resulting JWE object using the Compact serialization:
eyJhbGciOiJSU0ExXzUiLCJraWQiOiJmcm9kby5iYWdnaW5zQGhvYmJpdG9uLm
V4YW1wbGUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0
.
laLxI0j-nLH-_BgLOXMozKxmy9gffy2gTdvqzfTihJBuuzxg0V7yk1WClnQePF
vG2K-pvSlWc9BRIazDrn50RcRai__3TDON395H3c62tIouJJ4XaRvYHFjZTZ2G
Xfz8YAImcc91Tfk0WXC2F5Xbb71ClQ1DDH151tlpH77f2ff7xiSxh9oSewYrcG
TSLUeeCt36r1Kt3OSj7EyBQXoZlN7IxbyhMAfgIe7Mv1rOTOI5I8NQqeXXW8Vl
zNmoxaGMny3YnGir5Wf6Qt2nBq4qDaPdnaAuuGUGEecelIO1wx1BpyIfgvfjOh
MBs9M8XL223Fg47xlGsMXdfuY-4jaqVw
.
bbd5sTkYwhAIqfHsx8DayA
.
0fys_TY_na7f8dwSfXLiYdHaA2DxUjD67ieF7fcVbIR62JhJvGZ4_FNVSiGc_r
aa0HnLQ6s1P2sv3Xzl1p1l_o5wR_RsSzrS8Z-wnI3Jvo0mkpEEnlDmZvDu_k8O
WzJv7eZVEqiWKdyVzFhPpiyQU28GLOpRc2VbVbK4dQKPdNTjPPEmRqcaGeTWZV
yeSUvf5k59yJZxRuSvWFf6KrNtmRdZ8R4mDOjHSrM_s8uwIFcqt4r5GX8TKaI0
zT5CbL5Qlw3sRc7u_hg0yKVOiRytEAEs3vZkcfLkP6nbXdC_PkMdNS-ohP78T2
O6_7uInMGhFeX4ctHG7VelHGiT93JfWDEQi5_V9UN1rhXNrYu-0fVMkZAKX3VW
i7lzA6BP430m
.
kvKuFBXHe5mQr4lqgobAUg
Figure 81: Compact Serialization
The resulting JWE object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 42]
Internet-Draft JOSE Cookbook November 2014
{
"recipients": [
{
"encrypted_key": "laLxI0j-nLH-_BgLOXMozKxmy9gffy2gTdvqzf
TihJBuuzxg0V7yk1WClnQePFvG2K-pvSlWc9BRIazDrn50RcRai_
_3TDON395H3c62tIouJJ4XaRvYHFjZTZ2GXfz8YAImcc91Tfk0WX
C2F5Xbb71ClQ1DDH151tlpH77f2ff7xiSxh9oSewYrcGTSLUeeCt
36r1Kt3OSj7EyBQXoZlN7IxbyhMAfgIe7Mv1rOTOI5I8NQqeXXW8
VlzNmoxaGMny3YnGir5Wf6Qt2nBq4qDaPdnaAuuGUGEecelIO1wx
1BpyIfgvfjOhMBs9M8XL223Fg47xlGsMXdfuY-4jaqVw"
}
],
"protected": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiJmcm9kby5iYWdnaW
5zQGhvYmJpdG9uLmV4YW1wbGUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In
0",
"iv": "bbd5sTkYwhAIqfHsx8DayA",
"ciphertext": "0fys_TY_na7f8dwSfXLiYdHaA2DxUjD67ieF7fcVbIR62
JhJvGZ4_FNVSiGc_raa0HnLQ6s1P2sv3Xzl1p1l_o5wR_RsSzrS8Z-wn
I3Jvo0mkpEEnlDmZvDu_k8OWzJv7eZVEqiWKdyVzFhPpiyQU28GLOpRc
2VbVbK4dQKPdNTjPPEmRqcaGeTWZVyeSUvf5k59yJZxRuSvWFf6KrNtm
RdZ8R4mDOjHSrM_s8uwIFcqt4r5GX8TKaI0zT5CbL5Qlw3sRc7u_hg0y
KVOiRytEAEs3vZkcfLkP6nbXdC_PkMdNS-ohP78T2O6_7uInMGhFeX4c
tHG7VelHGiT93JfWDEQi5_V9UN1rhXNrYu-0fVMkZAKX3VWi7lzA6BP4
30m",
"tag": "kvKuFBXHe5mQr4lqgobAUg"
}
Figure 82: JSON General Serialization
The resulting JWE object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 43]
Internet-Draft JOSE Cookbook November 2014
{
"protected": "eyJhbGciOiJSU0ExXzUiLCJraWQiOiJmcm9kby5iYWdnaW
5zQGhvYmJpdG9uLmV4YW1wbGUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In
0",
"encrypted_key": "laLxI0j-nLH-_BgLOXMozKxmy9gffy2gTdvqzfTihJ
Buuzxg0V7yk1WClnQePFvG2K-pvSlWc9BRIazDrn50RcRai__3TDON39
5H3c62tIouJJ4XaRvYHFjZTZ2GXfz8YAImcc91Tfk0WXC2F5Xbb71ClQ
1DDH151tlpH77f2ff7xiSxh9oSewYrcGTSLUeeCt36r1Kt3OSj7EyBQX
oZlN7IxbyhMAfgIe7Mv1rOTOI5I8NQqeXXW8VlzNmoxaGMny3YnGir5W
f6Qt2nBq4qDaPdnaAuuGUGEecelIO1wx1BpyIfgvfjOhMBs9M8XL223F
g47xlGsMXdfuY-4jaqVw",
"iv": "bbd5sTkYwhAIqfHsx8DayA",
"ciphertext": "0fys_TY_na7f8dwSfXLiYdHaA2DxUjD67ieF7fcVbIR62
JhJvGZ4_FNVSiGc_raa0HnLQ6s1P2sv3Xzl1p1l_o5wR_RsSzrS8Z-wn
I3Jvo0mkpEEnlDmZvDu_k8OWzJv7eZVEqiWKdyVzFhPpiyQU28GLOpRc
2VbVbK4dQKPdNTjPPEmRqcaGeTWZVyeSUvf5k59yJZxRuSvWFf6KrNtm
RdZ8R4mDOjHSrM_s8uwIFcqt4r5GX8TKaI0zT5CbL5Qlw3sRc7u_hg0y
KVOiRytEAEs3vZkcfLkP6nbXdC_PkMdNS-ohP78T2O6_7uInMGhFeX4c
tHG7VelHGiT93JfWDEQi5_V9UN1rhXNrYu-0fVMkZAKX3VWi7lzA6BP4
30m",
"tag": "kvKuFBXHe5mQr4lqgobAUg"
}
Figure 83: JSON Flattened Serialization
5.2. Key Encryption using RSA-OAEP with A256GCM
This example illustrates encrypting content using the "RSA-OAEP"
(RSAES-OAEP) key encryption algorithm and the "A256GCM" (AES-GCM)
content encryption algorithm.
Note that RSAES-OAEP uses random data to generate the ciphertext; it
might not be possible to exactly replicate the results in this
section.
Note that whitespace is added for readability as described in
Section 1.1.
5.2.1. Input Factors
The following are supplied before beginning the encryption process:
o Plaintext content; this example uses the plaintext from Figure 72.
o RSA public key; this example uses the key from Figure 84.
o "alg" parameter of "RSA-OAEP"
Miller Expires May 17, 2015 [Page 44]
Internet-Draft JOSE Cookbook November 2014
o "enc" parameter of "A256GCM"
{
"kty": "RSA",
"kid": "samwise.gamgee@hobbiton.example",
"use": "enc",
"n": "wbdxI55VaanZXPY29Lg5hdmv2XhvqAhoxUkanfzf2-5zVUxa6prHRr
I4pP1AhoqJRlZfYtWWd5mmHRG2pAHIlh0ySJ9wi0BioZBl1XP2e-C-Fy
XJGcTy0HdKQWlrfhTm42EW7Vv04r4gfao6uxjLGwfpGrZLarohiWCPnk
Nrg71S2CuNZSQBIPGjXfkmIy2tl_VWgGnL22GplyXj5YlBLdxXp3XeSt
sqo571utNfoUTU8E4qdzJ3U1DItoVkPGsMwlmmnJiwA7sXRItBCivR4M
5qnZtdw-7v4WuR4779ubDuJ5nalMv2S66-RPcnFAzWSKxtBDnFJJDGIU
e7Tzizjg1nms0Xq_yPub_UOlWn0ec85FCft1hACpWG8schrOBeNqHBOD
FskYpUc2LC5JA2TaPF2dA67dg1TTsC_FupfQ2kNGcE1LgprxKHcVWYQb
86B-HozjHZcqtauBzFNV5tbTuB-TpkcvJfNcFLlH3b8mb-H_ox35FjqB
SAjLKyoeqfKTpVjvXhd09knwgJf6VKq6UC418_TOljMVfFTWXUxlnfhO
OnzW6HSSzD1c9WrCuVzsUMv54szidQ9wf1cYWf3g5qFDxDQKis99gcDa
iCAwM3yEBIzuNeeCa5dartHDb1xEB_HcHSeYbghbMjGfasvKn0aZRsnT
yC0xhWBlsolZE",
"e": "AQAB",
"alg": "RSA-OAEP",
"d": "n7fzJc3_WG59VEOBTkayzuSMM780OJQuZjN_KbH8lOZG25ZoA7T4Bx
cc0xQn5oZE5uSCIwg91oCt0JvxPcpmqzaJZg1nirjcWZ-oBtVk7gCAWq
-B3qhfF3izlbkosrzjHajIcY33HBhsy4_WerrXg4MDNE4HYojy68TcxT
2LYQRxUOCf5TtJXvM8olexlSGtVnQnDRutxEUCwiewfmmrfveEogLx9E
A-KMgAjTiISXxqIXQhWUQX1G7v_mV_Hr2YuImYcNcHkRvp9E7ook0876
DhkO8v4UOZLwA1OlUX98mkoqwc58A_Y2lBYbVx1_s5lpPsEqbbH-nqIj
h1fL0gdNfihLxnclWtW7pCztLnImZAyeCWAG7ZIfv-Rn9fLIv9jZ6r7r
-MSH9sqbuziHN2grGjD_jfRluMHa0l84fFKl6bcqN1JWxPVhzNZo01yD
F-1LiQnqUYSepPf6X3a2SOdkqBRiquE6EvLuSYIDpJq3jDIsgoL8Mo1L
oomgiJxUwL_GWEOGu28gplyzm-9Q0U0nyhEf1uhSR8aJAQWAiFImWH5W
_IQT9I7-yrindr_2fWQ_i1UgMsGzA7aOGzZfPljRy6z-tY_KuBG00-28
S_aWvjyUc-Alp8AUyKjBZ-7CWH32fGWK48j1t-zomrwjL_mnhsPbGs0c
9WsWgRzI-K8gE",
"p": "7_2v3OQZzlPFcHyYfLABQ3XP85Es4hCdwCkbDeltaUXgVy9l9etKgh
vM4hRkOvbb01kYVuLFmxIkCDtpi-zLCYAdXKrAK3PtSbtzld_XZ9nlsY
a_QZWpXB_IrtFjVfdKUdMz94pHUhFGFj7nr6NNxfpiHSHWFE1zD_AC3m
Y46J961Y2LRnreVwAGNw53p07Db8yD_92pDa97vqcZOdgtybH9q6uma-
RFNhO1AoiJhYZj69hjmMRXx-x56HO9cnXNbmzNSCFCKnQmn4GQLmRj9s
fbZRqL94bbtE4_e0Zrpo8RNo8vxRLqQNwIy85fc6BRgBJomt8QdQvIgP
gWCv5HoQ",
"q": "zqOHk1P6WN_rHuM7ZF1cXH0x6RuOHq67WuHiSknqQeefGBA9PWs6Zy
KQCO-O6mKXtcgE8_Q_hA2kMRcKOcvHil1hqMCNSXlflM7WPRPZu2qCDc
qssd_uMbP-DqYthH_EzwL9KnYoH7JQFxxmcv5An8oXUtTwk4knKjkIYG
RuUwfQTus0w1NfjFAyxOOiAQ37ussIcE6C6ZSsM3n41UlbJ7TCqewzVJ
aPJN5cxjySPZPD3Vp01a9YgAD6a3IIaKJdIxJS1ImnfPevSJQBE79-EX
e2kSwVgOzvt-gsmM29QQ8veHy4uAqca5dZzMs7hkkHtw1z0jHV90epQJ
JlXXnH8Q",
Miller Expires May 17, 2015 [Page 45]
Internet-Draft JOSE Cookbook November 2014
"dp": "19oDkBh1AXelMIxQFm2zZTqUhAzCIr4xNIGEPNoDt1jK83_FJA-xn
x5kA7-1erdHdms_Ef67HsONNv5A60JaR7w8LHnDiBGnjdaUmmuO8XAxQ
J_ia5mxjxNjS6E2yD44USo2JmHvzeeNczq25elqbTPLhUpGo1IZuG72F
ZQ5gTjXoTXC2-xtCDEUZfaUNh4IeAipfLugbpe0JAFlFfrTDAMUFpC3i
XjxqzbEanflwPvj6V9iDSgjj8SozSM0dLtxvu0LIeIQAeEgT_yXcrKGm
pKdSO08kLBx8VUjkbv_3Pn20Gyu2YEuwpFlM_H1NikuxJNKFGmnAq9Lc
nwwT0jvoQ",
"dq": "S6p59KrlmzGzaQYQM3o0XfHCGvfqHLYjCO557HYQf72O9kLMCfd_1
VBEqeD-1jjwELKDjck8kOBl5UvohK1oDfSP1DleAy-cnmL29DqWmhgwM
1ip0CCNmkmsmDSlqkUXDi6sAaZuntyukyflI-qSQ3C_BafPyFaKrt1fg
dyEwYa08pESKwwWisy7KnmoUvaJ3SaHmohFS78TJ25cfc10wZ9hQNOrI
ChZlkiOdFCtxDqdmCqNacnhgE3bZQjGp3n83ODSz9zwJcSUvODlXBPc2
AycH6Ci5yjbxt4Ppox_5pjm6xnQkiPgj01GpsUssMmBN7iHVsrE7N2iz
nBNCeOUIQ",
"qi": "FZhClBMywVVjnuUud-05qd5CYU0dK79akAgy9oX6RX6I3IIIPckCc
iRrokxglZn-omAY5CnCe4KdrnjFOT5YUZE7G_Pg44XgCXaarLQf4hl80
oPEf6-jJ5Iy6wPRx7G2e8qLxnh9cOdf-kRqgOS3F48Ucvw3ma5V6KGMw
QqWFeV31XtZ8l5cVI-I3NzBS7qltpUVgz2Ju021eyc7IlqgzR98qKONl
27DuEES0aK0WE97jnsyO27Yp88Wa2RiBrEocM89QZI1seJiGDizHRUP4
UZxw9zsXww46wy0P6f9grnYp7t8LkyDDk8eoI4KX6SNMNVcyVS9IWjlq
8EzqZEKIA"
}
Figure 84: RSA 4096-bit Key
(*NOTE*: While the key includes the private parameters, only the
public parameters "e" and "n" are necessary for the encryption
operation.)
5.2.2. Generated Factors
The following are generated before encrypting:
o AES symmetric key as the Content Encryption CEK (CEK); this
example uses the key from Figure 85.
o Initialization vector/nonce; this example uses the initialization
vector/nonce from Figure 86.
mYMfsggkTAm0TbvtlFh2hyoXnbEzJQjMxmgLN3d8xXA
Figure 85: Content Encryption Key, base64url-encoded
-nBoKLH0YkLZPSI9
Figure 86: Initialization Vector, base64url-encoded
Miller Expires May 17, 2015 [Page 46]
Internet-Draft JOSE Cookbook November 2014
Internet-Draft DNS Stateful Operations June 2018
7.2.2. Retry Delay TLV used as a Response Additional TLV
In the case of a request that returns a nonzero RCODE value, the
responder MAY append a Retry Delay TLV to the response, indicating
the time interval during which the initiator SHOULD NOT attempt this
operation again.
The indicated time interval during which the initiator SHOULD NOT
retry applies only to the failed operation, not to the DSO Session as
a whole.
7.3. Encryption Padding TLV
The Encryption Padding TLV (DSO-TYPE=3) can only be used as an
Additional or Response Additional TLV. It is only applicable when
the DSO Transport layer uses encryption such as TLS.
The DSO-DATA for the the Padding TLV is optional and is a variable
length field containing non-specified values. A DSO-LENGTH of 0
essentially provides for 4 bytes of padding (the minimum amount).
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
/ /
/ VARIABLE NUMBER OF BYTES /
/ /
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
As specified for the EDNS(0) Padding Option [RFC7830] the PADDING
bytes SHOULD be set to 0x00. Other values MAY be used, for example,
in cases where there is a concern that the padded message could be
subject to compression before encryption. PADDING bytes of any value
MUST be accepted in the messages received.
The Encryption Padding TLV may be included in either a DSO request,
response, or both. As specified for the EDNS(0) Padding Option
[RFC7830] if a request is received with an Encryption Padding TLV,
then the response MUST also include an Encryption Padding TLV.
The length of padding is intentionally not specified in this document
and is a function of current best practices with respect to the type
and length of data in the preceding TLVs
[I-D.ietf-dprive-padding-policy].
Bellis, et al. Expires December 9, 2018 [Page 44]
Internet-Draft DNS Stateful Operations June 2018
8. Summary Highlights
This section summarizes some noteworthy highlights about various
components of the DSO protocol.
8.1. QR bit and MESSAGE ID
In DSO Request Messages the QR bit is 0 and the MESSAGE ID is
nonzero.
In DSO Response Messages the QR bit is 1 and the MESSAGE ID is
nonzero.
In DSO Unacknowledged Messages the QR bit is 0 and the MESSAGE ID is
zero.
The table below illustrates which combinations are legal and how they
are interpreted:
+--------------------------+------------------------+
| MESSAGE ID zero | MESSAGE ID nonzero |
+--------+--------------------------+------------------------+
| QR=0 | Unacknowledged Message | Request Message |
+--------+--------------------------+------------------------+
| QR=1 | Invalid - Fatal Error | Response Message |
+--------+--------------------------+------------------------+
Bellis, et al. Expires December 9, 2018 [Page 45]
Internet-Draft DNS Stateful Operations June 2018
8.2. TLV Usage
The table below indicates, for each of the three TLVs defined in this
document, whether they are valid in each of ten different contexts.
The first five contexts are requests or unacknowledged messages from
client to server, and the corresponding responses from server back to
client:
o C-P - Primary TLV, sent in DSO Request message, from client to
server, with nonzero MESSAGE ID indicating that this request MUST
generate response message.
o C-U - Primary TLV, sent in DSO Unacknowledged message, from client
to server, with zero MESSAGE ID indicating that this request MUST
NOT generate response message.
o C-A - Additional TLV, optionally added to request message or
unacknowledged message from client to server.
o CRP - Response Primary TLV, included in response message sent back
to the client (in response to a client "C-P" request with nonzero
MESSAGE ID indicating that a response is required) where the DSO-
TYPE of the Response TLV matches the DSO-TYPE of the Primary TLV
in the request.
o CRA - Response Additional TLV, included in response message sent
back to the client (in response to a client "C-P" request with
nonzero MESSAGE ID indicating that a response is required) where
the DSO-TYPE of the Response TLV does not match the DSO-TYPE of
the Primary TLV in the request.
The second five contexts are their counterparts in the opposite
direction: requests or unacknowledged messages from server to client,
and the corresponding responses from client back to server.
+-------------------------+-------------------------+
| C-P C-U C-A CRP CRA | S-P S-U S-A SRP SRA |
+------------+-------------------------+-------------------------+
| KeepAlive | X X | X |
+------------+-------------------------+-------------------------+
| RetryDelay | X | X |
+------------+-------------------------+-------------------------+
| Padding | X X | X X |
+------------+-------------------------+-------------------------+
Note that some of the columns in this table are currently empty. The
table provides a template for future TLV definitions to follow. It
Bellis, et al. Expires December 9, 2018 [Page 46]
Internet-Draft DNS Stateful Operations June 2018
is recommended that definitions of future TLVs include a similar
table summarizing the contexts where the new TLV is valid.
Bellis, et al. Expires December 9, 2018 [Page 47]
Internet-Draft DNS Stateful Operations June 2018
9. IANA Considerations
9.1. DSO OPCODE Registration
The IANA is requested to record the value ([TBA1] tentatively) 6 for
the DSO OPCODE in the DNS OPCODE Registry. DSO stands for DNS
Stateful Operations.
9.2. DSO RCODE Registration
The IANA is requested to record the value ([TBA2] tentatively) 11 for
the DSOTYPENI error code in the DNS RCODE Registry. The DSOTYPENI
error code ("DSO-TYPE Not Implemented") indicates that the receiver
does implement DNS Stateful Operations, but does not implement the
specific DSO-TYPE of the primary TLV in the DSO request message.
9.3. DSO Type Code Registry
The IANA is requested to create the 16-bit DSO Type Code Registry,
with initial (hexadecimal) values as shown below:
+-----------+--------------------------------+----------+-----------+
| Type | Name | Status | Reference |
+-----------+--------------------------------+----------+-----------+
| 0000 | Reserved | Standard | RFC-TBD |
| | | | |
| 0001 | KeepAlive | Standard | RFC-TBD |
| | | | |
| 0002 | RetryDelay | Standard | RFC-TBD |
| | | | |
| 0003 | EncryptionPadding | Standard | RFC-TBD |
| | | | |
| 0004-003F | Unassigned, reserved for | | |
| | DSO session-management TLVs | | |
| | | | |
| 0040-F7FF | Unassigned | | |
| | | | |
| F800-FBFF | Reserved for | | |
| | experimental/local use | | |
| | | | |
| FC00-FFFF | Reserved for future expansion | | |
+-----------+--------------------------------+----------+-----------+
DSO Type Code zero is reserved and is not currently intended for
allocation.
Registrations of new DSO Type Codes in the "Reserved for DSO session-
management" range 0004-003F and the "Reserved for future expansion"
Bellis, et al. Expires December 9, 2018 [Page 48]
Internet-Draft DNS Stateful Operations June 2018
range FC00-FFFF require publication of an IETF Standards Action
document [RFC8126].
Requests to register additional new DSO Type Codes in the
"Unassigned" range 0040-F7FF are to be recorded by IANA after Expert
Review [RFC8126]. At the time of publication of this document, the
Designated Expert for the newly created DSO Type Code registry is
[*TBD*].
DSO Type Codes in the "experimental/local" range F800-FBFF may be
used as Experimental Use or Private Use values [RFC8126] and may be
used freely for development purposes, or for other purposes within a
single site. No attempt is made to prevent multiple sites from using
the same value in different (and incompatible) ways. There is no
need for IANA to review such assignments (since IANA does not record
them) and assignments are not generally useful for broad
interoperability. It is the responsibility of the sites making use
of "experimental/local" values to ensure that no conflicts occur
within the intended scope of use.
10. Security Considerations
If this mechanism is to be used with DNS over TLS, then these
messages are subject to the same constraints as any other DNS-over-
TLS messages and MUST NOT be sent in the clear before the TLS session
is established.
The data field of the "Encryption Padding" TLV could be used as a
covert channel.
When designing new DSO TLVs, the potential for data in the TLV to be
used as a tracking identifier should be taken into consideration, and
should be avoided when not required.
When used without TLS or similar cryptographic protection, a
malicious entity maybe able to inject a malicious Retry Delay
Unacknowledged Message into the data stream, specifying an
unreasonably large RETRY DELAY, causing a denial-of-service attack
against the client.
11. Acknowledgements
Thanks to Stephane Bortzmeyer, Tim Chown, Ralph Droms, Paul Hoffman,
Jan Komissar, Edward Lewis, Allison Mankin, Rui Paulo, David
Schinazi, Manju Shankar Rao, and Bernie Volz for their helpful
contributions to this document.
Bellis, et al. Expires December 9, 2018 [Page 49]
Internet-Draft DNS Stateful Operations June 2018
12. References
12.1. Normative References
[RFC1034] Mockapetris, P., "Domain names - concepts and facilities",
STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987,
<https://www.rfc-editor.org/info/rfc1034>.
[RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
November 1987, <https://www.rfc-editor.org/info/rfc1035>.
[RFC1918] Rekhter, Y., Moskowitz, B., Karrenberg, D., de Groot, G.,
and E. Lear, "Address Allocation for Private Internets",
BCP 5, RFC 1918, DOI 10.17487/RFC1918, February 1996,
<https://www.rfc-editor.org/info/rfc1918>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
Extensions", RFC 2132, DOI 10.17487/RFC2132, March 1997,
<https://www.rfc-editor.org/info/rfc2132>.
[RFC2136] Vixie, P., Ed., Thomson, S., Rekhter, Y., and J. Bound,
"Dynamic Updates in the Domain Name System (DNS UPDATE)",
RFC 2136, DOI 10.17487/RFC2136, April 1997,
<https://www.rfc-editor.org/info/rfc2136>.
[RFC5382] Guha, S., Ed., Biswas, K., Ford, B., Sivakumar, S., and P.
Srisuresh, "NAT Behavioral Requirements for TCP", BCP 142,
RFC 5382, DOI 10.17487/RFC5382, October 2008,
<https://www.rfc-editor.org/info/rfc5382>.
[RFC6891] Damas, J., Graff, M., and P. Vixie, "Extension Mechanisms
for DNS (EDNS(0))", STD 75, RFC 6891,
DOI 10.17487/RFC6891, April 2013,
<https://www.rfc-editor.org/info/rfc6891>.
[RFC7766] Dickinson, J., Dickinson, S., Bellis, R., Mankin, A., and
D. Wessels, "DNS Transport over TCP - Implementation
Requirements", RFC 7766, DOI 10.17487/RFC7766, March 2016,
<https://www.rfc-editor.org/info/rfc7766>.
Bellis, et al. Expires December 9, 2018 [Page 50]
Internet-Draft DNS Stateful Operations June 2018
[RFC7828] Wouters, P., Abley, J., Dickinson, S., and R. Bellis, "The
edns-tcp-keepalive EDNS0 Option", RFC 7828,
DOI 10.17487/RFC7828, April 2016,
<https://www.rfc-editor.org/info/rfc7828>.
[RFC7830] Mayrhofer, A., "The EDNS(0) Padding Option", RFC 7830,
DOI 10.17487/RFC7830, May 2016,
<https://www.rfc-editor.org/info/rfc7830>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
12.2. Informative References
[I-D.ietf-dnssd-mdns-relay]
Lemon, T. and S. Cheshire, "Multicast DNS Discovery
Relay", draft-ietf-dnssd-mdns-relay-00 (work in progress),
May 2018.
[I-D.ietf-dnssd-push]
Pusateri, T. and S. Cheshire, "DNS Push Notifications",
draft-ietf-dnssd-push-14 (work in progress), March 2018.
[I-D.ietf-dprive-padding-policy]
Mayrhofer, A., "Padding Policy for EDNS(0)", draft-ietf-
dprive-padding-policy-05 (work in progress), April 2018.
[I-D.ietf-tls-tls13]
Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", draft-ietf-tls-tls13-28 (work in progress),
March 2018.
[NagleDA] Cheshire, S., "TCP Performance problems caused by
interaction between Nagle's Algorithm and Delayed ACK",
May 2005,
<http://www.stuartcheshire.org/papers/nagledelayedack/>.
[RFC0768] Postel, J., "User Datagram Protocol", STD 6, RFC 768,
DOI 10.17487/RFC0768, August 1980,
<https://www.rfc-editor.org/info/rfc768>.
Bellis, et al. Expires December 9, 2018 [Page 51]
Internet-Draft DNS Stateful Operations June 2018
[RFC1122] Braden, R., Ed., "Requirements for Internet Hosts -
Communication Layers", STD 3, RFC 1122,
DOI 10.17487/RFC1122, October 1989,
<https://www.rfc-editor.org/info/rfc1122>.
[RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for
specifying the location of services (DNS SRV)", RFC 2782,
DOI 10.17487/RFC2782, February 2000,
<https://www.rfc-editor.org/info/rfc2782>.
[RFC6335] Cotton, M., Eggert, L., Touch, J., Westerlund, M., and S.
Cheshire, "Internet Assigned Numbers Authority (IANA)
Procedures for the Management of the Service Name and
Transport Protocol Port Number Registry", BCP 165,
RFC 6335, DOI 10.17487/RFC6335, August 2011,
<https://www.rfc-editor.org/info/rfc6335>.
[RFC6762] Cheshire, S. and M. Krochmal, "Multicast DNS", RFC 6762,
DOI 10.17487/RFC6762, February 2013,
<https://www.rfc-editor.org/info/rfc6762>.
[RFC6763] Cheshire, S. and M. Krochmal, "DNS-Based Service
Discovery", RFC 6763, DOI 10.17487/RFC6763, February 2013,
<https://www.rfc-editor.org/info/rfc6763>.
[RFC7413] Cheng, Y., Chu, J., Radhakrishnan, S., and A. Jain, "TCP
Fast Open", RFC 7413, DOI 10.17487/RFC7413, December 2014,
<https://www.rfc-editor.org/info/rfc7413>.
[RFC7858] Hu, Z., Zhu, L., Heidemann, J., Mankin, A., Wessels, D.,
and P. Hoffman, "Specification for DNS over Transport
Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May
2016, <https://www.rfc-editor.org/info/rfc7858>.
Authors' Addresses
Ray Bellis
Internet Systems Consortium, Inc.
950 Charter Street
Redwood City CA 94063
USA
Phone: +1 (650) 423-1200
Email: ray@isc.org
Bellis, et al. Expires December 9, 2018 [Page 52]
Internet-Draft DNS Stateful Operations June 2018
Stuart Cheshire
Apple Inc.
One Apple Park Way
Cupertino CA 95014
USA
Phone: +1 (408) 996-1010
Email: cheshire@apple.com
John Dickinson
Sinodun Internet Technologies
Magadalen Centre
Oxford Science Park
Oxford OX4 4GA
United Kingdom
Email: jad@sinodun.com
Sara Dickinson
Sinodun Internet Technologies
Magadalen Centre
Oxford Science Park
Oxford OX4 4GA
United Kingdom
Email: sara@sinodun.com
Ted Lemon
Barefoot Consulting
Brattleboro
VT 05301
USA
Email: mellon@fugue.com
Tom Pusateri
Unaffiliated
Raleigh NC 27608
USA
Phone: +1 (919) 867-1330
Email: pusateri@bangj.com
5.2.3. Encrypting the Key
Performing the key encryption operation over the CEK (Figure 85))
with the RSA key (Figure 84) produces the following encrypted key:
rT99rwrBTbTI7IJM8fU3Eli7226HEB7IchCxNuh7lCiud48LxeolRdtFF4nzQi
beYOl5S_PJsAXZwSXtDePz9hk-BbtsTBqC2UsPOdwjC9NhNupNNu9uHIVftDyu
cvI6hvALeZ6OGnhNV4v1zx2k7O1D89mAzfw-_kT3tkuorpDU-CpBENfIHX1Q58
-Aad3FzMuo3Fn9buEP2yXakLXYa15BUXQsupM4A1GD4_H4Bd7V3u9h8Gkg8Bpx
KdUV9ScfJQTcYm6eJEBz3aSwIaK4T3-dwWpuBOhROQXBosJzS1asnuHtVMt2pK
IIfux5BC6huIvmY7kzV7W7aIUrpYm_3H4zYvyMeq5pGqFmW2k8zpO878TRlZx7
pZfPYDSXZyS0CfKKkMozT_qiCwZTSz4duYnt8hS4Z9sGthXn9uDqd6wycMagnQ
fOTs_lycTWmY-aqWVDKhjYNRf03NiwRtb5BE-tOdFwCASQj3uuAgPGrO2AWBe3
8UjQb0lvXn1SpyvYZ3WFc7WOJYaTa7A8DRn6MC6T-xDmMuxC0G7S2rscw5lQQU
06MvZTlFOt0UvfuKBa03cxA_nIBIhLMjY2kOTxQMmpDPTr6Cbo8aKaOnx6ASE5
Jx9paBpnNmOOKH35j_QlrQhDWUN6A2Gg8iFayJ69xDEdHAVCGRzN3woEI2ozDR
s
Figure 87: Encrypted Key, base64url-encoded
5.2.4. Encrypting the Content
The following are generated before encrypting the plaintext:
o JWE Protected Header; this example uses the the header from
Figure 88, encoded using [RFC4648] base64url to produce Figure 89.
{
"alg": "RSA-OAEP",
"kid": "samwise.gamgee@hobbiton.example",
"enc": "A256GCM"
}
Figure 88: JWE Protected Header JSON
eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InNhbXdpc2UuZ2FtZ2VlQGhvYmJpdG
9uLmV4YW1wbGUiLCJlbmMiOiJBMjU2R0NNIn0
Figure 89: JWE Protected Header, base64url-encoded
Performing the content encryption operation over the Plaintext
(Figure 72) with the following:
o CEK (Figure 85);
o Initialization vector/nonce (Figure 86); and
o JWE Protected Header (Figure 89) as authenticated data
Miller Expires May 17, 2015 [Page 47]
Internet-Draft JOSE Cookbook November 2014
produces the following:
o Ciphertext from Figure 90.
o Authentication tag from Figure 91.
o4k2cnGN8rSSw3IDo1YuySkqeS_t2m1GXklSgqBdpACm6UJuJowOHC5ytjqYgR
L-I-soPlwqMUf4UgRWWeaOGNw6vGW-xyM01lTYxrXfVzIIaRdhYtEMRBvBWbEw
P7ua1DRfvaOjgZv6Ifa3brcAM64d8p5lhhNcizPersuhw5f-pGYzseva-TUaL8
iWnctc-sSwy7SQmRkfhDjwbz0fz6kFovEgj64X1I5s7E6GLp5fnbYGLa1QUiML
7Cc2GxgvI7zqWo0YIEc7aCflLG1-8BboVWFdZKLK9vNoycrYHumwzKluLWEbSV
maPpOslY2n525DxDfWaVFUfKQxMF56vn4B9QMpWAbnypNimbM8zVOw
Figure 90: Ciphertext, base64url-encoded
UCGiqJxhBI3IFVdPalHHvA
Figure 91: Authentication Tag, base64url-encoded
5.2.5. Output Results
The following compose the resulting JWE object:
o JWE Protected Header (Figure 89)
o Encrypted key (Figure 87)
o Initialization vector/nonce (Figure 86)
o Ciphertext (Figure 90)
o Authentication tag (Figure 91)
The resulting JWE object using the Compact serialization:
Miller Expires May 17, 2015 [Page 48]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InNhbXdpc2UuZ2FtZ2VlQGhvYmJpdG
9uLmV4YW1wbGUiLCJlbmMiOiJBMjU2R0NNIn0
.
rT99rwrBTbTI7IJM8fU3Eli7226HEB7IchCxNuh7lCiud48LxeolRdtFF4nzQi
beYOl5S_PJsAXZwSXtDePz9hk-BbtsTBqC2UsPOdwjC9NhNupNNu9uHIVftDyu
cvI6hvALeZ6OGnhNV4v1zx2k7O1D89mAzfw-_kT3tkuorpDU-CpBENfIHX1Q58
-Aad3FzMuo3Fn9buEP2yXakLXYa15BUXQsupM4A1GD4_H4Bd7V3u9h8Gkg8Bpx
KdUV9ScfJQTcYm6eJEBz3aSwIaK4T3-dwWpuBOhROQXBosJzS1asnuHtVMt2pK
IIfux5BC6huIvmY7kzV7W7aIUrpYm_3H4zYvyMeq5pGqFmW2k8zpO878TRlZx7
pZfPYDSXZyS0CfKKkMozT_qiCwZTSz4duYnt8hS4Z9sGthXn9uDqd6wycMagnQ
fOTs_lycTWmY-aqWVDKhjYNRf03NiwRtb5BE-tOdFwCASQj3uuAgPGrO2AWBe3
8UjQb0lvXn1SpyvYZ3WFc7WOJYaTa7A8DRn6MC6T-xDmMuxC0G7S2rscw5lQQU
06MvZTlFOt0UvfuKBa03cxA_nIBIhLMjY2kOTxQMmpDPTr6Cbo8aKaOnx6ASE5
Jx9paBpnNmOOKH35j_QlrQhDWUN6A2Gg8iFayJ69xDEdHAVCGRzN3woEI2ozDR
s
.
-nBoKLH0YkLZPSI9
.
o4k2cnGN8rSSw3IDo1YuySkqeS_t2m1GXklSgqBdpACm6UJuJowOHC5ytjqYgR
L-I-soPlwqMUf4UgRWWeaOGNw6vGW-xyM01lTYxrXfVzIIaRdhYtEMRBvBWbEw
P7ua1DRfvaOjgZv6Ifa3brcAM64d8p5lhhNcizPersuhw5f-pGYzseva-TUaL8
iWnctc-sSwy7SQmRkfhDjwbz0fz6kFovEgj64X1I5s7E6GLp5fnbYGLa1QUiML
7Cc2GxgvI7zqWo0YIEc7aCflLG1-8BboVWFdZKLK9vNoycrYHumwzKluLWEbSV
maPpOslY2n525DxDfWaVFUfKQxMF56vn4B9QMpWAbnypNimbM8zVOw
.
UCGiqJxhBI3IFVdPalHHvA
Figure 92: Compact Serialization
The resulting JWE object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 49]
Internet-Draft JOSE Cookbook November 2014
{
"recipients": [
{
"encrypted_key": "rT99rwrBTbTI7IJM8fU3Eli7226HEB7IchCxNu
h7lCiud48LxeolRdtFF4nzQibeYOl5S_PJsAXZwSXtDePz9hk-Bb
tsTBqC2UsPOdwjC9NhNupNNu9uHIVftDyucvI6hvALeZ6OGnhNV4
v1zx2k7O1D89mAzfw-_kT3tkuorpDU-CpBENfIHX1Q58-Aad3FzM
uo3Fn9buEP2yXakLXYa15BUXQsupM4A1GD4_H4Bd7V3u9h8Gkg8B
pxKdUV9ScfJQTcYm6eJEBz3aSwIaK4T3-dwWpuBOhROQXBosJzS1
asnuHtVMt2pKIIfux5BC6huIvmY7kzV7W7aIUrpYm_3H4zYvyMeq
5pGqFmW2k8zpO878TRlZx7pZfPYDSXZyS0CfKKkMozT_qiCwZTSz
4duYnt8hS4Z9sGthXn9uDqd6wycMagnQfOTs_lycTWmY-aqWVDKh
jYNRf03NiwRtb5BE-tOdFwCASQj3uuAgPGrO2AWBe38UjQb0lvXn
1SpyvYZ3WFc7WOJYaTa7A8DRn6MC6T-xDmMuxC0G7S2rscw5lQQU
06MvZTlFOt0UvfuKBa03cxA_nIBIhLMjY2kOTxQMmpDPTr6Cbo8a
KaOnx6ASE5Jx9paBpnNmOOKH35j_QlrQhDWUN6A2Gg8iFayJ69xD
EdHAVCGRzN3woEI2ozDRs"
}
],
"protected": "eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InNhbXdpc2UuZ2
FtZ2VlQGhvYmJpdG9uLmV4YW1wbGUiLCJlbmMiOiJBMjU2R0NNIn0",
"iv": "-nBoKLH0YkLZPSI9",
"ciphertext": "o4k2cnGN8rSSw3IDo1YuySkqeS_t2m1GXklSgqBdpACm6
UJuJowOHC5ytjqYgRL-I-soPlwqMUf4UgRWWeaOGNw6vGW-xyM01lTYx
rXfVzIIaRdhYtEMRBvBWbEwP7ua1DRfvaOjgZv6Ifa3brcAM64d8p5lh
hNcizPersuhw5f-pGYzseva-TUaL8iWnctc-sSwy7SQmRkfhDjwbz0fz
6kFovEgj64X1I5s7E6GLp5fnbYGLa1QUiML7Cc2GxgvI7zqWo0YIEc7a
CflLG1-8BboVWFdZKLK9vNoycrYHumwzKluLWEbSVmaPpOslY2n525Dx
DfWaVFUfKQxMF56vn4B9QMpWAbnypNimbM8zVOw",
"tag": "UCGiqJxhBI3IFVdPalHHvA"
}
Figure 93: JSON General Serialization
The resulting JWE object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 50]
Internet-Draft JOSE Cookbook November 2014
{
"protected": "eyJhbGciOiJSU0EtT0FFUCIsImtpZCI6InNhbXdpc2UuZ2
FtZ2VlQGhvYmJpdG9uLmV4YW1wbGUiLCJlbmMiOiJBMjU2R0NNIn0",
"encrypted_key": "rT99rwrBTbTI7IJM8fU3Eli7226HEB7IchCxNuh7lC
iud48LxeolRdtFF4nzQibeYOl5S_PJsAXZwSXtDePz9hk-BbtsTBqC2U
sPOdwjC9NhNupNNu9uHIVftDyucvI6hvALeZ6OGnhNV4v1zx2k7O1D89
mAzfw-_kT3tkuorpDU-CpBENfIHX1Q58-Aad3FzMuo3Fn9buEP2yXakL
XYa15BUXQsupM4A1GD4_H4Bd7V3u9h8Gkg8BpxKdUV9ScfJQTcYm6eJE
Bz3aSwIaK4T3-dwWpuBOhROQXBosJzS1asnuHtVMt2pKIIfux5BC6huI
vmY7kzV7W7aIUrpYm_3H4zYvyMeq5pGqFmW2k8zpO878TRlZx7pZfPYD
SXZyS0CfKKkMozT_qiCwZTSz4duYnt8hS4Z9sGthXn9uDqd6wycMagnQ
fOTs_lycTWmY-aqWVDKhjYNRf03NiwRtb5BE-tOdFwCASQj3uuAgPGrO
2AWBe38UjQb0lvXn1SpyvYZ3WFc7WOJYaTa7A8DRn6MC6T-xDmMuxC0G
7S2rscw5lQQU06MvZTlFOt0UvfuKBa03cxA_nIBIhLMjY2kOTxQMmpDP
Tr6Cbo8aKaOnx6ASE5Jx9paBpnNmOOKH35j_QlrQhDWUN6A2Gg8iFayJ
69xDEdHAVCGRzN3woEI2ozDRs",
"iv": "-nBoKLH0YkLZPSI9",
"ciphertext": "o4k2cnGN8rSSw3IDo1YuySkqeS_t2m1GXklSgqBdpACm6
UJuJowOHC5ytjqYgRL-I-soPlwqMUf4UgRWWeaOGNw6vGW-xyM01lTYx
rXfVzIIaRdhYtEMRBvBWbEwP7ua1DRfvaOjgZv6Ifa3brcAM64d8p5lh
hNcizPersuhw5f-pGYzseva-TUaL8iWnctc-sSwy7SQmRkfhDjwbz0fz
6kFovEgj64X1I5s7E6GLp5fnbYGLa1QUiML7Cc2GxgvI7zqWo0YIEc7a
CflLG1-8BboVWFdZKLK9vNoycrYHumwzKluLWEbSVmaPpOslY2n525Dx
DfWaVFUfKQxMF56vn4B9QMpWAbnypNimbM8zVOw",
"tag": "UCGiqJxhBI3IFVdPalHHvA"
}
Figure 94: JSON Flattened Serialization
5.3. Key Wrap using PBES2-AES-KeyWrap with AES-CBC-HMAC-SHA2
The example illustrates encrypting content using the
"PBES2-HS512+A256KW" (PBES2 Password-based Encryption using HMAC-
SHA-512 and AES-256-KeyWrap) key encryption algorithm with the
"A128CBC-HS256" (AES-128-CBC-HMAC-SHA-256) content encryption
algorithm.
Note that whitespace is added for readability as described in
Section 1.1.
5.3.1. Input Factors
The following are supplied before beginning the encryption process:
o Plaintext content; this example uses the plaintext from Figure 95
(*NOTE* all whitespace added for readability)
Miller Expires May 17, 2015 [Page 51]
Internet-Draft JOSE Cookbook November 2014
o Password; this example uses the password from Figure 96 - with the
sequence "\xe2\x80\x93" replaced with (U+2013 EN DASH)
o "alg" parameter of "PBES2-HS512+A256KW"
o "enc" parameter of "A128CBC-HS256"
{
"keys": [
{
"kty": "oct",
"kid": "77c7e2b8-6e13-45cf-8672-617b5b45243a",
"use": "enc",
"alg": "A128GCM",
"k": "XctOhJAkA-pD9Lh7ZgW_2A"
},
{
"kty": "oct",
"kid": "81b20965-8332-43d9-a468-82160ad91ac8",
"use": "enc",
"alg": "A128KW",
"k": "GZy6sIZ6wl9NJOKB-jnmVQ"
},
{
"kty": "oct",
"kid": "18ec08e1-bfa9-4d95-b205-2b4dd1d4321d",
"use": "enc",
"alg": "A256GCMKW",
"k": "qC57l_uxcm7Nm3K-ct4GFjx8tM1U8CZ0NLBvdQstiS8"
}
]
}
Figure 95: Plaintext Content
entrap_o\xe2\x80\x93peter_long\xe2\x80\x93credit_tun
Figure 96: Password
5.3.2. Generated Factors
The following are generated before encrypting:
o AES symmetric key as the Content Encryption Key (CEK); this
example uses the key from Figure 97.
o Initialization vector/nonce; this example uses the initialization
vector/nonce from Figure 98.
Miller Expires May 17, 2015 [Page 52]
Internet-Draft JOSE Cookbook November 2014
uwsjJXaBK407Qaf0_zpcpmr1Cs0CC50hIUEyGNEt3m0
Figure 97: Content Encryption Key, base64url-encoded
VBiCzVHNoLiR3F4V82uoTQ
Figure 98: Initialization Vector, base64url-encoded
5.3.3. Encrypting the Key
The following are generated before encrypting the CEK:
o Salt; this example uses the salt from Figure 99.
o Iteration count; this example uses the iteration count 8192.
8Q1SzinasR3xchYz6ZZcHA
Figure 99: Salt, base64url-encoded
Performing the key encryption operation over the CEK (Figure 97))
with the following:
o Password (Figure 96;
o Salt (Figure 99), encoded as an octet string; and
o Iteration count (8192)
produces the following encrypted key:
d3qNhUWfqheyPp4H8sjOWsDYajoej4c5Je6rlUtFPWdgtURtmeDV1g
Figure 100: Encrypted Key, base64url-encoded
5.3.4. Encrypting the Content
The following are generated before encrypting the content:
o JWE Protected Header; this example uses the header from
Figure 101, encoded using [RFC4648] base64url to produce
Figure 102.
Miller Expires May 17, 2015 [Page 53]
Internet-Draft JOSE Cookbook November 2014
{
"alg": "PBES2-HS512+A256KW",
"p2s": "8Q1SzinasR3xchYz6ZZcHA",
"p2c": 8192,
"cty": "jwk-set+json",
"enc": "A128CBC-HS256"
}
Figure 101: JWE Protected Header JSON
eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJwMnMiOiI4UTFTemluYXNSM3
hjaFl6NlpaY0hBIiwicDJjIjo4MTkyLCJjdHkiOiJqd2stc2V0K2pzb24iLCJl
bmMiOiJBMTI4Q0JDLUhTMjU2In0
Figure 102: JWE Protected Header, base64url-encoded
Performing the content encryption operation over the Plaintext
(Figure 95) with the the following:
o CEK (Figure 97);
o Initialization vector/nonce (Figure 98); and
o JWE Protected Header (Figure 102) as authenticated data
produces the following:
o Ciphertext from Figure 103.
o Authentication tag from Figure 104.
23i-Tb1AV4n0WKVSSgcQrdg6GRqsUKxjruHXYsTHAJLZ2nsnGIX86vMXqIi6IR
sfywCRFzLxEcZBRnTvG3nhzPk0GDD7FMyXhUHpDjEYCNA_XOmzg8yZR9oyjo6l
TF6si4q9FZ2EhzgFQCLO_6h5EVg3vR75_hkBsnuoqoM3dwejXBtIodN84PeqMb
6asmas_dpSsz7H10fC5ni9xIz424givB1YLldF6exVmL93R3fOoOJbmk2GBQZL
_SEGllv2cQsBgeprARsaQ7Bq99tT80coH8ItBjgV08AtzXFFsx9qKvC982KLKd
PQMTlVJKkqtV4Ru5LEVpBZXBnZrtViSOgyg6AiuwaS-rCrcD_ePOGSuxvgtrok
AKYPqmXUeRdjFJwafkYEkiuDCV9vWGAi1DH2xTafhJwcmywIyzi4BqRpmdn_N-
zl5tuJYyuvKhjKv6ihbsV_k1hJGPGAxJ6wUpmwC4PTQ2izEm0TuSE8oMKdTw8V
3kobXZ77ulMwDs4p
Figure 103: Ciphertext, base64url-encoded
0HlwodAhOCILG5SQ2LQ9dg
Figure 104: Authentication Tag, base64url-encoded
Miller Expires May 17, 2015 [Page 54]
Internet-Draft JOSE Cookbook November 2014
5.3.5. Output Results
The following compose the resulting JWE object:
o JWE Protected Header (Figure 102)
o Encrypted key (Figure 100)
o Initialization vector/nonce (Figure 98)
o Ciphertext (Figure 103)
o Authentication tag (Figure 104)
The resulting JWE object using the Compact serialization:
eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJwMnMiOiI4UTFTemluYXNSM3
hjaFl6NlpaY0hBIiwicDJjIjo4MTkyLCJjdHkiOiJqd2stc2V0K2pzb24iLCJl
bmMiOiJBMTI4Q0JDLUhTMjU2In0
.
d3qNhUWfqheyPp4H8sjOWsDYajoej4c5Je6rlUtFPWdgtURtmeDV1g
.
VBiCzVHNoLiR3F4V82uoTQ
.
23i-Tb1AV4n0WKVSSgcQrdg6GRqsUKxjruHXYsTHAJLZ2nsnGIX86vMXqIi6IR
sfywCRFzLxEcZBRnTvG3nhzPk0GDD7FMyXhUHpDjEYCNA_XOmzg8yZR9oyjo6l
TF6si4q9FZ2EhzgFQCLO_6h5EVg3vR75_hkBsnuoqoM3dwejXBtIodN84PeqMb
6asmas_dpSsz7H10fC5ni9xIz424givB1YLldF6exVmL93R3fOoOJbmk2GBQZL
_SEGllv2cQsBgeprARsaQ7Bq99tT80coH8ItBjgV08AtzXFFsx9qKvC982KLKd
PQMTlVJKkqtV4Ru5LEVpBZXBnZrtViSOgyg6AiuwaS-rCrcD_ePOGSuxvgtrok
AKYPqmXUeRdjFJwafkYEkiuDCV9vWGAi1DH2xTafhJwcmywIyzi4BqRpmdn_N-
zl5tuJYyuvKhjKv6ihbsV_k1hJGPGAxJ6wUpmwC4PTQ2izEm0TuSE8oMKdTw8V
3kobXZ77ulMwDs4p
.
0HlwodAhOCILG5SQ2LQ9dg
Figure 105: Compact Serialization
The resulting JWE object using the JSON General Serialization:
Miller Expires May 17, 2015 [Page 55]
Internet-Draft JOSE Cookbook November 2014
{
"recipients": [
{
"encrypted_key": "d3qNhUWfqheyPp4H8sjOWsDYajoej4c5Je6rlU
tFPWdgtURtmeDV1g"
}
],
"protected": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJwMnMiOi
I4UTFTemluYXNSM3hjaFl6NlpaY0hBIiwicDJjIjo4MTkyLCJjdHkiOi
Jqd2stc2V0K2pzb24iLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
"iv": "VBiCzVHNoLiR3F4V82uoTQ",
"ciphertext": "23i-Tb1AV4n0WKVSSgcQrdg6GRqsUKxjruHXYsTHAJLZ2
nsnGIX86vMXqIi6IRsfywCRFzLxEcZBRnTvG3nhzPk0GDD7FMyXhUHpD
jEYCNA_XOmzg8yZR9oyjo6lTF6si4q9FZ2EhzgFQCLO_6h5EVg3vR75_
hkBsnuoqoM3dwejXBtIodN84PeqMb6asmas_dpSsz7H10fC5ni9xIz42
4givB1YLldF6exVmL93R3fOoOJbmk2GBQZL_SEGllv2cQsBgeprARsaQ
7Bq99tT80coH8ItBjgV08AtzXFFsx9qKvC982KLKdPQMTlVJKkqtV4Ru
5LEVpBZXBnZrtViSOgyg6AiuwaS-rCrcD_ePOGSuxvgtrokAKYPqmXUe
RdjFJwafkYEkiuDCV9vWGAi1DH2xTafhJwcmywIyzi4BqRpmdn_N-zl5
tuJYyuvKhjKv6ihbsV_k1hJGPGAxJ6wUpmwC4PTQ2izEm0TuSE8oMKdT
w8V3kobXZ77ulMwDs4p",
"tag": "0HlwodAhOCILG5SQ2LQ9dg"
}
Figure 106: JSON General Serialization
The resulting JWE object using the JSON Flattened Serialization:
Miller Expires May 17, 2015 [Page 56]
Internet-Draft JOSE Cookbook November 2014
{
"protected": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJwMnMiOi
I4UTFTemluYXNSM3hjaFl6NlpaY0hBIiwicDJjIjo4MTkyLCJjdHkiOi
Jqd2stc2V0K2pzb24iLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0",
"encrypted_key": "d3qNhUWfqheyPp4H8sjOWsDYajoej4c5Je6rlUtFPW
dgtURtmeDV1g",
"iv": "VBiCzVHNoLiR3F4V82uoTQ",
"ciphertext": "23i-Tb1AV4n0WKVSSgcQrdg6GRqsUKxjruHXYsTHAJLZ2
nsnGIX86vMXqIi6IRsfywCRFzLxEcZBRnTvG3nhzPk0GDD7FMyXhUHpD
jEYCNA_XOmzg8yZR9oyjo6lTF6si4q9FZ2EhzgFQCLO_6h5EVg3vR75_
hkBsnuoqoM3dwejXBtIodN84PeqMb6asmas_dpSsz7H10fC5ni9xIz42
4givB1YLldF6exVmL93R3fOoOJbmk2GBQZL_SEGllv2cQsBgeprARsaQ
7Bq99tT80coH8ItBjgV08AtzXFFsx9qKvC982KLKdPQMTlVJKkqtV4Ru
5LEVpBZXBnZrtViSOgyg6AiuwaS-rCrcD_ePOGSuxvgtrokAKYPqmXUe
RdjFJwafkYEkiuDCV9vWGAi1DH2xTafhJwcmywIyzi4BqRpmdn_N-zl5
tuJYyuvKhjKv6ihbsV_k1hJGPGAxJ6wUpmwC4PTQ2izEm0TuSE8oMKdT
w8V3kobXZ77ulMwDs4p",
"tag": "0HlwodAhOCILG5SQ2LQ9dg"
}
Figure 107: JSON Flattened Serialization
5.4. Key Agreement with Key Wrapping using ECDH-ES and AES-KeyWrap with
AES-GCM
This example illustrates encrypting content using the "ECDH-
ES+A128KW" (Elliptic Curve Diffie-Hellman Ephemeral-Static with AES-
128-KeyWrap) key encryption algorithm and the "A128GCM" (AES-GCM)
content encryption algorithm.
Note that whitespace is added for readability as described in
Section 1.1.
5.4.1. Input Factors
The following are supplied before beginning the encryption process:
o Plaintext content; this example uses the content from Figure 72
o EC public key; this example uses the public key from Figure 108
o "alg" parameter of "ECDH-ES+A128KW"
o "enc" parameter of "A128GCM"
Miller Expires May 17, 2015 [Page 57]
Internet-Draft JOSE Cookbook November 2014
{
"kty": "EC",
"kid": "peregrin.took@tuckborough.example",
"use": "enc",
"crv": "P-384",
"x": "YU4rRUzdmVqmRtWOs2OpDE_T5fsNIodcG8G5FWPrTPMyxpzsSOGaQL
pe2FpxBmu2",
"y": "A8-yxCHxkfBz3hKZfI1jUYMjUhsEveZ9THuwFjH2sCNdtksRJU7D5-
SkgaFL1ETP",
"d": "iTx2pk7wW-GqJkHcEkFQb2EFyYcO7RugmaW3mRrQVAOUiPommT0Idn
YK2xDlZh-j"
}
Figure 108: Elliptic Curve P-384 Key, in JWK format
(*NOTE*: While the key includes the private parameters, only the
public parameters "crv", "x", and "y" are necessary for the
encryption operation.)
5.4.2. Generated Factors
The following are generated before encrypting:
o Symmetric AES key as the Content Encryption Key (CEK); this
example uses the key from Figure 109.
o Initialization vector/nonce; this example uses the initialization
vector/nonce from Figure 110
Nou2ueKlP70ZXDbq9UrRwg
Figure 109: Content Encryption Key, base64url-encoded
mH-G2zVqgztUtnW_
Figure 110: Initialization Vector, base64url-encoded
5.4.3. Encrypting the Key
To encrypt the Content Encryption Key, the following are generated:
o Ephemeral EC private key on the same curve as the EC public key;
this example uses the private key from Figure 111.
Miller Expires May 17, 2015 [Page 58]
Internet-Draft JOSE Cookbook November 2014
{
"kty": "EC",
"crv": "P-384",
"x": "uBo4kHPw6kbjx5l0xowrd_oYzBmaz-GKFZu4xAFFkbYiWgutEK6iuE
DsQ6wNdNg3",
"y": "sp3p5SGhZVC2faXumI-e9JU2Mo8KpoYrFDr5yPNVtW4PgEwZOyQTA-
JdaY8tb7E0",
"d": "D5H4Y_5PSKZvhfVFbcCYJOtcGZygRgfZkpsBr59Icmmhe9sW6nkZ8W
fwhinUfWJg"
}
Figure 111: Ephemeral Elliptic Curve P-384 Key, in JWK format
Performing the key encryption operation over the CEK (Figure 109)
with the following:
o The static Elliptic Curve public key (Figure 108); and
o The ephemeral Elliptic Curve private key (Figure 111);
produces the following JWE encrypted key:
0DJjBXri_kBcC46IkU5_Jk9BqaQeHdv2
Figure 112: Encrypted Key, base64url-encoded
5.4.4. Encrypting the Content
The following are generated before encrypting the content:
o JWE Protected Header; this example uses the header from
Figure 113, encoded to [RFC4648] base64url as Figure 114.
{
"alg": "ECDH-ES+A128KW",
"kid": "peregrin.took@tuckborough.example",
"epk": {
"kty": "EC",
"crv": "P-384",
"x": "uBo4kHPw6kbjx5l0xowrd_oYzBmaz-GKFZu4xAFFkbYiWgutEK6i
uEDsQ6wNdNg3",
"y": "sp3p5SGhZVC2faXumI-e9JU2Mo8KpoYrFDr5yPNVtW4PgEwZOyQT
A-JdaY8tb7E0"
},
"enc": "A128GCM"
}
Figure 113: JWE Protected Header JSON
Miller Expires May 17, 2015 [Page 59]
Internet-Draft JOSE Cookbook November 2014
eyJhbGciOiJFQ0RILUVTK0ExMjhLVyIsImtpZCI6InBlcmVncmluLnRvb2tAdH
Vja2Jvcm91Z2guZXhhbXBsZSIsImVwayI6eyJrdHkiOiJFQyIsImNydiI6IlAt
Mzg0IiwieCI6InVCbzRrSFB3Nmtiang1bDB4b3dyZF9vWXpCbWF6LUdLRlp1NH
hBRkZrYllpV2d1dEVLNml1RURzUTZ3TmROZzMiLCJ5Ijoic3AzcDVTR2haVkMy
ZmFYdW1JLWU5SlUyTW84S3BvWXJGRHI1eVBOVnRXNFBnRXdaT3lRVEEtSmRhWT
h0YjdFMCJ9LCJlbmMiOiJBMTI4R0NNIn0
Figure 114: JWE Protected Header, base64url-encoded
Performing the content encryption operation on the Plaintext
(Figure 72) using the following:
o CEK (Figure 109);
o Initialization vector/nonce (Figure 110); and
o JWE Protected Header (Figure 114) as authenticated data
produces the following:
o Ciphertext from Figure 115.
o Authentication tag from Figure 116.
tkZuOO9h95OgHJmkkrfLBisku8rGf6nzVxhRM3sVOhXgz5NJ76oID7lpnAi_cP
WJRCjSpAaUZ5dOR3Spy7QuEkmKx8-3RCMhSYMzsXaEwDdXta9Mn5B7cCBoJKB0
IgEnj_qfo1hIi-uEkUpOZ8aLTZGHfpl05jMwbKkTe2yK3mjF6SBAsgicQDVCkc
Y9BLluzx1RmC3ORXaM0JaHPB93YcdSDGgpgBWMVrNU1ErkjcMqMoT_wtCex3w0
3XdLkjXIuEr2hWgeP-nkUZTPU9EoGSPj6fAS-bSz87RCPrxZdj_iVyC6QWcqAu
07WNhjzJEPc4jVntRJ6K53NgPQ5p99l3Z408OUqj4ioYezbS6vTPlQ
Figure 115: Ciphertext, base64url-encoded
WuGzxmcreYjpHGJoa17EBg
Figure 116: Authentication Tag, base64url-encoded
5.4.5. Output Results
The following compose the resulting JWE object:
o JWE Protected Header (Figure 114)
o Encrypted key (Figure 112)
o Initialization vector/nonce (Figure 110)
o Ciphertext (Figure 115)
Miller Expires May 17, 2015 [Page 60]
Internet-Draft JOSE Cookbook November 2014
Bellis, et al. Expires December 9, 2018 [Page 53]