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
18extern "C" {
19#endif // __cplusplus
20
21enum {
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 */
40typedef 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
72OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, header, 0);
73OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, unlock_mode,
74 CHIP_BOOT_SVC_MSG_HEADER_SIZE);
75OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, din,
76 CHIP_BOOT_SVC_MSG_HEADER_SIZE + 4);
77OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, reserved,
78 CHIP_BOOT_SVC_MSG_HEADER_SIZE + 12);
79OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, nonce,
80 CHIP_BOOT_SVC_MSG_HEADER_SIZE + 44);
81OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, next_owner_key,
82 CHIP_BOOT_SVC_MSG_HEADER_SIZE + 52);
83OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_req_t, signature,
84 CHIP_BOOT_SVC_MSG_HEADER_SIZE + 148);
85OT_ASSERT_SIZE(boot_svc_ownership_unlock_req_t, 256);
86
87/**
88 * An ownership unlock response.
89 */
90typedef 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
101OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_res_t, header, 0);
102OT_ASSERT_MEMBER_OFFSET(boot_svc_ownership_unlock_res_t, status,
103 CHIP_BOOT_SVC_MSG_HEADER_SIZE);
104OT_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 */
111void 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 */
122void 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_