You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by ol...@apache.org on 2019/12/12 16:47:02 UTC
[sling-site] branch master updated: SLING-8914 Add initial
documentation
This is an automated email from the ASF dual-hosted git repository.
olli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 78c3f10 SLING-8914 Add initial documentation
78c3f10 is described below
commit 78c3f1035a4297c85d8e7b913f4d01a8d395f899
Author: Oliver Lietz <ol...@apache.org>
AuthorDate: Thu Dec 12 17:44:27 2019 +0100
SLING-8914 Add initial documentation
* CryptoService and PasswordProvider
* Jasypt implementation
* Web Console Plugin
* Sample configurations
---
.../commons-crypto/FilePasswordProvider~sample.png | Bin 0 -> 56843 bytes
.../JasyptRandomIvGeneratorRegistrar~sample.png | Bin 0 -> 55855 bytes
...JasyptStandardPBEStringCryptoService~sample.png | Bin 0 -> 149263 bytes
...ng-commons-crypto-encrypt-webconsole-plugin.png | Bin 0 -> 43831 bytes
src/main/jbake/content/documentation/bundles.md | 1 +
.../documentation/bundles/commons-crypto.md | 102 +++++++++++++++++++++
6 files changed, 103 insertions(+)
diff --git a/src/main/jbake/assets/documentation/bundles/commons-crypto/FilePasswordProvider~sample.png b/src/main/jbake/assets/documentation/bundles/commons-crypto/FilePasswordProvider~sample.png
new file mode 100644
index 0000000..30c5200
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/commons-crypto/FilePasswordProvider~sample.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png b/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png
new file mode 100644
index 0000000..cba4cf4
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptStandardPBEStringCryptoService~sample.png b/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptStandardPBEStringCryptoService~sample.png
new file mode 100644
index 0000000..744ceef
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/commons-crypto/JasyptStandardPBEStringCryptoService~sample.png differ
diff --git a/src/main/jbake/assets/documentation/bundles/commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png b/src/main/jbake/assets/documentation/bundles/commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png
new file mode 100644
index 0000000..c444249
Binary files /dev/null and b/src/main/jbake/assets/documentation/bundles/commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png differ
diff --git a/src/main/jbake/content/documentation/bundles.md b/src/main/jbake/content/documentation/bundles.md
index de7532c..51b4bed 100644
--- a/src/main/jbake/content/documentation/bundles.md
+++ b/src/main/jbake/content/documentation/bundles.md
@@ -48,6 +48,7 @@ The OSGi installer is a very flexible and powerful service to manage provisionin
* [Vault Package Install Hook](/documentation/bundles/installer-provider-installhook.html)
## Development and Utilities
+* [Commons Crypto](/documentation/bundles/commons-crypto.html)
* [Commons Thread Pools](/documentation/bundles/apache-sling-commons-thread-pool.html)
* [Commons HTML Utilities](/documentation/bundles/commons-html-utilities.html)
* [MIME Type Support (commons.mime and commons.contentdetection)](/documentation/bundles/mime-type-support-commons-mime.html)
diff --git a/src/main/jbake/content/documentation/bundles/commons-crypto.md b/src/main/jbake/content/documentation/bundles/commons-crypto.md
new file mode 100644
index 0000000..f93dabf
--- /dev/null
+++ b/src/main/jbake/content/documentation/bundles/commons-crypto.md
@@ -0,0 +1,102 @@
+title=Commons Crypto
+type=page
+status=published
+tags=commons,crypto
+~~~~~~
+
+[TOC]
+
+**Commons Crypto provides a simple API to encrypt and decrypt messages and an extensible implementation based on [Jasypt](http://www.jasypt.org).**
+
+The Jasypt implementation and Web Console plugin are optional.
+
+
+## API
+
+
+### Crypto Service
+
+Encrypt a secret message (e.g. service password) and decrypt the ciphertext. The used crypto method is up to the implementation.
+
+ ::java
+ public interface CryptoService {
+
+ String encrypt(String message);
+
+ String decrypt(String ciphertext);
+
+ }
+
+Use a reference target to get a particular crypto service, e.g. by *names* (names should be meaningful e.g. mail or database).
+
+ ::java
+ @Reference(
+ target = "(names=sample)"
+ )
+ private volatile CryptoService cryptoService;
+
+
+### Password Provider
+
+Password providers are useful when dealing with password-based encryption (PBE, see also [RFC 2898](https://tools.ietf.org/html/rfc2898)).
+
+ ::java
+ public interface PasswordProvider {
+
+ char[] getPassword();
+
+ }
+
+
+#### File Password Provider
+
+The file-based password provider reads the password for encryption/decryption from a given file.
+
+<img src="commons-crypto/FilePasswordProvider~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver">
+
+
+## Jasypt implementation
+
+The Commons Crypto module provides a crypto service implementation based on the [Jasypt](http://www.jasypt.org) `StandardPBEStringEncryptor`.
+
+The `JasyptStandardPBEStringCryptoService` requires at least a password provider and an initialization vector (IV) generator (`IvGenerator`) to set up the internal `StandardPBEStringEncryptor`.
+
+<img src="commons-crypto/JasyptStandardPBEStringCryptoService~sample.png" alt="JasyptStandardPBEStringCryptoService Sample Configuration" style="width: 50%; border: 1px solid silver">
+
+<img src="commons-crypto/JasyptRandomIvGeneratorRegistrar~sample.png" alt="JasyptRandomIvGeneratorRegistrar Sample Configuration" style="width: 50%; border: 1px solid silver">
+
+
+## Web Console Plugin
+
+The plugin (`/system/console/sling-commons-crypto-encrypt`) allows message encryption with a selected crypto service.
+
+<img src="commons-crypto/sling-commons-crypto-encrypt-webconsole-plugin.png" alt="Sling Commons Crypto Encrypt Web Console Plugin" style="width: 50%; border: 1px solid silver">
+
+
+## Sample configurations
+
+A module with (minimal) sample configurations can be found in [Sling's sample Git repo](https://github.com/apache/sling-samples/tree/master/sling-commons-crypto-configuration).
+
+`org.apache.sling.commons.crypto.internal.FilePasswordProvider~sample.json`
+
+ {
+ "jcr:primaryType": "sling:OsgiConfig",
+ "names": ["sample"], // names is optional
+ "path": "/var/sling/password"
+ }
+
+`org.apache.sling.commons.crypto.jasypt.internal.JasyptRandomIvGeneratorRegistrar~sample.json`
+
+ {
+ "jcr:primaryType": "sling:OsgiConfig",
+ "algorithm": "SHA1PRNG"
+ }
+
+
+`org.apache.sling.commons.crypto.jasypt.internal.JasyptStandardPBEStringCryptoService~sample.json`
+
+ {
+ "jcr:primaryType": "sling:OsgiConfig",
+ "names": ["sample"], // names is optional
+ "algorithm": "PBEWITHHMACSHA512ANDAES_256"
+ }