About Certificates and Managing Entitlements

Part of managing subscriptions requires verifying the identity of everything involved, such as the system, the subscription service, and the available products. The subscription service uses X.509 certificates to handle the identity and authentication aspects of the subscription service. These X.509 certificates also contain the actual data about available subscriptions and installed products.

The first time a system is subscribed to a subscription, it downloads a certificate from the subscription service. The entitlement certificate contains all of the information about products that are available through that subscription. The entitlement certificate is revoked and reissued any time there is a change in the subscriptions for an organization. Once a product is actually installed on a machine, then another certificate is issued to manage the entitlements for the product on the system.

Each certificate issued and used by the Subscription Manager services is a .pem formatted file. This file format stores both keys and certificates in a base-64 blob. For example:

Tools like openssl or pk12util can be used to extract and view information from these certificates, in a pretty-print format. The product- and subscription-related information is extracted and viewable in the CentOS Subscription Manager GUI or command-line tools.

This section describes the different certificates used by the subscription service and the entitlement information contained in those certificates. A much more detailed description of X.509 certificates and a public key infrastructure (PKI) is given in the CentOS Certificate System documentation in chapter 1, "Introduction to Public-Key Cryptography," in the CentOS Certificate System Deployment Guide.

Table 14.10. Types of Certificates Used for Content and Entitlements

Certificate Type	Description	Default Location
Consumer Identity Certificate	Used to identify the system (consumer) to the subscription service. This contains a unique ID which is assigned to the system when it is registered to the system. The identity certificate itself is generated by the subscription service when the system is registered and then sent to the consumer.	/etc/pki/consumer
Entitlement Certificate	Contains a list of products that are available to a system to install, based on the subscriptions that the system has been subscribed to. The entitlement certificate defines the software products, the content delivery location, and validity dates. The presence of an entitlement certificate means that the system has consumed one of the quantities from the subscription.	/etc/pki/entitlement
Product Certificate	Contains the information about a product after it has been installed.	/etc/pki/product/`product_serial#`.pem
CA Certificate	A certificate for the certificate authority which issued the SSL server certificate used by the subscription service. This must be installed on a system for the system to use SSl to connect to the subscription service.	/etc/rhsm/ca/candlepin-ca.pem
Satellite Certificate	An XML-formatted certificate which contains a product list. This is used by local Satellite 5.x systems, not the newer subscription service.

The Structure of Identity Certificates

An identity certificate is a standard SSL client certificate. This certificate is issued by the subscription service when the system registers to it. The system consumer subsequently uses this certificate to authenticate to the subscription service whenever it contacts the service after registration.

The certificate contains three important pieces of information:

The consumer UUID, in the subject CN of the certificate

The subscription service which the system is registered to, in the issuer field of the certificate
The user account which registered the system, as the DirName value in the Subject Alt Name

The validity period of this certificate is associated with the time when the system was registered, not to any subscription contract periods or user account settings.

Example 14.13. Identity Certificate

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1430 (0x596)
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=entitlement.server.example.com, C=US, L=Raleigh  
        Validity
            Not Before: Oct  6 16:32:05 2010 GMT
            Not After : Oct  6 23:59:59 2011 GMT
        Subject: CN=4881bd2f-868b-438c-af96-8b1d283daffc  
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:a3:72:2f:0e:be:20:cb:63:63:4d:c5:ec:eb:71:
                    8f:61:8b:19:3c:f9:54:ac:75:91:f5:98:ee:ae:0e:
                    0f:8c:3e:5e:50:47:4e:4b:7e:da:d4:15:f5:2f:b8:
                    4c:59:14:67:b5:e8:23:cd:0b:0c:bf:c1:38:da:72:
                    fe:0a:b9:73:97:30:c8:ab:e3:bf:68:23:49:2f:e9:
                    8a:18:18:35:77:39:cd:43:88:7d:28:f5:bd:bd:df:
                    1c:61:ce:93:37:42:71:93:32:5a:ad:73:d0:df:f3:
                    68:b0:a5:a7:fc:cf:fe:97:0c:a2:0e:0d:4c:08:36:
                    9e:23:4f:8c:56:2f:91:0f:a8:22:5d:7a:5a:64:29:
                    79:f3:34:cb:44:98:ec:de:e8:25:dd:93:f1:d6:63:
                    3a:2b:8b:57:67:15:64:b7:f0:8e:bc:06:f5:4a:64:
                    4f:62:74:de:0f:a7:d5:90:3d:ab:de:62:6c:b0:f9:
                    35:53:9d:4f:2f:7e:da:57:d1:85:d0:d5:89:96:95:
                    a0:58:90:5e:f8:3c:ea:a0:47:43:48:9e:10:db:85:
                    6b:a6:c2:bc:68:29:4f:17:01:b9:55:e6:b2:79:76:
                    fb:d7:67:32:2c:28:0e:a3:d9:a7:51:c1:e8:6d:ae:
                    36:6c:8d:7b:f2:2f:91:33:8f:14:9f:d9:55:bb:41:
                    4d:85
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            Netscape Cert Type:
                SSL Client, S/MIME
            X509v3 Key Usage:
                Digital Signature, Key Encipherment, Data Encipherment
            X509v3 Authority Key Identifier:
                keyid:68:98:D4:DD:94:B6:E9:71:70:C1:72:D2:3E:A0:40:62:D3:CA:8E:82
                DirName:/CN=entitlement.server.example.com/C=US/L=Raleigh
                serial:D6:CE:78:B1:56:9C:37:41
            X509v3 Subject Key Identifier:
                66:C1:E5:FA:8E:CE:1D:F6:83:85:AA:AF:08:5C:FF:DE:88:BA:92:20
            X509v3 Extended Key Usage:
                TLS Web Client Authentication
            X509v3 Subject Alternative Name:  
                DirName:/CN=admin-example  
    Signature Algorithm: sha1WithRSAEncryption
        0d:c4:74:6c:7a:fe:1f:61:f9:c7:3b:d9:18:70:7a:38:51:e2:
        bb:a3:03:7e:7e:af:76:82:5e:fa:89:11:d1:9e:1c:e4:3e:58:
        56:2f:eb:95:da:dc:aa:18:6f:73:24:04:8e:5f:ea:84:0c:ea:
        8d:e6:c5:40:07:88:8d:41:30:c6:89:46:ca:cf:be:7b:8a:00:
        f6:86:c4:38:7b:0b:fd:56:ad:d0:b6:76:a3:5a:77:dd:69:46:
        47:f7:5f:46:81:6b:34:f4:4b:60:ea:e7:2c:2b:08:1f:c7:57:
        ea:8d:24:4b:05:b3:a8:95:9b:af:05:36:11:38:e5:fa:5b:6b:
        ca:5f

The Structure of Entitlement Certificates

An entitlement is analogous to an assigned software license. Entitlement certificates contain a list of available products for a system - software that the system has been granted rights to download and update. When a system is subscribed to a subscription pool, the system pulls down the entitlement certificate from the subscription service, which contains all of the information about available products.

An entitlement certificate contains a list of every potential product from every potential content source. The structure of the entitlement certificate, then, allows multiple namespaces, each, for products, content servers, roles, orders, and systems. An entitlement certificate also contains complete information about the subscribed pool, even for products which may not be compatible with the specific system. In an entitlement certificate, the architecture and version definitions contain all of the allowed architectures and versions.

The local Subscription Manager polls the subscription service routinely (every four hours by default) to check for changes in the entitlements. When a subscription is changed in some way, then the original entitlement certificate is revoked and is replaced with a new entitlement certificate.

The entitlement certificate is a *.pem file stored in the entitlement certificates directory, /etc/pki/entitlement. The name of the *.pem file is a generated numeric identifier that is generated by the subscription service. This ID is an inventory number that is used to associate a subscription quantity with the system in the software inventory.

The heading of the certificate contains the name of the subscription service which issued it, the validity period of the certificate (which is tied to the installation date of the product), and then the serial number of the installation of the product.

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            3c:da:6c:06:90:7f:ff
        Signature Algorithm: sha1WithRSAEncryption
        Issuer: CN=candlepin1.devlab.phx1.redhat.com, C=US, L=Raleigh
        Validity
            Not Before: Oct  8 17:55:28 2010 GMT
            Not After : Oct  2 23:59:59 2011 GMT
        Subject: CN=8a878c912b875189012b8cfbc3f2264a
... [snip] ...

The key definition of the product is given in custom certificate extensions that are appended to the certificate. Each namespace defines certain information about a product, including its name, content servers which can deliver it, the format of delivery, and a GPG key to identify the release. Every individual entry is identified by a numeric object identifier (OID) with the same basic format:

1.3.6.1.4.1.2312.9.2.product_#.config_#:
   ..config_value

The 2 indicates that it is a product entry. product_# is a unique ID which identifies the specific product or variant. config_# relates to the installation information for that product, like its content server or the quantity available.

Every entitlements-related extension begins with the OID base 1.3.6.1.4.1.2312.9. The subsequent numbers identify different subscription areas:

.2. is the product-specific information

.1. is the subscription information

.4. contains the contract information, like its ID number and start and end dates
.5. contains the consumer information, like the consumer ID which installed a product

A product definition contains a series of entries which configure all of the information required to identify and install the product. Each type of information has its own ID, the config_# in the OID, that is used consistently for all products. An example product is listed in Example 14.14, "Annotated Community Enterprise Linux High Availability Product Extensions in an Entitlement Certificate".

Example 14.14. Annotated Community Enterprise Linux High Availability Product Extensions in an Entitlement Certificate

            content repository type  
            1.3.6.1.4.1.2312.9.2.30393.1:
                ..yum
            product  
            1.3.6.1.4.1.2312.9.2.30393.1.1:
                .HCommunity Enterprise Linux High Availability (for RHEL Entitlement) (RPMs)
            channel name  
            1.3.6.1.4.1.2312.9.2.30393.1.2:
                .Dred-hat-enterprise-linux-high-availability-for-rhel-entitlement-rpms
            vendor  
            1.3.6.1.4.1.2312.9.2.30393.1.5:
                ..CentOS
            download URL  
            1.3.6.1.4.1.2312.9.2.30393.1.6:
                .Q/content/dist/rhel/entitlement/releases/$releasever/$basearch/highavailability/os
            key download URL  
            1.3.6.1.4.1.2312.9.2.30393.1.7:
                .2file:///etc/pki/rpm-gpg/RPM-GPG-KEY-redhat-release
            flex quantity  
            1.3.6.1.4.1.2312.9.2.30393.1.4:
                ..0
            quantity  
            1.3.6.1.4.1.2312.9.2.30393.1.3:
                ..25
            repo enabled setting  
            1.3.6.1.4.1.2312.9.2.30393.1.8:
                ..1

The Structure of Product Certificates

The products that are installed on a system through the subscriptions assigned to a system are identified by X.509 certificates. When an available product is installed, the subscription service generates a product certificate, which contains the information about the product contract and the specific installation.

Structurally, entitlement certificates and product certificates are very similar, because they both provide much of the same information about products. The main difference is that a product certificate contains information about a single product that has been installed, so no other subscription information (like other available products or other product versions) is included in a product certificate the way that it is in an entitlement certificate.

A product certificate contains a single product namespace (meaning, a single product definition) which shows only what is actually installed on the system. The architecture and version definitions in a product certificate reflect the architecture and version of the product that is actually installed.

The product certificate is a *.pem file stored in the entitlement certificates directory, /etc/pki/product/product_serial#.pem. The name of the *.pem file is a generated numeric identifier that is generated by the subscription service. As with entitlement tracking, the generated ID is an inventory number, used to track installed products and associate them with systems within the subscription service.

Anatomy of Satellite Certificates

Satellite certificates are used by Satellite 5.x deployments. They are not used on Community Enterprise Operating System.7 or by the subscription service.

Every system has to have a secure, authoritative way to identify what subscriptions are available. For Satellite 5.x systems, this identification is done through a digitally-signed XML document that lists the products and quantities that a customer has purchased.

As with entitlement certificates, a Satellite certificate contains the information about the subscription that was purchased, including the total number of systems that can be registered against that subscription and its start and end dates.

There are two types of subscriptions:

System entitlements are subscriptions for services that can be performed, such as monitoring, provisioning, and virtualization.

Channel entitlements, or content entitlements, provide access to the different software product download channels on CentOS Network. These include Community Enterprise Linux add-ons like Supplementary and FastTrack and layered products like CentOS Directory Server.

Both types can be included in a single Satellite certificate.

A system entitlement and the metadata for an entitlement are both configured similarly in the certificate:

<rhn-cert-field name="configuration_area">value</rhn-cert-field>

The name argument identifies what entity is being configured. This can be the organization which ordered the subscription (name="owner"), the start and end dates for the entitlement (name="issued" and name="expires"), or the entitlement itself. A system entitlement uses the name argument to set the service being entitled; every content entitlement is set as a name="channel-family" type, with the specific product identified in an additional family argument.

The first section of the Satellite certificate is the metadata. The metadata identifies the organization which purchased it and the start and end dates of the entitlement. The field being set is in the name argument, while the value is between the tags. The last lines of the certificate also set metadata for the subscription, including the version of the Satellite and the signature that signs the XML document (and allows the XML file to be used as a certificate).

  <rhn-cert-field name="product">RHN-SATELLITE-001</rhn-cert-field>
  <rhn-cert-field name="owner">Example Corp</rhn-cert-field>
  <rhn-cert-field name="issued">2009-04-07 10:18:33</rhn-cert-field>
  <rhn-cert-field name="expires">2009-11-25 00:00:00</rhn-cert-field>
... [snip] ...
  <rhn-cert-field name="satellite-version">5.3</rhn-cert-field>
  <rhn-cert-field name="generation">2</rhn-cert-field>
  <rhn-cert-signature>
-----BEGIN PGP SIGNATURE-----
Version: Crypt::OpenPGP 1.03
iQBGBAARAwAGBQJJ22C+AAoJEJ5ynaAAAAkyyZ0An18+4hK5Ozt4HWieFvahsTnF
aPcaAJ0e5neOfdDZRLOgDE+Tp/Im3Hc3Rg==
=gqP7
-----END PGP SIGNATURE-----
</rhn-cert-signature>

The name="slot" field lists how many total systems are allowed to use this Satellite certificate to receive content. It is a global quantity.

  <rhn-cert-field name="slots">119</rhn-cert-field>

The system entitlements are set by identifying the service type in the name argument and then setting the quantity as the value within the tags.

  <rhn-cert-field name="provisioning-slots">117</rhn-cert-field>
  <rhn-cert-field name="monitoring-slots">20</rhn-cert-field>
  <rhn-cert-field name="virtualization_host">67</rhn-cert-field>

The content entitlements can include any combination of products, including base Community Enterprise Linux subscriptions, variations of Community Enterprise Linux, Community Enterprise Linux add-ons, and general software products. General Community Enterprise Linux server subscriptions are listed in the rhel-server family, while a specific Virtualization Server subscription provides an additional rhel-server-vt family..

  <rhn-cert-field name="channel-families" quantity="95" family="rhel-server"/>
  <rhn-cert-field name="channel-families" quantity="67" family="rhel-server-vt"/>

Add-ons and products for Community Enterprise Linux systems (but not necessarily operating system products) are also in a rhel-* family, because that refers to the platform the product is supported on. In this example, CentOS Directory Server is in the rhel-rhdirserv family.

  <rhn-cert-field name="channel-families" quantity="3" family="rhel-rhdirserv"/>

Most subscriptions will also include a subscription tool set to manage and enable within clients features such as provisioning or configuration management when registered to RHN Classic or Satellite 5.x.

  <rhn-cert-field name="channel-families" quantity="212" family="rhn-tools"/>

After explaining how to configure the network, this part discusses topics related to networking such as how to allow remote logins, share files and directories over the network, and set up a Web server.