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

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.

ID_LENGTH = 32

encrypt_payload_for_ursula()

Craft an offer to send to Ursula.

federated = True

classmethod from_bytes(arrangement_as_bytes)

payload()

abstract revoke()

Revoke arrangement.

splitter = <bytestring_splitter.BytestringSplitter object>

ID_LENGTH = 32

splitter = <bytestring_splitter.BytestringSplitter object>

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.

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 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)

Deserializes the PolicyCredential from JSON.

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

Bases: object

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

Bases: object

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

classmethod from_bytes(data: bytes)

attach_work_result(cfrag, reencryption_signature)

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

classmethod from_rest_payload(arrangement_id, rest_payload, ursula, alice_address)

payload()

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 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

A L{Logger} emits log messages to an observer. You should instantiate it as a class or module attribute, as documented in L{this module’s documentation <twisted.logger>}.

@type namespace: L{str} @ivar namespace: the namespace for this logger

@type source: L{object} @ivar source: The object which is emitting events via this logger

@type: L{ILogObserver} @ivar observer: The observer that this logger will send events to.

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.

publish_treasure_map(network_middleware: nucypher.network.middleware.RestMiddleware) → dict

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=True) → dict

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

consider_arrangement(network_middleware, ursula, arrangement) → bool

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

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

abstract sample_essential(quantity: int, handpicked_ursulas: Set[nucypher.characters.lawful.Ursula] = None) → Set[nucypher.characters.lawful.Ursula]

sample(handpicked_ursulas: Set[nucypher.characters.lawful.Ursula] = None) → 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] = None) → 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] = None) → Set[nucypher.characters.lawful.Ursula]

publish_to_blockchain() → dict

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

enact(network_middleware, publish=True) → dict

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