# TPM IDevID Enrollment Details

## Enroll Payload IAK certificate

**ENDPOINT**: $ACA_URL/enroll/request

The json payload necesary to enroll a TPM within the ACA is:

{
  "ak-pub": "${AK_PUB}",
  "ak-name": "${AK_NAME}",
  "ek-cert": "${EK_CERT}",
  "ek-pub": "${EK_PUB}"
}

Example:

curl -L -k --request POST \
    --url $ACA_URL/enroll/request/ \
    --header 'content-type: application/json' \
    --data '{
    "ak-pub": "${AK_PUB}",
    "ak-name": "${AK_NAME}",
    "ek-cert": "${EK_CERT}",
    "ek-pub": "${EK_PUB}"
}'

This generate and ACA signed AK Certificate encrypted with this two important extensions:

X509v3 Subject Alternative Name: 
    URI:http://localhost:12368/certs/5df298293132e008cebde67e.crt

1.3.6.1.4.1.54621.100.0:
    000be18772c80e28bd7838d7a1443ed12d715d80048805ac716452ce8d2e0596533c

The **Subject Alternative Name** Define and URL where you can download the certificate Again.

and the **1.3.6.1.4.1.54621.100.0** define the Ak public Key name. This will be use to name the device in pantahub later

## ACA Signed IAK Certificate

For this job the ACA server does several steps:

1. Validate the AK Public key and the AK name from the payload.
2. Validate that the EK cert public key and the AK public key are the same
3. Validate the EK cert agains a set of trusted Root certificates from TPM manufactor company (for now INTEL NUVOTON)
4. Using the TPM simulator on the Server and the AK and EK the ACA server creates an tpm2_credentials
5. ACA server save the certificate on data base and encrypt the certificate using the tpm credentials
6. The server sent back to the DEVICE the Payload with the encrypted certificate the credential and the IV used by the encrypt algoritm
7. The device take this and use tpm2_activecredential to get the secret to be able to decrypt the certificate

Payload

{
    "certificate": "Encrypted certificate base64 encoded",
    "credential": "tpm credential base64 encoded",
    "iv": "keu for the encrypted algoritm"
}

## Send IDevID.csr

**ENDPOINT:** ${ACA_URL}/register

Create a IDevID with this extentions

* **PH_OWNERPRN_OID**: 1.3.6.1.4.1.54621.100.1
* **PH_HMAC_OID**: 1.3.6.1.4.1.54621.100.2
* **PH_TOKEN_ID_OID**: 1.3.6.1.4.1.54621.100.3
* **PH_CERTIFY_ATTEST_OID**: 1.3.6.1.4.1.54621.100.4
* **PH_CERTIFY_SIG_OID**: 1.3.6.1.4.1.54621.100.5

PH_CERTIFY_ATTEST_OID and PH_CERTIFY_SIG_OID a the HEX encode version of the tpm2_certify of he IDEV.PUB.

tpm2_certify -C ${IDEVID_HANDLE} \
	-c ${AK_HANDLE} \
	-g sha256 \
	-o idevid.tpm2certify.attest \
	-s idevid.tpm2certify.sig \
	-f tss

PH_OWNERPRN_OID is the OWNER PRN in pantahub
PH_HMAC_OID is a signature of the idevid pub name using the TOKEN AUTO JOIN given by pantahub
PH_TOKEN_ID_OID is the tokenn id created in pantahub

Device start a request for a IDevID certificate using a JSON request.

The request need the this headers

* **PhTpm2ClientIDevPub**: ${idevidpub_hex}
* **PhTpm2ClientIAKCert**: ${akcert_hex}
* **PhTpm2ClientIAKPub**: ${akpub_hex}

and the payload should be:

{
    "csr" : "'idevid.csr base64 encoded"
}

## Validate IDevID.csr

The ACA validate the IDevID csr with all this validation:

1. Check the csr signature
2. Validate the IDevID csr public key and the idevid public key
3. Validate the verify signature in the certificate

## Validate Device Ownership

Send a request to Pantahub base API `${PANTAHUB_API_URL}/auth/signature/verify`

Payload

{
	"token-id": "TOKEN ID",
	"owner": "OWNER PRN",
	"idevid-name": "IDEVID PUB NAME",
	"signature": "HMAC SIGNATURE" // PH_HMAC_OID
}

Pantahub will validaate if the signature is correct and the token is for the owner.

## Ownership is valid

The server will response with 200 ok if the ownership is valid and error if not.

## New Device Request With IDevID

After all the validations the ACA sends a new device request to pantahub API

For that sends a request to the endpoint `` With this payload

{
    "csr": "IDevID certificate CSR",
    "name": "IDevID pub name (TPM name)",
	"device-name": "AK pub name (TPM name)"
}

## Certificate Request With CSR

Validates the certificate signature and the HMAC, then creates a certificate request again the CA using the EJBCA Web Services (SOAP API).

The minimal request payload for that will be:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:certificateRequest xmlns:ns2="http://ws.protocol.core.ejbca.org/">
            <arg0>
                <caName>PantacorCA</caName>
                <certificateProfileName>IDEVID</certificateProfileName>
                <clearPwd>false</clearPwd>
                <endEntityProfileName>pantahub</endEntityProfileName>
                <keyRecoverable>false</keyRecoverable>
                <password>secret</password>
                <sendNotification>false</sendNotification>
                <status>0</status>
                <subjectDN>subject</subjectDN>
                <username>username</username>
            </arg0>
            <arg1>PLAIN_TEXT_PEM</arg1>
            <arg2>0</arg2>
            <arg4>CERTIFICATE</arg4>
        </ns2:certificateRequest>
    </soap:Body>
</soap:Envelope>

## Certificate Response DER on BASE64

The EJBCA server will response with a requestCertificate Payload, that include the certificate in der format base64 encoded,

## Create Device in DB - if not exists

If the device doesn't exist created if is already there created a updated with the new idevid signed as meta data for the device.

## Signed IDevID and Device Payload

Send back to the ACA the device payload and the certificate in der format with base64 decoded.

{
    "crt": "IDevID base64 decoded (DER format)",
    "device": {
      "id": "",
      "prn": "",
      "nick": "",
      "owner": "",
      "time-created" ": "",
      "time-modified" ": "",
      "public": "",
      "user-meta": "",
      "device-meta": "",
      "garbage": ""
    }
}

## IDevID certificate (serialNumber == DeviceID)

The ACA sends back to the device the crt and the device saved in the NV memory of the TPM, in the address:

`0x01C90000`

This certificate haas been signed by the CA and can be trusted to be used as tls client certificate.