VirtualBox

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

Last change on this file since 72090 was 69500, checked in by vboxsync, 7 years ago

*: scm --update-copyright-year

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