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 way SSNv2 works is mainly described in Random 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

Warning

The migration process must be done in parallel for all CA instances. Complete each migration step for all CA instances before proceeding to the next step.

Step 1: Stop all CA instances in the system. In the latest PKI version it can be done with the following command:

# pki-server stop --wait

Warning

At this point it’s highly recommended to back up all CA and DS instances in case it’s necessary to rollback the migration.

Step 2: Once all CA instances are stopped, update all CA instances to have the latest PKI packages that supports SSNv2:

# dnf update dogtag-pki

Step 3: Once all CA instances have the latest PKI packages, switch to SSNv2 with the following commands:

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

Step 4: Once all CA instances have switched to SSNv2, restart all CA instances in the system. In the latest PKI version it can be done with the following command:

# pki-server start --wait