dcp

Documentation

Overview

Package dcp implements a driver for the NXP Data Co-Processor (DCP), a cryptographic hardware accelerator included in i.MX6ULL/i.MX6ULZ SoCs.

This package is only meant to be used with `GOOS=tamago GOARCH=arm` as supported by the TamaGo framework for bare metal Go on ARM SoCs, see https://github.com/f-secure-foundry/tamago.

Index

• Constants
• Variables
• func CipherChain(buf []byte, ivs []byte, count int, size int, index int, enc bool) (err error)
• func Decrypt(buf []byte, index int, iv []byte) (err error)
• func DeriveKey(diversifier []byte, iv []byte, index int) (key []byte, err error)
• func Encrypt(buf []byte, index int, iv []byte) (err error)
• func Init()
• func SetKey(index int, key []byte) (err error)
• func Sum256(data []byte) (sum [32]byte, err error)
• type Hash
  • func New256() (Hash, error)
• type WorkPacket
  • func (pkt *WorkPacket) Bytes() []byte
  • func (pkt *WorkPacket) SetCipherDefaults()
  • func (pkt *WorkPacket) SetHashDefaults()

Constants

const (
	DCP_BASE = 0x02280000

	DCP_CTRL     = DCP_BASE
	CTRL_SFTRST  = 31
	CTRL_CLKGATE = 30

	DCP_STAT     = DCP_BASE + 0x10
	DCP_STAT_CLR = DCP_BASE + 0x18
	DCP_STAT_IRQ = 0

	DCP_CHANNELCTRL = DCP_BASE + 0x0020

	DCP_KEY     = DCP_BASE + 0x0060
	KEY_INDEX   = 4
	KEY_SUBWORD = 0

	DCP_KEYDATA   = DCP_BASE + 0x0070
	DCP_CH0CMDPTR = DCP_BASE + 0x0100
	DCP_CH0SEMA   = DCP_BASE + 0x0110

	DCP_CH0STAT        = DCP_BASE + 0x0120
	CHxSTAT_ERROR_CODE = 16
	CHxSTAT_ERROR_MASK = 0b1111110

	DCP_CH0STAT_CLR = DCP_BASE + 0x0128
)

DCP registers

const (
	DCP_CHANNEL_0 = iota + 1
	DCP_CHANNEL_1
	DCP_CHANNEL_2
	DCP_CHANNEL_3
)

DCP channels

const (
	DCP_CTRL0_HASH_TERM       = 13
	DCP_CTRL0_HASH_INIT       = 12
	DCP_CTRL0_OTP_KEY         = 10
	DCP_CTRL0_CIPHER_INIT     = 9
	DCP_CTRL0_CIPHER_ENCRYPT  = 8
	DCP_CTRL0_ENABLE_HASH     = 6
	DCP_CTRL0_ENABLE_CIPHER   = 5
	DCP_CTRL0_CHAIN           = 2
	DCP_CTRL0_DECR_SEMAPHORE  = 1
	DCP_CTRL0_INTERRUPT_ENABL = 0

	DCP_CTRL1_HASH_SELECT = 16
	HASH_SELECT_SHA1      = 0x00
	HASH_SELECT_CRC32     = 0x01
	HASH_SELECT_SHA256    = 0x02

	DCP_CTRL1_KEY_SELECT  = 8
	KEY_SELECT_UNIQUE_KEY = 0xfe

	DCP_CTRL1_CIPHER_MODE = 4
	CIPHER_MODE_CBC       = 0x01

	DCP_CTRL1_CIPHER_SELECT = 0
	CIPHER_SELECT_AES128    = 0x00
)

DCP control packet settings

const WorkPacketLength = 32

Variables

var DeriveKeyMemory = &dma.Region{
	Start: imx6.IRAMStart,
	Size:  imx6.IRAMSize,
}

DeriveKeyMemory represents the DMA memory region used for exchanging DCP derived keys when the derivation index points to an internal DCP key RAM slot.

The default value allocates a DMA region within the i.MX6 On-Chip RAM (OCRAM/iRAM) to avoid passing through external RAM.

The DeriveKey() function uses DeriveKeyMemory only when the default DMA region is not already set within iRAM.

Applications can override the region with an arbitrary one when the iRAM needs to be avoided or is already used as non-default DMA region.

Functions

func CipherChain

func CipherChain(buf []byte, ivs []byte, count int, size int, index int, enc bool) (err error)

CipherChain performs chained in-place buffer encryption/decryption using AES-128-CBC, the key can be selected with the index argument from one previously set with SetKey().

The function expects a byte array with concatenated input data and a byte array with concatenated initialization vectors, the count and size arguments should reflect the number of slices, each to be ciphered and with the corresponding initialization vector slice.

func Decrypt

func Decrypt(buf []byte, index int, iv []byte) (err error)

Decrypt performs in-place buffer decryption using AES-128-CBC, the key can be selected with the index argument from one previously set with SetKey().

func DeriveKey

func DeriveKey(diversifier []byte, iv []byte, index int) (key []byte, err error)

DeriveKey derives a hardware unique key in a manner equivalent to PKCS#11 C_DeriveKey with CKM_AES_CBC_ENCRYPT_DATA.

The diversifier is AES-CBC encrypted using the internal OTPMK key (when SNVS is enabled).

*WARNING*: when SNVS is not enabled a default non-unique test vector is used and therefore key derivation is *unsafe*, see imx6.SNVS().

A negative index argument results in the derived key being computed and returned.

An index argument equal or greater than 0 moves the derived key directly to the corresponding internal DCP key RAM slot (see SetKey()). This is accomplished through an iRAM reserved DMA buffer, to ensure that the key is never exposed to external RAM or the Go runtime. In this case no key is returned by the function.

func Encrypt

func Encrypt(buf []byte, index int, iv []byte) (err error)

Encrypt performs in-place buffer encryption using AES-128-CBC, the key can be selected with the index argument from one previously set with SetKey().

func Init

func Init()

Init initializes the DCP module.

func SetKey

func SetKey(index int, key []byte) (err error)

SetKey configures an AES-128 key in one of the 4 available slots of the DCP key RAM.

func Sum256

func Sum256(data []byte) (sum [32]byte, err error)

Sum256 returns the SHA256 checksum of the data.

There must be sufficient DMA memory allocated to hold the data, otherwise the function will panic.

Types

type Hash

type Hash interface {
	// Write (via the embedded io.Writer interface) adds more data to the running hash.
	// It can return an error. It returns an error if Sum has been already invoked.
	io.Writer

	// Sum appends the current hash to b and returns the resulting slice.
	// Its invocation terminates the digest instance, for this reason Write
	// will return errors after Sum is invoked.
	Sum(b []byte) ([]byte, error)

	// BlockSize returns the hash's underlying block size.
	// The Write method must be able to accept any amount
	// of data, but it may operate more efficiently if all writes
	// are a multiple of the block size.
	BlockSize() int
}

Hash is the common interface to DCP hardware backed hash functions.

While similar to Go native hash.Hash, this interface is not fully compatible with it as hardware errors must be checked and checksum computation affects state.

func New256

func New256() (Hash, error)

New256 returns a new Digest computing the SHA256 checksum.

A single DCP channel is used for all operations, this entails that only one digest instance can be kept at any given time, if this condition is not met an error is returned.

The digest instance starts with New256() and terminates when when Sum() is invoked, after which the digest state can no longer be changed.

type WorkPacket

type WorkPacket struct {
	NextCmdAddr              uint32
	Control0                 uint32
	Control1                 uint32
	SourceBufferAddress      uint32
	DestinationBufferAddress uint32
	BufferSize               uint32
	PayloadPointer           uint32
	Status                   uint32
}

WorkPacket represents a DCP work packet (p1067, 13.2.6.4 Work Packet Structure, MCIMX28RM).

func (*WorkPacket) Bytes

func (pkt *WorkPacket) Bytes() []byte

Bytes converts the DCP work packet structure to byte array format.

func (*WorkPacket) SetCipherDefaults

func (pkt *WorkPacket) SetCipherDefaults()

SetCipherDefaults initializes default values for a DCP work packet that performs cipher operation.

func (*WorkPacket) SetHashDefaults

func (pkt *WorkPacket) SetHashDefaults()

SetHashDefaults initializes default values for a DCP work packet that performs hash operation.