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.ByteString.Lazy.Base64

Contents

- Encoding
- Decoding
- Validation

Description

This module contains `ByteString`-valued combinators for implementing the RFC 4648 specification of the Base64 encoding format. This includes lenient decoding variants, as well as internal and external validation for canonicity.

Synopsis

- encodeBase64 :: ByteString -> Base64 'StdPadded Text
- encodeBase64' :: ByteString -> Base64 'StdPadded ByteString
- decodeBase64 :: forall (k :: Alphabet). StdAlphabet k => Base64 k ByteString -> ByteString
- decodeBase64Untyped :: ByteString -> Either Text ByteString
- decodeBase64Lenient :: ByteString -> ByteString
- isBase64 :: ByteString -> Bool
- isValidBase64 :: ByteString -> Bool

# Encoding

encodeBase64 :: ByteString -> Base64 'StdPadded Text #

Encode a `ByteString` value as Base64 `Text` with padding.

See: RFC-4648 section 4

### Examples:

    >>> encodeBase64 "Sun"
    "U3Vu"

encodeBase64' :: ByteString -> Base64 'StdPadded ByteString #

Encode a `ByteString` value as a Base64 `ByteString` value with padding.

See: RFC-4648 section 4

### Examples:

    >>> encodeBase64' "Sun"
    "U3Vu"

# Decoding

decodeBase64 :: forall (k :: Alphabet). StdAlphabet k => Base64 k ByteString -> ByteString #

Decode a padded Base64-encoded `ByteString` value.

See: RFC-4648 section 4

### Examples:

    >>> decodeBase64 $ assertBase64 @'StdPadded "U3Vu"
    "Sun"

decodeBase64Untyped :: ByteString -> Either Text ByteString #

Decode a padded untyped Base64-encoded `ByteString` value.

See: RFC-4648 section 4

### Examples:

    >>> decodeBase64Untyped "U3Vu"
    Right "Sun"

    >>> decodeBase64Untyped "U3V"
    Left "Base64-encoded bytestring requires padding"

    >>> decodeBase64Untyped "U3V="
    Left "non-canonical encoding detected at offset: 2"

decodeBase64Lenient :: ByteString -> ByteString #

Leniently decode an unpadded Base64-encoded `ByteString` value. 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 "U3Vu"
    "Sun"

    >>> decodeBase64Lenient "U3V"
    "Su"

    >>> decodeBase64Lenient "U3V="
    "Su"

# Validation

isBase64 :: ByteString -> Bool #

Tell whether a `ByteString` value is base64 encoded.

This function will also detect non-canonical encodings such as `ZE==`, which are externally valid Base64-encoded values, but are internally inconsistent "impossible" values.

### Examples:

    >>> isBase64 "U3Vu"
    True

    >>> isBase64 "U3V"
    False

    >>> isBase64 "U3V="
    False

isValidBase64 :: ByteString -> Bool #

Tell whether a `ByteString` value is a valid Base64 format.

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

### Examples:

    >>> isValidBase64 "U3Vu"
    True

    >>> isValidBase64 "U3V"
    True

    >>> isValidBase64 "U3V="
    True

    >>> isValidBase64 "%"
    False