Introduction

Privacy CA defines a REST-style API designed as a straighforward interface to the TCG-defined Privacy CA functionality. It provides functions to retrieve Privacy CA certificates, and to request new Attestation Identity Key certificates.

Retrieving Privacy CA Certificates

Retrieving certificates is performed with an HTTP GET operation to one of the following URLs:

http://www.privacyca.com/api/pca/root
http://www.privacyca.com/api/pca/level0
http://www.privacyca.com/api/pca/level1
http://www.privacyca.com/api/pca/level2

These requests return respectively the root, level0, level1, or level2 Privacy CA certificate.

Optionally a parameter may be added to control the format of the returned certificate.

?ResponseFormat=binary
?ResponseFormat=PEM
?ResponseFormat=XML

binary is the default if no ResponseFormat is specified, and returns the data in raw (not base64 encoded) binary form. PEM format is base64 encoded suitable for parsing by, for example, the OpenSSL function PEM_read_X509 (). XML format is of the following form:

<?xml version="1.0"?>
<Certificate encoding="base64">
 (base64 encoded certificate data)
</Certificate>

Requesting Attestation Identity Key Certificates

Providing AIK certificates is the main purpose of Privacy CA. The API is designed to be accessed with an HTTP POST operation to one of the level0-level2 URLs above:

http://www.privacyca.com/api/pca/level0
http://www.privacyca.com/api/pca/level1
http://www.privacyca.com/api/pca/level2

The content of the POST operation must be a TCG-defined TCPA_IDENTITY_REQ blob. (A blob is the TCG's serialized version of the data structure, with arrays positioned inline within the struct, each preceded in the struct definition by its size in bytes.) This is the data format that is returned from the TCG Software Stack (TSS) function Tspi_TPM_CollateIdentityRequest (). This data must be transmitted in binary format.

On success, data is returned by default in binary form. The format is 256 bytes of "asymmetric" encrypted data (encrypted to the TPM Endorsement Key) followed by the remaining variable-length "symmetric" encrypted data, encrypted with AES-CBC to the key embedded in the asymmetric part. These two blocks of data are suitable for input to the TSS function Tspi_TPM_ActivateIdentity (). The output of this TSS function will be the AIK certificate issued by Privacy CA, in binary form.

If desired, a parameter may be added to the URL as with certificate retrieval to change the format of the returned data:

?ResponseFormat=binary
?ResponseFormat=PEM
?ResponseFormat=XML

The default is binary as described above. PEM is supported but is not very useful: it merely base64 encodes the binary data and surrounds it with "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" markers.

In the case of XML, the asymmetric and symmetric encrypted parts are returned in separate XML elements, base64 encoded, with the following structure:

<?xml version="1.0"?>
<EncryptedAIKCertificate>
  <AsymmetricEncryptedPart encoding="base64">
    (base64 encoded asymmetric data)
  </AsymmetricEncryptedPart>
  <SymmetricEncryptedPart encoding="base64">
    (base64 encoded symmetric data)
  </SymmetricEncryptedPart>
</EncryptedAIKCertificate>

Sample code

Sample C/C++ code based on the Trousers TPM Software Stack for Linux systems, and the libcurl library for network communication, is available at the link. Compile with:

gcc -o identity identity.c -lcurl -ltspi

Add -DREALEK if you have an Endorsement Certificate for your TPM and have configured Trousers to use it. (See the Trousers documentation for how to set this up.) This will cause the sample program to request level 1 certification. Otherwise the default is to create a placeholder Endorsement Certificate and request a level 0 AIK certificate, for testing only.