1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #pragma once
18 
19 #include <lk/compiler.h>
20 #include <lk/macros.h>
21 #include <stddef.h>
22 #include <stdint.h>
23 
24 #define KEYBOX_PORT "com.android.trusty.hwkeybox"
25 
26 /**
27  * enum keybox_cmd - Keybox service commands
28  *
29  * @KEYBOX_CMD_REQ_SHIFT: bitshift of the command index
30  * @KEYBOX_CMD_RSP_BIT: bit indicating that this is a response
31  * @KEYBOX_CMD_UNWRAP: Unwrap the provided keybox.
32  */
33 enum keybox_cmd {
34     KEYBOX_CMD_REQ_SHIFT = 1,
35     KEYBOX_CMD_RSP_BIT = 1,
36     KEYBOX_CMD_UNWRAP = 0 << KEYBOX_CMD_REQ_SHIFT,
37 };
38 
39 /**
40  * enum keybox_status - Keybox response code
41  *
42  * @KEYBOX_STATUS_SUCCESS:         Keybox successfully decrypted.
43  * @KEYBOX_STATUS_INVALID_REQUEST: Arguments don't validate.
44  * @KEYBOX_STATUS_UNWRAP_FAIL:     Failed to unwrap keybox.
45  * @KEYBOX_STATUS_FORBIDDEN:       Process requesting decryption should not
46  *                                 receive this keybox.
47  * @KEYBOX_STATUS_INTERNAL_ERROR:  An internal error occurred. Please report a bug.
48  */
49 enum keybox_status {
50     KEYBOX_STATUS_SUCCESS = 0,
51     KEYBOX_STATUS_INVALID_REQUEST = 1,
52     KEYBOX_STATUS_UNWRAP_FAIL = 2,
53     KEYBOX_STATUS_FORBIDDEN = 3,
54     KEYBOX_STATUS_INTERNAL_ERROR = 4,
55 };
56 
57 /**
58  * KEYBOX_MAX_SIZE - Maximum size of a keybox to be unwrapped by the service.
59  */
60 #define KEYBOX_MAX_SIZE 2048
61 
62 /**
63  * struct keybox_req - Keybox request message
64  *
65  * @cmd: Which command the keybox service should execute. Should be
66  *       an &enum keybox_command
67  * @reserved: MBZ
68  *
69  * This structure is used as a message header and is followed by a payload that
70  * has a command-specific meaning.
71  */
72 struct keybox_req {
73     uint32_t cmd;
74     uint32_t reserved;
75 };
76 
77 /**
78  * struct keybox_unwrap_req - Keybox unwrap request message
79  *
80  * @wrapped_keybox_len: The length of the wrapped keybox.
81  *
82  * The wrapped keybox follows.
83  */
84 struct keybox_unwrap_req {
85     uint64_t wrapped_keybox_len;
86 };
87 
88 /**
89  * struct keybox_resp - Keybox response message
90  *
91  * @cmd:    The command this is a response to, with the @KEYBOX_CMD_RSP_BIT set.
92  *          See &enum keybox_command for values.
93  * @status: Whether the request succeeded, or how it failed. This is
94  *          represented by a &enum keybox_status value.
95  *
96  * If status == KEYBOX_STATUS_SUCCESS, the commmand response header will follow.
97  *
98  */
99 struct keybox_resp {
100     uint32_t cmd;
101     int32_t status;
102 };
103 
104 /**
105  * struct keybox_unwrap_resp - Keybox unwrap response message
106  *
107  * @unwrapped_keybox_len: The length of the unwrapped keybox.
108  *
109  * The unwrapped keybox follows.
110  */
111 struct keybox_unwrap_resp {
112     uint64_t unwrapped_keybox_len;
113 };
114