Merge pull request #821 from matrix-org/rav/unpadded_base64

Specification of unpadded Base64

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

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.

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

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

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