Improve definition of "invalid padding" in `base64.b64decode`

[LamentXU123]

In the doc of b64decode:

It is claimed that an Exception will be raised if input byte s is incorrectly padded. However, with the argument validate set to False, which is the default value, python check if s is wrongly padded when some padding is missing, but don't check if padding is redundant.

import base64
print(base64.b64decode('aGVsbG8gd29ybGQ=')) #  hello world
print(base64.b64decode('aGVsbG8gd29ybGQ======')) #  hello world
print(base64.b64decode('aGVsbG8gd29ybGQ======', validate=True)) # binascii.Error: Non-base64 digit found
print(base64.b64decode('aGVsbG8gd29ybGQ')) # binascii.Error: Incorrect padding

I think if we could maybe made this clearer here? This doc really confused me when I'm decoding some base64 data that could be wrong (I expect an error will be raised if the padding of the input is wrong). Thanks.

Edit1: I think the program regard the redundant padding char as char after padding which should be discarded in default mode. Humm, I'm not sure should we consider redundant padding char as an Incorrect padding . For now, we treat aGVsbG8gd29ybGQ as an Incorrect padding but not aGVsbG8gd29ybGQ==, while the correct padding is aGVsbG8gd29ybGQ=.

Linked PRs

• gh-139287: Improve the definition of Incorrect padding in base64.rst documents #139301

[picnixz]

I expect an error will be raised if the padding of the input is wrong

That depends on the language (see https://eprint.iacr.org/2022/361) where libraries may or may not consider redundant padding. The various RFCs don't mention whether an entire string of = should be considered as a valid or not. In validate mode, we are more strict and thus we check if extra padding was added or not.

Now, a padding character is interpreted as an indication that we are at the end of the payload. So after we've processed the padding, we should not expect additional output. For instance:

>>> base64.b64decode("SGk=^_^")
b'Hi'

In other words, we're actually stopping early (we early exit). The same could be observed with a padding character in the middle of the string which will be ignored:

>>> base64.b64decode("====")
b''
>>> base64.b64decode("==SGk=")
b'Hi'
>>> base64.b64decode("S=Gk=")
b'Hi'

I agree that we could explain what "incorrect" padding means in this case. When validate is False, extra padding and = in the middle of the string (called "discontinuous padding) are ignored, whereas in validate, those are rejected.

[picnixz]

Actually the docs mention binascii.a2b_base64 which explains what padding we expect in strict mode. I therefore don't think we should change anything (see #139301 (review)).

[LamentXU123]

While users turn off the validate mode, they don't that much care about the padding issue. Doc here will be too verbose. I'll close this.