1 /*
2  * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 /*!
8  @addtogroup cc_util_asset_prov
9  @{
10 */
11 
12 /*!
13  @file mbedtls_cc_util_asset_prov.h
14  @brief This file contains CryptoCell runtime-library ICV and OEM asset-provisioning APIs and definitions.
15  */
16 
17 
18 #ifndef  _MBEDTLS_CC_UTIL_ASSET_PROV_H
19 #define  _MBEDTLS_CC_UTIL_ASSET_PROV_H
20 
21 #ifdef __cplusplus
22 extern "C"
23 {
24 #endif
25 #include "cc_pal_types_plat.h"
26 
27 /*! The maximal size of an asset package. */
28 #define CC_ASSET_PROV_MAX_ASSET_PKG_SIZE  4144
29 
30 /*! The type of key used to pack the asset. */
31 typedef enum {
32        /*! The ICV provisioning key (Kpicv) key was used to pack the asset. */
33        ASSET_PROV_KEY_TYPE_KPICV = 1,
34        /*! The OEM provisioning key (Kcp) key was used to pack the asset. */
35        ASSET_PROV_KEY_TYPE_KCP = 2,
36        /*! Reserved. */
37        ASSET_PROV_KEY_TYPE_RESERVED    = 0x7FFFFFFF,
38 } CCAssetProvKeyType_t;
39 
40 
41 /*!
42  @brief This function securely provisions ICV or OEM assets to devices using
43  CryptoCell.
44 
45  The function:
46  <ol>
47  <li>Receives an encrypted and autenticated asset package.
48  \note This asset package is produced by the ICV or OEM asset-packaging
49  offline utility (using AES-CCM with key derived from Kpicv or Kcp
50  respectively, and the asset identifier).</li>
51  <li>Authenticates the asset package.</li>
52  <li>Decrypts the asset package.</li>
53  <li>Returns the decrypted asset data to the caller.</li></ol>
54 
55  @note  The function is valid in all life-cycle states. However, an error
56  is returned if the requested key is locked.
57 
58  @return \c CC_UTIL_OK on success.
59  @return A non-zero value on failure, as defined in cc_util_error.h.
60  */
61 CCError_t mbedtls_util_asset_pkg_unpack(
62         /*! [in] The type of key used to pack the asset.*/
63         CCAssetProvKeyType_t        keyType,
64         /*! [in] A 32-bit index identifying the asset, in big-endian order. */
65         uint32_t                    assetId,
66         /*! [in] The encrypted and authenticated asset package. */
67         uint32_t                    *pAssetPackage,
68         /*! [in] The length of the asset package. Must not exceed
69         CC_ASSET_PROV_MAX_ASSET_PKG_SIZE. */
70         size_t                      assetPackageLen,
71         /*! [out] The buffer for retrieving the decrypted asset data. */
72         uint32_t                    *pAssetData,
73         /*! [in, out] In: The size of the available asset-data buffer. Maximal
74         size is 4KB. Out: A pointer to the actual length of the decrypted
75         asset data. */
76         size_t                      *pAssetDataLen
77         );
78 
79 
80 #ifdef __cplusplus
81 }
82 #endif
83 
84 /*!
85  @}
86  */
87 #endif /*_MBEDTLS_CC_UTIL_ASSET_PROV_H*/
88 
89