Skip to content

NDNCERT Protocol 0.3

Jump to bottom
Junxiao Shi edited this page Sep 21, 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.

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 SHA-256 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 either becoming a certificate issuer for the namespace, or applying for certificates of valid sub namespaces from the same issuer of the parent namespace.

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

The CA profile specifies a CA's requirement on name assignment, the CA's certificate, and other information. It is published in Data packets as a segmented object following NDN naming conventions.

Every requester needs to obtain the CA profile before applying for, renewing, or revoking certificates. It is assumed that a requester should already have certain means to authenticate a CA's profile. For example, the requester can obtain the CA's public key in advance through out-of-band channels, so that it can use the public key to verify that the CA profile Data packets are generated by the expected CA.

It is also possible to design an identity verification challenge to be bidirectional (the CA and the requester verifies each other's identity). In this case, the requester can provisionally accept the CA profile, and verify the CA's identity in a later step. For example, the challenge can require proof of awareness of a shared secret that is only known to the CA and the requester.

CA profile Data packets are 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 last segment. 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
  • 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.

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.2 PROBE step

2.2.1 Specification

A requester may use the PROBE step to find out which name prefix(es) this requester can apply a certificate for, based on the requester's identity information and the CA's policy. PROBE is useful when the CA needs to enforce a relation between a sub namespace and the identify of the owner of this sub namespace. For example, the CA could require the sub namespace to contain its owner's email address.

The PROBE step works as follows.

  1. The requester sends a PROBE Interest to the CA that contains a set of parameters describing their identity.
  2. The CA generates a list of available names from these parameters, and sends a reply in a Data packet.
  3. In case the CA does not have any namespace available for the requester, it should reply a Data packet containing the error message No Available Names as defined in Section 3.
  4. After PROBE, the requester can select one of the provided names, and continue certificate application process.

The PROBE step is purely information, and is optional. If the requester already knows what names can be used in certificate application, it does not have to use this step.

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
CanBePrefix False
MustBeFresh 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>
FreshnessPeriod 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

The NEW step formally initiates a certificate application process.

The NEW step works as follows.

  1. The requester generates a key pair using an asymmetric crypto algorithm (e.g., RSASSA-PKCS1-v1_5, ECDSA), and creates a self-signed certificate by signing the public key with the private key. This public key will be the public key that appears in the final certificate.
  2. The requester generates an ECDH key pair, which will be used to derive a session key to encrypt later messages.
  3. The requester sends a NEW Interest.
  4. The CA generates a unique ID for this request, generates an ECDH key pair, and derives a session key to encrypt later messages.
  5. The CA determines what challenges can be used for identity verification, sends a reply in a Data packet, and saves state about this request in its local database.

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 continue to the CHALLENGE step.

2.3.2 Packet Format

Interest format:

Field Description
Name /<CA-prefix>/CA/NEW/<ParameterSha256Digest>
CanBePrefix False
MustBeFresh True
ApplicationParameters see below
Signature Signed by the private key corresponding to the cert-request 
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 ECDH public key. See section 2.3.4 for details.
  • cert-request, bytes value, the TLV of a self-signed certificate generated by the requester. It should follow the NDN certificate format.

Data format:

Field Description
Name /<CA-prefix>/CA/NEW/<ParameterSha256Digest>
FreshnessPeriod 4 seconds
Content see below
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. See section 2.3.4 for details.
  • salt, bytes value, 32 bytes value. See section 2.3.5 for details.
  • 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 ValidityPeriod

The requester can specify the desired ValidityPeriod of the final certificate in the ValidityPeriod field of the self-signed certificate. The CA verifies that the ValidityPeriod does not violate the CA's policy; otherwise, 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)

in which

  • NOW is the current time.
  • ca-certificate is the CA's certificate.
  • max-validity-period is the maximum validity period allowed by the CA, as specified in the CA profile.
  • 120_s is a grace period to adjust for potential clock skew between the requester and the CA.

2.3.4 Elliptic-Curve Diffie-Hellman (ECDH) Key Agreement

During the NEW step, the requester and the CA each generates a fresh ECC key pair for ECDH purpose. This key should be generated with a cryptographically secure pseudo random generator, and each certificate request session must use a unique key. The ECC curve is prime256v1 (same as NIST P-256 and secp256r1).

The public key is sent to the other party in ecdh-pub field of NEW Interest and NEW Data, encoded as uncompressed format. Upon receiving the other party's public key, the requester and the CA each runs the ECDH algorithm to derive a 256-bit shared secret, which is then passed to the HKDF step below.

2.3.5 HMAC based Key Derivation Function (HKDF)

After ECDH, the requester and the CA each runs HKDF algorithm to generate an 128-bit AES key, for encrypting Interest ApplicationParameters and Data Content during CHALLENGE step.

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 SHA-256.
  • The IKM is the 256 bits result of the ECDH, as described in section 2.3.4.
  • The Salt is a 32-byte value freshly generated by the CA for each request using a cryptographically secure pseudo random generator, and communicated to the requester in salt field of the NEW Data.
  • 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.

2.4.2 AES-GCM Encryption

Messages in CHALLENGE step are encrypted with AES-GCM-128 algorithm. Encrypted messages are encoded as follows:

encrypted-message = 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 AES key used in CHALLENGE step is derived from the ECDH and HDKF in the NEW step.

AES-GCM supports 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 is not encrypted but can be used for authentication. NDNCERT uses the request ID as associated data, to cryptographically bind the encryption to a specific request.

Security of AES-GCM depends on choosing a unique initialization vector for every encryption performed with the same key. To ensure this requirement is met, the initialization vectors must be constructed as follows:

  • Each initialization vector is 96 bits (i.e. 12 octets).
  • The first bit (i.e. most significant bit of the first octet) identifies an entity. This bit should be set to 0 for messages from the requester and 1 for messages from the issuer.
  • The next 63 bits is a nonce. Each entity should generate a random 63-bit nonce at the beginning of the CHALLENGE step, and use it in every message.
  • The last 32 bits is a counter. Each entity should initialize the counter to zero at the beginning of the CHALLENGE step. Then, after encrypting a message of b AES blocks, it should increment the counter by b. Each AES block is 64 bits, so b = CEIL(len(plaintext) / 8). The counter field is big endian.

Recipient of each message should verify the uniqueness of initialization vectors. If a requester detects a violation, it should abort the certificate application process. If an issuer detects a violation, it should respond with error message 3.

2.4.3 Packet Format

Interest format:

Field Description
Name /<CA-prefix>/CA/CHALLENGE/<Request_ID>/<ParameterSha256Digest>
CanBePrefix False
MustBeFresh True
ApplicationParameters see below
Signature Signed by the private key corresponding to the cert-request 
ApplicationParameters = APPLICATION-PARAMETERS-TYPE TLV-LENGTH encrypted-message

; the plaintext before encryption
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 encryption.
  • encrypted-payload, bytes value, the AES GCM ciphertext.

In the plaintext before encryption:

  • 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, bytes value, the value of the parameter.

Data format:

Field Description
Name /<CA-prefix>/CA/CHALLENGE/<Request_ID>/<ParameterSha256Digest>
FreshnessPeriod 4 seconds
Content see below
Signature Signed by CA's identity key 
Content = CONTENT-TYPE TLV-LENGTH encrypted-message

; the plaintext before encryption
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 encryption.
  • authentication-tag, 16 bytes value, the authentication tag for AES GCM encryption.
  • encrypted-payload, bytes value, the AES GCM ciphertext.

In the plaintext before encryption:

  • status: non negative integer value, the application status code. See the list below for potential values.
  • 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.

Possible values of status are:

  • 0: STATUS_BEFORE_CHALLENGE, the requester has not selected a challenge.
  • 1: STATUS_CHALLENGE, the challenge is in progress.
  • 2: STATUS_PENDING, the challenge is finished, but not yet approved by the CA.
  • 3: STATUS_SUCCESS, the challenge is finished, and the CA has approved the result.

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 see below
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 PROBE NEW CHALLENGE Definition
1 ✔️ ✔️ ✔️ Bad Interest Format: the Interest format is incorrect, e.g., no ApplicationParameters.
2 ✔️ ✔️ ✔️ Bad Parameter Format: the ApplicationParameters field is not correctly formed.
3 ❌ ✔️ ✔️ Bad Signature or signature info: the Interest carries a invalid signature.
4 ✔️ ✔️ ✔️ Invalid parameters: the input from the requester is not expected.
5 ❌ ✔️ ✔️ Name not allowed: the requested certificate name cannot be assigned to the requester.
6 ❌ ✔️ ❌ Bad ValidityPeriod: requested certificate has a erroneous validity period, e.g., too long time.
7 ❌ ❌ ✔️ Run out of tries: the requester failed to complete the challenge within allowed number of attempts.
8 ❌ ❌ ✔️ Run out of time: the requester failed to complete the challenge within time limit.
9 ✔️ ❌ ❌ No Available Names: the 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-------->|
   |<----------------------|
   |                       |
   |----------NEW--------->|
   |<----------------------|
   |                       |
   |-------CHALLENGE------>|
   |<----------------------|

From a requester's perspective:

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. NEW. The CA verifies the self-signed certificate from the requester and collects all the available challenges back to the requester.
  3. 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 limit defined by the challenge selected. If the requester cannot finish the challenge within the time limit, the CA will remove the state.

4.2 Name Assignment

A CA may allow longer namespace assignment. In other words, if a CA permits, a requester can apply for a certificate whose name is longer than its deserved name.

For example, in the PROBE step, a CA may reply /example/alice with allow-longer-name indication. In the NEW step, the requester may apply for a certificate for the 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
authentication-tag 175 AF
Clone this wiki locally