Key Protection Technology (KPT)

Note

This section documents the Intel® QuickAssist Technology KPT API surface, data structures, and usage flow. KPT is supported on Intel® QAT 6xxx (QAT 5.1) platforms. Applications must confirm support at runtime using the capability check described in Capability Gating.

Platform Support

Intel® Key Protection Technology (KPT) is supported on Intel® QAT 6xxx (QAT 5.1) platforms.

Because availability also depends on the firmware and driver stack in use, applications must verify KPT capability at runtime before issuing KPT calls. See Capability Gating for the required check.

Primary Source Files

  • quickassist/include/lac/cpa_cy_kpt.h

  • quickassist/include/lac/cpa_cy_im.h

  • quickassist/lookaside/firmware/include/icp_qat_fw_kpt_pro.h

  • quickassist/lookaside/access_layer/src/sample_code/functional/asym/kpt/kpt_sample_common.h

  • quickassist/lookaside/access_layer/src/sample_code/functional/asym/kpt/kpt_sample_common.c

  • quickassist/lookaside/access_layer/src/sample_code/functional/asym/kpt/kpt_ecdsa_sample/kpt_ecdsa_sample_main.c

  • quickassist/lookaside/access_layer/src/sample_code/functional/asym/kpt/kpt_ecdsa_sample/kpt_ecdsa_sample_op.c

KPT API Surface (Public)

From cpa_cy_kpt.h.

Discovery / provisioning:

cpaCyKptQueryIssuingKeys(instanceHandle, pPublicX509IssueCert, pKptStatus)
cpaCyKptQueryDeviceCredentials(instanceHandle, pDevCredential, pKptStatus)
cpaCyKptLoadKey(instanceHandle, pSWK, keyHandle, pKptStatus)
cpaCyKptDeleteKey(instanceHandle, keyHandle, pKptStatus)

Usage:

cpaCyKptRsaDecrypt(instanceHandle, cb, callbackTag, pDecryptOpData, pOutputData, pKptUnwrapContext)
cpaCyKptEcdsaSignRS(instanceHandle, cb, callbackTag, pOpData, pSignStatus, pR, pS, pKptUnwrapContext)

KPT management status enum:

  • CPA_CY_KPT_SUCCESS

  • CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_VFID

  • CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED_PER_PASID

  • CPA_CY_KPT_LOADKEY_FAIL_QUOTA_EXCEEDED

  • CPA_CY_KPT_SWK_FAIL_NOT_FOUND

  • CPA_CY_KPT_FAILED

Capability Gating

From cpa_cy_im.h capabilities:

  • CpaCyCapabilitiesInfo includes kptSupported.

Expected runtime behavior pattern:

  1. Query instance capabilities via cpaCyQueryCapabilities.

  2. Require kptSupported == CPA_TRUE before issuing KPT calls.

  3. Handle API returns such as CPA_STATUS_UNSUPPORTED and CPA_STATUS_RETRY.

The sample helper queryCapabilitiesForKpt uses exactly this check and fails early when KPT is not supported.

Key Data Structures and Formats

From cpa_cy_kpt.h:

  • CpaCyKptHandle — 64-bit handle representing a loaded wrapping key in the device key table.

  • CpaCyKptLoadKey — contains encrypted SWK (eSWK) and wrappingAlgorithm.

  • CpaCyKptUnwrapContext — contains:

    • kptHandle

    • iv (max length 12)

    • additionalAuthData (max length 16)

    • aadLenInBytes

  • CpaCyKptRsaPrivateKeyRep1 / Rep2 and CpaCyKptRsaPrivateKey — represent wrapped RSA private key encodings and metadata.

  • CpaCyKptEcdsaSignRSOpData — contains wrapped private key plus message digest for the ECDSA sign operation.

Constants:

  • CPA_CY_KPT_MAX_IV_LENGTH = 12

  • CPA_CY_KPT_MAX_AAD_LENGTH = 16

  • AuthTag length indicated as 16 bytes in API comments and sample code.

Cryptographic Packaging Details

As documented in KPT header comments, the private key wrapping model is AES-256-GCM with:

  • Key: SWK

  • IV: nonce

  • AAD: DER(OID) for algorithm/curve context

  • Output: wrapped private key ciphertext plus 16-byte AuthTag

Documented OID/AAD examples include:

  • RSA context OID 1.2.840.113549.1.1

  • ECDSA curves secp256r1, secp384r1, secp521r1 with corresponding DER encodings

Operational requirement repeatedly noted in source:

  • The nonce (IV) must be unique per SWK encryption operation.

Firmware Provisioning Interface

From icp_qat_fw_kpt_pro.h:

  • Firmware request/response structures for KPT provisioning are defined.

  • Command and service fields are explicit.

  • The request contains source and destination physical addresses and key handle.

This confirms an explicit firmware messaging interface for KPT provisioning is present in source.

Sample-Derived Execution Flow

Based on kpt_sample_common.c and kpt_ecdsa_sample_op.c:

  1. Capability gate:

    • cpaCyQueryCapabilities

    • require kptSupported

  2. Obtain device credentials:

    • cpaCyKptQueryDeviceCredentials with a retry loop on CPA_STATUS_RETRY

  3. Encrypt SWK for device:

    • Build RSA public key from the queried per-part public key

    • Encrypt SWK using OpenSSL EVP_PKEY with OAEP + SHA-256

  4. Load encrypted SWK:

    • cpaCyKptLoadKey returns kptHandle

  5. Wrap private key locally:

    • AES-256-GCM using SWK, IV, AAD

    • append AuthTag

  6. Build unwrap context:

    • kptHandle, IV, AAD, AAD length

  7. Invoke KPT crypto op:

    • The ECDSA sample calls cpaCyKptEcdsaSignRS

    • The RSA sample path is analogous via cpaCyKptRsaDecrypt

  8. Cleanup:

    • cpaCyKptDeleteKey

    • free allocated buffers

Error Handling Patterns To Reuse

Observed in samples:

  • Retry bounded loops for provisioning calls returning CPA_STATUS_RETRY.

  • Validate both the generic API status and the KPT-specific status value.

  • Treat capability mismatch as a hard fail before operation setup.

  • Explicit cleanup on all failure paths.

Practical Integration Checklist

To use KPT on a supported 6xxx (QAT 5.1) platform:

  1. Confirm runtime support: cpaCyQueryCapabilities -> kptSupported == CPA_TRUE.

  2. Validate the firmware/driver stack matches package requirements.

  3. Query issuing and per-part credentials as needed.

  4. Encrypt and load SWK, capture CpaCyKptHandle.

  5. Wrap private keys with AES-256-GCM, unique IV per encryption.

  6. Populate CpaCyKptUnwrapContext correctly.

  7. Execute the KPT RSA/ECDSA API path.

  8. Delete the SWK handle before session teardown.

Usage Notes

  • KPT is supported on Intel® QAT 6xxx (QAT 5.1) platforms.

  • Always confirm kptSupported == CPA_TRUE at runtime before issuing KPT calls, as availability also depends on the firmware and driver stack in use.