Update the x.509 documentation ... which made a number of flaws very obvious.

src/x509/algident.rs

@@ -2,12 +2,28 @@ use num::BigUint;
 use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1};
 use x509::error::X509ParseError;
 
+/// A supported x509 hash algorithm
 #[derive(Clone,Copy,Debug,PartialEq)]
 pub enum HashAlgorithm { SHA1, SHA224, SHA256, SHA384, SHA512 }
 
+/// A supported x509 asymmetric crypto algorithm
 #[derive(Clone,Copy,Debug,PartialEq)]
 pub enum PublicKeyInfo { RSA, DSA, ECDSA }
 
+/// The algorithm used, either in a certificate or as part of the signing
+/// process. We only actually support a subset of the possible values,
+/// here, although we try to catch them all.
+/// 
+/// Specifically, this library supports:
+/// 
+///   |          | *RSA* | *DSA* | *ECDSA* |
+///   |----------|-------|-------|---------|
+///   | *SHA1*   |   X   |   X   |    X    |
+///   | *SHA224* |   X   |   X   |    X    |
+///   | *SHA256* |   X   |   X   |    X    |
+///   | *SHA384* |   X   |       |    X    |
+///   | *SHA512* |   X   |       |    X    |
+/// 
 #[derive(Clone,Debug,PartialEq)]
 pub struct AlgorithmIdentifier {
     pub hash: HashAlgorithm,

src/x509/atv.rs

@@ -1,11 +1,13 @@
 use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1};
 use std::ops::Index;
 use x509::error::X509ParseError;
-use x509::name::X520Name;
+pub use x509::name::X520Name;
 
+/// All of the various bits of information that are encoded within an x.509
+/// certificate.
 #[derive(Clone,Debug)]
 pub struct InfoBlock {
-    fields: Vec<AttributeTypeValue>
+    pub fields: Vec<AttributeTypeValue>
 }
 
 const EMPTY_STRING: &'static str = "";
@@ -116,11 +118,11 @@ impl ToASN1 for InfoBlock {
     }
 }
 
-
+/// An attribute within an x.509 key and its associated string value.
 #[derive(Clone,Debug,PartialEq)]
-struct AttributeTypeValue {
-    attrtype: X520Name,
-    value:    String
+pub struct AttributeTypeValue {
+    pub attrtype: X520Name,
+    pub value:    String
 }
 
 fn decode_attribute_type_value(x: &ASN1Block)

src/x509/misc.rs

@@ -3,6 +3,7 @@ use num::bigint::ToBigInt;
 use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1};
 use x509::error::X509ParseError;
 
+/// Which version of x.509 certificate this is.
 #[derive(Clone,Copy,Debug,PartialEq)]
 pub enum X509Version { V1, V2, V3 }
 
@@ -65,6 +66,7 @@ impl ToASN1 for X509Version {
 
 /******************************************************************************/
 
+/// The serial number for this certificate.
 #[derive(Clone,Debug,PartialEq)]
 pub struct X509Serial {
     num: BigUint

src/x509/mod.rs

@@ -12,13 +12,14 @@ use rsa::{SIGNING_HASH_SHA1,SIGNING_HASH_SHA224,SIGNING_HASH_SHA256,SIGNING_HASH
 use sha1::Sha1;
 use sha2::{Sha224,Sha256,Sha384,Sha512};
 use simple_asn1::{ASN1Block,FromASN1,der_decode,from_der};
-use x509::validity::Validity;
-use x509::algident::{AlgorithmIdentifier,HashAlgorithm,PublicKeyInfo,
-                     decode_algorithm_ident};
-use x509::atv::InfoBlock;
+pub use x509::validity::Validity;
+pub use x509::algident::{AlgorithmIdentifier,HashAlgorithm,PublicKeyInfo};
+use x509::algident::{decode_algorithm_ident};
+pub use x509::atv::InfoBlock;
 use x509::error::X509ParseError;
-use x509::misc::{X509Serial,X509Version,decode_signature};
-use x509::publickey::X509PublicKey;
+pub use x509::misc::{X509Serial,X509Version};
+use x509::misc::{decode_signature};
+pub use x509::publickey::X509PublicKey;
 
 /*******************************************************************************
  *
@@ -88,6 +89,8 @@ fn decode_certificate(x: &ASN1Block)
  *
  ******************************************************************************/
 
+/// Parse an X.590 certificate in memory into a generic certificate that can
+/// be used by a program.
 pub fn parse_x509(buffer: &[u8]) -> Result<GenericCertificate,X509ParseError> {
     let blocks = from_der(&buffer[..])?;
     match blocks.first() {

src/x509/name.rs

@@ -2,6 +2,8 @@ use num::BigUint;
 use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1};
 use x509::error::X509ParseError;
 
+/// One of the various attributes that can be encoded within an x.509 name. To
+/// see one of these paired with its value, consider `AttributeTypeValue`.
 #[derive(Copy,Clone,Debug,Eq,Hash,PartialEq)]
 pub enum X520Name {
     Name, Surname, GivenName, Initials, GenerationQualifier, CommonName,

src/x509/publickey.rs

@@ -10,6 +10,8 @@ use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1,
 use utils::TranslateNums;
 use x509::error::X509ParseError;
 
+/// A general type that includes all the supported public key types that we
+/// could read in an x.509 certificate.
 pub enum X509PublicKey {
     DSA(DSAPublic),
     RSA(RSAPublic),

src/x509/validity.rs

@@ -2,10 +2,11 @@ use chrono::{DateTime,Utc};
 use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1};
 use x509::error::X509ParseError;
 
+/// The range of dates in which this certificate is valid.
 #[derive(Clone,Debug,PartialEq)]
 pub struct Validity {
-    not_before: DateTime<Utc>,
-    not_after:  DateTime<Utc>
+    pub not_before: DateTime<Utc>,
+    pub not_after:  DateTime<Utc>
 }
 
 fn decode_validity_data(bs: &ASN1Block) -> Result<Validity,X509ParseError> {