documented and example for ASN1 module

openssl/src/asn1.rs

@@ -1,5 +1,10 @@
+#![deny(missing_docs)]
+
 //! Defines the format of certificiates
 //!
+//! This module is used by [`x509`] and other certificate building functions
+//! to describe time, strings, and objects.
+//!
 //! 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
@@ -11,7 +16,14 @@
 //! 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
-
+//! [`x509`]: ../x509/struct.X509Builder.html
+//!
+//! ## Examples
+//!
+//! ```
+//! use openssl::asn1::Asn1Time;
+//! let tomorrow = Asn1Time::days_from_now(1);
+//! ```
 use ffi;
 use foreign_types::{ForeignType, ForeignTypeRef};
 use libc::{c_long, c_char, c_int};
@@ -37,7 +49,8 @@ foreign_type! {
     /// example outside the year range of 1950-2049.
     ///
     /// [ASN1_GENERALIZEDTIME_set] documentation from OpenSSL provides
-    /// further details of implmentation.
+    /// further details of implmentation.  Note: these docs are from the master
+    /// branch as documentation on the 1.1.0 branch did not include this page.
     ///
     /// [ASN1_GENERALIZEDTIME_set]: https://www.openssl.org/docs/manmaster/man3/ASN1_GENERALIZEDTIME_set.html
     pub struct Asn1GeneralizedTime;
@@ -72,7 +85,7 @@ foreign_type! {
     /// [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
+    /// [ASN_TIME_set]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_TIME_set.html
     pub struct Asn1Time;
     /// Reference to an [`Asn1Time`]
     ///
@@ -115,7 +128,7 @@ foreign_type! {
     /// 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
+    /// [ASN1_STRING-to_UTF8]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_STRING_to_UTF8.html
     pub struct Asn1String;
     /// Reference to [`Asn1String`]
     ///
@@ -156,15 +169,38 @@ foreign_type! {
     type CType = ffi::ASN1_INTEGER;
     fn drop = ffi::ASN1_INTEGER_free;
 
+    /// Numeric representation
+    ///
+    /// Integers in ASN.1 may include BigNum, int64 or uint64.  BigNum implementation
+    /// can be found within [`bn`] module.
+    ///
+    /// OpenSSL documentation includes [`ASN1_INTEGER_set`].
+    ///
+    /// [`bn`]: ../bn/index.html
+    /// [`ASN1_INTEGER_set`]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_INTEGER_set.html
     pub struct Asn1Integer;
+    /// Reference to [`Asn1Integer`]
+    ///
+    /// [`Asn1Integer`]: struct.Asn1Integer.html
     pub struct Asn1IntegerRef;
 }
 
 impl Asn1IntegerRef {
+    /// Returns value of ASN.1 integer, or -1 if there is an error, and 0 if the integer is Null.
+    ///
+    /// OpenSSL documentation at [`ASN1_INTEGER_get`].
+    ///
+    /// [`ASN1_INTEGER_get`]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_INTEGER_get.html
     pub fn get(&self) -> i64 {
         unsafe { ::ffi::ASN1_INTEGER_get(self.as_ptr()) as i64 }
     }
-
+    /// Sets the ASN.1 value to the value of a signed 32-bit integer, for larger numbers
+    /// see [`bn`].
+    ///
+    /// OpenSSL documentation at [`ASN1_INTEGER_set`]
+    ///
+    /// [`bn`]: ../bn/struct.BigNumRef.html#method.to_asn1_integer
+    /// [`ASN1_INTEGER_set`]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_INTEGER_set.html
     pub fn set(&mut self, value: i32) -> Result<(), ErrorStack> {
         unsafe { cvt(::ffi::ASN1_INTEGER_set(self.as_ptr(), value as c_long)).map(|_| ()) }
     }
@@ -173,16 +209,25 @@ impl Asn1IntegerRef {
 foreign_type! {
     type CType = ffi::ASN1_BIT_STRING;
     fn drop = ffi::ASN1_BIT_STRING_free;
-
+    /// Sequence of bytes
+    ///
+    /// Asn1BitString is used in [`x509`] certificates for the signature.
+    /// The bit string acts as a collection of bytes.
+    ///
+    /// [`x509`]: ../x509/struct.X509.html#method.signature
     pub struct Asn1BitString;
+    /// Reference to [`Asn1BitString`]
+    ///
+    /// [`Asn1BitString`]: struct.Asn1BitString.html
     pub struct Asn1BitStringRef;
 }
 
 impl Asn1BitStringRef {
+    /// Returns the Asn1BitString as a slice
     pub fn as_slice(&self) -> &[u8] {
         unsafe { slice::from_raw_parts(ASN1_STRING_data(self.as_ptr() as *mut _), self.len()) }
     }
-
+    /// Length of Asn1BitString in number of bytes.
     pub fn len(&self) -> usize {
         unsafe { ffi::ASN1_STRING_length(self.as_ptr() as *mut _) as usize }
     }
@@ -192,7 +237,17 @@ foreign_type! {
     type CType = ffi::ASN1_OBJECT;
     fn drop = ffi::ASN1_OBJECT_free;
 
+    /// Object Identifier
+    ///
+    /// Use OBJ_nid2obj() ffi to create objects, not Asn1Object directly.
+    ///
+    /// OpenSSL documentation at [`ASN1_OBJECT_new`]
+    ///
+    /// [`ASN1_OBJECT_new`]: https://www.openssl.org/docs/man1.1.0/crypto/ASN1_OBJECT_new.html
     pub struct Asn1Object;
+    /// Reference to [`Asn1Object`]
+    ///
+    /// [`Asn1Object`]: struct.Asn1Object.html
     pub struct Asn1ObjectRef;
 }