Update Python API to support REST API v2

The PKIClient class has been added to replace PKIConnection
as the main access point to PKI services. By default it will
use REST API v2, then fall back to v1 if it's not available.
Optionally, PKIClient can be configured to use a specific
REST API version.

The InfoClient, CertClient, AccountClient, and UserClient
classes have been added/updated to construct the proper REST
URL according to the REST API version in PKIClient.

The pki-healthcheck has been updated to use PKIClient. Some
simple Python scripts have also been added to demonstrate
how to use PKIClient.

New tests have been added to run these scripts against the
current CA and KRA which support both REST API v1 and v2
and also against an older CA that only supports REST API v1.

.github/workflows/python-ca-test.yml

@@ -0,0 +1,281 @@
+name: CA Python API
+
+on: workflow_call
+
+env:
+  DS_IMAGE: ${{ vars.DS_IMAGE || 'quay.io/389ds/dirsrv' }}
+
+jobs:
+  # docs/installation/ca/Installing_CA.md
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    env:
+      SHARED: /tmp/workdir/pki
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v4
+
+      - name: Retrieve PKI images
+        uses: actions/cache@v4
+        with:
+          key: pki-images-${{ github.sha }}
+          path: pki-images.tar
+
+      - name: Load PKI images
+        run: docker load --input pki-images.tar
+
+      - name: Create network
+        run: docker network create example
+
+      ####################################################################################################
+      # Install CA that supports both REST API v1 and v2
+
+      - name: Set up DS container
+        run: |
+          tests/bin/ds-create.sh \
+              --image=${{ env.DS_IMAGE }} \
+              --hostname=ds.example.com \
+              --network=example \
+              --network-alias=ds.example.com \
+              --password=Secret.123 \
+              ds
+
+      - name: Set up PKI container
+        run: |
+          tests/bin/runner-init.sh \
+              --hostname=pki.example.com \
+              --network=example \
+              --network-alias=pki.example.com \
+              pki
+
+      - name: Install CA
+        run: |
+          docker exec pki pkispawn \
+              -f /usr/share/pki/server/examples/installation/ca.cfg \
+              -s CA \
+              -D pki_ds_url=ldap://ds.example.com:3389 \
+              -v
+
+      - name: Update PKI server configuration
+        run: |
+          docker exec pki dnf install -y xmlstarlet
+
+          # disable access log buffer
+          docker exec pki xmlstarlet edit --inplace \
+              -u "//Valve[@className='org.apache.catalina.valves.AccessLogValve']/@buffered" \
+              -v "false" \
+              -i "//Valve[@className='org.apache.catalina.valves.AccessLogValve' and not(@buffered)]" \
+              -t attr \
+              -n "buffered" \
+              -v "false" \
+              /etc/pki/pki-tomcat/server.xml
+
+          # restart PKI server
+          docker exec pki pki-server restart --wait
+
+      - name: Set up client
+        run: |
+          # export CA signing cert
+          docker exec pki pki-server cert-export \
+              --cert-file $SHARED/ca_signing.crt \
+              ca_signing
+
+          # export admin cert
+          docker exec pki openssl pkcs12 \
+             -in /root/.dogtag/pki-tomcat/ca_admin_cert.p12 \
+             -passin pass:Secret.123 \
+             -out admin.crt \
+             -clcerts \
+             -nokeys
+
+          # export admin key
+          docker exec pki openssl pkcs12 \
+             -in /root/.dogtag/pki-tomcat/ca_admin_cert.p12 \
+             -passin pass:Secret.123 \
+             -out admin.key \
+             -nodes \
+             -nocerts
+
+      ####################################################################################################
+      # Check Python API
+
+      - name: Check PKI server info
+        run: |
+          docker exec pki python /usr/share/pki/tests/bin/pki-info.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -1 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v2 by default
+          cat > expected << EOF
+          GET /pki/v2/info HTTP/1.1 200 -
+          EOF
+
+          diff expected output
+
+      - name: Check PKI server info with REST API v1
+        run: |
+          docker exec pki python /usr/share/pki/tests/bin/pki-info.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              --api v1 \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -1 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v1 as specified
+          cat > expected << EOF
+          GET /pki/v1/info HTTP/1.1 200 -
+          EOF
+
+      - name: Check CA certs
+        run: |
+          docker exec pki python /usr/share/pki/tests/ca/bin/pki-ca-cert-find.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -2 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v2 by default
+          cat > expected << EOF
+          GET /pki/v2/info HTTP/1.1 200 -
+          POST /ca/v2/certs/search HTTP/1.1 200 -
+          EOF
+
+          diff expected output
+
+      - name: Check CA certs with REST API v1
+        run: |
+          docker exec pki python /usr/share/pki/tests/ca/bin/pki-ca-cert-find.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              --api v1 \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -1 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v1 as specified
+          cat > expected << EOF
+          POST /ca/v1/certs/search HTTP/1.1 200 -
+          EOF
+
+          diff expected output
+
+      - name: Check CA users
+        run: |
+          docker exec pki python /usr/share/pki/tests/ca/bin/pki-ca-user-find.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              --client-cert admin.crt \
+              --client-key admin.key \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -4 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v2 by default
+          cat > expected << EOF
+          GET /pki/v2/info HTTP/1.1 200 -
+          GET /ca/v2/account/login HTTP/1.1 200 caadmin
+          GET /ca/v2/admin/users HTTP/1.1 200 caadmin
+          GET /ca/v2/account/logout HTTP/1.1 204 caadmin
+          EOF
+
+          diff expected output
+
+      - name: Check CA users with REST API v1
+        run: |
+          docker exec pki python /usr/share/pki/tests/ca/bin/pki-ca-user-find.py \
+              -U https://pki.example.com:8443 \
+              --ca-bundle $SHARED/ca_signing.crt \
+              --client-cert admin.crt \
+              --client-key admin.key \
+              --api v1 \
+              -v
+
+          sleep 1
+
+          # check HTTP methods, paths, protocols, status, and authenticated users
+          docker exec pki find /var/log/pki/pki-tomcat \
+              -name "localhost_access_log.*" \
+              -exec cat {} \; \
+              | tail -3 \
+              | sed -e 's/^.* .* \(.*\) \[.*\] "\(.*\)" \(.*\) .*$/\2 \3 \1/' \
+              | tee output
+
+          # Python API should use REST API v1 as specified
+          cat > expected << EOF
+          GET /ca/v1/account/login HTTP/1.1 200 caadmin
+          GET /ca/v1/admin/users HTTP/1.1 200 caadmin
+          GET /ca/v1/account/logout HTTP/1.1 204 caadmin
+          EOF
+
+          diff expected output
+
+      - name: Check DS server systemd journal
+        if: always()
+        run: |
+          docker exec ds journalctl -x --no-pager -u [email protected]
+
+      - name: Check DS container logs
+        if: always()
+        run: |
+          docker logs ds
+
+      - name: Check PKI server systemd journal
+        if: always()
+        run: |
+          docker exec pki journalctl -x --no-pager -u [email protected]
+
+      - name: Check PKI server access log
+        if: always()
+        run: |
+          docker exec pki find /var/log/pki/pki-tomcat -name "localhost_access_log.*" -exec cat {} \;
+
+      - name: Check CA debug log
+        if: always()
+        run: |
+          docker exec pki find /var/lib/pki/pki-tomcat/logs/ca -name "debug.*" -exec cat {} \;