Improve documentation for `NK_is_AES_supported` and `NK_send_startup`

[robinkrahl]

After looking at the libnitrokey source and the firmware, I’m still not sure what these functions do:

• NK_is_AES_supported – When would this ever be false? When should I check this?
• NK_send_startup – According to the documentation, it is like a combination of get_status_storage and set_time, but libnitrokey never uses the returned data. Why should I call this method and not NK_set_time?

[muellermartin]

I'd say a general documentation for the usage and especially for API would be very useful. Something with Doxygen, Sphinx (with Breathe and Doxygen), or QDoc would be nice.

[robinkrahl]

Very true, I was thinking about compiling an overview document once I’m done with nitrokey-rs and nitrocli.

[szszszsz]

@robinkrahl
NK_is_AES_supported - early Nitrokey App's were checking this, to make sure current device is supporting AES-related functionality. Currently both Pro (0.7+) and Storage (0.36+ and some earlier) are supporting it, so there is no need to use it. It should be deprecated and removed in the next major version.
NK_send_startup - indeed, both the C and C++ API are not returning the result, which is an error. However, the underlying response packet is defined correctly, so using the same implementation as in get_status_storage() will make it work.
I guess this command was created to combine the two mentioned to save the time - early releases had slower communication (with polling set to 100-200 ms).

[robinkrahl]

Could you please also add some more explanations for the NK_get_SD_usage_data function? My understanding is that it returns safe ranges for the creation of a hidden volume. But how is this range chosen – is it the first, last or largest free range? And is it guaranteed to be safe, or is it just a guess?

[szszszsz]

AFAIR NK_get_SD_usage_data simply returns extremes (min/max) of accessed blocks indexes, for both read and write, in the given power cycle.

[robinkrahl]

Interesting! So it could make sense to warn the user if they try to create a hidden volume outside of these bounds, but one should regard them as a safe choice per se, right?

[robinkrahl]

And if it returns (20, 80) – does that mean that all accessed blocks were in the range 20..80, or in the ranges 0..20 and 80..100?

[szszszsz]

Exactly. In Nitrokey App's UI this is simply not possible, since damaging EV could reveal the HV.
AFAIR 20,80 is the default, so the FS' table would have space to grow. The HV should be created within this bound, so between 20% and 80% of the EV.
The procedure is to:

1. Create the EV;
2. Populate EV with data one can reveal;
3. Get the usage bounds;
4. Create HV within the bounds.

One must never use the EV further on to not damage HV by overwriting it. There are no protections by design, as it must not be revealed.

Edit: some FS's write its backup data in the center of the volume (e.g. NTFS), so the inital bounds could be e.g. 20,50.
Edit: to reply to the question, the accessed blocks should be out of the provided bounds for this power cycle.

[robinkrahl]

Thanks for the explanation! (By the way, 20..80 was just an example – I get 1..99 for an unused Storage.)

[szszszsz]

I see. It must be default in the Nitrokey App then.