Notation directory structure for system configuration

Notation CLI requires local file systems support for the following components. They should be stored in different places per different operating system.

• Notation binary
• Plugins
• Configurations
• Trust stores
• Trust policies
• Signing key store

This documentation specifies the recommended directory structure for those components.

Category

The directories for various components are classified into the following catagories.

On Unix systems, notation follows XDG Base Directory Specification for user level directories. On Windows, Known Folders and App Settings are followed equivalently. On Darwin, macOS File System with System Integrity Protection is followed equivalently.

User Level

Default directory paths for various operating systems at user level are specified as below.

There is no default NOTATION_BIN path at user level since the notation binary can be put anywhere as long as it in the PATH environment variable. Common directories on Unix/Darwin are ~/bin and ~/.local/bin where manual PATH update by users may be required.

Structure

The overall directory structure for notation is summarized as follows.

{NOTATION_BIN}
└── notation

{NOTATION_CONFIG}
├── config.json
├── localkeys
│   ├── {key-name}.crt
│   └── {key-name}.pem
├── signingkeys.json
├── trustpolicy.json
└── truststore
    └── {trust-store-type}
        └── {named-store}
            └── {cert-file}
{NOTATION_LIBEXEC}
└── plugins
    └── {plugin-name}
        └── notation-{plugin-name}

Notation Binary

The path for the notation binary is as follows.

{NOTATION_BIN}/notation

On Windows, the .exe extension is required for executables.

{NOTATION_BIN}/notation.exe

Plugin

Plugins are binaries not meant to be executed directly by users' shell or scripts. The path of a plugin follows the pattern below.

{NOTATION_LIBEXEC}/plugins/{plugin-name}/notation-{plugin-name}

On Windows, the .exe extension is required for executables.

{NOTATION_LIBEXEC}/plugins/{plugin-name}/notation-{plugin-name}.exe

General Configuration

The path of the general configuration file of the notation CLI is as follows.

{NOTATION_CONFIG}/config.json

Trust Store

The path of a certificate file in a Trust Store follows the pattern of below

{NOTATION_CONFIG}/truststore/{trust-store-type}/{named-store}/{cert-file}

Trust Policy

The path of the Trust Policy file is as follows.

{NOTATION_CONFIG}/trustpolicy.json

Signing Key Store

Developers sign artifacts using local private keys with associated certificate chain. The signing key information is tracked in a JSON file at:

{NOTATION_CONFIG}/signingkeys.json

The signing key store is user-specific. Developers SHOULD consider safe places to store the passphrase-protected key and certificate pairs, or opt to remote signing.

For testing purpose, the following directory structure is suggested.

{NOTATION_CONFIG}/localkeys/{key-name}.crt
{NOTATION_CONFIG}/localkeys/{key-name}.pem

Since signingkeys.json takes references in absolute paths, it is not required to copy the private keys and certificates used for signing to the above directory structure.

Examples

Examples are shown on various operating systems where the user exampleuser overrides the notation config and the trust policy.

Unix

/
└── home
   └── exampleuser
       └── .config
           └── notation
               ├── config.json
               ├── localkeys
               │   ├── dev.crt
               │   ├── dev.pem
               │   ├── test.crt
               │   └── test.pem
               ├── plugins
               │   └── com.example.bar
               │       └── notation-com.example.bar
               ├── signingkeys.json
               ├── trustpolicy.json
               └── truststore
                   └── x509
                       ├── ca
                       │   └── acme-rockets
                       │       └── cert4.pem
                       └── tsa
                           └── publicly-trusted-tsa
                               └── tsa-cert2.pem

Windows

C:.
└── Users
    └── exampleuser
        └── AppData
            └── Roaming
                └── notation
                    ├── config.json
                    ├── localkeys
                    │   ├── dev.crt
                    │   ├── dev.pem
                    │   ├── test.crt
                    │   └── test.pem
                    ├── plugins
                    │   └── com.example.bar
                    │       └── notation-com.example.bar.exe
                    ├── signingkeys.json
                    ├── trustpolicy.json
                    └── truststore
                        └── x509
                            ├── ca
                            │   └── acme-rockets
                            │       └── cert4.pem
                            └── tsa
                                └── publicly-trusted-tsa
                                    └── tsa-cert2.pem

Darwin / macOS

/
└── Users
   └── exampleuser
       └── Library
           └── Application Support
              └── notation
                  ├── config.json
                  ├── localkeys
                  │   ├── dev.crt
                  │   ├── dev.pem
                  │   ├── test.crt
                  │   └── test.pem
                  ├── plugins
                  │   └── com.example.bar
                  │       └── notation-com.example.bar
                  ├── signingkeys.json
                  ├── trustpolicy.json
                  └── truststore
                      └── x509
                          ├── ca
                          │   └── acme-rockets
                          │       └── cert4.pem
                          └── tsa
                              └── publicly-trusted-tsa
                                  └── tsa-cert2.pem