From cbc7a7eb3e310989d5dc572597da696dc7c81252 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 16:58:59 -0700 Subject: [PATCH 01/96] Initial commit --- README.md | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..5a417f7df --- /dev/null +++ b/README.md @@ -0,0 +1,4 @@ +i-d-template +============ + +A template for IETF working group draft git repositories From 621c6e73a20d7b9e5d09df600b8e820b933db756 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 17:35:58 -0700 Subject: [PATCH 02/96] Initial version --- .gitignore | 8 + .travis.yml | 7 + CONTRIBUTING.md | 71 +++++ Makefile | 85 ++++++ README-template.md | 80 ++++++ README.md | 105 +++++++- template.md | 570 ++++++++++++++++++++++++++++++++++++++++ template.xml | 637 +++++++++++++++++++++++++++++++++++++++++++++ 8 files changed, 1560 insertions(+), 3 deletions(-) create mode 100644 .gitignore create mode 100644 .travis.yml create mode 100644 CONTRIBUTING.md create mode 100644 Makefile create mode 100644 README-template.md create mode 100644 template.md create mode 100644 template.xml diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..259948410 --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +*.redxml +*.txt +*.html +*~ +*.swp +/*-[0-9][0-9].xml +.refcache + diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..398742c74 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,7 @@ +language: python +install: + - gem install kramdown-rfc2629 + - pip install xml2rfc +script: make ghpages +env: + global: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..afdc617da --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,71 @@ +# Contributing + +Before submitting feedback, please familiarize yourself with our current issues +list and review the [working group home page](|WG-HOMEPAGE|). If you're +new to this, you may also want to read the [Tao of the +IETF](https://www.ietf.org/tao.html). + +Be aware that all contributions to the specification fall under the "NOTE WELL" +terms outlined below. + +1. The best way to provide feedback (editorial or design) and ask questions is +sending an e-mail to [our mailing +list](https://www.ietf.org/mailman/listinfo/|WG-NAME|). This will ensure that +the entire Working Group sees your input in a timely fashion. + +2. If you have **editorial** suggestions (i.e., those that do not change the +meaning of the specification), you can either: + + a) Fork this repository and submit a pull request; this is the lowest + friction way to get editorial changes in. + + b) Submit a new issue to Github, and mention that you believe it is editorial + in the issue body. It is not necessary to notify the mailing list for + editorial issues. + + c) Make comments on individual commits in Github. Note that this feedback is + processed only with best effort by the editors, so it should only be used for + quick editorial suggestions or questions. + +3. For non-editorial (i.e., **design**) issues, you can also create an issue on +Github. However, you **must notify the mailing list** when creating such issues, +providing a link to the issue in the message body. + + Note that **github issues are not for substantial discussions**; the only + appropriate place to discuss design issues is on the mailing list itself. + + +## NOTE WELL + +Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor +for publication as all or part of an IETF Internet-Draft or RFC and any +statement made within the context of an IETF activity is considered an "IETF +Contribution". Such statements include oral statements in IETF sessions, as +well as written and electronic communications made at any time or place, which +are addressed to: + + * The IETF plenary session + * The IESG, or any member thereof on behalf of the IESG + * Any IETF mailing list, including the IETF list itself, any working group + or design team list, or any other list functioning under IETF auspices + * Any IETF working group or portion thereof + * Any Birds of a Feather (BOF) session + * The IAB or any member thereof on behalf of the IAB + * The RFC Editor or the Internet-Drafts function + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) + (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). + +Statements made outside of an IETF session, mailing list or other function, +that are clearly not intended to be input to an IETF activity, group or +function, are not IETF Contributions in the context of this notice. + +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +3979](https://tools.ietf.org/html/rfc3979) for details. + +A participant in any IETF activity is deemed to accept all IETF rules of +process, as documented in Best Current Practices RFCs and IESG Statements. + +A participant in any IETF activity acknowledges that written, audio and video +records of meetings may be made and may be available to the public. diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..f4e91e920 --- /dev/null +++ b/Makefile @@ -0,0 +1,85 @@ +xml2rfc ?= xml2rfc +kramdown-rfc2629 ?= kramdown-rfc2629 +idnits ?= idnits + +draft := $(basename $(firstword $(wildcard draft-*.xml))) + +current_ver := $(shell git tag | grep "$(draft)-[0-9][0-9]" | tail -1 | sed -e"s/.*-//") +ifeq "${current_ver}" "" +next_ver ?= 00 +else +next_ver ?= $(shell printf "%.2d" $$((1$(current_ver)-99))) +endif +next := $(draft)-$(next_ver) + +.PHONY: latest submit clean + +latest: $(draft).txt $(draft).html + +submit: $(next).txt + +idnits: $(next).txt + $(idnits) $< + +clean: + -rm -f $(draft).txt $(draft).html index.html + -rm -f $(next).txt $(next).html + -rm -f $(draft)-[0-9][0-9].xml + +$(next).xml: $(draft).xml + sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ + +%.xml: %.md + $(kramdown-rfc2629) $< > $@ + +%.txt: %.xml + $(xml2rfc) $< $@ + +%.html: %.xml + $(xml2rfc) --html $< $@ + +GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) +.TRANSIENT: $(GHPAGES_TMP) +ifeq (,$(TRAVIS_COMMIT)) +GIT_ORIG := $(shell git branch | grep '*' | cut -c 3-) +else +GIT_ORIG := $(TRAVIS_COMMIT) +endif + +# Only run upload if we are local or on the master branch +IS_LOCAL := $(if $(TRAVIS),,true) +ifeq (master,$(TRAVIS_BRANCH)) +IS_MASTER := $(findstring false,$(TRAVIS_PULL_REQUEST)) +else +IS_MASTER := +endif + +index.html: draft.html + cp $< $@ + +ghpages: index.html $(draft).txt +ifneq (,$(or $(IS_LOCAL),$(IS_MASTER))) + mkdir $(GHPAGES_TMP) + cp -f $^ $(GHPAGES_TMP) + git clean -qfdX +ifeq (true,$(TRAVIS)) + git config user.email "ci-bot@example.com" + git config user.name "Travis CI Bot" + git checkout -q --orphan gh-pages + git rm -qr --cached . + git clean -qfd + git pull -qf origin gh-pages --depth=5 +else + git checkout gh-pages + git pull +endif + mv -f $(GHPAGES_TMP)/* $(CURDIR) + git add $^ + if test `git status -s | wc -l` -gt 0; then git commit -m "Script updating gh-pages."; fi +ifneq (,$(GH_TOKEN)) + @echo git push https://github.com/$(TRAVIS_REPO_SLUG).git gh-pages + @git push https://$(GH_TOKEN)@github.com/$(TRAVIS_REPO_SLUG).git gh-pages +endif + -git checkout -qf "$(GIT_ORIG)" + -rm -rf $(GHPAGES_TMP) +endif diff --git a/README-template.md b/README-template.md new file mode 100644 index 000000000..fe59cd667 --- /dev/null +++ b/README-template.md @@ -0,0 +1,80 @@ +# |DRAFT-TITLE| + +This is the working area for the [IETF |WG-TITLE| Working +Group](https://trac.tools.ietf.org/wg/|WG-NAME|/trac/wiki) draft of |DRAFT-TITLE| + +* [Editor's copy](https://rtcweb-wg.github.io/security-arch/) +* [Working Group Draft] (https://tools.ietf.org/html/|DRAFT-NAME|) + + +## Contributing + +Before submitting feedback, please familiarize yourself with our current issues +list and review the [working group home page](|WG-HOMEPAGE|). If you're +new to this, you may also want to read the [Tao of the +IETF](https://www.ietf.org/tao.html). + +Be aware that all contributions to the specification fall under the "NOTE WELL" +terms outlined below. + +1. The best way to provide feedback (editorial or design) and ask questions is +sending an e-mail to [our mailing +list](https://www.ietf.org/mailman/listinfo/|WG-NAME|). This will ensure that +the entire Working Group sees your input in a timely fashion. + +2. If you have **editorial** suggestions (i.e., those that do not change the +meaning of the specification), you can either: + + a) Fork this repository and submit a pull request; this is the lowest + friction way to get editorial changes in. + + b) Submit a new issue to Github, and mention that you believe it is editorial + in the issue body. It is not necessary to notify the mailing list for + editorial issues. + + c) Make comments on individual commits in Github. Note that this feedback is + processed only with best effort by the editors, so it should only be used for + quick editorial suggestions or questions. + +3. For non-editorial (i.e., **design**) issues, you can also create an issue on +Github. However, you **must notify the mailing list** when creating such issues, +providing a link to the issue in the message body. + + Note that **github issues are not for substantial discussions**; the only + appropriate place to discuss design issues is on the mailing list itself. + + +## NOTE WELL + +Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor +for publication as all or part of an IETF Internet-Draft or RFC and any +statement made within the context of an IETF activity is considered an "IETF +Contribution". Such statements include oral statements in IETF sessions, as +well as written and electronic communications made at any time or place, which +are addressed to: + + * The IETF plenary session + * The IESG, or any member thereof on behalf of the IESG + * Any IETF mailing list, including the IETF list itself, any working group + or design team list, or any other list functioning under IETF auspices + * Any IETF working group or portion thereof + * Any Birds of a Feather (BOF) session + * The IAB or any member thereof on behalf of the IAB + * The RFC Editor or the Internet-Drafts function + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) + (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). + +Statements made outside of an IETF session, mailing list or other function, +that are clearly not intended to be input to an IETF activity, group or +function, are not IETF Contributions in the context of this notice. + +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +3979](https://tools.ietf.org/html/rfc3979) for details. + +A participant in any IETF activity is deemed to accept all IETF rules of +process, as documented in Best Current Practices RFCs and IESG Statements. + +A participant in any IETF activity acknowledges that written, audio and video +records of meetings may be made and may be available to the public. diff --git a/README.md b/README.md index 5a417f7df..579a63fd6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,103 @@ -i-d-template -============ +# Internet Draft Template Repository + +The contents of this repository can be used to get started with a new +internet draft. + +## Getting Started + +This all assumes that you have an [account](https://github.com/join) with Github. + +### Working Group Setup + +Make a [new organization](https://github.com/organizations/new) for your working group. +This guide will use the name `unicorn-wg` for your working group. + +### New Draft Setup + +1. [Make a new repository](https://github.com/new). This guide will use the name + name `unicorn-protocol` here. + +2. Clone that repository: + +```sh +$ git clone https://github.com/unicorn-wg/unicorn-protocol.git +``` + +3. Copy the contents of this respository in: + +```sh +$ git pull https://github.com/martinthomson/i-d-template.git master +``` + +4. Choose whether you want to use markdown or xml as your input form. + If you already have a draft, then that decision is already made for you. + +5. Move the template file into place. + +```sh +$ git mv template.md draft-ietf-unicorn-protocol.md +``` + + Or add an existing file. + +```sh +git add draft-ietf-unicorn-protocol.xml +```` + +6. Remove the unnecessary template files. + +```sh +git rm template.md template.xml +``` + +7. Move the README.md template into place. + +```sh +$ git rm README.md +$ git mv README-template.md README.md +``` + +8. Edit the README.md and CONTRIBUTING.md files. + +```sh +$ vi README.md CONTRIBUTING.md +# ... +$ git add README.md CONTRIBUTING.md +``` + +8. Commit and push + +```sh +$ git commit -am "Initial commit" +$ git push +``` + + +### Setting Up The Editor's Copy + +This requires that you sign in with [Travis](https://travis-ci.org/). + +While you are there, enable builds for the new repository. + +You also need the travis command line tools, which is a Ruby script: + +```sh +$ sudo gem install travis +``` + +Then, you need to get yourself a [new Github application token](https://github.com/settings/tokens/new). +You might want to use a dummy account for this purpose. + +The application token only needs the `public_repo` privilege. +This will let it push updates to your `gh-pages` branch. + +Then, you update the Travis configuration file with an encrypted +copy of that token, as follows: + +```sh +$ travis encrypt GH_TOKEN= -a -p +$ git add .travis.yml +$ git commit -m "Updating Travis configuration" .travis.yml +$ git push +``` -A template for IETF working group draft git repositories diff --git a/template.md b/template.md new file mode 100644 index 000000000..e145e1014 --- /dev/null +++ b/template.md @@ -0,0 +1,570 @@ +--- +title: STUN/TURN using PHP in Despair +abbrev: STuPiD +docname: draft-hartke-xmpp-stupid-00 +date: 2009-07-05 +category: info + +ipr: trust200902 +area: General +workgroup: XMPP Working Group +keyword: Internet-Draft + +stand_alone: yes +pi: [toc, sortrefs, symrefs] + +author: + - + ins: K. Hartke + name: Klaus Hartke + organization: Universität Bremen TZI + email: hartke@tzi.org + - + ins: C. Bormann + name: Carsten Bormann + org: Universität Bremen TZI + street: Postfach 330440 + city: Bremen + code: D-28359 + country: Germany + phone: +49-421-218-63921 + facsimile: +49-421-218-7000 + email: cabo@tzi.org + +normative: + RFC2119: + RFC3986: + RFC4086: + RFC4648: + +informative: + RFC5389: + I-D.ietf-behave-turn: + STUNT: + target: http://deusty.blogspot.com/2007/09/stunt-out-of-band-channels.html + title: STUNT & out-of-band channels + author: + name: Robbie Hanson + ins: R. Hanson + date: 2007-09-17 + I-D.meyer-xmpp-e2e-encryption: + I-D.ietf-xmpp-3920bis: + + + +--- abstract + +NAT (Network Address Translator) Traversal may require TURN +(Traversal Using Relays around NAT) functionality in certain +cases that are not unlikely to occur. There is little +incentive to deploy TURN servers, except by those who need +them — who may not be in a position to deploy a new protocol +on an Internet-connected node, in particular not one with +deployment requirements as high as those of TURN. + +"STUN/TURN using PHP in Despair" is a highly deployable +protocol for obtaining TURN-like functionality, while also +providing the most important function of STUN. + +--- middle + +Introduction {#problems} +============ + +NAT (Network Address Translator) Traversal may require TURN +(Traversal Using Relays around NAT) +{{I-D.ietf-behave-turn}} +functionality in certain +cases that are not unlikely to occur. There is little +incentive to deploy TURN servers, except by those who need +them — who may not be in a position to deploy a new protocol +on an Internet-connected node, in particular not one with +deployment requirements as high as those of TURN. + +"STUN/TURN using PHP in Despair" is a highly deployable +protocol for obtaining TURN-like functionality, while also +providing the most important function of STUN +{{RFC5389}}. + +The high degree of deployability is achieved by making STuPiD +a Web service, implementable in any Web application deployment +scheme. As PHP appears to be the solution of choice for +avoiding deployment problems in the Web world, a PHP-based +sample implementation of STuPiD is presented in {{figimpl}} in {{impl}}. +(This single-page script has been tested with a free-of-charge +web hoster, so it should be deployable by literally everyone.) + + +The Need for Standardization {#need} +---------------------------- + +If STuPiD is so easy to deploy, why standardize on it? +First of all, STuPiD server implementations will be done by +other people than the clients making use of the service. +Clearly communicating between these communities is a good +idea, in particular if there are security considerations. + +Having one standard form of STuPiD service instead of one +specific to each kind of client also creates an incentive +for optimized implementations. + +Finally, where STuPiD becomes part of a client standard +(such as a potential extension to XMPP's in-band byte-stream +protocol as hinted in {{xmpp}}), it is a good +thing if STuPiD is already defined. + +Hence, this document focuses on the definition of the STuPiD +service itself, tries to make this as general as possible +without increasing complexity or cost and leaves the details +of any client standards to future documents. + + +Basic Protocol Operation {#ops} +======================== + +The STuPiD protocol will typically be used with application +instances that first attempt to obtain connectivity using +mechanisms similar to those described in the STUN +specification {{RFC5389}}. However, with STuPiD, +STUN is not really needed for TCP, as was demonstrated in +previous STUN-like implementations {{STUNT}}. +Instead, STuPiD (like {{STUNT}}) provides a +simple Web service that +echoes the remote address and port of an incoming HTTP +request; in most cases, this is enough to get the job done. + +In case no connection can be established with this simple +STUN(T)-like mechanism, a TURN-like relay is needed as a final +fall-back. +The STuPiD protocol supports this, but solely provides a way +for the data to be +relayed. STuPiD relies on an out-of-band channel to notify +the peer whenever new data is available (synchronization signal). +See {{xmpp}} for one likely example of such an +out-of-band channel. +(Note that the out-of-band channel may have a much lower +throughput than the STuPiD relay channel — this is exactly +the case in the example provided in {{xmpp}}, +where the out-of-band channel is typically throughput-limited +to on the order of a few kilobits per second.) + +By designing the STuPiD web service in such a way that it can +be implemented by a simple PHP script such as that presented +in {{impl}}, it is easy to deploy by those who +need the STuPiD services. +The combination of the low-throughput out-of-band channel for +synchronization and the STuPiD web service for bulk data +relaying is somewhat silly but gets the job done. + +The STuPiD data relay is implemented as follows (see {{figops}}): + +1. Peer A, the source of the data to be relayed, stores a chunk of + data at the STuPiD server using an opaque identifier, the "chunk + identifier". How that chunk identifier is chosen is local to Peer + A; it could be composed of a random session id and a sequence number. + +2. Peer A notifies the receiver of the data, Peer + B, that a new data chunk is available, specifying the URI needed + for retrieval. + This notification is provided through an out-out-band channel. + (As an optimization for multiple consecutive transfers, A might + inform B once of a constant prefix of that URI and only send a + varying part such as a sequence number in each notification — + this is something to be decided in the client-client notification + protocol.) + +3. Peer B retrieves the data from the STuPiD server using the URI + provided by Peer A. + +Note that the data transfer mechanism is one-way, i.e. to send +data in the other direction as well, Peer B needs to perform +the same steps using a STuPiD server at the same or a +different location. + +~~~~~~~~~~ + + + STuPiD ```````````````````````````````, + Script <----------------------------. , + | , + ^ , | , + | , | , + (1) | , | , (3) + POST | , | , GET + | , | , + | v | v + + Peer A -----------------------> Peer B + (2) + out-of-band + Notification +~~~~~~~~~~ +{: #figops title="STuPiD Protocol Operation"} + + +Protocol Definition +=================== + +Terminology {#Terminology} +----------- +In this document, the key words "MUST", "MUST NOT", "REQUIRED", +"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", +and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 +{{RFC2119}} and indicate requirement levels for compliant STuPiD +implementations. + + +Discovering External IP Address and Port +---------------------------------------- + +A client may discover its external IP address and the port +required for port prediction by performing a HTTP GET +request to a STuPiD server. The STuPiD server MUST reply +with the remote address and remote port in the following +format: + +host ":" port + +where 'host' and 'port' are defined as in {{RFC3986}}. + + +Storing Data +------------ + +Data chunks are stored using the POST request of HTTP. The +STuPiD server MUST support one URI parameter which is passed +as query-string: + +'chid': A unique ID identifying the data chunk to be stored. +The ID SHOULD be chosen from the characters of the base64url +set {{RFC4648}}. + +The payload of the POST request MUST be the data to be +stored. The 'Content-Type' SHOULD be +'application/octet-stream', although a STuPiD server +implementation SHOULD simply ignore the 'Content-Type' as a +client implementation may be restricted and may not able to +specify a specific 'Content-Type'. (E.g., in certain cases, +the peer may be limited to sending the data as +multipart-form-encoded — still, the data is stored as a +byte stream.) + +STuPiD servers may reject data chunks that are larger than +some predefined limit. +This maximum size in bytes of each data chunk is RECOMMENDED +to be 65536 or more. + +As HTTP already provides data transparency, +the data chunk SHOULD NOT be encoded using Base64 or any +other data transparency mechanism; in any case, the STuPiD +server will not attempt to decode the chunk. + +The sender MUST wait for the HTTP response before +going on to notify the receiver. + + +Notification +------------ + +The sender notifies the receiver of the data chunk by passing +via an out-of-band channel (which is not part of the STuPiD +protocol): + +The full URL from which the data chunk can be retrieved, +i.e. the same URL that was used to store the data chunk, +including the chunk ID parameter. + +The exact notification mechanism over the out-of-band channel +and the definition of a session is dependent on the +out-of-band channel. See {{xmpp}} for one +example of such an out-of-band channel. + + +Retrieving Data +--------------- + +The notified peer retrieves the data chunk using a GET request +with the URL supplied by the sender. The STuPiD server MUST +set the 'Content-Type' of the returned body to +'application/octet-stream'. + + +Implementation Notes +==================== + +A STuPiD server implementation SHOULD delete stored data some +time after it was stored. It is RECOMMENDED not to delete the +data before five minutes have elapsed after it was stored. +Different client protocols will have different reactions to +data that have been deleted prematurely and cannot be +retrieved by the notified peer; this may be as trivial as +packet loss or it may cause a reliable byte-stream to fail +({{impl}}). +(TODO: It may be useful to provide some hints in the storing +POST request.) + +STuPiD clients should aggregate data in order to minimize the +number of requests to the STuPiD server per second. +The specific aggregation method chosen depends on the data +rate required (and the maximum chunk size), the latency +requirements, and the application semantics. + +Clearly, it is up to the implementation to decide how the data +chunks are actually stored. A sufficiently silly STuPiD server +implementation might for instance use a MySQL database. + + +Security Considerations +======================= + +The security objectives of STuPiD are to be as secure as if +NAT traversal had succeeded, i.e., an on-path attacker can +overhear and fake messages, but an off-path attacker cannot. +If a higher level of security is desired, it should be +provided on top of the data relayed by STuPiD, e.g. by using +XTLS {{I-D.meyer-xmpp-e2e-encryption}}. + +Much of the security of STuPiD is based on the assumption that +an off-path attacker cannot guess the chunk identifiers. A +suitable source of randomness {{RFC4086}} should +be used to generate at least a sufficiently large part of the +chunk identifiers (e.g., the chunk identifier could be a hard +to guess prefix followed by a serial number). + +To protect the STuPiD server against denial of service and +possibly some forms of theft of service, it is RECOMMENDED +that the POST side of the STuPiD server be protected by some +form of authentication such as HTTP authentication. There is +little need to protect the GET side. + +--- back + + +Examples {#xmp} +======== + +This appendix provides some examples of the STuPiD protocol operation. + +~~~~~~~~~~ + Request: + + GET /stupid.php HTTP/1.0 + User-Agent: Example/1.11.4 + Accept: */* + Host: example.org + Connection: Keep-Alive + + Response: + + HTTP/1.1 200 OK + Date: Sun, 05 Jul 2009 00:30:37 GMT + Server: Apache/2.2 + Cache-Control: no-cache, must-revalidate + Expires: Sat, 26 Jul 1997 05:00:00 GMT + Vary: Accept-Encoding + Content-Length: 17 + Keep-Alive: timeout=1, max=400 + Connection: Keep-Alive + Content-Type: application/octet-stream + + 192.0.2.239:36654 +~~~~~~~~~~ +{: #figxmpdisco title="Discovering External IP Address and Port"} + +~~~~~~~~~~ + Request: + + POST /stupid.php?chid=i781hf64-0 HTTP/1.0 + User-Agent: Example/1.11.4 + Accept: */* + Host: example.org + Connection: Keep-Alive + Content-Type: application/octet-stream + Content-Length: 11 + + Hello World + + Response: + + HTTP/1.1 200 OK + Date: Sun, 05 Jul 2009 00:20:34 GMT + Server: Apache/2.2 + Cache-Control: no-cache, must-revalidate + Expires: Sat, 26 Jul 1997 05:00:00 GMT + Vary: Accept-Encoding + Content-Length: 0 + Keep-Alive: timeout=1, max=400 + Connection: Keep-Alive + Content-Type: application/octet-stream +~~~~~~~~~~ +{: #figxmpstore title="Storing Data"} + +~~~~~~~~~~ + Request: + + GET /stupid.php?chid=i781hf64-0 HTTP/1.0 + User-Agent: Example/1.11.4 + Accept: */* + Host: example.org + Connection: Keep-Alive + + Response: + + HTTP/1.1 200 OK + Date: Sun, 05 Jul 2009 00:21:29 GMT + Server: Apache/2.2 + Cache-Control: no-cache, must-revalidate + Expires: Sat, 26 Jul 1997 05:00:00 GMT + Vary: Accept-Encoding + Content-Length: 11 + Keep-Alive: timeout=1, max=400 + Connection: Keep-Alive + Content-Type: application/octet-stream + + Hello World +~~~~~~~~~~ +{: #figxmpretr title="Retrieving Data"} + + +Sample Implementation {#impl} +===================== + +~~~~~~~~~~ + +~~~~~~~~~~ +{: #figimpl title="STuPiD Sample Implementation"} + + +Using XMPP as Out-Of-Band Channel {#xmpp} +================================= + +XMPP {{I-D.ietf-xmpp-3920bis}} is a good choice for +an out-of-band channel. + +The notification protocol is closely modeled after XMPP's +In-Band Bytestreams (IBB, see +http://xmpp.org/extensions/xep-0047.html). Just replace the +namespace and insert the STuPiD Retrieval URI instead of the +actual Base64 encoded data, see {{figxmpnots}}. +(Note that the current proposal redundantly sends a sid and a +seq as well as the chid composed of these two; it may be +possible to optimize this, possibly sending the constant prefix +of the URI once at bytestream creation time.) + +Notifications MUST be processed in the order they are +received. If an out-of-sequence notification is received for a +particular session (determined by checking the 'seq' attribute), +then this indicates that a notification has been lost. The +recipient MUST NOT process such an out-of-sequence notification, +nor any that follow it within the same session; instead, the +recipient MUST consider the session invalid. (Adapted from +http://xmpp.org/extensions/xep-0047.html#send) + +Of course, other methods can be used for setup and teardown, such as Jingle +(see http://xmpp.org/extensions/xep-0261.html). + +~~~~~~~~~~ + + + +~~~~~~~~~~ +{: #figxmpcri title="Creating a Bytestream: Initiator requests session"} + + +~~~~~~~~~~ + +~~~~~~~~~~ +{: #figxmpcrr title="Creating a Bytestream: Responder accepts session"} + + + +~~~~~~~~~~ + + + +~~~~~~~~~~ +{: #figxmpnots title="Sending Notifications: Notification in an IQ stanza"} + +~~~~~~~~~~ + +~~~~~~~~~~ +{: #figxmpnota title="Sending Notifications: Acknowledging notification using IQ"} + +~~~~~~~~~~ + + + +~~~~~~~~~~ +{: #figxmpclor title="Closing the Bytestream: Request"} + +~~~~~~~~~~ + +~~~~~~~~~~ +{: #figxmpclos title="Closing the Bytestream: Success response"} + diff --git a/template.xml b/template.xml new file mode 100644 index 000000000..e47bb069a --- /dev/null +++ b/template.xml @@ -0,0 +1,637 @@ + + + + + + + + +]> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Full Title + + + + + + Full Organization name +
+ + + + Espoo + + + FI + + psavola@funet.fi + +
+ + + + + Folly Consulting + +
+ + + + Soham + + + + + + UK + + + +44 7889 488 335 + + + + elwynd@dial.pipex.com + + +
+ + + + + + + + + Operations & Management + + + Internet Engineering Task Force + + + + + + + This is an abstract abstract. I-Ds and RFCs MUST have an abstract. + Remember, don't add references here. So we would just say the 'language' used to write + this document is defined in RFC 2629. + + + + This "forward" section is an unnumbered section that is not included + in the table of contents. It is primarily used for the IESG to + make comments about the document. It can also be used for comments about the status + of the document and sometimes is used for the RFC2119 requirements language statement. + + In this example, it is used as a handy place to specify URLs to + documents and tools to author RFC-style documents using XML. + RFC2629 is the original published document on authoring RFC-style + documents in XML + (). + It is being updated (and called RFC2629(bis) and is + . + The tool to convert XML documents to RFC-style text (and HTML) files + is described in document . + + Please also remember to check out + for issues to note when writing + drafts and the automated tools documented at + . + Remember, you don't need to have any other tools than a 'notepad' + or your favorite editor to write xml2rfc drafts. You can use the web + interface at for processing. The benefit of + using XML editors is mostly catching those missing tags which the processor will + warn you about, but you don't need to worry about the editors when getting + started. + This template is not meant to be a conclusive list of everything, + but summarize the often-needed basic features to get one started. + + + + + The key words "MUST", "MUST NOT", + "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", + "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. + + + + + + +
+ Now you can have a bit lengthier text here. + The definition of the XML Data Type Description used to 'describe' an RFC or Internet + Draft can be found in a document which we can refer to as + RFC 2629. + Let's refer to a couple more documents, just for practice: + and + L2TP. For text generation, these look equivalent, + but the latter looks a bit neater in the HTML representation. + You might also add a note about the usage of RFC2119 keywords here.. + You can cross-reference the sections of the document in a stable manner either by + section number - the usual way - or by section title + (""): if the organization of the + document changes the reference will still be to the correct section. However + "sect2" is not a very good 'anchor' name because there is no guarantee that + this section will remain as Section 2 for ever. It is best to use some sort of mnemonic + for the contents of the section, which also makes it easier to remember the anchor when + creating a cross-reference many pages later. A final note about anchors: anchors are + XML 'tokens' and must therefore consist only of letters, numbers, underscores, hyphens + and periods, starting with either a letter or underscore. Anchors with spaces or other + punctuation characters are not allowed. + +
+ +
+ Technical documents often use lists. There are multiple list styles: + 'empty', 'symbols', 'letters', 'numbers', 'hanging', 'format', etc. + + A more complicated list structure can be found in . + + First bullet + Second bullet + + You can write text here as well - the difference, as compared with putting it in the next + <t> element, is that there will not be a blank line between the last list item + and this text if the processing instructions compact and subcompact are both set to + "yes". Otherwise list items and the text before and after will be separated by blank + lines. + + One can draw fancy diagrams as well; remember to ensure that they + don't exceed 69 chars/line until v1.31 comes along. v1.31 should give you the ability + to start figures at the left margin getting figures up to 72 characters wide. + Setting the alignment for the whole figure to "center" instead of the default "left" + causes all the components to be centred unless it is overridden just for the "artwork", + as it is here. +
+ Figures can have some text before the artwork should it be needed. Note + that figures should NOT be inside <t> elements. Originally they were allowed + to be but you will now get a warning that this is deprecated, and the figure should + be a 'child' of the section element. + + + + Figures can also have text after the artwork and before the caption (if + any). This figure has an anchor. This means that the figure will get a caption... + +
+ Note that including a CDATA means you don't need to escape most special characters + you might otherwise have to. Figures may also have a title attribute but it won't be + displayed unless there is also an anchor, and it will be somewhat disconcerting for + readers if some figures have numbers and others don't.. + +
+ There can be a lot of subsections (and sub-subsections). By default 3 levels of + nesting show in table of contents but that can be adjusted with the + value of the "tocdepth" processing instruction. +
+ +
+ Another item that you might need is a table. The XML for tables is very similar + to that for figures: + + + Tables use ttcol to define column headers and widths. + Every cell then has a "c" element for its content. + ttcol #1 + ttcol #2 + c #1 + c #2 + c #3 + c #4 + c #5 + c #6 + which is a very simple example. + +
+
+ +
+ One useful style of lists uses 'hanging labels' where the list item is indented by + the amount of the hangIndent with the hanging label displayed to the left of the first + line of the item. This example shows how <vspace> can be used to deal with the + odd label longer than the indent you really want to use (This is only really relevant + to text mode output because the labels are always on separate lines in HTML output): + + With a label shorter than the hangIndent there + is white space after the label and before the item text starts + although it starts on the same line - clearly separating the label + from the column of items. + With a label longer than the hangIndent + the label runs on into the text item and the separation is lost. + Inserting a + <vspace /> at the start of the item forces the new item to + start on a new line emphasizing the separation again. + + + + + List items in xml2rfc are made up of one <t> element. In some cases it would be + nice to have more than one paragraph in a list item. This can be achieved with + <vspace> also: + + First, a short item that needs only one paragraph. + Second, a longer list item. We have more to say, and we want a separate + paragraph. + And here we can have it, and go on to our heart's content. + + + If you just want an indented paragraph (say for a quotation) use the "empty" style: + + The quick, brown fox jumped over the lazy dog and lived to fool many another + hunter in the great wood in the west. + + +
+ Sometimes it is useful to be able to number items continuously although they are + in separate <list> elements, maybe in separate sections. This can be achieved + using the "format" style and a "counter" variable. + + First list with (say) requirements items: + + Requirement #1 + Requirement #2 + Requirement #3 + + It is wise to specify the indent explicitly so that all the items line up nicely. + Otherwise the indent in each list is determined by the maximum length of the labels + in that list, even if later lists have longer labels. + A little later there is a second list with requirements items: + + Requirement #4 + Requirement #5 + Requirement #6 + + before this section finishes. +
+
+ But in the next section the list of requirements continues: + Third list with requirements items: + + Requirement #7 + Requirement #8 + Requirement #9 + Requirement #10 + + And finally that is all about the requirements. +
+
+ +
+ The artwork element from RFC 2629 supports an + optional type attribute. While most possible values are + just ignored, including the special case where the attribute is unspecified or just + empty, some values are recognized. In particular, + type='abnf' can be used if the + artwork contains an Augmented Backus-Naur Form (ABNF) + syntax specification . As a special extension in its + behavior, xml2rfc will + attempt to validate the syntax and colorize the HTML output of ABNF, since it is so + widely used in RFCs. It does this colorizing by relying on the full parsing it does + right before, not on a quick and partial (e.g., line-by-line) pattern-based hack. + ABNF is the only artwork type to benefit from this kind of internal support at this + time. If the strict rfc-PI directive is activated, + invalid ABNF content will cause xml2rfc to abort with an + error message. Omitting the type attribute altogether + is the obvious way to avoid having this validation and colorizing performed. + +
+ For example (to be viewed in HTML): + " + ; bracketed string of SP and VCHAR + without angles + ; prose description, to be used as + last resort +]]> + + This is from the original RFC on ABNF , + with its minor mistakes in manually folded comment lines purposely left intact, + for illustration. Since the result is still valid ABNF (but incorrect with respect + to what was intended), this showcases how colorizing might give a human author + (or editor or reader) a better chance to spot the three mistakes (and correct them, + e.g., with extra semicolons, as has been done in a more recent + version  of the ABNF specification). Note that it is + the white space characters at the beginning of the subsequent lines (including the + commented ones) that conspire to extend the reach of those rules across several + lines. +
+
+ +
+ The most common form of xml2rfc parsing errors are those where a + closing tag has been expected to be present before a new kind of tag is + specified. In the example below, Introduction section's last paragraph was + missing the closing t-element. The rest of the error messages can be rather + easily understood as well by reading it carefully and examining the context. + The reason is typically a missing tag somewhere. +
+ + + +
+ +=======8<======== +]]> + +
+
+
+
+ + + +void +main(int argc, char *argv[]) +{ + int i; + + printf("program arguments are:\n"); + for (i = 0; i < argc; i++) { + printf("%d: \"%s\"\n", i, argv[i]); + } + + exit(0); +} /* main */ + +/* end of file */ +]]> + +
+
+
+ Remember, it's important to acknowledge people who have + contributed to the work. + This template was extended from an initial version written by Pekka Savola and + contributed by him to the xml2rfc project. +
+ + + +
+ This memo includes no request to IANA. + (It's good - indeed pretty much mandatory now - to have an explicit note because + otherwise IANA wastes cycles trying to figure out if something is needed..) +
+ +
+ Remember to consider security from the start.. and all drafts are required to have + a security considerations section before they will pass the IESG. + +
+ + + + + + + + + + RFC2661 + + + + + + + + + + + Key words for use in RFCs to Indicate Requirement + Levels + + Harvard University +
+ + 1350 Mass. Ave. + Cambridge + MA 02138 + + - +1 617 495 3864 + sob@harvard.edu +
+ + + General + keyword + + In many standards track documents several words are used to signify + the requirements in the specification. These words are often + capitalized. This document defines these words as they should be + interpreted in IETF documents. Authors who follow these guidelines + should incorporate this phrase near the beginning of their document: + + + + The key words "MUST", "MUST NOT", + "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", + "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. + + + + Note that the force of these words is modified by the requirement level of + the document in which they are used. + + + + + + + + + + + + &RFC2629; + + + + + + + Ultimate Plan for Taking Over the World + + Mad Dominators, Inc. + + + + + &RFC4234; + &RFC2234; + + +
+ You can add appendices just as regular sections, the only + difference is that they go within the "back" element, and not + within the "middle" element. And they follow the "reference" + elements. +
+ + + From 45e65efc30d1afaf057e4373bb3661d7d0c321eb Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 17:36:53 -0700 Subject: [PATCH 03/96] 24825 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 579a63fd6..299595e3a 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,13 @@ $ git mv template.md draft-ietf-unicorn-protocol.md Or add an existing file. ```sh -git add draft-ietf-unicorn-protocol.xml +$ git add draft-ietf-unicorn-protocol.xml ```` 6. Remove the unnecessary template files. ```sh -git rm template.md template.xml +$ git rm template.md template.xml ``` 7. Move the README.md template into place. From f3198d56b4b29e1ba510673a6a3666fe2b33a20e Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 20:00:44 -0700 Subject: [PATCH 04/96] Update --- .travis.yml | 15 +++++++++++++++ Makefile | 8 ++++++-- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++---- template.md | 2 +- template.xml | 2 +- 5 files changed, 65 insertions(+), 8 deletions(-) diff --git a/.travis.yml b/.travis.yml index 398742c74..83033447c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,3 +5,18 @@ install: script: make ghpages env: global: + - TRAVIS=true + +before_deploy: make submit +deploy: + provider: releases + api-key: + secure: "" + file: + - $TRAVIS_TAG.txt + - $TRAVIS_TAG.html + - $TRAVIS_TAG.xml + skip_cleanup: true + on: + branch: master + tags: true diff --git a/Makefile b/Makefile index f4e91e920..6ffd7240f 100644 --- a/Makefile +++ b/Makefile @@ -2,9 +2,13 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 idnits ?= idnits -draft := $(basename $(firstword $(wildcard draft-*.xml))) +draft := $(basename $(firstword $(wildcard draft-*.md draft-*.xml))) +ifeq (,$(draft)) +$(warning No file named draft-*.md or draft-*.xml) +$(error Read README.md for setup instructions) +endif -current_ver := $(shell git tag | grep "$(draft)-[0-9][0-9]" | tail -1 | sed -e"s/.*-//") +current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") ifeq "${current_ver}" "" next_ver ?= 00 else diff --git a/README.md b/README.md index 299595e3a..915c743d6 100644 --- a/README.md +++ b/README.md @@ -44,20 +44,33 @@ $ git mv template.md draft-ietf-unicorn-protocol.md $ git add draft-ietf-unicorn-protocol.xml ```` -6. Remove the unnecessary template files. +6. Edit the draft so that it has the right name. This template uses + the `-latest` suffix in place of the usual number ('-00', or '-08'). + +```xml + +``` + + Or in markdown: + +```yaml +docname: draft-ietf-unicorn-protocol-latest +``` + +7. Remove the unnecessary template files. ```sh $ git rm template.md template.xml ``` -7. Move the README.md template into place. +8. Move the README.md template into place. ```sh $ git rm README.md $ git mv README-template.md README.md ``` -8. Edit the README.md and CONTRIBUTING.md files. +9. Edit the README.md and CONTRIBUTING.md files. ```sh $ vi README.md CONTRIBUTING.md @@ -65,7 +78,7 @@ $ vi README.md CONTRIBUTING.md $ git add README.md CONTRIBUTING.md ``` -8. Commit and push +10. Commit and push ```sh $ git commit -am "Initial commit" @@ -101,3 +114,28 @@ $ git commit -m "Updating Travis configuration" .travis.yml $ git push ``` +## Submitting Drafts + +Occasionally, you will want to submit versions of your draft to the +official IETF repository. The following process makes this easy. + +1. Make a submission version of your draft. The makefile uses git + tags to work out what version to create. + +```sh +$ make submit +``` + +2. [Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) + that this produces. + +3. Tag your repository and upload the tags. The tag you should use + is your draft name with the usual number in place of `-latest`. + +```sh +$ git tag draft-ietf-unicorn-protocol-03 +$ git push --tags +``` + +You can setup Travis to produce a release in Github based on tags. +See `.travis.yml` for a details. diff --git a/template.md b/template.md index e145e1014..c62c6ba2d 100644 --- a/template.md +++ b/template.md @@ -1,7 +1,7 @@ --- title: STUN/TURN using PHP in Despair abbrev: STuPiD -docname: draft-hartke-xmpp-stupid-00 +docname: draft-hartke-xmpp-stupid-latest date: 2009-07-05 category: info diff --git a/template.xml b/template.xml index e47bb069a..d95422585 100644 --- a/template.xml +++ b/template.xml @@ -54,7 +54,7 @@ category="info" ipr="noModification3978" iprExtract="codeExample" - docName="draft-ietf-edu-xml2rfc-full-template-00.txt" > + docName="draft-ietf-edu-xml2rfc-full-template-latest" > From ddeebfc41f7a989c3a37df3715fcd2b9d252ac07 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 20:27:03 -0700 Subject: [PATCH 05/96] Update to show location of key --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 83033447c..8a6c197f4 100644 --- a/.travis.yml +++ b/.travis.yml @@ -5,7 +5,7 @@ install: script: make ghpages env: global: - - TRAVIS=true + - secure: "" before_deploy: make submit deploy: From 3f1ef18dc512bd393376b2030957287693f4840c Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 20:33:53 -0700 Subject: [PATCH 06/96] Noting manual maintenance options --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 915c743d6..f7246efc0 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,27 @@ $ git push ### Setting Up The Editor's Copy +Github uses the `gh-pages` branch as source for a project web page. +This branch needs to be initialized first. + +```sh +$ git checkout --orphan gh-pages +$ git rm -rf . +$ touch index.html +$ git add index.html +$ git commit +$ git push +``` + +You can maintain `gh-pages` manually by running the following +command occasionally. + +```sh +$ make ghpages +``` + +### Automatic Update for Editor's Copy + This requires that you sign in with [Travis](https://travis-ci.org/). While you are there, enable builds for the new repository. @@ -98,7 +119,8 @@ You also need the travis command line tools, which is a Ruby script: $ sudo gem install travis ``` -Then, you need to get yourself a [new Github application token](https://github.com/settings/tokens/new). +Then, you need to get yourself a +[new Github application token](https://github.com/settings/tokens/new). You might want to use a dummy account for this purpose. The application token only needs the `public_repo` privilege. @@ -114,6 +136,9 @@ $ git commit -m "Updating Travis configuration" .travis.yml $ git push ``` +As a side benefit, Travis will now also check pull requests for +compilation errors, letting you know if things didn't work out. + ## Submitting Drafts Occasionally, you will want to submit versions of your draft to the From c1b35964383e0dbc833a0fee441f49b69ef4c841 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 20:43:32 -0700 Subject: [PATCH 07/96] Updating README --- README.md | 78 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index f7246efc0..67b51645f 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,22 @@ # Internet Draft Template Repository -The contents of this repository can be used to get started with a new -internet draft. +The contents of this repository can be used to get started with a new internet +draft. ## Getting Started -This all assumes that you have an [account](https://github.com/join) with Github. +This all assumes that you have an [account](https://github.com/join) with +Github. ### Working Group Setup -Make a [new organization](https://github.com/organizations/new) for your working group. -This guide will use the name `unicorn-wg` for your working group. +Make a [new organization](https://github.com/organizations/new) for your working +group. This guide will use the name `unicorn-wg` for your working group. ### New Draft Setup -1. [Make a new repository](https://github.com/new). This guide will use the name - name `unicorn-protocol` here. +1. [Make a new repository](https://github.com/new). This guide will use the + name name `unicorn-protocol` here. 2. Clone that repository: @@ -29,8 +30,8 @@ $ git clone https://github.com/unicorn-wg/unicorn-protocol.git $ git pull https://github.com/martinthomson/i-d-template.git master ``` -4. Choose whether you want to use markdown or xml as your input form. - If you already have a draft, then that decision is already made for you. +4. Choose whether you want to use markdown or xml as your input form. If you + already have a draft, then that decision is already made for you. 5. Move the template file into place. @@ -44,9 +45,9 @@ $ git mv template.md draft-ietf-unicorn-protocol.md $ git add draft-ietf-unicorn-protocol.xml ```` -6. Edit the draft so that it has the right name. This template uses - the `-latest` suffix in place of the usual number ('-00', or '-08'). - +6. Edit the draft so that it has the right name. This template uses the + `-latest` suffix in place of the usual number ('-00', or '-08'). + ```xml ``` @@ -88,8 +89,8 @@ $ git push ### Setting Up The Editor's Copy -Github uses the `gh-pages` branch as source for a project web page. -This branch needs to be initialized first. +Github uses the `gh-pages` branch as source for a project web page. This branch +needs to be initialized first. ```sh $ git checkout --orphan gh-pages @@ -100,8 +101,8 @@ $ git commit $ git push ``` -You can maintain `gh-pages` manually by running the following -command occasionally. +You can maintain `gh-pages` manually by running the following command +occasionally. ```sh $ make ghpages @@ -111,23 +112,30 @@ $ make ghpages This requires that you sign in with [Travis](https://travis-ci.org/). -While you are there, enable builds for the new repository. +While you are there, enable builds for the new repository. (Hit the button with +a '+' on it once you are logged in.) -You also need the travis command line tools, which is a Ruby script: +You need the Travis command line tools, which is a Ruby script: ```sh $ sudo gem install travis ``` -Then, you need to get yourself a -[new Github application token](https://github.com/settings/tokens/new). -You might want to use a dummy account for this purpose. +*WARNING*: You might want to use a dummy account for this next part to minimize +any problems from accidental leaks. Once you enable pushes from Travis, be very +careful accepting pull requests that alter `.travis.yml` or `Makefile`. Those +files can cause the value of the token to be published for all to see. You +don't want that to happen, even though tokens can be revoked easily. Only +pushes to the main repository will be able to see the token, so don't worry +about pull requests. -The application token only needs the `public_repo` privilege. -This will let it push updates to your `gh-pages` branch. +Then, you need to get yourself a [new Github application +token](https://github.com/settings/tokens/new). The application token only +needs the `public_repo` privilege. This will let it push updates to your +`gh-pages` branch. -Then, you update the Travis configuration file with an encrypted -copy of that token, as follows: +Then, you update the Travis configuration file with an encrypted copy of that +token, as follows: ```sh $ travis encrypt GH_TOKEN= -a -p @@ -136,16 +144,16 @@ $ git commit -m "Updating Travis configuration" .travis.yml $ git push ``` -As a side benefit, Travis will now also check pull requests for -compilation errors, letting you know if things didn't work out. +As a side benefit, Travis will now also check pull requests for compilation +errors, letting you know if things didn't work out. ## Submitting Drafts -Occasionally, you will want to submit versions of your draft to the -official IETF repository. The following process makes this easy. +Occasionally, you will want to submit versions of your draft to the official +IETF repository. The following process makes this easy. -1. Make a submission version of your draft. The makefile uses git - tags to work out what version to create. +1. Make a submission version of your draft. The makefile uses git tags to work + out what version to create. ```sh $ make submit @@ -154,13 +162,13 @@ $ make submit 2. [Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) that this produces. -3. Tag your repository and upload the tags. The tag you should use - is your draft name with the usual number in place of `-latest`. +3. Tag your repository and upload the tags. The tag you should use is your + draft name with the usual number in place of `-latest`. ```sh $ git tag draft-ietf-unicorn-protocol-03 $ git push --tags ``` -You can setup Travis to produce a release in Github based on tags. -See `.travis.yml` for a details. +You can setup Travis to produce a release in Github based on tags. See +`.travis.yml` for a template. From e8fc4d46cb624c5bc5005a6ed61ff077e67a3350 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 22:20:44 -0700 Subject: [PATCH 08/96] Adding panache --- Makefile | 14 +++++++-- lib/addstyle.sed | 6 ++++ lib/style.css | 78 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 96 insertions(+), 2 deletions(-) create mode 100644 lib/addstyle.sed create mode 100644 lib/style.css diff --git a/Makefile b/Makefile index 6ffd7240f..188835826 100644 --- a/Makefile +++ b/Makefile @@ -3,6 +3,7 @@ kramdown-rfc2629 ?= kramdown-rfc2629 idnits ?= idnits draft := $(basename $(firstword $(wildcard draft-*.md draft-*.xml))) + ifeq (,$(draft)) $(warning No file named draft-*.md or draft-*.xml) $(error Read README.md for setup instructions) @@ -37,10 +38,19 @@ $(next).xml: $(draft).xml $(kramdown-rfc2629) $< > $@ %.txt: %.xml - $(xml2rfc) $< $@ + $(xml2rfc) $< -o $@ --text + +ifeq "$(shell uname -s 2>/dev/null)" "Darwin" +sed_i := sed -i '' +else +sed_i := sed -i +endif %.html: %.xml - $(xml2rfc) --html $< $@ + $(xml2rfc) $< -o $@ --html + $(sed_i) -f lib/addstyle.sed $@ + +### Below this deals with updating gh-pages GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) .TRANSIENT: $(GHPAGES_TMP) diff --git a/lib/addstyle.sed b/lib/addstyle.sed new file mode 100644 index 000000000..4df07896d --- /dev/null +++ b/lib/addstyle.sed @@ -0,0 +1,6 @@ +\~~ { a\ + +} diff --git a/lib/style.css b/lib/style.css new file mode 100644 index 000000000..477ece864 --- /dev/null +++ b/lib/style.css @@ -0,0 +1,78 @@ +@viewport { + zoom: 1.0; + width: extend-to-zoom; +} + +@-ms-viewport { + width: extend-to-zoom; + zoom: 1.0; +} + +body { + font: 11pt cambria, helvetica, arial, sans-serif; + font-size-adjust: 0.5; + line-height: 130%; + margin: 1em auto; + max-width: 700px; +} + +.title, .filename, h1, h2, h3, h4 { + font-family: candara, helvetica, arial, sans-serif; + font-size-adjust: 0.5; +} +.title { font-size: 150%; } +h1 { font-size: 130%; } +h2 { font-size: 120%; } +h3, h4 { font-size: 110%; } +ul.toc >li { font-size: 95%; } +ul.toc >li >ul, .figure, caption { font-size: 90%; } + +table { + margin-left: 0em; +} +table.header { + width: 100%; +} + +table.header td { + background-color: inherit; + color: black; +} + +samp, tt, code, pre { + font: 11pt consolas, monospace; + font-size-adjust: none; +} + +pre.text, pre.text2 { + width: 90%; +} + +dt { + float: left; clear: left; + margin: 0.5em 0.5em 0 0; +} +dt:first-child { + margin-top: 0; +} +dd { + margin: 0.5em 0 0 2em; +} +dd p, dd ul { + margin-top: 0; margin-bottom: 0; +} +dd *+p { + margin-top: 0.5em; +} + +ol, ul { + padding: 0; + margin: 0.5em 0 0.5em 2em; +} +ul.toc, ul.toc ul { + margin: 0 0 0 1.5em; +} +ul.toc a:first-child { + display: inline-block; + min-width: 1.2em; +} \ No newline at end of file From 9f085a193a3166ae855b5cc8288fff197d72a3b6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 22:22:42 -0700 Subject: [PATCH 09/96] Travis speedup --- .travis.yml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 8a6c197f4..20dd0f531 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,8 +1,18 @@ language: python + +before_install: + - sudo apt-get update -qq + - sudo apt-get install -y python-lxml python-pip install: + # here we don't use the travis default virtualenv because that + # causes us to install lxml again below, doubling the build time + # when it compiles the native modules from source + - deactivate - gem install kramdown-rfc2629 - - pip install xml2rfc + - sudo pip install xml2rfc + script: make ghpages + env: global: - secure: "" From f7efba4c6b560aaba5eaedda90749520e0b39a30 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Fri, 20 Jun 2014 22:39:15 -0700 Subject: [PATCH 10/96] Missing var --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 188835826..01b51bb03 100644 --- a/Makefile +++ b/Makefile @@ -68,7 +68,7 @@ else IS_MASTER := endif -index.html: draft.html +index.html: $(draft).html cp $< $@ ghpages: index.html $(draft).txt From 1143cc34fc5ced4090915fbd8abf47ab44acda89 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 23 Jun 2014 12:47:34 -0700 Subject: [PATCH 11/96] Updates based on testing --- Makefile | 6 ++++++ README.md | 46 ++++++++++++++++++++-------------------------- 2 files changed, 26 insertions(+), 26 deletions(-) diff --git a/Makefile b/Makefile index 01b51bb03..abf2e6686 100644 --- a/Makefile +++ b/Makefile @@ -9,6 +9,8 @@ $(warning No file named draft-*.md or draft-*.xml) $(error Read README.md for setup instructions) endif +draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).xml))) + current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") ifeq "${current_ver}" "" next_ver ?= 00 @@ -30,10 +32,14 @@ clean: -rm -f $(draft).txt $(draft).html index.html -rm -f $(next).txt $(next).html -rm -f $(draft)-[0-9][0-9].xml +ifeq (md,$(draft_type)) + -rm -f $(draft).xml +endif $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ +.INTERMEDIATE: $(draft).xml %.xml: %.md $(kramdown-rfc2629) $< > $@ diff --git a/README.md b/README.md index 67b51645f..03c4e26b9 100644 --- a/README.md +++ b/README.md @@ -17,75 +17,66 @@ group. This guide will use the name `unicorn-wg` for your working group. 1. [Make a new repository](https://github.com/new). This guide will use the name name `unicorn-protocol` here. - 2. Clone that repository: - ```sh $ git clone https://github.com/unicorn-wg/unicorn-protocol.git ``` - 3. Copy the contents of this respository in: - ```sh +$ cd unicorn-protocol $ git pull https://github.com/martinthomson/i-d-template.git master ``` - 4. Choose whether you want to use markdown or xml as your input form. If you already have a draft, then that decision is already made for you. - 5. Move the template file into place. - ```sh $ git mv template.md draft-ietf-unicorn-protocol.md ``` - Or add an existing file. - ```sh $ git add draft-ietf-unicorn-protocol.xml ```` - 6. Edit the draft so that it has the right name. This template uses the `-latest` suffix in place of the usual number ('-00', or '-08'). - ```xml ``` - Or in markdown: - ```yaml docname: draft-ietf-unicorn-protocol-latest ``` - + And add it: +```sh +$ git add draft-ietf-unicorn-protocol.md +``` 7. Remove the unnecessary template files. - ```sh $ git rm template.md template.xml ``` - 8. Move the README.md template into place. - ```sh $ git rm README.md $ git mv README-template.md README.md ``` - -9. Edit the README.md and CONTRIBUTING.md files. - +9. Edit the `README.md` and `CONTRIBUTING.md` files. Note that `CONTRIBUTING.md` + file is just the latter part of `README.md`. ```sh $ vi README.md CONTRIBUTING.md # ... $ git add README.md CONTRIBUTING.md ``` - 10. Commit and push - ```sh -$ git commit -am "Initial commit" +$ git commit $ git push ``` +Optional: If you are using markdown, you might like to add the following line to your +`.gitignore` to avoid committing the intermediate XML file that this might create. +``` +draft-*.xml +``` + ### Setting Up The Editor's Copy @@ -98,7 +89,8 @@ $ git rm -rf . $ touch index.html $ git add index.html $ git commit -$ git push +$ git push --set-upstream origin gh-pages +$ git checkout master ``` You can maintain `gh-pages` manually by running the following command @@ -113,7 +105,9 @@ $ make ghpages This requires that you sign in with [Travis](https://travis-ci.org/). While you are there, enable builds for the new repository. (Hit the button with -a '+' on it once you are logged in.) +a '+' on it once you are logged in.) Note that Travis can take quite a while to +synchronize its view of all the respositories, you might have to wait a day or +so for your new repository to show up. You need the Travis command line tools, which is a Ruby script: @@ -140,7 +134,7 @@ token, as follows: ```sh $ travis encrypt GH_TOKEN= -a -p $ git add .travis.yml -$ git commit -m "Updating Travis configuration" .travis.yml +$ git commit $ git push ``` From 93f36cfc816dda87b1ed5d123a50c8831d8c5d99 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 24 Jun 2014 15:23:47 -0700 Subject: [PATCH 12/96] Fixing formatting --- README.md | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 03c4e26b9..3469aac10 100644 --- a/README.md +++ b/README.md @@ -15,57 +15,59 @@ group. This guide will use the name `unicorn-wg` for your working group. ### New Draft Setup -1. [Make a new repository](https://github.com/new). This guide will use the - name name `unicorn-protocol` here. -2. Clone that repository: +[Make a new repository](https://github.com/new). This guide will use the +name name `unicorn-protocol` here. + +Clone that repository: ```sh $ git clone https://github.com/unicorn-wg/unicorn-protocol.git ``` -3. Copy the contents of this respository in: +Copy the contents of this respository in: ```sh $ cd unicorn-protocol $ git pull https://github.com/martinthomson/i-d-template.git master ``` -4. Choose whether you want to use markdown or xml as your input form. If you - already have a draft, then that decision is already made for you. -5. Move the template file into place. +Choose whether you want to use markdown or xml as your input form. If you +already have a draft, then that decision is already made for you. + +Move the template file into place. ```sh $ git mv template.md draft-ietf-unicorn-protocol.md ``` - Or add an existing file. +Or add an existing file. ```sh $ git add draft-ietf-unicorn-protocol.xml ```` -6. Edit the draft so that it has the right name. This template uses the - `-latest` suffix in place of the usual number ('-00', or '-08'). +Edit the draft so that it has the right name. This template uses the +`-latest` suffix in place of the usual number ('-00', or '-08'). ```xml ``` - Or in markdown: +Or in markdown: ```yaml docname: draft-ietf-unicorn-protocol-latest ``` - And add it: +And add it: ```sh $ git add draft-ietf-unicorn-protocol.md ``` -7. Remove the unnecessary template files. +Remove the unnecessary template files. ```sh $ git rm template.md template.xml ``` -8. Move the README.md template into place. +Move the README.md template into place. ```sh $ git rm README.md $ git mv README-template.md README.md ``` -9. Edit the `README.md` and `CONTRIBUTING.md` files. Note that `CONTRIBUTING.md` - file is just the latter part of `README.md`. +Edit the `README.md` and `CONTRIBUTING.md` files. Note that `CONTRIBUTING.md` +file is just the latter part of `README.md`. ```sh $ vi README.md CONTRIBUTING.md # ... $ git add README.md CONTRIBUTING.md ``` -10. Commit and push +Commit and push ```sh $ git commit $ git push @@ -146,18 +148,18 @@ errors, letting you know if things didn't work out. Occasionally, you will want to submit versions of your draft to the official IETF repository. The following process makes this easy. -1. Make a submission version of your draft. The makefile uses git tags to work - out what version to create. +Make a submission version of your draft. The makefile uses git tags to work +out what version to create. ```sh $ make submit ``` -2. [Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) - that this produces. +[Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) +that this produces. -3. Tag your repository and upload the tags. The tag you should use is your - draft name with the usual number in place of `-latest`. +Tag your repository and upload the tags. The tag you should use is your +draft name with the usual number in place of `-latest`. ```sh $ git tag draft-ietf-unicorn-protocol-03 From 3f35e40c207225d40676781eceb371b933ed5336 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 26 Jun 2014 12:17:43 -0700 Subject: [PATCH 13/96] Fixing draft name selection --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index abf2e6686..69c77ba7b 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 idnits ?= idnits -draft := $(basename $(firstword $(wildcard draft-*.md draft-*.xml))) +draft := $(basename $(lastword $(wildcard draft-*.xml draft-*.md))) ifeq (,$(draft)) $(warning No file named draft-*.md or draft-*.xml) From f91ee0b709220ef7398ae9500a0d850b06224df4 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 29 Jul 2014 15:04:54 -0700 Subject: [PATCH 14/96] Sorting to get the right answer --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 69c77ba7b..3f8c9c385 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 idnits ?= idnits -draft := $(basename $(lastword $(wildcard draft-*.xml draft-*.md))) +draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)))) ifeq (,$(draft)) $(warning No file named draft-*.md or draft-*.xml) From 056169d4db150f90331dc4216ee189b2cbcb9153 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 31 Jul 2014 14:10:13 -0700 Subject: [PATCH 15/96] Tweaks --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3469aac10..614c9c108 100644 --- a/README.md +++ b/README.md @@ -158,8 +158,8 @@ $ make submit [Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) that this produces. -Tag your repository and upload the tags. The tag you should use is your -draft name with the usual number in place of `-latest`. +Then you can tag your repository and upload the tags. The tag you should +use is your draft name with the usual number in place of `-latest`. ```sh $ git tag draft-ietf-unicorn-protocol-03 From ad811bf4ef2f8b6f6391d55fe544b244acab919c Mon Sep 17 00:00:00 2001 From: Kent Watsen Date: Thu, 31 Jul 2014 18:41:52 -0400 Subject: [PATCH 16/96] Now supports drafts authored using outline.el (i.e. draft-*.org) --- Makefile | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 3f8c9c385..f40f38183 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,16 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 +outline2xml ?= outline2xml idnits ?= idnits -draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)))) +draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)) )) ifeq (,$(draft)) -$(warning No file named draft-*.md or draft-*.xml) +$(warning No file named draft-*.md or draft-*.xml or draft-*.org) $(error Read README.md for setup instructions) endif -draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).xml))) +draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).xml) $(draft).org )) current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") ifeq "${current_ver}" "" @@ -35,6 +36,9 @@ clean: ifeq (md,$(draft_type)) -rm -f $(draft).xml endif +ifeq (org,$(draft_type)) + -rm -f $(draft).xml +endif $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ @@ -43,6 +47,9 @@ $(next).xml: $(draft).xml %.xml: %.md $(kramdown-rfc2629) $< > $@ +%.xml: %.org + $(outline2xml) -n "$@" $< > $@ + %.txt: %.xml $(xml2rfc) $< -o $@ --text From 3744cdc0f8440c13b35149e9d25f609d1f25abaa Mon Sep 17 00:00:00 2001 From: Kent Watsen Date: Mon, 4 Aug 2014 18:13:14 -0400 Subject: [PATCH 17/96] Fixed ordering issue found by Martin. Added links for tools called by Makefile. Added outline as an input format. --- Makefile | 12 +++++++++--- README.md | 4 ++-- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index f40f38183..21b79ebf7 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,12 @@ +# In case your system doesn't have any of these tools: +# https://pypi.python.org/pypi/xml2rfc +# https://github.com/cabo/kramdown-rfc2629 +# https://github.com/Juniper/libslax/tree/master/doc/oxtradoc +# https://tools.ietf.org/tools/idnits/ + xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 -outline2xml ?= outline2xml +oxtradoc ?= oxtradoc.in idnits ?= idnits draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)) )) @@ -10,7 +16,7 @@ $(warning No file named draft-*.md or draft-*.xml or draft-*.org) $(error Read README.md for setup instructions) endif -draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).xml) $(draft).org )) +draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).org $(draft).xml) )) current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") ifeq "${current_ver}" "" @@ -48,7 +54,7 @@ $(next).xml: $(draft).xml $(kramdown-rfc2629) $< > $@ %.xml: %.org - $(outline2xml) -n "$@" $< > $@ + $(oxtradoc) -m outline-to-xml -n "$@" $< > $@ %.txt: %.xml $(xml2rfc) $< -o $@ --text diff --git a/README.md b/README.md index 614c9c108..3514dc788 100644 --- a/README.md +++ b/README.md @@ -27,8 +27,8 @@ Copy the contents of this respository in: $ cd unicorn-protocol $ git pull https://github.com/martinthomson/i-d-template.git master ``` -Choose whether you want to use markdown or xml as your input form. If you -already have a draft, then that decision is already made for you. +Choose whether you want to use markdown, outline, or xml as your input form. +If you already have a draft, then that decision is already made for you. Move the template file into place. ```sh From c7862055febcd7ef3a25a8a4e42aa564f07d5dba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A5l-Erik=20Martinsen?= Date: Fri, 10 Oct 2014 22:13:46 +0200 Subject: [PATCH 18/96] Adding rfcdiff --- Makefile | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 21b79ebf7..2f09dff6d 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,7 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 oxtradoc ?= oxtradoc.in idnits ?= idnits +rfcdiff ?= rfcdiff draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)) )) @@ -25,8 +26,9 @@ else next_ver ?= $(shell printf "%.2d" $$((1$(current_ver)-99))) endif next := $(draft)-$(next_ver) +current := $(draft)-$(current_ver) -.PHONY: latest submit clean +.PHONY: latest submit diff clean latest: $(draft).txt $(draft).html @@ -35,10 +37,18 @@ submit: $(next).txt idnits: $(next).txt $(idnits) $< +diff: $(draft).txt + -git show $(current):$(draft)$(draft_type) > $(current).xml + -$(xml2rfc) $(current).xml --text + -$(rfcdiff) --browse $(draft).txt $(current).txt + -rm -f $(current).xml + -rm -f $(current).txt + clean: -rm -f $(draft).txt $(draft).html index.html -rm -f $(next).txt $(next).html -rm -f $(draft)-[0-9][0-9].xml + -rm -f *.diff.html ifeq (md,$(draft_type)) -rm -f $(draft).xml endif From 1b791a8b348e92403994ec89464d6db1e48aaeb2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A5l-Erik=20Martinsen?= Date: Mon, 13 Oct 2014 10:21:04 +0200 Subject: [PATCH 19/96] More toying with Makefile an diff cration. --- Makefile | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 2f09dff6d..616758220 100644 --- a/Makefile +++ b/Makefile @@ -10,14 +10,14 @@ oxtradoc ?= oxtradoc.in idnits ?= idnits rfcdiff ?= rfcdiff -draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)) )) +draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)))) ifeq (,$(draft)) $(warning No file named draft-*.md or draft-*.xml or draft-*.org) $(error Read README.md for setup instructions) endif -draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).org $(draft).xml) )) +draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).org $(draft).xml))) current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") ifeq "${current_ver}" "" @@ -26,7 +26,7 @@ else next_ver ?= $(shell printf "%.2d" $$((1$(current_ver)-99))) endif next := $(draft)-$(next_ver) -current := $(draft)-$(current_ver) +diff_ver := $(draft)-$(current_ver) .PHONY: latest submit diff clean @@ -37,18 +37,15 @@ submit: $(next).txt idnits: $(next).txt $(idnits) $< -diff: $(draft).txt - -git show $(current):$(draft)$(draft_type) > $(current).xml - -$(xml2rfc) $(current).xml --text - -$(rfcdiff) --browse $(draft).txt $(current).txt - -rm -f $(current).xml - -rm -f $(current).txt +diff: $(draft).txt $(draft)-$(current_ver).txt + $(rfcdiff) $* clean: -rm -f $(draft).txt $(draft).html index.html -rm -f $(next).txt $(next).html -rm -f $(draft)-[0-9][0-9].xml -rm -f *.diff.html + -rm -f $(diff_ver).txt ifeq (md,$(draft_type)) -rm -f $(draft).xml endif @@ -59,6 +56,9 @@ endif $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ +$(diff_ver).xml: $(draft).xml $(draft).txt + git show $(current):$(draft)$(draft_type) > $(diff_ver)$(draft_type) + .INTERMEDIATE: $(draft).xml %.xml: %.md $(kramdown-rfc2629) $< > $@ From 5e32d112047ccb8d204e6184626e63fe27f63cee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A5l-Erik=20Martinsen?= Date: Tue, 14 Oct 2014 12:40:30 +0200 Subject: [PATCH 20/96] Based on input from Martin. --- Makefile | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/Makefile b/Makefile index 616758220..e09bf2df3 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ xml2rfc ?= xml2rfc kramdown-rfc2629 ?= kramdown-rfc2629 oxtradoc ?= oxtradoc.in idnits ?= idnits -rfcdiff ?= rfcdiff +rfcdiff ?= rfcdiff --browse draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)))) @@ -20,7 +20,7 @@ endif draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).org $(draft).xml))) current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") -ifeq "${current_ver}" "" +ifeq (,$(current_ver)) next_ver ?= 00 else next_ver ?= $(shell printf "%.2d" $$((1$(current_ver)-99))) @@ -37,27 +37,25 @@ submit: $(next).txt idnits: $(next).txt $(idnits) $< -diff: $(draft).txt $(draft)-$(current_ver).txt - $(rfcdiff) $* - clean: -rm -f $(draft).txt $(draft).html index.html -rm -f $(next).txt $(next).html - -rm -f $(draft)-[0-9][0-9].xml + -rm -f $(addprefix $(draft)-[0-9][0-9].,xml md org) -rm -f *.diff.html - -rm -f $(diff_ver).txt -ifeq (md,$(draft_type)) - -rm -f $(draft).xml -endif -ifeq (org,$(draft_type)) +ifneq (xml,$(draft_type)) -rm -f $(draft).xml endif $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ -$(diff_ver).xml: $(draft).xml $(draft).txt - git show $(current):$(draft)$(draft_type) > $(diff_ver)$(draft_type) +ifneq (,$(current_ver)) +diff: $(draft).txt $(draft)-$(current_ver).txt + $(rfcdiff) $* + +$(draft)-$(current_ver).$(draft_type): + git show $(draft)-$(current_ver):$(draft).$(draft_type) > $@ +endif .INTERMEDIATE: $(draft).xml %.xml: %.md @@ -69,7 +67,7 @@ $(diff_ver).xml: $(draft).xml $(draft).txt %.txt: %.xml $(xml2rfc) $< -o $@ --text -ifeq "$(shell uname -s 2>/dev/null)" "Darwin" +ifeq (Darwin, $(shell uname -s 2>/dev/null)) sed_i := sed -i '' else sed_i := sed -i From fccb9497abc0de8c8b9f4001a8fa67b474c2284d Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 14 Oct 2014 21:26:02 -0700 Subject: [PATCH 21/96] Fixing intermediate handling --- Makefile | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index e09bf2df3..41800181c 100644 --- a/Makefile +++ b/Makefile @@ -10,7 +10,7 @@ oxtradoc ?= oxtradoc.in idnits ?= idnits rfcdiff ?= rfcdiff --browse -draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.md)) $(sort $(wildcard draft-*.org)))) +draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.org)) $(sort $(wildcard draft-*.md)))) ifeq (,$(draft)) $(warning No file named draft-*.md or draft-*.xml or draft-*.org) @@ -39,8 +39,7 @@ idnits: $(next).txt clean: -rm -f $(draft).txt $(draft).html index.html - -rm -f $(next).txt $(next).html - -rm -f $(addprefix $(draft)-[0-9][0-9].,xml md org) + -rm -f $(addprefix $(draft)-[0-9][0-9].,xml md org html txt) -rm -f *.diff.html ifneq (xml,$(draft_type)) -rm -f $(draft).xml @@ -50,11 +49,12 @@ $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ ifneq (,$(current_ver)) +.INTERMEDIATE: $(addprefix $(draft)-$(current_ver),.txt $(draft_type)) diff: $(draft).txt $(draft)-$(current_ver).txt - $(rfcdiff) $* + -$(rfcdiff) $^ -$(draft)-$(current_ver).$(draft_type): - git show $(draft)-$(current_ver):$(draft).$(draft_type) > $@ +$(draft)-$(current_ver)$(draft_type): + git show $(draft)-$(current_ver):$(draft)$(draft_type) > $@ endif .INTERMEDIATE: $(draft).xml From 35084ebc56d4fd2250e31c39fdba93025234df74 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 05:48:16 +0200 Subject: [PATCH 22/96] Adding update target --- Makefile | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 41800181c..0ae55c24e 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ endif next := $(draft)-$(next_ver) diff_ver := $(draft)-$(current_ver) -.PHONY: latest submit diff clean +.PHONY: latest submit diff clean update latest: $(draft).txt $(draft).html @@ -77,6 +77,19 @@ endif $(xml2rfc) $< -o $@ --html $(sed_i) -f lib/addstyle.sed $@ +### Update this Makefile + +# The prerequisites here are what is updated +update: Makefile lib .gitignore + git diff --quiet $^ || \ + (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) + git remote | grep i-d-template > /dev/null || \ + git remote add i-d-template https://github.com/martinthomson/i-d-template.git + git fetch i-d-template + git checkout i-d-template/master $^ + git diff --quiet $^ || \ + git commit -m "Update of $^ from i-d-template/$$(git rev-parse i-d-template/master)" $^ + ### Below this deals with updating gh-pages GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) From f2a426215e94843cdccd8db9635b9b9f31aeddab Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:14:16 +0200 Subject: [PATCH 23/96] Permitting local changes to files --- .gitignore | 1 + Makefile | 15 +++++++++++++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 259948410..c976e7182 100644 --- a/.gitignore +++ b/.gitignore @@ -5,4 +5,5 @@ *.swp /*-[0-9][0-9].xml .refcache +.i-d-template diff --git a/Makefile b/Makefile index 0ae55c24e..a6cb32fce 100644 --- a/Makefile +++ b/Makefile @@ -80,15 +80,26 @@ endif ### Update this Makefile # The prerequisites here are what is updated +.TRANSIENT: .i-d-template.diff update: Makefile lib .gitignore + if [ -f .i-d-template ]; then \ + git diff --exit-code $^ > .i-d-template.diff && \ + rm -f .i-d-template.diff \ + fi git diff --quiet $^ || \ (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) git remote | grep i-d-template > /dev/null || \ git remote add i-d-template https://github.com/martinthomson/i-d-template.git git fetch i-d-template - git checkout i-d-template/master $^ - git diff --quiet $^ || \ + [ -f .i-d-template ] && [ $$(git rev-parse i-d-template/master) = $$(cat .i-d-template) ] || \ + git checkout i-d-template/master $^ + git diff --quiet $^ && rm -f .i-d-template.diff || \ git commit -m "Update of $^ from i-d-template/$$(git rev-parse i-d-template/master)" $^ + if [ -f .i-d-template.diff ]; then \ + git apply .i-d-template.diff && \ + git commit -m "Restoring local changes to $$(git diff --name-only $^ | paste -s -d ' ' -)" $^ \ + fi + git rev-parse i-d-template/master > .i-d-template ### Below this deals with updating gh-pages From 3035e3855cfa6c047be4cb352f0286d7549cf029 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:15:49 +0200 Subject: [PATCH 24/96] I don't like using if in Makefile shells --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index a6cb32fce..28551080e 100644 --- a/Makefile +++ b/Makefile @@ -84,7 +84,7 @@ endif update: Makefile lib .gitignore if [ -f .i-d-template ]; then \ git diff --exit-code $^ > .i-d-template.diff && \ - rm -f .i-d-template.diff \ + rm -f .i-d-template.diff; \ fi git diff --quiet $^ || \ (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) @@ -97,7 +97,7 @@ update: Makefile lib .gitignore git commit -m "Update of $^ from i-d-template/$$(git rev-parse i-d-template/master)" $^ if [ -f .i-d-template.diff ]; then \ git apply .i-d-template.diff && \ - git commit -m "Restoring local changes to $$(git diff --name-only $^ | paste -s -d ' ' -)" $^ \ + git commit -m "Restoring local changes to $$(git diff --name-only $^ | paste -s -d ' ' -)" $^; \ fi git rev-parse i-d-template/master > .i-d-template From 64179e5626524b0506189bc234f9dda74448f3bd Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:18:35 +0200 Subject: [PATCH 25/96] Getting revisions right --- Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index 28551080e..4e8be0a6c 100644 --- a/Makefile +++ b/Makefile @@ -83,17 +83,17 @@ endif .TRANSIENT: .i-d-template.diff update: Makefile lib .gitignore if [ -f .i-d-template ]; then \ - git diff --exit-code $^ > .i-d-template.diff && \ + git diff --exit-code $$(cat .i-d-template) -- $^ > .i-d-template.diff && \ rm -f .i-d-template.diff; \ fi - git diff --quiet $^ || \ + git diff --quiet -- $^ || \ (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) git remote | grep i-d-template > /dev/null || \ git remote add i-d-template https://github.com/martinthomson/i-d-template.git git fetch i-d-template [ -f .i-d-template ] && [ $$(git rev-parse i-d-template/master) = $$(cat .i-d-template) ] || \ git checkout i-d-template/master $^ - git diff --quiet $^ && rm -f .i-d-template.diff || \ + git diff --quiet -- $^ && rm -f .i-d-template.diff || \ git commit -m "Update of $^ from i-d-template/$$(git rev-parse i-d-template/master)" $^ if [ -f .i-d-template.diff ]; then \ git apply .i-d-template.diff && \ From 0154e8621fb28e4388e980193c16795b5a304cb1 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:27:29 +0200 Subject: [PATCH 26/96] Removing ugly sed hack --- Makefile | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index 4e8be0a6c..5e2a5cd2d 100644 --- a/Makefile +++ b/Makefile @@ -67,20 +67,14 @@ endif %.txt: %.xml $(xml2rfc) $< -o $@ --text -ifeq (Darwin, $(shell uname -s 2>/dev/null)) -sed_i := sed -i '' -else -sed_i := sed -i -endif - -%.html: %.xml +%.htmltmp: %.xml $(xml2rfc) $< -o $@ --html - $(sed_i) -f lib/addstyle.sed $@ +%.html: %.htmltmp + sed -f lib/addstyle.sed $@ > $< ### Update this Makefile - # The prerequisites here are what is updated -.TRANSIENT: .i-d-template.diff +.INTERMEDIATE: .i-d-template.diff update: Makefile lib .gitignore if [ -f .i-d-template ]; then \ git diff --exit-code $$(cat .i-d-template) -- $^ > .i-d-template.diff && \ @@ -104,7 +98,7 @@ update: Makefile lib .gitignore ### Below this deals with updating gh-pages GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) -.TRANSIENT: $(GHPAGES_TMP) +.INTERMEDIATE: $(GHPAGES_TMP) ifeq (,$(TRAVIS_COMMIT)) GIT_ORIG := $(shell git branch | grep '*' | cut -c 3-) else From 4302b054b69374e53156a969dce334e1b1268b4c Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:30:18 +0200 Subject: [PATCH 27/96] Removing false error --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 5e2a5cd2d..88f4b5769 100644 --- a/Makefile +++ b/Makefile @@ -76,7 +76,7 @@ endif # The prerequisites here are what is updated .INTERMEDIATE: .i-d-template.diff update: Makefile lib .gitignore - if [ -f .i-d-template ]; then \ + -if [ -f .i-d-template ]; then \ git diff --exit-code $$(cat .i-d-template) -- $^ > .i-d-template.diff && \ rm -f .i-d-template.diff; \ fi From ef1788d913ae96028371eac63151a9e34078495e Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 21 Oct 2014 06:31:31 +0200 Subject: [PATCH 28/96] Fixing ordering --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 88f4b5769..f4ff969d2 100644 --- a/Makefile +++ b/Makefile @@ -76,12 +76,12 @@ endif # The prerequisites here are what is updated .INTERMEDIATE: .i-d-template.diff update: Makefile lib .gitignore + git diff --quiet -- $^ || \ + (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) -if [ -f .i-d-template ]; then \ git diff --exit-code $$(cat .i-d-template) -- $^ > .i-d-template.diff && \ rm -f .i-d-template.diff; \ fi - git diff --quiet -- $^ || \ - (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) git remote | grep i-d-template > /dev/null || \ git remote add i-d-template https://github.com/martinthomson/i-d-template.git git fetch i-d-template From ae6119f68b58eed9e794ea97d1499d5c86109f96 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Oct 2014 20:38:51 -0700 Subject: [PATCH 29/96] Updating to include PDF --- Makefile | 55 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 46 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index f4ff969d2..d1e231945 100644 --- a/Makefile +++ b/Makefile @@ -1,15 +1,38 @@ -# In case your system doesn't have any of these tools: -# https://pypi.python.org/pypi/xml2rfc -# https://github.com/cabo/kramdown-rfc2629 -# https://github.com/Juniper/libslax/tree/master/doc/oxtradoc -# https://tools.ietf.org/tools/idnits/ +# Original makefile from https://github.com/martinthomson/i-d-template +# The following tools are used by this file. +# All are assumed to be on the path, but you can override these +# in the environment, or command line. + +# Mandatory: +# https://pypi.python.org/pypi/xml2rfc xml2rfc ?= xml2rfc + +# If you are using markdown files: +# https://github.com/cabo/kramdown-rfc2629 kramdown-rfc2629 ?= kramdown-rfc2629 + +# If you are using outline files: +# https://github.com/Juniper/libslax/tree/master/doc/oxtradoc oxtradoc ?= oxtradoc.in + +# For sanity checkout your draft: +# https://tools.ietf.org/tools/idnits/ idnits ?= idnits + +# For diff: +# https://tools.ietf.org/tools/rfcdiff/ rfcdiff ?= rfcdiff --browse +# For generating PDF: +# https://www.gnu.org/software/enscript/ +enscript ?= enscript +# http://www.ghostscript.com/ +ps2pdf ?= ps2pdf + + +## Work out what to build + draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.org)) $(sort $(wildcard draft-*.md)))) ifeq (,$(draft)) @@ -28,9 +51,15 @@ endif next := $(draft)-$(next_ver) diff_ver := $(draft)-$(current_ver) -.PHONY: latest submit diff clean update -latest: $(draft).txt $(draft).html +## Targets + +.PHONY: latest txt html pdf submit diff clean update ghpages + +latest: txt html +txt: $(draft).txt +html: $(draft).html +pdf: $(draft).pdf submit: $(next).txt @@ -45,6 +74,8 @@ ifneq (xml,$(draft_type)) -rm -f $(draft).xml endif +## diff + $(next).xml: $(draft).xml sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ @@ -57,6 +88,8 @@ $(draft)-$(current_ver)$(draft_type): git show $(draft)-$(current_ver):$(draft)$(draft_type) > $@ endif +## Recipes + .INTERMEDIATE: $(draft).xml %.xml: %.md $(kramdown-rfc2629) $< > $@ @@ -72,7 +105,11 @@ endif %.html: %.htmltmp sed -f lib/addstyle.sed $@ > $< -### Update this Makefile +%.pdf: %.txt + $(enscript) --margins 76::76: -B -q -p - $^ | $(ps2pdf) - $@ + +## Update this Makefile + # The prerequisites here are what is updated .INTERMEDIATE: .i-d-template.diff update: Makefile lib .gitignore @@ -95,7 +132,7 @@ update: Makefile lib .gitignore fi git rev-parse i-d-template/master > .i-d-template -### Below this deals with updating gh-pages +## Update the gh-pages branch with useful files GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) .INTERMEDIATE: $(GHPAGES_TMP) From 8c7169bc92862413f9064f727a657bc608d3ca1e Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Oct 2014 20:47:22 -0700 Subject: [PATCH 30/96] Updating README --- Makefile | 4 ++-- README-template.md | 34 +++++++++++++++++++++++++++------- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index d1e231945..33def0fd7 100644 --- a/Makefile +++ b/Makefile @@ -67,8 +67,8 @@ idnits: $(next).txt $(idnits) $< clean: - -rm -f $(draft).txt $(draft).html index.html - -rm -f $(addprefix $(draft)-[0-9][0-9].,xml md org html txt) + -rm -f $(draft).{txt,html,pdf} index.html + -rm -f $(draft)-[0-9][0-9].{xml,md,org,txt,html,pdf} -rm -f *.diff.html ifneq (xml,$(draft_type)) -rm -f $(draft).xml diff --git a/README-template.md b/README-template.md index fe59cd667..5bbd19bf5 100644 --- a/README-template.md +++ b/README-template.md @@ -27,11 +27,11 @@ meaning of the specification), you can either: a) Fork this repository and submit a pull request; this is the lowest friction way to get editorial changes in. - + b) Submit a new issue to Github, and mention that you believe it is editorial in the issue body. It is not necessary to notify the mailing list for editorial issues. - + c) Make comments on individual commits in Github. Note that this feedback is processed only with best effort by the editors, so it should only be used for quick editorial suggestions or questions. @@ -44,6 +44,26 @@ providing a link to the issue in the message body. appropriate place to discuss design issues is on the mailing list itself. +## Building the Draft + +In order to build a copy of the draft, you will need to install xml2rfc. This +requires Python 2.7 and can be installed using `pip`: + +```sh +$ pip install xml2rfc +``` + +You may also need to install kramdown-xml2rfc, which requires Ruby and can be +installed using the roby package manager, `gem`: + +```sh +$ gem install kramdown-xml2rfc +``` + +Other tools can be used to produce PDF files, or to provide a comparison. These +tools - and where to find them - are described in the `Makefile`. + + ## NOTE WELL Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor @@ -55,22 +75,22 @@ are addressed to: * The IETF plenary session * The IESG, or any member thereof on behalf of the IESG - * Any IETF mailing list, including the IETF list itself, any working group + * Any IETF mailing list, including the IETF list itself, any working group or design team list, or any other list functioning under IETF auspices * Any IETF working group or portion thereof * Any Birds of a Feather (BOF) session * The IAB or any member thereof on behalf of the IAB * The RFC Editor or the Internet-Drafts function - * All IETF Contributions are subject to the rules of - [RFC 5378](https://tools.ietf.org/html/rfc5378) and - [RFC 3979](https://tools.ietf.org/html/rfc3979) + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). Statements made outside of an IETF session, mailing list or other function, that are clearly not intended to be input to an IETF activity, group or function, are not IETF Contributions in the context of this notice. -Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC 3979](https://tools.ietf.org/html/rfc3979) for details. A participant in any IETF activity is deemed to accept all IETF rules of From 7ea736940644910cfc377de2b5ced39bda94139a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Oct 2014 21:04:05 -0700 Subject: [PATCH 31/96] Fixing variables on HTML --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 33def0fd7..0b5b12296 100644 --- a/Makefile +++ b/Makefile @@ -103,7 +103,7 @@ endif %.htmltmp: %.xml $(xml2rfc) $< -o $@ --html %.html: %.htmltmp - sed -f lib/addstyle.sed $@ > $< + sed -f lib/addstyle.sed $< > $@ %.pdf: %.txt $(enscript) --margins 76::76: -B -q -p - $^ | $(ps2pdf) - $@ From ffa51179eb9e824958f5cd55fce29c0a3b347d74 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Oct 2014 21:06:36 -0700 Subject: [PATCH 32/96] ignoring pdf --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index c976e7182..3c71c47f5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ *.redxml *.txt *.html +*.pdf *~ *.swp /*-[0-9][0-9].xml From 88e3bba285e16875cd780d9c32eff76e331f205c Mon Sep 17 00:00:00 2001 From: wkumari Date: Thu, 30 Oct 2014 15:11:16 -0400 Subject: [PATCH 33/96] Fix make clean so it doesn't delete the source XML. Add a readme target, that copies the draft txt to README.md (after wrapping in backticks for formatting) --- Makefile | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 0b5b12296..36bb1880a 100644 --- a/Makefile +++ b/Makefile @@ -66,11 +66,17 @@ submit: $(next).txt idnits: $(next).txt $(idnits) $< +## If you'd like the main github page to show the draft text. +readme: $(next).txt + @echo '```' > README.md + @cat $(next).txt >> README.md + @echo '```' >> README.md + clean: -rm -f $(draft).{txt,html,pdf} index.html -rm -f $(draft)-[0-9][0-9].{xml,md,org,txt,html,pdf} -rm -f *.diff.html -ifneq (xml,$(draft_type)) +ifneq (.xml,$(draft_type)) -rm -f $(draft).xml endif From b853b00b272bc8850556cdb5fde366429920fd44 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 13 Nov 2014 12:27:10 -1000 Subject: [PATCH 34/96] Explaining tagging a little better. Closes #8. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3514dc788..36efed32c 100644 --- a/README.md +++ b/README.md @@ -148,8 +148,10 @@ errors, letting you know if things didn't work out. Occasionally, you will want to submit versions of your draft to the official IETF repository. The following process makes this easy. -Make a submission version of your draft. The makefile uses git tags to work -out what version to create. +Make a submission version of your draft. The makefile uses git tags to work out +what version to create. It looks for the last version number you have tagged +the draft with and calculates the next version. When there are no tags, it +generates a `-00` version. ```sh $ make submit From f94f69cf0ff6dc69af4fc67a3580d3a569872fe5 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 13 Nov 2014 12:28:13 -1000 Subject: [PATCH 35/96] Removing dead text --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index 36efed32c..93cc11349 100644 --- a/README.md +++ b/README.md @@ -167,6 +167,3 @@ use is your draft name with the usual number in place of `-latest`. $ git tag draft-ietf-unicorn-protocol-03 $ git push --tags ``` - -You can setup Travis to produce a release in Github based on tags. See -`.travis.yml` for a template. From fb9f8d04eaf42bc83c88b9a5755bc801c4c1bd4e Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 13 Nov 2014 12:30:32 -1000 Subject: [PATCH 36/96] Moving submission guidance to a new file. --- Makefile | 2 +- README.md | 23 +---------------------- SUBMITTING.md | 24 ++++++++++++++++++++++++ 3 files changed, 26 insertions(+), 23 deletions(-) create mode 100644 SUBMITTING.md diff --git a/Makefile b/Makefile index 36bb1880a..215b96215 100644 --- a/Makefile +++ b/Makefile @@ -118,7 +118,7 @@ endif # The prerequisites here are what is updated .INTERMEDIATE: .i-d-template.diff -update: Makefile lib .gitignore +update: Makefile lib .gitignore SUBMITTING.md git diff --quiet -- $^ || \ (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) -if [ -f .i-d-template ]; then \ diff --git a/README.md b/README.md index 93cc11349..9f4d482da 100644 --- a/README.md +++ b/README.md @@ -145,25 +145,4 @@ errors, letting you know if things didn't work out. ## Submitting Drafts -Occasionally, you will want to submit versions of your draft to the official -IETF repository. The following process makes this easy. - -Make a submission version of your draft. The makefile uses git tags to work out -what version to create. It looks for the last version number you have tagged -the draft with and calculates the next version. When there are no tags, it -generates a `-00` version. - -```sh -$ make submit -``` - -[Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) -that this produces. - -Then you can tag your repository and upload the tags. The tag you should -use is your draft name with the usual number in place of `-latest`. - -```sh -$ git tag draft-ietf-unicorn-protocol-03 -$ git push --tags -``` +See `SUBMITTING.md`. diff --git a/SUBMITTING.md b/SUBMITTING.md new file mode 100644 index 000000000..ab11668c4 --- /dev/null +++ b/SUBMITTING.md @@ -0,0 +1,24 @@ +# Submitting Drafts + +Occasionally, you will want to submit versions of your draft to the official +IETF repository. The following process makes this easy. + +Make a submission version of your draft. The makefile uses git tags to work out +what version to create. It looks for the last version number you have tagged +the draft with and calculates the next version. When there are no tags, it +generates a `-00` version. + +```sh +$ make submit +``` + +[Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) +that this produces. + +Then you can tag your repository and upload the tags. The tag you should +use is your draft name with the usual number in place of `-latest`. + +```sh +$ git tag draft-ietf-unicorn-protocol-03 +$ git push --tags +``` From 366d8d9d5055fe757bd3294f145cb4ba19ad095a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 26 Nov 2014 12:46:02 -0800 Subject: [PATCH 37/96] Updating travis sync notes --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9f4d482da..378463179 100644 --- a/README.md +++ b/README.md @@ -107,9 +107,8 @@ $ make ghpages This requires that you sign in with [Travis](https://travis-ci.org/). While you are there, enable builds for the new repository. (Hit the button with -a '+' on it once you are logged in.) Note that Travis can take quite a while to -synchronize its view of all the respositories, you might have to wait a day or -so for your new repository to show up. +a '+' on it once you are logged in.) Note that Travis only synchronizes +repositories with github once a day, so you might have to force a refresh. You need the Travis command line tools, which is a Ruby script: From 29322c0944cf44a48fa82ab0e3afb7e1d3b519ca Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 5 Mar 2015 20:15:03 -0800 Subject: [PATCH 38/96] setup-ghpages --- Makefile | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/Makefile b/Makefile index 215b96215..7c632f7b1 100644 --- a/Makefile +++ b/Makefile @@ -144,6 +144,9 @@ GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) .INTERMEDIATE: $(GHPAGES_TMP) ifeq (,$(TRAVIS_COMMIT)) GIT_ORIG := $(shell git branch | grep '*' | cut -c 3-) +ifneq (,$(findstring detached from,$(GIT_ORIG))) +GIT_ORIG := $(shell git show -s --format='format:%H') +endif else GIT_ORIG := $(TRAVIS_COMMIT) endif @@ -160,6 +163,8 @@ index.html: $(draft).html cp $< $@ ghpages: index.html $(draft).txt + @git show -s gh-pages > /dev/null 2>&1 || \ + ! echo 'Error: No gh-pages branch, run `make setup-ghpages` to initialize it.' ifneq (,$(or $(IS_LOCAL),$(IS_MASTER))) mkdir $(GHPAGES_TMP) cp -f $^ $(GHPAGES_TMP) @@ -185,3 +190,23 @@ endif -git checkout -qf "$(GIT_ORIG)" -rm -rf $(GHPAGES_TMP) endif + +.PHONY: setup-ghpages +setup-ghpages: +# Check if the gh-pages branch already exists locally + @if git show -s gh-pages >/dev/null 2>&1; then \ + ! echo "Error: gh-pages branch already exists"; \ + else true; fi +# Check if the gh-pages branch already exists on origin + @git show -s origin/gh-pages >/dev/null 2>&1 && \ + (echo 'Warning: gh-pages already present on the origin'; \ + git checkout -b gh-pages origin/gh-pages && \ + ! git checkout -qf $(GIT_ORIG) ) + @echo "Initializing gh-pages branch" + git checkout --orphan gh-pages + git rm -rf . + touch index.html + git add index.html + git commit -m "Automatic setup of gh-pages." + git push --set-upstream origin gh-pages + git checkout -qf "$(GIT_ORIG)" From 7df9c0a9112543cf949ee71e61f16ba43d88b0c3 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 5 Mar 2015 20:23:24 -0800 Subject: [PATCH 39/96] Update docs --- .travis.yml | 18 ---------------- Makefile | 3 +-- README.md | 61 ++++++++++++++++++++++++++++++++--------------------- 3 files changed, 38 insertions(+), 44 deletions(-) diff --git a/.travis.yml b/.travis.yml index 20dd0f531..4720bdbab 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,21 +12,3 @@ install: - sudo pip install xml2rfc script: make ghpages - -env: - global: - - secure: "" - -before_deploy: make submit -deploy: - provider: releases - api-key: - secure: "" - file: - - $TRAVIS_TAG.txt - - $TRAVIS_TAG.html - - $TRAVIS_TAG.xml - skip_cleanup: true - on: - branch: master - tags: true diff --git a/Makefile b/Makefile index 7c632f7b1..abd573912 100644 --- a/Makefile +++ b/Makefile @@ -200,8 +200,7 @@ setup-ghpages: # Check if the gh-pages branch already exists on origin @git show -s origin/gh-pages >/dev/null 2>&1 && \ (echo 'Warning: gh-pages already present on the origin'; \ - git checkout -b gh-pages origin/gh-pages && \ - ! git checkout -qf $(GIT_ORIG) ) + git branch gh-pages origin/gh-pages; false) @echo "Initializing gh-pages branch" git checkout --orphan gh-pages git rm -rf . diff --git a/README.md b/README.md index 378463179..895184576 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ draft. ## Getting Started This all assumes that you have an [account](https://github.com/join) with -Github. +GitHub. ### Working Group Setup @@ -82,17 +82,11 @@ draft-*.xml ### Setting Up The Editor's Copy -Github uses the `gh-pages` branch as source for a project web page. This branch -needs to be initialized first. +GitHub uses the `gh-pages` branch as source for a project web page. This branch +needs to be initialized first. The `setup-ghpages` make target does that: ```sh -$ git checkout --orphan gh-pages -$ git rm -rf . -$ touch index.html -$ git add index.html -$ git commit -$ git push --set-upstream origin gh-pages -$ git checkout master +$ make setup-ghpages ``` You can maintain `gh-pages` manually by running the following command @@ -102,29 +96,33 @@ occasionally. $ make ghpages ``` +Or, you can run an automatic commit after each checkin with Travis. + + ### Automatic Update for Editor's Copy This requires that you sign in with [Travis](https://travis-ci.org/). -While you are there, enable builds for the new repository. (Hit the button with -a '+' on it once you are logged in.) Note that Travis only synchronizes -repositories with github once a day, so you might have to force a refresh. +First enable builds for the new repository on the Travis site. (Hit the button +with a '+' on it once you are logged in.) Note that Travis only synchronizes +repositories with GitHub once a day, so you might have to force a refresh. -You need the Travis command line tools, which is a Ruby script: +You will need the Travis command line tool for the next step; this is available +as a [Ruby](https://www.ruby-lang.org/) [gem](https://rubygems.org/): ```sh $ sudo gem install travis ``` *WARNING*: You might want to use a dummy account for this next part to minimize -any problems from accidental leaks. Once you enable pushes from Travis, be very -careful accepting pull requests that alter `.travis.yml` or `Makefile`. Those -files can cause the value of the token to be published for all to see. You -don't want that to happen, even though tokens can be revoked easily. Only -pushes to the main repository will be able to see the token, so don't worry -about pull requests. - -Then, you need to get yourself a [new Github application +any problems from accidental leaks of your key. Once you enable pushes from +Travis, be very careful accepting pull requests that alter `.travis.yml` or +`Makefile`. Those files can cause the value of the token to be published for +all to see. You don't want that to happen, even though tokens can be revoked +easily. Only pushes to the main repository will be able to see the token, so +don't worry about pull requests. + +Then, you need to get yourself a [new GitHub application token](https://github.com/settings/tokens/new). The application token only needs the `public_repo` privilege. This will let it push updates to your `gh-pages` branch. @@ -139,8 +137,23 @@ $ git commit $ git push ``` -As a side benefit, Travis will now also check pull requests for compilation -errors, letting you know if things didn't work out. +As a side benefit, Travis will now also check pull requests for errors, letting +you know if things didn't work out so that you don't merge anything suspect. + + +## Updating the Makefile + +Occasionally improvements and changes are made to the Makefile or the support +files in this repository. The `update` make target looks after the update of +the core files. + +```sh +$ make update +``` + +This script is cunning enough to handle merging any simple changes that you +might have made to the Makefile yourself, such as adding targets. + ## Submitting Drafts From 773410de70789a23a6d3567bc31f492025204eec Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 5 Mar 2015 22:09:55 -0800 Subject: [PATCH 40/96] Fixes --- Makefile | 6 +++--- README.md | 1 + 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/Makefile b/Makefile index abd573912..761e94b32 100644 --- a/Makefile +++ b/Makefile @@ -163,7 +163,7 @@ index.html: $(draft).html cp $< $@ ghpages: index.html $(draft).txt - @git show -s gh-pages > /dev/null 2>&1 || \ + @git show-ref refs/heads/gh-pages > /dev/null 2>&1 || \ ! echo 'Error: No gh-pages branch, run `make setup-ghpages` to initialize it.' ifneq (,$(or $(IS_LOCAL),$(IS_MASTER))) mkdir $(GHPAGES_TMP) @@ -194,11 +194,11 @@ endif .PHONY: setup-ghpages setup-ghpages: # Check if the gh-pages branch already exists locally - @if git show -s gh-pages >/dev/null 2>&1; then \ + @if git show-ref refs/heads/gh-pages >/dev/null 2>&1; then \ ! echo "Error: gh-pages branch already exists"; \ else true; fi # Check if the gh-pages branch already exists on origin - @git show -s origin/gh-pages >/dev/null 2>&1 && \ + @git show-ref origin/gh-pages >/dev/null 2>&1 && \ (echo 'Warning: gh-pages already present on the origin'; \ git branch gh-pages origin/gh-pages; false) @echo "Initializing gh-pages branch" diff --git a/README.md b/README.md index 895184576..6a50dc532 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,7 @@ the core files. ```sh $ make update +$ git commit ``` This script is cunning enough to handle merging any simple changes that you From b5ccf8f22983a4f2459b31de5fc74cb9fd3b7a09 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 5 Mar 2015 22:18:18 -0800 Subject: [PATCH 41/96] Oops --- Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Makefile b/Makefile index 761e94b32..fb585eb1d 100644 --- a/Makefile +++ b/Makefile @@ -196,11 +196,12 @@ setup-ghpages: # Check if the gh-pages branch already exists locally @if git show-ref refs/heads/gh-pages >/dev/null 2>&1; then \ ! echo "Error: gh-pages branch already exists"; \ - else true; fi + else true; fi # Check if the gh-pages branch already exists on origin - @git show-ref origin/gh-pages >/dev/null 2>&1 && \ - (echo 'Warning: gh-pages already present on the origin'; \ - git branch gh-pages origin/gh-pages; false) + @if git show-ref origin/gh-pages >/dev/null 2>&1; then \ + echo 'Warning: gh-pages already present on the origin'; \ + git branch gh-pages origin/gh-pages; false; \ + else true; fi @echo "Initializing gh-pages branch" git checkout --orphan gh-pages git rm -rf . From a9549122cdfba375f9420bc1f76312dd1cd7d7e6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 5 Mar 2015 22:22:10 -0800 Subject: [PATCH 42/96] Fixing travis error --- Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Makefile b/Makefile index fb585eb1d..73bd391d5 100644 --- a/Makefile +++ b/Makefile @@ -163,8 +163,10 @@ index.html: $(draft).html cp $< $@ ghpages: index.html $(draft).txt +ifneq (true,$(TRAVIS)) @git show-ref refs/heads/gh-pages > /dev/null 2>&1 || \ ! echo 'Error: No gh-pages branch, run `make setup-ghpages` to initialize it.' +endif ifneq (,$(or $(IS_LOCAL),$(IS_MASTER))) mkdir $(GHPAGES_TMP) cp -f $^ $(GHPAGES_TMP) From c2dca95a15d6c499b302eaab59081d2629e7be71 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 21 Mar 2015 20:07:26 +0000 Subject: [PATCH 43/96] Recommend virtualenv for pip --- .gitignore | 2 +- README-template.md | 11 +++++++++-- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 3c71c47f5..c1f4701a4 100644 --- a/.gitignore +++ b/.gitignore @@ -7,4 +7,4 @@ /*-[0-9][0-9].xml .refcache .i-d-template - +venv/ diff --git a/README-template.md b/README-template.md index 5bbd19bf5..947c99c7c 100644 --- a/README-template.md +++ b/README-template.md @@ -47,10 +47,17 @@ providing a link to the issue in the message body. ## Building the Draft In order to build a copy of the draft, you will need to install xml2rfc. This -requires Python 2.7 and can be installed using `pip`: +requires Python 2.7 and can be installed using `pip` and `virtualenv`: ```sh -$ pip install xml2rfc +# install dependencies for lxml built for xml2rfc +sudo apt-get install libxml2-dev libxslt1-dev +# instead of "sudo pip" that pollutes system-wide packages, use +# virtual Python environment +virtualenv --no-site-packages venv +# remember also to activate the virtualenv before any 'make' run +source venv/bin/activate +pip install xml2rfc ``` You may also need to install kramdown-xml2rfc, which requires Ruby and can be From c68788df72b701345b64e413ca176bc9d594f231 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Sat, 21 Mar 2015 21:57:56 -0500 Subject: [PATCH 44/96] Beefing up installation instructions --- README-template.md | 62 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 14 deletions(-) diff --git a/README-template.md b/README-template.md index 947c99c7c..4fb2b13ba 100644 --- a/README-template.md +++ b/README-template.md @@ -46,29 +46,63 @@ providing a link to the issue in the message body. ## Building the Draft -In order to build a copy of the draft, you will need to install xml2rfc. This -requires Python 2.7 and can be installed using `pip` and `virtualenv`: +Formatted text and HTML versions of the draft can be built using `make`. ```sh -# install dependencies for lxml built for xml2rfc -sudo apt-get install libxml2-dev libxslt1-dev -# instead of "sudo pip" that pollutes system-wide packages, use -# virtual Python environment -virtualenv --no-site-packages venv +$ make +``` + +This requires that you have the necessary software installed. There are several +other tools that are enabled by make, check the Makefile for details, including +links to the software those tools might require. + + +## Installation and Setup + +Mac users will need to install +[XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see +[this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. +Some of the makefile targets need GNU make 4.0, which Apple doesn't ship yet; +sorry, but if you want those, you can +[download](https://www.gnu.org/software/make/) and build a copy for yourself. + +Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. + +All systems require [xml2rfc](http://xml2rfc.ietf.org/). This requires [Python +2.7](https://www.python.org/). The easiest way to get `xml2rfc` is with `pip`. + +Using a `virtualenv`: + +```sh +$ virtualenv --no-site-packages venv # remember also to activate the virtualenv before any 'make' run -source venv/bin/activate -pip install xml2rfc +$ source venv/bin/activate +$ pip install xml2rfc ``` -You may also need to install kramdown-xml2rfc, which requires Ruby and can be -installed using the roby package manager, `gem`: +To your local user account: ```sh -$ gem install kramdown-xml2rfc +$ pip install --user xml2rfc +``` + +Or globally: + +```sh +$ sudo pip install xml2rfc ``` -Other tools can be used to produce PDF files, or to provide a comparison. These -tools - and where to find them - are described in the `Makefile`. +xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and +[libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and +`libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, +Fedora). + +If you use markdown, you will also need to install `kramdown-xml2rfc`, which +requires Ruby and can be installed using the roby package manager, `gem`: + +```sh +$ gem install kramdown-xml2rfc +``` ## NOTE WELL From 5051bc88fcde7789124f6a7f03ef3cb15bd84ec7 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Apr 2015 13:49:45 -0700 Subject: [PATCH 45/96] Adding draft --- README-template.md | 141 ------- README.md | 216 +++++----- draft-thomson-http-encryption.md | 649 +++++++++++++++++++++++++++++++ template.md | 570 --------------------------- template.xml | 637 ------------------------------ 5 files changed, 746 insertions(+), 1467 deletions(-) delete mode 100644 README-template.md create mode 100644 draft-thomson-http-encryption.md delete mode 100644 template.md delete mode 100644 template.xml diff --git a/README-template.md b/README-template.md deleted file mode 100644 index 4fb2b13ba..000000000 --- a/README-template.md +++ /dev/null @@ -1,141 +0,0 @@ -# |DRAFT-TITLE| - -This is the working area for the [IETF |WG-TITLE| Working -Group](https://trac.tools.ietf.org/wg/|WG-NAME|/trac/wiki) draft of |DRAFT-TITLE| - -* [Editor's copy](https://rtcweb-wg.github.io/security-arch/) -* [Working Group Draft] (https://tools.ietf.org/html/|DRAFT-NAME|) - - -## Contributing - -Before submitting feedback, please familiarize yourself with our current issues -list and review the [working group home page](|WG-HOMEPAGE|). If you're -new to this, you may also want to read the [Tao of the -IETF](https://www.ietf.org/tao.html). - -Be aware that all contributions to the specification fall under the "NOTE WELL" -terms outlined below. - -1. The best way to provide feedback (editorial or design) and ask questions is -sending an e-mail to [our mailing -list](https://www.ietf.org/mailman/listinfo/|WG-NAME|). This will ensure that -the entire Working Group sees your input in a timely fashion. - -2. If you have **editorial** suggestions (i.e., those that do not change the -meaning of the specification), you can either: - - a) Fork this repository and submit a pull request; this is the lowest - friction way to get editorial changes in. - - b) Submit a new issue to Github, and mention that you believe it is editorial - in the issue body. It is not necessary to notify the mailing list for - editorial issues. - - c) Make comments on individual commits in Github. Note that this feedback is - processed only with best effort by the editors, so it should only be used for - quick editorial suggestions or questions. - -3. For non-editorial (i.e., **design**) issues, you can also create an issue on -Github. However, you **must notify the mailing list** when creating such issues, -providing a link to the issue in the message body. - - Note that **github issues are not for substantial discussions**; the only - appropriate place to discuss design issues is on the mailing list itself. - - -## Building the Draft - -Formatted text and HTML versions of the draft can be built using `make`. - -```sh -$ make -``` - -This requires that you have the necessary software installed. There are several -other tools that are enabled by make, check the Makefile for details, including -links to the software those tools might require. - - -## Installation and Setup - -Mac users will need to install -[XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see -[this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. -Some of the makefile targets need GNU make 4.0, which Apple doesn't ship yet; -sorry, but if you want those, you can -[download](https://www.gnu.org/software/make/) and build a copy for yourself. - -Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. - -All systems require [xml2rfc](http://xml2rfc.ietf.org/). This requires [Python -2.7](https://www.python.org/). The easiest way to get `xml2rfc` is with `pip`. - -Using a `virtualenv`: - -```sh -$ virtualenv --no-site-packages venv -# remember also to activate the virtualenv before any 'make' run -$ source venv/bin/activate -$ pip install xml2rfc -``` - -To your local user account: - -```sh -$ pip install --user xml2rfc -``` - -Or globally: - -```sh -$ sudo pip install xml2rfc -``` - -xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and -[libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and -`libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, -Fedora). - -If you use markdown, you will also need to install `kramdown-xml2rfc`, which -requires Ruby and can be installed using the roby package manager, `gem`: - -```sh -$ gem install kramdown-xml2rfc -``` - - -## NOTE WELL - -Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor -for publication as all or part of an IETF Internet-Draft or RFC and any -statement made within the context of an IETF activity is considered an "IETF -Contribution". Such statements include oral statements in IETF sessions, as -well as written and electronic communications made at any time or place, which -are addressed to: - - * The IETF plenary session - * The IESG, or any member thereof on behalf of the IESG - * Any IETF mailing list, including the IETF list itself, any working group - or design team list, or any other list functioning under IETF auspices - * Any IETF working group or portion thereof - * Any Birds of a Feather (BOF) session - * The IAB or any member thereof on behalf of the IAB - * The RFC Editor or the Internet-Drafts function - * All IETF Contributions are subject to the rules of - [RFC 5378](https://tools.ietf.org/html/rfc5378) and - [RFC 3979](https://tools.ietf.org/html/rfc3979) - (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). - -Statements made outside of an IETF session, mailing list or other function, -that are clearly not intended to be input to an IETF activity, group or -function, are not IETF Contributions in the context of this notice. - -Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC -3979](https://tools.ietf.org/html/rfc3979) for details. - -A participant in any IETF activity is deemed to accept all IETF rules of -process, as documented in Best Current Practices RFCs and IESG Statements. - -A participant in any IETF activity acknowledges that written, audio and video -records of meetings may be made and may be available to the public. diff --git a/README.md b/README.md index 6a50dc532..3cb0f6cc2 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,139 @@ -# Internet Draft Template Repository +# HTTP Content Encryption -The contents of this repository can be used to get started with a new internet -draft. -## Getting Started +* [Editor's copy](https://martinthomson.github.io/http-encryption/) +* [Formal Draft] (https://tools.ietf.org/html/draft-thomson-http-encryption) (older) -This all assumes that you have an [account](https://github.com/join) with -GitHub. -### Working Group Setup +## Contributing -Make a [new organization](https://github.com/organizations/new) for your working -group. This guide will use the name `unicorn-wg` for your working group. +Before submitting feedback, please familiarize yourself with our current issues +list and review the [working group home page](https://httpwg.github.io/). If you're +new to this, you may also want to read the [Tao of the +IETF](https://www.ietf.org/tao.html). -### New Draft Setup +Be aware that all contributions to the specification fall under the "NOTE WELL" +terms outlined below. -[Make a new repository](https://github.com/new). This guide will use the -name name `unicorn-protocol` here. +1. The best way to provide feedback (editorial or design) and ask questions is +sending an e-mail to [our mailing +list](https://lists.w3.org/Archives/Public/ietf-http-wg/). This will ensure that +the entire Working Group sees your input in a timely fashion. -Clone that repository: -```sh -$ git clone https://github.com/unicorn-wg/unicorn-protocol.git -``` -Copy the contents of this respository in: -```sh -$ cd unicorn-protocol -$ git pull https://github.com/martinthomson/i-d-template.git master -``` -Choose whether you want to use markdown, outline, or xml as your input form. -If you already have a draft, then that decision is already made for you. +2. If you have **editorial** suggestions (i.e., those that do not change the +meaning of the specification), you can either: -Move the template file into place. -```sh -$ git mv template.md draft-ietf-unicorn-protocol.md -``` -Or add an existing file. -```sh -$ git add draft-ietf-unicorn-protocol.xml -```` -Edit the draft so that it has the right name. This template uses the -`-latest` suffix in place of the usual number ('-00', or '-08'). -```xml - -``` -Or in markdown: -```yaml -docname: draft-ietf-unicorn-protocol-latest -``` -And add it: -```sh -$ git add draft-ietf-unicorn-protocol.md -``` -Remove the unnecessary template files. -```sh -$ git rm template.md template.xml -``` -Move the README.md template into place. -```sh -$ git rm README.md -$ git mv README-template.md README.md -``` -Edit the `README.md` and `CONTRIBUTING.md` files. Note that `CONTRIBUTING.md` -file is just the latter part of `README.md`. -```sh -$ vi README.md CONTRIBUTING.md -# ... -$ git add README.md CONTRIBUTING.md -``` -Commit and push -```sh -$ git commit -$ git push -``` + a) Fork this repository and submit a pull request; this is the lowest + friction way to get editorial changes in. -Optional: If you are using markdown, you might like to add the following line to your -`.gitignore` to avoid committing the intermediate XML file that this might create. -``` -draft-*.xml -``` + b) Submit a new issue to Github, and mention that you believe it is editorial + in the issue body. It is not necessary to notify the mailing list for + editorial issues. + c) Make comments on individual commits in Github. Note that this feedback is + processed only with best effort by the editors, so it should only be used for + quick editorial suggestions or questions. -### Setting Up The Editor's Copy +3. For non-editorial (i.e., **design**) issues, you can also create an issue on +Github. However, you **must notify the mailing list** when creating such issues, +providing a link to the issue in the message body. -GitHub uses the `gh-pages` branch as source for a project web page. This branch -needs to be initialized first. The `setup-ghpages` make target does that: + Note that **github issues are not for substantial discussions**; the only + appropriate place to discuss design issues is on the mailing list itself. -```sh -$ make setup-ghpages -``` -You can maintain `gh-pages` manually by running the following command -occasionally. +## Building the Draft + +Formatted text and HTML versions of the draft can be built using `make`. ```sh -$ make ghpages +$ make ``` -Or, you can run an automatic commit after each checkin with Travis. +This requires that you have the necessary software installed. There are several +other tools that are enabled by make, check the Makefile for details, including +links to the software those tools might require. + +## Installation and Setup -### Automatic Update for Editor's Copy +Mac users will need to install +[XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see +[this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. +Some of the makefile targets need GNU make 4.0, which Apple doesn't ship yet; +sorry, but if you want those, you can +[download](https://www.gnu.org/software/make/) and build a copy for yourself. -This requires that you sign in with [Travis](https://travis-ci.org/). +Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. -First enable builds for the new repository on the Travis site. (Hit the button -with a '+' on it once you are logged in.) Note that Travis only synchronizes -repositories with GitHub once a day, so you might have to force a refresh. +All systems require [xml2rfc](http://xml2rfc.ietf.org/). This requires [Python +2.7](https://www.python.org/). The easiest way to get `xml2rfc` is with `pip`. -You will need the Travis command line tool for the next step; this is available -as a [Ruby](https://www.ruby-lang.org/) [gem](https://rubygems.org/): +Using a `virtualenv`: ```sh -$ sudo gem install travis +$ virtualenv --no-site-packages venv +# remember also to activate the virtualenv before any 'make' run +$ source venv/bin/activate +$ pip install xml2rfc ``` -*WARNING*: You might want to use a dummy account for this next part to minimize -any problems from accidental leaks of your key. Once you enable pushes from -Travis, be very careful accepting pull requests that alter `.travis.yml` or -`Makefile`. Those files can cause the value of the token to be published for -all to see. You don't want that to happen, even though tokens can be revoked -easily. Only pushes to the main repository will be able to see the token, so -don't worry about pull requests. - -Then, you need to get yourself a [new GitHub application -token](https://github.com/settings/tokens/new). The application token only -needs the `public_repo` privilege. This will let it push updates to your -`gh-pages` branch. - -Then, you update the Travis configuration file with an encrypted copy of that -token, as follows: +To your local user account: ```sh -$ travis encrypt GH_TOKEN= -a -p -$ git add .travis.yml -$ git commit -$ git push +$ pip install --user xml2rfc ``` -As a side benefit, Travis will now also check pull requests for errors, letting -you know if things didn't work out so that you don't merge anything suspect. +Or globally: +```sh +$ sudo pip install xml2rfc +``` -## Updating the Makefile +xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and +[libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and +`libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, +Fedora). -Occasionally improvements and changes are made to the Makefile or the support -files in this repository. The `update` make target looks after the update of -the core files. +If you use markdown, you will also need to install `kramdown-xml2rfc`, which +requires Ruby and can be installed using the roby package manager, `gem`: ```sh -$ make update -$ git commit +$ gem install kramdown-xml2rfc ``` -This script is cunning enough to handle merging any simple changes that you -might have made to the Makefile yourself, such as adding targets. +## NOTE WELL + +Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor +for publication as all or part of an IETF Internet-Draft or RFC and any +statement made within the context of an IETF activity is considered an "IETF +Contribution". Such statements include oral statements in IETF sessions, as +well as written and electronic communications made at any time or place, which +are addressed to: + + * The IETF plenary session + * The IESG, or any member thereof on behalf of the IESG + * Any IETF mailing list, including the IETF list itself, any working group + or design team list, or any other list functioning under IETF auspices + * Any IETF working group or portion thereof + * Any Birds of a Feather (BOF) session + * The IAB or any member thereof on behalf of the IAB + * The RFC Editor or the Internet-Drafts function + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) + (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). + +Statements made outside of an IETF session, mailing list or other function, +that are clearly not intended to be input to an IETF activity, group or +function, are not IETF Contributions in the context of this notice. + +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +3979](https://tools.ietf.org/html/rfc3979) for details. -## Submitting Drafts +A participant in any IETF activity is deemed to accept all IETF rules of +process, as documented in Best Current Practices RFCs and IESG Statements. -See `SUBMITTING.md`. +A participant in any IETF activity acknowledges that written, audio and video +records of meetings may be made and may be available to the public. diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md new file mode 100644 index 000000000..28fecffbd --- /dev/null +++ b/draft-thomson-http-encryption.md @@ -0,0 +1,649 @@ +--- +title: Encrypted Content-Encoding for HTTP +abbrev: HTTP encryption coding +docname: draft-thomson-http-encryption-latest +date: 2015 +category: std + +ipr: trust200902 +area: General +workgroup: +keyword: Internet-Draft + +stand_alone: yes +pi: [toc, tocindent, sortrefs, symrefs, strict, compact, comments, inline] + +author: + - + ins: M. Thomson + name: Martin Thomson + organization: Mozilla + email: martin.thomson@gmail.com + +normative: + RFC2119: + RFC4492: + RFC4648: + RFC7230: + RFC7231: + RFC5116: + RFC5869: + FIPS180-2: + title: NIST FIPS 180-2, Secure Hash Standard + author: + name: NIST + ins: National Institute of Standards and Technology, U.S. Department of Commerce + date: 2002-08 + DH: + title: "New Directions in Cryptography" + author: + - ins: W. Diffie + - ins: M. Hellman + date: 1977-06 + seriesinfo: IEEE Transactions on Information Theory, V.IT-22 n.6 + +informative: + RFC4880: + RFC5226: + RFC5246: + RFC5652: + RFC7235: + I-D.ietf-httpbis-http2: + FIPS186: + title: "Digital Signature Standard (DSS)" + author: + - org: National Institute of Standards and Technology (NIST) + date: July 2013 + seriesinfo: NIST PUB 186-4 + X.692: + title: "Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)" + author: + - org: ANSI + date: 1998 + seriesinfo: ANSI X9.62 + I-D.ietf-jose-json-web-encryption: + XMLENC: + title: "XML Encryption Syntax and Processing" + author: + - ins: D. Eastlake + - ins: J. Reagle + - ins: T. Imamura + - ins: B. Dillaway + - ins: E. Simon + date: 2002-12 + seriesinfo: W3C REC + target: "http://www.w3.org/TR/xmlenc-core/" + +--- abstract + +This memo introduces a content-coding for HTTP that allows message payloads to be encrypted. + + +--- middle + +# Introduction + +It is sometimes desirable to encrypt the contents of a HTTP message (request or response) in a +persistent manner, so that when the payload is stored (e.g., with a HTTP PUT), only someone with +the appropriate key can read it. + +For example, it might be necessary to store a file on a server without exposing its contents to +that server. Furthermore, that same file could be replicated to other servers (to make it more +resistant to server or network failure), downloaded by clients (to make it available offline), etc. +without exposing its contents. + +These uses are not met by the use of TLS [RFC5246], since it only encrypts the channel between the +client and server. + +Message-based encryption formats - such as those that are described by [RFC4880], [RFC5652], +[I-D.ietf-jose-json-web-encryption], and [XMLENC] - are not suited to stream processing, which is +necessary for HTTP messages. While virtually any of these alternatives could be profiled and +adapted to suit, the overhead and complexity that would introduce is sub-optimal. However, this +format can be interpreted as sequence of JSON Web Encryption [I-D.ietf-jose-json-web-encryption] +values with a fixed header, see {{jwe}}. + +This document specifies a content-coding (Section 3.1.2 of [RFC7231]) for HTTP to serve these and +other use cases. + +This mechanism is likely only a small part of a larger design that uses content encryption. In +particular, this document does not describe key management practices. How clients and servers +acquire and identify keys will depend on the use case. + + +## Notational Conventions + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", +"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in +[RFC2119]. + + +# The "aesgcm-128" HTTP content-coding {#aesgcm128} + +The "aesgcm-128" HTTP content-coding indicates that a payload has been encrypted using Advanced +Encryption Standard (AES) in Galois/Counter Mode (GCM) as identified as AEAD_AES_128_GCM in +[RFC5116], Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content encryption key. + +When this content-coding is in use, the Encryption header field ({{encryption}}) describes how +encryption has been applied. The Encryption-Key header field ({{encryption-key}}) can be included to +describe how the the content encryption key is derived or retrieved. + +The "aesgcm-128" content-coding uses a single fixed set of encryption primitives. Cipher suite +agility is achieved by defining a new content-coding scheme. This ensures that only the HTTP +Accept-Encoding header field is necessary to negotiate the use of encryption. + +The "aesgcm-128" content-coding uses a fixed record size. The resulting encoding is a series of +fixed-size records, with a final record that is one or more octets shorter than a fixed sized +record. + +~~~ + +------+ + | data | input of between rs-256 + +------+ and rs-1 octets + | + v ++-----+-----------+ +| pad | data | add padding to form plaintext ++-----+-----------+ + | + v ++--------------------+ +| ciphertext | encrypt with AEAD_AES_128_GCM ++--------------------+ expands by 16 octets +~~~ + +The record size determines the length of each portion of plaintext that is enciphered. The record +size defaults to 4096 octets, but can be changed using the "rs" parameter on the Encryption header +field. + +AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input plaintext. Therefore, the +length of each enciphered record is equal to the value of the "rs" parameter plus 16 octets. It is +a fatal decryption error to have a remainder of 16 octets or less in size (though AEAD_AES_128_GCM +permits input plaintext to be zero length, records always contain at least one padding octet). + +Each record contains between 0 and 255 octets of padding, inserted into a record before the +enciphered content. The length of the padding is stored in the first octet of the payload. All +padding octets MUST be set to zero. It is a fatal decryption error to have a record with more +padding than the record size. + +The nonce used for each record is a 96-bit value containing the index of the current record in +network byte order. Records are indexed starting at zero. + +The additional data passed to the AEAD algorithm is a zero-length octet sequence. + +A sequence of full-sized records can be truncated to produce a shorter sequence of records with +valid authentication tags. To prevent an attacker from truncating a stream, an endoder MUST append +a record that contains only padding if the final record is not shorter than the record size. A +receiver MUST treat the stream as failed due to truncation if the final record is not less than the +full record size. + +Issue: +: Double check that this construction (with no AAD) is safe. + + +# The "Encryption" HTTP header field {#encryption} + +The "Encryption" HTTP header field describes the encrypted content encoding(s) that have been +applied to a message payload, and therefore how those content encoding(s) can be removed. + +~~~ + Encryption-val = #encryption_params + encryption_params = [ param *( ";" param ) ] +~~~ + +If the payload is encrypted more than once (as reflected by having multiple content-codings that +imply encryption), each application of the content encoding is reflected in the Encryption header +field, in the order in which they were applied. + +The Encryption header MAY be omitted if the sender does not intend for the immediate recipient to +be able to decrypt the message. Alternatively, the Encryption header field MAY be omitted if the +sender intends for the recipient to acquire the header field by other means. + +Servers processing PUT requests MUST persist the value of the Encryption header field, unless they +remove the content-coding by decrypting the payload. + + +## Encryption Header Field Parameters + +The following parameters are used in determining the key that is used for encryption: + +keyid: + +: The "keyid" parameter contains a string that identifies the keying material that is used. The +"keyid" parameter SHOULD be included, unless key identification is guaranteed by other means. The +"keyid" parameter MUST be used if keying material is included in an Encryption-Key header field. + +salt: + +: The "salt" parameter contains a base64 URL-encoded octets that is used as salt in deriving a +unique content encryption key (see {{derivation}}). The "salt" parameter MUST be present, and MUST +be exactly 16 octets long. The "salt" parameter MUST NOT be reused for two different messages that +have the same content encryption key; generating a random nonce for each message ensures that reuse +is highly unlikely. + +rs: + +: The "rs" parameter contains a positive decimal integer that describes the record size in octets. +This value MUST be greater than 1. If the "rs" parameter is absent, the record size defaults to +4096 octets. + + +## Content Encryption Key Derivation {#derivation} + +In order to allow the reuse of keying material for multiple different messages, a content encryption +key is derived for each message. This key is derived from the decoded value of the "s" parameter +using the HMAC-based key derivation function (HKDF) described in [RFC5869] using the SHA-256 hash +algorithm [FIPS180-2]. + +The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material +identified by the "keyid" parameter is the input keying material (IKM) to HKDF. Input keying +material can either be prearranged, or can be described using the Encryption-Key header field +({{encryption-key}}). The first step of HKDF is therefore: + +~~~ + PRK = HMAC-SHA-256(salt, IKM) +~~~ + +AEAD_AES_128_GCM requires 16 octets (128 bits) of key, so the length (L) parameter of HKDF is 16. +The info parameter is set to the ASCII-encoded string "Content-Encoding: aesgcm128". The second +step of HKDF can therefore be simplified to the first 16 octets of a single HMAC: + +~~~ + OKM = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) +~~~ + + +# Encryption-Key Header Field {#encryption-key} + +An Encryption-Key header field can be used to describe the input keying material used in the +Encryption header field. + +~~~ + Encryption-Key-val = #encryption_key_params + encryption_key_params = [ param *( ";" param ) ] +~~~ + +keyid: + +: The "keyid" parameter corresponds to the "keyid" parameter in the Encryption header field. + +key: + +: The "key" parameter contains the URL-safe base64 [RFC4648] octets of the input keying material. + +dh: + +: The "dh" parameter contains an ephemeral Diffie-Hellman share. This form of the header field can +be used to encrypt content for a specific recipient. + + +The input keying material used by the content-encoding key derivation (see {{derivation}}) can be +determined based on the information in the Encryption-Key header field. The method for key +derivation depends on the parameters that are present in the header field. + +Note that different methods for determining input keying materal will produce different +amounts of data. The HKDF process ensures that the final content encryption key is the necessary +size. + +Alternative methods for determining input keying material MAY be defined by specifications that use +this content-encoding. + + +## Explicit Key + +The "key" parameter is decoded and used directly if present. The "key" parameter MUST decode to +exactly 16 octets in order to be used as input keying material for "aesgcm128" content encoding. + +Other key determination parameters can be ignored if the "key" parameter is present. + + +## Diffie-Hellman + +The "dh" parameter is included to describe a Diffie-Hellman share, either modp (or finite field) +Diffie-Hellman [DH] or elliptic curve Diffie-Hellman (ECDH) [RFC4492]. + +This share is combined with other information at the recipient to determine the HKDF input keying +material. In order for the exchange to be successful, the following information MUST be established +out of band: + +* Which Diffie-Hellman form is used. + +* The modp group or elliptic curve that will be used. + +* The format of the ephemeral public share that is included in the "dh" parameter. For instance, + using ECDH both parties need to agree whether this is an uncompressed or compressed point. + +In addition to identifying which content-encoding this input keying material is used for, the +"keyid" parameter is used to identify this additional information at the receiver. + +The intended recipient recovers their private key and are then able to generate a shared secret +using the appropriate Diffie-Hellman process. + +Specifications that rely on an Diffie-Hellman exchange for determining input keying material MUST +either specify the parameters for Diffie-Hellman (group parameters, or curves and point format) that +are used, or describe how those parameters are negotiated between sender and receiver. + + +# Examples + +## Successful GET Response + +~~~ +HTTP/1.1 200 OK +Content-Type: application/octet-stream +Content-Encoding: aesgcm-128 +Connection: close +Encryption: keyid="http://example.org/bob/keys/123"; + salt="XZwpw6o37R-6qoZjw6KwAw" + +[encrypted payload] +~~~ + +Here, a successful HTTP GET response has been encrypted using a key that is identified by a URI. + +Note that the media type has been changed to "application/octet-stream" to avoid exposing +information about the content. + +## Encryption and Compression + +~~~ +HTTP/1.1 200 OK +Content-Type: text/html +Content-Encoding: aesgcm-128, gzip +Transfer-Encoding: chunked +Encryption: keyid="mailto:me@example.com"; + salt="m2hJ_NttRtFyUiMRPwfpHA" + +[encrypted payload] +~~~ + +## Encryption with More Than One Key + +~~~ +PUT /thing HTTP/1.1 +Host: storage.example.com +Content-Type: application/http +Content-Encoding: aesgcm-128, aesgcm-128 +Content-Length: 1234 +Encryption: keyid="mailto:me@example.com"; + salt="NfzOeuV5USPRA-n_9s1Lag", + keyid="http://example.org/bob/keys/123"; + salt="bDMSGoc2uobK_IhavSHsHA"; rs=1200 + +[encrypted payload] +~~~ + +Here, a PUT request has been encrypted with two keys; both will be necessary to read the content. +The outer layer of encryption uses a 1200 octet record size. + + +## Encryption with Explicit Key {#explicit} + +~~~ +HTTP/1.1 200 OK +Content-Length: 31 +Content-Encoding: aesgcm-128 +Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" +Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" + +zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc +~~~ + +This example shows the string "I am the walrus" encrypted using an explicit key. The content body +contains a single record only and is shown here encoded in URL-safe base64 for presentation reasons +only. + + +## Diffie-Hellman Encryption + +~~~ +HTTP/1.1 200 OK +Content-Length: 31 +Content-Encoding: aesgcm-128 +Encryption: keyid="dhkey"; salt="5hpuYfxDzG6nSs9-EQuaBg" +Encryption-Key: keyid="dhkey"; + dh="BLsyIPbDn6bquEOwHaju2gj8kUVoflzTtPs_6fGoock_ + dwxi1BcgFtObPVnic4alcEucx8I6G8HmEZCJnAl36Zg" + +BmuHqRzdD4W1mibxglrPiRHZRSY49Dzdm6jHrWXzZrE +~~~ + +This example shows the same string, "I am the walrus", encrypted using ECDH over the P-256 curve +[FIPS186]. The content body is shown here encoded in URL-safe base64 for presentation reasons only. + +The receiver (in this case, the HTTP client) uses the key identified by the string "dhkey" and the +sender (the server) uses a key pair for which the public share is included in the "dh" parameter +above. The keys shown below use uncompressed points [X.692] encoded using URL-safe base64. Line +wrapping is added for presentation purposes only. + +~~~ + Receiver: + private key: iCjNf8v4ox_g1rJuSs_gbNmYuUYx76ZRruQs_CHRzDg + public key: BPM1w41cSD4BMeBTY0Fz9ryLM-LeM22Dvt0gaLRukf05 + rMhzFAvxVW_mipg5O0hkWad9ZWW0uMRO2Nrd32v8odQ + Sender: + private key: W0cxgeHDZkR3uMQYAbVgF5swKQUAR7DgoTaaQVlA-Fg + public key: +~~~ + + +# IANA Considerations + +## The "aesgcm-128" HTTP content-coding + +This memo registers the "encrypted" HTTP content-coding in the HTTP Content Codings Registry, as +detailed in {{aesgcm128}}. + +* Name: aesgcm-128 +* Description: AES-GCM encryption with a 128-bit key +* Reference [this specification] + + +## Encryption Header Fields + +This memo registers the "Encryption" HTTP header field in the Permanent Message Header Registry, as +detailed in {{encryption}}. + +* Field name: Encryption +* Protocol: HTTP +* Status: Standard +* Reference: [this specification] +* Notes: + +This memo registers the "Encryption-Key" HTTP header field in the Permanent Message Header Registry, +as detailed in {{encryption-key}}. + +* Field name: Encryption-Key +* Protocol: HTTP +* Status: Standard +* Reference: [this specification] +* Notes: + + +## The HTTP Encryption Parameter Registry {#encryption-registry} + +This memo establishes a registry for parameters used by the "Encryption" header +field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The +"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +"Specification Required" policy [RFC5226]. + +Entries in this registry are expected to include the following information: + +* Parameter Name: The name of the parameter. +* Purpose: A brief description of the purpose of the parameter. +* Reference: A reference to a specification that defines the semantics of the parameter. + +The initial contents of this registry are: + +### keyid + +* Parameter Name: keyid +* Purpose: Identify the key that is in use. +* Reference: [this document] + +### salt + +* Parameter Name: salt +* Purpose: Provide a source of entropy for derivation of the content encryption key. This value is mandatory. +* Reference: [this document] + +### rs + +* Parameter Name: rs +* Purpose: The size of the encrypted records. +* Reference: [this document] + + +## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} + +This memo establishes a registry for parameters used by the "Encryption-Key" header +field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The +"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +"Specification Required" policy [RFC5226]. + +Entries in this registry are expected to include the following information: + +* Parameter Name: The name of the parameter. +* Purpose: A brief description of the purpose of the parameter. +* Reference: A reference to a specification that defines the semantics of the parameter. + +The initial contents of this registry are: + +### keyid + +* Parameter Name: keyid +* Purpose: Identify the key that is in use. +* Reference: [this document] + +### key + +* Parameter Name: key +* Purpose: Provide an explicit key. +* Reference: [this document] + +### dh + +* Parameter Name: dh +* Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive a key. +* Reference: [this document] + + +# Security Considerations + +This mechanism assumes the presence of a key management framework that is used to manage the +distribution of keys between valid senders and receivers. Defining key management is part of +composing this mechanism into a larger application, protocol, or framework. + +Implementation of cryptography - and key management in particular - can be difficult. For instance, +implementations need to account for the potential for exposing keying material on side channels, +such as might be exposed by the time it takes to perform a given operation. The requirements for a +good implementation of cryptographic algorithms can change over time. + + +## Key and Nonce Reuse + +Encrypting different plaintext with the same content encryption key and nonce in AES-GCM is not safe +[RFC5116]. The scheme defined here relies on the uniqueness of the "nonce" parameter to ensure that +the content encryption key is different for every message. + +If a key and nonce are reused, this could expose the content encryption key and it makes message +modification trivial. If the same key is used for multiple messages, then the nonce parameter MUST +be unique for each. An implementation SHOULD generate a random nonce parameter for every message, +though using a counter could achieve the desired result. + + +## Content Integrity + +This mechanism only provides content origin authentication. The authentication tag only ensures +that those with access to the content encryption key produce a message that will be accepted as +valid. + +Any entity with the content encryption key can therefore produce content that will be accepted as +valid. This includes all recipients of the same message. + +Furthermore, any entity that is able to modify both the Encryption header field and the message +payload can replace messages. Without the content encryption key however, modifications to or +replacement of parts of a message are not possible. + + +## Leaking Information in Headers + +Because "encrypted" only operates upon the message payload, any information exposed in header fields is +visible to anyone who can read the message. + +For example, the Content-Type header field can leak information about the message payload. + +There are a number of strategies available to mitigate this threat, depending upon the +application's threat model and the users' tolerance for leaked information: + +1. Determine that it is not an issue. For example, if it is expected that all content stored will be +"application/json", or another very common media type, exposing the Content-Type header field could be an +acceptable risk. + +2. If it is considered sensitive information and it is possible to determine it through other means +(e.g., out of band, using hints in other representations, etc.), omit the relevant headers, and/or +normalize them. In the case of Content-Type, this could be accomplished by always sending +Content-Type: application/octet-stream (the most generic media type), or no Content-Type at all. + +3. If it is considered sensitive information and it is not possible to convey it elsewhere, +encapsulate the HTTP message using the application/http media type (Section 8.3.2 of [RFC7230]), encrypting that as the +payload of the "outer" message. + + +## Poisoning Storage + +This mechanism only offers encryption of content; it does not perform authentication or +authorization, which still needs to be performed (e.g., by HTTP authentication [RFC7235]). + +This is especially relevant when a HTTP PUT request is accepted by a server; if the request is +unauthenticated, it becomes possible for a third party to deny service and/or poison the store. + + +## Sizing and Timing Attacks + +Applications using this mechanism need to be aware that the size of encrypted messages, as well as +their timing, HTTP methods, URIs and so on, may leak sensitive information. + +This risk can be mitigated through the use of the padding that this mechanism provides. +Alternatively, splitting up content into segments and storing the separately might reduce +exposure. HTTP/2 [I-D.ietf-httpbis-http2] combined with TLS [RFC5246] might be used to hide the size +of individual messages. + + +--- back + +# JWE Mapping {#jwe} + +The "aesgcm-128" content encoding can be considered as a sequence of JSON Web Encryption (JWE) +objects, each corresponding to a single fixed size record. The following transformations are +applied to a JWE object that might be expressed using the JWE Compact Serialization: + +* The JWE Protected Header is fixed to a value { "alg": "dir", "enc": "A128GCM" }, describing direct + encryption using AES-GCM with a 128-bit key. This header is not transmitted, it is instead + implied by the value of the Content-Encoding header field. + +* The JWE Encrypted Key is empty, as stipulated by the direct encryption algorithm. + +* The JWE Initialization Vector ("iv") for each record is set to the 96-bit integer value of the + record sequence number, starting at zero. This value is also not transmitted. + +* The final value is the concatenated JWE Ciphertext and the JWE Authentication Tag, both expressed + without URL-safe Base 64 encoding. The "." separator is omitted, since the length of these fields + is known. + +Thus, the example in {{explicit}} can be rendered using the JWE Compact Serialization as: + +~~~ +eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..AAAAAAAAAAAAAAAA. +LwTC-fwdKh8de0smD2jfzA.eh1vURhu65M2lxhctbbntA +~~~ + +Where the first line represents the fixed JWE Protected Header, JWE Encrypted Key, and JWE +Initialization Vector, all of which are determined algorithmically. The second line contains the +encoded body, split into JWE Ciphertext and JWE Authentication Tag. + +# Acknowledgements + +Mark Nottingham was an original author of this document. + +The following people provided valuable feedback and suggestions: Richard Barnes, +Mike Jones, Stephen Farrell, Eric Rescorla, and Jim Schaad. diff --git a/template.md b/template.md deleted file mode 100644 index c62c6ba2d..000000000 --- a/template.md +++ /dev/null @@ -1,570 +0,0 @@ ---- -title: STUN/TURN using PHP in Despair -abbrev: STuPiD -docname: draft-hartke-xmpp-stupid-latest -date: 2009-07-05 -category: info - -ipr: trust200902 -area: General -workgroup: XMPP Working Group -keyword: Internet-Draft - -stand_alone: yes -pi: [toc, sortrefs, symrefs] - -author: - - - ins: K. Hartke - name: Klaus Hartke - organization: Universität Bremen TZI - email: hartke@tzi.org - - - ins: C. Bormann - name: Carsten Bormann - org: Universität Bremen TZI - street: Postfach 330440 - city: Bremen - code: D-28359 - country: Germany - phone: +49-421-218-63921 - facsimile: +49-421-218-7000 - email: cabo@tzi.org - -normative: - RFC2119: - RFC3986: - RFC4086: - RFC4648: - -informative: - RFC5389: - I-D.ietf-behave-turn: - STUNT: - target: http://deusty.blogspot.com/2007/09/stunt-out-of-band-channels.html - title: STUNT & out-of-band channels - author: - name: Robbie Hanson - ins: R. Hanson - date: 2007-09-17 - I-D.meyer-xmpp-e2e-encryption: - I-D.ietf-xmpp-3920bis: - - - ---- abstract - -NAT (Network Address Translator) Traversal may require TURN -(Traversal Using Relays around NAT) functionality in certain -cases that are not unlikely to occur. There is little -incentive to deploy TURN servers, except by those who need -them — who may not be in a position to deploy a new protocol -on an Internet-connected node, in particular not one with -deployment requirements as high as those of TURN. - -"STUN/TURN using PHP in Despair" is a highly deployable -protocol for obtaining TURN-like functionality, while also -providing the most important function of STUN. - ---- middle - -Introduction {#problems} -============ - -NAT (Network Address Translator) Traversal may require TURN -(Traversal Using Relays around NAT) -{{I-D.ietf-behave-turn}} -functionality in certain -cases that are not unlikely to occur. There is little -incentive to deploy TURN servers, except by those who need -them — who may not be in a position to deploy a new protocol -on an Internet-connected node, in particular not one with -deployment requirements as high as those of TURN. - -"STUN/TURN using PHP in Despair" is a highly deployable -protocol for obtaining TURN-like functionality, while also -providing the most important function of STUN -{{RFC5389}}. - -The high degree of deployability is achieved by making STuPiD -a Web service, implementable in any Web application deployment -scheme. As PHP appears to be the solution of choice for -avoiding deployment problems in the Web world, a PHP-based -sample implementation of STuPiD is presented in {{figimpl}} in {{impl}}. -(This single-page script has been tested with a free-of-charge -web hoster, so it should be deployable by literally everyone.) - - -The Need for Standardization {#need} ----------------------------- - -If STuPiD is so easy to deploy, why standardize on it? -First of all, STuPiD server implementations will be done by -other people than the clients making use of the service. -Clearly communicating between these communities is a good -idea, in particular if there are security considerations. - -Having one standard form of STuPiD service instead of one -specific to each kind of client also creates an incentive -for optimized implementations. - -Finally, where STuPiD becomes part of a client standard -(such as a potential extension to XMPP's in-band byte-stream -protocol as hinted in {{xmpp}}), it is a good -thing if STuPiD is already defined. - -Hence, this document focuses on the definition of the STuPiD -service itself, tries to make this as general as possible -without increasing complexity or cost and leaves the details -of any client standards to future documents. - - -Basic Protocol Operation {#ops} -======================== - -The STuPiD protocol will typically be used with application -instances that first attempt to obtain connectivity using -mechanisms similar to those described in the STUN -specification {{RFC5389}}. However, with STuPiD, -STUN is not really needed for TCP, as was demonstrated in -previous STUN-like implementations {{STUNT}}. -Instead, STuPiD (like {{STUNT}}) provides a -simple Web service that -echoes the remote address and port of an incoming HTTP -request; in most cases, this is enough to get the job done. - -In case no connection can be established with this simple -STUN(T)-like mechanism, a TURN-like relay is needed as a final -fall-back. -The STuPiD protocol supports this, but solely provides a way -for the data to be -relayed. STuPiD relies on an out-of-band channel to notify -the peer whenever new data is available (synchronization signal). -See {{xmpp}} for one likely example of such an -out-of-band channel. -(Note that the out-of-band channel may have a much lower -throughput than the STuPiD relay channel — this is exactly -the case in the example provided in {{xmpp}}, -where the out-of-band channel is typically throughput-limited -to on the order of a few kilobits per second.) - -By designing the STuPiD web service in such a way that it can -be implemented by a simple PHP script such as that presented -in {{impl}}, it is easy to deploy by those who -need the STuPiD services. -The combination of the low-throughput out-of-band channel for -synchronization and the STuPiD web service for bulk data -relaying is somewhat silly but gets the job done. - -The STuPiD data relay is implemented as follows (see {{figops}}): - -1. Peer A, the source of the data to be relayed, stores a chunk of - data at the STuPiD server using an opaque identifier, the "chunk - identifier". How that chunk identifier is chosen is local to Peer - A; it could be composed of a random session id and a sequence number. - -2. Peer A notifies the receiver of the data, Peer - B, that a new data chunk is available, specifying the URI needed - for retrieval. - This notification is provided through an out-out-band channel. - (As an optimization for multiple consecutive transfers, A might - inform B once of a constant prefix of that URI and only send a - varying part such as a sequence number in each notification — - this is something to be decided in the client-client notification - protocol.) - -3. Peer B retrieves the data from the STuPiD server using the URI - provided by Peer A. - -Note that the data transfer mechanism is one-way, i.e. to send -data in the other direction as well, Peer B needs to perform -the same steps using a STuPiD server at the same or a -different location. - -~~~~~~~~~~ - - - STuPiD ```````````````````````````````, - Script <----------------------------. , - | , - ^ , | , - | , | , - (1) | , | , (3) - POST | , | , GET - | , | , - | v | v - - Peer A -----------------------> Peer B - (2) - out-of-band - Notification -~~~~~~~~~~ -{: #figops title="STuPiD Protocol Operation"} - - -Protocol Definition -=================== - -Terminology {#Terminology} ------------ -In this document, the key words "MUST", "MUST NOT", "REQUIRED", -"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", -and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119 -{{RFC2119}} and indicate requirement levels for compliant STuPiD -implementations. - - -Discovering External IP Address and Port ----------------------------------------- - -A client may discover its external IP address and the port -required for port prediction by performing a HTTP GET -request to a STuPiD server. The STuPiD server MUST reply -with the remote address and remote port in the following -format: - -host ":" port - -where 'host' and 'port' are defined as in {{RFC3986}}. - - -Storing Data ------------- - -Data chunks are stored using the POST request of HTTP. The -STuPiD server MUST support one URI parameter which is passed -as query-string: - -'chid': A unique ID identifying the data chunk to be stored. -The ID SHOULD be chosen from the characters of the base64url -set {{RFC4648}}. - -The payload of the POST request MUST be the data to be -stored. The 'Content-Type' SHOULD be -'application/octet-stream', although a STuPiD server -implementation SHOULD simply ignore the 'Content-Type' as a -client implementation may be restricted and may not able to -specify a specific 'Content-Type'. (E.g., in certain cases, -the peer may be limited to sending the data as -multipart-form-encoded — still, the data is stored as a -byte stream.) - -STuPiD servers may reject data chunks that are larger than -some predefined limit. -This maximum size in bytes of each data chunk is RECOMMENDED -to be 65536 or more. - -As HTTP already provides data transparency, -the data chunk SHOULD NOT be encoded using Base64 or any -other data transparency mechanism; in any case, the STuPiD -server will not attempt to decode the chunk. - -The sender MUST wait for the HTTP response before -going on to notify the receiver. - - -Notification ------------- - -The sender notifies the receiver of the data chunk by passing -via an out-of-band channel (which is not part of the STuPiD -protocol): - -The full URL from which the data chunk can be retrieved, -i.e. the same URL that was used to store the data chunk, -including the chunk ID parameter. - -The exact notification mechanism over the out-of-band channel -and the definition of a session is dependent on the -out-of-band channel. See {{xmpp}} for one -example of such an out-of-band channel. - - -Retrieving Data ---------------- - -The notified peer retrieves the data chunk using a GET request -with the URL supplied by the sender. The STuPiD server MUST -set the 'Content-Type' of the returned body to -'application/octet-stream'. - - -Implementation Notes -==================== - -A STuPiD server implementation SHOULD delete stored data some -time after it was stored. It is RECOMMENDED not to delete the -data before five minutes have elapsed after it was stored. -Different client protocols will have different reactions to -data that have been deleted prematurely and cannot be -retrieved by the notified peer; this may be as trivial as -packet loss or it may cause a reliable byte-stream to fail -({{impl}}). -(TODO: It may be useful to provide some hints in the storing -POST request.) - -STuPiD clients should aggregate data in order to minimize the -number of requests to the STuPiD server per second. -The specific aggregation method chosen depends on the data -rate required (and the maximum chunk size), the latency -requirements, and the application semantics. - -Clearly, it is up to the implementation to decide how the data -chunks are actually stored. A sufficiently silly STuPiD server -implementation might for instance use a MySQL database. - - -Security Considerations -======================= - -The security objectives of STuPiD are to be as secure as if -NAT traversal had succeeded, i.e., an on-path attacker can -overhear and fake messages, but an off-path attacker cannot. -If a higher level of security is desired, it should be -provided on top of the data relayed by STuPiD, e.g. by using -XTLS {{I-D.meyer-xmpp-e2e-encryption}}. - -Much of the security of STuPiD is based on the assumption that -an off-path attacker cannot guess the chunk identifiers. A -suitable source of randomness {{RFC4086}} should -be used to generate at least a sufficiently large part of the -chunk identifiers (e.g., the chunk identifier could be a hard -to guess prefix followed by a serial number). - -To protect the STuPiD server against denial of service and -possibly some forms of theft of service, it is RECOMMENDED -that the POST side of the STuPiD server be protected by some -form of authentication such as HTTP authentication. There is -little need to protect the GET side. - ---- back - - -Examples {#xmp} -======== - -This appendix provides some examples of the STuPiD protocol operation. - -~~~~~~~~~~ - Request: - - GET /stupid.php HTTP/1.0 - User-Agent: Example/1.11.4 - Accept: */* - Host: example.org - Connection: Keep-Alive - - Response: - - HTTP/1.1 200 OK - Date: Sun, 05 Jul 2009 00:30:37 GMT - Server: Apache/2.2 - Cache-Control: no-cache, must-revalidate - Expires: Sat, 26 Jul 1997 05:00:00 GMT - Vary: Accept-Encoding - Content-Length: 17 - Keep-Alive: timeout=1, max=400 - Connection: Keep-Alive - Content-Type: application/octet-stream - - 192.0.2.239:36654 -~~~~~~~~~~ -{: #figxmpdisco title="Discovering External IP Address and Port"} - -~~~~~~~~~~ - Request: - - POST /stupid.php?chid=i781hf64-0 HTTP/1.0 - User-Agent: Example/1.11.4 - Accept: */* - Host: example.org - Connection: Keep-Alive - Content-Type: application/octet-stream - Content-Length: 11 - - Hello World - - Response: - - HTTP/1.1 200 OK - Date: Sun, 05 Jul 2009 00:20:34 GMT - Server: Apache/2.2 - Cache-Control: no-cache, must-revalidate - Expires: Sat, 26 Jul 1997 05:00:00 GMT - Vary: Accept-Encoding - Content-Length: 0 - Keep-Alive: timeout=1, max=400 - Connection: Keep-Alive - Content-Type: application/octet-stream -~~~~~~~~~~ -{: #figxmpstore title="Storing Data"} - -~~~~~~~~~~ - Request: - - GET /stupid.php?chid=i781hf64-0 HTTP/1.0 - User-Agent: Example/1.11.4 - Accept: */* - Host: example.org - Connection: Keep-Alive - - Response: - - HTTP/1.1 200 OK - Date: Sun, 05 Jul 2009 00:21:29 GMT - Server: Apache/2.2 - Cache-Control: no-cache, must-revalidate - Expires: Sat, 26 Jul 1997 05:00:00 GMT - Vary: Accept-Encoding - Content-Length: 11 - Keep-Alive: timeout=1, max=400 - Connection: Keep-Alive - Content-Type: application/octet-stream - - Hello World -~~~~~~~~~~ -{: #figxmpretr title="Retrieving Data"} - - -Sample Implementation {#impl} -===================== - -~~~~~~~~~~ - -~~~~~~~~~~ -{: #figimpl title="STuPiD Sample Implementation"} - - -Using XMPP as Out-Of-Band Channel {#xmpp} -================================= - -XMPP {{I-D.ietf-xmpp-3920bis}} is a good choice for -an out-of-band channel. - -The notification protocol is closely modeled after XMPP's -In-Band Bytestreams (IBB, see -http://xmpp.org/extensions/xep-0047.html). Just replace the -namespace and insert the STuPiD Retrieval URI instead of the -actual Base64 encoded data, see {{figxmpnots}}. -(Note that the current proposal redundantly sends a sid and a -seq as well as the chid composed of these two; it may be -possible to optimize this, possibly sending the constant prefix -of the URI once at bytestream creation time.) - -Notifications MUST be processed in the order they are -received. If an out-of-sequence notification is received for a -particular session (determined by checking the 'seq' attribute), -then this indicates that a notification has been lost. The -recipient MUST NOT process such an out-of-sequence notification, -nor any that follow it within the same session; instead, the -recipient MUST consider the session invalid. (Adapted from -http://xmpp.org/extensions/xep-0047.html#send) - -Of course, other methods can be used for setup and teardown, such as Jingle -(see http://xmpp.org/extensions/xep-0261.html). - -~~~~~~~~~~ - - - -~~~~~~~~~~ -{: #figxmpcri title="Creating a Bytestream: Initiator requests session"} - - -~~~~~~~~~~ - -~~~~~~~~~~ -{: #figxmpcrr title="Creating a Bytestream: Responder accepts session"} - - - -~~~~~~~~~~ - - - -~~~~~~~~~~ -{: #figxmpnots title="Sending Notifications: Notification in an IQ stanza"} - -~~~~~~~~~~ - -~~~~~~~~~~ -{: #figxmpnota title="Sending Notifications: Acknowledging notification using IQ"} - -~~~~~~~~~~ - - - -~~~~~~~~~~ -{: #figxmpclor title="Closing the Bytestream: Request"} - -~~~~~~~~~~ - -~~~~~~~~~~ -{: #figxmpclos title="Closing the Bytestream: Success response"} - diff --git a/template.xml b/template.xml deleted file mode 100644 index d95422585..000000000 --- a/template.xml +++ /dev/null @@ -1,637 +0,0 @@ - - - - - - - - -]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Full Title - - - - - - Full Organization name -
- - - - Espoo - - - FI - - psavola@funet.fi - -
- - - - - Folly Consulting - -
- - - - Soham - - - - - - UK - - - +44 7889 488 335 - - - - elwynd@dial.pipex.com - - -
- - - - - - - - - Operations & Management - - - Internet Engineering Task Force - - - - - - - This is an abstract abstract. I-Ds and RFCs MUST have an abstract. - Remember, don't add references here. So we would just say the 'language' used to write - this document is defined in RFC 2629. - - - - This "forward" section is an unnumbered section that is not included - in the table of contents. It is primarily used for the IESG to - make comments about the document. It can also be used for comments about the status - of the document and sometimes is used for the RFC2119 requirements language statement. - - In this example, it is used as a handy place to specify URLs to - documents and tools to author RFC-style documents using XML. - RFC2629 is the original published document on authoring RFC-style - documents in XML - (). - It is being updated (and called RFC2629(bis) and is - . - The tool to convert XML documents to RFC-style text (and HTML) files - is described in document . - - Please also remember to check out - for issues to note when writing - drafts and the automated tools documented at - . - Remember, you don't need to have any other tools than a 'notepad' - or your favorite editor to write xml2rfc drafts. You can use the web - interface at for processing. The benefit of - using XML editors is mostly catching those missing tags which the processor will - warn you about, but you don't need to worry about the editors when getting - started. - This template is not meant to be a conclusive list of everything, - but summarize the often-needed basic features to get one started. - - - - - The key words "MUST", "MUST NOT", - "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", - "MAY", and "OPTIONAL" in this document are to be - interpreted as described in RFC 2119. - - - - - - -
- Now you can have a bit lengthier text here. - The definition of the XML Data Type Description used to 'describe' an RFC or Internet - Draft can be found in a document which we can refer to as - RFC 2629. - Let's refer to a couple more documents, just for practice: - and - L2TP. For text generation, these look equivalent, - but the latter looks a bit neater in the HTML representation. - You might also add a note about the usage of RFC2119 keywords here.. - You can cross-reference the sections of the document in a stable manner either by - section number - the usual way - or by section title - (""): if the organization of the - document changes the reference will still be to the correct section. However - "sect2" is not a very good 'anchor' name because there is no guarantee that - this section will remain as Section 2 for ever. It is best to use some sort of mnemonic - for the contents of the section, which also makes it easier to remember the anchor when - creating a cross-reference many pages later. A final note about anchors: anchors are - XML 'tokens' and must therefore consist only of letters, numbers, underscores, hyphens - and periods, starting with either a letter or underscore. Anchors with spaces or other - punctuation characters are not allowed. - -
- -
- Technical documents often use lists. There are multiple list styles: - 'empty', 'symbols', 'letters', 'numbers', 'hanging', 'format', etc. - - A more complicated list structure can be found in . - - First bullet - Second bullet - - You can write text here as well - the difference, as compared with putting it in the next - <t> element, is that there will not be a blank line between the last list item - and this text if the processing instructions compact and subcompact are both set to - "yes". Otherwise list items and the text before and after will be separated by blank - lines. - - One can draw fancy diagrams as well; remember to ensure that they - don't exceed 69 chars/line until v1.31 comes along. v1.31 should give you the ability - to start figures at the left margin getting figures up to 72 characters wide. - Setting the alignment for the whole figure to "center" instead of the default "left" - causes all the components to be centred unless it is overridden just for the "artwork", - as it is here. -
- Figures can have some text before the artwork should it be needed. Note - that figures should NOT be inside <t> elements. Originally they were allowed - to be but you will now get a warning that this is deprecated, and the figure should - be a 'child' of the section element. - - - - Figures can also have text after the artwork and before the caption (if - any). This figure has an anchor. This means that the figure will get a caption... - -
- Note that including a CDATA means you don't need to escape most special characters - you might otherwise have to. Figures may also have a title attribute but it won't be - displayed unless there is also an anchor, and it will be somewhat disconcerting for - readers if some figures have numbers and others don't.. - -
- There can be a lot of subsections (and sub-subsections). By default 3 levels of - nesting show in table of contents but that can be adjusted with the - value of the "tocdepth" processing instruction. -
- -
- Another item that you might need is a table. The XML for tables is very similar - to that for figures: - - - Tables use ttcol to define column headers and widths. - Every cell then has a "c" element for its content. - ttcol #1 - ttcol #2 - c #1 - c #2 - c #3 - c #4 - c #5 - c #6 - which is a very simple example. - -
-
- -
- One useful style of lists uses 'hanging labels' where the list item is indented by - the amount of the hangIndent with the hanging label displayed to the left of the first - line of the item. This example shows how <vspace> can be used to deal with the - odd label longer than the indent you really want to use (This is only really relevant - to text mode output because the labels are always on separate lines in HTML output): - - With a label shorter than the hangIndent there - is white space after the label and before the item text starts - although it starts on the same line - clearly separating the label - from the column of items. - With a label longer than the hangIndent - the label runs on into the text item and the separation is lost. - Inserting a - <vspace /> at the start of the item forces the new item to - start on a new line emphasizing the separation again. - - - - - List items in xml2rfc are made up of one <t> element. In some cases it would be - nice to have more than one paragraph in a list item. This can be achieved with - <vspace> also: - - First, a short item that needs only one paragraph. - Second, a longer list item. We have more to say, and we want a separate - paragraph. - And here we can have it, and go on to our heart's content. - - - If you just want an indented paragraph (say for a quotation) use the "empty" style: - - The quick, brown fox jumped over the lazy dog and lived to fool many another - hunter in the great wood in the west. - - -
- Sometimes it is useful to be able to number items continuously although they are - in separate <list> elements, maybe in separate sections. This can be achieved - using the "format" style and a "counter" variable. - - First list with (say) requirements items: - - Requirement #1 - Requirement #2 - Requirement #3 - - It is wise to specify the indent explicitly so that all the items line up nicely. - Otherwise the indent in each list is determined by the maximum length of the labels - in that list, even if later lists have longer labels. - A little later there is a second list with requirements items: - - Requirement #4 - Requirement #5 - Requirement #6 - - before this section finishes. -
-
- But in the next section the list of requirements continues: - Third list with requirements items: - - Requirement #7 - Requirement #8 - Requirement #9 - Requirement #10 - - And finally that is all about the requirements. -
-
- -
- The artwork element from RFC 2629 supports an - optional type attribute. While most possible values are - just ignored, including the special case where the attribute is unspecified or just - empty, some values are recognized. In particular, - type='abnf' can be used if the - artwork contains an Augmented Backus-Naur Form (ABNF) - syntax specification . As a special extension in its - behavior, xml2rfc will - attempt to validate the syntax and colorize the HTML output of ABNF, since it is so - widely used in RFCs. It does this colorizing by relying on the full parsing it does - right before, not on a quick and partial (e.g., line-by-line) pattern-based hack. - ABNF is the only artwork type to benefit from this kind of internal support at this - time. If the strict rfc-PI directive is activated, - invalid ABNF content will cause xml2rfc to abort with an - error message. Omitting the type attribute altogether - is the obvious way to avoid having this validation and colorizing performed. - -
- For example (to be viewed in HTML): - " - ; bracketed string of SP and VCHAR - without angles - ; prose description, to be used as - last resort -]]> - - This is from the original RFC on ABNF , - with its minor mistakes in manually folded comment lines purposely left intact, - for illustration. Since the result is still valid ABNF (but incorrect with respect - to what was intended), this showcases how colorizing might give a human author - (or editor or reader) a better chance to spot the three mistakes (and correct them, - e.g., with extra semicolons, as has been done in a more recent - version  of the ABNF specification). Note that it is - the white space characters at the beginning of the subsequent lines (including the - commented ones) that conspire to extend the reach of those rules across several - lines. -
-
- -
- The most common form of xml2rfc parsing errors are those where a - closing tag has been expected to be present before a new kind of tag is - specified. In the example below, Introduction section's last paragraph was - missing the closing t-element. The rest of the error messages can be rather - easily understood as well by reading it carefully and examining the context. - The reason is typically a missing tag somewhere. -
- - - -
- -=======8<======== -]]> - -
-
-
-
- - - -void -main(int argc, char *argv[]) -{ - int i; - - printf("program arguments are:\n"); - for (i = 0; i < argc; i++) { - printf("%d: \"%s\"\n", i, argv[i]); - } - - exit(0); -} /* main */ - -/* end of file */ -]]> - -
-
-
- Remember, it's important to acknowledge people who have - contributed to the work. - This template was extended from an initial version written by Pekka Savola and - contributed by him to the xml2rfc project. -
- - - -
- This memo includes no request to IANA. - (It's good - indeed pretty much mandatory now - to have an explicit note because - otherwise IANA wastes cycles trying to figure out if something is needed..) -
- -
- Remember to consider security from the start.. and all drafts are required to have - a security considerations section before they will pass the IESG. - -
- - - - - - - - - - RFC2661 - - - - - - - - - - - Key words for use in RFCs to Indicate Requirement - Levels - - Harvard University -
- - 1350 Mass. Ave. - Cambridge - MA 02138 - - - +1 617 495 3864 - sob@harvard.edu -
- - - General - keyword - - In many standards track documents several words are used to signify - the requirements in the specification. These words are often - capitalized. This document defines these words as they should be - interpreted in IETF documents. Authors who follow these guidelines - should incorporate this phrase near the beginning of their document: - - - - The key words "MUST", "MUST NOT", - "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", - "MAY", and "OPTIONAL" in this document are to be - interpreted as described in RFC 2119. - - - - Note that the force of these words is modified by the requirement level of - the document in which they are used. - - - - - - - - - - - - &RFC2629; - - - - - - - Ultimate Plan for Taking Over the World - - Mad Dominators, Inc. - - - - - &RFC4234; - &RFC2234; - - -
- You can add appendices just as regular sections, the only - difference is that they go within the "back" element, and not - within the "middle" element. And they follow the "reference" - elements. -
- - - From 0e3bc9c90f90aa79cc81908e1fb0dcd62290fd1d Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 29 Apr 2015 14:07:26 -0700 Subject: [PATCH 46/96] Updating travis config --- .travis.yml | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/.travis.yml b/.travis.yml index 4720bdbab..dd33830ba 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,14 +1,12 @@ language: python - before_install: - - sudo apt-get update -qq - - sudo apt-get install -y python-lxml python-pip +- sudo apt-get update -qq +- sudo apt-get install -y python-lxml python-pip install: - # here we don't use the travis default virtualenv because that - # causes us to install lxml again below, doubling the build time - # when it compiles the native modules from source - - deactivate - - gem install kramdown-rfc2629 - - sudo pip install xml2rfc - +- deactivate +- gem install kramdown-rfc2629 +- sudo pip install xml2rfc script: make ghpages +env: + global: + secure: YmX1en3m/xCy9YZXxswpq81RPjPa43+Zvwvb0gFFctl7Hk6LIs+coaS5v1at2/b8K8pg6PiycGkMhVOSNXxIHdcHim/VD69gXoYAsYf8G2kfmDtBj0E8mxFAunoStSVXZ98/U+armDyy2dZCtUCYt+FfsyV9ZYPbbGOhhkpgnOM= From 9a7506c305d0e8b4eca53f1b286dea8447bdbe14 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 12:41:16 -0700 Subject: [PATCH 47/96] Rework intro --- draft-thomson-http-encryption.md | 57 ++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 25 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 28fecffbd..f1937b6db 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -83,31 +83,38 @@ This memo introduces a content-coding for HTTP that allows message payloads to b # Introduction -It is sometimes desirable to encrypt the contents of a HTTP message (request or response) in a -persistent manner, so that when the payload is stored (e.g., with a HTTP PUT), only someone with -the appropriate key can read it. - -For example, it might be necessary to store a file on a server without exposing its contents to -that server. Furthermore, that same file could be replicated to other servers (to make it more -resistant to server or network failure), downloaded by clients (to make it available offline), etc. -without exposing its contents. - -These uses are not met by the use of TLS [RFC5246], since it only encrypts the channel between the -client and server. - -Message-based encryption formats - such as those that are described by [RFC4880], [RFC5652], -[I-D.ietf-jose-json-web-encryption], and [XMLENC] - are not suited to stream processing, which is -necessary for HTTP messages. While virtually any of these alternatives could be profiled and -adapted to suit, the overhead and complexity that would introduce is sub-optimal. However, this -format can be interpreted as sequence of JSON Web Encryption [I-D.ietf-jose-json-web-encryption] -values with a fixed header, see {{jwe}}. - -This document specifies a content-coding (Section 3.1.2 of [RFC7231]) for HTTP to serve these and -other use cases. - -This mechanism is likely only a small part of a larger design that uses content encryption. In -particular, this document does not describe key management practices. How clients and servers -acquire and identify keys will depend on the use case. +It is sometimes desirable to encrypt the contents of a HTTP message (request or +response) so that when the payload is stored (e.g., with a HTTP PUT), only +someone with the appropriate key can read it. + +For example, it might be necessary to store a file on a server without exposing +its contents to that server. Furthermore, that same file could be replicated to +other servers (to make it more resistant to server or network failure), +downloaded by clients (to make it available offline), etc. without exposing its +contents. + +These uses are not met by the use of TLS [RFC5246], since it only encrypts the +channel between the client and server. + +This document specifies a content-coding (Section 3.1.2 of [RFC7231]) for HTTP +to serve these and other use cases. + +This content-coding is not a direct adaptation of message-based encryption +formats - such as those that are described by [RFC4880], [RFC5652], +[I-D.ietf-jose-json-web-encryption], and [XMLENC] - which are not suited to +stream processing, which is necessary for HTTP. The format described here +cleaves more closely to the lower level constructs described in [RFC5116]. + +To the extent that message-based encryption formats use the same primitives, the +format can be considered as sequence of encrypted messages with a particular +profile. For instance, {{jwe}} explains how the format is congruent with a +sequence of JSON Web Encryption [I-D.ietf-jose-json-web-encryption] values with +a fixed header. + +This mechanism is likely only a small part of a larger design that uses content +encryption. In particular, this document does not describe key management +practices. How clients and servers acquire and identify keys will depend on the +use case. ## Notational Conventions From 2a0cfe3a679d516c7c4d7f45507ea36b6f8044b6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 12:52:30 -0700 Subject: [PATCH 48/96] Rework format description --- draft-thomson-http-encryption.md | 80 ++++++++++++++++++-------------- 1 file changed, 44 insertions(+), 36 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index f1937b6db..70cda6332 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -126,21 +126,24 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S # The "aesgcm-128" HTTP content-coding {#aesgcm128} -The "aesgcm-128" HTTP content-coding indicates that a payload has been encrypted using Advanced -Encryption Standard (AES) in Galois/Counter Mode (GCM) as identified as AEAD_AES_128_GCM in -[RFC5116], Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content encryption key. +The "aesgcm-128" HTTP content-coding indicates that a payload has been encrypted +using Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) as +identified as AEAD_AES_128_GCM in [RFC5116], Section 5.1. The AEAD_AES_128_GCM +algorithm uses a 128 bit content encryption key. -When this content-coding is in use, the Encryption header field ({{encryption}}) describes how -encryption has been applied. The Encryption-Key header field ({{encryption-key}}) can be included to -describe how the the content encryption key is derived or retrieved. +When this content-coding is in use, the Encryption header field ({{encryption}}) +describes how encryption has been applied. The Encryption-Key header field +({{encryption-key}}) can be included to describe how the the content encryption +key is derived or retrieved. -The "aesgcm-128" content-coding uses a single fixed set of encryption primitives. Cipher suite -agility is achieved by defining a new content-coding scheme. This ensures that only the HTTP -Accept-Encoding header field is necessary to negotiate the use of encryption. +The "aesgcm-128" content-coding uses a single fixed set of encryption +primitives. Cipher suite agility is achieved by defining a new content-coding +scheme. This ensures that only the HTTP Accept-Encoding header field is +necessary to negotiate the use of encryption. -The "aesgcm-128" content-coding uses a fixed record size. The resulting encoding is a series of -fixed-size records, with a final record that is one or more octets shorter than a fixed sized -record. +The "aesgcm-128" content-coding uses a fixed record size. The resulting +encoding is a series of fixed-size records, with a final record that is one or +more octets shorter than a fixed sized record. ~~~ +------+ @@ -158,30 +161,35 @@ record. +--------------------+ expands by 16 octets ~~~ -The record size determines the length of each portion of plaintext that is enciphered. The record -size defaults to 4096 octets, but can be changed using the "rs" parameter on the Encryption header -field. - -AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input plaintext. Therefore, the -length of each enciphered record is equal to the value of the "rs" parameter plus 16 octets. It is -a fatal decryption error to have a remainder of 16 octets or less in size (though AEAD_AES_128_GCM -permits input plaintext to be zero length, records always contain at least one padding octet). - -Each record contains between 0 and 255 octets of padding, inserted into a record before the -enciphered content. The length of the padding is stored in the first octet of the payload. All -padding octets MUST be set to zero. It is a fatal decryption error to have a record with more -padding than the record size. - -The nonce used for each record is a 96-bit value containing the index of the current record in -network byte order. Records are indexed starting at zero. - -The additional data passed to the AEAD algorithm is a zero-length octet sequence. - -A sequence of full-sized records can be truncated to produce a shorter sequence of records with -valid authentication tags. To prevent an attacker from truncating a stream, an endoder MUST append -a record that contains only padding if the final record is not shorter than the record size. A -receiver MUST treat the stream as failed due to truncation if the final record is not less than the -full record size. +The record size determines the length of each portion of plaintext that is +enciphered. The record size defaults to 4096 octets, but can be changed using +the "rs" parameter on the Encryption header field. + +AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input +plaintext. Therefore, the length of each enciphered record is equal to the +value of the "rs" parameter plus 16 octets. A receiver MUST fail to decrypt if +the remainder is 16 octets or less in size (though AEAD_AES_128_GCM permits +input plaintext to be zero length, records always contain at least one padding +octet). + +Each record contains between 0 and 255 octets of padding, inserted into a record +before the enciphered content. The length of the padding is stored in the first +octet of the payload. All padding octets MUST be set to zero. A receiver MUST +fail to decrypt if a record has more padding than the record size can +accommodate. + +The nonce used for each record is a 96-bit value containing the index of the +current record in network byte order. Records are indexed starting at zero. + +The additional data passed to each invocation of AEAD_AES_128_GCM is a +zero-length octet sequence. + +A sequence of full-sized records can be truncated to produce a shorter sequence +of records with valid authentication tags. To prevent an attacker from +truncating a stream, an encoder MUST append a record that contains only padding +and is smaller than the full record size if the final record ends on a record +boundary. A receiver MUST treat the stream as failed due to truncation if the +final record is the full record size. Issue: : Double check that this construction (with no AAD) is safe. From e0c9b10501ca50cf780f208a389b46a882a461ac Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 12:55:24 -0700 Subject: [PATCH 49/96] Correct error in derivation --- draft-thomson-http-encryption.md | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 70cda6332..ad8eb13a2 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -244,23 +244,26 @@ This value MUST be greater than 1. If the "rs" parameter is absent, the record ## Content Encryption Key Derivation {#derivation} -In order to allow the reuse of keying material for multiple different messages, a content encryption -key is derived for each message. This key is derived from the decoded value of the "s" parameter -using the HMAC-based key derivation function (HKDF) described in [RFC5869] using the SHA-256 hash -algorithm [FIPS180-2]. - -The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material -identified by the "keyid" parameter is the input keying material (IKM) to HKDF. Input keying -material can either be prearranged, or can be described using the Encryption-Key header field -({{encryption-key}}). The first step of HKDF is therefore: +In order to allow the reuse of keying material for multiple different messages, +a content encryption key is derived for each message. This key is derived from +the decoded value of the "salt" parameter using the HMAC-based key derivation +function (HKDF) described in [RFC5869] using the SHA-256 hash algorithm +[FIPS180-2]. + +The decoded value of the "salt" parameter is the salt input to HKDF function. +The keying material identified by the "keyid" parameter is the input keying +material (IKM) to HKDF. Input keying material can either be prearranged, or can +be described using the Encryption-Key header field ({{encryption-key}}). The +first step of HKDF is therefore: ~~~ PRK = HMAC-SHA-256(salt, IKM) ~~~ -AEAD_AES_128_GCM requires 16 octets (128 bits) of key, so the length (L) parameter of HKDF is 16. -The info parameter is set to the ASCII-encoded string "Content-Encoding: aesgcm128". The second -step of HKDF can therefore be simplified to the first 16 octets of a single HMAC: +AEAD_AES_128_GCM requires 16 octets (128 bits) of key, so the length (L) +parameter of HKDF is 16. The info parameter is set to the ASCII-encoded string +"Content-Encoding: aesgcm128". The second step of HKDF can therefore be +simplified to the first 16 octets of a single HMAC: ~~~ OKM = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) From 15b6ac3a2a7fccc6ad3ef260bdd0b7d38c846b23 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 12:57:37 -0700 Subject: [PATCH 50/96] Reflow --- draft-thomson-http-encryption.md | 321 +++++++++++++++++-------------- 1 file changed, 179 insertions(+), 142 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index ad8eb13a2..fbbf9025d 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -76,7 +76,8 @@ informative: --- abstract -This memo introduces a content-coding for HTTP that allows message payloads to be encrypted. +This memo introduces a content-coding for HTTP that allows message payloads to +be encrypted. --- middle @@ -119,9 +120,9 @@ use case. ## Notational Conventions -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", -"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in -[RFC2119]. +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC2119]. # The "aesgcm-128" HTTP content-coding {#aesgcm128} @@ -197,49 +198,55 @@ Issue: # The "Encryption" HTTP header field {#encryption} -The "Encryption" HTTP header field describes the encrypted content encoding(s) that have been -applied to a message payload, and therefore how those content encoding(s) can be removed. +The "Encryption" HTTP header field describes the encrypted content encoding(s) +that have been applied to a message payload, and therefore how those content +encoding(s) can be removed. ~~~ Encryption-val = #encryption_params encryption_params = [ param *( ";" param ) ] ~~~ -If the payload is encrypted more than once (as reflected by having multiple content-codings that -imply encryption), each application of the content encoding is reflected in the Encryption header -field, in the order in which they were applied. +If the payload is encrypted more than once (as reflected by having multiple +content-codings that imply encryption), each application of the content encoding +is reflected in the Encryption header field, in the order in which they were +applied. -The Encryption header MAY be omitted if the sender does not intend for the immediate recipient to -be able to decrypt the message. Alternatively, the Encryption header field MAY be omitted if the -sender intends for the recipient to acquire the header field by other means. +The Encryption header MAY be omitted if the sender does not intend for the +immediate recipient to be able to decrypt the message. Alternatively, the +Encryption header field MAY be omitted if the sender intends for the recipient +to acquire the header field by other means. -Servers processing PUT requests MUST persist the value of the Encryption header field, unless they -remove the content-coding by decrypting the payload. +Servers processing PUT requests MUST persist the value of the Encryption header +field, unless they remove the content-coding by decrypting the payload. ## Encryption Header Field Parameters -The following parameters are used in determining the key that is used for encryption: +The following parameters are used in determining the key that is used for +encryption: keyid: -: The "keyid" parameter contains a string that identifies the keying material that is used. The -"keyid" parameter SHOULD be included, unless key identification is guaranteed by other means. The -"keyid" parameter MUST be used if keying material is included in an Encryption-Key header field. +: The "keyid" parameter contains a string that identifies the keying material +that is used. The "keyid" parameter SHOULD be included, unless key +identification is guaranteed by other means. The "keyid" parameter MUST be used +if keying material is included in an Encryption-Key header field. salt: -: The "salt" parameter contains a base64 URL-encoded octets that is used as salt in deriving a -unique content encryption key (see {{derivation}}). The "salt" parameter MUST be present, and MUST -be exactly 16 octets long. The "salt" parameter MUST NOT be reused for two different messages that -have the same content encryption key; generating a random nonce for each message ensures that reuse -is highly unlikely. +: The "salt" parameter contains a base64 URL-encoded octets that is used as salt +in deriving a unique content encryption key (see {{derivation}}). The "salt" +parameter MUST be present, and MUST be exactly 16 octets long. The "salt" +parameter MUST NOT be reused for two different messages that have the same +content encryption key; generating a random nonce for each message ensures that +reuse is highly unlikely. rs: -: The "rs" parameter contains a positive decimal integer that describes the record size in octets. -This value MUST be greater than 1. If the "rs" parameter is absent, the record size defaults to -4096 octets. +: The "rs" parameter contains a positive decimal integer that describes the +record size in octets. This value MUST be greater than 1. If the "rs" +parameter is absent, the record size defaults to 4096 octets. ## Content Encryption Key Derivation {#derivation} @@ -272,8 +279,8 @@ simplified to the first 16 octets of a single HMAC: # Encryption-Key Header Field {#encryption-key} -An Encryption-Key header field can be used to describe the input keying material used in the -Encryption header field. +An Encryption-Key header field can be used to describe the input keying material +used in the Encryption header field. ~~~ Encryption-Key-val = #encryption_key_params @@ -282,63 +289,72 @@ Encryption header field. keyid: -: The "keyid" parameter corresponds to the "keyid" parameter in the Encryption header field. +: The "keyid" parameter corresponds to the "keyid" parameter in the Encryption +header field. key: -: The "key" parameter contains the URL-safe base64 [RFC4648] octets of the input keying material. +: The "key" parameter contains the URL-safe base64 [RFC4648] octets of the input +keying material. dh: -: The "dh" parameter contains an ephemeral Diffie-Hellman share. This form of the header field can -be used to encrypt content for a specific recipient. +: The "dh" parameter contains an ephemeral Diffie-Hellman share. This form of +the header field can be used to encrypt content for a specific recipient. -The input keying material used by the content-encoding key derivation (see {{derivation}}) can be -determined based on the information in the Encryption-Key header field. The method for key -derivation depends on the parameters that are present in the header field. +The input keying material used by the content-encoding key derivation (see +{{derivation}}) can be determined based on the information in the Encryption-Key +header field. The method for key derivation depends on the parameters that are +present in the header field. -Note that different methods for determining input keying materal will produce different -amounts of data. The HKDF process ensures that the final content encryption key is the necessary -size. +Note that different methods for determining input keying materal will produce +different amounts of data. The HKDF process ensures that the final content +encryption key is the necessary size. -Alternative methods for determining input keying material MAY be defined by specifications that use -this content-encoding. +Alternative methods for determining input keying material MAY be defined by +specifications that use this content-encoding. ## Explicit Key -The "key" parameter is decoded and used directly if present. The "key" parameter MUST decode to -exactly 16 octets in order to be used as input keying material for "aesgcm128" content encoding. +The "key" parameter is decoded and used directly if present. The "key" +parameter MUST decode to exactly 16 octets in order to be used as input keying +material for "aesgcm128" content encoding. -Other key determination parameters can be ignored if the "key" parameter is present. +Other key determination parameters can be ignored if the "key" parameter is +present. ## Diffie-Hellman -The "dh" parameter is included to describe a Diffie-Hellman share, either modp (or finite field) -Diffie-Hellman [DH] or elliptic curve Diffie-Hellman (ECDH) [RFC4492]. +The "dh" parameter is included to describe a Diffie-Hellman share, either modp +(or finite field) Diffie-Hellman [DH] or elliptic curve Diffie-Hellman (ECDH) +[RFC4492]. -This share is combined with other information at the recipient to determine the HKDF input keying -material. In order for the exchange to be successful, the following information MUST be established -out of band: +This share is combined with other information at the recipient to determine the +HKDF input keying material. In order for the exchange to be successful, the +following information MUST be established out of band: * Which Diffie-Hellman form is used. * The modp group or elliptic curve that will be used. -* The format of the ephemeral public share that is included in the "dh" parameter. For instance, - using ECDH both parties need to agree whether this is an uncompressed or compressed point. +* The format of the ephemeral public share that is included in the "dh" + parameter. For instance, using ECDH both parties need to agree whether this + is an uncompressed or compressed point. -In addition to identifying which content-encoding this input keying material is used for, the -"keyid" parameter is used to identify this additional information at the receiver. +In addition to identifying which content-encoding this input keying material is +used for, the "keyid" parameter is used to identify this additional information +at the receiver. -The intended recipient recovers their private key and are then able to generate a shared secret -using the appropriate Diffie-Hellman process. +The intended recipient recovers their private key and are then able to generate +a shared secret using the appropriate Diffie-Hellman process. -Specifications that rely on an Diffie-Hellman exchange for determining input keying material MUST -either specify the parameters for Diffie-Hellman (group parameters, or curves and point format) that -are used, or describe how those parameters are negotiated between sender and receiver. +Specifications that rely on an Diffie-Hellman exchange for determining input +keying material MUST either specify the parameters for Diffie-Hellman (group +parameters, or curves and point format) that are used, or describe how those +parameters are negotiated between sender and receiver. # Examples @@ -356,10 +372,11 @@ Encryption: keyid="http://example.org/bob/keys/123"; [encrypted payload] ~~~ -Here, a successful HTTP GET response has been encrypted using a key that is identified by a URI. +Here, a successful HTTP GET response has been encrypted using a key that is +identified by a URI. -Note that the media type has been changed to "application/octet-stream" to avoid exposing -information about the content. +Note that the media type has been changed to "application/octet-stream" to avoid +exposing information about the content. ## Encryption and Compression @@ -390,8 +407,8 @@ Encryption: keyid="mailto:me@example.com"; [encrypted payload] ~~~ -Here, a PUT request has been encrypted with two keys; both will be necessary to read the content. -The outer layer of encryption uses a 1200 octet record size. +Here, a PUT request has been encrypted with two keys; both will be necessary to +read the content. The outer layer of encryption uses a 1200 octet record size. ## Encryption with Explicit Key {#explicit} @@ -406,9 +423,9 @@ Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc ~~~ -This example shows the string "I am the walrus" encrypted using an explicit key. The content body -contains a single record only and is shown here encoded in URL-safe base64 for presentation reasons -only. +This example shows the string "I am the walrus" encrypted using an explicit key. +The content body contains a single record only and is shown here encoded in +URL-safe base64 for presentation reasons only. ## Diffie-Hellman Encryption @@ -425,13 +442,15 @@ Encryption-Key: keyid="dhkey"; BmuHqRzdD4W1mibxglrPiRHZRSY49Dzdm6jHrWXzZrE ~~~ -This example shows the same string, "I am the walrus", encrypted using ECDH over the P-256 curve -[FIPS186]. The content body is shown here encoded in URL-safe base64 for presentation reasons only. +This example shows the same string, "I am the walrus", encrypted using ECDH over +the P-256 curve [FIPS186]. The content body is shown here encoded in URL-safe +base64 for presentation reasons only. -The receiver (in this case, the HTTP client) uses the key identified by the string "dhkey" and the -sender (the server) uses a key pair for which the public share is included in the "dh" parameter -above. The keys shown below use uncompressed points [X.692] encoded using URL-safe base64. Line -wrapping is added for presentation purposes only. +The receiver (in this case, the HTTP client) uses the key identified by the +string "dhkey" and the sender (the server) uses a key pair for which the public +share is included in the "dh" parameter above. The keys shown below use +uncompressed points [X.692] encoded using URL-safe base64. Line wrapping is +added for presentation purposes only. ~~~ Receiver: @@ -448,8 +467,8 @@ wrapping is added for presentation purposes only. ## The "aesgcm-128" HTTP content-coding -This memo registers the "encrypted" HTTP content-coding in the HTTP Content Codings Registry, as -detailed in {{aesgcm128}}. +This memo registers the "encrypted" HTTP content-coding in the HTTP Content +Codings Registry, as detailed in {{aesgcm128}}. * Name: aesgcm-128 * Description: AES-GCM encryption with a 128-bit key @@ -458,8 +477,8 @@ detailed in {{aesgcm128}}. ## Encryption Header Fields -This memo registers the "Encryption" HTTP header field in the Permanent Message Header Registry, as -detailed in {{encryption}}. +This memo registers the "Encryption" HTTP header field in the Permanent Message +Header Registry, as detailed in {{encryption}}. * Field name: Encryption * Protocol: HTTP @@ -467,8 +486,8 @@ detailed in {{encryption}}. * Reference: [this specification] * Notes: -This memo registers the "Encryption-Key" HTTP header field in the Permanent Message Header Registry, -as detailed in {{encryption-key}}. +This memo registers the "Encryption-Key" HTTP header field in the Permanent +Message Header Registry, as detailed in {{encryption-key}}. * Field name: Encryption-Key * Protocol: HTTP @@ -513,9 +532,9 @@ The initial contents of this registry are: ## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} -This memo establishes a registry for parameters used by the "Encryption-Key" header -field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The -"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +This memo establishes a registry for parameters used by the "Encryption-Key" +header field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. +The "Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an "Specification Required" policy [RFC5226]. Entries in this registry are expected to include the following information: @@ -547,117 +566,135 @@ The initial contents of this registry are: # Security Considerations -This mechanism assumes the presence of a key management framework that is used to manage the -distribution of keys between valid senders and receivers. Defining key management is part of -composing this mechanism into a larger application, protocol, or framework. +This mechanism assumes the presence of a key management framework that is used +to manage the distribution of keys between valid senders and receivers. +Defining key management is part of composing this mechanism into a larger +application, protocol, or framework. -Implementation of cryptography - and key management in particular - can be difficult. For instance, -implementations need to account for the potential for exposing keying material on side channels, -such as might be exposed by the time it takes to perform a given operation. The requirements for a -good implementation of cryptographic algorithms can change over time. +Implementation of cryptography - and key management in particular - can be +difficult. For instance, implementations need to account for the potential for +exposing keying material on side channels, such as might be exposed by the time +it takes to perform a given operation. The requirements for a good +implementation of cryptographic algorithms can change over time. ## Key and Nonce Reuse -Encrypting different plaintext with the same content encryption key and nonce in AES-GCM is not safe -[RFC5116]. The scheme defined here relies on the uniqueness of the "nonce" parameter to ensure that -the content encryption key is different for every message. +Encrypting different plaintext with the same content encryption key and nonce in +AES-GCM is not safe [RFC5116]. The scheme defined here relies on the uniqueness +of the "nonce" parameter to ensure that the content encryption key is different +for every message. -If a key and nonce are reused, this could expose the content encryption key and it makes message -modification trivial. If the same key is used for multiple messages, then the nonce parameter MUST -be unique for each. An implementation SHOULD generate a random nonce parameter for every message, -though using a counter could achieve the desired result. +If a key and nonce are reused, this could expose the content encryption key and +it makes message modification trivial. If the same key is used for multiple +messages, then the nonce parameter MUST be unique for each. An implementation +SHOULD generate a random nonce parameter for every message, though using a +counter could achieve the desired result. ## Content Integrity -This mechanism only provides content origin authentication. The authentication tag only ensures -that those with access to the content encryption key produce a message that will be accepted as -valid. +This mechanism only provides content origin authentication. The authentication +tag only ensures that those with access to the content encryption key produce a +message that will be accepted as valid. -Any entity with the content encryption key can therefore produce content that will be accepted as -valid. This includes all recipients of the same message. +Any entity with the content encryption key can therefore produce content that +will be accepted as valid. This includes all recipients of the same message. -Furthermore, any entity that is able to modify both the Encryption header field and the message -payload can replace messages. Without the content encryption key however, modifications to or -replacement of parts of a message are not possible. +Furthermore, any entity that is able to modify both the Encryption header field +and the message payload can replace messages. Without the content encryption +key however, modifications to or replacement of parts of a message are not +possible. ## Leaking Information in Headers -Because "encrypted" only operates upon the message payload, any information exposed in header fields is -visible to anyone who can read the message. +Because "encrypted" only operates upon the message payload, any information +exposed in header fields is visible to anyone who can read the message. -For example, the Content-Type header field can leak information about the message payload. +For example, the Content-Type header field can leak information about the +message payload. -There are a number of strategies available to mitigate this threat, depending upon the -application's threat model and the users' tolerance for leaked information: +There are a number of strategies available to mitigate this threat, depending +upon the application's threat model and the users' tolerance for leaked +information: -1. Determine that it is not an issue. For example, if it is expected that all content stored will be -"application/json", or another very common media type, exposing the Content-Type header field could be an -acceptable risk. +1. Determine that it is not an issue. For example, if it is expected that all + content stored will be "application/json", or another very common media type, + exposing the Content-Type header field could be an acceptable risk. -2. If it is considered sensitive information and it is possible to determine it through other means -(e.g., out of band, using hints in other representations, etc.), omit the relevant headers, and/or -normalize them. In the case of Content-Type, this could be accomplished by always sending -Content-Type: application/octet-stream (the most generic media type), or no Content-Type at all. +2. If it is considered sensitive information and it is possible to determine it + through other means (e.g., out of band, using hints in other representations, + etc.), omit the relevant headers, and/or normalize them. In the case of + Content-Type, this could be accomplished by always sending Content-Type: + application/octet-stream (the most generic media type), or no Content-Type at + all. -3. If it is considered sensitive information and it is not possible to convey it elsewhere, -encapsulate the HTTP message using the application/http media type (Section 8.3.2 of [RFC7230]), encrypting that as the -payload of the "outer" message. +3. If it is considered sensitive information and it is not possible to convey it + elsewhere, encapsulate the HTTP message using the application/http media type + (Section 8.3.2 of [RFC7230]), encrypting that as the payload of the "outer" + message. ## Poisoning Storage -This mechanism only offers encryption of content; it does not perform authentication or -authorization, which still needs to be performed (e.g., by HTTP authentication [RFC7235]). +This mechanism only offers encryption of content; it does not perform +authentication or authorization, which still needs to be performed (e.g., by +HTTP authentication [RFC7235]). -This is especially relevant when a HTTP PUT request is accepted by a server; if the request is -unauthenticated, it becomes possible for a third party to deny service and/or poison the store. +This is especially relevant when a HTTP PUT request is accepted by a server; if +the request is unauthenticated, it becomes possible for a third party to deny +service and/or poison the store. ## Sizing and Timing Attacks -Applications using this mechanism need to be aware that the size of encrypted messages, as well as -their timing, HTTP methods, URIs and so on, may leak sensitive information. +Applications using this mechanism need to be aware that the size of encrypted +messages, as well as their timing, HTTP methods, URIs and so on, may leak +sensitive information. -This risk can be mitigated through the use of the padding that this mechanism provides. -Alternatively, splitting up content into segments and storing the separately might reduce -exposure. HTTP/2 [I-D.ietf-httpbis-http2] combined with TLS [RFC5246] might be used to hide the size -of individual messages. +This risk can be mitigated through the use of the padding that this mechanism +provides. Alternatively, splitting up content into segments and storing the +separately might reduce exposure. HTTP/2 [I-D.ietf-httpbis-http2] combined with +TLS [RFC5246] might be used to hide the size of individual messages. --- back # JWE Mapping {#jwe} -The "aesgcm-128" content encoding can be considered as a sequence of JSON Web Encryption (JWE) -objects, each corresponding to a single fixed size record. The following transformations are -applied to a JWE object that might be expressed using the JWE Compact Serialization: +The "aesgcm-128" content encoding can be considered as a sequence of JSON Web +Encryption (JWE) objects, each corresponding to a single fixed size record. The +following transformations are applied to a JWE object that might be expressed +using the JWE Compact Serialization: -* The JWE Protected Header is fixed to a value { "alg": "dir", "enc": "A128GCM" }, describing direct - encryption using AES-GCM with a 128-bit key. This header is not transmitted, it is instead - implied by the value of the Content-Encoding header field. +* The JWE Protected Header is fixed to a value { "alg": "dir", "enc": "A128GCM" + }, describing direct encryption using AES-GCM with a 128-bit key. This header + is not transmitted, it is instead implied by the value of the Content-Encoding + header field. * The JWE Encrypted Key is empty, as stipulated by the direct encryption algorithm. -* The JWE Initialization Vector ("iv") for each record is set to the 96-bit integer value of the - record sequence number, starting at zero. This value is also not transmitted. +* The JWE Initialization Vector ("iv") for each record is set to the 96-bit + integer value of the record sequence number, starting at zero. This value is + also not transmitted. -* The final value is the concatenated JWE Ciphertext and the JWE Authentication Tag, both expressed - without URL-safe Base 64 encoding. The "." separator is omitted, since the length of these fields - is known. +* The final value is the concatenated JWE Ciphertext and the JWE Authentication + Tag, both expressed without URL-safe Base 64 encoding. The "." separator is + omitted, since the length of these fields is known. -Thus, the example in {{explicit}} can be rendered using the JWE Compact Serialization as: +Thus, the example in {{explicit}} can be rendered using the JWE Compact +Serialization as: ~~~ eyAiYWxnIjogImRpciIsICJlbmMiOiAiQTEyOEdDTSIgfQ..AAAAAAAAAAAAAAAA. LwTC-fwdKh8de0smD2jfzA.eh1vURhu65M2lxhctbbntA ~~~ -Where the first line represents the fixed JWE Protected Header, JWE Encrypted Key, and JWE -Initialization Vector, all of which are determined algorithmically. The second line contains the -encoded body, split into JWE Ciphertext and JWE Authentication Tag. +Where the first line represents the fixed JWE Protected Header, JWE Encrypted +Key, and JWE Initialization Vector, all of which are determined algorithmically. +The second line contains the encoded body, split into JWE Ciphertext and JWE +Authentication Tag. # Acknowledgements From 6dca13d211b35e3470021efcbf761e38f49a196a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 13:00:11 -0700 Subject: [PATCH 51/96] Fixup of grammar --- draft-thomson-http-encryption.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index fbbf9025d..fedc56dd7 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -595,8 +595,8 @@ counter could achieve the desired result. ## Content Integrity This mechanism only provides content origin authentication. The authentication -tag only ensures that those with access to the content encryption key produce a -message that will be accepted as valid. +tag only ensures that an entity with access to the content encryption key +produced the encrypted data. Any entity with the content encryption key can therefore produce content that will be accepted as valid. This includes all recipients of the same message. From ca5edbd946ac0ea1db0b6cbbaa907dc0cf5fd7a0 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 13:01:56 -0700 Subject: [PATCH 52/96] Removing some errors --- draft-thomson-http-encryption.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index fedc56dd7..e141888fd 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -472,7 +472,7 @@ Codings Registry, as detailed in {{aesgcm128}}. * Name: aesgcm-128 * Description: AES-GCM encryption with a 128-bit key -* Reference [this specification] +* Reference: this specification ## Encryption Header Fields @@ -483,7 +483,7 @@ Header Registry, as detailed in {{encryption}}. * Field name: Encryption * Protocol: HTTP * Status: Standard -* Reference: [this specification] +* Reference: this specification * Notes: This memo registers the "Encryption-Key" HTTP header field in the Permanent @@ -492,7 +492,7 @@ Message Header Registry, as detailed in {{encryption-key}}. * Field name: Encryption-Key * Protocol: HTTP * Status: Standard -* Reference: [this specification] +* Reference: this specification * Notes: @@ -515,19 +515,19 @@ The initial contents of this registry are: * Parameter Name: keyid * Purpose: Identify the key that is in use. -* Reference: [this document] +* Reference: this document ### salt * Parameter Name: salt * Purpose: Provide a source of entropy for derivation of the content encryption key. This value is mandatory. -* Reference: [this document] +* Reference: this document ### rs * Parameter Name: rs * Purpose: The size of the encrypted records. -* Reference: [this document] +* Reference: this document ## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} @@ -549,19 +549,19 @@ The initial contents of this registry are: * Parameter Name: keyid * Purpose: Identify the key that is in use. -* Reference: [this document] +* Reference: this document ### key * Parameter Name: key * Purpose: Provide an explicit key. -* Reference: [this document] +* Reference: this document ### dh * Parameter Name: dh * Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive a key. -* Reference: [this document] +* Reference: this document # Security Considerations From 630e53639ce61be4f0bd4f2ede8cf164f79b702f Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 11 May 2015 13:21:47 -0700 Subject: [PATCH 53/96] Update from upstream --- Makefile | 2 +- lib/style.css | 10 ++++------ 2 files changed, 5 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 73bd391d5..b5e6d9a93 100644 --- a/Makefile +++ b/Makefile @@ -108,7 +108,7 @@ endif %.htmltmp: %.xml $(xml2rfc) $< -o $@ --html -%.html: %.htmltmp +%.html: %.htmltmp lib/addstyle.sed lib/style.css sed -f lib/addstyle.sed $< > $@ %.pdf: %.txt diff --git a/lib/style.css b/lib/style.css index 477ece864..65fb9d8e7 100644 --- a/lib/style.css +++ b/lib/style.css @@ -24,8 +24,6 @@ body { h1 { font-size: 130%; } h2 { font-size: 120%; } h3, h4 { font-size: 110%; } -ul.toc >li { font-size: 95%; } -ul.toc >li >ul, .figure, caption { font-size: 90%; } table { margin-left: 0em; @@ -69,10 +67,10 @@ ol, ul { padding: 0; margin: 0.5em 0 0.5em 2em; } -ul.toc, ul.toc ul { +ul.toc, ul.toc ul { margin: 0 0 0 1.5em; } -ul.toc a:first-child { - display: inline-block; +ul.toc a:first-child { + display: inline-block; min-width: 1.2em; -} \ No newline at end of file +} From 72df1435e4c14b1b2cea8418ba38d42453bb6235 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 18 May 2015 14:33:58 -0700 Subject: [PATCH 54/96] Using idref db on github --- Makefile | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index b5e6d9a93..53e654177 100644 --- a/Makefile +++ b/Makefile @@ -30,6 +30,9 @@ enscript ?= enscript # http://www.ghostscript.com/ ps2pdf ?= ps2pdf +# Where to get references +XML_RESOURCE_ORG_PREFIX ?= http://unicorn-wg.github.io/idrefs + ## Work out what to build @@ -98,7 +101,8 @@ endif .INTERMEDIATE: $(draft).xml %.xml: %.md - $(kramdown-rfc2629) $< > $@ + XML_RESOURCE_ORG_PREFIX=$(XML_RESOURCE_ORG_PREFIX) \ + $(kramdown-rfc2629) $< > $@ %.xml: %.org $(oxtradoc) -m outline-to-xml -n "$@" $< > $@ From 7fcddf914d0e821e5146a764752c519471104d5f Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 16 Jun 2015 16:51:36 -0700 Subject: [PATCH 55/96] Updating header field definitions --- draft-thomson-http-encryption.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index e141888fd..2a042b1b1 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -196,15 +196,18 @@ Issue: : Double check that this construction (with no AAD) is safe. -# The "Encryption" HTTP header field {#encryption} +# The Encryption HTTP header field {#encryption} -The "Encryption" HTTP header field describes the encrypted content encoding(s) +The `Encryption` HTTP header field describes the encrypted content encoding(s) that have been applied to a message payload, and therefore how those content encoding(s) can be removed. +The `Encryption` header field uses the extended ABNF syntax defined in +Section 1.2 of [RFC7230] and the `parameter` rule from [RFC7231] + ~~~ Encryption-val = #encryption_params - encryption_params = [ param *( ";" param ) ] + encryption_params = [ parameter *( ";" parameter ) ] ~~~ If the payload is encrypted more than once (as reflected by having multiple @@ -282,9 +285,12 @@ simplified to the first 16 octets of a single HMAC: An Encryption-Key header field can be used to describe the input keying material used in the Encryption header field. +The Encryption-Key header field uses the extended ABNF syntax defined in Section +1.2 of [RFC7230] and the `parameter` rule from [RFC7231]. + ~~~ Encryption-Key-val = #encryption_key_params - encryption_key_params = [ param *( ";" param ) ] + encryption_key_params = [ parameter *( ";" parameter ) ] ~~~ keyid: From eb3226b380a03ad5618bb1efe177c499b0d9c3f0 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 13:56:48 -0700 Subject: [PATCH 56/96] Properly qualify 'key' on each use --- draft-thomson-http-encryption.md | 78 +++++++++++++++++--------------- 1 file changed, 41 insertions(+), 37 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 2a042b1b1..ee8387871 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -226,15 +226,16 @@ field, unless they remove the content-coding by decrypting the payload. ## Encryption Header Field Parameters -The following parameters are used in determining the key that is used for -encryption: +The following parameters are used in determining the content encryption key that +is used for encryption: keyid: : The "keyid" parameter contains a string that identifies the keying material that is used. The "keyid" parameter SHOULD be included, unless key identification is guaranteed by other means. The "keyid" parameter MUST be used -if keying material is included in an Encryption-Key header field. +if keying material included in an Encryption-Key header field is needed to +derive the content encryption key. salt: @@ -255,10 +256,10 @@ parameter is absent, the record size defaults to 4096 octets. ## Content Encryption Key Derivation {#derivation} In order to allow the reuse of keying material for multiple different messages, -a content encryption key is derived for each message. This key is derived from -the decoded value of the "salt" parameter using the HMAC-based key derivation -function (HKDF) described in [RFC5869] using the SHA-256 hash algorithm -[FIPS180-2]. +a content encryption key is derived for each message. The content encryption +key is derived from the decoded value of the "salt" parameter using the +HMAC-based key derivation function (HKDF) described in [RFC5869] using the +SHA-256 hash algorithm [FIPS180-2]. The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material identified by the "keyid" parameter is the input keying @@ -270,13 +271,13 @@ first step of HKDF is therefore: PRK = HMAC-SHA-256(salt, IKM) ~~~ -AEAD_AES_128_GCM requires 16 octets (128 bits) of key, so the length (L) -parameter of HKDF is 16. The info parameter is set to the ASCII-encoded string -"Content-Encoding: aesgcm128". The second step of HKDF can therefore be -simplified to the first 16 octets of a single HMAC: +AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key, so the +length (L) parameter to HKDF is 16. The info parameter is set to the +ASCII-encoded string "Content-Encoding: aesgcm128". The second step of HKDF can +therefore be simplified to the first 16 octets of a single HMAC: ~~~ - OKM = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) + CEK = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) ~~~ @@ -324,9 +325,9 @@ specifications that use this content-encoding. ## Explicit Key -The "key" parameter is decoded and used directly if present. The "key" -parameter MUST decode to exactly 16 octets in order to be used as input keying -material for "aesgcm128" content encoding. +The "key" parameter is decoded and used as the input keying material if present. +The "key" parameter MUST decode to exactly 16 octets in order to be used as +input keying material for "aesgcm128" content encoding. Other key determination parameters can be ignored if the "key" parameter is present. @@ -378,8 +379,8 @@ Encryption: keyid="http://example.org/bob/keys/123"; [encrypted payload] ~~~ -Here, a successful HTTP GET response has been encrypted using a key that is -identified by a URI. +Here, a successful HTTP GET response has been encrypted using input keying +material that is identified by a URI. Note that the media type has been changed to "application/octet-stream" to avoid exposing information about the content. @@ -413,8 +414,9 @@ Encryption: keyid="mailto:me@example.com"; [encrypted payload] ~~~ -Here, a PUT request has been encrypted with two keys; both will be necessary to -read the content. The outer layer of encryption uses a 1200 octet record size. +Here, a PUT request has been encrypted twice with different input keying +material; decrypting twice is necessary to read the content. The outer layer of +encryption uses a 1200 octet record size. ## Encryption with Explicit Key {#explicit} @@ -429,9 +431,10 @@ Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc ~~~ -This example shows the string "I am the walrus" encrypted using an explicit key. -The content body contains a single record only and is shown here encoded in -URL-safe base64 for presentation reasons only. +This example shows the string "I am the walrus" encrypted using an directly +provided value for the input keying material. The content body contains a +single record only and is shown here encoded in URL-safe base64 for presentation +reasons only. ## Diffie-Hellman Encryption @@ -452,9 +455,9 @@ This example shows the same string, "I am the walrus", encrypted using ECDH over the P-256 curve [FIPS186]. The content body is shown here encoded in URL-safe base64 for presentation reasons only. -The receiver (in this case, the HTTP client) uses the key identified by the -string "dhkey" and the sender (the server) uses a key pair for which the public -share is included in the "dh" parameter above. The keys shown below use +The receiver (in this case, the HTTP client) uses a key pair that is identified +by the string "dhkey" and the sender (the server) uses a key pair for which the +public share is included in the "dh" parameter above. The keys shown below use uncompressed points [X.692] encoded using URL-safe base64. Line wrapping is added for presentation purposes only. @@ -477,7 +480,7 @@ This memo registers the "encrypted" HTTP content-coding in the HTTP Content Codings Registry, as detailed in {{aesgcm128}}. * Name: aesgcm-128 -* Description: AES-GCM encryption with a 128-bit key +* Description: AES-GCM encryption with a 128-bit content encryption key * Reference: this specification @@ -526,7 +529,7 @@ The initial contents of this registry are: ### salt * Parameter Name: salt -* Purpose: Provide a source of entropy for derivation of the content encryption key. This value is mandatory. +* Purpose: Provide a source of entropy for derivation of a content encryption key. This value is mandatory. * Reference: this document ### rs @@ -560,13 +563,13 @@ The initial contents of this registry are: ### key * Parameter Name: key -* Purpose: Provide an explicit key. +* Purpose: Provide an explicit input keying material value. * Reference: this document ### dh * Parameter Name: dh -* Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive a key. +* Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive input keying material. * Reference: this document @@ -591,11 +594,12 @@ AES-GCM is not safe [RFC5116]. The scheme defined here relies on the uniqueness of the "nonce" parameter to ensure that the content encryption key is different for every message. -If a key and nonce are reused, this could expose the content encryption key and -it makes message modification trivial. If the same key is used for multiple -messages, then the nonce parameter MUST be unique for each. An implementation -SHOULD generate a random nonce parameter for every message, though using a -counter could achieve the desired result. +If a content encryption key and nonce are reused, this could expose the content +encryption key and it makes message modification trivial. Thus, if the same +input keying material key is used for multiple messages, then the salt parameter +MUST be unique for each. This ensures that the content encryption key differs. +An implementation SHOULD generate a random salt parameter for every message; +alternatively, a counter could achieve the desired result. ## Content Integrity @@ -675,9 +679,9 @@ following transformations are applied to a JWE object that might be expressed using the JWE Compact Serialization: * The JWE Protected Header is fixed to a value { "alg": "dir", "enc": "A128GCM" - }, describing direct encryption using AES-GCM with a 128-bit key. This header - is not transmitted, it is instead implied by the value of the Content-Encoding - header field. + }, describing direct encryption using AES-GCM with a 128-bit content + encryption key. This header is not transmitted, it is instead implied by the + value of the Content-Encoding header field. * The JWE Encrypted Key is empty, as stipulated by the direct encryption algorithm. From 5f8fa93df09f4e8ea202628fcde9c8c6786dc678 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:11:38 -0700 Subject: [PATCH 57/96] Being more precise about what message means --- draft-thomson-http-encryption.md | 50 +++++++++++++++++--------------- 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index ee8387871..dcfbb6985 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -199,7 +199,7 @@ Issue: # The Encryption HTTP header field {#encryption} The `Encryption` HTTP header field describes the encrypted content encoding(s) -that have been applied to a message payload, and therefore how those content +that have been applied to a payload body, and therefore how those content encoding(s) can be removed. The `Encryption` header field uses the extended ABNF syntax defined in @@ -216,9 +216,9 @@ is reflected in the Encryption header field, in the order in which they were applied. The Encryption header MAY be omitted if the sender does not intend for the -immediate recipient to be able to decrypt the message. Alternatively, the -Encryption header field MAY be omitted if the sender intends for the recipient -to acquire the header field by other means. +immediate recipient to be able to decrypt the payload body. Alternatively, +the Encryption header field MAY be omitted if the sender intends for the +recipient to acquire the header field by other means. Servers processing PUT requests MUST persist the value of the Encryption header field, unless they remove the content-coding by decrypting the payload. @@ -242,9 +242,9 @@ salt: : The "salt" parameter contains a base64 URL-encoded octets that is used as salt in deriving a unique content encryption key (see {{derivation}}). The "salt" parameter MUST be present, and MUST be exactly 16 octets long. The "salt" -parameter MUST NOT be reused for two different messages that have the same -content encryption key; generating a random nonce for each message ensures that -reuse is highly unlikely. +parameter MUST NOT be reused for two different payload bodies that have the same +content encryption key; generating a random nonce for every application of the +content encoding ensures that reuse is highly unlikely. rs: @@ -255,10 +255,10 @@ parameter is absent, the record size defaults to 4096 octets. ## Content Encryption Key Derivation {#derivation} -In order to allow the reuse of keying material for multiple different messages, -a content encryption key is derived for each message. The content encryption -key is derived from the decoded value of the "salt" parameter using the -HMAC-based key derivation function (HKDF) described in [RFC5869] using the +In order to allow the reuse of keying material for multiple different HTTP +messages, a content encryption key is derived for each message. The content +encryption key is derived from the decoded value of the "salt" parameter using +the HMAC-based key derivation function (HKDF) described in [RFC5869] using the SHA-256 hash algorithm [FIPS180-2]. The decoded value of the "salt" parameter is the salt input to HKDF function. @@ -592,14 +592,14 @@ implementation of cryptographic algorithms can change over time. Encrypting different plaintext with the same content encryption key and nonce in AES-GCM is not safe [RFC5116]. The scheme defined here relies on the uniqueness of the "nonce" parameter to ensure that the content encryption key is different -for every message. +for every application of the content encoding. If a content encryption key and nonce are reused, this could expose the content -encryption key and it makes message modification trivial. Thus, if the same -input keying material key is used for multiple messages, then the salt parameter -MUST be unique for each. This ensures that the content encryption key differs. -An implementation SHOULD generate a random salt parameter for every message; -alternatively, a counter could achieve the desired result. +encryption key and it makes modification attacks trivial. Thus, if the same +input keying material is reused, then the salt parameter MUST be unique each +time. This ensures that the content encryption key is not reused. An +implementation SHOULD generate a random salt parameter for every message; +a counter could achieve the same result. ## Content Integrity @@ -609,21 +609,23 @@ tag only ensures that an entity with access to the content encryption key produced the encrypted data. Any entity with the content encryption key can therefore produce content that -will be accepted as valid. This includes all recipients of the same message. +will be accepted as valid. This includes all recipients of the same HTTP +message. Furthermore, any entity that is able to modify both the Encryption header field -and the message payload can replace messages. Without the content encryption -key however, modifications to or replacement of parts of a message are not -possible. +and the HTTP message body can replace the contents. Without the content +encryption key or the input keying material, modifications to or replacement of +parts of a payload body are not possible. ## Leaking Information in Headers -Because "encrypted" only operates upon the message payload, any information -exposed in header fields is visible to anyone who can read the message. +Because only the payload body is encrypted, information exposed in header fields +is visible to anyone who can read the HTTP message. This could expose +side-channel information. For example, the Content-Type header field can leak information about the -message payload. +payload body. There are a number of strategies available to mitigate this threat, depending upon the application's threat model and the users' tolerance for leaked From 84de030e85d9632c626152f1c3d337d510471c93 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:18:11 -0700 Subject: [PATCH 58/96] Some key management, not none --- draft-thomson-http-encryption.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index dcfbb6985..1a296041e 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -113,9 +113,10 @@ sequence of JSON Web Encryption [I-D.ietf-jose-json-web-encryption] values with a fixed header. This mechanism is likely only a small part of a larger design that uses content -encryption. In particular, this document does not describe key management -practices. How clients and servers acquire and identify keys will depend on the -use case. +encryption. How clients and servers acquire and identify keys will depend on +the use case. Though a complete key management system is not described, this +document defines an Encryption-Key header field that can be used to convey +keying material. ## Notational Conventions From 0470790df63215123cb992c8919ddac69b59be88 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:18:16 -0700 Subject: [PATCH 59/96] Editorial fixes --- draft-thomson-http-encryption.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 1a296041e..c2af7d6b2 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -135,8 +135,8 @@ algorithm uses a 128 bit content encryption key. When this content-coding is in use, the Encryption header field ({{encryption}}) describes how encryption has been applied. The Encryption-Key header field -({{encryption-key}}) can be included to describe how the the content encryption -key is derived or retrieved. +({{encryption-key}}) can be included to describe how the content encryption key +is derived or retrieved. The "aesgcm-128" content-coding uses a single fixed set of encryption primitives. Cipher suite agility is achieved by defining a new content-coding @@ -148,9 +148,9 @@ encoding is a series of fixed-size records, with a final record that is one or more octets shorter than a fixed sized record. ~~~ - +------+ - | data | input of between rs-256 - +------+ and rs-1 octets + +------+ input of between rs-256 + | data | and rs-1 octets + +------+ (one fewer for the last record) | v +-----+-----------+ From 8522d9bd5219383fb5beb79f0edcfca5830a8ab2 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:20:18 -0700 Subject: [PATCH 60/96] The last record size is smaller than rs+taglength --- draft-thomson-http-encryption.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index c2af7d6b2..1768f8061 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -164,8 +164,9 @@ more octets shorter than a fixed sized record. ~~~ The record size determines the length of each portion of plaintext that is -enciphered. The record size defaults to 4096 octets, but can be changed using -the "rs" parameter on the Encryption header field. +enciphered, with the exception of the final record, which is necessarily +smaller. The record size defaults to 4096 octets, but can be changed using the +"rs" parameter on the Encryption header field. AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input plaintext. Therefore, the length of each enciphered record is equal to the From 459b3dfc31bf8afb8216f2f4be4dd5d404e0cf74 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:25:14 -0700 Subject: [PATCH 61/96] Padding is right 1-256, not 0-255 --- draft-thomson-http-encryption.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 1768f8061..f9dcc890d 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -169,17 +169,17 @@ smaller. The record size defaults to 4096 octets, but can be changed using the "rs" parameter on the Encryption header field. AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input -plaintext. Therefore, the length of each enciphered record is equal to the -value of the "rs" parameter plus 16 octets. A receiver MUST fail to decrypt if -the remainder is 16 octets or less in size (though AEAD_AES_128_GCM permits -input plaintext to be zero length, records always contain at least one padding -octet). - -Each record contains between 0 and 255 octets of padding, inserted into a record -before the enciphered content. The length of the padding is stored in the first -octet of the payload. All padding octets MUST be set to zero. A receiver MUST -fail to decrypt if a record has more padding than the record size can -accommodate. +plaintext. Therefore, the length of each enciphered record other than the last +is equal to the value of the "rs" parameter plus 16 octets. A receiver MUST +fail to decrypt if the remainder is 16 octets or less in size (though +AEAD_AES_128_GCM permits input plaintext to be zero length, records always +contain at least one padding octet). + +Each record contains between 1 and 256 octets of padding, inserted into a record +before the enciphered content. Padding consists of a length byte, followed that +number of zero-valued bytes. A receiver MUST fail to decrypt if any padding +byte other than the first is non-zero, or a record has more padding than the +record size can accommodate. The nonce used for each record is a 96-bit value containing the index of the current record in network byte order. Records are indexed starting at zero. From 144353cd2671d559a68af7752527db66f030db44 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:39:52 -0700 Subject: [PATCH 62/96] Removing confusion about the use of 'nonce' --- draft-thomson-http-encryption.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index f9dcc890d..be79d02a3 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -171,9 +171,9 @@ smaller. The record size defaults to 4096 octets, but can be changed using the AEAD_AES_128_GCM expands ciphertext to be 16 octets longer than its input plaintext. Therefore, the length of each enciphered record other than the last is equal to the value of the "rs" parameter plus 16 octets. A receiver MUST -fail to decrypt if the remainder is 16 octets or less in size (though -AEAD_AES_128_GCM permits input plaintext to be zero length, records always -contain at least one padding octet). +fail to decrypt if the final record ciphertext is 16 octets or less in size. +Valid records always contain at least one byte of padding and a 16 octet +authentication tag. Each record contains between 1 and 256 octets of padding, inserted into a record before the enciphered content. Padding consists of a length byte, followed that @@ -245,7 +245,7 @@ salt: in deriving a unique content encryption key (see {{derivation}}). The "salt" parameter MUST be present, and MUST be exactly 16 octets long. The "salt" parameter MUST NOT be reused for two different payload bodies that have the same -content encryption key; generating a random nonce for every application of the +content encryption key; generating a random salt for every application of the content encoding ensures that reuse is highly unlikely. rs: @@ -592,16 +592,19 @@ implementation of cryptographic algorithms can change over time. ## Key and Nonce Reuse Encrypting different plaintext with the same content encryption key and nonce in -AES-GCM is not safe [RFC5116]. The scheme defined here relies on the uniqueness -of the "nonce" parameter to ensure that the content encryption key is different -for every application of the content encoding. - -If a content encryption key and nonce are reused, this could expose the content -encryption key and it makes modification attacks trivial. Thus, if the same -input keying material is reused, then the salt parameter MUST be unique each -time. This ensures that the content encryption key is not reused. An -implementation SHOULD generate a random salt parameter for every message; -a counter could achieve the same result. +AES-GCM is not safe [RFC5116]. The scheme defined here uses a fixed progression +of nonce values. Thus, a new content encryption key is needed for every +application of the content encoding. Since input keying material can be reused, +a unique "salt" parameter is needed to ensure a content encryption key is not +reused. + +If a content encryption key is reused - that is, if input keying material and +salt are reused - this could expose the content encryption key or make +modification attacks trivial. Thus, if the same input keying material is +reused, then the salt parameter MUST be unique each time. This ensures that the +content encryption key is not reused. An implementation SHOULD generate a +random salt parameter for every message; a counter could achieve the same +result. ## Content Integrity From 4d62804f50d6907bedbd685c251ca984f5310954 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 22 Jun 2015 14:55:53 -0700 Subject: [PATCH 63/96] CEK -> IKM as a constraint on salt uniqueness --- draft-thomson-http-encryption.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index be79d02a3..3a6342f6d 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -245,8 +245,8 @@ salt: in deriving a unique content encryption key (see {{derivation}}). The "salt" parameter MUST be present, and MUST be exactly 16 octets long. The "salt" parameter MUST NOT be reused for two different payload bodies that have the same -content encryption key; generating a random salt for every application of the -content encoding ensures that reuse is highly unlikely. +input keying material; generating a random salt for every application of the +content encoding ensures that content encryption key reuse is highly unlikely. rs: @@ -317,7 +317,7 @@ The input keying material used by the content-encoding key derivation (see header field. The method for key derivation depends on the parameters that are present in the header field. -Note that different methods for determining input keying materal will produce +Note that different methods for determining input keying material will produce different amounts of data. The HKDF process ensures that the final content encryption key is the necessary size. From 5ad153cb5098100fa2b39eba21401f9f2567e86b Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 09:01:42 -0700 Subject: [PATCH 64/96] At least 16 octets, not exactly --- draft-thomson-http-encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 3a6342f6d..dfde97e06 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -328,7 +328,7 @@ specifications that use this content-encoding. ## Explicit Key The "key" parameter is decoded and used as the input keying material if present. -The "key" parameter MUST decode to exactly 16 octets in order to be used as +The "key" parameter MUST decode to at least 16 octets in order to be used as input keying material for "aesgcm128" content encoding. Other key determination parameters can be ignored if the "key" parameter is From 566734c96de3c801399e8fe022fbdefc4edf1cf4 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 09:02:34 -0700 Subject: [PATCH 65/96] Scoping Encryption-Key --- draft-thomson-http-encryption.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index dfde97e06..3b5cb5d5b 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -317,6 +317,10 @@ The input keying material used by the content-encoding key derivation (see header field. The method for key derivation depends on the parameters that are present in the header field. +The value or values provided in the Encryption-Key header field is valid only +for the current HTTP message unless additional information indicates a greater +scope. + Note that different methods for determining input keying material will produce different amounts of data. The HKDF process ensures that the final content encryption key is the necessary size. From 5b01481fa21893d7231f42b03d0a6c2da1601bef Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 09:09:37 -0700 Subject: [PATCH 66/96] Lengths on examples were wrong --- draft-thomson-http-encryption.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 3b5cb5d5b..d39447dd9 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -429,7 +429,7 @@ encryption uses a 1200 octet record size. ~~~ HTTP/1.1 200 OK -Content-Length: 31 +Content-Length: 32 Content-Encoding: aesgcm-128 Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" @@ -447,7 +447,7 @@ reasons only. ~~~ HTTP/1.1 200 OK -Content-Length: 31 +Content-Length: 32 Content-Encoding: aesgcm-128 Encryption: keyid="dhkey"; salt="5hpuYfxDzG6nSs9-EQuaBg" Encryption-Key: keyid="dhkey"; From 33eda453024d489af8cb2e84d4b1b529c0869f1a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 09:13:31 -0700 Subject: [PATCH 67/96] Reuse implications --- draft-thomson-http-encryption.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index d39447dd9..06ce96281 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -603,12 +603,12 @@ a unique "salt" parameter is needed to ensure a content encryption key is not reused. If a content encryption key is reused - that is, if input keying material and -salt are reused - this could expose the content encryption key or make -modification attacks trivial. Thus, if the same input keying material is -reused, then the salt parameter MUST be unique each time. This ensures that the -content encryption key is not reused. An implementation SHOULD generate a -random salt parameter for every message; a counter could achieve the same -result. +salt are reused - this could expose the plaintext and the authentication key, +nullifying the protection offered by encryption. Thus, if the same input keying +material is reused, then the salt parameter MUST be unique each time. This +ensures that the content encryption key is not reused. An implementation SHOULD +generate a random salt parameter for every message; a counter could achieve the +same result. ## Content Integrity From 9e6cc6130983a65bb761a62fe35090cb749d61c6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 11:54:41 -0700 Subject: [PATCH 68/96] Starting from a non-zero nonce --- draft-thomson-http-encryption.md | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 06ce96281..d3b045403 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -181,8 +181,8 @@ number of zero-valued bytes. A receiver MUST fail to decrypt if any padding byte other than the first is non-zero, or a record has more padding than the record size can accommodate. -The nonce used for each record is a 96-bit value containing the index of the -current record in network byte order. Records are indexed starting at zero. +The nonce for each record is a 96-bit value constructed from the record sequence +number and the input keying material. Nonce derivation is covered in {{nonce}}. The additional data passed to each invocation of AEAD_AES_128_GCM is a zero-length octet sequence. @@ -283,6 +283,27 @@ therefore be simplified to the first 16 octets of a single HMAC: ~~~ +## Nonce Derivation {#nonce} + +The nonce input to AEAD_AES_128_GCM is constructed for each record. The nonce +for each record is a 12 octet (96 bit) value is produced from the record +sequence number and a value derived from the input keying material. + +The input keying material and salt values are input to HKDF with different info +and length parameters. The info parameter for the nonce is the ASCII-encoded +string "Content-Encoding: nonce" and the length (L) parameter is 12 octets. + +The result is combined with the record sequence number - using exclusive or - to +produce the nonce. The record sequence number (SEQ) is a 96-bit unsigned +integer in network byte order that starts at zero. + +Thus, the final nonce for each record is a 12 octet value: + +~~~ + NONCE = HMAC-SHA-256(PRK, "Content-Encoding: nonce" || 0x01) ^ SEQ +~~~ + + # Encryption-Key Header Field {#encryption-key} An Encryption-Key header field can be used to describe the input keying material From 26da125348fe9e5aaaa5a959c27e7f6eda346e93 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 11:54:51 -0700 Subject: [PATCH 69/96] The hyphen must die --- draft-thomson-http-encryption.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index d3b045403..cf1ad54ff 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -126,9 +126,9 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", interpreted as described in [RFC2119]. -# The "aesgcm-128" HTTP content-coding {#aesgcm128} +# The "aesgcm128" HTTP content-coding {#aesgcm128} -The "aesgcm-128" HTTP content-coding indicates that a payload has been encrypted +The "aesgcm128" HTTP content-coding indicates that a payload has been encrypted using Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) as identified as AEAD_AES_128_GCM in [RFC5116], Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content encryption key. @@ -138,12 +138,12 @@ describes how encryption has been applied. The Encryption-Key header field ({{encryption-key}}) can be included to describe how the content encryption key is derived or retrieved. -The "aesgcm-128" content-coding uses a single fixed set of encryption +The "aesgcm128" content-coding uses a single fixed set of encryption primitives. Cipher suite agility is achieved by defining a new content-coding scheme. This ensures that only the HTTP Accept-Encoding header field is necessary to negotiate the use of encryption. -The "aesgcm-128" content-coding uses a fixed record size. The resulting +The "aesgcm128" content-coding uses a fixed record size. The resulting encoding is a series of fixed-size records, with a final record that is one or more octets shorter than a fixed sized record. @@ -398,7 +398,7 @@ parameters are negotiated between sender and receiver. ~~~ HTTP/1.1 200 OK Content-Type: application/octet-stream -Content-Encoding: aesgcm-128 +Content-Encoding: aesgcm128 Connection: close Encryption: keyid="http://example.org/bob/keys/123"; salt="XZwpw6o37R-6qoZjw6KwAw" @@ -417,7 +417,7 @@ exposing information about the content. ~~~ HTTP/1.1 200 OK Content-Type: text/html -Content-Encoding: aesgcm-128, gzip +Content-Encoding: aesgcm128, gzip Transfer-Encoding: chunked Encryption: keyid="mailto:me@example.com"; salt="m2hJ_NttRtFyUiMRPwfpHA" @@ -431,7 +431,7 @@ Encryption: keyid="mailto:me@example.com"; PUT /thing HTTP/1.1 Host: storage.example.com Content-Type: application/http -Content-Encoding: aesgcm-128, aesgcm-128 +Content-Encoding: aesgcm128, aesgcm128 Content-Length: 1234 Encryption: keyid="mailto:me@example.com"; salt="NfzOeuV5USPRA-n_9s1Lag", @@ -451,7 +451,7 @@ encryption uses a 1200 octet record size. ~~~ HTTP/1.1 200 OK Content-Length: 32 -Content-Encoding: aesgcm-128 +Content-Encoding: aesgcm128 Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" @@ -469,7 +469,7 @@ reasons only. ~~~ HTTP/1.1 200 OK Content-Length: 32 -Content-Encoding: aesgcm-128 +Content-Encoding: aesgcm128 Encryption: keyid="dhkey"; salt="5hpuYfxDzG6nSs9-EQuaBg" Encryption-Key: keyid="dhkey"; dh="BLsyIPbDn6bquEOwHaju2gj8kUVoflzTtPs_6fGoock_ @@ -501,12 +501,12 @@ added for presentation purposes only. # IANA Considerations -## The "aesgcm-128" HTTP content-coding +## The "aesgcm128" HTTP content-coding This memo registers the "encrypted" HTTP content-coding in the HTTP Content Codings Registry, as detailed in {{aesgcm128}}. -* Name: aesgcm-128 +* Name: aesgcm128 * Description: AES-GCM encryption with a 128-bit content encryption key * Reference: this specification @@ -705,7 +705,7 @@ TLS [RFC5246] might be used to hide the size of individual messages. # JWE Mapping {#jwe} -The "aesgcm-128" content encoding can be considered as a sequence of JSON Web +The "aesgcm128" content encoding can be considered as a sequence of JSON Web Encryption (JWE) objects, each corresponding to a single fixed size record. The following transformations are applied to a JWE object that might be expressed using the JWE Compact Serialization: From d91947c3b47f5c18d128b2621871802914d337fd Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 13:21:34 -0700 Subject: [PATCH 70/96] Adding record sizing note; s/byte/octet --- draft-thomson-http-encryption.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index cf1ad54ff..cda7c5f21 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -47,6 +47,7 @@ informative: RFC5226: RFC5246: RFC5652: + RFC7233: RFC7235: I-D.ietf-httpbis-http2: FIPS186: @@ -177,8 +178,8 @@ authentication tag. Each record contains between 1 and 256 octets of padding, inserted into a record before the enciphered content. Padding consists of a length byte, followed that -number of zero-valued bytes. A receiver MUST fail to decrypt if any padding -byte other than the first is non-zero, or a record has more padding than the +number of zero-valued octets. A receiver MUST fail to decrypt if any padding +octet other than the first is non-zero, or a record has more padding than the record size can accommodate. The nonce for each record is a 96-bit value constructed from the record sequence @@ -194,8 +195,11 @@ and is smaller than the full record size if the final record ends on a record boundary. A receiver MUST treat the stream as failed due to truncation if the final record is the full record size. -Issue: -: Double check that this construction (with no AAD) is safe. +A consequence of this record structure is that range requests [RFC7233] and +random access to encrypted payload bodies are possible at the granularity of the +record size. However, without data from adjacent ranges, partial records cannot +be used. Thus, it is best if records start and end on multiples of the record +size, plus the 16 octet authentication tag size. # The Encryption HTTP header field {#encryption} From 9370368fec2e4ae76450db2877a075f2210c4339 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 23 Jun 2015 13:34:38 -0700 Subject: [PATCH 71/96] ...when decoded --- draft-thomson-http-encryption.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index cda7c5f21..daf599e75 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -247,10 +247,11 @@ salt: : The "salt" parameter contains a base64 URL-encoded octets that is used as salt in deriving a unique content encryption key (see {{derivation}}). The "salt" -parameter MUST be present, and MUST be exactly 16 octets long. The "salt" -parameter MUST NOT be reused for two different payload bodies that have the same -input keying material; generating a random salt for every application of the -content encoding ensures that content encryption key reuse is highly unlikely. +parameter MUST be present, and MUST be exactly 16 octets long when decoded. The +"salt" parameter MUST NOT be reused for two different payload bodies that have +the same input keying material; generating a random salt for every application +of the content encoding ensures that content encryption key reuse is highly +unlikely. rs: From 6af8817d74b5465809783eb6249d0c17850c6de4 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 24 Jun 2015 18:52:47 -0700 Subject: [PATCH 72/96] Moving IANA considerations, fixing capitals --- draft-thomson-http-encryption.md | 206 +++++++++++++++---------------- 1 file changed, 103 insertions(+), 103 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index daf599e75..12cffce23 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -127,7 +127,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", interpreted as described in [RFC2119]. -# The "aesgcm128" HTTP content-coding {#aesgcm128} +# The "aesgcm128" HTTP Content Encoding {#aesgcm128} The "aesgcm128" HTTP content-coding indicates that a payload has been encrypted using Advanced Encryption Standard (AES) in Galois/Counter Mode (GCM) as @@ -202,7 +202,7 @@ be used. Thus, it is best if records start and end on multiples of the record size, plus the 16 octet authentication tag size. -# The Encryption HTTP header field {#encryption} +# The Encryption HTTP Header Field {#encryption} The `Encryption` HTTP header field describes the encrypted content encoding(s) that have been applied to a payload body, and therefore how those content @@ -504,107 +504,6 @@ added for presentation purposes only. ~~~ -# IANA Considerations - -## The "aesgcm128" HTTP content-coding - -This memo registers the "encrypted" HTTP content-coding in the HTTP Content -Codings Registry, as detailed in {{aesgcm128}}. - -* Name: aesgcm128 -* Description: AES-GCM encryption with a 128-bit content encryption key -* Reference: this specification - - -## Encryption Header Fields - -This memo registers the "Encryption" HTTP header field in the Permanent Message -Header Registry, as detailed in {{encryption}}. - -* Field name: Encryption -* Protocol: HTTP -* Status: Standard -* Reference: this specification -* Notes: - -This memo registers the "Encryption-Key" HTTP header field in the Permanent -Message Header Registry, as detailed in {{encryption-key}}. - -* Field name: Encryption-Key -* Protocol: HTTP -* Status: Standard -* Reference: this specification -* Notes: - - -## The HTTP Encryption Parameter Registry {#encryption-registry} - -This memo establishes a registry for parameters used by the "Encryption" header -field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The -"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an -"Specification Required" policy [RFC5226]. - -Entries in this registry are expected to include the following information: - -* Parameter Name: The name of the parameter. -* Purpose: A brief description of the purpose of the parameter. -* Reference: A reference to a specification that defines the semantics of the parameter. - -The initial contents of this registry are: - -### keyid - -* Parameter Name: keyid -* Purpose: Identify the key that is in use. -* Reference: this document - -### salt - -* Parameter Name: salt -* Purpose: Provide a source of entropy for derivation of a content encryption key. This value is mandatory. -* Reference: this document - -### rs - -* Parameter Name: rs -* Purpose: The size of the encrypted records. -* Reference: this document - - -## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} - -This memo establishes a registry for parameters used by the "Encryption-Key" -header field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. -The "Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an -"Specification Required" policy [RFC5226]. - -Entries in this registry are expected to include the following information: - -* Parameter Name: The name of the parameter. -* Purpose: A brief description of the purpose of the parameter. -* Reference: A reference to a specification that defines the semantics of the parameter. - -The initial contents of this registry are: - -### keyid - -* Parameter Name: keyid -* Purpose: Identify the key that is in use. -* Reference: this document - -### key - -* Parameter Name: key -* Purpose: Provide an explicit input keying material value. -* Reference: this document - -### dh - -* Parameter Name: dh -* Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive input keying material. -* Reference: this document - - # Security Considerations This mechanism assumes the presence of a key management framework that is used @@ -706,6 +605,107 @@ separately might reduce exposure. HTTP/2 [I-D.ietf-httpbis-http2] combined with TLS [RFC5246] might be used to hide the size of individual messages. +# IANA Considerations + +## The "aesgcm128" HTTP Content Encoding + +This memo registers the "encrypted" HTTP content-coding in the HTTP Content +Codings Registry, as detailed in {{aesgcm128}}. + +* Name: aesgcm128 +* Description: AES-GCM encryption with a 128-bit content encryption key +* Reference: this specification + + +## Encryption Header Fields + +This memo registers the "Encryption" HTTP header field in the Permanent Message +Header Registry, as detailed in {{encryption}}. + +* Field name: Encryption +* Protocol: HTTP +* Status: Standard +* Reference: this specification +* Notes: + +This memo registers the "Encryption-Key" HTTP header field in the Permanent +Message Header Registry, as detailed in {{encryption-key}}. + +* Field name: Encryption-Key +* Protocol: HTTP +* Status: Standard +* Reference: this specification +* Notes: + + +## The HTTP Encryption Parameter Registry {#encryption-registry} + +This memo establishes a registry for parameters used by the "Encryption" header +field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The +"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +"Specification Required" policy [RFC5226]. + +Entries in this registry are expected to include the following information: + +* Parameter Name: The name of the parameter. +* Purpose: A brief description of the purpose of the parameter. +* Reference: A reference to a specification that defines the semantics of the parameter. + +The initial contents of this registry are: + +### keyid + +* Parameter Name: keyid +* Purpose: Identify the key that is in use. +* Reference: this document + +### salt + +* Parameter Name: salt +* Purpose: Provide a source of entropy for derivation of a content encryption key. This value is mandatory. +* Reference: this document + +### rs + +* Parameter Name: rs +* Purpose: The size of the encrypted records. +* Reference: this document + + +## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} + +This memo establishes a registry for parameters used by the "Encryption-Key" +header field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. +The "Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +"Specification Required" policy [RFC5226]. + +Entries in this registry are expected to include the following information: + +* Parameter Name: The name of the parameter. +* Purpose: A brief description of the purpose of the parameter. +* Reference: A reference to a specification that defines the semantics of the parameter. + +The initial contents of this registry are: + +### keyid + +* Parameter Name: keyid +* Purpose: Identify the key that is in use. +* Reference: this document + +### key + +* Parameter Name: key +* Purpose: Provide an explicit input keying material value. +* Reference: this document + +### dh + +* Parameter Name: dh +* Purpose: Carry a modp or elliptic curve Diffie-Hellman share used to derive input keying material. +* Reference: this document + + --- back # JWE Mapping {#jwe} From 34aa9fee0ae628c249a4bc3ea8808d2ba2af8aa6 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 25 Jun 2015 11:58:03 -0700 Subject: [PATCH 73/96] Updating JWE text --- draft-thomson-http-encryption.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 12cffce23..b747d1aa5 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -722,9 +722,10 @@ using the JWE Compact Serialization: * The JWE Encrypted Key is empty, as stipulated by the direct encryption algorithm. -* The JWE Initialization Vector ("iv") for each record is set to the 96-bit - integer value of the record sequence number, starting at zero. This value is - also not transmitted. +* The JWE Initialization Vector ("iv") for each record is set to the exclusive + or of the 96-bit record sequence number, starting at zero, and a value derived + from the input keying material (see {{nonce}}). This value is also not + transmitted. * The final value is the concatenated JWE Ciphertext and the JWE Authentication Tag, both expressed without URL-safe Base 64 encoding. The "." separator is From 88657bbf1ef2cfdda1ed54d6531cf1b54aa96da7 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 25 Jun 2015 12:00:50 -0700 Subject: [PATCH 74/96] Updating references --- draft-thomson-http-encryption.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index b747d1aa5..3ceb64992 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -49,7 +49,8 @@ informative: RFC5652: RFC7233: RFC7235: - I-D.ietf-httpbis-http2: + RFC7516: + RFC7540: FIPS186: title: "Digital Signature Standard (DSS)" author: @@ -62,7 +63,6 @@ informative: - org: ANSI date: 1998 seriesinfo: ANSI X9.62 - I-D.ietf-jose-json-web-encryption: XMLENC: title: "XML Encryption Syntax and Processing" author: @@ -102,16 +102,15 @@ This document specifies a content-coding (Section 3.1.2 of [RFC7231]) for HTTP to serve these and other use cases. This content-coding is not a direct adaptation of message-based encryption -formats - such as those that are described by [RFC4880], [RFC5652], -[I-D.ietf-jose-json-web-encryption], and [XMLENC] - which are not suited to -stream processing, which is necessary for HTTP. The format described here -cleaves more closely to the lower level constructs described in [RFC5116]. +formats - such as those that are described by [RFC4880], [RFC5652], [RFC7516], +and [XMLENC] - which are not suited to stream processing, which is necessary for +HTTP. The format described here cleaves more closely to the lower level +constructs described in [RFC5116]. To the extent that message-based encryption formats use the same primitives, the format can be considered as sequence of encrypted messages with a particular profile. For instance, {{jwe}} explains how the format is congruent with a -sequence of JSON Web Encryption [I-D.ietf-jose-json-web-encryption] values with -a fixed header. +sequence of JSON Web Encryption [RFC7516] values with a fixed header. This mechanism is likely only a small part of a larger design that uses content encryption. How clients and servers acquire and identify keys will depend on @@ -601,8 +600,8 @@ sensitive information. This risk can be mitigated through the use of the padding that this mechanism provides. Alternatively, splitting up content into segments and storing the -separately might reduce exposure. HTTP/2 [I-D.ietf-httpbis-http2] combined with -TLS [RFC5246] might be used to hide the size of individual messages. +separately might reduce exposure. HTTP/2 [RFC7540] combined with TLS [RFC5246] +might be used to hide the size of individual messages. # IANA Considerations @@ -711,9 +710,9 @@ The initial contents of this registry are: # JWE Mapping {#jwe} The "aesgcm128" content encoding can be considered as a sequence of JSON Web -Encryption (JWE) objects, each corresponding to a single fixed size record. The -following transformations are applied to a JWE object that might be expressed -using the JWE Compact Serialization: +Encryption (JWE) objects [RFC7516], each corresponding to a single fixed size +record. The following transformations are applied to a JWE object that might be +expressed using the JWE Compact Serialization: * The JWE Protected Header is fixed to a value { "alg": "dir", "enc": "A128GCM" }, describing direct encryption using AES-GCM with a 128-bit content From acc21d435b23c8e5c4e6dcc1b8f0750b22429db9 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 1 Jul 2015 16:40:47 -0700 Subject: [PATCH 75/96] Crediting John properly --- draft-thomson-http-encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 3ceb64992..b35804619 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -748,4 +748,4 @@ Authentication Tag. Mark Nottingham was an original author of this document. The following people provided valuable feedback and suggestions: Richard Barnes, -Mike Jones, Stephen Farrell, Eric Rescorla, and Jim Schaad. +Mike Jones, Stephen Farrell, John Mattsson, Eric Rescorla, and Jim Schaad. From 9bd6a72417f6234e34f600015fa8694933613370 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 1 Oct 2015 10:32:51 -0700 Subject: [PATCH 76/96] s/key/aesgcm128/g --- draft-thomson-http-encryption.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index b35804619..5a2c29224 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -326,10 +326,10 @@ keyid: : The "keyid" parameter corresponds to the "keyid" parameter in the Encryption header field. -key: +aesgcm128: -: The "key" parameter contains the URL-safe base64 [RFC4648] octets of the input -keying material. +: The "aesgcm128" parameter contains the URL-safe base64 [RFC4648] octets of the +input keying material. dh: @@ -356,12 +356,13 @@ specifications that use this content-encoding. ## Explicit Key -The "key" parameter is decoded and used as the input keying material if present. -The "key" parameter MUST decode to at least 16 octets in order to be used as -input keying material for "aesgcm128" content encoding. +The "aesgcm128" parameter is decoded and used as the input keying material for +the "aesgcm128" content encoding. The "aesgcm128" parameter MUST decode to at +least 16 octets in order to be used as input keying material for "aesgcm128" +content encoding. -Other key determination parameters can be ignored if the "key" parameter is -present. +Other key determination parameters can be ignored if the "aesgcm128" parameter +is present. ## Diffie-Hellman @@ -457,7 +458,7 @@ HTTP/1.1 200 OK Content-Length: 32 Content-Encoding: aesgcm128 Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" -Encryption-Key: keyid="a1"; key="9Z57YCb3dK95dSsdFJbkag" +Encryption-Key: keyid="a1"; aesgcm128="9Z57YCb3dK95dSsdFJbkag" zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc ~~~ @@ -692,10 +693,10 @@ The initial contents of this registry are: * Purpose: Identify the key that is in use. * Reference: this document -### key +### aesgcm128 -* Parameter Name: key -* Purpose: Provide an explicit input keying material value. +* Parameter Name: aesgcm128 +* Purpose: Provide an explicit input keying material value for the aesgcm128 content encoding. * Reference: this document ### dh From 522d699b34b2b53e4d612cfa1b2e0cd9dd8ad2fa Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 1 Oct 2015 11:18:54 -0700 Subject: [PATCH 77/96] Fixing header definition --- draft-thomson-http-encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 5a2c29224..0f82b9160 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -693,7 +693,7 @@ The initial contents of this registry are: * Purpose: Identify the key that is in use. * Reference: this document -### aesgcm128 +### aesgcm128 {#iana-ekey-aesgcm128} * Parameter Name: aesgcm128 * Purpose: Provide an explicit input keying material value for the aesgcm128 content encoding. From 76f9312c0be7cf64da33b0df84e14e66696ddebd Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 19 Oct 2015 11:44:59 -0700 Subject: [PATCH 78/96] Cleanup --- .gitignore | 10 --- .travis.yml | 12 --- CONTRIBUTING.md | 71 --------------- Makefile | 218 ----------------------------------------------- README.md | 139 ------------------------------ SUBMITTING.md | 24 ------ lib/addstyle.sed | 6 -- lib/style.css | 76 ----------------- 8 files changed, 556 deletions(-) delete mode 100644 .gitignore delete mode 100644 .travis.yml delete mode 100644 CONTRIBUTING.md delete mode 100644 Makefile delete mode 100644 README.md delete mode 100644 SUBMITTING.md delete mode 100644 lib/addstyle.sed delete mode 100644 lib/style.css diff --git a/.gitignore b/.gitignore deleted file mode 100644 index c1f4701a4..000000000 --- a/.gitignore +++ /dev/null @@ -1,10 +0,0 @@ -*.redxml -*.txt -*.html -*.pdf -*~ -*.swp -/*-[0-9][0-9].xml -.refcache -.i-d-template -venv/ diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index dd33830ba..000000000 --- a/.travis.yml +++ /dev/null @@ -1,12 +0,0 @@ -language: python -before_install: -- sudo apt-get update -qq -- sudo apt-get install -y python-lxml python-pip -install: -- deactivate -- gem install kramdown-rfc2629 -- sudo pip install xml2rfc -script: make ghpages -env: - global: - secure: YmX1en3m/xCy9YZXxswpq81RPjPa43+Zvwvb0gFFctl7Hk6LIs+coaS5v1at2/b8K8pg6PiycGkMhVOSNXxIHdcHim/VD69gXoYAsYf8G2kfmDtBj0E8mxFAunoStSVXZ98/U+armDyy2dZCtUCYt+FfsyV9ZYPbbGOhhkpgnOM= diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index afdc617da..000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,71 +0,0 @@ -# Contributing - -Before submitting feedback, please familiarize yourself with our current issues -list and review the [working group home page](|WG-HOMEPAGE|). If you're -new to this, you may also want to read the [Tao of the -IETF](https://www.ietf.org/tao.html). - -Be aware that all contributions to the specification fall under the "NOTE WELL" -terms outlined below. - -1. The best way to provide feedback (editorial or design) and ask questions is -sending an e-mail to [our mailing -list](https://www.ietf.org/mailman/listinfo/|WG-NAME|). This will ensure that -the entire Working Group sees your input in a timely fashion. - -2. If you have **editorial** suggestions (i.e., those that do not change the -meaning of the specification), you can either: - - a) Fork this repository and submit a pull request; this is the lowest - friction way to get editorial changes in. - - b) Submit a new issue to Github, and mention that you believe it is editorial - in the issue body. It is not necessary to notify the mailing list for - editorial issues. - - c) Make comments on individual commits in Github. Note that this feedback is - processed only with best effort by the editors, so it should only be used for - quick editorial suggestions or questions. - -3. For non-editorial (i.e., **design**) issues, you can also create an issue on -Github. However, you **must notify the mailing list** when creating such issues, -providing a link to the issue in the message body. - - Note that **github issues are not for substantial discussions**; the only - appropriate place to discuss design issues is on the mailing list itself. - - -## NOTE WELL - -Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor -for publication as all or part of an IETF Internet-Draft or RFC and any -statement made within the context of an IETF activity is considered an "IETF -Contribution". Such statements include oral statements in IETF sessions, as -well as written and electronic communications made at any time or place, which -are addressed to: - - * The IETF plenary session - * The IESG, or any member thereof on behalf of the IESG - * Any IETF mailing list, including the IETF list itself, any working group - or design team list, or any other list functioning under IETF auspices - * Any IETF working group or portion thereof - * Any Birds of a Feather (BOF) session - * The IAB or any member thereof on behalf of the IAB - * The RFC Editor or the Internet-Drafts function - * All IETF Contributions are subject to the rules of - [RFC 5378](https://tools.ietf.org/html/rfc5378) and - [RFC 3979](https://tools.ietf.org/html/rfc3979) - (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). - -Statements made outside of an IETF session, mailing list or other function, -that are clearly not intended to be input to an IETF activity, group or -function, are not IETF Contributions in the context of this notice. - -Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC -3979](https://tools.ietf.org/html/rfc3979) for details. - -A participant in any IETF activity is deemed to accept all IETF rules of -process, as documented in Best Current Practices RFCs and IESG Statements. - -A participant in any IETF activity acknowledges that written, audio and video -records of meetings may be made and may be available to the public. diff --git a/Makefile b/Makefile deleted file mode 100644 index 53e654177..000000000 --- a/Makefile +++ /dev/null @@ -1,218 +0,0 @@ -# Original makefile from https://github.com/martinthomson/i-d-template - -# The following tools are used by this file. -# All are assumed to be on the path, but you can override these -# in the environment, or command line. - -# Mandatory: -# https://pypi.python.org/pypi/xml2rfc -xml2rfc ?= xml2rfc - -# If you are using markdown files: -# https://github.com/cabo/kramdown-rfc2629 -kramdown-rfc2629 ?= kramdown-rfc2629 - -# If you are using outline files: -# https://github.com/Juniper/libslax/tree/master/doc/oxtradoc -oxtradoc ?= oxtradoc.in - -# For sanity checkout your draft: -# https://tools.ietf.org/tools/idnits/ -idnits ?= idnits - -# For diff: -# https://tools.ietf.org/tools/rfcdiff/ -rfcdiff ?= rfcdiff --browse - -# For generating PDF: -# https://www.gnu.org/software/enscript/ -enscript ?= enscript -# http://www.ghostscript.com/ -ps2pdf ?= ps2pdf - -# Where to get references -XML_RESOURCE_ORG_PREFIX ?= http://unicorn-wg.github.io/idrefs - - -## Work out what to build - -draft := $(basename $(lastword $(sort $(wildcard draft-*.xml)) $(sort $(wildcard draft-*.org)) $(sort $(wildcard draft-*.md)))) - -ifeq (,$(draft)) -$(warning No file named draft-*.md or draft-*.xml or draft-*.org) -$(error Read README.md for setup instructions) -endif - -draft_type := $(suffix $(firstword $(wildcard $(draft).md $(draft).org $(draft).xml))) - -current_ver := $(shell git tag | grep '$(draft)-[0-9][0-9]' | tail -1 | sed -e"s/.*-//") -ifeq (,$(current_ver)) -next_ver ?= 00 -else -next_ver ?= $(shell printf "%.2d" $$((1$(current_ver)-99))) -endif -next := $(draft)-$(next_ver) -diff_ver := $(draft)-$(current_ver) - - -## Targets - -.PHONY: latest txt html pdf submit diff clean update ghpages - -latest: txt html -txt: $(draft).txt -html: $(draft).html -pdf: $(draft).pdf - -submit: $(next).txt - -idnits: $(next).txt - $(idnits) $< - -## If you'd like the main github page to show the draft text. -readme: $(next).txt - @echo '```' > README.md - @cat $(next).txt >> README.md - @echo '```' >> README.md - -clean: - -rm -f $(draft).{txt,html,pdf} index.html - -rm -f $(draft)-[0-9][0-9].{xml,md,org,txt,html,pdf} - -rm -f *.diff.html -ifneq (.xml,$(draft_type)) - -rm -f $(draft).xml -endif - -## diff - -$(next).xml: $(draft).xml - sed -e"s/$(basename $<)-latest/$(basename $@)/" $< > $@ - -ifneq (,$(current_ver)) -.INTERMEDIATE: $(addprefix $(draft)-$(current_ver),.txt $(draft_type)) -diff: $(draft).txt $(draft)-$(current_ver).txt - -$(rfcdiff) $^ - -$(draft)-$(current_ver)$(draft_type): - git show $(draft)-$(current_ver):$(draft)$(draft_type) > $@ -endif - -## Recipes - -.INTERMEDIATE: $(draft).xml -%.xml: %.md - XML_RESOURCE_ORG_PREFIX=$(XML_RESOURCE_ORG_PREFIX) \ - $(kramdown-rfc2629) $< > $@ - -%.xml: %.org - $(oxtradoc) -m outline-to-xml -n "$@" $< > $@ - -%.txt: %.xml - $(xml2rfc) $< -o $@ --text - -%.htmltmp: %.xml - $(xml2rfc) $< -o $@ --html -%.html: %.htmltmp lib/addstyle.sed lib/style.css - sed -f lib/addstyle.sed $< > $@ - -%.pdf: %.txt - $(enscript) --margins 76::76: -B -q -p - $^ | $(ps2pdf) - $@ - -## Update this Makefile - -# The prerequisites here are what is updated -.INTERMEDIATE: .i-d-template.diff -update: Makefile lib .gitignore SUBMITTING.md - git diff --quiet -- $^ || \ - (echo "You have uncommitted changes to:" $^ 1>&2; exit 1) - -if [ -f .i-d-template ]; then \ - git diff --exit-code $$(cat .i-d-template) -- $^ > .i-d-template.diff && \ - rm -f .i-d-template.diff; \ - fi - git remote | grep i-d-template > /dev/null || \ - git remote add i-d-template https://github.com/martinthomson/i-d-template.git - git fetch i-d-template - [ -f .i-d-template ] && [ $$(git rev-parse i-d-template/master) = $$(cat .i-d-template) ] || \ - git checkout i-d-template/master $^ - git diff --quiet -- $^ && rm -f .i-d-template.diff || \ - git commit -m "Update of $^ from i-d-template/$$(git rev-parse i-d-template/master)" $^ - if [ -f .i-d-template.diff ]; then \ - git apply .i-d-template.diff && \ - git commit -m "Restoring local changes to $$(git diff --name-only $^ | paste -s -d ' ' -)" $^; \ - fi - git rev-parse i-d-template/master > .i-d-template - -## Update the gh-pages branch with useful files - -GHPAGES_TMP := /tmp/ghpages$(shell echo $$$$) -.INTERMEDIATE: $(GHPAGES_TMP) -ifeq (,$(TRAVIS_COMMIT)) -GIT_ORIG := $(shell git branch | grep '*' | cut -c 3-) -ifneq (,$(findstring detached from,$(GIT_ORIG))) -GIT_ORIG := $(shell git show -s --format='format:%H') -endif -else -GIT_ORIG := $(TRAVIS_COMMIT) -endif - -# Only run upload if we are local or on the master branch -IS_LOCAL := $(if $(TRAVIS),,true) -ifeq (master,$(TRAVIS_BRANCH)) -IS_MASTER := $(findstring false,$(TRAVIS_PULL_REQUEST)) -else -IS_MASTER := -endif - -index.html: $(draft).html - cp $< $@ - -ghpages: index.html $(draft).txt -ifneq (true,$(TRAVIS)) - @git show-ref refs/heads/gh-pages > /dev/null 2>&1 || \ - ! echo 'Error: No gh-pages branch, run `make setup-ghpages` to initialize it.' -endif -ifneq (,$(or $(IS_LOCAL),$(IS_MASTER))) - mkdir $(GHPAGES_TMP) - cp -f $^ $(GHPAGES_TMP) - git clean -qfdX -ifeq (true,$(TRAVIS)) - git config user.email "ci-bot@example.com" - git config user.name "Travis CI Bot" - git checkout -q --orphan gh-pages - git rm -qr --cached . - git clean -qfd - git pull -qf origin gh-pages --depth=5 -else - git checkout gh-pages - git pull -endif - mv -f $(GHPAGES_TMP)/* $(CURDIR) - git add $^ - if test `git status -s | wc -l` -gt 0; then git commit -m "Script updating gh-pages."; fi -ifneq (,$(GH_TOKEN)) - @echo git push https://github.com/$(TRAVIS_REPO_SLUG).git gh-pages - @git push https://$(GH_TOKEN)@github.com/$(TRAVIS_REPO_SLUG).git gh-pages -endif - -git checkout -qf "$(GIT_ORIG)" - -rm -rf $(GHPAGES_TMP) -endif - -.PHONY: setup-ghpages -setup-ghpages: -# Check if the gh-pages branch already exists locally - @if git show-ref refs/heads/gh-pages >/dev/null 2>&1; then \ - ! echo "Error: gh-pages branch already exists"; \ - else true; fi -# Check if the gh-pages branch already exists on origin - @if git show-ref origin/gh-pages >/dev/null 2>&1; then \ - echo 'Warning: gh-pages already present on the origin'; \ - git branch gh-pages origin/gh-pages; false; \ - else true; fi - @echo "Initializing gh-pages branch" - git checkout --orphan gh-pages - git rm -rf . - touch index.html - git add index.html - git commit -m "Automatic setup of gh-pages." - git push --set-upstream origin gh-pages - git checkout -qf "$(GIT_ORIG)" diff --git a/README.md b/README.md deleted file mode 100644 index 3cb0f6cc2..000000000 --- a/README.md +++ /dev/null @@ -1,139 +0,0 @@ -# HTTP Content Encryption - - -* [Editor's copy](https://martinthomson.github.io/http-encryption/) -* [Formal Draft] (https://tools.ietf.org/html/draft-thomson-http-encryption) (older) - - -## Contributing - -Before submitting feedback, please familiarize yourself with our current issues -list and review the [working group home page](https://httpwg.github.io/). If you're -new to this, you may also want to read the [Tao of the -IETF](https://www.ietf.org/tao.html). - -Be aware that all contributions to the specification fall under the "NOTE WELL" -terms outlined below. - -1. The best way to provide feedback (editorial or design) and ask questions is -sending an e-mail to [our mailing -list](https://lists.w3.org/Archives/Public/ietf-http-wg/). This will ensure that -the entire Working Group sees your input in a timely fashion. - -2. If you have **editorial** suggestions (i.e., those that do not change the -meaning of the specification), you can either: - - a) Fork this repository and submit a pull request; this is the lowest - friction way to get editorial changes in. - - b) Submit a new issue to Github, and mention that you believe it is editorial - in the issue body. It is not necessary to notify the mailing list for - editorial issues. - - c) Make comments on individual commits in Github. Note that this feedback is - processed only with best effort by the editors, so it should only be used for - quick editorial suggestions or questions. - -3. For non-editorial (i.e., **design**) issues, you can also create an issue on -Github. However, you **must notify the mailing list** when creating such issues, -providing a link to the issue in the message body. - - Note that **github issues are not for substantial discussions**; the only - appropriate place to discuss design issues is on the mailing list itself. - - -## Building the Draft - -Formatted text and HTML versions of the draft can be built using `make`. - -```sh -$ make -``` - -This requires that you have the necessary software installed. There are several -other tools that are enabled by make, check the Makefile for details, including -links to the software those tools might require. - - -## Installation and Setup - -Mac users will need to install -[XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see -[this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. -Some of the makefile targets need GNU make 4.0, which Apple doesn't ship yet; -sorry, but if you want those, you can -[download](https://www.gnu.org/software/make/) and build a copy for yourself. - -Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. - -All systems require [xml2rfc](http://xml2rfc.ietf.org/). This requires [Python -2.7](https://www.python.org/). The easiest way to get `xml2rfc` is with `pip`. - -Using a `virtualenv`: - -```sh -$ virtualenv --no-site-packages venv -# remember also to activate the virtualenv before any 'make' run -$ source venv/bin/activate -$ pip install xml2rfc -``` - -To your local user account: - -```sh -$ pip install --user xml2rfc -``` - -Or globally: - -```sh -$ sudo pip install xml2rfc -``` - -xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and -[libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and -`libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, -Fedora). - -If you use markdown, you will also need to install `kramdown-xml2rfc`, which -requires Ruby and can be installed using the roby package manager, `gem`: - -```sh -$ gem install kramdown-xml2rfc -``` - - -## NOTE WELL - -Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor -for publication as all or part of an IETF Internet-Draft or RFC and any -statement made within the context of an IETF activity is considered an "IETF -Contribution". Such statements include oral statements in IETF sessions, as -well as written and electronic communications made at any time or place, which -are addressed to: - - * The IETF plenary session - * The IESG, or any member thereof on behalf of the IESG - * Any IETF mailing list, including the IETF list itself, any working group - or design team list, or any other list functioning under IETF auspices - * Any IETF working group or portion thereof - * Any Birds of a Feather (BOF) session - * The IAB or any member thereof on behalf of the IAB - * The RFC Editor or the Internet-Drafts function - * All IETF Contributions are subject to the rules of - [RFC 5378](https://tools.ietf.org/html/rfc5378) and - [RFC 3979](https://tools.ietf.org/html/rfc3979) - (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). - -Statements made outside of an IETF session, mailing list or other function, -that are clearly not intended to be input to an IETF activity, group or -function, are not IETF Contributions in the context of this notice. - -Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC -3979](https://tools.ietf.org/html/rfc3979) for details. - -A participant in any IETF activity is deemed to accept all IETF rules of -process, as documented in Best Current Practices RFCs and IESG Statements. - -A participant in any IETF activity acknowledges that written, audio and video -records of meetings may be made and may be available to the public. diff --git a/SUBMITTING.md b/SUBMITTING.md deleted file mode 100644 index ab11668c4..000000000 --- a/SUBMITTING.md +++ /dev/null @@ -1,24 +0,0 @@ -# Submitting Drafts - -Occasionally, you will want to submit versions of your draft to the official -IETF repository. The following process makes this easy. - -Make a submission version of your draft. The makefile uses git tags to work out -what version to create. It looks for the last version number you have tagged -the draft with and calculates the next version. When there are no tags, it -generates a `-00` version. - -```sh -$ make submit -``` - -[Submit the .txt and .xml files](https://datatracker.ietf.org/submit/) -that this produces. - -Then you can tag your repository and upload the tags. The tag you should -use is your draft name with the usual number in place of `-latest`. - -```sh -$ git tag draft-ietf-unicorn-protocol-03 -$ git push --tags -``` diff --git a/lib/addstyle.sed b/lib/addstyle.sed deleted file mode 100644 index 4df07896d..000000000 --- a/lib/addstyle.sed +++ /dev/null @@ -1,6 +0,0 @@ -\~~ { a\ - -} diff --git a/lib/style.css b/lib/style.css deleted file mode 100644 index 65fb9d8e7..000000000 --- a/lib/style.css +++ /dev/null @@ -1,76 +0,0 @@ -@viewport { - zoom: 1.0; - width: extend-to-zoom; -} - -@-ms-viewport { - width: extend-to-zoom; - zoom: 1.0; -} - -body { - font: 11pt cambria, helvetica, arial, sans-serif; - font-size-adjust: 0.5; - line-height: 130%; - margin: 1em auto; - max-width: 700px; -} - -.title, .filename, h1, h2, h3, h4 { - font-family: candara, helvetica, arial, sans-serif; - font-size-adjust: 0.5; -} -.title { font-size: 150%; } -h1 { font-size: 130%; } -h2 { font-size: 120%; } -h3, h4 { font-size: 110%; } - -table { - margin-left: 0em; -} -table.header { - width: 100%; -} - -table.header td { - background-color: inherit; - color: black; -} - -samp, tt, code, pre { - font: 11pt consolas, monospace; - font-size-adjust: none; -} - -pre.text, pre.text2 { - width: 90%; -} - -dt { - float: left; clear: left; - margin: 0.5em 0.5em 0 0; -} -dt:first-child { - margin-top: 0; -} -dd { - margin: 0.5em 0 0 2em; -} -dd p, dd ul { - margin-top: 0; margin-bottom: 0; -} -dd *+p { - margin-top: 0.5em; -} - -ol, ul { - padding: 0; - margin: 0.5em 0 0.5em 2em; -} -ul.toc, ul.toc ul { - margin: 0 0 0 1.5em; -} -ul.toc a:first-child { - display: inline-block; - min-width: 1.2em; -} From ebec93424cc8ac5696471a688de99a03a68f6057 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 19 Oct 2015 11:45:26 -0700 Subject: [PATCH 79/96] Setup repository for draft-thomson-http-encryption --- .gitignore | 11 ++++ .gitmodules | 3 + .travis.yml | 13 +++++ CONTRIBUTING.md | 73 ++++++++++++++++++++++++ Makefile | 1 + README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++ circle.yml | 26 +++++++++ lib | 1 + 8 files changed, 271 insertions(+) create mode 100644 .gitignore create mode 100644 .gitmodules create mode 100644 .travis.yml create mode 100644 CONTRIBUTING.md create mode 100644 Makefile create mode 100644 README.md create mode 100644 circle.yml create mode 160000 lib diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..3ea10c6c1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,11 @@ +*.redxml +*.txt +*.html +*.pdf +*~ +*.swp +/*-[0-9][0-9].xml +.refcache +venv/ +issues.json +draft-thomson-http-encryption.xml diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 000000000..b20fa617e --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "lib"] + path = lib + url = https://github.com/martinthomson/i-d-template diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 000000000..0dbd18a44 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,13 @@ +language: python +sudo: false +addons: + apt: + packages: + - python-lxml + - python-pip + +install: + - gem install kramdown-rfc2629 + - pip install xml2rfc + +script: make ghpages diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..6d74bcff1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,73 @@ +# Contributing + +Before submitting feedback, please familiarize yourself with our current issues +list and review the [working group +documents](https://datatracker.ietf.org/wg/http/documents/) and [mailing +list discussion](https://mailarchive.ietf.org/arch/browse/http/). If you're +new to this, you may also want to read the [Tao of the +IETF](https://www.ietf.org/tao.html). + +Be aware that all contributions to the specification fall under the "NOTE WELL" +terms outlined below. + +1. The best way to provide feedback (editorial or design) and ask questions is +sending an e-mail to our mailing list +([info](https://www.ietf.org/mailman/listinfo/http)). This will ensure that +the entire Working Group sees your input in a timely fashion. + +2. If you have **editorial** suggestions (i.e., those that do not change the +meaning of the specification), you can either: + + a) Fork this repository and submit a pull request; this is the lowest + friction way to get editorial changes in. + + b) Submit a new issue to Github, and mention that you believe it is editorial + in the issue body. It is not necessary to notify the mailing list for + editorial issues. + + c) Make comments on individual commits in Github. Note that this feedback is + processed only with best effort by the editors, so it should only be used for + quick editorial suggestions or questions. + +3. For non-editorial (i.e., **design**) issues, you can also create an issue on +Github. However, you **must notify the mailing list** when creating such issues, +providing a link to the issue in the message body. + + Note that **github issues are not for substantial discussions**; the only + appropriate place to discuss design issues is on the mailing list itself. + + +## NOTE WELL + +Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor +for publication as all or part of an IETF Internet-Draft or RFC and any +statement made within the context of an IETF activity is considered an "IETF +Contribution". Such statements include oral statements in IETF sessions, as +well as written and electronic communications made at any time or place, which +are addressed to: + + * The IETF plenary session + * The IESG, or any member thereof on behalf of the IESG + * Any IETF mailing list, including the IETF list itself, any working group + or design team list, or any other list functioning under IETF auspices + * Any IETF working group or portion thereof + * Any Birds of a Feather (BOF) session + * The IAB or any member thereof on behalf of the IAB + * The RFC Editor or the Internet-Drafts function + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) + (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). + +Statements made outside of an IETF session, mailing list or other function, +that are clearly not intended to be input to an IETF activity, group or +function, are not IETF Contributions in the context of this notice. + +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +3979](https://tools.ietf.org/html/rfc3979) for details. + +A participant in any IETF activity is deemed to accept all IETF rules of +process, as documented in Best Current Practices RFCs and IESG Statements. + +A participant in any IETF activity acknowledges that written, audio and video +records of meetings may be made and may be available to the public. diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..591fc9d8f --- /dev/null +++ b/Makefile @@ -0,0 +1 @@ +include lib/main.mk diff --git a/README.md b/README.md new file mode 100644 index 000000000..143d90154 --- /dev/null +++ b/README.md @@ -0,0 +1,143 @@ +# Encrypted Content-Encoding for HTTP + +This is the working area for the Individual internet-draft, "Encrypted Content-Encoding for HTTP". + +* [Editor's copy](https://martinthomson.github.io/http-encryption/) +* [Individual Draft] (https://tools.ietf.org/html/draft-thomson-http-encryption) + + +## Contributing + +Before submitting feedback, please familiarize yourself with our current issues +list and review the [working group +documents](https://datatracker.ietf.org/wg/http/documents/) and [mailing +list discussion](https://mailarchive.ietf.org/arch/browse/http/). If you're +new to this, you may also want to read the [Tao of the +IETF](https://www.ietf.org/tao.html). + +Be aware that all contributions to the specification fall under the "NOTE WELL" +terms outlined below. + +1. The best way to provide feedback (editorial or design) and ask questions is +sending an e-mail to our mailing list +([info](https://www.ietf.org/mailman/listinfo/http)). This will ensure that +the entire Working Group sees your input in a timely fashion. + +2. If you have **editorial** suggestions (i.e., those that do not change the +meaning of the specification), you can either: + + a) Fork this repository and submit a pull request; this is the lowest + friction way to get editorial changes in. + + b) Submit a new issue to Github, and mention that you believe it is editorial + in the issue body. It is not necessary to notify the mailing list for + editorial issues. + + c) Make comments on individual commits in Github. Note that this feedback is + processed only with best effort by the editors, so it should only be used for + quick editorial suggestions or questions. + +3. For non-editorial (i.e., **design**) issues, you can also create an issue on +Github. However, you **must notify the mailing list** when creating such issues, +providing a link to the issue in the message body. + + Note that **github issues are not for substantial discussions**; the only + appropriate place to discuss design issues is on the mailing list itself. + + +## Building the Draft + +Formatted text and HTML versions of the draft can be built using `make`. + +```sh +$ make +``` + +This requires that you have the necessary software installed. There are several +other tools that are enabled by make, check the Makefile for details, including +links to the software those tools might require. + + +## Installation and Setup + +Mac users will need to install +[XCode](https://itunes.apple.com/us/app/xcode/id497799835) to get `make`, see +[this answer](http://stackoverflow.com/a/11494872/1375574) for instructions. + +Windows users will need to use [Cygwin](http://cygwin.org/) to get `make`. + +All systems require [xml2rfc](http://xml2rfc.ietf.org/). This +requires [Python](https://www.python.org/). The easiest way to get +`xml2rfc` is with `pip`. + +Using a `virtualenv`: + +```sh +$ virtualenv --no-site-packages venv +# remember also to activate the virtualenv before any 'make' run +$ source venv/bin/activate +$ pip install xml2rfc +``` + +To your local user account: + +```sh +$ pip install --user xml2rfc +``` + +Or globally: + +```sh +$ sudo pip install xml2rfc +``` + +xml2rfc depends on development versions of [libxml2](http://xmlsoft.org/) and +[libxslt1](http://xmlsoft.org/XSLT). These packages are named `libxml2-dev` and +`libxslt1-dev` (Debian, Ubuntu) or `libxml2-devel` and `libxslt1-devel` (RedHat, +Fedora). + +If you use markdown, you will also need to install `kramdown-rfc2629`, +which requires Ruby and can be installed using the roby package +manager, `gem`: + +```sh +$ gem install kramdown-rfc2629 +``` + +Some other helpful tools are listed in `config.mk`. + + +## NOTE WELL + +Any submission to the [IETF](https://www.ietf.org/) intended by the Contributor +for publication as all or part of an IETF Internet-Draft or RFC and any +statement made within the context of an IETF activity is considered an "IETF +Contribution". Such statements include oral statements in IETF sessions, as +well as written and electronic communications made at any time or place, which +are addressed to: + + * The IETF plenary session + * The IESG, or any member thereof on behalf of the IESG + * Any IETF mailing list, including the IETF list itself, any working group + or design team list, or any other list functioning under IETF auspices + * Any IETF working group or portion thereof + * Any Birds of a Feather (BOF) session + * The IAB or any member thereof on behalf of the IAB + * The RFC Editor or the Internet-Drafts function + * All IETF Contributions are subject to the rules of + [RFC 5378](https://tools.ietf.org/html/rfc5378) and + [RFC 3979](https://tools.ietf.org/html/rfc3979) + (updated by [RFC 4879](https://tools.ietf.org/html/rfc4879)). + +Statements made outside of an IETF session, mailing list or other function, +that are clearly not intended to be input to an IETF activity, group or +function, are not IETF Contributions in the context of this notice. + +Please consult [RFC 5378](https://tools.ietf.org/html/rfc5378) and [RFC +3979](https://tools.ietf.org/html/rfc3979) for details. + +A participant in any IETF activity is deemed to accept all IETF rules of +process, as documented in Best Current Practices RFCs and IESG Statements. + +A participant in any IETF activity acknowledges that written, audio and video +records of meetings may be made and may be available to the public. diff --git a/circle.yml b/circle.yml new file mode 100644 index 000000000..5459be0dd --- /dev/null +++ b/circle.yml @@ -0,0 +1,26 @@ +machine: + python: + version: 2.7.6 + ruby: + version: 2.2.3 + +checkout: + post: + - git submodule sync + - git submodule update --init + - git fetch origin gh-pages --depth 10 + +dependencies: + pre: + - pip install xml2rfc + - gem install kramdown-rfc2629 + +test: + override: + - make + +deployment: + production: + branch: master + commands: + - make ghpages diff --git a/lib b/lib new file mode 160000 index 000000000..a72b8cbd3 --- /dev/null +++ b/lib @@ -0,0 +1 @@ +Subproject commit a72b8cbd3973d56bcdf4421611b6b944b47225fb From 12707ab12298275d0515692893b5ce0edb507077 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 19 Oct 2015 11:47:42 -0700 Subject: [PATCH 80/96] Updating acknowledgments --- draft-thomson-http-encryption.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 0f82b9160..316466e3c 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -748,5 +748,6 @@ Authentication Tag. Mark Nottingham was an original author of this document. -The following people provided valuable feedback and suggestions: Richard Barnes, -Mike Jones, Stephen Farrell, John Mattsson, Eric Rescorla, and Jim Schaad. +The following people provided valuable input: Richard Barnes, David Benjamin, +Peter Beverloo, Mike Jones, Stephen Farrell, Adam Langley, John Mattsson, Eric +Rescorla, and Jim Schaad. From 8f5ccd99c28a37307cf7717562251dd566e50e1a Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 19 Oct 2015 11:55:25 -0700 Subject: [PATCH 81/96] Updating build setup --- lib | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib b/lib index a72b8cbd3..afc9bcf32 160000 --- a/lib +++ b/lib @@ -1 +1 @@ -Subproject commit a72b8cbd3973d56bcdf4421611b6b944b47225fb +Subproject commit afc9bcf328751d87bb89a9474c9c9122781c2188 From ad786a811bf89b62434740f64a757e5d23d24f9d Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 10 Nov 2015 08:03:48 -0800 Subject: [PATCH 82/96] Adding fix for contributory behaviour; renaming Encryption-Key to Crypto-Key; fixing examples --- draft-thomson-http-encryption.md | 128 +++++++++++++++++++------------ 1 file changed, 81 insertions(+), 47 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 316466e3c..b78def223 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -115,8 +115,8 @@ sequence of JSON Web Encryption [RFC7516] values with a fixed header. This mechanism is likely only a small part of a larger design that uses content encryption. How clients and servers acquire and identify keys will depend on the use case. Though a complete key management system is not described, this -document defines an Encryption-Key header field that can be used to convey -keying material. +document defines an Crypto-Key header field that can be used to convey keying +material. ## Notational Conventions @@ -134,9 +134,9 @@ identified as AEAD_AES_128_GCM in [RFC5116], Section 5.1. The AEAD_AES_128_GCM algorithm uses a 128 bit content encryption key. When this content-coding is in use, the Encryption header field ({{encryption}}) -describes how encryption has been applied. The Encryption-Key header field -({{encryption-key}}) can be included to describe how the content encryption key -is derived or retrieved. +describes how encryption has been applied. The Crypto-Key header field +({{crypto-key}}) can be included to describe how the content encryption key is +derived or retrieved. The "aesgcm128" content-coding uses a single fixed set of encryption primitives. Cipher suite agility is achieved by defining a new content-coding @@ -239,8 +239,8 @@ keyid: : The "keyid" parameter contains a string that identifies the keying material that is used. The "keyid" parameter SHOULD be included, unless key identification is guaranteed by other means. The "keyid" parameter MUST be used -if keying material included in an Encryption-Key header field is needed to -derive the content encryption key. +if keying material included in an Crypto-Key header field is needed to derive +the content encryption key. salt: @@ -270,20 +270,26 @@ SHA-256 hash algorithm [FIPS180-2]. The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material identified by the "keyid" parameter is the input keying material (IKM) to HKDF. Input keying material can either be prearranged, or can -be described using the Encryption-Key header field ({{encryption-key}}). The +be described using the Crypto-Key header field ({{crypto-key}}). The first step of HKDF is therefore: ~~~ PRK = HMAC-SHA-256(salt, IKM) ~~~ +The info parameter to HKDF is set to the ASCII-encoded string "Content-Encoding: +aesgcm128", a single zero octet and an optional context string: + +~~~ + cek_info = "Content-Encoding: aesgcm128" || 0x00 || context +~~~ + AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key, so the -length (L) parameter to HKDF is 16. The info parameter is set to the -ASCII-encoded string "Content-Encoding: aesgcm128". The second step of HKDF can +length (L) parameter to HKDF is 16. The second step of HKDF can therefore be simplified to the first 16 octets of a single HMAC: ~~~ - CEK = HMAC-SHA-256(PRK, "Content-Encoding: aesgcm128" || 0x01) + CEK = HMAC-SHA-256(PRK, cek_info || 0x01) ~~~ @@ -294,8 +300,17 @@ for each record is a 12 octet (96 bit) value is produced from the record sequence number and a value derived from the input keying material. The input keying material and salt values are input to HKDF with different info -and length parameters. The info parameter for the nonce is the ASCII-encoded -string "Content-Encoding: nonce" and the length (L) parameter is 12 octets. +and length parameters. + +The length (L) parameter is 12 octets. The info parameter for the nonce is the +ASCII-encoded string "Content-Encoding: nonce", a single zero octet and an +context: + +~~~ + nonce_info = "Content-Encoding: nonce" || 0x00 || context +~~~ + +Unless otherwise specified, the context is a zero length octet sequence. The result is combined with the record sequence number - using exclusive or - to produce the nonce. The record sequence number (SEQ) is a 96-bit unsigned @@ -304,21 +319,21 @@ integer in network byte order that starts at zero. Thus, the final nonce for each record is a 12 octet value: ~~~ - NONCE = HMAC-SHA-256(PRK, "Content-Encoding: nonce" || 0x01) ^ SEQ + NONCE = HMAC-SHA-256(PRK, nonce_info || 0x01) XOR SEQ ~~~ -# Encryption-Key Header Field {#encryption-key} +# Crypto-Key Header Field {#crypto-key} -An Encryption-Key header field can be used to describe the input keying material +An Crypto-Key header field can be used to describe the input keying material used in the Encryption header field. -The Encryption-Key header field uses the extended ABNF syntax defined in Section -1.2 of [RFC7230] and the `parameter` rule from [RFC7231]. +The Crypto-Key header field uses the extended ABNF syntax defined in Section 1.2 +of [RFC7230] and the `parameter` rule from [RFC7231]. ~~~ - Encryption-Key-val = #encryption_key_params - encryption_key_params = [ parameter *( ";" parameter ) ] + Crypto-Key-val = #crypto_key_params + crypto_key_params = [ parameter *( ";" parameter ) ] ~~~ keyid: @@ -337,12 +352,12 @@ dh: the header field can be used to encrypt content for a specific recipient. -The input keying material used by the content-encoding key derivation (see -{{derivation}}) can be determined based on the information in the Encryption-Key -header field. The method for key derivation depends on the parameters that are -present in the header field. +The input keying material used by the key derivation (see {{derivation}}) can be +determined based on the information in the Crypto-Key header field. The method +for key derivation depends on the parameters that are present in the header +field. -The value or values provided in the Encryption-Key header field is valid only +The value or values provided in the Crypto-Key header field is valid only for the current HTTP message unless additional information indicates a greater scope. @@ -379,16 +394,35 @@ following information MUST be established out of band: * The modp group or elliptic curve that will be used. +* A label that uniquely identifies the group. This label will be expressed as a + sequence of octets and MUST NOT include a zero-valued octet. + * The format of the ephemeral public share that is included in the "dh" - parameter. For instance, using ECDH both parties need to agree whether this - is an uncompressed or compressed point. + parameter. This encoding MUST result in a single sequence of octets. For + instance, using ECDH both parties need to agree whether this is an + uncompressed or compressed point. In addition to identifying which content-encoding this input keying material is used for, the "keyid" parameter is used to identify this additional information at the receiver. The intended recipient recovers their private key and are then able to generate -a shared secret using the appropriate Diffie-Hellman process. +a shared secret using the designated Diffie-Hellman process. + +To provide contributory behavior, the context for content encryption key and +nonce derivation (see {{derivation}}) is set to include the derivation mode. +The context is formed from the group label, a single zero octet, the length of +the public key of the recipient, the encoded public key of the recipient, the +length of the public key of the sender, and the public key of the sender: + +~~~ + context = label || 0x00 || + length(recipient_public) || recipient_public || + length(sender_public) || sender_public +~~~ + +The two length fields are encoded as a two octet unsigned integer in network +byte order. Specifications that rely on an Diffie-Hellman exchange for determining input keying material MUST either specify the parameters for Diffie-Hellman (group @@ -457,10 +491,10 @@ encryption uses a 1200 octet record size. HTTP/1.1 200 OK Content-Length: 32 Content-Encoding: aesgcm128 -Encryption: keyid="a1"; salt="ibZx1RNz537h1XNkRcPpjA" -Encryption-Key: keyid="a1"; aesgcm128="9Z57YCb3dK95dSsdFJbkag" +Encryption: keyid="a1"; salt="vr0o6Uq3w_KDWeatc27mUg" +Crypto-Key: keyid="a1"; aesgcm128="csPJEXBYA5U-Tal9EdJi-w" -zK3kpG__Z8whjIkG6RYgPz11oUkTKcxPy9WP-VPMfuc +fuag8ThIRIazSHKUqJ5OduR75UgEUuM76J8UFwadEvg ~~~ This example shows the string "I am the walrus" encrypted using an directly @@ -475,12 +509,12 @@ reasons only. HTTP/1.1 200 OK Content-Length: 32 Content-Encoding: aesgcm128 -Encryption: keyid="dhkey"; salt="5hpuYfxDzG6nSs9-EQuaBg" -Encryption-Key: keyid="dhkey"; - dh="BLsyIPbDn6bquEOwHaju2gj8kUVoflzTtPs_6fGoock_ - dwxi1BcgFtObPVnic4alcEucx8I6G8HmEZCJnAl36Zg" +Encryption: keyid="dhkey"; salt="BXlfKQLkr1Uye5npraPXsw" +Crypto-Key: keyid="dhkey"; + dh="BAAchS17kTRTkYanibzO_L4jrHf91xu5ntQg5mHllLdS + NYoiuOBoQwMSx0eUWjrt3p0fSnoEMlwAe-Kbom_b0q0" -BmuHqRzdD4W1mibxglrPiRHZRSY49Dzdm6jHrWXzZrE +UNkrli1bKtIa_k8gq_z4ASltJFQOarvE76gQ__iImLc ~~~ This example shows the same string, "I am the walrus", encrypted using ECDH over @@ -495,11 +529,11 @@ added for presentation purposes only. ~~~ Receiver: - private key: iCjNf8v4ox_g1rJuSs_gbNmYuUYx76ZRruQs_CHRzDg - public key: BPM1w41cSD4BMeBTY0Fz9ryLM-LeM22Dvt0gaLRukf05 - rMhzFAvxVW_mipg5O0hkWad9ZWW0uMRO2Nrd32v8odQ + private key: c2FFWBracEQR_EiVp8l9zBG-bbZI2qzTbz4dlEvzpCE + public key: BDzMceVKKGnijK94B-j0BnmhvKEwiAyhvmpgo7D-yvMB + RBfuPnLfaaDau47K_isqoQRJJGR33GcENUUjohECyNs Sender: - private key: W0cxgeHDZkR3uMQYAbVgF5swKQUAR7DgoTaaQVlA-Fg + private key: f0vn_1qHZmluyKDzQncncko0Y3UMkqiiRYbV3PuB2P4 public key: ~~~ @@ -628,10 +662,10 @@ Header Registry, as detailed in {{encryption}}. * Reference: this specification * Notes: -This memo registers the "Encryption-Key" HTTP header field in the Permanent -Message Header Registry, as detailed in {{encryption-key}}. +This memo registers the "Crypto-Key" HTTP header field in the Permanent +Message Header Registry, as detailed in {{crypto-key}}. -* Field name: Encryption-Key +* Field name: Crypto-Key * Protocol: HTTP * Status: Standard * Reference: this specification @@ -672,11 +706,11 @@ The initial contents of this registry are: * Reference: this document -## The HTTP Encryption-Key Parameter Registry {#encryption-key-registry} +## The HTTP Crypto-Key Parameter Registry {#crypto-key-registry} -This memo establishes a registry for parameters used by the "Encryption-Key" -header field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. -The "Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an +This memo establishes a registry for parameters used by the "Crypto-Key" header +field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The +"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an "Specification Required" policy [RFC5226]. Entries in this registry are expected to include the following information: From e54def80f2184e7e7bf2db8e00d2b0deb46488f8 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 10 Nov 2015 16:59:47 -0800 Subject: [PATCH 83/96] Updating examples to include new label --- draft-thomson-http-encryption.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index b78def223..9446942fb 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -509,17 +509,18 @@ reasons only. HTTP/1.1 200 OK Content-Length: 32 Content-Encoding: aesgcm128 -Encryption: keyid="dhkey"; salt="BXlfKQLkr1Uye5npraPXsw" +Encryption: keyid="dhkey"; salt="Qg61ZJRva_XBE9IEUelU3A" Crypto-Key: keyid="dhkey"; - dh="BAAchS17kTRTkYanibzO_L4jrHf91xu5ntQg5mHllLdS - NYoiuOBoQwMSx0eUWjrt3p0fSnoEMlwAe-Kbom_b0q0" + dh="BDgpRKok2GZZDmS4r63vbJSUtcQx4Fq1V58-6-3NbZzS + TlZsQiCEDTQy3CZ0ZMsqeqsEb7qW2blQHA4S48fynTk" -UNkrli1bKtIa_k8gq_z4ASltJFQOarvE76gQ__iImLc +G6j_sfKg0qebO62yXpTCayN2KV24QitNiTvLgcFiEj0 ~~~ This example shows the same string, "I am the walrus", encrypted using ECDH over -the P-256 curve [FIPS186]. The content body is shown here encoded in URL-safe -base64 for presentation reasons only. +the P-256 curve [FIPS186], which is identified with the label "P-256" encoded in +ASCII. The content body is shown here encoded in URL-safe base64 for +presentation reasons only. The receiver (in this case, the HTTP client) uses a key pair that is identified by the string "dhkey" and the sender (the server) uses a key pair for which the @@ -529,11 +530,11 @@ added for presentation purposes only. ~~~ Receiver: - private key: c2FFWBracEQR_EiVp8l9zBG-bbZI2qzTbz4dlEvzpCE - public key: BDzMceVKKGnijK94B-j0BnmhvKEwiAyhvmpgo7D-yvMB - RBfuPnLfaaDau47K_isqoQRJJGR33GcENUUjohECyNs + private key: 9FWl15_QUQAWDaD3k3l50ZBZQJ4au27F1V4F0uLSD_M + public key: BCEkBjzL8Z3C-oi2Q7oE5t2Np-p7osjGLg93qUP0wvqR + T21EEWyf0cQDQcakQMqz4hQKYOQ3il2nNZct4HgAUQU Sender: - private key: f0vn_1qHZmluyKDzQncncko0Y3UMkqiiRYbV3PuB2P4 + private key: vG7TmzUX9NfVR4XUGBkLAFu8iDyQe-q_165JkkN0Vlw public key: ~~~ From 1b56bc47eca4e0531bd59ab672137ab920eebde4 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Mon, 16 Nov 2015 13:08:50 -0800 Subject: [PATCH 84/96] Adding note about expanded context --- draft-thomson-http-encryption.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 9446942fb..3cbd58ca0 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -284,6 +284,10 @@ aesgcm128", a single zero octet and an optional context string: cek_info = "Content-Encoding: aesgcm128" || 0x00 || context ~~~ +Unless otherwise specified, the context is a zero length octet sequence. +Specifications that use this content encoding MAY specify the use of an expanded +context to cover additional inputs in the key derivation. + AEAD_AES_128_GCM requires a 16 octet (128 bit) content encryption key, so the length (L) parameter to HKDF is 16. The second step of HKDF can therefore be simplified to the first 16 octets of a single HMAC: @@ -310,7 +314,8 @@ context: nonce_info = "Content-Encoding: nonce" || 0x00 || context ~~~ -Unless otherwise specified, the context is a zero length octet sequence. +The context for nonce derivation SHOULD be the same as is used for content +encryption key derivation. The result is combined with the record sequence number - using exclusive or - to produce the nonce. The record sequence number (SEQ) is a 96-bit unsigned From 7603d682e02b3bf6aee33511a3254a701d40aa7d Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 19 Nov 2015 14:59:34 -0800 Subject: [PATCH 85/96] Fixing ABNF declarations --- draft-thomson-http-encryption.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 3cbd58ca0..d98ea734e 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -211,7 +211,7 @@ The `Encryption` header field uses the extended ABNF syntax defined in Section 1.2 of [RFC7230] and the `parameter` rule from [RFC7231] ~~~ - Encryption-val = #encryption_params + Encryption = #encryption_params encryption_params = [ parameter *( ";" parameter ) ] ~~~ @@ -337,7 +337,7 @@ The Crypto-Key header field uses the extended ABNF syntax defined in Section 1.2 of [RFC7230] and the `parameter` rule from [RFC7231]. ~~~ - Crypto-Key-val = #crypto_key_params + Crypto-Key = #crypto_key_params crypto_key_params = [ parameter *( ";" parameter ) ] ~~~ From 69269ee3a9c08ad4074c8b490e46c757356cc934 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 19 Nov 2015 15:00:24 -0800 Subject: [PATCH 86/96] Adding authentication secret section --- draft-thomson-http-encryption.md | 47 ++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 5 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index d98ea734e..fac2f5e69 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -270,8 +270,8 @@ SHA-256 hash algorithm [FIPS180-2]. The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material identified by the "keyid" parameter is the input keying material (IKM) to HKDF. Input keying material can either be prearranged, or can -be described using the Crypto-Key header field ({{crypto-key}}). The -first step of HKDF is therefore: +be described using the Crypto-Key header field ({{crypto-key}}). The first step +of HKDF is therefore: ~~~ PRK = HMAC-SHA-256(salt, IKM) @@ -414,9 +414,9 @@ at the receiver. The intended recipient recovers their private key and are then able to generate a shared secret using the designated Diffie-Hellman process. -To provide contributory behavior, the context for content encryption key and -nonce derivation (see {{derivation}}) is set to include the derivation mode. -The context is formed from the group label, a single zero octet, the length of +The context for content encryption key and nonce derivation (see {{derivation}}) +is set to include the means by which the keys were derived. The context is +formed from the concatenation of group label, a single zero octet, the length of the public key of the recipient, the encoded public key of the recipient, the length of the public key of the sender, and the public key of the sender: @@ -435,6 +435,43 @@ parameters, or curves and point format) that are used, or describe how those parameters are negotiated between sender and receiver. +## Pre-shared Authentication Secrets {#auth} + +Key derivation MAY be extended to include an additional authentication secret. +Such a secret is shared between the sender and receiver of a message using other +means. + +A pre-shared authentication secret is not explicitly signaled in either the +Encryption or Crypto-Key header fields. Use of this additional step depends on +prior agreement. + +When a shared authentication secret is used, the keying material produced by the +key agreement method (e.g., Diffie-Hellman, explicit key, or otherwise) is +combined with the authentication secret using HKDF. The output of HKDF is the +input keying material used to derive the content encryption key and nonce +{{derivation}}. + +The authentication secret is used as the "salt" parameter to HKDF, the raw +keying material (e.g., Diffie-Hellman output) is used as the "IKM" parameter, +the ASCII-encoded string "Content-Encoding: auth" with a terimal zero octet is +used as the "info" parameter, and the length of the output is 16 octets: + +~~~ + auth_context = "Content-Encoding: auth" || 0x00 + IKM = HKDF(authentication, raw_key, auth_context, 16) +~~~ + +This invocation of HKDF does not take the same additional context that is +provided to the final key derivation stages. + +Note that in the absence of an authentication secret, the input keying material +is simply the raw keying material: + +~~~ + IKM = raw_key +~~~ + + # Examples ## Successful GET Response From da50a1df163165b9acc33a072844dd5fa27d6644 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 19 Nov 2015 15:24:52 -0800 Subject: [PATCH 87/96] Expanding the length of the IKM when derived from an authentication secret --- draft-thomson-http-encryption.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index fac2f5e69..74d3b68f3 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -454,11 +454,12 @@ input keying material used to derive the content encryption key and nonce The authentication secret is used as the "salt" parameter to HKDF, the raw keying material (e.g., Diffie-Hellman output) is used as the "IKM" parameter, the ASCII-encoded string "Content-Encoding: auth" with a terimal zero octet is -used as the "info" parameter, and the length of the output is 16 octets: +used as the "info" parameter, and the length of the output is 32 octets (i.e., +the entire output of the underlying SHA-256 HMAC function): ~~~ auth_context = "Content-Encoding: auth" || 0x00 - IKM = HKDF(authentication, raw_key, auth_context, 16) + IKM = HKDF(authentication, raw_key, auth_context, 32) ~~~ This invocation of HKDF does not take the same additional context that is From 14721d3bd7d0ab9da401f21fda2a9b22127b7b67 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 19 Nov 2015 15:34:40 -0800 Subject: [PATCH 88/96] Additional corrections/clarifications --- draft-thomson-http-encryption.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 74d3b68f3..dece944e2 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -453,17 +453,18 @@ input keying material used to derive the content encryption key and nonce The authentication secret is used as the "salt" parameter to HKDF, the raw keying material (e.g., Diffie-Hellman output) is used as the "IKM" parameter, -the ASCII-encoded string "Content-Encoding: auth" with a terimal zero octet is +the ASCII-encoded string "Content-Encoding: auth" with a terminal zero octet is used as the "info" parameter, and the length of the output is 32 octets (i.e., the entire output of the underlying SHA-256 HMAC function): ~~~ - auth_context = "Content-Encoding: auth" || 0x00 - IKM = HKDF(authentication, raw_key, auth_context, 32) + auth_info = "Content-Encoding: auth" || 0x00 + IKM = HKDF(authentication, raw_key, auth_info, 32) ~~~ -This invocation of HKDF does not take the same additional context that is -provided to the final key derivation stages. +This invocation of HKDF does not take the same context that is provided to the +final key derivation stages. Alternatively, this phase can be viewed as always +having a zero-length context. Note that in the absence of an authentication secret, the input keying material is simply the raw keying material: From a6393240c6d5f81397dc9973d56304efa65600ef Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Thu, 3 Dec 2015 16:12:00 +1100 Subject: [PATCH 89/96] Canonical encoding to octets of context --- draft-thomson-http-encryption.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index dece944e2..3d7e909c9 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -403,9 +403,9 @@ following information MUST be established out of band: sequence of octets and MUST NOT include a zero-valued octet. * The format of the ephemeral public share that is included in the "dh" - parameter. This encoding MUST result in a single sequence of octets. For - instance, using ECDH both parties need to agree whether this is an - uncompressed or compressed point. + parameter. This encoding MUST result in a single, canonical sequence of + octets. For instance, using ECDH both parties need to agree whether this is + an uncompressed or compressed point. In addition to identifying which content-encoding this input keying material is used for, the "keyid" parameter is used to identify this additional information @@ -417,8 +417,10 @@ a shared secret using the designated Diffie-Hellman process. The context for content encryption key and nonce derivation (see {{derivation}}) is set to include the means by which the keys were derived. The context is formed from the concatenation of group label, a single zero octet, the length of -the public key of the recipient, the encoded public key of the recipient, the -length of the public key of the sender, and the public key of the sender: +the public key of the recipient, the public key of the recipient, the length of +the public key of the sender, and the public key of the sender. The public keys +are encoded into octets as defined for the group when determining the context +string. ~~~ context = label || 0x00 || From 916d37d4291d90779b98c52157bd384fc15bdf2f Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 15 Dec 2015 10:17:50 +1100 Subject: [PATCH 90/96] Update template --- draft-thomson-http-encryption.md | 2 +- lib | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 3d7e909c9..b4b7c86a4 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -11,7 +11,7 @@ workgroup: keyword: Internet-Draft stand_alone: yes -pi: [toc, tocindent, sortrefs, symrefs, strict, compact, comments, inline] +pi: [toc, tocindent, sortrefs, symrefs, strict, compact, comments, inline, docmapping] author: - diff --git a/lib b/lib index afc9bcf32..fe8c1f4d2 160000 --- a/lib +++ b/lib @@ -1 +1 @@ -Subproject commit afc9bcf328751d87bb89a9474c9c9122781c2188 +Subproject commit fe8c1f4d216f8181076fd5c129f6701bf1ac59ed From d11c8263ef3a9fa9cec261898b5d462162045099 Mon Sep 17 00:00:00 2001 From: Peter Beverloo Date: Wed, 16 Dec 2015 21:05:28 +0000 Subject: [PATCH 91/96] Disallow duplicated values in the Encryption and Crypto-Key headers --- draft-thomson-http-encryption.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index b4b7c86a4..fa2c188a7 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -220,6 +220,9 @@ content-codings that imply encryption), each application of the content encoding is reflected in the Encryption header field, in the order in which they were applied. +Encryption header field values with multiple instances of the same parameter +name are invalid. + The Encryption header MAY be omitted if the sender does not intend for the immediate recipient to be able to decrypt the payload body. Alternatively, the Encryption header field MAY be omitted if the sender intends for the @@ -356,6 +359,8 @@ dh: : The "dh" parameter contains an ephemeral Diffie-Hellman share. This form of the header field can be used to encrypt content for a specific recipient. +Crypto-Key header field values with multiple instances of the same parameter +name are invalid. The input keying material used by the key derivation (see {{derivation}}) can be determined based on the information in the Crypto-Key header field. The method From f3c04fba8981d07ae3d427157e3bd63f1a86dc6b Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 22 Dec 2015 12:39:55 +1100 Subject: [PATCH 92/96] Update SHA-256 ref --- draft-thomson-http-encryption.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index fa2c188a7..0833d3d30 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -28,12 +28,13 @@ normative: RFC7231: RFC5116: RFC5869: - FIPS180-2: - title: NIST FIPS 180-2, Secure Hash Standard + FIPS180-4: + title: NIST FIPS 180-4, Secure Hash Standard author: name: NIST ins: National Institute of Standards and Technology, U.S. Department of Commerce - date: 2002-08 + date: 2012-03 + target: http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf DH: title: "New Directions in Cryptography" author: From 8201dea1306b4ced0a09ed2018c916cfaa39012c Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 22 Dec 2015 12:41:19 +1100 Subject: [PATCH 93/96] Fixing reference --- draft-thomson-http-encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index 0833d3d30..dabaf12ba 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -269,7 +269,7 @@ In order to allow the reuse of keying material for multiple different HTTP messages, a content encryption key is derived for each message. The content encryption key is derived from the decoded value of the "salt" parameter using the HMAC-based key derivation function (HKDF) described in [RFC5869] using the -SHA-256 hash algorithm [FIPS180-2]. +SHA-256 hash algorithm [FIPS180-4]. The decoded value of the "salt" parameter is the salt input to HKDF function. The keying material identified by the "keyid" parameter is the input keying From 5a872d537fa669e9ff8bbf19e4d7d23410df3ca4 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Tue, 22 Dec 2015 14:09:50 +1100 Subject: [PATCH 94/96] Fixing X9.62 ref --- draft-thomson-http-encryption.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index dabaf12ba..c353efb8c 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -58,7 +58,7 @@ informative: - org: National Institute of Standards and Technology (NIST) date: July 2013 seriesinfo: NIST PUB 186-4 - X.692: + X9.62: title: "Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)" author: - org: ANSI @@ -577,7 +577,7 @@ presentation reasons only. The receiver (in this case, the HTTP client) uses a key pair that is identified by the string "dhkey" and the sender (the server) uses a key pair for which the public share is included in the "dh" parameter above. The keys shown below use -uncompressed points [X.692] encoded using URL-safe base64. Line wrapping is +uncompressed points [X9.62] encoded using URL-safe base64. Line wrapping is added for presentation purposes only. ~~~ From 9de3ced8338d5d3b97c147034f447649ea76ab14 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 23 Dec 2015 16:01:41 +1100 Subject: [PATCH 95/96] Fixing template --- .gitignore | 1 + .gitmodules | 3 --- draft-thomson-http-encryption.md | 4 ++-- lib | 1 - 4 files changed, 3 insertions(+), 6 deletions(-) delete mode 100644 .gitmodules delete mode 160000 lib diff --git a/.gitignore b/.gitignore index 3ea10c6c1..0f6450c40 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ venv/ issues.json draft-thomson-http-encryption.xml +lib diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index b20fa617e..000000000 --- a/.gitmodules +++ /dev/null @@ -1,3 +0,0 @@ -[submodule "lib"] - path = lib - url = https://github.com/martinthomson/i-d-template diff --git a/draft-thomson-http-encryption.md b/draft-thomson-http-encryption.md index c353efb8c..77fa049bf 100644 --- a/draft-thomson-http-encryption.md +++ b/draft-thomson-http-encryption.md @@ -729,8 +729,8 @@ Message Header Registry, as detailed in {{crypto-key}}. This memo establishes a registry for parameters used by the "Encryption" header field under the "Hypertext Transfer Protocol (HTTP) Parameters" grouping. The -"Hypertext Transfer Protocol (HTTP) Encryption Parameters" operates under an -"Specification Required" policy [RFC5226]. +"Hypertext Transfer Protocol (HTTP) Encryption Parameters" registry operates +under an "Specification Required" policy [RFC5226]. Entries in this registry are expected to include the following information: diff --git a/lib b/lib deleted file mode 160000 index fe8c1f4d2..000000000 --- a/lib +++ /dev/null @@ -1 +0,0 @@ -Subproject commit fe8c1f4d216f8181076fd5c129f6701bf1ac59ed From 47d00a621d58437818dbf360ee34d0acc7e65a76 Mon Sep 17 00:00:00 2001 From: Martin Thomson Date: Wed, 23 Dec 2015 16:53:16 +1100 Subject: [PATCH 96/96] Making friendly target right --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 29cdef573..4b776c1d4 100644 --- a/Makefile +++ b/Makefile @@ -54,7 +54,7 @@ key.%: draft-ietf-httpbis-key.% client-hints.%: draft-ietf-httpbis-client-hints.% cp -f $< $@ -crypto.%: draft-ietf-httpbis-encryption-encoding.% +encryption-encoding.%: draft-ietf-httpbis-encryption-encoding.% cp -f $< $@ define makerule_submit_xml =