From f9a3879d995a28e139f43bf8493135014b5db519 Mon Sep 17 00:00:00 2001 From: Peter Amstutz Date: Fri, 17 May 2024 06:44:26 -0400 Subject: [PATCH] PR to add "secret" field to input parameters. --- CommandLineTool.yml | 4 ++++ Process.yml | 55 +++++++++++++++++++++++++++++++++++++++++++++ Workflow.yml | 5 +++++ 3 files changed, 64 insertions(+) diff --git a/CommandLineTool.yml b/CommandLineTool.yml index 604c668..ce15754 100644 --- a/CommandLineTool.yml +++ b/CommandLineTool.yml @@ -51,6 +51,10 @@ $graph: ## Changelog for v1.3.0-dev1 + * Added `secret` option on [input parameters](#InputParameter) + to request special handling of secrets such as passwords and + API tokens. + See also the [CWL Workflow Description, v1.3.0-dev1 changelog](Workflow.html#Changelog). For other changes since CWL v1.0, see the [CWL Command Line Tool Description, v1.1 changelog](https://www.commonwl.org/v1.1/CommandLineTool.html#Changelog) diff --git a/Process.yml b/Process.yml index 53f877c..1dd3c8d 100644 --- a/Process.yml +++ b/Process.yml @@ -772,6 +772,61 @@ $graph: from the input object, or if the value of the parameter in the input object is `null`. Default values are applied before evaluating expressions (e.g. dependent `valueFrom` fields). + - name: secret + type: ["null", boolean, string] + doc: | + Indicates this input parameter value is sensitive. + Implementations should apply special handling to secret values + to avoid displaying them in logs, including them in output, or + otherwise making them visible or accessible in any way beyond + what is required to make the value of the secret input + parameter available to workflow processes that need it. + + This feature is intended to provide a safer way to handle + credentials such as passwords and API tokens. + + Possible values of the `secret` field can be: + + * null or not provided (default, the input parameter is not secret) + * false (same as null) + * true (parameter is secret) + * a non-empty string (parameter is secret, and may be looked up in platform storage) + + If the value of `secret` is a string, this is a lookup key to + be used to fetch a secret value from the workflow platform + secret store. This assumes a model where a non-sensitive + lookup key is passed to the secret store and a sensitive + string value (the password, API token, etc) is returned. + + The format of this lookup key, as well as management, access + permissions, and authentication for the secret store are + implementation specific and out of scope for this document. + + If the input parameter is a secret, the `type` of the input + parameter must only consist of `string`, `array`, or + `null`. + + If `secret` is a string and the platform supports looking up + credentials, the input parameter is implicitly optional for + the caller, and platform should look up the secret to fill in + the input parameter value when not provided by the caller. + + An explict value provided by the caller always takes + precidence over looking up a value, i.e. checking the secret + store must only happen if the caller did not provide an + explicit value for this secret parameter, or the value is + null. + + If the platform does not support secrets lookup, a string + value of `secret` is treated like boolean true, indicating the + parameter is secret, but must be provided in the input + document (unless marked as optional). + + Failure to look up the secret (for example, due to denial of + access) may yield a value of "null". Execution continues only + if the parameter is optional (i.e. "null" is an accepted + type). However implementations may, at user option, treat + failure to look up a secret as a fatal error. - name: OutputParameter diff --git a/Workflow.yml b/Workflow.yml index 176de9a..5f94063 100644 --- a/Workflow.yml +++ b/Workflow.yml @@ -40,6 +40,11 @@ $graph: CWL group. ## Changelog + + * Added `secret` option on [input parameters](#InputParameter) + to request special handling of secrets such as passwords and + API tokens. + See also the [CWL Command Line Tool Description, v1.3.0-dev1 changelog](CommandLineTool.html#Changelog). For other changes since CWL v1.0, see the [CWL Workflow Description, v1.1 changelog](https://www.commonwl.org/v1.1/Workflow.html#Changelog)