diff --git a/cx-ssi-lib/docs/Architecture.md b/cx-ssi-lib/docs/Architecture.md new file mode 100644 index 00000000..5661e591 --- /dev/null +++ b/cx-ssi-lib/docs/Architecture.md @@ -0,0 +1,164 @@ +# Architecture + +**Documentation Template: arc42** + +arc42, the template for documentation of software and system architecture. +Template Version 8.2 EN. (based upon AsciiDoc version), January 2023 +See [arc42.org](https://arc42.org/license). + +## Introduction and Goals + +The *SSI Agent Lib* (hereafter referred to as the **lib**) is an open-source Java library developed under the Tractus-X project. It provides core functionalities and abstractions commonly required when implementing a digital wallet or any service leveraging self-sovereign identities (SSI). + +### Requirements Overview + +The lib supports the following use cases and interactions: + +| Feature | Description / Constraints | +| ------------------------------------------------------------------------------- | ------------------------- | +| [Create DID](Feature-Create-Did.md) | | +| [Parse DID](Feature-Parse-Did.md) | | +| [Generate DID document](Feature-Generate-Did-Document.md) | | +| [Resolve DID document](Feature-Resolve-Did-Document.md) | | +| [Issue Verifiable Credential](Feature-Issue-Verifiable-Credential.md) | | +| [Issue Verifiable Presentation](Feature-Issue-Verifiable-Presentation.md) | | +| [Verify Verifiable Presentation](Feature-Verify-Verifiable-Presentation.md) | | +| [Validate Verifiable Presentation](Feature-Validate-Verifiable-Presentation.md) | | +| [Generate a key pair](Feature-Generate-Key-Pair.md) | Only Ed25519 supported. | + +### Quality Goals + +| Priority | Quality Goal | Scenario | +|----------|-------------- |-------------------------------------------------------------------------------------| +| 1 | Flexibility | Support for multiple cryptographic algorithms. | +| 1 | Extensibility | Integration of custom implementations for certain aspects (e.g., DID resolution). | +| 2 | Usability | Seamless integration and usage within other systems. | + +## Architecture Constraints + +- Java is the designated programming language to ensure compatibility with the Managed Identity Wallet and the [Tractus-X EDC](https://github.com/eclipse-tractusx/tractusx-edc). +- [JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) based verifiable presentations are required for interoperability with the [DAPS](https://github.com/International-Data-Spaces-Association/IDS-G/tree/main/Components/IdentityProvider/DAPS), which uses JWT Access-Tokens for AuthN/AuthZ. +- [JsonWebKey2020](https://www.w3.org/community/reports/credentials/CG-FINAL-lds-jws2020-20220721/) serves as the Crypto Suite for Verifiable Credentials (VCs) & Verifiable Presentations (VPs). + +## System Scope and Context + +![System Scope](images/SystemScope.png) + +The SSI Lib is intended for use by the Catena-X Managed Identity Wallet (MIW), the Eclipse Dataspace Connector (EDC), and third-party self-hosted wallets. While the SSI Lib provides did:web DID resolution capabilities, it also supports external DID resolution (e.g., Uniresolver). + +## Solution Strategy + +The library adopts a stateless design with no data persistency. It offers segregated interfaces, allowing usage of both internal features and external components. For instance, internal and external + +DID resolution can be swapped (see `DidDocumentResolver.java`). + +## Building Block View + +### Whitebox Overall System + +![Whitebox System Overview](images/WhiteboxSystem.png) + +The library's building blocks are divided into various packages based on the provided SSI features, along with additional packages like `model` and `exception` for basic utilities. + +**Key Building Blocks** + +- `resolver` +- `jwt` +- `model` +- `proof` +- `serialization` +- `util` +- `validation` +- `exception` +- `did` +- `base` +- `crypt` + +**Crucial Interfaces** + +- `DidDocumentResolver` +- `LinkedDataProofGenerator` +- `validateLdProofValidator` +- `SignedJwtVerifier` +- `SignedJwtFactory` +- `JsonLdValidator` + + +#### resolver + +This component is responsible for resolving Decentralized Identifiers (DIDs). It interacts with the underlying infrastructure to retrieve and parse DID Documents associated with a given DID. + +#### jwt + +The JWT (JSON Web Tokens) component is responsible for creating and verifying JWT-based verifiable presentations and credentials. It ensures the proper formatting and signing of JWTs. + +#### model + +The model component contains the data structures and classes used across the library. It defines the main objects (like DID, Verifiable Credential, etc.) that the library operates on. + +#### proof + +This component deals with the creation and validation of Linked Data Proofs. It generates proofs for Verifiable Credentials and validates incoming proofs. + +#### serialization + +The serialization component converts between the library's internal data structures and the JSON-LD format used in SSI. It is essential for the import and export of SSI data. + +#### util + +The util (or utility) component includes helper functions and classes used across the library. This may involve utility functions for encoding/decoding, date and time handling, etc. + +#### validation + +The validation component verifies that data is correctly formatted and valid according to the defined schemas and specifications. It is used in multiple contexts, such as when receiving Verifiable Credentials or Verifiable Presentations. + +#### exception + +The exception component defines the error and exception classes used in the library. It provides structured error handling and aids in debugging and error tracking. + +#### did + +The DID component involves all functionality specifically related to DIDs, such as generation, parsing, and formatting of DIDs and DID Documents. + +#### base + +The base component includes fundamental functionality and classes used throughout the library, setting the base structure of the library. + +#### crypt + +The crypt (or cryptography) component is responsible for all cryptographic operations, like signing, verification, and key generation. It directly supports JsonWebKey2020 based operations. + +## Runtime View + +Refer to the respective Feature Specs for insights into the library's runtime behavior. + +## Deployment View + +The SSI Lib can be integrated into an application as a standard JAR file through common build tools (i.e., Maven, Gradle, etc.). Therefore, no additional deployment artifacts are necessary. + +## Cross-cutting Concepts + +### Extensibility +The architecture is designed to allow for the easy addition and integration of new features or alterations to existing ones. This is evident in the support for custom implementations (e.g., DID resolution) and the use of interfaces to allow flexibility in the underlying implementations. + +### Exception Handling +Exception handling is a recurring concept in the architecture. The library has the exception building block, and other building blocks should follow consistent practices for error/exception handling to ensure robust operation. + +## Architecture Decisions + +## Quality Requirements + +- The library should create a JWT-based proof via JsonWebKey2020 / ED25519 signature within 0.5 seconds on current-generation server hardware under normal load (< 50% CPU Utilization) + +## Risks and Technical Debts + +- Currently, only ED25519 is supported. +- No formal interface exists for key encoding; it currently uses a byte array. + +## Glossary + +| Term | Definition | +|------|------------------------------------| +| EDC | Eclipse Dataspace Connector | +| MIW | Managed Identity Wallet | +| SSI | Self-Sovereign Identity | diff --git a/cx-ssi-lib/docs/Documentation.pdf b/cx-ssi-lib/docs/Documentation.pdf new file mode 100644 index 00000000..70c1c4fd Binary files /dev/null and b/cx-ssi-lib/docs/Documentation.pdf differ diff --git a/cx-ssi-lib/docs/Feature-Create-Did.md b/cx-ssi-lib/docs/Feature-Create-Did.md new file mode 100644 index 00000000..e18be555 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Create-Did.md @@ -0,0 +1,38 @@ +# Feature: Create DID + +## 1. Specification + +Create a Decentralized Identifier (DID) as specified in [W3C-DID-Core](https://www.w3.org/TR/did-core/), for a set of supported DID methods. + +*Example:* +``` +did:web:mydomain.com:12345 +``` + +#### 1.1 Assumptions +There is no need to ensure uniqueness of the created DID. + +#### 1.2 Constraints +Currently only DID method **did:web** *MUST* be supported. + +#### 1.3 System Environment +Any kind of registration process of a DID is out of scope and needs to be handled by the client. + +## 2. Architecture + +#### 2.1 Class Diagram + +![CreateParseDid.png](images/CreateParseDid.png) + +* DidFactory - Public factory interface. +* DidMethod - Defines a DID method, and allows retrieving a **CreateDidOptions** object specific to the respective DID method. +* CreateDidOptions - Marker interface. Implementations hold properties required to create a new DID of the respective **DidMethod**. +* DidFactoryRegistry - *MAY* be used to register **DidFactory** implementations for multiple **DidMethod**s +* DidWebMethod - Example implementation of **DidMethod** for method *did:web*. +* CreateDidWebOptions - Example implementation of **CreateDidOptions** for method *did:web*. +* Did - Value class representing a DID. *MAY* refer to a **DidDocument** +* DidDocument - Value class representing a DID document. + + + + diff --git a/cx-ssi-lib/docs/Feature-Generate-Did-Document.md b/cx-ssi-lib/docs/Feature-Generate-Did-Document.md new file mode 100644 index 00000000..8f9fe234 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Generate-Did-Document.md @@ -0,0 +1,52 @@ +# Feature: Generate DID Document + +## 1. Specification + +Given a valid DID, generate DID document as specified in [W3C-DID-Core](https://www.w3.org/TR/did-core/). + +*Example:* +```json +{ + "@context": [ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1", + "https://w3id.org/security/suites/ed25519-2020/v1" + ] + "id": "did:web:mydomain.com:12345", + "verificationMethod": [{ + "id": "did:web:mydomain.com:12345#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A", + "type": "JsonWebKey2020", + "controller": "did:web:mydomain.com:12345", + "publicKeyJwk": { + "crv": "Ed25519", + "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", + "kty": "OKP", + "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" + } + }, { + "id": "did:example:123456789abcdefghi#keys-1", + "type": "Ed25519VerificationKey2020", + "controller": "did:example:pqrstuvwxyz0987654321", + "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" + }], +} +``` + +#### 1.1 Assumptions +Multiple verification methods *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification type **Ed25519VerificationKey2020** needs to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams + +![CreateDidClass.png](images/CreateDidClass.png) + +#### 2.2 Sequence Diagrams + +![CreateDidSequence.png](images/CreateDidSequence.png) + +*You can find an Example of the class interactions here:* /src/main/java/org/eclipse/tractusx/ssi/examples/BuildDIDDoc.java + diff --git a/cx-ssi-lib/docs/Feature-Generate-Key-Pair.md b/cx-ssi-lib/docs/Feature-Generate-Key-Pair.md new file mode 100644 index 00000000..b4d51438 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Generate-Key-Pair.md @@ -0,0 +1,35 @@ +# Feature: Generate Key Pair + +## 1. Specification + +Given a supported key algorithm, generate a public / private key pair. + +*OPTIONAL*: +- Generated keys *MAY* be returned as strings, encoded in a supported encoding. +- The seed used to initialize the random number generator *SHOULD* be returned. +- A seed *MAY* be specified to allow generating pseudo-random key pair (e.g. for testing purposes). + +*Example:* +```json +{ + "type": "Ed25519VerificationKey2020", + "publicKeyMultibase": "z6Mkqhx5Go6yU6yVt7vsWvu4QFPW5KMVGZmQASeiAdZ9ZmXL", + "privateKeyMultibase": "zrv4DKJ9CLMzdmPanZmEi49nNMzj8MaHBH2CMfRQVdAr4FY1mpfex9qTGboUdmwvFA73zzzdqy6ycwXPrPELHQhdoCS" +} +``` + +#### 1.1 Assumptions +Multiple key algorithms *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification type **Ed25519VerificationKey2020** needs to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams + +![CreateKeypairEd25519Class.png](images/CreateKeypairEd25519Class.png) + +#### 2.2 Sequence Diagrams + +![CreateKeypairEd25519Sequence.png](images/CreateKeypairEd25519Sequence.png) diff --git a/cx-ssi-lib/docs/Feature-Issue-Verifiable-Credential.md b/cx-ssi-lib/docs/Feature-Issue-Verifiable-Credential.md new file mode 100644 index 00000000..fd183e98 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Issue-Verifiable-Credential.md @@ -0,0 +1,56 @@ +# Feature: Issue Verifiable Presentation + +## 1. Specification + +Given a JSON-LD, an issuer DID and a supported signature algorithm, generate a proof as specified in the [W3C VC-data-model, section 6.3.2](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) and return the signed verifiable credential. + +*Example:* +```json +{ + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://www.w3.org/2018/credentials/examples/v1" + ], + "id": "http://example.edu/credentials/1872", + "type": ["VerifiableCredential", "AlumniCredential"], + "issuer": "https://example.edu/issuers/565049", + "issuanceDate": "2010-01-01T19:23:24Z", + "credentialSubject": { + "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", + "alumniOf": { + "id": "did:example:c276e12ec21ebfeb1f712ebc6f1", + "name": [{ + "value": "Example University", + "lang": "en" + }, { + "value": "Exemple d'Université", + "lang": "fr" + }] + } + }, + "proof": { + "type": "RsaSignature2018", + "created": "2017-06-18T21:19:10Z", + "proofPurpose": "assertionMethod", + "verificationMethod": "https://example.edu/issuers/565049#key-1", + "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X + sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc + X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj + PAYuNzVBAh4vGHSrQyHUdBBPM" + } +} +``` + +#### 1.1 Assumptions +Multiple signature algorithms *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification type **Ed25519Signature2020** needs to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams +*Provide here any class diagrams needed to illustrate the application. These can be ordered by which component they construct or contribute to. If there is any ambiguity in the diagram or if any piece needs more description provide it here as well in a subsection.* + +#### 2.2 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* diff --git a/cx-ssi-lib/docs/Feature-Issue-Verifiable-Presentation.md b/cx-ssi-lib/docs/Feature-Issue-Verifiable-Presentation.md new file mode 100644 index 00000000..ec9e5c6c --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Issue-Verifiable-Presentation.md @@ -0,0 +1,62 @@ +# Feature: Issue Verifiable Presentation + +## 1. Specification + +Given a verifiable credential, an issuer DID and an audience, return a verifiable presentation as a JWT. + +*Example: JWT payload* +```json +{ + "iss": "did:web:localhost%3A8080", + "sub": "did:web:localhost%3A8080", + "aud": "test", + "vp": { + "id": "did:web:localhost%3A8080#fd10a61d-3726-45e7-8355-db5f3a4dbe60", + "type": [ + "VerifiablePresentation" + ], + "@context": [ + "https://www.w3.org/2018/credentials/v1" + ], + "verifiableCredential": { + "@context": [ + "https://www.w3.org/2018/credentials/v1" + ], + "type": [ + "VerifiableCredential" + ], + "id": "https://localhost:8080/12345", + "issuer": "did:web:localhost%3A8080", + "issuanceDate": "2023-05-26T13:58:00Z", + "expirationDate": "2000-01-23T04:56:07Z", + "credentialSubject": { + "name": "Jane Doe", + "id": "did:example:abcdef1234567" + }, + "proof": { + "proofPurpose": "proofPurpose", + "type": "Ed25519Signature2020", + "proofValue": "zLLs4YXK4dhsaifJGmeyp23TsyUnGxJkobsT8fDgzXdq27dKFSgbXwvb857VyXRtBSLv2wBQbargrHJos93DreKT", + "verificationMethod": "did:web:localhost%3A8080#key-1", + "created": "2023-05-26T13:58:00Z" + } + } + }, + "exp": 1686311279, + "jti": "89c16630-69ca-4b18-baa7-e93d3d3a016c" +} +``` + +#### 1.1 Assumptions +Multiple signature algorithms *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification type **Ed25519Signature2020** needs to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams +*Provide here any class diagrams needed to illustrate the application. These can be ordered by which component they construct or contribute to. If there is any ambiguity in the diagram or if any piece needs more description provide it here as well in a subsection.* + +#### 2.2 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* diff --git a/cx-ssi-lib/docs/Feature-Parse-Did.md b/cx-ssi-lib/docs/Feature-Parse-Did.md new file mode 100644 index 00000000..345ed094 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Parse-Did.md @@ -0,0 +1,28 @@ +# Feature: Parse DID + +## 1. Specification + +Create a Decentralized Identifier (DID) as specified in [W3C-DID-Core](https://www.w3.org/TR/did-core/), for a set of supported DID methods. + +*Example:* +``` +did:web:mydomain.com:12345 +``` + +#### 1.1 Assumptions +There is no need to ensure uniqueness of the created DID. + +#### 1.2 Constraints +Currently only DID method **did:web** *MUST* be supported. + +#### 1.3 System Environment +Any kind of registration process of a DID is out of scope and needs to be handled by the client. + +## 2. Architecture + +#### 2.1 Class Diagrams +![ResolveDIDdoc.png](images/CreateParseDid.png) + + +#### 2.2 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* diff --git a/cx-ssi-lib/docs/Feature-Resolve-Did-Document.md b/cx-ssi-lib/docs/Feature-Resolve-Did-Document.md new file mode 100644 index 00000000..cf8bab38 --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Resolve-Did-Document.md @@ -0,0 +1,59 @@ +# Feature: Resolve DID Document + +## 1. Specification + +Given a valid DID, retrieve the respective DID document as specified in [W3C-DID-Core](https://www.w3.org/TR/did-core/), for a set of supported DID methods. + +*Example:* +```json +{ + "@context": [ + "https://www.w3.org/ns/did/v1", + "https://w3id.org/security/suites/jws-2020/v1", + "https://w3id.org/security/suites/ed25519-2020/v1" + ] + "id": "did:web:mydomain.com:12345", + "verificationMethod": [{ + "id": "did:web:mydomain.com:12345#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A", + "type": "JsonWebKey2020", + "controller": "did:web:mydomain.com:12345", + "publicKeyJwk": { + "crv": "Ed25519", + "x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ", + "kty": "OKP", + "kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A" + } + }, { + "id": "did:example:123456789abcdefghi#keys-1", + "type": "Ed25519VerificationKey2020", + "controller": "did:example:pqrstuvwxyz0987654321", + "publicKeyMultibase": "zH3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" + }], +} +``` + +#### 1.1 Assumptions +* There *MAY* be muliple resolvers available for a given DID method. +* The priority of the resolvers *MUST* be customizable. +* A resolver *MAY* support multiple DID methods. + +#### 1.2 Constraints +*none* + +#### 1.3 System Environment +If the resolver is running as a separate process, all operational & communication aspects are out of scope. + +## 2. Architecture + +#### 2.1 Overview +Define a public resolver interface and exception class. This enables clients to freely choose the provided implementations or use a custom one. +The *isResolvable* method *SHOULD* be used to determine whether the resolver is able to resolve the DID document of a provided DID without actually doing it, which allows to apply a ressource efficient 'fail early' strategy. +Support for multiple resolvers is achieved by a resolver that applies the [Composite Pattern](https://en.wikipedia.org/wiki/Composite_pattern) to execute the provided resolvers in sequence. + +#### 2.2 Class Diagrams +![ResolveDidDoc.png](images/ResolveDidDoc.png) + +* DidResolver - Public interface to be used by clients. +* DidResolverException - Exception class to be thrown when a DID cannot be resolved. +* DidWebResolver / DidUniResolverAdapter - Examples of implementations of the *DidResolver* interface. +* CompositeDidResolver - *DidResolver* implementation that is able to chain multiple resolvers. It may execute the *resolve* method of each provided resolver until a DID document is returned. diff --git a/cx-ssi-lib/docs/Feature-Validate-Verifiable-Presentation.md b/cx-ssi-lib/docs/Feature-Validate-Verifiable-Presentation.md new file mode 100644 index 00000000..393cc67d --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Validate-Verifiable-Presentation.md @@ -0,0 +1,65 @@ +# Feature: Validate Verifiable Presentation + +## 1. Specification + +Given a verifiable presentation, evaluate if the presention is valid. +The validity *MAY* be determined based on different criteria, e.g. +- expiration date +- expected audience + +*Example: JWT payload* +```json +{ + "iss": "did:web:localhost%3A8080", + "sub": "did:web:localhost%3A8080", + "aud": "test", + "vp": { + "id": "did:web:localhost%3A8080#fd10a61d-3726-45e7-8355-db5f3a4dbe60", + "type": [ + "VerifiablePresentation" + ], + "@context": [ + "https://www.w3.org/2018/credentials/v1" + ], + "verifiableCredential": { + "@context": [ + "https://www.w3.org/2018/credentials/v1" + ], + "type": [ + "VerifiableCredential" + ], + "id": "https://localhost:8080/12345", + "issuer": "did:web:localhost%3A8080", + "issuanceDate": "2023-05-26T13:58:00Z", + "expirationDate": "2000-01-23T04:56:07Z", + "credentialSubject": { + "name": "Jane Doe", + "id": "did:example:abcdef1234567" + }, + "proof": { + "proofPurpose": "proofPurpose", + "type": "Ed25519Signature2020", + "proofValue": "zLLs4YXK4dhsaifJGmeyp23TsyUnGxJkobsT8fDgzXdq27dKFSgbXwvb857VyXRtBSLv2wBQbargrHJos93DreKT", + "verificationMethod": "did:web:localhost%3A8080#key-1", + "created": "2023-05-26T13:58:00Z" + } + } + }, + "exp": 1686311279, + "jti": "89c16630-69ca-4b18-baa7-e93d3d3a016c" +} +``` + +#### 1.1 Assumptions +Multiple signature algorithms *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification type **Ed25519Signature2020** needs to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams +*Provide here any class diagrams needed to illustrate the application. These can be ordered by which component they construct or contribute to. If there is any ambiguity in the diagram or if any piece needs more description provide it here as well in a subsection.* + +#### 2.2 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* diff --git a/cx-ssi-lib/docs/Feature-Verify-Verifiable-Presentation.md b/cx-ssi-lib/docs/Feature-Verify-Verifiable-Presentation.md new file mode 100644 index 00000000..2827827e --- /dev/null +++ b/cx-ssi-lib/docs/Feature-Verify-Verifiable-Presentation.md @@ -0,0 +1,19 @@ +# Feature: Verify Verifiable Presentation + +## 1. Specification + +Given a verifiable presentation, verify if the provided signatures are valid. + +#### 1.1 Assumptions +Multiple signature algorithms *SHOULD* be supported. + +#### 1.2 Constraints +Currently only verification types **Ed25519Signature2020** and **JsonWebKey2020** need to be supported. + +## 2. Architecture + +#### 2.1 Class Diagrams +*Provide here any class diagrams needed to illustrate the application. These can be ordered by which component they construct or contribute to. If there is any ambiguity in the diagram or if any piece needs more description provide it here as well in a subsection.* + +#### 2.2 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* diff --git a/cx-ssi-lib/docs/README.md b/cx-ssi-lib/docs/README.md index 2bf0ede2..fb6a3d42 100644 --- a/cx-ssi-lib/docs/README.md +++ b/cx-ssi-lib/docs/README.md @@ -1,6 +1,4 @@ -# Documentation - - +# Readme ## Installation diff --git a/cx-ssi-lib/docs/Test.md b/cx-ssi-lib/docs/Test.md new file mode 100644 index 00000000..e65882e3 --- /dev/null +++ b/cx-ssi-lib/docs/Test.md @@ -0,0 +1,51 @@ +# Testing: Create DID + +## 1. Specification + +Create a Decentralized Identifier (DID) as specified in [W3C-DID-Core](https://www.w3.org/TR/did-core/), for a set of supported DID methods. + +*Example:* +``` +did:web:mydomain.com:12345 +``` + +#### 1.1 Assumptions +There is no need to ensure uniqueness of the created DID. + +#### 1.2 Constraints +Currently only DID method **did:web** *MUST* be supported. + +#### 1.3 System Environment +Any kind of registration process of a DID is out of scope and needs to be handled by the client. + +## 2. Architecture + +#### 2.1 Overview +*Provide here a descriptive overview of the software/system/application architecture.* + +#### 2.2 Component Diagrams +*Provide here the diagram and a detailed description of its most valuable parts. There may be multiple diagrams. Include a description for each diagram. Subsections can be used to list components and their descriptions.* + +#### 2.3 Class Diagrams +*Provide here any class diagrams needed to illustrate the application. These can be ordered by which component they construct or contribute to. If there is any ambiguity in the diagram or if any piece needs more description provide it here as well in a subsection.* + +#### 2.4 Sequence Diagrams +*Provide here any sequence diagrams. If possible list the use case they contribute to or solve. Provide descriptions if possible.* + +#### 2.5 Deployment Diagrams +*Provide here the deployment diagram for the system including any information needed to describe it. Also, include any information needed to describe future scaling of the system.* + +#### 2.6 Other Diagrams +*Provide here any additional diagrams and their descriptions in subsections.* + +## 3 User Interface Design +*Provide here any user interface mock-ups or templates. Include explanations to describe the screen flow or progression.* + +## 4 Appendices and References + + +#### 4.1 Definitions and Abbreviations +*List here any definitions or abbreviations that could be used to help a new team member understand any jargon that is frequently referenced in the design document.* + +#### 4.2 References +*List here any references that can be used to give extra information on a topic found in the design document. These references can be referred to using superscript in the rest of the document.* diff --git a/cx-ssi-lib/docs/images/CreateDidClass.png b/cx-ssi-lib/docs/images/CreateDidClass.png new file mode 100644 index 00000000..c1ae4cf5 Binary files /dev/null and b/cx-ssi-lib/docs/images/CreateDidClass.png differ diff --git a/cx-ssi-lib/docs/images/CreateDidSequence.png b/cx-ssi-lib/docs/images/CreateDidSequence.png new file mode 100644 index 00000000..c8c72aeb Binary files /dev/null and b/cx-ssi-lib/docs/images/CreateDidSequence.png differ diff --git a/cx-ssi-lib/docs/images/CreateKeypairEd25519Class.png b/cx-ssi-lib/docs/images/CreateKeypairEd25519Class.png new file mode 100644 index 00000000..37679ff3 Binary files /dev/null and b/cx-ssi-lib/docs/images/CreateKeypairEd25519Class.png differ diff --git a/cx-ssi-lib/docs/images/CreateKeypairEd25519Sequence.png b/cx-ssi-lib/docs/images/CreateKeypairEd25519Sequence.png new file mode 100644 index 00000000..05b8d756 Binary files /dev/null and b/cx-ssi-lib/docs/images/CreateKeypairEd25519Sequence.png differ diff --git a/cx-ssi-lib/docs/images/CreateParseDid.png b/cx-ssi-lib/docs/images/CreateParseDid.png new file mode 100644 index 00000000..6b718e17 Binary files /dev/null and b/cx-ssi-lib/docs/images/CreateParseDid.png differ diff --git a/cx-ssi-lib/docs/images/ResolveDidDoc.png b/cx-ssi-lib/docs/images/ResolveDidDoc.png new file mode 100644 index 00000000..137b624c Binary files /dev/null and b/cx-ssi-lib/docs/images/ResolveDidDoc.png differ diff --git a/cx-ssi-lib/docs/images/SystemScope.png b/cx-ssi-lib/docs/images/SystemScope.png new file mode 100644 index 00000000..d84c8c8a Binary files /dev/null and b/cx-ssi-lib/docs/images/SystemScope.png differ diff --git a/cx-ssi-lib/docs/images/WhiteboxSystem.png b/cx-ssi-lib/docs/images/WhiteboxSystem.png new file mode 100644 index 00000000..5b56bb87 Binary files /dev/null and b/cx-ssi-lib/docs/images/WhiteboxSystem.png differ diff --git a/cx-ssi-lib/docs/pandoc.Dockerfile b/cx-ssi-lib/docs/pandoc.Dockerfile new file mode 100644 index 00000000..6e5ebce0 --- /dev/null +++ b/cx-ssi-lib/docs/pandoc.Dockerfile @@ -0,0 +1,12 @@ +FROM pandoc/latex:latest-ubuntu + +COPY . /data +WORKDIR /data +# Generate md file with pandoc page break tag +RUN echo '\\newpage' > /data/newpage.md +# Replace links to sub pages with anchors +RUN /bin/bash -c "sed -i -E 's/\((.*).md\)/\(#\L\1\)/g' /data/Architecture.md" +# Generate doc as pdf +RUN pandoc -s -o Documentation.pdf /data/README.md /data/newpage.md /data/Architecture.md /data/Feature-*.md /data/Test.md + +ENTRYPOINT ["tail", "-f", "/dev/null"] \ No newline at end of file diff --git a/cx-ssi-lib/docs/puml/CreateDidClass.puml b/cx-ssi-lib/docs/puml/CreateDidClass.puml new file mode 100644 index 00000000..9abf4aea --- /dev/null +++ b/cx-ssi-lib/docs/puml/CreateDidClass.puml @@ -0,0 +1,43 @@ +@startuml + +class ManagedIdentityWallet { + +fromHostname(hostName): Did +} + +class DidWebFactory { + +fromHostname(hostName): Did +} + +class MultibaseFactory { + +create(publicKey): MultibaseString +} + +class Ed25519VerificationKey2020Builder { + +id(uri): Ed25519VerificationKey2020Builder + +controller(uri): Ed25519VerificationKey2020Builder + +publicKeyMultiBase(publicKeyBase): Ed25519VerificationKey2020Builder + +build(): Ed25519VerificationKey2020 +} + +class Ed25519VerificationKey2020 { + +id: URI + +controller: URI + +publicKeyMultiBase: MultibaseString +} + +class DidDocumentBuilder { + +id(uri): DidDocumentBuilder + +verificationMethods(methods): DidDocumentBuilder + +build(): DidDocument +} + +ManagedIdentityWallet --> DidWebFactory: <> +ManagedIdentityWallet --> MultibaseFactory: <> +ManagedIdentityWallet --> Ed25519VerificationKey2020Builder: <> +ManagedIdentityWallet --> DidDocumentBuilder: <> + +Ed25519VerificationKey2020Builder --> Ed25519VerificationKey2020: <> + +DidDocumentBuilder --> DidDocument: <> + +@enduml diff --git a/cx-ssi-lib/docs/puml/CreateDidSequence.puml b/cx-ssi-lib/docs/puml/CreateDidSequence.puml new file mode 100644 index 00000000..9cf963c3 --- /dev/null +++ b/cx-ssi-lib/docs/puml/CreateDidSequence.puml @@ -0,0 +1,34 @@ +@startuml + +participant "ManagedIdentityWallet" as MIW +participant "DidWebFactory" as DWF +participant "MultibaseFactory" as MF +participant "Ed25519VerificationKey2020Builder" as EKB +participant "Ed25519VerificationKey2020" as EK +participant "DidDocumentBuilder" as DDB + +MIW -> DWF: fromHostname(hostName) +activate DWF + +MIW -> MF: create(keySet.getPublicKey()) +activate MF + +MIW -> EKB: new() +activate EKB +EKB -> EK: id(URI.create(did.toUri() + "#key-" + 1)) +EKB -> EK: controller(did.toUri()) +EKB -> EK: publicKeyMultiBase(publicKeyBase) +EKB -> EK: build() +deactivate EKB + +MIW -> DDB: new() +activate DDB +DDB -> DDB: id(did.toUri()) +DDB -> DDB: verificationMethods(verificationMethods) +DDB -> DDB: build() +deactivate DDB + +MIW <-- DDB: return +deactivate DDB + +@enduml diff --git a/cx-ssi-lib/docs/puml/CreateKeypairEd25519Class.puml b/cx-ssi-lib/docs/puml/CreateKeypairEd25519Class.puml new file mode 100644 index 00000000..5cdd891a --- /dev/null +++ b/cx-ssi-lib/docs/puml/CreateKeypairEd25519Class.puml @@ -0,0 +1,58 @@ +@startuml + +class User { +} + +class KeyPairGeneratorSpi.Ed25519 { + +initialize(int, SecureRandom) + +generateKeyPair(): KeyPair +} + +class SecureRandom { + // Methods and attributes of SecureRandom +} + +class KeyPair { + +getPublic(): PublicKey + +getPrivate(): PrivateKey +} + +class PrivateKeyFactory { + +createKey(byte[]): PrivateKey +} + +class PublicKeyFactory { + +createKey(byte[]): PublicKey +} + +class PublicKey { + // Methods and attributes of PublicKey +} + +class PrivateKey { + // Methods and attributes of PrivateKey +} + +class Ed25519PrivateKeyParameters { + // Methods and attributes of Ed25519PrivateKeyParameters +} + +class Ed25519PublicKeyParameters { + // Methods and attributes of Ed25519PublicKeyParameters +} + +User --> KeyPairGeneratorSpi.Ed25519 +User --> SecureRandom +User --> KeyPair +User --> PrivateKeyFactory +User --> PublicKeyFactory +KeyPairGeneratorSpi.Ed25519 --> SecureRandom +KeyPairGeneratorSpi.Ed25519 --> KeyPair +KeyPair --> PublicKey +KeyPair --> PrivateKey +PrivateKeyFactory --> PrivateKey +PublicKeyFactory --> PublicKey +PrivateKey --> Ed25519PrivateKeyParameters +PublicKey --> Ed25519PublicKeyParameters + +@enduml diff --git a/cx-ssi-lib/docs/puml/CreateKeypairEd25519Sequence.puml b/cx-ssi-lib/docs/puml/CreateKeypairEd25519Sequence.puml new file mode 100644 index 00000000..33c041db --- /dev/null +++ b/cx-ssi-lib/docs/puml/CreateKeypairEd25519Sequence.puml @@ -0,0 +1,20 @@ +@startuml +skinparam participantPadding 10 + +actor User + +participant "KeyPairGeneratorSpi.Ed25519" as KPG +participant "SecureRandom" as Random +participant "KeyPair" as KP +participant "PrivateKeyFactory" as PKFactory +participant "PublicKeyFactory" as PubKFactory + +User -> KPG: ed25519 = new KeyPairGeneratorSpi.Ed25519() +User -> KPG: ed25519.initialize(256, Random) +User -> KPG: keyPair = ed25519.generateKeyPair() +User -> KP: keyPair.getPublic() +User -> KP: keyPair.getPrivate() +User -> PKFactory: PrivateKeyFactory.createKey(PivKey.getEncoded()) +User -> PubKFactory: PublicKeyFactory.createKey(PubKey.getEncoded()) + +@enduml diff --git a/cx-ssi-lib/docs/puml/CreateParseDid.puml b/cx-ssi-lib/docs/puml/CreateParseDid.puml new file mode 100644 index 00000000..3fae48b2 --- /dev/null +++ b/cx-ssi-lib/docs/puml/CreateParseDid.puml @@ -0,0 +1,27 @@ +@startuml Create and parse DID +interface DidFactory { + Did : create(DidMethod method, DidMethodOptions options) +} +class DidWebFactory implements DidFactory { + Did : create(DidMethod method, DidMethodOptions options) +} +interface DidMethod { + T: newCreateOptions() +} +class DidWebMethod implements DidMethod { + + CreateDidWebOptions: newCreateOptions() +} + +interface CreateDidOptions +class CreateDidWebOptions implements CreateDidOptions + + +class Did { + -DidDocument didDoc + {static} Did : +parse(String didString) +} +class DidDocument { +} +DidWebFactory --> Did : creates +Did --> DidDocument : relates to +@endml \ No newline at end of file diff --git a/cx-ssi-lib/docs/puml/ResolveDidDoc.puml b/cx-ssi-lib/docs/puml/ResolveDidDoc.puml new file mode 100644 index 00000000..98f2aee1 --- /dev/null +++ b/cx-ssi-lib/docs/puml/ResolveDidDoc.puml @@ -0,0 +1,25 @@ +@startuml ResolveDidDoc +interface DidResolver { + DidDocument : resolve(Did did) + boolean: isResolvable(Did did) +} +class CompositeDidResolver { + +CompositeDidResolver(DidResolver[] resolvers) + -DidResolver nextResolver + +DidDocument : resolve(Did did) + +boolean : isResolvable(Did did) +} +class DidWebResolver { + +DidDocument : doResolve(Did did) + +boolean: isResolvable(Did did) +} +class DidUniResolverAdapter { + +DidDocument : doResolve(Did did) + +boolean: isResolvable(Did did) +} +class DidResolverException +DidResolver --> DidResolverException : throws +DidResolver <|-- CompositeDidResolver +DidResolver <|-- DidWebResolver +DidResolver <|-- DidUniResolverAdapter +@enduml \ No newline at end of file diff --git a/cx-ssi-lib/docs/puml/SystemScope.puml b/cx-ssi-lib/docs/puml/SystemScope.puml new file mode 100644 index 00000000..8bd80736 --- /dev/null +++ b/cx-ssi-lib/docs/puml/SystemScope.puml @@ -0,0 +1,20 @@ +@startuml SystemScope + +package "System Under Design" { + artifact "SSI-Lib" as LIB +} + +artifact "Eclipse\nDataspace\nConnector" as EDC +artifact "Managed\nIdentity\nWallet" as MIW +artifact "Self\nHosted\nWallet" as SHW + +file "DID +\nDID-Document" as DID + + +LIB .> DID : resolve (via Lib) +LIB <-- EDC : use +LIB <-- MIW : use +LIB <-- SHW : use +SHW -up-> DID : resolve (external Resolver) + +@enduml \ No newline at end of file diff --git a/cx-ssi-lib/docs/puml/WhiteboxSystem.puml b/cx-ssi-lib/docs/puml/WhiteboxSystem.puml new file mode 100644 index 00000000..9dcb2b1c --- /dev/null +++ b/cx-ssi-lib/docs/puml/WhiteboxSystem.puml @@ -0,0 +1,39 @@ +@startuml SystemScope + +component "SSI-Lib" as LIB { + component resolver + component jwt + component model + component proof + component serialization + component util + note right: should this be part\nof serialization? + component validation + component exception + component did + note right: can we merge this with resolver? + component base + note right: should be part of crypt + component crypt + note right: duplicate of ED25519 Key in model, can this be merged in model? +} + + + +interface DidDocumentResolver +resolver --- DidDocumentResolver + +interface LinkedDataProofGenerator +interface validateLdProofValidation +proof --- LinkedDataProofGenerator +proof --- validateLdProofValidation + +interface SignedJwtVerifier +jwt --- SignedJwtVerifier + +interface SignedJwtFactory +jwt --- SignedJwtFactory + +interface JsonLdValidator +validation --- JsonLdValidator +@enduml \ No newline at end of file diff --git a/cx-ssi-lib/docs/scripts/generateDoc.sh b/cx-ssi-lib/docs/scripts/generateDoc.sh new file mode 100644 index 00000000..22f9351a --- /dev/null +++ b/cx-ssi-lib/docs/scripts/generateDoc.sh @@ -0,0 +1,9 @@ +#!/bin/bash +# generates a combined PDF out of all all md files + +BASEDIR="$(dirname "$(dirname "$(readlink -fm "$0")")")" + +echo $BASEDIR +docker build --no-cache --file "$BASEDIR"/pandoc.Dockerfile -t catena-x/pandoc-generator:latest "$BASEDIR" +containerId=$(docker create catena-x/pandoc-generator:latest) +docker cp "$containerId":/data/Documentation.pdf "$BASEDIR" diff --git a/cx-ssi-lib/docs/scripts/generateImages.sh b/cx-ssi-lib/docs/scripts/generateImages.sh new file mode 100644 index 00000000..6496f0bb --- /dev/null +++ b/cx-ssi-lib/docs/scripts/generateImages.sh @@ -0,0 +1,13 @@ +#!/bin/bash +# converts all puml files to png images + +BASEDIR=$(dirname "$0")/../puml +TARGETDIR=$BASEDIR/../images +mkdir -p $TARGETDIR +for FILE in $BASEDIR/*.puml; do + echo Converting $FILE + FILE_PNG=${FILE//\.puml/\.png} + cat $FILE | docker run --rm -i think/plantuml -tpng > $FILE_PNG +done +mv $BASEDIR/*.png $TARGETDIR/ +echo Done \ No newline at end of file