Keyring support

bin/utils/keyring-util/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+## 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 
+
+## Functions
+
+  * `NEWRING` - creates a keyring
+       * Example: `keyring-util NEWRING USER01 ZOWERING` 
+
+  * `DELRING` - deletes a keyring
+       * Example: `keyring-util DELRING USER01 ZOWERING`
+
+  * `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 `localhost` certificate owned by the `USER01` from the `ZOWERING` keyring owned by the `USER01` userid
+       * Example: `keyring-util DELCERT USER01 ZOWERING localhost`
+
+       The following example removes `localhost` 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 '*' localhost`
+
+  * `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)
+

bin/utils/keyring-util/build.sh

@@ -0,0 +1 @@
+xlc -q64 -o keyring-util keyring-util.c

bin/utils/keyring-util/keyring-util.c

@@ -0,0 +1,175 @@
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+
+#ifdef _LP64
+    #pragma linkage(IRRSDL64, OS)
+#else
+    #error "31-bit not supported yet."
+#endif
+
+#include "keyring-util.h"
+
+int debug = 0;
+
+int main(int argc, char **argv)
+{
+    int i;
+
+    if (getenv("KEYRING_UTIL_DEBUG") != NULL && ! strcmp(getenv("KEYRING_UTIL_DEBUG"), "YES")) {
+        debug = 1;
+    }
+    Command_line_parms parms;
+    memset(&parms, 0, sizeof(Command_line_parms));
+
+    R_datalib_data_remove rem_parm;
+    memset(&rem_parm, 0x00, sizeof(R_datalib_data_remove));
+
+    R_datalib_parm_list_64 p;
+
+    process_cmdline_parms(&parms, argc, argv);
+
+    R_datalib_function function_table[] = {
+        {"NEWRING", NEWRING_CODE, 0x00000000, 0, NULL, simple_action},
+        {"DELCERT", DELCERT_CODE, 0x00000000, 0, &rem_parm, delcert_action},
+        {"DELRING", DELRING_CODE, 0x00000000, 0, NULL, simple_action},
+        {"REFRESH", REFRESH_CODE, 0x00000000, 0, NULL, simple_action},
+        {"HELP",    HELP_CODE,    0x00000000, 0, NULL, print_help},
+        {"NOTSUPPORTED", NOTSUPPORTED_CODE, 0x00000000, 0, NULL, print_help}
+    };
+
+    R_datalib_function function;
+    for (i = 0; i < sizeof(function_table)/sizeof(R_datalib_function); i++) {
+        if (strncasecmp(function_table[i].name, parms.function, sizeof(parms.function)) == 0) {
+            function = function_table[i];
+            break;
+        }
+        function = function_table[sizeof(function_table)/sizeof(R_datalib_function) - 1];
+    }
+    if (debug) {
+        printf("Selected function is %s with code of %.2X\n", function.name, function.code);
+    }
+    function.action(&p, &function, &parms);
+
+    return 0;
+}
+
+void simple_action(R_datalib_parm_list_64* rdatalib_parms, void * function, Command_line_parms* parms) {
+    R_datalib_function *func = function;
+    if (debug) {
+        printf("%s action\n", func->name);
+    }
+    set_up_R_datalib_parameters(rdatalib_parms, function, parms->userid, parms->keyring);
+    invoke_R_datalib(rdatalib_parms);
+    check_return_code(rdatalib_parms);
+}
+
+void delcert_action(R_datalib_parm_list_64* rdatalib_parms, void * function, Command_line_parms* parms) {
+    R_datalib_function *func = function;
+    R_datalib_data_remove *rem_parm = func->parmlist;
+
+    if (debug) {
+        printf("%s action\n", func->name);
+    }
+    rem_parm->label_len = strlen(parms->label);
+    rem_parm->label_addr = parms->label;
+    rem_parm->CERT_userid_len = 0x00;
+
+    set_up_R_datalib_parameters(rdatalib_parms, func, parms->userid, parms->keyring);
+    invoke_R_datalib(rdatalib_parms);
+    check_return_code(rdatalib_parms);
+    // refresh DIGTCERT class if required
+    if (rdatalib_parms->return_code == 4 && rdatalib_parms->RACF_return_code == 4 && rdatalib_parms->RACF_reason_code == 12) {
+        printf("DIGTCERT class has to refreshed.\n");
+        func->code = REFRESH_CODE;
+        set_up_R_datalib_parameters(rdatalib_parms, func, "", "");
+        invoke_R_datalib(rdatalib_parms);
+        check_return_code(rdatalib_parms);
+        printf("DIGTCERT class refreshed.\n");
+    }
+}
+
+void validate_and_set_parm(char * parm, char * cmd_parm, int maxlen) {
+    if (strlen(cmd_parm) <= maxlen) {
+        strcpy(parm, cmd_parm);
+    } else {
+        printf("ERROR: %s parm too long and will not be set.\n", cmd_parm);
+    }
+}
+
+void check_return_code(R_datalib_parm_list_64* p) {
+    if (p->return_code != 0 || p->RACF_return_code != 0 || p->RACF_reason_code != 0) {
+        printf("Function code: %.2X, SAF rc: %d, RACF rc: %d, RACF rsn: %d\n",
+            p->function_code, p->return_code, p->RACF_return_code, p->RACF_reason_code);
+    }
+}
+
+void process_cmdline_parms(Command_line_parms* parms, int argc, char** argv) {
+    int i;
+    for (i = 1; i < argc; i++) {
+        if (debug) {
+            printf("%d. parameter: %s\n", i, argv[i]);
+        }
+        switch(i) {
+            case 1:
+                validate_and_set_parm(parms->function, argv[i], MAX_FUNCTION_LEN);
+                break;
+            case 2:
+                validate_and_set_parm(parms->userid, argv[i], MAX_USERID_LEN);
+                break;
+            case 3:
+                validate_and_set_parm(parms->keyring, argv[i], MAX_KEYRING_LEN);
+                break;
+            case 4:
+                validate_and_set_parm(parms->label, argv[i], MAX_LABEL_LEN);
+                break;
+            default:
+                printf("WARNING: %i. parameter - %s - is currently not supported and will be ignored.\n", i, argv[i]);
+        }
+    }
+}
+
+void invoke_R_datalib(R_datalib_parm_list_64 * p) {
+
+    IRRSDL64(
+                &p->num_parms,
+                &p->workarea,
+                &p->saf_rc_ALET, &p->return_code,
+                &p->racf_rc_ALET, &p->RACF_return_code,
+                &p->racf_rsn_ALET, &p->RACF_reason_code,
+                &p->function_code,
+                &p->attributes,
+                &p->RACF_userid_len,
+                &p->ring_name_len,
+                &p->parm_list_version,
+                p->parmlist
+            );
+}
+
+void set_up_R_datalib_parameters(R_datalib_parm_list_64 * p, R_datalib_function * function, char * userid, char * keyring) {
+    memset(p, 0, sizeof(R_datalib_parm_list_64));
+    p->num_parms = 14;
+    p->saf_rc_ALET = 0;
+    p->racf_rc_ALET = 0;
+    p->racf_rsn_ALET = 0;
+    p->function_code = function->code;
+    p->attributes = function->default_attributes;
+    memset(&p->RACF_userid_len, strlen(userid), 1);
+    memcpy(p->RACF_userid, userid, strlen(userid));
+    memset(&p->ring_name_len, strlen(keyring), 1);
+    memcpy(p->ring_name, keyring, strlen(keyring));
+    p->parm_list_version = function->parm_list_version;
+    p->parmlist = function->parmlist;
+}
+
+void print_help(R_datalib_parm_list_64* rdatalib_parms, void * function, Command_line_parms* parms) {
+    printf("----------------------------------------------------\n");
+    printf("Usage: keyring-util function userid keyring label\n");
+    printf("----------------------------------------------------\n");
+    printf("function:\n");
+    printf("NEWRING - creates a new keyring.\n");
+    printf("DELRING - deletes a keyring\n");
+    printf("DELCERT - disconnects a certificate (label) from a keyring or deletes a certificate from RACF database\n");
+    printf("REFRESH - refreshes DIGTCERT class\n");
+    printf("HELP    - prints this help\n");
+}

bin/utils/keyring-util/keyring-util.h

@@ -0,0 +1,70 @@
+#ifndef _keyring_util
+#define _keyring_util
+
+#define MAX_FUNCTION_LEN 16
+#define MAX_USERID_LEN 8
+#define MAX_KEYRING_LEN 236
+#define MAX_LABEL_LEN 32
+
+#define NEWRING_CODE 0x07
+#define DELCERT_CODE 0x09
+#define DELRING_CODE 0x0A
+#define REFRESH_CODE 0x0B
+#define HELP_CODE  0x00
+#define NOTSUPPORTED_CODE 0x00
+
+
+typedef struct _Command_line_params {
+    char function[MAX_FUNCTION_LEN];
+    char userid[MAX_USERID_LEN + 1];
+    char keyring[MAX_KEYRING_LEN + 1];
+    char label[MAX_LABEL_LEN + 1];
+
+} Command_line_parms;
+
+typedef struct _R_datalib_parm_list_64 {
+	int num_parms;
+    double workarea[128];  // double word aligned, 1024 bytes long workarea
+    int saf_rc_ALET, return_code;
+    int racf_rc_ALET, RACF_return_code;
+    int racf_rsn_ALET, RACF_reason_code;
+    char function_code;
+    int  attributes;
+    char RACF_userid_len; // DO NOT change position of this field
+    char RACF_userid[MAX_USERID_LEN];  // DO NOT change position of this field
+    char ring_name_len;   // DO NOT change position of this field
+    char ring_name[MAX_KEYRING_LEN];  // DO NOT change position of this field
+    int  parm_list_version;
+    void *parmlist;
+} R_datalib_parm_list_64;
+
+typedef void (*function_action)(R_datalib_parm_list_64*, void*, Command_line_parms*);
+
+typedef struct _R_datalib_function {
+	char name[MAX_FUNCTION_LEN];
+    char code;
+    int default_attributes;
+    int parm_list_version;
+    void *parmlist;
+    function_action action;
+} R_datalib_function;
+
+typedef _Packed struct _R_datalib_data_remove {
+    int label_len;
+    int reserve_1;
+    char *label_addr;
+    char CERT_userid_len;  // DO NOT change position of this field
+    char CERT_userid[MAX_USERID_LEN];   // DO NOT change position of this field
+    char reserved_2[3];
+} R_datalib_data_remove;
+
+void invoke_R_datalib(R_datalib_parm_list_64*);
+void set_up_R_datalib_parameters(R_datalib_parm_list_64* , R_datalib_function* , char* ,char* );
+void simple_action(R_datalib_parm_list_64*, void*, Command_line_parms*);
+void delcert_action(R_datalib_parm_list_64*, void*, Command_line_parms*);
+void print_help(R_datalib_parm_list_64*, void*, Command_line_parms*);
+void process_cmdline_parms(Command_line_parms*, int , char**);
+void validate_and_set_parm(char*, char*, int);
+void check_return_code(R_datalib_parm_list_64*);
+
+#endif

bin/zowe-setup-certificates.env

@@ -34,5 +34,8 @@ KEYSTORE_DIRECTORY=/global/zowe/keystore
 KEYSTORE_ALIAS=localhost
 # Specify zowe user id to set up ownership of the generated certificates
 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 USS keystore
+# files will be created.
+ZOWE_KEYRING=