Versioning of the Nitro Secure Module?

[robotal]

I couldn't find any documentation of how to interpret the results of DescribeNSM response

From src/api/mod.rs:

pub enum Request {
...
  DescribeNSM
...
}

pub enum Response {
...
  DescribeNSM {
          /// Breaking API changes are denoted by `major_version`
          version_major: u16,
          /// Minor API changes are denoted by `minor_version`. Minor versions should be backwards compatible.
          version_minor: u16,
          /// Patch version. These are security and stability updates and do not affect API.
          version_patch: u16,
          /// `module_id` is an identifier for a singular NitroSecureModule
          module_id: String,
          /// The maximum number of PCRs exposed by the NitroSecureModule.
          max_pcrs: u16,
          /// The PCRs that are read-only.
          locked_pcrs: BTreeSet<u16>,
          /// The digest of the PCR Bank
          digest: Digest,
      },
...

}

Other than trying out different nitro enclaves and seeing what values it returns, is there some sort of guidance on how to interpret the versions returned here? Would that potentially affect the API used to send requests to the nsm device API in src/driver/mod.rs? Is that something my enclave application should worry about checking?

[petreeftime]

The enclave application shouldn't really care about the version exposed in this field, except maybe for debugging reasons, or for libraries to be able to provide backwards compatibility.

For example, if we replace a method or field in version 2.0, a library might be able to run a compatibility layer than transforms the input from it's API to work with either version 1.0 or version 2.0.

Another reason to check might be if a feature is added, it might take some time until it propagates everywhere, so a library might want to check and emit a useful error message if the required functionality is not yet available, or fall back on an already existing API.

In practice, the API will be either backwards compatible (ie. version 1.x.y), or if there is a breaking change, it will require opt-in as an additional enclave feature (ie. nitro-cli run-enclave --nsm-version 2), such that users will not be impacted by changes without their express consent.

Today, the reported version is static, so it should always be 1.0.y (but obviously won't be the same forever).