Rust: Add API for calculating digests (SHA-256, etc.).

Author: briansmith

.gitignore

@@ -17,3 +17,7 @@ doc/doc.css
 *.userosscache
 *.vsp
 *.vspx
+
+# Cargo Junk
+Cargo.lock
+target/

BUILDING.md

@@ -13,8 +13,23 @@ affect building:
 
 
 
-Building on Linux and Similar Platforms
-=======================================
+Building the Rust Library
+=========================
+
+*ring*'s Rust crate is named ```rust_ring```. You can build it
+using ```cargo build --release``` and you can run the tests
+with ```cargo test --release```. When you use ```cargo build```, you don't need
+to follow the instructions below to build the C code separately, because
+[build.rs](build.rs) does that automatically. Unlike a lot of Rust wrappers
+around C libraries, the build script for ```ring``` is implemented using the
+msbuild projects (on Windows) or the Makefile (on other platforms). Because
+this is a little unusual, I would be particularly grateful if you could report
+any problems building (or using) *ring*'s Rust crate.
+
+
+
+Building the C Library on Linux and Similar Platforms
+=====================================================
 
 There is no ./configure step.
 
@@ -62,8 +77,8 @@ be in ```$PATH```. Example:
 
 
 
-Building on Windows
-===================
+Building the C Library on Windows
+=================================
 
 Note that currently the assembly language optimizations are NOT built on
 Windows yet, only because the additions to the project files to support doing

Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+authors = ["Brian Smith <[email protected]>"]
+build = "build.rs"
+description = "A Rust interface for a simplification of BoringSSL's libcrypto."
+license-file = "LICENSE"
+name = "rust-ring"
+readme = "README.md"
+repository = "https://github.com/briansmith/ring"
+version = "0.1.0"
+
+[lib]
+name = "rust_ring"
+crate-type = ["rlib"]
+
+[dependencies]
+libc = "0.1"
+
+# TODO: [dev-dependencies]
+rustc-serialize = "0.3.15"
+
+[profile.release]
+opt-level = 3
+debug = false
+rpath = false
+lto = true
+debug-assertions = false
+codegen-units = 1

README.md

@@ -11,12 +11,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 What is *ring*?
 ===============
 
-*ring* is a simplified version of BoringSSL that has the following features
-removed:
-
-* TLS (libssl)
-* X.509 (crypto/pem, crypto/x509, crypto/x509v3)
-* ASN.1 (crypto/asn1 and crypto/obj)
+*ring* is a simplified version of BoringSSL with C and Rust APIs.
 
 *ring* makes OpenSSL's high-quality, high-performance crypto primitives
 conveniently available to new crypto libraries written in safer (than C)
@@ -36,6 +31,32 @@ were developed for *ring* have already been integrated upstream in BoringSSL.
 
 
 
+The Rust API
+============
+The first part of the ```rust_ring``` Rust crate is now available.
+
+Currently only support for cryptographic digests is available. See the
+documentation at
+https://briansmith.github.io/ring/rust_ring/. Also take a look at the example
+program [checkdigest.rs](examples/checkdigest.rs).
+
+See [Building the Rust Library](BUILDING.md#building-the-rust-library) for
+instructions on how to build it (hint: it's just ```cargo build```).
+
+
+
+The C API
+=========
+The C API is the same as BoringSSL's, except that its SSL/TLS, X.509, and
+ASN.1 APIs have been removed. See
+[this](https://github.com/briansmith/ring/blob/wip/BUILDING.md#building-the-c-library-on-windows)
+(for Windows) and
+[this](https://github.com/briansmith/ring/blob/wip/BUILDING.md#building-the-c-library-on-linux-and-similar-platforms)
+(for other platforms) for instructions on how to build *ring* and incorporate
+it into your project.
+
+
+
 Warning: The ```wip``` Branch Gets Rebased Frequently
 =====================================================
 
@@ -46,14 +67,6 @@ I intend to never rebase, and then I will delete the ```wip``` branch.
 
 
 
-Building
-========
-
-See [BUILDING.md](BUILDING.md) for instructions on how to build *ring* and
-incorporate it into your project.
-
-
-
 Contributing
 ============
 

build.rs

@@ -0,0 +1,87 @@
+// Copyright 2015 Brian Smith.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+use std::env;
+use std::path::Path;
+
+fn main() {
+    let host_str = env::var("HOST").unwrap();
+    let host_triple = host_str.split('-').collect::<Vec<&str>>();
+
+    let target_str = env::var("TARGET").unwrap();
+    let target_triple = target_str.split('-').collect::<Vec<&str>>();
+
+    let out_dir = env::var("OUT_DIR").unwrap();
+
+    let use_msbuild = host_triple.contains(&"msvc") &&
+                      target_triple.contains(&"msvc");
+
+    let debug_var = env::var("DEBUG").unwrap();
+    let is_debug = match debug_var.as_ref() {
+        "true" => true,
+        "false" => false,
+        _ => panic!("$DEBUG is not 'true' or 'false': {}", debug_var)
+    };
+
+    // TODO: deal with link-time-optimization flag.
+
+    let command_name;
+    let args;
+    let lib_path;
+    if !use_msbuild {
+        command_name = "make";
+        // Environment variables |CC|, |CXX|, etc. will be inherited from this
+        // process.
+        let cmake_build_type = "RELWITHDEBINFO"; // TODO: support DEBUG mode.
+        args = vec![
+            format!("-j{}", env::var("NUM_JOBS").unwrap()),
+            format!("TARGET={}", target_str),
+            format!("CMAKE_BUILD_TYPE={}", cmake_build_type),
+            format!("BUILD_PREFIX={}/", out_dir),
+        ];
+        lib_path = Path::new(&out_dir).join("lib");
+    } else {
+        // TODO: This assumes that the package is being built under a
+        // {VS2013,VS2015} {x86,x64} Native Tools Command Prompt. It would be
+        // nice if we didn't require that to be the case. At least it should be
+        // documented.
+        command_name = "msbuild";
+        let platform = match target_triple[0] {
+            "i686" => "Win32",
+            "x86_64" => "x64",
+            _ => panic!("unexpected ARCH: {}", target_triple[0])
+        };
+        let configuration = if is_debug { "Debug" } else { "Release" };
+        args = vec![
+            format!("ring.sln"),
+            format!("/m:{}", env::var("NUM_JOBS").unwrap()),
+            format!("/p:Platform={}", platform),
+            format!("/p:Configuration={}", configuration),
+            format!("/p:OutRootDir={}/", out_dir),
+        ];
+        lib_path = Path::new(&out_dir).join("lib");
+    }
+
+    if !std::process::Command::new(command_name)
+            .args(&args)
+            .status()
+            .unwrap_or_else(|e| { panic!("failed to execute {}: {}",
+                            command_name, e); })
+            .success() {
+        panic!("{} execution failed", command_name);
+    }
+
+    println!("cargo:rustc-link-search=native={}", lib_path.to_str().unwrap());
+    println!("cargo:rustc-link-lib=static=ring");
+}

examples/checkdigest.rs

@@ -0,0 +1,113 @@
+// Copyright 2015 Brian Smith.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND AND THE AUTHORS DISCLAIM ALL WARRANTIES
+// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY
+// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+extern crate rust_ring;
+extern crate rustc_serialize;
+
+use rust_ring::{Digest, SHA256, SHA384, SHA512};
+use rustc_serialize::hex::FromHex;
+use std::error::Error;
+use std::io::{Read, Write};
+
+
+fn print_usage(program_name: &str) {
+    let program_file_name = std::path::Path::new(program_name)
+                                .file_name().unwrap().to_str().unwrap();
+
+    println!(
+        "Usage: {} sha256|sha384|sha512 <digest value in hex> <filename>\n\
+         \n\
+         On success nothing is output, and 0 is returned.\n\
+         On failure, an error message is printed, and a non-zero value is returned\n\
+         \n\
+         Example:\n\
+         {} sha256 \
+           def7352915ac84bea5e2ed16f6fff712d35de519799777bf927e2a567ab53b7e \
+           LICENSE",
+         program_file_name, program_file_name);
+}
+
+fn run(digest_name: &str, expected_digest_hex: &str,
+       file_path: &std::path::Path) -> Result<(), &'static str> {
+    enum D {
+        SHA256(SHA256),
+        SHA384(SHA384),
+        SHA512(SHA512),
+    }
+
+    let mut digest = try!(match digest_name {
+        "sha256" => Ok(D::SHA256(SHA256::new())),
+        "sha384" => Ok(D::SHA384(SHA384::new())),
+        "sha512" => Ok(D::SHA512(SHA512::new())),
+        _ => Err("unsupported digest algorithm")
+    });
+
+    {
+        let mut file = match std::fs::File::open(file_path) {
+            Ok(file) => file,
+            // TODO: don't use panic here.
+            Err(why) => panic!("couldn't open {}: {}", file_path.display(),
+                               why.description())
+        };
+
+        let mut chunk = vec![0u8; 128 * 1024];
+        loop {
+            match file.read(&mut chunk[..]) {
+                Ok(0) => break,
+                Ok(bytes_read) => match digest {
+                    D::SHA256(ref mut ctx) => ctx.update(&chunk[0..bytes_read]),
+                    D::SHA384(ref mut ctx) => ctx.update(&chunk[0..bytes_read]),
+                    D::SHA512(ref mut ctx) => ctx.update(&chunk[0..bytes_read]),
+                },
+                // TODO: don't use panic here
+                Err(why) => panic!("couldn't open {}: {}", file_path.display(),
+                               why.description())
+            }
+        }
+    }
+
+    let matched = match expected_digest_hex.from_hex() {
+        Ok(expected) => match digest {
+            D::SHA256(ref mut ctx) => &expected[..] == &ctx.finish()[..],
+            D::SHA384(ref mut ctx) => &expected[..] == &ctx.finish()[..],
+            D::SHA512(ref mut ctx) => &expected[..] == &ctx.finish()[..],
+        },
+        Err(_) => panic!("syntactically invalid digest")
+    };
+
+    match matched {
+        true => Ok(()),
+        false => Err("digest mismatch") // TODO: calculated digest.
+    }
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+
+    if args.iter().any(|arg| arg == "-h") {
+        print_usage(&args[0]);
+        return
+    } else if args.len() < 4 {
+        print_usage(&args[0]);
+        std::process::exit(1);
+    }
+
+    match run(&args[1], &args[2], std::path::Path::new(&args[3])) {
+        Ok(x) => x,
+        Err(s) => {
+            let _ = writeln!(&mut std::io::stderr(), "{}", s);
+            std::process::exit(1)
+        }
+    }
+}

include/openssl/md5.h

@@ -92,6 +92,7 @@ OPENSSL_EXPORT uint8_t *MD5(const uint8_t *data, size_t len, uint8_t *out);
  * transformation using the state from |md5| and 64 bytes from |block|. */
 OPENSSL_EXPORT void MD5_Transform(MD5_CTX *md5, const uint8_t *block);
 
+/* ring: Keep this in sync with |md5_state_st| in digest.rs. */
 struct md5_state_st {
   uint32_t A, B, C, D;
   uint32_t Nl, Nh;

include/openssl/sha.h

@@ -92,6 +92,7 @@ OPENSSL_EXPORT int SHA1_Final(uint8_t *md, SHA_CTX *sha);
  * transformation using the state from |sha| and 64 bytes from |block|. */
 OPENSSL_EXPORT void SHA1_Transform(SHA_CTX *sha, const uint8_t *block);
 
+/* ring: Keep this in sync with |sha_state_st| in digest.rs. */
 struct sha_state_st {
   uint32_t h0, h1, h2, h3, h4;
   uint32_t Nl, Nh;
@@ -143,6 +144,7 @@ OPENSSL_EXPORT int SHA256_Final(uint8_t *md, SHA256_CTX *sha);
  * transformation using the state from |sha| and 64 bytes from |block|. */
 OPENSSL_EXPORT void SHA256_Transform(SHA256_CTX *sha, const uint8_t *data);
 
+/* ring: Keep this in sync with |sha256_state_st| in digest.rs. */
 struct sha256_state_st {
   uint32_t h[8];
   uint32_t Nl, Nh;
@@ -198,6 +200,7 @@ OPENSSL_EXPORT int SHA512_Final(uint8_t *md, SHA512_CTX *sha);
  * transformation using the state from |sha| and 64 bytes from |block|. */
 OPENSSL_EXPORT void SHA512_Transform(SHA512_CTX *sha, const uint8_t *data);
 
+/* ring: Keep this in sync with |sha512_state_st| in digest.rs. */
 struct sha512_state_st {
   uint64_t h[8];
   uint64_t Nl, Nh;