Common Lisp Package: COM.INFORMATIMAGO.COMMON-LISP.RFC3548.RFC3548

This packages exports functions to encode an decode text blocks according to the encoding described in: RFC3548: The Base16, Base32, and Base64 Data Encodings base64-encode (read-byte write-char) base64-decode (read-char write-byte &key (ignore-invalid-input nil)) filebase64-encode (read-byte write-char) filebase64-decode (read-char write-byte &key (ignore-invalid-input nil)) base32-encode (read-byte write-char) base32-decode (read-char write-byte &key (ignore-invalid-input nil)) base16-encode (read-byte write-char) base16-decode (read-char write-byte &key (ignore-invalid-input nil)) READ-BYTE: A function taking no argument and returning a byte (integer 0 255) or nil for eof. It may be called several times after eof and should keep returning nil. WRITE-BYTE: A function taking one byte (integer 0 255) argument used to collect decoded bytes. READ-CHAR: A function taking no argument and returning a character or nil for eof. It may be called several times after eof and should keep returning nil. Only characters whose code is between 0 and 255 should be returned. WRITE-CHAR: A function taking one character argument, used to collect encoded bytes. IGNORE-INVALID-INPUT: When true, any invalid character or padding is ignored and processing continues as if it did not occur. When nil, such an occurence would raise an error. base64-encode-bytes (bytes &key line-width (new-line +new-line+)) base64-decode-bytes (encoded &key ignore-crlf ignore-invalid-input) filebase64-encode-bytes (bytes &key line-width (new-line +new-line+)) filebase64-decode-bytes (encoded &key ignore-crlf ignore-invalid-input) base32-encode-bytes (bytes &key line-width (new-line +new-line+)) base32-decode-bytes (encoded &key ignore-crlf ignore-invalid-input) base16-encode-bytes (bytes &key line-width (new-line +new-line+)) base16-decode-bytes (encoded &key ignore-crlf ignore-invalid-input) BYTES: A vector of (unsigned-byte 8). ENCODED: A string. LINE-WIDTH: NIL or an integer indicating the line width. the string new-line will be inserted after that many characters have been written on a given line. NEW-LINE: A string contaiing the new-line character or characters. the default +new-line+ is (format nil "~%"). IGNORE-CRLF: When true, ASCII characters LF and CR are not passed to the decoding function. When NIL, they're passed, and if invalid input is not ignored, an error would be raised. IGNORE-INVALID-INPUT: Passed to the decoding function. See above. The encoding functions take a vector of bytes and return an encoded string. The decoding functions take an encoded string and return a vector of bytes. To encode a string, characters must be converted to bytes, and to decode a string, bytes must be converted to characters. This must be done accordingly to the characeter set encoding. License: AGPL3 Copyright Pascal J. Bourguignon 2004 - 2012 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

README:

FUNCTION

Public

BASE16-DECODE (READ-CHAR WRITE-BYTE &KEY (IGNORE-INVALID-INPUT NIL))

DO: Decode the BASE16 text stream read with the READ-CHAR closure into a binary stream written with WRITE-BYTE closure. READ-CHAR: A function taking no argument and returning a character or nil for eof. It may be called several times after eof and should keep returning nil. Only characters whose code is between 0 and 255 should be returned. WRITE-BYTE: A function taking one byte (integer 0 255) argument used to collect decoded bytes. IGNORE-INVALID-INPUT: When true, any invalid character or padding is ignored and processing continues as if it did not occur. When nil, such an occurence would raise an error.

BASE16-DECODE-BYTES (ENCODED &KEY IGNORE-CRLF IGNORE-INVALID-INPUT)

DO: Decode the BASE16 encoded string ENCODED. RETURN: A decoded vector of (unsigned-byte 8). ENCODED: A string. IGNORE-CRLF: When true, ASCII characters LF and CR are not passed to the decoding function. When NIL, they're passed, and if invalid input is not ignored, an error would be raised. IGNORE-INVALID-INPUT: Passed to the decoding function. See above.

BASE16-ENCODE (READ-BYTE WRITE-CHAR)

DO: Encode the stream read with the READ-BYTE closure in BASE16 text written with WRITE-CHAR closure. READ-BYTE: A function taking no argument and returning a byte (integer 0 255) or nil for eof. It may be called several times after eof and should keep returning nil. WRITE-CHAR: A function taking one character argument, used to collect encoded bytes.

BASE16-ENCODE-BYTES (BYTES &KEY LINE-WIDTH (NEW-LINE +NEW-LINE+))

DO: Encode the BYTES in BASE16 text. RETURN: An encoded string. BYTES: A vector of (unsigned-byte 8). LINE-WIDTH: NIL or an integer indicating the line width. the string new-line will be inserted after that many characters have been written on a given line. NEW-LINE: A string contaiing the new-line character or characters. the default +new-line+ is (format nil "~%").

BASE32-DECODE (READ-CHAR WRITE-BYTE &KEY (IGNORE-INVALID-INPUT NIL))

DO: Decode the BASE32 text stream read with the READ-CHAR closure into a binary stream written with WRITE-BYTE closure. READ-CHAR: A function taking no argument and returning a character or nil for eof. It may be called several times after eof and should keep returning nil. Only characters whose code is between 0 and 255 should be returned. WRITE-BYTE: A function taking one byte (integer 0 255) argument used to collect decoded bytes. IGNORE-INVALID-INPUT: When true, any invalid character or padding is ignored and processing continues as if it did not occur. When nil, such an occurence would raise an error.

BASE32-DECODE-BYTES (ENCODED &KEY IGNORE-CRLF IGNORE-INVALID-INPUT)

DO: Decode the BASE32 encoded string ENCODED. RETURN: A decoded vector of (unsigned-byte 8). ENCODED: A string. IGNORE-CRLF: When true, ASCII characters LF and CR are not passed to the decoding function. When NIL, they're passed, and if invalid input is not ignored, an error would be raised. IGNORE-INVALID-INPUT: Passed to the decoding function. See above.

BASE32-ENCODE (READ-BYTE WRITE-CHAR)

DO: Encode the stream read with the READ-BYTE closure in BASE32 text written with WRITE-CHAR closure. READ-BYTE: A function taking no argument and returning a byte (integer 0 255) or nil for eof. It may be called several times after eof and should keep returning nil. WRITE-CHAR: A function taking one character argument, used to collect encoded bytes.

BASE32-ENCODE-BYTES (BYTES &KEY LINE-WIDTH (NEW-LINE +NEW-LINE+))

DO: Encode the BYTES in BASE32 text. RETURN: An encoded string. BYTES: A vector of (unsigned-byte 8). LINE-WIDTH: NIL or an integer indicating the line width. the string new-line will be inserted after that many characters have been written on a given line. NEW-LINE: A string contaiing the new-line character or characters. the default +new-line+ is (format nil "~%").

BASE64-DECODE (READ-CHAR WRITE-BYTE &KEY (IGNORE-INVALID-INPUT NIL))

DO: Decode the BASE64 text stream read with the READ-CHAR closure into a binary stream written with WRITE-BYTE closure. READ-CHAR: A function taking no argument and returning a character or nil for eof. It may be called several times after eof and should keep returning nil. Only characters whose code is between 0 and 255 should be returned. WRITE-BYTE: A function taking one byte (integer 0 255) argument used to collect decoded bytes. IGNORE-INVALID-INPUT: When true, any invalid character or padding is ignored and processing continues as if it did not occur. When nil, such an occurence would raise an error.

BASE64-DECODE-BYTES (ENCODED &KEY IGNORE-CRLF IGNORE-INVALID-INPUT)

DO: Decode the BASE64 encoded string ENCODED. RETURN: A decoded vector of (unsigned-byte 8). ENCODED: A string. IGNORE-CRLF: When true, ASCII characters LF and CR are not passed to the decoding function. When NIL, they're passed, and if invalid input is not ignored, an error would be raised. IGNORE-INVALID-INPUT: Passed to the decoding function. See above.

BASE64-ENCODE (READ-BYTE WRITE-CHAR)

DO: Encode the stream read with the READ-BYTE closure in BASE64 text written with WRITE-CHAR closure. READ-BYTE: A function taking no argument and returning a byte (integer 0 255) or nil for eof. It may be called several times after eof and should keep returning nil. WRITE-CHAR: A function taking one character argument, used to collect encoded bytes.

BASE64-ENCODE-BYTES (BYTES &KEY LINE-WIDTH (NEW-LINE +NEW-LINE+))

DO: Encode the BYTES in BASE64 text. RETURN: An encoded string. BYTES: A vector of (unsigned-byte 8). LINE-WIDTH: NIL or an integer indicating the line width. the string new-line will be inserted after that many characters have been written on a given line. NEW-LINE: A string contaiing the new-line character or characters. the default +new-line+ is (format nil "~%").

FILEBASE64-DECODE (READ-CHAR WRITE-BYTE &KEY (IGNORE-INVALID-INPUT NIL))

DO: Decode the FILEBASE64 text stream read with the READ-CHAR closure into a binary stream written with WRITE-BYTE closure. NOTE: It's the same encoding as BASE64, but the 62nd and 63rd characters are - and _ instead of + and /, thus making it usable for file names and URLs. READ-CHAR: A function taking no argument and returning a character or nil for eof. It may be called several times after eof and should keep returning nil. Only characters whose code is between 0 and 255 should be returned. WRITE-BYTE: A function taking one byte (integer 0 255) argument used to collect decoded bytes. IGNORE-INVALID-INPUT: When true, any invalid character or padding is ignored and processing continues as if it did not occur. When nil, such an occurence would raise an error.

FILEBASE64-DECODE-BYTES (ENCODED &KEY IGNORE-CRLF IGNORE-INVALID-INPUT)

DO: Decode the FILEBASE64 encoded string ENCODED. RETURN: A decoded vector of (unsigned-byte 8). ENCODED: A string. IGNORE-CRLF: When true, ASCII characters LF and CR are not passed to the decoding function. When NIL, they're passed, and if invalid input is not ignored, an error would be raised. IGNORE-INVALID-INPUT: Passed to the decoding function. See above.

FILEBASE64-ENCODE (READ-BYTE WRITE-CHAR)

DO: Encode the stream read with the READ-BYTE closure in FILEBASE64 text written with WRITE-CHAR closure. NOTE: It's the same encoding as BASE64, but the 62nd and 63rd characters are - and _ instead of + and /, thus making it usable for file names and URLs. READ-BYTE: A function taking no argument and returning a byte (integer 0 255) or nil for eof. It may be called several times after eof and should keep returning nil. WRITE-CHAR: A function taking one character argument, used to collect encoded bytes.

FILEBASE64-ENCODE-BYTES (BYTES &KEY LINE-WIDTH (NEW-LINE +NEW-LINE+))

DO: Encode the BYTES in FILEBASE64 text. RETURN: An encoded string. BYTES: A vector of (unsigned-byte 8). LINE-WIDTH: NIL or an integer indicating the line width. the string new-line will be inserted after that many characters have been written on a given line. NEW-LINE: A string contaiing the new-line character or characters. the default +new-line+ is (format nil "~%").

Private

MAKE-DECODE-TABLE (CODE &KEY (CASE-SENSITIVE T))

CODE: A string of length (1+ (expt 2 n)). RETURN: An array A:[0..255] --> [-1..(expt 2 n)] character-code --> encoding-value

PADDING-CODE (CODE)

The position of the padding character in code (the last one).

Undocumented

DECODE32 (DECODE PADCHAR PADCODE READ-CHAR WRITE-BYTE IGNORE-INVALID-INPUT)

DECODE64 (DECODE PADCHAR PADCODE READ-CHAR WRITE-BYTE IGNORE-INVALID-INPUT)

ENCODE32 (ENCODE READ-BYTE WRITE-CHAR)

ENCODE64 (ENCODE READ-BYTE WRITE-CHAR)

TEST

TEST-BASE16-DECODE

TEST-BASE16-ENCODE

TEST-ENCODING (ENCODING &KEY LINE-WIDTH IGNORE-CRLF)

MACRO

Private

WITH-INPUT-FROM-BYTE-VECTOR ((VAR BYTE-VECTOR &KEY INDEX START END) &BODY BODY)

DO: Execute the BODY with VAR bound to an input byte vector stream reading bytes from the BYTE-VECTOR, from START to END. If INDEX is given it should be a place into which the last position is stored. RETURN: The last position.

WITH-OUTPUT-TO-BYTE-VECTOR ((VAR &OPTIONAL BYTE-VECTOR-FORM &KEY ELEMENT-TYPE) &BODY BODY)

DO: Execute the BODY with VAR bound to an output byte vector stream. If BYTE-VECTOR-FORM is given it should produce a byte vector with a fill-pointer where the bytes written to the bvstream are stored. ELEMENT-TYPE: The type of bytes. If BYTE-VECTOR-FORM is nil, one can choose a different element-type for the byte vector. RETURN: The byte vector written.

Undocumented

DECODE-BYTES (DECODE ENCODED IGNORE-CRLF IGNORE-INVALID-INPUT)

ENCODE-BYTES (ENCODE BYTES LINE-WIDTH NEW-LINE)

WITH-IO ((IN OUT) (DECODE PADCHAR PADCODE READ-CHAR WRITE-BYTE IGNORE-INVALID-INPUT) &BODY BODY)

GENERIC-FUNCTION

Private

BVSTREAM-READ-BYTE (BVSTREAM)

Read a byte from the BVSTREAM.

BVSTREAM-WRITE-BYTE (BVSTREAM BYTE)

Write a byte to the BVSTREAM.

VARIABLE

Private

+BASE32-DECODE+

An array A:[0..255] |--> [-1..31] character-code ---> encoding-value

+BASE32-ENCODE+

An array A[0..32] --> character giving the character used to encode the values from 0 to 31, and the padding character in slot 32.

+BASE64-DECODE+

An array A:[0..255] |--> [-1..63] character-code ---> encoding-value

+BASE64-ENCODE+

An array A[0..64] --> character giving the character used to encode the values from 0 to 63, and the padding character in slot 64.

+FILEBASE64-DECODE+

An array A:[0..255] |--> [-1..63] character-code ---> encoding-value

+FILEBASE64-ENCODE+

An array A[0..64] --> character giving the character used to encode the values from 0 to 63, and the padding character in slot 64.

Undocumented

+NEW-LINE+