Fix doc comments

.github/workflows/ci.yml

@@ -28,6 +28,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
       - name: Install Rust
         run: rustup update stable && rustup default stable
       - name: Get rust version
@@ -55,82 +57,4 @@ jobs:
           path: target
           key: clippy-target-${{ runner.os }}-${{ steps.rust-version.outputs.version }}-${{ hashFiles('Cargo.lock') }}
       - name: Run clippy
-        run: cargo clippy --all --all-targets
+        run: cargo clippy --all --all-targets
-
-  min-version:
-    name: min-version
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Install Rust
-        run: rustup update 1.31.0 && rustup default 1.31.0
-      - name: Get rust version
-        id: rust-version
-        run: echo "::set-output name=version::$(rustc --version)"
-      - name: Cache cargo index
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/registry/index
-          key: index-${{ runner.os }}-${{ github.run_number }}
-          restore-keys: |
-            index-${{ runner.os }}-
-      - name: Create lockfile
-        run: cargo generate-lockfile
-      - name: Cache cargo registry
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/registry/cache
-          key: registry-${{ runner.os }}-${{ steps.rust-version.outputs.version }}-${{ hashFiles('Cargo.lock') }}
-      - name: Fetch dependencies
-        run: cargo fetch
-      - name: Cache target directory
-        uses: actions/cache@v1
-        with:
-          path: target
-          key: min-version-target-${{ runner.os }}-${{ steps.rust-version.outputs.version }}-${{ hashFiles('Cargo.lock') }}
-      - name: Check openssl
-        run: cargo check -p openssl
-
-  windows-vcpkg:
-    name: windows-vcpkg
-    runs-on: windows-latest
-    env:
-      VCPKGRS_DYNAMIC: 1
-    steps:
-      - uses: actions/checkout@v2
-      - name: Install Rust
-        run: rustup update stable && rustup default stable
-      - name: Get rust version
-        id: rust-version
-        run: echo "::set-output name=version::$(rustc --version)"
-      - name: Set vcpkg root
-        run: echo "::set-env name=VCPKG_ROOT::$Env:VCPKG_INSTALLATION_ROOT"
-      - name: Install OpenSSL
-        run: vcpkg install openssl:x64-windows
-      - name: Cache cargo index
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/registry/index
-          key: index-${{ runner.os }}-${{ github.run_number }}
-          restore-keys: |
-            index-${{ runner.os }}-
-      - name: Create lockfile
-        run: cargo generate-lockfile
-      - name: Cache cargo registry
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/registry/cache
-          key: registry-${{ runner.os }}-${{ steps.rust-version.outputs.version }}-${{ hashFiles('Cargo.lock') }}
-      - name: Fetch dependencies
-        run: cargo fetch
-      - name: Cache target directory
-        uses: actions/cache@v1
-        with:
-          path: target
-          key: min-version-target-${{ runner.os }}-${{ steps.rust-version.outputs.version }}-${{ hashFiles('Cargo.lock') }}
-      - name: Run systest
-        run: cargo run -p systest
-      - name: Test openssl
-        run: cargo test -p openssl
-      - name: Test openssl-errors
-        run: cargo test -p openssl-errors

boring/examples/mk_certs.rs

@@ -1,19 +1,19 @@
 //! A program that generates ca certs, certs verified by the ca, and public
 //! and private keys.
 
-extern crate openssl;
+extern crate boring;
 
-use openssl::asn1::Asn1Time;
+use boring::asn1::Asn1Time;
-use openssl::bn::{BigNum, MsbOption};
+use boring::bn::{BigNum, MsbOption};
-use openssl::error::ErrorStack;
+use boring::error::ErrorStack;
-use openssl::hash::MessageDigest;
+use boring::hash::MessageDigest;
-use openssl::pkey::{PKey, PKeyRef, Private};
+use boring::pkey::{PKey, PKeyRef, Private};
-use openssl::rsa::Rsa;
+use boring::rsa::Rsa;
-use openssl::x509::extension::{
+use boring::x509::extension::{
     AuthorityKeyIdentifier, BasicConstraints, KeyUsage, SubjectAlternativeName,
     SubjectKeyIdentifier,
 };
-use openssl::x509::{X509NameBuilder, X509Ref, X509Req, X509ReqBuilder, X509VerifyResult, X509};
+use boring::x509::{X509NameBuilder, X509Ref, X509Req, X509ReqBuilder, X509VerifyResult, X509};
 
 /// Make a CA certificate and private key
 fn mk_ca_cert() -> Result<(X509, PKey<Private>), ErrorStack> {

boring/src/aes.rs

@@ -22,7 +22,7 @@
 //!
 //! ## Key wrapping
 //! ```rust
-//! use openssl::aes::{AesKey, unwrap_key, wrap_key};
+//! use boring::aes::{AesKey, unwrap_key, wrap_key};
 //!
 //! let kek = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F";
 //! let key_to_wrap = b"\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xAA\xBB\xCC\xDD\xEE\xFF";

boring/src/asn1.rs

@@ -21,7 +21,7 @@
 //! ## Examples
 //!
 //! ```
-//! use openssl::asn1::Asn1Time;
+//! use boring::asn1::Asn1Time;
 //! let tomorrow = Asn1Time::days_from_now(1);
 //! ```
 use ffi;

boring/src/bn.rs

@@ -9,8 +9,8 @@
 //! # Examples
 //!
 //! ```
-//! use openssl::bn::BigNum;
+//! use boring::bn::BigNum;
-//! use openssl::error::ErrorStack;
+//! use boring::error::ErrorStack;
 //!
 //! fn main() -> Result<(), ErrorStack> {
 //!   let a = BigNum::new()?; // a = 0
@@ -103,8 +103,8 @@ foreign_type_and_impl_send_sync! {
     ///
     /// # Examples
     /// ```
-    /// use openssl::bn::BigNum;
+    /// use boring::bn::BigNum;
-    /// # use openssl::error::ErrorStack;
+    /// # use boring::error::ErrorStack;
     /// # fn bignums() -> Result< (), ErrorStack > {
     /// let little_big = BigNum::from_u32(std::u32::MAX)?;
     /// assert_eq!(*&little_big.num_bytes(), 4);
@@ -339,7 +339,7 @@ impl BigNumRef {
     /// # Examples
     ///
     /// ```
-    /// # use openssl::bn::BigNum;
+    /// # use boring::bn::BigNum;
     /// # use std::cmp::Ordering;
     /// let s = -BigNum::from_u32(8).unwrap();
     /// let o = BigNum::from_u32(8).unwrap();
@@ -380,8 +380,8 @@ impl BigNumRef {
     /// # Examples
     ///
     /// ```
-    /// use openssl::bn::{BigNum, MsbOption};
+    /// use boring::bn::{BigNum, MsbOption};
-    /// use openssl::error::ErrorStack;
+    /// use boring::error::ErrorStack;
     ///
     /// fn generate_random() -> Result< BigNum, ErrorStack > {
     ///    let mut big = BigNum::new()?;
@@ -439,8 +439,8 @@ impl BigNumRef {
     /// # Examples
     ///
     /// ```
-    /// use openssl::bn::BigNum;
+    /// use boring::bn::BigNum;
-    /// use openssl::error::ErrorStack;
+    /// use boring::error::ErrorStack;
     ///
     /// fn generate_weak_prime() -> Result< BigNum, ErrorStack > {
     ///    let mut big = BigNum::new()?;
@@ -843,7 +843,7 @@ impl BigNumRef {
     /// `self` can be recreated by using `from_slice`.
     ///
     /// ```
-    /// # use openssl::bn::BigNum;
+    /// # use boring::bn::BigNum;
     /// let s = -BigNum::from_u32(4543).unwrap();
     /// let r = BigNum::from_u32(4543).unwrap();
     ///
@@ -863,7 +863,7 @@ impl BigNumRef {
     /// Returns a decimal string representation of `self`.
     ///
     /// ```
-    /// # use openssl::bn::BigNum;
+    /// # use boring::bn::BigNum;
     /// let s = -BigNum::from_u32(12345).unwrap();
     ///
     /// assert_eq!(&**s.to_dec_str().unwrap(), "-12345");
@@ -878,7 +878,7 @@ impl BigNumRef {
     /// Returns a hexadecimal string representation of `self`.
     ///
     /// ```
-    /// # use openssl::bn::BigNum;
+    /// # use boring::bn::BigNum;
     /// let s = -BigNum::from_u32(0x99ff).unwrap();
     ///
     /// assert_eq!(&**s.to_hex_str().unwrap(), "-99ff");
@@ -957,7 +957,7 @@ impl BigNum {
     /// [`BN_bin2bn`]: https://www.openssl.org/docs/man1.1.0/crypto/BN_bin2bn.html
     ///
     /// ```
-    /// # use openssl::bn::BigNum;
+    /// # use boring::bn::BigNum;
     /// let bignum = BigNum::from_slice(&[0x12, 0x00, 0x34]).unwrap();
     ///
     /// assert_eq!(bignum, BigNum::from_u32(0x120034).unwrap());

boring/src/dsa.rs

@@ -40,9 +40,9 @@ generic_foreign_type_and_impl_send_sync! {
     /// # Examples
     ///
     /// ```
-    /// use openssl::dsa::Dsa;
+    /// use boring::dsa::Dsa;
-    /// use openssl::error::ErrorStack;
+    /// use boring::error::ErrorStack;
-    /// use openssl::pkey::Private;
+    /// use boring::pkey::Private;
     ///
     /// fn create_dsa() -> Result<Dsa<Private>, ErrorStack> {
     ///     let sign = Dsa::generate(2048)?;

boring/src/ec.rs

@@ -687,10 +687,10 @@ impl EcKey<Public> {
     /// # Example
     ///
     /// ```no_run
-    /// use openssl::bn::BigNumContext;
+    /// use boring::bn::BigNumContext;
-    /// use openssl::ec::*;
+    /// use boring::ec::*;
-    /// use openssl::nid::Nid;
+    /// use boring::nid::Nid;
-    /// use openssl::pkey::PKey;
+    /// use boring::pkey::PKey;
     ///
     /// // get bytes from somewhere, i.e. this will not produce a valid key
     /// let public_key: Vec<u8> = vec![];

boring/src/error.rs

@@ -6,8 +6,8 @@
 //! # Examples
 //!
 //! ```
-//! use openssl::error::ErrorStack;
+//! use boring::error::ErrorStack;
-//! use openssl::bn::BigNum;
+//! use boring::bn::BigNum;
 //!
 //! let an_error = BigNum::from_dec_str("Cannot parse letters");
 //! match an_error {

boring/src/hash.rs

@@ -100,7 +100,7 @@ use self::State::*;
 /// Calculate a hash in one go:
 ///
 /// ```
-/// use openssl::hash::{hash, MessageDigest};
+/// use boring::hash::{hash, MessageDigest};
 ///
 /// let data = b"\x42\xF4\x97\xE0";
 /// let spec = b"\x7c\x43\x0f\x17\x8a\xef\xdf\x14\x87\xfe\xe7\x14\x4e\x96\x41\xe2";
@@ -111,7 +111,7 @@ use self::State::*;
 /// Supply the input in chunks:
 ///
 /// ```
-/// use openssl::hash::{Hasher, MessageDigest};
+/// use boring::hash::{Hasher, MessageDigest};
 ///
 /// let data = [b"\x42\xF4", b"\x97\xE0"];
 /// let spec = b"\x7c\x43\x0f\x17\x8a\xef\xdf\x14\x87\xfe\xe7\x14\x4e\x96\x41\xe2";

boring/src/memcmp.rs

@@ -16,7 +16,7 @@
 //! values:
 //!
 //! ```
-//! use openssl::memcmp::eq;
+//! use boring::memcmp::eq;
 //!
 //! // We want to compare `a` to `b` and `c`, without giving
 //! // away through timing analysis that `c` is more similar to `a`
@@ -48,7 +48,7 @@ use libc::size_t;
 /// values:
 ///
 /// ```
-/// use openssl::memcmp::eq;
+/// use boring::memcmp::eq;
 ///
 /// // We want to compare `a` to `b` and `c`, without giving
 /// // away through timing analysis that `c` is more similar to `a`

boring/src/nid.rs

@@ -33,7 +33,7 @@ pub struct SignatureAlgorithms {
 /// To view the integer representation of a `Nid`:
 ///
 /// ```
-/// use openssl::nid::Nid;
+/// use boring::nid::Nid;
 ///
 /// assert!(Nid::AES_256_GCM.as_raw() == 901);
 /// ```

boring/src/pkey.rs

@@ -29,20 +29,15 @@
 //! Generate a 2048-bit RSA public/private key pair and print the public key.
 //!
 //! ```rust
-//!
+//! use boring::rsa::Rsa;
-//! extern crate openssl;
+//! use boring::pkey::PKey;
-//!
-//! use openssl::rsa::Rsa;
-//! use openssl::pkey::PKey;
 //! use std::str;
 //!
-//! fn main() {
+//! let rsa = Rsa::generate(2048).unwrap();
-//!     let rsa = Rsa::generate(2048).unwrap();
+//! let pkey = PKey::from_rsa(rsa).unwrap();
-//!     let pkey = PKey::from_rsa(rsa).unwrap();
 //!
-//!     let pub_key: Vec<u8> = pkey.public_key_to_pem().unwrap();
+//! let pub_key: Vec<u8> = pkey.public_key_to_pem().unwrap();
-//!     println!("{:?}", str::from_utf8(pub_key.as_slice()).unwrap());
+//! println!("{:?}", str::from_utf8(pub_key.as_slice()).unwrap());
-//! }
 //! ```
 
 use ffi;

boring/src/rand.rs

@@ -5,7 +5,7 @@
 //! To generate a buffer with cryptographically strong bytes:
 //!
 //! ```
-//! use openssl::rand::rand_bytes;
+//! use boring::rand::rand_bytes;
 //!
 //! let mut buf = [0; 256];
 //! rand_bytes(&mut buf).unwrap();
@@ -25,7 +25,7 @@ use error::ErrorStack;
 /// To generate a buffer with cryptographically strong bytes:
 ///
 /// ```
-/// use openssl::rand::rand_bytes;
+/// use boring::rand::rand_bytes;
 ///
 /// let mut buf = [0; 256];
 /// rand_bytes(&mut buf).unwrap();

boring/src/rsa.rs

@@ -16,17 +16,12 @@
 //! Generate a 2048-bit RSA key pair and use the public key to encrypt some data.
 //!
 //! ```rust
+//! use boring::rsa::{Rsa, Padding};
 //!
-//! extern crate openssl;
+//! let rsa = Rsa::generate(2048).unwrap();
-//!
+//! let data = b"foobar";
-//! use openssl::rsa::{Rsa, Padding};
+//! let mut buf = vec![0; rsa.size() as usize];
-//!
+//! let encrypted_len = rsa.public_encrypt(data, &mut buf, Padding::PKCS1).unwrap();
-//! fn main() {
-//!     let rsa = Rsa::generate(2048).unwrap();
-//!     let data = b"foobar";
-//!     let mut buf = vec![0; rsa.size() as usize];
-//!     let encrypted_len = rsa.public_encrypt(data, &mut buf, Padding::PKCS1).unwrap();
-//! }
 //! ```
 use ffi;
 use foreign_types::{ForeignType, ForeignTypeRef};

boring/src/sha.rs

@@ -14,10 +14,9 @@
 //! you can create a hasher that you can repeatedly update to add bytes to.
 //!
 //! ```rust
-//! extern crate openssl;
 //! extern crate hex;
 //!
-//! use openssl::sha;
+//! use boring::sha;
 //!
 //! fn main() {
 //!     let mut hasher = sha::Sha256::new();
@@ -35,10 +34,9 @@
 //! to the algorithm you want to use.
 //!
 //! ```rust
-//! extern crate openssl;
 //! extern crate hex;
 //!
-//! use openssl::sha::sha256;
+//! use boring::sha::sha256;
 //!
 //! fn main() {
 //!     let hash = sha256(b"your data or message");

boring/src/sign.rs

@@ -10,10 +10,10 @@
 //! Sign and verify data given an RSA keypair:
 //!
 //! ```rust
-//! use openssl::sign::{Signer, Verifier};
+//! use boring::sign::{Signer, Verifier};
-//! use openssl::rsa::Rsa;
+//! use boring::rsa::Rsa;
-//! use openssl::pkey::PKey;
+//! use boring::pkey::PKey;
-//! use openssl::hash::MessageDigest;
+//! use boring::hash::MessageDigest;
 //!
 //! // Generate a keypair
 //! let keypair = Rsa::generate(2048).unwrap();

boring/src/ssl/mod.rs

@@ -8,7 +8,7 @@
 //! To connect as a client to a remote server:
 //!
 //! ```no_run
-//! use openssl::ssl::{SslMethod, SslConnector};
+//! use boring::ssl::{SslMethod, SslConnector};
 //! use std::io::{Read, Write};
 //! use std::net::TcpStream;
 //!
@@ -26,7 +26,7 @@
 //! To accept connections as a server from remote clients:
 //!
 //! ```no_run
-//! use openssl::ssl::{SslMethod, SslAcceptor, SslStream, SslFiletype};
+//! use boring::ssl::{SslMethod, SslAcceptor, SslStream, SslFiletype};
 //! use std::net::{TcpListener, TcpStream};
 //! use std::sync::Arc;
 //! use std::thread;

boring/src/symm.rs

@@ -5,7 +5,7 @@
 //! Encrypt data in AES128 CBC mode
 //!
 //! ```
-//! use openssl::symm::{encrypt, Cipher};
+//! use boring::symm::{encrypt, Cipher};
 //!
 //! let cipher = Cipher::aes_128_cbc();
 //! let data = b"Some Crypto Text";
@@ -26,8 +26,8 @@
 //! Encrypting an asymmetric key with a symmetric cipher
 //!
 //! ```
-//! use openssl::rsa::{Padding, Rsa};
+//! use boring::rsa::{Padding, Rsa};
-//! use openssl::symm::Cipher;
+//! use boring::symm::Cipher;
 //!
 //! // Generate keypair and encrypt private key:
 //! let keypair = Rsa::generate(2048).unwrap();
@@ -228,7 +228,7 @@ unsafe impl Send for Cipher {}
 /// CBC mode.
 ///
 /// ```
-/// use openssl::symm::{Cipher, Mode, Crypter};
+/// use boring::symm::{Cipher, Mode, Crypter};
 ///
 /// let plaintexts: [&[u8]; 2] = [b"Some Stream of", b" Crypto Text"];
 /// let key = b"\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F";
@@ -552,7 +552,7 @@ impl Drop for Crypter {
 /// Encrypt data in AES128 CBC mode
 ///
 /// ```
-/// use openssl::symm::{encrypt, Cipher};
+/// use boring::symm::{encrypt, Cipher};
 ///
 /// let cipher = Cipher::aes_128_cbc();
 /// let data = b"Some Crypto Text";
@@ -591,7 +591,7 @@ pub fn encrypt(
 /// Decrypt data in AES128 CBC mode
 ///
 /// ```
-/// use openssl::symm::{decrypt, Cipher};
+/// use boring::symm::{decrypt, Cipher};
 ///
 /// let cipher = Cipher::aes_128_cbc();
 /// let data = b"\xB4\xB9\xE7\x30\xD6\xD6\xF7\xDE\x77\x3F\x1C\xFF\xB3\x3E\x44\x5A\x91\xD7\x27\x62\

boring/src/x509/extension.rs

@@ -8,17 +8,12 @@
 //! # Example
 //!
 //! ```rust
-//! extern crate openssl;
+//! use boring::x509::extension::BasicConstraints;
+//! use boring::x509::X509Extension;
 //!
-//! use openssl::x509::extension::BasicConstraints;
+//! let mut bc = BasicConstraints::new();
-//! use openssl::x509::X509Extension;
+//! let bc = bc.critical().ca().pathlen(1);
-//!
+//! let extension: X509Extension = bc.build().unwrap();
-//! fn main() {
-//!     let mut bc = BasicConstraints::new();
-//!     let bc = bc.critical().ca().pathlen(1);
-//!
-//!     let extension: X509Extension = bc.build().unwrap();
-//! }
 //! ```
 use std::fmt::Write;
 

boring/src/x509/mod.rs

@@ -275,16 +275,16 @@ impl X509Builder {
     /// The `CN` field is used for the common name, such as a DNS name.
     ///
     /// ```
-    /// use openssl::x509::{X509, X509NameBuilder};
+    /// use boring::x509::{X509, X509NameBuilder};
     ///
-    /// let mut x509_name = openssl::x509::X509NameBuilder::new().unwrap();
+    /// let mut x509_name = boring::x509::X509NameBuilder::new().unwrap();
     /// x509_name.append_entry_by_text("C", "US").unwrap();
     /// x509_name.append_entry_by_text("ST", "CA").unwrap();
     /// x509_name.append_entry_by_text("O", "Some organization").unwrap();
     /// x509_name.append_entry_by_text("CN", "www.example.com").unwrap();
     /// let x509_name = x509_name.build();
     ///
-    /// let mut x509 = openssl::x509::X509::builder().unwrap();
+    /// let mut x509 = boring::x509::X509::builder().unwrap();
     /// x509.set_subject_name(&x509_name).unwrap();
     /// ```
     pub fn set_subject_name(&mut self, subject_name: &X509NameRef) -> Result<(), ErrorStack> {

boring/src/x509/store.rs

@@ -6,38 +6,32 @@
 //! # Example
 //!
 //! ```rust
+//! use boring::x509::store::{X509StoreBuilder, X509Store};
+//! use boring::x509::{X509, X509Name};
+//! use boring::pkey::PKey;
+//! use boring::hash::MessageDigest;
+//! use boring::rsa::Rsa;
+//! use boring::nid::Nid;
 //!
-//! extern crate openssl;
+//! let rsa = Rsa::generate(2048).unwrap();
+//! let pkey = PKey::from_rsa(rsa).unwrap();
+//! let mut name = X509Name::builder().unwrap();
 //!
-//! use openssl::x509::store::{X509StoreBuilder, X509Store};
+//! name.append_entry_by_nid(Nid::COMMONNAME, "foobar.com").unwrap();
-//! use openssl::x509::{X509, X509Name};
-//! use openssl::pkey::PKey;
-//! use openssl::hash::MessageDigest;
-//! use openssl::rsa::Rsa;
-//! use openssl::nid::Nid;
 //!
-//! fn main() {
+//! let name = name.build();
-//!     let rsa = Rsa::generate(2048).unwrap();
+//! let mut builder = X509::builder().unwrap();
-//!     let pkey = PKey::from_rsa(rsa).unwrap();
 //!
-//!     let mut name = X509Name::builder().unwrap();
+//! builder.set_version(2).unwrap();
-//!     name.append_entry_by_nid(Nid::COMMONNAME, "foobar.com").unwrap();
+//! builder.set_subject_name(&name).unwrap();
-//!     let name = name.build();
+//! builder.set_issuer_name(&name).unwrap();
+//! builder.set_pubkey(&pkey).unwrap();
+//! builder.sign(&pkey, MessageDigest::sha256()).unwrap();
 //!
-//!     let mut builder = X509::builder().unwrap();
+//! let certificate: X509 = builder.build();
-//!     builder.set_version(2).unwrap();
+//! let mut builder = X509StoreBuilder::new().unwrap();
-//!     builder.set_subject_name(&name).unwrap();
+//! let _ = builder.add_cert(certificate);
-//!     builder.set_issuer_name(&name).unwrap();
+//! let store: X509Store = builder.build();
-//!     builder.set_pubkey(&pkey).unwrap();
-//!     builder.sign(&pkey, MessageDigest::sha256()).unwrap();
-//!
-//!     let certificate: X509 = builder.build();
-//!
-//!     let mut builder = X509StoreBuilder::new().unwrap();
-//!     let _ = builder.add_cert(certificate);
-//!
-//!     let store: X509Store = builder.build();
-//! }
 //! ```
 
 use ffi;