Secrets for Zowe SDK

(Co-author: Andrew Harn)

{Core} The Secrets SDK is a new package in the Open Mainframe Project Zowe for managing secure data, such as credentials or sensitive information. It can be found in the “packages” folder of the Zowe CLI repository and currently consists of one module named keyring. This module allows Zowe developers to interface with an end user’s credential vault. Developers of Zowe CLI plug-ins and Zowe Explorer (for VS Code) extenders should now use the keyring module instead of node-keytar.

Click here to access the Secrets SDK on GitHub.

For more information on supported architectures and operating systems, please refer to src/keyring/README.md.

Using Secrets SDK

To start using the Secrets SDK, install @zowe/secrets-for-zowe-sdk as a dependency using npm or your preferred package manager:

npm install @zowe/secrets-for-zowe-sdk

Import the keyring module from the Secrets SDK package in your code. The keyring module supports both CommonJS and ES6 import resolution:

const { keyring } = require("@zowe/secrets-for-zowe-sdk");
/* or, use ES6: */
import { keyring } from "@zowe/secrets-for-zowe-sdk";

The keyring module has four primary capabilities when interacting with credential data: set, get, find, and delete. In addition, this module’s exported functions match the function prototypes from node-keytar. Here is an example of accessing these functions through this module:

/* Sets the password for the given service and account */
await keyring.setPassword("Zowe", "secure_config_props");

/* Gets the password stored under the given service and account */
await keyring.getPassword("Zowe", "secure_config_props");

/* Finds all credentials, given a service pattern */
await keyring.findCredentials("Zowe");

/* Finds a password, given a service pattern */
await keyring.findPassword("Zowe/secure_config_props");

/* Deletes the password stored under the given service and account */
await keyring.deletePassword("Zowe", "secure_config_props");

Why use the Secrets SDK instead of keytar?

Keytar is a package developed by contributors to the Atom editor. This package allows programs to store and retrieve credentials in the user’s operating system keyring. It is the current credential storage technology behind Zowe CLI Secure Credential Store and VS Code.

For context: Although the Zowe community has an extension for IntelliJ IDEA, the Secrets SDK is designed to work with Zowe projects that use Node.js. We sometimes refer to Zowe Explorer (for VS Code) as “Zowe Explorer” in this article for brevity.

In June of 2022, a blog was published by GitHub that announced the sunsetting of the Atom organization and its repositories. At the time, the Zowe CLI and Zowe Explorer squads believed the keytar repository would migrate out of the Atom organization following the announcement. In November 2022, we began investigating alternatives to keytar in case the Atom organization would archive the component. On December 15, 2022, all Atom repositories, including node-keytar, were archived.

The keytar package remains available for download on NPM but is no longer maintained.

On June 20, 2023, an issue was opened on Zowe Explorer’s GitHub repository, alerting the team that VS Code will no longer provide keytar starting with their August release. This meant credential storage in Zowe Explorer and its extenders would cease to function after this update. We allocated additional resources to expedite the development of our replacement to minimize breakage for Zowe Explorer users and extenders.

The Zowe CLI team is also replacing keytar in all V1 and V2 packages with the new Secrets SDK. This SDK provides feature parity with the original keytar implementations while being actively maintained by Zowe CLI and Explorer teams.

How extenders may be affected

Zowe CLI plug-ins

Zowe CLI plug-ins that use the Imperative framework for loading and saving profiles should not be affected by this change. Changes to Zowe CLI will automatically support those plug-ins. Any plug-ins directly importing the node-keytar package should replace it with the new keyring module from the @zowe/secrets-for-zowe-sdk package. The replacement’s design allows backward compatibility with saved credentials from keytar.

Zowe Explorer (for VS Code) Extenders

Extenders for Zowe Explorer can continue using the existing credential APIs from zowe-explorer-api. Extenders that leverage Imperative’s credential manager APIs can continue using them. However, developers must prepare the Secrets SDK if their extension uses a JavaScript bundler (such as Webpack or ESbuild). This is because JavaScript bundlers do not support automatic bundling of Node-native binaries imported using a filesystem path.

Bundled Node.js packages: using Secrets SDK

To use the Secrets SDK as a direct dependency of a bundled package, developers must set up a prebuilds folder alongside the package root folder. This is a limitation of bundling Node-native binaries, as they cannot be embedded directly into the bundled code.

For example, if your Node.js package directory is named your-pkg and the build files are located in the out folder, your folder structure should look like this:

your-pkg/
├── package.json
├── src/
├── out/
│ └── bundle.js
├── prebuilds/
│ └── (node binaries for Secrets SDK)

Users can leverage a script that copies the prebuilt binaries from the Secrets SDK node_modules folder to this folder. Note that the following script only works with Node.js 16.7.0 and newer.

const { cpSync } = require("fs");
const { join } = require("path");
cpSync("/path/to/node_modules/@zowe/secrets-for-zowe-sdk/prebuilds", 
       "prebuilds"), { force: true, recursive: true });

To automate this script, save the above code as a JavaScript file (e.g., scripts/copyKeyringBinaries.js) and execute it with a “prepare” script in your package.json file:

{
    "scripts": {
        "prepare": "node scripts/copyKeyringBinaries.js"
    }
}

For Webpack and ESbuild users, consider using a “copy plug-in” instead to copy these binaries during the bundling process:

• Webpack: copy-webpack-plugin
• ESbuild: esbuild-copy-static-files

For an example of how to use the Webpack plug-in, see Zowe Explorer’s webpack.config.js file.

Migration utility

Some users of Zowe Explorer, specifically those who take advantage of the Remote Development extensions of VS Code, may be required to re-enter their credentials after the Secrets SDK migration is complete. If a user is required to re-enter their credentials, they will be prompted after interacting with a profile in Zowe Explorer. This is due to a fundamental change in storing secrets in a VS Code environment. Previously, the keytar shim provided by VS Code could store secure credentials on the local machine, sharing those credentials with the remote VS Code server when required. With the new change, credentials remain on the system with the Zowe Explorer extension installed, which would be the remote server during remote development.

Investigation into a proof-of-concept credential migration utility has begun, and preliminary results show that it is possible to migrate user credentials from a local system to a remote one if required. However, this migration utility needs another VS Code extension to access the local machine’s credentials, and it would only be advisable to keep the extension for as long as the migration process requires.

Individuals interested in such an extension to perform these migration functions should add a thumbs-up to this issue on the Zowe Explorer issue board: https://github.com/zowe/vscode-extension-for-zowe/issues/2429

Learn More

If you enjoyed this blog, check out more Zowe blogs here. Or, ask a question and join the conversation on the Open Mainframe Project Slack Channel #zowe-explorer, #zowe-cli, as well as #zowe-dev, #zowe-user, #zowe-api, or #zowe-onboarding.

If this is your first time using the Open Mainframe Slack Channel register here.