Skip to content

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Wallet Provider based on Spring Boot and Warden Supreme

A-SIT Plus Official GitHub license Kotlin

A Kotlin-based Spring Boot service for EUDI Wallet ecosystem attestation flows, providing challenges, token issuance, and status list management.

⚠️ Warning
This service is intended as a Technology Demonstrator!

Demo Setup

Create keystore file

keytool -genkeypair -alias CHANGEME -keyalg EC -groupname secp256r1 -storetype PKCS12 -keystore keystore.p12 -validity 3650

Customize application.yaml

The service is a Spring Boot application, configured through server/src/main/resources/application.yaml.

Module Option Description
server
port Port the server listens on
address IP address the server listens on
spring.datasource
url JDBC URL of the database (H2 in PostgreSQL mode, or PostgreSQL), default in-memory H2
username / password Credentials of the database
database
exportInterval Interval of the export scheduler (ISO 8601)
keystore
file Path to p12 keystore file
alias Alias of key to be used
secret Secret to unlock keystore file
admin
username User name of the admin login (default admin)
password Password of the admin login, plain or as hash (e.g. {bcrypt}$2a$...); empty disables login
provider
publicContext Public base url
clientId Value used as the WIA subject/client identifier
issuer Provider/certification URL used in certification information fields
solutionId Value used as the WIA wallet_name claim
solutionOid Identifies additional information in the csr attributes
endpoints
challenge Endpoint for the wallet solution to request an attestation challenge via warden-supreme
instanceAttestation Endpoint where the wallet solution posts the InstanceAttestationRequest
keyAttestation Endpoint where the wallet solution posts the KeyAttestationRequest
clientStatus Endpoint to obtain the revocation status of instance attestations
keyStorageStatus Endpoint to obtain the revocation status of key attestations
nonce Endpoint for the wallet solution to obtain a nonce for the instance attestation proof jwt
attestation.keyAttestation
maintenance Duration how long the provider maintains the keyStorageStatus
lifetime Technical validity of the key attestation jwt
attestation.instanceAttestation
maintenance Duration how long the provider maintains the clientStatus
lifetime Technical validity of the instance attestation jwt
supreme SupremeConfiguration Configuration yaml according to https://a-sit-plus.github.io/warden-supreme/integration/config

The database schema wallet_provider (spring.flyway.default-schema) is created and migrated by Flyway on startup, with the scripts in server/src/main/resources/db/walletprovider and its own history table flyway_schema_history_wallet_provider, so the provider can share a PostgreSQL database with other services, like the services of the wallet registry.

Upgrading from the Ktor version

The Ktor version kept its status lists in the tables key_storage_status and client_status_lists of the default schema. On the first start, migration V2 copies them into the provider's schema, so revocations and the status list indices are kept; the old tables are left unchanged. Before upgrading, move the database settings:

Ktor version Now
database.url spring.datasource.url; for H2 replace MODE=MYSQL with MODE=PostgreSQL
database.driver not needed, the driver is inferred from the URL
user and password spring.datasource.username and spring.datasource.password (or in the URL); none for the H2 file, as before

The provider ignores database.url and database.driver: without spring.datasource.url it would start on its default database, without the status lists of the Ktor version.

The supreme section is loaded with Warden Supreme's Spring Boot binding (config-spring), like any other Spring configuration: single values of a source with higher precedence (e.g. the config server) override those of application.yaml, a list is replaced as a whole. Not supported by this binding: overriding a value with an explicit null, and supreme values from environment variables. An empty list can only be written as Warden Supreme's sentinel value (e.g. revocation: DISABLED), as Spring reads [] like null; quote strings that look like numbers (e.g. iOS build numbers like "21E236").

For local overrides, e.g. the admin password, create application-secrets.yaml (gitignored) in the working directory:

admin:
  password: "set-a-local-password"

Run Terminal Command

./gradlew :server:bootRun

The working directory is server/, so the keystore file and application-secrets.yaml are resolved relative to it. Without spring.datasource.url the status lists are kept in an in-memory H2 database, so they are lost on restart.

Docker

For a deployment with a config server, a PostgreSQL database and the signing key in /vault, see deployment/README.md, with a sample config server file and a script for the signing key.

The image loads its configuration from a Spring Cloud Config server, i.e. the YAML file (as defined above) named ${SPRING_APPLICATION_NAME}-${SPRING_PROFILES_ACTIVE}.yaml on branch ${SPRING_CLOUD_CONFIG_LABEL}:

Variable Description
SPRING_CLOUD_CONFIG_URI URL of the config server, e.g. http://config-server:8888
SPRING_APPLICATION_NAME Name of the configuration (default wallet-provider)
SPRING_PROFILES_ACTIVE Profile of the configuration (default default)
SPRING_CLOUD_CONFIG_LABEL Branch of the configuration (default main)
PORT Port the server listens on (default 8080)
JAVA_OPTS Additional JVM options

The config server is optional: if it cannot be reached, the service starts with the defaults of application.yaml. Set SPRING_CLOUD_CONFIG_FAIL_FAST=true to stop instead. Any setting can also be given as environment variable, e.g. ADMIN_PASSWORD for admin.password.

Docker Compose

compose.yaml builds and starts the provider on http://localhost:8080 together with a PostgreSQL database, without a config server: the provider uses the defaults of application.yaml (including the supreme section), with the settings in its environment (KEYSTORE_ALIAS, KEYSTORE_SECRET, ADMIN_PASSWORD, PROVIDER_PUBLICCONTEXT and the SPRING_DATASOURCE_* connection, all CHANGEME or local defaults). The provider starts once the database accepts connections; Flyway then creates the schema wallet_provider. The status lists are kept in the volume postgres-data across restarts;

Create the signing key in ./vault (mounted read-only as /vault, gitignored) with the alias and password of compose.yaml, and start the provider:

mkdir vault
keytool -genkeypair -alias CHANGEME -keyalg EC -groupname secp256r1 -storetype PKCS12 -keystore vault/keystore.p12 \
  -storepass CHANGEME -validity 3650
docker compose up --build

The admin pages are reachable with user admin and the ADMIN_PASSWORD of compose.yaml. Change the passwords in compose.yaml (and of the keystore accordingly) for anything but a local demo. Further settings can be added to its environment, e.g. PROVIDER_SOLUTIONID for provider.solutionId.

Endpoints

Attestation & Authentication Endpoints

Endpoint Method Description
/api/v1/challenge GET Challenge for instance attestation
/api/v1/nonce GET Nonce for client authentication
/api/v1/instanceAttestation POST JSON-encoded InstanceAttestationRequest
/api/v1/keyAttestation POST JSON-encoded KeyAttestationRequest

Both POST requests are limited to supreme.maxAttestationPayloadBytes (Warden Supreme's limit for attestation proofs, 1 MiB by default); larger ones are answered with 413 Content Too Large.

/api/v1/instanceAttestation returns a Wallet Instance Attestation which is a jwt of type oauth-client-attestation+jwt extended with wallet_name, wallet_version, wallet_solution_certification_information and client_status fields according to the ts3-wallet-unit-attestation.

Example content:

{
  "sub" : "https://wallet.a-sit.at/app",
  "iat" : 1778512996,
  "exp" : 1778556196,
  "cnf" : {
    "jwk" : {
      "crv" : "P-256",
      "kty" : "EC",
      "x" : "...",
      "y" : "..."
    }
  },
  "wallet_name" : "Valera",
  "wallet_version" : "1.0",
  "wallet_solution_certification_information" : "https://wallet.a-sit.at",
  "client_status" : {
    "status" : {
      "status_list" : {
        "idx" : 0,
        "uri" : "https://wallet-provider.a-sit.plus/api/v1/clientStatus/1"
      }
    },
    "exp" : 1781191696
  }
}

/api/v1/keyAttestation returns a Key Attestation which is a jwt of type keyattestation+jwt extended with key_storage, user_authentication, certification and key_storage_status fields according to the ts3-wallet-unit-attestation. Example content:

{
  "iat" : 1778513051,
  "exp" : 1778556251,
  "attested_keys" : [ {
    "crv" : "P-256",
    "kty" : "EC",
    "x" : "...",
    "y" : "..."
  } ],
  "key_storage" : [ "iso_18045_high" ],
  "user_authentication" : [ "iso_18045_high" ],
  "certification" : "https://wallet.a-sit.at",
  "key_storage_status" : {
    "status" : {
      "status_list" : {
        "idx" : 0,
        "uri" : "https://wallet-provider.a-sit.plus/api/v1/keyStorageStatus/1"
      }
    },
    "exp" : 1781191751
  }
}

Revocations Status Endpoints

Endpoint Method Description
/api/v1/keyStorageStatus/{period} GET Status list JWT. Use uri from KeyAttestationJwt
/api/v1/clientStatus/{period} GET Status list JWT. Use uri from InstanceAttestationJwt

Web Interface

Endpoint Method Description
/ GET Overview of the provider and its endpoints
/admin/login GET/POST Login for the admin pages
/admin/key-storage-status GET/POST View and change the revocation status of key attestations (admin)
/admin/client-status GET/POST View and change the revocation status of instance attestations (admin)
/admin/logout POST Logout

References

Contributing

External contributions are greatly appreciated! Just be sure to observe the contribution guidelines (see CONTRIBUTING.md).


The Apache License does not apply to the logos, (including the A-SIT logo) and the project/module name(s), as these are the sole property of A-SIT/A-SIT Plus GmbH and may not be used in derivative works without explicit permission!

About

No description, website, or topics provided.

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages