freeipa/doc/designs/random-serial-numbers.md

Random Serial Numbers v3 (RSNv3)

Overview

Previously PKI used range-based serial numbers in order to ensure uniqueness across multiple clones. Based on their experience they determined that this would not fit well into cloud environments with short-lived certificates.

The new version 3 implementation of serial numbers uses a 128-bit random value for the serial number which they compute collisions will be mathematically small.

See https://github.com/dogtagpki/pki/wiki/Random-Certificate-Serial-Numbers-v3 for more details.

Given the known issues reported this will be supported in IPA for new installations only.

Use Cases

RSNv3 will be supported only for new installations. If enabled it is required to use RSNv3 on all PKI services including the CA and KRA in the deployment.

The PKI team currently discourages mixing ranged and random serial numbers and in practice creating a ranged clone from a RSNv3 server will fail. At some point in the future it may be possible to write a tool to flip values in an existing deployment to enable RSNv3 on existing servers prior to creating new replicas but it will be complex and require significant testing. Currently interoperability between ranged and RSNv3 is not a good experience.

How to Use

Instructions for installing a CA: https://github.com/dogtagpki/pki/blob/master/docs/installation/ca/Installing-CA-with-Random-Serial-Numbers-v3.adoc

Instructions for installing a KRA: https://github.com/dogtagpki/pki/blob/master/docs/installation/kra/Installig-KRA-with-Random-Serial-Numbers-v3.adoc

A new option was added for ipa-server-install and ipa-ca-install to --random-serial-numbers to enable RSNv3. This sets the configuration values as described in the documentation above.

Design

SerialNumber class

The first limitation within IPA related to RSNv3 is the size of the serial numbers which can be up to 40-digit decimal values. This far exceeds the limits of XML-RPC and JSON integer values.

There has never been a reason to treat serial numbers as integers and the original CA implementation transmitted them as strings. A new class will be needed to handle the huge integers as strings with some basic validation.

The validation will include:

• Minimum length of 1, no empty serial numbers
• Maximum length of 40 (2^^128)
• No negative values
• Greater than 0
• If prefixed with 0x a valid hex value

The only "math" we do on serial numbers is conversion to and from hex. Python internally can handle these huge numbers, it is only in the transmission that there is a problem.

Determining RSN version

There are two possible methods to handle the introduction of random serial numbers:

Implement as a Domain Level 2

There are existing checks which will limit interoperability that may be extended as needed. This was not chosen because with RSNv3 it is an all or nothing affair according to the PKI documentation. All existing servers would need to be moved at once, not something easily enforceable or doable in large installations.

Store the RSN version as a value in LDAP

Instead store the version number in LDAP which is easily searchable and a common practice in IPA. A non-existent value will be treated as 0 and therefore no RSN capability. This will allow for expansion into future RSN versions. Current CA ACLs can be extended to allow read/write to this for admin users.

KRA impact

The PKI team strongly encouraged that if RSNv3 is enabled anywhere then it should be enabled everywhere. This includes request and key IDs and a KRA. A check will be done on KRA installation to automatically enable RSNv3 if it is enabled on the underlying CA.

Implementation

The RSN version will be stored in the IPA CA entry which will exist on any IPA server with a CA.

The new attribute is named ipaCaRandomSerialNumberVersion and consists of:

attributeTypes: (2.16.840.1.113730.3.8.21.1.9 NAME 'ipaCaRandomSerialNumberVersion' DESC 'Random Serial Number Version' EQUALITY integerMatch ORDERING integerOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE X-ORIGIN 'IPA v4.9 RSNv3' )

This attribute is not yet merged into IANA pending design approval.

It will be added as MAY to ipaCa objectclass.

A sample entry looks like:

dn: cn=ipa,cn=cas,cn=ca,dc=example,dc=test
objectClass: top
objectClass: ipaca
cn: ipa
description: IPA CA
ipaCaId: <UUID>
ipaCaIssuerDN: CN=Certificate Authority,O=EXAMPLE.TEST
ipaCaSubjectDN: CN=Certificate Authority,O=EXAMPLE.TEST
ipaCaRandomSerialNumberVersion: 3

During replica install or ipa-ca-install a check will be made to determine if RSN is > 0 to determine whether it is allowed or not.

No special effort is needed to include externally signed IPA certificates.

CAless installations are unaffected. Promotion from CAless can include RSN and be held to the same standards as a new installation.

Unfortunately the PKI server provides no mechanism to determine whether the RSNv3 capability exists in the server so a straight version number check is required. It is only available in 11.2.0+.

Feature Management

UI

N/A

CLI

A new option, --random-serial-numbers, is added to ipa-server-install and ipa-ca-install. If --setup-ca is provided to ipa-replica-install then RSN is determined automatically based on the capability of the remote CA.

Configuration

N/A

Upgrade

Not currently allowed. While theoretically possible to write a tool to enable it doing so is complex and prone to user error which could result in a non-functioning installation.

Test plan

A RSNv3 installation varies only from a ranged installation in its CA/KRA configuration. Existing CA tests can be extended to pass the --random-serial-numbers option and from a user perspective, beyond getting certificates with potentially huge serial numbers, there is no difference.

A selected set of existing tests will be subclassed to add the RSNv3 installation option, including CA-less to CA-full installations.

Typically "is the CA ok" tests which do "ipa cert-show 1" can still work to show that communication is working (e.g. Not Found is a fine answer), existing tests will be extended to use the IPA CA serial number so we get a positive answer back.

During development the entire test suite was successfully executed with RSNv3 enabled. Doing so even on a nightly basis is an extremely heavy-weight option.

Troubleshooting and debugging

Given this supports new installations only that greatly simplifies the possible conditions.

There are only two conditions which would disallow a server to be installed:

• PKI < 11.2.0
• The LDAP-stored RSNv3 value prevents ipa-ca-install or ipa-replica-install

It is possible that some client tools may not honor huge serial numbers but testing has not borne any out yet.