Add documentation for SecureStore
Provides javadoc and documentation for SecureStore.
Change-Id: I24a5565dc7d38b506a77459aa13fccd606f0e408
Signed-off-by: Dariusz Luksza <dariusz@luksza.org>
diff --git a/Documentation/dev-plugins.txt b/Documentation/dev-plugins.txt
index c26d4f2..cecb258 100644
--- a/Documentation/dev-plugins.txt
+++ b/Documentation/dev-plugins.txt
@@ -1731,6 +1731,34 @@
}
----
+[[secure-store]]
+== SecureStore
+
+SecureStore allows to change the way Gerrit stores sensitive data like
+passwords.
+
+In order to replace the default SecureStore (no-op) implementation,
+a class that extends `com.google.gerrit.server.securestore.SecureStore`
+needs to be provided (with dependencies) in a separate jar file. Then
+link:pgm-SwitchSecureStore.html[SwitchSecureStore] must be run to
+switch implementations.
+
+The SecureStore implementation is instantiated using a Guice injector
+which binds the `File` annotated with the `@SitePath` annotation.
+This means that a SecureStore implementation class can get access to
+the `site_path` like in the following example:
+
+[source,java]
+----
+@Inject
+MySecureStore(@SitePath java.io.File sitePath) {
+ // your code
+}
+----
+
+No Guice bindings or modules are required. Gerrit will automatically
+discover and bind the implementation.
+
[[download-commands]]
== Download Commands
diff --git a/Documentation/pgm-SwitchSecureStore.txt b/Documentation/pgm-SwitchSecureStore.txt
new file mode 100644
index 0000000..f9b2aa4
--- /dev/null
+++ b/Documentation/pgm-SwitchSecureStore.txt
@@ -0,0 +1,39 @@
+= SwitchSecureStore
+
+== NAME
+SwitchSecureStore - Changes the currently used SecureStore implementation
+
+== SYNOPSIS
+--
+'java' -jar gerrit.war 'SwitchSecureStore' [<OPTIONS>]
+--
+
+== DESCRIPTION
+Changes the SecureStore implementation used by Gerrit. It migrates all data
+stored in the old implementation, removes the old implementation jar file
+from `$site_path/lib` and puts the new one there. As a final step
+the link:config-gerrit.html#gerrit.secureStoreClass[gerrit.secureStoreClass]
+property of `gerrit.config` will be updated.
+
+All dependencies not provided by Gerrit should be put the in `$site_path/lib`
+directory manually, before running the `SwitchSecureStore` program.
+
+After this operation there is no automatic way back the to standard Gerrit no-op
+secure store implementation, however there is a manual procedure:
+* stop Gerrit,
+* remove SecureStore jar file from `$site_path/lib`,
+* put plain text passwords into `$site_path/etc/secure.conf` file,
+* start Gerrit.
+
+== OPTIONS
+
+--new-secure-store-lib::
+ Path to jar file with new SecureStore implementation. Jar dependencies must be
+ put in `$site_path/lib` directory.
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
+
+SEARCHBOX
+---------
diff --git a/Documentation/pgm-index.txt b/Documentation/pgm-index.txt
index 3bb6182..bf6dc57 100644
--- a/Documentation/pgm-index.txt
+++ b/Documentation/pgm-index.txt
@@ -24,6 +24,9 @@
link:pgm-reindex.html[reindex]::
Rebuild the secondary index.
+link:pgm-SwitchSecureStore.html[SwitchSecureStore]::
+ Change used SecureStore implementation.
+
link:pgm-rulec.html[rulec]::
Compile project-specific Prolog rules to JARs.
