aries_cloudagent.wallet package

Abstract and Indy wallet handling.

Subpackages

Submodules

aries_cloudagent.wallet.askar module

aries_cloudagent.wallet.base module

Wallet base class.

class aries_cloudagent.wallet.base.BaseWallet[source]

Bases: ABC

Abstract wallet interface.

abstract async create_key(key_type: KeyType, seed: Optional[str] = None, metadata: Optional[dict] = None) KeyInfo[source]

Create a new public/private keypair.

Parameters
  • key_type – Key type to create

  • seed – Seed for key

  • metadata – Optional metadata to store with the keypair

Returns

A KeyInfo representing the new record

Raises
  • WalletDuplicateError – If the resulting verkey already exists in the wallet

  • WalletError – If there is another backend error

abstract async create_local_did(method: DIDMethod, key_type: KeyType, seed: Optional[str] = None, did: Optional[str] = None, metadata: Optional[dict] = None) DIDInfo[source]

Create and store a new local DID.

Parameters
  • method – The method to use for the DID

  • key_type – The key type to use for the DID

  • seed – Optional seed to use for DID

  • did – The DID to use

  • metadata – Metadata to store with DID

Returns

The created DIDInfo

async create_public_did(method: DIDMethod, key_type: KeyType, seed: Optional[str] = None, did: Optional[str] = None, metadata: Optional[dict] = None) DIDInfo[source]

Create and store a new public DID.

Parameters
  • seed – Optional seed to use for DID

  • did – The DID to use

  • metadata – Metadata to store with DID

Returns

The created DIDInfo

abstract async create_signing_key(key_type: KeyType, seed: Optional[str] = None, metadata: Optional[dict] = None) KeyInfo[source]

Create a new public/private signing keypair.

Parameters
  • key_type – Key type to create

  • seed – Optional seed allowing deterministic key creation

  • metadata – Optional metadata to store with the keypair

Returns

A KeyInfo representing the new record

abstract async get_local_did(did: str) DIDInfo[source]

Find info for a local DID.

Parameters

did – The DID for which to get info

Returns

A DIDInfo instance for the DID

abstract async get_local_did_for_verkey(verkey: str) DIDInfo[source]

Resolve a local DID from a verkey.

Parameters

verkey – Verkey for which to get DID info

Returns

A DIDInfo instance for the DID

abstract async get_local_dids() Sequence[DIDInfo][source]

Get list of defined local DIDs.

Returns

A list of DIDInfo instances

async get_posted_dids() Sequence[DIDInfo][source]

Get list of defined posted DIDs.

Returns

A list of DIDInfo instances

abstract async get_public_did() DIDInfo[source]

Retrieve the public DID.

Returns

The currently public DIDInfo, if any

abstract async get_signing_key(verkey: str) KeyInfo[source]

Fetch info for a signing keypair.

Parameters

verkey – The verification key of the keypair

Returns

A KeyInfo representing the keypair

abstract async pack_message(message: str, to_verkeys: Sequence[str], from_verkey: Optional[str] = None) bytes[source]

Pack a message for one or more recipients.

Parameters
  • message – The message to pack

  • to_verkeys – The verkeys to pack the message for

  • from_verkey – The sender verkey

Returns

The packed message

abstract async replace_local_did_metadata(did: str, metadata: dict)[source]

Replace the metadata associated with a local DID.

Prefer set_did_endpoint() to set endpoint in metadata.

Parameters
  • did – DID for which to replace metadata

  • metadata – The new metadata

abstract async replace_signing_key_metadata(verkey: str, metadata: dict)[source]

Replace the metadata associated with a signing keypair.

Parameters
  • verkey – The verification key of the keypair

  • metadata – The new metadata to store

abstract async rotate_did_keypair_apply(did: str) None[source]

Apply temporary keypair as main for DID that wallet owns.

Parameters

did – signing DID

Raises
  • WalletNotFoundError – if wallet does not own DID

  • WalletError – if wallet has not started key rotation

abstract async rotate_did_keypair_start(did: str, next_seed: Optional[str] = None) str[source]

Begin key rotation for DID that wallet owns: generate new keypair.

Parameters
  • did – signing DID

  • next_seed – seed for incoming ed25519 key pair (default random)

Returns

The new verification key

Raises

WalletNotFoundError – if wallet does not own DID

async set_did_endpoint(did: str, endpoint: str, _ledger: BaseLedger, endpoint_type: Optional[EndpointType] = None, write_ledger: bool = True, endorser_did: Optional[str] = None, routing_keys: Optional[List[str]] = None)[source]

Update the endpoint for a DID in the wallet, send to ledger if posted.

Parameters
  • did – DID for which to set endpoint

  • endpoint – the endpoint to set, None to clear

  • ledger – the ledger to which to send endpoint update if DID is public or posted

  • endpoint_type – the type of the endpoint/service. Only endpoint_type ‘endpoint’ affects local wallet

abstract async set_public_did(did: Union[str, DIDInfo]) DIDInfo[source]

Assign the public DID.

Returns

The updated DIDInfo

abstract async sign_message(message: Union[List[bytes], bytes], from_verkey: str) bytes[source]

Sign message(s) using the private key associated with a given verkey.

Parameters
  • message – The message(s) to sign

  • from_verkey – Sign using the private key related to this verkey

Returns

The signature

abstract async store_did(did_info: DIDInfo) DIDInfo[source]

Store a DID in the wallet.

This enables components external to the wallet to define how a DID is created and then store it in the wallet for later use.

Parameters

did_info – The DID to store

Returns

The stored DIDInfo

abstract async unpack_message(enc_message: bytes) Tuple[str, str, str][source]

Unpack a message.

Parameters

enc_message – The encrypted message

Returns

(message, from_verkey, to_verkey)

Return type

A tuple

abstract async verify_message(message: Union[List[bytes], bytes], signature: bytes, from_verkey: str, key_type: KeyType) bool[source]

Verify a signature against the public key of the signer.

Parameters
  • message – The message to verify

  • signature – The signature to verify

  • from_verkey – Verkey to use in verification

  • key_type – The key type to derive the signature verification algorithm from

Returns

True if verified, else False

aries_cloudagent.wallet.bbs module

BBS+ crypto.

exception aries_cloudagent.wallet.bbs.BbsException(*args, error_code: Optional[str] = None, **kwargs)[source]

Bases: BaseError

Base BBS exception.

aries_cloudagent.wallet.bbs.create_bls12381g2_keypair(seed: Optional[bytes] = None) Tuple[bytes, bytes][source]

Create a public and private bls12381g2 keypair from a seed value.

Parameters

seed – Seed for keypair

Returns

A tuple of (public key, secret key)

aries_cloudagent.wallet.bbs.sign_messages_bls12381g2(messages: List[bytes], secret: bytes)[source]

Sign messages using a bls12381g2 private signing key.

Parameters
  • messages (List[bytes]) – The messages to sign

  • secret (bytes) – The private signing key

Returns

The signature

Return type

bytes

aries_cloudagent.wallet.bbs.verify_signed_messages_bls12381g2(messages: List[bytes], signature: bytes, public_key: bytes) bool[source]

Verify an ed25519 signed message according to a public verification key.

Parameters
  • signed – The signed messages

  • public_key – The public key to use in verification

Returns

True if verified, else False

aries_cloudagent.wallet.crypto module

Cryptography functions used by BasicWallet.

aries_cloudagent.wallet.crypto.add_pack_recipients(wrapper: JweEnvelope, cek: bytes, to_verkeys: Sequence[bytes], from_secret: Optional[bytes] = None)[source]

Assemble the recipients block of a packed message.

Parameters
  • wrapper – The envelope to add recipients to

  • cek – The content encryption key

  • to_verkeys – Verkeys of recipients

  • from_secret – Secret to use for signing keys

Returns

A tuple of (json result, key)

aries_cloudagent.wallet.crypto.create_ed25519_keypair(seed: Optional[bytes] = None) Tuple[bytes, bytes][source]

Create a public and private ed25519 keypair from a seed value.

Parameters

seed – Seed for keypair

Returns

A tuple of (public key, secret key)

aries_cloudagent.wallet.crypto.create_keypair(key_type: KeyType, seed: Optional[bytes] = None) Tuple[bytes, bytes][source]

Create a public and private keypair from a seed value.

Parameters
  • key_type – The type of key to generate

  • seed – Seed for keypair

Raises

WalletError – If the key type is not supported

Returns

A tuple of (public key, secret key)

aries_cloudagent.wallet.crypto.decode_pack_message(enc_message: bytes, find_key: Callable) Tuple[str, Optional[str], str][source]

Decode a packed message.

Disassemble and unencrypt a packed message, returning the message content, verification key of the sender (if available), and verification key of the recipient.

Parameters
  • enc_message – The encrypted message

  • find_key – Function to retrieve private key

Returns

A tuple of (message, sender_vk, recip_vk)

Raises
  • ValueError – If the packed message is invalid

  • ValueError – If the packed message recipients are invalid

  • ValueError – If the pack algorithm is unsupported

  • ValueError – If the sender’s public key was not provided

aries_cloudagent.wallet.crypto.decode_pack_message_outer(enc_message: bytes) Tuple[dict, dict, bool][source]

Decode the outer wrapper of a packed message and extract the recipients.

Parameters

enc_message – The encrypted message

Returns: a tuple of the decoded wrapper, recipients, and authcrypt flag

aries_cloudagent.wallet.crypto.decode_pack_message_payload(wrapper: JweEnvelope, payload_key: bytes) str[source]

Decode the payload of a packed message once the CEK is known.

Parameters
  • wrapper – The decoded message wrapper

  • payload_key – The decrypted payload key

aries_cloudagent.wallet.crypto.decrypt_plaintext(ciphertext: bytes, recips_bin: bytes, nonce: bytes, key: bytes) str[source]

Decrypt the payload of a packed message.

Parameters
  • ciphertext

  • recips_bin

  • nonce

  • key

Returns

The decrypted string

aries_cloudagent.wallet.crypto.did_is_self_certified(did: str, verkey: str) bool[source]

Check if the DID is self certified.

Parameters
  • did – DID string

  • verkey – VERKEY string

aries_cloudagent.wallet.crypto.ed25519_pk_to_curve25519(public_key: bytes) bytes[source]

Covert a public Ed25519 key to a public Curve25519 key as bytes.

aries_cloudagent.wallet.crypto.encode_pack_message(message: str, to_verkeys: Sequence[bytes], from_secret: Optional[bytes] = None) bytes[source]

Assemble a packed message for a set of recipients, optionally including the sender.

Parameters
  • message – The message to pack

  • to_verkeys – The verkeys to pack the message for

  • from_secret – The sender secret

Returns

The encoded message

aries_cloudagent.wallet.crypto.encrypt_plaintext(message: str, add_data: bytes, key: bytes) Tuple[bytes, bytes, bytes][source]

Encrypt the payload of a packed message.

Parameters
  • message – Message to encrypt

  • add_data

  • key – Key used for encryption

Returns

A tuple of (ciphertext, nonce, tag)

aries_cloudagent.wallet.crypto.extract_pack_recipients(recipients: Sequence[JweRecipient]) dict[source]

Extract the pack message recipients into a dict indexed by verkey.

Parameters

recipients – Recipients to locate

Raises

ValueError – If the recipients block is mal-formatted

aries_cloudagent.wallet.crypto.extract_payload_key(sender_cek: dict, recip_secret: bytes) Tuple[bytes, str][source]

Extract the payload key from pack recipient details.

Returns: A tuple of the CEK and sender verkey

aries_cloudagent.wallet.crypto.seed_to_did(seed: str) str[source]

Derive a DID from a seed value.

Parameters

seed – The seed to derive

Returns

The DID derived from the seed

aries_cloudagent.wallet.crypto.sign_message(message: Union[List[bytes], bytes], secret: bytes, key_type: KeyType) bytes[source]

Sign message(s) using a private signing key.

Parameters
  • message – The message(s) to sign

  • secret – The private signing key

  • key_type – The key type to derive the signature algorithm from

Returns

The signature

Return type

bytes

aries_cloudagent.wallet.crypto.sign_message_ed25519(message: bytes, secret: bytes) bytes[source]

Sign message using a ed25519 private signing key.

Parameters
  • messages (bytes) – The message to sign

  • secret (bytes) – The private signing key

Returns

The signature

Return type

bytes

aries_cloudagent.wallet.crypto.sign_pk_from_sk(secret: bytes) bytes[source]

Extract the verkey from a secret signing key.

aries_cloudagent.wallet.crypto.validate_seed(seed: Optional[Union[str, bytes]]) bytes[source]

Convert a seed parameter to standard format and check length.

Parameters

seed – The seed to validate

Returns

The validated and encoded seed

aries_cloudagent.wallet.crypto.verify_signed_message(message: Union[List[bytes], bytes], signature: bytes, verkey: bytes, key_type: KeyType) bool[source]

Verify a signed message according to a public verification key.

Parameters
  • message – The message(s) to verify

  • signature – The signature to verify

  • verkey – The verkey to use in verification

  • key_type – The key type to derive the signature verification algorithm from

Returns

True if verified, else False

aries_cloudagent.wallet.crypto.verify_signed_message_ed25519(message: bytes, signature: bytes, verkey: bytes) bool[source]

Verify an ed25519 signed message according to a public verification key.

Parameters
  • message – The message to verify

  • signature – The signature to verify

  • verkey – The verkey to use in verification

Returns

True if verified, else False

aries_cloudagent.wallet.default_verification_key_strategy module

aries_cloudagent.wallet.did_info module

KeyInfo, DIDInfo.

class aries_cloudagent.wallet.did_info.DIDInfo(did, verkey, metadata, method, key_type)

Bases: tuple

did: str

Alias for field number 0

key_type: KeyType

Alias for field number 4

metadata: dict

Alias for field number 2

method: DIDMethod

Alias for field number 3

verkey: str

Alias for field number 1

class aries_cloudagent.wallet.did_info.KeyInfo(verkey, metadata, key_type)

Bases: tuple

key_type: KeyType

Alias for field number 2

metadata: dict

Alias for field number 1

verkey: str

Alias for field number 0

aries_cloudagent.wallet.did_method module

did method.py contains registry for did methods.

class aries_cloudagent.wallet.did_method.DIDMethod(name: str, key_types: List[KeyType], rotation: bool = False, holder_defined_did: HolderDefinedDid = HolderDefinedDid.NO)[source]

Bases: object

Class to represent a did method.

holder_defined_did() HolderDefinedDid[source]

Return the did derivation policy.

eg: did:key DIDs are derived from the verkey -> HolderDefinedDid.NO eg: did:web DIDs cannot be derived from key material -> HolderDefinedDid.REQUIRED

property method_name

Get method name.

property supported_key_types

Get supported key types.

supports_key_type(key_type: KeyType) bool[source]

Check whether the current method supports the key type.

property supports_rotation

Check rotation support.

class aries_cloudagent.wallet.did_method.DIDMethods[source]

Bases: object

DID Method class specifying DID methods with supported key types.

from_did(did: str) DIDMethod[source]

Get DID method instance from the did url.

from_metadata(metadata: Mapping) Optional[DIDMethod][source]

Get DID method instance from metadata object.

Returns SOV if no metadata was found for backwards compatibility.

from_method(method_name: str) Optional[DIDMethod][source]

Retrieve a did method from method name.

register(method: DIDMethod)[source]

Register a new did method.

registered(method: str) bool[source]

Check for a supported method.

class aries_cloudagent.wallet.did_method.HolderDefinedDid(value)[source]

Bases: Enum

Define if a holder can specify its own did for a given method.

ALLOWED = 'allowed'
NO = 'no'
REQUIRED = 'required'

aries_cloudagent.wallet.did_parameters_validation module

aries_cloudagent.wallet.did_posture module

Ledger utilities.

class aries_cloudagent.wallet.did_posture.DIDPosture(value)[source]

Bases: Enum

Enum for DID postures: public, posted but not public, or in wallet only.

POSTED = DIDPostureSpec(moniker='posted', ordinal=1, public=False, posted=True)
PUBLIC = DIDPostureSpec(moniker='public', ordinal=0, public=True, posted=True)
WALLET_ONLY = DIDPostureSpec(moniker='wallet_only', ordinal=2, public=False, posted=False)
static get(posture: Union[str, Mapping]) DIDPosture[source]

Return enum instance corresponding to input string or DID metadata.

property metadata: Mapping

DID metadata for DID posture.

property moniker: str

Name for DID posture.

property ordinal: Mapping

public first, then posted and wallet-only.

Type

Ordinal for presentation

class aries_cloudagent.wallet.did_posture.DIDPostureSpec(moniker, ordinal, public, posted)

Bases: tuple

moniker

Alias for field number 0

ordinal

Alias for field number 1

posted

Alias for field number 3

public

Alias for field number 2

aries_cloudagent.wallet.error module

Wallet-related exceptions.

exception aries_cloudagent.wallet.error.WalletDuplicateError(*args, error_code: Optional[str] = None, **kwargs)[source]

Bases: WalletError

Duplicate record exception.

exception aries_cloudagent.wallet.error.WalletError(*args, error_code: Optional[str] = None, **kwargs)[source]

Bases: BaseError

General wallet exception.

exception aries_cloudagent.wallet.error.WalletNotFoundError(*args, error_code: Optional[str] = None, **kwargs)[source]

Bases: WalletError

Record not found exception.

exception aries_cloudagent.wallet.error.WalletSettingsError(*args, error_code: Optional[str] = None, **kwargs)[source]

Bases: WalletError

Invalid settings exception.

aries_cloudagent.wallet.in_memory module

aries_cloudagent.wallet.indy module

aries_cloudagent.wallet.jwt module

aries_cloudagent.wallet.key_pair module

Key pair storage manager.

class aries_cloudagent.wallet.key_pair.KeyPairStorageManager(store: BaseStorage)[source]

Bases: object

Key pair storage manager.

async delete_key_pair(verkey: str)[source]

Remove a previously-stored key pair record.

Raises

StorageNotFoundError – If the record is not found

async find_key_pairs(tag_query: Optional[Mapping] = None) List[dict][source]

Find key pairs by tag query.

async get_key_pair(verkey: str) dict[source]

Retrieve signing key pair from storage by verkey.

Parameters
  • storage (BaseStorage) – The storage to use for querying

  • verkey (str) – The verkey to query for

Raises
  • StorageDuplicateError – If more than one key pair is found for this verkey

  • StorageNotFoundError – If no key pair is found for this verkey

Returns

The key pair data

Return type

dict

async store_key_pair(public_key: bytes, secret_key: bytes, key_type: KeyType, metadata: Optional[dict] = None, tags: Optional[dict] = None)[source]

Store signing key pair in storage.

Parameters
  • public_key (bytes) – The public key

  • secret_key (bytes) – The secret key

  • key_type (KeyType) – The key type

  • metadata (dict, optional) – The metadata

  • tags (dict, optional) – The tags.

async update_key_pair_metadata(verkey: str, metadata: dict)[source]

Update the metadata of a key pair record by verkey.

Raises

StorageNotFoundError – If the record is not found.

aries_cloudagent.wallet.key_type module

Key type code.

class aries_cloudagent.wallet.key_type.KeyType(key_type: str, multicodec_name: str, multicodec_prefix: bytes)[source]

Bases: object

Key Type class.

property key_type: str

Get Key type, type.

property multicodec_name: str

Get key type multicodec name.

property multicodec_prefix: bytes

Get key type multicodec prefix.

class aries_cloudagent.wallet.key_type.KeyTypes[source]

Bases: object

KeyType class specifying key types with multicodec name.

from_key_type(key_type: str) Optional[KeyType][source]

Get KeyType instance from the key type identifier.

from_multicodec_name(multicodec_name: str) Optional[KeyType][source]

Get KeyType instance based on multicodec name. Returns None if not found.

from_multicodec_prefix(multicodec_prefix: bytes) Optional[KeyType][source]

Get KeyType instance based on multicodec prefix. Returns None if not found.

from_prefixed_bytes(prefixed_bytes: bytes) Optional[KeyType][source]

Get KeyType instance based on prefix in bytes. Returns None if not found.

register(key_type: KeyType)[source]

Register a new key type.

aries_cloudagent.wallet.routes module

aries_cloudagent.wallet.sd_jwt module

aries_cloudagent.wallet.util module

Wallet utility functions.

aries_cloudagent.wallet.util.abbr_verkey(full_verkey: str, did: Optional[str] = None) str[source]

Given a full verkey and DID, return the abbreviated verkey.

aries_cloudagent.wallet.util.b58_to_bytes(val: str) bytes[source]

Convert a base 58 string to bytes.

aries_cloudagent.wallet.util.b64_to_bytes(val: str, urlsafe=False) bytes[source]

Convert a base 64 string to bytes.

aries_cloudagent.wallet.util.b64_to_str(val: str, urlsafe=False, encoding=None) str[source]

Convert a base 64 string to string on input encoding (default utf-8).

aries_cloudagent.wallet.util.bytes_to_b58(val: bytes) str[source]

Convert a byte string to base 58.

aries_cloudagent.wallet.util.bytes_to_b64(val: bytes, urlsafe=False, pad=True, encoding: str = 'ascii') str[source]

Convert a byte string to base 64.

aries_cloudagent.wallet.util.default_did_from_verkey(verkey: str) str[source]

Given a verkey, return the default indy did.

By default the did is the first 16 bytes of the verkey.

aries_cloudagent.wallet.util.full_verkey(did: str, abbr_verkey: str) str[source]

Given a DID and abbreviated verkey, return the full verkey.

async aries_cloudagent.wallet.util.notify_endorse_did_attrib_event(profile: Profile, did: str, meta_data: dict)[source]

Send notification for a DID ATTRIB post-process event.

async aries_cloudagent.wallet.util.notify_endorse_did_event(profile: Profile, did: str, meta_data: dict)[source]

Send notification for a DID post-process event.

aries_cloudagent.wallet.util.pad(val: str) str[source]

Pad base64 values if need be: JWT calls to omit trailing padding.

aries_cloudagent.wallet.util.random_seed() bytes[source]

Generate a random seed value.

Returns

A new random seed

aries_cloudagent.wallet.util.set_urlsafe_b64(val: str, urlsafe: bool = True) str[source]

Set URL safety in base64 encoding.

aries_cloudagent.wallet.util.str_to_b64(val: str, urlsafe=False, encoding=None, pad=True) str[source]

Convert a string to base64 string on input encoding (default utf-8).

aries_cloudagent.wallet.util.unpad(val: str) str[source]

Remove padding from base64 values if need be.