Data.ByteString.Short.Base64.URL

This module contains ShortByteString-valued combinators for implementing the RFC 4648 specification of the Base64url encoding format. This includes strictly padded/unpadded and lenient decoding variants, as well as internal and external validation for canonicity.

Encoding

encodeBase64 :: ShortByteString -> Base64 'UrlPadded ShortText

Encode a ShortByteString value as a Base64url Text value with padding.

See: RFC-4648 section 5

Examples:

>>> encodeBase64 "<<?>>"
"PDw_Pj4="

encodeBase64' :: ShortByteString -> Base64 'UrlPadded ShortByteString

Encode a ShortByteString as a Base64url ShortByteString value with padding.

See: RFC-4648 section 5

Examples:

>>> encodeBase64' "<<?>>"
"PDw_Pj4="

encodeBase64Unpadded :: ShortByteString -> Base64 'UrlUnpadded ShortText

Encode a ShortByteString value as Base64url Text without padding.

See: RFC-4648 section 3.2

Examples:

>>> encodeBase64Unpadded "<<?>>"
"PDw_Pj4"

encodeBase64Unpadded' :: ShortByteString -> Base64 'UrlUnpadded ShortByteString

Encode a ShortByteString value as Base64url without padding.

See: RFC-4648 section 3.2

Examples:

>>> encodeBase64Unpadded' "<<?>>"
"PDw_Pj4"

Decoding

decodeBase64 :: UrlAlphabet k => Base64 k ShortByteString -> ShortByteString

Decode a Base64url encoded ShortByteString value, either padded or unpadded. The correct decoding function is dispatched based on the existence of padding.

For typed values: - If a padded value is required, use decodeBase64Padded - If an unpadded value is required, use decodeBase64Unpadded

See: RFC-4648 section 4

Examples:

>>> decodeBase64 $ assertBase64 @'UrlPadded "PDw_Pj4="
"<<?>>"

>>> decodeBase64 $ assertBase64 @'UrlUnpadded "PDw_Pj4"
"<<?>>"

decodeBase64Untyped :: ShortByteString -> Either Text ShortByteString

Decode an untyped Base64url encoded ByteString value. If its length is not a multiple of 4, then padding chars will be added to fill out the input to a multiple of 4 for safe decoding as Base64url-encoded values are optionally padded.

For a decoder that fails to decode untyped values of incorrect size: - If a padded value is required, use decodeBase64PaddedUntyped - If an unpadded value is required, use decodeBase64UnpaddedUntyped

See: RFC-4648 section 4

Examples:

>>> decodeBase64Untyped "PDw_Pj4="
Right "<<?>>"

>>> decodeBase64Untyped "PDw_Pj4"
Right "<<?>>"

>>> decodeBase64Untyped "PDw-Pg="
Left "Base64-encoded bytestring has invalid padding"

>>> decodeBase64Untyped "PDw-Pg"
Right "<<>>"

decodeBase64Unpadded :: Base64 'UrlUnpadded ShortByteString -> ShortByteString

Decode an unpadded Base64url-encoded ShortByteString value.

See: RFC-4648 section 4

Examples:

>>> decodeBase64Unpadded $ assertBase64 @'UrlUnpadded "PDw_Pj4"
"<<?>>"

decodeBase64UnpaddedUntyped :: ShortByteString -> Either Text ShortByteString

Decode an unpadded, untyped Base64url encoded ByteString value. If its length is not a multiple of 4, then padding chars will be added to fill out the input to a multiple of 4 for safe decoding as Base64url-encoded values are optionally padded.

In general, unless unpadded Base64url is explicitly required, it is safer to call decodeBase64.

See: RFC-4648 section 4

Examples:

>>> decodeBase64UnpaddedUntyped "PDw_Pj4"
Right "<<?>>"

>>> decodeBase64UnpaddedUntyped "PDw-Pg="
Left "Base64-encoded bytestring has invalid padding"

>>> decodeBase64UnpaddedUntyped "PDw-Pg"
Right "<<>>"

decodeBase64Padded :: Base64 'UrlPadded ShortByteString -> ShortByteString

Decode a padded Base64url-encoded ShortByteString value.

See: RFC-4648 section 4

Examples:

>>> decodeBase64Padded $ assertBase64 @'UrlPadded "PDw_Pj4="
"<<?>>"

decodeBase64PaddedUntyped :: ShortByteString -> Either Text ShortByteString

Decode a padded, untyped Base64url encoded ByteString value.

For a decoder that fails on unpadded input of incorrect size, use decodeBase64UnpaddedUntyped.

See: RFC-4648 section 4

Examples:

>>> decodeBase64PaddedUntyped "PDw_Pj4="
Right "<<?>>"

>>> decodeBase64PaddedUntyped "PDw_Pj4"
Left "Base64-encoded bytestring requires padding"

decodeBase64Lenient :: ShortByteString -> ShortByteString

Leniently decode an unpadded, untyped Base64url-encoded ShortByteString. This function will not generate parse errors. If input data contains padding chars, then the input will be parsed up until the first pad character.

Note: This is not RFC 4648-compliant.

Examples:

>>> decodeBase64Lenient "PDw_Pj4="
"<<?>>"

>>> decodeBase64Lenient "PDw_%%%$}Pj4"
"<<?>>"

Validation

isBase64Url :: ShortByteString -> Bool

Tell whether an untyped ShortByteString is Base64url-encoded.

Examples:

>>> isBase64Url "PDw_Pj4="
True

>>> isBase64Url "PDw_Pj4"
True

>>> isBase64Url "PDw_Pj"
False

isValidBase64Url :: ShortByteString -> Bool

Tell whether an untyped ShortByteString is a valid Base64url format.

This will not tell you whether or not this is a correct Base64url representation, only that it conforms to the correct shape. To check whether it is a true Base64 encoded ShortByteString value, use isBase64Url.

Examples:

>>> isValidBase64Url "PDw_Pj4="
True

>>> isValidBase64Url "PDw_Pj"
True

>>> isValidBase64Url "%"
False