Introduction
Intel® Security Dev API is an API library that makes it easy for application developers to provision RSA private keys onto Trusted Platform Modules (TPMs) using the Go programming language.
APIs
This release of the API library provides a Go wrapper that allows access to the following APIs:
- Secure Data API: Set of API functions that enables you to protect data on the local device, even from the application itself.
- Crypto API: Cryptographic utilities. This release provides RSA signing.
Related Documentation
Document | Scope |
---|---|
Get Started Guide | The Get Started Guide describes how to install the SDK and open a Hello World code sample. |
Code samples | The SDK contains complete code samples, including source files and makefiles, in $GOPATH/src/intel.com/isec/samples/ . The samples demonstrate the tasks described in this Developer Guide and more. |
FAQs | Have a question? Browse the FAQs for answers. |
Release Notes | The Release Notes describe known issues. |
For more documentation, such as developer guides for other programming languages, see the Intel® Security Dev API website.
Specifications
Target Devices
Intel® Security Dev API is compatible with the following device configurations.
- Trusted Platform Modules (TPMs), version 2.0 or higher.
Development Environment
Intel® Security Dev API is compatible with the following development environment.
Item | Description |
---|---|
Hardware | Your development and deployment environments must feature a Trusted Platform Module (TPM) that supports the TPM 2.0 hardware standard and a compatible TPM Software Stack (TSS), such as Intel® TSS |
Operating system | Ubuntu 16.04 64-bit Desktop Version |
Software to encrypt and protect sensitive information, such as data and algorithms, is readily available for almost all operating systems. Unfortunately, the security provided by software can only be as strong as the operating system hosting the software security solution. Sophisticated malware can attack vulnerabilities in the operating system and obtain the privileges of the operating system itself. With these privileges, the attacker can freely access sensitive information that the operating system was tasked to protect.
Hardware security provides an additional layer of protection by isolating sensitive information from the operating system.
Intel® Security Dev API enables you to use the following hardware security technologies:
- Trusted platform module (TPM)
Trusted Platform Module (TPM)
A trusted platform module (TPM) is a microcontroller, typically affixed to the motherboard of a computing device. All TPMs meet the standards of the Trusted Computing Group (TCG).
The API library supports TPMs that meet the TPM 2.0 standard and are FIPS-compliant. Using the APIs, you can protect an RSA private key and use the key to sign data. The signing process occurs inside the TPM, so that the key is not exposed to the operating system.
Secure Data API
On a trusted platform module (TPM) enabled device, you can use the Secure Data API to protect RSA private keys.
To protect a key, you create a Secure Data object, consisting of the following components:
- Secret data: The key that requires protection from disclosure and modification.
- Non-secret data (optional): Public information associated with the secret data. For example, a description of the key.
- Protection policy: A set of attributes defining the security protection level of the data, particularly access level and allowed usage.
Once you have created the Secure Data object, you can reference it via the handle returned by the creation API. You can use the protected data by providing the handle to other API calls. In other words, your application exposes the handle rather than the actual data, reducing the risk of disclosure should your application become compromised. The protection policy defines which API calls your application is allowed to use. For example, the API provides get
and set
calls that allow the application to read and update the data, respectively, but the protection policy set by the initial data creator might prohibit the use of those calls.
Intel trusted logic running on the OS provides the RSA private key to the TPM. The TPM generates a wrapper key, encrypts the RSA private key with the wrapper key, and provides the encrypted RSA private key to Intel trusted logic. Intel trusted logic creates a Secure Data object of the encrypted RSA private key.
When the data is not in use (also referred to as "at-rest data"), you can seal the Secure Data object for storage.
Sealing
Sealing is hardware-based encryption for at-rest protection of data.
By using the API, you first create a Secure Data object to protect the data while the data is in use. When the data is at-rest, for example, in need of storage, you use the API to seal the Secure Data object. On TPM enabled devices, Intel trusted logic running on the OS uses AES-GCM to seal the Secure Data object. The key used for sealing is defined in the protection policy. You can specify local protection only.
A local protection policy is used to ensure that unsealing is only possible on the same device that the data was sealed on. The sealing key material is a TPM generated and protected storage key. The access password in Startup
, if provided, is also added to the set of information used to derive the sealing key.
The resulting sealed Secure Data object is called a "sealed blob." To decrypt the data and begin to use it again, you use the API to recreate the Secure Data object. Before attempting to recreate the object, you must make sure the sealed blob is in the correct environment. In the case of local protection, the sealed blob must be on the device it originated from.
Create a Secure Data Object
The following summarizes how to use the Secure Data API in an application. The key size must be 2048 bit.
- Import the
isec go
package:import "intel.com/isec"
- Create a protection policy by using the
NewLocalPolicy
function:policy, err := isec.NewLocalPolicy(isec.DataUsageRsaPublicKey, isec.DataAccessUpdate, isec.DataFlagsNoVersionTracking) if err != nil { fmt.Printf("Error string for '%+v' should be nil \n", err) }
- Create an RSA Private Key using the policy you just created:
pubKeyPolicy, err := isec.NewLocalPolicy(isec.DataUsageRsaPublicKey, isec.DataAccessUse, DataFlagsNoVersionTracking) if err != nil { logError("NewLocal Policy return with ", err) return nil, nil, err } priKeyPolicy, err := isec.NewLocalPolicy(isec.DataUsageRsaPrivateKey, isec.DataAccessUse, isec.DataFlagsNoVersionTracking) if err != nil { logError("NewLocal Policy return with ", err) return nil, nil, err, pubKey, priKey, isecerr := isec.GenerateKeyPair(isec.KeyGenTypeRSA, 2048, isec.KeyGenMethodDefault, "RRP_HW_Root_Key", pubKeyPolicy, priKeyPolicy) } if isecerr != nil { fmt.Printf("Key Generate failed with: %v", isecerr) } fmt.Printf("pubKey is %x\n", pubKey.handle) fmt.Printf("priKey is %x\n", priKey.handle)
- Create a Secure Data object of the key by using the
NewSecureDataWithPolicy
function and reference the handle of the policy object you created in step 1:nonsecretdata := []byte("this is nonSecretData") data := []byte("this is secret data") sd, err := isec.NewSecureDataWithPolicy(data, nonsecretdata, policy) if err != nil { fmt.Printf("isec.NewSecureDataWithPolicy failed with %v", err) } fmt.Printf("SecureData object is %v", sd) }
Get a Sealed Blob
You can seal the Secure Data object for storage. You can also recreate the Secure Data object from the sealed blob.
- Call and reference the handle of the Secure Data object.
size, err := sd.GetSealedBlobSize()
- Call
GetSealedBlob
and reference the handle of the Secure Data object.data, err := sd.GetSealedBlob()
- At this point, the Secure Data handle is no longer needed. Call
sd.Close()
to delete the memory resources associated with the handle.err = sd.Close() if err != nil { fmt.Printf("Error string for '%+v' should be nil \n", err) }
- Write your own code to place the blob in the desired location.
- To unseal the data, call
RecreateFromSealed
and reference the buffer pointer and size. This call recreates the Secure Data object.You can use the new handle in other API calls:
data := []byte("secret data") cipher, err := DataAsymmetricEncrypt(data, pubKey, EncryptionPaddingPKCS1_v15) sealed, err := priKey.GetSealedBlob() if err != nil { fmt.Fatalf("Get Sealed blob failed with %+v", err) } recreatedKey, err := RecreateFromSealed(sealed) if err != nil { fmt.Fatalf("Recreate from sealed failed with %+v", err) } plainTxt, err := DataAsymmetricDecrypt(cipher, recreatedKey, EncryptionPaddingPKCS1_v15) if ok := bytes.Compare(data, plainTxt); ok == 0 { fmt.Printf("Recreate from sealed blob success") } else { fmt.Fatalf("Recreate from sealed failed, expected %v, received %v", data, plainTxt) }
Get the Non-Secret Data
You can get the non-secret data in a Secure Data object.
- Call
GetNonSecretSize
and reference the handle of the Secure Data object.obtainedDataSize, err := sd.GetNonSecretSize()
- Call
GetNonSecretData()
.data, err := sd.GetNonSecretData()
Manage Memory
When Secure Data objects are no longer needed, you must delete the memory resources associated with the objects. Call destroy()
Close()
and reference the object to delete method / function. This call prevents race conditions by using synchronization primitives to block execution to ensure the object is not in use by another thread.
err := sd.Close()
When a Secure Data object is an input of another Secure Data object, you must destroy the objects in the reverse order in which they were created. In other words, if Object A is an input of Object B, destroy Object B, then destroy Object A.
Protection Policies
Each Secure Data object contains a protection policy. The protection policy is a set of attributes that define allowed usage of the secret data (plaintext), the encryption method for sealing the Secure Data object, and more.
When the Secure Data object is in use, the protection policy is included in the form of an object. When you seal the object, the protection policy is packed as part of the sealed blob. When you recreate the object from the sealed blob, the protection policy is reconstructed and enforced.
For TPM enabled devices, you can use only the local
protection policy: NewLocalPolicy
. See Create a Secure Data Object for the appropriate attributes.
Crypto API
The Crypto API provides common cryptographic utilities and is intended for cryptography experts. The API supports trusted platform module (TPM) enabled devices only.
RSA Signing
You can sign a hash with an RSA private key on TPM enabled devices. RSA signing is performed inside the TPM. The output is signed data.
In this release, Intel® Security Dev API does not provide the ability to hash data.
The RSA signing function requires that you input the RSA private key as a Secure Data object. For more information, see Create a Secure Data Object.
To sign a hash with an RSA private key, call HashSign
with the following parameters:
- For the
[]byte
parameter, provide the size of the data in bytes. The size must be 20 or 32 bytes. - For the
hashed
parameter, provide the pointer to the data buffer. - For the
privateKey
parameter, provide the Secure Data handle of the RSA private key. - For the
padding
parameter, provide the padding type. - For the
hash
parameter, provide the size of the buffer to contain the result.
Legal and Disclaimers
INTEL CONFIDENTIAL
You may not use or facilitate the use of this document in connection with any infringement or other legal analysis concerning Intel products described herein. You agree to grant Intel a non-exclusive, royalty-free license to any patent claim thereafter drafted which includes subject matter disclosed herein.
No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document.
All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps.
The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Performance varies depending on system configuration. No computer system can be absolutely secure. Check with your system manufacturer or retailer or learn more at intel.com.
No computer system can be absolutely secure.
Intel, the Intel logo, and Intel Core are trademarks of Intel Corporation in the U.S. and/or other countries.