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.keymanager.back.shared;
019
020 import javax.xml.bind.annotation.XmlRootElement;
021
022 import org.cumulus4j.crypto.CryptoRegistry;
023
024 /**
025 * <p>
026 * {@link Request} implementation to get a specific symmetric secret key.
027 * </p><p>
028 * In order to prevent an attacker dumping an app-server's memory from gaining access to <b>all</b> the data,
029 * Cumulus4j uses many different keys for encryption. Usually, it rotates the encryption key once per day, but
030 * different settings are possible (e.g. once per hour for the very paranoid).
031 * </p><p>
032 * Which key was used to encrypt which record is stored together with the record in the {@link #getKeyID() keyID}.
033 * Whenever a record (data or index) needs to be decrypted, the corresponding key is requested from the key-manager
034 * via this request.
035 * </p>
036 *
037 * @author Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de
038 * @see GetKeyResponse
039 */
040 @XmlRootElement
041 public class GetKeyRequest extends Request
042 {
043 private static final long serialVersionUID = 1L;
044
045 private long keyID;
046
047 private String keyEncryptionTransformation;
048
049 private byte[] keyEncryptionPublicKey;
050
051 /**
052 * Create an empty instance of <code>GetKeyRequest</code>.
053 * Only used for serialisation/deserialisation.
054 */
055 public GetKeyRequest() { }
056
057 /**
058 * Create an instance of <code>GetKeyRequest</code> for asking the key-manager about
059 * a certain symmetric secret key.
060 *
061 * @param cryptoSessionID the identifier of the crypto-session in which the request should be processed.
062 * It must exist and be unlocked for this request to succeed.
063 * @param keyID the identifier of the key requested by the app-server.
064 * @param keyEncryptionTransformation the asymmetric encryption algorithm (with padding) that should be
065 * used by the key-manager to encrypt the symmetric secret key, before sending it to the app-server. For example
066 * "RSA//OAEPWITHSHA1ANDMGF1PADDING".
067 * @param keyEncryptionPublicKey the public key to be used by the key-manager to encrypt the
068 * key when sending it back to the app-server.
069 */
070 public GetKeyRequest(String cryptoSessionID, long keyID, String keyEncryptionTransformation, byte[] keyEncryptionPublicKey) {
071 super(cryptoSessionID);
072 this.keyID = keyID;
073 this.keyEncryptionTransformation = keyEncryptionTransformation;
074 this.keyEncryptionPublicKey = keyEncryptionPublicKey;
075 }
076
077 /**
078 * Get the identifier of the requested symmetric secret key.
079 * @return the identifier of the requested symmetric secret key.
080 * @see #setKeyID(long)
081 */
082 public long getKeyID() {
083 return keyID;
084 }
085 /**
086 * Set the identifier of the requested symmetric secret key.
087 * @param keyID the identifier of the requested symmetric secret key.
088 * @see #getKeyID()
089 */
090 public void setKeyID(long keyID) {
091 this.keyID = keyID;
092 }
093
094 /**
095 * <p>
096 * Get the asymmetric encryption algorithm to be used to encrypt the symmetric secret key.
097 * </p><p>
098 * The key-manager uses this transformation
099 * (which should include a padding, e.g. "RSA//OAEPWITHSHA1ANDMGF1PADDING") to
100 * {@link CryptoRegistry#createCipher(String) obtain a Cipher} for encrypting the secret key
101 * before sending it to the app-server.
102 * </p>
103 * @return the asymmetric encryption algorithm to be used when encrypting the symmetric secret key.
104 * @see #setKeyEncryptionTransformation(String)
105 */
106 public String getKeyEncryptionTransformation() {
107 return keyEncryptionTransformation;
108 }
109 /**
110 * Set the asymmetric encryption algorithm to be used when encrypting the symmetric secret key.
111 * @param keyEncryptionTransformation the asymmetric encryption algorithm to be used when encrypting the symmetric secret key.
112 * @see #getKeyEncryptionTransformation()
113 */
114 public void setKeyEncryptionTransformation(String keyEncryptionTransformation) {
115 this.keyEncryptionTransformation = keyEncryptionTransformation;
116 }
117
118 /**
119 * Get the public key to be used to encrypt the symmetric secret key.
120 * @return the public key to be used to encrypt the symmetric secret key.
121 */
122 public byte[] getKeyEncryptionPublicKey() {
123 return keyEncryptionPublicKey;
124 }
125 /**
126 * Set the public key to be used to encrypt the symmetric secret key.
127 * @param keyEncryptionPublicKey the public key to be used to encrypt the symmetric secret key.
128 */
129 public void setKeyEncryptionPublicKey(byte[] keyEncryptionPublicKey) {
130 this.keyEncryptionPublicKey = keyEncryptionPublicKey;
131 }
132 }