PIV Text Storage

This walkthrough shows how to securely store notes/secrets on the PIV application of a Yubikey/RP2350

Storage Requirements

The PIV application has a limited amount of storage space available for storing data. The maximum size of a single data object on a typical Yubikey is 1024 bytes, and the total storage capacity is 32 KB.

The PIV application on the RP2350-based keys like RS-Key have a maximum size of 2048 bytes for a single data object, and the total storage capacity is 64 KB. (or more)

Therefore, it is important to keep the notes/secrets small and concise.

Real-World Storage Example

I was able to manually prune a 12371-byte secrets file down to 3223 bytes by removing unnecessary whitespace and comments, and removing extraneous or redundant information. While my master secrets file is quite large and complex, this file targets only the most important secrets, in particular for services from which the others can later be retrieved.

That 3223-byte file is still too large to store in a single data object on a Yubikey, but I was able to compress it with gzip to 1465 bytes, which is small enough to store in a single data object on an RS-Key firmware.

The PIV Application

The PIV application on a Yubikey/RP2350 is designed to store cryptographic keys and certificates, but it can also be used to store arbitrary data in the form of "data objects". Each data object is identified by a unique Object Identifier (OID) and can be read or written using the PIV commands.

This works independently of the cryptographic functions of the PIV application, so you can use it to store notes/secrets without needing to pre-emptively configure your PIV authentication. (ie generate or manage keys/certificates)

PIV Data Objects

Complete List of PIV Data Objects

A number of these data objects are necessary for the PIV application to function properly as an authentication/cryptography device, and some are reserved for specific purposes. However, there are several data objects that can be used to store arbitrary data, such as notes or secrets. See the shorter list below for the most useful containers for this purpose.

Short List: Top 3 Containers for Plaintext/Token Storage

These containers are rarely used for their intended purpose and are large enough to store arbitrary data. They are also PIN-protected, which is important for security.

My Experience

I personally use the 0x5FC121 container for my primary secrets vault. I may try storing a PGP private key in the 0x5FC108 container, but I have not yet done so. I intend to reserver the 0x5FC103 container for emergency codes and other small secrets that I may need to access quickly.

Write the Notes/Secrets to the PIV Application

Pre-requisites:

• A Yubikey or RP2350 device with PIV application enabled.
• The ykman command-line tool installed on your system.
• A PIN configured for your PIV application (default is 123456).

To begin, create a /tmp/secret.txt file with your secret data.

# Create a secret file
nano /tmp/secret.txt

Check the size of your secret file to see if it fits as-is into one of the PIV containers.

# Check the size of the secret file
wc -c /tmp/secret.txt
# Output: <num-bytes> /tmp/secret.txt

Write File Directly

If the file is small enough to fit into one of the PIV containers, you can write it directly.
If not, you may need to compress it or split it into multiple parts.

Write the secret file directly to a PIV container (if it fits).

# Write the secret file to the Cardholder Iris Images container (0x5FC121)
ykman piv objects import 0x5fc121 /tmp/secret.txt
# Output: Enter PIN: 
#         Object imported.

Compress File Before Writing

Compress the secret file and write it to a PIV container (if it doesn't fit).

# Compress the secret file using gzip
gzip -9 -c /tmp/secret.txt > /tmp/secret.txt.gz
# Compress the file using xz
xz -9 -e -c /tmp/secret.txt > /tmp/secret.txt.xz
# Check the size of the compressed file(s)
wc -c /tmp/secret.txt.gz
wc -c /tmp/secret.txt.xz
# Output: <num-bytes> /tmp/secret.txt.gz
#         <num-bytes> /tmp/secret.txt.xz

Hopefully, one of the compressed files is small enough to fit into a PIV container.
If not, you will need to further trim the file or split it into multiple parts.

Once you have a file that fits, you can write it to the PIV container as shown in Option A:

Gzip Example:

# Write the compressed secret file to the Cardholder Iris Images container (0x5FC121)
ykman piv objects import 0x5fc121 /tmp/secret.txt.gz
# Output: Enter PIN: 
#         Object imported.

Xz Example:

# Write the compressed secret file to the Cardholder Iris Images container (0x5FC121)
ykman piv objects import 0x5fc121 /tmp/secret.txt.xz
# Output: Enter PIN: 
#         Object imported.

Read the Notes/Secrets from the PIV Application

Option A: Uncompressed File

# Read the secret file from the Cardholder Iris Images container (0x5FC121)
ykman piv objects export 0x5fc121 /tmp/secret.txt
# Output: Enter PIN:
#         Exported object 6275361 to /tmp/secret.txt.

Option B: Compressed with gzip

# Read the compressed secret file from the Cardholder Iris Images container (0x5FC121)
ykman piv objects export 0x5fc121 /tmp/secret.txt.gz
# Decompress the file
gunzip /tmp/secret.txt.gz
rm -f /tmp/secret.txt.gz
# Output: Enter PIN:
#         Exported object 6275361 to /tmp/secret.txt.gz.
# NOTE: Output file will be /tmp/secret.txt after decompression.

Option C: Compressed with xz

# Read the compressed secret file from the Cardholder Iris Images container (0x5FC121)
ykman piv objects export 0x5fc121 /tmp/secret.txt.xz
# Decompress the file
xz -d /tmp/secret.txt.xz
rm -f /tmp/secret.txt.xz
# Output: Enter PIN:
#         Exported object 6275361 to /tmp/secret.txt.xz.
# NOTE: File will be /tmp/secret.txt

Tips and Tricks

Using typed text or an input prompt instead of a file

Here are some examples of how to write a secret directly from typed text or an input prompt without creating a plaintext file on disk.

Include the secret text directly in the command:

# Write a secret directly from typed text using a here-document
ykman piv objects import 0x5fc121 <(echo -n "This is my secret text that I want to store in the PIV application.")

Use an input prompt to read the secret and write it directly:

# Write a secret directly from an input prompt using read
read -p "Enter your secret: " secret && ykman piv objects import 0x5fc121 <(echo -n "$secret")

On Compression

If you choose to use a compressed secret file, it is important to remember that you will need to decompress it after reading it from the PIV application.

The examples earlier in the document show how to do this using gunzip for gzip-compressed files and xz -d for xz-compressed files.

If you forget to decompress the file, you will not be able to read the original secret text until you do.

However, leaving a compressed file on disk is still a security risk as it is trivially easy to decompress it and recover the original secret text.

Therefore, it is important to always securely delete any temporary files after use.

IMPORTANT Security Considerations

After verifying the secret file was successfully written to the PIV application, it is important to securely delete the original plaintext file from your system. This can be done using a secure deletion tool such as shred or srm, or simply using rm -f is probably sufficient for most modern SSD drives.

Standard Cleanup

It's better to include everything even if we didn't use interimediary compressed files, so that the cleanup is complete and secure so the commands below will remove any temporary files that may have been created during the process.

# Remove the original (or new) plaintext secret file
rm -f /tmp/secret.txt
# Remove the compressed secret file(s) (if used)
rm -f /tmp/secret.txt.gz
rm -f /tmp/secret.txt.xz
# Check for any other temporary files with similar names and remove them as needed
find /tmp -type f -name 'secret.txt*' -exec rm -f {} \;
find /tmp -type f -name 'secret.*' -exec rm -f {} \;
find /tmp -type f -name 'secrets*' -exec rm -f {} \;
# Sanity check to ensure no temporary secret files remain
ls -l /tmp | grep 'secret'

Paranoid Cleanup

This uses the shred command to overwrite the files before deletion, which is more secure than simply deleting them. This is especially important if you are using a traditional spinning hard drive, as it makes it much harder to recover the deleted data.

# Overwrite and remove the original (or new) plaintext secret file
shred -u /tmp/secret.txt
# Overwrite and remove the compressed secret file(s) (if used)
shred -u /tmp/secret.txt.gz
shred -u /tmp/secret.txt.xz
# Check for any other temporary files with similar names and shred them as needed
find /tmp -type f -name 'secret.txt*' -exec shred -u {}
find /tmp -type f -name 'secret.*' -exec shred -u {}
find /tmp -type f -name 'secrets*' -exec shred -u {}
# Sanity check to ensure no temporary secret files remain
ls -l /tmp | grep 'secret'

Conclusion

Now you should have a fairly good idea how to use a Yubikey or RP2350 device to securely store notes/secrets in the PIV application. Remember to always keep your secrets small and concise, and to securely delete any temporary files after use.