Skip to content

Class swarmauri_core.mre_crypto.IMreCrypto.IMreCrypto

swarmauri_core.mre_crypto.IMreCrypto.IMreCrypto

Bases: ABC

supports abstractmethod 

supports()

Return a capability map describing supported algorithms, modes, and features. Providers SHOULD list only what they actually implement.

Keys (omit any you do not support): - "payload": iterable[str] of AEAD algorithms usable for the shared payload. (Only relevant for modes that use a shared AEAD.) - "recipient": iterable[str] of recipient protection algorithms (e.g., "OpenPGP", "X25519-SEAL", "RSA-OAEP-SHA256", "AES-KW"). - "modes": iterable[MreMode|str] of supported composition modes. - "features": iterable[str] of optional features (e.g., "aad", "threshold", "rewrap_without_reencrypt").

Example

return { "payload": ("AES-256-GCM", "XCHACHA20-POLY1305"), "recipient": ("OpenPGP", "X25519-SEAL"), "modes": (MreMode.ENC_ONCE_HEADERS, MreMode.SEALED_CEK_AEAD), "features": ("aad", "rewrap_without_reencrypt"), }

Source code in swarmauri_core/mre_crypto/IMreCrypto.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
@abstractmethod
def supports(self) -> Dict[str, Iterable[str | MreMode]]:
    """
    Return a capability map describing supported algorithms, modes, and features.
    Providers SHOULD list only what they actually implement.

    Keys (omit any you do not support):
      - "payload": iterable[str] of AEAD algorithms usable for the shared payload.
                   (Only relevant for modes that use a shared AEAD.)
      - "recipient": iterable[str] of recipient protection algorithms
                     (e.g., "OpenPGP", "X25519-SEAL", "RSA-OAEP-SHA256", "AES-KW").
      - "modes": iterable[MreMode|str] of supported composition modes.
      - "features": iterable[str] of optional features (e.g., "aad",
                    "threshold", "rewrap_without_reencrypt").

    Example:
        return {
          "payload": ("AES-256-GCM", "XCHACHA20-POLY1305"),
          "recipient": ("OpenPGP", "X25519-SEAL"),
          "modes": (MreMode.ENC_ONCE_HEADERS, MreMode.SEALED_CEK_AEAD),
          "features": ("aad", "rewrap_without_reencrypt"),
        }
    """
    ...

encrypt_for_many abstractmethod async 

encrypt_for_many(
    recipients,
    pt,
    *,
    payload_alg=None,
    recipient_alg=None,
    mode=None,
    aad=None,
    shared=None,
    opts=None,
)

Encrypt 'pt' for all 'recipients' and return a single MultiRecipientEnvelope.

PARAMETER DESCRIPTION
recipients

public-key KeyRefs (or handles) for each recipient.
pt

plaintext bytes.
payload_alg

AEAD for the shared payload (if required by the mode).
recipient_alg

per‑recipient protection algorithm (wrap/seal).
mode

MRE composition mode (see supports()["modes"]).
aad

Additional Authenticated Data (supported only by AEAD modes).
shared

optional map of app-defined fields to bind/version with envelope.
opts

provider hints (e.g., {"threshold_k": 2}).
RETURNS DESCRIPTION
MultiRecipientEnvelope

MultiRecipientEnvelope with: - top-level metadata (mode, payload_alg, recipient_alg, etc.), - either a shared AEAD payload or per‑recipient sealed payloads, - recipient header list with the material needed to open.
Source code in swarmauri_core/mre_crypto/IMreCrypto.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
@abstractmethod
async def encrypt_for_many(
    self,
    recipients: Sequence[KeyRef],
    pt: bytes,
    *,
    payload_alg: Optional[Alg] = None,
    recipient_alg: Optional[Alg] = None,
    mode: Optional[MreMode | str] = None,
    aad: Optional[bytes] = None,
    shared: Optional[Mapping[str, bytes]] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> MultiRecipientEnvelope:
    """
    Encrypt 'pt' for all 'recipients' and return a single MultiRecipientEnvelope.

    Parameters:
      recipients     : public-key KeyRefs (or handles) for each recipient.
      pt             : plaintext bytes.
      payload_alg    : AEAD for the shared payload (if required by the mode).
      recipient_alg  : per‑recipient protection algorithm (wrap/seal).
      mode           : MRE composition mode (see supports()["modes"]).
      aad            : Additional Authenticated Data (supported only by AEAD modes).
      shared         : optional map of app-defined fields to bind/version with envelope.
      opts           : provider hints (e.g., {"threshold_k": 2}).

    Returns:
      MultiRecipientEnvelope with:
        - top-level metadata (mode, payload_alg, recipient_alg, etc.),
        - either a shared AEAD payload or per‑recipient sealed payloads,
        - recipient header list with the material needed to open.
    """
    ...

open_for abstractmethod async 

open_for(my_identity, env, *, aad=None, opts=None)

Open 'env' using a single private identity.

PARAMETER DESCRIPTION
my_identity

private-key KeyRef (or HSM handle) corresponding to one recipient.
env

envelope produced by encrypt_for_many.
aad

AAD value (must match for AEAD modes).
opts

optional hints (e.g., {"prefer_handle": True}).
RETURNS DESCRIPTION
bytes

plaintext bytes.

Raises on authentication failure, unsupported mode/alg, or identity mismatch.

Source code in swarmauri_core/mre_crypto/IMreCrypto.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
@abstractmethod
async def open_for(
    self,
    my_identity: KeyRef,
    env: MultiRecipientEnvelope,
    *,
    aad: Optional[bytes] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bytes:
    """
    Open 'env' using a single private identity.

    Parameters:
      my_identity : private-key KeyRef (or HSM handle) corresponding to one recipient.
      env         : envelope produced by encrypt_for_many.
      aad         : AAD value (must match for AEAD modes).
      opts        : optional hints (e.g., {"prefer_handle": True}).

    Returns:
      plaintext bytes.

    Raises on authentication failure, unsupported mode/alg, or identity mismatch.
    """
    ...

open_for_many abstractmethod async 

open_for_many(my_identities, env, *, aad=None, opts=None)

Attempt to open 'env' with any of the provided identities. Useful when a service has multiple keys/slots or when a scheme requires multiple partial openings.

PARAMETER DESCRIPTION
my_identities

sequence of private-key KeyRefs / handles.
env

envelope to open.
aad

AAD (if required by the mode).
opts

optional hints (e.g., {"threshold_parts": {...}}).
RETURNS DESCRIPTION
bytes

plaintext bytes on success.

Raises on failure to satisfy the scheme (e.g., threshold unmet).

Source code in swarmauri_core/mre_crypto/IMreCrypto.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
@abstractmethod
async def open_for_many(
    self,
    my_identities: Sequence[KeyRef],
    env: MultiRecipientEnvelope,
    *,
    aad: Optional[bytes] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> bytes:
    """
    Attempt to open 'env' with any of the provided identities. Useful when a service
    has multiple keys/slots or when a scheme requires multiple partial openings.

    Parameters:
      my_identities : sequence of private-key KeyRefs / handles.
      env           : envelope to open.
      aad           : AAD (if required by the mode).
      opts          : optional hints (e.g., {"threshold_parts": {...}}).

    Returns:
      plaintext bytes on success.

    Raises on failure to satisfy the scheme (e.g., threshold unmet).
    """
    ...

rewrap abstractmethod async 

rewrap(
    env,
    *,
    add=None,
    remove=None,
    recipient_alg=None,
    opts=None,
)

Modify the recipient set, re‑wrapping headers without re‑encrypting the payload when the mode permits.

PARAMETER DESCRIPTION
env

existing envelope.
add

recipients to grant (append headers).
remove

recipient IDs to revoke (drop headers).
recipient_alg

optionally switch the per‑recipient protection algorithm.
opts

hints (e.g., {"rotate_payload_on_revoke": True}).
RETURNS DESCRIPTION
MultiRecipientEnvelope

Updated MultiRecipientEnvelope.
Notes
  • If safe header removal is not possible for the mode (e.g., sealed-per-recipient payload), providers SHOULD rotate the payload key and re‑encrypt.
  • Providers SHOULD document complexity: header‑only O(1) vs payload re‑encrypt O(N).
Source code in swarmauri_core/mre_crypto/IMreCrypto.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
@abstractmethod
async def rewrap(
    self,
    env: MultiRecipientEnvelope,
    *,
    add: Optional[Sequence[KeyRef]] = None,
    remove: Optional[Sequence[RecipientId]] = None,
    recipient_alg: Optional[Alg] = None,
    opts: Optional[Mapping[str, object]] = None,
) -> MultiRecipientEnvelope:
    """
    Modify the recipient set, re‑wrapping headers without re‑encrypting the payload
    when the mode permits.

    Parameters:
      env            : existing envelope.
      add            : recipients to grant (append headers).
      remove         : recipient IDs to revoke (drop headers).
      recipient_alg  : optionally switch the per‑recipient protection algorithm.
      opts           : hints (e.g., {"rotate_payload_on_revoke": True}).

    Returns:
      Updated MultiRecipientEnvelope.

    Notes:
      - If safe header removal is not possible for the mode (e.g., sealed-per-recipient
        payload), providers SHOULD rotate the payload key and re‑encrypt.
      - Providers SHOULD document complexity: header‑only O(1) vs payload re‑encrypt O(N).
    """
    ...