From 2fb2afc733aae5eec3e18fa0cd7be3d49e538634 Mon Sep 17 00:00:00 2001 From: ff137 Date: Fri, 21 Jul 2023 10:39:26 +0200 Subject: [PATCH 1/9] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20upgrade=20`pyjwt`=20to?= =?UTF-8?q?=20latest?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ff137 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 4be4b73b0f..ae33a54706 100644 --- a/requirements.txt +++ b/requirements.txt @@ -20,7 +20,7 @@ packaging~=20.4 portalocker~=2.7.0 prompt_toolkit~=2.0.9 pydid~=0.3.6 -pyjwt~=2.4.0 +pyjwt~=2.8.0 pyld~=2.0.3 pynacl~=1.5.0 python-dateutil~=2.8.1 From 2acf36a6988b638bfae28a282a06ea4b3c00dde3 Mon Sep 17 00:00:00 2001 From: ff137 Date: Mon, 24 Jul 2023 18:38:33 +0200 Subject: [PATCH 2/9] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20upgrade=20`pyjwt`=20to?= =?UTF-8?q?=202.5.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ff137 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index ddef3ec15d..1bc25bd56c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -20,7 +20,7 @@ packaging~=23.1 portalocker~=2.7.0 prompt_toolkit~=2.0.9 pydid~=0.3.6 -pyjwt~=2.8.0 +pyjwt~=2.5.0 pyld~=2.0.3 pynacl~=1.5.0 python-dateutil~=2.8.1 From 5d88a26dffa5f0c347360ca2ece71738a3c6b820 Mon Sep 17 00:00:00 2001 From: ff137 Date: Mon, 24 Jul 2023 19:25:49 +0200 Subject: [PATCH 3/9] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20upgrade=20`pyjwt`=20to?= =?UTF-8?q?=202.6.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ff137 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index 1bc25bd56c..58e346fa88 100644 --- a/requirements.txt +++ b/requirements.txt @@ -20,7 +20,7 @@ packaging~=23.1 portalocker~=2.7.0 prompt_toolkit~=2.0.9 pydid~=0.3.6 -pyjwt~=2.5.0 +pyjwt~=2.6.0 pyld~=2.0.3 pynacl~=1.5.0 python-dateutil~=2.8.1 From 795a21b78d56f7cc6e8c7084278e2f2363166c9a Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Mon, 24 Jul 2023 18:12:38 +0000 Subject: [PATCH 4/9] Add more context to the ACA-Py Revocation handling documentation Signed-off-by: Stephen Curran --- .../CredentialRevocation.md | 108 ++++++++++++++++-- 1 file changed, 101 insertions(+), 7 deletions(-) diff --git a/docs/GettingStartedAriesDev/CredentialRevocation.md b/docs/GettingStartedAriesDev/CredentialRevocation.md index 50501c5801..46f9426fe5 100644 --- a/docs/GettingStartedAriesDev/CredentialRevocation.md +++ b/docs/GettingStartedAriesDev/CredentialRevocation.md @@ -1,8 +1,100 @@ -# Credential Revocation - -These are the ACA-py steps and APIs involved to support credential revocation. - -Run ACA-Py with tails server support enabled. You will need to have the URL of an running instance of https://github.com/bcgov/indy-tails-server. +# Credential Revocation in ACA-Py + +## Overview + +Revocation is perhaps the most difficult aspect of verifiable credentials to +manage. This is true in AnonCreds, particularly in the management of AnonCreds +revocation registries (RevRegs). Through experience in deploying use cases with +ACA-Py we have found that it is very difficult for the controller (the +application code) to manage revocation registries, and as such, we have changed +the implementation in ACA-Py to ensure that it is handling almost all the work +in revoking credentials. The only thing the controller writer has to do is track +the minimum things necessary to the business rules around revocation, such as +whose credentials should be revoked, and how close to real-time should +revocations be published? + +Here is a summary of all of the AnonCreds revocation activities performed +by issuers. After this, we'll provide a (much shorter) list of what an ACA-Py +issuer controller has to do. For those interested, there is a more [complete +overview of AnonCreds revocation], including all of the roles, and some details +of the cryptography behind the approach: + +- Issuers indicate that a credential will support revocation when creating the + credential definition (CredDef). +- Issuers create a Revocation Registry definition object of a given size + (MaxSize -- the number of credentials that can use the RevReg) and publish it + to the ledger (or more precisely, the verifiable data registry). In doing + that, a Tails file is also created and published somewhere on the Internet, + accessible to all Holders. +- Issuers create and publish an initial Revocation Registry Entry that defines + the state of all credentials within the RevReg, either all active or all + revoked. It's a really bad idea to create a RevReg starting with "all + revoked", so don't do that. +- Issuers issue credentials and note the "revocation ID" of each credential. The + "revocation Id" is a compound key consisting of the RevRegId from which the + credential was issued, and the index within that registry of that credential. + An index (from 1 to Max Size of the registry -- or perhaps 0 to Max Size - 1) + can only be associated with one issued credential. +- At some point, a RevReg is all used up (full), and the Issuer must create another + one. Ideally, this does not cause an extra delay in the process of issuing credentials. +- At some point, the Issuer revokes the credential of a holder, using the + revocation Id of the relevant credential. +- At some point, either in conjunction with each revocation, or for a batch of + revocations, the Issuer publishes the RevReg(s) associated with a CredDef to + the ledger. If there are multiple revocations spread across multiple RevRegs, + there may be multiple writes to the ledger. + +[complete overview of AnonCreds revocation]: https://github.com/hyperledger/indy-hipe/blob/main/text/0011-cred-revocation/README.md + +Since managing RevRegs is really hard for an ACA-Py controller, we have tried to +minimize what an ACA-Py Issuer controller has to do, leaving everything else to be +handled by ACA-Py. Of the items in the previous list, here is what an ACA-Py +issuer controller does: + +- Issuers flag that revocation will be used when creating the CredDef and the + desired size of the RevReg. ACA-Py takes case of creating the initial + RevReg(s) without further action by the controller. + - Two RevRegs are initially created, so there is no delay when one fills up, + and another is needed. In ongoing operations, when one RevReg fills up, the + other active RevReg is used, and a new RevReg is created. + - On creation of each RevReg, its corresponding tails file is published by + ACA-Py. +- On Issuance, the controller receives the logical “revocation ID" (combination + of RevRegId+Index) of the issued credential to track. +- On Revocation, the controller passes in the logical “revocation ID" of the + credential to be revoked, including a “notify holder” flag. ACA-Py records the + revocation as pending and, if asked, sends a notification to the holder using + a DIDComm message ([Aries RFC 0183: Revocation Notification]). +- The Issuer requests that the revocations for a CredDefId be published. ACA-Py + figures out what RevRegs contain pending revocation and so need to be + published, and publishes each. + +That is the minimum amount of tracking the controller must do while still being +able to execute the business rules around revoking credentials. + +[Aries RFC 0183: Revocation Notification]: https://github.com/hyperledger/aries-rfcs/blob/main/features/0183-revocation-notification/README.md + +From experience, we’ve added to two extra features to deal with unexpected +conditions: + +- When using an Indy (or similar) ledger, if the local copy of a RevReg gets out + of sync with the ledger copy (perhaps due to a failed ledger write), the + Framework can create an update transaction to “fix” the issue. This is needed + for a revocation state using deltas-type solution (like Indy), but not for a + ledger that publishes revocation states containing the entire state of each + credential. +- From time to time there may be a need to [“rotate” a + RevReg](#revocation-registry-rotation) — to mark existing, active RevRegs as + “decommissioned”, and create new ones in their place. We’ve added an endpoint + (api call) for that. + +## Using ACA-Py Revocation + +The following are the ACA-Py steps and APIs involved in handling credential revocation. + +To try these out, use the ACA-Py Alice/Faber demo with tails server support +enabled. You will need to have the URL of an running instance of +[https://github.com/bcgov/indy-tails-server](https://github.com/bcgov/indy-tails-server). Include the command line parameter `--tails-server-base-url ` @@ -60,7 +152,7 @@ Include the command line parameter `--tails-server-base-url NOTE: This capability is deprecated and will likely be removed entirely in an upcoming release of ACA-Py. + The process for creating revocation registries is completely automated - when you create a Credential Definition with revocation enabled, a revocation registry is automatically created (in fact 2 registries are created), and when a registry fills up, a new one is automatically created. -However the Aca-Py admin api supports endpoints to explicitely create a new revocation registry, if you desire. +However the ACA-Py admin api supports endpoints to explicitly create a new revocation registry, if you desire. There are several endpoints that must be called, and they must be called in this order: From e3f1eeb7f713943835b03b856e753015e63aaa96 Mon Sep 17 00:00:00 2001 From: ff137 Date: Mon, 24 Jul 2023 21:07:37 +0200 Subject: [PATCH 5/9] introduce leeway of 5s for `jwt.decode` This addresses breaking change in `pyjwt` version 2.6 (https://github.com/jpadilla/pyjwt/pull/797), where validation will now raise an `ImmatureSignatureError` if the 'issued at' time is in the future. Integration tests fail with `pyjwt~=2.6`, potentially because of clock synchronization / network latency / time zone differences in `issued_at` time of the jwt, so a leeway of 5 seconds attempts to accommodate ant potential latency / clock sync issue Signed-off-by: ff137 --- aries_cloudagent/multitenant/base.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aries_cloudagent/multitenant/base.py b/aries_cloudagent/multitenant/base.py index 03fbb7a515..d28a3a1cf2 100644 --- a/aries_cloudagent/multitenant/base.py +++ b/aries_cloudagent/multitenant/base.py @@ -321,7 +321,7 @@ async def create_auth_token( def get_wallet_details_from_token(self, token: str) -> Tuple[str, str]: """Get the wallet_id and wallet_key from provided token.""" jwt_secret = self._profile.context.settings.get("multitenant.jwt_secret") - token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"]) + token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=5) wallet_id = token_body.get("wallet_id") wallet_key = token_body.get("wallet_key") return wallet_id, wallet_key @@ -360,7 +360,7 @@ async def get_profile_for_token( jwt_secret = self._profile.context.settings.get("multitenant.jwt_secret") extra_settings = {} - token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"]) + token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=5) wallet_id = token_body.get("wallet_id") wallet_key = token_body.get("wallet_key") From cebcbd655effbeec590ac23d26b5c60622887e7d Mon Sep 17 00:00:00 2001 From: ff137 Date: Mon, 24 Jul 2023 21:47:51 +0200 Subject: [PATCH 6/9] =?UTF-8?q?=E2=AC=86=EF=B8=8F=20upgrade=20`pyjwt`=20to?= =?UTF-8?q?=202.8.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: ff137 --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index e6b1fa705e..88841288ff 100644 --- a/requirements.txt +++ b/requirements.txt @@ -20,7 +20,7 @@ packaging~=23.1 portalocker~=2.7.0 prompt_toolkit~=2.0.9 pydid~=0.3.6 -pyjwt~=2.6.0 +pyjwt~=2.8.0 pyld~=2.0.3 pynacl~=1.5.0 python-dateutil~=2.8.1 From 9f66f0982b4ea2400adc9d571a1f8f834ae618b3 Mon Sep 17 00:00:00 2001 From: ff137 Date: Mon, 24 Jul 2023 21:53:37 +0200 Subject: [PATCH 7/9] =?UTF-8?q?=F0=9F=90=9B=E2=9C=85=20introduce=20leeway?= =?UTF-8?q?=20of=201s=20for=20`jwt.decode`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This addresses breaking change in `pyjwt` version 2.6 (https://github.com/jpadilla/pyjwt/pull/797), where validation will now raise an `ImmatureSignatureError` if the 'issued at' time is in the future, with default 0 leeway. Integration tests fail with `pyjwt~=2.6`, potentially because of clock synchronization / network latency between `issued_at` time at generation and decoding of the jwt; so, a leeway of 1 second accommodates any potential latency / clock sync issue Signed-off-by: ff137 --- aries_cloudagent/multitenant/base.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aries_cloudagent/multitenant/base.py b/aries_cloudagent/multitenant/base.py index d28a3a1cf2..6d07b52867 100644 --- a/aries_cloudagent/multitenant/base.py +++ b/aries_cloudagent/multitenant/base.py @@ -321,7 +321,7 @@ async def create_auth_token( def get_wallet_details_from_token(self, token: str) -> Tuple[str, str]: """Get the wallet_id and wallet_key from provided token.""" jwt_secret = self._profile.context.settings.get("multitenant.jwt_secret") - token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=5) + token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=1) wallet_id = token_body.get("wallet_id") wallet_key = token_body.get("wallet_key") return wallet_id, wallet_key @@ -360,7 +360,7 @@ async def get_profile_for_token( jwt_secret = self._profile.context.settings.get("multitenant.jwt_secret") extra_settings = {} - token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=5) + token_body = jwt.decode(token, jwt_secret, algorithms=["HS256"], leeway=1) wallet_id = token_body.get("wallet_id") wallet_key = token_body.get("wallet_key") From ff8d5db1dc8d9d58f3ab87149ccbf7015928bb2a Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Mon, 24 Jul 2023 20:02:42 +0000 Subject: [PATCH 8/9] 0.9.0 Signed-off-by: Stephen Curran --- CHANGELOG.md | 8 ++++++-- aries_cloudagent/version.py | 2 +- open-api/openapi.json | 2 +- open-api/swagger.json | 2 +- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bf81979654..c0f6910c66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ -# 0.9.0-rc0 +# 0.9.0 -## July 21, 2023 +## July 24, 2023 Release 0.9.0 is an important upgrade that changes (PR [\#2302]) the dependency on the now archived Hyperledger Ursa project to its updated, improved @@ -82,6 +82,9 @@ about changes you might need to make to your deployment. - Fix: Track endorser and author roles in per-tenant settings [\#2331](https://github.com/hyperledger/aries-cloudagent-python/pull/2331) [shaangill025](https://github.com/shaangill025) - Added base wallet provisioning details to Multitenancy.md [\#2328](https://github.com/hyperledger/aries-cloudagent-python/pull/2328) [esune](https://github.com/esune) - Other Fixes, Demo, and Documentation Fixes + - Add more context to the ACA-Py Revocation handling documentation [\#2343](https://github.com/hyperledger/aries-cloudagent-python/pull/2343) [swcurran](https://github.com/swcurran) + - Document the Indy SDK to Askar Migration process [\#2340](https://github.com/hyperledger/aries-cloudagent-python/pull/2340) [swcurran](https://github.com/swcurran) + - Add revocation registry rotate to faber demo [\#2333](https://github.com/hyperledger/aries-cloudagent-python/pull/2333) [usingtechnology](https://github.com/usingtechnology) - chore: add indy deprecation warnings [\#2332](https://github.com/hyperledger/aries-cloudagent-python/pull/2332) [dbluhm](https://github.com/dbluhm) - Fix alice/faber demo execution [\#2305](https://github.com/hyperledger/aries-cloudagent-python/pull/2305) [andrewwhitehead](https://github.com/andrewwhitehead) - Add .indy_client folder to Askar only image. [\#2308](https://github.com/hyperledger/aries-cloudagent-python/pull/2308) [WadeBarnes](https://github.com/WadeBarnes) @@ -109,6 +112,7 @@ about changes you might need to make to your deployment. - Docker images and GHA for publishing images help wanted [\#2076](https://github.com/hyperledger/aries-cloudagent-python/pull/2076) [dbluhm](https://github.com/dbluhm) - ci: test additional versions of python nightly [\#2059](https://github.com/hyperledger/aries-cloudagent-python/pull/2059) [dbluhm](https://github.com/dbluhm) - Release management pull requests + - 0.9.0 [\#2343](https://github.com/hyperledger/aries-cloudagent-python/pull/2343) [swcurran](https://github.com/swcurran) - 0.9.0-rc0 [\#2338](https://github.com/hyperledger/aries-cloudagent-python/pull/2338) [swcurran](https://github.com/swcurran) # 0.8.2 diff --git a/aries_cloudagent/version.py b/aries_cloudagent/version.py index 396b0dcfb4..6f6b1c93b8 100644 --- a/aries_cloudagent/version.py +++ b/aries_cloudagent/version.py @@ -1,4 +1,4 @@ """Library version information.""" -__version__ = "0.9.0-rc0" +__version__ = "0.9.0" RECORD_TYPE_ACAPY_VERSION = "acapy_version" diff --git a/open-api/openapi.json b/open-api/openapi.json index 8d937cb373..9e48752bde 100644 --- a/open-api/openapi.json +++ b/open-api/openapi.json @@ -2,7 +2,7 @@ "openapi" : "3.0.1", "info" : { "title" : "Aries Cloud Agent", - "version" : "v0.9.0-rc0" + "version" : "v0.9.0" }, "servers" : [ { "url" : "/" diff --git a/open-api/swagger.json b/open-api/swagger.json index f28786e033..bbf53925e8 100644 --- a/open-api/swagger.json +++ b/open-api/swagger.json @@ -1,7 +1,7 @@ { "swagger" : "2.0", "info" : { - "version" : "v0.9.0-rc0", + "version" : "v0.9.0", "title" : "Aries Cloud Agent" }, "tags" : [ { From 1251807db954d4798d6bcbcebbd35f3d7a08f89f Mon Sep 17 00:00:00 2001 From: Stephen Curran Date: Mon, 24 Jul 2023 20:57:46 +0000 Subject: [PATCH 9/9] Fix PR number for this PR, add in last change Signed-off-by: Stephen Curran --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c0f6910c66..cca31fd2eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -95,6 +95,7 @@ about changes you might need to make to your deployment. - Plugin Handling Updates - Feature: Add the ability to deny specific plugins from loading 0.7.4 [\#1737](https://github.com/hyperledger/aries-cloudagent-python/pull/1737) [frostyfrog](https://github.com/frostyfrog) - Dependencies and Internal Updates + - upgrade pyjwt to latest; introduce leeway to jwt.decodet [\#2335](https://github.com/hyperledger/aries-cloudagent-python/pull/2335) [ff137](https://github.com/ff137) - upgrade requests to latest [\#2336](https://github.com/hyperledger/aries-cloudagent-python/pull/2336) [ff137](https://github.com/ff137) - upgrade packaging to latest [\#2334](https://github.com/hyperledger/aries-cloudagent-python/pull/2334) [ff137](https://github.com/ff137) - chore: update PyYAML [\#2329](https://github.com/hyperledger/aries-cloudagent-python/pull/2329) [dbluhm](https://github.com/dbluhm) @@ -112,7 +113,7 @@ about changes you might need to make to your deployment. - Docker images and GHA for publishing images help wanted [\#2076](https://github.com/hyperledger/aries-cloudagent-python/pull/2076) [dbluhm](https://github.com/dbluhm) - ci: test additional versions of python nightly [\#2059](https://github.com/hyperledger/aries-cloudagent-python/pull/2059) [dbluhm](https://github.com/dbluhm) - Release management pull requests - - 0.9.0 [\#2343](https://github.com/hyperledger/aries-cloudagent-python/pull/2343) [swcurran](https://github.com/swcurran) + - 0.9.0 [\#2344](https://github.com/hyperledger/aries-cloudagent-python/pull/2344) [swcurran](https://github.com/swcurran) - 0.9.0-rc0 [\#2338](https://github.com/hyperledger/aries-cloudagent-python/pull/2338) [swcurran](https://github.com/swcurran) # 0.8.2