@atlasauth/pca-abe 0.3.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @atlasauth/pca-abe
 
-Proof-carrying encryption for Proof-Carrying Authority (PCA). Tool payloads or results are sealed under an access policy over capability attributes (`holder:`, `verb:`, `resource:`, `scope:`), so they decrypt only for an agent whose PCA capability satisfies the policy. The construction is a Boneh-Franklin identity-based KEM on BLS12-381 composed over a monotone AND/OR/threshold tree by Shamir secret sharing, with the payload sealed by AES-256-GCM.
+Proof-carrying encryption for Proof-Carrying Authority (PCA). Tool payloads or results are sealed under an access policy over capability attributes (`holder:`, `verb:`, `resource:`, `scope:`, and bound `act:` verb-on-resource pairs), so they decrypt only for an agent whose PCA capability satisfies the policy. The construction is Bethencourt-Sahai-Waters ciphertext-policy ABE (IEEE S&P 2007, ePrint 2006/309) with a per-key randomiser, adapted to the asymmetric (type-3) pairing on BLS12-381, over a monotone AND/OR/threshold tree shared by Shamir secret sharing, with the payload sealed by AES-256-GCM. Keys issued to different holders cannot be pooled to satisfy a policy neither satisfies.
 
 ## Install
 
@@ -46,15 +46,30 @@ A key derived from a capability that does not satisfy the policy gets `{ ok: fal
 
 ## API
 
-- Keys: `setup`, `keygenForAttributes`, `keygenForCapability`.
+- Keys: `setup`, `keygenForAttributes`, `keygenForCapability`, `rerandomizeKey` (re-randomise a key, optionally to a subset of its attributes; needs only the public key).
 - Raw bytes/text: `encryptForPolicy`, `decrypt`, `decryptText`, `parseCiphertext`.
 - Tool payloads: `encryptToolPayload`, `decryptWithCapability`.
 - Policies: `Policy` (`{ attr }`, `{ allOf }`, `{ anyOf }`, `{ threshold, of }`), `normalizePolicy`, `satisfies`, `policyAttributes`.
-- Attributes: `Attr`, `capabilityAttributes`.
+- Attributes: `Attr`, `capabilityAttributes`. A capability with ONE predicate yields flat `verb:`/`resource:` tokens plus `act:` pair tokens; a capability with TWO OR MORE predicates yields only `act:["verb","resource"]` pairs (plus `holder:`/`scope:`), so `read /public/*` + `write /acct/42` can never open a `read /acct/42` ciphertext (red-team RT-08; breaking: policies over flat tokens for multi-predicate capabilities must move to `Attr.act`). Predicate `where` conditions and other caveats are not encoded in any token. `scope:` tokens come only from the ROOT capability's caveats: a delegated hop's own `scope` caveats are restrictions, not grants (R2-07, breaking). For a delegated capability pass the chain, `capabilityAttributes(cap, { chain, principal })` / `keygenForCapability(msk, cap, [], { chain, principal })`; without a verified chain it gets no `scope:` tokens, and (R3-09, breaking) no `act:`/`verb:`/`resource:` tokens either, because the envelope is also read from the ROOT only (a delegatee-appended `envelope` caveat is a restriction and can no longer self-grant attributes); a chain that fails verification yields no attributes.
 
 ## Status
 
-Experimental and unaudited. Confidentiality rests on the Bilinear Diffie-Hellman assumption (random-oracle model); integrity on AES-256-GCM. Policies are monotone (no negation). This binds confidentiality to possession of capability-derived keys, not to a zero-knowledge proof, and collusion resistance holds only within a single issued key: two separately issued keys could pool attributes. Issue one key per capability. The scheme is not post-quantum.
+Research-grade, unaudited. Do not make it the only control for high-value data.
+
+What holds, and under what assumptions:
+
+- Collusion resistance. Every key carries a fresh randomiser `r`, so components of different keys do not combine; pooling two holders' keys (whole, or component by component) fails. This is tested, including against a py_ecc oracle for the key and ciphertext components and the pairing equations.
+- The security notion of BSW07 is selective chosen-plaintext security (the adversary names the challenge policy before seeing the public key) in the generic bilinear group model, with the attribute hash as a random oracle. That proof is for the paper's symmetric pairing.
+
+What is not established:
+
+- The type-3 adaptation used here (which elements live in G1 and which in G2) is this package's own; it has no proof. No reduction to a standard assumption, no standard-model security.
+- No adaptive security, and no CCA security of the ABE layer. AES-256-GCM over the whole header makes tampering detectable (integrity); that is not a CCA proof.
+- The policy is public in the ciphertext (no attribute hiding). No key revocation. Whoever holds the master secret can decrypt everything. Policies are monotone (no negation).
+- Not a zero-knowledge proof: confidentiality is bound to possession of capability-derived keys. Not post-quantum (pairing based). Not constant-time (JavaScript).
+- Decryption costs one multi-pairing over the satisfied leaves; it is slower than the earlier per-attribute scheme.
+
+Breaking change from earlier 0.x: key, public key, master key and ciphertext formats changed; old material is not readable.
 
 Source and issues: https://github.com/Atlas-Authorization/pca
 

package/dist/abe.d.ts

@@ -1,64 +1,96 @@
 import { type Capability } from '@atlasauth/pca';
+import { type CapabilityAttributeOpts } from './attributes';
 import { type Policy } from './policy';
 /**
- * Proof-carrying encryption: Ciphertext-Policy attribute/policy-based encryption built from a
- * Boneh-Franklin IBE KEM on BLS12-381, composed over a monotone access structure by Shamir
- * secret-sharing (an LSSS), sealing the payload with AES-256-GCM.
+ * Proof-carrying encryption: Ciphertext-Policy Attribute-Based Encryption after Bethencourt, Sahai and
+ * Waters, "Ciphertext-Policy Attribute-Based Encryption" (IEEE S&P 2007, ePrint 2006/309; "BSW07"),
+ * Section 4, adapted to the asymmetric (type-3) pairing e: G1 x G2 -> GT of BLS12-381, with the payload
+ * sealed under AES-256-GCM. The access structure is the package's AND / OR / k-of-n tree, realised as a
+ * Shamir sharing down the tree exactly as BSW's access tree.
  *
- * CONSTRUCTION
- *   setup()             -> master key pair (s, P_pub = s*g2).
- *   keygen(attrs)       -> one BF decryption key d_A = s*H1(A) per attribute A the holder owns.
- *   encrypt(policy, m)  -> pick a random root secret S; share it down the policy's threshold tree with
- *                          Shamir (AND = n-of-n, OR = 1-of-n, threshold = k-of-n); at each leaf attribute
- *                          A, BF-encapsulate a fresh KEM key and XOR-mask that leaf's assigned share.
- *                          The content-encryption key is HKDF(S); the payload is AES-256-GCM sealed with
- *                          the whole KEM header as AAD.
- *   decrypt(key, ct)    -> at every leaf the key owns, decapsulate -> unmask that share; interpolate each
- *                          gate once >= t shares are recovered; recover S iff the key's attribute set
- *                          satisfies the policy; derive the CEK and open the AEAD. Else fail (null).
+ * CONSTRUCTION (g1, g2 the generators of G1, G2; H: {0,1}* -> G1 hash-to-curve, a random oracle)
+ *   setup()           alpha, beta <- Z_r*.   MSK = (alpha, beta).
+ *                     MPK = ( h = beta*g2 in G2,  f = beta^-1 * g1 in G1,  Y = e(g1,g2)^alpha in GT ).
+ *   keygen(S)         r <- Z_r*; for each attribute j in S, r_j <- Z_r*.
+ *                     D = ((alpha + r)/beta) * g1                                  (G1)
+ *                     D_j = r*g1 + r_j*H(j)   (G1),      D'_j = r_j*g2   (G2)     for j in S
+ *                     The per-USER randomiser r is shared by every component of one key and is what makes
+ *                     keys of different users incompatible (collusion resistance).
+ *   encrypt(T, m)     s <- Z_r*; C_0 = s*h (G2). Share s down the tree T (q_root(0) = s, Shamir per gate);
+ *                     for each leaf x with attribute j: C_x = q_x(0)*g2 (G2), C'_x = q_x(0)*H(j) (G1).
+ *                     The blinding value is K = Y^s = e(g1,g2)^(alpha*s); CEK = HKDF(K, salt).
+ *   decrypt(SK, CT)   DecryptNode at a leaf x (j in S):
+ *                         F_x = e(D_j, C_x) / e(C'_x, D'_j) = e(g1,g2)^(r*q_x(0)).
+ *                     At a gate, F_gate = prod_i F_i^{Delta_i(0)} over any t recovered children (Lagrange
+ *                     interpolation in the exponent) = e(g1,g2)^(r*q_gate(0)). At the root
+ *                         A = e(g1,g2)^(r*s),   K = e(D, C_0) / A = e(g1,g2)^((alpha+r)*s - r*s) = Y^s.
  *
- * SECURITY PROPERTY (honest)
- *   Confidentiality holds under the Bilinear Diffie-Hellman assumption on BLS12-381 in the random-oracle
- *   model (standard BF-IBE), and the Shamir sharing is information-theoretic (fewer than `t` shares of a
- *   gate reveal nothing about its secret). A holder whose attribute set does NOT satisfy the policy
- *   cannot recover enough shares to reconstruct S and therefore cannot derive the CEK. Payload and header
- *   integrity are guaranteed by AES-256-GCM.
+ * ADAPTATION TO TYPE-3 PAIRINGS (this is the package's adaptation, not a result of the BSW paper)
+ *   BSW07 is stated in a symmetric bilinear group of composite-free prime order p with a single generator g.
+ *   Here every element is assigned a fixed side so that each pairing in the scheme has one G1 and one G2
+ *   argument: D, D_j, C'_x, f, H(.) in G1; h, D'_j, C_x, C_0 in G2. The one extra public element f = g^(1/beta)
+ *   (present in BSW07's public key for Delegate) is used here for key re-randomisation and delegation
+ *   (`rerandomizeKey`). The equations above are exactly BSW07's with g replaced by g1 or g2 according to the side.
  *
- *   This is NOT a proof-of-knowledge / NIZK: it binds confidentiality to POSSESSION of capability-derived
- *   attribute keys, not to a verified proof. Like any IBE-KEM-composed access structure (as opposed to a
- *   single monolithic CP-ABE with per-key randomisation), it is collusion-resistant only within a single
- *   issued key: two SEPARATELY issued keys under the same master, each holding part of the required
- *   attributes, could in principle pool their attribute keys. Atlas issues exactly one key per capability
- *   (`keygenForCapability`), and decryption is evaluated against that one key's attribute set — so the
- *   enforced statement is precisely "this capability's authority satisfies the policy".
+ * SECURITY NOTION (honest)
+ *   BSW07 proves the scheme secure against collusion and chosen-plaintext attack in the SELECTIVE model
+ *   (the adversary commits to the challenge access structure before seeing the public key), in the GENERIC
+ *   BILINEAR GROUP model with H a random oracle (the paper's Theorem 1 is for the symmetric setting). This
+ *   package does NOT carry that proof over: the type-3 adaptation above has no proof of its own here, the
+ *   generic-group argument is not a reduction to a standard assumption, and no standard-model security is
+ *   claimed. No adaptive (full) security, no CCA security of the ABE layer (the AES-GCM tag over the whole
+ *   header makes tampering detectable, which is integrity, not a CCA proof), no key-revocation, no
+ *   attribute hiding (the policy is public in the ciphertext), and the MSK holder can decrypt everything.
+ *   Not a NIZK: confidentiality is bound to POSSESSION of capability-derived keys, not to a verified proof.
+ *   Research-grade, not independently audited.
+ *
+ *   What the construction does give, in the paper's model: two users whose attribute sets individually do
+ *   not satisfy a policy cannot combine their keys (or components of them) to decrypt it, because every
+ *   leaf recovery yields e(g1,g2)^(r*q) with the randomiser r of the key it was computed from, and the root
+ *   needs a single consistent r.
  */
-export declare const ABE_ALG = "bf-ibe-bls12381/lsss/aes-256-gcm";
+export declare const ABE_ALG = "bsw07-cpabe-bls12381-type3/lsss/aes-256-gcm";
 export interface MasterPublicKey {
     v: 1;
     curve: 'bls12-381';
-    /** b64u compressed G2 point `P_pub = s * g2`. */
-    pPub: string;
+    /** b64u compressed G2 point `h = beta * g2`. */
+    h: string;
+    /** b64u compressed G1 point `f = beta^-1 * g1` (used to re-randomise / delegate keys). */
+    f: string;
+    /** b64u 576-byte GT element `Y = e(g1, g2)^alpha`. */
+    egga: string;
 }
 export interface MasterSecretKey {
     v: 1;
     curve: 'bls12-381';
-    /** b64u 32-byte master secret scalar `s`. */
-    s: string;
+    /** b64u 32-byte master scalar `alpha`. */
+    alpha: string;
+    /** b64u 32-byte master scalar `beta`. */
+    beta: string;
+}
+/** Per-attribute key component: `D_j = r*g1 + r_j*H(j)` (G1) and `D'_j = r_j*g2` (G2). */
+export interface AttributeKey {
+    /** b64u compressed G1 point `D_j`. */
+    dj: string;
+    /** b64u compressed G2 point `D'_j`. */
+    dpj: string;
 }
 export interface DecryptionKey {
     v: 1;
     curve: 'bls12-381';
     /** The capability's bound holder key, when issued from a capability (informational). */
     holder?: string;
-    /** attribute token -> b64u compressed G1 decryption key `d_A = s * H1(A)`. */
-    attrs: Record<string, string>;
+    /** b64u compressed G1 point `D = ((alpha + r)/beta) * g1`, bound to this key's randomiser `r`. */
+    d: string;
+    /** attribute token -> its `(D_j, D'_j)` components. */
+    attrs: Record<string, AttributeKey>;
 }
-/** The KEM header: the access structure realised as a tree of per-leaf encapsulations. */
+/** The access tree: gates carry the Shamir threshold; leaves carry `C_x = q_x(0)*g2` and `C'_x = q_x(0)*H(attr)`. */
 export type KemTree = {
     kind: 'leaf';
     attr: string;
-    U: string;
-    wrap: string;
+    c: string;
+    cp: string;
 } | {
     kind: 'gate';
     t: number;
@@ -70,9 +102,11 @@ export type KemTree = {
 export interface AbeCiphertext {
     v: 1;
     alg: typeof ABE_ALG;
-    /** b64u HKDF salt (16 bytes) bound into every derived key and the CEK. */
+    /** b64u HKDF salt (16 bytes) bound into the CEK. */
     salt: string;
-    /** The share-distribution tree (also the authenticated access structure). */
+    /** b64u compressed G2 point `C_0 = s * h`. */
+    c0: string;
+    /** The access tree (also the authenticated access structure). */
     kem: KemTree;
     /** b64u AES-256-GCM IV (12 bytes). */
     iv: string;
@@ -97,7 +131,14 @@ export declare function keygenForAttributes(msk: MasterSecretKey, attrs: Iterabl
  * extended with explicit extra tokens. The key can decrypt only ciphertexts whose policy is satisfied
  * by this capability's authority.
  */
-export declare function keygenForCapability(msk: MasterSecretKey, capability: Capability, extraAttributes?: Iterable<string>): DecryptionKey;
+export declare function keygenForCapability(msk: MasterSecretKey, capability: Capability, extraAttributes?: Iterable<string>, opts?: CapabilityAttributeOpts): DecryptionKey;
+/**
+ * Re-randomise a key with fresh randomness (BSW07 Delegate): the result decrypts exactly what `key` decrypts
+ * (restricted to `subset` when given, which must be attributes the key holds) but shares no component with it
+ * and carries a new randomiser `r + r~`, so it is as incompatible with the original as with any other user's key.
+ * Needs only the public key. Throws {@link PcaEncryptionError} on a malformed key / mpk or a subset attribute not held.
+ */
+export declare function rerandomizeKey(mpk: MasterPublicKey, key: DecryptionKey, subset?: Iterable<string>): DecryptionKey;
 /**
  * Encrypt `plaintext` so that it decrypts only for a holder whose attribute set satisfies `policy`.
  * Throws {@link PcaEncryptionError} on an invalid policy or master public key.
@@ -109,8 +150,8 @@ export declare function encryptForPolicy(mpk: MasterPublicKey, policy: Policy, p
 export declare function parseCiphertext(x: unknown): AbeCiphertext | null;
 /**
  * Decrypt. Returns the plaintext iff the key's attribute set satisfies the ciphertext's policy AND the
- * AEAD authenticates; otherwise returns null (never throws). A key missing a required attribute cannot
- * recover the root secret and therefore cannot derive the content-encryption key.
+ * AEAD authenticates; otherwise returns null (never throws). Components of keys issued to different users
+ * carry different randomisers and cannot be combined.
  */
 export declare function decrypt(key: DecryptionKey, ciphertext: unknown): Uint8Array | null;
 /** Like {@link decrypt} but returns the plaintext decoded as UTF-8 text, or null. */