Notary signer configuration file
Estimated reading time: 5 minutesThis document is for those who are running their own Notary service who want to specify custom options.
Overview
Notary signer requires environment variables
to encrypt private keys at rest. It also requires a configuration file, the path to which is
specified on the command line using the -config
flag.
Here is a full signer configuration file example; click on the top level JSON keys to learn more about the configuration section corresponding to that key:
{
<a href="signer-config.md#server-section-required">"server"</a>: {
"http_addr": ":4444",
"grpc_addr": ":7899",
"tls_cert_file": "./fixtures/notary-signer.crt",
"tls_key_file": "./fixtures/notary-signer.key",
"client_ca_file": "./fixtures/notary-server.crt"
},
<a href="../common-configs/#logging-section-optional">"logging"</a>: {
"level": 2
},
<a href="signer-config.md#storage-section-required">"storage"</a>: {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "passwordalias1"
},
<a href="../common-configs/#reporting-section-optional">"reporting"</a>: {
"bugsnag": {
"api_key": "c9d60ae4c7e70c4b6c4ebd3e8056d2b8",
"release_stage": "production"
}
}
}
server section (required)
“server” in this case refers to Notary signer’s HTTP/GRPC server, not “Notary server”.
Example:
"server": {
"http_addr": ":4444",
"grpc_addr": ":7899",
"tls_cert_file": "./fixtures/notary-signer.crt",
"tls_key_file": "./fixtures/notary-signer.key",
"client_ca_file": "./fixtures/notary-server.crt"
}
Parameter | Required | Description |
---|---|---|
http_addr |
yes | The TCP address (IP and port) to listen for HTTP
traffic on. Examples:
|
grpc_addr |
yes | The TCP address (IP and port) to listen for GRPC
traffic. Examples:
|
tls_key_file |
yes | The path to the private key to use for HTTPS. The path is relative to the directory of the configuration file. |
tls_cert_file |
yes | The path to the certificate to use for HTTPS. The path is relative to the directory of the configuration file. |
client_ca_file |
no | The root certificate to trust for mutual authentication. If provided, any clients connecting to Notary signer need a client certificate signed by this root. If not provided, mutual authentication is not required. The path is relative to the directory of the configuration file. |
storage section (required)
This is used to store encrypted private keys. We only support MySQL or an in-memory store, currently.
Example:
"storage": {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "passwordalias1"
}
Parameter | Required | Description |
---|---|---|
backend |
yes | Must be "mysql" or "memory" .
If "memory" is selected, the db_url
is ignored. |
db_url |
yes if not memory |
The
the Data Source Name used to access the DB.
(include parseTime=true as part of the DSN) |
default_alias |
yes if not memory |
This parameter specifies the alias of the current
password used to encrypt the private keys in the DB. All new
private keys are encrypted using this password, which
must also be provided as the environment variable
NOTARY_SIGNER_<DEFAULT_ALIAS_VALUE> .
See the environment variable
section for more information. |
Environment variables (required if using MySQL)
Notary signer stores the private keys in encrypted form. The alias of the passphrase used to encrypt the keys is also stored. In order to encrypt the keys for storage and decrypt the keys for signing, the passphrase must be passed in as an environment variable.
For example, the configuration above specifies the default password alias to be
passwordalias1
.
If this configuration is used, then you must:
export NOTARY_SIGNER_PASSWORDALIAS1=mypassword
so that that Notary signer knows to encrypt all keys with the passphrase
mypassword
, and to decrypt any private key stored with password alias
passwordalias1
with the passphrase mypassword
.
Older passwords may also be provided as environment variables.
Let’s say that you wanted to change the password that is used to create new keys (rotating the passphrase and re-encrypting all the private keys is not supported yet).
You could change the config to look like:
"storage": {
"backend": "mysql",
"db_url": "user:pass@tcp(notarymysql:3306)/databasename?parseTime=true",
"default_alias": "passwordalias2"
}
Then you can set:
export NOTARY_SIGNER_PASSWORDALIAS1=mypassword
export NOTARY_SIGNER_PASSWORDALIAS2=mynewfancypassword
That way, all new keys are encrypted and decrypted using the passphrase
mynewfancypassword
, but old keys that were encrypted using the passphrase
mypassword
can still be decrypted.
The environment variables for the older passwords are optional, but Notary Signer cannot decrypt older keys if they are not provided, and attempts to sign data using those keys fail.