latchset/custodia.ipa

FreeIPA vault plugin for Custodia

custodia.ipa — IPA vault plugin for Custodia

WARNING custodia.ipa is a tech preview with a provisional API.

custodia.ipa is a collection of plugins for Custodia. It provides integration with FreeIPA. The IPAVault plugin is an interface to FreeIPA vault. Secrets are encrypted and stored in Dogtag's Key Recovery Agent. The IPACertRequest plugin creates private key and signed certificates on-demand. Finally the IPAInterface plugin is a helper plugin that wraps ipalib and GSSAPI authentication.

Requirements

Installation

• pip
• setuptools >= 18.0

Runtime

• custodia >= 0.5.0
• ipalib >= 4.5.0
• ipaclient >= 4.5.0
• Python 2.7 (Python 3 support in IPA vault is unstable.)

custodia.ipa requires an IPA-enrolled host and a Kerberos TGT for authentication. It is recommended to provide credentials with a keytab file or GSS-Proxy. Furthermore IPAVault depends on Key Recovery Agent service (ipa-kra-install).

Testing and development

• wheel
• tox

virtualenv requirements

custodia.ipa depends on several binary extensions and shared libraries for e.g. python-cryptography, python-gssapi, python-ldap, and python-nss. For installation in a virtual environment, a C compiler and several development packages are required.

$ virtualenv venv
$ venv/bin/pip install --upgrade custodia.ipa

Fedora

$ sudo dnf install python2 python-pip python-virtualenv python-devel \
    gcc redhat-rpm-config krb5-workstation krb5-devel libffi-devel \
    nss-devel openldap-devel cyrus-sasl-devel openssl-devel

Debian / Ubuntu

$ sudo apt-get update
$ sudo apt-get install -y python2.7 python-pip python-virtualenv python-dev \
    gcc krb5-user libkrb5-dev libffi-dev libnss3-dev libldap2-dev \
    libsasl2-dev libssl-dev

---

Example configuration

Create directories

$ sudo mkdir /etc/custodia /var/lib/custodia /var/log/custodia /var/run/custodia
$ sudo chown USER:GROUP /var/lib/custodia /var/log/custodia /var/run/custodia
$ sudo chmod 750 /var/lib/custodia /var/log/custodia

Create service account and keytab

$ kinit admin
$ ipa service-add custodia/$HOSTNAME
$ ipa service-allow-create-keytab custodia/$HOSTNAME --users=admin
$ mkdir -p /etc/custodia
$ ipa-getkeytab -p custodia/$HOSTNAME -k /etc/custodia/ipa.keytab
$ chown custodia:custodia /etc/custodia/ipa.keytab

The IPA cert request plugin needs additional permissions

$ ipa privilege-add \
    --desc="Create and request service certs with Custodia" \
    "Custodia Service Certs"
$ ipa privilege-add-permission \
    --permissions="Retrieve Certificates from the CA" \
    --permissions="Request Certificate" \
    --permissions="Revoke Certificate" \
    --permissions="System: Modify Services" \
    "Custodia Service Certs"
# for add_principal=True
$ ipa privilege-add-permission \
    --permissions="System: Add Services" \
    "Custodia Service Certs"
$ ipa role-add \
    --desc="Create and request service certs with Custodia" \
    "Custodia Service Cert Adminstrator"
$ ipa role-add-privilege \
    --privileges="Custodia Service Certs" \
    "Custodia Service Cert Adminstrator"
$ ipa role-add-member \
    --services="custodia/$HOSTNAME" \
    "Custodia Service Cert Adminstrator"

Create /etc/custodia/ipa.conf

# /etc/custodia/ipa.conf

[global]
debug = true
makedirs = true

[auth:ipa]
handler = IPAInterface
keytab = ${configdir}/${instance}.keytab
ccache = FILE:${rundir}/ccache

[auth:creds]
handler = SimpleCredsAuth
uid = root
gid = root

[authz:paths]
handler = SimplePathAuthz
paths = /. /secrets

[store:vault]
handler = IPAVault

[store:cert]
handler = IPACertRequest
backing_store = vault

[/]
handler = Root

[/secrets]
handler = Secrets
store = vault

[/secrets/certs]
handler = Secrets
store = cert

Run Custodia server

$ systemctl start [email protected]

IPA cert request

The IPACertRequest store plugin generates or revokes certificates on the fly. It uses a backing store to cache certs and private keys. The plugin can create service principal automatically. However the host must already exist. The IPACertRequest does not create host entries on demand.

A request like GET /path/to/store/HTTP/client1.ipa.example generates a private key and CSR for the service HTTP/client1.ipa.example with DNS subject alternative name client1.ipa.example. The CSR is then forwarded to IPA and signed by Dogtag. The resulting cert and its trust chain is returned together with the private key as a PEM bundle.

$ export CUSTODIA_INSTANCE=ipa
$ custodia-cli get /certs/HTTP/client1.ipa.example
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
Subject: organizationName=IPA.EXAMPLE, commonName=client1.ipa.example
Serial Number: 22
Validity:
    Not Before: 2017-04-27 09:44:20
    Not After: 2019-04-28 09:44:20
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
Issuer: organizationName=IPA.EXAMPLE, commonName=Certificate Authority
Serial Number: 1
Validity:
    Not Before: 2017-04-26 08:24:11
    Not After: 2037-04-26 08:24:11
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

A DELETE request removes the cert/key pair from the backing store and revokes the cert at the same time.

Automatical renewal of revoked or expired certificates is not implemented yet.

FreeIPA 4.4 support

The default settings and permissions are tuned for FreeIPA >= 4.5. For 4.4, the plugin must be configured with chain=False. The additional permission Request Certificate with SubjectAltName is required, too.

ipa privilege-add-permission \
    --permissions="Request Certificate with SubjectAltName" \
    "Custodia Service Certs"

custodia.ipa's Issues

Optimize list()

The list() operation simply grabs a list of all available vaults from the server. That doesn't scale well. Find a way to optimize it.

Plugin raises CCacheError error when TGT has expired

It looks like GSSAPI does not auto-refresh a TGT with client keytab when the TGT is expired:

2017-04-13 13:38:12 - custodia                         - Custodia debug logger enabled
2017-04-13 13:38:12 - custodia                         - Custodia audit log: /tmp/audit.log
2017-04-13 13:38:12 - custodia                         - Config file <closed file 'custodia.conf', mode 'r' at 0x7f025fc29660> loaded
2017-04-13 13:38:13 - IPAInterface-[auth:ipa]          - Unable to get principal from GSSAPI. Are you missing a TGT or valid Kerberos keytab?
Traceback (most recent call last):
  File "/tmp/venv/bin/custodia", line 11, in <module>
    sys.exit(main())
  File "/tmp/venv/lib/python2.7/site-packages/custodia/server/__init__.py", line 211, in main
    _load_plugins(config, cfgparser)
  File "/tmp/venv/lib/python2.7/site-packages/custodia/server/__init__.py", line 191, in _load_plugins
    raise RuntimeError(menu, name, e)
RuntimeError: ('authenticators', 'ipa', CCacheError(u'Major (720896): The referenced credential has expired, Minor (100001): Success',))

$ klist
Ticket cache: FILE:/tmp/ccache
Default principal: custodia/[email protected]

Valid starting       Expires              Service principal
2017-04-12 13:07:18  2017-04-13 13:07:18  krbtgt/[email protected]
2017-04-12 13:07:39  2017-04-13 13:07:18  HTTP/[email protected]

Retrieve and cache KRA transport cert

With https://pagure.io/freeipa/issue/6652 and https://pagure.io/freeipa/issue/6787 FreeIPA 4.6 and 4.5 + patch will be able to properly cache the KRA transport cert. custodia.ipa should retrieve the KRA transport cert in the master process by calling vaultconfig_show command. The command always overrides the KRA transport cert on disk.

Path to cache is currently hard-coded.

Map `ACIError: Insufficient access` to 404

When principal has no permission to set or get an entry, FreeIPA fails with an exception like

ACIError: Insufficient access: Insufficient 'add' privilege to add the entry 'cn=keys__secrets__test10,cn=custodia/[email protected],cn=services,cn=vaults,cn=kra,dc=ipa,dc=example'

custodia.ipa should map the exception to HTTP 404 error.

Potential race condition in cert request

The cert request and caching code is subject to a potential race condition. There is no locking in place that prevents issuing of multiple certs for the same service. In case a replication controller schedules multiple instances of a pod on multiple nodes at the same time, IPACertRequest may request multiple certificates in parallel.

Check validity of cached cert

IPACertRequest.get does not validate if a cached cert is still valid. It should perform at least two tests:

• check the status of the certificate in IPA. The cert may have been revoked by an admin through web interface of ipa tool.
• check expiration date is below a configurable threshold, e.g. still usable for 30 days.

Document that IPAVault needs KRA

KRA needs to be configured with ipa-kra-install. I'm not sure if KRA needs to be available on all CA replicas or if FreeIPA finds any available KRA in the cluster by itself.

Look for a proper way to handle NSS_STRICT_NOFORK

https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/Reference/NSS_environment_variables

It is an error to try to use a PKCS#11 crypto module in a process before it has been initialized in that process, even if the module was initialized in the parent process. Beginning in NSS 3.12.3, Softoken will detect this error. This environment variable controls Softoken's response to that error.

    If set to to "1" or unset, Softoken will trigger an assertion failure in debug builds, and will report an error in non-DEBUG builds.
    If set  to "DISABLED", Softoken will ignore forks, and behave as it did in older versions.
    If set to any other non-empty value, Softoken will report an error in both DEBUG and non-DEBUG builds.

Perhaps python-nss has a way to init the crypto module again?

Don't log to file

By default, ipalib creates a file handler and writes all log messages to ~/.ipa/log/default.log (or whatever the context is). The log file is not auto-rotated or shrinked. File logging can be disable with bootstrap(log=None).