User Guide to Obtain a Testbed Certificate

Prerequisite

Essential NDN software

Ensure that you have installed NFD and ndncert.
If you do not have the latest ndn-cxx and NFD installed yet, you can follow NFD installation page installation guide.
If you do not have ndncert installed yet, you can build NDNCERT from source and install:

git clone https://github.com/named-data/ndncert
cd ndncert
./waf configure
./waf
sudo ./waf install
sudo ldconfig

Configure ndncert-client

sudo cp /usr/local/etc/ndncert/client.conf.sample /usr/local/etc/ndncert/client.conf

Reachable email address

Ensure that you have an reachable email address. When the ndncert client notifies you that Testbed sends a identity verification code to your provided email address, you should be able to return that code within 300 seconds by the mean described below.

Request a certificate

Open your terminal, connect your local NFD to the NDN Testbed by
```
~$ nfd-start 
~$ ndn-autoconfig
```
Run the NDNCERT client by

~$ ndncert-client

The terminal should show a CA selection page with a default CA prefix /ndn at index 0. Choose index 0 to probe the NDN Testbed root CA.

***************************************
Step 1: CA SELECTION
> Index: 0
>> CA prefix:/ndn
>> Introduction:
Please type in the CA's index that you want to apply or type in NONE if your expected CA is not in the list:
(Example input: 0)

After choosing the CA, NDNCERT client will ask your email address for this certificate request.

***************************************
Step 2: Please provide information for name assignment
Please input: email
(Example input: [email protected])

Enter your email address to continue. Inferred from email address, if your organization have a site CA, NDNCERT client will redirect you to your site CA. Then your site CA will send a verification code to your supplied email address.
```
You will be redirected to CA: /ndn/edu/ucla
You are assigned to name: /ndn/edu/ucla/cs/tianyuan
```
If your organization does not have a site CA or the supplied email is a non-testbed institutional address (e.g., [email protected]), Testbed Root CA will assign a name for you.

Enter your certificate validity period.

***************************************
Step 3: Please type in your expected validity period of your certificate. Type the number of hours (168 for week, 730 for month, 8760 for year). The CA may reject your application if your expected period is too long. The maximum validity period allowed by this CA is 360 hours.
(Example input: 80)

(Optional) Key Selection: If local keychain already has a key with same name, you need to select whether you want to certify an existing key, or creating a new key under the same name and certify it.

Step 4: KEY SELECTION
> Index: 0
>> Key Name:  +->* /ndn/edu/ucla/cs/tianyuan/KEY/%BE%B1cqk%25%3D%20
Please type in the key's index that you want to certify or type in NEW if you want to certify a new key:
(Example input: 0)

Enter the verification code: Check your email and paste the secret code into the terminal when it asks.

***************************************
Step 4: Please provide parameters used for Identity Verification Challenge
Please input your verification code
(Example input: 456982)

If verification succeeds, the certificate will be issued and installed into your local ndnsec keychain, you can view all existing certificates by running:

~$ ndnsec list -c
  (Example certificate 1)
  * /ndn/edu/ucla/tianyuan
	+->* /ndn/edu/ucla/tianyuan/KEY/%3E%F7%A5%5B%A2%16%F4h
		+->* /ndn/edu/ucla/tianyuan/KEY/%3E%F7%A5%5B%A2%16%F4h/NDNCERT/v=1638271730898
  (Example certificate 2) 
  * /ndn/com/gmail/tianyuan
	+->* /ndn/com/gmail/tianyuan/KEY/%D5%3F%91%91%E4u4%A3
		+->* /ndn/com/gmail/tianyuan/KEY/%D5%3F%91%91%E4u4%A3/NDNCERT/v=1639647763098

How it works and what to expect

Overview

NDN Testbed Root CA /ndn/CA issues certificate to each site CA (e.g., /ndn/edu/ucla/CA). Each site CA serves as local trust anchor and is able to issue certificate to requesters who control email addresses belong to that organization. If the email that the certificate requester controls doesn't not belong to any existing organizations of NDN Testbed, Root CA will handle the certificate signing request and issue a certificate to client.

							 NDN Testbed Root CA
							       /ndn/CA
									  |
									  |
   ---------------------------------------------------------------------------------
   |                     |                   |                    |                ....    
 Site CA               Site CA            Site CA              Site CA
/ndn/edu/ucla/CA   /ndn/edu/arizona/CA  /ndn/edu/memphis/CA    /ndn/edu/wustl/CA

Probing for site CA and redirecting

The NDN Testbed Root CA uses the email address to infer the certificate namespace.

[email protected] -> /ndn/edu/ucla/tom
[email protected] -> /ndn/edu/wustl/bob
[email protected] -> /ndn/edu/umich/alice
[email protected] -> /ndn/com/gmail/tianyuan

Based on the certificate namespace, Root CA redirect the requester to the corresponding site CA by returning the site CA certificate name.

[email protected] -> redirect to --> /ndn/edu/ucla/CA 
[email protected] -> redirect to --> /ndn/edu/wustl/CA
[email protected] -> redirect to --> /ndn/edu/umich/CA
[email protected] -> directly handled by --> /ndn/CA

If the requester provides a non-institutional address or the address of the institution is not part of the NDN Testbed, Root CA will handle this certificate request, verify the requester's identity, then issue certificate.

tianyuan129/ObtainingCert.md