|
Gerrit Code Review - 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 `contactstore.url` setting in `gerrit.config` is not set, |
|
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. |
|
|
|
Choose 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_path/etc/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, preferably over HTTPS. |
|
Existing open-source server implementations can be found in the |
|
gerrit-contactstore project. |
|
|
|
* link:https://code.google.com/p/gerrit/source/checkout?repo=contactstore[gerrit-contactstore] |
|
|
|
Configure `'$site_path'/etc/gerrit.config` with the contact store's |
|
URL (in `contactstore.url`), and if needed, APPSEC value (in |
|
`contactstore.appsec`): |
|
|
|
==== |
|
git config --file $site_path/etc/gerrit.config appsec.url https://... |
|
git config --file $site_path/etc/gerrit.config appsec.appsec sekret |
|
==== |
|
|
|
|
|
Contact Store Protocol |
|
---------------------- |
|
|
|
To implement a new contact store, the following details are useful. |
|
|
|
Gerrit connects to the contact store by sending a standard |
|
`application/x-www-form-urlencoded` within an HTTP POST request |
|
sent to the store URL (the exact URL that is in contactstore.url) |
|
with the following form fields 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 contactstore.appsec. |
|
|
|
* 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 Gerrit |
|
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 per line. 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. |
|
|
|
Data Format |
|
~~~~~~~~~~~ |
|
|
|
Once decrypted the `data` field looks something like the following: |
|
|
|
---- |
|
Account-Id: 1001240 |
|
Date: 2009-02-23 20:32:32.852 UTC |
|
Full-Name: John Doe |
|
Preferred-Email: jdoe@example.com |
|
Identity: jd15@some-isp.com |
|
Identity: jdoe@example.com <https://www.google.com/accounts/o8/id?id=AIt18axxafvda821aQZaHDF1k8akbalk218sak> |
|
Identity: jdoe@example.com <http://jdoe.blogger.com/> |
|
Address: |
|
123 Any Street |
|
Any Town, Somewhere |
|
Country: USA |
|
Phone-Number: +1 (555) 555-1212 |
|
Fax-Number: 555.1200 |
|
---- |
|
|
|
The fields are as follows: |
|
|
|
* `Account-Id` |
|
+ |
|
Value of the `account_id` field in the metadata database. This is |
|
a unique key for this account, and links all data records to it. |
|
|
|
* `Date` |
|
+ |
|
Date and time of when this contact record was submitted by the user. |
|
Written in an ISO formatted date/time string (`YYYY-MM-DD hh:mm:ss`), |
|
in the UTC timezone. |
|
|
|
* `Full-Name` |
|
+ |
|
The `full_name` field of the account record when the user submitted |
|
the contact information. This should be the user's given name and |
|
family name. |
|
|
|
* `Preferred-Email` |
|
+ |
|
The `preferred_email` field of the account record when the user |
|
submitted the contact information. This should be one of the emails |
|
listed in the `Identity` field. |
|
|
|
* `Identity` |
|
+ |
|
This field occurs once for each `account_external_id` record |
|
in the database for this account. The email address is listed, |
|
and if the user is using OpenID authentication, the OpenID claimed |
|
identity follows in brackets (`<...>`). Identity lines without an |
|
OpenID identity are usually created by sending an email containing |
|
a unique hyperlink that the user must visit to setup the identity. |
|
|
|
* `Address` |
|
+ |
|
Free form text, as entered by the user. This should describe some |
|
location that physical documents could be sent to, but it is not |
|
verified, so users can enter pretty much anything here. Each line |
|
is prefixed with a single TAB character, but is otherwise exactly |
|
as entered. |
|
|
|
* `Country` |
|
+ |
|
Free form text, as entered by the user. This should be some sort |
|
of country name or ISO country abbreviation, but it is not verified, |
|
so it can be pretty much anything. |
|
|
|
* `Phone-Number`, `Fax-Number` |
|
+ |
|
Free form text, as entered by the user. The format here can be |
|
anything, and as the example shows, may not even be consistent in |
|
the same record. |
|
|
|
GERRIT |
|
------ |
|
Part of link:index.html[Gerrit Code Review] |