Merge pull request #811 from apeduru/x509-docs (753a7d07) · Commits · Public Repositories / Rust Openssl

openssl/src/verify.rs

+18 −0

Original line number	Diff line number	Diff line
		@@ -7,6 +7,7 @@ use cvt;
		use error::ErrorStack;

		bitflags! {
		/// Flags used to check an `X509` certificate.
		pub struct X509CheckFlags: c_uint {
		const ALWAYS_CHECK_SUBJECT = ffi::X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT;
		const FLAG_NO_WILDCARDS = ffi::X509_CHECK_FLAG_NO_WILDCARDS;
		@@ -24,17 +25,29 @@ foreign_type_and_impl_send_sync! {
		type CType = ffi::X509_VERIFY_PARAM;
		fn drop = ffi::X509_VERIFY_PARAM_free;

		/// Adjust parameters associated with certificate verification.
		pub struct X509VerifyParam;
		/// Reference to `X509VerifyParam`.
		pub struct X509VerifyParamRef;
		}

		impl X509VerifyParamRef {
		/// Set the host flags.
		///
		/// This corresponds to [`X509_VERIFY_PARAM_set_hostflags`].
		///
		/// [`X509_VERIFY_PARAM_set_hostflags`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_VERIFY_PARAM_set_hostflags.html
		pub fn set_hostflags(&mut self, hostflags: X509CheckFlags) {
		unsafe {
		ffi::X509_VERIFY_PARAM_set_hostflags(self.as_ptr(), hostflags.bits);
		}
		}

		/// Set the expected DNS hostname.
		///
		/// This corresponds to [`X509_VERIFY_PARAM_set1_host`].
		///
		/// [`X509_VERIFY_PARAM_set1_host`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_VERIFY_PARAM_set1_host.html
		pub fn set_host(&mut self, host: &str) -> Result<(), ErrorStack> {
		unsafe {
		cvt(ffi::X509_VERIFY_PARAM_set1_host(
		@@ -45,6 +58,11 @@ impl X509VerifyParamRef {
		}
		}

		/// Set the expected IPv4 or IPv6 address.
		///
		/// This corresponds to [`X509_VERIFY_PARAM_set1_ip`].
		///
		/// [`X509_VERIFY_PARAM_set1_ip`]: https://www.openssl.org/docs/man1.1.0/crypto/X509_VERIFY_PARAM_set1_ip.html
		pub fn set_ip(&mut self, ip: IpAddr) -> Result<(), ErrorStack> {
		unsafe {
		let mut buf = [0; 16];

openssl/src/x509/extension.rs

+82 −0

Original line number	Diff line number	Diff line
		//! Add extensions to an `X509` certificate or certificate request.
		//!
		//! The extensions defined for X.509 v3 certificates provide methods for
		//! associating additional attributes with users or public keys and for
		//! managing relationships between CAs. The extensions created using this
		//! module can be used with `X509v3Context` objects.
		//!
		//! # Example
		//!
		//! ```rust
		//! extern crate openssl;
		//!
		//! use openssl::x509::extension::BasicConstraints;
		//! use openssl::x509::X509Extension;
		//!
		//! fn main() {
		//! let mut bc = BasicConstraints::new();
		//! let bc = bc.critical().ca().pathlen(1);
		//!
		//! let extension: X509Extension = bc.build().unwrap();
		//! }
		//! ```
		use std::fmt::Write;

		use error::ErrorStack;
		use nid::Nid;
		use x509::{X509Extension, X509v3Context};

		/// An extension which indicates whether a certificate is a CA certificate.
		pub struct BasicConstraints {
		critical: bool,
		ca: bool,
		@@ -11,6 +34,7 @@ pub struct BasicConstraints {
		}

		impl BasicConstraints {
		/// Construct a new `BasicConstraints` extension.
		pub fn new() -> BasicConstraints {
		BasicConstraints {
		critical: false,
		@@ -19,21 +43,26 @@ impl BasicConstraints {
		}
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut BasicConstraints {
		self.critical = true;
		self
		}

		/// Sets the `ca` flag to `true`.
		pub fn ca(&mut self) -> &mut BasicConstraints {
		self.ca = true;
		self
		}

		/// Sets the pathlen to an optional non-negative value. The pathlen is the
		/// maximum number of CAs that can appear below this one in a chain.
		pub fn pathlen(&mut self, pathlen: u32) -> &mut BasicConstraints {
		self.pathlen = Some(pathlen);
		self
		}

		/// Return the `BasicConstraints` extension as an `X509Extension`.
		pub fn build(&self) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		if self.critical {
		@@ -52,6 +81,7 @@ impl BasicConstraints {
		}
		}

		/// An extension consisting of a list of names of the permitted key usages.
		pub struct KeyUsage {
		critical: bool,
		digital_signature: bool,
		@@ -66,6 +96,7 @@ pub struct KeyUsage {
		}

		impl KeyUsage {
		/// Construct a new `KeyUsage` extension.
		pub fn new() -> KeyUsage {
		KeyUsage {
		critical: false,
		@@ -81,56 +112,67 @@ impl KeyUsage {
		}
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut KeyUsage {
		self.critical = true;
		self
		}

		/// Sets the `digitalSignature` flag to `true`.
		pub fn digital_signature(&mut self) -> &mut KeyUsage {
		self.digital_signature = true;
		self
		}

		/// Sets the `nonRepudiation` flag to `true`.
		pub fn non_repudiation(&mut self) -> &mut KeyUsage {
		self.non_repudiation = true;
		self
		}

		/// Sets the `keyEncipherment` flag to `true`.
		pub fn key_encipherment(&mut self) -> &mut KeyUsage {
		self.key_encipherment = true;
		self
		}

		/// Sets the `dataEncipherment` flag to `true`.
		pub fn data_encipherment(&mut self) -> &mut KeyUsage {
		self.data_encipherment = true;
		self
		}

		/// Sets the `keyAgreement` flag to `true`.
		pub fn key_agreement(&mut self) -> &mut KeyUsage {
		self.key_agreement = true;
		self
		}

		/// Sets the `keyCertSign` flag to `true`.
		pub fn key_cert_sign(&mut self) -> &mut KeyUsage {
		self.key_cert_sign = true;
		self
		}

		/// Sets the `cRLSign` flag to `true`.
		pub fn crl_sign(&mut self) -> &mut KeyUsage {
		self.crl_sign = true;
		self
		}

		/// Sets the `encipherOnly` flag to `true`.
		pub fn encipher_only(&mut self) -> &mut KeyUsage {
		self.encipher_only = true;
		self
		}

		/// Sets the `decipherOnly` flag to `true`.
		pub fn decipher_only(&mut self) -> &mut KeyUsage {
		self.decipher_only = true;
		self
		}

		/// Return the `KeyUsage` extension as an `X509Extension`.
		pub fn build(&self) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		let mut first = true;
		@@ -168,6 +210,8 @@ impl KeyUsage {
		}
		}

		/// An extension consisting of a list of usages indicating purposes
		/// for which the certificate public key can be used for.
		pub struct ExtendedKeyUsage {
		critical: bool,
		server_auth: bool,
		@@ -185,6 +229,7 @@ pub struct ExtendedKeyUsage {
		}

		impl ExtendedKeyUsage {
		/// Construct a new `ExtendedKeyUsage` extension.
		pub fn new() -> ExtendedKeyUsage {
		ExtendedKeyUsage {
		critical: false,
		@@ -203,66 +248,79 @@ impl ExtendedKeyUsage {
		}
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut ExtendedKeyUsage {
		self.critical = true;
		self
		}

		/// Sets the `serverAuth` flag to `true`.
		pub fn server_auth(&mut self) -> &mut ExtendedKeyUsage {
		self.server_auth = true;
		self
		}

		/// Sets the `clientAuth` flag to `true`.
		pub fn client_auth(&mut self) -> &mut ExtendedKeyUsage {
		self.client_auth = true;
		self
		}

		/// Sets the `codeSigning` flag to `true`.
		pub fn code_signing(&mut self) -> &mut ExtendedKeyUsage {
		self.code_signing = true;
		self
		}

		/// Sets the `timeStamping` flag to `true`.
		pub fn time_stamping(&mut self) -> &mut ExtendedKeyUsage {
		self.time_stamping = true;
		self
		}

		/// Sets the `msCodeInd` flag to `true`.
		pub fn ms_code_ind(&mut self) -> &mut ExtendedKeyUsage {
		self.ms_code_ind = true;
		self
		}

		/// Sets the `msCodeCom` flag to `true`.
		pub fn ms_code_com(&mut self) -> &mut ExtendedKeyUsage {
		self.ms_code_com = true;
		self
		}

		/// Sets the `msCTLSign` flag to `true`.
		pub fn ms_ctl_sign(&mut self) -> &mut ExtendedKeyUsage {
		self.ms_ctl_sign = true;
		self
		}

		/// Sets the `msSGC` flag to `true`.
		pub fn ms_sgc(&mut self) -> &mut ExtendedKeyUsage {
		self.ms_sgc = true;
		self
		}

		/// Sets the `msEFS` flag to `true`.
		pub fn ms_efs(&mut self) -> &mut ExtendedKeyUsage {
		self.ms_efs = true;
		self
		}

		/// Sets the `nsSGC` flag to `true`.
		pub fn ns_sgc(&mut self) -> &mut ExtendedKeyUsage {
		self.ns_sgc = true;
		self
		}

		/// Sets a flag not already defined.
		pub fn other(&mut self, other: &str) -> &mut ExtendedKeyUsage {
		self.other.push(other.to_owned());
		self
		}

		/// Return the `ExtendedKeyUsage` extension as an `X509Extension`.
		pub fn build(&self) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		let mut first = true;
		@@ -290,20 +348,25 @@ impl ExtendedKeyUsage {
		}
		}

		/// An extension that provides a means of identifying certificates that contain a
		/// particular public key.
		pub struct SubjectKeyIdentifier {
		critical: bool,
		}

		impl SubjectKeyIdentifier {
		/// Construct a new `SubjectKeyIdentifier` extension.
		pub fn new() -> SubjectKeyIdentifier {
		SubjectKeyIdentifier { critical: false }
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut SubjectKeyIdentifier {
		self.critical = true;
		self
		}

		/// Return a `SubjectKeyIdentifier` extension as an `X509Extension`.
		pub fn build(&self, ctx: &X509v3Context) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		let mut first = true;
		@@ -313,6 +376,8 @@ impl SubjectKeyIdentifier {
		}
		}

		/// An extension that provides a means of identifying the public key corresponding
		/// to the private key used to sign a CRL.
		pub struct AuthorityKeyIdentifier {
		critical: bool,
		keyid: Option<bool>,
		@@ -320,6 +385,7 @@ pub struct AuthorityKeyIdentifier {
		}

		impl AuthorityKeyIdentifier {
		/// Construct a new `AuthorityKeyIdentifier` extension.
		pub fn new() -> AuthorityKeyIdentifier {
		AuthorityKeyIdentifier {
		critical: false,
		@@ -328,21 +394,25 @@ impl AuthorityKeyIdentifier {
		}
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut AuthorityKeyIdentifier {
		self.critical = true;
		self
		}

		/// Sets the `keyid` flag.
		pub fn keyid(&mut self, always: bool) -> &mut AuthorityKeyIdentifier {
		self.keyid = Some(always);
		self
		}

		/// Sets the `issuer` flag.
		pub fn issuer(&mut self, always: bool) -> &mut AuthorityKeyIdentifier {
		self.issuer = Some(always);
		self
		}

		/// Return a `AuthorityKeyIdentifier` extension as an `X509Extension`.
		pub fn build(&self, ctx: &X509v3Context) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		let mut first = true;
		@@ -361,12 +431,15 @@ impl AuthorityKeyIdentifier {
		}
		}

		/// An extension that allows additional identities to be bound to the subject
		/// of the certificate.
		pub struct SubjectAlternativeName {
		critical: bool,
		names: Vec<String>,
		}

		impl SubjectAlternativeName {
		/// Construct a new `SubjectAlternativeName` extension.
		pub fn new() -> SubjectAlternativeName {
		SubjectAlternativeName {
		critical: false,
		@@ -374,46 +447,55 @@ impl SubjectAlternativeName {
		}
		}

		/// Sets the `critical` flag to `true`. The extension will be critical.
		pub fn critical(&mut self) -> &mut SubjectAlternativeName {
		self.critical = true;
		self
		}

		/// Sets the `email` flag.
		pub fn email(&mut self, email: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("email:{}", email));
		self
		}

		/// Sets the `uri` flag.
		pub fn uri(&mut self, uri: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("URI:{}", uri));
		self
		}

		/// Sets the `dns` flag.
		pub fn dns(&mut self, dns: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("DNS:{}", dns));
		self
		}

		/// Sets the `rid` flag.
		pub fn rid(&mut self, rid: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("RID:{}", rid));
		self
		}

		/// Sets the `ip` flag.
		pub fn ip(&mut self, ip: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("IP:{}", ip));
		self
		}

		/// Sets the `dirName` flag.
		pub fn dir_name(&mut self, dir_name: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("dirName:{}", dir_name));
		self
		}

		/// Sets the `otherName` flag.
		pub fn other_name(&mut self, other_name: &str) -> &mut SubjectAlternativeName {
		self.names.push(format!("otherName:{}", other_name));
		self
		}

		/// Return a `SubjectAlternativeName` extension as an `X509Extension`.
		pub fn build(&self, ctx: &X509v3Context) -> Result<X509Extension, ErrorStack> {
		let mut value = String::new();
		let mut first = true;

openssl/src/x509/mod.rs

+166 −3

File changed.

Preview size limit exceeded, changes collapsed.

openssl/src/x509/store.rs

+46 −0

Original line number	Diff line number	Diff line
		//! Describe a context in which to verify an `X509` certificate.
		//!
		//! The `X509` certificate store holds trusted CA certificates used to verify
		//! peer certificates.
		//!
		//! # Example
		//!
		//! ```rust
		//!
		//! extern crate openssl;
		//!
		//! use openssl::x509::store::{X509StoreBuilder, X509Store};
		//! use openssl::x509::{X509, X509Name};
		//! use openssl::pkey::PKey;
		//! use openssl::hash::MessageDigest;
		//! use openssl::rsa::Rsa;
		//! use openssl::nid::Nid;
		//!
		//! fn main() {
		//! let rsa = Rsa::generate(2048).unwrap();
		//! let pkey = PKey::from_rsa(rsa).unwrap();
		//!
		//! let mut name = X509Name::builder().unwrap();
		//! name.append_entry_by_nid(Nid::COMMONNAME, "foobar.com").unwrap();
		//! let name = name.build();
		//!
		//! let mut builder = X509::builder().unwrap();
		//! builder.set_version(2).unwrap();
		//! builder.set_subject_name(&name).unwrap();
		//! builder.set_issuer_name(&name).unwrap();
		//! 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;
		use foreign_types::ForeignTypeRef;
		use std::mem;
		@@ -10,7 +52,9 @@ foreign_type! {
		type CType = ffi::X509_STORE;
		fn drop = ffi::X509_STORE_free;

		/// A builder type used to construct an `X509Store`.
		pub struct X509StoreBuilder;
		/// Reference to an `X509StoreBuilder`.
		pub struct X509StoreBuilderRef;
		}

		@@ -58,6 +102,8 @@ foreign_type! {
		type CType = ffi::X509_STORE;
		fn drop = ffi::X509_STORE_free;

		/// A certificate store to hold trusted `X509` certificates.
		pub struct X509Store;
		/// Reference to an `X509Store`.
		pub struct X509StoreRef;
		}