pyhanko-cli 0.1.0__py3-none-any.whl

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/__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/_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/_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/_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

pyhanko/cli/commands/crypt.py

@@ -0,0 +1,219 @@
+import getpass
+
+import click
+from pyhanko.cli._root import cli_root
+from pyhanko.cli.runtime import pyhanko_exception_manager
+from pyhanko.cli.utils import _warn_empty_passphrase, readable_file
+from pyhanko.keys import load_certs_from_pemder
+from pyhanko.pdf_utils import crypt
+from pyhanko.pdf_utils.crypt import StandardSecurityHandler
+from pyhanko.pdf_utils.crypt.permissions import PubKeyPermissions
+from pyhanko.pdf_utils.reader import PdfFileReader
+from pyhanko.pdf_utils.writer import copy_into_new_writer
+
+__all__ = ['decrypt', 'encrypt_file']
+
+
+@cli_root.command(help='encrypt PDF files (AES-256 only)', name='encrypt')
+@click.argument('infile', type=readable_file)
+@click.argument('outfile', type=click.Path(writable=True, dir_okay=False))
+@click.option(
+    '--password',
+    help='password to encrypt the file with',
+    required=False,
+    type=str,
+)
+@click.option(
+    '--recipient',
+    required=False,
+    multiple=True,
+    help='certificate(s) corresponding to entities that '
+    'can decrypt the output file',
+    type=click.Path(readable=True, dir_okay=False),
+)
+def encrypt_file(infile, outfile, password, recipient):
+    if password and recipient:
+        raise click.ClickException(
+            "Specify either a password or a list of recipients."
+        )
+    elif not password and not recipient:
+        password = getpass.getpass(prompt='Output file password: ')
+
+    recipient_certs = None
+    if recipient:
+        recipient_certs = list(load_certs_from_pemder(cert_files=recipient))
+
+    with pyhanko_exception_manager():
+        with open(infile, 'rb') as inf:
+            r = PdfFileReader(inf)
+            w = copy_into_new_writer(r)
+
+            if recipient_certs:
+                w.encrypt_pubkey(recipient_certs)
+            else:
+                w.encrypt(owner_pass=password)
+
+            with open(outfile, 'wb') as outf:
+                w.write(outf)
+
+
+@cli_root.group(
+    help='decrypt PDF files (any standard PDF encryption scheme)',
+    name='decrypt',
+)
+def decrypt():
+    pass
+
+
+decrypt_force_flag = click.option(
+    '--force',
+    help='ignore access restrictions (use at your own risk)',
+    required=False,
+    type=bool,
+    is_flag=True,
+    default=False,
+)
+
+
+@decrypt.command(help='decrypt using password', name='password')
+@click.argument('infile', type=readable_file)
+@click.argument('outfile', type=click.Path(writable=True, dir_okay=False))
+@click.option(
+    '--password',
+    help='password to decrypt the file with',
+    required=False,
+    type=str,
+)
+@decrypt_force_flag
+def decrypt_with_password(infile, outfile, password, force):
+    with pyhanko_exception_manager():
+        with open(infile, 'rb') as inf:
+            r = PdfFileReader(inf)
+            if r.security_handler is None:
+                raise click.ClickException("File is not encrypted.")
+            elif not isinstance(r.security_handler, StandardSecurityHandler):
+                raise click.ClickException(
+                    "File is not encrypted with the standard (password-based) security handler"
+                )
+            if not password:
+                password = getpass.getpass(prompt='File password: ')
+            auth_result = r.decrypt(password)
+            if auth_result.status == crypt.AuthStatus.USER and not force:
+                raise click.ClickException(
+                    "Password specified was the user password, not "
+                    "the owner password. Pass --force to decrypt the "
+                    "file anyway."
+                )
+            elif auth_result.status == crypt.AuthStatus.FAILED:
+                raise click.ClickException("Password didn't match.")
+            w = copy_into_new_writer(r)
+            with open(outfile, 'wb') as outf:
+                w.write(outf)
+
+
+@decrypt.command(help='decrypt using private key (PEM/DER)', name='pemder')
+@click.argument('infile', type=readable_file)
+@click.argument('outfile', type=click.Path(writable=True, dir_okay=False))
+@click.option(
+    '--key',
+    type=readable_file,
+    required=True,
+    help='file containing the recipient\'s private key (PEM/DER)',
+)
+@click.option(
+    '--cert',
+    help='file containing the recipient\'s certificate (PEM/DER)',
+    type=readable_file,
+    required=True,
+)
+@click.option(
+    '--passfile',
+    required=False,
+    type=click.File('rb'),
+    help='file containing the passphrase for the private key',
+    show_default='stdin',
+)
+@click.option(
+    '--no-pass',
+    help='assume the private key file is unencrypted',
+    type=bool,
+    is_flag=True,
+    default=False,
+    show_default=True,
+)
+@decrypt_force_flag
+def decrypt_with_pemder(infile, outfile, key, cert, passfile, force, no_pass):
+    if passfile is not None:
+        passphrase = passfile.read()
+        passfile.close()
+    elif not no_pass:
+        passphrase = getpass.getpass(prompt='Key passphrase: ').encode('utf-8')
+        if not passphrase:
+            _warn_empty_passphrase()
+            passphrase = None
+    else:
+        passphrase = None
+
+    sedk = crypt.SimpleEnvelopeKeyDecrypter.load(
+        key, cert, key_passphrase=passphrase
+    )
+
+    _decrypt_pubkey(sedk, infile, outfile, force)
+
+
+def _decrypt_pubkey(
+    sedk: crypt.SimpleEnvelopeKeyDecrypter, infile, outfile, force
+):
+    with pyhanko_exception_manager():
+        with open(infile, 'rb') as inf:
+            r = PdfFileReader(inf)
+            if r.security_handler is None:
+                raise click.ClickException("File is not encrypted.")
+            if not isinstance(r.security_handler, crypt.PubKeySecurityHandler):
+                raise click.ClickException(
+                    "File was not encrypted with a public-key security handler."
+                )
+            auth_result = r.decrypt_pubkey(sedk)
+            if auth_result.status == crypt.AuthStatus.USER:
+                if (
+                    not force
+                    and auth_result.permission_flags
+                    and not (
+                        PubKeyPermissions.ALLOW_ENCRYPTION_CHANGE
+                        in auth_result.permission_flags
+                    )
+                ):
+                    raise click.ClickException(
+                        "Change of encryption is typically not allowed with "
+                        "user access. Pass --force to decrypt the file anyway."
+                    )
+            elif auth_result.status == crypt.AuthStatus.FAILED:
+                raise click.ClickException("Failed to decrypt the file.")
+            w = copy_into_new_writer(r)
+            with open(outfile, 'wb') as outf:
+                w.write(outf)
+
+
+@decrypt.command(help='decrypt using private key (PKCS#12)', name='pkcs12')
+@click.argument('infile', type=readable_file)
+@click.argument('outfile', type=click.Path(writable=True, dir_okay=False))
+@click.argument('pfx', type=readable_file)
+@click.option(
+    '--passfile',
+    required=False,
+    type=click.File('r'),
+    help='file containing the passphrase for the PKCS#12 file',
+    show_default='stdin',
+)
+@decrypt_force_flag
+def decrypt_with_pkcs12(infile, outfile, pfx, passfile, force):
+    if passfile is None:
+        passphrase = getpass.getpass(prompt='Key passphrase: ').encode('utf-8')
+    else:
+        passphrase = passfile.readline().strip().encode('utf-8')
+        passfile.close()
+    sedk = crypt.SimpleEnvelopeKeyDecrypter.load_pkcs12(
+        pfx, passphrase=passphrase
+    )
+
+    _decrypt_pubkey(sedk, infile, outfile, force)