Middleware Client Certificate Issuance

Middleware Client certificates can be used for Client TLS authentication to the ED REST API and ED LDAP directory.

Usage

Docker login

Before pulling the Docker image, you must authenticate with the Docker registry.

docker login -u <your-username> code.vt.edu:5005

Replace with your PID or GitLab username.

Enter Your GitLab Access Token: When prompted for a password, enter your GitLab personal access token. If you do not have an access token, follow the steps below to create one:

• Visit the GitLab documentation to learn how to create a personal access token.
• Ensure the token has at least the read_registry scope.

With these credentials, you should be able to pull Docker images from the registry successfully.

Pulling the Image

To pull the Docker image, run the following command:

docker pull code.vt.edu:5005/middleware/certs/middleware-client-cert-handler

Note to Windows Users:

To ensure compatibility, Docker must be running in Linux container mode. If Docker is currently using the Windows daemon, you will see an option labeled “Switch to Linux containers…” in the Docker menu. To confirm that you’re using the correct mode, verify that the menu option reads “Switch to Windows containers…

Please follow the instructions here to Switch between Windows and Linux containers

Certificate Request

Users creating a service for the first time should follow this procedure:

Request an ED service from IMCS by following VT 4Help KB0011183

After IMCS creates the ED service, they will provide the service owner with a password credential that is valid for 7 days.

Subsequently, the service owner should follow below steps to request a Middleware Client certificate.

docker run -it -v /path/to/output/directory/on/host:/app/data code.vt.edu:5005/middleware/certs/middleware-client-cert-handler request <ed-service-name> <tier>

•	ed-service-name: Name of the ED service.
•	tier: The environment tier (dev, pprd, prod).

When prompted for password, please enter the password credential shared by IMCS.

Upon execution, the endpoint will deliver the keystore in P12 format along with the corresponding password. Neither the private key nor the keystore password will be retrievable later. Therefore, it’s imperative for the service owner to securely store them for future use.

Certificate Renewal

Service owners seeking to renew their certificates should use their existing Middleware Client certificate and private key and follow below procedure

docker run -it -v /path/to/output/directory/on/host:/app/data -v /path/to/cert/on/host:/app/certs/cert.pem -v /path/to/key/on/host:/app/certs/key.pem code.vt.edu:5005/middleware/certs/middleware-client-cert-handler renew <tier>

•	tier: The environment tier (dev, pprd, prod).

Upon execution, the endpoint will deliver the keystore in P12 format along with the corresponding password. Neither the private key nor the keystore password will be retrievable later. Therefore, it’s imperative for the service owner to securely store them for future use.

Certificate Revocation

Service owners seeking to revoking their certificates should use their existing Middleware Client certificate and private key and follow below procedure:

docker run -it -v /path/to/cert/on/host:/app/certs/cert.pem -v /path/to/key/on/host:/app/certs/key.pem code.vt.edu:5005/middleware/certs/middleware-client-cert-handler revoke <tier> <serial>

•	tier: The environment tier (dev, pprd, prod).
•	serial: The serial number of the certificate to be revoked (in decimal format).

Show serial number

To show serial number of a p12 file in decimal format:

docker run -it -v /path/to/p12/on/host:/app/certs/keystore.p12 code.vt.edu:5005/middleware/certs/middleware-client-cert-handler showcertserial

Example

Here is an example to renew a certificate:

Linux:

docker run -it -v /tmp:/app/data -v /Users/alice/Documents/test-service.crt:/app/certs/cert.pem -v /Users/alice/Documents/test-service.key:/app/certs/key.pem code.vt.edu:5005/middleware/certs/middleware-client-cert-handler renew dev

This command will store the output in the /tmp/certs/test-service/dev directory on the host and use the certificate from /Users/alice/Documents/test-service.crt and key from /Users/alice/Documents/test-service.key.

Windows:

docker run -it -v C:\Users\service-owner\Desktop\output-directory\:/app/data -v C:\Users\service-owner\Desktop\test-service.crt:/app/certs/cert.pem -v C:\Users\service-owner\Desktop\test-service.key:/app/certs/key.pem code.vt.edu:5005/middleware/certs/middleware-client-cert-handler renew dev

This command will store the output in the C:\Users\service-owner\Desktop\output-directory\certs\test-service\dev directory on the host and use the certificate from C:\Users\service-owner\Desktop\test-service.crt and key from C:\Users\service-owner\Desktop\test-service.key.

Notes

. The -it will run the container in interactive mode that let's the user input password.
. The output files are saved to the host path specified in the docker run command with the -v option.
. Ensure that the required certificate and key files are mounted correctly inside the container.

Useful openssl commands

• Extract private key from p12 in unencrypted format:

  • For OpenSSL v3.0 and above:
    • openssl pkcs12 -in test-service.p12 -nocerts -noenc -out test-key.pem -passin pass:<password>
  • For OpenSSL versions prior to v3.0:
    • openssl pkcs12 -in test-service.p12 -nocerts -nodes -out test-key.pem -passin pass:<password>
• Extract private key from p12 in encrypted format:
  • openssl pkcs12 -in test-service.p12 -nocerts -out test-key.pem -passin pass:<password> -passout pass:<password>
• Extract certificate from p12 in encrypted format:
  • openssl pkcs12 -in test-service.p12 -out test-cert.pem -clcerts -nokeys -password pass:<password>
• Create p12 file from certificate and key:
  • openssl pkcs12 -export -out test-service.p12 -inkey test-key.pem -in test-cert.pem -name "your-alias" -passout pass:<password>
• Extract certificate serial number (for revocation) from existing .p12 file (Also available in docker image):
  • echo “ibase=16; $(openssl pkcs12 -in test-service.p12 -nokeys | openssl x509 -noout -serial | awk -F= ‘{print $2}‘)” | bc
• Extract certificate serial number (for revocation) from existing certificate .pem file:
  • echo “ibase=16; $(openssl x509 -in test-service.pem -noout -serial | awk -F= ‘{print $2}‘)” | bc

FAQ

• Where is the new Middleware CA hosted?

  The Middleware CA is hosted Enterprise Systems vault. The URL for the CA and URL are as below:

  1. prod: https://vault.es.cloud.vt.edu:8200/v1/middleware_pki/ca https://vault.es.cloud.vt.edu:8200/v1/middleware_pki/crl
  2. pprd: https://vault.es.cloud.vt.edu:8200/v1/middleware_pki_pprd/ca https://vault.es.cloud.vt.edu:8200/v1/middleware_pki_pprd/crl
  3. dev: https://vault.es.cloud.vt.edu:8200/v1/middleware_pki_dev/ca https://vault.es.cloud.vt.edu:8200/v1/middleware_pki_dev/crl

• Will there be emailed alerts prior to expiration of Middleware Client Certs?

  No, there are currently no emailed alerts for certificate expiration. However, Middleware is looking into implementing it.

• Should I use the respective tiered certs? Is that enforced?

  Yes, respective tiered certificates must be used to authenticate to LDAP and REST endpoints.

• Are we able to generate any number of certs in each tier per ED service?

  Yes, you can generate any number of certificates in each tier for an ED service.

• Now that I have a middleware client cert from each tier, is the old middleware client cert invalid?

  The old middleware client certificate can still be used with LDAP and ED until it expires. However, please note that the servers are expected to be retired, after which CRL and OCSP services will no longer be available.