github.com/usbarmory/tamago@v0.0.0-20240508072735-8612bbe1e454/soc/nxp/caam/caam.go (about)

     1  // NXP Cryptographic Acceleration and Assurance Module (CAAM) driver
     2  // https://github.com/usbarmory/tamago
     3  //
     4  // Copyright (c) WithSecure Corporation
     5  // https://foundry.withsecure.com
     6  //
     7  // Use of this source code is governed by the license
     8  // that can be found in the LICENSE file.
     9  
    10  // Package caam implements a driver for the NXP Cryptographic Acceleration and
    11  // Assurance Module (CAAM) adopting the following reference specifications:
    12  //   - IMX6ULSRM - i.MX6UL Security Reference Manual - Rev 0 04/2016
    13  //   - IMX7DSSRM - i.MX7DS Security Reference Manual - Rev 0 03/2017
    14  //
    15  // This package is only meant to be used with `GOOS=tamago GOARCH=arm` as
    16  // supported by the TamaGo framework for bare metal Go on ARM SoCs, see
    17  // https://github.com/usbarmory/tamago.
    18  package caam
    19  
    20  import (
    21  	"sync"
    22  
    23  	"github.com/usbarmory/tamago/dma"
    24  	"github.com/usbarmory/tamago/internal/reg"
    25  )
    26  
    27  // CAAM registers
    28  const (
    29  	CAAM_SCFGR     = 0xc
    30  	SCFGR_RNGSH0   = 9
    31  	SCFGR_RANDDPAR = 8
    32  
    33  	CAAM_RTMCTL     = 0x600
    34  	RTMCTL_PRGM     = 16
    35  	RTMCTL_ENT_VAL  = 10
    36  	RTMCTL_RST_DEF  = 6
    37  	RTMCTL_TRNG_ACC = 5
    38  
    39  	CAAM_RTENT0  = 0x640
    40  	CAAM_RTENT15 = 0x67c
    41  
    42  	CAAM_C0CWR = 0x8044
    43  	C0CWR_C1M  = 0
    44  )
    45  
    46  // CAAM represents the Cryptographic Acceleration and Assurance Module
    47  // instance.
    48  type CAAM struct {
    49  	sync.Mutex
    50  
    51  	// Base register
    52  	Base uint32
    53  	// Clock gate register
    54  	CCGR uint32
    55  	// Clock gate
    56  	CG int
    57  
    58  	// DeriveKeyMemory represents the DMA memory region where the CAAM blob
    59  	// key encryption key (BKEK), derived from the hardware unique key, is
    60  	// placed to derive diversified keys. The memory region must be
    61  	// initialized before DeriveKey().
    62  	//
    63  	// When BEE is not used to encrypt external RAM it is recommended to
    64  	// use a DMA region within the internal RAM (e.g. i.MX6 On-Chip
    65  	// OCRAM/iRAM).
    66  	//
    67  	// The DeriveKey() function uses DeriveKeyMemory only if the default
    68  	// DMA region start does not overlap with it.
    69  	DeriveKeyMemory *dma.Region
    70  
    71  	// Disable Timing Equalization protections (when supported)
    72  	DisableTimingEqualization bool
    73  
    74  	// control registers
    75  	scfgr   uint32
    76  	rtmctl  uint32
    77  	rtent0  uint32
    78  	rtent15 uint32
    79  
    80  	// current RTENTa register
    81  	rtenta uint32
    82  
    83  	// default job ring
    84  	jr *jobRing
    85  }
    86  
    87  // Init initializes the CAAM module.
    88  func (hw *CAAM) Init() {
    89  	hw.Lock()
    90  	defer hw.Unlock()
    91  
    92  	if hw.Base == 0 || hw.CCGR == 0 {
    93  		panic("invalid CAAM instance")
    94  	}
    95  
    96  	hw.scfgr = hw.Base + CAAM_SCFGR
    97  	hw.rtmctl = hw.Base + CAAM_RTMCTL
    98  	hw.rtent0 = hw.Base + CAAM_RTENT0
    99  	hw.rtent15 = hw.Base + CAAM_RTENT15
   100  
   101  	// enable clock
   102  	reg.SetN(hw.CCGR, hw.CG, 0b11, 0b11)
   103  
   104  	// enter program mode
   105  	reg.Set(hw.rtmctl, RTMCTL_PRGM)
   106  	// reset defaults
   107  	reg.Set(hw.rtmctl, RTMCTL_RST_DEF)
   108  
   109  	// enable entropy generation
   110  	hw.rtenta = hw.rtent0
   111  
   112  	// force entropy re-generation
   113  	reg.Set(hw.rtmctl, RTMCTL_TRNG_ACC)
   114  	defer reg.Clear(hw.rtmctl, RTMCTL_TRNG_ACC)
   115  
   116  	// disable RNG deterministic mode
   117  	reg.Set(hw.scfgr, SCFGR_RNGSH0)
   118  	// enable Random Differential Power Analysis Resistance
   119  	reg.Set(hw.scfgr, SCFGR_RANDDPAR)
   120  
   121  	// enter run mode
   122  	reg.Clear(hw.rtmctl, RTMCTL_PRGM)
   123  }