community.crypto/plugins/modules/acme_certificate_renewal_info.py

#!/usr/bin/python
# Copyright (c) 2018 Felix Fontein <felix@fontein.de>
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import annotations

DOCUMENTATION = r"""
module: acme_certificate_renewal_info
author: "Felix Fontein (@felixfontein)"
version_added: 2.20.0
short_description: Determine whether a certificate should be renewed or not
description:
  - Uses various information to determine whether a certificate should be renewed or not.
  - If available, the ARI extension (ACME Renewal Information, L(RFC 9773, https://www.rfc-editor.org/rfc/rfc9773.html)) is
    used.
extends_documentation_fragment:
  - community.crypto._acme.basic
  - community.crypto._acme.no_account
  - community.crypto._attributes
  - community.crypto._attributes.info_module
  - community.crypto._attributes.idempotent_not_modify_state
attributes:
  idempotent:
    support: partial
    details:
      - The module is not idempotent if O(now) is a relative timestamp, or is not specified.
      - If O(use_ari=true), the module is not idempotent if O(ari_algorithm=standard).
options:
  certificate_path:
    description:
      - A path to the X.509 certificate to determine renewal of.
      - In case the certificate does not exist, the module will always return RV(should_renew=true).
      - O(certificate_path) and O(certificate_content) are mutually exclusive.
    type: path
  certificate_content:
    description:
      - The content of the X.509 certificate to determine renewal of.
      - O(certificate_path) and O(certificate_content) are mutually exclusive.
    type: str
  use_ari:
    description:
      - Whether to use ARI information, if available.
      - Set this to V(false) if the ACME server implements ARI in a way that is incompatible with this module.
    type: bool
    default: true
  ari_algorithm:
    description:
      - If ARI information is used, selects which algorithm is used to determine whether to renew now.
      - V(standard) selects the L(algorithm provided in the the ARI specification,
        https://www.rfc-editor.org/rfc/rfc9773.html#section-4.2).
      - V(start) returns RV(should_renew=true) once the start of the renewal interval has been reached.
    type: str
    choices:
      - standard
      - start
    default: standard
  remaining_days:
    description:
      - The number of days the certificate must have left being valid.
      - For example, if O(remaining_days=20), this check causes RV(should_renew=true) if the certificate is valid for less
        than 20 days.
    type: int
  remaining_percentage:
    description:
      - The percentage of the certificate's validity period that should be left.
      - For example, if O(remaining_percentage=0.1), and the certificate's validity period is 90 days, this check causes RV(should_renew=true)
        if the certificate is valid for less than 9 days.
      - Must be a value between 0 and 1.
    type: float
  now:
    description:
      - Use this timestamp instead of the current timestamp to determine whether a certificate should be renewed.
      - Time can be specified either as relative time or as absolute timestamp.
      - Time will always be interpreted as UTC.
      - Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer + C([w | d | h | m | s]) (for example
        V(+32w1d2h)).
    type: str
  treat_parsing_error_as_non_existing:
    description:
      - Determines the behavior when the certificate file exists or its contents are provided, but the certificate cannot be parsed.
      - If V(true), will exit successfully with RV(exists=true), RV(parsable=false), and RV(should_renew=true).
      - If V(false), the module will fail.
      - If the file exists, but cannot be loaded due to I/O errors or permission errors, the module always fails.
    type: bool
    default: false
    version_added: 2.24.0
seealso:
  - module: community.crypto.acme_certificate
    description: Allows to obtain a certificate using the ACME protocol.
  - module: community.crypto.acme_ari_info
    description: Obtain renewal information for a certificate.
"""

EXAMPLES = r"""
---
- name: Retrieve renewal information for a certificate
  community.crypto.acme_certificate_renewal_info:
    certificate_path: /etc/httpd/ssl/sample.com.crt
  register: cert_data

- name: Should the certificate be renewed?
  ansible.builtin.debug:
    var: cert_data.should_renew
"""

RETURN = r"""
should_renew:
  description:
    - Whether the certificate should be renewed.
    - If no certificate is provided, or the certificate is expired, will always be V(true).
  returned: success
  type: bool
  sample: true

exists:
  description:
    - Whether the certificate file exists, or O(certificate_content) was provided.
  returned: success
  type: bool
  sample: true
  version_added: 2.24.0

parsable:
  description:
    - Whether the certificate file exists, or O(certificate_content) was provided, and the certificate can be parsed.
    - Can only differ from RV(exists) if O(treat_parsing_error_as_non_existing=true).
  returned: success
  type: bool
  sample: true
  version_added: 2.24.0

msg:
  description:
    - Information on the reason for renewal.
    - Should be shown to the user, as in case of ARI triggered renewal it can contain important information, for example on
      forced revocations for misissued certificates.
  type: str
  returned: success
  sample: The certificate does not exist.

supports_ari:
  description:
    - Whether ARI information was used to determine renewal. This can be used to determine whether to specify
      O(community.crypto.acme_certificate#module:include_renewal_cert_id=when_ari_supported)
      for the M(community.crypto.acme_certificate) module.
    - If O(use_ari=false), this will always be V(false).
  returned: success
  type: bool
  sample: true

cert_id:
  description:
    - The certificate ID according to L(Section 4.1 in RFC 9773, https://www.rfc-editor.org/rfc/rfc9773.html#section-4.1).
  returned: success, the certificate exists, and has an Authority Key Identifier X.509 extension
  type: str
  sample: aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE
"""

import os
import random
import typing as t

from ansible_collections.community.crypto.plugins.module_utils._acme.acme import (
    ACMEClient,
    create_backend,
    create_default_argspec,
)
from ansible_collections.community.crypto.plugins.module_utils._acme.errors import (
    ModuleFailException,
)
from ansible_collections.community.crypto.plugins.module_utils._acme.io import read_file
from ansible_collections.community.crypto.plugins.module_utils._acme.utils import (
    compute_cert_id,
)


def main() -> t.NoReturn:
    argument_spec = create_default_argspec(with_account=False)
    argument_spec.update_argspec(
        certificate_path={"type": "path"},
        certificate_content={"type": "str"},
        use_ari={"type": "bool", "default": True},
        ari_algorithm={
            "type": "str",
            "choices": ["standard", "start"],
            "default": "standard",
        },
        remaining_days={"type": "int"},
        remaining_percentage={"type": "float"},
        now={"type": "str"},
        treat_parsing_error_as_non_existing={"type": "bool", "default": False},
    )
    argument_spec.update(
        mutually_exclusive=[("certificate_path", "certificate_content")],
    )
    module = argument_spec.create_ansible_module(supports_check_mode=True)
    backend = create_backend(module, needs_acme_v2=True)

    result = {
        "changed": False,
        "msg": "The certificate is still valid and no condition was reached",
        "exists": False,
        "parsable": False,
        "supports_ari": False,
    }

    def complete(should_renew: bool, **kwargs: t.Any) -> t.NoReturn:
        result["should_renew"] = should_renew
        result.update(kwargs)
        module.exit_json(**result)

    if (
        not module.params["certificate_path"]
        and not module.params["certificate_content"]
    ):
        complete(True, msg="No certificate was specified")

    if module.params["certificate_path"] is not None:
        if not os.path.exists(module.params["certificate_path"]):
            complete(True, msg="The certificate file does not exist")
        if module.params["treat_parsing_error_as_non_existing"]:
            try:
                read_file(module.params["certificate_path"])
            except ModuleFailException as e:
                e.do_fail(module=module)

    result["exists"] = True
    try:
        cert_info = backend.get_cert_information(
            cert_filename=module.params["certificate_path"],
            cert_content=module.params["certificate_content"],
        )
    except ModuleFailException as e:
        if module.params["treat_parsing_error_as_non_existing"]:
            complete(True, msg=f"Certificate cannot be parsed: {e.msg}")
        e.do_fail(module=module)

    result["parsable"] = True
    try:
        cert_id = compute_cert_id(
            backend=backend,
            cert_info=cert_info,
            none_if_required_information_is_missing=True,
        )
        if cert_id is not None:
            result["cert_id"] = cert_id

        if module.params["now"]:
            now = backend.parse_module_parameter(value=module.params["now"], name="now")
        else:
            now = backend.get_now()

        if now >= cert_info.not_valid_after:
            complete(True, msg="The certificate has already expired")

        client = ACMEClient(module=module, backend=backend)
        if (
            cert_id is not None
            and module.params["use_ari"]
            and client.directory.has_renewal_info_endpoint()
        ):
            renewal_info = client.get_renewal_info(cert_id=cert_id)
            window_start = backend.parse_acme_timestamp(
                renewal_info["suggestedWindow"]["start"]
            )
            window_end = backend.parse_acme_timestamp(
                renewal_info["suggestedWindow"]["end"]
            )
            msg_append = ""
            if "explanationURL" in renewal_info:
                msg_append = f". Information on renewal interval: {renewal_info['explanationURL']}"
            result["supports_ari"] = True
            if now > window_end:
                complete(
                    True,
                    msg=f"The suggested renewal interval provided by ARI is in the past{msg_append}",
                )
            if module.params["ari_algorithm"] == "start":
                if now > window_start:
                    complete(
                        True,
                        msg=f"The suggested renewal interval provided by ARI has begun{msg_append}",
                    )
            else:
                random_time = backend.interpolate_timestamp(
                    window_start, window_end, percentage=random.random()
                )
                if now > random_time:
                    complete(
                        True,
                        msg=f"The picked random renewal time {random_time} in sugested renewal internal provided by ARI is in the past{msg_append}",
                    )

        if module.params["remaining_days"] is not None:
            remaining_days = (cert_info.not_valid_after - now).days
            if remaining_days < module.params["remaining_days"]:
                complete(
                    True,
                    msg=f"The certificate expires in {remaining_days} days",
                )

        if module.params["remaining_percentage"] is not None:
            timestamp = backend.interpolate_timestamp(
                cert_info.not_valid_before,
                cert_info.not_valid_after,
                percentage=1 - module.params["remaining_percentage"],
            )
            if timestamp < now:
                complete(
                    True,
                    msg=f"The remaining percentage {module.params['remaining_percentage'] * 100}% of the certificate's lifespan was reached on {timestamp}",
                )

        complete(False)
    except ModuleFailException as e:
        e.do_fail(module=module)


if __name__ == "__main__":
    main()