Data.Text.Encoding.Base64.URL

base64-1.0: A modern Base64 library

Copyright | (c) 2019-2023 Emily Pillmore
License | BSD-style
Maintainer | Emily Pillmore <emilypi@cohomolo.gy>
Stability | stable
Portability | non-portable
Safe Haskell | None
Language | Haskell2010

Data.Text.Encoding.Base64.URL

Contents

- Encoding
- Decoding
- Validation

Description

This module contains `Text`-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.

Synopsis

- encodeBase64 :: Text -> Base64 'UrlPadded Text
- encodeBase64Unpadded :: Text -> Base64 'UrlUnpadded Text
- decodeBase64 :: forall (k :: Alphabet). UrlAlphabet k => Base64 k Text -> Text
- decodeBase64Untyped :: Text -> Either Text Text
- decodeBase64UntypedWith :: (ByteString -> Either err Text) -> ByteString -> Either (Base64Error err) Text
- decodeBase64Unpadded :: Base64 'UrlUnpadded Text -> Text
- decodeBase64UnpaddedUntyped :: Text -> Either Text Text
- decodeBase64UnpaddedUntypedWith :: (ByteString -> Either err Text) -> ByteString -> Either (Base64Error err) Text
- decodeBase64Padded :: Base64 'UrlPadded Text -> Text
- decodeBase64PaddedUntyped :: Text -> Either Text Text
- decodeBase64PaddedUntypedWith :: (ByteString -> Either err Text) -> ByteString -> Either (Base64Error err) Text
- decodeBase64Lenient :: Text -> Text
- isBase64Url :: Text -> Bool
- isValidBase64Url :: Text -> Bool

# Encoding

encodeBase64 :: Text -> Base64 'UrlPadded Text #

Encode a `Text` value in Base64url with padding.

See: RFC-4648 section 5

### Examples:

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

encodeBase64Unpadded :: Text -> Base64 'UrlUnpadded Text #

Encode a `Text` value in Base64url without padding.

See: RFC-4648 section 3.2

### Examples:

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

# Decoding

decodeBase64 :: forall (k :: Alphabet). UrlAlphabet k => Base64 k Text -> Text #

Decode a Base64url encoded `Text` 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 :: Text -> Either Text Text #

Decode an untyped Base64url encoded `Text` 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 "<<>>"

decodeBase64UntypedWith #

Arguments

:: (ByteString -> Either err Text) | convert a bytestring to text (e.g. `decodeUtf8'`)
-> ByteString | Input text to decode
-> Either (Base64Error err) Text |

Attempt to decode an untyped `ByteString` value as Base64url, converting from `ByteString` to `Text` according to some encoding function. In practice, This is something like `decodeUtf8'`, which may produce an error.

See: RFC-4648 section 4

### Examples:

    decodeBase64UntypedWith decodeUtf8'
      :: Text -> Either (Base64Error UnicodeException) Text

decodeBase64Unpadded :: Base64 'UrlUnpadded Text -> Text #

Decode an unpadded Base64url encoded `Text` value.

See: RFC-4648 section 4

### Examples:

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

decodeBase64UnpaddedUntyped :: Text -> Either Text Text #

Decode a unpadded, untyped Base64url-encoded `Text` 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 encodings are optionally padded.

For a decoder that fails on unpadded input, use `decodeBase64PaddedUntyped`

See: RFC-4648 section 4

### Examples:

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

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

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

decodeBase64UnpaddedUntypedWith #

Arguments

:: (ByteString -> Either err Text) | convert a bytestring to text (e.g. `decodeUtf8'`)
-> ByteString | Input text to decode
-> Either (Base64Error err) Text |

Attempt to decode an untyped, unpadded `ByteString` value as Base64url, converting from `ByteString` to `Text` according to some encoding function. In practice, This is something like `decodeUtf8'`, which may produce an error.

See: RFC-4648 section 4

### Example:

    decodeBase64UnpaddedUntypedWith decodeUtf8'
      :: ByteString -> Either (Base64Error UnicodeException) Text

decodeBase64Padded :: Base64 'UrlPadded Text -> Text #

Decode a padded Base64url encoded `Text` value

See: RFC-4648 section 4

### Examples:

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

decodeBase64PaddedUntyped :: Text -> Either Text Text #

Decode an untyped, padded Base64url encoded `Text` value

For a decoder that fails on padded input, use `decodeBase64UnpaddedUntyped`

See: RFC-4648 section 4

### Examples:

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

decodeBase64PaddedUntypedWith #

Arguments

:: (ByteString -> Either err Text) | convert a bytestring to text (e.g. `decodeUtf8'`)
-> ByteString | Input text to decode
-> Either (Base64Error err) Text |

Attempt to decode a padded, untyped `ByteString` value as Base64url, converting from `ByteString` to `Text` according to some encoding function. In practice, This is something like `decodeUtf8'`, which may produce an error.

See: RFC-4648 section 4

### Example:

    decodeBase64PaddedWith decodeUtf8'
      :: ByteString -> Either (Base64Error UnicodeException) Text

decodeBase64Lenient :: Text -> Text #

Leniently decode an untyped Base64url-encoded `Text`. 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 :: Text -> Bool #

Tell whether an untyped `Text` value is Base64url-encoded.

### Examples:

    >>> isBase64Url "PDw_Pj4="
    True

    >>> isBase64Url "PDw_Pj4"
    True

    >>> isBase64Url "PDw_Pj"
    False

isValidBase64Url :: Text -> Bool #

Tell whether an untyped `Text` value 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 `Text` value, use `isBase64Url`.

### Examples:

    >>> isValidBase64Url "PDw_Pj4="
    True

    >>> isValidBase64Url "PDw_Pj"
    True

    >>> isValidBase64Url "%"
    False