base64 — Base16, Base32, Base64, Base85 데이터 인코딩

base64 — Base16, Base32, Base64, Base85 데이터 인코딩 (Base16, Base32, Base64, Base85 Data Encodings)

이진 데이터를 인쇄 가능한 ASCII 문자로 인코딩하고, 그 인코딩을 다시 이진 데이터로 디코딩하는 함수들을 제공하는 모듈이에요. RFC 4648(Base64, Base32, Base16)에 명시된 인코딩, PDF 2.0에 명시된 Base85 인코딩, 그리고 다른 곳에서 쓰이는 비표준 Base85 변형까지 포함해요.

출처: Python 표준 라이브러리

본문

이 모듈은 이진 데이터를 인쇄 가능한 ASCII 문자로 인코딩하고 그 인코딩을 다시 이진 데이터로 디코딩하는 함수를 제공해요. 여기에는 RFC 4648(Base64, Base32, Base16)에 명시된 인코딩, PDF 2.0에 명시된 Base85 인코딩, 그리고 다른 곳에서 쓰이는 비표준 Base85 변형이 포함돼요.

이 모듈이 제공하는 인터페이스는 두 가지예요. 현대 인터페이스(modern interface) 는 bytes류 객체를 ASCII bytes로 인코딩하고, bytes류 객체나 ASCII를 포함한 문자열을 bytes로 디코딩하는 것을 지원해요. RFC 4648에 정의된 두 Base-64 알파벳(일반, 그리고 URL·파일시스템 안전) 모두 지원돼요.

레거시 인터페이스(legacy interface) 는 문자열에서 디코딩하는 기능은 지원하지 않지만, 파일 객체를 사용해 인코딩·디코딩하는 함수를 제공해요. 표준 Base64 알파벳만 지원하고, RFC 2045에 따라 76자마다 새 줄을 추가해요. RFC 2045 지원을 찾고 있다면 email 패키지를 보는 게 더 나을 거예요.

3.3 버전 변경: 현대 인터페이스의 디코딩 함수가 이제 ASCII 전용 유니코드 문자열도 받아들여요.

3.4 버전 변경: 이 모듈의 모든 인코딩·디코딩 함수가 이제 모든 bytes류 객체를 받아들여요. Ascii85/Base85 지원이 추가됐어요.

RFC 4648 인코딩

RFC 4648 인코딩은 이진 데이터를 안전하게 이메일로 보내거나, URL의 일부로 사용하거나, HTTP POST 요청의 일부로 포함할 수 있도록 하는 데 적합해요.

`base64.b64encode(s, altchars=None)`

bytes류 객체 s를 Base64로 인코딩하고 인코딩된 bytes를 반환해요. 선택 인자 altchars는 +와 / 문자에 대한 대체 알파벳을 지정하는 길이 2의 bytes류 객체여야 해요. 이를 통해 예를 들어 URL이나 파일시스템 안전한 Base64 문자열을 생성할 수 있어요. 기본값은 None이며, 표준 Base64 알파벳이 사용돼요. altchars의 길이가 2가 아니면 ValueError를 단언하거나 발생시킬 수 있고, altchars가 bytes류 객체가 아니면 TypeError를 발생시켜요.

`base64.b64decode(s, altchars=None, validate=False)`

Base64로 인코딩된 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요. 선택 인자 altchars는 +와 / 문자 대신 사용할 대체 알파벳을 지정하는 길이 2의 bytes류 객체나 ASCII 문자열이에요. s가 잘못 패딩됐으면 binascii.Error 예외가 발생해요. validate가 False(기본값)이면 일반 base-64 알파벳도 대체 알파벳도 아닌 문자는 패딩 검사 전에 버려져요. validate가 True이면 입력의 이런 비알파벳 문자는 binascii.Error로 이어져요. 엄격한 base64 검사에 대한 자세한 내용은 binascii.a2b_base64()를 참고하세요. altchars의 길이가 2가 아니면 ValueError를 단언하거나 발생시킬 수 있어요.

`base64.standard_b64encode(s)`

표준 Base64 알파벳을 사용해 bytes류 객체 s를 인코딩하고 인코딩된 bytes를 반환해요.

`base64.standard_b64decode(s)`

표준 Base64 알파벳을 사용해 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요.

`base64.urlsafe_b64encode(s)`

URL·파일시스템 안전 알파벳(표준 Base64 알파벳에서 -는 +를, _는 /를 대체)을 사용해 bytes류 객체 s를 인코딩하고 인코딩된 bytes를 반환해요. 결과는 여전히 =를 포함할 수 있어요.

`base64.urlsafe_b64decode(s)`

URL·파일시스템 안전 알파벳을 사용해 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요.

`base64.b32encode(s)`

bytes류 객체 s를 Base32로 인코딩하고 인코딩된 bytes를 반환해요.

`base64.b32decode(s, casefold=False, map01=None)`

Base32로 인코딩된 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요. 선택 인자 casefold는 소문자 알파벳이 입력으로 받아들여질지 여부를 지정하는 플래그예요. 보안 목적으로 기본값은 False예요. RFC 4648은 숫자 0(zero)을 문자 O(oh)로, 숫자 1(one)을 문자 I(eye) 또는 L(el)로 선택적으로 매핑하는 것을 허용해요. 선택 인자 map01은 None이 아닐 때 숫자 1이 매핑될 문자를 지정해요(map01이 None이 아닐 때 숫자 0은 항상 문자 O로 매핑돼요). 보안 목적으로 기본값은 None이라 0과 1은 입력에서 허용되지 않아요. s가 잘못 패딩되거나 입력에 비알파벳 문자가 있으면 binascii.Error가 발생해요.

`base64.b32hexencode(s)`

b32encode()와 비슷하지만 RFC 4648에 정의된 Extended Hex Alphabet을 사용해요. 3.10 버전에서 추가.

`base64.b32hexdecode(s, casefold=False)`

b32decode()와 비슷하지만 RFC 4648에 정의된 Extended Hex Alphabet을 사용해요. 이 버전은 숫자 0을 O로, 숫자 1을 I 또는 L로 매핑하는 것을 허용하지 않아요. 이 모든 문자는 Extended Hex Alphabet에 포함되어 있어 서로 바꿔 쓸 수 없어요. 3.10 버전에서 추가.

`base64.b16encode(s)`

bytes류 객체 s를 Base16으로 인코딩하고 인코딩된 bytes를 반환해요.

`base64.b16decode(s, casefold=False)`

Base16으로 인코딩된 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요. 선택 인자 casefold는 소문자 알파벳이 입력으로 받아들여질지 여부를 지정하는 플래그예요. 보안 목적으로 기본값은 False예요. s가 잘못 패딩되거나 입력에 비알파벳 문자가 있으면 binascii.Error가 발생해요.

Base85 인코딩

Base85 인코딩은 네 바이트를 다섯 개의 ASCII 문자로 표현하는 알고리즘 계열이에요. 원래 Unix의 btoa(1) 유틸리티에서 구현됐고, 나중에 그 버전 중 하나가 Adobe가 PostScript 언어에 채택했으며 PDF 2.0(ISO 32000-2)에서 표준화됐어요. 이 버전(btoa와 PDF 변형 모두)은 a85encode()로 구현돼요.

다른 출력 문자 집합을 사용하는 별도 버전은 RFC 1924에서 만우절 농담으로 정의됐지만 지금은 Git과 다른 소프트웨어에서 사용돼요. 이 버전은 b85encode()로 구현되죠.

마지막으로 프로그래밍 언어 문자열에 안전하게 포함되도록 설계된 또 다른 출력 문자 집합을 사용하는 세 번째 버전은 ZeroMQ에 의해 정의되며 여기서 z85encode()로 구현돼요.

이 모듈의 함수들은 다음을 어떻게 처리하는지에 따라 달라요:

<~와 ~> 둘러싸는 마커를 포함·기대하는지 여부.
입력을 여러 줄로 접는지 여부.
인코딩에 사용되는 ASCII 문자 집합.
공백과 null 바이트 시퀀스의 컴팩트 인코딩.
입력에 적용되는 zero-padding 바이트의 인코딩.

각 함수에 대한 자세한 내용은 개별 함수 문서를 참고하세요.

`base64.a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)`

bytes류 객체 b를 Ascii85로 인코딩하고 인코딩된 bytes를 반환해요. foldspaces는 btoa가 지원하는 것처럼 4개의 연속 공백(ASCII 0x20) 대신 특수 짧은 시퀀스 'y'를 사용하는 선택 플래그예요. 이 기능은 PDF에서 쓰는 표준 인코딩에서는 지원되지 않아요. wrapcol은 출력에 새 줄(b'\n') 문자를 추가할지 여부를 제어해요. 이 값이 0이 아니면 각 출력 줄은 끝의 새 줄을 제외하고 최대 이만큼의 문자 길이가 돼요. pad는 입력 끝에 적용된 zero-padding이 출력 인코딩에 완전히 유지될지 여부를 제어해요(btoa처럼 정확히 5바이트 배수의 출력을 생성). 이는 데이터 길이를 보존하지 않으므로 PDF에서 쓰는 표준 인코딩에는 포함되지 않아요. adobe는 인코딩된 바이트 시퀀스가 PostScript base-85 문자열 리터럴처럼 <~와 ~>로 둘러싸이는지 여부를 제어해요. PDF 문서의 ASCII85Decode 스트림은 ~>로 끝나야 하지만 앞의 <~는 사용하면 안 된다는 점을 참고하세요. 3.4 버전에서 추가.

`base64.a85decode(b, *, foldspaces=False, adobe=False, ignorechars=b' \t\n\r\x0b')`

Ascii85로 인코딩된 bytes류 객체나 ASCII 문자열 b를 디코딩하고 디코딩된 bytes를 반환해요. foldspaces는 'y' 짧은 시퀀스가 4개의 연속 공백(ASCII 0x20)의 약식으로 받아들여져야 하는지 여부를 지정하는 플래그예요. 이 기능은 PDF와 PostScript에서 쓰는 표준 Ascii85 인코딩에서는 지원되지 않아요. adobe는 <~와 ~> 마커가 존재하는지 여부를 제어해요. 앞의 <~는 필수가 아니지만 입력은 ~>로 끝나야 하며, 그렇지 않으면 ValueError가 발생해요. ignorechars는 입력에서 무시할 문자를 포함하는 바이트 문자열이어야 해요. 공백 문자만 포함해야 하며, 기본적으로 ASCII의 모든 공백 문자를 포함해요. 3.4 버전에서 추가.

`base64.b85encode(b, pad=False)`

bytes류 객체 b를 base85(예: git 스타일 이진 diff에서 사용)로 인코딩하고 인코딩된 bytes를 반환해요. 입력은 인코딩 전에 길이가 4바이트의 배수가 되도록 b'\0'으로 패딩돼요. pad가 True면 결과 문자가 모두 출력에 유지되는데, 항상 5바이트의 배수가 되므로 디코딩 시 데이터 길이가 보존되지 않을 수 있어요. 3.4 버전에서 추가.

`base64.b85decode(b)`

base85로 인코딩된 bytes류 객체나 ASCII 문자열 b를 디코딩하고 디코딩된 bytes를 반환해요. 3.4 버전에서 추가.

`base64.z85encode(s)`

bytes류 객체 s를 Z85(ZeroMQ에서 사용)로 인코딩하고 인코딩된 bytes를 반환해요. ZeroMQ 사양은 Z85 인코딩 데이터의 길이가 5바이트의 배수여야 한다고 요구해요. 규격을 준수하는 데이터 프레임을 만들려면 이 함수에 전달하는 입력 데이터를 4바이트의 배수로 패딩해야 해요. 3.13 버전에서 추가.

`base64.z85decode(s)`

Z85로 인코딩된 bytes류 객체나 ASCII 문자열 s를 디코딩하고 디코딩된 bytes를 반환해요. 3.13 버전에서 추가.

레거시 인터페이스

`base64.decode(input, output)`

이진 입력 파일의 내용을 디코딩하고 결과 이진 데이터를 출력 파일에 써요. input과 output은 파일 객체여야 해요. input.readline()이 빈 bytes 객체를 반환할 때까지 input을 읽어요.

`base64.decodebytes(s)`

한 줄 이상의 base64 인코딩 데이터를 포함해야 하는 bytes류 객체 s를 디코딩하고 디코딩된 bytes를 반환해요. 3.1 버전에서 추가.

`base64.encode(input, output)`

이진 입력 파일의 내용을 인코딩하고 결과 base64 인코딩 데이터를 출력 파일에 써요. input과 output은 파일 객체여야 해요. input.read()가 빈 bytes 객체를 반환할 때까지 input을 읽어요. encode()는 RFC 2045(MIME)에 따라 출력의 76바이트마다 새 줄 문자(b'\n')를 삽입하고, 출력이 항상 새 줄로 끝나도록 보장해요.

`base64.encodebytes(s)`

임의의 이진 데이터를 포함할 수 있는 bytes류 객체 s를 인코딩하고, RFC 2045(MIME)에 따라 출력의 76바이트마다 새 줄(b'\n')이 삽입되고 끝에 새 줄이 있는 것을 보장하는 base64 인코딩 데이터를 포함한 bytes를 반환해요. 3.1 버전에서 추가.

모듈 사용 예시:

>>> import base64
>>> encoded = base64.b64encode(b'data to be encoded')
>>> encoded
b'ZGF0YSB0byBiZSBlbmNvZGVk'
>>> data = base64.b64decode(encoded)
>>> data
b'data to be encoded'

보안 고려사항

RFC 4648의 섹션 12에 새 보안 고려사항 섹션이 추가됐어요. 프로덕션에 배포하는 코드라면 보안 섹션을 검토하는 걸 권장해요.

더 알아보기

Module binascii — ASCII에서 이진으로, 이진에서 ASCII로 변환을 포함하는 지원 모듈.
RFC 1521 — MIME 1부. 섹션 5.2, "Base64 Content-Transfer-Encoding"이 base64 인코딩의 정의를 제공해요.
ISO 32000-2 — PDF 2.0. 섹션 7.4.3, "ASCII85Decode Filter"가 PDF와 PostScript에서 쓰는 Ascii85 인코딩(출력 문자 집합, zero-padding과 부분 출력 그룹을 사용한 데이터 길이 보존 세부사항 포함)의 정의를 제공해요.
ZeroMQ RFC 32/Z85 — "Formal Specification" 섹션이 Z85에서 사용하는 문자 집합을 제공해요.