drivers/puf/fsl_puf.c

0001 /*
0002  * Copyright 2018-2021 NXP
0003  * All rights reserved.
0004  *
0005  *
0006  * SPDX-License-Identifier: BSD-3-Clause
0007  */
0008
0009 #include "fsl_puf.h"
0010 #include "fsl_clock.h"
0011 #include "fsl_common.h"
0012
0013 #if !(defined(FSL_FEATURE_PUF_HAS_NO_RESET) && (FSL_FEATURE_PUF_HAS_NO_RESET > 0))
0014 #include "fsl_reset.h"
0015 #endif /* FSL_FEATURE_PUF_HAS_NO_RESET */
0016
0017 /* Component ID definition, used by tools. */
0018 #ifndef FSL_COMPONENT_ID
0019 #define FSL_COMPONENT_ID "platform.drivers.puf"
0020 #endif
0021
0022 /* RT6xx POWER CONTROL bit masks */
0023 #if defined(FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL) && (FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL > 0)
0024 #define PUF_PWRCTRL_CKDIS_MASK         (0x4U)
0025 #define PUF_PWRCTRL_RAMINIT_MASK       (0x8U)
0026 #define PUF_PWRCTRL_RAMPSWLARGEMA_MASK (0x10U)
0027 #define PUF_PWRCTRL_RAMPSWLARGEMP_MASK (0x20U)
0028 #define PUF_PWRCTRL_RAMPSWSMALLMA_MASK (0x40U)
0029 #define PUF_PWRCTRL_RAMPSWSMALLMP_MASK (0x80U)
0030 #endif
0031
0032 #if defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0033 #define DEFAULT_CKGATING 0x0u
0034 #define PUF_ENABLE_MASK  0xFFFFFFFEu
0035 #define PUF_ENABLE_CTRL  0x1u
0036
0037 #else
0038 static void puf_wait_usec(volatile uint32_t usec, uint32_t coreClockFrequencyMHz)
0039 {
0040     SDK_DelayAtLeastUs(usec, coreClockFrequencyMHz * 1000000U);
0041
0042     /* Instead of calling SDK_DelayAtLeastUs() implement delay loop here */
0043     // while (usec > 0U)
0044     // {
0045     //     usec--;
0046
0047     //     number of MHz is directly number of core clocks to wait 1 usec.
0048     //     the while loop below is actually 4 clocks so divide by 4 for ~1 usec
0049     //     volatile uint32_t ticksCount = coreClockFrequencyMHz / 4u + 1u;
0050     //     while (0U != ticksCount--)
0051     //     {
0052     //     }
0053     // }
0054 }
0055 #endif /* defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0) */
0056
0057 static status_t puf_waitForInit(PUF_Type *base)
0058 {
0059     status_t status = kStatus_Fail;
0060
0061     /* wait until status register reads non-zero. All zero is not valid. It should be BUSY or OK or ERROR */
0062     while (0U == base->STAT)
0063     {
0064     }
0065
0066     /* wait if busy */
0067     while ((base->STAT & PUF_STAT_BUSY_MASK) != 0U)
0068     {
0069     }
0070
0071     /* return status */
0072     if (0U != (base->STAT & (PUF_STAT_SUCCESS_MASK | PUF_STAT_ERROR_MASK)))
0073     {
0074         status = kStatus_Success;
0075     }
0076
0077     return status;
0078 }
0079
0080 static void puf_powerOn(PUF_Type *base, puf_config_t *conf)
0081 {
0082 #if defined(FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL) && (FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL > 0)
0083     /* RT6xxs */
0084     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK);
0085     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0086     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0087 #elif defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0088     /* LPCXpresso55s16 */
0089     conf->puf_sram_base->CFG |= PUF_ENABLE_CTRL;
0090     while (0U == (PUF_SRAM_CTRL_STATUS_READY_MASK & conf->puf_sram_base->STATUS))
0091     {
0092     }
0093 #else  /* !FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL */
0094     /* LPCXpresso55s69 & LPCXpresso54S018 */
0095     base->PWRCTRL = PUF_PWRCTRL_RAMON_MASK;
0096     while (0U == (PUF_PWRCTRL_RAMSTAT_MASK & base->PWRCTRL))
0097     {
0098     }
0099 #endif /* FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL */
0100 }
0101 /*!
0102  * brief Powercycle PUF
0103  *
0104  * This function make powercycle of PUF.
0105  *
0106  * param base PUF peripheral base address
0107  * param conf PUF configuration structure
0108  * return Status of the powercycle operation.
0109  */
0110 status_t PUF_PowerCycle(PUF_Type *base, puf_config_t *conf)
0111 {
0112 #if defined(FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL) && (FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL > 0)
0113     /* RT6xxs */
0114     uint32_t coreClockFrequencyMHz = conf->coreClockFrequencyHz / 1000000u;
0115
0116     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK); /* disable RAM CK */
0117
0118     /* enter ASPS mode */
0119     base->PWRCTRL = (PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK); /* SLEEP = 1 */
0120     base->PWRCTRL = (PUF_PWRCTRL_RAMINIT_MASK);                           /* enable RAM CK */
0121     base->PWRCTRL = (PUF_PWRCTRL_RAMINIT_MASK | PUF_PWRCTRL_RAMPSWLARGEMA_MASK | PUF_PWRCTRL_RAMPSWLARGEMP_MASK |
0122                      PUF_PWRCTRL_RAMPSWSMALLMA_MASK | PUF_PWRCTRL_RAMPSWSMALLMP_MASK); /* SLEEP=1, PSW*=1 */
0123
0124     /* Wait enough time to discharge fully */
0125     puf_wait_usec(conf->dischargeTimeMsec * 1000u, conf->coreClockFrequencyHz / 1000000u);
0126
0127     /* write PWRCTRL=0x38. wait time > 1 us */
0128     base->PWRCTRL = (PUF_PWRCTRL_RAMINIT_MASK | PUF_PWRCTRL_RAMPSWLARGEMA_MASK |
0129                      PUF_PWRCTRL_RAMPSWLARGEMP_MASK); /* SLEEP=1. PSWSMALL*=0. PSWLARGE*=1. */
0130     puf_wait_usec(1, coreClockFrequencyMHz);
0131
0132     /* write PWRCTRL=0x8. wait time > 1 us */
0133     base->PWRCTRL = PUF_PWRCTRL_RAMINIT_MASK; /* SLEEP=1. PSWSMALL*=0. PSWLARGE*=0 */
0134     puf_wait_usec(1, coreClockFrequencyMHz);
0135
0136     base->PWRCTRL = (PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0137     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0138     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0139
0140     /* Generate INITN low pulse */
0141     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK);
0142     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK);
0143     base->PWRCTRL = PUF_PWRCTRL_RAM_ON_MASK;
0144 #elif defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0145     /* LPCXpresso55s16 */
0146     conf->puf_sram_base->CFG &= PUF_ENABLE_MASK;
0147 #else
0148     /* LPCXpresso55s69 & LPCXpresso54S018 */
0149     base->PWRCTRL = 0x0u;
0150     while (0U != (PUF_PWRCTRL_RAMSTAT_MASK & base->PWRCTRL))
0151     {
0152     }
0153
0154     /* Wait enough time to discharge fully */
0155     puf_wait_usec(conf->dischargeTimeMsec * 1000u, conf->coreClockFrequencyHz / 1000000u);
0156 #endif
0157
0158 #if !(defined(FSL_FEATURE_PUF_HAS_NO_RESET) && (FSL_FEATURE_PUF_HAS_NO_RESET > 0))
0159     /* Reset PUF and reenable power to PUF SRAM */
0160     RESET_PeripheralReset(kPUF_RST_SHIFT_RSTn);
0161 #endif /* FSL_TEATURE_PUF_HAS_NO_RESET */
0162     puf_powerOn(base, conf);
0163
0164     return kStatus_Success;
0165 }
0166
0167 /*!
0168  * brief Sets the default configuration of PUF
0169  *
0170  * This function initialize PUF config structure to default values.
0171  *
0172  * param conf PUF configuration structure
0173  */
0174 void PUF_GetDefaultConfig(puf_config_t *conf)
0175 {
0176 #if defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0177     /* LPCXpresso55s16 */
0178     conf->puf_sram_base = PUF_SRAM_CTRL;
0179
0180     /* Default configuration after reset */
0181     conf->CKGATING = DEFAULT_CKGATING; /* PUF SRAM Clock Gating */
0182 #endif                                 /* FSL_FEATURE_PUF_HAS_SRAM_CTRL */
0183
0184     conf->dischargeTimeMsec    = KEYSTORE_PUF_DISCHARGE_TIME_FIRST_TRY_MS;
0185     conf->coreClockFrequencyHz = CLOCK_GetFreq(kCLOCK_CoreSysClk);
0186
0187     return;
0188 }
0189
0190 /*!
0191  * brief Initialize PUF
0192  *
0193  * This function enables power to PUF block and waits until the block initializes.
0194  *
0195  * param base PUF peripheral base address
0196  * param conf PUF configuration structure
0197  * return Status of the init operation
0198  */
0199 status_t PUF_Init(PUF_Type *base, puf_config_t *conf)
0200 {
0201     status_t status = kStatus_Fail;
0202
0203 #if !(defined(FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL) && FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL)
0204     CLOCK_EnableClock(kCLOCK_Puf);
0205 #endif
0206 #if !(defined(FSL_FEATURE_PUF_HAS_NO_RESET) && (FSL_FEATURE_PUF_HAS_NO_RESET > 0))
0207     /* Reset PUF */
0208     RESET_PeripheralReset(kPUF_RST_SHIFT_RSTn);
0209 #endif /* FSL_FEATURE_PUF_HAS_NO_RESET */
0210
0211 #if defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0212     /* Set configuration for SRAM */
0213     conf->puf_sram_base->CFG |= PUF_SRAM_CTRL_CFG_CKGATING(conf->CKGATING);
0214
0215 #endif /* FSL_FEATURE_PUF_HAS_SRAM_CTRL */
0216
0217     /* Enable power to PUF SRAM */
0218     puf_powerOn(base, conf);
0219
0220     /* Wait for peripheral to become ready */
0221     status = puf_waitForInit(base);
0222
0223     /* In case of error or enroll or start not allowed, do power-cycle */
0224     /* First try with shorter discharge time, if then it also fails try with longer time */
0225     /* conf->dischargeTimeMsec    = KEYSTORE_PUF_DISCHARGE_TIME_FIRST_TRY_MS; */
0226     if ((status != kStatus_Success) || (0U == (base->ALLOW & (PUF_ALLOW_ALLOWENROLL_MASK | PUF_ALLOW_ALLOWSTART_MASK))))
0227     {
0228         (void)PUF_PowerCycle(base, conf);
0229         status = puf_waitForInit(base);
0230     }
0231
0232     /* In case of error or enroll or start not allowed, do power-cycle with worst discharge timing */
0233     if ((status != kStatus_Success) || (0U == (base->ALLOW & (PUF_ALLOW_ALLOWENROLL_MASK | PUF_ALLOW_ALLOWSTART_MASK))))
0234     {
0235         conf->dischargeTimeMsec = KEYSTORE_PUF_DISCHARGE_TIME_MAX_MS;
0236         (void)PUF_PowerCycle(base, conf);
0237         status = puf_waitForInit(base);
0238     }
0239
0240     return status;
0241 }
0242
0243 /*!
0244  * brief Denitialize PUF
0245  *
0246  * This function disables power to PUF SRAM and peripheral clock.
0247  *
0248  * param base PUF peripheral base address
0249  * param conf PUF configuration structure
0250  */
0251 void PUF_Deinit(PUF_Type *base, puf_config_t *conf)
0252 {
0253 #if defined(FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL) && (FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL > 0)
0254     /* RT6xxs */
0255     base->PWRCTRL = (PUF_PWRCTRL_RAM_ON_MASK | PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK); /* disable RAM CK */
0256
0257     /* enter ASPS mode */
0258     base->PWRCTRL = (PUF_PWRCTRL_CK_DIS_MASK | PUF_PWRCTRL_RAMINIT_MASK); /* SLEEP = 1 */
0259     base->PWRCTRL = PUF_PWRCTRL_RAMINIT_MASK;                             /* enable RAM CK */
0260     base->PWRCTRL = (PUF_PWRCTRL_RAMINIT_MASK | PUF_PWRCTRL_RAMPSWLARGEMA_MASK | PUF_PWRCTRL_RAMPSWLARGEMP_MASK |
0261                      PUF_PWRCTRL_RAMPSWSMALLMA_MASK | PUF_PWRCTRL_RAMPSWSMALLMP_MASK); /* SLEEP=1, PSW*=1 */
0262     puf_wait_usec(conf->dischargeTimeMsec * 1000u, conf->coreClockFrequencyHz / 1000000u);
0263 #elif defined(FSL_FEATURE_PUF_HAS_SRAM_CTRL) && (FSL_FEATURE_PUF_HAS_SRAM_CTRL > 0)
0264     /* LPCXpresso55s16 */
0265     conf->puf_sram_base = PUF_SRAM_CTRL;
0266     conf->puf_sram_base->CFG &= PUF_ENABLE_MASK;
0267 #else /* !FSL_FEATURE_PUF_PWR_HAS_MANUAL_SLEEP_CONTROL */
0268     /* LPCXpresso55s69 & LPCXpresso54S018 */
0269     base->PWRCTRL = 0x00u;
0270     puf_wait_usec(conf->dischargeTimeMsec * 1000u, conf->coreClockFrequencyHz / 1000000u);
0271 #endif
0272
0273 #if !(defined(FSL_FEATURE_PUF_HAS_NO_RESET) && (FSL_FEATURE_PUF_HAS_NO_RESET > 0))
0274     RESET_SetPeripheralReset(kPUF_RST_SHIFT_RSTn);
0275 #endif /* FSL_FEATURE_PUF_HAS_NO_RESET */
0276
0277 #if !(defined(FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL) && FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL)
0278     CLOCK_DisableClock(kCLOCK_Puf);
0279 #endif
0280 }
0281
0282 /*!
0283  * brief Enroll PUF
0284  *
0285  * This function derives a digital fingerprint, generates the corresponding Activation Code (AC)
0286  * and returns it to be stored in an NVM or a file. This step needs to be
0287  * performed only once for each device. This function may be permanently disallowed by a fuse.
0288  *
0289  * param base PUF peripheral base address
0290  * param[out] activationCode Word aligned address of the resulting activation code.
0291  * param activationCodeSize Size of the activationCode buffer in bytes. Shall be 1192 bytes.
0292  * return Status of enroll operation.
0293  */
0294 status_t PUF_Enroll(PUF_Type *base, uint8_t *activationCode, size_t activationCodeSize)
0295 {
0296     status_t status                 = kStatus_Fail;
0297     uint32_t *activationCodeAligned = NULL;
0298     register uint32_t temp32        = 0;
0299
0300     /* check that activation code buffer size is at least 1192 bytes */
0301     if (activationCodeSize < PUF_ACTIVATION_CODE_SIZE)
0302     {
0303         return kStatus_InvalidArgument;
0304     }
0305
0306     /* only work with aligned activationCode */
0307     if (0U != (0x3u & (uintptr_t)activationCode))
0308     {
0309         return kStatus_InvalidArgument;
0310     }
0311
0312     activationCodeAligned = (uint32_t *)(uintptr_t)activationCode;
0313
0314     /* check if ENROLL is allowed */
0315     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWENROLL_MASK))
0316     {
0317         return kStatus_EnrollNotAllowed;
0318     }
0319
0320     /* begin */
0321     base->CTRL = PUF_CTRL_ENROLL_MASK;
0322
0323     /* check status */
0324     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0325     {
0326     }
0327
0328     /* read out AC */
0329     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0330     {
0331         if (0U != (PUF_STAT_CODEOUTAVAIL_MASK & base->STAT))
0332         {
0333             temp32 = base->CODEOUTPUT;
0334             if (activationCodeSize >= sizeof(uint32_t))
0335             {
0336                 *activationCodeAligned = temp32;
0337                 activationCodeAligned++;
0338                 activationCodeSize -= sizeof(uint32_t);
0339             }
0340         }
0341     }
0342
0343     if (((base->STAT & PUF_STAT_SUCCESS_MASK) != 0U) && (activationCodeSize == 0U))
0344     {
0345         status = kStatus_Success;
0346     }
0347
0348     return status;
0349 }
0350
0351 /*!
0352  * brief Start PUF
0353  *
0354  * The Activation Code generated during the Enroll operation is used to
0355  * reconstruct the digital fingerprint. This needs to be done after every power-up
0356  * and reset.
0357  *
0358  * param base PUF peripheral base address
0359  * param activationCode Word aligned address of the input activation code.
0360  * param activationCodeSize Size of the activationCode buffer in bytes. Shall be 1192 bytes.
0361  * return Status of start operation.
0362  */
0363 status_t PUF_Start(PUF_Type *base, const uint8_t *activationCode, size_t activationCodeSize)
0364 {
0365     status_t status                       = kStatus_Fail;
0366     const uint32_t *activationCodeAligned = NULL;
0367     register uint32_t temp32              = 0;
0368
0369     /* check that activation code size is at least 1192 bytes */
0370     if (activationCodeSize < 1192U)
0371     {
0372         return kStatus_InvalidArgument;
0373     }
0374
0375     /* only work with aligned activationCode */
0376     if (0U != (0x3u & (uintptr_t)activationCode))
0377     {
0378         return kStatus_InvalidArgument;
0379     }
0380
0381     activationCodeAligned = (const uint32_t *)(uintptr_t)activationCode;
0382
0383     /* check if START is allowed */
0384     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWSTART_MASK))
0385     {
0386         return kStatus_StartNotAllowed;
0387     }
0388
0389     /* begin */
0390     base->CTRL = PUF_CTRL_START_MASK;
0391
0392     /* check status */
0393     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0394     {
0395     }
0396
0397     /* while busy send AC */
0398     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0399     {
0400         if (0U != (PUF_STAT_CODEINREQ_MASK & base->STAT))
0401         {
0402             if (activationCodeSize >= sizeof(uint32_t))
0403             {
0404                 temp32 = *activationCodeAligned;
0405                 activationCodeAligned++;
0406                 activationCodeSize -= sizeof(uint32_t);
0407             }
0408             base->CODEINPUT = temp32;
0409         }
0410     }
0411
0412     /* get status */
0413     if (0U != (base->STAT & PUF_STAT_SUCCESS_MASK))
0414     {
0415         status = kStatus_Success;
0416     }
0417
0418     return status;
0419 }
0420
0421 /*!
0422  * brief Set intrinsic key
0423  *
0424  * The digital fingerprint generated during the Enroll/Start
0425  * operations is used to generate a Key Code (KC) that defines a unique intrinsic
0426  * key. This KC is returned to be stored in an NVM or a file. This operation
0427  * needs to be done only once for each intrinsic key.
0428  * Each time a Set Intrinsic Key operation is executed a new unique key is
0429  * generated.
0430  *
0431  * param base PUF peripheral base address
0432  * param keyIndex PUF key index register
0433  * param keySize Size of the intrinsic key to generate in bytes.
0434  * param[out] keyCode Word aligned address of the resulting key code.
0435  * param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
0436  * return Status of set intrinsic key operation.
0437  */
0438 status_t PUF_SetIntrinsicKey(
0439     PUF_Type *base, puf_key_index_register_t keyIndex, size_t keySize, uint8_t *keyCode, size_t keyCodeSize)
0440 {
0441     status_t status          = kStatus_Fail;
0442     uint32_t *keyCodeAligned = NULL;
0443     register uint32_t temp32 = 0;
0444
0445     /* check if SET KEY is allowed */
0446     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWSETKEY_MASK))
0447     {
0448         return kStatus_Fail;
0449     }
0450
0451     /* only work with aligned keyCode */
0452     if (0U != (0x3u & (uintptr_t)keyCode))
0453     {
0454         return kStatus_InvalidArgument;
0455     }
0456
0457     /* Check that keySize is in the correct range and that it is multiple of 8 */
0458     if ((keySize < (uint32_t)kPUF_KeySizeMin) || (keySize > (uint32_t)kPUF_KeySizeMax) || (0U != (keySize & 0x7U)))
0459     {
0460         return kStatus_InvalidArgument;
0461     }
0462
0463     /* check that keyCodeSize is correct for given keySize */
0464     if (keyCodeSize < PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize))
0465     {
0466         return kStatus_InvalidArgument;
0467     }
0468
0469     if ((uint32_t)keyIndex > (uint32_t)kPUF_KeyIndexMax)
0470     {
0471         return kStatus_InvalidArgument;
0472     }
0473
0474     keyCodeAligned = (uint32_t *)(uintptr_t)keyCode;
0475
0476     /* program the key size and index */
0477     base->KEYSIZE  = keySize >> 3;
0478     base->KEYINDEX = (uint32_t)keyIndex;
0479
0480     /* begin */
0481     base->CTRL = PUF_CTRL_GENERATEKEY_MASK;
0482
0483     /* wait till command is accepted */
0484     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0485     {
0486     }
0487
0488     /* while busy read KC */
0489     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0490     {
0491         if (0U != (PUF_STAT_CODEOUTAVAIL_MASK & base->STAT))
0492         {
0493             temp32 = base->CODEOUTPUT;
0494             if (keyCodeSize >= sizeof(uint32_t))
0495             {
0496                 *keyCodeAligned = temp32;
0497                 keyCodeAligned++;
0498                 keyCodeSize -= sizeof(uint32_t);
0499             }
0500         }
0501     }
0502
0503     /* get status */
0504     if (0U != (base->STAT & PUF_STAT_SUCCESS_MASK))
0505     {
0506         status = kStatus_Success;
0507     }
0508
0509     return status;
0510 }
0511
0512 /*!
0513  * brief Set user key
0514  *
0515  * The digital fingerprint generated during the Enroll/Start
0516  * operations and a user key (UK) provided as input are used to
0517  * generate a Key Code (KC). This KC is sent returned to be stored
0518  * in an NVM or a file. This operation needs to be done only once for each user key.
0519  *
0520  * param base PUF peripheral base address
0521  * param keyIndex PUF key index register
0522  * param userKey Word aligned address of input user key.
0523  * param userKeySize Size of the input user key in bytes.
0524  * param[out] keyCode Word aligned address of the resulting key code.
0525  * param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(userKeySize).
0526  * return Status of set user key operation.
0527  */
0528 status_t PUF_SetUserKey(PUF_Type *base,
0529                         puf_key_index_register_t keyIndex,
0530                         const uint8_t *userKey,
0531                         size_t userKeySize,
0532                         uint8_t *keyCode,
0533                         size_t keyCodeSize)
0534 {
0535     status_t status                = kStatus_Fail;
0536     uint32_t *keyCodeAligned       = NULL;
0537     const uint32_t *userKeyAligned = NULL;
0538     register uint32_t temp32       = 0;
0539
0540     /* check if SET KEY is allowed */
0541     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWSETKEY_MASK))
0542     {
0543         return kStatus_Fail;
0544     }
0545
0546     /* only work with aligned keyCode */
0547     if (0U != (0x3u & (uintptr_t)keyCode))
0548     {
0549         return kStatus_InvalidArgument;
0550     }
0551
0552     /* Check that userKeySize is in the correct range and that it is multiple of 8 */
0553     if ((userKeySize < (uint32_t)kPUF_KeySizeMin) || (userKeySize > (uint32_t)kPUF_KeySizeMax) ||
0554         (0U != (userKeySize & 0x7U)))
0555     {
0556         return kStatus_InvalidArgument;
0557     }
0558
0559     /* check that keyCodeSize is correct for given userKeySize */
0560     if (keyCodeSize < PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(userKeySize))
0561     {
0562         return kStatus_InvalidArgument;
0563     }
0564
0565     if ((uint32_t)keyIndex > (uint32_t)kPUF_KeyIndexMax)
0566     {
0567         return kStatus_InvalidArgument;
0568     }
0569
0570     keyCodeAligned = (uint32_t *)(uintptr_t)keyCode;
0571     userKeyAligned = (const uint32_t *)(uintptr_t)userKey;
0572
0573     /* program the key size and index */
0574     base->KEYSIZE  = userKeySize >> 3; /* convert to 64-bit blocks */
0575     base->KEYINDEX = (uint32_t)keyIndex;
0576
0577     /* We have to store the user key on index 0 swaped for HW bus */
0578     if (keyIndex == kPUF_KeyIndex_00)
0579     {
0580         userKeyAligned = userKeyAligned + (userKeySize / sizeof(uint32_t));
0581     }
0582
0583     /* begin */
0584     base->CTRL = PUF_CTRL_SETKEY_MASK;
0585
0586     /* wait till command is accepted */
0587     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0588     {
0589     }
0590
0591     /* while busy write UK and read KC */
0592     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0593     {
0594         if (0U != (PUF_STAT_KEYINREQ_MASK & base->STAT))
0595         {
0596             if (userKeySize >= sizeof(uint32_t))
0597             {
0598 #if defined(LPC54S018_SERIES)
0599                 if (keyIndex == kPUF_KeyIndex_00)
0600                 {
0601                     userKeyAligned--;
0602                     temp32 = *userKeyAligned;
0603                     userKeySize -= sizeof(uint32_t);
0604                 }
0605 #else
0606                 if (keyIndex == kPUF_KeyIndex_00)
0607                 {
0608                     userKeyAligned--;
0609                     temp32 = __REV(*userKeyAligned);
0610                     userKeySize--;
0611                 }
0612 #endif /* defined(LPC54S018_SERIES) */
0613                 else if (keyIndex != kPUF_KeyIndex_00)
0614                 {
0615                     temp32 = *userKeyAligned;
0616                     userKeyAligned++;
0617                     userKeySize -= sizeof(uint32_t);
0618                 }
0619                 else
0620                 {
0621                     /* Intentional empty */
0622                 }
0623             }
0624             base->KEYINPUT = temp32;
0625         }
0626
0627         if (0U != (PUF_STAT_CODEOUTAVAIL_MASK & base->STAT))
0628         {
0629             temp32 = base->CODEOUTPUT;
0630             if (keyCodeSize >= sizeof(uint32_t))
0631             {
0632                 *keyCodeAligned = temp32;
0633                 keyCodeAligned++;
0634                 keyCodeSize -= sizeof(uint32_t);
0635             }
0636         }
0637     }
0638
0639     /* get status */
0640     if (0U != (base->STAT & PUF_STAT_SUCCESS_MASK))
0641     {
0642         status = kStatus_Success;
0643     }
0644
0645     return status;
0646 }
0647
0648 static status_t puf_getHwKey(PUF_Type *base, const uint8_t *keyCode, size_t keyCodeSize)
0649 {
0650     status_t status          = kStatus_Fail;
0651     uint32_t *keyCodeAligned = NULL;
0652     register uint32_t temp32 = 0;
0653
0654     keyCodeAligned = (uint32_t *)(uintptr_t)keyCode;
0655
0656     /* begin */
0657     base->CTRL = PUF_CTRL_GETKEY_MASK;
0658
0659     /* wait till command is accepted */
0660     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0661     {
0662     }
0663
0664     /* while busy send KC, key is reconstructed to HW bus */
0665     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0666     {
0667         if (0U != (PUF_STAT_CODEINREQ_MASK & base->STAT))
0668         {
0669             if (keyCodeSize >= sizeof(uint32_t))
0670             {
0671                 temp32 = *keyCodeAligned;
0672                 keyCodeAligned++;
0673                 keyCodeSize -= sizeof(uint32_t);
0674             }
0675             base->CODEINPUT = temp32;
0676         }
0677     }
0678
0679     /* get status */
0680     if (0U != (base->STAT & PUF_STAT_SUCCESS_MASK))
0681     {
0682         status = kStatus_Success;
0683     }
0684
0685     return status;
0686 }
0687
0688 /*!
0689  * brief Reconstruct hw bus key from a key code
0690  *
0691  * The digital fingerprint generated during the Start operation and the KC
0692  * generated during a Set Key operation (Set intrinsic key or Set user key) are used to retrieve a stored key. This
0693  * operation needs to be done every time a key is needed.
0694  * This function accepts only Key Codes created for PUF index register kPUF_KeyIndex_00.
0695  * Such a key is output directly to a dedicated hardware bus. The reconstructed key is not exposed to system memory.
0696  *
0697  * param base PUF peripheral base address
0698  * param keyCode Word aligned address of the input key code.
0699  * param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
0700  * param keySlot key slot to output on hw bus. Parameter is ignored on devices with less than two key slots.
0701  * param keyMask key masking value. Shall be random for each POR/reset. Value does not have to be cryptographicaly
0702  * secure.
0703  * return Status of get key operation.
0704  */
0705 status_t PUF_GetHwKey(
0706     PUF_Type *base, const uint8_t *keyCode, size_t keyCodeSize, puf_key_slot_t keySlot, uint32_t keyMask)
0707 {
0708     status_t status = kStatus_Fail;
0709     uint32_t keyIndex;
0710
0711     /* check if GET KEY is allowed */
0712     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWGETKEY_MASK))
0713     {
0714         return kStatus_Fail;
0715     }
0716
0717     /* only work with aligned keyCode */
0718     if (0U != (0x3u & (uintptr_t)keyCode))
0719     {
0720         return kStatus_Fail;
0721     }
0722
0723     /* check that keyCodeSize is at least PUF_MIN_KEY_CODE_SIZE */
0724     if (keyCodeSize < PUF_MIN_KEY_CODE_SIZE)
0725     {
0726         return kStatus_InvalidArgument;
0727     }
0728
0729     keyIndex = (uint32_t)(0x0Fu & (uint32_t)keyCode[1]);
0730
0731     /* check the Key Code header byte 1. index must be zero for the hw key. */
0732     if (kPUF_KeyIndex_00 != (puf_key_index_register_t)keyIndex)
0733     {
0734         return kStatus_Fail;
0735     }
0736
0737 #if defined(PUF_KEYMASK_COUNT) && (PUF_KEYMASK_COUNT > 0)
0738     volatile uint32_t *keyMask_reg = NULL;
0739     uint32_t regVal                = ((uint32_t)2U << ((uint32_t)2U * (uint32_t)keySlot));
0740
0741     switch (keySlot)
0742     {
0743         case kPUF_KeySlot0:
0744             keyMask_reg = &base->KEYMASK[0];
0745             break;
0746
0747         case kPUF_KeySlot1:
0748             keyMask_reg = &base->KEYMASK[1];
0749             break;
0750 #if (PUF_KEYMASK_COUNT > 2)
0751         case kPUF_KeySlot2:
0752             keyMask_reg = &base->KEYMASK[2];
0753             break;
0754
0755         case kPUF_KeySlot3:
0756             keyMask_reg = &base->KEYMASK[3];
0757             break;
0758 #endif /* PUF_KEYMASK_COUNT > 2 */
0759         default:
0760             status = kStatus_InvalidArgument;
0761             break;
0762     }
0763 #endif /* PUF_KEYMASK_COUNT */
0764
0765     if (status != kStatus_InvalidArgument)
0766     {
0767 #if defined(PUF_KEYMASK_COUNT) && (PUF_KEYMASK_COUNT > 0)
0768         base->KEYRESET  = regVal;
0769         base->KEYENABLE = regVal;
0770         *keyMask_reg    = keyMask;
0771 #endif /* FSL_FEATURE_PUF_HAS_KEYSLOTS */
0772
0773         status = puf_getHwKey(base, keyCode, keyCodeSize);
0774
0775 #if defined(FSL_FEATURE_PUF_HAS_SHIFT_STATUS) && (FSL_FEATURE_PUF_HAS_SHIFT_STATUS > 0)
0776         size_t keyWords = 0;
0777
0778         if (status == kStatus_Success)
0779         {
0780             /* if the corresponding shift count does not match, return fail anyway */
0781             keyWords = ((((size_t)keyCode[3]) * 2U) - 1u) << ((size_t)keySlot << 2U);
0782             if (keyWords != ((0x0FUL << ((uint32_t)keySlot << 2U)) & base->SHIFT_STATUS))
0783             {
0784                 status = kStatus_Fail;
0785             }
0786         }
0787 #elif defined(PUF_IDXBLK_SHIFT_IND_KEY0_MASK) && PUF_IDXBLK_SHIFT_IND_KEY0_MASK
0788         size_t keyWords = 0;
0789
0790         if (status == kStatus_Success)
0791         {
0792             /* if the corresponding shift count does not match, return fail anyway */
0793             keyWords = ((((size_t)keyCode[3]) * 2U) - 1u) << ((size_t)keySlot << 2U);
0794             if (keyWords != ((0x0FUL << ((uint32_t)keySlot << 2U)) & base->IDXBLK_SHIFT))
0795             {
0796                 status = kStatus_Fail;
0797             }
0798         }
0799 #endif /* FSL_FEATURE_PUF_HAS_SHIFT_STATUS || PUF_IDXBLK_SHIFT_IND_KEY0_MASK */
0800     }
0801
0802     return status;
0803 }
0804
0805 /*!
0806  * brief Checks if Get Key operation is allowed.
0807  *
0808  * This function returns true if get key operation is allowed.
0809  *
0810  * param base PUF peripheral base address
0811  * return true if get key operation is allowed
0812  */
0813 bool PUF_IsGetKeyAllowed(PUF_Type *base)
0814 {
0815     /* check if GET KEY is allowed */
0816     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWGETKEY_MASK))
0817     {
0818         return false;
0819     }
0820
0821     return true;
0822 }
0823
0824 /*!
0825  * brief Reconstruct key from a key code
0826  *
0827  * The digital fingerprint generated during the Start operation and the KC
0828  * generated during a Set Key operation (Set intrinsic key or Set user key) are used to retrieve a stored key. This
0829  * operation needs to be done every time a key is needed.
0830  * This function accepts only Key Codes created for PUF index registers kPUF_KeyIndex_01 to kPUF_KeyIndex_15.
0831  *
0832  * param base PUF peripheral base address
0833  * param keyCode Word aligned address of the input key code.
0834  * param keyCodeSize Size of the keyCode buffer in bytes. Shall be PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize).
0835  * param[out] key Word aligned address of output key.
0836  * param keySize Size of the output key in bytes.
0837  * return Status of get key operation.
0838  */
0839 status_t PUF_GetKey(PUF_Type *base, const uint8_t *keyCode, size_t keyCodeSize, uint8_t *key, size_t keySize)
0840 {
0841     status_t status          = kStatus_Fail;
0842     uint32_t *keyCodeAligned = NULL;
0843     uint32_t *keyAligned     = NULL;
0844     uint32_t keyIndex;
0845     register uint32_t temp32 = 0;
0846
0847     /* check if GET KEY is allowed */
0848     if (0x0u == (base->ALLOW & PUF_ALLOW_ALLOWGETKEY_MASK))
0849     {
0850         return kStatus_Fail;
0851     }
0852
0853     /* only work with aligned keyCode */
0854     if (0U != (0x3u & (uintptr_t)keyCode))
0855     {
0856         return kStatus_Fail;
0857     }
0858
0859     /* only work with aligned key */
0860     if (0U != (0x3u & (uintptr_t)key))
0861     {
0862         return kStatus_Fail;
0863     }
0864
0865     /* check that keyCodeSize is correct for given keySize */
0866     if (keyCodeSize < PUF_GET_KEY_CODE_SIZE_FOR_KEY_SIZE(keySize))
0867     {
0868         return kStatus_InvalidArgument;
0869     }
0870
0871     keyIndex = (0x0Fu & (uint32_t)keyCode[1]);
0872
0873     /* check the Key Code header byte 1. index must be non-zero for the register key. */
0874     if (kPUF_KeyIndex_00 == (puf_key_index_register_t)keyIndex)
0875     {
0876         return kStatus_Fail;
0877     }
0878
0879     keyCodeAligned = (uint32_t *)(uintptr_t)keyCode;
0880     keyAligned     = (uint32_t *)(uintptr_t)key;
0881
0882     /* begin */
0883     base->CTRL = PUF_CTRL_GETKEY_MASK;
0884
0885     /* wait till command is accepted */
0886     while (0U == (base->STAT & (PUF_STAT_BUSY_MASK | PUF_STAT_ERROR_MASK)))
0887     {
0888     }
0889
0890     /* while busy send KC, read key */
0891     while (0U != (base->STAT & PUF_STAT_BUSY_MASK))
0892     {
0893         if (0U != (PUF_STAT_CODEINREQ_MASK & base->STAT))
0894         {
0895             temp32 = 0;
0896             if (keyCodeSize >= sizeof(uint32_t))
0897             {
0898                 temp32 = *keyCodeAligned;
0899                 keyCodeAligned++;
0900                 keyCodeSize -= sizeof(uint32_t);
0901             }
0902             base->CODEINPUT = temp32;
0903         }
0904
0905         if (0U != (PUF_STAT_KEYOUTAVAIL_MASK & base->STAT))
0906         {
0907             keyIndex = base->KEYOUTINDEX;
0908             temp32   = base->KEYOUTPUT;
0909             if (keySize >= sizeof(uint32_t))
0910             {
0911                 *keyAligned = temp32;
0912                 keyAligned++;
0913                 keySize -= sizeof(uint32_t);
0914             }
0915         }
0916     }
0917
0918     /* get status */
0919     if ((keyIndex != 0U) && (0U != (base->STAT & PUF_STAT_SUCCESS_MASK)))
0920     {
0921         status = kStatus_Success;
0922     }
0923
0924     return status;
0925 }
0926
0927 /*!
0928  * brief Zeroize PUF
0929  *
0930  * This function clears all PUF internal logic and puts the PUF to error state.
0931  *
0932  * param base PUF peripheral base address
0933  * return Status of the zeroize operation.
0934  */
0935 status_t PUF_Zeroize(PUF_Type *base)
0936 {
0937     status_t status = kStatus_Fail;
0938
0939     /* zeroize command is always allowed */
0940     base->CTRL = PUF_CTRL_ZEROIZE_MASK;
0941
0942     /* check that command is accepted */
0943     if ((0U != (base->STAT & PUF_STAT_ERROR_MASK)) && (0U == base->ALLOW))
0944     {
0945         status = kStatus_Success;
0946     }
0947
0948     return status;
0949 }