docs: edits to page covering max PIV cert sizes by equijano21 · Pull Request #356 · Yubico/Yubico.NET.SDK

equijano21 · 2025-12-01T19:49:42Z

Description

Removed inaccurate statements about typical PIV cert sizes, reworked/streamlined chapter.

Addresses RFE-3560.

How has this been tested?

Local docs build.

JMarkstrom · 2025-12-02T07:36:59Z

docs/users-manual/application-piv/cert-size.md

-|       5.x FIPS        |              about 49,890              |   24 certs at 2079 bytes    |       16 certs at 3052 bytes        |
-
-Note that that total amount of storage on a YubiKey (for certs, for PUT DATA objects,
+Note that that total amount of storage on a YubiKey (for certs, PUT DATA objects,


The (original) text is confusing. The PIV applet storage is 50K (AFAIK), with about 1K(?) occupied by from the factory by the PIV attestation objects. This means available theoretical space is 49K unless the user deletes the attestation cert. Further, the statement: " there will be very little space left for anything else." suggests that there's something else the audience should put on the applet besides certificates. Very strange...

I would move this (shortened) to the opening paragraph. Actual storage should be verified by fw team.

The Yubikey PIV applet can store up to 24 certificates with corresponding private keys. In practice the number of certificates and keys that can be stored is determined by choice of algorithm and key length (e.g. RSA 1024 vs RSA 4096), certificate complexity (e.g. use of OIDs, size attributes), the presence of PIV attestation objects etcetera.

Note: the total storage capacity of the YubiKey PIV applet is X with Y being occupied by the PIV attestation objects.

Added note about cert sizes in practice: d3bd2ae

Additional updates regarding total storage space: 38c5d2b

JMarkstrom · 2025-12-02T07:40:53Z

docs/users-manual/application-piv/cert-size.md

-to store up to 24 certs.
+there will be very little space left for anything else.
+
+|    YubiKey Version    | Maximum Total Cert<br/>Space Available | Maximum Average<br/>Cert Size | Number of Certs<br/>at Maximum Size |


Instead of "YubiKey Version", write: "Firmware"
Instead of "Number of Certs", write: "Number of certificates*"

Add "*" at table footer with text:

"*The approximate number of certificates with corresponding private keys"

Spelled out "certificates" across tables and other page text: 56e0ec2

Wrote out model and firmware in tables, rearranged as necessary: 485ca63

(model is important because there are differences in total size available between fips and standard keys)

JMarkstrom · 2025-12-02T07:40:58Z

docs/users-manual/application-piv/cert-size.md

+Although YubiKeys with firmware version 4.x and higher will allow 3052-byte certificates, they will not be able to store 24 certificates of that size due to the key's total certificate space limit. Even if a YubiKey has empty certificate slots available, you cannot fill them once the maximum certificate space has been reached.  

-A NEO (pre-4.0), only has four slots, and will be able to hold four certs of the maximum
+However, a YubiKey NEO, which only has four slots, will be able to hold four certs of the maximum


NEO is long dead. No need to confuse the audience with it (IMHO).

I'm really hesitant to remove product information like this. If we want to start scrubbing any mention of NEO keys from the docs, I'd like to get eng and product consensus on it first.

OK, up to you. I would at least spell out "YubiKey NEO" then, and "certificates" instead of "certs" (feels too colloquial to me).

Updated product names in both tables: de90d2d

JMarkstrom · 2025-12-02T07:40:59Z

docs/users-manual/application-piv/cert-size.md


-Although a YubiKey 5.x will allow a 3052-byte cert in one of the slots, it will not be
-able to store 24 certs that big.
+Although YubiKeys with firmware version 4.x and higher will allow 3052-byte certificates, they will not be able to store 24 certificates of that size due to the key's total certificate space limit. Even if a YubiKey has empty certificate slots available, you cannot fill them once the maximum certificate space has been reached.  


Skip 4.x mention. I don't know if we should fixate on "3052" like this. The paragraph also seems redundant considering the previous statements.

I think the diff might be confusing—here's what the HTML output looks like:

What do you mean by "fixate on 3052"? This page just covers max cert size and total cert space available, so the 3052 max byte size is kind of a critical piece of info, especially given the contents of the second table.

Ok, I realize this is scope creep, but for starters the summary is longer than the article. That does not make any sense. In fact the article is Soo short that it does not need any summary (I would remove it). Now, if you read the summary only then '3052' is a totally out of the blue number. You have to carefully read the table to make sense of the summary, and that is NOT a good approach to a summary. If you really want to keep the summary then I would suggest you put '3052' in some kind of context, e.g. referring to it there as the maximum size of an importable object.

JMarkstrom · 2025-12-02T07:41:01Z

docs/users-manual/application-piv/cert-size.md


 ## Maximum size for a single certificate

+If you attempt to load a certificate that is larger than the key's maximum allowable certificate size (as indicated in the table below), the YubiKey will reject it, and the SDK will throw an exception.


I don't think this is a correct statement. If you want to keep it, I would use "YubiKey's" instead of "key's" (otherwise its confusing since we are talking about certificates and private, public keys). Does this table indicate certificate maximum size or is it "private key + certificate" combined maximum size?

I don't know about the table data—I wasn't the original writer of this page. I can verify the information with the firmware team if you're not sure it's correct.

Also, this statement was already in the docs, I just relocated it and reworked the sentence a bit.

Wrote out "YubiKey" where necessary: fefe4c0

Confirmed with the firmware team that the table data is correct.

JMarkstrom · 2025-12-02T07:41:01Z

docs/users-manual/application-piv/cert-size.md

-
-Nonetheless, these are the space limitations for certs in the PIV application on the
-YubiKey.
+It is possible to store up to 24 private key/certificate pairs in the PIV slots for YubiKeys with firmware version 4.x and higher. However, there are limits to the size of each certificate and the total space available for all certificates.


I would skip any mention of YK fw. 4 (it was released in 2015 and we cannot reasonably expect customers to enroll certificates on YK 4 ten years later, right?). Maybe something along the lines of:

The Yubikey PIV applet can store up to 24 certificates with corresponding private keys. In practice the number of certificates and keys that can be stored is determined by choice of algorithm and key length (e.g. RSA 1024 vs RSA 4096), certificate complexity (e.g. use of OIDs, size attributes), the presence of PIV attestation objects etcetera.

I don't see a reason to remove mention of the firmware version—all we're saying here is that X is true for YubiKeys with firmware Y and above. That doesn't read to me as something that would confuse a developer with 5.x keys.

equijano21 · 2025-12-02T22:54:02Z

@JMarkstrom I made a couple other changes after discussing these docs with the firmware team: 38c5d2b

The PR is now ready for another review.

JMarkstrom

Added some comments. Consider them or ignore them as you see fit.

equijano21 · 2025-12-11T19:20:32Z

Thanks for all the feedback, @JMarkstrom! Final changes have been applied. @DennisDyallo the PR is now ready for your review and sign-off.

removed statements about typical cert sizes, reworked chapter

0a8eec5

equijano21 requested a review from DennisDyallo December 1, 2025 19:49

JMarkstrom reviewed Dec 2, 2025

View reviewed changes

equijano21 added 5 commits December 2, 2025 10:17

spelled out certificates

56e0ec2

wrote out model and firmware in tables

485ca63

added note about cert sizes in practice

d3bd2ae

wrote out YubiKey

fefe4c0

added info from discussion with firmware team

38c5d2b

equijano21 requested a review from JMarkstrom December 2, 2025 22:54

additional info and edits from FW discussion

a064b5c

JMarkstrom reviewed Dec 11, 2025

View reviewed changes

equijano21 and others added 2 commits December 11, 2025 11:16

updated product names, header in tables

de90d2d

Merge branch 'develop' into docs-rfe-3560

0ddc124

DennisDyallo requested a review from JMarkstrom January 7, 2026 09:41

DennisDyallo approved these changes Jan 7, 2026

View reviewed changes

equijano21 merged commit 73dd477 into develop Jan 7, 2026
4 checks passed

equijano21 deleted the docs-rfe-3560 branch January 7, 2026 17:31

DennisDyallo mentioned this pull request Jan 28, 2026

Release/1.15.1 #403

Merged


		## Maximum size for a single certificate

		If you attempt to load a certificate that is larger than the key's maximum allowable certificate size (as indicated in the table below), the YubiKey will reject it, and the SDK will throw an exception.

Conversation

equijano21 commented Dec 1, 2025

Description

How has this been tested?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

equijano21 Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

equijano21 commented Dec 2, 2025

Uh oh!

JMarkstrom left a comment

Choose a reason for hiding this comment

Uh oh!

equijano21 commented Dec 11, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

equijano21 Dec 2, 2025 •

edited

Loading