Skip to contentSkip to conversation

fscrypt: align Base64 encoding with RFC 4648 base64url

PATCH Applied Eric Biggers 3 participants 5 messages Jul 18, 2021 – Jul 26, 2021

Subsystems (3)
lore
Share & tools
lore

Eric Biggers

author maintainer
#0 lore raw

PATCH 1/1 fscrypt: align Base64 encoding with RFC 4648 base64url

From: Eric Biggers <[email protected]>

fscrypt uses a Base64 encoding to encode no-key filenames (the filenames that are presented to userspace when a directory is listed without its encryption key). There are many variants of Base64, but the most common ones are specified by RFC 4648. fscrypt can't use the regular RFC 4648 "base64" variant because "base64" uses the '/' character, which isn't allowed in filenames. However, RFC 4648 also specifies a "base64url" variant for use in URLs and filenames. "base64url" is less common than "base64", but it's still implemented in many programming libraries.

Unfortunately, what fscrypt actually uses is a custom Base64 variant that differs from "base64url" in several ways:

- The binary data is divided into 6-bit chunks differently.

- Values 62 and 63 are encoded with '+' and ',' instead of '-' and '_'.

- '='-padding isn't used. This isn't a problem per se, as the padding isn't technically necessary, and RFC 4648 doesn't strictly require it. But it needs to be properly documented.

There have been two attempts to copy the fscrypt Base64 code into lib/
(https://lkml.kernel.org/r/[email protected] and
https://lkml.kernel.org/r/[email protected]), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late.

Therefore, switch the fscrypt Base64 variant to base64url, in order to align more closely with RFC 4648 and other implementations and uses of Base64. However, I opted not to implement '='-padding, as '='-padding adds complexity, is unnecessary, and isn't required by the RFC.

---
 Documentation/filesystems/fscrypt.rst |  10 +--
 fs/crypto/fname.c                     | 106 ++++++++++++++++----------
 2 files changed, 70 insertions(+), 46 deletions(-)
Documentation/filesystems/fscrypt.rst +5 -5
index 44b67ebd6e40..968938b1a9ff 100644
@@ -1235,12 +1235,12 @@ the user-supplied name to get the ciphertext.
 
 Lookups without the key are more complicated.  The raw ciphertext may
 contain the ``\0`` and ``/`` characters, which are illegal in
-filenames.  Therefore, readdir() must base64-encode the ciphertext for
-presentation.  For most filenames, this works fine; on ->lookup(), the
-filesystem just base64-decodes the user-supplied name to get back to
-the raw ciphertext.
+filenames.  Therefore, readdir() must base64url-encode the ciphertext
+for presentation.  For most filenames, this works fine; on ->lookup(),
+the filesystem just base64url-decodes the user-supplied name to get
+back to the raw ciphertext.
 
-However, for very long filenames, base64 encoding would cause the
+However, for very long filenames, base64url encoding would cause the
 filename length to exceed NAME_MAX.  To prevent this, readdir()
 actually presents long filenames in an abbreviated form which encodes
 a strong "hash" of the ciphertext filename, along with the optional
fs/crypto/fname.c +65 -41

194 lines not on this page · raw message

base-commit: e73f0f0ee7541171d89f2e2491130c7771ba58d3

Signature · 1 line
2.32.0
Reviewed-by on v1 1/1
#1 lore raw
Quoted 36 lines · Eric Biggers

From: Eric Biggers <[email protected]>

fscrypt uses a Base64 encoding to encode no-key filenames (the filenames that are presented to userspace when a directory is listed without its encryption key). There are many variants of Base64, but the most common ones are specified by RFC 4648. fscrypt can't use the regular RFC 4648 "base64" variant because "base64" uses the '/' character, which isn't allowed in filenames. However, RFC 4648 also specifies a "base64url" variant for use in URLs and filenames. "base64url" is less common than "base64", but it's still implemented in many programming libraries.

Unfortunately, what fscrypt actually uses is a custom Base64 variant that differs from "base64url" in several ways:

- The binary data is divided into 6-bit chunks differently.

- Values 62 and 63 are encoded with '+' and ',' instead of '-' and '_'.

- '='-padding isn't used. This isn't a problem per se, as the padding isn't technically necessary, and RFC 4648 doesn't strictly require it. But it needs to be properly documented.

There have been two attempts to copy the fscrypt Base64 code into lib/
(https://lkml.kernel.org/r/[email protected] and
https://lkml.kernel.org/r/[email protected]), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late.

Therefore, switch the fscrypt Base64 variant to base64url, in order to align more closely with RFC 4648 and other implementations and uses of Base64. However, I opted not to implement '='-padding, as '='-padding adds complexity, is unnecessary, and isn't required by the RFC.

Quoted 6 lines
---
 Documentation/filesystems/fscrypt.rst |  10 +--
 fs/crypto/fname.c                     | 106 ++++++++++++++++----------
 2 files changed, 70 insertions(+), 46 deletions(-)

Thanks for doing it. I got confused by it myself, and having it named 'base64encode' while not _actually_ being base64 didn't help, either.

Cheers,

Hannes

Signature · 4 lines
Dr. Hannes Reinecke		           Kernel Storage Architect
[email protected]			                  +49 911 74053 688
SUSE Software Solutions Germany GmbH, Maxfeldstr. 5, 90409 Nürnberg
HRB 36809 (AG Nürnberg), GF: Felix Imendörffer
author maintainer
#2 lore raw
In reply to Eric Biggers
Quoted 9 lines · Eric Biggers

There have been two attempts to copy the fscrypt Base64 code into lib/
(https://lkml.kernel.org/r/[email protected] and
https://lkml.kernel.org/r/[email protected]), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late.

Jeff, any thoughts on whether this is the variant of Base64 you want to use in the CephFS fscrypt support?

- Eric

#3 lore raw
Quoted 11 lines · Eric Biggers
Quoted 9 lines · Eric Biggers

There have been two attempts to copy the fscrypt Base64 code into lib/
(https://lkml.kernel.org/r/[email protected] and
https://lkml.kernel.org/r/[email protected]), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late.

Quoted 3 lines

Jeff, any thoughts on whether this is the variant of Base64 you want to use in the CephFS fscrypt support?

I can't do a deep review today, but this looks fine at first glance.

We're not too particular about what sort of encoding we use for ceph. We just need something that is consistent and results in valid POSIX filenames. Changing it to better adhere to the standard sounds like a good thing to do.

Thanks,

Signature · 1 line
Jeff Layton <[email protected]>
author maintainer Applied
#4 lore raw
In reply to Eric Biggers
Quoted 36 lines · Eric Biggers

From: Eric Biggers <[email protected]>

fscrypt uses a Base64 encoding to encode no-key filenames (the filenames that are presented to userspace when a directory is listed without its encryption key). There are many variants of Base64, but the most common ones are specified by RFC 4648. fscrypt can't use the regular RFC 4648 "base64" variant because "base64" uses the '/' character, which isn't allowed in filenames. However, RFC 4648 also specifies a "base64url" variant for use in URLs and filenames. "base64url" is less common than "base64", but it's still implemented in many programming libraries.

Unfortunately, what fscrypt actually uses is a custom Base64 variant that differs from "base64url" in several ways:

- The binary data is divided into 6-bit chunks differently.

- Values 62 and 63 are encoded with '+' and ',' instead of '-' and '_'.

- '='-padding isn't used. This isn't a problem per se, as the padding isn't technically necessary, and RFC 4648 doesn't strictly require it. But it needs to be properly documented.

There have been two attempts to copy the fscrypt Base64 code into lib/
(https://lkml.kernel.org/r/[email protected] and
https://lkml.kernel.org/r/[email protected]), and both have been caught up by the fscrypt Base64 variant being nonstandard and not properly documented. Also, the planned use of the fscrypt Base64 code in the CephFS storage back-end will prevent it from being changed later (whereas currently it can still be changed), so we need to choose an encoding that we're happy with before it's too late.

Therefore, switch the fscrypt Base64 variant to base64url, in order to align more closely with RFC 4648 and other implementations and uses of Base64. However, I opted not to implement '='-padding, as '='-padding adds complexity, is unnecessary, and isn't required by the RFC.

Quoted 5 lines
---
 Documentation/filesystems/fscrypt.rst |  10 +--
 fs/crypto/fname.c                     | 106 ++++++++++++++++----------
 2 files changed, 70 insertions(+), 46 deletions(-)

Applied to fscrypt.git#master for 5.15.

- Eric