Usage¶
The REST API typically requires Basic Authentication. To use the examples in this section, the following assumptions are made:
The httpie command is available to perform the requests.
A
.netrc
file configured with the username, password, and host of your Pulp server. See the httpie .netrc docs for more information on setting that.The jq library is available to easily parse responses.
Pre-Setup¶
To meaningfully use pulp-certguard you should already have a Pulp Distribution that requires
authorization and ideally it should have content in it. These examples assume you have pulp_file installed with a FileRepository
with at least
one RepositoryVersion
with content in it. Also you’ll need a FileDistribution
serving that
RepositoryVersion
. Below are links to instructions on how to create those objects.
The pulp-certguard examples should be straightforward to port to protect another distribution type.
Create a pulp_file repository, and sync some basic content into it¶
This step is about creating some data to test with. The significant thing for pulp-certguard is having a repository to protect and having some content in that repository to test against.
The examples below assume the Distribution href is saved to the bash variable DISTRIBUTION_HREF
for example:
$ echo $DISTRIBUTION_HREF
/pulp/api/v3/distributions/file/file/efc690a5-7e29-4fe5-8c48-9fef7727223f/
X509 CertGuard¶
Create a content guard¶
This example assumes that ~/ca.pem
is a PEM encoded Certificate Authority (CA) certificate. Each
X509 Content Guard needs a name so for this example we’ll use myguard
.
$ http POST http://localhost/pulp/api/v3/contentguards/certguard/x509/ name=myguard ca_certificate=@~/ca.pem
{
"pulp_href": "/pulp/api/v3/contentguards/certguard/x509/2432b932-a057-43ec-ba20-391bd99f943f/",
}
$ export X509_GUARD_HREF=$(http localhost/pulp/api/v3/contentguards/certguard/x509/?name=myguard | jq -r '.results[0].pulp_href')
Protect the Distribution with the X509CertGuard¶
$ http PATCH localhost$DISTRIBUTION_HREF content_guard=${X509_GUARD_HREF}
{
"pulp_href": "/pulp/api/v3/distributions/305adfe0-4851-432f-9de3-13f9b10fe131/"
}
Download protected
content¶
The following example assume the client will connect to the reverse proxy using TLS with the following:
The PEM encoded client certificate is stored at
~/client.pem
which is signed by the CA stored on the X509CertGuard.The corresponding PEM encoded private key at
~/key.pem
.
It attempts to download the test.iso
file from the FileDistribution at the path
/pulp/content/somepath/
Note the somepath
part of this is from the base_url
of the
Distribution you are testing against.
For example with httpie you can submit the client cert and key via TLS using:
$ http --cert ~/client.pem --cert-key ~/key.pem https://localhost/pulp/content/somepath/test.iso
This is expected to yield binary data with a response like:
HTTP/1.1 200 OK
Accept-Ranges: bytes
Connection: keep-alive
Content-Length: 3145728
Content-Type: application/octet-stream
Date: Tue, 21 Apr 2020 20:35:11 GMT
Last-Modified: Tue, 21 Apr 2020 19:23:06 GMT
Server: nginx/1.16.1
+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+
RHSM CertGuard¶
Note
To use the RHSMCertGuard
you have to manually install the rhsm Python module which provides RHSM certificate parsing on the pulp server.
It requires some system level dependencies, e.g. OpenSSL libraries, which are not the same on
all operating operating systems. rhsm
from PyPI not being cross-distro is why this requires
manual installation.
Create a content guard¶
This example assumes that ~/ca.pem
is a PEM encoded Certificate Authority (CA) certificate. Each
RHSM Content Guard needs a name so for this example we’ll use myguard
.
$ http POST http://localhost/pulp/api/v3/contentguards/certguard/rhsm/ name=myguard ca_certificate=@~/ca.pem
{
"pulp_href": "/pulp/api/v3/contentguards/certguard/rhsm/302971d1-48a9-439f-a6a9-052e33f75733/",
}
$ export RHSM_GUARD_HREF=$(http localhost/pulp/api/v3/contentguards/certguard/rhsm/?name=myguard | jq -r '.results[0].pulp_href')
Protect the Distribution with the RHSMCertGuard¶
$ http PATCH localhost$DISTRIBUTION_HREF content_guard=${RHSM_GUARD_HREF}
{
"pulp_href": "/pulp/api/v3/distributions/335ccd96-d8ca-4d07-8c2e-e45eda6b18ba/"
}
Download protected
content¶
The following example assume the client will connect to the reverse proxy using TLS with the following:
The PEM encoded, RHSM client certificate is stored at
~/client.pem
which is signed by the CA stored on the RHSMCertGuard.The corresponding PEM encoded private key at
~/key.pem
.
It attempts to download the test.iso
file from the FileDistribution at the path
/pulp/content/somepath/
Note the somepath
part of this is from the base_url
of the
Distribution you are testing against.
Note
If the RHSM client cert contains entitlement paths, they must match the full path to the
Distribution the client is fetching from. In this example that is /pulp/content/somepath/
.
For example with httpie you can submit the client cert and key via TLS using:
$ http --cert ~/client.pem --cert-key ~/key.pem https://localhost/pulp/content/somepath/test.iso
This is expected to yield binary data with a response like:
HTTP/1.1 200 OK
Accept-Ranges: bytes
Connection: keep-alive
Content-Length: 3145728
Content-Type: application/octet-stream
Date: Tue, 21 Apr 2020 20:35:11 GMT
Last-Modified: Tue, 21 Apr 2020 19:23:06 GMT
Server: nginx/1.16.1
+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+