Sequential Serial Numbers v2

Overview

Warning

This feature is still being developed. Do not use in production.

The Sequential Serial Numbers v2 (SSNv2) works exactly as SSNv1 with serial numbers but it has a different configuration and solves the issues of not contiguous range allocation for the certificate serials.

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

Notes:

• SSNv2 is only supported for requests and certificates in CA.

• SSNv2 is not supported for random serial numbers using dbs.enableRandomSerialNumbers=true. Use Random Serial Numbers v3 instead.

• SSNv2 is not supported for requests and keys in KRA. Use Random Serial Numbers v3 instead.

Installation

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

• pki_request_id_generator=legacy2

• 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 SSNv2 for certificate serial numbers, specify the following parameters:

• pki_cert_id_generator=legacy2

• 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>

Current Range

For request IDs, the current range is stored in the following parameters in CS.cfg:

• dbs.beginRequestNumber=<value>

• dbs.endRequestNumber=<value>

• dbs.requestCloneTransferNumber=<value>

• dbs.requestIncrement=<value>

• dbs.requestLowWaterMark=<value>

For certificate serial numbers, the current range is stored in the following parameters in CS.cfg:

• dbs.beginSerialNumber=<value>

• dbs.endSerialNumber=<value>

• dbs.serialCloneTransferNumber=<value>

• dbs.serialIncrement=<value>

• dbs.serialLowWaterMark=<value>

The parameters are the same as in SSNv1 but the value can be in decimal or hexadecimal with 0x prefix.

Allocated Range

For request IDs, the allocated ranges are stored as entries under ou=requests,ou=ranges_v2,dc=ca,dc=pki,dc=example,dc=com, for example:

dn: cn=11,ou=requests,ou=ranges_v2,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_v2,dc=ca,dc=pki,dc=example,dc=com.

dn: cn=19,ou=certificateRepository,ou=ranges_v2,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 19
endRange: 36
cn: 19
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			19 (0x13)
Range allocation	1 - 18 (0x1 - 0x12)	18	19 - 36 (0x13 - 0x24)	18	37 (0x25)
Range switch	19 - 36 (0x13 - 0x24)	18	19 - 36 (0x13 - 0x24)	18	37 (0x25)
Range allocation	19 - 36 (0x13 - 0x24)	18	37 - 54 (0x25 - 0x36)	18	55 (0x37)
Range switch	37 - 54 (0x25 - 0x36)	18	37 - 54 (0x25 - 0x36)	18	55 (0x37)

Migration

See Migrating to Sequential Serial Numbers v2.