add comments

1 files changed, 22 insertions, 0 deletions

diff --git a/request_cert.sh b/request_cert.sh
index 4d0a34e..5446362 100644
--- a/request_cert.sh
+++ b/request_cert.sh
@@ -17,6 +17,7 @@ set -eu
 AUTH_VAULT_URL=${AUTH_VAULT_URL-https://vault.dings:8199}
 CERT_VAULT_URL=${CERT_VAULT_URL-https://vault.dings:8200}
 
+# Unless a vault token is already provided by the user, fetch a token using LDAP credentials
 if [ -z "${VAULT_TOKEN-}" ]; then
    read -p USER: LDAPUSER
    read -s -p PASSWORD: LPDAPASSWD
@@ -37,7 +38,21 @@ is_hostname() {
   echo "$1" | grep -Eq "^$RFC952_hname_ERE\$"
 }
 
+# Following block will set the two variables CN and cert_request_data
+# depending on the provided arguments.
+#
+# CN is the common name to be used for the certificate.  CN is also used to
+# specify the output directory and the file names of the generated key and
+# certificates.  The common name should be a domainname as described by
+# [RFC952], section A.
+# [RFC952]: https://www.rfc-editor.org/rfc/rfc952.txt
+#
+# cert_response_data specifies the parameters to for generating a certificate
+# and key.  The parameters should be specified as JSON object as described by
+# https://developer.hashicorp.com/vault/api-docs/secret/pki#generate-certificate-and-key
+#
 if [ $# = 2 ] && [ "$1" = -s ]; then
+   # Simple usage: user has provided only a fully qualified domain name which should be used as common name for the certificate
    CN=$2
    if ! is_hostname "$CN"; then
      echo "error: specified FQDN is not a valid hostname: $CN" >&2
@@ -56,12 +71,19 @@ else
    exit 1
 fi
 
+# Note that $CN does not have to be quoted after this point because we've
+# asserted it's a domain name above and thus cannot cause word splitting.
+# This comment can be deleted if $CN gets quoted below.
+
 if [ -d $CN ]; then
    rm -r $CN
 fi
 
 mkdir $CN
 
+# TODO rz_q-ca_2021aa and rz-drv look like they correspond to :issuer_ref and :name
+# in https://developer.hashicorp.com/vault/api-docs/secret/pki#generate-certificate-and-key
+# If that's the case, then both should probably be made configurable the same way CERT_VAULT_URL is
 cert_response_data=$(echo "$cert_request_data" | curl -Ssf -H "X-Vault-Token: $VAULT_TOKEN" -d @- "$CERT_VAULT_URL/v1/pki_rz_q-ca_2021aa/issue/rz-drv")
 
 echo "$cert_response_data" > $CN/$CN.json