VirtualBox

source: vbox/trunk/src/VBox/Main/include/SecretKeyStore.h@ 87093

Last change on this file since 87093 was 82968, checked in by vboxsync, 5 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: 5.9 KB
Line 
1/* $Id: SecretKeyStore.h 82968 2020-02-04 10:35:17Z vboxsync $ */
2/** @file
3 * Main - Secret key interface.
4 */
5
6/*
7 * Copyright (C) 2015-2020 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 */
17
18#ifndef MAIN_INCLUDED_SecretKeyStore_h
19#define MAIN_INCLUDED_SecretKeyStore_h
20#ifndef RT_WITHOUT_PRAGMA_ONCE
21# pragma once
22#endif
23
24#include "VirtualBoxBase.h"
25#include "VBox/com/array.h"
26
27class SecretKey
28{
29 public:
30
31 /**
32 * Constructor for a secret key.
33 *
34 * @param pbKey The key buffer.
35 * @param cbKey Size of the key.
36 * @param fKeyBufNonPageable Flag whether the key buffer should be non pageable.
37 */
38 SecretKey(const uint8_t *pbKey, size_t cbKey, bool fKeyBufNonPageable);
39
40 /**
41 * Secret key destructor.
42 */
43 ~SecretKey();
44
45 /**
46 * Increments the reference counter of the key.
47 *
48 * @returns The new reference count.
49 */
50 uint32_t retain();
51
52 /**
53 * Releases a reference of the key.
54 * If the reference counter reaches 0 the key buffer might be protected
55 * against further access or the data will become scrambled.
56 *
57 * @returns The new reference count.
58 */
59 uint32_t release();
60
61 /**
62 * Returns the reference count of the secret key.
63 */
64 uint32_t refCount();
65
66 /**
67 * Sets the possible number of users for this key.
68 *
69 * @returns VBox status code.
70 * @param cUsers The possible number of user for this key.
71 */
72 int setUsers(uint32_t cUsers);
73
74 /**
75 * Returns the possible amount of users.
76 *
77 * @returns Possible amount of users.
78 */
79 uint32_t getUsers();
80
81 /**
82 * Sets the remove on suspend flag.
83 *
84 * @returns VBox status code.
85 * @param fRemoveOnSuspend Flag whether to remove the key on host suspend.
86 */
87 int setRemoveOnSuspend(bool fRemoveOnSuspend);
88
89 /**
90 * Returns whether the key should be destroyed on suspend.
91 */
92 bool getRemoveOnSuspend();
93
94 /**
95 * Returns the buffer to the key.
96 */
97 const void *getKeyBuffer();
98
99 /**
100 * Returns the size of the key.
101 */
102 size_t getKeySize();
103
104 private:
105 /** Reference counter of the key. */
106 volatile uint32_t m_cRefs;
107 /** Key material. */
108 uint8_t *m_pbKey;
109 /** Size of the key in bytes. */
110 size_t m_cbKey;
111 /** Flag whether to remove the key on suspend. */
112 bool m_fRemoveOnSuspend;
113 /** Number of entities which will use this key. */
114 uint32_t m_cUsers;
115};
116
117class SecretKeyStore
118{
119 public:
120
121 /**
122 * Constructor for a secret key store.
123 *
124 * @param fKeyBufNonPageable Flag whether the key buffer is required to
125 * be non pageable.
126 */
127 SecretKeyStore(bool fKeyBufNonPageable);
128
129 /**
130 * Destructor of a secret key store. This will free all stored secret keys
131 * inluding the key buffers. Make sure there no one accesses one of the keys
132 * stored.
133 */
134 ~SecretKeyStore();
135
136 /**
137 * Add a secret key to the store.
138 *
139 * @returns VBox status code.
140 * @param strKeyId The key identifier.
141 * @param pbKey The key to store.
142 * @param cbKey Size of the key.
143 */
144 int addSecretKey(const com::Utf8Str &strKeyId, const uint8_t *pbKey, size_t cbKey);
145
146 /**
147 * Deletes a key from the key store associated with the given identifier.
148 *
149 * @returns VBox status code.
150 * @param strKeyId The key identifier.
151 */
152 int deleteSecretKey(const com::Utf8Str &strKeyId);
153
154 /**
155 * Returns the secret key object associated with the given identifier.
156 * This increments the reference counter of the secret key object.
157 *
158 * @returns VBox status code.
159 * @param strKeyId The key identifier.
160 * @param ppKey Where to store the secret key object on success.
161 */
162 int retainSecretKey(const com::Utf8Str &strKeyId, SecretKey **ppKey);
163
164 /**
165 * Releases a reference to the secret key object.
166 *
167 * @returns VBox status code.
168 * @param strKeyId The key identifier.
169 */
170 int releaseSecretKey(const com::Utf8Str &strKeyId);
171
172 /**
173 * Deletes all secret keys from the key store.
174 *
175 * @returns VBox status code.
176 * @param fSuspend Flag whether to delete only keys which are
177 * marked for deletion during a suspend.
178 * @param fForce Flag whether to force deletion if some keys
179 * are still in use. Otherwise an error is returned.
180 */
181 int deleteAllSecretKeys(bool fSuspend, bool fForce);
182
183 private:
184
185 typedef std::map<com::Utf8Str, SecretKey *> SecretKeyMap;
186
187 /** The map to map key identifers to secret keys. */
188 SecretKeyMap m_mapSecretKeys;
189 /** Flag whether key buffers should be non pagable. */
190 bool m_fKeyBufNonPageable;
191};
192
193#endif /* !MAIN_INCLUDED_SecretKeyStore_h */
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