Software APIs
boot_svc_ownership_unlock.h
1 // Copyright lowRISC contributors (OpenTitan project).
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_BOOT_SVC_BOOT_SVC_OWNERSHIP_UNLOCK_H_
6 #define OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_BOOT_SVC_BOOT_SVC_OWNERSHIP_UNLOCK_H_
7 
8 #include <stdint.h>
9 
10 #include "sw/device/lib/base/macros.h"
11 #include "sw/device/silicon_creator/lib/base/chip.h"
12 #include "sw/device/silicon_creator/lib/boot_svc/boot_svc_header.h"
13 #include "sw/device/silicon_creator/lib/error.h"
14 #include "sw/device/silicon_creator/lib/nonce.h"
15 #include "sw/device/silicon_creator/lib/ownership/datatypes.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif // __cplusplus
20 
21 enum {
22  // ASCII: ANY
23  kBootSvcUnlockAny = 0x00594e41,
24  // ASCII: ENDO
25  kBootSvcUnlockEndorsed = 0x4f444e45,
26  // ASCII: UPD
27  kBootSvcUnlockUpdate = 0x00445055,
28  // ASCII: ABRT
29  kBootSvcUnlockAbort = 0x54524241,
30 
31  /** Ownership unlock request: `UNLK`. */
32  kBootSvcOwnershipUnlockReqType = 0x4b4c4e55,
33  /** Ownership unlock response: `KLNU`. */
34  kBootSvcOwnershipUnlockResType = 0x554e4c4b,
35 };
36 
37 /**
38  * An ownership unlock request.
39  */
40 typedef struct boot_svc_ownership_unlock_req {
41  /**
42  * Boot services message header.
43  */
44  boot_svc_header_t header;
45  /**
46  * Unlock mode: Any, Endorsed, Update or Abort.
47  */
48  uint32_t unlock_mode;
49  /**
50  * The 64-bit ID subfield of the full 256-bit device ID.
51  */
52  uint32_t din[2];
53  /**
54  * Reserved for future use.
55  */
56  uint32_t reserved[8];
57  /**
58  * The current ownership nonce.
59  */
60  nonce_t nonce;
61  /**
62  * The public key of the next owner (for endorsed mode).
63  */
64  owner_key_t next_owner_key;
65  /**
66  * Signature over [unlock_mode..next_owner_key]
67  */
68  owner_signature_t signature;
69 
70 } boot_svc_ownership_unlock_req_t;
71 
72 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, header, 0);
73 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, unlock_mode,
74  CHIP_BOOT_SVC_MSG_HEADER_SIZE);
75 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, din,
76  CHIP_BOOT_SVC_MSG_HEADER_SIZE + 4);
77 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, reserved,
78  CHIP_BOOT_SVC_MSG_HEADER_SIZE + 12);
79 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, nonce,
80  CHIP_BOOT_SVC_MSG_HEADER_SIZE + 44);
81 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, next_owner_key,
82  CHIP_BOOT_SVC_MSG_HEADER_SIZE + 52);
83 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, signature,
84  CHIP_BOOT_SVC_MSG_HEADER_SIZE + 148);
85 OT_ASSERT_SIZE(boot_svc_ownership_unlock_req_t, 256);
86 
87 /**
88  * An ownership unlock response.
89  */
90 typedef struct boot_svc_ownership_unlock_res {
91  /**
92  * Boot services message header.
93  */
94  boot_svc_header_t header;
95  /**
96  * Response status from the ROM_EXT.
97  */
98  rom_error_t status;
99 } boot_svc_ownership_unlock_res_t;
100 
101 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_res_t, header, 0);
102 OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_res_t, status,
103  CHIP_BOOT_SVC_MSG_HEADER_SIZE);
104 OT_ASSERT_SIZE(boot_svc_ownership_unlock_res_t, 48);
105 
106 /**
107  * Initialize an ownership unlock request.
108  *
109  * @param[out] msg Output buffer for the message.
110  */
111 void boot_svc_ownership_unlock_req_init(uint32_t unlock_mode, nonce_t nonce,
112  const owner_key_t *next_owner_key,
113  const owner_signature_t *signature,
114  boot_svc_ownership_unlock_req_t *msg);
115 
116 /**
117  * Initialize an ownership unlock response.
118  *
119  * @param status Reponse from the ROM_EXT after receiving the request.
120  * @param[out] msg Output buffer for the message.
121  */
122 void boot_svc_ownership_unlock_res_init(rom_error_t status,
123  boot_svc_ownership_unlock_res_t *msg);
124 
125 #ifdef __cplusplus
126 } // extern "C"
127 #endif // __cplusplus
128 
129 #endif // OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_BOOT_SVC_BOOT_SVC_OWNERSHIP_UNLOCK_H_
Return to OpenTitan Documentation