Sequential Serial Numbers v1 - dogtagpki/pki GitHub Wiki

Overview

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. Newer PKI versions are using Random Serial Numbers v3 by default, but the SSNv1 is still available as an option.

The way SSNv1 works is mainly described in Random Serial Numbers v1.

Installation

To enable SSNv1 for request IDs, specify the following parameters:

  • pki_request_id_generator=legacy

  • pki_request_number_range_start=<decimal>

  • pki_request_number_range_end=<decimal>

  • pki_request_number_range_increment=<decimal>

  • pki_request_number_range_minimum=<decimal>

  • pki_request_number_range_transfer=<decimal>

To enable SSNv1 for certificate serial numbers, specify the following parameters:

  • pki_cert_id_generator=legacy

  • pki_serial_number_range_start=<hexadecimal>

  • pki_serial_number_range_end=<hexadecimal>

  • pki_serial_number_range_increment=<hexadecimal>

  • pki_serial_number_range_minimum=<hexadecimal>

  • pki_serial_number_range_transfer=<hexadecimal>

Notes:

  • The hexadecimal numbers should be specified without 0x prefix.

  • Due to a bug, the hexadecimal numbers cannot contain A to F.

  • The increment, minimum, and transfer parameters are only available in PKI 10.6 or later.

Current Range

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 0x prefix.

  • Unlike the installation parameters, the hexadecimal numbers in CS.cfg can contain A to F.

Allocated Range

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: 8443

For 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: 8443

Next Range

For 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).

Range Progression

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)

Known Issues

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) whereas it should have been 19 (0x13). 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 numbers 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.

These issues are addressed in Sequential Serial Numbers v2.

Tip
 To find a page in the Wiki, enter the keywords in search field, press Enter, then click Wikis.
⚠️ **GitHub.com Fallback** ⚠️