Update Python API to support REST API v2

The Python API has been updated to support REST API v2 with
the ability to fall back to v1 if v2 is not available.

The PKIClient class has been added to replace PKIConnection
as the main class to be used by the client application. The
REST API version can be specified when creating this object.
The InfoClient, CertClient, AccountClient, and UserClient
classes have been added/updated to support REST API v2 with
fallback to v1.

Some Python scripts have been added to demonstrate how to
use the updated Python API. New tests have been added to use
the 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 {} \;