======================
Pulp 2.3 Release Notes
======================

Pulp 2.3.0
==========

CVE-2013-7450
-------------

Versions of Pulp < 2.3.0 distributed the same certificate authority key and
certificate to all Pulp users[0]. This CA is used by the /login API call
(pulp-admin login uses this call) to generate and sign a client certificate.
This client certificate is then used for subsequent API calls.

Due to this vulnerability, remote attackers are able to obtain the CA key
from the Pulp git repository and use it to generate valid client certificates
for any Pulp installations that use the default CA. The Pulp documentation
did not emphasize the importance of replacing this CA for production
deployments, so there may be users who use this common CA key in production
environments.

Users are urged to replace the CA certificate and key on any Pulp
installations that began their life with a version less than 2.3.0. Upgrading
alone is not sufficient, as Pulp upgrades do not replace existing CA key
pairs. Versions of Pulp >= 2.3.0 do ship a utility (pulp-gen-ca-certificate)
that is capable of generating a new CA keypair for you, but it should be
noted that there are some known local attacks that this script is vulnerable
to as well[1][2]. The best option is to generate your own CA certificate if
you are concerned about these local attacks.

Thanks to Sander Bos for notifying the Pulp team that we had neglected to
acquire a CVE for this vulnerability at the time of its discovery.

[0] CVE-2013-7450: https://bugzilla.redhat.com/show_bug.cgi?id=1003326
[1] CVE-2016-3095 (fixed in Pulp >= 2.8.2): http://www.openwall.com/lists/oss-security/2016/04/06/3
[2] CVE-2016-3106 (fixed in Pulp >= 2.8.3): https://pulp.plan.io/issues/1827


New Features
------------

-  Repository sync and publish history is now available. See
   ``pulp-admin repo history --help`` for details, or see the developer guide
   for how to retrieve these via the REST API.

-  Qpid SSL Certificates generated by the pulp-qpid-ssl-cfg script are no longer world readable.  It is
   recommended that existing installations are updated manually.  If the default locations were used the
   following changes would be be needed.

   -  chmod 640 /etc/pki/pulp/qpid/\*.crt
   -  chgrp apache /etc/pki/pulp/qpid/\*.crt
   -  chmod 640 /etc/pki/pulp/qpid/nss/*
   -  chgrp qpidd /etc/pki/pulp/qpid/nss/*

-  OAuth authentication is enabled by default using generated credentials.

-  The out-of-the-box CA (Certificate Authority) used by Pulp to sign and validate user login is generated
   during installation. Previously, the SSL private key and certificate were installed from the
   git repository. This means that each installation initially had the same key and certificate
   installed, although any production deployments should have been configured to use a custom CA.
   In 2.3, the CA key stored at ``/etc/pki/pulp/ca.key`` and certificate stored
   at ``/etc/pki/pulp/ca.crt`` will be uniquely generated for each install. The key and certificate
   are **not** updated during RPM upgrade. Users upgrading to 2.3 who chose not to
   deploy their own CA are encouraged to generate a new (unique) CA key and certificate
   by running: `pulp-gen-ca-certificate` as root. Then, restart httpd. pulp-admin
   users will need to login again.

.. note:: It is strongly recommended that Pulp deployments use custom CA certificates.

New Node Features
-----------------

-  Users can now limit the bandwidth and number of connections used during a sync.

-  The authentication method used by *Nodes* has been changed to OAuth. Users upgrading Pulp
   servers that are functioning as child *Nodes* will need to update a new *Nodes* configuration
   file as specified in :doc:`../nodes` section of this user guide.

Bugs
----

You can see the complete list of over 100 bugs that were
`fixed in Pulp 2.3.0 <https://bugzilla.redhat.com/buglist.cgi?bug_status=VERIFIED&classification=Community&list_id=1927252&product=Pulp&query_format=advanced&target_release=2.3.0>`_.

REST API Changes
----------------

-  The consumer applicability API is vastly different and performs much faster.
   Please see the developer guide for details on the new API.

Internal API Changes
--------------------

-  Importers no longer pass the related repositories to the validate_config(...) method.

-  Distributors now pass a pulp.plugins.conduits.repo_config.RepoConfigConduit instead of the related
   repositories to the validate_config(...) method.  The RepoConfigConduit is used to provide
   methods for performing the kind of cross repository searching & validation that formerly had to be done
   manually by comparing the configuration of each related repository.

Upgrade Instructions for 2.2.x --> 2.3.0
----------------------------------------

To upgrade to the new Pulp release from version 2.2.x, you should begin by using yum to install the latest RPMs
from the Pulp repository and run the database migrations::

   $ sudo yum upgrade
   $ sudo pulp-manage-db

To address CVE-2013-7450, you will need to replace your CA certificate and key. As mentioned above,
there are some known CVE's that the new ``pulp-gen-ca-certificate`` is vulnerable to. Thus, the
recommended upgrade strategy is to generate a new CA certificate and key yourself, unless you
upgrade all the way to Pulp 2.8.3 where CVE-2016-3095 and CVE-2016-3106 have been fixed. If you are
not concerned about these local attacks, you can use ``pulp-gen-ca-certificate`` to regenerate the
CA with the risk of a local user being able to read the private key. If you wish to use the script::

    $ sudo pulp-gen-ca-certificate
    # pulp-gen-ca-certificate in 2.3.0 does not install the files with the correct SELinux context
    $ sudo restorecon -R /etc/pki/pulp


Pulp 2.3.1
==========

Bugs Fixed
----------

The ``pulp-qpid-ssl-cfg`` tool
`displayed an incorrect path <https://bugzilla.redhat.com/show_bug.cgi?id=1039619>`_ to the qpid
configuration file.
