1# Hacking Tink for Java and Android 2 3## Building Tink 4 5* Install [Bazel](https://docs.bazel.build/versions/master/install.html). 6 7* To build Java, install Android SDK 23 or newer and set the ANDROID_HOME 8 environment variable to the path of your Android SDK. On macOS, the SDK is 9 usually installed at `/Users/username/Library/Android/sdk/`. You also need 10 Android SDK Build Tools 24.0.3 or newer. 11 12* The javadoc targets require using JDK 8. 13 14* Check out the source code, navigate to the Java Bazel workspace and execute 15 all test targets in the project: 16 17```shell 18git clone https://github.com/google/tink 19cd tink/java_src 20bazel test ... 21``` 22 23## Code structure 24 25### Java packages 26 27* **com.google.crypto.tink** This package consists of only the core of Tink, 28 including the primitive interfaces and key management APIs. Users that 29 [develop their own primitives or key 30 types](JAVA-HOWTO.md#custom-implementation-of-a-primitive) 31 can depend only on this package and exclude the rest. 32 33 * internal dependencies: none 34 * external dependencies 35 * com.google.protobuf.ByteString 36 * com.google.protobuf.MessageLite 37 * javax.annotation.concurrent.GuardedBy 38 * com.google.gson.JsonArray; 39 * com.google.gson.JsonObject; 40 * com.google.gson.JsonParseException; 41 * com.google.gson.JsonParser; 42 * com.google.gson.internal.Streams; 43 * com.google.gson.stream.JsonReader; 44 * API backward-compatibility guarantee: yes 45 46* **com.google.crypto.tink.aead|daead|mac|signature|hybrid|streamingaead** 47 These packages contain the public APIs exposing the primitives that Tink 48 supports. 49 50 * internal dependencies 51 * com.google.crypto.tink 52 * com.google.crypto.tink.subtle 53 * com.google.crypto.tink.proto 54 * external dependencies 55 * com.google.protobuf.ByteString 56 * com.google.protobuf.MessageLite 57 * javax.annotation.concurrent.GuardedBy 58 * API backward-compatibility guarantee: yes 59 60* **com.google.crypto.tink.integration.gcpkms** This package allows users to 61 store keys in [Google Cloud Key Management 62 System](https://cloud.google.com/kms/). 63 64 * internal dependencies 65 * com.google.crypto.tink 66 * com.google.crypto.tink.subtle 67 * external dependencies 68 * com.google.api.services.cloudkms.v1 69 * com.google.api.client.googleapis.auth.oauth2.GoogleCredential 70 * com.google.api.client.http.javanet.NetHttpTransport 71 * com.google.api.client.json.jackson2.JacksonFactory 72 * com.google.auto.service.AutoService 73 * API backward-compatibility guarantee: yes 74 75* **com.google.crypto.tink.integration.awskms** This package allows users to 76 store keys in [AWS Key Management System](https://aws.amazon.com/kms/). 77 78 * internal dependencies 79 * com.google.crypto.tink 80 * com.google.crypto.tink.subtle 81 * external dependencies 82 * com.amazonaws.AmazonServiceException 83 * com.amazonaws.auth.AWSCredentialsProvider 84 * com.amazonaws.auth.DefaultAWSCredentialsProviderChain 85 * com.amazonaws.auth.PropertiesFileCredentialsProvider 86 * com.amazonaws.services.kms 87 * com.google.auto.service.AutoService 88 * API backward-compatibility guarantee: yes 89 90* **com.google.crypto.tink.integration.android** This package allows Android 91 users to store keys in private preferences, wrapped with master key in 92 [Android 93 Keystore](https://developer.android.com/training/articles/keystore.html). 94 The integration with Android Keystore only works on Android M (API level 23) 95 or higher. 96 97 * internal dependencies 98 * com.google.crypto.tink 99 * com.google.crypto.tink.subtle 100 * external dependencies 101 * Android SDK 23 or higher 102 * API backward-compatibility guarantee: yes 103 104* **com.google.crypto.tink.subtle** This package contains implementations of 105 primitives. Aside from the primitive interfaces, this package is not allowed 106 to depend on anything else in Tink. Users should never directly depend on 107 this package. 108 109 * internal dependencies 110 * com.google.crypto.tink.Aead 111 * com.google.crypto.tink.DeterministicAead 112 * com.google.crypto.tink.HybridDecrypt 113 * com.google.crypto.tink.HybridEncrypt 114 * com.google.crypto.tink.Mac 115 * com.google.crypto.tink.StreamingAead 116 * com.google.crypto.tink.PublicKeySign 117 * com.google.crypto.tink.PublicKeyVerify 118 * external dependencies 119 * javax.annotation.concurrent.GuardedBy 120 * API backward-compatibility guarantee: no 121 122* **com.google.crypto.tink.proto** This package contains protobuf 123 auto-generated Java code. Users should never directly depend on this 124 package. 125 126 * internal dependencies: none 127 * external dependencies: none 128 * API backward-compatibility guarantee: no 129 130### Bazel targets 131 132* **//java** This public target exports all public APIs, except 133 com.google.crypto.tink.integration.android and 134 com.google.crypto.tink.CleartextKeysetHandle. It is expected to run on 135 servers, not Android. 136 137* **//java:android** Similar to java, but this public target adds 138 com.google.crypto.tink.integration.android, and removes 139 com.google.crypto.tink.integration.gcpkms and 140 com.google.crypto.tink.integration.awskms. To build it, one needs Android 141 SDK 23 or newer. 142 143* **//java:subtle** This restricted target exposes 144 com.google.crypto.tink.subtle. It's restricted because most users are 145 supposed not to use it directly. 146 147* **//java:cleartext_keyset_handle** and 148 **//java:cleartext_keyset_handle_android** This restricted target exposes 149 com.google.crypto.tink.CleartextKeysetHandle. It's restricted because it 150 allows users to read cleartext keysets from disk, which is a bad practice. 151 152* **//java:protos** and **//java:protos_android** This restricted target 153 exposes com.google.crypto.tink.proto. It's restricted because most users are 154 supposed not to use it directly. 155 156### Maven jars 157 158* **[com.google.crypto.tink:tink](https://mvnrepository.com/artifact/com.google.crypto.tink/tink)** 159 includes //java and //java:cleartext_keyset_handle. 160 161* **[com.google.crypto.tink:tink-android](https://mvnrepository.com/artifact/com.google.crypto.tink/tink-android)** 162 includes //java:android and //java:cleartext_keyset_handle_android 163