1 files changed, 82 insertions, 0 deletions

diff --git a/openssl/src/x509/extension.rs b/openssl/src/x509/extension.rs
index 5c276b4a..f173be92 100644
--- a/openssl/src/x509/extension.rs
+++ b/openssl/src/x509/extension.rs
@@ -1,9 +1,32 @@
+//! 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;