Update Rust binding to v0.0.3 (#349)

* Update Rust binding to v0.0.3

This is a cumulative update of rust-themis to version 0.0.3 from here:

    https://github.com/ilammy/rust-themis

You can see `git diff v0.0.2..v0.0.3` there for detailed changes.
Obviously, the diff does not apply as is and has been manually merged
into this repository, taking into account previous changes and the new
code layout.

Some notable changes since v0.0.2:

- Secure zeroing of key material is included into this update.

- Rust 2018 edition support and API documentation updates
  introduce a lot of diff clutter. Deal with it.

- Vendored build is back. It is mostly intended as a hack for
  docs.rs support rather than an actual use-case.

  This brings a new `libthemis-src` crate to contain the whole
  source code of Themis. It is implemented with a symbolic link
  to the top of the repository. Hopefully, this loop does not
  break anything anywhere...

  For one, symlink usage *has* broken `libthemis-src` compilation
  (due to a bug in 3rd-party crate) so vendored build is currently
  failing. We'll fix this issue later.

- There are some other interesting TODOs added and removed during
  the development. Just grep for them in you're interested.

These changes do not integrate rust-themis into the main build system.
It is possible to build rust-themis alone with Cargo, but the Makefile
does not know about us yet. This will be added later.

* Don't use empty keys in Secure Cell examples

Secure Cell does not allow empty keys. Encryption and decryption will
fail if an empty key is used, but this will be detected later, not at
the construction site.

Currently we don't do anything about it (so just update the API docs),
but later this will become an enforced assertion.

* Context Imprint mode requires non-empty context

Secure Cell *requires* non-empty user context when in context imprint
mode. It fails to operate if the provided context is empty. Currently
this is noted only in the very last example in the module-level
documentation. Let's be more explicit about this.

Later we'll get even more serious and add some assertions in the code
as well as a "Panics" section in the docs.

Cargo.toml

@@ -1,6 +1,7 @@
 [package]
 name = "themis"
-version = "0.0.2"
+version = "0.0.3"
+edition = "2018"
 authors = ["rust-themis developers"]
 description = "High-level cryptographic services for storage and messaging"
 homepage = "https://www.cossacklabs.com/themis/"
@@ -21,6 +22,23 @@ include = [
 [lib]
 path = "src/wrappers/themis/rust/src/lib.rs"
 
+[features]
+vendored = ["bindings/vendored"]
+
+[dependencies]
+bindings = { package = "libthemis-sys", path = "src/wrappers/themis/rust/libthemis-sys", version = "=0.0.3" }
+zeroize = "0.5.2"
+
+[dev-dependencies]
+byteorder = "1.2.7"
+clap = "2.32"
+log = "0.4.6"
+env_logger = "0.6.0"
+
+[package.metadata.docs.rs]
+features = ["vendored"]
+dependencies = ["libssl-dev"]
+
 [[example]]
 name = "keygen"
 path = "docs/examples/rust/keygen.rs"
@@ -64,12 +82,3 @@ path = "tests/rust/secure_message.rs"
 [[test]]
 name = "secure_session"
 path = "tests/rust/secure_session.rs"
-
-[dependencies]
-libthemis-sys = { path = "src/wrappers/themis/rust/libthemis-sys", version = "=0.0.2" }
-
-[dev-dependencies]
-byteorder = "1.2.7"
-clap = "2.32"
-log = "0.4.5"
-env_logger = "0.5.13"

docs/examples/rust/README.md

@@ -17,10 +17,10 @@ Here we have some examples of Themis usage.
 
 You can run the examples with Cargo like this:
 
-```console
+```
 $ cargo run --example keygen -- --help
-keygen 0.0.1
-Generating private-public ECDSA key pairs.
+keygen 0.0.3
+Generating ECDSA key pairs.
 
 USAGE:
     keygen [OPTIONS]
@@ -30,8 +30,8 @@ FLAGS:
     -V, --version    Prints version information
 
 OPTIONS:
-        --private <path>    Private key file (default: private.key)
-        --public <path>     Public key file (default: public.key)
+        --public <path>    Public key file (default: public.key)
+        --secret <path>    Secret key file (default: secret.key)
 ```
 
 Note that the arguments are passed after `--`.
@@ -85,46 +85,46 @@ It is deliberately kept simple,
 but the same principle can be applied to properly framed TCP transports
 as well as to using Tokio for async IO instead of blocking stdlib.
 
-Usually you don't need to specify any custom options,
+Usually you don’t need to specify any custom options,
 the command-line defaults are expected to work right away.
 But you can override the defaults for port assignment and key file locations if necessary.
 
-First you'll need to generate the keys for clients.
+First you’ll need to generate the keys for clients.
 It also may be useful to enable logging before starting the server.
 This example uses [`env_logger` crate][env_logger] for logging
 which is configurable via environment variable `RUST_LOG`.
 
-[env_logger]: https://docs.rs/env_logger/0.6.0/env_logger/
+[env_logger]: https://crates.io/crates/env_logger
 
-```console
+```
 $ export RUST_LOG=secure_message=info
 $ cargo run --example keygen
 ```
 
 Then you can start up the server as well as some clients
 (in separate terminal sessions):
 
-```console
+```
 $ cargo run --example secure_message_server
  INFO 2018-09-30T19:39:49Z: secure_message_server: listening on port 7573
  INFO 2018-09-30T19:40:33Z: secure_message_server: new peer: [::1]:56375
  INFO 2018-09-30T19:40:36Z: secure_message_server: new peer: [::1]:56376
 ```
 
-```console
+```
 $ cargo run --example secure_message_client_encrypt
 2: hello
 1: hello
 ```
 
 The first message from the client will introduce it to the server
-after which the server will relay other clients' messages to the newly joined peer.
-(Sorry, you'll have to manually type in nicknames at the moment.)
+after which the server will relay other clients’ messages to the newly joined peer.
+(Sorry, you have to manually type in nicknames at the moment.)
 
 The clients use the generated keys to secure communications.
 You can observe the exchange with `tcpdump`:
 
-```console
+```
 $ sudo tcpdump -i any -n -X udp port 7573
 tcpdump: data link type PKTAP
 tcpdump: verbose output suppressed, use -v or -vv for full protocol decode

docs/examples/rust/keygen.rs

@@ -12,13 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[macro_use]
-extern crate clap;
-extern crate themis;
-
 use std::fs::File;
 use std::io::{self, Write};
 
+use clap::clap_app;
 use themis::keygen::gen_ec_key_pair;
 
 fn main() {
@@ -27,7 +24,8 @@ fn main() {
         (about: "Generating ECDSA key pairs.")
         (@arg secret: --secret [path] "Secret key file (default: secret.key)")
         (@arg public: --public [path] "Public key file (default: public.key)")
-    ).get_matches();
+    )
+    .get_matches();
     let secret_path = matches.value_of("secret").unwrap_or("secret.key");
     let public_path = matches.value_of("public").unwrap_or("public.key");
 

docs/examples/rust/secure_cell.rs

@@ -12,13 +12,10 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[macro_use]
-extern crate clap;
-extern crate themis;
-
 use std::fs::File;
 use std::io::{self, Read, Write};
 
+use clap::clap_app;
 use themis::secure_cell::SecureCell;
 
 fn main() {
@@ -32,7 +29,8 @@ fn main() {
         (@arg password: -p --password <string> "Password to use")
         (@arg input:  +required "Input file")
         (@arg output: +required "Output file")
-    ).get_matches();
+    )
+    .get_matches();
 
     let encrypt = !matches.is_present("decrypt");
     let password = matches.value_of("password").unwrap();

docs/examples/rust/secure_compare.rs

@@ -12,15 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-extern crate byteorder;
-#[macro_use]
-extern crate clap;
-extern crate themis;
-
 use std::io::{self, Read, Write};
 use std::net::{TcpListener, TcpStream};
 
 use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
+use clap::clap_app;
 use themis::secure_comparator::SecureComparator;
 
 fn main() {
@@ -40,7 +36,8 @@ fn main() {
             (about: "Connect to server for comparison")
             (@arg address: -c --connect [address] "Server address (default: [::1]:7575)")
         )
-    ).get_matches();
+    )
+    .get_matches();
 
     let mut comparison = SecureComparator::new();
 

docs/examples/rust/secure_message_client_encrypt.rs

@@ -12,10 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[macro_use]
-extern crate clap;
-extern crate env_logger;
-extern crate themis;
 #[macro_use]
 extern crate log;
 
@@ -25,6 +21,7 @@ use std::net::UdpSocket;
 use std::sync::Arc;
 use std::thread;
 
+use clap::clap_app;
 use themis::keys::{KeyPair, PublicKey, SecretKey};
 use themis::secure_message::SecureMessage;
 
@@ -37,7 +34,8 @@ fn main() {
         (@arg secret: --secret [path] "Secret key file (default: secret.key)")
         (@arg public: --public [path] "Public key file (default: public.key)")
         (@arg address: -c --connect [addr] "Relay server address (default: localhost:7573)")
-    ).get_matches();
+    )
+    .get_matches();
 
     let secret_path = matches.value_of("secret").unwrap_or("secret.key");
     let public_path = matches.value_of("public").unwrap_or("public.key");

docs/examples/rust/secure_message_client_verify.rs

@@ -12,10 +12,6 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[macro_use]
-extern crate clap;
-extern crate env_logger;
-extern crate themis;
 #[macro_use]
 extern crate log;
 
@@ -24,6 +20,7 @@ use std::io::{self, Read, Write};
 use std::net::UdpSocket;
 use std::thread;
 
+use clap::clap_app;
 use themis::keys::{PublicKey, SecretKey};
 use themis::secure_message::{SecureSign, SecureVerify};
 
@@ -36,7 +33,8 @@ fn main() {
         (@arg secret: --secret [path] "Secret key file (default: secret.key)")
         (@arg public: --public [path] "Public key file (default: public.key)")
         (@arg address: -c --connect [addr] "Relay server address (default: localhost:7573)")
-    ).get_matches();
+    )
+    .get_matches();
 
     let secret_path = matches.value_of("secret").unwrap_or("secret.key");
     let public_path = matches.value_of("public").unwrap_or("public.key");

docs/examples/rust/secure_message_server.rs

@@ -12,24 +12,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#[macro_use]
-extern crate clap;
-extern crate env_logger;
 #[macro_use]
 extern crate log;
 
 use std::collections::HashSet;
 use std::io;
 use std::net::{SocketAddr, UdpSocket};
 
+use clap::clap_app;
+
 fn main() {
     env_logger::init();
 
     let matches = clap_app!(secure_message_server =>
         (version: env!("CARGO_PKG_VERSION"))
         (about: "Relay server for Secure Message chat client.")
         (@arg port: -p --port [number] "Listening port (default: 7573)")
-    ).get_matches();
+    )
+    .get_matches();
 
     let port = matches.value_of("port").unwrap_or("7573").parse().unwrap();
     let listen_addr = SocketAddr::new([0; 16].into(), port);

src/wrappers/themis/rust/CHANGELOG.md

@@ -3,6 +3,25 @@
 
 The version currently under development.
 
+Version 0.0.3 — 2019-01-17
+==========================
+
+Documentation and internal improvements.
+
+Themis now requires **Rust 2018** (rustc 1.31+) to compile.
+
+## New features
+
+- Crate feature `vendored` allows to build and use a vendored copy of the core
+  Themis library in case it is not installed in the system. ([#9])
+
+- All modules, data types and functions now have proper
+  [API documentation][docs.rs], complete with examples and references to
+  underlying cryptographic algorithms.
+
+[#9]: https://github.com/ilammy/rust-themis/pull/9
+[docs.rs]: https://docs.rs/crate/themis/
+
 Version 0.0.2 — 2018-11-18
 ==========================