001 /*
002 * Cumulus4j - Securing your data in the cloud - http://cumulus4j.org
003 * Copyright (C) 2011 NightLabs Consulting GmbH
004 *
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program. If not, see <http://www.gnu.org/licenses/>.
017 */
018 package org.cumulus4j.store.crypto;
019
020 import org.cumulus4j.store.model.EncryptionCoordinateSet;
021 import org.datanucleus.NucleusContext;
022
023 /**
024 * <p>
025 * {@link CryptoManager}s allow the Cumulus4j-DataNucleus-plug-in to encrypt and decrypt data.
026 * </p>
027 * <p>
028 * The primary purpose to make this feature pluggable is to provide different possibilities
029 * of the communication between the Cumulus4j-backend and a key store. For example, one client
030 * might prefer to manage the keys on the client while another client provides the coordinates
031 * of a key server to the backend.
032 * </p>
033 * <p>
034 * There is one shared instance of <code>CryptoManager</code> per {@link NucleusContext} and
035 * {@link #getCryptoManagerID() cryptoManagerID}. Due to this, instances of <code>CryptoManager</code>
036 * must be thread-safe!
037 * </p>
038 * <p>
039 * A <code>CryptoManager</code> must not be instantiated directly, but instead obtained via
040 * {@link CryptoManagerRegistry#getCryptoManager(String)}.
041 * </p>
042 * <p>
043 * <b>Important:</b> It is strongly recommended to subclass {@link AbstractCryptoManager} instead of
044 * directly implementing this interface!
045 * </p>
046 *
047 * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
048 */
049 public interface CryptoManager
050 {
051 /**
052 * <p>
053 * Property-name used to pass the {@link #getCryptoManagerID() cryptoManagerID} to the Cumulus4j-core.
054 * </p>
055 * <p>
056 * The property can either be set in the persistence-unit/persistence-properties-file for the
057 * <code>PersistenceManagerFactory</code>/<code>EntityManagerFactory</code> or it can be
058 * passed via
059 * {@link javax.jdo.PersistenceManager#setProperty(String, Object)} or
060 * {@link javax.persistence.EntityManager#setProperty(String, Object)}. If it is not set
061 * on the PM/EM level, the default-value set on the PMF/EMF level will be used.
062 * </p>
063 */
064 static final String PROPERTY_CRYPTO_MANAGER_ID = "cumulus4j.cryptoManagerID";
065
066 /**
067 * <p>
068 * Property to control the encryption algorithm that is used to encrypt data within the datastore. Both
069 * data and index are encrypted using this algorithm.
070 * </p>
071 * <p>
072 * By default (if the property {@value #PROPERTY_ENCRYPTION_ALGORITHM} is not specified),
073 * "Twofish/GCM/NoPadding" is used. For example, to switch to "AES/CFB/NoPadding", you'd have
074 * to specify "cumulus4j.encryptionAlgorithm=AES/CFB/NoPadding" in the persistence-unit/persistence-properties-file.
075 * </p>
076 * <p>
077 * See <a target="_blank" href="http://cumulus4j.org/1.2.0-SNAPSHOT/documentation/supported-algorithms.html">this document</a>
078 * for further information about what values are supported.
079 * </p>
080 * <p>
081 * The encryption algorithm used during encryption is stored in the encryption-record's meta-data in order
082 * to use the correct algorithm during decryption, no matter what current encryption algorithm is configured.
083 * Therefore, you can safely change this setting at any time - it will affect future encryption
084 * operations, only.
085 * </p>
086 * <p>
087 * <b>Important:</b> The default MAC algorithm is "NONE", which is a very bad choice for most encryption algorithms!
088 * Therefore, you must change the MAC algorithm via the property {@value #PROPERTY_MAC_ALGORITHM}
089 * if you change the encryption algorithm!
090 * </p>
091 * <p>
092 * The property can be set in the persistence-unit/persistence-properties-file for the
093 * <code>PersistenceManagerFactory</code>/<code>EntityManagerFactory</code>.
094 * </p>
095 * @see #getEncryptionAlgorithm()
096 */
097 static final String PROPERTY_ENCRYPTION_ALGORITHM = "cumulus4j.encryptionAlgorithm";
098
099 /**
100 * <p>
101 * Property to control the <a target="_blank" href="http://en.wikipedia.org/wiki/Message_authentication_code">MAC</a>
102 * algorithm that is used to protect the data within the key-store against manipulation.
103 * </p>
104 * <p>
105 * Whenever data is encrypted, this MAC algorithm is used to calculate a MAC over the original plain-text-data.
106 * The MAC is then stored together with the plain-text-data within the encrypted area.
107 * When data is decrypted, the MAC is calculated again over the decrypted plain-text-data and compared to the
108 * original MAC in order to make sure (1) that data was correctly decrypted [i.e. the key is correct] and
109 * (2) that the data in the datastore was not manipulated by an attacker.
110 * </p>
111 * <p>
112 * The MAC algorithm used during encryption is stored in the encryption-record's meta-data in order
113 * to use the correct algorithm during decryption, no matter what current MAC algorithm is configured.
114 * Therefore, you can safely change this setting at any time - it will affect future encryption
115 * operations, only.
116 * </p>
117 * <p>
118 * Some block cipher modes (e.g. <a target="_blank" href="http://en.wikipedia.org/wiki/Galois/Counter_Mode">GCM</a>) already include authentication
119 * and therefore no MAC is necessary. In this case, you can specify the MAC algorithm {@value #MAC_ALGORITHM_NONE}.
120 * </p>
121 * <p>
122 * <b>Important:</b> If you specify the MAC algorithm "NONE" and use an encryption algorithm without
123 * authentication, the key store will not be able to detect a wrong password and instead return
124 * corrupt data!!! Be VERY careful with the MAC algorithm "NONE"!!!
125 * </p>
126 * <p>
127 * The default value (used when this system property is not specified) is "NONE", because the default
128 * encryption algorithm is "Twofish/GCM/NoPadding", which (due to "GCM") does not require an additional
129 * MAC.
130 * </p>
131 * <p>
132 * The property can be set in the persistence-unit/persistence-properties-file for the
133 * <code>PersistenceManagerFactory</code>/<code>EntityManagerFactory</code>.
134 * </p>
135 * @see #getMACAlgorithm()
136 */
137 static final String PROPERTY_MAC_ALGORITHM = "cumulus4j.macAlgorithm";
138
139 /**
140 * <p>
141 * Constant for deactivating the <a target="_blank" href="http://en.wikipedia.org/wiki/Message_authentication_code">MAC</a>.
142 * </p>
143 * <p>
144 * <b>Important: Deactivating the MAC is dangerous!</b> Choose this value only, if you are absolutely
145 * sure that your {@link #PROPERTY_ENCRYPTION_ALGORITHM encryption algorithm} already
146 * provides authentication - like <a target="_blank" href="http://en.wikipedia.org/wiki/Galois/Counter_Mode">GCM</a>
147 * does for example.
148 * </p>
149 * @see #PROPERTY_MAC_ALGORITHM
150 */
151 static final String MAC_ALGORITHM_NONE = EncryptionCoordinateSet.MAC_ALGORITHM_NONE;
152
153 /**
154 * <p>
155 * Persistence property to control when the timer for cleaning up expired {@link CryptoSession}s is called. The
156 * value configured here is a period, i.e. the timer will be triggered every X ms (roughly).
157 * </p><p>
158 * If this persistence property is not present (or not a valid number > 0), the default is 60000 (1 minute), which means
159 * the timer will wake up once a minute and do the clean-up (default implementation is calling
160 * {@link AbstractCryptoManager#closeExpiredCryptoSessions(boolean)} with <code>force = true</code>).
161 * </p><p>
162 * If this persistence property is set to 0, the timer is deactivated and cleanup happens only synchronously
163 * when {@link #getCryptoSession(String)} is called (periodically - not every time this method is called).
164 * </p>
165 * @see #PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED
166 */
167 public static final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD = "cumulus4j.cryptoSessionExpiryTimer.period";
168
169 /**
170 * Persistence property to control whether the timer for cleaning up expired {@link CryptoSession}s is enabled.
171 * The value configured here is a boolean (i.e. must be "true" or "false"). The default value (if the property
172 * is not specified or incorrect) is "true".
173 * @see #PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD
174 */
175 public static final String PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_ENABLED = "cumulus4j.cryptoSessionExpiryTimer.enabled";
176
177 /**
178 * <p>
179 * Persistence property to control after which time an unused {@link CryptoSession} expires.
180 * </p><p>
181 * <code>CryptoSession</code>s that are unused for the configured time in milliseconds are considered expired and
182 * either periodically removed by a timer (see property {@value #PROPERTY_CRYPTO_SESSION_EXPIRY_TIMER_PERIOD})
183 * or periodically removed synchronously during a call to {@link #getCryptoSession(String)}.
184 * </p><p>
185 * If this property is not present (or not a valid number), the default value is 1800000 (30 minutes).
186 * </p>
187 */
188 public static final String PROPERTY_CRYPTO_SESSION_EXPIRY_AGE = "cumulus4j.cryptoSessionExpiryAge";
189
190 /**
191 * Get the registry which manages this {@link CryptoManager}.
192 * This method should normally never return <code>null</code>, because
193 * the registry is {@link #setCryptoManagerRegistry(CryptoManagerRegistry) set} immediately
194 * after instantiation.
195 * @return the registry holding this {@link CryptoManager}.
196 * @see #setCryptoManagerRegistry(CryptoManagerRegistry)
197 */
198 CryptoManagerRegistry getCryptoManagerRegistry();
199
200 /**
201 * Set the registry which manages this {@link CryptoManager}.
202 * This method is called by the {@link CryptoManagerRegistry} whenever
203 * it creates a new instance of <code>CryptoManager</code>.
204 *
205 * @param cryptoManagerRegistry
206 * @see #getCryptoManagerRegistry()
207 */
208 void setCryptoManagerRegistry(CryptoManagerRegistry cryptoManagerRegistry);
209
210 /**
211 * <p>
212 * Set the <code>cryptoManagerID</code> of this instance.
213 * </p>
214 * <p>
215 * This method is called with the value configured in the <code>plugin.xml</code>
216 * directly after instantiating the <code>CryptoManager</code>.
217 * </p>
218 * <p>
219 * <b>You must never directly call this method! It is not an API method!</b>
220 * </p>
221 *
222 * @param cryptoManagerID the identifier to set.
223 * @see #getCryptoManagerID()
224 */
225 void setCryptoManagerID(String cryptoManagerID);
226
227 /**
228 * <p>
229 * Get the <code>cryptoManagerID</code> of this instance.
230 * </p>
231 * <p>
232 * The <code>cryptoManagerID</code> is configured in the <code>plugin.xml</code> when registering an extension
233 * to the extension-point <code>org.cumulus4j.api.cryptoManager</code>. It is then used by the client to
234 * specify which method of key-exchange (or key-management in general) and encryption/decryption is desired.
235 * This is done by setting the property {@link #PROPERTY_CRYPTO_MANAGER_ID}.
236 * </p>
237 * <p>
238 * This method is thread-safe.
239 * </p>
240 *
241 * @return the <code>cryptoManagerID</code> of this instance.
242 */
243 String getCryptoManagerID();
244
245 /**
246 * <p>
247 * Get the {@link CryptoSession} identified by the given <code>cryptoSessionID</code>.
248 * </p>
249 * <p>
250 * Usually, every client opens one crypto-session. How exactly this happens, is highly dependent
251 * on the <code>CryptoManager</code> and <code>CryptoSession</code> implementation. The
252 * {@link CryptoSession#getCryptoSessionID() cryptoSessionID} is then passed from the client to
253 * the server which itself passes it to the <code>PersistenceManager</code> (or <code>EntityManager</code>)
254 * via the property with the name {@link CryptoSession#PROPERTY_CRYPTO_SESSION_ID}.
255 * </p>
256 * <p>
257 * Calling this method with a non-existing <code>cryptoSessionID</code> implicitely creates
258 * a <code>CryptoSession</code> instance and returns it. A future call to this method with the same
259 * <code>cryptoSessionID</code> returns the same <code>CryptoSession</code> instance.
260 * </p>
261 * <p>
262 * A <code>CryptoSession</code> should only be kept in the memory of a <code>CryptoManager</code> for a limited time.
263 * It is recommended to remove it
264 * a short configurable time (e.g. 10 minutes) after the {@link CryptoSession#getLastUsageTimestamp() last usage}.
265 * </p>
266 * <p>
267 * This method must call {@link CryptoSession#updateLastUsageTimestamp()}.
268 * </p>
269 * <p>
270 * This method is thread-safe.
271 * </p>
272 *
273 * @param cryptoSessionID the {@link CryptoSession#getCryptoSessionID() cryptoSessionID} for which to look up or
274 * create a <code>CryptoSession</code>.
275 * @return the <code>CryptoSession</code> identified by the given identifier; never <code>null</code>.
276 */
277 CryptoSession getCryptoSession(String cryptoSessionID);
278
279 /**
280 * <p>
281 * Notify the {@link CryptoManager} about the fact that a session is currently being closed.
282 * </p>
283 * <p>
284 * <b>Important:</b> This method must never be called directly! It must be called by {@link CryptoSession#close()}.
285 * </p>
286 *
287 * @param cryptoSession the session that is currently closed.
288 */
289 void onCloseCryptoSession(CryptoSession cryptoSession);
290
291 /**
292 * Get the value of the property {@value #PROPERTY_ENCRYPTION_ALGORITHM}.
293 * This property can be configured in the persistence-unit/persistence-properties-file.
294 * @return the currently configured encryption algorithm.
295 * @see #PROPERTY_ENCRYPTION_ALGORITHM
296 */
297 String getEncryptionAlgorithm();
298
299 /**
300 * Get the value of the property {@value #PROPERTY_MAC_ALGORITHM}.
301 * This property can be configured in the persistence-unit/persistence-properties-file.
302 * @return the currently configured MAC algorithm.
303 * @see #PROPERTY_MAC_ALGORITHM
304 */
305 String getMACAlgorithm();
306
307 }