Allow configuration dir to be overridden

[jeremyrickard]

What is the areas you would like to add the new feature to?

Notation CLI

Is your feature request related to a problem?

Currently, the notation CLI defaults to using os.UserConfigDir from notation-go dir/path via cmd/notation/verify.go and notation-go verifier/trustpolicy/trustpolicy.go

On MacOS, this ends up being $HOME/Library/Application Support which isn't extremely obvious and is super varied based on system:

// On Unix systems, it returns $XDG_CONFIG_HOME as specified by
// https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html if
// non-empty, else $HOME/.config.
// On Darwin, it returns $HOME/Library/Application Support.
// On Windows, it returns %AppData%.
// On Plan 9, it returns $home/lib.

What solution do you propose?

It would be nice if this value could be overridden with an environment variable, so a user could support multiple configurations (as with docker or kubectl) or could more easily store things in their home directory (os.UserHomeDir) on non linux based operating systems.

What alternatives have you considered?

There could be multiple other avenues for this but an environment variable seems the most flexible.

Some alternatives could be:

1. A new configuration flag. This would be extremely cumbersome from a user experience stand point.
2. Changing the value to use os.UserHomeDir instead. This wouldn't provide flexibility and would not incorporate the original reason for using os.UserConfigDir

Any additional context?

No response

[yizha1]

@JeyJeyGao PTAL, /cc: @shizhMSFT

[JeyJeyGao]

Hi @jeremyrickard, sorry for late reply. Currently, you can use those environment variables for each platform to override the config directory as you mentioned, which is by designed. The Notation cli will add a trust policy command to manage the trustpolicy.json file, so you may don't need modify the files under notation config directory manually. As a result, I prefer to keep the current UX and decide to whether optimize the directory experience after the CLI command has been completed.

[jeremyrickard]

@JeyJeyGao you can you an environment variable to override the config directory? I couldn't find documentation for that so it might be useful to document how this is done?

I tried to determine by looking at code:

// NewFromConfig returns a verifier based on local file system
func NewFromConfig() (notation.Verifier, error) {
	// load trust policy
	policyDocument, err := trustpolicy.LoadDocument()
	if err != nil {
		return nil, err
	}
	// load trust store
	x509TrustStore := truststore.NewX509TrustStore(dir.ConfigFS())

	return New(policyDocument, x509TrustStore, plugin.NewCLIManager(dir.PluginFS()))
}

and

// LoadDocument loads a trust policy document from a local file system
func LoadDocument() (*Document, error) {
	jsonFile, err := dir.ConfigFS().Open(dir.PathTrustPolicy)
	if err != nil {
		return nil, err
	}
	defer jsonFile.Close()
	policyDocument := &Document{}
	err = json.NewDecoder(jsonFile).Decode(policyDocument)
	if err != nil {
		return nil, err
	}
	return policyDocument, nil
}

It wasn't clear how a user could override today.

Documentation for the notation CLI would be beneficial for this.

[JeyJeyGao]

Hi @jeremyrickard , are you a CLI user? or notation-go library user?
For CLI user, you can modify the environment variable based on per OS to change the notation config directory

OS	Directory
Unix	$XDG_CONFIG_HOME/notation
Windows	%AppData%/notation
Darwin	$HOME/Library/Application Support/notation

For example, you are a MacOS user, you can create a path <Your prefered directory>/Application Support/notation and update $HOME to be <Your prefered directory>, then you can override the notation directory to be your custom directory. However, it is not recommanded to change the default directory. Different OSes may have different policies to manage the configuration files, so put them in the OS prefered directory is rational.

For a Notation-go user, you can update the package variable dir.UserConfigDir to be your custom directory.

[ningziwen]

I could identify a use case of overriding NOTATION_CONFIG and NOTATION_LIBEXEC, basically giving users more flexibility.

Assuming in Unix, I want to customize my config path and plugin path. The only way of doing it is to override $XDG_CONFIG_HOME. This works if I directly use notation.

However, if I want to integrate notation to my application and let my users customize their notation configs, the only safe way is exposing something like $NOTATION_HOME in my application and translate it to $XDG_CONFIG_HOME when calling notation, which is cumbersome. Directly exposing $XDG_CONFIG_HOME for notation is not safe because $XDG_CONFIG_HOME may be also used for other configs in my application.

I posted a quick PR for discussion notaryproject/notation-go#279 and happy to discuss different thoughts. @JeyJeyGao

[JeyJeyGao]

Currently, we are improving user experience of notation CLI. After the improvement, the user can add trust policy or add plugin by cli command, so the user don't need to manipulate the configuration directory by themselves and don't need to be care about where is the config directory.

If the user uses notation-go library, they can easily change the UserConfigDir or UserLibexecDir to be prefered directories.

Also, adding those environment variables is risky. The behavior of notation is extensively decided by configuration files which can be overridden by environment variables. I'm not sure is this the right way to do it.

[ningziwen]

Got it. The use case is the downstream software using Notation as dependency may want to separate their user data from the normal Notation's user data to keep a clear trust boundary. Does this imply that the downstream software using Notation as dependency should use notation-go instead of notation CLI?

[shizhMSFT]

Got it. The use case is the downstream software using Notation as dependency may want to separate their user data from the normal Notation's user data to keep a clear trust boundary. Does this imply that the downstream software using Notation as dependency should use notation-go instead of notation CLI?

Downstream software should use notation-go if it is written in Go. Otherwise, notation CLI binary should be used since we currently don't have libraries for other languages.

[ningziwen]

The macOS path is a bit complicated. $HOME/Library/Application Support/notation

Is there a specific reason to make Library/Application Support part of path instead of some simple paths like $HOME/.notation?

I have the solution of dealing with Library/Application Support in my use case but it needs some additional logic.

If notation is open to simply the macOS path, I'm happy to help. If notation has a specific reason of keeping the long path, I'm happy to learn and add the addtional logic of dealing with Library/Application Support in my use case.

@JeyJeyGao @shizhMSFT