ARMmbed / ARMmbed/mbed-crypto

psa_import_key() documentation improvements

Open
#338 1 comment 0 reactions 0 assignees View on GitHub
Jira status: OPEN mirrored type: enhancement
Dominant language
C
Stars
108
Forks
95
PR merge metrics
No merged PRs in 30d

Description

### Description

Here's some things that were hard to figure out for psa_import_key() of an EC key for use with ECDSA that could be addressed with documentation. I figured them out from the source code and such and it took a long time.
* When you import a private EC key, the public key is always created from the private key. So the import is either of a key pair or a public key, never just a private key. Design is fine, but it is not obvious. OpenSSL doesn't work this way for example.
* For import to work, the one attribute you have to set is the key type, psa_set_key_type(), or it won't know what type of key you are importing.
* To make the key you imported usable for sometime you have to set some policy, particularly what algorithms you want it to work with and what operations you want to perform.

I'm working off-target on MacOS with Xcode against MBed 2.0, MBed 1.1 and MBed 1.1 as integrated into TF-M.

(Sorry I can't actually make pull requests to improve the documentation. I just have too many projects going to get involved at that level here, though I'd like to.)

### Issue request type

[ ] Question
[ X] Enhancement
[ ] Bug

Contributor guide

Open the contributing guide

Research direction

Start at the psa_import_key() API documentation and compare it with the source code and the psa_set_key_type() and policy APIs. Document that EC private-key imports derive the public key, that the key type is required, and that policy settings control use with ECDSA; confirm the wording against Mbed 2.0, Mbed 1.1, and TF-M integrations.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
cryptography, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.