nucypher.policy

Submodules

class TreasureMap(m: int = None, destinations=None, message_kit: nucypher.crypto.kits.PolicyMessageKit = None, public_signature: umbral.signing.Signature = None, hrac: Optional[bytes] = None)

Bases: object

ID_LENGTH = 32

exception NowhereToBeFound(*args, **kwargs)

Bases: nucypher.network.middleware.RestMiddleware.NotFound

Called when no known nodes have it.

exception IsDisorienting

Bases: nucypher.network.nodes.Learner.NotEnoughNodes

Called when an oriented TreasureMap lists fewer than m destinations, which leaves Bob disoriented.

node_id_splitter = <bytestring_splitter.BytestringSplitter object>

exception InvalidSignature

Bases: Exception

Raised when a Signature is not valid.

classmethod splitter()

prepare_for_publication(bob_encrypting_key, bob_verifying_key, alice_stamp, label)

property m

property destinations

nodes_as_bytes()

add_arrangement(arrangement)

public_id() → str

We need an ID that Bob can glean from knowledge he already has and which Ursula can verify came from Alice. Ursula will refuse to propagate this if it she can’t prove the payload is signed by Alice’s public key, which is included in it,

classmethod from_bytes(bytes_representation, verify=True)

public_verify()

orient(compass)

When Bob receives the TreasureMap, he’ll pass a compass (a callable which can verify and decrypt the payload message kit).

check_for_sufficient_destinations()

class SignedTreasureMap(blockchain_signature=NOT_SIGNED, *args, **kwargs)

Bases: nucypher.policy.collections.TreasureMap

classmethod splitter()

include_blockchain_signature(blockchain_signer)

verify_blockchain_signature(checksum_address)

class PolicyCredential(alice_verifying_key, label, expiration, policy_pubkey, treasure_map=None)

Bases: object

A portable structure that contains information necessary for Alice or Bob to utilize the policy on the network that the credential describes.

to_json()

Serializes the PolicyCredential to JSON.

classmethod from_json(data: str, federated=False)

Deserializes the PolicyCredential from JSON.

class WorkOrder(bob: nucypher.characters.lawful.Bob, arrangement_id, alice_address: bytes, tasks: dict, receipt_signature, ursula=None, blockhash=None)

Bases: object

class PRETask(capsule, signature, cfrag=None, cfrag_signature=None)

Bases: object

input_splitter = <bytestring_splitter.BytestringSplitter object>

output_splitter = <bytestring_splitter.BytestringSplitter object>

get_specification(ursula_pubkey, alice_address, blockhash, ursula_identity_evidence=b'')

classmethod from_bytes(data: bytes)

attach_work_result(cfrag, cfrag_signature)

HEADER = b'wo:'

classmethod construct_by_bob(arrangement_id, alice_verifying, capsules, ursula, bob)

classmethod from_rest_payload(arrangement_id, rest_payload, ursula, alice_address)

payload()

Creates a serialized WorkOrder. Called by Bob requesting reencryption tasks

complete(cfrags_and_signatures)

sanitize()

class WorkOrderHistory

Bases: object

property ursulas

most_recent_replete(capsule)

Returns most recent WorkOrders for each Ursula which contain a complete task (with CFrag attached) for this Capsule.

save_work_order(work_order, as_replete=False)

by_checksum_address(checksum_address)

by_capsule(capsule: umbral.pre.Capsule)

class Revocation(arrangement_id: bytes, signer: SignatureStamp = None, signature: umbral.signing.Signature = None)

Bases: object

Represents a string used by characters to perform a revocation on a specific Ursula. It’s a bytestring made of the following format: REVOKE-<arrangement id to revoke><signature of the previous string> This is sent as a payload in a DELETE method to the /KFrag/ endpoint.

revocation_splitter = <bytestring_splitter.BytestringSplitter object>

classmethod from_bytes(revocation_bytes)

verify_signature(alice_pubkey: umbral.keys.UmbralPublicKey)

Verifies the revocation was from the provided pubkey.

class IndisputableEvidence(task: WorkOrder.Task, work_order: WorkOrder, delegating_pubkey: umbral.keys.UmbralPublicKey = None, receiving_pubkey: umbral.keys.UmbralPublicKey = None, verifying_pubkey: umbral.keys.UmbralPublicKey = None)

Bases: object

get_proof_challenge_scalar() → umbral.curvebn.CurveBN

precompute_values() → bytes

evaluation_arguments() → Tuple

class Arrangement(alice: nucypher.characters.lawful.Alice, expiration: maya.core.MayaDT, ursula: nucypher.characters.lawful.Ursula = None, arrangement_id: bytes = None, kfrag: umbral.kfrags.KFrag = UNKNOWN_KFRAG)

Bases: object

A Policy must be implemented by arrangements with n Ursulas. This class tracks the status of that implementation.

federated = True

ID_LENGTH = 32

splitter = <bytestring_splitter.BytestringSplitter object>

status = None

These will normally not be set if Alice is drawing up this arrangement - she hasn’t assigned a kfrag yet (because she doesn’t know if this Arrangement will be accepted). She doesn’t have an Ursula, for the same reason.

classmethod from_bytes(arrangement_as_bytes)

encrypt_payload_for_ursula()

Craft an offer to send to Ursula.

payload()

abstract revoke()

Revoke arrangement.

class BlockchainArrangement(alice: nucypher.characters.lawful.Alice, ursula: nucypher.characters.lawful.Ursula, rate: int, expiration: maya.core.MayaDT, duration_periods: int, *args, **kwargs)

Bases: nucypher.policy.policies.Arrangement

A relationship between Alice and a single Ursula as part of Blockchain Policy

federated = False

exception InvalidArrangement

Bases: Exception

revoke() → str

Revoke this arrangement and return the transaction hash as hex.

payload()

class NodeEngagementMutex(callable_to_engage, nodes, network_middleware, percent_to_complete_before_release=5, note=None, threadpool_size=120, timeout=20, *args, **kwargs)

Bases: object

TODO: Does this belong on middleware?

TODO: There are a couple of ways this can break. If one fo the jobs hangs, the whole thing will hang. Also,

if there are fewer successfully completed than percent_to_complete_before_release, the partial queue will never release.

TODO: Make registry per… I guess Policy? It’s weird to be able to accidentally enact again.

log

Drop-in replacement of Twisted’s Logger, patching the emit() method to tolerate inputs with curly braces, i.e., not compliant with PEP 3101.

See Issue #724 and, particularly, https://github.com/nucypher/nucypher/issues/724#issuecomment-600190455

block_until_success_is_reasonably_likely()

https://www.youtube.com/watch?v=OkSLswPSq2o

block_until_complete()

total_disposed()

start()

class Policy(alice, label, expiration: maya.core.MayaDT, bob=None, kfrags=UNKNOWN_KFRAG, public_key=None, m: int = None, alice_signature=NOT_SIGNED)

Bases: abc.ABC

An edict by Alice, arranged with n Ursulas, to perform re-encryption for a specific Bob for a specific path.

Once Alice is ready to enact a Policy, she generates KFrags, which become part of the Policy.

Each Ursula is offered a Arrangement (see above) for a given Policy by Alice.

Once Alice has secured agreement with n Ursulas to enact a Policy, she sends each a KFrag, and generates a TreasureMap for the Policy, recording which Ursulas got a KFrag.

POLICY_ID_LENGTH = 16

log

Drop-in replacement of Twisted’s Logger, patching the emit() method to tolerate inputs with curly braces, i.e., not compliant with PEP 3101.

See Issue #724 and, particularly, https://github.com/nucypher/nucypher/issues/724#issuecomment-600190455

exception Rejected

Bases: RuntimeError

Too many Ursulas rejected

exception MoreKFragsThanArrangements

Bases: TypeError

Raised when a Policy has been used to generate Arrangements with Ursulas insufficient number such that we don’t have enough KFrags to give to each Ursula.

property n

property id

property accepted_ursulas

hrac() → bytes

# TODO: #180 - This function is hanging on for dear life. After 180 is closed, it can be completely deprecated.

The “hashed resource authentication code”.

A hash of: * Alice’s public key * Bob’s public key * the label

Alice and Bob have all the information they need to construct this. Ursula does not, so we share it with her.

async put_treasure_map_on_node(node, network_middleware)

publish_treasure_map(network_middleware: nucypher.network.middleware.RestMiddleware, blockchain_signer: Callable = None) → nucypher.policy.policies.NodeEngagementMutex

credential(with_treasure_map=True)

Creates a PolicyCredential for portable access to the policy via Alice or Bob. By default, it will include the treasure_map for the policy unless with_treasure_map is False.

enact(network_middleware, publish_treasure_map=True) → dict

Assign kfrags to ursulas_on_network, and distribute them via REST, populating enacted_arrangements

propose_arrangement(network_middleware, arrangement) → bool

make_arrangements(network_middleware: nucypher.network.middleware.RestMiddleware, handpicked_ursulas: Optional[Set[nucypher.characters.lawful.Ursula]] = None, discover_on_this_thread: bool = True, *args, **kwargs) → None

abstract make_arrangement(ursula: nucypher.characters.lawful.Ursula, *args, **kwargs)

abstract sample_essential(*args, **kwargs) → Set[nucypher.characters.lawful.Ursula]

sample(handpicked_ursulas: Optional[Set[nucypher.characters.lawful.Ursula]] = None, discover_on_this_thread: bool = False) → Set[nucypher.characters.lawful.Ursula]

class FederatedPolicy(alice, label, expiration: maya.core.MayaDT, bob=None, kfrags=UNKNOWN_KFRAG, public_key=None, m: int = None, alice_signature=NOT_SIGNED)

Bases: nucypher.policy.policies.Policy

make_arrangements(*args, **kwargs) → None

sample_essential(quantity: int, handpicked_ursulas: Set[nucypher.characters.lawful.Ursula], discover_on_this_thread: bool = True) → Set[nucypher.characters.lawful.Ursula]

make_arrangement(ursula: nucypher.characters.lawful.Ursula, *args, **kwargs)

class BlockchainPolicy(alice: nucypher.characters.lawful.Alice, value: int, rate: int, duration_periods: int, expiration: maya.core.MayaDT, *args, **kwargs)

Bases: nucypher.policy.policies.Policy

A collection of n BlockchainArrangements representing a single Policy

exception NoSuchPolicy

Bases: Exception

exception InvalidPolicy

Bases: Exception

exception InvalidPolicyValue

Bases: ValueError

exception NotEnoughBlockchainUrsulas

Bases: nucypher.policy.policies.Policy.MoreKFragsThanArrangements

validate_fee_value() → None

static generate_policy_parameters(n: int, duration_periods: int, value: int = None, rate: int = None) → dict

sample_essential(quantity: int, handpicked_ursulas: Set[nucypher.characters.lawful.Ursula], learner_timeout: int = 1, timeout: int = 10, discover_on_this_thread: bool = False) → Set[nucypher.characters.lawful.Ursula]

publish_to_blockchain() → dict

make_arrangement(ursula: nucypher.characters.lawful.Ursula, *args, **kwargs)

enact(network_middleware, publish_to_blockchain=True, publish_treasure_map=True) → nucypher.policy.policies.NodeEngagementMutex

Assign kfrags to ursulas_on_network, and distribute them via REST, populating enacted_arrangements