Package: sd-jwt
SD-JWT Reference ImplementationThis is the reference implementation of theIETF SD-JWT specificationwritten in Python.This implementation is used to generate the examples in the IETF SD-JWT specification and it can also be used in other projects for implementing SD-JWT.SetupTo install this implementation, make sure thatpython3andpip(orpip3) are available on your system and run the following command:# create a virtual environment to install the dependenciespython3-mvenvvenvsourcevenv/bin/activate# install the latest version from gitpipinstallgit+https://github.com/openwallet-foundation-labs/sd-jwt-python.gitThis will install thesdjwtpython package and thesd-jwt-generatescript.If you want to access the scripts in a new shell, it is required to activate the virtual environment:sourcevenv/bin/activatesd-jwt-generateThe scriptsd-jwt-generateis useful for generating test cases, as they might be used for doing interoperability tests with other SD-JWT implementations, and for generating examples in the SD-JWT specification and other documents.For both use cases, the script expects a JSON file with settings (settings.yml). Examples for these files can be found in thetests/testcasesandexamplesdirectories.Furthermore, the script expects, in its working directory, one subdirectory for each test case or example. In each such directory, there must be a filespecification.ymlwith the test case or example specifications. Examples for these files can be found in the subdirectories of thetests/testcasesandexamplesdirectories, respectively.The script outputs the following files in each test case or example directory:sd_jwt_issuance.txt: The issued SD-JWT. (*)sd_jwt_presentation.txt: The presented SD-JWT. (*)disclosures.md: The disclosures, formatted as markdown (only in 'example' mode).user_claims.json: The user claims.sd_jwt_payload.json: The payload of the SD-JWT.sd_jwt_jws_part.txt: The serialized JWS component of the SD-JWT. (*)kb_jwt_payload.json: The payload of the key binding JWT.kb_jwt_serialized.txt: The serialized key binding JWT.verified_contents.json: The verified contents of the SD-JWT.(*) Note: When JWS JSON Serialization is used, the file extensions of these files are.jsoninstead of.txt.To run the script, enter the respective directory and executesd-jwt-generate:cdtests/testcases
sd-jwt-generateexamplespecification.yml for Test Cases and ExamplesThespecification.ymlfile contains the test case or example specifications.
For examples, the file contains the 'input user data' (i.e., the payload that is
turned into an SD-JWT) and the holder disclosed claims (i.e., a description of
what data the holder wants to release). For test cases, an additional third
property is contained, which is the expected output of the verifier.Implementers of SD-JWT libraries are advised to run at least the following tests:End-to-end: The issuer creates an SD-JWT according to the input data, the
holder discloses the claims according to the holder disclosed claims, and
the verifier verifies the SD-JWT and outputs the expected verified contents.
The test passes if the output of the verifier matches the expected verified
contents.Issuer-direct-to-holder: The issuer creates an SD-JWT according to the input
data and the whole SD-JWT is put directly into the Verifier for consumption.
(Note that this is possible because an SD-JWT presentation differs only by
one '~' character from the SD-JWT issued by the issuer if key binding is
not enforced. This character can easily be added in the test execution.)
This test simulates that a holder releases all data contained in the SD-JWT
and is useful to verify that the Issuer put all data into the SD-JWT in a
correct way. The test passes if the output of the verifier matches the input
user claims (including all claims marked for selective disclosure).In this library, the two tests are implemented intests/test_e2e_testcases.pyandtests/test_disclose_all_shortcut.py,
respectively.Thespecification.ymlfile has the following format for test cases (find more examples intests/testcases):Input data:user_claimsuser_claimsis a YAML dictionary with the user claims, i.e., the payload that
is to be turned into an SD-JWT.Object keysandarray elements(and only
those!) can be marked for selective disclosure at any level in the data by
applying the YAML tag "!sd" to them.This is an example of an object where two out of three keys are marked for selective disclosure:user_claims:is_over:"13":True# not selectively disclosable - always visible to the verifier!sd"18":False# selectively disclosable!sd"21":False# selectively disclosableThe following shows an array with two elements, where both are marked for selective disclosure:user_claims:nationalities:-!sd"DE"-!sd"US"The following shows an array with two elements that are both objects, one of which is marked for selective disclosure:user_claims:addresses:-street:"123MainSt"city:"Anytown"state:"NY"zip:"12345"type:"main_address"-!sdstreet:"456MainSt"city:"Anytown"state:"NY"zip:"12345"type:"secondary_address"The following shows an object that has only one claim (sd_array) which is marked for selective disclosure. Note that within the array, there is no selective disclosure.user_claims:!sd sd_array:-32-23Holder Behavior:holder_disclosed_claimsholder_disclosed_claimsis a YAML dictionary with the claims that the holder
discloses to the verifier. The structure must follow the structure ofuser_claims, but elements can be omitted. The following rules apply:For scalar values (strings, numbers, booleans, null), the value must beTrueoryesif the claim is disclosed andFalseornoif the claim
should not be disclosed.Arrays mirror the elements of the same array inuser_claims. For each
value, if it is notFalseorno, the value is disclosed. If an array
element inuser_claimsis an object or array, an object or array can be
provided here as well to describe which elements of that object/array should
be disclosed or not, if applicable.For objects, list all keys that are to be disclosed, using a value that is
notFalseorno. As above, if the value is an object or array, it is used
to describe which elements of that object/array should be disclosed or not,
if applicable.Verifier Output:expect_verified_user_claimsFinally,expect_verified_user_claimsdescribes what the verifier is expected
to output after successfully consuming the presentation from the holder. In
other words, after applyingholder_disclosed_claimstouser_claims, the
result isexpect_verified_user_claims.Other PropertiesWhenkey_bindingis set totrue, a Key Binding JWT will be generated.Usingserialization_format, the serialization format of the SD-JWT can be
specified. The default iscompact, butjsonis also supported.