This
section
specifies
the
data
model
that
is
used
for
expressing
data
integrity
proofs
,
controller
documents
,
and
verification
methods
.
A
data
integrity
proof
provides
information
about
the
proof
mechanism,
parameters
required
to
verify
that
proof,
and
the
proof
value
itself.
All
of
this
information
is
provided
using
Linked
Data
vocabularies
such
as
the
[
SECURITY-VOCABULARY
].
The
following
attributes
are
defined
for
use
in
a
data
integrity
proof
:
-
id
-
An
optional
identifier
for
the
proof,
which
MUST
be
a
URL
[
URL
],
such
as
a
UUID
as
a
URN
(
urn:uuid:6a1676b8-b51f-11ed-937b-d76685a20ff5
).
The
usage
of
this
property
is
further
explained
in
Section
2.1.2
Proof
Chains
.
-
type
-
The
specific
proof
type
used
for
the
cryptographic
proof
MUST
be
specified
as
a
string
that
maps
to
a
URL
[
URL
].
Examples
of
proof
types
include
DataIntegrityProof
and
Ed25519Signature2020
.
Proof
types
determine
what
other
fields
are
required
to
secure
and
verify
the
proof.
-
proofPurpose
-
The
reason
the
proof
was
created
MUST
be
specified
as
a
string
that
maps
to
a
URL
[
URL
].
The
proof
purpose
acts
as
a
safeguard
to
prevent
the
proof
from
being
misused
by
being
applied
to
a
purpose
other
than
the
one
that
was
intended.
For
example,
without
this
value
the
creator
of
a
proof
could
be
tricked
into
using
cryptographic
material
typically
used
to
create
a
Verifiable
Credential
(
assertionMethod
)
during
a
login
process
(
authentication
)
which
would
then
result
in
the
creation
of
a
Verifiable
Credential
they
never
meant
to
create
instead
of
the
intended
action,
which
was
to
merely
logging
into
a
website.
-
verificationMethod
-
The
means
and
information
needed
to
verify
the
proof
MUST
be
specified
as
a
string
that
maps
to
a
[
URL
].
An
example
of
a
verification
method
is
a
link
to
a
public
key
which
includes
cryptographic
material
that
is
used
by
a
verifier
during
the
verification
process.
-
created
-
The
date
and
time
the
proof
was
created
is
OPTIONAL
and,
if
included,
MUST
be
specified
as
an
[
XMLSCHEMA11-2
]
combined
date
and
time
string.
-
expires
-
An
OPTIONAL
property
that
conveys
the
date
and
time
that
a
proof
expires
and
that,
if
present,
MUST
be
specified
as
an
[
XMLSCHEMA11-2
]
combined
date
and
time
string.
-
domain
-
The
creator
of
a
proof
SHOULD
include
a
string
value
that
indicates
its
intended
usage,
which
a
verifier
SHOULD
use
to
ensure
the
proof
was
intended
to
be
used
by
them.
The
specification
of
the
domain
parameter
is
useful
in
challenge-response
protocols
where
the
verifier
is
operating
from
within
a
security
domain
known
to
the
creator
of
the
proof.
Examples
of
a
domain
parameter
include:
domain.example
(DNS
domain),
https://domain.example:8443
(full
Web
origin),
mycorp-intranet
(well-known
text
string),
and
b31d37d4-dd59-47d3-9dd8-c973da43b63a
(UUID).
-
challenge
-
A
string
value
that
SHOULD
be
included
in
a
proof
if
a
domain
is
specified.
The
value
is
used
once
for
a
particular
domain
and
window
of
time.
This
value
is
used
to
mitigate
replay
attacks.
Examples
of
a
challenge
value
include:
1235abcd6789
,
79d34551-ae81-44ae-823b-6dadbab9ebd4
,
and
ruby
.
-
proofValue
-
A
string
value
that
contains
the
data
necessary
to
verify
the
digital
proof
using
the
verificationMethod
specified.
The
contents
of
the
value
MUST
be
a
[
MULTIBASE
]-encoded
binary
value.
Alternative
fields
with
different
encodings
MAY
be
used
to
encode
the
data
necessary
to
verify
the
digital
proof
instead
of
this
value.
The
contents
of
this
value
are
determined
by
a
cryptosuite
and
set
to
the
proof
value
generated
by
the
Add
Proof
Algorithm
.
-
previousProof
-
An
optional
string
value
that
identifies
another
data
integrity
proof
that
MUST
verify
before
the
current
proof
is
processed.
This
property
is
used
in
Section
2.1.2
Proof
Chains
.
-
nonce
-
An
OPTIONAL
string
value
supplied
by
the
proof
creator.
One
use
of
this
field
is
to
increase
privacy
by
decreasing
linkability
that
is
the
result
of
deterministically
generated
signatures.
Note
All
of
the
terms
above
map
to
URLs.
The
vocabulary
where
these
terms
are
defined
is
the
[
SECURITY-VOCABULARY
].
A
proof
can
be
added
to
a
JSON
document
like
the
following:
{
"title": "Hello world!"
};
The
following
proof
secures
the
document
above
using
the
jcs-eddsa-2022
cryptography
suite
[
DI-EDDSA
],
which
produces
a
verifiable
digital
proof
by
transforming
the
input
data
using
the
JSON
Canonicalization
Scheme
(JCS)
[
RFC8785
]
and
then
digitally
signing
it
using
an
Edwards
Digital
Signature
Algorithm
(EdDSA).
Example
2
:
A
simple
signed
JSON
data
document
{
"title": "Hello world!",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "jcs-eddsa-2022",
"created": "2023-03-05T19:23:24Z",
"verificationMethod": "https://di.example/issuer#z6MkjLrk3gKS2nnkeWcmcxiZPGskmesDpuwRBorgHxUXfxnG",
"proofPurpose": "assertionMethod",
"proofValue": "zQeVbY4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYV8nQApmEcqaqA3Q1gVHMrXFkXJeV6doDwLWx"
}
}
Similarly,
a
proof
can
be
added
to
a
JSON-LD
data
document
like
the
following:
{
"@context": {"title": "https://schema.org/title"},
"title": "Hello world!"
};
The
following
proof
secures
the
document
above
by
using
the
ecdsa-2019
cryptography
suite
[
DI-ECDSA
],
which
produces
a
verifiable
digital
proof
by
transforming
the
input
data
using
the
RDF
Dataset
Canonicalization
Scheme
[
RDF-CANON
]
and
then
digitally
signing
it
using
the
Elliptic
Curve
Digital
Signature
Algorithm
(ECDSA).
Example
4
:
A
simple
signed
JSON-LD
data
document
{
"@context": [
{"title": "https://schema.org/title"},
"https://w3id.org/security/data-integrity/v1"
],
"title": "Hello world!",
"proof": {
"type": "DataIntegrityProof",
"cryptosuite": "ecdsa-2019",
"created": "2020-06-11T19:14:04Z",
"verificationMethod": "https://ldi.example/issuer#zDnaepBuvsQ8cpsWrVKw8fbpGpvPeNSjVPTWoq6cRqaYzBKVP",
"proofPurpose": "assertionMethod",
"proofValue": "zXb23ZkdakfJNUhiTEdwyE598X7RLrkjnXEADLQZ7vZyUGXX8cyJZRBkNw813SGsJHWrcpo4Y8hRJ7adYn35Eetq"
}
}
Note
:
Representing
time
values
to
individuals
This
specification
enables
the
expression
of
dates
and
times,
such
as
through
the
created
and
expires
properties.
This
information
might
be
indirectly
exposed
to
an
individual
if
a
proof
is
processed
and
is
detected
to
be
outside
an
allowable
time
range.
When
displaying
date
and
time
values
related
to
the
validity
of
cryptographic
proofs,
implementers
are
advised
to
respect
the
locale
and
local
calendar
preferences
of
the
individual
[
LTLI
].
Conversion
of
timestamps
to
local
time
values
are
expected
to
consider
the
time
zone
expectations
of
the
individual.
See
Verifiable
Credentials
Data
Model
v2.0
for
more
details
about
representing
time
values
to
individuals.
Issue
Add
a
note
indicating
that
selective
disclosure
proof
mechanisms
can
be
compatible
with
Data
Integrity;
for
example,
an
algorithm
could
produce
a
merkle
tree
from
a
canonicalized
set
of
N-Quads
and
then
sign
the
root
hash.
Disclosure
would
involve
including
the
merkle
paths
for
each
N-Quad
that
is
to
be
revealed.
This
mechanism
would
merely
consume
the
normalized
output
differently
(this,
and
the
proof
mechanism
would
be
modifications
to
this
core
spec).
It
might
also
be
necessary
to
generate
proof
parameters
such
as
a
private
key/seed
that
can
be
used
along
with
an
algorithm
to
deterministically
generate
nonces
that
are
concatenated
with
each
N-Quad
to
prevent
rainbow
table
or
similar
attacks.
Issue
Add
a
note
indicating
that
this
specification
should
not
be
construed
to
indicate
that
public
key
controllers
should
be
restricted
to
a
single
public
key
or
that
systems
that
use
this
spec
and
involve
real
people
should
identify
each
person
as
only
ever
being
a
single
entity
rather
than
perhaps
N
entities
with
M
keys.
There
are
no
such
restrictions
and
in
many
cases
those
kinds
of
restrictions
are
ill-advised
due
to
privacy
considerations.
The
Data
Integrity
specification
supports
the
concept
of
multiple
proofs
in
a
single
document.
There
are
two
types
of
multi-proof
approaches
that
are
identified:
Proof
Sets
(un-ordered)
and
Proof
Chains
(ordered).
A
proof
set
is
useful
when
the
same
data
needs
to
be
secured
by
multiple
entities,
but
where
the
order
of
proofs
does
not
matter,
such
as
in
the
case
of
a
set
of
signatures
on
a
contract.
A
proof
set,
which
has
no
order,
is
represented
by
associating
a
set
of
proofs
with
the
proof
key
in
a
document.
{
"@context": [
{"title": "https://schema.org/title"},
"https://w3id.org/security/data-integrity/v1"
],
"title": "Hello world!",
"proof": [{
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-2022",
"created": "2020-11-05T19:23:24Z",
"verificationMethod": "https://ldi.example/issuer/1#z6MkjLrk3gKS2nnkeWcmcxiZPGskmesDpuwRBorgHxUXfxnG",
"proofPurpose": "assertionMethod",
"proofValue": "z4oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQeVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV6"
}, {
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-2022",
"created": "2020-11-05T13:08:49Z",
"verificationMethod": "https://pfps.example/issuer/2#z6MkGskxnGjLrk3gKS2mesDpuwRBokeWcmrgHxUXfnncxiZP",
"proofPurpose": "assertionMethod",
"proofValue": "z5QLBrp19KiWXerb8ByPnAZ9wujVFN8PDsxxXeMoyvDqhZ6Qnzr5CG9876zNht8BpStWi8H2Mi7XCY3inbLrZrm95"
}]
}
A
proof
chain
is
useful
when
the
same
data
needs
to
be
signed
by
multiple
entities
and
the
order
of
when
the
proofs
occurred
matters,
such
as
in
the
case
of
a
notary
counter-signing
a
proof
that
had
been
created
on
a
document.
A
proof
chain,
where
proof
order
needs
to
be
preserved,
is
expressed
by
providing
at
least
one
proof
with
an
id
,
such
as
a
UUID
as
a
URN,
and
another
proof
with
a
previousProof
value
that
identifies
the
previous
proof.
{
"@context": [
{"title": "https://schema.org/title"},
"https://w3id.org/security/data-integrity/v1"
],
"title": "Hello world!",
"proof": [{
"id": "urn:uuid:60102d04-b51e-11ed-acfe-2fcd717666a7",
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-2022",
"created": "2020-11-05T19:23:42Z",
"verificationMethod": "https://ldi.example/issuer/1#z6MkjLrk3gKS2nnkeWcmcxiZPGskmesDpuwRBorgHxUXfxnG",
"proofPurpose": "assertionMethod",
"proofValue": "zVbY8nQAVHMrXFkXJpmEcqdoDwLWxaqA3Q1geV64oey5q2M3XKaxup3tmzN4DRFTLVqpLMweBrSxMY2xHX5XTYVQe"
}, {
"type": "DataIntegrityProof",
"cryptosuite": "eddsa-2022",
"created": "2020-11-05T21:28:14Z",
"verificationMethod": "https://pfps.example/issuer/2#z6MkGskxnGjLrk3gKS2mesDpuwRBokeWcmrgHxUXfnncxiZP",
"proofPurpose": "assertionMethod",
"proofValue": "z6Qnzr5CG9876zNht8BpStWi8H2Mi7XCY3inbLrZrm955QLBrp19KiWXerb8ByPnAZ9wujVFN8PDsxxXeMoyvDqhZ",
"previousProof": "urn:uuid:60102d04-b51e-11ed-acfe-2fcd717666a7"
}]
}
A
proof
that
describes
its
purpose
helps
prevent
it
from
being
misused
for
some
other
purpose.
Issue
Add
a
mention
of
JWK's
key_ops
parameter
and
WebCrypto's
KeyUsage
restrictions;
explain
that
Proof
Purpose
serves
a
different
goal
and
allows
for
finer-grained
restrictions.
Dave
Longley
suggested
that
proof
purposes
enable
verifiers
to
know
what
the
proof
creator's
intent
was
so
the
message
can't
be
accidentally
abused
for
another
purpose,
e.g.,
a
message
signed
for
the
purpose
of
merely
making
an
assertion
(and
thus
perhaps
intended
to
be
widely
shared)
being
abused
as
a
message
to
authenticate
to
a
service
or
take
some
action
(invoke
a
capability).
It's
a
goal
to
keep
the
number
of
them
limited
to
as
few
categories
as
are
really
needed
to
accomplish
this
goal.
The
following
is
a
list
of
commonly
used
proof
purpose
values.
-
authentication
-
Indicates
that
a
given
proof
is
only
to
be
used
for
the
purposes
of
an
authentication
protocol.
-
assertionMethod
-
Indicates
that
a
proof
can
only
be
used
for
making
assertions,
for
example
signing
a
Verifiable
Credential.
-
keyAgreement
-
Indicates
that
a
proof
is
used
for
for
key
agreement
protocols,
such
as
Elliptic
Curve
Diffie
Hellman
key
agreement
used
by
popular
encryption
libraries.
-
capabilityDelegation
-
Indicates
that
the
proof
can
only
be
used
for
delegating
capabilities.
See
the
Authorization
Capabilities
[
ZCAP
]
specification
for
more
detail.
-
capabilityInvocation
-
Indicates
that
the
proof
can
only
be
used
for
invoking
capabilities.
See
the
Authorization
Capabilities
[
ZCAP
]
specification
for
more
detail.
Note:
The
Authorization
Capabilities
[
ZCAP
]
specification
defines
additional
proof
purposes
for
that
use
case,
such
as
capabilityInvocation
and
capabilityDelegation
.
A
controller
document
is
a
set
of
data
that
specifies
one
or
more
relationships
between
a
controller
and
a
set
of
data,
such
as
a
set
of
public
cryptographic
keys.
The
controller
document
SHOULD
contain
verification
relationships
that
explicitly
permit
the
use
of
certain
verification
methods
for
specific
purposes.
Issue
Add
examples
of
common
Controller
documents,
such
as
controller
documents
published
on
a
ledger-based
registry,
or
on
a
mutable
medium
in
combination
with
an
integrity
protection
mechanism
such
as
Hashlinks.
A
controller
document
can
express
verification
methods
,
such
as
cryptographic
public
keys
,
which
can
be
used
to
authenticate
or
authorize
interactions
with
the
controller
or
associated
parties.
For
example,
a
cryptographic
public
key
can
be
used
as
a
verification
method
with
respect
to
a
digital
signature;
in
such
usage,
it
verifies
that
the
signer
could
use
the
associated
cryptographic
private
key.
Verification
methods
might
take
many
parameters.
An
example
of
this
is
a
set
of
five
cryptographic
keys
from
which
any
three
are
required
to
contribute
to
a
cryptographic
threshold
signature.
-
verificationMethod
-
The
verificationMethod
property
is
OPTIONAL
.
If
present,
the
value
MUST
be
a
set
of
verification
methods
,
where
each
verification
method
is
expressed
using
a
map
.
The
verification
method
map
MUST
include
the
id
,
type
,
controller
,
and
specific
verification
material
properties
that
are
determined
by
the
value
of
type
and
are
defined
in
2.3.1.1
Verification
Material
.
A
verification
method
MAY
include
additional
properties.
Verification
methods
SHOULD
be
registered
in
the
Data
Integrity
Specification
Registries
[TBD
-
DIS-REGISTRIES].
Note
The
verificationMethod
property
is
REQUIRED
for
proofs,
unlike
controller
documents,
for
which
it
is
optional.
See
section
2.1
Proofs
.
-
id
-
The
value
of
the
id
property
for
a
verification
method
MUST
be
a
string
that
conforms
to
the
conforms
to
the
[
URL
]
syntax.
-
type
-
The
value
of
the
type
property
MUST
be
a
string
that
references
exactly
one
verification
method
type.
In
order
to
maximize
global
interoperability,
the
verification
method
type
SHOULD
be
registered
in
the
Data
Integrity
Specification
Registries
[TBD
--
DIS-REGISTRIES].
-
controller
-
The
value
of
the
controller
property
MUST
be
a
string
that
conforms
to
the
[
URL
]
syntax.
-
revoked
-
The
revoked
property
is
OPTIONAL
.
If
provided,
it
MUST
be
an
[
XMLSCHEMA11-2
]
combined
date
and
time
string
specifying
when
the
verification
method
ceased
to
be
used.
Once
the
value
is
set,
it
is
not
expected
to
be
updated,
and
systems
depending
on
the
value
are
expected
to
not
verify
any
proofs
associated
with
the
verification
method
at
or
after
the
time
of
revocation.
Example
7
:
Example
verification
method
structure
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/data-integrity/v1"
]
"id": "did:example:123456789abcdefghi",
"verificationMethod": [{
"id": ,
"type": ,
"controller": ,
"publicKeyJwk":
}, {
"id": ,
"type": ,
"controller": ,
"publicKeyMultibase":
}]
}
Note
:
Verification
method
controller(s)
and
controller(s)
The
semantics
of
the
controller
property
are
the
same
when
the
subject
of
the
relationship
is
the
controller
document
as
when
the
subject
of
the
relationship
is
a
verification
method
,
such
as
a
cryptographic
public
key.
Since
a
key
can't
control
itself,
and
the
key
controller
cannot
be
inferred
from
the
controller
document
,
it
is
necessary
to
explicitly
express
the
identity
of
the
controller
of
the
key.
The
difference
is
that
the
value
of
controller
for
a
verification
method
is
not
necessarily
a
controller
.
controllers
are
expressed
using
the
`
controller
`
property
at
the
highest
level
of
the
controller
document
.
Verification
material
is
any
information
that
is
used
by
a
process
that
applies
a
verification
method
.
The
type
of
a
verification
method
is
expected
to
be
used
to
determine
its
compatibility
with
such
processes.
Examples
of
verification
material
include
JsonWebKey
and
Multikey
.
A
cryptographic
suite
specification
is
responsible
for
specifying
the
verification
method
type
and
its
associated
verification
material
format.
For
examples,
see
the
Data
Integrity
ECDSA
Cryptosuites
and
the
Data
Integrity
EdDSA
Cryptosuites
.
For
a
list
of
verification
method
types
please
see
the
[
SECURITY-VOCABULARY
].
To
increase
the
likelihood
of
interoperable
implementations,
this
specification
limits
the
number
of
formats
for
expressing
verification
material
in
a
controller
document
.
The
fewer
formats
that
implementers
have
to
implement,
the
more
likely
it
will
be
that
they
will
support
all
of
them.
This
approach
attempts
to
strike
a
delicate
balance
between
ease
of
implementation
and
supporting
formats
that
have
historically
had
broad
deployment.
A
verification
method
MUST
NOT
contain
multiple
verification
material
properties
for
the
same
material.
For
example,
expressing
key
material
in
a
verification
method
using
both
publicKeyJwk
and
publicKeyMultibase
at
the
same
time
is
prohibited.
An
example
of
a
controller
document
containing
verification
methods
using
both
properties
above
is
shown
below.
Example
8
:
Verification
methods
using
publicKeyJwk
and
publicKeyMultibase
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/suites/jws-2020/v1",
"https://w3id.org/security/multikey/v1"
]
"id": "did:example:123456789abcdefghi",
"verificationMethod": [{
"id": "did:example:123#_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A",
"type": "JsonWebKey",
"controller": "did:example:123",
"publicKeyJwk": {
"crv": "Ed25519",
"x": "VCpo2LMLhn6iWku8MKvSLg2ZAoC-nlOyPVQaO3FxVeQ",
"kty": "OKP",
"kid": "_Qq0UL2Fq651Q0Fjd6TvnYE-faHiOpRlPVQcY_-tA4A"
}
}, {
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Multikey",
"controller": "did:example:pqrstuvwxyz0987654321",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}],
}
The
Multikey
data
model
is
a
specific
type
of
verification
method
that
utilizes
the
[
MULTICODEC
]
specification
to
encode
key
types
into
a
single
binary
stream
that
is
then
encoded
using
the
[
MULTIBASE
]
specification.
When
specifing
a
Multikey
,
the
object
takes
the
following
form:
-
type
-
The
type
property
MUST
contain
the
string
Multikey
.
-
publicKeyMultibase
-
The
publicKeyMultibase
property
is
OPTIONAL
.
If
present,
the
value
MUST
be
a
[
MULTIBASE
]
encoded
[
MULTICODEC
]
value.
-
secretKeyMultibase
-
The
secretKeyMultibase
property
is
OPTIONAL
.
If
present,
the
value
MUST
be
a
[
MULTIBASE
]
encoded
[
MULTICODEC
]
value.
An
example
of
a
Multikey
is
provided
below:
Example
9
:
Multikey
encoding
of
a
Ed25519
public
key
{
"@context": ["https://w3id.org/security/multikey/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
In
the
example
above,
the
publicKeyMultibase
value
starts
with
the
letter
z
,
which
is
the
[
MULTIBASE
]
header
that
conveys
that
the
binary
data
is
base58-encoded
using
the
Bitcoin
base-encoding
alphabet.
The
decoded
binary
data
[
MULTICODEC
]
header
is
0xed
,
which
specifies
that
the
remaining
data
is
a
32-byte
raw
Ed25519
public
key
.
The
Multikey
data
model
is
also
capable
of
encoding
secret
keys,
whose
subtypes
include
symmetric
keys
and
private
keys
.
Example
10
:
Multikey
encoding
of
a
Ed25519
secret
key
{
"@context": ["https://w3id.org/security/suites/secrets/v1"],
"id": "did:example:123456789abcdefghi#keys-1",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"secretKeyMultibase": "z3u2fprgdREFtGakrHr6zLyTeTEZtivDnYCPZmcSt16EYCER"
}
In
the
example
above,
the
secretKeyMultibase
value
starts
with
the
letter
z
,
which
is
the
[
MULTIBASE
]
header
that
conveys
that
the
binary
data
is
base58-encoded
using
the
Bitcoin
base-encoding
alphabet.
The
decoded
binary
data
[
MULTICODEC
]
header
is
0x1300
,
which
specifies
that
the
remaining
data
is
a
32-byte
raw
Ed25519
private
key.
The
JSON
Web
Key
(JWK)
data
model
is
a
specific
type
of
verification
method
that
uses
the
JWK
specification
[
RFC7517
]
to
encode
key
types
into
a
set
of
parameters.
When
specifing
a
JsonWebKey
,
the
object
takes
the
following
form:
-
type
-
The
type
property
MUST
contain
the
string
JsonWebKey
.
-
publicKeyJwk
-
The
publicKeyJwk
property
is
OPTIONAL
.
If
present,
the
value
MUST
be
a
map
representing
a
JSON
Web
Key
that
conforms
to
[
RFC7517
].
The
map
MUST
NOT
any
members
of
the
private
information
class,
such
as
"d",
as
described
in
the
JWK
Registration
Template
.
It
is
RECOMMENDED
that
verification
methods
that
use
JWKs
[
RFC7517
]
to
represent
their
public
keys
use
the
value
of
kid
as
their
fragment
identifier.
It
is
RECOMMENDED
that
JWK
kid
values
are
set
to
the
public
key
fingerprint
[
RFC7638
].
See
the
first
key
in
Example
8
for
an
example
of
a
public
key
with
a
compound
key
identifier.
-
secretKeyJwk
-
The
secretKeyJwk
property
is
OPTIONAL
.
If
present,
the
value
MUST
be
a
map
representing
a
JSON
Web
Key
that
conforms
to
[
RFC7517
].
An
example
of
an
object
that
conforms
to
this
data
model
is
provided
below:
Example
11
:
JSON
Web
Key
encoding
of
an
Ed25519
public
key
{
"@context": ["https://www.w3.org/ns/security/jwk/v1"],
"id": "did:example:123456789abcdefghi#key-1",
"type": "JsonWebKey",
"controller": "did:example:123456789abcdefghi",
"publicKeyJwk": {
"kty": "OKP",
"alg": "EdDSA"
"crv": "Ed25519",
"kid": "key-1",
"x": "_1EiHquO2aUx9JARSu0P8jdYT_OVneYxYOnOMAmUcFI",
}
}
In
the
example
above,
the
publicKeyJwk
value
contains
the
JSON
Web
Key.
The
kty
property
encodes
the
key
type
of
"OKP",
which
means
"Octet
string
key
pairs".
The
alg
property
identifies
the
algorithm
intended
for
use
with
the
public
key.
The
crv
property
identifies
the
particular
curve
type
of
the
public
key.
The
kid
property
specifies
how
the
public
key
might
be
referenced
in
software
systems;
if
present,
the
kid
value
SHOULD
match
the
id
property
of
the
encapsulating
JsonWebKey
object.
Finally,
the
x
property
specifies
the
point
on
the
Ed25519
curve
that
is
associated
with
the
public
key.
The
publicKeyJwk
property
MUST
NOT
contain
any
property
marked
as
"Private"
in
any
registry
contained
in
the
JOSE
Registries
[
JOSE-REGISTRIES
].
The
JSON
Web
Key
data
model
is
also
capable
of
encoding
secret
keys
,
sometimes
referred
to
as
private
keys
.
Example
12
:
JSON
Web
Key
encoding
of
an
Ed25519
secret
key
{
"@context": ["https://www.w3.org/ns/security/jwk/v1"],
"id": "did:example:123456789abcdefghi#key-1",
"type": "JsonWebKey",
"controller": "did:example:123456789abcdefghi",
"secretKeyJwk": {
"kty": "OKP",
"alg": "EdDSA"
"crv": "Ed25519",
"kid": "key-1",
"d": "Q6JwjCUdThSnoxfXHSFt5C1nVFycY_ZpW7qVzK644_g",
"x": "_1EiHquO2aUx9JARSu0P8jdYT_OVneYxYOnOMAmUcFI",
}
}
The
private
key
example
above
is
almost
identical
to
the
previous
example
of
the
public
key,
except
that
the
information
is
stored
in
the
secretKeyJwk
property
(rather
than
the
publicKeyJwk
),
and
the
private
key
value
is
encoded
in
the
d
property
thereof
(alongside
the
x
property,
which
still
specifies
the
point
on
the
Ed25519
curve
that
is
associated
with
the
public
key).
A
verification
relationship
expresses
the
relationship
between
the
controller
and
a
verification
method
.
Different
verification
relationships
enable
the
associated
verification
methods
to
be
used
for
different
purposes.
It
is
up
to
a
verifier
to
ascertain
the
validity
of
a
verification
attempt
by
checking
that
the
verification
method
used
is
contained
in
the
appropriate
verification
relationship
property
of
the
controller
document
.
The
verification
relationship
between
the
controller
and
the
verification
method
is
explicit
in
the
controller
document
.
Verification
methods
that
are
not
associated
with
a
particular
verification
relationship
cannot
be
used
for
that
verification
relationship
.
For
example,
a
verification
method
in
the
value
of
the
`
authentication
`
property
cannot
be
used
to
engage
in
key
agreement
protocols
with
the
controller
—the
value
of
the
`
keyAgreement
`
property
needs
to
be
used
for
that.
The
controller
document
does
not
express
revoked
keys
using
a
verification
relationship
.
If
a
referenced
verification
method
is
not
in
the
latest
controller
document
used
to
dereference
it,
then
that
verification
method
is
considered
invalid
or
revoked.
The
following
sections
define
several
useful
verification
relationships
.
A
controller
document
MAY
include
any
of
these,
or
other
properties,
to
express
a
specific
verification
relationship
.
In
order
to
maximize
global
interoperability,
any
such
properties
used
SHOULD
be
registered
in
the
Data
Integrity
Specification
Registries
[TBD:
DIS-REGISTRIES].
The
authentication
verification
relationship
is
used
to
specify
how
the
controller
is
expected
to
be
authenticated
,
for
purposes
such
as
logging
into
a
website
or
engaging
in
any
sort
of
challenge-response
protocol.
-
authentication
-
The
authentication
property
is
OPTIONAL
.
If
present,
the
associated
value
MUST
be
a
set
of
one
or
more
verification
methods
.
Each
verification
method
MAY
be
embedded
or
referenced.
Example
14
:
Authentication
property
containing
three
verification
methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
"authentication": [
"did:example:123456789abcdefghi#keys-1",
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
If
authentication
is
established,
it
is
up
to
the
application
to
decide
what
to
do
with
that
information.
This
is
useful
to
any
authentication
verifier
that
needs
to
check
to
see
if
an
entity
that
is
attempting
to
authenticate
is,
in
fact,
presenting
a
valid
proof
of
authentication.
When
a
verifier
receives
some
data
(in
some
protocol-specific
format)
that
contains
a
proof
that
was
made
for
the
purpose
of
"authentication",
and
that
says
that
an
entity
is
identified
by
the
id
,
then
that
verifier
checks
to
ensure
that
the
proof
can
be
verified
using
a
verification
method
(e.g.,
public
key
)
listed
under
`
authentication
`
in
the
controller
document
.
Note
that
the
verification
method
indicated
by
the
`
authentication
`
property
of
a
controller
document
can
only
be
used
to
authenticate
the
controller
.
To
authenticate
a
different
controller
,
the
entity
associated
with
the
value
of
controller
needs
to
authenticate
with
its
own
controller
document
and
associated
`
authentication
`
verification
relationship
.
The
assertionMethod
verification
relationship
is
used
to
specify
how
the
controller
is
expected
to
express
claims,
such
as
for
the
purposes
of
issuing
a
Verifiable
Credential
[
VC-DATA-MODEL-2.0
].
-
assertionMethod
-
The
assertionMethod
property
is
OPTIONAL
.
If
present,
the
associated
value
MUST
be
a
set
of
one
or
more
verification
methods
.
Each
verification
method
MAY
be
embedded
or
referenced.
This
property
is
useful,
for
example,
during
the
processing
of
a
verifiable
credential
by
a
verifier.
During
verification,
a
verifier
checks
to
see
if
a
verifiable
credential
contains
a
proof
created
by
the
controller
by
checking
that
the
verification
method
used
to
assert
the
proof
is
associated
with
the
`
assertionMethod
`
property
in
the
corresponding
controller
document
.
Example
15
:
Assertion
method
property
containing
two
verification
methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
"assertionMethod": [
"did:example:123456789abcdefghi#keys-1",
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
The
keyAgreement
verification
relationship
is
used
to
specify
how
an
entity
can
generate
encryption
material
in
order
to
transmit
confidential
information
intended
for
the
controller
,
such
as
for
the
purposes
of
establishing
a
secure
communication
channel
with
the
recipient.
-
keyAgreement
-
The
keyAgreement
property
is
OPTIONAL
.
If
present,
the
associated
value
MUST
be
a
set
of
one
or
more
verification
methods
.
Each
verification
method
MAY
be
embedded
or
referenced.
An
example
of
when
this
property
is
useful
is
when
encrypting
a
message
intended
for
the
controller
.
In
this
case,
the
counterparty
uses
the
cryptographic
public
key
information
in
the
verification
method
to
wrap
a
decryption
key
for
the
recipient.
Example
16
:
Key
agreement
property
containing
two
verification
methods
{
"@context": "https://www.w3.org/ns/did/v1",
"id": "did:example:123456789abcdefghi",
"keyAgreement": [
"did:example:123456789abcdefghi#keys-1",
{
"id": "did:example:123#zC9ByQ8aJs8vrNXyDhPHHNNMSHPcaSgNpjjsBYpMMjsTdS",
"type": "X25519KeyAgreementKey2019",
"controller": "did:example:123",
"publicKeyMultibase": "z6LSn6p3HRxx1ZZk1dT9VwcfTBCYgtNWdzdDMKPZjShLNWG7"
}
],
}
The
capabilityInvocation
verification
relationship
is
used
to
specify
a
verification
method
that
might
be
used
by
the
controller
to
invoke
a
cryptographic
capability,
such
as
the
authorization
to
update
the
controller
document
.
-
capabilityInvocation
-
The
capabilityInvocation
property
is
OPTIONAL
.
If
present,
the
associated
value
MUST
be
a
set
of
one
or
more
verification
methods
.
Each
verification
method
MAY
be
embedded
or
referenced.
An
example
of
when
this
property
is
useful
is
when
a
controller
needs
to
access
a
protected
HTTP
API
that
requires
authorization
in
order
to
use
it.
In
order
to
authorize
when
using
the
HTTP
API,
the
controller
uses
a
capability
that
is
associated
with
a
particular
URL
that
is
exposed
via
the
HTTP
API.
The
invocation
of
the
capability
could
be
expressed
in
a
number
of
ways,
e.g.,
as
a
digitally
signed
message
that
is
placed
into
the
HTTP
Headers.
The
server
providing
the
HTTP
API
is
the
verifier
of
the
capability
and
it
would
need
to
verify
that
the
verification
method
referred
to
by
the
invoked
capability
exists
in
the
`
capabilityInvocation
`
property
of
the
controller
document
.
The
verifier
would
also
check
to
make
sure
that
the
action
being
performed
is
valid
and
the
capability
is
appropriate
for
the
resource
being
accessed.
If
the
verification
is
successful,
the
server
has
cryptographically
determined
that
the
invoker
is
authorized
to
access
the
protected
resource.
Example
17
:
Capability
invocation
property
containing
two
verification
methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
"capabilityInvocation": [
"did:example:123456789abcdefghi#keys-1",
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
The
capabilityDelegation
verification
relationship
is
used
to
specify
a
mechanism
that
might
be
used
by
the
controller
to
delegate
a
cryptographic
capability
to
another
party,
such
as
delegating
the
authority
to
access
a
specific
HTTP
API
to
a
subordinate.
-
capabilityDelegation
-
The
capabilityDelegation
property
is
OPTIONAL
.
If
present,
the
associated
value
MUST
be
a
set
of
one
or
more
verification
methods
.
Each
verification
method
MAY
be
embedded
or
referenced.
An
example
of
when
this
property
is
useful
is
when
a
controller
chooses
to
delegate
their
capability
to
access
a
protected
HTTP
API
to
a
party
other
than
themselves.
In
order
to
delegate
the
capability,
the
controller
would
use
a
verification
method
associated
with
the
capabilityDelegation
verification
relationship
to
cryptographically
sign
the
capability
over
to
another
controller
.
The
delegate
would
then
use
the
capability
in
a
manner
that
is
similar
to
the
example
described
in
2.3.2.4
Capability
Invocation
.
Example
18
:
Capability
Delegation
property
containing
two
verification
methods
{
"@context": [
"https://www.w3.org/ns/did/v1",
"https://w3id.org/security/multikey/v1"
],
"id": "did:example:123456789abcdefghi",
"capabilityDelegation": [
"did:example:123456789abcdefghi#keys-1",
{
"id": "did:example:123456789abcdefghi#keys-2",
"type": "Multikey",
"controller": "did:example:123456789abcdefghi",
"publicKeyMultibase": "z6MkmM42vxfqZQsv4ehtTjFFxQ4sQKS2w6WR7emozFAn5cxu"
}
],
}
The
term
Linked
Data
is
used
to
describe
a
recommended
best
practice
for
exposing,
sharing,
and
connecting
information
on
the
Web
using
standards,
such
as
URLs,
to
identify
things
and
their
properties.
When
information
is
presented
as
Linked
Data,
other
related
information
can
be
easily
discovered
and
new
information
can
be
easily
linked
to
it.
Linked
Data
is
extensible
in
a
decentralized
way,
greatly
reducing
barriers
to
large
scale
integration.
With
the
increase
in
usage
of
Linked
Data
for
a
variety
of
applications,
there
is
a
need
to
be
able
to
verify
the
authenticity
and
integrity
of
Linked
Data
documents.
This
specification
adds
authentication
and
integrity
protection
to
data
documents
through
the
use
of
mathematical
proofs
without
sacrificing
Linked
Data
features
such
as
extensibility
and
composability.
Note
:
Use
of
Linked
Data
is
an
optional
feature
While
this
specification
provides
mechanisms
to
digitally
sign
Linked
Data,
the
use
of
Linked
Data
is
not
necessary
to
gain
some
of
the
advantages
provided
by
this
specification.
Issue
:
(AT
RISK)
Hash
values
might
change
during
Candidate
Recommendation
This
section
lists
cryptographic
hash
values
that
might
change
during
the
Candidate
Recommendation
phase
based
on
implementer
feedback
that
requires
the
referenced
files
to
be
modified.
Implementations
that
perform
JSON-LD
processing
MUST
treat
the
following
JSON-LD
context
URLs
as
already
resolved,
where
the
resolved
document
matches
the
corresponding
hash
values
below:
|
URL
and
Media
Type
|
Content
|
https://www.w3.org/ns/data-integrity/v1
application/ld+json
|
sha256:
v/POI0jhSjPansxhJAP1fwepCBZ2HK77fRZfCCyBDs0=
sha3-512:
Sg1PLFxKyEYQns9Zr0BoYXtFeDNfrHUDNMkyq4QEWv
wGIaX1v5xovnCG+dfceZEzr7BhBjm396noZF1HEeCM8g==
|
https://www.w3.org/ns/multikey/v1
application/ld+json
|
sha256:
SA+P0RxXl8ZH6xdPcmX71crzeGkCYMPfYjdVT46SF0o=
sha3-512:
BgQBN00t6vj1T4uYt5SwdPOhe2BVNY11UEvkVo/rbBv
fBd+Z09isxhGhf2HkVqMT
SANah1u7rLk6Uw6GeQGH1w==
|
The
security
vocabulary
terms
that
the
JSON-LD
contexts
listed
above
resolve
to
are
in
the
https://w3id.org/security#
namespace.
That
is,
all
security
terms
in
this
vocabulary
are
of
the
form
https://w3id.org/security#TERM
,
where
TERM
is
the
name
of
a
term.
Implementations
that
perform
RDF
processing
MUST
treat
the
following
JSON-LD
vocabulary
URL
as
already
resolved,
where
the
resolved
document
matches
the
corresponding
hash
values
below.
When
dereferencing
the
https://w3id.org/security#
URL,
the
data
returned
depends
on
HTTP
content
negotiation.
These
are
as
follows:
|
Media
Type
|
Description
and
Cryptographic
Hashes
|
|
application/ld+json
|
The
vocabulary
in
JSON-LD
format
[
JSON-LD
].
sha256:
LEaoTyf796eTaSlYWjfPe3Yb+poCW9TjWYTbFDmC0tc=
sha3-512:
f4DhJ3xhT8nT+GZ8UUZi4QC+HT//wXE2fRTgUP4UNw
e4kvel2PFfd6jcofHBm9BjwEiGzVFGv4K+fFTKXRD2NA==
|
|
text/turtle
|
The
vocabulary
in
Turtle
format
[
TURTLE
].
sha256:
McnhLyt7+/A/0iLb3CUXD0itNw+7bwwjtzOww/zwoyI=
sha3-512:
jZtZsqgPPPo+jphAcN8/St4VdRLLAmN3nEQhzs0twE
MTmCY45euQ01Z4Zo7VlJMYNTf0KC6BMpogpSTAi/1J7Q==
|
|
|
text/html
|
The
vocabulary
in
HTML+RDFa
Format
[
HTML-RDFA
].
sha256:
eUHP1xiSC157iTPDydZmxg/hvmX3g/nnCn+FO25d4dc=
sha3-512:
z53j8ryjVeX16Z/dby//ujhw37degwi09+LAZCTUB8
WJZjjzW1AydhdEWmgHM0P5KUcPMmSe7edMlGr7G9rmcA==
|
|
It
is
possible
to
confirm
the
digests
listed
above
by
running
the
following
command
from
a
modern
Unix
command
interface
line:
curl
-sL
-H
"Accept:
<MEDIA_TYPE>"
<DOCUMENT_URL>
|
openssl
dgst
-<DIGEST_ALGORITHM>
-binary
|
openssl
base64
-nopad
-a
.
For
further
information
regarding
processing
of
JSON-LD
Contexts
and
Vocabularies,
see
Verifiable
Credentials
v2.0:
Base
Context
and
Verifiable
Credentials
v2.0:
Vocabularies
.
The
following
section
describes
security
considerations
that
developers
implementing
this
specification
should
be
aware
of
in
order
to
create
secure
software.
Cryptography
secures
information
through
the
use
of
secrets.
Knowledge
of
the
necessary
secret
makes
it
computationally
easy
to
access
certain
information.
The
same
information
can
be
accessed
if
a
computationally-difficult,
brute-force
effort
successfully
guesses
the
secret.
All
modern
cryptography
requires
the
computationally
difficult
approach
to
remain
difficult
throughout
time,
which
does
not
always
hold
due
to
breakthroughs
in
science
and
mathematics.
That
is
to
say
that
Cryptography
has
a
shelf
life
.
This
specification
plans
for
the
obsolescence
of
all
cryptographic
approaches
by
asserting
that
whatever
cryptography
is
in
use
today
is
highly
likely
to
be
broken
over
time.
Software
systems
have
to
be
able
to
change
the
cryptography
in
use
over
time
in
order
to
continue
to
secure
information.
Such
changes
might
involve
increasing
required
secret
sizes
or
modifications
to
the
cryptographic
primitives
used.
However,
some
combinations
of
cryptographic
parameters
might
actually
reduce
security.
Given
these
assumptions,
systems
need
to
be
able
to
distinguish
different
combinations
of
safe
cryptographic
parameters,
also
known
as
cryptographic
suites,
from
one
another.
When
identifying
or
versioning
cryptographic
suites,
there
are
several
approaches
that
can
be
taken
which
include:
parameters,
numbers,
and
dates.
Parametric
versioning
specifies
the
particular
cryptographic
parameters
that
are
employed
in
a
cryptographic
suite.
For
example,
one
could
use
an
identifier
such
as
RSASSA-PKCS1-v1_5-SHA1
.
The
benefit
to
this
scheme
is
that
a
well-trained
cryptographer
will
be
able
to
determine
all
of
the
parameters
in
play
by
the
identifier.
The
drawback
to
this
scheme
is
that
most
of
the
population
that
uses
these
sorts
of
identifiers
are
not
well
trained
and
thus
will
not
understand
that
the
previously
mentioned
identifier
is
a
cryptographic
suite
that
is
no
longer
safe
to
use.
Additionally,
this
lack
of
knowledge
might
lead
software
developers
to
generalize
the
parsing
of
cryptographic
suite
identifiers
such
that
any
combination
of
cryptographic
primitives
becomes
acceptable,
resulting
in
reduced
security.
Ideally,
cryptographic
suites
are
implemented
in
software
as
specific,
acceptable
profiles
of
cryptographic
parameters
instead.
Numbered
versioning
might
specify
a
major
and
minor
version
number
such
as
1.0
or
2.1
.
Numbered
versioning
conveys
a
specific
order
and
suggests
that
higher
version
numbers
are
more
capable
than
lower
version
numbers.
The
benefit
of
this
approach
is
that
it
removes
complex
parameters
that
less
expert
developers
might
not
understand
with
a
simpler
model
that
conveys
that
an
upgrade
might
be
appropriate.
The
drawback
of
this
approach
is
that
its
not
clear
if
an
upgrade
is
necessary,
as
software
version
number
increases
often
don't
require
an
upgrade
for
the
software
to
continue
functioning.
This
can
lead
to
developers
thinking
their
usage
of
a
particular
version
is
safe,
when
it
is
not.
Ideally,
additional
signals
would
be
given
to
developers
that
use
cryptographic
suites
in
their
software
that
periodic
reviews
of
those
suites
for
continued
security
are
required.
Date-based
versioning
specifies
a
particular
release
date
for
a
specific
cryptographic
suite.
The
benefit
of
a
date,
such
as
a
year,
is
that
it
is
immediately
clear
to
a
developer
if
the
date
is
relatively
old
or
new.
Seeing
an
old
date
might
prompt
the
developer
to
go
searching
for
a
newer
cryptographic
suite,
where
as
a
parametric
or
number-based
versioning
scheme
might
not.
The
downside
of
a
date-based
version
is
that
some
cryptographic
suites
might
not
expire
for
5-10
years,
prompting
the
developer
to
go
searching
for
a
newer
cryptographic
suite
only
to
not
find
one
that
is
newer.
While
this
might
be
an
inconvenience,
it
is
one
that
results
in
safer
ecosystem
behavior.
The
following
text
is
currently
under
debate:
It
is
highly
encouraged
that
cryptographic
suite
identifiers
are
versioned
using
a
year
designation.
For
example,
the
cryptographic
suite
identifier
ecdsa-2022
implies
that
the
suite
is
probably
an
acceptable
of
ECDSA
in
the
year
2025,
but
might
not
be
a
safe
choice
in
the
year
2042.
A
date-based
versioning
mechanism,
however,
is
not
enough
by
itself.
All
cryptographic
suites
that
follow
this
specification
are
intended
to
be
registered
[
VC-SPECS
]
in
a
way
that
clearly
signal
which
cryptosuites
are
deprecated,
standardized,
or
experimental.
Cryptosuite
registration
will
follow
CFRG,
IETF,
NIST,
FIPS,
and
safecurves
guidance.
Use
of
deprecated
suites
are
expected
to
throw
errors
in
implementations
unless
a
useUnsafeCryptosuites
option
is
used
specifying
exactly
the
unsafe
cryptosuite
to
use.
Use
of
experimental
suites
are
expected
to
throw
errors
in
implementations
unless
a
useExperimentalCryptosuites
option
is
used
specifying
exactly
the
experimental
cryptosuite
to
use.
Modern
cryptographic
algorithms
provide
a
number
of
tunable
parameters
and
options
to
ensure
that
the
algorithms
can
meet
the
varied
requirements
of
different
use
cases.
For
example,
embedded
systems
have
limited
processing
and
memory
environments
and
might
not
have
the
resources
to
generate
the
strongest
digital
signatures
for
a
given
algorithm.
Other
environments,
like
financial
trading
systems,
might
only
need
to
protect
data
for
a
day
while
the
trade
is
occurring,
while
other
environments
might
need
to
protect
data
for
multiple
decades.
To
meet
these
needs,
cryptographic
algorithm
designers
often
provide
multiple
ways
to
configure
a
cryptographic
algorithm.
Cryptographic
library
implementers
often
take
the
specifications
created
by
cryptographic
algorithm
designers
and
specification
authors
and
implement
them
such
that
all
options
are
available
to
the
application
developers
that
use
their
libraries.
This
can
be
due
to
not
knowing
which
combination
of
features
a
particular
application
developer
might
need
for
a
given
cryptographic
deployment.
All
options
are
often
exposed
to
application
developers.
Application
developers
that
use
cryptographic
libraries
often
do
not
have
the
requisite
cryptographic
expertise
and
knowledge
necessary
to
appropriately
select
cryptographic
parameters
and
options
for
a
given
application.
This
lack
of
expertise
can
lead
to
an
inappropriate
selection
of
cryptographic
parameters
and
options
for
a
particular
application.
This
specification
sets
the
priority
of
constituencies
to
protect
application
developers
over
cryptographic
library
implementers
over
cryptographic
specification
authors
over
cryptographic
algorithm
designers.
Given
these
priorities,
the
following
recommendations
are
made:
-
Cryptographic
algorithm
designers
are
advised
[
RFC7696
]
to
minimize
the
number
of
options
and
parameters
to
as
few
as
possible
to
ensure
that
cryptographic
library
implementers
have
a
more
easily
auditable
security
attack
surface
for
their
software
libraries.
-
Cryptographic
specification
authors
are
advised
to,
if
possible,
further
minimize
the
number
of
options
and
parameters
to
as
few
as
possible
to
ensure
cryptographic
agility
while
also
keeping
the
auditable
security
attack
surface
for
downstream
software
libraries
to
a
minimum.
-
Cryptographic
library
implementers
are
advised
to,
if
possible,
provide
known
good
combinations
of
options
and
parameters
to
application
developers.
There
would
ideally
be
two
pre-set
default
configurations
for
any
algorithmic
class,
such
as
Elliptic
Curve
Digital
Signatures,
with
no
ability
to
fine
tune
parameters
and
options
when
using
these
pre-sets.
Library
options
can
be
provided
to
experts
to
fine
tune
their
use
of
the
library,
use
of
those
options
by
the
general
application
developer
population
is
to
be
discouraged.
-
Application
developers
are
advised
to
choose
from
a
number
of
pre-set
cryptography
library
configurations
and
to
avoid
modifying
cryptographic
options
and
parameters,
or
using
experimental
or
deprecated
cryptography.
The
guidance
above
is
meant
to
ensure
that
useful
cryptographic
options
and
parameters
are
provided
at
the
lower
layers
of
the
architecture
while
not
exposing
those
options
and
parameters
to
application
developers
who
may
not
fully
understand
the
balancing
benefits
and
drawbacks
of
each
option.
Issue
:
Use
of
experimental
and
deprecated
cryptography
The
VCWG
is
seeking
guidance
on
adding
language
to
allow
the
use
of
experimental
or
deprecated
cryptography.
By
default,
those
features
will
be
disabled
and
will
require
the
application
developer
to
specifically
allow
use
on
a
per-cryptographic
suite
basis.
There
will
be
requirements
for
all
implementing
libraries
to
throw
errors
or
warnings
when
deprecated
or
experimental
options
are
selected
without
the
appropriate
override
flags.
Section
5.1
Versioning
Cryptography
Suites
emphasized
the
importance
of
providing
relatively
easy
to
understand
information
concerning
the
timeliness
of
particular
cryptographic
suite,
while
section
5.2
Protecting
Application
Developers
further
emphasized
minimizing
the
number
of
options
to
be
specified.
Indeed,
section
3.
Cryptographic
Suites
lists
requirements
for
cryptographic
suites
which
include
detailed
specification
of
algorithm,
transformation,
hashing,
and
serialization.
Hence,
the
name
of
the
cryptographic
suite
does
not
need
to
include
all
this
detail,
which
implies
the
parametric
versioning
mentioned
in
section
5.1
Versioning
Cryptography
Suites
is
neither
necessary
nor
desirable.
The
recommended
naming
convention
for
cryptographic
suites
is
a
string
composed
of
a
signature
algorithm
identifier,
separated
by
a
hyphen
from
an
option
identifier
(if
the
cryptosuite
supports
incompatible
implementation
options),
followed
by
a
hyphen
and
designation
of
the
approximate
year
that
the
suite
was
proposed.
For
example,
the
[
DI-EDDSA
]
is
based
on
EdDSA
digital
signatures,
supports
two
incompatible
options
based
on
canonicalization
approaches,
and
was
proposed
in
roughly
the
year
2022,
so
it
would
have
two
different
cryptosuite
names:
eddsa-rdfc-2022
and
eddsa-jcs-2022
.
Although
the
[
DI-ECDSA
]
is
based
on
ECDSA
digital
signatures,
supports
the
same
two
incompatible
canonicalization
approaches
as
[
DI-EDDSA
],
and
supports
two
different
levels
of
security
(128
bit
and
192
bit)
via
two
alternative
sets
of
elliptic
curves
and
hashes,
it
has
only
two
cryptosuite
names:
ecdsa-rdfc-2019
and
ecdsa-jcs-2019
.
The
security
level
and
corresponding
curves
and
hashes
are
determined
from
the
multi-key
format
of
the
public
key
used
in
validation.
Cryptographic
agility
is
a
practice
by
which
one
designs
frequently
connected
information
security
systems
to
support
switching
between
multiple
cryptographic
primitives
and/or
algorithms
.
The
primary
goal
of
cryptographic
agility
is
to
enable
systems
to
rapidly
adapt
to
new
cryptographic
primitives
and
algorithms
without
making
disruptive
changes
to
the
systems'
infrastructure.
Thus,
when
a
particular
cryptographic
primitive,
such
as
the
SHA-1
algorithm,
is
determined
to
be
no
longer
safe
to
use,
systems
can
be
reconfigured
to
use
a
newer
primitive
via
a
simple
configuration
file
change.
Cryptographic
agility
is
most
effective
when
the
client
and
the
server
in
the
information
security
system
are
in
regular
contact.
However,
when
the
messages
protected
by
a
particular
cryptographic
algorithm
are
long-lived,
as
with
Verifiable
Credentials,
and/or
when
the
client
(holder)
might
not
be
able
to
easily
recontact
the
server
(issuer),
then
cryptographic
agility
does
not
provide
the
desired
protections.
Cryptographic
layering
is
a
practice
where
one
designs
rarely
connected
information
security
systems
to
employ
multiple
primitives
and/or
algorithms
at
the
same
time
.
The
primary
goal
of
cryptographic
layering
is
to
enable
systems
to
survive
the
failure
or
one
or
more
cryptographic
algorithms
or
primitives
without
losing
cryptographic
protection
on
the
payload.
For
example,
digitally
signing
a
single
piece
of
information
using
RSA,
ECDSA,
and
Falcon
algorithms
in
parallel
would
provide
a
mechanism
that
could
survive
the
failure
of
two
of
these
three
digital
signature
algorithms.
When
a
particular
cryptographic
protection
is
compromised,
such
as
an
RSA
digital
signature
using
768-bit
keys,
systems
can
still
utilize
the
non-compromised
cryptographic
protections
to
continue
to
protect
the
information.
Developers
are
urged
to
take
advantage
of
this
feature
for
all
signed
content
that
might
need
to
be
protected
for
a
year
or
longer.
This
specification
provides
for
both
forms
of
agility.
It
provides
for
cryptographic
agility,
which
allows
one
to
easily
switch
from
one
algorithm
to
another.
It
also
provides
for
cryptographic
layering,
which
allows
one
to
simultaneously
use
multiple
cryptographic
algorithms,
typically
in
parallel,
such
that
any
of
those
used
to
protect
information
can
be
used
without
reliance
on
or
requirement
of
the
others,
while
still
keeping
the
digital
proof
format
easy
to
use
for
developers.
The
inspectability
of
application
data
has
effects
on
system
efficiency
and
developer
productivity.
When
cryptographically
protected
application
data,
such
as
base-encoded
binary
data,
is
not
easily
processed
by
application
subsystems,
such
as
databases,
it
increases
the
effort
of
working
with
the
cryptographically
protected
information.
For
example,
a
cryptographically
protected
payload
that
can
be
natively
stored
and
indexed
by
a
database
will
result
in
a
simpler
system
that:
-
benefits
from
utilizing
existing
industry-standard
database
features
with
no
changes
to
the
protected
information,
-
avoids
the
complexity
of
duplicating
data
where
one
copy
of
the
data
preserves
the
message
and
digital
signature,
while
the
other
copy
only
stores
and
indexes
the
message
and
is
what
drives
system
behaviour,
-
avoids
the
complexity
of
bespoke
solutions
that
have
to
structurally
modify
the
protected
information,
such
as
serializing
and
deserializing
nested
digitally
signed
data
that
has
multiple
nested
base-encoded
payloads.
Similarly,
a
cryptographically
protected
payload
that
can
be
processed
by
multiple
upstream
networked
systems
increases
the
ability
to
properly
layer
security
architectures.
For
example,
if
upstream
systems
do
not
have
to
repeatedly
decode
the
incoming
payload,
it
increases
the
ability
for
a
system
to
distribute
processing
load
by
specializing
upstream
subsystems
to
actively
combat
attacks.
While
a
digital
signature
needs
to
always
be
checked
before
taking
substantive
action,
other
upstream
checks
can
be
performed
on
transparent
payloads
—
such
as
identifier-based
rate
limiting,
signature
expiration
checking,
or
nonce/challenge
checking
—
to
reject
obviously
bad
requests.
Additionally,
if
a
developer
is
not
able
to
easily
view
data
in
a
system,
the
ability
to
easily
audit
or
debug
system
correctness
is
hampered.
For
example,
requiring
application
developers
to
cut-and-paste
base-encoded
application
data
makes
development
more
challenging
and
increases
the
chances
that
obvious
bugs
will
be
missed
because
every
message
needs
to
go
through
a
manually
operated
base-decoding
tool.
There
are
times,
however,
where
the
correct
design
decision
is
to
make
data
opaque.
Data
that
does
not
need
to
be
processed
by
other
application
subsystems,
as
well
as
data
that
does
not
need
to
be
modified
or
accessed
by
an
application
developer,
can
be
serialized
into
opaque
formats.
Examples
include
digital
signature
values,
cryptographic
key
parameters,
and
other
data
fields
that
only
need
to
be
accessed
by
a
cryptographic
library
and
need
not
be
modified
by
the
application
developer.
There
are
also
examples
where
data
opacity
is
appropriate
when
the
underlying
subsystem
does
not
expose
the
application
developer
to
the
underlying
complexity
of
the
opaque
data,
such
as
databases
that
perform
encryption
at
rest.
In
these
cases,
the
application
developer
continues
to
develop
against
transparent
application
data
formats
while
the
database
manages
the
complexity
of
encrypting
and
decrypting
the
application
data
to
and
from
long-term
storage.
This
specification
strives
to
provide
an
architecture
where
application
data
remains
in
its
native
format
and
is
not
made
opaque,
while
other
cryptographic
data,
such
as
digital
signatures,
are
kept
in
their
opaque
binary
encoded
form.
Cryptographic
suite
implementers
are
urged
to
consider
appropriate
use
of
data
opacity
when
designing
their
suites,
and
to
weigh
the
design
trade-offs
when
making
application
data
opaque
versus
providing
access
to
cryptographic
data
at
the
application
layer.
Issue
Implementers
must
ensure
that
a
verification
method
is
bound
to
a
particular
controller
by
going
from
the
verification
method
to
the
controller
document,
and
then
ensuring
that
the
controller
document
also
contains
the
verification
method.
When
an
implementation
is
verifying
a
proof
,
it
is
imperative
that
it
verify
not
only
that
the
verification
method
used
to
generate
the
proof
is
listed
in
the
controller
document
,
but
also
that
it
was
intended
to
be
used
to
generate
the
proof
that
is
being
verified.
This
process
is
known
as
"verification
relationship
validation".
The
process
for
verification
relationship
validation
is
outlined
in
Section
4.5
Retrieve
Verification
Method
.
This
process
is
used
to
ensure
that
cryptographic
material,
such
as
a
private
cryptographic
key,
is
not
misused
by
application
to
an
unintended
purpose.
An
example
of
cryptographic
material
misuse
would
be
if
a
private
cryptographic
key
meant
to
be
used
to
issue
a
Verifiable
Credential
was
instead
used
to
log
into
a
website
(that
is,
for
authentication).
Not
checking
a
verification
relationship
is
dangerous
because
the
restriction
and
protection
profile
for
some
cryptographic
material
could
be
determined
by
its
intended
use.
For
example,
some
applications
could
be
trusted
to
use
cryptographic
material
for
only
one
purpose,
or
some
cryptographic
material
could
be
more
protected,
such
as
through
storage
in
a
hardware
security
module
in
a
data
center
versus
as
an
unencrypted
file
on
a
laptop.
When
an
implementation
is
verifying
a
proof
,
it
is
imperative
that
it
verify
that
the
proof
purpose
match
the
intended
use.
This
process
is
used
to
ensure
that
proofs
are
not
misused
by
an
application
for
an
unintended
purpose,
as
this
is
dangerous
for
the
proof
creator.
An
example
of
misuse
would
be
if
a
proof
that
stated
its
purpose
was
for
securing
assertions
in
verifiable
credentials
was
instead
used
for
authentication
to
log
into
a
website.
In
this
case,
the
proof
creator
attached
proofs
to
any
number
of
verifiable
credentials
that
they
expected
to
be
distributed
to
an
unbounded
number
of
other
parties.
Any
one
of
these
parties
could
log
into
a
website
as
the
proof
creator
if
the
website
erroneously
accepted
such
a
proof
as
authentication
instead
of
its
intended
purpose.
One
of
the
algorithmic
processes
used
by
this
specification
is
canonicalization,
which
is
a
type
of
transformation
.
Canonicalization
is
the
process
of
taking
information
that
might
be
expressed
in
a
variety
of
semantically
equivalent
ways
as
input,
and
expressing
all
output
in
a
single
way,
called
a
"canonical
form".
The
security
of
a
resulting
data
integrity
proof
that
utilizes
canonicalization
is
highly
dependent
on
the
correctness
of
the
algorithm.
For
example,
if
a
canonicalization
algorithm
converts
two
inputs
that
have
different
meanings
into
the
same
output,
then
the
author's
intentions
can
be
misrepresented
to
a
verifier
.
This
can
be
used
as
an
attack
vector
by
adversaries.
Additionally,
if
semantically
relevant
information
in
an
input
is
not
present
in
the
output,
then
an
attacker
could
insert
such
information
into
a
message
without
causing
proof
verification
to
fail.
This
is
similar
to
another
transformation
that
is
commonly
used
when
cryptographically
signing
messages:
cryptographic
hashing.
If
an
attacker
is
able
to
produce
the
same
cryptographic
hash
from
a
different
input,
then
the
cryptographic
hash
algorithm
is
not
considered
secure.
Implementers
are
strongly
urged
to
ensure
proper
vetting
of
any
canonicalization
algorithms
to
be
used
for
transformation
of
input
to
a
hashing
process.
Proper
vetting
includes,
at
a
minimum,
association
with
a
peer
reviewed
mathematical
proof
of
algorithm
correctness;
multiple
implementations
and
vetting
by
experts
in
a
standards
setting
organization
is
preferred.
Implementers
are
strongly
urged
not
to
invent
or
use
new
mechanisms
unless
they
have
formal
training
in
information
canonicalization
and/or
access
to
experts
in
the
field
who
are
capable
of
producing
a
peer
reviewed
mathematical
proof
of
algorithm
correctness.
The
following
section
describes
privacy
considerations
that
developers
implementing
this
specification
should
be
aware
of
in
order
to
create
privacy
enhancing
software.
When
a
digitally-signed
payload
contains
data
that
is
seen
by
multiple
verifiers,
it
becomes
a
point
of
correlation.
An
example
of
such
data
is
a
shopping
loyalty
card
number.
Correlatable
data
can
be
used
for
tracking
purposes
by
verifiers,
which
can
sometimes
violate
privacy
expectations.
The
fact
that
some
data
can
be
used
for
tracking
might
not
be
immediately
apparent.
Examples
of
such
correlatable
data
include,
but
are
not
limited
to,
a
static
digital
signature
or
a
cryptographic
hash
of
an
image.
It
is
possible
to
create
a
digitally-signed
payload
that
does
not
have
any
correlatable
tracking
data
while
also
providing
some
level
of
assurance
that
the
payload
is
trustworthy
for
a
given
interaction.
This
characteristic
is
called
unlinkability
which
ensures
that
no
correlatable
data
are
used
in
a
digitally-signed
payload
while
still
providing
some
level
of
trust,
the
sufficiency
of
which
must
be
determined
by
each
verifier.
It
is
important
to
understand
that
not
all
use
cases
require
or
even
permit
unlinkability.
There
are
use
cases
where
linkability
and
correlation
are
required
due
to
regulatory
or
safety
reasons,
such
as
correlating
organizations
and
individuals
that
are
shipping
and
storing
hazardous
materials.
Unlinkability
is
useful
when
there
is
an
expectation
of
privacy
for
a
particular
interaction.
There
are
at
least
two
mechanisms
that
can
provide
some
level
of
unlinkability.
The
first
method
is
to
ensure
that
no
data
value
used
in
the
message
is
ever
repeated
in
a
future
message.
The
second
is
to
ensure
that
any
repeated
data
value
provides
adequate
herd
privacy
such
that
it
becomes
practically
impossible
to
correlate
the
entity
that
expects
some
level
of
privacy
in
the
interaction.
A
variety
of
methods
can
be
used
to
achieve
unlinkability.
These
methods
include
ensuring
that
a
message
is
a
single
use
bearer
token
with
no
information
that
can
be
used
for
the
purposes
of
correlation,
using
attributes
that
ensure
an
adequate
level
of
herd
privacy,
and
the
use
of
cryptosuites
that
enable
the
entity
presenting
a
message
to
regenerate
new
signatures
while
not
compromising
the
trust
in
the
message
being
presented.
Selective
disclosure
is
a
technique
that
enables
the
recipient
of
a
previously-signed
message
(that
is,
a
message
signed
by
its
creator)
to
reveal
only
parts
of
the
message
without
disturbing
the
verifiability
of
those
parts.
For
example,
one
might
selectively
disclose
a
digital
driver's
license
for
the
purpose
of
renting
a
car.
This
could
involve
revealing
only
the
issuing
authority,
license
number,
birthday,
and
authorized
motor
vehicle
class
from
the
license.
Note
that
in
this
case,
the
license
number
is
correlatable
information,
but
some
amount
of
privacy
is
preserved
because
the
driver's
full
name
and
address
are
not
shared.
Not
all
software
or
cryptosuites
are
capable
of
providing
selective
disclosure.
If
the
author
of
a
message
wishes
it
to
be
selectively
disclosable
by
its
recipient,
then
they
need
to
enable
selective
disclosure
on
the
specific
message,
and
both
need
to
use
a
capable
cryptosuite.
The
author
might
also
make
it
mandatory
to
disclose
certain
parts
of
the
message.
A
recipient
that
wants
to
selectively
disclose
partial
content
of
the
message
needs
to
utilize
software
that
is
able
to
perform
the
technique.
An
example
of
a
cryptosuite
that
supports
selective
disclosure
is
bbs-2022
.
It
is
possible
to
selectively
disclose
information
in
a
way
that
does
not
preserve
unlinkability.
For
example,
one
might
want
to
disclose
the
inspection
results
related
to
a
shipment,
which
include
the
shipment
identifier
or
lot
number,
which
might
have
to
be
correlatable
due
to
regulatory
requirements.
However,
disclosure
of
the
entire
inspection
result
might
not
be
required
as
selectively
disclosing
just
the
pass/fail
status
could
be
deemed
adequate.
For
more
information
on
disclosing
information
while
preserving
privacy,
see
Section
6.1
Unlinkability
.
