zowe · Joe-Winchester · Jul 28, 2020 · Feb 19, 2020 · Feb 21, 2020 · Mar 3, 2020
diff --git a/bin/apiml_cm.sh b/bin/apiml_cm.sh
diff --git a/bin/utils/keyring-util/README.md b/bin/utils/keyring-util/README.md
@@ -0,0 +1,69 @@
+The keyring-util's source code can be found in the 
+https://github.com/zowe/keyring-utilities
+
+# keyring-util
+
+The keyring-util program leverages
+[R_datalib callable service](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichd100/datalib.htm)
+to perform various operations on digital certificates and RACF key rings.
+
+## Build
+Execute the `build.sh` script
+
+## Syntax
+```bash
+keyring-util function userid keyring label
+```
+**Parametres:**
+ 1. `function` see [Functions](##Functions) section below
+ 2. `userid` - an owner of the `keyring` and `label` certificate
+ 3. `keyring` - a name of the keyring
+ 4. `label` - a label of the certificate
+ 5. `extra-parm-1` - specific to a used function
+ 6. `extra-parm-2` - specific to a used function
+
+## Functions
+
+  * `NEWRING` - creates a keyring
+       * Example: `keyring-util NEWRING USER01 RING02`
+
+  * `DELRING` - deletes a keyring
+       * Example: `keyring-util DELRING USER01 RING02`
+
+  * `DELCERT` - remove a certificate from a keyring or deletes a certificate from RACF database
+
+    **Current Limitation:** The `DELCERT` function can only manipulate a certificate that is owned by the `userid`, i.e. it can't
+     work with certificates owned by the CERTAUTH, SITE or different userid.
+
+       The following example removes `CERT03` certificate owned by the `USER01` from the `RING02` keyring owned by the `USER01` userid
+       * Example: `keyring-util DELCERT USER01 RING02 CERT03`
+
+       The following example removes `CERT03` certificate owned by the `USER01` from the RACF database. The command fails if the certificate
+       is still connected to some keyring.
+       * Example: `keyring-util DELCERT USER01 '*' CERT03`
+
+  * `EXPORT` - exports a certificate in PEM format. The file is created in a `pwd` directory with a name of `<cert_alias>.pem`
+       * Example: `keyring-util EXPORT USER01 RING02 CERT03`
+
+         Creates a file CERT03.pem.
+
+  * `IMPORT` - imports a certificate from the PKCS12 format. 
+
+       **Warning:** The scenario where a private key is also imported currently works only with RACF.
+
+       * Example: `keyring-util IMPORT USER01 RING02 CERT03 /path/to/file.p12 pkcs12_password`
+
+  * `REFRESH` - refreshes DIGTCERT class
+       * Example: `keyring-util REFRESH`
+
+For any return and reason codes, check [R_datalib return and reason codes](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichd100/ich2d100238.htm)
+
+## Further development
+There is room for improvement:
+  * command line argument processing and syntax (perhaps using the argp library from [ambitus project](https://github.com/ambitus/glibc/tree/zos/2.28/master/argp))
+  * an extension of functionality of the current R_datalib functions
+  * adding support for other [R_datalib functions](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichd100/ich2d100226.htm)
+
+Work with the following resource if you want to add support for other R_datalib functions [Data areas for R_datalib callable service](https://www.ibm.com/support/knowledgecenter/SSLTBW_2.4.0/com.ibm.zos.v2r4.ichc400/comx.htm)
+
+
diff --git a/bin/utils/keyring-util/keyring-util b/bin/utils/keyring-util/keyring-util
diff --git a/bin/zowe-setup-certificates.env b/bin/zowe-setup-certificates.env
@@ -1,7 +1,7 @@
 # Zowe development: if you edit this file, please make sure to update the 
 # ../workflows/ZWEWRF05.xml file accordingly.
 
-# The hostname of the system running API Mediation. If the hostname is 
+# The hostname of the system running API Mediation. If the hostname is
 # omitted, the configuration script attempts to calculate the value on 
 # its own.
 HOSTNAME=
@@ -13,15 +13,18 @@ IPADDRESS=
 VERIFY_CERTIFICATES=true
 
 # optional - Path to a PKCS12 keystore with a server certificate for API
-# Mediaton Layer (APIML)
+# Mediaton Layer (APIML). Ignore if you used the ZWEKRING jcl
 EXTERNAL_CERTIFICATE=
-# optional - Alias of the certificate in the keystore
+# optional - Alias of the certificate in the keystore. Ignore if you used
+# the ZWEKRING jcl
 EXTERNAL_CERTIFICATE_ALIAS=
 # optional - Public certificates of trusted CAs - multiple certificates 
 # delimitad with space has to be enclosed with quotes ("cer1 cer2")
+# Ignore if you used the ZWEKRING jcl
 EXTERNAL_CERTIFICATE_AUTHORITIES=
 # optional - Public certificates of z/OSMF - multiple certificates 
 # delimited with space has to be enclosed with quotes ("cer1 cer2")
+# Ignore if you used the ZWEKRING jcl
 ZOSMF_CERTIFICATE=
 # If APIML SSO token not present, Zowe components are allowed to attempt authentication with other user-provided data
 SSO_FALLBACK_TO_NATIVE_AUTH=true
@@ -32,13 +35,24 @@ PKCS11_TOKEN_LABEL=
 
 # Select a password that is used to secure EXTERNAL_CERTIFICATE keystore
 # and that will be also used to secure newly generated keystores for API 
-# Mediation
+# Mediation. Ignore if you used the ZWEKRING jcl
 KEYSTORE_PASSWORD=password
-# Location for generated certificates
+# Location for generated certificates and/or JWT token
 KEYSTORE_DIRECTORY=/global/zowe/keystore
-# Select an alias for the certificate in the generated keystore
+# Select an alias for the certificate in the generated keystore.
+# If you used the ZWEKRING jcl, then this variable has to be set to the
+# Zowe certificate's LABEL specified in the JCL.
 KEYSTORE_ALIAS=localhost
-# Specify zowe user id to set up ownership of the generated certificates
+# Specify zowe user id to set up ownership of the generated certificates.
+# This variable is also used for keyring configuration. If you used
+# the ZWEKRING jcl, set the variable to the same user id as in the jcl.
 ZOWE_USER_ID=ZWESVUSR
-# Specify zowe user id to set up ownership of the generated certificates
+# Specify zowe group id to set up ownership of the generated certificates
 ZOWE_GROUP_ID=ZWEADMIN
+# Specify zowe keyring that keeps zowe certificates, if not specified then
+# USS keystore files will be created. If you used the ZWEKRING jcl, set
+# the variable to the same keyring that you used in the jcl.
+ZOWE_KEYRING=
+# If you used ZWEKRING jcl to configure the certificates for the keyring
+# then set this variable to false (defaults to false)
+GENERATE_CERTS_FOR_KEYRING=false
diff --git a/bin/zowe-setup-certificates.sh b/bin/zowe-setup-certificates.sh
@@ -13,6 +13,10 @@
 # - KEYSTORE_PASSWORD - a password that is used to secure EXTERNAL_CERTIFICATE keystore and
 #                       that will be also used to secure newly generated keystores for API Mediation.
 # - ZOWE_USER_ID - zowe user id to set up ownership of the generated certificates
+# - ZOWE_KEYRING - specify zowe keyring that keeps zowe certificates, if not specified USS keystore
+#                  files will be created.
+# - GENERATE_CERTS_FOR_KEYRING - If you used ZWEKRING jcl to configure certificates and the keyring
+#                                then set this variable to false (defaults to false)
 
 # process input parameters.
 while getopts "l:p:" opt; do
@@ -27,6 +31,8 @@ while getopts "l:p:" opt; do
 done
 shift $(($OPTIND-1))
 
+umask 0027
+
 if [[ -z ${ZOWE_ROOT_DIR} ]]
 then
   export ZOWE_ROOT_DIR=$(cd $(dirname $0)/../;pwd)
@@ -96,15 +102,25 @@ SAN="SAN=dns:${ZOWE_EXPLORER_HOST},ip:${ZOWE_IP_ADDRESS},dns:localhost.localdoma
 
 if [[ -z "${EXTERNAL_CERTIFICATE}" ]] || [[ -z "${EXTERNAL_CERTIFICATE_ALIAS}" ]] || [[ -z "${EXTERNAL_CERTIFICATE_AUTHORITIES}" ]]; then
   if [[ -z "${EXTERNAL_CERTIFICATE}" ]] && [[ -z "${EXTERNAL_CERTIFICATE_ALIAS}" ]] && [[ -z "${EXTERNAL_CERTIFICATE_AUTHORITIES}" ]]; then
-    ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --service-password ${KEYSTORE_PASSWORD} \
-      --service-alias ${KEYSTORE_ALIAS} --service-keystore ${KEYSTORE_PREFIX} --service-truststore ${TRUSTSTORE_PREFIX} --local-ca-filename ${LOCAL_CA_PREFIX}
-    RC=$?
-    echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+    if [[ -z "${ZOWE_KEYRING}" ]]; then
+      ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --service-password ${KEYSTORE_PASSWORD} \
+        --service-alias ${KEYSTORE_ALIAS} --service-keystore ${KEYSTORE_PREFIX} --service-truststore ${TRUSTSTORE_PREFIX} --local-ca-filename ${LOCAL_CA_PREFIX}
+      RC=$?
+      echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+    elif [[ "${GENERATE_CERTS_FOR_KEYRING}" != "false" ]]; then
+      ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --service-keystore ${KEYSTORE_PREFIX} \
+        --service-alias ${KEYSTORE_ALIAS} --zowe-userid ${ZOWE_USER_ID} --zowe-keyring ${ZOWE_KEYRING} --service-storetype "JCERACFKS" --local-ca-filename ${LOCAL_CA_PREFIX}
+      RC=$?
+      echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+    else
+      echo "Generating certificates for the keyring is skipped."
+    fi
   else
     (>&2 echo "Zowe Install setup configuration is invalid; check your zowe-setup-certificates.env file.")
     (>&2 echo "Some external apiml certificate fields are supplied...Fields must be filled out in full or left completely blank.")
     (>&2 echo "See $LOG_FILE for more details.")
     echo "</zowe-setup-certificates.sh>" >> $LOG_FILE
+    rm ${KEYSTORE_PREFIX}* ${TRUSTSTORE_PREFIX}* ${EXTERNAL_CA_PREFIX}* ${LOCAL_CA_PREFIX}* 2> /dev/null
     exit 1
   fi
 else
@@ -113,25 +129,43 @@ else
       EXT_CA_PARM="${EXT_CA_PARM} --external-ca ${CA} "
   done
 
-  ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --service-password ${KEYSTORE_PASSWORD} \
-    --external-certificate ${EXTERNAL_CERTIFICATE} --external-certificate-alias ${EXTERNAL_CERTIFICATE_ALIAS} ${EXT_CA_PARM} \
-    --service-alias ${KEYSTORE_ALIAS} --service-keystore ${KEYSTORE_PREFIX} --service-truststore ${TRUSTSTORE_PREFIX} --local-ca-filename ${LOCAL_CA_PREFIX} \
-    --external-ca-filename ${EXTERNAL_CA_PREFIX}
-  RC=$?
-
-  echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+  if [[ -z "${ZOWE_KEYRING}" ]]; then
+    ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --service-password ${KEYSTORE_PASSWORD} \
+      --external-certificate ${EXTERNAL_CERTIFICATE} --external-certificate-alias ${EXTERNAL_CERTIFICATE_ALIAS} ${EXT_CA_PARM} \
+      --service-alias ${KEYSTORE_ALIAS} --service-keystore ${KEYSTORE_PREFIX} --service-truststore ${TRUSTSTORE_PREFIX} --local-ca-filename ${LOCAL_CA_PREFIX} \
+      --external-ca-filename ${EXTERNAL_CA_PREFIX}
+    RC=$?
+    echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+  elif [[ "${GENERATE_CERTS_FOR_KEYRING}" != "false" ]]; then
+    ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action setup --service-ext ${SAN} --zowe-userid ${ZOWE_USER_ID} --zowe-keyring ${ZOWE_KEYRING} \
+      --service-storetype "JCERACFKS" --external-certificate ${EXTERNAL_CERTIFICATE} --external-certificate-alias ${EXTERNAL_CERTIFICATE_ALIAS} \
+      --service-alias ${KEYSTORE_ALIAS} --service-keystore ${KEYSTORE_PREFIX}  --local-ca-filename ${LOCAL_CA_PREFIX}
+    RC=$?
+    echo "apiml_cm.sh --action setup returned: $RC" >> $LOG_FILE
+  else
+    echo "Generating certificates for the keyring is skipped."
+  fi
 fi
 
 if [ "$RC" -ne "0" ]; then
     (>&2 echo "apiml_cm.sh --action setup has failed. See $LOG_FILE for more details")
     echo "</zowe-setup-certificates.sh>" >> $LOG_FILE
+    rm ${KEYSTORE_PREFIX}* ${TRUSTSTORE_PREFIX}* ${EXTERNAL_CA_PREFIX}* ${LOCAL_CA_PREFIX}* 2> /dev/null
     exit 1
 fi
 
 if [[ "${VERIFY_CERTIFICATES}" == "true" ]]; then
-  ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action trust-zosmf \
-    --service-password ${KEYSTORE_PASSWORD} --service-truststore ${TRUSTSTORE_PREFIX} --zosmf-certificate "${ZOSMF_CERTIFICATE}" \
-    --service-keystore ${KEYSTORE_PREFIX}
+  if [[ -z "${ZOWE_KEYRING}" ]]; then
+    ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action trust-zosmf \
+      --service-password ${KEYSTORE_PASSWORD} --service-truststore ${TRUSTSTORE_PREFIX} --zosmf-certificate "${ZOSMF_CERTIFICATE}" \
+      --service-keystore ${KEYSTORE_PREFIX}
+  else
+    export GENERATE_CERTS_FOR_KEYRING;
+    ${ZOWE_ROOT_DIR}/bin/apiml_cm.sh --verbose --log $LOG_FILE --action trust-zosmf --zowe-userid ${ZOWE_USER_ID} \
+      --zowe-keyring ${ZOWE_KEYRING} --service-storetype "JCERACFKS" --zosmf-certificate "${ZOSMF_CERTIFICATE}" \
+      --service-keystore ${KEYSTORE_PREFIX} --service-password ${KEYSTORE_PASSWORD} \
+      --service-truststore ${TRUSTSTORE_PREFIX}
+  fi
   RC=$?
 
   echo "apiml_cm.sh --action trust-zosmf returned: $RC" >> $LOG_FILE
@@ -141,6 +175,7 @@ if [[ "${VERIFY_CERTIFICATES}" == "true" ]]; then
       (>&2 echo "ZOWE_ZOSMF_HOST=${ZOWE_ZOSMF_HOST}   ZOWE_ZOSMF_PORT=${ZOWE_ZOSMF_PORT}")
       (>&2 echo "You can also specify z/OSMF certificate explicitly in the ZOSMF_CERTIFICATE environmental variable in the zowe-setup-certificates.env file.")
       echo "</zowe-setup-certificates.sh>" >> $LOG_FILE
+      rm ${KEYSTORE_PREFIX}* ${TRUSTSTORE_PREFIX}* ${EXTERNAL_CA_PREFIX}* ${LOCAL_CA_PREFIX}* 2> /dev/null
       exit 1
   fi
 fi
@@ -173,21 +208,39 @@ fi
 ZOWE_CERTIFICATES_ENV=${KEYSTORE_DIRECTORY}/${ZOWE_CERT_ENV_NAME}
 rm ${ZOWE_CERTIFICATES_ENV} 2> /dev/null
 
-cat >${KEYSTORE_DIRECTORY}/${ZOWE_CERT_ENV_NAME} <<EOF
-  KEY_ALIAS=${KEYSTORE_ALIAS}
-  KEYSTORE_PASSWORD=${KEYSTORE_PASSWORD}
-  KEYSTORE=${KEYSTORE_PREFIX}.p12
-  KEYSTORE_TYPE="PKCS12"
-  TRUSTSTORE=${TRUSTSTORE_PREFIX}.p12
-  KEYSTORE_KEY=${KEYSTORE_PREFIX}.key
-  KEYSTORE_CERTIFICATE=${KEYSTORE_PREFIX}.cer-ebcdic
-  KEYSTORE_CERTIFICATE_AUTHORITY=${LOCAL_CA_PREFIX}.cer-ebcdic
-  ZOWE_APIM_VERIFY_CERTIFICATES=${VERIFY_CERTIFICATES}
-  SETUP_APIML_SSO=${SETUP_APIML_SSO}
-  SSO_FALLBACK_TO_NATIVE_AUTH=${SSO_FALLBACK_TO_NATIVE_AUTH}
-  PKCS11_TOKEN_NAME=${PKCS11_TOKEN_NAME}
-  PKCS11_TOKEN_LABEL=${UPPER_KEY_LABEL}
+if [[ -z "${ZOWE_KEYRING}" ]]; then
+  cat >${KEYSTORE_DIRECTORY}/${ZOWE_CERT_ENV_NAME} <<EOF
+    KEY_ALIAS=${KEYSTORE_ALIAS}
+    KEYSTORE_PASSWORD=${KEYSTORE_PASSWORD}
+    KEYSTORE=${KEYSTORE_PREFIX}.p12
+    KEYSTORE_TYPE="PKCS12"
+    TRUSTSTORE=${TRUSTSTORE_PREFIX}.p12
+    KEYSTORE_KEY=${KEYSTORE_PREFIX}.key
+    KEYSTORE_CERTIFICATE=${KEYSTORE_PREFIX}.cer-ebcdic
+    KEYSTORE_CERTIFICATE_AUTHORITY=${LOCAL_CA_PREFIX}.cer-ebcdic
+    ZOWE_APIM_VERIFY_CERTIFICATES=${VERIFY_CERTIFICATES}
+    SETUP_APIML_SSO=${SETUP_APIML_SSO}
+    SSO_FALLBACK_TO_NATIVE_AUTH=${SSO_FALLBACK_TO_NATIVE_AUTH}
+    PKCS11_TOKEN_NAME=${PKCS11_TOKEN_NAME}
+    PKCS11_TOKEN_LABEL=${UPPER_KEY_LABEL}
+EOF
+else
+  cat >${KEYSTORE_DIRECTORY}/${ZOWE_CERT_ENV_NAME} <<EOF
+    KEY_ALIAS=${KEYSTORE_ALIAS}
+    KEYSTORE_PASSWORD="password"
+    KEYRING_OWNER="${ZOWE_USER_ID}"
+    KEYRING_NAME="${ZOWE_KEYRING}"
+    KEYSTORE="safkeyring:////\${KEYRING_OWNER}/\${KEYRING_NAME}"
+    KEYSTORE_TYPE="JCERACFKS"
+    TRUSTSTORE="safkeyring:////\${KEYRING_OWNER}/\${KEYRING_NAME}"
+    ZOWE_APIM_VERIFY_CERTIFICATES=${VERIFY_CERTIFICATES}
+    SETUP_APIML_SSO=${SETUP_APIML_SSO}
+    SSO_FALLBACK_TO_NATIVE_AUTH=${SSO_FALLBACK_TO_NATIVE_AUTH}
+    PKCS11_TOKEN_NAME=${PKCS11_TOKEN_NAME}
+    PKCS11_TOKEN_LABEL=${UPPER_KEY_LABEL}
 EOF
+fi
+
 # set up privileges and ownership
 chmod -R 500 ${KEYSTORE_DIRECTORY}/${LOCAL_KEYSTORE_SUBDIR}/* ${KEYSTORE_DIRECTORY}/${KEYSTORE_ALIAS}/*
 echo "Trying to change an owner of the ${KEYSTORE_DIRECTORY}."