To understand using KeyRing, below is a walkthrough given a specific example. For this example, I'm targeting Joe Smith, VP of Marketing at Evil Corp (E-Corp). During OSINT, I've found the following information for my target:

• E-Corp username scheme is (First Initial)(Last Name): JSmith
• Target uses Photoshop and we know this file path exists: C:\Program Files\Adobe\Adobe Photoshop CC 2019\Photoshop.exe

Unfortunately, that is all the information we were able to discover.

We're going to be using a JScript based payload, eventually we'll be sticking it within an HTA file. So a prerequisite will be the raw JScript stage0 payload, maybe from Empire or somewhere else.

See the README.md page to get KeyRing on your system

Start with ./keyring --help to get a handle on what options there are.

Since KeyRing is config file based, we will go ahead and grab the example config from the ./examples/ directory to edit (./examples/js-config.yml). Set the payloadFile to the raw JS payload from the Prerequisites section and the outputFile to the desinated filename to stored the keyed payload.

Also, at the bottom of the file, notice the retries and sleep settings? This is useful if your using HTTP and/or DNS keying, as maybe we want the payload to keep retrying the possible keys to decrypt over and over again. If you set retries to 0, then this functionality will be removed (regardless of what sleep is set to). Since we won't be using HTTP or DNS keying for this example, we'll keep retries at 0.

Now we just need to figure out the keyers: section...

The example config shows a couple of environment variable keyers and shows the structure of how a keyer function should be indicated in a config file. Essentially, this structure is as follows:

  -
    name: <keyer ID>
    inputs:
      - <input 1>
      - <input N>
    keydata: <result from function to add to final key>

Ok, so how do we figure out how to add more keyers or even what keyers are supported?

keyring --list-keyers <lang> will display all the supported keyers for a given lang (keyring --list-langs will show you all supported langs). For this situation, we'll be listing supported keyers for jscript. As listed in the scenario, we need an environmental variable keyer (which we already have in the config file), along with a file path.

This is a clipping from the --list-keyers jscript which may be what we need.

<SNIP>
    - directory (File/Folder Paths)
	Encrypts based on a folder or file path accessible to the host. Spiders all files
<SNIP>

This looks like the keyer we need. When listing all the supported keyers, the value right after the dash (-) is the keyer ID. In the clipping above, the keyer ID would be directory.

We now know that directory is a keyer we need to add to our config file, but how? Using the --help-keyer <lang>/<keyer> command line switch we can get more information.

Below is the results of running ./keyring --help-keyer jscript/directory

Keyer: directory
	File/Folder Paths
Type: chain
Number of inputs: 2
Input 1: The directory to start spidering from
    ex) C:\Users
Input 2: How far down the directory structure to go
    ex) 5

Nice, so looks like this keyer will encrypt on the filepath we have. And to "hide" which filepath we use in the keyed payload, the keyed code will spider through all recursive file/folder paths underneath a directory and try each one on the target system. The filepath we are using to encrypt with should be within that directory.

Ok, so looking at the help for the keyer, it looks like this keyer function uses 2 inputs and is a chain function. Below is how I applied the information into our config file, matching the Photoshop file path above.

  -
    name: directory
    inputs:
      - C:\Program Files
      - 10
    keydata: C:\Program Files\Adobe\Adobe Photoshop\Photoshop.exe

So we will recursively receive all file and folder paths underneath C:\Program Files, stopping 10 directories deep. The file path for Photoshop.exe will be added to the key data.

As noted above, we only really found two pieces of data we could use to create our keyed payload. Let's throw in some benign keyer functions to make it appear more complex.

Below I've added two more environment variables to key off of, but the keydata: is blank, which means it will not be used for the key.

  -
    name: envkey
    inputs:
      - COMPUTERNAME
    keydata:
  -
    name: envkey
    inputs:
      - USERPROFILE
    keydata:

Alright, our config file should be all set! Let's take a look at what our final config file would look like. Important note: All keydata values are forced lowercase, so nothing to worry about for casing.

language: jscript
payloadFile: ourstealthydropper.js
outputFile: keyed.js
keyers:
  -
    name: envkey
    inputs:
      - USERNAME
    keydata: JSmith
  -
    name: directory
    inputs:
      - C:\Program Files
      - 10
    keydata: C:\Program Files\Adobe\Adobe Photoshop\Photoshop.exe
  -
    name: envkey
    inputs:
      - COMPUTERNAME
    keydata:
  -
    name: envkey
    inputs:
      - USERPROFILE
    keydata:
retries: 0
sleep: 0

Finally, we can run ./keyring --config js-config.yml to generate our keyed payload!