documented and example for ASN1 module

#![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

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

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

    /// [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`]

    ///

    /// 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`]

    ///

    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(|_| ()) }

    }

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 }

    }

    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;

}