| 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 | 4 | ▶ | use v5.36; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 19 | |||||||||||||||||||||||||||||
| 20 | package Protocol::HAP::Crypto; | ||||||||||||||||||||||||||||
| 21 | 4 | our $VERSION = '0.1.0'; | |||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | # Protocol::HAP::Crypto - randomness and the primitives that the HAP | ||||||||||||||||||||||||||||
| 24 | # protocol needs. | ||||||||||||||||||||||||||||
| 25 | # | ||||||||||||||||||||||||||||
| 26 | # Every method is a class method. The module keeps no state and never | ||||||||||||||||||||||||||||
| 27 | # logs. A programming error dies; there is no partial result and no | ||||||||||||||||||||||||||||
| 28 | # quiet fallback, because a caller cannot recover from a key that is | ||||||||||||||||||||||||||||
| 29 | # not a key. | ||||||||||||||||||||||||||||
| 30 | # | ||||||||||||||||||||||||||||
| 31 | # random_bytes uses core Perl only. The signature, key-agreement and | ||||||||||||||||||||||||||||
| 32 | # AEAD groups load their Crypt::* library on first use, so a program | ||||||||||||||||||||||||||||
| 33 | # that never signs anything never needs them installed. | ||||||||||||||||||||||||||||
| 34 | # | ||||||||||||||||||||||||||||
| 35 | # The read from /dev/urandom is a documented exception to the sans-IO | ||||||||||||||||||||||||||||
| 36 | # rule of Protocol::HAP: key material must come from the kernel. | ||||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | 4 | ▶ | use constant URANDOM_PATH => '/dev/urandom'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 39 | |||||||||||||||||||||||||||||
| 40 | # Which library each function group needs. The failure message names | ||||||||||||||||||||||||||||
| 41 | # the module and the group, so an operator knows what to install and | ||||||||||||||||||||||||||||
| 42 | # why. | ||||||||||||||||||||||||||||
| 43 | 4 | my %GROUP = ( | |||||||||||||||||||||||||||
| 44 | ed25519 => 'Crypt::Ed25519', | ||||||||||||||||||||||||||||
| 45 | x25519 => 'Crypt::Curve25519', | ||||||||||||||||||||||||||||
| 46 | hkdf => 'Crypt::KeyDerivation', | ||||||||||||||||||||||||||||
| 47 | aead => 'Crypt::AuthEnc::ChaCha20Poly1305', | ||||||||||||||||||||||||||||
| 48 | ); | ||||||||||||||||||||||||||||
| 49 | |||||||||||||||||||||||||||||
| 50 | 4 | my %loaded; | |||||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||||||
| 52 | # $class->random_bytes($length): | ||||||||||||||||||||||||||||
| 53 | # Return $length bytes from /dev/urandom. | ||||||||||||||||||||||||||||
| 54 | # | ||||||||||||||||||||||||||||
| 55 | # The method dies when the device does not open, and dies on a | ||||||||||||||||||||||||||||
| 56 | # short read. Neither one has a recovery: a caller that continues | ||||||||||||||||||||||||||||
| 57 | # with fewer bytes than it asked for builds a key with a known | ||||||||||||||||||||||||||||
| 58 | # prefix. | ||||||||||||||||||||||||||||
| 59 | 30 | ▶ | sub random_bytes ( $class, $length ) | ||||||||||||||||||||||||||
|
Subroutine
random_bytes: called CC=7 SCAR=20.5
Pod
documented
| |||||||||||||||||||||||||||||
| 60 | { | ||||||||||||||||||||||||||||
| 61 | 30 | ▶ | die 'random_bytes needs a positive length' | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $length and $length > 0
MC/DC100%2/2
defined $length and $length > 0
defined $length
$length > 0
Truth table100%3/3
A and B
A= defined $lengthB= $length > 0
| |||||||||||||||||||||||||||||
| 62 | unless defined $length && $length > 0; | ||||||||||||||||||||||||||||
| 63 | |||||||||||||||||||||||||||||
| 64 | 27 | ▶ | open my $fh, '<', URANDOM_PATH | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 65 | or die 'Cannot open ' . URANDOM_PATH . ": $!"; | ||||||||||||||||||||||||||||
| 66 | 27 | binmode $fh; | |||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||
| 68 | 27 | my $bytes = ''; | |||||||||||||||||||||||||||
| 69 | 27 | ▶ | while ( length($bytes) < $length ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 70 | 27 | my $n = read $fh, my $chunk, $length - length($bytes); | |||||||||||||||||||||||||||
| 71 | 27 | ▶ | if ( !defined $n ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 72 | 0 | close $fh; | |||||||||||||||||||||||||||
| 73 | 0 | die 'Cannot read ' . URANDOM_PATH . ": $!"; | |||||||||||||||||||||||||||
| 74 | } | ||||||||||||||||||||||||||||
| 75 | 27 | ▶ | if ( $n == 0 ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 76 | 0 | close $fh; | |||||||||||||||||||||||||||
| 77 | 0 | die 'Short read from ' | |||||||||||||||||||||||||||
| 78 | . URANDOM_PATH | ||||||||||||||||||||||||||||
| 79 | . ': got ' | ||||||||||||||||||||||||||||
| 80 | . length($bytes) | ||||||||||||||||||||||||||||
| 81 | . ", expected $length"; | ||||||||||||||||||||||||||||
| 82 | } | ||||||||||||||||||||||||||||
| 83 | 27 | $bytes .= $chunk; | |||||||||||||||||||||||||||
| 84 | } | ||||||||||||||||||||||||||||
| 85 | 27 | close $fh; | |||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | 27 | return $bytes; | |||||||||||||||||||||||||||
| 88 | } | ||||||||||||||||||||||||||||
| 89 | |||||||||||||||||||||||||||||
| 90 | # $class->preload: | ||||||||||||||||||||||||||||
| 91 | # Load every Crypt::* library now. A daemon that pledges without | ||||||||||||||||||||||||||||
| 92 | # prot_exec must call this before it pledges: a lazy require | ||||||||||||||||||||||||||||
| 93 | # after the pledge dlopens a shared object, and that kills the | ||||||||||||||||||||||||||||
| 94 | # process. | ||||||||||||||||||||||||||||
| 95 | # | ||||||||||||||||||||||||||||
| 96 | # The method returns the number of libraries it loaded. It dies | ||||||||||||||||||||||||||||
| 97 | # when one is missing, because a daemon that discovers a missing | ||||||||||||||||||||||||||||
| 98 | # library after the pledge cannot report it. | ||||||||||||||||||||||||||||
| 99 | 0 | ▶ | sub preload ($class) | ||||||||||||||||||||||||||
|
Subroutine
preload: not called CC=3 SCAR=24.8
Pod
documented
| |||||||||||||||||||||||||||||
| 100 | { | ||||||||||||||||||||||||||||
| 101 | 0 | my $count = 0; | |||||||||||||||||||||||||||
| 102 | 0 | for my $group ( sort keys %GROUP ) { | |||||||||||||||||||||||||||
| 103 | 0 | ▶ | $count++ unless $loaded{$group}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 104 | 0 | _load($group); | |||||||||||||||||||||||||||
| 105 | } | ||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||
| 107 | 0 | return $count; | |||||||||||||||||||||||||||
| 108 | } | ||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||
| 110 | # $class->ed25519_keypair: | ||||||||||||||||||||||||||||
| 111 | # Return ($secret_key, $public_key) for a fresh Ed25519 identity. | ||||||||||||||||||||||||||||
| 112 | 0 | ▶ | sub ed25519_keypair ($class) | ||||||||||||||||||||||||||
|
Subroutine
ed25519_keypair: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 113 | { | ||||||||||||||||||||||||||||
| 114 | 0 | _load('ed25519'); | |||||||||||||||||||||||||||
| 115 | |||||||||||||||||||||||||||||
| 116 | 0 | my ( $public, $secret ) = Crypt::Ed25519::generate_keypair(); | |||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||
| 118 | 0 | return ( $secret, $public ); | |||||||||||||||||||||||||||
| 119 | } | ||||||||||||||||||||||||||||
| 120 | |||||||||||||||||||||||||||||
| 121 | # $class->ed25519_sign($message, $secret_key, $public_key): | ||||||||||||||||||||||||||||
| 122 | # Return the 64-byte signature over $message. | ||||||||||||||||||||||||||||
| 123 | 0 | ▶ | sub ed25519_sign ( $class, $message, $secret_key, $public_key ) | ||||||||||||||||||||||||||
|
Subroutine
ed25519_sign: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 124 | { | ||||||||||||||||||||||||||||
| 125 | 0 | _load('ed25519'); | |||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||
| 127 | 0 | return Crypt::Ed25519::sign( $message, $public_key, $secret_key ); | |||||||||||||||||||||||||||
| 128 | } | ||||||||||||||||||||||||||||
| 129 | |||||||||||||||||||||||||||||
| 130 | # $class->ed25519_verify($signature, $message, $public_key): | ||||||||||||||||||||||||||||
| 131 | # Report if the signature is valid for the message and the key. | ||||||||||||||||||||||||||||
| 132 | 0 | ▶ | sub ed25519_verify ( $class, $signature, $message, $public_key ) | ||||||||||||||||||||||||||
|
Subroutine
ed25519_verify: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 133 | { | ||||||||||||||||||||||||||||
| 134 | 0 | _load('ed25519'); | |||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||
| 136 | 0 | return Crypt::Ed25519::verify( $message, $public_key, $signature ); | |||||||||||||||||||||||||||
| 137 | } | ||||||||||||||||||||||||||||
| 138 | |||||||||||||||||||||||||||||
| 139 | # $class->x25519_keypair: | ||||||||||||||||||||||||||||
| 140 | # Return ($secret_key, $public_key) for a fresh X25519 exchange. | ||||||||||||||||||||||||||||
| 141 | 0 | ▶ | sub x25519_keypair ($class) | ||||||||||||||||||||||||||
|
Subroutine
x25519_keypair: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 142 | { | ||||||||||||||||||||||||||||
| 143 | 0 | _load('x25519'); | |||||||||||||||||||||||||||
| 144 | |||||||||||||||||||||||||||||
| 145 | 0 | my $secret = | |||||||||||||||||||||||||||
| 146 | Crypt::Curve25519::curve25519_secret_key( | ||||||||||||||||||||||||||||
| 147 | $class->random_bytes(32) ); | ||||||||||||||||||||||||||||
| 148 | 0 | my $public = Crypt::Curve25519::curve25519_public_key($secret); | |||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||
| 150 | 0 | return ( $secret, $public ); | |||||||||||||||||||||||||||
| 151 | } | ||||||||||||||||||||||||||||
| 152 | |||||||||||||||||||||||||||||
| 153 | # $class->x25519_shared_secret($our_secret, $their_public): | ||||||||||||||||||||||||||||
| 154 | # Return the 32-byte shared secret of the exchange. | ||||||||||||||||||||||||||||
| 155 | 0 | ▶ | sub x25519_shared_secret ( $class, $our_secret, $their_public ) | ||||||||||||||||||||||||||
|
Subroutine
x25519_shared_secret: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 156 | { | ||||||||||||||||||||||||||||
| 157 | 0 | _load('x25519'); | |||||||||||||||||||||||||||
| 158 | |||||||||||||||||||||||||||||
| 159 | 0 | return Crypt::Curve25519::curve25519_shared_secret( $our_secret, | |||||||||||||||||||||||||||
| 160 | $their_public ); | ||||||||||||||||||||||||||||
| 161 | } | ||||||||||||||||||||||||||||
| 162 | |||||||||||||||||||||||||||||
| 163 | # $class->hkdf_sha512($ikm, $salt, $info, $length): | ||||||||||||||||||||||||||||
| 164 | # Derive $length bytes with HKDF over SHA-512. | ||||||||||||||||||||||||||||
| 165 | 0 | ▶ | sub hkdf_sha512 ( $class, $ikm, $salt, $info, $length ) | ||||||||||||||||||||||||||
|
Subroutine
hkdf_sha512: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||
| 166 | { | ||||||||||||||||||||||||||||
| 167 | 0 | _load('hkdf'); | |||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||
| 169 | 0 | return Crypt::KeyDerivation::hkdf( $ikm, $salt, 'SHA512', $length, | |||||||||||||||||||||||||||
| 170 | $info ); | ||||||||||||||||||||||||||||
| 171 | } | ||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||
| 173 | # $class->chacha20poly1305_encrypt($key, $nonce, $plaintext, $aad): | ||||||||||||||||||||||||||||
| 174 | # Return ($ciphertext, $tag). | ||||||||||||||||||||||||||||
| 175 | 0 | ▶ | sub chacha20poly1305_encrypt ( $class, $key, $nonce, $plaintext, $aad = '' ) | ||||||||||||||||||||||||||
|
Subroutine
chacha20poly1305_encrypt: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||
| 176 | { | ||||||||||||||||||||||||||||
| 177 | 0 | _load('aead'); | |||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||
| 179 | 0 | my ( $ciphertext, $tag ) = | |||||||||||||||||||||||||||
| 180 | Crypt::AuthEnc::ChaCha20Poly1305::chacha20poly1305_encrypt_authenticate( | ||||||||||||||||||||||||||||
| 181 | $key, $nonce, $aad, $plaintext ); | ||||||||||||||||||||||||||||
| 182 | |||||||||||||||||||||||||||||
| 183 | 0 | return ( $ciphertext, $tag ); | |||||||||||||||||||||||||||
| 184 | } | ||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||
| 186 | # $class->chacha20poly1305_decrypt($key, $nonce, $ciphertext, $tag, $aad): | ||||||||||||||||||||||||||||
| 187 | # Return the plaintext, or undef when the tag does not verify. A | ||||||||||||||||||||||||||||
| 188 | # failed verification is the normal answer for a forged or | ||||||||||||||||||||||||||||
| 189 | # damaged message, so it is not fatal. | ||||||||||||||||||||||||||||
| 190 | 0 | ▶ | sub chacha20poly1305_decrypt ( $class, $key, $nonce, $ciphertext, $tag, | ||||||||||||||||||||||||||
|
Subroutine
chacha20poly1305_decrypt: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||
| 191 | 0 | $aad = '' ) | |||||||||||||||||||||||||||
| 192 | { | ||||||||||||||||||||||||||||
| 193 | 0 | _load('aead'); | |||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||
| 195 | return | ||||||||||||||||||||||||||||
| 196 | 0 | Crypt::AuthEnc::ChaCha20Poly1305::chacha20poly1305_decrypt_verify( | |||||||||||||||||||||||||||
| 197 | $key, $nonce, $aad, $ciphertext, $tag ); | ||||||||||||||||||||||||||||
| 198 | } | ||||||||||||||||||||||||||||
| 199 | |||||||||||||||||||||||||||||
| 200 | # _load($group): | ||||||||||||||||||||||||||||
| 201 | # Load the library that a function group needs, once. The failure | ||||||||||||||||||||||||||||
| 202 | # names the module and the group, because "Can't locate | ||||||||||||||||||||||||||||
| 203 | # Crypt/Ed25519.pm in @INC" tells an operator nothing about which | ||||||||||||||||||||||||||||
| 204 | # feature stopped working. | ||||||||||||||||||||||||||||
| 205 | 0 | ▶ | sub _load ($group) | ||||||||||||||||||||||||||
|
Subroutine
_load: not called CC=4 SCAR=30.0
| |||||||||||||||||||||||||||||
| 206 | { | ||||||||||||||||||||||||||||
| 207 | 0 | ▶ | return 1 if $loaded{$group}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||
| 209 | 0 | ▶ | my $module = $GROUP{$group} // die "Unknown crypto group: $group"; | ||||||||||||||||||||||||||
|
Condition0%0/2
$GROUP{$group} // die("Unknown crypto group: $group")
MC/DC0%0/1
$GROUP{$group} // die("Unknown crypto group: $group")
$GROUP{$group}
Truth table0%0/2
A
A= $GROUP{$group}
| |||||||||||||||||||||||||||||
| 210 | 0 | my $path = $module =~ s{::}{/}gr . '.pm'; | |||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||
| 212 | 0 | ▶ | eval { require $path; 1 } | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 213 | or die | ||||||||||||||||||||||||||||
| 214 | "Protocol::HAP::Crypto needs $module for $group operations: $@"; | ||||||||||||||||||||||||||||
| 215 | |||||||||||||||||||||||||||||
| 216 | 0 | $loaded{$group} = 1; | |||||||||||||||||||||||||||
| 217 | |||||||||||||||||||||||||||||
| 218 | 0 | return 1; | |||||||||||||||||||||||||||
| 219 | } | ||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||
| 221 | 4 | 1; | |||||||||||||||||||||||||||