API Specification for PCCS¶

Get PCK Certificate¶

Retrieve the X.509 SGX Provisioning Certification Key (PCK) certificate for an SGX-enabled platform at a specified TCB level.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/pckcert
GET https://pccs-server-url:8081/sgx/certification/v4/pckcert

Request¶

Name	Type	Request Type	Required	Pattern	Description
`encrypted_ppid`	String	Query	False	`^[0-9a-fA-F]{512}$`	Base16-encoded Encrypted_PPID
`cpusvn`	String	Query	True	`^[0-9a-fA-F]{32}$`	Base16-encoded CPUSVN value
`pcesvn`	String	Query	True	`^[0-9a-fA-F]{4}$`	Base16-encoded PCESVN value
`pceid`	String	Query	True	`^[0-9a-fA-F]{4}$`	Base16-encoded PCEID value
`qeid`	String	Query	True	`^[0-9a-fA-F]{32}$`	Base16-encoded QEID value

Table 1.

Response¶

PckCert (x-pem-file) - PEM-encoded representation of Intel® SGX PCK Certificate in case of success (200 HTTP status code)

Status codes¶

Code	Model	Headers	Description
200	`PckCert`	`SGX-PCK-Certificate-Issuer-Chain` (String): URL-encoded Issuer Certificate chain for SGX PCK Certificate in PEM format. It consists of SGX Intermediate CA Certificate (Processor CA) followed by SGX Root CA Certificate `SGX-TCBm` (String): Hex-encoded string representation of concatenation of CPUSVN (16 bytes) and PCESVN (2 bytes) as returned in corresponding SGX PCK Certificate	Successfully completed
400	-	-	Invalid request parameters
404	-	-	No cache data for this platform
461	-	-	The platform was not found in the cache.
462	-	-	Certificates are not available for certain TCBs.
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS.

Table 2.

Process¶

Checks request parameters upon client request and returns the 400 error if any parameter is invalid.
Gets the platform object from platforms table with the input {qeid, pceid} as key (see platformsDao.getPlatform).
If the platform was found, which means the platform was already cached:
1. Queries PCK Certificate for this platform and PCK Certificate issuer chain from cache db with the input {qeid, cpusvn, pcesvn, pceid} as key (see pckcertDao.getCert).
2. Goes to step 4.
If collateral was not retrieved in step 3:
1. If platform is not cached
  1. If cache fill mode is LAZY:
    1. Gets all PCK Certificates for this platform from PCS v4 API with {encrypted_ppid, pceid} for single-package platform, or {platform_manifest, pceid} for multi-package platform.
    2. Parses the first cert (X.509) in the array to get FMSPC and ca type (processor or platform).
    3. Contacts PCS again to get SGX TCB Info as well as TDX TCB Info (if available) with the above FMSPC value.
    4. Gets the best cert with PCKCertSelectionTool using {cpusvn, pcesvn, pceid, SGX TCB Info, PCK Certificates}.
    5. Updates the cache tables:
      - platforms table: calls platformsDao.upsertPlatform to update the platforms table;
      - pck_cert table: first calls pckcertDao.deleteCerts to delete old records associated with the {qeid, pceid}, then for each certificate fetched in i., calls pckcertDao.upsertPckCert to insert the certificate;
      - platform_tcbs table: for the new raw TCB in the request and all old cached raw TCBs, inserts/updates the new TCB mapping by calling platformTcbsDao.upsertPlatformTcbs;
      - fmspc_tcbs table: calls fmspcTcbDao.upsertFmspcTcb to update fmspc_tcbs table for both SGX TCB Info and TDX TCB Info (if available);
      - pck_certchain table: calls pckCertchainDao.upsertPckCertchain to update pck_certchain table with the ca type in step ii.;
      - pcs_certificates table: calls pcsCertificatesDao.upsertPckCertificateIssuerChain to update PCK Certificate issuer chain with the ca type in step ii.
    6. Returns the PCK Certificate in the response body and PCK Certificate issuer chain in the response header.
    7. Responds with the 200 status code.
    8. Else return 461 (not found) error
  2. Else
    1. Gets PCK Certificates from cache DB with {qeid, pceid} (see pckcertDao.getCerts).
    2. Gets TCB Info from cache DB with the FMSPC of the platform (see fmspcTcbDao.getTcbInfo).
    3. Runs PCK Certificate selection tool with the raw TCB, PCK Certificates, and SGX TCB Info.
    4. Gets PCK Certificate issuer chain from cache DB (see pckCertchainDao.getPckCertChain).
    5. If success, returns the "best" certificate and certificate chain, else returns the 404 error.
    6. Updates platform_tcbs table for this raw TCB (see platformTcbsDao.upsertPlatformTcbs).
2. Else
  1. Returns the PCK Certificate in the response body and PCK Certificate issuer chain in the response header.

Get PCK Certificate CRL¶

Retrieve the X.509 Certificate Revocation List with the revoked Intel® SGX PCK Certificates. The CRL is issued either by Intel® SGX Platform CA or by Intel® SGX Processor CA.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/pckcrl
GET https://pccs-server-url:8081/sgx/certification/v4/pckcrl

Request¶

Name	Type	Request Type	Required	Pattern	Description
`ca`	String	Query	True	Enum: `processor`, `platform`	Identifier of the CA that issued the requested CRL
`encoding`	String	Query	True	Enum: `der`	Optional identifier of the encoding for the requested CRL. If the parameter is not provided, HEX-encoded DER is assumed. If `der` is provided, raw DER format CRL will be returned.

Table 3.

Response¶

PckCrl (PKIX-CRL) – DER or HEX-encoded DER representation of SGX Platform CA CRL or SGX Processor CA CRL in case of success.

Status codes¶

Code	Model	Headers	Description
200	`PckCrl`	`SGX-PCK-CRL-Issuer-Chain`: Issuer Certificate chain for SGX PCK CRL. It consists of SGX Intermediate CA Certificate (Processor CA) followed by SGX Root CA Certificate	Successfully completed
400	-	-	Invalid request parameters
404	-	-	PCK CRL cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS.

Table 4.

Process¶

Checks request parameters and returns the 400 error if any input parameter is invalid
Queries PCK CRL along with CRL issuer chain with the key {ca} (see pckcrlDao.GetPckCrl).
1. If record exists:
  1. Returns pck_crl in the response body and the PCK CRL certificate chain in the response header.
  2. Responds with the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY
    1. Gets PCK CRL and PCK CRL certificate chain from PCS v4 API with {ca}. If failed, returns the 404 error.
    2. Updates pck_crl and pcs_certificates table:
      1. Calls pckcrlDao.upsertPckCrl(ca, crl), crl is a response body.
      2. Calls pcsCertificatesDao.upsertPckCrlCertchain with {ca} and retrieved PCK CRL certificate chain.
    3. Returns PCK CRL in the response body and PCK CRL certificate chain in the response header.
    4. Responds with the 200 status code.

Get TCB Info¶

Retrieve Intel® SGX or TDX TCB Information for the given FMSPC

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/tcb
GET https://pccs-server-url:8081/sgx/certification/v4/tcb
GET https://pccs-server-url:8081/tdx/certification/v4/tcb

Request¶

Name	Type	Request Type	Required	Pattern	Description
`fmspc`	String	Query	True	`^[0-9a-fA-F]{12}`	Base16-encoded FMSPC value
`update`	String	Query	False	Enum: `early`, `standard`	Type of update to TCB Info. If not provided `standard` is assumed. `early` indicates an early access to updated TCB Info provided as part of a TCB recovery event (commonly the day of public disclosure of the items in scope) `standard` indicates standard access to updated TCB Info provided as part of a TCB recovery event (commonly approximately 6 weeks after public disclosure of the items in scope)

Table 5.

Response¶

TcbInfo (JSON) - Intel® SGX TCB Info encoded as JSON string in case of success

Status codes¶

Code	Model	Headers	Description
200	`TcbInfo`	`SGX-TCB-Info-Issuer-Chain` (v3) or `TCB-Info-Issuer-Chain` (v4): Issuer Certificate chain for Intel® SGX TCB Info. It consists of Intel® TCB Signing Certificate followed by Root CA Certificate	Successfully completed
400	-	-	Invalid request parameters
404	-	-	TCB Information for provided `{fmspc}` cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 6.

Process¶

Checks request parameters and returns the 400 error if any parameter is invalid.
Queries TCB Info along with Intel® TCB Info issuer chain with key {type, fmspc, version, update_type} (see fmspcTcbDao. getTcbInfo). Type can be 0:SGX or 1:TDX.
1. If record exists:
  1. Returns tcb_info in the response body and the issuer chain in the response header.
  2. Responds with the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY
    1. Gets TCB Info from PCS with {type, fmspc, version}. If failed, return the 404 error.
      
      If type is 0:SGX, send request to /sgx/ url, else if type is 1:TDX, send request to /tdx/ url. Version will be translated to either /v3/ or /v4/. 2. Updates fmspc_tcbs and pcs_certificates: - fmspc_tcbs table: calls fmspcTcbDao.upsertFmspcTcb; - pcs_certificates table: calls pcsCertificatesDao.upsertTcbInfoIssuerChain. 3. Returns TCB Info in the response body and TCB Info certificate chain in the response header. 4. Responds with the 200 status code.

Get Intel's QE Identity¶

Retrieve the Quote Identity information for the Quoting Enclave issued by Intel.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/qe/identity
GET https://pccs-server-url:8081/sgx/certification/v4/qe/identity

Request¶

Name	Type	Request Type	Required	Pattern	Description
`update`	String	Query	False	Enum: `early`, `standard`	Type of update to QE Identity. If not provided `standard` is assumed. `early` indicates an early access to updated QE Identity provided as part of a TCB recovery event (commonly the day of public disclosure of the items in scope) `standard` indicates standard access to updated QE Identity provided as part of a TCB recovery event (commonly approximately 6 weeks after public disclosure of the items in scope)

Table 7.

Response¶

QEIdentity (JSON) - QE Identity data structure encoded as JSON string in case of success

Status codes¶

Code	Model	Headers	Description
200	`QEIdentity`	`SGX-Enclave-Identity-Issuer-Chain`: Issuer Certificate chain for Intel® SGX QE Identity. It consists of Intel® SGX TCB Signing Certificate followed by Intel® SGX Root CA Certificate	Successfully completed
404	-	-	QE identity information cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 8.

Process¶

Queries QE identity along with SGX Enclave identity issuer chain (see identityDao. getIdentity).
1. If record exists:
  1. Returns qe_identity in the response body and the QE certificate chain in the response header.
  2. Returns the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY:
    1. Gets QE identity from the corresponding API version of PCS. If failed, returns the 404 error.
    2. Updates identities and pcs_certificates table:
      - identities table: calls identityDao.upsertIdentity.
      - pcs_certificates table: calls pcsCertificatesDao.upsertIdentityIssuerChain.
    3. Returns qe_identity in the response body and the QE certificate chain in the response header.
    4. Returns the 200 status code.

Get Intel's QvE Identity¶

Retrieve Identity information for Quote Verification Enclave issued by Intel.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/qve/identity
GET https://pccs-server-url:8081/sgx/certification/v4/qve/identity

Request¶

Name	Type	Request Type	Required	Pattern	Description
`update`	String	Query	False	Enum: `early`, `standard`	Type of update to QVE Identity. If not provided `standard` is assumed. `early` indicates an early access to updated QVE Identity provided as part of a TCB recovery event (commonly the day of public disclosure of the items in scope) `standard` indicates standard access to updated QVE Identity provided as part of a TCB recovery event (commonly approximately 6 weeks after public disclosure of the items in scope)

Table 9.

Response¶

QvEIdentity (JSON) - QvE Identity data structure encoded as JSON string in case of success

Status codes¶

Code	Model	Headers	Description
200	`QvEIdentity`	`SGX-Enclave-Identity-Issuer-Chain`: Issuer Certificate chain for Intel® SGX QvE Identity. It consists of Intel® SGX TCB Signing Certificate followed by Intel® SGX Root CA Certificate	Successfully completed
404	-	-	QvE identity information cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 10.

Process¶

Queries QvE identity along with Intel® SGX Enclave identity issuer chain (see identityDao.getEnclaveIdentity).
1. If record exists:
  1. Returns qve_identity in the response body and QVE certificate chain in the response header.
  2. Returns the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY:
    1. Gets QvE identity from the corresponding API version of PCS . If failed, returns the 404 error.
    2. Updates identities and pcs_certificates table:
      - identities table: calls identityDao.upsertIdentity;
      - pcs_certificates table: calls pcsCertificatesDao.upsertIdentityIssuerChain.
    3. Returns qve_identity in the response body and QVE certificate chain in the response header.
    4. Returns the 200 status code.

Get Intel's TD QE Identity¶

Retrieve Identity information for TD Quote Enclave issued by Intel.

Endpoint(s)¶

GET https://pccs-server-url:8081/tdx/certification/v4/qe/identity

Request¶

Name	Type	Request Type	Required	Pattern	Description
`update`	String	Query	False	Enum: `early`, `standard`	Type of update to QE Identity. If not provided `standard` is assumed. `early` indicates an early access to updated QE Identity provided as part of a TCB recovery event (commonly the day of public disclosure of the items in scope) `standard` indicates standard access to updated QE Identity provided as part of a TCB recovery event (commonly approximately 6 weeks after public disclosure of the items in scope)

Table 11.

Response¶

TDQEIdentity (JSON) - TDQE Identity data structure encoded as JSON string in case of success

Status codes¶

Code	Model	Headers	Description
200	`TDQEIdentity`	`SGX-Enclave-Identity-Issuer-Chain`: Issuer Certificate chain for Intel® SGX TDQE Identity. It consists of Intel® SGX TCB Signing Certificate followed by Intel® SGX Root CA Certificate	Successfully completed
404	-	-	TDQE identity information cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 12.

Process¶

Queries TDQE identity along with Intel® SGX Enclave identity issuer chain (see identityDao.getIdentity).
1. If record exists:
  1. Returns tdqe_identity in the response body and TDQE certificate chain in the response header.
  2. Returns the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY:
    1. Gets TDQE identity from PCS v4 API. If failed, returns the 404 error.
    2. Updates identities and pcs_certificates table:
      - identities table: calls identityDao.upsertEnclaveIdentity;
      - pcs_certificates table: calls pcsCertificatesDao.upsertIdentityIssuerChain.
    3. Returns tdqe_identity in the response body and TDQE certificate chain in the response header.
    4. Returns the 200 status code.

Get Root CA CRL¶

Retrieve Root CA CRL.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/rootcacrl
GET https://pccs-server-url:8081/sgx/certification/v4/rootcacrl

Request¶

No parameters

Response¶

RootCACRL – The HEX-encoded DER representation of Root CA CRL in case of success

Status codes¶

Code	Model	Headers	Description
200	`RootCACRL`	-	Successfully completed
404	-	-	Root CA CRL cannot be found
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 13.

Process¶

Queries root CA record(id=1) from pcs_certificates table (see pcsCertificatesDao.getCertificateById)
1. If the root CA record exists and the CRL field is not empty:
  1. Returns the CRL in the response body.
  2. Returns the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, return the 404 error to client
  2. If cache fill mode is LAZY:
    1. Calls PCS v4 API to get QE identity and extracts the root CA from the certificate chain in response header. If failed, returns empty body.
    2. Parses the root CA to get cdp uri
    3. Contacts the cdp uri to get root CA CRL. If failed, returns the 500 error.
    4. Updates pcs_certificates table with root CA and CRL(see pcsCertificatesDao.upsertPcsCertificates)
    5. Returns the root CA CRL in the response body (hex-encoded)
    6. Returns the 200 status code.

Post Platforms IDs¶

This API stores platform identity information provided in the request. This API is restricted to users with the access to the user-token.

Endpoint(s)¶

POST https://pccs-server-url:8081/sgx/certification/v3/platforms
POST https://pccs-server-url:8081/sgx/certification/v4/platforms

Request¶

Parameters¶

Name	Type	Request Type	Required	Pattern	Description
`user-token`	String	Header	True	String	PCCS user token which provides access to this API.

Table 14.

Body¶

{
    "qe_id": "Base16-encoded QE-ID value",
    "pce_id": "Base16-encoded PCE-ID value",
    "cpu_svn": "Base16-encoded CPUSVN value",
    "pce_svn": "Base16-encoded PCESVN value",
    "enc_ppid": "Base16-encoded PPID encrypted with PPIDEK",
    "platform_manifest": "Base16-encoded platform manifest value"
}

Response¶

Status codes¶

Code	Model	Headers	Description
200	-	-	Successfully completed (entry updated)
201	-	-	Successfully completed (entry created)
400	-	-	Invalid request parameters
401	-	-	Authentication failed
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS

Table 15.

Process¶

Validates the user token(calculate sha-512 hash of the token and compare the hash value with UserTokenHash in the configuration file). If validation fails, returns the 401 error.
Validates the request body with pre-defined JSON schema. If the validation fails, returns the 400 error to client.
Checks cache status for this platform.
1. Gets the platform object from platforms table based on the provided {qeid, pceid} (see platformsDao.getPlatform) .
2. If the platform_manifest in the request does not match the one in the cache (Note: Treat the absence of the platform_manifest in the request while there is a PLATFORM_MANIFEST in the cache as a match):
  1. Updates platforms table of the cache with the new manifest.
  2. Sets cache status to FALSE.
3. Else if platform_manifest matches:
  1. Queries PCK Certificate from cache db with {qeid, cpusvn, pcesvn, pceid} to check whether PCK Certificate for this platform is cached (see pckcertDao.getCert).
  2. If found, sets cache status to TRUE.
  3. Else: sets cache status to FALSE.
If cache fill mode is OFFLINE:
1. If cache status is FALSE:
  1. Adds the platform registration data to platforms_registered table and returns SUCCESS (call platformsRegDao.registerPlatform with state=NEW).
Else:
1. If cache status is FALSE:
  1. If cache fill mode is REQ, adds the platform registration data to platforms_registered table (calls platformsRegDao.registerPlatform with state=NEW)
  2. Uses the same logic in section Get PCK Certificate to get PCK Certificate from PCS.
  3. If cache fill mode is REQ, deletes the platform registration data from platforms_registered table (calls platformsRegDao.registerPlatform with state=DELETED).
2. Checks quote verification collateral (PCK CRL, QE identity, QvE identity, Root CA CRL). If not cached, retrieves them from PCS and fills the cache

Get Platform IDs¶

Administrators use this API to retrieve the platform ID information for registered platforms or cached platforms. This API is restricted to users with the access to the admin-token.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/platforms
GET https://pccs-server-url:8081/sgx/certification/v4/platforms

Request¶

Name	Type	Request Type	Required	Pattern	Description
`admin-token`	String	Header	True	String	The administrator token required to perform the request.
`fmspc`	String	Query	False	[fmspc1,fmspc2, …]	FMSPC array.

Table 16.

Response¶

An array of data structures defined below encoded as JSON in case of success (200 HTTP status code). When the Queue Status is 0, information for all registered platforms is retrieved.

Response format:

[
    {
        "qe_id": "xxxx",
        "pce_id": "xxxx",
        "cpu_svn": "xxxx",
        "pce_svn": "xxxx",
        "enc_ppid": "xxxx",
        "platform_manifest": "xxxx"
    },
    {}
]

Empty body otherwise.

Status codes¶

Code	Model	Headers	Description
200	See "response format" above	-	Successfully completed
400	-	-	Invalid request parameters
401	-	-	Authentication failed
500	-	-	Internal server error occurred

Table 17.

Process¶

Checks if request parameters include fmspc.
1. If fmspc is not included (will return platforms in registration queue):
  1. Gets the registration platforms list from cache db (see platformsRegDao.findRegisteredPlatforms).
2. If fmspc is provided ():
  1. The format should be [fmspc1, fmspc2, …]. If not, returns the 400 error.
  2. Gets cached platforms, whose fmspc is in the list (see platformsDao.getCachedPlatformsByFmspc).
Returns the JSON list in response body and platforms count in response header.

Put Platform Collateral to Cache¶

Administrators use this API to push the platform collateral for collected platforms from the PCS into the caching service. This API is restricted to users with the access to the admin-token.

Endpoint(s)¶

PUT https://pccs-server-url:8081/sgx/certification/v3/platformcollateral
PUT https://pccs-server-url:8081/sgx/certification/v4/platformcollateral

Request¶

Parameters¶

Name	Type	Request Type	Required	Pattern	Description
`Content-Type`	String	Header	True	`application/json`	MIME type of the request body.
`admin-token`	String	Header	True	String	The administrator token required to perform the request.
`platform_count`	Integer	Query	True	`^[1-9][0-9]*$`	Number of platforms in the PCK Certificate array.

Table 18.

Body¶

A JSON object includes all the collaterals for the registered platforms.

Body format:

{
    "platforms": [
        {
            "qe_id": "xxxx",
            "pce_id": "xxxx",
            "cpu_svn": "xxxx",
            "pce_svn": "xxxx",
            "enc_ppid": "xxxx",
            "platform_manifest": "xxxx"
        },
        {}
    ],
    "collaterals": {
        "version": "4",
        "pck_certs": [
            {
                "qe_id": "string",
                "pce_id": "string",
                "enc_ppid": "string",
                "platform_manifest": "string",
                "certs": []
            },
            {}
        ],
        "tcbinfos": [
            {
                "fmspc": "string",
                "sgx_tcbinfo": {},
                "tdx_tcbinfo": {}
            },
            {}
        ],
        "pckcacrl": "string",
        "qeidentity": "string",
        "tdqeidentity": "string",
        "qveidentity": "string",
        "certificates": {
            "SGX-PCK-Certificate-Issuer-Chain": "string",
            "TCB-Info-Issuer-Chain": "string",
            "SGX-Enclave-Identity-Issuer-Chain": "string"
        },
        "rootcacrl": "string"
    }
}

Response¶

Status codes¶

Code	Model	Headers	Description
200	-	-	Successfully completed
400	-	-	Invalid request parameters
401	-	-	Authentication failed
500	-	-	Internal server error occurred

Table 19.

Process¶

Validates the admin token(calculate sha-512 hash of the token and compare the hash value with AdminTokenHash in the configuration file). If the validation fails, returns the 401 error to client.
Validates the request body with pre-defined collateral schema. If the validation fails, returns the 400 error to client.
For each platform in the list:
1. Deletes old PCK Certificates for this platform (pckcertDao.deleteCerts).
2. Inserts all PCK Certificates for this platform to pck_cert table(pckcertDao.upsertPckCert).
3. Merges the raw TCBs in the request and cached platform_tcbs table to get a full raw tcb list.
4. Extracts fmspc and ca value from any leaf cert (use the first cert for convenience).
5. Finds the TCB Info for this fmspc from the TCBInfos in the request.
6. For each raw TCB in the raw tcb list:
  1. Gets the best cert with PCKCertSelectionTool using {cpusvn, pcesvn, pceid, TCB Info, PCK Certificates}.
  2. Updates platform_tcbs tables.
7. Updates platforms table.
For each TCB Info in the list:
1. Updates fmspc_tcbs table.
Updates pck_crl, qe_identities, qve_identities, pck_certchain if present.
Updates pcs_certificates and root CA CRL if present.

Cache Data Refresh¶

Refresh through HTTP Request¶

This API is for maintenance only. Refresh expired {TCB Info, PCK CRLs, QE Identity, QvE Identity, Root CA CRL} or {PCK Certificates} in cache DB. This API is restricted to users with the access to the admin-token.

Note

This API can be used when configured for with REQ or LAZY cache fill mode. It is not supported for OFFLINE cache fill mode.

Endpoint(s)¶

[Deprecated] GET https://pccs-server-url:8081/sgx/certification/v3/refresh
POST https://pccs-server-url:8081/sgx/certification/v3/refresh
POST https://pccs-server-url:8081/sgx/certification/v4/refresh

Request¶

Name	Type	Request Type	Required	Pattern	Description
`type`	String	Query	False	`certs`	Refresh type. If not provided, TCB Info, PCK CRLs, QE Identity, TDQE identity (v4 only) and QVE Identity will be refreshed. If `type = certs` and no fmspc is specified, all cached PCK Certificates will be refreshed.
`admin-token`	String	Header	True	String	The administrator token required to perform the request.
`fmspc`	String	Query	False	FMSPc1, FMSPC2, …, FMSPcn	Used with "type=certs". If fmspc is provided, refresh only certs for those FMSPCs.

Table 20.

Response¶

Based on the result, returns one of the following status codes.

Status codes¶

Code	Model	Headers	Description
200	-	-	Successfully completed
401	-	-	Operation failed
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS
503	-	-	Server is currently unable to process the request

Table 21.

Process¶

Default (type is not specified)¶

For each record in pck_crls table, contacts PCS service to get the latest PCK CRL and PCK CRL certificate chain, then updates the pck_crls table if necessary.

For each record in fmspc_tcbs table, contacts PCS service to get the latest TCB Info, then updates the fmspc_tcbs table if necessary.

For each record in identities table, contacts PCS service to get the latest QE Identity, QvE Identity and TDQE identity (v4 only) then updates the identities table if necessary.

Refresh root CA CRL: Get the root CA from pcs_certificates table, and parse it to get the CRL cdp uri, then contacts PCS service to get the CRL and update the pcs_certificates table.

Refresh cached CRLs: Get all cached CRLs from crl_cache table, for each of them, download the CRL with the cdp_url as target url, and update the crl_cache table.

Type is `certs`¶

Gets all records for all the FMSPCs in the platform_tcbs table (see platformTcbsDao.getPlatformTcbs(fmspc)). If the FMSPCs are not provided, updates all platforms that are already cached.
Sorts the records by {qeid, pceid} so that the TCB mapping records of the same platform are put together.
For each platform:
1. Gets all PCK Certificates for this platform from Intel SGX/TDX with {encrypted_ppid, pceid} or {PLATFORM_MANIFEST, pceid}.
2. Parses the first cert (X.509) in the array to get FMSPC value.
3. Contacts PCS again to get TCB Info with the above FMSPC value.
  
  Note: This does not update the TCB Info in the cache. The TCB Info is only used with the PCK Cert Selection library to update the platform_tcbs table.
4. Deletes old certificates and inserts new certificates for the platform.
5. For each raw TCB in the list of step 2, runs the PCK Cert Selection Tool to get the best certificate and update the cache.

Scheduled Cache Data Refresh¶

The PCCS can also be configured to refresh the cache data regularly, for example, once a day or once a week, etc. The scheduled task does not refresh PCK Certificates because the network traffic overhead is large.

This refresh method is only supported in the LAZY cache fill mode.

It supports Cron-style Scheduling:

* * * * * *
┬ ┬ ┬ ┬ ┬ ┬
│ │ │ │ │ │
│ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun)
│ │ │ │ └───── month (1 - 12)
│ │ │ └────────── day of month (1 - 31)
│ │ └─────────────── hour (0 - 23)
│ └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, OPTIONAL)

Get CRL by endpoint¶

Retrieve the X.509 Certificate Revocation List by the CRL endpoint.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/crl
GET https://pccs-server-url:8081/sgx/certification/v4/crl

Request¶

Name	Type	Request Type	Required	Pattern	Description
`uri`	String	Query	True	Example: https://certificates.trustedservices.intel.com/IntelSGXRootCA.der	URL to DER-encoded CRL (Root CA CRL, Platform/Package CA PCK CRL)

Table 22.

Response¶

Crl - DER-encoded representation of specified CRL.

Status codes¶

Code	Model	Headers	Description
200	`Crl`	-	Successfully completed
400	-	-	Invalid request parameters
500	-	-	Internal server error occurred
502	-	-	Unable to retrieve the collateral from the PCS
503	-	-	Server is currently unable to process the request

Table 23.

Process¶

Checks request parameters and returns the 400 error if the input parameter is invalid
Queries CRL with the uri as the key (see crlCacheDao.getCrl).
1. If record exists:
  1. Returns the crl buffer.
  2. Responds with the 200 status code.
2. Else:
  1. If cache fill mode is not LAZY, returns the 404 (No cache data) error to client.
  2. If cache fill mode is LAZY
    1. Download the CRL with the uri address as target. If failed, returns the 404 error.
    2. Updates crl_cache table:
      1. Calls crlCacheDao.upsertCrl(uri, crl), crl is response body.
    3. Returns CRL in the response body.
    4. Responds with the 200 status code.

Get default platform policy¶

Retrieve the default platform policy provided by the platform owner.

Endpoint(s)¶

GET https://pccs-server-url:8081/sgx/certification/v3/appraisalpolicy
GET https://pccs-server-url:8081/sgx/certification/v4/appraisalpolicy

Request¶

Name	Type	Request Type	Required	Pattern	Description
`fmspc`	String	Query	True	`^[0-9a-fA-F]{12}`	Base16-encoded FMSPC value

Table 24.

Response¶

The default platform policy for this fmspc in jwt format.

Status codes¶

Code	Model	Headers	Description
200	-	-	Successfully completed
400	-	-	Invalid request parameters
404	-	-	The default platform policy can't be found.
500	-	-	Internal server error occurred

Table 25.

Process¶

Checks request parameters and returns the 400 error if the input parameter is invalid
Queries the policy whose default flag is true for the specified fmspc (see appraisalPolicyDao. getDefaultAppraisalPolicies).
1. If record exists:
  1. Returns the policy buffer.
  2. Responds with the 200 status code.
2. Else:
  1. Returns the 404 error.

Put appraisal policy¶

Upload an appraisal policy to the PCCS.

Endpoint(s)¶

PUT https://pccs-server-url:8081/sgx/certification/v3/appraisalpolicy
PUT https://pccs-server-url:8081/sgx/certification/v4/appraisalpolicy

Request¶

Parameters¶

N/A

Body¶

{
    "policy": policy string,
    "is_default": default flag,
    "fmspc": fmspc value
}

Response¶

Status codes¶

Code	Model	Headers	Description
200	-	-	Successfully completed
400	-	-	Invalid request parameters
401	-	-	Authentication failed
500	-	-	Internal server error occurred

Table 26.

Process¶

Validates the admin token(calculate sha-512 hash of the token and compare the hash value with AdminTokenHash in the configuration file). If the validation fails, returns the 401 error to client.
Validates the request body with pre-defined policy schema. If the validation fails, returns the 400 error to client.
Calculate sha384 hash of the policy data, which will be used as the ID of the policy.
Parse the policy file to get policy type based on the class id. Currently only 3 types are supported: 0 – SGX; 1 – TDX 1.0; 2 – TDX 1.5;
Insert or update the appraisal_policies table (see appraisalPolicyDao).

API Specification for PCCS¶

Get PCK Certificate¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get PCK Certificate CRL¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get TCB Info¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get Intel's QE Identity¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get Intel's QvE Identity¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get Intel's TD QE Identity¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Get Root CA CRL¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Post Platforms IDs¶

Endpoint(s)¶

Request¶

Parameters¶

Body¶

Response¶

Status codes¶

Process¶

Get Platform IDs¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Put Platform Collateral to Cache¶

Endpoint(s)¶

Request¶

Parameters¶

Body¶

Response¶

Status codes¶

Process¶

Cache Data Refresh¶

Refresh through HTTP Request¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Process¶

Default (type is not specified)¶

Type is certs¶

Scheduled Cache Data Refresh¶

Get CRL by endpoint¶

Endpoint(s)¶

Request¶

Response¶

Status codes¶

Type is `certs`¶