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

Overview

Existing CA instances using SSNv1 can be migrated to SSNv2 using the pki-server ca-id-generator-update command. The command will take the generator type to update and the new generator name, then update the information in CS.cfg and in DS for the new generator.

For the request the changes will be limited only to the generator name CS.cfg because the values are already correct.

For the cert the command will perform 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

  • dbs.serialLowWaterMark

• Update the generator name in dbs.cert.id.generator to legacy2.

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

Migration Process

First, stop all CA instances in the system. In the latest PKI version it can be done with the following command:

# pki-server stop --wait

At this point it’s highly recommended to create a backup of all servers in case there’s a problem with the migration.

Next, be sure to install the latest PKI packages that supports SSNv2:

# dnf update dogtag-pki

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

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

Once all CA instances have been updated, restart all CA instances in the system. In the latest PKI version it can be done with the following command:

# pki-server start --wait