Documentation/config-contact.txt - gerrit - Git at Google

 Gerrit2 - Contact Information
 =============================

 To help ensure contributor privacy, but still support gathering of
 contributor agreements as necessary, Gerrit encrypts all offline
 contact information gathered from users.  This data is shipped to
 another server, typically at a different location, to make it more
 difficult for an attacker to obtain.

 This feature is optional.  If the crypto APIs aren't installed
 and the `contact_store_url` column in `system_config` is left
 NULL, Gerrit will not collect contact information from users.


 Setup
 -----

 Ensure Bouncy Castle Crypto API is available in the web application's
 CLASSPATH (e.g. in `'JETTY_HOME'/lib/plus` for Jetty).  Gerrit needs
 both `bcprov-jdk\*-*.jar` and `bcpg-jdk\*-*.jar` to be provided
 for the contact encryption to work.

 * link:http://www.bouncycastle.org/latest_releases.html[Bouncy Castle Crypto API]

 Ensure a proper JCE policy file is installed.  By default most
 JRE installations forbid the use of a strong key, resulting in
 SecurityException messages when trying to encrypt the contact data.
 You need to obtain a strong JCE policy file and install it by hand.
 Look for the 'Unlimited Strength Jurisdiction Policy' download.

 * link:http://java.sun.com/javase/downloads/index.jsp[Java SE Downloads]

 Create a public/private key pair for contact data handling.
 Generate the keys on a protected system, where the resulting
 private key is unlikely to fall into the wrong hands.

 ====
   gpg --gen-key
 ====

 Select to use a `DSA and Elgamal` key type, as the public key will
 be used for data encryption.

 The information chosen for name, email and comment fields can be
 anything reasonable which would identify the contact store of this
 Gerrit instance.  It is probably a good idea to not use a real
 person's name here, but instead some sort of organizational role.
 The actual values chosen don't matter later, and are only to help
 document the purpose of the key.

 Chose a fairly long expiration period, such as 20 years.  For most
 Gerrit instances, contact data will be written once, and rarely,
 if ever, read back.

 Export the public key for Gerrit to use during encryption.  The
 public key must be stored in a file called `contact_information.pub`
 and reside inside of the `site_config` directory.  Armoring it
 during export makes it easier to transport between systems, as
 you can easily copy-and-paste the text.  Gerrit can read both the
 armored and unarmored formats.

 ====
   gpg --export --armor KEYEMAIL >$site_config/contact_information.pub
 ====

 Consider storing the private key with some sort of key escrow
 service within your organization.  Without the private key it
 is impossible to recover contact records.

 Install a contact store implementation somewhere to receive
 the contact records.  To be really paranoid, Gerrit always
 ships the data to another HTTP server, preferrably over HTTPS.
 Existing open-source server implementations can be found in the
 gerrit-contactstore project.

 * link:http://android.git.kernel.org/?p=tools/gerrit-contactstore.git[gerrit-contactstore]

 Configure the `system_config` table with the contact store's URL
 (in field `contact_store_url`), and if needed, APPSEC value (in
 field `contact_store_appsec`).


 Contact Store Protocol
 ----------------------

 To implement a new contact store, the following details are useful.

 Gerrit connects to the contact store by sending a standard
 HTTP POST request to the store URL (the exact URL that is in
 `contact_store_url` in the `system_config` table), with the
 following form parameters in the body:

 * APPSEC
 +
 A shared secret "password" that should be known only to Gerrit
 and the contact store.  The contact store should test this value to
 deter spamming of the contact store by outside parties.  Gerrit reads
 this from `system_config` in the `contact_store_appsec` field.

 * account_id
 +
 Unique account_id value from the Gerrit database for the account
 the contact information belongs to.  Base 10 integer.

 * email
 +
 Preferred email address of the account.  May facilitate lookups in
 the contact store at a future date.  May be omitted or the empty
 string if the user hasn't chosen a preferred email.

 * filed
 +
 Seconds since the UNIX epoch of when the contact information
 was filed.  May be omitted or the empty string if the application
 doesn't think the supplied contact information is valid enough.

 * data
 +
 Encrypted account data as an armored ASCII blob.  This is usually
 several KB of text data as a single string, with embedded newlines
 to break the lines at about 70-75 characters.  Data can be decoded
 using GnuPG with the correct private key.

 Upon successful store, the contact store application should respond
 with HTTP status code `200` and a body consisting only of `OK`
 (or `OK\n`).  Any other response code or body is considered to be
 a failure by Gerrit.

 Using `https://` for the store URL is *highly* encouraged, as it
 prevents man-in-the-middle attacks from reading the shared secret
 APPSEC token, or messing with the data field.


 [[upgrade_203]]
 Upgrading From Gerrit 2.0.3 (or Earlier)
 ----------------------------------------

 To upgrade from schema 4 (Gerrit 2.0.3 and earlier) to schema 5
 (Gerrit 2.0.4 and later), run the following sequence.

 Replace `your-appid` with the Google App Engine application id of
 your contact store application, and `APPSEC` with the value compiled
 into the application when it was uploaded.

 The use of Google App Engine isn't required.  It is relatively easy
 to create another web service to receive the application data,
 and point the `contact_store_url` at that server.  See above for
 more details about the form data posted.

 ====
   git clone git://android.git.kernel.org/tools/gerrit-contactstore.git
   cd gerrit-contactstore/google_appengine
   make update APPID=your-appid

   gpg --export --armor KEYEMAIL >$site_config/contact_information.pub

   java -jar gerrit.war --cat sql/upgrade004_005_part1.sql | psql reviewdb
   psql -c "UPDATE system_config SET contact_store_url = 'https://your-appid.appspot.com/store'" reviewdb
   psql -c "UPDATE system_config SET contact_store_appsec = 'APPSEC'" reviewdb
   java -DGerritServer=GerritServer.properties -cp bcprov-jdk15-141.jar:bcpg-jdk15-141.jar:gerrit.war ExecutableWarMain EncryptContactInfo
 ====

 It may be a good idea to delay part2.sql until after the existing
 contact information has been archived and has been verified to be
 readable.  The part2 script simply drops the old contact columns
 from the `accounts` table.

 ====
   java -jar gerrit.war --cat sql/upgrade004_005_part2.sql | psql reviewdb
 ====
	Gerrit2 - Contact Information
	=============================

	To help ensure contributor privacy, but still support gathering of
	contributor agreements as necessary, Gerrit encrypts all offline
	contact information gathered from users. This data is shipped to
	another server, typically at a different location, to make it more
	difficult for an attacker to obtain.

	This feature is optional. If the crypto APIs aren't installed
	and the `contact_store_url` column in `system_config` is left
	NULL, Gerrit will not collect contact information from users.


	Setup
	-----

	Ensure Bouncy Castle Crypto API is available in the web application's
	CLASSPATH (e.g. in `'JETTY_HOME'/lib/plus` for Jetty). Gerrit needs
	both `bcprov-jdk\-.jar` and `bcpg-jdk\-.jar` to be provided
	for the contact encryption to work.

	* link:http://www.bouncycastle.org/latest_releases.html[Bouncy Castle Crypto API]

	Ensure a proper JCE policy file is installed. By default most
	JRE installations forbid the use of a strong key, resulting in
	SecurityException messages when trying to encrypt the contact data.
	You need to obtain a strong JCE policy file and install it by hand.
	Look for the 'Unlimited Strength Jurisdiction Policy' download.

	* link:http://java.sun.com/javase/downloads/index.jsp[Java SE Downloads]

	Create a public/private key pair for contact data handling.
	Generate the keys on a protected system, where the resulting
	private key is unlikely to fall into the wrong hands.

	====
	gpg --gen-key
	====

	Select to use a `DSA and Elgamal` key type, as the public key will
	be used for data encryption.

	The information chosen for name, email and comment fields can be
	anything reasonable which would identify the contact store of this
	Gerrit instance. It is probably a good idea to not use a real
	person's name here, but instead some sort of organizational role.
	The actual values chosen don't matter later, and are only to help
	document the purpose of the key.

	Chose a fairly long expiration period, such as 20 years. For most
	Gerrit instances, contact data will be written once, and rarely,
	if ever, read back.

	Export the public key for Gerrit to use during encryption. The
	public key must be stored in a file called `contact_information.pub`
	and reside inside of the `site_config` directory. Armoring it
	during export makes it easier to transport between systems, as
	you can easily copy-and-paste the text. Gerrit can read both the
	armored and unarmored formats.

	====
	gpg --export --armor KEYEMAIL >$site_config/contact_information.pub
	====

	Consider storing the private key with some sort of key escrow
	service within your organization. Without the private key it
	is impossible to recover contact records.

	Install a contact store implementation somewhere to receive
	the contact records. To be really paranoid, Gerrit always
	ships the data to another HTTP server, preferrably over HTTPS.
	Existing open-source server implementations can be found in the
	gerrit-contactstore project.

	* link:http://android.git.kernel.org/?p=tools/gerrit-contactstore.git[gerrit-contactstore]

	Configure the `system_config` table with the contact store's URL
	(in field `contact_store_url`), and if needed, APPSEC value (in
	field `contact_store_appsec`).


	Contact Store Protocol
	----------------------

	To implement a new contact store, the following details are useful.

	Gerrit connects to the contact store by sending a standard
	HTTP POST request to the store URL (the exact URL that is in
	`contact_store_url` in the `system_config` table), with the
	following form parameters in the body:

	* APPSEC
	+
	A shared secret "password" that should be known only to Gerrit
	and the contact store. The contact store should test this value to
	deter spamming of the contact store by outside parties. Gerrit reads
	this from `system_config` in the `contact_store_appsec` field.

	* account_id
	+
	Unique account_id value from the Gerrit database for the account
	the contact information belongs to. Base 10 integer.

	* email
	+
	Preferred email address of the account. May facilitate lookups in
	the contact store at a future date. May be omitted or the empty
	string if the user hasn't chosen a preferred email.

	* filed
	+
	Seconds since the UNIX epoch of when the contact information
	was filed. May be omitted or the empty string if the application
	doesn't think the supplied contact information is valid enough.

	* data
	+
	Encrypted account data as an armored ASCII blob. This is usually
	several KB of text data as a single string, with embedded newlines
	to break the lines at about 70-75 characters. Data can be decoded
	using GnuPG with the correct private key.

	Upon successful store, the contact store application should respond
	with HTTP status code `200` and a body consisting only of `OK`
	(or `OK\n`). Any other response code or body is considered to be
	a failure by Gerrit.

	Using `https://` for the store URL is highly encouraged, as it
	prevents man-in-the-middle attacks from reading the shared secret
	APPSEC token, or messing with the data field.



	[[upgrade_203]]
	Upgrading From Gerrit 2.0.3 (or Earlier)
	----------------------------------------

	To upgrade from schema 4 (Gerrit 2.0.3 and earlier) to schema 5
	(Gerrit 2.0.4 and later), run the following sequence.

	Replace `your-appid` with the Google App Engine application id of
	your contact store application, and `APPSEC` with the value compiled
	into the application when it was uploaded.

	The use of Google App Engine isn't required. It is relatively easy
	to create another web service to receive the application data,
	and point the `contact_store_url` at that server. See above for
	more details about the form data posted.

	====
	git clone git://android.git.kernel.org/tools/gerrit-contactstore.git
	cd gerrit-contactstore/google_appengine
	make update APPID=your-appid

	gpg --export --armor KEYEMAIL >$site_config/contact_information.pub

	java -jar gerrit.war --cat sql/upgrade004_005_part1.sql \| psql reviewdb
	psql -c "UPDATE system_config SET contact_store_url = 'https://your-appid.appspot.com/store'" reviewdb
	psql -c "UPDATE system_config SET contact_store_appsec = 'APPSEC'" reviewdb
	java -DGerritServer=GerritServer.properties -cp bcprov-jdk15-141.jar:bcpg-jdk15-141.jar:gerrit.war ExecutableWarMain EncryptContactInfo
	====

	It may be a good idea to delay part2.sql until after the existing
	contact information has been archived and has been verified to be
	readable. The part2 script simply drops the old contact columns
	from the `accounts` table.

	====
	java -jar gerrit.war --cat sql/upgrade004_005_part2.sql \| psql reviewdb
	====