WIP ASN.1 documentation

//! 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};

    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;

}

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;

}

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();

        }

    }

    /// 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 }

    }