Basic DIDComm v2 support in python
Project description
DIDComm Python
Basic DIDComm v2 support in Python.
Installation
pip install didcomm
DIDComm + peerdid Demo
See https://github.com/sicpa-dlab/didcomm-demo.
Assumptions and Limitations
- Python >= 3.7.
- In order to use the library,
SecretsResolver
andDIDResolver
interfaces must be implemented on the application level. Implementation of that interfaces is out of DIDComm library scope.- Verification materials are expected in JWK, Base58 and Multibase (internally Base58 only) formats.
- In Base58 and Multibase formats, keys using only X25519 and Ed25519 curves are supported.
- For private keys in Base58 and Multibase formats, the verification material value contains both private and public parts (concatenated bytes).
- In Multibase format, bytes of the verification material value is prefixed with the corresponding Multicodec code.
- Key IDs (kids) used in
SecretsResolver
must match the corresponding key IDs from DID Doc verification methods. - Key IDs (kids) in DID Doc verification methods and secrets must be a full DID Fragment, that is
did#key-id
. - Verification methods referencing another DID Document are not supported (see Referring to Verification Methods).
- Verification materials are expected in JWK, Base58 and Multibase (internally Base58 only) formats.
- The following curves and algorithms are supported:
- Encryption:
- Curves: X25519, P-384, P-256, P-521
- Content encryption algorithms:
- XC20P (to be used with ECDH-ES only, default for anoncrypt),
- A256GCM (to be used with ECDH-ES only),
- A256CBC-HS512 (default for authcrypt)
- Key wrapping algorithms: ECDH-ES+A256KW, ECDH-1PU+A256KW
- Signing:
- Curves: Ed25519, Secp256k1, P-256
- Algorithms: EdDSA (with crv=Ed25519), ES256, ES256K
- Encryption:
- Forward protocol is implemented and used by default.
- DID rotation (
fromPrior
field) is supported. - DIDComm has been implemented under the following Assumptions
Examples
See demo scripts for details.
A general usage of the API is the following:
- Sender Side:
- Build a
Message
(plaintext, payload). - Convert a message to a DIDComm Message for further transporting by calling one of the following:
pack_encrypted
to build an Encrypted DIDComm messagepack_signed
to build a Signed DIDComm messagepack_plaintext
to build a Plaintext DIDComm message
- Build a
- Receiver side:
- Call
unpack
on receiver side that will decrypt the message, verify signature if needed and return aMessage
for further processing on the application level.
- Call
1. Build an Encrypted DIDComm message for the given recipient
This is the most common DIDComm message to be used in most of the applications.
A DIDComm encrypted message is an encrypted JWM (JSON Web Messages) that
- hides its content from all but authorized recipients
- (optionally) discloses and proves the sender to only those recipients
- provides message integrity guarantees
It is important in privacy-preserving routing. It is what normally moves over network transports in DIDComm applications, and is the safest format for storing DIDComm data at rest.
See pack_encrypted
documentation for more details.
Authentication encryption example (most common case):
# ALICE
message = Message(
body={"aaa": 1, "bbb": 2},
id="1234567890",
type="my-protocol/1.0",
frm=ALICE_DID,
to=[BOB_DID],
)
pack_result = await pack_encrypted(
resolvers_config=resolvers_config_alice,
message=message,
frm=ALICE_DID,
to=BOB_DID,
pack_config=PackEncryptedConfig(),
)
packed_msg = pack_result.packed_msg
print(f"Sending ${packed_msg} to ${pack_result.service_metadata.service_endpoint}")
# BOB
unpack_result = await unpack(resolvers_config_bob, packed_msg)
print(f"Got ${unpack_result.message} message")
Anonymous encryption example:
message = Message(
body={"aaa": 1, "bbb": 2},
id="1234567890",
type="my-protocol/1.0",
frm=ALICE_DID,
to=[BOB_DID],
)
pack_result = await pack_encrypted(
resolvers_config=resolvers_config_alice,
message=message,
to=BOB_DID,
pack_config=PackEncryptedConfig(),
)
Encryption with non-repudiation example:
message = Message(
body={"aaa": 1, "bbb": 2},
id="1234567890",
type="my-protocol/1.0",
frm=ALICE_DID,
to=[BOB_DID],
)
pack_result = await pack_encrypted(
resolvers_config=resolvers_config_alice,
message=message,
frm=ALICE_DID,
sign_frm=ALICE_DID,
to=BOB_DID,
pack_config=PackEncryptedConfig(),
)
2. Build an unencrypted but Signed DIDComm message
Signed messages are only necessary when
- the origin of plaintext must be provable to third parties
- or the sender can’t be proven to the recipient by authenticated encryption because the recipient is not known in advance (e.g., in a broadcast scenario).
Adding a signature when one is not needed can degrade rather than enhance security because it relinquishes the sender’s ability to speak off the record.
See pack_signed
documentation for more details.
# ALICE
message = Message(
body={"aaa": 1, "bbb": 2},
id="1234567890",
type="my-protocol/1.0",
frm=ALICE_DID,
to=[BOB_DID],
)
pack_result = await pack_signed(
resolvers_config=resolvers_config_alice,
message=message,
sign_frm=ALICE_DID
)
packed_msg = pack_result.packed_msg
print(f"Publishing ${packed_msg}")
# BOB
unpack_result = await unpack(resolvers_config_bob, packed_msg)
print(f"Got ${unpack_result.message} message signed as ${unpack_result.metadata.signed_message}")
3. Build a Plaintext DIDComm message
A DIDComm message in its plaintext form that
- is not packaged into any protective envelope
- lacks confidentiality and integrity guarantees
- repudiable
They are therefore not normally transported across security boundaries.
# ALICE
message = Message(
body={"aaa": 1, "bbb": 2},
id="1234567890",
type="my-protocol/1.0",
frm=ALICE_DID,
to=[BOB_DID],
)
pack_result = await pack_plaintext(resolvers_config=resolvers_config_alice, message)
print(f"Publishing ${pack_result.packed_msg}")
# BOB
unpack_result = await unpack(resolvers_config_bob, pack_result.packed_msg)
print(f"Got ${unpack_result.message} message")
Contribution
PRs are welcome!
The following CI checks are run against every PR:
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file didcomm-0.3.2.tar.gz
.
File metadata
- Download URL: didcomm-0.3.2.tar.gz
- Upload date:
- Size: 36.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.2 CPython/3.10.6 Linux/5.15.0-1036-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | fde54701f5fce07d01e98f099d311f7e57fc3fa8103df93d2a4f8cd3a451a525 |
|
MD5 | 6da74c593531a745bfdbe6adb214ec21 |
|
BLAKE2b-256 | 4554e96feab80135fe5ce2c2f46284b0d00128d6ab94db6243e9b76b0b0a01b1 |
File details
Details for the file didcomm-0.3.2-py3-none-any.whl
.
File metadata
- Download URL: didcomm-0.3.2-py3-none-any.whl
- Upload date:
- Size: 57.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.4.2 CPython/3.10.6 Linux/5.15.0-1036-azure
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | e105709722623c00a54a043c8ce8cb5b8b92927d6a64f9a1c141787acc2b570f |
|
MD5 | 47ad131a453a4c150075470e5a58d984 |
|
BLAKE2b-256 | 30bcdb32cbb17ce10890eba63c652088bc20b4f3293eec3465af271a6f7f30f2 |