| 1 | # ex:ts=8 sw=4: | ||||||||||
| 2 | # $OpenBSD$ | ||||||||||
| 3 | # | ||||||||||
| 4 | # Copyright (c) 2026 Dick Olsson <hi@senzilla.io> | ||||||||||
| 5 | # | ||||||||||
| 6 | # Permission to use, copy, modify, and distribute this software for any | ||||||||||
| 7 | # purpose with or without fee is hereby granted, provided that the above | ||||||||||
| 8 | # copyright notice and this permission notice appear in all copies. | ||||||||||
| 9 | # | ||||||||||
| 10 | # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||||||||||
| 11 | # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||||||||||
| 12 | # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||||||||||
| 13 | # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||||||||||
| 14 | # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||||||||||
| 15 | # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||||||||||
| 16 | # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||||||||||
| 17 | |||||||||||
| 18 | package App::FuguSeed::Mnemonic; | ||||||||||
| 19 | 2 | our $VERSION = '0.2.0'; | |||||||||
| 20 | |||||||||||
| 21 | 2 | ▶ | use v5.34; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 22 | 2 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 23 | 2 | ▶ | use experimental 'signatures'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 24 | 2 | ▶ | no feature qw(indirect multidimensional bareword_filehandles); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 25 | |||||||||||
| 26 | 2 | ▶ | use Digest::SHA (); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 27 | |||||||||||
| 28 | 2 | ▶ | use App::FuguSeed::List (); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 29 | |||||||||||
| 30 | # App::FuguSeed::Mnemonic - the word checks and the BIP39 checksum. | ||||||||||
| 31 | # | ||||||||||
| 32 | # The module proves the count and the list membership of the words | ||||||||||
| 33 | # (QR-MNEMONIC-1, LAST-WORD-1), it gives the index of each word, and | ||||||||||
| 34 | # it computes the BIP39 checksum (QR-MNEMONIC-2, LAST-WORD-4). It | ||||||||||
| 35 | # holds the parts that fuguseed-last and fuguseed-qr both call, and | ||||||||||
| 36 | # no other part. | ||||||||||
| 37 | # | ||||||||||
| 38 | # Every method is a class method, and every method is pure: it takes | ||||||||||
| 39 | # values and it returns values. The module touches no stream. A | ||||||||||
| 40 | # caller gets the failure message and prints it, and the message | ||||||||||
| 41 | # names a count or a word position, never a word (SEC-CHANNELS-2). | ||||||||||
| 42 | # | ||||||||||
| 43 | # The module runs on core perl v5.34 with Digest::SHA alone, because | ||||||||||
| 44 | # scripts/pack embeds it in fuguseed-last and fuguseed-qr (D-07). | ||||||||||
| 45 | |||||||||||
| 46 | # INDEX_BITS: | ||||||||||
| 47 | # The bit width of one word index. The list holds 2048 words, | ||||||||||
| 48 | # so an index needs 11 bits (BIP39). | ||||||||||
| 49 | 2 | ▶ | use constant INDEX_BITS => 11; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 50 | |||||||||||
| 51 | # ENTROPY_BITS: | ||||||||||
| 52 | # The entropy bits of 12 words. The 12 indexes give 132 bits, | ||||||||||
| 53 | # and the 4 bits after the entropy are the checksum (BIP39). | ||||||||||
| 54 | 2 | ▶ | use constant ENTROPY_BITS => 128; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 55 | |||||||||||
| 56 | # CHECKSUM_BITS: | ||||||||||
| 57 | # The checksum bits of 12 words (BIP39). The RED column of the | ||||||||||
| 58 | # word sheet carries them, because it gives the low 4 bits of | ||||||||||
| 59 | # an index (D-05). | ||||||||||
| 60 | 2 | ▶ | use constant CHECKSUM_BITS => 4; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 61 | |||||||||||
| 62 | # $class->fault($words, $count): | ||||||||||
| 63 | # The failure message for the words of the array reference | ||||||||||
| 64 | # $words, or undef when they are $count words of the list. The | ||||||||||
| 65 | # message names a count or a word position, never a word. | ||||||||||
| 66 | 40 | ▶ | sub fault ( $, $words, $count ) | ||||||||
|
Subroutine
fault: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||
| 67 | { | ||||||||||
| 68 | 40 | my $found = scalar @{$words}; | |||||||||
| 69 | 40 | ▶ | return "the input holds $found words, not $count" | ||||||||
|
Branch: 1 branch
| |||||||||||
| 70 | if $found != $count; | ||||||||||
| 71 | |||||||||||
| 72 | 36 | for my $position ( 1 .. $count ) { | |||||||||
| 73 | 414 | my $index = | |||||||||
| 74 | App::FuguSeed::List->index( $words->[ $position - 1 ] ); | ||||||||||
| 75 | 414 | ▶ | return "word $position is not in the word list" | ||||||||
|
Branch: 1 branch
| |||||||||||
| 76 | unless defined $index; | ||||||||||
| 77 | } | ||||||||||
| 78 | |||||||||||
| 79 | 33 | return; | |||||||||
| 80 | } | ||||||||||
| 81 | |||||||||||
| 82 | # $class->indexes($words): | ||||||||||
| 83 | # The 0-based list index of each word. The caller proves the | ||||||||||
| 84 | # words with fault first. | ||||||||||
| 85 | 327 | ▶ | sub indexes ( $, $words ) | ||||||||
|
Subroutine
indexes: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 86 | { | ||||||||||
| 87 | 327 | return map { App::FuguSeed::List->index($_) } @{$words}; | |||||||||
| 88 | } | ||||||||||
| 89 | |||||||||||
| 90 | # $class->checksum(@index): | ||||||||||
| 91 | # The 4 checksum bits of the 12 indexes @index, as a number. | ||||||||||
| 92 | # The 12 indexes give 132 bits, and the first 128 bits are the | ||||||||||
| 93 | # entropy. BIP39 takes the checksum from the first bits of the | ||||||||||
| 94 | # SHA-256 of the 16 entropy bytes. The low 4 bits of index 12 | ||||||||||
| 95 | # are no part of the entropy, so they do not change the result. | ||||||||||
| 96 | 321 | ▶ | sub checksum ( $, @index ) | ||||||||
|
Subroutine
checksum: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 97 | { | ||||||||||
| 98 | 321 | my $bits = join q{}, map { sprintf '%0' . INDEX_BITS . 'b', $_ } @index; | |||||||||
| 99 | 321 | my $entropy = pack 'B' . ENTROPY_BITS, substr( $bits, 0, ENTROPY_BITS ); | |||||||||
| 100 | 321 | my $digest = Digest::SHA::sha256($entropy); | |||||||||
| 101 | |||||||||||
| 102 | 321 | return ord( substr $digest, 0, 1 ) >> ( 8 - CHECKSUM_BITS ); | |||||||||
| 103 | } | ||||||||||
| 104 | |||||||||||
| 105 | 2 | 1; | |||||||||