VirtualBox

source: vbox/trunk/include/VBox/VBoxCryptoIf.h@ 99578

Last change on this file since 99578 was 98103, checked in by vboxsync, 2 years ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.1 KB
Line 
1/** @file
2 * VirtualBox - Cryptographic support functions Interface.
3 */
4
5/*
6 * Copyright (C) 2022-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef VBOX_INCLUDED_VBoxCryptoIf_h
37#define VBOX_INCLUDED_VBoxCryptoIf_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/vfs.h>
43#include <VBox/types.h>
44
45/** An opaque VBox cryptographic context handle. */
46typedef struct VBOXCRYPTOCTXINT *VBOXCRYPTOCTX;
47/**Pointer to an opaque VBox cryptographic context handle. */
48typedef VBOXCRYPTOCTX *PVBOXCRYPTOCTX;
49
50/** Magic identifying the cryptographic interface (Charles Babbage). */
51#define VBOXCRYPTOIF_MAGIC UINT32_C(0x17911226)
52
53/** Pointer to const cryptographic interface. */
54typedef const struct VBOXCRYPTOIF *PCVBOXCRYPTOIF;
55/**
56 * The main cryptographic callbacks interface table.
57 */
58typedef struct VBOXCRYPTOIF
59{
60 /** Interface magic, set to VBOXCRYPTOIF_MAGIC. */
61 uint32_t u32Magic;
62 /** Interface version.
63 * This is set to VBOXCRYPTOIF_VERSION. */
64 uint32_t u32Version;
65 /** Description string. */
66 const char *pszDesc;
67
68 /** @name Generic crytographic context operations.
69 * @{ */
70
71 /**
72 * Creates a new cryptographic context for encryption.
73 *
74 * @returns VBox status code.
75 * @param pszCipher The identifier of the cipher to use.
76 * @param pszPassword Password for encrypting the context.
77 * @param phCryptoCtx Where to store the handle to the crypto context on success.
78 */
79 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxCreate, (const char *pszCipher, const char *pszPassword,
80 PVBOXCRYPTOCTX phCryptoCtx));
81
82 /**
83 * Creates a new cryptographic context for decryption from the given base-64 encoded context.
84 *
85 * @returns VBox status code.
86 * @param pszStoredCtx The base-64 encoded context to decrypt with the given password.
87 * @param pszPassword Password for encrypting the context.
88 * @param phCryptoCtx Where to store the handle to the crypto context on success.
89 */
90 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxLoad, (const char *pszStoredCtx, const char *pszPassword,
91 PVBOXCRYPTOCTX phCryptoCtx));
92
93 /**
94 * Destroys a previously created cryptographic context.
95 *
96 * @returns VBox status code.
97 * @param hCryptoCtx Handle of crpytographic context to destroy.
98 */
99 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxDestroy, (VBOXCRYPTOCTX hCryptoCtx));
100
101 /**
102 * Returns the given cryptographic context as a base-64 encoded string.
103 *
104 * @returns VBox status code.
105 * @param hCryptoCtx Handle of crpytographic context.
106 * @param ppszStoredCtx Where to store the base-64 encoded cryptographic context on success.
107 * Must be freed with RTMemFree() when not required anymore.
108 */
109 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxSave, (VBOXCRYPTOCTX hCryptoCtx, char **ppszStoredCtx));
110
111 /**
112 * Changes the encryption password for the given context.
113 *
114 * @returns VBox status code.
115 * @param hCryptoCtx Handle of crpytographic context.
116 * @param pszPassword New password used for encrypting the DEK.
117 */
118 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxPasswordChange, (VBOXCRYPTOCTX hCryptoCtx, const char *pszPassword));
119
120 /**
121 * Queries the required size of the output buffer for encrypted data. Depends on the cipher.
122 *
123 * @returns VBox status code.
124 * @param hCryptoCtx Handle of crpytographic context.
125 * @param cbPlainText The size of the data to be encrypted.
126 * @param pcbEncrypted Where to store the size in bytes of the encrypted data on success.
127 */
128 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxQueryEncryptedSize, (VBOXCRYPTOCTX hCryptoCtx, size_t cbPlaintext,
129 size_t *pcbEncrypted));
130
131 /**
132 * Queries the required size of the output buffer for decrypted data. Depends on the cipher.
133 *
134 * @returns VBox status code.
135 * @param hCryptoCtx Handle of crpytographic context.
136 * @param cbEncrypted The size of the encrypted chunk before decryption.
137 * @param pcbPlaintext Where to store the size in bytes of the decrypted data on success.
138 */
139 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxQueryDecryptedSize, (VBOXCRYPTOCTX hCryptoCtx, size_t cbEncrypted,
140 size_t *pcbPlaintext));
141
142 /**
143 * Encrypts data.
144 *
145 * @returns VBox status code.
146 * @param hCryptoCtx Handle of crpytographic context.
147 * @param fPartial Only part of data to be encrypted is specified. The encryption
148 * cipher context will not be closed. Set to false for last piece
149 * of data, or if data is specified completely.
150 * Only CTR mode supports partial encryption.
151 * @param pvIV Pointer to IV. If null it will be generated.
152 * @param cbIV Size of the IV.
153 * @param pvPlainText Data to encrypt.
154 * @param cbPlainText Size of the data in the pvPlainText.
155 * @param pvAuthData Data used for authenticate the pvPlainText
156 * @param cbAuthData Size of the pvAuthData
157 * @param pvEncrypted Buffer to store encrypted data
158 * @param cbEncrypted Size of the buffer in pvEncrypted
159 * @param pcbEncrypted Placeholder where the size of the encrypted data returned.
160 */
161 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxEncrypt, (VBOXCRYPTOCTX hCryptoCtx, bool fPartial, void const *pvIV, size_t cbIV,
162 void const *pvPlainText, size_t cbPlainText,
163 void const *pvAuthData, size_t cbAuthData,
164 void *pvEncrypted, size_t cbEncrypted,
165 size_t *pcbEncrypted));
166
167 /**
168 * Decrypts data.
169 *
170 * @returns VBox status code.
171 * @param hCryptoCtx Handle of crpytographic context.
172 * @param fPartial Only part of data to be encrypted is specified. The encryption
173 * cipher context will not be closed. Set to false for last piece
174 * of data, or if data is specified completely.
175 * Only CTR mode supports partial encryption.
176 * @param pvEncrypted Data to decrypt.
177 * @param cbEncrypted Size of the data in the pvEncrypted.
178 * @param pvAuthData Data used for authenticate the pvEncrypted
179 * @param cbAuthData Size of the pvAuthData
180 * @param pvPlainText Buffer to store decrypted data
181 * @param cbPlainText Size of the buffer in pvPlainText
182 * @param pcbPlainText Placeholder where the size of the decrypted data returned.
183 */
184 DECLR3CALLBACKMEMBER(int, pfnCryptoCtxDecrypt, (VBOXCRYPTOCTX hCryptoCtx, bool fPartial,
185 void const *pvEncrypted, size_t cbEncrypted,
186 void const *pvAuthData, size_t cbAuthData,
187 void *pvPlainText, size_t cbPlainText, size_t *pcbPlainText));
188 /** @} */
189
190 /** @name File based cryptographic operations.
191 * @{ */
192 /**
193 * Creates a new VFS file handle for an encrypted or to be encrypted file handle.
194 *
195 * @returns VBox status code.
196 * @param hVfsFile The input file handle, a new reference is retained upon success.
197 * @param pszKeyStore The key store containing the DEK used for encryption.
198 * @param pszPassword Password encrypting the DEK.
199 * @param phVfsFile Where to store the handle to the VFS file on success.
200 */
201 DECLR3CALLBACKMEMBER(int, pfnCryptoFileFromVfsFile, (RTVFSFILE hVfsFile, const char *pszKeyStore, const char *pszPassword,
202 PRTVFSFILE phVfsFile));
203
204 /**
205 * Opens a new encryption I/O stream.
206 *
207 * @returns VBox status code.
208 * @param hVfsIosDst The encrypted output stream (must be writeable).
209 * The reference is not consumed, instead another
210 * one is retained.
211 * @param pszKeyStore The key store containing the DEK used for encryption.
212 * @param pszPassword Password encrypting the DEK.
213 * @param phVfsIosCrypt Where to return the crypting input I/O stream handle
214 * (you write to this).
215 */
216 DECLR3CALLBACKMEMBER(int, pfnCryptoIoStrmFromVfsIoStrmEncrypt, (RTVFSIOSTREAM hVfsIosDst, const char *pszKeyStore,
217 const char *pszPassword, PRTVFSIOSTREAM phVfsIosCrypt));
218
219 /**
220 * Opens a new decryption I/O stream.
221 *
222 * @returns VBox status code.
223 * @param hVfsIosIn The encrypted input stream (must be readable).
224 * The reference is not consumed, instead another
225 * one is retained.
226 * @param pszKeyStore The key store containing the DEK used for encryption.
227 * @param pszPassword Password encrypting the DEK.
228 * @param phVfsIosOut Where to return the handle to the decrypted I/O stream (read).
229 */
230 DECLR3CALLBACKMEMBER(int, pfnCryptoIoStrmFromVfsIoStrmDecrypt, (RTVFSIOSTREAM hVfsIosIn, const char *pszKeyStore,
231 const char *pszPassword, PRTVFSIOSTREAM phVfsIosOut));
232 /** @} */
233
234 /** @name Keystore related functions.
235 * @{ */
236 /**
237 * Return the encryption parameters and DEK from the base64 encoded key store data.
238 *
239 * @returns VBox status code.
240 * @param pszEnc The base64 encoded key store data.
241 * @param pszPassword The password to use for key decryption.
242 * If the password is NULL only the cipher is returned.
243 * @param ppbKey Where to store the DEK on success.
244 * Must be freed with RTMemSaferFree().
245 * @param pcbKey Where to store the DEK size in bytes on success.
246 * @param ppszCipher Where to store the used cipher for the decrypted DEK.
247 * Must be freed with RTStrFree().
248 */
249 DECLR3CALLBACKMEMBER(int, pfnCryptoKeyStoreGetDekFromEncoded, (const char *pszEnc, const char *pszPassword,
250 uint8_t **ppbKey, size_t *pcbKey, char **ppszCipher));
251
252 /**
253 * Stores the given DEK in a key store protected by the given password.
254 *
255 * @returns VBox status code.
256 * @param pszPassword The password to protect the DEK.
257 * @param pbKey The DEK to protect.
258 * @param cbKey Size of the DEK to protect.
259 * @param pszCipher The cipher string associated with the DEK.
260 * @param ppszEnc Where to store the base64 encoded key store data on success.
261 * Must be freed with RTMemFree().
262 */
263 DECLR3CALLBACKMEMBER(int, pfnCryptoKeyStoreCreate, (const char *pszPassword, const uint8_t *pbKey, size_t cbKey,
264 const char *pszCipher, char **ppszEnc));
265 /** @} */
266
267 DECLR3CALLBACKMEMBER(int, pfnReserved1,(void)); /**< Reserved for minor structure revisions. */
268 DECLR3CALLBACKMEMBER(int, pfnReserved2,(void)); /**< Reserved for minor structure revisions. */
269 DECLR3CALLBACKMEMBER(int, pfnReserved3,(void)); /**< Reserved for minor structure revisions. */
270 DECLR3CALLBACKMEMBER(int, pfnReserved4,(void)); /**< Reserved for minor structure revisions. */
271 DECLR3CALLBACKMEMBER(int, pfnReserved5,(void)); /**< Reserved for minor structure revisions. */
272 DECLR3CALLBACKMEMBER(int, pfnReserved6,(void)); /**< Reserved for minor structure revisions. */
273
274 /** Reserved for minor structure revisions. */
275 uint32_t uReserved7;
276
277 /** End of structure marker (VBOXCRYPTOIF_VERSION). */
278 uint32_t u32EndMarker;
279} VBOXCRYPTOIF;
280/** Current version of the VBOXCRYPTOIF structure. */
281#define VBOXCRYPTOIF_VERSION RT_MAKE_U32(0, 1)
282
283
284/**
285 * The VBoxCrypto entry callback function.
286 *
287 * @returns VBox status code.
288 * @param ppCryptoIf Where to store the pointer to the crypto module interface callback table
289 * on success.
290 */
291typedef DECLCALLBACKTYPE(int, FNVBOXCRYPTOENTRY,(PCVBOXCRYPTOIF *ppCryptoIf));
292/** Pointer to a FNVBOXCRYPTOENTRY. */
293typedef FNVBOXCRYPTOENTRY *PFNVBOXCRYPTOENTRY;
294
295/** The name of the crypto module entry point. */
296#define VBOX_CRYPTO_MOD_ENTRY_POINT "VBoxCryptoEntry"
297
298
299/**
300 * Checks if cryptographic interface version is compatible.
301 *
302 * @returns true if the do, false if they don't.
303 * @param u32Provider The provider version.
304 * @param u32User The user version.
305 */
306#define VBOXCRYPTO_IS_VER_COMPAT(u32Provider, u32User) \
307 ( VBOXCRYPTO_IS_MAJOR_VER_EQUAL(u32Provider, u32User) \
308 && (int32_t)RT_LOWORD(u32Provider) >= (int32_t)RT_LOWORD(u32User) ) /* stupid casts to shut up gcc */
309
310/**
311 * Check if two cryptographic interface versions have the same major version.
312 *
313 * @returns true if the do, false if they don't.
314 * @param u32Ver1 The first version number.
315 * @param u32Ver2 The second version number.
316 */
317#define VBOXCRYPTO_IS_MAJOR_VER_EQUAL(u32Ver1, u32Ver2) (RT_HIWORD(u32Ver1) == RT_HIWORD(u32Ver2))
318
319#endif /* !VBOX_INCLUDED_VBoxCryptoIf_h */
320
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette