binascii documentation incorrect

[mouse07410]

BPO	25495
Nosy	@birkenfeld, @bitdancer, @vadmium, @matrixise, @mouse07410
Files	issue25495.patch issue25495.base64.2.7.patch: For 2.7

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2015-12-13.23:16:59.619>
created_at = <Date 2015-10-27.23:10:17.513>
labels = ['docs']
title = 'binascii documentation incorrect'
updated_at = <Date 2015-12-14.01:30:39.453>
user = 'https://github.com/mouse07410'

bugs.python.org fields:

activity = <Date 2015-12-14.01:30:39.453>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2015-12-13.23:16:59.619>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2015-10-27.23:10:17.513>
creator = 'mouse07410'
dependencies = []
files = ['40878', '40953']
hgrepos = []
issue_num = 25495
keywords = ['patch']
message_count = 27.0
messages = ['253572', '253577', '253607', '253625', '253627', '253710', '253744', '253766', '253918', '253920', '253921', '253922', '253924', '253935', '253955', '254011', '254100', '254118', '254122', '254141', '254148', '254195', '254820', '256021', '256348', '256349', '256354']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'r.david.murray', 'docs@python', 'python-dev', 'martin.panter', 'matrixise', 'mouse07410']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue25495'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5', 'Python 3.6']

[mouse07410]

binascii b2a_base64() documentation says:

The length of data should be at most 57 to adhere to the base64 standard.

This is incorrect, because there is no base64 standard that restricts the length of input data, especially to such a small value.

What RFC4648 (that superseded RFC3548 that your documentation still keeps referring to) actually says is that MIME enforces the limit ofthe OUTPUT LINE length at 76, but NOT of the entire output, and certainly not of the entire input.

Please correct the documentation, making it conformant with what the ACTUAL base64 standard says.

See https://en.wikipedia.org/wiki/Base64 and
https://tools.ietf.org/html/rfc4648

Thanks!

[bitdancer]

I agree that the documentation is not optimal. To give you some background, binascii was primarily implemented to support the email module, and the standard it is referring to is in fact the MIME standard that references base64 (I believe at the time the independent base64 standard did not exist). The number 57 is derived from the fact that 57 * 4/3 = 76; that is, input data of length 57 will result in an encoded line that is equal to the maximum recommended line length. Thus in encoding an email the email package (originally, it no longer does this) passed the data in in 57 byte chunks and appended the resulting lines to the output buffer.

So, this documentation is historically correct, but no longer particularly useful. Suggested improvements are welcome.

This state of affairs exists because the binascii module doesn't really have a current maintainer. Someday I'd love to have enough time to pick it up, since I maintain email and it is still used by email (and could be used better, with some module improvements).

[mouse07410]

Yes I know where this came from. :-)

Here is my proposed change.

Replace the statement

The length of data should be at most 57 to adhere to the base64 standard.

with:

To be MIME-compliant, the Base64 output (as defined in RFC4648) should be broken into lines of at most 76 characters long. This post-processing of the output is the responsibility of the caller. Note that the original PEM context-transfer encoding limited line length to 64 characters.

Would this change be agreeable to you?

[matrixise]

Here is a patch with the submitted description.

[mouse07410]

Thank you for the quick turn-around, and for taking care of this issue!

[vadmium]

Thanks for bringing this up, it has often bugged me.

My understanding, based on the original wording and places where this is used, is that the data is often pre-processed into 57-byte chunks, rather than post-processing it. Maybe it is worthwhile restoring that info. It should help understanding the presence of the newline parameter (or why a newline is always added in 3.5).

Also, the link between RFC 4648 and this function could be made even more explicit. Maybe move “as defined” into the first sentence, or change “the Base64 output” to “the function’s output”.

[mouse07410]

As far as I remember, the data was not "originally processed in 57-byte chunks". I've been around the first PEM and MIME standards and discussions (and code, though not in Python, which wasn't around then) to be in position to know. :)

Whether the user prefers to process data in chunks or not, is up to the user.
Not to mention that PEM is long gone, and MIME also changed somewhat.

The link between this function and RFC4648 can and should be more explicit, but I think just referring to it is enough.

Do you have a recommendation for additional info to explain newline issues?

Yes, changing "Base64 output" to "function output" makes perfect sense.

Thanks!

[vadmium]

I was only referring to the original Python documentation and library. See the base64.encode() implementation for an example which does do this 57-byte pre-chunking. Simplified:

MAXLINESIZE = 76 # Excluding the CRLF
MAXBINSIZE = (MAXLINESIZE//4)*3  # 57
...
while True:
    s = input.read(MAXBINSIZE)
    if not s:
        break
    line = binascii.b2a_base64(s)
    output.write(line)

Here’s my attempt to rewrite the doc (3.6 version):

'''
Convert binary data to the base 64 encoding defined in :rfc:`4648`. The return value includes a trailing newline ``b"\n"`` if *newline* is true.

To be MIME-compliant, base 64 output should be broken into lines at most 76 characters long. One way to do this is to call this function with 57-byte chunks and newline=True. Also, the original PEM context-transfer encoding limited the line length to 64 characters.
'''

But if PEM is long gone as you say, perhaps we don’t need that last sentence?

[mouse07410]

1. I concede knowing nothing about the early Python library implementation, functionality, or even purpose.

2. I don't think it makes sense now to either refer to PEM. We'd be two decades too late for that (well, 27 years, to be precise :). See
   https://en.wikipedia.org/wiki/Privacy-enhanced_Electronic_Mail

3. I don't think we are in position to tell programmers how to split a string of characters into 76-long chunks. Not to mention that the example you gave is likely to suffer in performance (just count those function calls), compared to other methods, and won't reflect well on the authors.

Here's one possible doc version:

'''
Convert binary data to the base 64 encoding defined in :rfc:`4648`. The return value includes a trailing newline ``b"\n"`` if *newline* is true.

If the output is used as Base64 transfer encoding for MIME (:rfc: 2045), base 64 output should be broken into lines at most 76 characters long to be compliant. Base64 encoding standard does not limit the maximum encoded line length.
'''

[bitdancer]

Add a parenthetical "(57 bytes of the input per line)" and I'll be happy with that.

[mouse07410]

Let's not insinuate anything about the input. This is about what constraints on the OUTPUT MAY be there, not a tutorial from the 80-ties on how one might accomplish it.

[mouse07410]

And even those constraints depend on the use. E.g. X.509 does not have those.

[bitdancer]

Please take a look at the Examples section of this:

http://perldoc.perl.org/MIME/Base64.html

Looks kind of like Martin's suggestion :)