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.

Limitations:

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

• SSNv2 is not supported for random serial number (dbs.enableRandomSerialNumbers=true). Use Random Serial Numbers v3 instead.

• SSNv2 is not supported for KRA.

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)

Migrating from SSNv1

Overview

Existing PKI 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 requests the command will perform the following operations:

• Update the dbs.request.id.generator to legacy2.

For certs the command will perform the following operations:

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

• Update the following parameters to hexadecimal with 0x prefix:

  • dbs.beginSerialNumber

  • dbs.endSerialNumber

  • dbs.nextBeginRequestNumber

  • dbs.nextEndSerialNumber

  • dbs.serialCloneTransferNumber

  • dbs.serialIncrement

  • dbs.serialLowWaterMark

• If there are no allocated ranges available, update the nextRange to dbs.endSerialNumber + 1 and store it as decimal.

• If there are allocated ranges find the last range, and if the range belongs to the instance being migrated get the endRange value and update the nextRange to endRange + 1 and store it as decimal.

• Finally, update the beginRange and endRange in all ranges belonging to the instance being migrated to decimal.

Migration Process

Warning

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

Step 1: Stop all PKI 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 PKI and DS instances in case it’s necessary to rollback the migration.

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

# dnf update dogtag-pki

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

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

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

# pki-server start --wait

Warning

Verify that everything is working properly. If there is a problem it might be necessary to restore all PKI and DS instances from the backup.