Sequential Serial Numbers v2

Overview

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 basic functionality is mainly described in Random Certificate Serial Numbers v1.

Warning

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

Installation

New instances can be installed with SSNv2 directly.

To install a new instance with 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 install a new instance with 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>

Configuration

For request IDs, the current range are stored in CS.cfg:

• dbs.request.id.generator=legacy2

• dbs.beginRequestNumber=<value>

• dbs.endRequestNumber=<value>

• dbs.requestCloneTransferNumber=<value>

• dbs.requestIncrement=<value>

• dbs.requestLowWaterMark=<value>

For certificate serial numbers, the current range are stored in CS.cfg:

• dbs.cert.id.generator=legacy2

• 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

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

dn: cn=21,ou=requests,ou=ranges,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 21
endRange: 30
cn: 21
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=19,ou=certificateRepository,ou=ranges,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 19
endRange: 36
cn: 19
host: pki.example.com
SecurePort: 8443

dn: cn=37,ou=certificateRepository,ou=ranges,dc=ca,dc=pki,dc=example,dc=com
objectClass: top
objectClass: pkiRange
beginRange: 37
endRange: 54
cn: 37
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)

Migrating from SSNv1

First, stop all servers in the system:

# pki-server stop --wait

Next, install the latest PKI packages:

# dnf update dogtag-pki

To migrate an existing CA from SSNv1 to SSNv2 it is possible to use the pki-server command ca-range-generator-update. The command takes the generator type to update to and the new generator name. So to update cert and request it is possible to run the commands:

# pki-server ca-range-generator-update --type request legacy2
# pki-server ca-range-generator-update --type cert legacy2

Finally, restart all servers in the system:

# pki-server start --wait

The command will update the information in CS.cfg and in DS for the new generator. For the request the change is limited only to the generator name CS.cfg because the values are already correct.

For the cert the command performs the following operations:

• Update the format to hex for the following CS.cfg values: dbs.beginSerialNumber, dbs.endSerialNumber, dbs.nextBeginRequestNumber, dbs.nextEndSerialNumber, dbs.serialCloneTransferNumber, dbs.serialIncrement and dbs.serialLowWaterMark. Update the generator name in dbs.cert.id.generator.

• If no ranges are available in DS (dn from dbs.serialRangeDN, default value is ou=certificateRepository,ou=ranges,<base dn>) update the nextRange to dbs.endSerialNumber + 1 and store in decimal in the dn from dbs.serialDN (default value is ou=certificateRepository, ou=ca, <base dn>

• If ranges have been created, search for last range and if it associated with the updating instance get the endRange value and update nextRange to endRange + 1 in decimal.

• Finally, update all the ranges associated with the instance to decimal.

It is important to update all clones before creating new ranges to avoid number collisions.