diff --git a/Readme.md b/Readme.md index a18abd6..147a6d6 100644 --- a/Readme.md +++ b/Readme.md @@ -32,3 +32,126 @@ Built with ❤️ by [Consensys](https://consensys.io/). ## Concepts ![`go-did-it` concepts](.github/concepts.png) + +## Installation + +```bash +go get github.com/ucan-wg/go-did-it +``` + +## Usage + +### Signature verification + +On the verifier (~server) side, you can parse and resolve DIDs and perform signature verification: + +```go +package main + +import ( + "encoding/base64" + "fmt" + + "github.com/ucan-wg/go-did-it" + + // 0) Import the methods you want to support + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" +) + +func main() { + // 1) Parse the DID string into a DID object + d, _ := did.Parse("did:key:z6MknwcywUtTy2ADJQ8FH1GcSySKPyKDmyzT4rPEE84XREse") + + // 2) Resolve to the DID Document + doc, _ := d.Document() + + // 3) Use the appropriate set of verification methods (ex: verify a signature for authentication purpose) + sig, _ := base64.StdEncoding.DecodeString("nhpkr5a7juUM2eDpDRSJVdEE++0SYqaZXHtuvyafVFUx8zsOdDSrij+vHmd/ARwUOmi/ysmSD+b3K9WTBtmmBQ==") + if ok, method := did.TryAllVerify(doc.Authentication(), []byte("message"), sig); ok { + fmt.Println("Signature is valid, verified with method:", method.Type(), method.ID()) + } else { + fmt.Println("Signature is invalid") + } + + // Output: Signature is valid, verified with method: Ed25519VerificationKey2020 did:key:z6MknwcywUtTy2ADJQ8FH1GcSySKPyKDmyzT4rPEE84XREse#z6MknwcywUtTy2ADJQ8FH1GcSySKPyKDmyzT4rPEE84XREse +} +``` + +### Key agreement + +You can also compute a shared secret to bootstrap an encrypted communication protocol. + +> **⚠️ Security Warning**: The shared secret returned by key agreement should NOT be used directly as an encryption key. It must be processed through a Key Derivation Function (KDF) such as HKDF before being used in cryptographic protocols. Using the raw shared secret directly can lead to security vulnerabilities. + +```go +package main + +import ( + "encoding/base64" + "fmt" + + "github.com/ucan-wg/go-did-it" + "github.com/ucan-wg/go-did-it/crypto/x25519" + + // 0) Import the methods you want to support + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" +) + +func main() { + // 1) We have a private key for Alice + privAliceBytes, _ := base64.StdEncoding.DecodeString("fNOf3xWjFZYGYWixorM5+JR+u/2Udnc9Zw5+9rSvjqo=") + privAlice, _ := x25519.PrivateKeyFromBytes(privAliceBytes) + + // 2) We resolve the DID Document for Bob + dBob, _ := did.Parse("did:key:z6MkgRNXpJRbEE6FoXhT8KWHwJo4KyzFo1FdSEFpRLh5vuXZ") + docBob, _ := dBob.Document() + + // 3) We perform the key agreement + key, method, _ := did.FindMatchingKeyAgreement(docBob.KeyAgreement(), privAlice) + + fmt.Println("Shared key:", base64.StdEncoding.EncodeToString(key)) + fmt.Println("Verification method used:", method.Type(), method.ID()) + + // Output: Shared key: 7G1qwS/gn5W1hxBtObHc3F0jA7m2vuXkLJJ32yBuHVQ= + // Verification method used: X25519KeyAgreementKey2020 did:key:z6MkgRNXpJRbEE6FoXhT8KWHwJo4KyzFo1FdSEFpRLh5vuXZ#z6LSjeQx2VkXz8yirhrYJv8uicu9BBaeYU3Q1D9sFBovhmPF +} +``` + +## Features + +### Supported DID Methods + +| Method | Status | Description | +|-----------|--------|------------------------------------------| +| `did:key` | ✅ | Self-contained DIDs based on public keys | + +### Supported Verification Method Types + +| Type | Use Case | +|-------------------------------------|--------------------------| +| `EcdsaSecp256k1VerificationKey2019` | secp256k1 signatures | +| `Ed25519VerificationKey2018` | Ed25519 signatures | +| `Ed25519VerificationKey2020` | Ed25519 signatures | +| `JsonWebKey2020` | All supported algorithms | +| `Multikey` | All supported algorithms | +| `P256Key2021` | P-256 signatures | +| `X25519KeyAgreementKey2020` | X25519 key agreement | + +### Supported Cryptographic Algorithms + +#### Signing Keys +| Algorithm | Signature Format | Public Key Formats | Private Key Formats | +|-----------------|-------------------|-------------------------------------|---------------------------| +| Ed25519 | Raw bytes, ASN.1 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | +| ECDSA P-256 | Raw bytes, ASN.1 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | +| ECDSA P-384 | Raw bytes, ASN.1 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | +| ECDSA P-521 | Raw bytes, ASN.1 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | +| ECDSA secp256k1 | Raw bytes, ASN.1 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | +| RSA | PKCS#1 v1.5 ASN.1 | X.509 DER/PEM, Multibase | PKCS#8 DER/PEM | + + +#### Key Agreement (Encryption) +| Algorithm | Public Key Formats | Private Key Formats | +|-----------|-------------------------------------|---------------------------| +| X25519 | Raw bytes, X.509 DER/PEM, Multibase | Raw bytes, PKCS#8 DER/PEM | + diff --git a/did_test.go b/did_test.go index 685cfb7..2fc22ff 100644 --- a/did_test.go +++ b/did_test.go @@ -9,7 +9,7 @@ import ( "github.com/ucan-wg/go-did-it" "github.com/ucan-wg/go-did-it/crypto/x25519" - _ "github.com/ucan-wg/go-did-it/methods/did-key" + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" ) func Example_signature() { @@ -21,7 +21,7 @@ func Example_signature() { // 2) Resolve to the DID Document doc, _ := d.Document() - // 3) Use the appropriate verification method (ex: verify a signature for authentication purpose) + // 3) Use the appropriate set of verification methods (ex: verify a signature for authentication purpose) sig, _ := base64.StdEncoding.DecodeString("nhpkr5a7juUM2eDpDRSJVdEE++0SYqaZXHtuvyafVFUx8zsOdDSrij+vHmd/ARwUOmi/ysmSD+b3K9WTBtmmBQ==") if ok, method := did.TryAllVerify(doc.Authentication(), []byte("message"), sig); ok { fmt.Println("Signature is valid, verified with method:", method.Type(), method.ID()) diff --git a/document/document.go b/document/document.go index fdbb78e..cbf5754 100644 --- a/document/document.go +++ b/document/document.go @@ -8,7 +8,7 @@ import ( "net/url" "github.com/ucan-wg/go-did-it" - "github.com/ucan-wg/go-did-it/verifications" + verifications "github.com/ucan-wg/go-did-it/verifiers/_methods" ) var _ did.Document = &Document{} diff --git a/document/document_test.go b/document/document_test.go index 7f3d156..9f752af 100644 --- a/document/document_test.go +++ b/document/document_test.go @@ -6,10 +6,10 @@ import ( "github.com/stretchr/testify/require" - _ "github.com/ucan-wg/go-did-it/methods/did-key" - "github.com/ucan-wg/go-did-it/verifications/ed25519" - "github.com/ucan-wg/go-did-it/verifications/jsonwebkey" - "github.com/ucan-wg/go-did-it/verifications/x25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/jsonwebkey" + "github.com/ucan-wg/go-did-it/verifiers/_methods/x25519" + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" ) func TestRoundTrip(t *testing.T) { diff --git a/verifications/ed25519/VerificationKey2018.go b/verifiers/_methods/ed25519/VerificationKey2018.go similarity index 100% rename from verifications/ed25519/VerificationKey2018.go rename to verifiers/_methods/ed25519/VerificationKey2018.go diff --git a/verifications/ed25519/VerificationKey2018_test.go b/verifiers/_methods/ed25519/VerificationKey2018_test.go similarity index 91% rename from verifications/ed25519/VerificationKey2018_test.go rename to verifiers/_methods/ed25519/VerificationKey2018_test.go index bb41f37..fa8ff74 100644 --- a/verifications/ed25519/VerificationKey2018_test.go +++ b/verifiers/_methods/ed25519/VerificationKey2018_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - ed25519vm "github.com/ucan-wg/go-did-it/verifications/ed25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" ) func TestJsonRoundTrip2018(t *testing.T) { diff --git a/verifications/ed25519/VerificationKey2020.go b/verifiers/_methods/ed25519/VerificationKey2020.go similarity index 100% rename from verifications/ed25519/VerificationKey2020.go rename to verifiers/_methods/ed25519/VerificationKey2020.go diff --git a/verifications/ed25519/VerificationKey2020_test.go b/verifiers/_methods/ed25519/VerificationKey2020_test.go similarity index 95% rename from verifications/ed25519/VerificationKey2020_test.go rename to verifiers/_methods/ed25519/VerificationKey2020_test.go index 2ca2da2..ba22bba 100644 --- a/verifications/ed25519/VerificationKey2020_test.go +++ b/verifiers/_methods/ed25519/VerificationKey2020_test.go @@ -9,8 +9,8 @@ import ( "github.com/ucan-wg/go-did-it" "github.com/ucan-wg/go-did-it/crypto/ed25519" - _ "github.com/ucan-wg/go-did-it/methods/did-key" - "github.com/ucan-wg/go-did-it/verifications/ed25519" + ed25519vm "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" ) func TestJsonRoundTrip2020(t *testing.T) { diff --git a/verifications/json.go b/verifiers/_methods/json.go similarity index 71% rename from verifications/json.go rename to verifiers/_methods/json.go index c4ef030..dc74238 100644 --- a/verifications/json.go +++ b/verifiers/_methods/json.go @@ -1,16 +1,16 @@ -package verifications +package methods import ( "encoding/json" "fmt" "github.com/ucan-wg/go-did-it" - "github.com/ucan-wg/go-did-it/verifications/ed25519" - "github.com/ucan-wg/go-did-it/verifications/jsonwebkey" - "github.com/ucan-wg/go-did-it/verifications/multikey" - p256vm "github.com/ucan-wg/go-did-it/verifications/p256" - secp256k1vm "github.com/ucan-wg/go-did-it/verifications/secp256k1" - "github.com/ucan-wg/go-did-it/verifications/x25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/jsonwebkey" + "github.com/ucan-wg/go-did-it/verifiers/_methods/multikey" + p256vm "github.com/ucan-wg/go-did-it/verifiers/_methods/p256" + secp256k1vm "github.com/ucan-wg/go-did-it/verifiers/_methods/secp256k1" + "github.com/ucan-wg/go-did-it/verifiers/_methods/x25519" ) func UnmarshalJSON(data []byte) (did.VerificationMethod, error) { diff --git a/verifications/jsonwebkey/JsonWebKey2020.go b/verifiers/_methods/jsonwebkey/JsonWebKey2020.go similarity index 100% rename from verifications/jsonwebkey/JsonWebKey2020.go rename to verifiers/_methods/jsonwebkey/JsonWebKey2020.go diff --git a/verifications/jsonwebkey/JsonWebKey2020_test.go b/verifiers/_methods/jsonwebkey/JsonWebKey2020_test.go similarity index 100% rename from verifications/jsonwebkey/JsonWebKey2020_test.go rename to verifiers/_methods/jsonwebkey/JsonWebKey2020_test.go diff --git a/verifications/multikey/multikey.go b/verifiers/_methods/multikey/multikey.go similarity index 100% rename from verifications/multikey/multikey.go rename to verifiers/_methods/multikey/multikey.go diff --git a/verifications/multikey/multikey_test.go b/verifiers/_methods/multikey/multikey_test.go similarity index 85% rename from verifications/multikey/multikey_test.go rename to verifiers/_methods/multikey/multikey_test.go index 14bb77c..77a881d 100644 --- a/verifications/multikey/multikey_test.go +++ b/verifiers/_methods/multikey/multikey_test.go @@ -6,8 +6,9 @@ import ( "github.com/stretchr/testify/require" - _ "github.com/ucan-wg/go-did-it/methods/did-key" - "github.com/ucan-wg/go-did-it/verifications/multikey" + _ "github.com/ucan-wg/go-did-it/verifiers/did-key" + + "github.com/ucan-wg/go-did-it/verifiers/_methods/multikey" ) func TestJsonRoundTrip(t *testing.T) { diff --git a/verifications/p256/key2021.go b/verifiers/_methods/p256/key2021.go similarity index 100% rename from verifications/p256/key2021.go rename to verifiers/_methods/p256/key2021.go diff --git a/verifications/p256/key2021_test.go b/verifiers/_methods/p256/key2021_test.go similarity index 92% rename from verifications/p256/key2021_test.go rename to verifiers/_methods/p256/key2021_test.go index 6dacd0c..f208605 100644 --- a/verifications/p256/key2021_test.go +++ b/verifiers/_methods/p256/key2021_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - p256vm "github.com/ucan-wg/go-did-it/verifications/p256" + "github.com/ucan-wg/go-did-it/verifiers/_methods/p256" ) func TestJsonRoundTrip(t *testing.T) { diff --git a/verifications/secp256k1/VerificationKey2019.go b/verifiers/_methods/secp256k1/VerificationKey2019.go similarity index 100% rename from verifications/secp256k1/VerificationKey2019.go rename to verifiers/_methods/secp256k1/VerificationKey2019.go diff --git a/verifications/secp256k1/VerificationKey2019_test.go b/verifiers/_methods/secp256k1/VerificationKey2019_test.go similarity index 91% rename from verifications/secp256k1/VerificationKey2019_test.go rename to verifiers/_methods/secp256k1/VerificationKey2019_test.go index 2ecca83..68cb856 100644 --- a/verifications/secp256k1/VerificationKey2019_test.go +++ b/verifiers/_methods/secp256k1/VerificationKey2019_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - secp256k1vm "github.com/ucan-wg/go-did-it/verifications/secp256k1" + "github.com/ucan-wg/go-did-it/verifiers/_methods/secp256k1" ) func TestJsonRoundTrip(t *testing.T) { diff --git a/verifications/x25519/KeyAgreementKey2019.go b/verifiers/_methods/x25519/KeyAgreementKey2019.go similarity index 100% rename from verifications/x25519/KeyAgreementKey2019.go rename to verifiers/_methods/x25519/KeyAgreementKey2019.go diff --git a/verifications/x25519/KeyAgreementKey2019_test.go b/verifiers/_methods/x25519/KeyAgreementKey2019_test.go similarity index 91% rename from verifications/x25519/KeyAgreementKey2019_test.go rename to verifiers/_methods/x25519/KeyAgreementKey2019_test.go index 1baf13f..1289055 100644 --- a/verifications/x25519/KeyAgreementKey2019_test.go +++ b/verifiers/_methods/x25519/KeyAgreementKey2019_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - x25519vm "github.com/ucan-wg/go-did-it/verifications/x25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/x25519" ) func TestJsonRoundTrip2019(t *testing.T) { diff --git a/verifications/x25519/KeyAgreementKey2020.go b/verifiers/_methods/x25519/KeyAgreementKey2020.go similarity index 100% rename from verifications/x25519/KeyAgreementKey2020.go rename to verifiers/_methods/x25519/KeyAgreementKey2020.go diff --git a/verifications/x25519/KeyAgreementKey2020_test.go b/verifiers/_methods/x25519/KeyAgreementKey2020_test.go similarity index 91% rename from verifications/x25519/KeyAgreementKey2020_test.go rename to verifiers/_methods/x25519/KeyAgreementKey2020_test.go index f366ee8..2d1ce04 100644 --- a/verifications/x25519/KeyAgreementKey2020_test.go +++ b/verifiers/_methods/x25519/KeyAgreementKey2020_test.go @@ -6,7 +6,7 @@ import ( "github.com/stretchr/testify/require" - x25519vm "github.com/ucan-wg/go-did-it/verifications/x25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/x25519" ) func TestJsonRoundTrip2020(t *testing.T) { diff --git a/methods/did-key/document.go b/verifiers/did-key/document.go similarity index 100% rename from methods/did-key/document.go rename to verifiers/did-key/document.go diff --git a/methods/did-key/document_test.go b/verifiers/did-key/document_test.go similarity index 98% rename from methods/did-key/document_test.go rename to verifiers/did-key/document_test.go index e085bb7..4b21045 100644 --- a/methods/did-key/document_test.go +++ b/verifiers/did-key/document_test.go @@ -7,7 +7,7 @@ import ( "github.com/stretchr/testify/require" "github.com/ucan-wg/go-did-it" - "github.com/ucan-wg/go-did-it/methods/did-key/testvectors" + "github.com/ucan-wg/go-did-it/verifiers/did-key/testvectors" ) func TestDocument(t *testing.T) { diff --git a/methods/did-key/key.go b/verifiers/did-key/key.go similarity index 92% rename from methods/did-key/key.go rename to verifiers/did-key/key.go index ae92a5f..c21df4e 100644 --- a/methods/did-key/key.go +++ b/verifiers/did-key/key.go @@ -14,12 +14,12 @@ import ( "github.com/ucan-wg/go-did-it/crypto/rsa" "github.com/ucan-wg/go-did-it/crypto/secp256k1" "github.com/ucan-wg/go-did-it/crypto/x25519" - "github.com/ucan-wg/go-did-it/verifications/ed25519" - "github.com/ucan-wg/go-did-it/verifications/jsonwebkey" - "github.com/ucan-wg/go-did-it/verifications/multikey" - p256vm "github.com/ucan-wg/go-did-it/verifications/p256" - secp256k1vm "github.com/ucan-wg/go-did-it/verifications/secp256k1" - "github.com/ucan-wg/go-did-it/verifications/x25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/jsonwebkey" + "github.com/ucan-wg/go-did-it/verifiers/_methods/multikey" + "github.com/ucan-wg/go-did-it/verifiers/_methods/p256" + "github.com/ucan-wg/go-did-it/verifiers/_methods/secp256k1" + "github.com/ucan-wg/go-did-it/verifiers/_methods/x25519" ) // Specification: https://w3c-ccg.github.io/did-method-key/ diff --git a/methods/did-key/key_test.go b/verifiers/did-key/key_test.go similarity index 97% rename from methods/did-key/key_test.go rename to verifiers/did-key/key_test.go index 1431834..c995cf5 100644 --- a/methods/did-key/key_test.go +++ b/verifiers/did-key/key_test.go @@ -9,7 +9,7 @@ import ( "github.com/ucan-wg/go-did-it" "github.com/ucan-wg/go-did-it/crypto/ed25519" - didkey "github.com/ucan-wg/go-did-it/methods/did-key" + didkey "github.com/ucan-wg/go-did-it/verifiers/did-key" ) func ExampleGenerateKeyPair() { diff --git a/methods/did-key/testvectors/bls12381.json b/verifiers/did-key/testvectors/bls12381.json similarity index 100% rename from methods/did-key/testvectors/bls12381.json rename to verifiers/did-key/testvectors/bls12381.json diff --git a/methods/did-key/testvectors/ed25519-x25519.json b/verifiers/did-key/testvectors/ed25519-x25519.json similarity index 100% rename from methods/did-key/testvectors/ed25519-x25519.json rename to verifiers/did-key/testvectors/ed25519-x25519.json diff --git a/methods/did-key/testvectors/nist-curves.json b/verifiers/did-key/testvectors/nist-curves.json similarity index 100% rename from methods/did-key/testvectors/nist-curves.json rename to verifiers/did-key/testvectors/nist-curves.json diff --git a/methods/did-key/testvectors/rsa.json b/verifiers/did-key/testvectors/rsa.json similarity index 100% rename from methods/did-key/testvectors/rsa.json rename to verifiers/did-key/testvectors/rsa.json diff --git a/methods/did-key/testvectors/secp256k1.json b/verifiers/did-key/testvectors/secp256k1.json similarity index 100% rename from methods/did-key/testvectors/secp256k1.json rename to verifiers/did-key/testvectors/secp256k1.json diff --git a/methods/did-key/testvectors/vectors.go b/verifiers/did-key/testvectors/vectors.go similarity index 96% rename from methods/did-key/testvectors/vectors.go rename to verifiers/did-key/testvectors/vectors.go index 1958d16..6f31987 100644 --- a/methods/did-key/testvectors/vectors.go +++ b/verifiers/did-key/testvectors/vectors.go @@ -13,10 +13,10 @@ import ( "github.com/ucan-wg/go-did-it/crypto/jwk" "github.com/ucan-wg/go-did-it/crypto/p256" "github.com/ucan-wg/go-did-it/crypto/secp256k1" - ed25519vm "github.com/ucan-wg/go-did-it/verifications/ed25519" - "github.com/ucan-wg/go-did-it/verifications/jsonwebkey" - p256vm "github.com/ucan-wg/go-did-it/verifications/p256" - secp256k1vm "github.com/ucan-wg/go-did-it/verifications/secp256k1" + "github.com/ucan-wg/go-did-it/verifiers/_methods/ed25519" + "github.com/ucan-wg/go-did-it/verifiers/_methods/jsonwebkey" + "github.com/ucan-wg/go-did-it/verifiers/_methods/p256" + "github.com/ucan-wg/go-did-it/verifiers/_methods/secp256k1" ) // Origin: https://github.com/w3c-ccg/did-key-spec/tree/main/test-vectors diff --git a/methods/did-key/testvectors/x25519.json b/verifiers/did-key/testvectors/x25519.json similarity index 100% rename from methods/did-key/testvectors/x25519.json rename to verifiers/did-key/testvectors/x25519.json