-
Notifications
You must be signed in to change notification settings - Fork 13
NDNCERT Protocol 0.3
Authors
- Zhiyi Zhang (zhiyi@cs.ucla.edu)
Acknowledgement
- Junxiao Shi (https://yoursunny.com/m/)
- Davide Pesavento (davide.pesavento@nist.gov)
- Members from NDN Dev Call
Note
- NDNCERT protocol v0.3 is for future use and has not been implemented nor deployed. It may subject to future changes after peer reviews.
Ongoing Issues
- Zhiyi: I added
max-validity-period
in CA profile because a requester require the information to determine the validity period. - Junxiao: TLV evolvability guidelines should be followed by default, unless there's a reason to opt out of TLV evolvability guidelines.
- Junxiao: Use version + segment in
/<ca-prefix>/CA/INFO
instead of timestamp - Junxiao and Davide: Add error response.
- Junxiao: Use ABNF format for TLV packet format spec
- Junxiao: Consider merging "parameter-key" and "parameter-key" into a single "parameter-key" TLV-TYPE, and merging "parameter-value" and "parameter-value" into a single "parameter-value" TLV-TYPE
- Junxiao: Make all the TLV-TYPEs in the first version of NDNCERT 0.3 be critical.
- Remove DOWNLOAD step
- Remove
_
from_PROBE
,_NEW
,_CHALLENGE
- Separate INFO out of PROBE step
- Add Redirection extension to PROBE step to improve scalability and usability
- PROBE step become purely informational and there is no more bindings between PROBE and later steps
- CA can allow its requesters to get multiple certificates under the same identity name for different keys
- CA can allow its requesters to get certificates of a longer name (sub namespace) than the designated identity name
- Add error handling
- Use TLV to replace JSON text used in PROBE, NEW, and CHALLENGE steps
- Use uncompressed ECC (Elliptic Curve Cryptography) public key in the ECDH (Elliptic Curve Diffie-Hellman) in NEW step
- Issuer or Certificate Authority (CA). Issuer and CA are used interchangeably in this document. An issuer or a CA is the party who owns a namespace and can issue certificates to requesters who want to get a sub namespace from the issuer/CA.
- Requester or Client. Requester and client are used interchangeably in this document. A requester or a client is the party who wants to get a sub namespace and its corresponding certificate from an Issuer.
-
<variable>
represents one or more name components in an NDN name. For example,/<ca-prefix>/CA/INFO
refers to/ndn/edu/ucla/CA/INFO
when CA's name is/ndn/edu/ucla
. -
<timestamp>
,<version>
,<segment>
, and<ParameterSha256Digest>
are one name component which contains a timestamp, a version ID, a segment ID, and a SHA256 digest value, respectively. Refer more details of these name components to NDN naming conventions. -
<Request-ID>
is one generic name component containing a 8 byte unique ID to identify the PROBE/application/renewal/revocation request. - Parent namespace and sub namespace are used to refer to relations between the CA's name and a requested name. For example, we call
/example/alice
a sub namespace with respect that/example
is the parent namespace. - Signed Interest or Interest Signature. All signed Interest packets appear in this document is supposed to follow the format as defined signed Interest. In NDNCERT, each signed Interest should contain a SignatureNonce and a SignatureTime.
- TLV encoding. In this document, all the elements carried by the Interest ApplicationParameters and Data content are encoded using Type-Length-Value encoding.
- The string TLV value fields appear in this specification all assume the use of UTF-8 encoding.
In Named Data Networking (NDN), to generate Data packets with legitimate names and verifiable signatures, an application (producer) needs to obtain a name and an associated certificate for that name. The certificate application can either be accomplished manually or through automated means. NDN certificate management protocol (NDNCERT) aims to enable automatic certificate management in NDN, including
- certificate application,
- certificate renewal
- certificate revocation
All aforementioned management operations will require certain out-of-band or in-band identity verification means.
Furthermore, NDNCERT allows a namespace owner to easily manage its sub-namespaces and corresponding certificates by
- becoming a certificate issuer for the parent namespace
or
- applying for certificates for valid sub namespaces from the same issuer as the one who issued the parent namespace to that entity.
For example, with NDNCERT, Alice (as a requester) can get a namespace /ndn/edu/ucla/alice
from the issuer /ndn/edu/ucla
after she successfully proves her identity.
After that, by utilizing NDNCERT protocol, Alice can become an issuer for namespace /ndn/edu/ucla/alice
and issue names/certificates to her devices, e.g., designating name /ndn/edu/ucla/alice/working-laptop
to her laptop.
If issuer /ndn/edu/ucla
allows, Alice can also directly apply for namespace /ndn/edu/ucla/alice/working-laptop
for her laptop directly from /ndn/edu/ucla
.
Note that NDNCERT does not impose any specific trust model or trust anchors.
A profile file contains this CA's requirement on name assignment, CA's certificate, etc. The CA profile is published in Data packets as a segmented object following NDN naming conventions. The profile is needed for all the requesters who want to get/renew/revoke certificates from the CA.
Importantly, a requester should already have certain means to authenticate a CA's profile. For example, the requester can be aware of the CA's public key in advance through out-of-band channels so that the requester can use the public key to verify the profile is truly generated by the expected CA.
Otherwise, the requester should not trust the profile. However, by properly designing an identity verification challenge to be bidirectional (i.e., the CA verifies the requester's identity, while at the same time, the requester also verifies CA's identity), the requester can verify trust the CA in a later step. For example, the challenge can be proof of awareness of a shared secret which is only known to the CA and the requester.
CA profile Data packets are considered to be static and can be hosted by a repository. By using version and segment components, the CA profile can be fetched with NDN RDR protocol.
Data format:
Field | Description |
---|---|
Name | /<CA-Prefix>/CA/INFO/<version>/<segment> |
FinalBlockId | Only present in the final block. Same value as the segment component |
Content | TLV of CA's profile |
Signature | Signed by CA's identity key |
Content = CONTENT-TYPE TLV-LENGTH
ca-prefix
ca-info
*parameter-key
max-validity-period
ca-certificate
ca-prefix = CA-PREFIX-TYPE TLV-LENGTH
Name
ca-info = CA-INFO-TYPE TLV-LENGTH *OCTET
parameter-key = PARAMETER-KEY-TYPE TLV-LENGTH *OCTET
max-validity-period = MAX-VALIDITY-PERIOD-TYPE TLV-LENGTH
nonNegativeInteger
ca-certificate = CA-CERTIFICATE-TYPE TLV-LENGTH CertificateV2
An example
T:Content, L, V:
T:ca-prefix, L, V:"/ndn/CA"
T:ca-info, L, V:"NDN Testbed CA"
T:parameter-key, L, V:"email",
T:parameter-key, L, V:"full name"
T:max-validity-period, L, V:3600
T:ca-certificate, L, V:...
The attributes in a CA profile carried by INFO Data packet contains:
-
ca-prefix
, bytes value, the TLV of NDN name of the CA. This name should be reachable to requesters. -
ca-info
, UTF-8 string value, a brief introduction of the CA. - A number of
parameter-key
, UTF-8 string value, a list of attributes required by the CA to identify the name for a requester in the PROBE step. -
max-validity-period
, non negative integer value, maximum allowed validity period of the desired certificate. The unit is second. -
ca-certificate
, bytes value, TLV of the CA's certificate.
PROBE is used by the requester to know which name is legitimate with respect to requester's identity information. PROBE is useful when the CA needs to keep an association between a sub namespace with the identify of the owner of this sub namespace.
The PROBE step works as follows.
- Requester: prepare the parameters used for PROBE and send a PROBE Interest to the CA.
- CA: generate available names from the parameters input from the requester and replies them to the requester.
After PROBE, a requester can select one name among the names provided by the CA for the later certificate application.
If CA does not have any namespace available for the requester, CA should reply a Data packet containing the error message No Available Names
as defined in Section 3.
Interest format:
Field | Description |
---|---|
Name | /<CA-Prefix>/CA/PROBE/<ParameterSha256Digest> |
ApplicationParameters | A list of TLV tuples of parameter-key and parameter-value
|
Can Be Prefix | False |
Must Be Fresh | True |
Signature | Not required |
ApplicationParameters = APPLICATION-PARAMETERS-TYPE TLV-LENGTH
*(parameter-key parameter-value)
parameter-key = PARAMETER-KEY-TYPE TLV-LENGTH *OCTET
parameter-value = PARAMETER-VALUE-TYPE TLV-LENGTH *OCTET
-
parameter-key
, UTF-8 string value, the same asparameter-key
specified in the CA profile. -
parameter-value
, binary value, the value of eachparameter-key
.
Data format:
Field | Description |
---|---|
Name | /<CA-Prefix>/CA/PROBE/<ParameterSha256Digest> |
Freshness Period | 4 seconds |
Content | A list of probe-response
|
Signature | Signed by CA's identity key |
Content = CONTENT-TYPE TLV-LENGTH 1*probe-response
probe-response = PROBE-RESPONSE-TYPE TLV-LENGTH Name [allow-longer-name]
allow-longer-name = ALLOW-LONGER-NAME-TYPE TLV-LENGTH ;==0
-
probe-response
, bytes value, it contains an NDNName
TLV and an optionalallow-longer-name
. -
allow-longer-name
, no value, the existence ofallow-longer-name
indicates the CA allow a requester to apply for a longer name than the name listed in CA's PROBE Data packet.
An example.
Interest:
Name: /ndn/edu/ucla/CA/PROBE/params-sha256=893259d...
ApplicationParameters:
{
T:parameter-key, L, V:"email"
T:parameter-value, L, V:"zhiyi@cs.ucla.edu"
T:parameter-key, L, V:"full name"
T:parameter-value, L, V:"zhiyi zhang"
}
Data:
Name: /ndn/edu/ucla/CA/PROBE/params-sha256=893259d...
Content:
{
T:probe-response, L, V:
T:Name, L, V:/ndn/edu/ucla/zhiyi@cs.ucla.edu
T:probe-response, L, V:
T:Name, L, V:/ndn/edu/ucla/zhiyi@cs.ucla.edu
T:allow-longer-name, L
}
Signature
NEW is for requester to formally start a certificate application process. The CA will also start to keep the request state.
The NEW step works as follows.
- Requester: prepare a pair of asymmetric key (e.g., RSASSA-PKCS1-v1_5, ECDSA), use the private key to sign the public key into a self-signed certificate, generate a fresh ECC key pair for ECDH, and send the NEW Interest
- CA: keep the request state, generate a fresh ECC key pair for ECDH, collect available challenges for identity verification, and send the NEW Data reply.
Importantly, the requester can define the desired validity time of its certificate which will be issued by the CA later.
To do this, the requester should specify the validity period of the self-signed certificate in the corresponding field as defined in NDN certificate.
If the desired validity period exceeds CA's policy, the certificate request will be rejected.
Specifically, the NotBefore
field and NotAfter
field in the certificate request should satisfy:
cert-request.NotBefore >= Max(NOW - 120_s, ca-certificate.NotBefore)
cert-request.NotBefore < cert-request.NotAfter
cert-request.NotAfter <= Min(NOW + max-validity-period, ca-certificate.NotAfter)
where NOW
is the time when requester generates the certificate request, ca-certificate
is CA's certificate, max-validity-period
is the maximum validity period allowed by the CA, and 120_s
is not before grace period.
Both the requester and the CA will take self private key and received public key as input and execute ECDH along with HKDF to generate the symmetric key. The symmetric key will be used to encrypt the Interest ApplicationParameters and Data Content used in the CHALLENGE.
After NEW, a requester can select one challenge among the challenges provided by the CA for the identity verification and enter the CHALLENGE step.
Interest format:
Field | Description |
---|---|
Name | /<CA-prefix>/CA/NEW/<ParameterSha256Digest> |
ApplicationParameters |
ecdh-pub ,cert-request
|
Can Be Prefix | False |
Must Be Fresh | True |
Signature | Signed by the private key whose public key is going to be certified by the CA |
ApplicationParameters = APPLICATION-PARAMETERS-TYPE TLV-LENGTH
ecdh-pub
cert-request
ecdh-pub = ECDH-PUB-TYPE
TLV-LENGTH ; == 65
65OCTET
cert-request = CERT-REQUEST-TYPE TLV-LENGTH *OCTET
-
ecdh-pub
, bytes value, requester's ECC public key used for Elliptic-Curve Diffie-Hellman key agreement. The key should be encoded as its uncompressed format. Such a ECC public key should be generated with cryptographically secure pseudo random generator for every NEW-CHALLENGE session. The ECC curve is prime256v1 (same as P-256 and secp256r1). -
cert-request
, bytes value, the TLV of a self-signed certificate generated by the requester. Such a certificate follows the certificate format defined in NDN certificate.
Data format:
Field | Description |
---|---|
Name | /<CA-prefix>/CA/NEW/<ParameterSha256Digest> |
Freshness Period | 4 seconds |
Content |
ecdh-pub , salt , request-id , status , A list of challenge
|
Signature | Signed by CA's identity key |
Content = CONTENT-TYPE TLV-LENGTH
ecdh-pub
salt
request-id
1*challenge
ecdh-pub = ECDH-PUB-TYPE
TLV-LENGTH ; == 65
65OCTET
salt = SALT-TYPE
TLV-LENGTH ; == 32
32OCTET
request-id = REQUEST-ID-TYPE
TLV-LENGTH ; == 8
8OCTET
challenge = CHALLENGE-TYPE
TLV-LENGTH
*OCTET
-
ecdh-pub
, bytes value, the issuer's ECC public key used for Elliptic-Curve Diffie-Hellman key agreement. The key should be encoded as its raw format without compression. Such a ECC public key should be generated with cryptographically secure pseudo random generator for every NDNCERT session. -
salt
, bytes value, 32 bytes value. This value will be used in HMAC based Key Derivation Function to generate the symmetric AES key to encrypt the Interest ApplicationParameters and Data Content used in CHALLENGE step. -
request-id
, 8 bytes value, unique ID assignment for this request instance. -
challenge
, UTF-8 string value, the name of a challenge that the requester can choose to prove their identity.
After NEW step, both the requester and the CA will perform HKDF.
Following the notation used in RFC 5869, we consider the format of HKDF to be (Hash, IKM, salt, Info, L) -> OKM
.
In NDNCERT, we have:
- The
Hash
function is SHA256. - The
IKM
is the 256 bits result of the ECDH over curve prime256v1 (same as P-256 and secp256r1). - The
Salt
is specified in the NEW Data reply from the CA. - The
Info
is the 8 byte value ofrequest-id
. - The
L
should be 16 bytes (128 bit) used for AES-GCM-128 encryption in the CHALLENGE step.
CHALLENGE step is for the requester to prove their identity to the CA. Once approved, the CA will issue the certificate for the requester.
Notice that the payload in ApplicationParameters field in Interest and Content field in Data will be encrypted using the AES-GCM-128 key derived from the ECDH and HDKF in the NEW step. Importantly, in CHALLENGE step, NDNCERT utilizes AES-GCM's Authenticated Encryption with Associated Data (AEAD) feature: in the encryption process, besides secret key, nonce, plaintext, there is an additional parameter called associated data. The associated data will not be encrypted but will be used for authentication. In NDNCERT, we let the request ID to be the associated data in order to cryptographically bind the encryption to a specific request.
Interest format:
Field | Description |
---|---|
Name | /<CA-prefix>/CA/CHALLENGE/<Request_ID>/<ParameterSha256Digest> |
ApplicationParameters |
initialization-vector , encrypted-payload
|
Can Be Prefix | False |
Must Be Fresh | True |
Signature | Signed by the private key whose public key is going to be certified by the CA |
ApplicationParameters = APPLICATION-PARAMETERS-TYPE TLV-LENGTH
initialization-vector
authentication-tag
encrypted-payload
initialization-vector = INITIALIZATION-VECTOR-TYPE
TLV-LENGTH ; == 12
12OCTET
authentication-tag = AUTHENTICATION_TAG_TYPE
TLV-LENGTH ; == 16
16OCTET
encrypted-payload = ENCRYPTED-PAYLOAD-TYPE TLV-LENGTH *OCTET
; the plaintext to be encrypted
plaintext = selected-challenge
1*(parameter-key parameter-value)
selected-challenge = SELECTED-CHALLENGE-TYPE TLV-LENGTH *OCTET
parameter-key = PARAMETER-KEY-TYPE TLV-LENGTH *OCTET
parameter-value = PARAMETER-VALUE-TYPE TLV-LENGTH *OCTET
-
initialization-vector
, 12 bytes value, the IV for AES GCM encryption. -
authentication-tag
, 16 bytes value, the authentication tag for AES GCM 128 encryption. -
encrypted-payload
, bytes value, the AES GCM ciphertext. The encrypted content containsselected-challenge
and one or moreparameter-key
,challenge-value
pairs-
selected-challenge
, UTF-8 string value, the challenge selected by the requester. -
parameter-key
, UTF-8 string value, the name of a parameter required by the selected challenge -
parameter-value
, binary value, the value of the parameter.
-
Data format:
Field | Description |
---|---|
Freshness Period | 4 seconds |
Name | /<CA-prefix>/CA/CHALLENGE/<Request_ID>/<ParameterSha256Digest> |
Content |
initialization-vector , encrypted-payload
|
Signature | Signed by CA's identity key |
Content = CONTENT-TYPE TLV-LENGTH
initialization-vector
authentication-tag
encrypted-payload
initialization-vector = INITIALIZATION-VECTOR-TYPE
TLV-LENGTH ; == 12
12OCTET
authentication-tag = AUTHENTICATION_TAG_TYPE
TLV-LENGTH ; == 16
16OCTET
encrypted-payload = ENCRYPTED-PAYLOAD-TYPE TLV-LENGTH *OCTET
; the TLV to be encrypted
plaintext = status
challenge-status
remaining-tries
remaining-time
[issued-cert-name]
status = STATUS-TYPE
TLV-LENGTH ; == 1
nonNegativeInteger
challenge-status = CHALLENGE-STATUS-TYPE TLV-LENGTH *OCTET
remaining-tries = REMAINING-TRIES-TYPE TLV-LENGTH
nonNegativeInteger
remaining-time = REMAINING-TIME-TYPE TLV-LENGTH
nonNegativeInteger
issued-cert-name = ISSUED-CERT-NAME-TYPE TLV-LENGTH Name
-
initialization-vector
, 12 bytes value, the IV for AES GCM 128 encryption. -
authentication-tag
, 16 bytes value, the authentication tag for AES GCM 128 encryption. -
encrypted-payload
, bytes value, the AES GCM ciphertext. The encrypted content contains following information-
status
: non negative integer value, the application status code. In CHALLENGE step, when challenge has not been selected, the status isSTATUS_BEFORE_CHALLENGE
; when challenge has been selected but not finished, the status isSTATUS_CHALLENGE
; when challenge is finished but not yet approved by the CA, the status isSTATUS_PENDING
; when challenge is finished and CA has approved the result, the status isSTATUS_SUCCESS
.- STATUS_BEFORE_CHALLENGE = 0,
- STATUS_CHALLENGE = 1,
- STATUS_PENDING = 2,
- STATUS_SUCCESS = 3,
-
challenge-status
, UTF-8 string value, the challenge status code, specified by the selected challenge implementation. -
remaining-tries
, non negative integer value, the remaining times that the requester can send a challenge Interest. -
remaining-time
, non negative integer value, the remaining time in unit of second for the requester to finish the challenge. -
issued-cert-name
, bytes value, full name TLV of the certificate issued by the CA for the requester after the challenge has been successfully accomplished.
-
This section defines the format for the error messages used in PROBE, NEW, and CHALLENGE steps. Error messages are not needed in the INFO step because a published INFO packet is considered static and usually will be hosted by a third party repository (e.g., a repo-ng server).
Notice that, in CHALLENGE step, if the challenge already starts and the Interest has a valid and fresh signature, the allowed number of attempts will also be reduced.
When there is an error in the PROBE or NEW step, the CA server should not abort the request and erase the state used for the request. When there is an error in the CHALLENGE step, the CA will abort the application only when all the allowed attempts are used up or the challenge goes out of time.
Data format:
Field | Description |
---|---|
Name | Same as the Interest name |
Content |
error-code , error-info
|
Signature | Signed by CA's identity key |
Content = CONTENT-TYPE TLV-LENGTH
error-code
error-info
error-code = ERROR-CODE-TYPE
TLV-LENGTH ; == 1
nonNegativeInteger
error-info = ERROR-INFO-TYPE TLV-LENGTH *OCTET
-
error-code
, non negative integer value, the error code. -
error-info
, UTF-8 string value, a human-readable error message.
Error Code | Definition |
---|---|
1 | Bad Interest Format, used in PROBE, NEW, and CHALLENGE steps when the Interest format is incorrect, e.g., no ApplicationParameters |
2 | Bad Parameter Format, used in PROBE, NEW, and CHALLENGE steps when the Interest ApplicationParameters field is not correctly formed. |
3 | Bad Signature or signature info, used in NEW, and CHALLENGE steps when the Interest carries a invalid signature. |
4 | Invalid parameters, used in PROBE, NEW, and CHALLENGE step when the input from the requester is not expected. |
5 | Name not allowed, used in NEW and CHALLENGE steps when the requested certificate name cannot be assigned to the requester. |
6 | Bad Validity Period, used in NEW step when requested certificate has a erroneous validity period, e.g., too long time. |
7 | Run out of tries, used in CHALLENGE step when the requester wants to proceed the challenge after they have already used up all the allowed attempts. |
8 | Run out of time, used in CHALLENGE step when the requester wants to proceed the challenge after they have already used up all the allowed time. |
9 | No Available Names, used in PROBE step when CA finds there is no namespaces available based on the PROBE parameters provided. |
New certificate application contains three steps: PROBE, NEW, and CHALLENGE.
Requester CA
| |
| (Optionally) |
|---------PROBE-------->|
|<----------------------|
| |
|---------RENEW-------->|
|<----------------------|
| |
|-------CHALLENGE------>|
|<----------------------|
From a requester's perspective:
- Optional PROBE. When CA has a name assignment policy, a requester may need the PROBE step to know the expected name that they can obtain based on their identity information. Without the PROBE step, a name request may be rejected by the CA.
- NEW. The requester prepares a pair of asymmetric key (e.g., RSASSA-PKCS1-v1_5, ECDSA), use the private key to sign the public key into a self-signed certificate, and start the application by taking NEW step.
- CHALLENGE. The requester selects one challenge among available challenges offered by the CA and finish the in-band or out-of-band identity verification. Once the challenge is accomplished, the certificate will be issued.
From a CA's perspective:
- Optional PROBE. When CA has a name assignment policy, the CA needs to explicitly specify the parameters needed for the PROBE in its profile, which can be downloaded through INFO. In the PROBE step, the CA takes the parameters from the requester as input and generate an available name for the requester.
- NEW. The CA verifies the self-signed certificate from the requester and collects all the available challenges back to the requester.
- CHALLENGE. According to the challenge selected by the requester, the CA sets up the challenge and verifies the requester's ownership of the identity.
In the NEW step, after the CA sends out the NEW reply, it sets a timer to be 1 minute within which the requester should send the first CHALLENGE interest. If there is no incoming Interest from the requester, all state will be removed by the CA.
In the CHALLENGE step, after the CA sends out the first Data packet, the CA will keep the state for the time as defined in remaining-time
field defined by the challenge selected.
If the requester cannot finish the challenge within remaining-time
and remaining-tries
, the state will be removed by the CA.
NDNCERT protocol does not put restrictions on whether a CA should allow longer namespace assignment, namely, if a CA permits, a requester can apply for a certificate whose name is longer than its deserved name.
For example, assuming in PROBE step, a CA replies /example/alice
to the requester. Then in the NEW step, the requester can apply for a name /example/alice/phone
if the requester can prove its identity associated with name /example/alice
.
Attribute | TLV-TYPE Number (decimal) | TLV-TYPE Number (hexadecimal) |
---|---|---|
ca-prefix | 129 | 81 |
ca-info | 131 | 83 |
parameter-key | 133 | 85 |
parameter-value | 135 | 87 |
ca-certificate | 137 | 89 |
max-validity-period | 139 | 8B |
probe-response | 141 | 8D |
allow-longer-name | 143 | 8F |
ecdh-pub | 145 | 91 |
cert-request | 147 | 93 |
salt | 149 | 95 |
request-id | 151 | 97 |
challenge | 153 | 99 |
status | 155 | 9B |
initialization-vector | 157 | 9D |
encrypted-payload | 159 | 9F |
selected-challenge | 161 | A1 |
challenge-status | 163 | A3 |
remaining-tries | 165 | A5 |
remaining-time | 167 | A7 |
issued-cert-name | 169 | A9 |
error-code | 171 | AB |
error-info | 173 | AD |
authentication-tag | 175 | AF |