diff --git a/src/cargo/util/toml.rs b/src/cargo/util/toml.rs
index 82ea4533aca..207e22b7db2 100644
--- a/src/cargo/util/toml.rs
+++ b/src/cargo/util/toml.rs
@@ -134,6 +134,9 @@ pub fn to_manifest(contents: &[u8],
     return Ok((manifest, paths));
 
     fn add_unused_keys(m: &mut Manifest, toml: &toml::Value, key: String) {
+        if key == "package.metadata" {
+            return
+        }
         match *toml {
             toml::Value::Table(ref table) => {
                 for (k, v) in table.iter() {
diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index c03c1b66274..4dcb7609a9a 100644
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -126,6 +126,25 @@ provide useful information to users of the registry and also influence the
 search ranking of a crate. It is highly discouraged to omit everything in a
 published crate.
 
+## The `metadata` Table (optional)
+
+Cargo by default will warn about unused keys in `Cargo.toml` to assist in
+detecting typos and such. The `package.metadata` table, however, is completely
+ignored by Cargo and will not be warned about. This section can be used for
+tools which would like to store project configuration in `Cargo.toml`. For
+example:
+
+```toml
+[package]
+name = "..."
+# ...
+
+# Metadata used when generating an Android APK, for example.
+[package.metadata.android]
+package-name = "my-awesome-android-app"
+assets = "path/to/static"
+```
+
 # Dependency Sections
 
 See the [specifying dependencies page](specifying-dependencies.html) for
diff --git a/tests/build.rs b/tests/build.rs
index 7c4876c7f56..6d196ece302 100644
--- a/tests/build.rs
+++ b/tests/build.rs
@@ -2240,3 +2240,26 @@ fn explicit_color_config_is_propagated_to_rustc() {
         -L dependency=[..]target[..]debug[..]deps`
 "));
 }
+
+#[test]
+fn no_warn_about_package_metadata() {
+    let p = project("foo")
+        .file("Cargo.toml", r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [package.metadata]
+            foo = "bar"
+            a = true
+            b = 3
+
+            [package.metadata.another]
+            bar = 3
+        "#)
+        .file("src/lib.rs", "");
+    assert_that(p.cargo_process("build"),
+                execs().with_status(0)
+                       .with_stderr("[..] foo v0.0.1 ([..])\n"));
+}