Skip to content

Commit

Permalink
Add Base64Url encoding (#4822)
Browse files Browse the repository at this point in the history
Co-authored-by: Ernesto García <ernestognw@gmail.com>
  • Loading branch information
Amxx and ernestognw authored Jan 16, 2024
1 parent 281ab15 commit 692dbc5
Show file tree
Hide file tree
Showing 6 changed files with 133 additions and 22 deletions.
5 changes: 5 additions & 0 deletions .changeset/twenty-feet-grin.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'openzeppelin-solidity': minor
---

`Base64`: Add `encodeURL` following section 5 of RFC4648 for URL encoding
3 changes: 2 additions & 1 deletion .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,7 +83,8 @@ jobs:
- name: Set up environment
uses: ./.github/actions/setup
- name: Run tests
run: forge test -vv
# Base64Test requires `--ffi`. See test/utils/Base64.t.sol
run: forge test -vv --no-match-contract Base64Test

coverage:
runs-on: ubuntu-latest
Expand Down
53 changes: 37 additions & 16 deletions contracts/utils/Base64.sol
Original file line number Diff line number Diff line change
Expand Up @@ -9,29 +9,48 @@ pragma solidity ^0.8.20;
library Base64 {
/**
* @dev Base64 Encoding/Decoding Table
* See sections 4 and 5 of https://datatracker.ietf.org/doc/html/rfc4648
*/
string internal constant _TABLE = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
string internal constant _TABLE_URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";

/**
* @dev Converts a `bytes` to its Bytes64 `string` representation.
*/
function encode(bytes memory data) internal pure returns (string memory) {
return _encode(data, _TABLE, true);
}

/**
* @dev Converts a `bytes` to its Bytes64Url `string` representation.
*/
function encodeURL(bytes memory data) internal pure returns (string memory) {
return _encode(data, _TABLE_URL, false);
}

/**
* @dev Internal table-agnostic conversion
*/
function _encode(bytes memory data, string memory table, bool withPadding) private pure returns (string memory) {
/**
* Inspired by Brecht Devos (Brechtpd) implementation - MIT licence
* https://github.com/Brechtpd/base64/blob/e78d9fd951e7b0977ddca77d92dc85183770daf4/base64.sol
*/
if (data.length == 0) return "";

// Loads the table into memory
string memory table = _TABLE;

// Encoding takes 3 bytes chunks of binary data from `bytes` data parameter
// and split into 4 numbers of 6 bits.
// The final Base64 length should be `bytes` data length multiplied by 4/3 rounded up
// If padding is enabled, the final length should be `bytes` data length divided by 3 rounded up and then
// multiplied by 4 so that it leaves room for padding the last chunk
// - `data.length + 2` -> Round up
// - `/ 3` -> Number of 3-bytes chunks
// - `4 *` -> 4 characters for each chunk
string memory result = new string(4 * ((data.length + 2) / 3));
// If padding is disabled, the final length should be `bytes` data length multiplied by 4/3 rounded up as
// opposed to when padding is required to fill the last chunk.
// - `4 *` -> 4 characters for each chunk
// - `data.length + 2` -> Round up
// - `/ 3` -> Number of 3-bytes chunks
uint256 resultLength = withPadding ? 4 * ((data.length + 2) / 3) : (4 * data.length + 2) / 3;

string memory result = new string(resultLength);

/// @solidity memory-safe-assembly
assembly {
Expand Down Expand Up @@ -73,15 +92,17 @@ library Base64 {
resultPtr := add(resultPtr, 1) // Advance
}

// When data `bytes` is not exactly 3 bytes long
// it is padded with `=` characters at the end
switch mod(mload(data), 3)
case 1 {
mstore8(sub(resultPtr, 1), 0x3d)
mstore8(sub(resultPtr, 2), 0x3d)
}
case 2 {
mstore8(sub(resultPtr, 1), 0x3d)
if withPadding {
// When data `bytes` is not exactly 3 bytes long
// it is padded with `=` characters at the end
switch mod(mload(data), 3)
case 1 {
mstore8(sub(resultPtr, 1), 0x3d)
mstore8(sub(resultPtr, 2), 0x3d)
}
case 2 {
mstore8(sub(resultPtr, 1), 0x3d)
}
}
}

Expand Down
31 changes: 31 additions & 0 deletions scripts/tests/base64.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
#!/usr/bin/env bash

set -euo pipefail

_encode() {
# - Print the input to stdout
# - Remove the first two characters
# - Convert from hex to binary
# - Convert from binary to base64
# - Remove newlines from `base64` output
echo -n "$1" | cut -c 3- | xxd -r -p | base64 | tr -d \\n
}

encode() {
# - Convert from base64 to hex
# - Remove newlines from `xxd` output
_encode "$1" | xxd -p | tr -d \\n
}

encodeURL() {
# - Remove padding from `base64` output
# - Replace `+` with `-`
# - Replace `/` with `_`
# - Convert from base64 to hex
# - Remove newlines from `xxd` output
_encode "$1" | sed 's/=//g' | sed 's/+/-/g' | sed 's/\//_/g' | xxd -p | tr -d \\n
}

# $1: function name
# $2: input
$1 $2
32 changes: 32 additions & 0 deletions test/utils/Base64.t.sol
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// SPDX-License-Identifier: MIT

pragma solidity ^0.8.20;

import {Test} from "forge-std/Test.sol";

import {Base64} from "@openzeppelin/contracts/utils/Base64.sol";

/// NOTE: This test requires `ffi` to be enabled. It does not run in the CI
/// environment given `ffi` is not recommended.
/// See: https://github.com/foundry-rs/foundry/issues/6744
contract Base64Test is Test {
function testEncode(bytes memory input) external {
string memory output = Base64.encode(input);
assertEq(output, _base64Ffi(input, "encode"));
}

function testEncodeURL(bytes memory input) external {
string memory output = Base64.encodeURL(input);
assertEq(output, _base64Ffi(input, "encodeURL"));
}

function _base64Ffi(bytes memory input, string memory fn) internal returns (string memory) {
string[] memory command = new string[](4);
command[0] = "bash";
command[1] = "scripts/tests/base64.sh";
command[2] = fn;
command[3] = vm.toString(input);
bytes memory retData = vm.ffi(command);
return string(retData);
}
}
31 changes: 26 additions & 5 deletions test/utils/Base64.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,10 @@ const { ethers } = require('hardhat');
const { expect } = require('chai');
const { loadFixture } = require('@nomicfoundation/hardhat-network-helpers');

// Replace "+/" with "-_" in the char table, and remove the padding
// see https://datatracker.ietf.org/doc/html/rfc4648#section-5
const base64toBase64Url = str => str.replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');

async function fixture() {
const mock = await ethers.deployContract('$Base64');
return { mock };
Expand All @@ -12,18 +16,35 @@ describe('Strings', function () {
Object.assign(this, await loadFixture(fixture));
});

describe('from bytes - base64', function () {
describe('base64', function () {
for (const { title, input, expected } of [
{ title: 'converts to base64 encoded string with double padding', input: 'test', expected: 'dGVzdA==' },
{ title: 'converts to base64 encoded string with single padding', input: 'test1', expected: 'dGVzdDE=' },
{ title: 'converts to base64 encoded string without padding', input: 'test12', expected: 'dGVzdDEy' },
{ title: 'empty bytes', input: '0x', expected: '' },
{ title: 'converts to base64 encoded string (/ case)', input: 'où', expected: 'b/k=' },
{ title: 'converts to base64 encoded string (+ case)', input: 'zs~1t8', expected: 'enN+MXQ4' },
{ title: 'empty bytes', input: '', expected: '' },
])
it(title, async function () {
const raw = ethers.isBytesLike(input) ? input : ethers.toUtf8Bytes(input);
const buffer = Buffer.from(input, 'ascii');
expect(await this.mock.$encode(buffer)).to.equal(ethers.encodeBase64(buffer));
expect(await this.mock.$encode(buffer)).to.equal(expected);
});
});

expect(await this.mock.$encode(raw)).to.equal(ethers.encodeBase64(raw));
expect(await this.mock.$encode(raw)).to.equal(expected);
describe('base64url', function () {
for (const { title, input, expected } of [
{ title: 'converts to base64url encoded string with double padding', input: 'test', expected: 'dGVzdA' },
{ title: 'converts to base64url encoded string with single padding', input: 'test1', expected: 'dGVzdDE' },
{ title: 'converts to base64url encoded string without padding', input: 'test12', expected: 'dGVzdDEy' },
{ title: 'converts to base64url encoded string (_ case)', input: 'où', expected: 'b_k' },
{ title: 'converts to base64url encoded string (- case)', input: 'zs~1t8', expected: 'enN-MXQ4' },
{ title: 'empty bytes', input: '', expected: '' },
])
it(title, async function () {
const buffer = Buffer.from(input, 'ascii');
expect(await this.mock.$encodeURL(buffer)).to.equal(base64toBase64Url(ethers.encodeBase64(buffer)));
expect(await this.mock.$encodeURL(buffer)).to.equal(expected);
});
});
});

0 comments on commit 692dbc5

Please sign in to comment.