WIP ASN.1 documentation

openssl/src/asn1.rs

@@ -1,3 +1,17 @@
+//! Defines the format of certificiates
+//!
+//! Abstract Syntax Notation One is an interface description language.
+//! The specification comes from [X.208] by OSI, and rewritten in X.680.
+//! ASN.1 describes properties of an object with a type set.  Those types
+//! can be atomic, structured, choice, and other (CHOICE and ANY).  These
+//! types are expressed as a number and the assignment operator ::=  gives
+//! the type a name.
+//!
+//! The implementation here provides a subset of the ASN.1 types that OpenSSL
+//! uses, especially in the properties of a certificate used in HTTPS.
+//!
+//! [X.208]: https://www.itu.int/rec/T-REC-X.208-198811-W/en
+
 use ffi;
 use foreign_types::{ForeignType, ForeignTypeRef};
 use libc::{c_long, c_char, c_int};
@@ -16,7 +30,20 @@ foreign_type! {
     type CType = ffi::ASN1_GENERALIZEDTIME;
     fn drop = ffi::ASN1_GENERALIZEDTIME_free;
 
+    /// Non-UTC representation of time
+    ///
+    /// If a time can be represented by UTCTime, UTCTime is used
+    /// otherwise, ASN1_GENERALIZEDTIME is used.  This would be, for
+    /// example outside the year range of 1950-2049.
+    ///
+    /// [ASN1_GENERALIZEDTIME_set] documentation from OpenSSL provides
+    /// further details of implmentation.
+    ///
+    /// [ASN1_GENERALIZEDTIME_set]: https://www.openssl.org/docs/manmaster/man3/ASN1_GENERALIZEDTIME_set.html
     pub struct Asn1GeneralizedTime;
+    /// Reference to a [`Asn1GeneralizedTime`]
+    ///
+    /// [`Asn1GeneralizedTime`]: struct.Asn1GeneralizedTime.html
     pub struct Asn1GeneralizedTimeRef;
 }
 
@@ -36,8 +63,20 @@ impl fmt::Display for Asn1GeneralizedTimeRef {
 foreign_type! {
     type CType = ffi::ASN1_TIME;
     fn drop = ffi::ASN1_TIME_free;
-
+    /// Time storage and comparison
+    ///
+    /// Asn1Time should be used to store and share time information
+    /// using certificates.  If Asn1Time is set using a string, it must
+    /// be in either YYMMDDHHMMSSZ, YYYYMMDDHHMMSSZ, or another ASN.1 format.
+    ///
+    /// [ASN_TIME_set] documentation at OpenSSL explains the ASN.1 implementaiton
+    /// used by OpenSSL.
+    ///
+    /// [ASN_TIME_set]: https://www.openssl.org/docs/manmaster/man3/ASN1_TIME_set.html
     pub struct Asn1Time;
+    /// Reference to an [`Asn1Time`]
+    ///
+    /// [`Asn1Time`]: struct.Asn1Time.html
     pub struct Asn1TimeRef;
 }
 
@@ -70,12 +109,26 @@ impl Asn1Time {
 foreign_type! {
     type CType = ffi::ASN1_STRING;
     fn drop = ffi::ASN1_STRING_free;
-
+    /// Primary ASN.1 type used by OpenSSL
+    ///
+    /// Almost all ASN.1 types in OpenSSL are represented by ASN1_STRING
+    /// structures.  This implementation uses [ASN1_STRING-to_UTF8] to preserve
+    /// compatibility with Rust's String.
+    ///
+    /// [ASN1_STRING-to_UTF8]: https://www.openssl.org/docs/manmaster/man3/ASN1_STRING_to_UTF8.html
     pub struct Asn1String;
+    /// Reference to [`Asn1String`]
+    ///
+    /// [`Asn1String`]: struct.Asn1String.html
     pub struct Asn1StringRef;
 }
 
 impl Asn1StringRef {
+    /// Converts the ASN.1 underlying format to UTF8
+    ///
+    /// ASN.1 strings may utilize UTF-16, ASCII, BMP, or UTF8.  This is important to
+    /// consume the string in a meaningful way without knowing the underlying
+    /// format.
     pub fn as_utf8(&self) -> Result<OpensslString, ErrorStack> {
         unsafe {
             let mut ptr = ptr::null_mut();
@@ -88,10 +141,12 @@ impl Asn1StringRef {
         }
     }
 
+    /// Return the string as an array of bytes
     pub fn as_slice(&self) -> &[u8] {
         unsafe { slice::from_raw_parts(ASN1_STRING_data(self.as_ptr()), self.len()) }
     }
 
+    /// Return the length of the Asn1String (number of bytes)
     pub fn len(&self) -> usize {
         unsafe { ffi::ASN1_STRING_length(self.as_ptr()) as usize }
     }