deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/2] deltaspike git commit: DELTASPIKE-1250 add documentation and improve JavaDocs
Date Tue, 23 May 2017 14:15:13 GMT
DELTASPIKE-1250 add documentation and improve JavaDocs


Branch: refs/heads/master
Commit: d1cc650d68686d02656f53a4f532a2acb911bc6d
Parents: 63ee99e
Author: Mark Struberg <>
Authored: Tue May 23 16:07:37 2017 +0200
Committer: Mark Struberg <>
Committed: Tue May 23 16:07:37 2017 +0200

 .../core/api/crypto/          | 10 +-
 documentation/src/main/asciidoc/encryption.adoc | 97 ++++++++++++++++++++
 2 files changed, 106 insertions(+), 1 deletion(-)
diff --git a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/crypto/
index 269ae05..b04e818 100644
--- a/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/crypto/
+++ b/deltaspike/core/api/src/main/java/org/apache/deltaspike/core/api/crypto/
@@ -44,12 +44,20 @@ public interface CipherService
      * Encrypt the given cleartext.
      * We use the masterSalt to access the MasterHash to use as key for encryption
-     * @param cleartext
+     * @param cleartext to get encrypted
      * @param masterSalt the same as used for {@link #setMasterHash(String, String, boolean)}
      * @return the encrypted String to store somewhere
     String encrypt(String cleartext, String masterSalt);
+    /**
+     * Decrypt the given encrypted value.
+     * We use the masterSalt to access the MasterHash to use as key for encryption
+     *
+     * @param encryptedValue to get decrypted
+     * @param masterSalt the same as used for {@link #setMasterHash(String, String, boolean)}
+     * @return the decrypted plaintext
+     */
     String decrypt(String encryptedValue, String masterSalt);
diff --git a/documentation/src/main/asciidoc/encryption.adoc b/documentation/src/main/asciidoc/encryption.adoc
new file mode 100644
index 0000000..4dd9ccf
--- /dev/null
+++ b/documentation/src/main/asciidoc/encryption.adoc
@@ -0,0 +1,97 @@
+= DeltaSpike Crypto Mechanism
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license
agreements. See the NOTICE file distributed with this work for additional information regarding
copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with the License. You may
obtain a copy of the License at. . Unless required
by applicable law or agreed to in writing, software distributed under the License is distributed
on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the
+== Introduction
+Many applications still use plaintext to store sensitive information.
+This should be avoided to not loose sensible user information in case of a security breach.
+Apache DeltaSpike provides a mechanism to encrypt and decrypt secured information to better
guard such information.
+== The Algorithm
+DeltaSpike provides encryption based on a split secret approach.
+Many systems (like Maven, Jenkins) store the hash of a 'master password' in the users home
+This master hash is then used to encrypt/decrypt the actual passwords.
+If an attacker manages to get his hands on the content of the database then he still cannot
do much with the encrypted content stored therein.
+He would also need the content of the file containing the master password.
+DeltaSpike improves this mechanism by adding an additional secret (`masterSalt`) which needs
to be provided by the application.
+With this approach we add an additional obstacle for any attacker.
+The attacker would now not only need the file from the users home folder but also need to
debug and reconstruct the application.
+This approach additionally has the benefit to be able to store and use multiple different
master passwords at the same time.
+That means that DeltaSpike needs 3 different pieces
+- the encryted content. E.g. a password stored in some property file or in the database
+- The `~/.deltaspike/master.hash` file containing the previously set master password.
+- the `masterSalt` provided by the application and while setting the master password.
+All that still does *not* create absolute security, mostly because there is no such thing
like _absolute_ security!
+Each system which claims absolute security is to be taken with caution.
+But this handling will drastically improve the security of your application.
+See the section about the `masterSalt` for more tips to strengthten security.
+== Using the Command Line Interface
+Apache DeltaSpike also contains CLI commands to store the `masterPassword` and encrypt user
+The first step is to create a master hash.
+It is by default stored in the users home folder at `~/.deltaspike/master.hash`.
+For creating a master hash you need to use a `masterPassword` and a `masterSalt`
+$> java -jar deltaspike-core-impl.jar encode -masterPassword myMasterPassword -masterSalt
+A new master password got set. Hash key is cbd90f294dc4ed3d1113a98107fabbc370b303c4a5e3208c2df3e0326c31499c
+You can now go on and encrypt your plaintext information:
+$> java -jar deltaspike-core-impl.jar encode -plaintext textOneWantsToEncrypt -masterSalt
+Encrypted value: 9d4196aa28d83a08b32752966aa5f4aa41c359fec847fdad3565241bb5e2df12
+The encrypted value can then be stored in the databas, config files, etc.
+== The masterPassword
+The masterPassword is used to protect the secret.
+Note that it's not possible to reconstruct the masterPassword from the master.hash file.
+== Providing a masterSalt
+The `masterSalt` is not used to encrypt the secrets but it only protects the `masterPassword`
in the `master.hash` file.
+This means that the masterSalt could be either static or even change over time.
+The `masterSalt` could also be a combined local information.
+As an example we take the local IP address and the user name running the application.
+String localInformation = InetAddress.getLocalHost().getHostAddress() + System.getProperty("");
+String masterSalt = sha1(localInformation);
+Note the usage of the hash.
+Otherwise it would be too obvious how the masterSalt gets constructed
+If this code is well hidden within the application code it is really hard for an attacker
to find out how it is determined.
+Otoh this hash can easily be constructed on the command line with classic unix tools like
+== Programmatic usage
+A program could either inject a CipherService or create a new DefaultCipherService to programmatically
decrypt values.
+A usr could also provide a `ConfigFilter` to apply decryption on encrypted configuration
values on the fly

View raw message