diff --git a/README.md b/README.md
index d7213fd34d2fef58ecf4ddffc9765df28a0191e5..7a2643f8399f244531abcfc7514619abe021fde1 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ operations (like symmetric encryption, message authentication codes, digital
 signatures, hybrid encryption), and additional primitives are in preparation.
 Moreover, Tink lets users add new primitives or custom implementations of
 existing primitives, which allows them to build upon Tink's core architecture
-and key manangement abilities without having to fork the library.
+and key management abilities without having to fork the library.
 
 The basic use of Tink proceeds in three steps:
 
@@ -45,9 +45,9 @@ To be more concrete, here is how these steps would look like when performing
 symmetric encryption (AEAD) in a Java program:
 
 ``` java
-    import com.google.cloud.crypto.tink.Aead;
-    import com.google.cloud.crypto.tink.aead.AeadFactory;
-    import com.google.cloud.crypto.tink.KeysetHandle;
+    import com.google.crypto.tink.Aead;
+    import com.google.crypto.tink.aead.AeadFactory;
+    import com.google.crypto.tink.KeysetHandle;
     // [...]
 
     // 1. Get the key material.
@@ -73,9 +73,9 @@ the Message Authentication Code (MAC) primitive (notice the usage of
 `MacFactory`):
 
 ``` java
-    import com.google.cloud.crypto.tink.Mac;
-    import com.google.cloud.crypto.tink.mac.MacFactory;
-    import com.google.cloud.crypto.tink.KeysetHandle;
+    import com.google.crypto.tink.Mac;
+    import com.google.crypto.tink.mac.MacFactory;
+    import com.google.crypto.tink.KeysetHandle;
     // [...]
 
     // 1. Get the key material.
@@ -93,8 +93,8 @@ implementations of AEAD and MAC primitives offered by Tink, the initialization
 looks as follows:
 
 ``` java
-    import com.google.cloud.crypto.tink.aead.AeadConfig;
-    import com.google.cloud.crypto.tink.mac.MacConfig;
+    import com.google.crypto.tink.aead.AeadConfig;
+    import com.google.crypto.tink.mac.MacConfig;
     // [...]
 
     // Register standard implementations of AEAD and MAC primitives.
@@ -111,9 +111,9 @@ see [Java HOW-TO](https://github.com/google/tink/blob/master/doc/JAVA-HOWTO.md).
 
 ## Tink overview
 
-**Basic Features** Tink provides a set of basic tools to perform common crypto
-tasks in a variety of environments. The main operations are accessible via
-so-called _primitives_, which represent cryptographic tools.
+**Basic Features** Tink provides a set of basic tools to perform common
+cryptographic tasks in a variety of environments. The main operations are
+accessible via so-called _primitives_, which represent cryptographic tools.
 Currently Tink supports the following cryptographic operations:
 
 - authenticated encryption with associated data (primitive: AEAD)
diff --git a/doc/JAVA-HOWTO.md b/doc/JAVA-HOWTO.md
index 99e1333b4d77d36338f1843e553235462bf4fbd2..99643ed2bfde663f30f35596fbeb93f3fa36477f 100644
--- a/doc/JAVA-HOWTO.md
+++ b/doc/JAVA-HOWTO.md
@@ -8,14 +8,14 @@ common tasks in [Tink](https://github.com/google/tink).
 Tink provides customizable initialization, which allows for choosing specific
 implementations (identified by _key types_) of desired primitives.  This
 initialization happens via _registration_ of the implementations.  To register
-standard implementations of primtives one can use
+standard implementations of primitives one can use
 `registerStandardKeyTypes()`-methods of corresponding `Config`-classes.  For
 example if one wants to use the standard implementations of AEAD and MAC
 primitives offered by Tink, the initialization would look as follows:
 
 ``` java
-    import com.google.cloud.crypto.tink.aead.AeadConfig;
-    import com.google.cloud.crypto.tink.mac.MacConfig;
+    import com.google.crypto.tink.aead.AeadConfig;
+    import com.google.crypto.tink.mac.MacConfig;
     // (...)
 
     // Register standard implementations of AEAD and MAC primitives.
@@ -26,8 +26,8 @@ primitives offered by Tink, the initialization would look as follows:
 For custom initialization the registration proceeds directly via `Registry`-class:
 
 ``` java
-    import com.google.cloud.crypto.tink.Registry;
-    import com.google.cloud.crypto.tink.aead.AesCtrHmacAeadKeyManager;
+    import com.google.crypto.tink.Registry;
+    import com.google.crypto.tink.aead.AesCtrHmacAeadKeyManager;
     import my.custom.package.aead.MyAeadKeyManager;
     // (...)
 
@@ -46,17 +46,17 @@ For custom initialization the registration proceeds directly via `Registry`-clas
 Each `KeyManager`-implementation provides `newKey(..)`-methods that generate new
 keys of the corresponding key type.  However to avoid accidental leakage of
 sensitive key material one should be careful with mixing key(set) generation
-with key(set) useage in code.  To support the separation between these
+with key(set) usage in code.  To support the separation between these
 activities Tink package provides a command-line tool
 called [Tinkey](https://github.com/google/tink/tree/master/tools/tinkey), which
 can be used for common key management tasks.  Moreover, there is also
-[`KmsEncryptedKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/KmsEncryptedKeysetHandle.java)-class,
+[`KmsEncryptedKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KmsEncryptedKeysetHandle.java)-class,
 which enables working with keysets in which the sensitive key material is
 encrypted with a KMS-managed key.
 
 Still, if there is a need to generate a KeysetHandle with fresh key material
 directly in Java code, one can use
-[`CleartextKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/CleartextKeysetHandle.java)-class:
+[`CleartextKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java)-class:
 
 ``` java
     KeysetHandle keysetHandle = CleartextKeysetHandle.generateNew(keyTemplate);
@@ -65,24 +65,24 @@ directly in Java code, one can use
 where `keyTemplate` can be initialized with one of pre-generated templates from
 [tools/tinkey/keytemplates](https://github.com/google/tink/tree/master/tools/tinkey/keytemplates)-folder.
 Alternatively, one can use also
-[`KeysetManager`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/KeysetManager.java)-class.
+[`KeysetManager`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KeysetManager.java)-class.
 
 ## Loading Existing Keysets
-Via [`KmsEncryptedKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/KmsEncryptedKeysetHandle.java) or
-[`CleartextKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/CleartextKeysetHandle.java),
+Via [`KmsEncryptedKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KmsEncryptedKeysetHandle.java) or
+[`CleartextKeysetHandle`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java),
 
 TODO: write more in this section
 
 ## Creating and Using a Primitive
 
-After all needed KeyManagers have been registered, one instantiates a primitive
-via the corresponding factory.  For example, here is how to instantiate and use
+After all needed KeyManagers have been registered, one creates a primitive
+via the corresponding factory.  For example, here is how to create and use
 AEAD-primitive:
 
 ``` java
-    import com.google.cloud.crypto.tink.Aead;
-    import com.google.cloud.crypto.tink.aead.AeadFactory;
-    import com.google.cloud.crypto.tink.KeysetHandle;
+    import com.google.crypto.tink.Aead;
+    import com.google.crypto.tink.aead.AeadFactory;
+    import com.google.crypto.tink.KeysetHandle;
     // (...)
 
     // 1. Get the key material.
@@ -95,13 +95,125 @@ AEAD-primitive:
 
 
 ## Key Rotation
-Via [Tinkey](https://github.com/google/tink/tree/master/tools/tinkey) or
-[`KeysetManager`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/cloud/crypto/tink/KeysetManager.java).
 
-TODO: write more in this section
+The support for key rotation in Tink is provided via
+[`KeysetManager`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KeysetManager.java)-class.
+One has to provide a `KeysetHandle`-object that contains the keyset that should
+be rotated, and a specification of the new key via a
+[`KeyTemplate`](https://github.com/google/tink/blob/master/proto/tink.proto#L50)-message.
+
+``` java
+    import com.google.crypto.tink.KeysetHandle;
+    import com.google.crypto.tink.KeysetManager;
+    import com.google.crypto.tink.proto.KeyTemplate;
+
+    KeysetHandle keysetHandle = ...;   // existing keyset
+    KeyTemplate keyTemplate = ...;     // template for the new key
+
+    KeysetHandle rotatedKeysetHandle = new KeysetManager.Builder()
+        .setKeysetHandle(keysetHandle)
+        .build()
+        .rotate(keyTemplate)
+        .getKeysetHandle();
+```
+
+Some common specifications are available as pre-generated templates
+in [examples/keytemplates](https://github.com/google/tink/tree/master/examples/keytemplates)-folder, and can be accessed via `...KeyTemplates.java`
+classes of the respective primitives.  After a successful rotation
+the resulting keyset contains a new key generated according to the 
+specification in `keyTemplate`, and the new key becomes 
+the _primary key_ of the keyset.  For the rotation to succeed the
+`Registry` must contain a key manager for the key type specified in
+`keyTemplate`.
+
+Alternatively, one can
+use [Tinkey](https://github.com/google/tink/tree/master/tools/tinkey) to rotate
+a key.
+
+TODO: write more about Tinkey
 
 ## Custom Implementation of a Primitive
-TODO: write this section
+
+**NOTE**: The usage of **custom key managers should be enjoyed
+responsibly**: we (i.e. Tink developers) have no way checking or enforcing that
+a custom implementation satisfies security properties of the corresponding
+primitive interface, so it is up to the implementer and the user of the custom
+implementation ensure the required properties.
+
+As described in [Tink overview](../README.md#tink-overview), the main
+cryptographic operations offered by Tink are accessible via so-called
+_primitives_, which essentially are interfaces that represent corresponding
+cryptographic functionalities.  While Tink comes with several standard
+implementations of common primitives, it allows also for adding custom
+implementations of primitives.  Such implementations allow for seamless
+integration of Tink with custom third-party cryptographic schemes or hardware
+modules, and in combination with [key rotation](#key-rotation)-features enable
+painless migration between cryptographic schemes.
+
+To create a custom implementation of a primitive proceed as follows:
+
+1. Determine for which _primitive_ a custom implementation is needed.
+2. Define protocol buffers that hold key material and parameters for the custom
+   cryptographic scheme; the name of the key protocol buffer (a.k.a. type URL)
+   determines the _key type_ for the custom implementation.
+3. Implement [`KeyManager`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KeyManager.java) interface for the _primitive_
+   from step #1 and the _key type_ from step #2.
+
+To use a custom implementation of a primitive in an application, register with
+the [`Registry`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/Registry.java) the  custom `KeyManager`-implementation 
+(from step #3 above) for the custom key type (from step #2 above):
+
+``` java
+    Registry.INSTANCE.registerKeyManager(keyType, keyManager);
+```
+
+Afterwards the implementation will be accessed automatically by the `Factory`
+corresponding to the primitive (when keys of the specific key type are in use),
+or can be retrieved directly via `Registry.getKeyManager(keyType)`.
+
+When defining the protocol buffers for the key material and parameters (step #2
+above), one should provide definitions of three messages
+(see [tink.proto](https://github.com/google/tink/blob/master/proto/tink.proto)
+for details):
+
+ * `...Params`: parameters of an instantiation of the primitive,
+   needed when a key is being used.
+ * `...Key`: the actual key proto, contains the key material and the
+   corresponding `...Params`-proto.
+ * `...KeyFormat`: parameters needed to generate a new key.
+
+Alternatively, depending on the use case requirements, one can skip step #2
+entirely and re-use for the key material an existing protocol buffer messages.
+In such a case one should not configure the Registry via the method
+`registerStandardKeyTypes()` of the corresponding `Config`-class, but rather
+register the needed `KeyManager`-instances manually.
+
+For a concrete example, let's assume that we'd like a custom implementation
+of
+[`Aead`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/Aead.java)-primitive
+(step #1).  We define then three protocol buffer messages (step #2):
+
+ * `MyCustomAeadParams`: holds parameters needed for the use of the key material.
+ * `MyCustomAeadKey`: holds the actual key material and parameters needed for its use.
+ * `MyCustomAeadKeyFormat`: holds parameters needed for generation of a new `MyCustomAeadKey`-key.
+
+The corresponding _key type_ is defined as
+
+``` java
+    String keyType = "type.googleapis.com/mycompany.mypackage.MyCustomAeadKey";`
+```
+
+and the corresponding _key manager_ implements (step #3) the interface [`KeyManager<Aead>`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/KeyManager.java)
+
+``` java
+    class MyCustomAeadKeyManager implements KeyManager<Aead> {
+      // ...
+    }
+```
+
+After registering `MyCustomAeadKeyManager` with the Registry we can use it
+via [`AeadFactory`](https://github.com/google/tink/blob/master/java/src/main/java/com/google/crypto/tink/aead/AeadFactory.java).
+
 
 ## Adding a Custom Primitive
 TODO: write this section
diff --git a/tools/tinkey/README.md b/tools/tinkey/README.md
index 9774ad954e30eeb44e350b22a801fbde748f162e..65ed1221e2cc7c7e37eed369298e3f20e062a096 100644
--- a/tools/tinkey/README.md
+++ b/tools/tinkey/README.md
@@ -1 +1,20 @@
 # Tinkey is a command-line tool to manage keys for Tink.
+
+**Usage**: `tinkey <command> [<args>]
+
+Available commands:
+
+ * `add`: Generates and adds a new key to an existing keyset.
+ * `change-master-key`: Changes the master key of a keyset. The keyset will be
+   encrypted with the new master key.
+ * `create`: Creates a new keyset.
+ * `create-public-keyset`: Creates a public keyset from an existing private keyset.
+ * `create-key-template`: Creates a new key template.
+ * `destroy`: Destroys a specified key in a keyset.
+ * `disable`: Disables a specified key in a keyset.
+ * `enable`: Enables a specified key in a keyset.
+ * `list`: Lists keys in a keyset.
+ * `rotate`: Performs a key rotation in a keyset.
+
+To obtain info about arguments available/required for a command, run `tinkey
+<command>` without further arguments.