@darkbio/crypto 0.19.1 → 0.20.0

package/README.md

@@ -60,10 +60,17 @@ await cose.verifyDetached(signature, cbor.text.value("payload"), signer.publicKe
 // Sign and encrypt a payload to the recipient, then open and verify it back.
 // The second argument is authenticated but must be supplied separately.
 const metadata = cbor.text.value("metadata");
-const sealed = await cose.seal(cbor.text.value("payload"), metadata, signer, recipient.publicKey(), domain);
+const padding = cose.Padding.buckets({ floor: 8192, step: 20 });
+const sealed = await cose.seal(cbor.text.value("payload"), metadata, signer, recipient.publicKey(), domain, padding);
 const opened = await cose.open(cbor.text.bytes(sealed), metadata, recipient, signer.publicKey(), domain, 60);
 ```
 
+`cose.seal` and `cose.encrypt` take a `cose.Padding` policy after the domain. `cose.Padding.none()` adds no padding. Buckets pad the signed envelope with zeros inside the encryption, to the smallest of a series of sizes that starts at `floor` bytes and grows by `1/step` of each, rounded up. The example's first sizes are 8,192, 8,602 and 9,033 bytes.
+
+Both bucket parameters must be integers from 1 to 4,294,967,295, or `cose.Padding.buckets` throws.
+
+`cose.open` and `cose.decrypt` need no policy. They strip any number of zero bytes after the signed envelope and refuse a nonzero byte.
+
 ## Native packages
 
 The underlying implementation exists in two sibling repos, which track the same feature set and API surfaces, released at corresponding version points.

package/dist/cose.d.ts

@@ -1,6 +1,30 @@
 import { Decodable, Encodable } from './cbor.js';
 import { SecretKey as XdsaSecretKey, PublicKey as XdsaPublicKey, Fingerprint as XdsaFingerprint } from './xdsa.js';
 import { SecretKey as XhpkeSecretKey, PublicKey as XhpkePublicKey, Fingerprint as XhpkeFingerprint } from './xhpke.js';
+/**
+ * How many zero bytes a sender appends to the signed envelope inside the
+ * encryption, so the ciphertext's length shows little about the message.
+ *
+ * Receivers strip any number of zeros, so the policy is the sender's alone and
+ * can change without them.
+ */
+export declare class Padding {
+    private readonly build;
+    private constructor();
+    /** No padding: the plaintext is the signed envelope alone. */
+    static none(): Padding;
+    /**
+     * Zeros after the signed envelope, up to the smallest size that fits. Sizes
+     * start at `floor`, and each next one is the previous one plus `1/step` of
+     * it, rounded up.
+     *
+     * @throws If `floor` or `step` is not an integer from 1 to 4,294,967,295
+     */
+    static buckets({ floor, step }: {
+        floor: number;
+        step: number;
+    }): Padding;
+}
 /**
  * Creates a COSE_Sign1 signature with an embedded payload.
  *
@@ -119,12 +143,14 @@ export declare function recipient(ciphertext: Uint8Array): Promise<XhpkeFingerpr
  * @param signerKey - The xDSA secret key to sign with
  * @param recipientKey - The xHPKE public key to encrypt to
  * @param domain - Application domain for HPKE key derivation
+ * @param padding - Sender's policy for zeros after the signed envelope
  * @returns The serialized COSE_Encrypt0 envelope holding the encrypted
  *   COSE_Sign1
  * @throws CodecError if a message does not fit its codec
  * @throws If a message falls outside the restricted CBOR type system
+ * @throws If `padding` is not a {@link Padding}
  */
-export declare function seal<S, A>(msgToSeal: Encodable<S>, msgToAuth: Encodable<A>, signerKey: XdsaSecretKey, recipientKey: XhpkePublicKey, domain: Uint8Array): Promise<Uint8Array>;
+export declare function seal<S, A>(msgToSeal: Encodable<S>, msgToAuth: Encodable<A>, signerKey: XdsaSecretKey, recipientKey: XhpkePublicKey, domain: Uint8Array, padding: Padding): Promise<Uint8Array>;
 /**
  * Decrypts and verifies a sealed message.
  *
@@ -158,10 +184,12 @@ export declare function open<T, A>(msgToOpen: Decodable<T>, msgToAuth: Encodable
  * @param msgToAuth - The same additional authenticated data used during sealing
  * @param recipientKey - The xHPKE public key to encrypt to
  * @param domain - Application domain for HPKE key derivation
+ * @param padding - Sender's policy for zeros after the signed envelope
  * @returns The serialized COSE_Encrypt0 envelope
  * @throws CodecError if `msgToAuth` does not fit its codec
+ * @throws If `padding` is not a {@link Padding}
  */
-export declare function encrypt<A>(sign1: Uint8Array, msgToAuth: Encodable<A>, recipientKey: XhpkePublicKey, domain: Uint8Array): Promise<Uint8Array>;
+export declare function encrypt<A>(sign1: Uint8Array, msgToAuth: Encodable<A>, recipientKey: XhpkePublicKey, domain: Uint8Array, padding: Padding): Promise<Uint8Array>;
 /**
  * Decrypts a sealed message without verifying the signature.
  *
@@ -169,13 +197,16 @@ export declare function encrypt<A>(sign1: Uint8Array, msgToAuth: Encodable<A>, r
  * to extract the signer's fingerprint, then {@link verify} with the same
  * `msgToAuth` and `domain` to verify.
  *
+ * It strips the zero bytes after the COSE_Sign1, accepting any number of them,
+ * and returns the COSE_Sign1 as encoded.
+ *
  * @param msgToOpen - The serialized COSE_Encrypt0 envelope
  * @param msgToAuth - The same additional authenticated data used during sealing
  * @param recipientKey - The xHPKE secret key to decrypt with
  * @param domain - Application domain for HPKE key derivation
  * @returns The decrypted COSE_Sign1 envelope, not yet verified
  * @throws If the envelope is malformed or does not decrypt for this key,
- *   `msgToAuth` and `domain`
+ *   `msgToAuth` and `domain`, or a nonzero byte follows the COSE_Sign1
  * @throws CodecError if `msgToAuth` does not fit its codec
  */
 export declare function decrypt<A>(msgToOpen: Uint8Array, msgToAuth: Encodable<A>, recipientKey: XhpkeSecretKey, domain: Uint8Array): Promise<Uint8Array>;

package/dist/cose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cose.d.ts","sourceRoot":"","sources":["../src/cose.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cose.d.ts","sourceRoot":"","sources":["../src/cose.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,6 +7,8 @@
  * authenticated messages are bound to a `cbor` codec, which declares their
  * shape. The WASM module loads on the first call of any async function, so
  * there is no separate setup step.
+ * COSE sealing and encryption take a sender padding policy. Opening strips
+ * zero padding without needing that policy.
  *
  * @module
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AAEH,4DAA4D;AAC5D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,kCAAkC;AAClC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,8CAA8C;AAC9C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,yDAAyD;AACzD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,wDAAwD;AACxD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,8BAA8B;AAC9B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,uDAAuD;AACvD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,4CAA4C;AAC5C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AAEH,4DAA4D;AAC5D,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,kCAAkC;AAClC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,8CAA8C;AAC9C,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,yDAAyD;AACzD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,wDAAwD;AACxD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,8BAA8B;AAC9B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,uDAAuD;AACvD,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,4CAA4C;AAC5C,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC"}