doc: update doc

input-output-hk · Jul 12, 2024 · a3f5141 · a3f5141
1 parent c6b9b72
commit a3f5141
Show file tree

Hide file tree

Showing 8 changed files with 51 additions and 42 deletions.
diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_algo_identifier.rs b/catalyst-gateway-crates/c509-certificate/src/c509_algo_identifier.rs
@@ -1,11 +1,15 @@
 //! C509 Algorithm Identifier
+//!
 //! This module handle the `AlgorithmIdentifier` type where OID does not fall into the
 //! table.
 //!
 //! ```cddl
 //!    AlgorithmIdentifier = int / ~oid / [ algorithm: ~oid, parameters: bytes ]
 //! ```
 //!
+//! **Note** `AlgorithmIdentifier` that have the same OID with different parameters are
+//! not implemented yet.
+//!
 //! For more information about `AlgorithmIdentifier`,
 //! visit [C509 Certificate](https://datatracker.ietf.org/doc/draft-ietf-cose-cbor-encoded-cert/09/)
 

diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_attributes/mod.rs b/catalyst-gateway-crates/c509-certificate/src/c509_attributes/mod.rs
@@ -3,12 +3,13 @@
 //! ```cddl
 //! Attributes = ( attributeType: int, attributeValue: [+text] ) //
 //! ( attributeType: ~oid, attributeValue: [+bytes] )
+//! ```
 //!
 //! Use case:
 //! ```cddl
-//! SubjectDirectoryAttributes = [+Attributes]
+//!     SubjectDirectoryAttributes = [+Attributes]
 //! ```
-//! 
+//!
 //! For more information about `Atributes`,
 //! visit [C509 Certificate](https://datatracker.ietf.org/doc/draft-ietf-cose-cbor-encoded-cert/09/)
 

diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_big_uint.rs b/catalyst-gateway-crates/c509-certificate/src/c509_big_uint.rs
@@ -1,4 +1,5 @@
 //! C509 Unwrapped CBOR Unsigned Bignum (~biguint)
+//!
 //! Please refer to [CDDL Wrapping](https://datatracker.ietf.org/doc/html/rfc8610#section-3.7)
 //! for unwrapped types.
 

diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_extensions/mod.rs b/catalyst-gateway-crates/c509-certificate/src/c509_extensions/mod.rs
@@ -1,4 +1,5 @@
 //! C509 Extension as a part of `TBSCertificate` used in C509 Certificate.
+//!
 //! Extension fallback of C509 OID extension
 //! Given OID if not found in the registered OID table, it will be encoded as a PEN OID.
 //! If the OID is not a PEN OID, it will be encoded as an unwrapped OID.

diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_name/mod.rs b/catalyst-gateway-crates/c509-certificate/src/c509_name/mod.rs
@@ -1,9 +1,10 @@
 //! C509 type Name
+//!
 //! Currently only support natively signed c509 certificate, so all text strings
-//! are UTF-8 encoded and all attributeType SHALL be non-negative.
+//! are UTF-8 encoded and all attributeType should be non-negative.
 //!
 //! ```cddl
-//!  Name = [ * RelativeDistinguishedName ] / text / bytes
+//! Name = [ * RelativeDistinguishedName ] / text / bytes
 //! RelativeDistinguishedName = Attribute / [ 2* Attribute ]
 //! Attribute = ( attributeType: int, attributeValue: text ) //
 //!             ( attributeType: ~oid, attributeValue: bytes ) //

diff --git a/catalyst-gateway-crates/c509-certificate/src/c509_oid.rs b/catalyst-gateway-crates/c509-certificate/src/c509_oid.rs
@@ -1,4 +1,5 @@
 //! C509 OID provides an encoding and decoding of C509 Object Identifier (OID).
+//!
 //! Please refer to [RFC9090](https://datatracker.ietf.org/doc/rfc9090/) for OID encoding
 //! Please refer to [CDDL Wrapping](https://datatracker.ietf.org/doc/html/rfc8610#section-3.7)
 //! for unwrapped types.
@@ -16,7 +17,7 @@ const PEN_PREFIX: Oid<'static> = oid!(1.3.6 .1 .4 .1);
 /// Tag number representing IANA Private Enterprise Number (PEN) OID.
 const OID_PEN_TAG: u64 = 112;
 
-/// A strut of C509 OID with Registered Integer Encoding/Decoding.
+/// A strut of C509 OID with Registered Integer.
 #[derive(Debug, Clone, PartialEq)]
 pub struct C509oidRegistered {
     /// The `C509oid`.

diff --git a/catalyst-gateway-crates/c509-certificate/src/lib.rs b/catalyst-gateway-crates/c509-certificate/src/lib.rs
@@ -1,7 +1,37 @@
 //! CBOR Encoded X.509 Certificate (C509 Certificate) library
 //!
-//! This crate provides a library for generating C509 Certificates.
-//! The function is exposed to Javascript through wasm-bindgen.
+//! This crate provides a functionality for generating C509 Certificate.
+//!
+//! ## C509 certificate contains 2 parts
+//! 1. `TBSCertificate`
+//! 2. `issuerSignatureValue`
+//!
+//! In order to generate an unsigned C509 certificate, the TBS Certificate must be
+//! provided. Then the unsigned C509 certificate will then be used to calculate the
+//! issuerSignatureValue.
+//!
+//! # TBS Certificate
+//!
+//! The To Be Sign Certificate contains the following fields:
+//!    * c509CertificateType: A certificate type, whether 0 a natively signed C509
+//!      certificate following X.509 v3 or 1 a CBOR re-encoded X.509 v3 DER certificate.
+//!    * certificateSerialNumber: A unique serial number for the certificate.
+//!    * issuer: The entity that issued the certificate.
+//!    * validityNotBefore: The duration for which the Certificate Authority (CA)
+//!      guarantees it will retain information regarding the certificate's status on which
+//!      the period begins.
+//!    * validityNotAfter: The duration for which the Certificate Authority (CA)
+//!      guarantees it will retain information regarding the certificate's status on which
+//!      the period ends.
+//!    * subject: The entity associated with the public key stored in the subject public
+//!      key field.
+//!    * subjectPublicKeyAlgorithm: The algorithm that the public key is used.
+//!    * subjectPublicKey: The public key of the subject.
+//!    * extensions: A list of extensions defined for X.509 v3 certificate, providing
+//!      additional attributes for users or public keys, and for managing relationships
+//!      between Certificate Authorities (CAs).
+//!    * issuerSignatureAlgorithm: The algorithm used to sign the certificate (must be the
+//!      algorithm uses to create `IssuerSignatureValue`).
 //!
 //! Please refer to the [C509 Certificate](https://datatracker.ietf.org/doc/draft-ietf-cose-cbor-encoded-cert/09/) for more information.
 
@@ -23,41 +53,11 @@ pub mod signing;
 mod tables;
 pub mod tbs_cert;
 
-/// C509 certificate contains 2 parts
-/// 1. `TBSCertificate`
-/// 2. `issuerSignatureValue`
-/// In order to generate an unsigned C509 certificate, the TBS Certificate must be
-/// provided. Then the unsigned C509 certificate will then be used to calculate the
-/// issuerSignatureValue.
-///
-/// # TBS Certificate
-///
-/// * `tbs_cert` - The `TbsCertificate` is the TBS Certificate containing
-///    * c509CertificateType: A certificate type, whether 0 a natively signed C509
-///      certificate following X.509 v3 or 1 a CBOR re-encoded X.509 v3 DER certificate.
-///    * certificateSerialNumber: A unique serial number for the certificate.
-///    * issuer: The entity that issued the certificate.
-///    * validityNotBefore: The duration for which the Certificate Authority (CA)
-///      guarantees it will retain information regarding the certificate's status on which
-///      the period begins.
-///    * validityNotAfter: The duration for which the Certificate Authority (CA)
-///      guarantees it will retain information regarding the certificate's status on which
-///      the period ends.
-///    * subject: The entity associated with the public key stored in the subject public
-///      key field.
-///    * subjectPublicKeyAlgorithm: The algorithm that the public key is used,
-///    * subjectPublicKey: The public key of the subject.
-///    * extensions: A list of extensions defined for X.509 v3 certificate, providing
-///      additional attributes for users or public keys, and for managing relationships
-///      between Certificate Authorities (CAs).
-///    * issuerSignatureAlgorithm: The algorithm used to sign the certificate (must be the
-///      algorithm uses to create `IssuerSignatureValue`).
-
 /// Generate a signed C509 certificate.
 ///
 /// # Arguments
-/// `tbs_cert` - A cbor encoded TBS certificate.
-/// `private_key` - The private key used to sign the certificate.
+/// - `tbs_cert` - A cbor encoded TBS certificate.
+/// - `private_key` - The private key used to sign the certificate.
 ///
 /// # Returns
 /// Returns a signed C509 certificate.
@@ -78,8 +78,8 @@ pub fn generate_signed_c509_cert(
 /// Verify the signature of a C509 certificate.
 ///
 /// # Arguments
-/// `c509` - The C509 certificate to verify.
-/// `public_key` - The public key used to verify the certificate.
+/// - `c509` - The C509 certificate to verify.
+/// - `public_key` - The public key used to verify the certificate.
 ///
 /// # Errors
 /// Returns an error if the `issuer_signature_value` is invalid or the signature cannot be

diff --git a/catalyst-gateway-crates/c509-certificate/src/tbs_cert.rs b/catalyst-gateway-crates/c509-certificate/src/tbs_cert.rs
@@ -1,4 +1,4 @@
-//! To Be Sign Certificate (TBS Certificate) module use to construct a C509 certificate.
+//! To Be Sign Certificate (TBS Certificate) use to construct a C509 certificate.
 
 use minicbor::{encode::Write, Decode, Decoder, Encode, Encoder};