pyhanko-cli 0.1.0__tar.gz

pyhanko_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2023 Matthias Valvekens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyhanko_cli-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+# Exclude tests from sdist until we have clear requirements
+#  from downstreams on how to package test data / build setup stuff
+#  in a monorepo context. All things considered, building from the whole
+#  source tarball seems like the only reasonable option in a context like that
+prune tests

pyhanko_cli-0.1.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: pyhanko-cli
+Version: 0.1.0
+Summary: CLI tools for stamping and signing PDF files
+Author-email: Matthias Valvekens <dev@mvalvekens.be>
+Maintainer-email: Matthias Valvekens <dev@mvalvekens.be>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MatthiasValvekens/pyHanko
+Project-URL: Documentation, https://pyhanko.readthedocs.io/
+Project-URL: Changes, https://pyhanko.readthedocs.io/en/latest/changelog.html
+Project-URL: Source Code, https://github.com/MatthiasValvekens/pyHanko
+Project-URL: Issue Tracker, https://github.com/MatthiasValvekens/pyHanko/issues
+Keywords: signature,pdf,pades,digital-signature,pkcs11
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: asn1crypto>=1.5.1
+Requires-Dist: tzlocal>=4.3
+Requires-Dist: pyhanko<0.30,>=0.29.0
+Requires-Dist: pyhanko-certvalidator<0.28,>=0.27.0
+Requires-Dist: click<8.2.0,>=8.1.3
+Dynamic: license-file
+
+The lack of open-source CLI tooling to handle digitally signing and stamping PDF files was bothering me, so I went ahead and rolled my own.
+
+### Installing
+
+PyHanko is hosted on [PyPI](https://pypi.org/project/pyHanko/),
+and can be installed using `pip`:
+
+```bash
+pip install pyhanko-cli
+```
+
+### Documentation
+
+The [documentation for pyHanko is hosted on ReadTheDocs](https://pyhanko.readthedocs.io/en/latest/)
+and includes information on CLI usage, library usage, and API reference documentation derived from
+inline docstrings.
+
+
+### Optional features
+
+Optional dependencies are managed at the level of the ``pyhanko`` package.
+
+```bash
+pip install 'pyHanko[pkcs11,image-support,opentype,qr]' pyhanko-cli
+```
+
+Depending on your shell, you might have to leave off the quotes:
+
+```bash
+pip install pyHanko[pkcs11,image-support,opentype,qr] pyhanko-cli
+```
+
+This `pip` invocation includes the optional dependencies required for PKCS#11, image handling,
+OpenType/TrueType support and QR code generation.

pyhanko_cli-0.1.0/README.md

@@ -0,0 +1,34 @@
+The lack of open-source CLI tooling to handle digitally signing and stamping PDF files was bothering me, so I went ahead and rolled my own.
+
+### Installing
+
+PyHanko is hosted on [PyPI](https://pypi.org/project/pyHanko/),
+and can be installed using `pip`:
+
+```bash
+pip install pyhanko-cli
+```
+
+### Documentation
+
+The [documentation for pyHanko is hosted on ReadTheDocs](https://pyhanko.readthedocs.io/en/latest/)
+and includes information on CLI usage, library usage, and API reference documentation derived from
+inline docstrings.
+
+
+### Optional features
+
+Optional dependencies are managed at the level of the ``pyhanko`` package.
+
+```bash
+pip install 'pyHanko[pkcs11,image-support,opentype,qr]' pyhanko-cli
+```
+
+Depending on your shell, you might have to leave off the quotes:
+
+```bash
+pip install pyHanko[pkcs11,image-support,opentype,qr] pyhanko-cli
+```
+
+This `pip` invocation includes the optional dependencies required for PKCS#11, image handling,
+OpenType/TrueType support and QR code generation.

pyhanko_cli-0.1.0/pyproject.toml

@@ -0,0 +1,101 @@
+[build-system]
+requires = ["setuptools>=80.8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyhanko-cli"
+description = "CLI tools for stamping and signing PDF files"
+authors = [{name = "Matthias Valvekens", email = "dev@mvalvekens.be"}]
+maintainers = [{name = "Matthias Valvekens", email = "dev@mvalvekens.be"}]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "signature",
+    "pdf",
+    "pades",
+    "digital-signature",
+    "pkcs11",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "asn1crypto>=1.5.1",
+    "tzlocal>=4.3",
+    "pyhanko>=0.29.0,<0.30",
+    "pyhanko-certvalidator>=0.27.0,<0.28",
+    "click>=8.1.3,<8.2.0",
+]
+version = "0.1.0"
+
+
+[project.readme]
+file = "README.md"
+content-type = "text/markdown"
+
+[project.urls]
+Homepage = "https://github.com/MatthiasValvekens/pyHanko"
+Documentation = "https://pyhanko.readthedocs.io/"
+Changes = "https://pyhanko.readthedocs.io/en/latest/changelog.html"
+"Source Code" = "https://github.com/MatthiasValvekens/pyHanko"
+"Issue Tracker" = "https://github.com/MatthiasValvekens/pyHanko/issues"
+
+[dependency-groups]
+testing-base = [
+    "common-test-utils",
+    "pytest>=6.1.1",
+    "requests-mock>=1.8.0",
+    "freezegun>=1.1.0",
+    "certomancer>=0.12.3,<0.13",
+    "pytest-cov>=4.0,<6.2",
+    "pytest-asyncio==0.24.0;python_version<\"3.9\"",
+    "pytest-asyncio==0.26.0;python_version>=\"3.9\"",
+    "backports.zoneinfo[tzdata];python_version<\"3.9\"",
+]
+testing = [
+    {include-group = "testing-base"},
+    "aiohttp>=3.9,<3.12",
+    "pytest-aiohttp>=1.0.4,<1.2.0",
+    "pyhanko[pkcs11,opentype,async_http,image-support,qr]"
+]
+
+[project.scripts]
+pyhanko = "pyhanko.__main__:launch"
+
+[tool.setuptools]
+include-package-data = false
+package-dir = {"" = "src"}
+
+
+[tool.setuptools.package-data]
+pyhanko = ["py.typed"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+log_format = "%(asctime)s %(levelname)s %(message)s"
+log_date_format = "%Y-%m-%d %H:%M:%S"
+log_cli = true
+log_cli_level = "INFO"
+asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope="function"
+markers = [
+    "nosmoke: exclude from smoke test runs"
+]
+
+[tool.coverage.run]
+omit = ["*docs*", "*test*", "*venv*", "setup.py", "_saslprep.py"]
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover", "pragma: nocover", "raise AssertionError", "raise NotImplementedError", "TYPE_CHECKING", "^\\s*\\.\\.\\."]
+precision = 2

pyhanko_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyhanko_cli-0.1.0/src/pyhanko/__main__.py

@@ -0,0 +1,9 @@
+from typing import List
+
+from pyhanko.cli import launch
+
+__all__: List[str] = []
+
+
+if __name__ == '__main__':
+    launch()

pyhanko_cli-0.1.0/src/pyhanko/cli/__init__.py

@@ -0,0 +1,12 @@
+from pyhanko.cli._root import cli_root
+from pyhanko.cli.commands.crypt import *
+from pyhanko.cli.commands.fields import *
+from pyhanko.cli.commands.signing import *
+from pyhanko.cli.commands.stamp import *
+from pyhanko.cli.commands.validation import *
+
+__all__ = ['launch', 'cli_root']
+
+
+def launch():
+    cli_root(prog_name='pyhanko')

pyhanko_cli-0.1.0/src/pyhanko/cli/_ctx.py

@@ -0,0 +1,92 @@
+from dataclasses import dataclass, field
+from typing import Optional
+
+from pyhanko.cli.config import CLIConfig
+from pyhanko.sign import PdfSignatureMetadata
+from pyhanko.sign.fields import SigFieldSpec
+from pyhanko.stamp import BaseStampStyle
+
+
+@dataclass
+class UXContext:
+    """
+    Context object to track information that affects the UX, e.g. user intent
+    as inferred from certain argument combinations that are otherwise difficult
+    to wire throughout the UI code.
+    """
+
+    visible_signature_desired: bool = False
+    """
+    Set to `True` if the user explicitly specifies `--field` with a bounding box
+    or passes `--style-name` explicitly.
+    """
+
+
+@dataclass
+class CLIContext:
+    """
+    Context object that cobbles together various CLI settings values that were
+    gathered by various subcommands during the lifetime of a CLI invocation,
+    either from configuration or from command line arguments.
+    This object is passed around as a ``click`` context object.
+
+    Not all settings are applicable to all subcommands, so all values are
+    optional.
+    """
+
+    sig_settings: Optional[PdfSignatureMetadata] = None
+    """
+    The settings that will be used to produce a new signature.
+    """
+
+    config: Optional[CLIConfig] = None
+    """
+    Values for CLI configuration settings.
+    """
+
+    existing_fields_only: bool = False
+    """
+    Whether signing operations should use existing fields only.
+    """
+
+    timestamp_url: Optional[str] = None
+    """
+    Endpoint URL for the timestamping service to use.
+    """
+
+    stamp_style: Optional[BaseStampStyle] = None
+    """
+    Stamp style to use for generating visual signature appearances, if
+    applicable.
+    """
+
+    stamp_url: Optional[str] = None
+    """
+    For QR stamp styles, defines the URL used to generate the QR code.
+    """
+
+    new_field_spec: Optional[SigFieldSpec] = None
+    """
+    Field spec used to generate new signature fields, if applicable.
+    """
+
+    prefer_pss: bool = False
+    """
+    When working with RSA keys, prefer RSASSA-PSS signing if available.
+    """
+
+    detach_pem: bool = False
+    """
+    When producing detached signature payloads (i.e. non-PDF CMS), save the
+    result in a PEM file instead of in a DER file.
+    """
+
+    lenient: bool = False
+    """
+    Process PDF files in nonstrict mode.
+    """
+
+    ux: UXContext = field(default_factory=UXContext)
+    """
+    UX information.
+    """

pyhanko_cli-0.1.0/src/pyhanko/cli/_root.py

@@ -0,0 +1,171 @@
+import itertools
+import logging
+from typing import Iterable, Optional
+
+import click
+from pyhanko.cli._ctx import CLIContext
+from pyhanko.cli.config import CLIRootConfig, parse_cli_config
+from pyhanko.cli.plugin_api import (
+    SIGNING_PLUGIN_ENTRY_POINT_GROUP,
+    SIGNING_PLUGIN_REGISTRY,
+)
+from pyhanko.cli.runtime import DEFAULT_CONFIG_FILE, logging_setup
+from pyhanko.cli.version import __version__ as cli_version
+from pyhanko.config.logging import LogConfig, parse_logging_config
+from pyhanko.version import __version__ as lib_version
+
+__all__ = ['cli_root']
+
+
+full_version = f"{lib_version} (CLI {cli_version})"
+
+
+@click.group()
+@click.version_option(prog_name='pyHanko', version=full_version)
+@click.option(
+    '--config',
+    help=(
+        'YAML file to load configuration from'
+        f'[default: {DEFAULT_CONFIG_FILE}]'
+    ),
+    required=False,
+    type=click.File('r'),
+)
+@click.option(
+    '--verbose',
+    help='Run in verbose mode',
+    required=False,
+    default=False,
+    type=bool,
+    is_flag=True,
+)
+@click.option(
+    '--no-plugins',
+    help='Disable non-builtin plugin loading',
+    type=bool,
+    is_flag=True,
+)
+@click.pass_context
+def _root(ctx: click.Context, config, verbose, no_plugins):
+    config_text = None
+    if config is None:
+        try:
+            with open(DEFAULT_CONFIG_FILE, 'r') as f:
+                config_text = f.read()
+            config = DEFAULT_CONFIG_FILE
+        except FileNotFoundError:
+            pass
+        except IOError as e:
+            raise click.ClickException(
+                f"Failed to read {DEFAULT_CONFIG_FILE}: {str(e)}"
+            )
+    else:
+        try:
+            config_text = config.read()
+        except IOError as e:
+            raise click.ClickException(
+                f"Failed to read configuration: {str(e)}",
+            )
+
+    ctx.ensure_object(CLIContext)
+    ctx_obj: CLIContext = ctx.obj
+    cfg: Optional[CLIRootConfig] = None
+    if config_text is not None:
+        cfg = parse_cli_config(config_text)
+        ctx_obj.config = cfg.config
+        log_config = cfg.log_config
+    else:
+        # grab the default
+        log_config = parse_logging_config({})
+
+    from .commands.signing import register
+
+    plugins_to_register = _load_plugins(cfg, plugins_enabled=not no_plugins)
+    register(plugins_to_register)
+
+    if verbose:
+        # override the root logger's logging level, but preserve the output
+        root_logger_config = log_config[None]
+        log_config[None] = LogConfig(
+            level=logging.DEBUG, output=root_logger_config.output
+        )
+    else:
+        # use the root logger's output settings to populate the default
+        log_output = log_config[None].output
+        # Revinfo fetch logs -> filter by default
+        log_config['pyhanko_certvalidator.fetchers'] = LogConfig(
+            level=logging.WARNING, output=log_output
+        )
+        if 'fontTools.subset' not in log_config:
+            # the fontTools subsetter has a very noisy INFO log, so
+            # set that one to WARNING by default
+            log_config['fontTools.subset'] = LogConfig(
+                level=logging.WARNING, output=log_output
+            )
+
+    logging_setup(log_config, verbose)
+
+    if verbose:
+        logging.debug("Running with --verbose")
+    if config_text is not None:
+        logging.debug(f'Finished reading configuration from {config}.')
+    else:
+        logging.debug('There was no configuration to parse.')
+
+
+def _load_plugins(root_config: Optional[CLIRootConfig], plugins_enabled: bool):
+    import sys
+    from importlib import metadata
+
+    # we always load the default ones
+    to_load = [
+        'pyhanko.cli.commands.signing.pkcs11_cli:PKCS11Plugin',
+        'pyhanko.cli.commands.signing.simple:PKCS12Plugin',
+        'pyhanko.cli.commands.signing.simple:PemderPlugin',
+    ]
+
+    eps_from_metadata: Iterable[metadata.EntryPoint] = []
+    if plugins_enabled:
+        if root_config is not None:
+            to_load += [str(mod) for mod in root_config.plugin_endpoints]
+
+        # need to use dict interface for 3.8 interop
+        if sys.version_info < (3, 10):
+            eps_from_metadata = metadata.entry_points().get(
+                SIGNING_PLUGIN_ENTRY_POINT_GROUP, []
+            )
+        else:
+            eps_from_metadata = metadata.entry_points(
+                group=SIGNING_PLUGIN_ENTRY_POINT_GROUP
+            )
+
+    # noinspection PyArgumentList
+    to_load_as_endpoints: Iterable[metadata.EntryPoint] = [
+        metadata.EntryPoint(
+            name='',
+            value=v,
+            group=SIGNING_PLUGIN_ENTRY_POINT_GROUP,
+        )
+        for v in to_load
+    ]
+    resulting_plugins = list(SIGNING_PLUGIN_REGISTRY)
+    seen = set(type(x) for x in SIGNING_PLUGIN_REGISTRY)
+    for ep in itertools.chain(to_load_as_endpoints, eps_from_metadata):
+        plugin_cls = ep.load()
+        if not isinstance(plugin_cls, type):
+            click.echo(
+                click.style(
+                    f"Plugins must be defined as references to classes with a "
+                    f"nullary init function, but '{ep.value}' is "
+                    f"a {type(plugin_cls)}. Disregarding...",
+                    bold=True,
+                )
+            )
+            continue
+        if plugin_cls not in seen:
+            seen.add(plugin_cls)
+            resulting_plugins.append(plugin_cls())
+    return resulting_plugins
+
+
+cli_root: click.Group = _root

pyhanko_cli-0.1.0/src/pyhanko/cli/_trust.py

@@ -0,0 +1,159 @@
+from typing import Iterable, Optional, TypeVar, Union
+
+import click
+from pyhanko.cli.config import CLIConfig
+from pyhanko.cli.utils import logger, readable_file
+from pyhanko.config.errors import ConfigurationError
+from pyhanko.config.trust import init_validation_context_kwargs
+from pyhanko.keys import load_certs_from_pemder
+
+
+def build_vc_kwargs(
+    cli_config: Optional[CLIConfig],
+    validation_context: Optional[str],
+    trust: Union[Iterable[str], str],
+    trust_replace: bool,
+    other_certs: Union[Iterable[str], str],
+    retroactive_revinfo: bool,
+    allow_fetching: Optional[bool] = None,
+):
+    try:
+        if validation_context is not None:
+            if any((trust, other_certs)):
+                raise click.ClickException(
+                    "--validation-context is incompatible with --trust "
+                    "and --other-certs"
+                )
+            # load the desired context from config
+            if cli_config is None:
+                raise click.ClickException("No config file specified.")
+            try:
+                result = cli_config.get_validation_context(
+                    validation_context, as_dict=True
+                )
+            except ConfigurationError as e:
+                msg = (
+                    "Configuration problem. Are you sure that the validation "
+                    f"context '{validation_context}' is properly defined in the"
+                    " configuration file?"
+                )
+                logger.error(msg, exc_info=e)
+                raise click.ClickException(msg)
+        elif trust or other_certs:
+            # load a validation profile using command line kwargs
+            result = init_validation_context_kwargs(
+                trust=trust,
+                trust_replace=trust_replace,
+                other_certs=other_certs,
+                retroactive_revinfo=retroactive_revinfo,
+            )
+        elif cli_config is not None:
+            # load the default settings from the CLI config
+            try:
+                result = cli_config.get_validation_context(as_dict=True)
+            except ConfigurationError as e:
+                msg = "Failed to load default validation context."
+                logger.error(msg, exc_info=e)
+                raise click.ClickException(msg)
+        else:
+            result = {}
+
+        if allow_fetching is not None:
+            result['allow_fetching'] = allow_fetching
+        else:
+            result.setdefault('allow_fetching', True)
+
+        # allow CLI --retroactive-revinfo flag to override settings
+        # if necessary
+        if retroactive_revinfo:
+            result['retroactive_revinfo'] = True
+        return result
+    except click.ClickException:
+        raise
+    except IOError as e:
+        msg = "I/O problem while reading validation config"
+        logger.error(msg, exc_info=e)
+        raise click.ClickException(msg)
+    except Exception as e:
+        msg = "Generic processing problem while reading validation config"
+        logger.error(msg, exc_info=e)
+        raise click.ClickException(msg)
+
+
+def _get_key_usage_settings(ctx: click.Context, validation_context: str):
+    cli_config: Optional[CLIConfig] = ctx.obj.config
+    if cli_config is None:
+        return None
+
+    # note: validation_context can be None, this triggers fallback to the
+    # default validation context specified in the configuration file
+    # If we add support for specifying key usage settings as CLI arguments,
+    # using the same fallbacks as _build_cli_kwargs would probably be cleaner
+    return cli_config.get_signer_key_usages(name=validation_context)
+
+
+TRUST_OPTIONS = [
+    click.Option(
+        ('--validation-context',),
+        help='use validation context from config',
+        required=False,
+        type=str,
+    ),
+    click.Option(
+        ('--trust',),
+        help='list trust roots (multiple allowed)',
+        required=False,
+        multiple=True,
+        type=readable_file,
+    ),
+    click.Option(
+        ('--trust-replace',),
+        help='listed trust roots supersede OS-provided trust store',
+        required=False,
+        type=bool,
+        is_flag=True,
+        default=False,
+        show_default=True,
+    ),
+    click.Option(
+        ('--other-certs',),
+        help='other certs relevant for validation',
+        required=False,
+        multiple=True,
+        type=readable_file,
+    ),
+]
+
+
+FC = TypeVar('FC', bound=click.Command)
+
+
+def trust_options(f: FC) -> FC:
+    f.params.extend(TRUST_OPTIONS)
+    return f
+
+
+def _prepare_vc(vc_kwargs, soft_revocation_check, force_revinfo):
+    if soft_revocation_check and force_revinfo:
+        raise click.ClickException(
+            "--soft-revocation-check is incompatible with " "--force-revinfo"
+        )
+    if force_revinfo:
+        rev_mode = 'require'
+    elif soft_revocation_check:
+        rev_mode = 'soft-fail'
+    else:
+        rev_mode = 'hard-fail'
+    vc_kwargs['revocation_mode'] = rev_mode
+    return vc_kwargs
+
+
+def grab_certs(files):
+    if not files:
+        return None
+    try:
+        return list(load_certs_from_pemder(files))
+    except (IOError, ValueError) as e:
+        raise click.ClickException(
+            f'Could not load certificates from {files}'
+        ) from e