VBoxCryptoIf.h@ 94674

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: