Copyright | (c) 2019-2023 Emily Pillmore |
---|---|
License | BSD-style |
Maintainer | Emily Pillmore <emilypi@cohomolo.gy> |
Stability | stable |
Portability | non-portable |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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.
Synopsis
- encodeBase64 :: ShortByteString -> Base64 'UrlPadded ShortText
- encodeBase64' :: ShortByteString -> Base64 'UrlPadded ShortByteString
- encodeBase64Unpadded :: ShortByteString -> Base64 'UrlUnpadded ShortText
- encodeBase64Unpadded' :: ShortByteString -> Base64 'UrlUnpadded ShortByteString
- decodeBase64 :: UrlAlphabet k => Base64 k ShortByteString -> ShortByteString
- decodeBase64Untyped :: ShortByteString -> Either Text ShortByteString
- decodeBase64Unpadded :: Base64 'UrlUnpadded ShortByteString -> ShortByteString
- decodeBase64UnpaddedUntyped :: ShortByteString -> Either Text ShortByteString
- decodeBase64Padded :: Base64 'UrlPadded ShortByteString -> ShortByteString
- decodeBase64PaddedUntyped :: ShortByteString -> Either Text ShortByteString
- decodeBase64Lenient :: ShortByteString -> ShortByteString
- isBase64Url :: ShortByteString -> Bool
- isValidBase64Url :: ShortByteString -> Bool
Encoding
encodeBase64 :: ShortByteString -> Base64 'UrlPadded ShortText Source #
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 Source #
Encode a ShortByteString
as a Base64url ShortByteString
value with padding.
See: RFC-4648 section 5
Examples:
>>>
encodeBase64' "<<?>>"
"PDw_Pj4="
encodeBase64Unpadded :: ShortByteString -> Base64 'UrlUnpadded ShortText Source #
Encode a ShortByteString
value as Base64url Text
without padding.
See: RFC-4648 section 3.2
Examples:
>>>
encodeBase64Unpadded "<<?>>"
"PDw_Pj4"
encodeBase64Unpadded' :: ShortByteString -> Base64 'UrlUnpadded ShortByteString Source #
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 Source #
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 Source #
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 Source #
Decode an unpadded Base64url-encoded ShortByteString
value.
See: RFC-4648 section 4
Examples:
>>>
decodeBase64Unpadded $ assertBase64 @'UrlUnpadded "PDw_Pj4"
"<<?>>"
decodeBase64UnpaddedUntyped :: ShortByteString -> Either Text ShortByteString Source #
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 Source #
Decode a padded Base64url-encoded ShortByteString
value.
See: RFC-4648 section 4
Examples:
>>>
decodeBase64Padded $ assertBase64 @'UrlPadded "PDw_Pj4="
"<<?>>"
decodeBase64PaddedUntyped :: ShortByteString -> Either Text ShortByteString Source #
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 Source #
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 Source #
Tell whether an untyped ShortByteString
is Base64url-encoded.
Examples:
>>>
isBase64Url "PDw_Pj4="
True
>>>
isBase64Url "PDw_Pj4"
True
>>>
isBase64Url "PDw_Pj"
False
isValidBase64Url :: ShortByteString -> Bool Source #
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