rpmb

Documentation

Overview

Package rpmb implements Replay Protected Memory Block (RPMB) configuration and control on eMMCs accessed through TamaGo NXP uSDHC driver.

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/usbarmory/tamago.

The API supports mitigations for CVE-2020-13799 as described in the whitepaper linked at:

https://www.westerndigital.com/support/productsecurity/wdc-20008-replay-attack-vulnerabilities-rpmb-protocol-applications

Index

• Constants
• type Config
• type DataFrame
  • func (d *DataFrame) Bytes() []byte
  • func (d *DataFrame) Counter() uint32
• type OperationError
  • func (e *OperationError) Error() string
• type RPMB
  • func Init(card *usdhc.USDHC, key []byte, dummyBlock uint16, writeDummy bool) (p *RPMB, err error)
  • func (p *RPMB) Counter(auth bool) (n uint32, err error)
  • func (p *RPMB) ProgramKey() (err error)
  • func (p *RPMB) Read(offset uint16, buf []byte) (err error)
  • func (p *RPMB) Write(offset uint16, buf []byte) (err error)

Constants

const (
	AuthenticationKeyProgramming = iota + 1
	WriteCounterRead
	AuthenticatedDataWrite
	AuthenticatedDataRead
	ResultRead
	AuthenticatedDeviceConfigurationWrite
	AuthenticatedDeviceConfigurationRead
)

p99, Table 18 — RPMB Request/Response Message Types, JESD84-B51

const (
	OperationOK = iota
	GeneralFailure
	AuthenticationFailure
	CounterFailure
	AddressFailure
	WriteFailure
	ReadFailure
	AuthenticationKeyNotYetProgrammed
)

p100, Table 20 — RPMB Operation Results, JESD84-B51

const (
	FrameLength = 512
)

Types

type Config

type Config struct {
	// compute request MAC before sending
	RequestMAC bool
	// validate response MAC after receiving
	ResponseMAC bool
	// set Nonce field with random value
	RandomNonce bool
	// get response with a result read request
	ResultRead bool
}

Request configuration

type DataFrame

type DataFrame struct {
	StuffBytes   [196]byte
	KeyMAC       [32]byte
	Data         [256]byte
	Nonce        [16]byte
	WriteCounter [4]byte
	Address      [2]byte
	BlockCount   [2]byte
	Result       [2]byte
	Resp         byte
	Req          byte
}

p98, Table 17 — Data Frame Files for RPMB, JESD84-B51

func (*DataFrame) Bytes

func (d *DataFrame) Bytes() []byte

Bytes converts the data frame structure to byte array format.

func (*DataFrame) Counter

func (d *DataFrame) Counter() uint32

Counter returns the data frame WriteCounter in uint32 format.

type OperationError

type OperationError struct {
	Result uint16
}

func (*OperationError) Error

func (e *OperationError) Error() string

type RPMB

type RPMB struct {
	sync.Mutex
	// contains filtered or unexported fields
}

RPMB defines a Replay Protected Memory Block partition access instance.

func Init

func Init(card *usdhc.USDHC, key []byte, dummyBlock uint16, writeDummy bool) (p *RPMB, err error)

Init returns a new RPMB instance for a specific MMC card and MAC key. The dummyBlock argument is an unused sector, required for CVE-2020-13799 mitigation to invalidate uncommitted writes.

func (*RPMB) Counter

func (p *RPMB) Counter(auth bool) (n uint32, err error)

Counter returns the RPMB partition write counter, the argument boolean indicates whether the read operation should be authenticated.

func (*RPMB) ProgramKey

func (p *RPMB) ProgramKey() (err error)

ProgramKey programs the RPMB partition authentication key.

*WARNING*: this is a one-time irreversible operation for the specific MMC card associated to the RPMB partition instance.

func (*RPMB) Read

func (p *RPMB) Read(offset uint16, buf []byte) (err error)

Read performs an authenticated data transfer from the card RPMB partition, the input buffer can contain up to 256 bytes of data.

func (*RPMB) Write

func (p *RPMB) Write(offset uint16, buf []byte) (err error)

Write performs an authenticated data transfer to the card RPMB partition, the input buffer can contain up to 256 bytes of data.

The write operation mitigates CVE-2020-13799 by verifying that the response counter is equal to a single increment of the request counter, otherwise an error is returned.