To create a Podman image featuring the DID toolbox, if not created already, please run:
# Optionally, use --build-arg VERSION=<ANY_VALID_VERSION> option to install any other particular version
$ podman build -t didtoolbox:latest .So, running the podman image ls command right after should result in at least two entries:
REPOSITORY TAG IMAGE ID CREATED SIZE
localhost/didtoolbox latest cca764c73f4a About a minute ago 237 MB
gcr.io/distroless/java21-debian12 latest 3c56da19216a About an hour ago 204 MB
Finally, once you manage to build a Podman image in your local repo, to run the DID toolbox (as Podman image),
please use an appropriate podman run ... command, e.g.:
# On Linux/macOS, using an alias (for the podman run command) always comes in handy
$ alias didtoolbox='podman run -v $(pwd):$(pwd):z,exec -w $(pwd) didtoolbox'
$ didtoolbox -h
[the entire help page should be displayed here]
$ didtoolbox -V
[the actual version should be displayed here]Probably the simplest way to use the generator would be to let it generate as much on its own as possible:
didtoolbox create -u https://domain.com/path1/path2/did.jsonl -fThe command would create a valid DID log entry also featuring some assertion/verification keys in various format such as JWKS and PEM.
Beyond that, and since no verification material is supplied explicitly,
the generator will take care of that, too. Hence, all required key pairs will also be generated and stored in .didtoolbox directory, for later use:
# ll .didtoolbox
total 48
-rw------- 1 vladica.stojic staff 227B Feb 11 13:53 assert-key-01
-rw-r--r-- 1 vladica.stojic staff 178B Feb 11 13:53 assert-key-01.pub
-rw------- 1 vladica.stojic staff 227B Feb 11 13:53 auth-key-01
-rw-r--r-- 1 vladica.stojic staff 178B Feb 11 13:53 auth-key-01.pub
-rw------- 1 vladica.stojic staff 168B Feb 11 13:53 id_ed25519
-rw-r--r-- 1 vladica.stojic staff 113B Feb 11 13:53 id_ed25519.pubThis implies that you may now also try running the command in a usual/recommended way:
didtoolbox create \
-a my-assert-key-01,.didtoolbox/assert-key-01.pub \
-t my-auth-key-01,.didtoolbox/auth-key-01.pub \
-u https://domain.com/path1/path2/did.jsonl \
-s .didtoolbox/id_ed25519 \
-v .didtoolbox/id_ed25519.pub As this repo already contains some keys intended for testing purposes, feel free to also try out the following example:
didtoolbox create \
-a my-assert-key-01,src/test/data/assert-key-01.pub \
-t my-auth-key-01,src/test/data/auth-key-01.pub \
-u https://domain.com/path1/path2/did.jsonl \
-j src/test/data/mykeystore.jks \
--jks-password changeit \
--jks-alias myalias Alternatively, besides Java KeyStore (PKCS12) also PEM format of signing/verifying key is supported:
didtoolbox create \
-a my-assert-key-01,src/test/data/assert-key-01.pub \
-t my-auth-key-01,src/test/data/auth-key-01.pub \
-u https://domain.com/path1/path2/did.jsonl \
-s src/test/data/private.pem \
-v src/test/data/public.pemSo, regardless of whether verification material is generated
or supplied manually via -a/-t CLI options, a generated DID log entry will always feature some e.g. the command above
should produce a following output (prettified/pretty-printed version):
{
"versionId": "1-QmVNnbsLiQ9FR3xLDeDTucTwg9ZwXrF6jvE2jHFA88x1jY",
"versionTime": "2026-02-11T13:02:04Z",
"parameters": {
"method": "did:webvh:1.0",
"scid": "QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD",
"updateKeys": [
"z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP"
],
"portable": false
},
"state": {
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/jwk/v1"
],
"id": "did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2",
"authentication": [
"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01"
],
"assertionMethod": [
"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01"
],
"verificationMethod": [
{
"id": "did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01",
"type": "JsonWebKey2020",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-256",
"kid": "my-auth-key-01",
"x": "-MUDoZjNImUbo0vNmdAqhAOPdJoptUC0tlK9xvLrqDg",
"y": "Djlu_TF69xQF5_L3px2FmCDQksM_fIp6kKbHRQLVIb0"
}
},
{
"id": "did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01",
"type": "JsonWebKey2020",
"publicKeyJwk": {
"kty": "EC",
"crv": "P-256",
"kid": "my-assert-key-01",
"x": "wdET0dp6vq59s1yyVh_XXyIPPU9Co7PlcTPMRRXx85Y",
"y": "eThC9-NetN-oXA5WU0Dn0eed7fgHtsXs2E3mU82pA9k"
}
}
]
},
"proof": [
{
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-jcs-2022",
"created": "2026-02-11T13:02:04Z",
"verificationMethod": "did:key:z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP#z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP",
"proofPurpose": "assertionMethod",
"proofValue": "z4z8eeSqiGp9MG2MWwwFqNs3GN5m2XbMPxedYWd3s9yXopnM6oAgAVPS8dMyijDnaMik1Ym7gnD2CWd2mTx685dEV"
}
]
}The same content un-prettified, as it should be found in the did.jsonl file:
{"versionId":"1-QmVNnbsLiQ9FR3xLDeDTucTwg9ZwXrF6jvE2jHFA88x1jY","versionTime":"2026-02-11T13:02:04Z","parameters":{"method":"did:webvh:1.0","scid":"QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD","updateKeys":["z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP"],"portable":false},"state":{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/jwk/v1"],"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2","authentication":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01"],"assertionMethod":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01"],"verificationMethod":[{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-auth-key-01","x":"-MUDoZjNImUbo0vNmdAqhAOPdJoptUC0tlK9xvLrqDg","y":"Djlu_TF69xQF5_L3px2FmCDQksM_fIp6kKbHRQLVIb0"}},{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-assert-key-01","x":"wdET0dp6vq59s1yyVh_XXyIPPU9Co7PlcTPMRRXx85Y","y":"eThC9-NetN-oXA5WU0Dn0eed7fgHtsXs2E3mU82pA9k"}}]},"proof":[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","created":"2026-02-11T13:02:04Z","verificationMethod":"did:key:z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP#z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP","proofPurpose":"assertionMethod","proofValue":"z4z8eeSqiGp9MG2MWwwFqNs3GN5m2XbMPxedYWd3s9yXopnM6oAgAVPS8dMyijDnaMik1Ym7gnD2CWd2mTx685dEV"}]}Once a newly created did.jsonl file is available, you may use the update subcommand at any point to completely
replace the existing verification material in DID document:
didtoolbox update \
-d did.jsonl \
-a my-assert-key-01,src/test/data/assert-key-01.pub \
-t my-auth-key-01,src/test/data/auth-key-01.pub \
-s src/test/data/private.pem \
-v src/test/data/public.pemThe command above should produce the following DID log featuring a whole new DID log entry:
{"versionId":"1-QmVNnbsLiQ9FR3xLDeDTucTwg9ZwXrF6jvE2jHFA88x1jY","versionTime":"2026-02-11T13:02:04Z","parameters":{"method":"did:webvh:1.0","scid":"QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD","updateKeys":["z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP"],"portable":false},"state":{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/jwk/v1"],"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2","authentication":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01"],"assertionMethod":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01"],"verificationMethod":[{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-auth-key-01","x":"-MUDoZjNImUbo0vNmdAqhAOPdJoptUC0tlK9xvLrqDg","y":"Djlu_TF69xQF5_L3px2FmCDQksM_fIp6kKbHRQLVIb0"}},{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-assert-key-01","x":"wdET0dp6vq59s1yyVh_XXyIPPU9Co7PlcTPMRRXx85Y","y":"eThC9-NetN-oXA5WU0Dn0eed7fgHtsXs2E3mU82pA9k"}}]},"proof":[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","created":"2026-02-11T13:02:04Z","verificationMethod":"did:key:z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP#z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP","proofPurpose":"assertionMethod","proofValue":"z4z8eeSqiGp9MG2MWwwFqNs3GN5m2XbMPxedYWd3s9yXopnM6oAgAVPS8dMyijDnaMik1Ym7gnD2CWd2mTx685dEV"}]}
{"versionId":"2-QmUznSmYWCL1qE1c6tvkkQUsoV6drWcYC9yLc2V3fAGLiZ","versionTime":"2026-02-11T13:02:49Z","parameters":{},"state":{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/jwk/v1"],"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2","authentication":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01"],"assertionMethod":["did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01"],"verificationMethod":[{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-auth-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-auth-key-01","x":"-MUDoZjNImUbo0vNmdAqhAOPdJoptUC0tlK9xvLrqDg","y":"Djlu_TF69xQF5_L3px2FmCDQksM_fIp6kKbHRQLVIb0"}},{"id":"did:webvh:QmXKFnvqd29GfKgvoGDP7RRyLhiQVWJagFDu6qYghqWBdD:domain.com:path1:path2#my-assert-key-01","type":"JsonWebKey2020","publicKeyJwk":{"kty":"EC","crv":"P-256","kid":"my-assert-key-01","x":"wdET0dp6vq59s1yyVh_XXyIPPU9Co7PlcTPMRRXx85Y","y":"eThC9-NetN-oXA5WU0Dn0eed7fgHtsXs2E3mU82pA9k"}}]},"proof":[{"type":"DataIntegrityProof","cryptosuite":"eddsa-jcs-2022","created":"2026-02-11T13:02:49Z","verificationMethod":"did:key:z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP#z6MkvdAjfVZ2CWa38V2VgZvZVjSkENZpiuiV5gyRKsXDA8UP","proofPurpose":"assertionMethod","proofValue":"z3hoSFSc3PmtApvFti3GaJ3Yg8f5rxHHtdEyEtqCd3CEL87mBtioo2a94NzQXwtXbrMf2wyRHMfTesugJ41txzKpg"}]}