Ledger App OpenPGP.
(c) 2024 Ledger SAS.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
OpenPGP Application manage 4 keys to Perform Security Operation (PSO) plus 2 for secure channel.
The 4 keys are defined as follow:
The 3 first asymmetric keys can be either randomly generated on-card or explicitly imported from outside.
The 4th is imported from outside.
It's never possible to retrieve private key from the card.
This add-on specification propose a solution to derive those keys from the master seed managed by the Ledger Token. This allows owner to restore a broken token without the needs to keep track of keys outside the card.
Moreover this add-on specification propose to manage multiple set of the 4 previously described keys.
To modify the keys slot, just select the corresponding menu from the screen.
Nano
Wallet (Stax, Flex)
OpenPGP Application provides, as optional feature, to generate random bytes.
This add-on specification propose new type of random generation:
A full key backup mechanism is provided.
The deterministic key derivation process relies on the
BIP32 scheme. The master install path of the App is set
to /0x80'GPG', aka /80475047.
Deterministic key derivation maybe activated in:
Settings -> Seed Mode -> Set on
This activation remains effective until set off is selected.
The key management remains the same if seed mode is on or off. So there is no performance impact when using seeded keys.
Seeded keys are generated as follow:
Step 1:
For a given keys slot n, starting from 1, a seed is first derived with the following path
Sn = BIP32_derive (/0x80475047/n)
Step 2:
Then specific seeds are derived with the SHA3-XOF function for each of the 4 key:
Sk[i] = SHA3-XOF(SHA256(Sn \| <key_name> \| int16(i)), length)
Where:
Step 3:
RSA key generation
Generate two seed Sp, Sq in step2 with:
Generate two prime numbers p, q:
Generate RSA key pair as usual:
ECC key generation
Generate one seed Sd in step2 with:
Generate ECC key pair:
AES key generation
Generate one seed Sd in step2 with:
Generate AES key:
The deterministic random number generation relies on the
BIP32 scheme. The master install path of the App is set
to /0x80'GPG', aka /80475047.
Random prime number generation:
For a given length L:
Seeded random number:
For a given length L and seed S:
Seeded prime number generation:
For a given length L and seed S:
In order to backup/restore private key the commands put_data and get_data accept the tags:
put_data command accept the exact output of get_data. The get_data command return both the public and private key.
For security and confidentiality, private key is returned encrypted in AES. The key used is derived according to previously described AES key derivation with name 'key'.
The data payload is formatted as follow:
size Description 4 OS Target ID 4 API Level 4 public key size var public key 4 private key size var encrypted private key
Key slots are managed by data object 01F1 and 01F2 witch are manageable by PUT/GET DATA command as for others DO and organized as follow.
On application reset, the 01F2 content is set to Default Slot value of 01F1.
01F1:
bytes Description R/W 1 Number of slot R 2 Default slot R/W 3 Allowed slot selection method R/W
Byte 3 is encoded as follow:
b8 b7 b6 b5 b4 b3 b2 b1 Meaning - - - - - - - x selection by APDU - - - - - - x - selection by screen
01F2:
bytes Description R/W 1 Current slot R/W
01F0:
bytes Description R/W 1-3 01F1 content R 4 01F2 content R
Access Conditions:
DO
Read
Write 01F0 Always Never 01F1 Always Verify PW3 01F2 Always Verify PW2
P2 parameter of GENERATE ASYMMETRIC KEY PAIR is set to (hex value):
P1 parameter of GET CHALLENGE is a bit-field encoded as follow:
b8 b7 b6 b5 b4 b3 b2 b1 Meaning - - - - - - - x seeded random - - - - - - x - prime random
When seeded mode is set, data field contains the seed and P2 contains the length of random bytes to generate.
GnuPG use both fingerprints and serial number to identify key on card. So, the put_data command is able to modify the AID file with '4F' tag. In that case the data field shall be 4 bytes length and shall contain the new serial number. '4F' is protected by PW3 (admin) PIN.