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/level2These 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/level2The content of the POST operation must be a TCG-defined TPM_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.
The asymmetric encrypted data portion is a TCG TPM_ASYM_CA_CONTENTS structure, RSA-encrypted to the TPM Endorsement Key, with OAEP padding. The symmetric encrypted portion is a TPM_SYM_CA_ATTESTATION structure, which includes the AES-encrypted AIK certificate. The encryption is in CBC mode, with PKCS-5 padding. The IV will either appear within the TPM_SYMMETRIC_KEY_PARMS struct which is part of the TPM_SYM_CA_ATTESTATION, or else it will be the 16 bytes at the front of the CBC encrypted portion. The Trousers open-source TSS stack presently uses the latter convention. Privacy CA will accept either placement for the IV in the request, and in its response will copy the method used by the requestor.
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=XMLThe 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>
See the Source Code page for sample client code that can commuicate with Privacy CA.