Configuration

Autogrpah's configuration is split between Service level configuration and authorization/signer configuration.

Service Configuration

The service configuration lives in autograph-service.yaml. Use the flag -c to provide an alternate path for service config.

Server

Define an address and port for the API to listen on and an optional HAWK nonce cache size to prevent replay attacks:

server:
    listen: "192.168.1.28:8000"
    noncecachesize: 524288
    idletimeout: 60s
    readtimeout: 60s
    writetimeout: 60s

Use flag -p to provide an alternate port and override any port specified in the config.

Database

Configure postgres using the sample below. Use the schema in database/schema.sql to initialize the db. Make sure to set a user with limited grants in the configuration.

database:
    name: autograph
    user: myautographdbuser
    password: myautographdbpassword
    host: 127.0.0.1:5432
    sslmode: full-verify
    sslrootcert: /etc/ssl/certs/db-root.crt
    maxopenconns: 100
    maxidleconns: 10
    monitorpollinterval: 10s
heartbeat:
    dbchecktimeout: 15ms

heartbeat.dbchecktimeout is how long the heartbeat handler should wait for the DB to return a response before erroring.

Hardware Security Module (HSM)

Several signers support key operations using an HSM. To configure it globally, set the following config where:

path is the file system path to a pkcs11 library
tokenlabel is set by the type of hsm (cavium for cloudhsm)
pin is the credentials to use the hsm ($user:$pass for cloudhsm)

hsm:
    # sample config for cloudhsm
    path:       /opt/cloudhsm/lib/libcloudhsm_pkcs11.so
    tokenlabel: cavium
    pin:        ulfr:e2deea623796eecd
heartbeat:
    hsmchecktimeout: 10ms

Refer to each signer's configuration doc to know how they each make use of the HSM.

heartbeat.hsmchecktimeout is how long the heartbeat handler should wait for the HSM to return a response before erroring.

GCP

Allows for the setting of a projectid to retrieve secret values from. Required for GCP Secret Manager support.

Signer and Auth Configuration

Signer and Auth configuration lives in the database in the signer, auth, and auth_signers tables. Autograph also supports loading certain sensitive data from GCP Secret Manager that is not storable in KMS/HSM.

Signers

The detailed configuration for each signer is described in their respective README under the autograph/signer/ directory.

Every signer is expected to have at least an id and type defined. See your specific signers documentation to know which properties need to be defined.

Example:

INSERT INTO signer(id, type, mode, comments, secret, public)
VALUES('apk_signer_for_focus', 'apk2', 'v3enabled', 'for focus android signing', 'apk-signer-focus-secrets', jsonb_build_object(
  'certificate', '-----BEGIN CERTIFICATE-----
NOT-REAL-CERT
-----END CERTIFICATE-----')
);

Authorizations

Authorizations map an arbitrary username and key to a list of signers. The key does not need to be generated in any special way. You can use openssl or the tool in tools/maketoken/main.go to obtain a random 256-bit string:

$ openssl rand -hex 32
ecf1dbcf7d8b161f51d7f590ea4a4eec8332918276ddcfc657fb0b863b2e37e7

Then add it to the auth and auth_signers tables in the database like:

INSERT INTO auth(id, key)
VALUES('alice', 'fs5wgcer9qj819kfptdlp8gm227ewxnzvsuj9ztycsx08hfhzu'),
('bob', '9vh6bhlc10y63ow2k4zke7k0c3l9hpr8mo96p92jmbfqngs9e7d');

INSERT INTO auth_signers(auth, signer)
VALUES('alice', 'appkey1'),
('alice', 'appkey2'),
('bob', 'appkey2');

The configuration above allows alice to request signatures from both appkey1 and appkey2, while bob is only allowed to request signatures from appkey2.

Note that, when a user is allowed to sign with more than one signer, and no specific signer key id is provided in the signing request, autograph will use the first signer in the list. For example, if alice requests a signature without providing a key id, the private key from appkey1 will be used to sign her request.

Secret Signer Data

You shouldn't store private key's or passphrases in the database. For things that cannot be stored in KMS/HSM but must be kept secure and have access audited, we support storing them in GCP Secret Manager.

Currently we support 'privatekey', 'passphrase', and 'issuerprivkey' values to be retrieved and mapped into the resulting signer config. The GCP Project Id needs to be defined in service config, then secret column value needs to point at a valid GCP secret.

Building and running

Build the autograph binary using make:

$ make install

The binary is located in $GOPATH/bin/autograph and can be started with the configuration file:

$ $GOPATH/bin/autograph -c autograph-service.yaml
{"Timestamp":1453721399358695130,"Type":"app.log","Logger":"Autograph","Hostname":"gator1","EnvVersion":"2.0","Pid":17287,"Fields":{"msg":"main.go:74: Starting Autograph API on localhost:8000"}}

You can test that the API is alive by querying its heartbeat URL:

$ curl localhost:8000/__heartbeat__
ohai

Test Key/Cert

For dev and testing purposes, the private key appkey1 can be used with the following self-signed certificate:

Navigation Menu

Repository navigation

configuration.md

configuration.md

Configuration

Service Configuration

Server

Database

Hardware Security Module (HSM)

GCP

Signer and Auth Configuration

Signers

Authorizations

Secret Signer Data

Building and running

Test Key/Cert

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

Configuration

Service Configuration

Server

Database

Hardware Security Module (HSM)

GCP

Signer and Auth Configuration

Signers

Authorizations

Secret Signer Data

Building and running

Test Key/Cert