Add PQ example

Cargo.toml

@@ -1,13 +1,13 @@
 [package]
 name = "wolfssl-sys"
-version = "0.1.6"
+version = "0.1.7"
 edition = "2021"
 authors = ["pete.m@expressvpn.com"]
 license = "GPL-2.0"
 readme = "README.md"
 description = "System bindings for WolfSSL"
 repository = "https://github.com/expressvpn/wolfssl-sys"
-keywords = ["wolfssl", "vpn", "expressvpn", "lightway", "post-quantum", "cryptography"]
+keywords = ["wolfssl", "vpn", "lightway", "post-quantum", "cryptography"]
 links = "wolfssl"
 
 [build-dependencies]
@@ -24,6 +24,9 @@ postquantum = ["dep:oqs-sys"]
 
 
 [package.metadata.cargo-all-features]
-
 # Not an actual feature
 denylist = ["oqs-sys"]
+
+[[example]]
+name = "connect_pq"
+required-features = ["postquantum"]

README.md

@@ -14,9 +14,11 @@ Add `wolfssl-sys` to your Cargo manifest:
 
 ```
 [dependencies]
-wolfssl-sys = "0.1.6"
+wolfssl-sys = "0.1.7"
 ```
-To ensure that the crate can be built even offline, the crate includes the source code for WolfSSL (currently version `5.4.0`). WolfSSL uses autotools to build and configure the library so this will need to be install on the build system.
+To ensure that the crate can be built even offline, the crate includes the source code for WolfSSL (currently version `5.4.0`). WolfSSL uses autotools to build and configure the library so this will need to be installed on the build system.
+
+Note: This crate includes a patch from the WolfSSL master branch to improve reporting with Post Quantum curves. It has no other effect and as it is already merged into master, will be removed when WolfSSL cuts a new release.
 
 ## Building with Earthly
 There is also an `Earthfile` provided so that you can build the crate in [Earthly](https://earthly.dev):
@@ -30,11 +32,30 @@ WolfSSL offers Post Quantum support by leveraging `liboqs`, a library from the [
 
 ``` toml
 [dependencies]
-wolfssl-sys = { version = "0.1.6" features = ["postquantum"] }
+wolfssl-sys = { version = "0.1.7" features = ["postquantum"] }
 ```
 
 This will automatically build `liboqs` from the `oqs-sys` crate and link WolfSSL against it, making definitions such as `WOLFSSL_P521_KYBER_LEVEL5` available.
 
+### Testing it
+The crate includes an example called `connect_pq`. It is a *very* basic application that connects to the test site of the Open Quantum Safe project and tries to use the hybrid P521 and Kyber Level 5 key exchange mechanism. You can run this example with:
+
+``` shell
+cargo run --example connect_pq --features=postquantum
+```
+
+All being well you should get output like this:
+
+``` text
+Connected to  test.openquantumsafe.org
+Key Exchange: "P521_KYBER_LEVEL5"
+Cipher:       "TLS13-AES128-GCM-SHA256"
+```
+
+The example shows how easy it is to use WolfSSL's Post Quantum support, but it is certainly not production ready!
+
+
+
 ## Contributors
 A number of people have taken the time to contribute towards this crate. From opening valuable issues, to contributing a line or two of code, we would like to give credit for their help here:
 

build.rs

@@ -10,7 +10,7 @@ use std::env;
 use std::path::PathBuf;
 use std::process::Command;
 
-static WOLFSSL_VERSION: &str = "wolfssl-5.4.0-stable";
+static WOLFSSL_VERSION: &str = "wolfssl-5.4.0p1-stable";
 
 /**
  * Work around for bindgen creating duplicate values.
@@ -73,9 +73,12 @@ fn build_wolfssl(dest: &str) -> PathBuf {
         // Disable DH key exchanges
         .disable("dh", None)
         // Enable elliptic curve exchanges
+        .enable("supportedcurves", None)
         .enable("curve25519", None)
         // Enable Secure Renegotiation
         .enable("secure-renegotiation", None)
+        // Enable SNI
+        .enable("sni", None)
         // CFLAGS
         .cflag("-g")
         .cflag("-fPIC")

examples/connect_pq.rs

@@ -0,0 +1,99 @@
+/// This is an example application that attempts to connect to the OQS test site
+/// using the hybrid P521 and Kyber Level 5 key exchange. The test site port that
+/// we use only offers this specific combination, making it an effective test.
+///
+/// Note: This tool is built with unsafe primitives with limited error handling or
+///       checking. This is to demonstrate how easy it is to use WolfSSL to gain PQ
+///       protection, even if you roll it entirely by hand. Generally you would use
+///       a higher level API (which hasn't been written yet) to gain access to these
+///       features. In the meantime, you can see it here, but do not base any real
+///       world system on this raw code!
+///
+use wolfssl_sys as ffi;
+
+use std::net::TcpStream;
+use std::os::unix::io::AsRawFd;
+
+use std::ffi::CStr;
+use std::ffi::CString;
+
+fn main() {
+    // The website we're going to test against
+    let site = "test.openquantumsafe.org";
+    let site_len = site.len() as u16;
+    // There admittedly has to be something better than this...
+    let sitec = CString::new(site)
+        .expect("Couldn't convert URL to a c string")
+        .as_c_str()
+        .as_ptr() as *mut ::std::os::raw::c_void;
+    // The port that runs P521 Kyber Level 5 hybrid
+    let port = 6051;
+
+    // Compile in the OQS CA at build time
+    let pq_osa_ca = include_bytes!("test_certs/pq-osa-ca.crt");
+    // Cast to what the ffi functions are looking for
+    let pq_osa_ca_size = pq_osa_ca.len() as i64;
+    let pq_osa_ca = pq_osa_ca as *const u8;
+
+    // We'll do everything else in an unsafe block as it's clearer than wrapping each function
+    // in its own block.
+    unsafe {
+        // Init WolfSSL
+        ffi::wolfSSL_Init();
+
+        // Set up client method
+        let method = ffi::wolfTLSv1_3_client_method();
+
+        // Create context
+        let context = ffi::wolfSSL_CTX_new(method);
+
+        // Load in the CA
+        ffi::wolfSSL_CTX_load_verify_buffer(
+            context,
+            pq_osa_ca,
+            pq_osa_ca_size,
+            ffi::WOLFSSL_FILETYPE_PEM,
+        );
+
+        // Enable SNI
+        ffi::wolfSSL_CTX_UseSNI(context, ffi::WOLFSSL_SNI_HOST_NAME as u8, sitec, site_len);
+
+        // Create new SSL stream
+        let ssl = ffi::wolfSSL_new(context);
+
+        // Enable Kyber
+        let res = ffi::wolfSSL_UseKeyShare(ssl, ffi::WOLFSSL_P521_KYBER_LEVEL5 as u16);
+
+        // Check that Kyber was enabled
+        assert_eq!(res, ffi::WOLFSSL_SUCCESS);
+
+        // Try to open a TCP stream to OQS test site - 6007
+        let stream = TcpStream::connect(format!("{}:{}", site, port))
+            .expect("Couldn't connect to test site");
+
+        // Tell WolfSSL what the file descriptor is for the stream
+        ffi::wolfSSL_set_fd(ssl, stream.as_raw_fd());
+
+        // Try to connect
+        let res = ffi::wolfSSL_connect(ssl);
+
+        // Exit out here if we didn't complete the handshake
+        if res != ffi::WOLFSSL_SUCCESS {
+            println!(
+                "Connection failed with error: {}",
+                ffi::wolfSSL_get_error(ssl, res)
+            );
+            std::process::exit(-1);
+        }
+
+        println!("Connected to {}", site);
+        println!(
+            "Key Exchange: {:?}",
+            CStr::from_ptr(ffi::wolfSSL_get_curve_name(ssl))
+        );
+        println!(
+            "Cipher: {:?}",
+            CStr::from_ptr(ffi::wolfSSL_get_cipher_name(ssl))
+        );
+    }
+}

examples/test_certs/pq-osa-ca.crt

@@ -0,0 +1,29 @@
+-----BEGIN CERTIFICATE-----
+MIIFCzCCAvOgAwIBAgIUavME2jj8LFyR4tz95Uc8eKKrYmswDQYJKoZIhvcNAQEL
+BQAwFTETMBEGA1UEAwwKb3FzdGVzdF9DQTAeFw0yMjA3MzEwOTQ5NThaFw0yMzEy
+MTMwOTQ5NThaMBUxEzARBgNVBAMMCm9xc3Rlc3RfQ0EwggIiMA0GCSqGSIb3DQEB
+AQUAA4ICDwAwggIKAoICAQDuURsbjnFzcUIISF/8zse/DgLAaHf6hdxlqZvTwZKV
++4pu1IAsKNgzLXYLqbtaKP96IdRscBLcWitp4o+SEYyFsrrTF4N35HtALbkQpDKO
+nIVj7Mlt+dvKRLgT5Ll6VQSzmsgqhENabwb1XSpmMlV29VAilseNXOe8uhNjnEPW
+ZJ5AFESJZx3ltIA1pqUrt/uIQhvlswRdKssyk/AoZjuA+Ybz628PeV4u3q4lc3sZ
+xDRb1HY5kotd/nlwI1JQqGpJvsUjKAFLgF5QiCIxix5JXNHgf2h/0thhqkjLq3BF
+wpKIJZW2WwW0F3TS1ourmT619+XrDs+3q0d3WtXY1iwNf6PYqbxpNfqKgzw7oULA
+MduAlfTeCDpem13JkdJpl/1cQt+1nrLyiOwEGCpmdo0jBwcUr355Oqe9HQY24VOj
+rOLmMZIIBiA759hXyK7HBn7+TtqNVRRgZoO+4a4WRqLHJ3qQHAfjQmL6mVhGCUC0
+e7gqtp92wOVn3J6SXlIbclvyfQJKoTJLEz83IXjUKgV1BqYZ/UdjoA+aZmDSRSMc
+CvmyzyA3takr2hkhJf70duPlzcxgIhchoZKtiGb7xpGvwQN8xpkbKxeXQaAPUVyg
+RGRoG0pCtpzWAYkt9hHIMKiYUHvi0aNMDptKKNLGCqnaCcwqb1LyVZyxZ+EoLj8K
+FwIDAQABo1MwUTAdBgNVHQ4EFgQUN1SCM+6DvXQ0K9rpAV9SJbqzY7QwHwYDVR0j
+BBgwFoAUN1SCM+6DvXQ0K9rpAV9SJbqzY7QwDwYDVR0TAQH/BAUwAwEB/zANBgkq
+hkiG9w0BAQsFAAOCAgEABponyfODLkcG5WHP9PrRNn0OmPl7DI6UBhS/N6SxvwN6
+Fe/TPu1qYYFZOvPx57CJZOZvroOQ024CTtj/EO8B+JFFT6EHjYvC0FH9Z+Hyo5MP
+fd2GAIRJhh+Jo+PMTIxg6ToZhPbNto4OLyY6qcmJyz+WwJ01VwSGIrZef9nb5a3+
+wNlOHOnbfZh0IkIss6n3bGq9s+fx42+jdrMPxaBY0L1xtuMDodjcLlzlmOySmfBV
+KbdppbYsnv3kAe2cqpL37UraIo/jER5BQbAmkh8qKZ66X9JnQaiPFqcAbEb1tqDL
+XSlkWJiTV6E9k3FaULiE93WvFB/JLwkiAZhLzU3JyTJkfD0tMVF8NL1q2g2/RtGg
+BWjxfY3YYk9Pcm09jbVxVuvSI/PqjAs9Tw1P6gJYq2ZbCC0ssSLAHLMCp80sPtEh
+et0+SB7wS14hK138NAupTT9lZMmUHxeVbbMQ3c/3VvA0CU3/nnkLCUBe8F3MtbIH
+dLv4uL7FWFPFf3cTesTBam1LhkiuUKIvV9w3nOfaYD4lvtI3zxTGu9zYQQXdp964
+xdY/Jvfz7n/8ZF3e5mtm7K8mp4NAPJZWFv9jS8Qu7iEfG61zBavn2Rc4W4jd9gRr
+GAPCdl05udTDQBNqRjVvhPH2djCIEmyb9o2c7Vf89/hiEhCuUHshJEGCBv+Pkj0=
+-----END CERTIFICATE-----