Skip to content

Latest commit

 

History

History
96 lines (72 loc) · 4.41 KB

README.md

File metadata and controls

96 lines (72 loc) · 4.41 KB
Raw

Secretless Plugins

Secretless plugins allow you to extend the functionality of Secretless beyond the currently supported built-in plugins.

Currently Supported Plugin Types

Secretless supports plugins for the following internal components:

External Plugin Basics

Secretless uses Go plugins.

If you've never used Go plugins before, a good introduction to them is here. Essentially, to write a Secretless plugin you'll write normal Go functions but compile them using -buildmode=plugin. This produces a shared object library file (with a .so extension) instead of a normal executable.

Technically, a Secretless plugin is a Go shared library file that implements some predefined functions. For more information on what you need to implement to build a plugin, please see the README for the specific plugin type you are building.

Plugin Metadata

Regardless of plugin type, each plugin must supply Secretless with some essential metadata. To do this, each plugin must implement the PluginInfo function. This top level function is always required and it returns basic information about your plugin. Its signature is:

func PluginInfo() map[string]string

The returned map must have the following keys:

  • version: The version of the plugin itself. This allows plugin authors to version the plugins they write.
  • pluginAPIVersion: The version of the Secretless plugin API that your plugin is written for. This allows the Secretless plugin API to change over time without breaking plugins.
  • type: This must be a supported plugin type. Currently, it must be either the string "connector.tcp" or the string "connector.http".
  • id: A short, clear, unique name for use in logs and the secretless.yml config file. Allowed characters are: lowercase letters, _, :, -, and ~.
  • description: A short summary of the plugin, not to exceed 100 characters. This may be used in the future by the Secretless command line tool to list available plugins.

External Plugin Basics

When running Secretless with external plugins, you can leverage some special command-line flags when starting Secretless:

  • -p flag: Specifies the directory in which the external plugins shared library (".so") files live.. Defaults to /usr/local/lib/secretless. Sub-directory traversal is not supported at this time.
  • -s flag: Refers to a file that contains sha256sum plugin checksums for verifying the plugins.

When Secretless starts, it:

  • Checks for available external plugins (eg ".so" files) in the plugin directory.
  • Verifies external plugin checksums (if a checksum file was provided on start).
  • Loads the external plugin. For each plugin file Secretless:
    • Opens the Go plugin file.
    • Parses PluginInfo for plugin metadata.
    • Verifies that the plugin type supplied in PluginInfo is supported.
    • Loads the plugin into the list of plugins to run.

From there, the startup process continues and external plugins are treated the same as internal plugins.

Building the Shared Library File

To build your plugin's shared library (.so) file, follow the instructions for building Go plugins.

For example, to compile your plugin code into a .so file, run the following command:

go build -buildmode=plugin -o=/path/to/my-plugin.so my_plugin.go

Once you've done this, place the .so file in the /usr/local/lib/secretless directory in the container where Secretless will run (or in another directory you specify using the -p flag). That's all you have to do. The .so files are self-contained and include any dependencies that you've imported.

Note: .so plugin files must be placed directly in /usr/local/lib/secretless (or the directory you specify). Sub-directories of the plugin folder are not searched.

Plugin Checksum Verification

Plugins can be secured by a checksum file to prevent injection attacks. We recommend all production deployments use this feature. Find out more here.