From 72248ef2ec2a37b2f9b5903fb075e2245a05bf64 Mon Sep 17 00:00:00 2001 From: Lukas Puehringer Date: Wed, 13 Mar 2024 17:56:52 +0100 Subject: [PATCH] Add signer API code docs introductory text The idea was to provide just enough detail to "get" the signer api at a glance. Finding the right words and the right level of detail was quite hard. But it's a start. My feeling is that the intro could use a little bit more detail, and the docstrings a little less. Plus there should be examples, and public methods in specific Signer and Key implementations need to be included Signed-off-by: Lukas Puehringer --- docs/signer.rst | 52 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/signer.rst b/docs/signer.rst index 316b880a..743cd4a4 100644 --- a/docs/signer.rst +++ b/docs/signer.rst @@ -3,12 +3,64 @@ Signer API .. currentmodule:: securesystemslib.signer +At its core the signer API defines abstract interfaces to create and verify +cryptographic signatures: + +* ``Signer.sign`` +* ``Key.verify_signature`` + +These interfaces can be implemented using arbitrary PKI technology. Many +default implementations are included. + +In addition, the API provides generic *load* methods for signers and public +keys: + +* ``Signer.from_priv_key_uri`` - to load a signer from a URI +* ``Key.from_dict`` - to load a public key from a serialized format + +These methods allow an application to use the exact same code, in order to load +any signer or public key, which implements above interface, independently of +the specific implementation. + +For a signer or public key implementation to become discoverable, it needs +to be *registered* in the corresponding lookup table: + +* ``SIGNER_FOR_URI_SCHEME`` +* ``KEY_FOR_TYPE_AND_SCHEME`` + +Usage +----- +The signer API is streamlined for the following series of user events, +which may happen on different systems and at different points in time: + +1. **Generate** key pair (signature provider -specific) + + Typically, this is done outside of the signer API, e.g. by using a Cloud KMS + web UI or an HSM console. + +2. **Configure** public key and signer access URI + + The public key for a signer must be available in the signing context, + in order to express its eligibility. + + Some of the existing signer implementations have methods to import a public + key from a signature provider and to build the related signer access URI. + + The public key can then be serialized with interface methods for use + in the signing context and in the verification context. + +3. **Sign**, given a configured public key and signer access URI + +4. **Verify**, given a configured public key + .. warning:: The API is experimental and may change without warning in versions ``<1.0.0``. See `'New Signer API' `_ blog post for background infos. +API documentation +----------------- .. Autodoc cannot resolve docs for imported globals (sphinx-doc/sphinx#6495) .. As workaround we reference their original internal definition.