Skip to content

Latest commit

 

History

History
145 lines (105 loc) · 4.46 KB

sep-0028.md

File metadata and controls

145 lines (105 loc) · 4.46 KB

Preamble

SEP: 0028
Title: XDR Base64 Encoding
Author: Leigh McCulloch <@leighmcculloch>
Status: Final
Created: 2019-12-19
Updated: 2019-12-19
Version: 1.0.0

Simple Summary

On the Stellar network, XDR messages such as transaction envelopes, transaction results, and others are often encoded into base64. This is a common best practice that makes the binary messages portable, embeddable in other message formats such as JSON, and is often required by other SEPs.

Base64 encoders are available in the standard libraries of many programming languages and are relatively consistent. Base64 decoders are just as available but are less consistent. Some languages contain base64 decoders that are very strict about aspects such as padding, while others are less strict. As an example, base64 that has had its padding removed will be parseable in JavaScript, Java, and Ruby, but will error in Python and Go. Because of this it is important that when base64-encoding XDR messages that they are consistently encoded according to the specification below, and unaltered. Following the specification below should be low effort because many programming languages' standard libraries support this form of encoding by default, and this specification serves to capture current expectations.

Specification

XDR messages when base64-encoded should follow the specification in RFC4648 Section 4.

The alphabet to use for encoding is the standard alphabet utilizing the A-Z a-z 0-9 + / character set for value encoding, and = for padding.

Special characters in the alphabet should not be substituted for alternative alphabets such as the URL or Filename Safe Alphabet described in the RFC's Section 5.

Padding must always be used, and never removed from the message.

Line feeds should not be added to the base64-encoded data.

Test Cases

Valid Encoding

No Padding

Base64 Encoded Message:

AAAABgABAvD+/wAA

Decoded Message:

00000000  00 00 00 06 00 01 02 f0  fe ff 00 00              |............|
[]byte{0x0, 0x0, 0x0, 0x6, 0x0, 0x1, 0x2, 0xf0, 0xfe, 0xff, 0x0, 0x0}

One Character Padding

Base64 Encoded Message:

AAAABAABAvA=

Decoded Message:

00000000  00 00 00 04 00 01 02 f0                           |........|
[]byte{0x0, 0x0, 0x0, 0x4, 0x0, 0x1, 0x2, 0xf0}

Two Character Padding

Base64 Encoded Message:

AAAACgABAvD+/wAAAAAAAA==

Decoded Message:

00000000  00 00 00 0a 00 01 02 f0  fe ff 00 00 00 00 00 00  |................|
[]byte{0x0, 0x0, 0x0, 0xa, 0x0, 0x1, 0x2, 0xf0, 0xfe, 0xff, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0}

No Line Feeds

Base64 Encoded Message:

AAAASwD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wA=

Decoded Message:

00000000  00 00 00 4b 00 fe ff 00  fe ff 00 fe ff 00 fe ff  |...K............|
00000010  00 fe ff 00 fe ff 00 fe  ff 00 fe ff 00 fe ff 00  |................|
00000020  fe ff 00 fe ff 00 fe ff  00 fe ff 00 fe ff 00 fe  |................|
00000030  ff 00 fe ff 00 fe ff 00  fe ff 00 fe ff 00 fe ff  |................|
00000040  00 fe ff 00 fe ff 00 fe  ff 00 fe ff 00 fe ff 00  |................|
[]byte{0x0, 0x0, 0x0, 0x4b, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0, 0xfe, 0xff, 0x0}

Invalid Encoding

No Padding when Required

AAAACgABAvD+/wAAAAAAAA

Alternate Alphabet (e.g. URL/Filename Safe Alphabet)

AAAACgABAvD-_wAAAAAAAA==

Line Feeds

AAAASwD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wD+
/wD+/wD+/wD+/wD+/wD+/wD+/wD+/wA=

Example Implementations

These examples of base64-encoding XDR messages perform the encoding per the above specification. These are examples, not an exhaustive list of all programming langauges that are known to support the standard.

Go

import "encoding/base64"

base64.StdEncoding.EncodeToString(xdrBytes)

Java

import java.util.Base64;

Base64.getEncoder().encodeToString(xdrBytes)

Python

import base64

base64.b64encode(xdr_bytes)