diff options
-rw-r--r-- | openssl/src/asn1.rs | 69 |
1 files changed, 62 insertions, 7 deletions
diff --git a/openssl/src/asn1.rs b/openssl/src/asn1.rs index 867887d7..37b54d79 100644 --- a/openssl/src/asn1.rs +++ b/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; } |