README.md
1Conscrypt - A Java Security Provider
2========================================
3
4Conscrypt is a Java Security Provider (JSP) that implements parts of the
5Java Cryptography Extension (JCE) and Java Secure Socket Extension (JSSE).
6It uses BoringSSL to provide cryptographical primitives and Transport Layer
7Security (TLS) for Java applications on Android and OpenJDK.
8
9The core SSL engine has borrowed liberally from the [Netty](http://netty.io/) project and their
10work on [netty-tcnative](http://netty.io/wiki/forked-tomcat-native.html), giving `Conscrypt`
11similar performance.
12
13<table>
14 <tr>
15 <td><b>Homepage:</b></td>
16 <td>
17 <a href="https://conscrypt.org/">conscrypt.org</a>
18 </td>
19 </tr>
20 <tr>
21 <td><b>Mailing List:</b></td>
22 <td>
23 <a href="https://groups.google.com/forum/#!forum/conscrypt">conscrypt@googlegroups.com</a>
24 </td>
25 </tr>
26</table>
27
28Download
29-------------
30All Conscrypt artifacts target the **Java 6** runtime and are available on Maven central.
31
32#### Download JARs
33You can download
34[the JARs](http://search.maven.org/#search%7Cga%7C1%7Cg:%22org.conscrypt%22)
35directly from the Maven repositories.
36
37#### OpenJDK (i.e. non-Android)
38
39##### Native Classifiers
40
41The OpenJDK artifacts are platform-dependent since each embeds a native library for a particular
42platform. We publish artifacts to Maven Central for the following platforms:
43
44Classifier | OS | Architecture
45-----------| ------- | ---------------- |
46linux-x86_64 | Linux | x86_64 (64-bit)
47osx-x86_64 | Mac | x86_64 (64-bit)
48windows-x86 | Windows | x86 (32-bit)
49windows-x86_64 | Windows | x86_64 (64-bit)
50
51##### Maven
52
53Use the [os-maven-plugin](https://github.com/trustin/os-maven-plugin) to add the dependency:
54
55```xml
56<build>
57 <extensions>
58 <extension>
59 <groupId>kr.motd.maven</groupId>
60 <artifactId>os-maven-plugin</artifactId>
61 <version>1.4.1.Final</version>
62 </extension>
63 </extensions>
64</build>
65
66<dependency>
67 <groupId>org.conscrypt</groupId>
68 <artifactId>conscrypt-openjdk</artifactId>
69 <version>1.0.1</version>
70 <classifier>${os.detected.classifier}</classifier>
71</dependency>
72```
73
74##### Gradle
75Use the [osdetector-gradle-plugin](https://github.com/google/osdetector-gradle-plugin)
76(which is a wrapper around the os-maven-plugin) to add the dependency:
77
78```gradle
79buildscript {
80 repositories {
81 mavenCentral()
82 }
83 dependencies {
84 classpath 'com.google.gradle:osdetector-gradle-plugin:1.4.0'
85 }
86}
87
88// Use the osdetector-gradle-plugin
89apply plugin: "com.google.osdetector"
90
91dependencies {
92 compile 'org.conscrypt:conscrypt-jdk:1.0.1:' + osdetector.classifier
93}
94```
95
96##### Uber JAR
97
98For convenience, we also publish an Uber JAR to Maven Central that contains the shared
99libraries for all of the published platforms. While the overall size of the JAR is
100larger than depending on a platform-specific artifact, it greatly simplifies the task of
101dependency management for most platforms.
102
103To depend on the uber jar, simply use the `conscrypt-openjdk-uber` artifacts.
104
105###### Maven
106```xml
107<dependency>
108 <groupId>org.conscrypt</groupId>
109 <artifactId>conscrypt-openjdk-uber</artifactId>
110 <version>1.0.1</version>
111</dependency>
112```
113
114###### Gradle
115```gradle
116dependencies {
117 compile 'org.conscrypt:conscrypt-jdk-uber:1.0.1'
118}
119```
120
121
122How to Build
123------------
124
125If you are making changes to Conscrypt, see the [building
126instructions](BUILDING.md).
127
128Source Overview
129----------------------------
130
131Here's a quick readers' guide to the code to help folks get started. The high-level modules are __Common__, __Android__,
132__OpenJDK__, and __Platform__.
133
134### Common
135
136This contains the bulk of the code for both Java and C. This isn't an actual module and builds no
137artifacts. Rather, the other modules just point to this directory as source.
138
139### Android
140
141This module provides the `Platform` class for Android and also adds compatibility classes for
142supporting various versions of Android. This generates an `aar` library artifact.
143
144### OpenJDK
145
146These modules provide the `Platform` class for non-Android (OpenJDK-based) systems. It also provides
147a native library loader supports bundling the shared library with the JAR.
148
149### Platform
150This module contains code that is bundled with the Android operating system. The inclusion in the
151build is only to ensure that changes to other modules do not accidentally break the Android build.
152