Should CLI/GUI tools expose checksum completion?

[BenWestgate]

Before releasing python-codex32 v1, I’d appreciate feedback on whether checksum completion is useful enough to justify its misuse risk.

My candidate ms32 checksum command completes a Codex32 Book worksheet. It saves manual checksum computation, but can also give wrong data a valid checksum. Users might interpret that as evidence their backup is secure/random.

Safeguards:

• Requires a valid codex32 header and format, and exactly 26, 32, 39, 45, 52, or 103 payload characters. Bad input is rejected without explaining the required format or length.
• Two independent entries must agree. The command clears the screen and scrollback before re-entry, without showing the previous answer. Automatic input history is disabled.
• No result or hint about what should have been entered is given after invalid input, a mismatch, or cancellation.
• Help and prompts deliberately give no input recipe: no explanation of header fields, length, or character set. Users are referred to the Book.

These checks cannot guarantee data was generated correctly. Entering wrong data twice can still succeed.

Help

Complete a Codex32 Book checksum worksheet.
Requires an interactive terminal and two matching entries.

Proposed warning

DANGER: Incorrect input can cause permanent loss of funds.
Follow the Codex32 Book procedure and its Dice De-biasing Worksheet exactly.
This command cannot verify how your data was generated.
Do not enter raw dice rolls, seed words, hexadecimal seeds, or passwords.

Prompts, separated by terminal clearing

Checksum worksheet non-pink bold squares:

> MS1

Re-enter the worksheet non-pink bold squares:

> MS1

Input errors

ms32 checksum: The input does not match the expected format of the filled-out non-pink bold squares.
Consult the Codex32 Book and check the worksheet.

ms32 checksum: No input was provided.

Would you keep this command or remove user-facing checksum completion? What about for a GUI? My concern is users may checksum low entropy data or replace a damaged backup’s checksum.

[BenWestgate]

Slightly related,ms32 correct produces a warning when less than 5-bits of checksum discrimination remain for the candidate. That includes 13 or 15 contiguous erasures and possibly some other correction classes. I refuse to show corrections that exceed the checksums' discrimination i.e. 14/16 erasures.

This is because filling erasures is effectively the checksum command. But it's also important users know the correction is unreliable as it has BIP39 levels of error detection left.

[apoelstra]

My concern is users may checksum low entropy data or replace a damaged backup’s checksum.

Yeah. So, if they're starting with low entropy data there's not too much we can do. But I don't think users will be fooled into thinking that the checksum somehow makes "insecure data" into "secure data".

I do think users will be fooled into thinking that they can take data with poor integrity (or data which is actually wrong/corrupted) and then "restore it" by using the checksum generation. I agree it seems plausible that users would drop a checksum that doesn't validate then attempt to "restore it".

So my proposal is:

• Keep your angry red warnings when the user tries to correct something with too many errors/erasures.
• Drop an explicit "checksum completer" but maybe suggest to users somewhere that they can do the same thing by just putting 13 erasures at the end of their data (and then the existing warning will yell at them). If we make this suggestion we should emphasize that users should NOT attempt to delete and replace a checksum on existing data, since this will only "lock in" the actual errors.

We should also extend the "are you recovering" warning. I think we should say something like:

If you are generating new data and attempting to fill in the missing squares to complete a checksum,
ensure that you have transcribed the data **exactly as it will be used**. There is no way to detect
or correct transcription errors, so any errors you have made up to this point will be "locked in" by
completing the checksum.

If you are recovering data with this many missing characters, understand that the completion may
be incorrect and you may need to resort to other methods (e.g. grinding through possible typos)
to recover you data.

If you understand this, type YES to attempt to correct the data.

[scgbckbone]

Drop an explicit "checksum completer" but maybe suggest to users somewhere that they can do the same thing by just putting 13 erasures at the end of their data

this is same as providing checksum calculator but with worse UI.

Even tho I agree there exist some "footguns", calculating checksum is very useful (as hand calculation is extremely tedious). Not just to calculate it, but also to verify your hand calculation.

[apoelstra]

this is same as providing checksum calculator but with worse UI.

Yes. But the "worse UI" forces the user to think through what they're doing. That is, if they have a string whose checksum doesn't pass, they should see something "obviously wrong" with telling the computer that they have 13 erasures at the end of the string. Versus deleting the checksum and regenerate it, which might feel like a sensible "just reboot it and see if the problem goes away" solution.

to verify your hand calculation.

You can do this by just typing the complete checksummed string into the checksum validator.

[scgbckbone]

You can do this by just typing the complete checksummed string into the checksum validator.

correct - so only useful for those that do not want to do hand calculation for csum

[BenWestgate]

only useful for those that do not want to do hand calculation for csum

It's possible to split the work:

• create the randomness and checksum by hand, verify the checksum by machine; or
• create the randomness and/or checksum by electronics, verify it by hand.

The first flow makes a lot more sense, gives assurances against electronic bugs/malice and fits the book better:

[scgbckbone]

One concrete finding from our implementation that can be useful for others: our calculator first validates the input as a complete checksummed string. If valid, it returns it unchanged. If validation fails, it tries treating the input as a header and payload without a checksum.

The problem is that a failed checksum does not necessarily mean the checksum is missing. A complete shorter string can have exactly the same length as a longer string without its checksum. For MS1:

• 128-bit complete ↔ 192-bit without checksum: 48 characters
• 160-bit complete ↔ 224-bit without checksum: 54 characters
• 192-bit complete ↔ 256-bit without checksum: 61 characters

A shorter string with a bad checksum can therefore be mistaken for a longer payload awaiting a checksum. The calculator absorbs the old checksum into the payload and appends a new one, producing a valid string for different wallet material. The user doesn’t even need to delete the failed checksum.

We encountered this with CW1. Coldcard/firmware#828 restricts checksum calculation to MS1. Our supported MS1 sizes—128/256/512 bits—have no such overlap. A calculator supporting all the lengths listed above would need to account for this ambiguity. Our calculator only allows the lengths that we support (128/256/512)

[BenWestgate]

a failed checksum does not necessarily mean the checksum is missing.

a "valid checksum" does not necessarily mean the checksum is not missing.

I'm very confused why a checksum verifier needs to be part of a checksum creator or vice versa.