hare

commit c04278f9b7e7ef9f6a050360c2588547f114c029
parent 6f31c96a2c7502616e8c41e69f23e98528e4015e
Author: Armin Preiml <apreiml@strohwolke.at>
Date:   Tue,  7 May 2024 14:46:07 +0200

crypto::ec: improve doc on curve parameters

Signed-off-by: Armin Preiml <apreiml@strohwolke.at>

Diffstat:
M
crypto/ec/p256.ha
 | 
8
++++++--
M
crypto/ec/prime.ha
 | 
16
++++++++++++----
M
crypto/ec/types.ha
 | 
24
+++++++++++++++++-------

3 files changed, 35 insertions(+), 13 deletions(-)
diff --git a/crypto/ec/p256.ha b/crypto/ec/p256.ha
@@ -1242,10 +1242,14 @@ const _p256: curve = curve {
 };
 
 // Size of a [[p256]] point in bytes.
-export def P256_POINTSZ = len(P256_G);
+export def P256_POINTSZ = 65;
 
 // Size of a [[p256]] scalar in bytes.
-export def P256_SCALARSZ = len(P256_N);
+export def P256_SCALARSZ = 32;
 
 // A [[curve]] implementation of P-256, also known as secp256r1 or prime256v1.
+//
+// The point size is defined by [[P256_POINTSZ]] and the scalar size is defined
+// by [[P256_SCALARSZ]. See the documentation of [[curve]] on how to encode
+// such values.
 export const p256: *curve = &_p256;
diff --git a/crypto/ec/prime.ha b/crypto/ec/prime.ha
@@ -697,12 +697,16 @@ const _p384: curve = curve {
 };
 
 // Size of a [[p384]] point in bytes.
-export def P384_POINTSZ = len(P384_G);
+export def P384_POINTSZ = 97;
 
 // Size of a [[p384]] scalar in bytes.
-export def P384_SCALARSZ = len(P384_N);
+export def P384_SCALARSZ = 48;
 
 // A [[curve]] implementation of P-384, also known as secp384r1;
+//
+// The point size is defined by [[P384_POINTSZ]] and the scalar size is defined
+// by [[P384_SCALARSZ]. See the documentation of [[curve]] on how to encode
+// such values.
 export const p384: *curve = &_p384;
 
 const P521_N: [_]u8 = [
@@ -759,10 +763,14 @@ const _p521: curve = curve {
 };
 
 // Size of a [[p521]] point in bytes.
-export def P521_POINTSZ = len(P521_G);
+export def P521_POINTSZ = 133;
 
 // Size of a [[p521]] scalar in bytes.
-export def P521_SCALARSZ = len(P521_N);
+export def P521_SCALARSZ = 66;
 
 // A [[curve]] implementation of P-521, also known as secp521r1;
+//
+// The point size is defined by [[P521_POINTSZ]] and the scalar size is defined
+// by [[P521_SCALARSZ]. See the documentation of [[curve]] on how to encode
+// such values.
 export const p521: *curve = &_p521;
diff --git a/crypto/ec/types.ha b/crypto/ec/types.ha
@@ -14,14 +14,18 @@ export def MAX_SCALARSZ = P521_SCALARSZ;
 
 // Interface for common operations over a specific curve.
 //
-// The encoding of points depends on the curve. For the NIST curves
-// ([[p256]], [[p384]] and [[p521]] the point is required to be
-// uncompressed with a leading byte of value 0x04. The coordinates must be of
-// length 'pointsz' / 2, left padded by 0x0.
+// The encoding of points (e.g. public keys for dsa and dh) depends on the curve.
+// For the NIST curves ([[p256]], [[p384]] and [[p521]]) the point is required
+// to be stored according to the uncompressed format defined in RFC 8422 Chapter
+// 5.4.1. That means with a leading byte of value 0x04 that indicates the
+// format. Followed by the x and y coordinates, which must be of length
+// [[pointsz]] / 2, left padded by 0.
 //
-// Scalar values must be provided in big-endian encoding. They MUST be non zero
-// and less than the order, otherwise result values will be indeterminate and
-// an error code is not guaranteed.
+// Scalar values (e.g. private keys for dsa and dh) must be provided in
+// big-endian encoding and left-padded to fill the indicated space. They MUST be
+// non-zero and less than the curve order, otherwise result values will be
+// indeterminate and an error code is not guaranteed. The function [[scalarsz]]
+// will return the encoded scalar size of any curve implemented by this module.
 export type curve = struct {
 	// Size in bytes of an encoded point.
 	pointsz: size,
@@ -67,5 +71,11 @@ export type curve = struct {
 	keygen: *fn (c: *curve, priv: []u8, rand: io::handle) (size | io::error),
 };
 
+// Returns the encoded size of any point of curve 'c'.
+export fn pointsz(c: *curve) size = c.pointsz;
+
+// Returns the encoded size of any scalar of curve 'c'.
+export fn scalarsz(c: *curve) size = len(c.order());
+
 // Invalid curve parameter.
 export type invalid = !void;