Quantcast
Channel: Intel Developer Zone Articles
Viewing all articles
Browse latest Browse all 3384

Intel® Security Dev API: Go Developer Guide

$
0
0

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


DocumentScope
Get Started GuideThe Get Started Guide describes how to install the SDK and open a Hello World code sample.
Code samplesThe 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.
FAQsHave a question? Browse the FAQs for answers.
Release NotesThe 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.

ItemDescription
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 systemUbuntu 16.04 64-bit Desktop Version

 


Hardware Security

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.

  1. Import the isec gopackage:
    import "intel.com/isec"
  2. 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)
    }
  3. 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)
  4. 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.

  1. Call and reference the handle of the Secure Data object.
    size, err := sd.GetSealedBlobSize()	
  2. Call GetSealedBlob and reference the handle of the Secure Data object.
    data, err := sd.GetSealedBlob()
  3. 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)
    }
  4. Write your own code to place the blob in the desired location.
  5. 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.

  1. Call GetNonSecretSize and reference the handle of the Secure Data object.
    obtainedDataSize, err := sd.GetNonSecretSize()
  2. 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.


Viewing all articles
Browse latest Browse all 3384

Trending Articles



<script src="https://jsc.adskeeper.com/r/s/rssing.com.1596347.js" async> </script>