From da686ba4ebe0798d1cbaf29adb022b4bc2adf96c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 1 Mar 2017 08:50:07 +0000 Subject: [PATCH] Specification of unpadded Base64 --- specification/appendices/base64.rst | 57 +++++++++++++++++++++++ specification/appendices/signing_json.rst | 4 +- specification/identity_service_api.rst | 4 +- specification/server_server_api.rst | 5 +- specification/targets.yaml | 1 + 5 files changed, 66 insertions(+), 5 deletions(-) create mode 100644 specification/appendices/base64.rst diff --git a/specification/appendices/base64.rst b/specification/appendices/base64.rst new file mode 100644 index 00000000..d046e0fc --- /dev/null +++ b/specification/appendices/base64.rst @@ -0,0 +1,57 @@ +.. Copyright 2017 Vector Creations Limited +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +Unpadded Base64 +--------------- + +*Unpadded* Base64 refers to 'standard' Base64 encoding as defined in `RFC +4648`_, without "=" padding. Specifically, where RFC 4648 requires that encoded +data be padded to a multiple of four characters using ``=`` characters, +unpadded Base64 omits this padding. + +For reference, RFC 4648 uses the following alphabet for Base 64:: + + Value Encoding Value Encoding Value Encoding Value Encoding + 0 A 17 R 34 i 51 z + 1 B 18 S 35 j 52 0 + 2 C 19 T 36 k 53 1 + 3 D 20 U 37 l 54 2 + 4 E 21 V 38 m 55 3 + 5 F 22 W 39 n 56 4 + 6 G 23 X 40 o 57 5 + 7 H 24 Y 41 p 58 6 + 8 I 25 Z 42 q 59 7 + 9 J 26 a 43 r 60 8 + 10 K 27 b 44 s 61 9 + 11 L 28 c 45 t 62 + + 12 M 29 d 46 u 63 / + 13 N 30 e 47 v + 14 O 31 f 48 w + 15 P 32 g 49 x + 16 Q 33 h 50 y + +Examples of strings encoded using unpadded Base64:: + + UNPADDED_BASE64("") = "" + UNPADDED_BASE64("f") = "Zg" + UNPADDED_BASE64("fo") = "Zm8" + UNPADDED_BASE64("foo") = "Zm9v" + UNPADDED_BASE64("foob") = "Zm9vYg" + UNPADDED_BASE64("fooba") = "Zm9vYmE" + UNPADDED_BASE64("foobar") = "Zm9vYmFy" + +When decoding Base64, implementations SHOULD accept input with or without +padding characters whereever possible, to ensure maximum interoperability. + +.. _`RFC 4648`: https://tools.ietf.org/html/rfc4648 diff --git a/specification/appendices/signing_json.rst b/specification/appendices/signing_json.rst index 5536af5e..bc76c89a 100644 --- a/specification/appendices/signing_json.rst +++ b/specification/appendices/signing_json.rst @@ -91,8 +91,8 @@ Signing Details JSON is signed by encoding the JSON object without ``signatures`` or keys grouped as ``unsigned``, using the canonical encoding described above. The JSON bytes are then signed using the -signature algorithm and the signature is encoded using base64 with the padding -stripped. The resulting base64 signature is added to an object under the +signature algorithm and the signature is encoded using `unpadded Base64`._ +The resulting base64 signature is added to an object under the *signing key identifier* which is added to the ``signatures`` object under the name of the entity signing it which is added back to the original JSON object along with the ``unsigned`` object. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 3be9d9eb..36f4c3d4 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -267,7 +267,7 @@ This is less secure than the client doing it itself, but may be useful where thi The identity service will happily sign invitation details with a request-specified ed25519 private key for you, if you want it to. It takes URL-encoded POST parameters: - mxid (string, required) - token (string, required) -- private_key (string, required): The unpadded base64-encoded private key. +- private_key (string, required): The private key, encoded as `Unpadded base64`_. It will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. It will then respond with JSON which looks something like:: @@ -281,3 +281,5 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe }, "token": "abc123" } + +.. _`Unpadded Base64`: ../appendices.html#unpadded-base64 diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index 1f283722..cb76c3d5 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -165,7 +165,7 @@ events sent by that server can still be checked. ``signatures`` Object Digital signatures for this object signed using the ``verify_keys``. ``tls_fingerprints`` Array of Objects Hashes of X.509 TLS certificates used - by this this server encoded as base64. + by this this server encoded as `Unpadded Base64`_. ``valid_until_ts`` Integer POSIX timestamp when the list of valid keys should be refreshed. ==================== =================== ====================================== @@ -271,7 +271,7 @@ at ``/_matrix/key/v1``. ``signatures`` Object Digital signatures for this object signed using the ``verify_keys``. ``tls_certificate`` String The X.509 TLS certificate used by this - this server encoded as base64. + this server encoded as `Unpadded Base64`_. ==================== =================== ====================================== .. code:: json @@ -1144,3 +1144,4 @@ that are too long. known hash functions like SHA-256 when none of the keys have been redacted]] .. _`Canonical JSON`: ../appendices.html#canonical-json +.. _`Unpadded Base64`: ../appendices.html#unpadded-base64 diff --git a/specification/targets.yaml b/specification/targets.yaml index 7d415fb4..0d64815b 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -32,6 +32,7 @@ targets: appendices: files: - appendices.rst + - appendices/base64.rst - appendices/signing_json.rst - appendices/threat_model.rst - appendices/test_vectors.rst