kinto-signer 5.0.1

Content-Signature protocol

Kinto-signer produces signatures for the content of Kinto collections using ECDSA with the P-384 strength.

• The content is prepended with Content-Signature:\x00 prior to signing.

• The signature is produced with ECDSA on P-384 using SHA-384.

• The signature is returned as encoded using URL-safe variant of base-64.

See Content Signature

The content signature is validated in Firefox using the Personal Security Manager.

Notes on canonical JSON

The canonical_json() can be used in projects with:

pip install --no-deps kinto-signer

from kinto_signer.serializer import canonical_json

Specific to Kinto:

• The payload to be signed has two attributes: last_modified with the current timestamp as a string, data with the array of records.

• Records are sorted by ascending id

• Records with deleted: true are omitted

Standard canonical JSON:

• Object keys are sorted alphabetically

• No extra spaces in serialized content

• Double quotes are used

• Hexadecimal character escape sequences are used

• The alphabetical hexadecimal digits are lowercase

• Duplicate or empty properties are omitted

• NaN and Infinity are serialized as null

About numbers:

• Scientific notation is used for numbers < 10e-6 and >= 10e21

• Exponents use a lowercase e and have no leading zeros

• Only significant numbers are kept (no fractional zeros)

• Float are serialized with 8 significant numbers at most

>>> canonical_json([{'id': '4', 'a': '"quoted"', 'b': 'Ich ♥ Bücher'},
                    {'id': '1', 'deleted': true},
                    {'id': '26', 'a': ''}])

'[{"a":"","id":"26"},{"a":"\\"quoted\\"","b":"Ich \\u2665 B\\u00fccher","id":"4"}]'

• Gecko client side code

• ES6 Number#toString() to obtain similar output for floats

• See Internet-Draft Predictable Serialization for JSON Tools

• See jsesc to obtain similar output for escape sequences in JavaScript.

Configuration for the (default) ECDSA local signer

Configuration for the Autograph signer

Kinto signer can integrate with the Autograph server version 2. To do so, use the following settings:

Workflows

A workflow can be enabled on the source collection status.

The workflow is basically work-in-progress → to-review → to-sign → signed and makes sure that:

• the collection is reviewed before being signed

• the user asking for review is the not the one approving the review

• the user asking for review belongs to a group editors and the one approving the review belongs to reviewers.

See Kinto groups API for more details about how to define groups.

The above settings can be set or overriden by bucket using the <bucket_id>_ prefix or by collection using the <bucket_id>_<collection_id>_ prefix. For example:

kinto.signer.staging.group_check_enabled = true
kinto.signer.staging.to_review_enabled = true
kinto.signer.staging.certificates.group_check_enabled = false
kinto.signer.staging.certificates.to_review_enabled = false
kinto.signer.staging.certificates.reviewers_group = certificates-reviewers

If the review process is enabled, it is possible to configure a preview collection, that will be updated and signed when the status is set to to-review. This preview collection can be used by clients to test and validate the changes before approving them.

If a resources entry contains a semi-column separated triplet, then a preview collection will be enabled.

kinto.signer.resources =
    /buckets/staging            -> /buckets/preview            -> /buckets/blog
    /buckets/bid/collections/c1 -> /buckets/bid/collections/c2 -> /buckets/bid/collections/c3

The editors and reviewers groups are automatically created when the source collection is created.

Multiple certificates

Using above settings, every collections is signed with the same key. But it is also possible to define multiple signers, per bucket or per collection.

Settings can be prefixed with bucket id:

kinto.signer.signer_backend = kinto_signer.signer.autograph
kinto.signer.autograph.server_url = http://172.11.20.1:8888

kinto.signer.<bucket-id>.autograph.hawk_id = bob
kinto.signer.<bucket-id>.autograph.hawk_secret = a-secret

Or prefixed with bucket and collection:

kinto.signer.<bucket-id>.<collection-id>.signer_backend = kinto_signer.signer.local_ecdsa
kinto.signer.<bucket-id>.<collection-id>.ecdsa.private_key = /path/to/private.pem
kinto.signer.<bucket-id>.<collection-id>.ecdsa.public_key = /path/to/public.pem

Cloudfront CDN invalidation

When a request for review or approval is done, the changes are pushed to the preview or destination collection.

For the setups where those public collections are served behind a Cloudfront CDN, kinto-signer can take care of invalidating some paths.

kinto.signer.distribution_id = E155JIFUEHFGY

By default, it invalidates the whole CDN (/v1/*). But paths can be configured:

kinto.signer.invalidation_paths = /v1/buckets/{bucket_id}/collections/{collection_id}*
                                  /v1/buckets/monitor/collections/changes*
                                  /v1/blocklist/*

Tracking fields

During the review process, the source collection metadata will receive the following read-only fields:

• last_edit_by: last user to perform change on records in the source collection

• last_edit_date: date of the last records change

• last_review_request_by: last user to request a review

• last_review_request_date: date of the last review request

• last_review_by: last user to approve a review

• last_review_date: date of the last review approval

• last_signature_by: last user to trigger a signature

• last_signature_date: date of the last signature

Refresh signature

In order to refresh the signature, set the source to to-resign, the content signature metadata will be recomputed and updated and the status restore to its previous value (eg. signed or to-review…).

This is useful when the signer certificates are rotated etc.

echo '{"data": {"status": "to-resign"}}' | http PATCH http://0.0.0.0:8888/v1/buckets/source/collections/collection1 --auth user:pass