added example and updated docs

Author: Goirad

examples/simple-server-pkcs8.rs

@@ -0,0 +1,43 @@
+extern crate native_tls;
+
+use native_tls::{Identity, TlsAcceptor, TlsStream};
+use std::fs::File;
+use std::io::{Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::sync::Arc;
+use std::thread;
+
+fn main() {
+    let mut cert_file = File::open("test/cert.pem").unwrap();
+    let mut certs = vec![];
+    cert_file.read_to_end(&mut certs).unwrap();
+    let mut key_file = File::open("test/key.pem").unwrap();
+    let mut key = vec![];
+    key_file.read_to_end(&mut key).unwrap();
+    let pkcs8 = Identity::from_pkcs8(&certs, &key).unwrap();
+
+    let acceptor = TlsAcceptor::new(pkcs8).unwrap();
+    let acceptor = Arc::new(acceptor);
+
+    let listener = TcpListener::bind("0.0.0.0:8443").unwrap();
+
+    fn handle_client(mut stream: TlsStream<TcpStream>) {
+        let mut buf = [0; 1024];
+        let read = stream.read(&mut buf).unwrap();
+        let received = std::str::from_utf8(&buf[0..read]).unwrap();
+        stream.write_all(format!("received '{}'", received).as_bytes()).unwrap();
+    }
+
+    for stream in listener.incoming() {
+        match stream {
+            Ok(stream) => {
+                let acceptor = acceptor.clone();
+                thread::spawn(move || {
+                    let stream = acceptor.accept(stream).unwrap();
+                    handle_client(stream);
+                });
+            }
+            Err(_e) => { /* connection failed */ }
+        }
+    }
+}

src/lib.rs

@@ -27,6 +27,7 @@
 //! * TLS/SSL client communication
 //! * TLS/SSL server communication
 //! * PKCS#12 encoded identities
+//! * PKCS#8  encoded identities
 //! * Secure-by-default for client and server
 //!     * Includes hostname verification for clients
 //! * Supports asynchronous I/O for both the server and the client
@@ -186,10 +187,15 @@ impl Identity {
         Ok(Identity(identity))
     }
 
-    /// buf is the contents of a file containing a chain of PEM encoded certificates
-    /// key is the contents of a file containing a PEM encoded private key
-    pub fn from_pkcs8(buf: &[u8], key: &[u8]) -> Result<Identity> {
-        let identity = imp::Identity::from_pkcs8(buf, key)?;
+    /// Parses a chain of PEM encoded X509 certificates, with the leaf certificate first.
+    /// `key` is a PEM encoded PKCS #8 formatted private key for the leaf certificate.
+    ///
+    /// The certificate chain should contain any intermediate cerficates that should be sent to
+    /// clients to allow them to build a chain to a trusted root.
+    ///
+    /// A certificate chain here means a series of PEM encoded certificates concatenated together.
+    pub fn from_pkcs8(pem: &[u8], key: &[u8]) -> Result<Identity> {
+        let identity = imp::Identity::from_pkcs8(pem, key)?;
         Ok(Identity(identity))
     }
 }