Public / private distinction in crypto.h, crypto_values.h, crypto_struct.h
- Dominant language
- C
- Stars
- 108
- Forks
- 95
- PR merge metrics
- No merged PRs in 30d
Description
### Description
It seems clear that everything in crypto.h is public interface and can be depended on when using the PSA Crypto API, but it is not clear for the other files like crypto_values.h and crypto_struct.h.
For example it seems like most of crypto_values.h is public which makes you think the same is true for crypto_struct.h, but it's not. The internals of `struct psa_hash_operation_s` are clearly private and depend on how MBed works. It is different in the MBed in TF-M than it is in the source in this repository (and that seems perfectly OK).
Since C doesn't allow you to hide stuff in headers, the way to address this is to clearly label stuff that is private in a comment. Here's an example:
```
struct _QCBOREncodeContext {
// PRIVATE DATA STRUCTURE
UsefulOutBuf OutBuf; // Pointer to output buffer, its length and
// position in it
uint8_t uError; // Error state, always from QCBORError enum
QCBORTrackNesting nesting; // Keep track of array and map nesting
};
```
I noticed this when I started to write code against the internal of crypto_struct.h and then saw the difference between this repository and TF-M.
### Issue request type
[ ] Question
[X] Enhancement
[ ] Bug
Contributor guide
Research direction
Start by comparing crypto.h, crypto_values.h, and crypto_struct.h, focusing on which declarations are intended as public PSA Crypto API and which are implementation details. Mark private structures or data clearly in comments, using the reported crypto_struct.h internals as the reference; done means the public/private distinction is explicit without changing the API.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- cryptography
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100