{"id":20314506,"url":"https://github.com/release-engineering/pubtools-sign","last_synced_at":"2026-01-29T05:05:33.783Z","repository":{"id":174998272,"uuid":"638079060","full_name":"release-engineering/pubtools-sign","owner":"release-engineering","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-26T11:24:14.000Z","size":941,"stargazers_count":0,"open_issues_count":5,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-08-26T14:47:01.271Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://release-engineering.github.io/pubtools-sign/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/release-engineering.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-09T03:20:54.000Z","updated_at":"2025-08-26T11:23:23.000Z","dependencies_parsed_at":"2024-01-08T08:26:10.735Z","dependency_job_id":"b6f3cc39-5459-4789-9361-f0a06b50d071","html_url":"https://github.com/release-engineering/pubtools-sign","commit_stats":null,"previous_names":["release-engineering/pubtools-sign"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/release-engineering/pubtools-sign","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fpubtools-sign","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fpubtools-sign/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fpubtools-sign/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fpubtools-sign/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/release-engineering","download_url":"https://codeload.github.com/release-engineering/pubtools-sign/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/release-engineering%2Fpubtools-sign/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273213951,"owners_count":25065059,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T18:15:38.520Z","updated_at":"2026-01-29T05:05:28.762Z","avatar_url":"https://github.com/release-engineering.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"===============\n pubtools-sign\n===============\n\nSet of scripts used for signing artifacts via configured signers \n\n\nRequirements\n============\n\n* Python 3.7+\n\nSetup\n=====\n\n.. code-block:: bash\n\n  $ pip install -r requirements.txt\n  $ pip install . \n  or\n  $ python setup.py install\n\nFor specific signers you may also need to install some additional dependencies.\nCosign signer requires `cosign` binary to be installed and available in PATH.\nMsgSigner requires following python packages to be installed:\n\n- pyOpenSSL\n- python-qpid-proton\n\n  note that for ssl support python-qpid-proton must be compiled with ssl support,\n  it might be better to install it via system package manager\n\nSupported signers\n=================\n* Cosign\n* MsgSigner\n\nUsage\n=====\n\n.. code-block:: bash\n\n  $ pubtools-sign --help\n  $ pubtools-sign cosign-container-sign --help\n  $ pubtools-sign msg-clear-sign --help\n  $ pubtools-sign msg-container-sign --help\n\n\nCosign container signing\n========================\n\nCosign container signier sign provided container images and digests with `cosign`.\nExample of usage:\n\n.. code-block:: bash\n\n  $ pubtools-sign cosign-container-sign --signing-key signing-key \\\n      --config-file ~/.config/pubtools-sign/conf.yaml \\\n      --reference internal-registry/prod/repository:latest \\\n      --digest sha256:1a452c013d37a60014c5506c4230d5b85686b106f1b7dbd9b93fc44f87a12643 \\\n      --identity public-registry.com/repository:latest \\\n      --task-id t-1\n\nOutput:\n\n.. code-block:: none\n\n  {\"signer_result\": {\"status\": \"ok\", \"error_message\": \"\"},\n   \"operation_results\": [\"Pushing signature to: internal-registry/prod/repository:latest\\n\"],\n   \"operation\": {\n      \"digests\": [\"sha256:1a452c013d37a60014c5506c4230d5b85686b106f1b7dbd9b93fc44f87a12643\"],\n      \"references\": [\"internal-registry/prod/repository:latest\"],\n      \"signing_key\": \"signing-key\",\n      \"task_id\": \"t-1\"}, \n   \"signing_key\": \"signing-key\"}\n\nThe command will sign mentioned container image provided by reference and digest with provided key.\nProduced signature will be pushed to the same registry as the image. Credentials which are use to \nauthenticate to the registry are taken from standard container configuration files (e.i. `~/.docker/config.json`). Identity set in the command will be stored in the signature itself. With that container images can be verified against public registry.\n\nVerification\n------------\nTo verify the signature, adjust container configuration in `/etc/containers/registries.d/registry.yaml` to \nhave `use-sigstore-attachments: true`. Example:\n\n.. code-block:: yaml\n\n  docker:\n    example-registry.com:\n      use-sigstore-attachments: true\n\nThen in `/etc/containers/policy.json` add following policy:\n\n.. code-block:: none\n\n  {\n    \"default\": [\n      {\n        \"type\": \"insecureAcceptAnything\"\n      }\n    ],\n    \"transports\": {\n      \"docker\": {\n        \"example-registry.com\": [\n          {\n            \"type\": \"sigstoreSigned\",\n            \"keyPath\": \"path-to-public-key\",\n            \"signedIdentity\": {\n              \"type\": \"matchRepoDigestOrExact\"\n            }\n          }\n        ]\n      }\n    }\n  }\n\nMore info about policy file can be found here:\nhttps://github.com/containers/image/blob/main/docs/containers-policy.json.5.md\n\nMessaging signing\n=================\nExample of usage:\n\n.. code-block:: bash\n  \n  $ pubtools-sign-msg-container-sign --digest sha256:123456 \\\n    --reference registry.com/repository:latest \\\n    --signing-key signing-key \\\n    --task-id task-1 \\\n    --digest sha256:123456\n\nOutput:\n\n.. code-block:: none\n\n  {\"signer_result\": {\"status\": \"ok\", \"error_message\": \"\"},\n   \"operation_results\": [\n      [\n        \u003cmessage\u003e,\n        \u003cmessage-headers\u003e\n      ]\n  ],\n  \"operation\": {\n    \"digests\": [\"sha256:123456\"],\n    \"references\": [\"registry.com/repository:latest\"],\n    \"signing_key\": \"signing-key\",\n    \"task_id\": \"task-1\"\n  },\n  \"signing_key\": \"signing-key\"\n  }\n\nMessaging signer is used to send requests to signing server via messaging brorker. Every reference + digest is send in separate message with following format:\n\n.. code-block:: none\n\n  {\n    \"sig_key_id\": \u003csigning-key\u003e,\n    \"request_id\": \u003crequest-id\u003e,\n    \"created\": \u003ctimestamp\u003e,\n    \"requested_by\": \u003crequester-id\u003e,\n    \"repo\": \u003crepository\u003e,\n    \"data\": \u003cbase64-encoded-data-to-be-signed\u003e, # in the case of container signing\n    \"claim-file\": \u003cbase64-encoded-data-to-be-signed\u003e, # in the case of clear signing\n  }\n\n\nFor clearsign signing, data is base64 content you want to sign. For container signing, data is base64 encoded \njson with following structure:\n\n.. code-block:: none\n\n  {\n    \"critical\": {\n      \"type\": \"atomic container signature\",\n      \"image\": {\"docker-manifest-digest\": \u003cdigest\u003e},\n      \"identity\": {\"docker-reference\": \u003creference\u003e},\n    },\n    \"optional\": {\"creator\": \"pubtools-sign\"},\n  }\n\n\nMessages are sent senquantially to the topic `topic_send_to` specified in the configuration file. After then msg signer listen for response on the queue `topic_listen_to`. Configuration variable `topic_listen_to` can contain following templating variables:\n- {creator} - UID from client certificate\n- {task_id} - task_id from signing request\nWhen messages are sent, their request_ids are stored in mapping which determines whether reply the to message was received or not. When msg signer receives a message, it uses \u003cmessage_id_key\u003e attribute from the message to identify messages expected to be received.\nReceiving happens in a loop with configured timeout `timeout`. If no message from the expected messages is received within the `tiemout` period, receiving is considered as failed. If any expected message is received, timeout time is reset. On the timeout event, receving is restarted.\nIf number of receiving retries is bigger then `retries`, the whole process is considered as failed. Process is considered as failed and messages which haven't been received are sent again. This keeps happening until number of attempts to send and received messages is not greater than `send_retries`.\n\nConfiguration\n=============\n\nConfiguration is done via a yaml file. The default location is `~/.config/.pubtools-sign/conf.yaml` or `/etc/pubtools-sign/conf.yaml`. You can also specify a custom location via the `--config` argument. The configuration file is divided into sections, each section is a signer. Each signer has a set of attributes that are used to configure the signer\nConf.yaml has following structure:::\n\n  msg_signer:\n    messaging_brokers:\n      - \u003cprotocol://\u003chost\u003e:\u003cport\u003e for messaging broker\n    messaging_cert_key: \u003cpath to messaging client key + certificate in PEM format\u003e\n    messaging_ca_cert: \u003cpath to CA certificate bundle\u003e\n    topic_send_to: topic://\u003ctopic\u003e - topic where to send signing requests\n    topic_listen_to: queue://\u003cqueue\u003e - queue where to listen for answers from signing server. Supported templating variables: {creator - UID from client cert}, {task_id}\n    environment: \u003cenv\u003e - environment attribute which is included in signing request\n    service: \u003cservice\u003e - service attribute which is included in signing request\n    timeout: \u003cint\u003e - timeout for signing request\n    retries: \u003cint\u003e - number of retries for receiving signing responses from messaging brokers\n    send_retries: \u003cint\u003e - number of retries for whole send + receive cycle\n    message_id_key: \u003cid\u003e - attribute in message response used as unique identifier for signing request\n    log_level: \u003clevel\u003e - log level for pubtools-sign\n  cosign_signer:\n    rekor_url: \u003crekor-url\u003e\n    upload_tlog: \u003ctrue|false\u003e\n    registry_user: \u003cuser\u003e - used to login to registry where images will be signed\n    registry_password: \u003cpassword\u003e\n    env_variables:\n      \u003ckey\u003e: \u003cval\u003e - mapping of environment variables used in signing process. This can be used for example for AWS setup\n    key_aliases:\n      \u003calias\u003e: \u003ckey\u003e - mapping of key aliases to actual keys. When passing alias as signing key, \u003ckey\u003e is used instead. This\n                       way you cna define for example \"prod-key\" alias and have different real keys for different signers\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelease-engineering%2Fpubtools-sign","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frelease-engineering%2Fpubtools-sign","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frelease-engineering%2Fpubtools-sign/lists"}