acapy_agent.wallet package

Abstract and Indy wallet handling.

Subpackages

acapy_agent.wallet.keys package
acapy_agent.wallet.models package
- Submodules
- acapy_agent.wallet.models.wallet_record module
  - WalletRecord
  - WalletRecordSchema
    - WalletRecordSchema.Meta

Submodules

acapy_agent.wallet.anoncreds_upgrade module

acapy_agent.wallet.askar module

acapy_agent.wallet.base module

Wallet base class.

class acapy_agent.wallet.base.BaseWallet[source]

Bases: ABC

Abstract wallet interface.

abstractmethod async assign_kid_to_key(verkey: str, kid: str) → KeyInfo[source]

Assign a KID to a key.

This is separate from the create_key method because some DIDs are only known after keys are created.

Parameters:

verkey – The verification key of the keypair
kid – The kid to assign to the keypair

Returns:

A KeyInfo representing the keypair

abstractmethod async create_key(key_type: KeyType, seed: str | None = None, metadata: dict | None = None, kid: str | None = 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
kid – Optional key identifier

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

abstractmethod async create_local_did(method: DIDMethod, key_type: KeyType, seed: str | None = None, did: str | None = None, metadata: dict | None = 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: str | None = None, did: str | None = None, metadata: dict | None = None) → DIDInfo[source]

Create and store a new public DID.

This method creates a new public DID using the specified DID method and key type.

The optional seed parameter can be used to provide a seed for the DID: generation.
If a did is provided, it will be used as the DID instead of generating a new: one.

The metadata parameter can be used to store additional metadata with the DID.

Parameters:

method – The DID method to use for creating the DID.
key_type – The key type to use for the DID.
seed – Optional seed to use for DID generation.
did – The DID to use instead of generating a new one.
metadata – Optional metadata to store with the DID.

Returns:

The created DIDInfo object.

abstractmethod async create_signing_key(key_type: KeyType, seed: str | None = None, metadata: dict | None = 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

abstractmethod async get_key_by_kid(kid: str) → KeyInfo[source]

Fetch a key by looking up its kid.

Parameters:: kid – the key identifier
Returns:: The key identified by kid

abstractmethod 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

abstractmethod 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

abstractmethod 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

abstractmethod async get_public_did() → DIDInfo | None[source]

Retrieve the public DID.

Returns:: The currently public DIDInfo, if any

abstractmethod 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

abstractmethod async pack_message(message: str, to_verkeys: Sequence[str], from_verkey: str | None = 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

abstractmethod 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

abstractmethod 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

abstractmethod 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

abstractmethod async rotate_did_keypair_start(did: str, next_seed: str | None = 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: EndpointType | None = None, write_ledger: bool = True, endorser_did: str | None = None, routing_keys: List[str] | None = None)[source]

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

Parameters:

did (str) – The DID for which to set the endpoint.
endpoint (str) – The endpoint to set. Use None to clear the endpoint.
_ledger (BaseLedger) – The ledger to which to send the endpoint update if the DID is public or posted.
endpoint_type (EndpointType, optional) – The type of the endpoint/service. Only endpoint_type ‘endpoint’ affects the local wallet.
write_ledger (bool, optional) – Whether to write the endpoint update to the ledger. Defaults to True.
endorser_did (str, optional) – The DID of the endorser. Defaults to None.
routing_keys (List[str], optional) – The list of routing keys. Defaults to None.

Raises:

WalletError – If the DID method is not ‘did:sov’.

abstractmethod async set_public_did(did: str | DIDInfo) → DIDInfo[source]

Assign the public DID.

Returns:: The updated DIDInfo

abstractmethod async sign_message(message: 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

abstractmethod 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

abstractmethod 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

abstractmethod async verify_message(message: 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

acapy_agent.wallet.bbs module

BBS+ crypto.

exception acapy_agent.wallet.bbs.BbsException(*args, error_code: str | None = None, **kwargs)[source]

Bases: BaseError

Base BBS exception.

acapy_agent.wallet.bbs.create_bls12381g2_keypair(seed: bytes | None = 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)

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

acapy_agent.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:

messages (List[bytes]) – The signed messages to verify.
signature (bytes) – The signature to verify.
public_key (bytes) – The public key to use in verification.

Returns:

True if the signature is verified, else False.

Return type:

bool

Raises:

BbsException – If unable to verify the BBS+ signature.

acapy_agent.wallet.crypto module

Cryptography functions used by BasicWallet.

acapy_agent.wallet.crypto.add_pack_recipients(wrapper: JweEnvelope, cek: bytes, to_verkeys: Sequence[bytes], from_secret: bytes | None = 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)

acapy_agent.wallet.crypto.create_ed25519_keypair(seed: bytes | None = 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)

acapy_agent.wallet.crypto.create_keypair(key_type: KeyType, seed: bytes | None = 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)

acapy_agent.wallet.crypto.decode_pack_message(enc_message: bytes, find_key: Callable) → Tuple[str, str | None, 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

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

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

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

Decrypt the payload of a packed message.

Parameters:

ciphertext (bytes) – The encrypted payload to be decrypted.
recips_bin (bytes) – The binary representation of the recipients’ public keys.
nonce (bytes) – The nonce used for encryption.
key (bytes) – The secret key used for encryption.

Returns:

The decrypted string.

Return type:

str

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

acapy_agent.wallet.crypto.ed25519_pk_to_curve25519(public_key: bytes) → bytes[source]: Covert a public Ed25519 key to a public Curve25519 key as bytes.

acapy_agent.wallet.crypto.encode_pack_message(message: str, to_verkeys: Sequence[bytes], from_secret: bytes | None = 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

acapy_agent.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 (str) – The message to encrypt.
add_data (bytes) – Additional data to include in the encryption.
key (bytes) – The key used for encryption.

Returns:

A tuple containing the ciphertext, nonce, and tag.

Return type:

Tuple[bytes, bytes, bytes]

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

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

acapy_agent.wallet.crypto.seed_to_did(seed: str, method: ~acapy_agent.wallet.did_method.DIDMethod | None = <acapy_agent.wallet.did_method.DIDMethod object>) → str[source]

Derive a DID from a seed value.

Parameters:

seed – The seed to derive
method – The DID method to use

Returns:

The DID derived from the seed

acapy_agent.wallet.crypto.sign_message(message: 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

acapy_agent.wallet.crypto.sign_message_ed25519(message: bytes, secret: bytes) → bytes[source]

Sign message using an ed25519 private signing key.

This function takes a message and a private signing key as input and returns the signature of the message using the ed25519 algorithm.

Parameters:

message (bytes) – The message to sign.
secret (bytes) – The private signing key.

Returns:

The signature of the message.

Return type:

bytes

acapy_agent.wallet.crypto.sign_pk_from_sk(secret: bytes) → bytes[source]: Extract the verkey from a secret signing key.

acapy_agent.wallet.crypto.validate_seed(seed: str | bytes | None) → bytes[source]

Convert a seed parameter to standard format and check length.

Parameters:: seed – The seed to validate
Returns:: The validated and encoded seed

acapy_agent.wallet.crypto.verify_signed_message(message: 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

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

acapy_agent.wallet.default_verification_key_strategy module

acapy_agent.wallet.did_info module

KeyInfo, DIDInfo.

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

Bases: NamedTuple

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 acapy_agent.wallet.did_info.KeyInfo(verkey: str, metadata: dict, key_type: KeyType, kid: List[str] | str | None = None)[source]

Bases: NamedTuple

Class returning key information.

key_type: KeyType: Alias for field number 2

kid: List[str] | str | None: Alias for field number 3

metadata: dict: Alias for field number 1

verkey: str: Alias for field number 0

acapy_agent.wallet.did_method module

did method.py contains registry for did methods.

class acapy_agent.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 acapy_agent.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) → DIDMethod | None[source]

Get DID method instance from metadata object.

Returns SOV if no metadata was found for backwards compatibility.

from_method(method_name: str) → DIDMethod | None[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 acapy_agent.wallet.did_method.HolderDefinedDid(*values)[source]

Bases: Enum

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

ALLOWED = 'allowed'

NO = 'no'

REQUIRED = 'required'

acapy_agent.wallet.did_parameters_validation module

acapy_agent.wallet.did_posture module

Ledger utilities.

class acapy_agent.wallet.did_posture.DIDPosture(*values)[source]

Bases: Enum

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

POSTED = ('posted', 1, False, True)

PUBLIC = ('public', 0, True, True)

WALLET_ONLY = ('wallet_only', 2, False, False)

static get(posture: 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 acapy_agent.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

acapy_agent.wallet.error module

Wallet-related exceptions.

exception acapy_agent.wallet.error.WalletDuplicateError(*args, error_code: str | None = None, **kwargs)[source]

Bases: WalletError

Duplicate record exception.

exception acapy_agent.wallet.error.WalletError(*args, error_code: str | None = None, **kwargs)[source]

Bases: BaseError

General wallet exception.

exception acapy_agent.wallet.error.WalletNotFoundError(*args, error_code: str | None = None, **kwargs)[source]

Bases: WalletError

Record not found exception.

exception acapy_agent.wallet.error.WalletSettingsError(*args, error_code: str | None = None, **kwargs)[source]

Bases: WalletError

Invalid settings exception.

acapy_agent.wallet.jwt module

acapy_agent.wallet.kanon_wallet module

acapy_agent.wallet.key_type module

Key type code.

class acapy_agent.wallet.key_type.KeyType(key_type: str, multicodec_name: str, multicodec_prefix: bytes, jws_alg: str | None)[source]

Bases: object

Key Type class.

property jws_algorithm: str | None: Get key type JWS Algorithm (used in the JOSE header).

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 acapy_agent.wallet.key_type.KeyTypes[source]

Bases: object

KeyType class specifying key types with multicodec name.

from_key_type(key_type: str) → KeyType | None[source]: Get KeyType instance from the key type identifier.

from_multicodec_name(multicodec_name: str) → KeyType | None[source]: Get KeyType instance based on multicodec name. Returns None if not found.

from_multicodec_prefix(multicodec_prefix: bytes) → KeyType | None[source]: Get KeyType instance based on multicodec prefix. Returns None if not found.

from_prefixed_bytes(prefixed_bytes: bytes) → KeyType | None[source]: Get KeyType instance based on prefix in bytes. Returns None if not found.

register(key_type: KeyType)[source]: Register a new key type.

acapy_agent.wallet.routes module

acapy_agent.wallet.sd_jwt module

acapy_agent.wallet.singletons module

Module that contains singleton classes for wallet operations.

class acapy_agent.wallet.singletons.IsAnonCredsSingleton(*args, **kwargs)[source]

Bases: object

Singleton class used as cache for anoncreds wallet-type queries.

instance = None

remove_wallet(wallet: str)[source]: Remove a wallet name.

set_wallet(wallet: str)[source]: Set a wallet name.

wallets = {}

class acapy_agent.wallet.singletons.UpgradeInProgressSingleton(*args, **kwargs)[source]

Bases: object

Singleton class used as cache for upgrade in progress.

instance = None

remove_wallet(wallet: str)[source]: Remove a wallet name.

set_wallet(wallet: str)[source]: Set a wallet name.

wallets = {}

acapy_agent.wallet.util module

Wallet utility functions.

acapy_agent.wallet.util.abbr_verkey(full_verkey: str, did: str | None = None) → str[source]: Given a full verkey and DID, return the abbreviated verkey.

acapy_agent.wallet.util.b58_to_bytes(val: str) → bytes[source]: Convert a base 58 string to bytes.

acapy_agent.wallet.util.b64_to_bytes(val: str, urlsafe=False) → bytes[source]: Convert a base 64 string to bytes.

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

acapy_agent.wallet.util.bytes_to_b58(val: bytes) → str[source]: Convert a byte string to base 58.

acapy_agent.wallet.util.bytes_to_b64(val: bytes, urlsafe=False, pad=True, encoding: str = 'ascii') → str[source]: Convert a byte string to base 64.

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

acapy_agent.wallet.util.full_verkey(did: str, abbr_verkey: str) → str[source]: Given a DID and abbreviated verkey, return the full verkey.

async acapy_agent.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 acapy_agent.wallet.util.notify_endorse_did_event(profile: Profile, did: str, meta_data: dict)[source]: Send notification for a DID post-process event.

acapy_agent.wallet.util.pad(val: str) → str[source]: Pad base64 values if need be: JWT calls to omit trailing padding.

acapy_agent.wallet.util.random_seed() → bytes[source]

Generate a random seed value.

Returns:: A new random seed

acapy_agent.wallet.util.set_urlsafe_b64(val: str, urlsafe: bool = True) → str[source]: Set URL safety in base64 encoding.

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

acapy_agent.wallet.util.unpad(val: str) → str[source]: Remove padding from base64 values if need be.