From da470746de8ddf2f0839ec659e769af51d3b6b66 Mon Sep 17 00:00:00 2001 From: Zicchio <33022304+Zicchio@users.noreply.github.com> Date: Thu, 24 Oct 2024 14:40:15 +0200 Subject: [PATCH] feat: docs (#291) * feat: trust docs + lint * feat: storage ttl docs --- README.SATOSA.md | 86 +++++++++++++++++++++++++----------------------- docs/STORAGE.md | 2 ++ docs/TRUST.md | 52 +++++++++++++++++++++++++++++ 3 files changed, 98 insertions(+), 42 deletions(-) create mode 100644 docs/TRUST.md diff --git a/README.SATOSA.md b/README.SATOSA.md index 10287161..393b158a 100644 --- a/README.SATOSA.md +++ b/README.SATOSA.md @@ -17,14 +17,14 @@ To install the OpenID4VP SATOSA backend you just need to: 4. In `plugins/microservices/target_based_routing.yaml` please add ` "https://eudi.wallet.gov.it": "OpenID4VP"` 5. Customize [example/satosa/static/disco.html](example/satosa/static/disco.html), then copy it in satosa static file folder. Example `example/static/static/disco.html` 6. Customize [example/satosa/templates/*.html](example/satosa/templates/*.html), then copy it in satosa templates file folder (the path your have configured in your `pyeudiw_backend.yaml` file). -7. Customize [example/satosa/internal_attributes.yaml](example/satosa/internal_attributes.yaml), then copy it the path your have configured in your `proxy_conf.yaml` file). +7. Customize [example/satosa/internal_attributes.yaml](example/satosa/internal_attributes.yaml), then copy it the path your have configured in your `proxy_conf.yaml` file. ### Backend Configuration Parameters #### Top-Level | Parameter | Description | Example value | -|-----------|----------------------------------------------------|-----------------------------------------| +| --------- | -------------------------------------------------- | --------------------------------------- | | module | The name of the module that implements the backend | pyeudiw.satosa.backend.OpenID4VPBackend | | name | The name of the backend | OpenID4VP | @@ -33,7 +33,7 @@ To install the OpenID4VP SATOSA backend you just need to: ##### UI | Parameter | Description | Example value | -|------------------------------|-----------------------------------------------|-----------------------------------| +| ---------------------------- | --------------------------------------------- | --------------------------------- | | config.ui.static_storage_url | The URL of the static storage for the UI | https://localhost/static | | config.ui.template_folder | The folder where the UI templates are located | templates | | config.ui.qrcode_template | The name of the template for the QR code | qr_code.html | @@ -43,7 +43,7 @@ To install the OpenID4VP SATOSA backend you just need to: ##### Endpoints | Parameter | Description | Example value | -|---------------------------------------|---------------------------------------------------|--------------------------------| +| ------------------------------------- | ------------------------------------------------- | ------------------------------ | | config.endpoints.pre_request | The endpoint for the pre-request | /pre-request | | config.endpoints.response | The endpoint for the response | /response-uri | | config.endpoints.request | The endpoint for the request | /request-uri | @@ -54,7 +54,7 @@ To install the OpenID4VP SATOSA backend you just need to: ##### QR Code | Parameter | Description | Example value | -|-------------------------------|----------------------------------------------------|---------------| +| ----------------------------- | -------------------------------------------------- | ------------- | | config.qrcode.size | The size of the QR code in pixels | 100 | | config.qrcode.color | The color of the QR code in hexadecimal | #2B4375 | | config.qrcode.expiration_time | The expiration time of the QR code in seconds | 120 | @@ -63,64 +63,65 @@ To install the OpenID4VP SATOSA backend you just need to: ##### JWT -| Parameter | Description | Example value | -|--------------------------------|---------------------------------------------------------|-----------------------------------------------------------------------------------| -| config.jwt.default_sig_alg | The default signature algorithm for the JWT | ES256 | -| config.jwt.default_enc_alg | The default encryption algorithm for the JWT | RSA-OAEP | -| config.jwt.default_enc_enc | The default encryption encoding for the JWT | A256CBC-HS512 | -| config.jwt.default_exp | The default expiration time for the JWT in minutes | 6 | -| config.jwt.enc_alg_supported | The list of supported encryption algorithms for the JWT | [RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW] | -| config.jwt.enc_enc_supported | The list of supported encryption encodings for the JWT | [A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM] | -| config.jwt.sig_alg_supported | The list of supported signature algorithms for the JWT | [RS256, RS384, RS512, ES256, ES384, ES512] | +| Parameter | Description | Example value | +| ---------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- | +| config.jwt.default_sig_alg | The default signature algorithm for the JWT | ES256 | +| config.jwt.default_enc_alg | The default encryption algorithm for the JWT | RSA-OAEP | +| config.jwt.default_enc_enc | The default encryption encoding for the JWT | A256CBC-HS512 | +| config.jwt.default_exp | The default expiration time for the JWT in minutes | 6 | +| config.jwt.enc_alg_supported | The list of supported encryption algorithms for the JWT | [RSA-OAEP, RSA-OAEP-256, ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW] | +| config.jwt.enc_enc_supported | The list of supported encryption encodings for the JWT | [A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM, A256GCM] | +| config.jwt.sig_alg_supported | The list of supported signature algorithms for the JWT | [RS256, RS384, RS512, ES256, ES384, ES512] | ##### Authorization -| Parameter | Description | Example value | -|------------------------------------------------|--------------------------------------------------------------------------------|-----------------------------------------------| -| config.authorization.url_scheme | The URL scheme for the authorization | eudiw | -| config.authorization.scopes | The list of scopes for the authorization | [pid-sd-jwt:unique_id+given_name+family_name] | -| config.authorization.default_acr_value | The default authentication context class reference value for the authorization | https://www.spid.gov.it/SpidL2 | +| Parameter | Description | Example value | +| -------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | +| config.authorization.url_scheme | The URL scheme for the authorization | eudiw | +| config.authorization.scopes | The list of scopes for the authorization | [pid-sd-jwt:unique_id+given_name+family_name] | +| config.authorization.default_acr_value | The default authentication context class reference value for the authorization | https://www.spid.gov.it/SpidL2 | ##### User Attributes -| Parameter | Description | Example value | -|------------------------------------------------|--------------------------------------------------------------------------------|--------------------------| -| config.user_attributes.unique_identifiers | The list of unique identifiers for the user attributes | [tax_id_code, unique_id] | -| config.user_attributes.subject_id_random_value | A random value to be used in hashing | CHANGE_ME! | +| Parameter | Description | Example value | +| ---------------------------------------------- | ------------------------------------------------------ | ------------------------ | +| config.user_attributes.unique_identifiers | The list of unique identifiers for the user attributes | [tax_id_code, unique_id] | +| config.user_attributes.subject_id_random_value | A random value to be used in hashing | CHANGE_ME! | ##### Network | Parameter | Description | Example Value | -|---------------------------------------------|-----------------------------------------------------------------|---------------| +| ------------------------------------------- | --------------------------------------------------------------- | ------------- | | config.network.httpc_params.connection.ssl | The flag to indicate whether to use SSL for the HTTP connection | true | | config.network.httpc_params.session.timeout | The timeout value for the HTTP session | 6 | -##### Federation - -| Parameter | Description | Example Value | -|----------------------------------------------------------------|-----------------------------------------------------------|--------------------------------------------------------------------------| -| config.federation.metadata_type | The type of metadata to use for the federation | wallet_relying_party | -| config.federation.authority_hints | The list of authority hints to use for the federation | [http://127.0.0.1:10000] | -| config.federation.trust_anchors | The list of trust anchors to use for the federation | [http://127.0.0.1:10000] | -| config.federation.default_sig_alg | The default signature algorithm to use for the federation | RS256 | -| config.federation.federation_entity_metadata.organization_name | The organization name | Developers Italia SATOSA OpenID4VP backend policy_uri, tos_uri, logo_uri | -| config.federation.federation_entity_metadata.homepage_uri | The URI of the homepage | https://developers.italia.it | -| config.federation.federation_entity_metadata.policy_uri | The URI of the policy | https://developers.italia.it/policy.html | -| config.federation.federation_entity_metadata.tos_uri | The URI of the TOS | https://developers.italia.it/tos.html | -| config.federation.federation_entity_metadata.logo_uri | The URI of the logo | https://developers.italia.it/assets/icons/logo-it.svg | -| config.federation.federation_jwks | The list of (private) JSON Web Keys for the federation | | +##### Trust + +| Parameter | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------- | +| config.trust | A dictionary of trust implementation, where the key is a user friendly identitfier and the value is described below | + +The parameters of a `config.trust` dictionary entry value are + +| Parameter | Description | Example Value | +| -------------------------------- | ----------------------------------------------------------- | -------------------------------------------- | +| config.trust..module | A python module that provides a trust implementation | pyeudiw.trust.default.direct_trust_sd_jwt_vc | +| config.trust..class | The class in the module that implements the trust interface | DirectTrustSdJwtVc | +| config.trust..config | The configuration of the class in the module | + +For more deatils on available trust implementations and their configurations, see [docs/TRUST.md](/docs/TRUST.md) ##### Metadata jwks | Parameter | Description | Example Value | -|----------------------|------------------------------------------------------|---------------| +| -------------------- | ---------------------------------------------------- | ------------- | | config.metadata_jwks | The list of (private) JSON Web Keys for the metadata | | ##### Storage | Parameter | Description | Example Value | -|-----------------------------------------------------------------------------------|--------------------------------------------------------|-------------------------------| +| --------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- | | config.storage.mongo_db.cache.module | The module name for the MongoDB cache | pyeudiw.storage.mongo_cache | | config.storage.mongo_db.cache.class | The class name for the MongoDB cache | MongoCache | | config.storage.mongo_db.cache.init_params.url | The URL for the MongoDB connection | mongodb://satosa-mongo:27017 | @@ -134,13 +135,14 @@ To install the OpenID4VP SATOSA backend you just need to: | config.storage.mongo_db.storage.init_params.conf.db_sessions_collection | The name of the collection to store sessions | sessions | | config.storage.mongo_db.storage.init_params.conf.db_trust_attestations_collection | The name of the collection to store trust attestations | trust_attestations | | config.storage.mongo_db.storage.init_params.conf.db_trust_anchors_collection | The name of the collection to store trust anchors | trust_anchors | +| config.storage.mongo_db.storage.init_params.conf.data_ttl | The lifetime duration of data in the database | 63072000 | | config.storage.mongo_db.storage.connection_params.username | The username for authentication to the database | satosa | | config.storage.mongo_db.storage.connection_params.password | The password for authentication to the database | thatpassword | ##### Metadata | Parameter | Description | Example value | -|--------------------------------------------------------|------------------------------------------------------------------------------------------|------------------------------------------------------------------| +| ------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | config.metadata.application_type | The type of application that uses the OpenID Connect protocol | web | | config.metadata.authorization_encrypted_response_alg | The algorithm used to encrypt the authorization response | `` | | config.metadata.authorization_encrypted_response_enc | The encryption method used to encrypt the authorization response | `` | @@ -164,7 +166,7 @@ To install the OpenID4VP SATOSA backend you just need to: ###### Presentation definition | Parameter | Description | Example value | -|----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------| +| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------- | | config.metadata.presentation_definition.id | The unique identifier of the presentation definition | d76c51b7-ea90-49bb-8368-6b3d194fc131 | | config.metadata.presentation_definition.input_descriptors | The list of input descriptors that specify the verifiable credentials that the client requests | See below | | config.metadata.presentation_definition.id | The unique identifier of the input descriptor | IdentityCredential | diff --git a/docs/STORAGE.md b/docs/STORAGE.md index 580ae076..a10da897 100644 --- a/docs/STORAGE.md +++ b/docs/STORAGE.md @@ -56,12 +56,14 @@ The `BaseCache` class implements the following methods: - `set`: sets the object value in the cache. ## MongoDB + In the realm of pyeudiw, seamless integration with MongoDB is facilitated through specialized classes, namely [`MongoStorage`](../pyeudiw/storage/mongo_storage.py) and [`MongoCache`](../pyeudiw/storage/mongo_cache.py). These classes not only offer a robust implementation but also serve as tangible representations of the abstract base classes, `BaseStorage` and `BaseCache`. This classes can be used as references while providing a custom implementation for other databases. +For a complete list of the MongoDB configuration parameters, see [README.SATOSA.md](/README.SATOSA.md#storage) ### Data Examples in MongoDB diff --git a/docs/TRUST.md b/docs/TRUST.md new file mode 100644 index 00000000..63cb5737 --- /dev/null +++ b/docs/TRUST.md @@ -0,0 +1,52 @@ +# Trust + +Trust module main responsability is to provide cryptographic material, metadata and revocation status of parties involved in the [OpnedID4VP](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) protocol. +Users can define their own trust module by realizing and configuring a class that satisfy the interface [pyeudiw.trust.interface.TrustEvaluator](/pyeudiw/trust/interface.py). +This project includes some default implementation of trust, whose configuration are described below. + +## Configuration of default Trust modules + +### Direct Trust for SD-JWT VC + +Module `pyeudiw.trust.default.direct_trust_sd_jwt_vc` provides a source of direct trust that can be used to validate VP tokens with format [SD-JWT VC](https://www.ietf.org/archive/id/draft-ietf-oauth-sd-jwt-vc-05.html). + +The configuration parameters of the module are the following. + +| Parameter | Description | Example Value | +| ---------------- | ----------------------------------------------------------------------- | -------------------------- | +| jwk_endpoint | Path component of the endpoint where JWT issuer metadata can be fetched | /.well-known/jwt-vc-issuer | +| httpc_parameters | (Optional) Parameters of the HTTP connection of the request above | (see below) | + +HTTPC parameters are optional and described below. + +| Parameter | Description | +| ----------------------- | --------------------------------------------------------------------------- | +| httpc_params.connection | dictionary that represents a `aiohttp._RequestOptions` used in GET requests | +| httpc_params.session | dictionary that represents the keyword arguments of `aiohttp.ClientSession` | + +Some HTTPC parameters are commonly used, have a default value and as an alternative can be optionally defined by an environment variable. + +| Parameter | Description | Default Value | Environment Variable | +| ---------------------------- | --------------------------------------------------------------- | ------------- | --------------------- | +| httpc_params.connection.ssl | The flag to indicate whether to use SSL for the HTTP connection | true | PYEUDIW_HTTPC_SSL | +| httpc_params.session.timeout | The timeout value for the HTTP session | 6 | PYEUDIW_HTTPC_TIMEOUT | + +### Federation + +Module `pyeudiw.trust.default.federation` provides a source of trusted entities and metadata based on [OpenID Federation](https://openid.net/specs/openid-federation-1_0.html) that is intended to be applicable to Issuer, Holders and Verifiers. In the specific case of the Verifier (this application), the module can expose verifier metadata at the `.well-known/openid-federation` endpoint. + +The configuration parameters of the module are the following. + + +| Parameter | Description | Example Value | +| -------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------ | +| config.federation.metadata_type | The type of metadata to use for the federation | wallet_relying_party | +| config.federation.authority_hints | The list of authority hints to use for the federation | [http://127.0.0.1:10000] | +| config.federation.trust_anchors | The list of trust anchors to use for the federation | [http://127.0.0.1:10000] | +| config.federation.default_sig_alg | The default signature algorithm to use for the federation | RS256 | +| config.federation.federation_entity_metadata.organization_name | The organization name | Developers Italia SATOSA OpenID4VP backend policy_uri, tos_uri, logo_uri | +| config.federation.federation_entity_metadata.homepage_uri | The URI of the homepage | https://developers.italia.it | +| config.federation.federation_entity_metadata.policy_uri | The URI of the policy | https://developers.italia.it/policy.html | +| config.federation.federation_entity_metadata.tos_uri | The URI of the TOS | https://developers.italia.it/tos.html | +| config.federation.federation_entity_metadata.logo_uri | The URI of the logo | https://developers.italia.it/assets/icons/logo-it.svg | +| config.federation.federation_jwks | The list of (private) JSON Web Keys for the federation | |