Sequential Serial Numbers v1 - dogtagpki/pki GitHub Wiki
The Sequential Serial Numbers v1 (SSNv1) is a mechanism to generate unique IDs across the system using distributed ranges. This mechanism is used to generate certificate serial numbers, request IDs, and key IDs in older PKI versions. PKI 11.5 uses Random Serial Numbers v3 by default, but the SSNv1 is still available as an option.
For each subsystem:
-
Current serial number management is based on assigning ranges of sequential serial numbers.
-
Subsystem is requesting new range when crossing below defined thresholds.
-
Subsystem stores information about newly acquired range once it is assigned to the subsystem.
-
Subsystem continues using old range till all numbers are exhausted from it and then it moves to the new range.
-
Cloned subsystems are synchronizing range assignment through replication conflicts
For new clones:
-
Part of the current range of the subsystem is transferred to new clone in the process of cloning.
-
New clone may request new range if transferred range is below defined threshold.
See also Random Serial Numbers v1.
For request IDs, the current range is stored in the following parameters in CS.cg:
-
dbs.beginRequestNumber=<decimal> -
dbs.endRequestNumber=<decimal> -
dbs.requestCloneTransferNumber=<decimal> -
dbs.requestIncrement=<decimal> -
dbs.requestLowWaterMark=<decimal>
For certificate serial numbers, the current range is stored in the following parameters in CS.cg:
-
dbs.beginSerialNumber=<hexadecimal> -
dbs.endSerialNumber=<hexadecimal> -
dbs.serialCloneTransferNumber=<hexadecimal> -
dbs.serialIncrement=<hexadecimal> -
dbs.serialLowWaterMark=<hexadecimal>
Notes:
-
The hexadecimal numbers should be specified without
0xprefix. -
Unlike the installation parameters, the hexadecimal numbers in
CS.cfgcan containAtoF.
For request IDs, the allocated ranges are stored as entries under ou=requests,ou=ranges,dc=ca,dc=pki,dc=example,dc=com, for example:
dn: cn=11,ou=requests,ou=ranges,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 11
endRange: 20
cn: 11
host: pki.example.com
SecurePort: 8443For certificate serial numbers, the allocated ranges are stored as entries under ou=certificateRepository,ou=ranges,dc=ca,dc=pki,dc=example,dc=com.
dn: cn=13,ou=certificateRepository,ou=ranges,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 13
endRange: 30
cn: 13
host: pki.example.com
SecurePort: 8443For request IDs, the next range is stored in the nextRange attribute in ou=ca,ou=requests,dc=ca,dc=pki,dc=example,dc=com as decimal.
For certificate serial numbers, the next range is stored in the nextRange attribute in ou=certificateRepository,ou=ca,dc=ca,dc=pki,dc=example,dc=com as decimal too (not hexadecimal).
For example, suppose a CA is configured with the following range:
-
size: 18 (0x12)
-
increment: 18 (0x12)
-
minimum: 9 (0x9)
The range progression will look like the following:
| Event | Current Range | Current Size | Allocated Range | Allocated Size | Next Range |
|---|---|---|---|---|---|
Initial range |
1 - 18 (0x1 - 0x12) |
18 |
13 (0xd) |
||
Range allocation |
1 - 18 (0x1 - 0x12) |
18 |
13 - 30 (0xd - 0x1e) |
18 |
31 (0x1f) |
Range switch |
19 - 36 (0x13 - 0x24) |
18 |
13 - 30 (0xd - 0x1e) |
18 |
31 (0x1f) |
Range allocation |
19 - 36 (0x13 - 0x24) |
18 |
31 - 48 (0x1f - 0x30) |
18 |
49 (0x31) |
Range switch |
49 - 66 (0x31 - 0x42) |
18 |
31 - 48 (0x1f - 0x30) |
18 |
49 (0x31) |
Hexadecimal numbers in installation parameters (e.g. pki_serial_number_range_start) cannot contain A to F.
This issue have been addressed in Sequential Serial Numbers v2.
The serial numbers issued using SSNv1 are not contiguous. Sometimes there are gaps between the serial numbers.
The first problem is, the initial Next Range is incorrectly set to 13 (0xd) instead of 19 (0x13) causing it to allocate an incorrect range.
This is caused by a bug in pki-server ca-range-update (SubsystemRangeUpdateCLI.java) that parses the dbs.endSerialNumber as a decimal instead of hexadecimal.
The second problem is, the serial number jumps from 36 (0x24) to 49 (0x31). This is caused by a bug in Repository.checkRanges() that parses the Next Range as hexadecimal instead of decimal.
This issue have been addressed in Sequential Serial Numbers v2.
When a CA is cloned, the primary CA will have a replica ID 96 with range 1 - 95 (size: 95). The CA replica will have a replica ID 97 with range 98 - 100 (size: 3). The tertiary CA will have a replica ID 1095 with range 1096 - 1099 (size: 4).
This issue has not been addressed.
In older PKI the CertificateRepository.getLastSerialNumberInRange() relies on VLV to find the last serial number in the range.
Recently PKI the code has been replaced to use Simple Paged Results since VLV has been deprecated and has performance degradation in newer DS.
However, with Simple Paged Results for some operations the code has to retrieve all records in the range which can be expensive if the range is large.
This issue does not exist with Random Serial Numbers v3 since it uses NSS’s secure random generator and does not rely on VLV.
SSNv1 needs to check which serial numbers are already issued in the range before it can issue the next one, and the code is quite complicated, so pruning old certificates from the database is not supported because it’s risky and difficult to test properly.
This issue does not exist with Random Serial Numbers v3 since it can generate a unique serial number regardless of the content of the database.
SSNv1 needs to store the range information in the CS.cfg. This means the server needs to have a write access to the configuration file which can pose a security risk if the server is compromised.
This issue does not exist with Random Serial Numbers v3 since it does not need to read/write the CS.cfg.
Since SSNv1 could update the CS.cfg at anytime, there is a risk of race conditions which might result in data corruption. If the range information is lost or corrupted, it might be difficult to fix due to the Range Gap issue above.
This issue does not exist with Random Serial Numbers v3 since it does not need to read/write the CS.cfg.
When a CA replica is created, it needs to call an existing CA to obtain a subset of the range.
This process is relatively slow and will not work if there are no other CA instance running.
Also, the existing CA will need to update its CS.cfg too which will worsen the reliability issue.
This issue does not exist with Random Serial Numbers v3 since it does not rely on distributed ranges.
SSNv1 is slower to set up since it needs to obtain a subset of the range from another instance so generally the instances are meant to be running all the time, which could bring the cost higher.
This issue does not exist with Random Serial Numbers v3 since the instances do not require communicating with each other so they can be created/destroyed more quickly.