nucypher.policy¶

Submodules¶

class Card(character_flag: Union[ALICE(b’?\xba\x93\xd8V\xb4G\x95’), BOB(b’\xfd(1@\x11\x98k\xd4’)], verifying_key: Union[umbral.PublicKey, bytes], encrypting_key: Union[umbral.PublicKey, bytes, None] = None, nickname: Union[bytes, str, None] = None)¶

Bases: object

” A simple serializable representation of a character’s public materials.

TRUNCATE = 16¶

CARD_DIR = PosixPath('/home/docs/.local/share/nucypher/cards')¶

exception InvalidCard¶

Bases: Exception

Raised when an invalid, corrupted, or otherwise unsable card is encountered

exception UnknownCard¶

Bases: Exception

Raised when a card cannot be found in storage

exception UnsignedCard¶

Bases: Exception

Raised when a card serialization cannot be handled due to the lack of a signature

property character¶

classmethod from_bytes(card_bytes: bytes) → nucypher.policy.identity.Card ¶

classmethod from_hex(hexdata: str)¶

to_hex() → str ¶

classmethod from_base64(b64data: str)¶

to_base64() → str ¶

to_qr_code()¶

classmethod from_dict(card: Dict)¶

to_dict() → Dict¶

describe(truncate: int = 16) → Dict¶

to_json(as_string: bool = True) → Union[dict, str]¶

classmethod from_character(character: nucypher.characters.base.Character, nickname: Optional[str] = None) → nucypher.policy.identity.Card ¶

property verifying_key¶

property encrypting_key¶

property id¶

set_nickname(nickname: str) → None ¶

property nickname¶

property filepath¶

property is_saved¶

save(encoder: Callable = <function b64encode>, overwrite: bool = False) → pathlib.Path ¶

classmethod lookup(identifier: str, card_dir: Optional[pathlib.Path] = PosixPath('/home/docs/.local/share/nucypher/cards')) → pathlib.Path ¶: Resolve a card ID or nickname into a Path object

classmethod load(filepath: Optional[pathlib.Path] = None, identifier: str = None, card_dir: Optional[pathlib.Path] = None, decoder: Callable = <function b64decode>) → nucypher.policy.identity.Card ¶

delete() → None ¶

class PolicyMessageKit(policy_encrypting_key: umbral.PublicKey, threshold: int, result: nucypher.policy.kits.RetrievalResult, message_kit: nucypher_core.MessageKit)¶

Bases: object

classmethod from_message_kit(message_kit: nucypher_core.MessageKit, policy_encrypting_key: umbral.PublicKey, threshold: int) → nucypher.policy.kits.PolicyMessageKit ¶

as_retrieval_kit() → nucypher_core.RetrievalKit¶

decrypt(sk: umbral.SecretKey) → bytes ¶

is_decryptable_by_receiver() → bool ¶

with_result(result: nucypher.policy.kits.RetrievalResult) → nucypher.policy.kits.PolicyMessageKit ¶

class RetrievalResult(cfrags: Dict[NewType.<locals>.new_type, umbral.VerifiedCapsuleFrag])¶

Bases: object

An object representing retrieval results for a single capsule.

classmethod empty()¶

canonical_addresses() → Set[bytes]¶

with_result(result: nucypher.policy.kits.RetrievalResult) → nucypher.policy.kits.RetrievalResult ¶

Joins two RetrievalResult objects.

If both objects contain cfrags from the same Ursula, the one from result will be kept.

class ReencryptionPrerequisite¶

Bases: abc.ABC

Baseclass for reencryption preconditions relating to a policy.

ONCHAIN = NotImplemented¶

NAME = NotImplemented¶

abstract verify(payee: NewType.<locals>.new_type, request: nucypher_core.ReencryptionRequest) → bool ¶: returns True if reencryption is permitted by the payee (ursula) for the given reencryption request.

class PaymentMethod¶

Bases: nucypher.policy.payment.ReencryptionPrerequisite, abc.ABC

Extends ReencryptionPrerequisite to facilitate policy payment and payment verification.

class Quote(rate, value, commencement, expiration, duration, shares)¶

Bases: tuple

property rate¶: Alias for field number 0

property value¶: Alias for field number 1

property commencement¶: Alias for field number 2

property expiration¶: Alias for field number 3

property duration¶: Alias for field number 4

property shares¶: Alias for field number 5

abstract pay(policy: nucypher.policy.policies.Policy) → Dict¶: Carry out payment for the given policy.

abstract property rate¶: The cost of this payment method per unit.

abstract quote(shares: int, duration: Optional[int] = None, commencement: Optional[NewType.<locals>.new_type] = None, expiration: Optional[int] = None, value: Optional[int] = None, rate: Optional[int] = None) → nucypher.policy.payment.PaymentMethod.Quote ¶: Generates a valid quote for this payment method using pricing details.

abstract validate_price(shares: int, value: int, duration: int) → None ¶

class ContractPayment(eth_provider: str, network: str, registry: Optional[nucypher.blockchain.eth.registry.BaseContractRegistry] = None, *args, **kwargs)¶

Bases: nucypher.policy.payment.PaymentMethod, abc.ABC

Baseclass for on-chain policy payment; Requires a blockchain connection.

ONCHAIN = True¶

class Quote¶: Bases: nucypher.policy.payment.PaymentMethod.Quote

property agent¶: Returns an instance of the agent used to carry out contract payments.

class FreeReencryptions¶

Bases: nucypher.policy.payment.PaymentMethod

Useful for private federations and testing.

ONCHAIN = False¶

NAME = 'Free'¶

verify(payee: NewType.<locals>.new_type, request: nucypher_core.ReencryptionRequest) → bool ¶: returns True if reencryption is permitted by the payee (ursula) for the given reencryption request.

pay(policy: nucypher.policy.policies.Policy) → Dict¶: Carry out payment for the given policy.

property rate¶: The cost of this payment method per unit.

quote(shares: int, commencement: Optional[NewType.<locals>.new_type] = None, expiration: Optional[NewType.<locals>.new_type] = None, duration: Optional[int] = None, *args, **kwargs) → nucypher.policy.payment.PaymentMethod.Quote ¶: Generates a valid quote for this payment method using pricing details.

validate_price(*args, **kwargs) → bool ¶

class SubscriptionManagerPayment(eth_provider: str, network: str, registry: Optional[nucypher.blockchain.eth.registry.BaseContractRegistry] = None, *args, **kwargs)¶

Bases: nucypher.policy.payment.ContractPayment

Handle policy payment using the SubscriptionManager contract.

NAME = 'SubscriptionManager'¶

verify(payee: NewType.<locals>.new_type, request: nucypher_core.ReencryptionRequest) → bool ¶: Verify policy payment by reading the SubscriptionManager contract

pay(policy: nucypher.policy.policies.BlockchainPolicy) → web3.types.TxReceipt¶: Writes a new policy to the SubscriptionManager contract.

property rate¶: The cost of this payment method per unit.

quote(shares: int, commencement: Optional[NewType.<locals>.new_type] = None, expiration: Optional[NewType.<locals>.new_type] = None, duration: Optional[int] = None, value: Optional[NewType.<locals>.new_type] = None, rate: Optional[NewType.<locals>.new_type] = None, *args, **kwargs) → nucypher.policy.payment.PaymentMethod.Quote ¶: A quote for the SubscriptionManager is calculated as rate * duration seconds

validate_price(value: NewType.<locals>.new_type, duration: NewType.<locals>.new_type, shares: int, *args, **kwargs) → bool ¶

class Policy(publisher: Alice, label: bytes, bob: Bob, kfrags: Sequence[umbral.VerifiedKeyFrag], public_key: umbral.PublicKey, threshold: int, expiration: maya.core.MayaDT, commencement: maya.core.MayaDT, value: int, rate: int, duration: int, payment_method: PaymentMethod)¶

Bases: abc.ABC

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

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

Bases: Exception

Base exception for policy exceptions

exception NotEnoughUrsulas¶

Bases: nucypher.policy.policies.Policy.PolicyException

Raised when a Policy cannot be generated due an insufficient number of available qualified network nodes.

enact(network_middleware: nucypher.network.middleware.RestMiddleware, ursulas: Optional[Iterable[Ursula]] = None) → EnactedPolicy¶: Attempts to enact the policy, returns an EnactedPolicy object on success.

class FederatedPolicy(publisher: Alice, label: bytes, bob: Bob, kfrags: Sequence[umbral.VerifiedKeyFrag], public_key: umbral.PublicKey, threshold: int, expiration: maya.core.MayaDT, commencement: maya.core.MayaDT, value: int, rate: int, duration: int, payment_method: PaymentMethod)¶: Bases: nucypher.policy.policies.Policy

class BlockchainPolicy(publisher: Alice, label: bytes, bob: Bob, kfrags: Sequence[umbral.VerifiedKeyFrag], public_key: umbral.PublicKey, threshold: int, expiration: maya.core.MayaDT, commencement: maya.core.MayaDT, value: int, rate: int, duration: int, payment_method: PaymentMethod)¶: Bases: nucypher.policy.policies.Policy

class EnactedPolicy(hrac: nucypher_core.HRAC, label: bytes, public_key: umbral.PublicKey, threshold: int, treasure_map: EncryptedTreasureMap, revocation_kit: nucypher.policy.revocation.RevocationKit, publisher_verifying_key: umbral.PublicKey)¶: Bases: object

make_federated_staker_reservoir(known_nodes: nucypher.acumen.perception.FleetSensor, exclude_addresses: Optional[Iterable[NewType.<locals>.new_type]] = None, include_addresses: Optional[Iterable[NewType.<locals>.new_type]] = None)¶: Get a sampler object containing the federated stakers.

make_decentralized_staking_provider_reservoir(application_agent: nucypher.blockchain.eth.agents.PREApplicationAgent, exclude_addresses: Optional[Iterable[NewType.<locals>.new_type]] = None, include_addresses: Optional[Iterable[NewType.<locals>.new_type]] = None, pagination_size: int = None)¶: Get a sampler object containing the currently registered staking providers.

class MergedReservoir(values: Iterable, reservoir: nucypher.blockchain.eth.agents.StakingProvidersReservoir)¶

Bases: object

A reservoir made of a list of addresses and a StakingProviderReservoir. Draws the values from the list first, then from StakingProviderReservoir, then returns None on subsequent calls.

class PrefetchStrategy(reservoir: nucypher.policy.reservoir.MergedReservoir, need_successes: int)¶

Bases: object

Encapsulates the batch draw strategy from a reservoir. Determines how many values to draw based on the number of values that have already led to successes.

class RevocationKit(treasure_map, signer: nucypher.crypto.signing.SignatureStamp)¶

Bases: object

property revokable_addresses¶: Returns a Set of revokable addresses in the checksum address formatting

add_confirmation(ursula_address, signed_receipt)¶: Adds a signed confirmation of Ursula’s ability to revoke the node.