factom_did.client package¶
client.did module¶
-
class
factom_did.client.did.
DID
(did=None, management_keys=None, did_keys=None, services=None, spec_version='0.2.0')¶ Bases:
object
Enables the construction of a DID document, by facilitating the construction of management keys and DID keys and the addition of services. Allows exporting of the resulting DID object into a format suitable for recording on the Factom blockchain.
Provides encryption functionality of private keys for the DID and their export to a string or to a JSON file.
-
did
¶ The decentralized identifier, a 32 byte hexadecimal string
Type: str, optional
-
management_keys
¶ A list of management keys
Type: ManagementKey[], optional
-
deactivate
()¶ Raises: RuntimeError
– If no management keys are available for the DIDReturns: Return type: DIDDeactivator
-
did_key
(alias, purpose, key_type=<KeyType.EdDSA: 'Ed25519VerificationKey'>, controller=None, priority_requirement=None)¶ Creates a new DID key for the DID.
Parameters: - alias (str) – A human-readable nickname for the key. It should be unique across the keys defined in the DID document.
- purpose (DIDKeyPurpose or DIDKeyPurpose[]) – Shows what purpose(s) the key serves. (PublicKey, AuthenticationKey or both)
- key_type (KeyType, optional) – Identifies the type of signature that the key pair can be used to generate and verify.
- controller (str, optional) – An entity that will be making the signatures. It must be a valid DID. If the argument is not passed in, the default value is used which is the current DID itself.
- priority_requirement (int, optional) – A non-negative integer showing the minimum hierarchical level a key must have in order to remove this key.
-
export_encrypted_keys_as_json
(password)¶ Exports encrypted keys as JSON.
Parameters: password (str) – A password to use for the encryption of the keys. Returns: Encrypted keys JSON. Return type: str
-
export_encrypted_keys_as_str
(password)¶ Exports encrypted keys cipher text.
Parameters: password (str) – A password to use for the encryption of the keys. Returns: Encrypted keys cipher text. Return type: str
-
export_entry_data
()¶ Exports content that can be recorded on-chain to create the DID.
Returns: A dictionary with the ExtIDs and entry content of strings used that are the header columns. Return type: dict Raises: ValueError
– If there are no management keys. If there is no management key with priority 0. If the entry size exceeds the entry size limit.
-
get_chain
()¶ Returns: The chain ID where this DID is (or will be) stored Return type: str
-
id
¶
-
static
is_valid_did
(did)¶
-
mainnet
()¶ Sets the DID network to mainnet.
-
management_key
(alias, priority, key_type=<KeyType.EdDSA: 'Ed25519VerificationKey'>, controller=None, priority_requirement=None)¶ Creates a new management key for the DID.
Parameters: - alias (str) – A human-readable nickname for the key. It should be unique across the keys defined in the DID document.
- priority (int) – A non-negative integer showing the hierarchical level of the key. Keys with lower priority override keys with higher priority.
- key_type (KeyType, optional) – Identifies the type of signature that the key pair can be used to generate and verify.
- controller (str, optional) – An entity that controls the key. It must be a valid DID. If the argument is not passed in, the default value is used which is the current DID itself.
- priority_requirement (int, optional) – A non-negative integer showing the minimum hierarchical level a key must have in order to remove this key.
-
method_spec_version_upgrade
(new_spec_version)¶ Parameters: new_spec_version (str) – The new DID Method version
Raises: RuntimeError
– If no management keys are available for the DIDValueError
– If the new version is not an upgrade on the current version
Returns: Return type:
-
record_on_chain
(factomd, walletd, ec_address, verbose=False)¶ Attempts to create the DIDManagement chain.
Parameters: - factomd (obj) – Factomd instance, instantiated from the Python factom-api package.
- walletd (obj) – Factom walletd instance, instantiated from the Python factom-api package.
- ec_address (str) – EC address used to pay for the chain & entry creation.
- verbose (bool, optional) – If true, display the contents of the entry that will be recorded on-chain.
Raises: RuntimeError
– If the chain cannot be created
-
service
(alias, service_type, endpoint, priority_requirement=None, custom_fields=None)¶ Adds a new service to the DID Document.
Parameters: - alias (str) – A human-readable nickname for the service endpoint. It should be unique across the services defined in the DID document.
- service_type (str) – Type of the service endpoint.
- endpoint (str) – A service endpoint may represent any type of service the subject wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction. The service endpoint must be a valid URL.
- priority_requirement (int, optional) – A non-negative integer showing the minimum hierarchical level a key must have in order to remove this service.
- custom_fields (dict, optional) – A dictionary containing custom fields (e.g “description”: “My public social inbox”).
-
testnet
()¶ Sets the DID network to testnet.
-
update
()¶ Raises: RuntimeError
– If no management keys are available for the DIDReturns: An object allowing updates to the existing DID Return type: DIDUpdater
-
client.encryptor module¶
-
factom_did.client.encryptor.
encrypt_keys
(management_keys, did_keys, password)¶ Encrypts keys with a password.
Parameters: - management_keys (ManagementKeyModel[]) – A list of management keys to be encrypted.
- did_keys (DidKeyModel[]) – A list of did keys to be encrypted.
- password (str) – A password to use for the encryption of the keys.
Returns: An object containing salt, initial vector, tag and encrypted data.
Return type: obj
-
factom_did.client.encryptor.
decrypt_keys_from_str
(cipher_text_b64, password, encryption_algo='AES-GCM')¶ Decrypts keys from cipher text and password.
Parameters: - cipher_text_b64 (str) – Base 64 encoded cipher text.
- password (str) – A password used for the encryption of the keys.
- encryption_algo (str) – The encryption algorithm used. Currently only ‘AES-GCM’ is supported
Returns: An object containing dictionaries of decrypted management and did keys.
Return type: obj
Raises: ValueError
– If the cipher text or the password used for the encryption is invalid.
-
factom_did.client.encryptor.
decrypt_keys_from_json_str
(encrypted_keys_json_str, password)¶ Decrypts keys from JSON string and password. The JSON string must have a schema compatible with the one produced by DID.export_encrypted_keys_as_json():
- ‘{
- “encryptionAlgo”: {
- “salt”: …, “iv”: …, “name”: …, “tagLength”: …,
}, “data”: … (encrypted private keys), “did”: …
}’
Parameters: - encrypted_keys_json_str (str) – JSON string containing encrypted keys data.
- password (str) – A password used for the encryption of the keys.
Returns: An object containing dictionaries of decrypted management and did keys.
Return type: obj
Raises: ValueError
– If the JSON or the password used for the encryption is invalid.
-
factom_did.client.encryptor.
decrypt_keys_from_json_file
(file_path, password)¶ Decrypts keys from JSON file and password. The file must contain valid JSON with a schema compatible with the one produced by DID.export_encrypted_keys_as_json(). See decrypt_keys_from_json_str for details.
Parameters: - file_path (str) – Path to a file to read from.
- password (str) – A password used for the encryption of the keys.
Returns: An object containing dictionaries of decrypted management and did keys.
Return type: obj
Raises: ValueError
– If the file or the password is invalid.
client.enums module¶
-
class
factom_did.client.enums.
KeyType
¶ Bases:
enum.Enum
An enumeration.
-
ECDSA
= 'ECDSASecp256k1VerificationKey'¶
-
EdDSA
= 'Ed25519VerificationKey'¶
-
RSA
= 'RSAVerificationKey'¶
-
from_str
= <function KeyType.from_str>¶
-
-
class
factom_did.client.enums.
EntryType
¶ Bases:
enum.Enum
An enumeration.
-
Create
= 'DIDManagement'¶
-
Deactivation
= 'DIDDeactivation'¶
-
Update
= 'DIDUpdate'¶
-
VersionUpgrade
= 'DIDMethodVersionUpgrade'¶
-
client.keys package¶
client.service module¶
-
class
factom_did.client.service.
Service
(alias, service_type, endpoint, priority_requirement=None, custom_fields=None)¶ Bases:
object
Represent a service associated with a DID. A service is an end-point, which can be used to communicate with the DID or to carry out different tasks on behalf of the DID (such as signatures, e.g.)
-
alias
¶ A human-readable nickname for the service endpoint.
Type: str
-
service_type
¶ Type of the service endpoint (e.g. email, credential store).
Type: str
-
endpoint
¶ A service endpoint may represent any type of service the subject wishes to advertise, including decentralized identity management services for further discovery, authentication, authorization, or interaction. The service endpoint must be a valid URL.
Type: str
-
priority_requirement
¶ A non-negative integer showing the minimum hierarchical level a key must have in order to remove this service.
Type: int, optional
-
custom_fields
¶ A dictionary containing custom fields (e.g “description”: “My public social inbox”).
Type: dict, optional
-
static
from_entry_dict
(entry_dict, version='1.0.0')¶
-
full_id
(did)¶ Returns: The full id for the service, constituting of the DID_METHOD_NAME, the controller and the service alias. Return type: str
-
to_entry_dict
(did, version='1.0.0')¶ Converts the object to a dictionary suitable for recording on-chain.
Parameters: - did (str) – The DID to which this service belongs.
- version (str) – The entry schema version
Raises: NotImplementedError
– If the entry schema version is not supported
-
client.updater module¶
-
class
factom_did.client.updater.
DIDUpdater
(did)¶ Bases:
object
Facilitates the creation of an update entry for an existing DID.
Provides support for adding and revoking management keys, DID keys and services.
-
did
¶ The DID object to update
Type: client.did.DID
-
add_did_key
(alias, purpose, key_type=<KeyType.EdDSA: 'Ed25519VerificationKey'>, controller=None, priority_requirement=None)¶ Adds a DID key to the DID object.
Parameters: - alias (str) –
- purpose (did.enums.DIDKeyPurpose) –
- key_type (KeyType, optional) –
- controller (str, optional) –
- priority_requirement (int, optional) –
-
add_management_key
(alias, priority, key_type=<KeyType.EdDSA: 'Ed25519VerificationKey'>, controller=None, priority_requirement=None)¶ Adds a management key to the DID object.
Parameters: - alias (str) –
- priority (int) –
- key_type (KeyType, optional) –
- controller (str, optional) –
- priority_requirement (int, optional) –
-
add_service
(alias, service_type, endpoint, priority_requirement=None, custom_fields=None)¶ Adds a service to the DID object.
Parameters: - alias (str) –
- service_type (str) –
- endpoint (str) –
- priority_requirement (int, optional) –
- custom_fields (dict, optional) –
-
static
exists_management_key_with_priority_zero
(active_management_keys, new_management_keys, management_keys_to_revoke)¶ Checks if a management key of priority zero would be present if the management keys will be updated according to the given parameters.
Parameters: - active_management_keys (set) – The currently active management keys
- new_management_keys (set) – The management keys to be added
- management_keys_to_revoke (set) – The management keys to be revoked
Returns: Return type: bool
-
export_entry_data
()¶ Constructs a signed DIDUpdate entry ready for recording on-chain.
Returns: A dictionary with ExtIDs and content for the entry Return type: dict Raises: RuntimeError
– If a management key of sufficient priority is not available to sign the update.
-
get_updated
()¶
-
record_on_chain
(factomd, walletd, ec_address, verbose=False)¶ Attempts to record the DIDUpdate entry on-chain.
Parameters: - factomd (obj) – Factomd instance, instantiated from the Python factom-api package.
- walletd (obj) – Factom walletd instance, instantiated from the Python factom-api package.
- ec_address (str) – EC address used to pay for the chain & entry creation.
- verbose (bool, optional) – If true, display the contents of the entry that will be recorded on-chain.
Raises: RuntimeError
– If the entry cannot be recorded
-
revoke_did_key
(alias)¶ Revokes a DID key from the DID object.
Parameters: alias (str) – The alias of the key to be revoked
-
revoke_did_key_purpose
(alias, purpose)¶ Revokes a single purpose of a DID key from DID object.
Parameters: - alias (str) – The alias of the DID key
- purpose (DIDKeyPurpose) – The purpose to revoke
-
revoke_management_key
(alias)¶ Revokes a management key from the DID object.
Parameters: alias (str) – The alias of the key to be revoked
-
revoke_service
(alias)¶ Revokes a service from the DID object.
Parameters: alias (str) – The alias of the service to be revoked
-
rotate_did_key
(alias)¶ Rotates a DID key.
Parameters: alias (str) – The alias of the DID key to be rotated
-
rotate_management_key
(alias)¶ Rotates a management key.
Parameters: alias (str) – The alias of the management key to be rotated
-