Add support for Sigstore signing and verification (v2)

.gitignore

@@ -52,3 +52,7 @@ MANIFEST
 .venv*/
 .conda*/
 .python-version
+
+# ansible-sign files and directories
+/.ansible-sign/*
+/MANIFEST.in

docs/rundown.rst

@@ -230,6 +230,110 @@ If verification fails for any reason, some information will be printed to help
 you debug the cause. More verbosity can be enabled by passing the global
 ``--debug`` flag, immediately after ``ansible-sign`` in your commands.
 
+Signing and Verifying content with Sigstore
+===========================================
+
+``ansible-sign`` now supports signing and verifying projects using `Sigstore <https://www.sigstore.dev/>`_.
+Sigstore is a new standard for signing, verifying and protecting software.
+It allows developers to sign artifacts using a "keyless" signing flow and to store signing materials in a tamper-resistant transparency log.
+
+-----------------------
+How does Sigstore work?
+-----------------------
+
+Sigstore signs artifacts by authentifying signers via an OpenID Connect flow, redirecting them to an identity provider such as Google, Microsoft or GitHub.
+When a proof of identity is obtained from one of those providers, it is used to generate an ephemeral signing certificate with Sigstore's Certificate Authority `Fulcio <https://docs.sigstore.dev/fulcio/overview/>`_.
+The Sigstore client then uses this certificate and an ephemeral key pair to sign the artifact,
+and stores the signing materials in the `Rekor <https://docs.sigstore.dev/rekor/overview/>`_
+transparency log for everyone to verify the integrity and authenticity of the artifact signature.
+
+The ``ansible-sign`` command line uses the ``sigstore-python`` CLI under the hood, providing similar utilities,
+adapted to Ansible project signing.
+For further documentation about the different options available, refer to the `sigstore-python documentation <https://sigstore.github.io/sigstore-python/sigstore.html>`_
+or to the client `GitHub repository <https://github.com/sigstore/sigstore-python>`_.
+
+General documentation about Sigstore can be found on `docs.sigstore.dev <https://docs.sigstore.dev/>`_.
+
+------------------------------------------------------------------------
+Tutorial: signing and verifying content with `ansible-sign` and Sigstore
+------------------------------------------------------------------------
+
+The Sigstore signing utility is available under the `ansible-sign project sigstore-sign` subcommands.
+For more information about the different command line arguments available, use ansible-sign project sigstore-sign --help`.
+
+By default, ``ansible-sign`` will use the Sigstore public good instances of Fulcio, Rekor and of the OpenID Connect issuer.
+If you wish to connect to private instances of Sigstore, specify the corresponding URLs with the ``--rekor-url``, ``--fulcio-url`` and ``--oidc-issuer`` options.
+
+As for the GPG signing workflow, ``ansible-sign`` generates a file containing the checksums of files specified in the project ``MANIFEST.in`` under the ``.ansible-sign/`` directory
+and then signs this artifact file. The siging materials generated by Sigstore (bundled in a ``sha256sum.txt.sigstore`` file) are stored under the same directory.
+See the :ref:`Signing Content` section of the documentation for more information on how this manifest is generated.
+
+Different options exist to authentify with an OIDC provider:
+If no specific command line option is specified, Sigstore will first look for `ambient credentials <https://dlorenc.medium.com/a-bit-of-ambiance-comes-to-sigstore-f80d1d6b1c30>`_
+in the environment. This approach is well adapted to automated signing workflows, for example in the context of GitHub Actions.
+If no ambient credentials are found, the client will start an interactive browser session where the signer can authentify through
+a supported OIDC provider.
+It is also possible to directly pass an identity token obtained from an OIDC provider via the ``--identity-token`` command line option.
+
+Here is an example of the command output when using the interactive session method to authentify:
+
+.. code-block:: shell
+ :caption: Generating a checksum manifest file and signing it with Sigstore
+
+ $ ansible-sign project sigstore-sign .
+ Waiting for browser interaction...
+ Using ephemeral certificate:
+ -----BEGIN CERTIFICATE-----
+ MIICujCCAkGgAwIBAgIUEzqVrbrUo417s+8H0MsRrb9fAqcwCgYIKoZIzj0EAwMw
+ NzEVMBMGA1UEChMMc2lnc3RvcmUuZGV2MR4wHAYDVQQDExVzaWdzdG9yZS1pbnRl
+ cm1lZGlhdGUwHhcNMjMwMjA5MTAyNDAzWhcNMjMwMjA5MTAzNDAzWjAAMHYwEAYH
+ KoZIzj0CAQYFK4EEACIDYgAEBL9AcKhNxgzTRUz2OfhsW+Ipw7841Ct4gCRbpsZe
+ ipSIC0WATguVYyIhQR3T/bIZk+KbLeyhVx2oM6cMUcg342Lc/8UIL2rPini46yo2
+ A2hsZC2IVqgYPtKOA7u0NueBo4IBQzCCAT8wDgYDVR0PAQH/BAQDAgeAMBMGA1Ud
+ JQQMMAoGCCsGAQUFBwMDMB0GA1UdDgQWBBQkI8srmkuqcWkY/3lC9Z956oLVLDAf
+ BgNVHSMEGDAWgBTf0+nPViQRlvmo2OkoVaLGLhhkPzAhBgNVHREBAf8EFzAVgRNt
+ Y29zdGFudEByZWRoYXQuY29tMCkGCisGAQQBg78wAQEEG2h0dHBzOi8vYWNjb3Vu
+ dHMuZ29vZ2xlLmNvbTCBiQYKKwYBBAHWeQIEAgR7BHkAdwB1AN09MGrGxxEyYxke
+ HJlnNwKiSl643jyt/4eKcoAvKe6OAAABhjW0I/QAAAQDAEYwRAIgPkB9qTeaoPwn
+ 26r0KvDN/wkuHSa6tUYE5RMlmZpOY+kCIHOUROUVEQJxgWUFDWLm6bRmWdXCZ+gD
+ aqx+L0IYxCPEMAoGCCqGSM49BAMDA2cAMGQCMF+lOS9FZtYe5RsE08n6YmN4MTvE
+ OlUyiCqKyZJV4jjeSn5F+icnWOF3Z7XuOTyulAIwKh2iH6SEvT8LMvpkwag1ydy/
+ a9fNmx6YE1hue2QQPSkAvKTUoK2d+/i1RFyjt27G
+ -----END CERTIFICATE-----
+
+ Transparency log entry created at index: 12964841
+ Sigstore bundle written to /home/sample-project/.ansible-sign/sha256sum.txt.sigstore
+
+The signature materials are now written under the ``.ansible-sign/`` directory of your project and the entry created in the Rekor Transparency log. Congratulations!
+
+Let's now take a look at the different ways to verify a project signed with Sigstore.
+``ansible-sign`` will assume that the project signing materials are always located under ``.ansible-sign/``;
+this is why the command should specify the path of the project root when verifying a signature.
+
+The Sigstore verify options are available under the ``ansible-sign project sigstore-verify`` subcommand, either using ``ansible-sign project sigstore-verify identity``
+for projects signed by authentifying through an OIDC provider
+``or ansible-sign project sigstore-verify github`` for projects signed by a GitHub workflow.
+
+Verifying a project signature requires to pass the expected OIDC issuer and signer OIDC signer identity Sigstore expects to find on the signing certificate,
+respectively via the ``--cert-oidc-issuer`` and ``--cert-identity`` options.
+
+**Offline verification:** Sigstore supports offline verification of signatures, which means a verification without
+connecting to the Rekor instance where the signature entry was previously logged.
+This type of verification uses the Sigstore bundle ``sha256sum.txt.sigstore`` file generated while signing the artifact.
+and requires the ``--offline`` flag to be passed to the command.
+Note: while this type of verification is useful in disconnected environments, it is considered slightly weaker than the usual mode
+because it does not compute the `inclusion proof <https://github.com/google/trillian/blob/master/docs/TransparentLogging.md#inclusion-proofs-vs-promises>`_
+of the signature entry in the transparency log.
+
+.. code-block:: shell
+ :caption: Verifying the project signature with Sigstore
+
+ $ ansible-sign project sigstore-verify identity . --cert-identity [email protected] --cert-oidc-issuer https://accounts.google.com
+ OK: /home/sample-project/.ansible-sign/sha256sum.txt
+
+The output of the command shows that the checksums file signature was verified successfully.
+
+
 Notes About Automation
 ======================
 

setup.cfg

@@ -47,6 +47,9 @@ install_requires =
  importlib-metadata; python_version<"3.8"
  python-gnupg
  distlib
+ sigstore==2.1.2
+ sigstore-protobuf-specs~=0.2.0
+ cryptography
 
 
 [options.packages.find]