Skip to content

NDNCERT Protocol 0.3

Jump to bottom
Zhiyi Zhang edited this page Apr 22, 2020 · 56 revisions

NDN Certificate Management (NDNCERT) Protocol v0.3

Authors

Acknowledgement

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.

Changes

Major Changes

  • 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

Minor Changes

  • 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

Terminology

  • 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.

1. Overview

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.

2. Packet Specification

2.1 CA profile

2.1.1 Specification

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.

2.1.2 Packet Format

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:...

2.1.3 CA Profile

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.

2.2 PROBE step

2.2.1 Specification

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.

2.2.2 Packet Format

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 as parameter-key specified in the CA profile.
  • parameter-value, binary value, the value of each parameter-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 NDN Name TLV and an optional allow-longer-name.
  • allow-longer-name, no value, the existence of allow-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

2.3 NEW step

2.3.1 Specification

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.

2.3.2 Packet Format

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.

2.3.3 HMAC based Key Derivation Function (HKDF)

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 of request-id.
  • The L should be 16 bytes (128 bit) used for AES-GCM-128 encryption in the CHALLENGE step.

2.4 CHALLENGE step

2.4.1 Specification

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.

2.4.2 Packet Format

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
                          encrypted-payload
initialization-vector = INITIALIZATION-VECTOR-TYPE
                 TLV-LENGTH ; == 12
                 12OCTET
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.
  • encrypted-payload, bytes value, the AES GCM ciphertext. The encrypted content contains selected-challenge and one or more parameter-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
            encrypted-payload
initialization-vector = INITIALIZATION-VECTOR-TYPE
                 TLV-LENGTH ; == 12
                 12OCTET
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.
  • 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 is STATUS_BEFORE_CHALLENGE; when challenge has been selected but not finished, the status is STATUS_CHALLENGE; when challenge is finished but not yet approved by the CA, the status is STATUS_PENDING; when challenge is finished and CA has approved the result, the status is STATUS_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.

3. Error Handling

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.

3.1 Error Message Data Packet Format

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.

3.2 Error Code and Reason

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.

4. New Certificate Application Protocol

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.

4.1 Timers Maintained by CAs

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.

4.2 Name Assignment

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.

Appendix A: TLV-TYPE Numbers

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
Clone this wiki locally