Fixed BaseError display trait impl.

- Changed to the displayed messages to proper sentences and also add
  information that is relevant for this crate.

- Added tests for missing items.

- Added documentation build check for CI.

Co-authored-by: Wiktor Kwapisiewicz <[email protected]>

Signed-off-by: Jesper Brynolf <[email protected]>

Author: Superhepper

.github/workflows/ci.yml

@@ -46,8 +46,6 @@ jobs:
         run: docker run -v $(pwd):/tmp/rust-tss-esapi -w /tmp/rust-tss-esapi/tss-esapi ubuntucontainer /tmp/rust-tss-esapi/tss-esapi/tests/all-ubuntu.sh
       - name: Run the cross-compilation script
         run: docker run -v $(pwd):/tmp/rust-tss-esapi -w /tmp/rust-tss-esapi/tss-esapi ubuntucontainer /tmp/rust-tss-esapi/tss-esapi/tests/cross-compile.sh
-      - name: Check the documentation
-        run: docker run -v $(pwd):/tmp/rust-tss-esapi -w /tmp/rust-tss-esapi/tss-esapi ubuntucontainer cargo doc
 
   tests-ubuntu-v3:
     name: Ubuntu tests on v3.x.y of tpm2-tss
@@ -90,3 +88,14 @@ jobs:
         run: docker build -t ubuntucontainer tss-esapi/tests/ --file tss-esapi/tests/Dockerfile-ubuntu
       - name: Run the tests
         run: docker run -v $(pwd):/tmp/rust-tss-esapi -w /tmp/rust-tss-esapi/tss-esapi ubuntucontainer /tmp/rust-tss-esapi/tss-esapi/tests/valgrind.sh
+
+  # Check that the documentation builds as well.
+  docs:
+    name: Check documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build the container
+        run: docker build -t ubuntucontainer tss-esapi/tests/ --file tss-esapi/tests/Dockerfile-ubuntu
+      - name: Check documentation
+        run: docker run -v $(pwd):/tmp/rust-tss-esapi -w /tmp/rust-tss-esapi/tss-esapi -e RUSTDOCFLAGS="-Dwarnings" ubuntucontainer cargo doc --document-private-items --no-deps

tss-esapi/src/constants/return_code/base_error.rs

@@ -55,58 +55,118 @@ use std::convert::TryFrom;
 #[derive(FromPrimitive, ToPrimitive, Copy, Clone, Debug, PartialEq, Eq, Hash)]
 #[repr(u16)]
 pub enum BaseError {
+    /// Catch all for all errors not otherwise specified.
     GeneralFailure = TSS2_BASE_RC_GENERAL_FAILURE as u16,
+    /// If called functionality isn't implemented.
     NotImplemented = TSS2_BASE_RC_NOT_IMPLEMENTED as u16,
+    /// A context structure is bad.
     BadContext = TSS2_BASE_RC_BAD_CONTEXT as u16,
+    /// Passed in ABI version doesn't match called module's ABI version.
     AbiMismatch = TSS2_BASE_RC_ABI_MISMATCH as u16,
+    /// A pointer is NULL that isn't allowed to be NULL.
     BadReference = TSS2_BASE_RC_BAD_REFERENCE as u16,
+    /// A buffer isn't large enough.
     InsufficientBuffer = TSS2_BASE_RC_INSUFFICIENT_BUFFER as u16,
+    /// Function called in the wrong order.
     BadSequence = TSS2_BASE_RC_BAD_SEQUENCE as u16,
+    /// Fails to connect to next lower layer.
     NoConnection = TSS2_BASE_RC_NO_CONNECTION as u16,
+    /// Operation timed out; function must be called again to be completed.
     TryAgain = TSS2_BASE_RC_TRY_AGAIN as u16,
+    /// IO failure.
     IoError = TSS2_BASE_RC_IO_ERROR as u16,
+    /// A parameter has a bad value.
     BadValue = TSS2_BASE_RC_BAD_VALUE as u16,
+    /// Operation not permitted.
     NotPermitted = TSS2_BASE_RC_NOT_PERMITTED as u16,
+    /// The TPM command doesn't use the number of sessions provided by the caller.
     InvalidSessions = TSS2_BASE_RC_INVALID_SESSIONS as u16,
+    /// A session with `decrypt` set in its [SessionAttributes](crate::attributes::SessionAttributes)
+    /// (TPMA_SESSION_DECRYPT bit set) was passed to a TPM command that doesn't support encryption
+    /// of the first command parameter.
     NoDecryptParam = TSS2_BASE_RC_NO_DECRYPT_PARAM as u16,
+    /// A session with `encrypt` set in its [SessionAttributes](crate::attributes::SessionAttributes)
+    /// (TPMA_SESSION_ENCRYPT bit set) was passed to a TPM command that doesn't support encryption
+    /// of the first response parameter.
     NoEncryptParam = TSS2_BASE_RC_NO_ENCRYPT_PARAM as u16,
+    /// If size of a parameter is incorrect.
     BadSize = TSS2_BASE_RC_BAD_SIZE as u16,
+    /// Response is malformed.
     MalformedResponse = TSS2_BASE_RC_MALFORMED_RESPONSE as u16,
+    /// Context not large enough.
     InsufficientContext = TSS2_BASE_RC_INSUFFICIENT_CONTEXT as u16,
+    /// Response is not long enough.
     InsufficientResponse = TSS2_BASE_RC_INSUFFICIENT_RESPONSE as u16,
+    /// Unknown or unusable TCTI version.
     IncompatibleTcti = TSS2_BASE_RC_INCOMPATIBLE_TCTI as u16,
+    /// Functionality not supported.
     NotSupported = TSS2_BASE_RC_NOT_SUPPORTED as u16,
+    /// TCTI context is bad.
     BadTctiStructure = TSS2_BASE_RC_BAD_TCTI_STRUCTURE as u16,
+    /// Memory allocation failed.
     Memory = TSS2_BASE_RC_MEMORY as u16,
+    /// Invalid [ObjectHandle](crate::handles::ObjectHandle)
+    /// (ESYS_TR handle).
     BadTr = TSS2_BASE_RC_BAD_TR as u16,
+    /// More than one session with `decrypt` set in its [SessionAttributes](crate::attributes::SessionAttributes)
+    /// (TPMA_SESSION_DECRYPT bit set).
     MultipleDecryptSessions = TSS2_BASE_RC_MULTIPLE_DECRYPT_SESSIONS as u16,
+    /// More than one session with encrypt set its [SessionAttributes](crate::attributes::SessionAttributes)
+    /// (TPMA_SESSION_ENCRYPT bit set).
     MultipleEncryptSessions = TSS2_BASE_RC_MULTIPLE_ENCRYPT_SESSIONS as u16,
+    /// Authorizing the TPM response failed.
     RspAuthFailed = TSS2_BASE_RC_RSP_AUTH_FAILED as u16,
+    /// No config is available.
     NoConfig = TSS2_BASE_RC_NO_CONFIG as u16,
+    /// The provided path is bad.
     BadPath = TSS2_BASE_RC_BAD_PATH as u16,
+    /// The object is not deletable.
     NotDeletable = TSS2_BASE_RC_NOT_DELETABLE as u16,
+    /// The provided path already exists.
     PathAlreadyExists = TSS2_BASE_RC_PATH_ALREADY_EXISTS as u16,
+    /// The key was not found.
     KeyNotFound = TSS2_BASE_RC_KEY_NOT_FOUND as u16,
+    /// Signature verification failed.
     SignatureVerificationFailed = TSS2_BASE_RC_SIGNATURE_VERIFICATION_FAILED as u16,
+    /// Hash mismatch.
     HashMismatch = TSS2_BASE_RC_HASH_MISMATCH as u16,
+    /// Key is not duplicatable.
     KeyNotDuplicable = TSS2_BASE_RC_KEY_NOT_DUPLICABLE as u16,
+    /// The path was not found.
     PathNotFound = TSS2_BASE_RC_PATH_NOT_FOUND as u16,
+    /// No certificate.
     NoCert = TSS2_BASE_RC_NO_CERT as u16,
+    /// No PCR.
     NoPcr = TSS2_BASE_RC_NO_PCR as u16,
+    /// PCR not resettable.
     PcrNotResettable = TSS2_BASE_RC_PCR_NOT_RESETTABLE as u16,
+    /// The template is bad.
     BadTemplate = TSS2_BASE_RC_BAD_TEMPLATE as u16,
+    /// Authorization failed.
     AuthorizationFailed = TSS2_BASE_RC_AUTHORIZATION_FAILED as u16,
+    /// Authorization is unknown.
     AuthorizationUnknown = TSS2_BASE_RC_AUTHORIZATION_UNKNOWN as u16,
+    /// NV is not readable.
     NvNotReadable = TSS2_BASE_RC_NV_NOT_READABLE as u16,
+    /// NV is too small.
     NvTooSmall = TSS2_BASE_RC_NV_TOO_SMALL as u16,
+    /// NV is not writable.
     NvNotWriteable = TSS2_BASE_RC_NV_NOT_WRITEABLE as u16,
+    /// The policy is unknown.
     PolicyUnknown = TSS2_BASE_RC_POLICY_UNKNOWN as u16,
+    /// The NV type is wrong.
     NvWrongType = TSS2_BASE_RC_NV_WRONG_TYPE as u16,
+    /// The name already exists.
     NameAlreadyExists = TSS2_BASE_RC_NAME_ALREADY_EXISTS as u16,
+    /// No TPM available.
     NoTpm = TSS2_BASE_RC_NO_TPM as u16,
+    /// The key is bad.
     BadKey = TSS2_BASE_RC_BAD_KEY as u16,
+    /// No handle provided.
     NoHandle = TSS2_BASE_RC_NO_HANDLE as u16,
+    /// Provisioning was not executed.
     NotProvisioned = TSS2_BASE_RC_NOT_PROVISIONED as u16,
+    /// Already provisioned.
     AlreadyProvisioned = TSS2_BASE_RC_ALREADY_PROVISIONED as u16,
 }
 

tss-esapi/src/error/return_code/base.rs

@@ -47,59 +47,70 @@ impl std::error::Error for BaseReturnCode {}
 impl std::fmt::Display for BaseReturnCode {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self.base_error {
-            BaseError::GeneralFailure => write!(f, "General Error"),
-            BaseError::NotImplemented => write!(f, "Not Implemented"),
-            BaseError::BadContext => write!(f, "Bad Context"),
-            BaseError::AbiMismatch => write!(f, "ABI Mismatch"),
-            BaseError::BadReference => write!(f, "Bad Reference"),
-            BaseError::InsufficientBuffer => write!(f, "Insufficient Buffer"),
-            BaseError::BadSequence => write!(f, "Bad Sequence"),
-            BaseError::NoConnection => write!(f, "No Connection"),
-            BaseError::TryAgain => write!(f, "Try Again"),
-            BaseError::IoError => write!(f, "IO Error"),
-            BaseError::BadValue => write!(f, "Bad Value"),
-            BaseError::NotPermitted => write!(f, "Not Permitted"),
-            BaseError::InvalidSessions => write!(f, "Invalid Sessions"),
-            BaseError::NoDecryptParam => write!(f, "No Decrypt Param"),
-            BaseError::NoEncryptParam => write!(f, "No Encrypt Param"),
-            BaseError::BadSize => write!(f, "Bad Size"),
-            BaseError::MalformedResponse => write!(f, "Malformed Response"),
-            BaseError::InsufficientContext => write!(f, "Insufficient Context"),
-            BaseError::InsufficientResponse => write!(f, "Insufficient Response"),
-            BaseError::IncompatibleTcti => write!(f, "Incompatible TCTI"),
-            BaseError::NotSupported => write!(f, "Not Supported"),
-            BaseError::BadTctiStructure => write!(f, "Bad TCTI Structure"),
-            BaseError::Memory => write!(f, "Memory"),
-            BaseError::BadTr => write!(f, "Bad TR"),
-            BaseError::MultipleDecryptSessions => write!(f, "Multiple Decrypt Sessions"),
-            BaseError::MultipleEncryptSessions => write!(f, "Multiple Encrypt Sessions"),
-            BaseError::RspAuthFailed => write!(f, "RSP Auth Failed"),
-            BaseError::NoConfig => write!(f, "No Config"),
-            BaseError::BadPath => write!(f, "Bad Path"),
-            BaseError::NotDeletable => write!(f, "Not Deletable"),
-            BaseError::PathAlreadyExists => write!(f, "Path Already Exists"),
-            BaseError::KeyNotFound => write!(f, "Key Not Found"),
-            BaseError::SignatureVerificationFailed => write!(f, "Signature Verification Failed"),
-            BaseError::HashMismatch => write!(f, "Hash Mismatch"),
-            BaseError::KeyNotDuplicable => write!(f, "Key Not Duplicable"),
-            BaseError::PathNotFound => write!(f, "Path Not Found"),
-            BaseError::NoCert => write!(f, "No Cert"),
-            BaseError::NoPcr => write!(f, "No PCR"),
-            BaseError::PcrNotResettable => write!(f, "PCR Not Resettable"),
-            BaseError::BadTemplate => write!(f, "Bad Template"),
-            BaseError::AuthorizationFailed => write!(f, "Authorization Failed"),
-            BaseError::AuthorizationUnknown => write!(f, "Authorization Unknown"),
-            BaseError::NvNotReadable => write!(f, "NV Not Readable"),
-            BaseError::NvTooSmall => write!(f, "NV Too Small"),
-            BaseError::NvNotWriteable => write!(f, "NV Not Writeable"),
-            BaseError::PolicyUnknown => write!(f, "Policy Unknown"),
-            BaseError::NvWrongType => write!(f, "NV Wrong Type"),
-            BaseError::NameAlreadyExists => write!(f, "Name Already Exists"),
-            BaseError::NoTpm => write!(f, "No TPM"),
-            BaseError::BadKey => write!(f, "Bad Key"),
-            BaseError::NoHandle => write!(f, "No Handle"),
-            BaseError::NotProvisioned => write!(f, "Not Provisioned"),
-            BaseError::AlreadyProvisioned => write!(f, "Already Provisioned"),
+            BaseError::GeneralFailure => write!(f, "An unspecified error occurred."),
+            BaseError::NotImplemented => write!(f, "Called functionality isn't implemented."),
+            BaseError::BadContext => write!(f, "A context structure is bad."),
+            BaseError::AbiMismatch => write!(
+                f,
+                "Passed in ABI version doesn't match called module's ABI version."
+            ),
+            BaseError::BadReference => {
+                write!(f, "A pointer is NULL that isn't allowed to be NULL.")
+            }
+            BaseError::InsufficientBuffer => write!(f, "A buffer isn't large enough."),
+            BaseError::BadSequence => write!(f, "Function called in the wrong order."),
+            BaseError::NoConnection => write!(f, "Fails to connect to next lower layer."),
+            BaseError::TryAgain => write!(
+                f,
+                "Operation timed out; function must be called again to be completed."
+            ),
+            BaseError::IoError => write!(f, "IO failure."),
+            BaseError::BadValue => write!(f, "A parameter has a bad value."),
+            BaseError::NotPermitted => write!(f, "Operation not permitted."),
+            BaseError::InvalidSessions => write!(
+                f,
+                "The TPM command doesn't use the number of sessions provided by the caller."
+            ),
+            BaseError::NoDecryptParam => write!(f, "A session with decrypt set in its SessionAttributes (TPMA_SESSION_DECRYPT bit set) was passed to a TPM command that doesn't support encryption of the first command parameter."),
+            BaseError::NoEncryptParam => write!(f, "A session with encrypt set in its SessionAttributes (TPMA_SESSION_ENCRYPT bit set) was passed to a TPM command that doesn't support encryption of the first response parameter."),
+            BaseError::BadSize => write!(f, "Size of a parameter is incorrect."),
+            BaseError::MalformedResponse => write!(f, "Response is malformed."),
+            BaseError::InsufficientContext => write!(f, "Context not large enough."),
+            BaseError::InsufficientResponse => write!(f, "Response is not long enough."),
+            BaseError::IncompatibleTcti => write!(f, "Unknown or unusable TCTI version."),
+            BaseError::NotSupported => write!(f, "Functionality not supported."),
+            BaseError::BadTctiStructure => write!(f, "TCTI context is bad."),
+            BaseError::Memory => write!(f, "Memory allocation failed."),
+            BaseError::BadTr => write!(f, "Invalid ObjectHandle(ESYS_TR handle)."),
+            BaseError::MultipleDecryptSessions => write!(f, "More than one session with decrypt set in SessionAttributes (TPMA_SESSION_DECRYPT bit set)."),
+            BaseError::MultipleEncryptSessions => write!(f, "More than one session with encrypt set in SessionAttributes (TPMA_SESSION_ENCRYPT bit set)."),
+            BaseError::RspAuthFailed => write!(f, "Authorizing the TPM response failed."),
+            BaseError::NoConfig => write!(f, "No config is available."),
+            BaseError::BadPath => write!(f, "The provided path is bad."),
+            BaseError::NotDeletable => write!(f, "The object is not deletable."),
+            BaseError::PathAlreadyExists => write!(f, "The provided path already exists."),
+            BaseError::KeyNotFound => write!(f, "The key was not found."),
+            BaseError::SignatureVerificationFailed => write!(f, "Signature verification failed."),
+            BaseError::HashMismatch => write!(f, "Hash mismatch."),
+            BaseError::KeyNotDuplicable => write!(f, "Key is not duplicatable."),
+            BaseError::PathNotFound => write!(f, "The path was not found."),
+            BaseError::NoCert => write!(f, "No certificate."),
+            BaseError::NoPcr => write!(f, "No PCR."),
+            BaseError::PcrNotResettable => write!(f, "PCR not resettable."),
+            BaseError::BadTemplate => write!(f, "The template is bad."),
+            BaseError::AuthorizationFailed => write!(f, "Authorization failed."),
+            BaseError::AuthorizationUnknown => write!(f, "Authorization is unknown."),
+            BaseError::NvNotReadable => write!(f, "NV is not readable."),
+            BaseError::NvTooSmall => write!(f, "NV is too small."),
+            BaseError::NvNotWriteable => write!(f, "NV is not writable."),
+            BaseError::PolicyUnknown => write!(f, "The policy is unknown."),
+            BaseError::NvWrongType => write!(f, "The NV type is wrong."),
+            BaseError::NameAlreadyExists => write!(f, "The name already exists."),
+            BaseError::NoTpm => write!(f, "No TPM available."),
+            BaseError::BadKey => write!(f, "The key is bad."),
+            BaseError::NoHandle => write!(f, "No handle provided."),
+            BaseError::NotProvisioned => write!(f, "Provisioning was not executed."),
+            BaseError::AlreadyProvisioned => write!(f, "Already provisioned."),
         }
     }
 }

tss-esapi/src/interface_types/session_handles.rs

@@ -92,7 +92,7 @@ pub enum AuthSession {
 }
 
 impl AuthSession {
-    /// Function that creates a Option<Session>.
+    /// Function that creates a `Option<Session>`.
     ///
     /// If a Session is created from the NoneHandle
     /// then the returned value from the function will be None.

tss-esapi/src/structures/lists/pcr_selection.rs

@@ -52,7 +52,7 @@ impl PcrSelectionList {
         Ok(())
     }
 
-    /// Function for retrieving the PcrSelectionList from Option<PcrSelectionList>
+    /// Function for retrieving the PcrSelectionList from `Option<PcrSelectionList>`
     ///
     /// This returns an empty list if None is passed
     pub fn list_from_option(pcr_list: Option<PcrSelectionList>) -> PcrSelectionList {