From 060b82b35157865e0143de6359622e51eb81e247 Mon Sep 17 00:00:00 2001 From: Adam Wick Date: Mon, 27 May 2019 20:46:34 -0700 Subject: [PATCH] Update the x.509 documentation ... which made a number of flaws very obvious. --- src/x509/algident.rs | 16 ++++++++++++++++ src/x509/atv.rs | 14 ++++++++------ src/x509/misc.rs | 2 ++ src/x509/mod.rs | 15 +++++++++------ src/x509/name.rs | 2 ++ src/x509/publickey.rs | 2 ++ src/x509/validity.rs | 5 +++-- 7 files changed, 42 insertions(+), 14 deletions(-) diff --git a/src/x509/algident.rs b/src/x509/algident.rs index fbc7252..c8314a3 100644 --- a/src/x509/algident.rs +++ b/src/x509/algident.rs @@ -2,12 +2,28 @@ use num::BigUint; use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1}; use x509::error::X509ParseError; +/// A supported x509 hash algorithm #[derive(Clone,Copy,Debug,PartialEq)] pub enum HashAlgorithm { SHA1, SHA224, SHA256, SHA384, SHA512 } +/// A supported x509 asymmetric crypto algorithm #[derive(Clone,Copy,Debug,PartialEq)] pub enum PublicKeyInfo { RSA, DSA, ECDSA } +/// The algorithm used, either in a certificate or as part of the signing +/// process. We only actually support a subset of the possible values, +/// here, although we try to catch them all. +/// +/// Specifically, this library supports: +/// +/// | | *RSA* | *DSA* | *ECDSA* | +/// |----------|-------|-------|---------| +/// | *SHA1* | X | X | X | +/// | *SHA224* | X | X | X | +/// | *SHA256* | X | X | X | +/// | *SHA384* | X | | X | +/// | *SHA512* | X | | X | +/// #[derive(Clone,Debug,PartialEq)] pub struct AlgorithmIdentifier { pub hash: HashAlgorithm, diff --git a/src/x509/atv.rs b/src/x509/atv.rs index 6d3f615..597d88a 100644 --- a/src/x509/atv.rs +++ b/src/x509/atv.rs @@ -1,11 +1,13 @@ use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1}; use std::ops::Index; use x509::error::X509ParseError; -use x509::name::X520Name; +pub use x509::name::X520Name; +/// All of the various bits of information that are encoded within an x.509 +/// certificate. #[derive(Clone,Debug)] pub struct InfoBlock { - fields: Vec + pub fields: Vec } const EMPTY_STRING: &'static str = ""; @@ -116,11 +118,11 @@ impl ToASN1 for InfoBlock { } } - +/// An attribute within an x.509 key and its associated string value. #[derive(Clone,Debug,PartialEq)] -struct AttributeTypeValue { - attrtype: X520Name, - value: String +pub struct AttributeTypeValue { + pub attrtype: X520Name, + pub value: String } fn decode_attribute_type_value(x: &ASN1Block) diff --git a/src/x509/misc.rs b/src/x509/misc.rs index f499c85..643a879 100644 --- a/src/x509/misc.rs +++ b/src/x509/misc.rs @@ -3,6 +3,7 @@ use num::bigint::ToBigInt; use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1}; use x509::error::X509ParseError; +/// Which version of x.509 certificate this is. #[derive(Clone,Copy,Debug,PartialEq)] pub enum X509Version { V1, V2, V3 } @@ -65,6 +66,7 @@ impl ToASN1 for X509Version { /******************************************************************************/ +/// The serial number for this certificate. #[derive(Clone,Debug,PartialEq)] pub struct X509Serial { num: BigUint diff --git a/src/x509/mod.rs b/src/x509/mod.rs index 412ba5a..84d16ed 100644 --- a/src/x509/mod.rs +++ b/src/x509/mod.rs @@ -12,13 +12,14 @@ use rsa::{SIGNING_HASH_SHA1,SIGNING_HASH_SHA224,SIGNING_HASH_SHA256,SIGNING_HASH use sha1::Sha1; use sha2::{Sha224,Sha256,Sha384,Sha512}; use simple_asn1::{ASN1Block,FromASN1,der_decode,from_der}; -use x509::validity::Validity; -use x509::algident::{AlgorithmIdentifier,HashAlgorithm,PublicKeyInfo, - decode_algorithm_ident}; -use x509::atv::InfoBlock; +pub use x509::validity::Validity; +pub use x509::algident::{AlgorithmIdentifier,HashAlgorithm,PublicKeyInfo}; +use x509::algident::{decode_algorithm_ident}; +pub use x509::atv::InfoBlock; use x509::error::X509ParseError; -use x509::misc::{X509Serial,X509Version,decode_signature}; -use x509::publickey::X509PublicKey; +pub use x509::misc::{X509Serial,X509Version}; +use x509::misc::{decode_signature}; +pub use x509::publickey::X509PublicKey; /******************************************************************************* * @@ -88,6 +89,8 @@ fn decode_certificate(x: &ASN1Block) * ******************************************************************************/ +/// Parse an X.590 certificate in memory into a generic certificate that can +/// be used by a program. pub fn parse_x509(buffer: &[u8]) -> Result { let blocks = from_der(&buffer[..])?; match blocks.first() { diff --git a/src/x509/name.rs b/src/x509/name.rs index ce9ce06..7067b18 100644 --- a/src/x509/name.rs +++ b/src/x509/name.rs @@ -2,6 +2,8 @@ use num::BigUint; use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1}; use x509::error::X509ParseError; +/// One of the various attributes that can be encoded within an x.509 name. To +/// see one of these paired with its value, consider `AttributeTypeValue`. #[derive(Copy,Clone,Debug,Eq,Hash,PartialEq)] pub enum X520Name { Name, Surname, GivenName, Initials, GenerationQualifier, CommonName, diff --git a/src/x509/publickey.rs b/src/x509/publickey.rs index 2742001..7b23976 100644 --- a/src/x509/publickey.rs +++ b/src/x509/publickey.rs @@ -10,6 +10,8 @@ use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,OID,ToASN1, use utils::TranslateNums; use x509::error::X509ParseError; +/// A general type that includes all the supported public key types that we +/// could read in an x.509 certificate. pub enum X509PublicKey { DSA(DSAPublic), RSA(RSAPublic), diff --git a/src/x509/validity.rs b/src/x509/validity.rs index 4e273d1..749a2fe 100644 --- a/src/x509/validity.rs +++ b/src/x509/validity.rs @@ -2,10 +2,11 @@ use chrono::{DateTime,Utc}; use simple_asn1::{ASN1Block,ASN1Class,ASN1EncodeErr,FromASN1,ToASN1}; use x509::error::X509ParseError; +/// The range of dates in which this certificate is valid. #[derive(Clone,Debug,PartialEq)] pub struct Validity { - not_before: DateTime, - not_after: DateTime + pub not_before: DateTime, + pub not_after: DateTime } fn decode_validity_data(bs: &ASN1Block) -> Result {