README.md 5.67 KB
Newer Older
Moxie Marlinspike's avatar
Moxie Marlinspike committed
1
2
# Gradle Witness

Moxie Marlinspike's avatar
Moxie Marlinspike committed
3
A gradle plugin that enables static verification for remote dependencies.
Moxie Marlinspike's avatar
Moxie Marlinspike committed
4

Moxie Marlinspike's avatar
Moxie Marlinspike committed
5
Build systems like gradle and maven allow one to specify dependencies for versioned artifacts. An
Moxie Marlinspike's avatar
Moxie Marlinspike committed
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
Android project might list dependencies like this:

    dependency {
        compile 'com.actionbarsherlock:actionbarsherlock:4.4.0@aar'
        compile 'com.android.support:support-v4:19.0.1'
        compile 'com.google.android.gcm:gcm-client:1.0.2'
        compile 'se.emilsjolander:stickylistheaders:2.2.0'
    }

This allows the sample Android project to very easily make use of versioned third party libraries like
[ActionBarSherlock](http://actionbarsherlock.com/), or [StickyListHeaders](https://github.com/emilsjolander/StickyListHeaders).
During the build process, gradle will automatically retrieve the libraries from the configured
maven repositories and incorporate them into the build.  This makes it easy to manage dependencies
without having to check jars into a project's source tree.

## Dependency Problems

A "published" maven/gradle artifact [looks like this](https://github.com/WhisperSystems/maven/tree/master/gson/releases/org/whispersystems/gson/2.2.4):

    gson-2.2.4.jar
    gson-2.2.4.jar.md5
    gson-2.2.4.jar.sha1
    gson-2.2.4.pom
    gson-2.2.4.pom.md5
    gson-2.2.4.pom.sha1

In the remote directory, the artifact consists of a POM file and a jar or aar, along with md5sum and
sha1sum hash values for those files.

When gradle retrieves the artifact, it will also retrieve the md5sum and sha1sums to verify that
they match the calculated md5sum and sha1sum of the retrieved files.  The problem, obviously, is 
that if someone is able to compromise the remote maven repository and change the jar/aar for a 
dependency to include some malicious functionality, they could just as easily change the md5sum
and sha1sum values the repository advertises as well.

## The Witness Solution

This gradle plugin simply allows the author of a project to statically specify the sha256sum of
the dependencies that it uses.  For our dependency example above, `gradle-witness` would allow
the project to specify:

    dependency {
        compile 'com.actionbarsherlock:actionbarsherlock:4.4.0@aar'
        compile 'com.android.support:support-v4:19.0.1'
        compile 'com.google.android.gcm:gcm-client:1.0.2'
        compile 'se.emilsjolander:stickylistheaders:2.2.0'
    }

    dependencyVerification {
        verify = [
                'com.actionbarsherlock:actionbarsherlock:5ab04d74101f70024b222e3ff9c87bee151ec43331b4a2134b6cc08cf8565819',
                'com.android.support:support-v4:a4268abd6370c3fd3f94d2a7f9e6e755f5ddd62450cf8bbc62ba789e1274d585',
                'com.google.android.gcm:gcm-client:5ff578202f93dcba1c210d015deb4241c7cdad9b7867bd1b32e0a5f4c16986ca',
                'se.emilsjolander:stickylistheaders:89146b46c96fea0e40200474a2625cda10fe94891e4128f53cdb42375091b9b6',
        ]
    }

The `dependency` definition is the same, but `gradle-witness` allows one to also specify a
`dependencyVerification` definition as well.  That definition should include a single list called
`verify` with elements in the format of `group_id:name:sha256sum`.

At this point, running `gradle build` will first verify that all of the listed dependencies have
the specified sha256sums.  If there's a mismatch, the build is aborted.  If the remote repository
is later compromised, an attacker won't be able to undetectably modify these artifacts.

## Using Witness

Unfortunately, it doesn't make sense to publish `gradle-witness` as an artifact, since that
Moxie Marlinspike's avatar
Moxie Marlinspike committed
74
creates a bootstrapping problem.  To use `gradle-witness`, the jar needs to be built and included
Moxie Marlinspike's avatar
Moxie Marlinspike committed
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
in your project:

    $ git clone https://github.com/WhisperSystems/gradle-witness.git
    $ cd gradle-witness
    $ gradle build
    $ cp build/libs/gradle-witness.jar /path/to/your/project/libs/gradle-witness.jar

Then in your project's `build.gradle`, the buildscript needs to add a `gradle-witness` dependency.
It might look something like:

    buildscript {
        repositories {
            mavenCentral()
        }
        dependencies {
            classpath 'com.android.tools.build:gradle:0.9.+'
            classpath files('libs/gradle-witness.jar')
        }
    }

Moxie Marlinspike's avatar
Moxie Marlinspike committed
95
96
    apply plugin: 'witness'

Moxie Marlinspike's avatar
Moxie Marlinspike committed
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
At this point you can use `gradle-witness` in your project.  If you're feeling "trusting on first
use," you can have `gradle-witness` calculate the sha256sum for all your project's dependencies
(and transitive dependencies!) for you:

    $ gradle -q calculateChecksums

This will print the full `dependencyVerification` definition to include in the project's `build.gradle`.
For a project that has a dependency definition like:

    dependency {
        compile 'com.actionbarsherlock:actionbarsherlock:4.4.0@aar'
        compile 'com.android.support:support-v4:19.0.1'
        compile 'com.google.android.gcm:gcm-client:1.0.2'
        compile 'se.emilsjolander:stickylistheaders:2.2.0'
    }

Running `gradle -q calculateChecksums` will print:

    dependencyVerification {
        verify = [
                'com.actionbarsherlock:actionbarsherlock:5ab04d74101f70024b222e3ff9c87bee151ec43331b4a2134b6cc08cf8565819',
                'com.android.support:support-v4:a4268abd6370c3fd3f94d2a7f9e6e755f5ddd62450cf8bbc62ba789e1274d585',
                'com.google.android.gcm:gcm-client:5ff578202f93dcba1c210d015deb4241c7cdad9b7867bd1b32e0a5f4c16986ca',
                'se.emilsjolander:stickylistheaders:89146b46c96fea0e40200474a2625cda10fe94891e4128f53cdb42375091b9b6',
        ]
    }

...which you can then include directly below the `dependency` definition in the project's `build.gradle`.

And that's it! From then on, running a standard `gradle build` will verify the integrity of
Moxie Marlinspike's avatar
Moxie Marlinspike committed
127
the project's dependencies.