Skip to content

Certificate Manager

Attributes

CERTIFICATE_EXPIRY_WARNING_DAYS module-attribute

CERTIFICATE_EXPIRY_WARNING_DAYS = 30

CERT_ORGANIZATION module-attribute

CERT_ORGANIZATION = 'Fed-BioMed'

CERT_PURPOSE_CLIENT module-attribute

CERT_PURPOSE_CLIENT = 'client'

CERT_PURPOSE_SERVER module-attribute

CERT_PURPOSE_SERVER = 'server'

Classes

CertificateManager

CertificateManager(db_path, component_type)

Certificate manager to manage certificates of parties

A manager is one component's, and the rules a registration has to satisfy are that component's. Its type is therefore held here rather than passed at each call, so that no caller registers under another component's rules.

Attrs

Parameters:

Name Type Description Default
db_path str

The name of the DB file to connect through TinyDB

required
component_type str

Type of the component the manager belongs to, NODE or RESEARCHER.

required

Raises:

Type Description
FedbiomedCertificateError

the component type is neither NODE nor RESEARCHER.

Source code in fedbiomed/common/certificate_manager.py
def __init__(self, db_path: str, component_type: str):
    """Opens a component's certificate database.

    Args:
        db_path: The name of the DB file to connect through TinyDB
        component_type: Type of the component the manager belongs to, `NODE`
            or `RESEARCHER`.

    Raises:
        FedbiomedCertificateError: the component type is neither `NODE` nor
            `RESEARCHER`.
    """
    self._component_type: str = _validated_component_type(component_type)
    self._query: Query = Query()

    db = TinyDB(db_path)
    db.table_class = DBTable
    self._tinydb: Optional[TinyDB] = db
    self._db: Optional[Table] = db.table("Certificates")

Methods:

close
close()

Closes the underlying TinyDB handle and releases the open file.

Source code in fedbiomed/common/certificate_manager.py
def close(self) -> None:
    """Closes the underlying TinyDB handle and releases the open file."""
    if self._tinydb is not None:
        self._tinydb.close()
        self._tinydb = None
        self._db = None
delete
delete(component_id)

Deletes given component from table

Parameters:

Name Type Description Default
component_id

Component id

required

Returns:

Type Description
List[int]

The document IDs of deleted certificates

Source code in fedbiomed/common/certificate_manager.py
def delete(self, component_id) -> List[int]:
    """Deletes given component from table

    Args:
        component_id: Component id

    Returns:
        The document IDs of deleted certificates
    """

    # Read before removing: revoking trust is auditable only while the entry
    # being removed can still be described.
    document = self.get(component_id=component_id) or {}
    removed = self._table.remove(self._query.component_id == component_id)

    if removed:
        logger.security_event(
            operation="certificate_deleted",
            status="success",
            component_id=component_id,
            **certificate_audit_fields(document.get("certificate", "")),
        )

    return removed
expiring_certificates
expiring_certificates(within_days)

(component_id, expiry) for certs expiring within within_days (or expired).

Source code in fedbiomed/common/certificate_manager.py
def expiring_certificates(self, within_days: int) -> List[Tuple[str, datetime]]:
    """`(component_id, expiry)` for certs expiring within `within_days` (or
    expired)."""
    threshold = datetime.now(timezone.utc) + timedelta(days=within_days)
    expiring = []
    for doc in self._table.all():
        expiry = certificate_expiry(doc["certificate"])
        if expiry is not None and expiry <= threshold:
            expiring.append((doc["component_id"], expiry))
    return sorted(expiring, key=lambda item: item[1])
generate_self_signed_ssl_certificate staticmethod
generate_self_signed_ssl_certificate(
    certificate_folder,
    component_id,
    purpose,
    certificate_name="FBM_",
    san=None,
)

Creates self-signed certificates

The subject states who the component is, never where it is reached: CN=<component_id>, O= the organization marking it as Fed-BioMed's. The Extended Key Usage declares purpose, the single TLS role the component acts in.

Parameters:

Name Type Description Default
certificate_folder

The path where certificate files .pem and .key will be saved. Path should be absolute.

required
component_id str

ID of the component, which the certificate identifies.

required
purpose str

TLS role the certificate declares, CERT_PURPOSE_CLIENT or CERT_PURPOSE_SERVER.

required
certificate_name str

Name of the certificate file.

'FBM_'
san Optional[List[str]]

Hosts and IP addresses the component is reached at, which peers verify it under. Required for a certificate peers verify by name.

None

Returns:

Name Type Description
private_key str

Private key file

public_key str

Certificate file

Raises:

Type Description
FedbiomedCertificateError

If the purpose is unknown, if certificate directory is invalid, or an error occurs while writing certificate files in given path.

Certificate files

Certificate files will be saved in the given directory as
`certificates.key` for private key `certificate.pem` for public key.
Source code in fedbiomed/common/certificate_manager.py
@staticmethod
def generate_self_signed_ssl_certificate(
    certificate_folder,
    component_id: str,
    purpose: str,
    certificate_name: str = "FBM_",
    san: Optional[List[str]] = None,
) -> Tuple[str, str]:
    """Creates self-signed certificates

    The subject states who the component is, never where it is reached:
    `CN=<component_id>`, `O=` the organization marking it as Fed-BioMed's. The
    Extended Key Usage declares `purpose`, the single TLS role the component acts
    in.

    Args:
        certificate_folder: The path where certificate files `.pem` and `.key`
            will be saved. Path should be absolute.
        component_id: ID of the component, which the certificate identifies.
        purpose: TLS role the certificate declares, `CERT_PURPOSE_CLIENT` or
            `CERT_PURPOSE_SERVER`.
        certificate_name: Name of the certificate file.
        san: Hosts and IP addresses the component is reached at, which peers
            verify it under. Required for a certificate peers verify by name.

    Returns:
        private_key: Private key file
        public_key: Certificate file

    Raises:
        FedbiomedCertificateError: If the purpose is unknown, if certificate
            directory is invalid, or an error occurs while writing certificate
            files in given path.

    !!! info "Certificate files"
            Certificate files will be saved in the given directory as
            `certificates.key` for private key `certificate.pem` for public key.
    """
    if purpose not in (CERT_PURPOSE_CLIENT, CERT_PURPOSE_SERVER):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Unknown certificate purpose `{purpose}`; "
            f"expected `{CERT_PURPOSE_CLIENT}` or `{CERT_PURPOSE_SERVER}`."
        )

    if not os.path.isabs(certificate_folder):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Certificate path should be absolute: "
            f"{certificate_folder}"
        )

    if not os.path.isdir(certificate_folder):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Certificate path is not valid: {certificate_folder}"
        )

    pkey = rsa.generate_private_key(public_exponent=65537, key_size=2048)

    # The names given and no others. One issued for none — a node's, resolved by
    # fingerprint — carries no SubjectAlternativeName at all.
    san_names = list(dict.fromkeys(entry for entry in san or [] if entry))

    # A peer on this machine dials it by whichever loopback form it holds, and
    # verifies only what the certificate carries: naming one names all three.
    if any(is_loopback_name(name) for name in san_names):
        san_names = list(
            dict.fromkeys([*san_names, "localhost", "127.0.0.1", "::1"])
        )

    # Who the component is, not where: its id, under the organization that marks
    # the certificate as issued by Fed-BioMed.
    name = x509.Name(
        [
            x509.NameAttribute(NameOID.ORGANIZATION_NAME, CERT_ORGANIZATION),
            x509.NameAttribute(NameOID.COMMON_NAME, component_id),
        ]
    )

    builder = (
        x509.CertificateBuilder()
        .subject_name(name)
        .issuer_name(name)
        .public_key(pkey.public_key())
        .serial_number(x509.random_serial_number())
        .not_valid_before(datetime.now(timezone.utc))
        .not_valid_after(datetime.now(timezone.utc) + timedelta(days=5 * 365))
    )

    if purpose == CERT_PURPOSE_SERVER:
        extended_key_usages = [ExtendedKeyUsageOID.SERVER_AUTH]
        key_encipherment = True
    else:
        extended_key_usages = [ExtendedKeyUsageOID.CLIENT_AUTH]
        key_encipherment = False

    builder = (
        builder.add_extension(
            x509.BasicConstraints(ca=False, path_length=None), critical=True
        )
        .add_extension(
            x509.KeyUsage(
                digital_signature=True,
                content_commitment=False,
                key_encipherment=key_encipherment,
                data_encipherment=False,
                key_agreement=False,
                key_cert_sign=False,
                crl_sign=False,
                encipher_only=False,
                decipher_only=False,
            ),
            critical=True,
        )
        .add_extension(x509.ExtendedKeyUsage(extended_key_usages), critical=False)
    )

    if san_names:
        builder = builder.add_extension(
            x509.SubjectAlternativeName([san_entry(name) for name in san_names]),
            critical=False,
        )

    certificate = builder.sign(private_key=pkey, algorithm=hashes.SHA256())

    # Certificate names
    key_file = os.path.join(certificate_folder, f"{certificate_name}.key")
    pem_file = os.path.join(certificate_folder, f"{certificate_name}.pem")

    try:
        # Opened restricted rather than restricted afterwards, so the key is
        # never briefly readable to anyone but the component.
        descriptor = os.open(
            key_file,
            os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
            _PRIVATE_KEY_FILE_MODE,
        )
        with open(descriptor, "wb") as f:
            f.write(
                pkey.private_bytes(
                    encoding=serialization.Encoding.PEM,
                    format=serialization.PrivateFormat.TraditionalOpenSSL,
                    encryption_algorithm=serialization.NoEncryption(),
                )
            )
        # `os.open` applies the mode only to a file it creates.
        os.chmod(key_file, _PRIVATE_KEY_FILE_MODE)
    except Exception as e:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Can not write private key: {e}"
        ) from e

    try:
        with open(pem_file, "wb") as f:
            f.write(certificate.public_bytes(serialization.Encoding.PEM))
    except Exception as e:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Can not write certificate: {e}"
        ) from e

    return key_file, pem_file
get
get(component_id)

Gets certificate/public key of given component

Parameters:

Name Type Description Default
component_id str

ID of the component which certificate will be retrieved from DB

required

Returns:

Type Description
Union[dict, None]

Certificate, dict like TinyDB document

Source code in fedbiomed/common/certificate_manager.py
def get(self, component_id: str) -> Union[dict, None]:
    """Gets certificate/public key  of given component

    Args:
        component_id: ID of the component which certificate will be retrieved
            from DB

    Returns:
        Certificate, dict like TinyDB document
    """

    v = self._table.get(self._query.component_id == component_id)
    return v
list
list(verbose=False)

Lists registered certificates.

Parameters:

Name Type Description Default
verbose bool

Prints list of registered certificates in tabular format

False

Returns:

Type Description
List[Document]

List of certificate objects registered in DB

Source code in fedbiomed/common/certificate_manager.py
def list(self, verbose: bool = False) -> List[Document]:
    """Lists registered certificates.

    Args:
        verbose: Prints list of registered certificates in tabular format

    Returns:
        List of certificate objects registered in DB
    """
    certificates = self._table.all()

    if verbose:
        to_print = copy.deepcopy(certificates)
        for doc in to_print:
            expiry = certificate_expiry(doc.pop("certificate"))
            doc["expires"] = expiry.strftime("%Y-%m-%d") if expiry else "unknown"

        print(tabulate(to_print, headers="keys"))

    return certificates
register
register(certificate, component_id=None, upsert=False)

Registers a certificate, applying every rule a stored certificate must meet.

The single entry point for granting trust: it validates, then writes. Callers holding a file use register_certificate instead, and no caller writes to the table directly. Which rules apply follows from the component this manager was opened for: a node holds one certificate, its researcher's, and requires it to state a host. The certificate is stored re-encoded as PEM.

The component id may be recovered from the certificate's CN=, but only on a certificate Fed-BioMed issued (O=Fed-BioMed); any other issuer's CN= is free text:

  • certificate carries an identity, component_id omitted: recovered;
  • certificate carries none: component_id is required;
  • both present: they must be the same.

Parameters:

Name Type Description Default
certificate str

PEM encoded certificate to register.

required
component_id Optional[str]

ID of the component the certificate belongs to. Optional when the certificate embeds an identity in CN=, required otherwise.

None
upsert bool

Replaces the certificate registered for that component; without it, registering a component twice raises.

False

Returns:

Type Description
str

The component id the certificate was registered under, which the caller

str

may not have supplied: it is recovered from the certificate when

str

component_id is omitted.

Raises:

Type Description
FedbiomedCertificateError

If the certificate cannot be read or has expired; if component_id is neither given nor recoverable from the certificate; if a given component_id conflicts with the certificate identity; if the certificate is already registered under another component id; or, on a node, if it already holds a certificate for another component or is given one stating no host.

Source code in fedbiomed/common/certificate_manager.py
def register(
    self,
    certificate: str,
    component_id: Optional[str] = None,
    upsert: bool = False,
) -> str:
    """Registers a certificate, applying every rule a stored certificate must meet.

    The single entry point for granting trust: it validates, then writes. Callers
    holding a file use `register_certificate` instead, and no caller writes to the
    table directly. Which rules apply follows from the component this manager was
    opened for: a node holds one certificate, its researcher's, and requires it to
    state a host. The certificate is stored re-encoded as PEM.

    The component id may be recovered from the certificate's `CN=`, but only on a
    certificate Fed-BioMed issued (`O=Fed-BioMed`); any other issuer's `CN=` is
    free text:

    - certificate carries an identity, `component_id` omitted: recovered;
    - certificate carries none: `component_id` is required;
    - both present: they must be the same.

    Args:
        certificate: PEM encoded certificate to register.
        component_id: ID of the component the certificate belongs to. Optional
            when the certificate embeds an identity in `CN=`, required otherwise.
        upsert: Replaces the certificate registered for that component; without
            it, registering a component twice raises.

    Returns:
        The component id the certificate was registered under, which the caller
        may not have supplied: it is recovered from the certificate when
        `component_id` is omitted.

    Raises:
        FedbiomedCertificateError: If the certificate cannot be read or has
            expired; if `component_id` is neither given nor recoverable from the
            certificate; if a given `component_id` conflicts with the certificate
            identity; if the certificate is already registered under another
            component id; or, on a node, if it already holds a certificate for
            another component or is given one stating no host.
    """
    # Every rule below passes on a certificate it cannot read, so reject it first.
    try:
        # `cryptography` reads a PEM whose line breaks were lost, e.g. pasted on
        # one line, which the OpenSSL gRPC hands it to does not: stored re-encoded.
        certificate = (
            x509.load_pem_x509_certificate(certificate.encode("utf-8"))
            .public_bytes(serialization.Encoding.PEM)
            .decode("utf-8")
        )
    except (TypeError, ValueError) as exp:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate could not be read: it is "
            "not a PEM encoded certificate. Register the `.pem` file the component "
            "serves."
        ) from exp
    fingerprint = certificate_fingerprint(certificate)

    # An expired certificate completes no handshake, so registering it would only
    # defer the failure to the connection, where it is reported as a dropped
    # handshake naming no certificate. The date is there to read: the PEM the
    # fingerprint was taken from is the one it is read from.
    expiry = certificate_expiry(certificate)
    now = datetime.now(timezone.utc)
    if expiry <= now:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate expired on "
            f"{expiry:%Y-%m-%d}, so no connection can be established with it. "
            "Request the party it belongs to reissue its certificate, and "
            "register the one it serves then."
        )

    certificate_id = certificate_component_id(certificate)

    if certificate_id is not None:
        if component_id is not None and component_id != certificate_id:
            raise FedbiomedCertificateError(
                f"{ErrorNumbers.FB619.value}: Given component id `{component_id}` "
                f"does not match the certificate identity `{certificate_id}`."
            )
        component_id = certificate_id
    elif component_id is None:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate does not embed a "
            "Fed-BioMed identity, so `component_id` must be provided to "
            "register it."
        )

    registering_on_node = self._component_type == ComponentType.NODE.name

    # gRPC falls back to the Common Name, which holds the component id, not a host
    if registering_on_node and not certificate_san_names(certificate):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate states no host: its "
            "Subject Alternative Name carries no host name and no address, so "
            "nothing in it says which server it is valid for. Request the "
            "researcher to reissue its certificate for the hosts nodes reach "
            "it at."
        )

    others = [d for d in self.list() if d["component_id"] != component_id]

    # A node communicates with a single researcher, so it holds one certificate
    if registering_on_node and others:
        registered = ", ".join(f"`{d['component_id']}`" for d in others)
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: This node already has a certificate "
            f"registered for {registered}, and the one given belongs to another "
            f"component, `{component_id}`. A node connects to a single researcher, "
            "so it holds only that researcher's certificate: to register this one "
            f"instead, delete the certificate registered for {registered} first. "
            "Replacing a registered certificate only applies to the same component."
        )

    # A researcher registers one certificate per node, so the same one
    # under two component ids would identify neither.
    duplicates = [
        d["component_id"]
        for d in others
        if certificate_fingerprint(d["certificate"]) == fingerprint
    ]
    if duplicates:
        registered = ", ".join(f"`{d}`" for d in duplicates)
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: This certificate is already "
            f"registered under {registered}, and a certificate identifies a "
            f"single component. Delete that registration, or register a "
            f"certificate of its own for `{component_id}`."
        )

    self._insert(
        certificate=certificate,
        component_id=component_id,
        upsert=upsert,
    )

    # Reported here because a node hears about the researcher certificate it pins
    # nowhere else: only the researcher watches its registry for expiries.
    if expiry <= now + timedelta(days=CERTIFICATE_EXPIRY_WARNING_DAYS):
        logger.warning(
            f"Certificate `{component_id}` expires on {expiry:%Y-%m-%d}; "
            "register an updated certificate to avoid connection failures."
        )

    return component_id
register_certificate
register_certificate(
    certificate_path, component_id=None, upsert=False
)

Registers the certificate stored at the given path.

Reads the file; register holds the rules, the meaning of every other argument and the returned component id.

Raises:

Type Description
FedbiomedCertificateError

the path is not a file, or register rejects the certificate.

Source code in fedbiomed/common/certificate_manager.py
def register_certificate(
    self,
    certificate_path: str,
    component_id: Optional[str] = None,
    upsert: bool = False,
) -> str:
    """Registers the certificate stored at the given path.

    Reads the file; `register` holds the rules, the meaning of every other
    argument and the returned component id.

    Raises:
        FedbiomedCertificateError: the path is not a file, or `register` rejects
            the certificate.
    """
    if not os.path.isfile(certificate_path):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Certificate path does not represents a file."
        )

    return self.register(
        certificate=read_file(certificate_path),
        component_id=component_id,
        upsert=upsert,
    )

TrustedCertificateBundle

TrustedCertificateBundle(db_path)

Registered certificates, for mutual authentication.

Answers the two questions the researcher asks of its registry: which certificates to trust (the PEM bundle, as the trusted-certificate source of the gRPC server) and, for a certificate a peer presented, which component it is registered as. Each call re-reads the certificate database, so certificates registered or deleted after startup take effect without a restart; an absent database reads as no certificate. Thread-safe: called from gRPC handshake threads.

Certificates expiring within CERTIFICATE_EXPIRY_WARNING_DAYS are reported once each, on the first read after they enter that window.

Source code in fedbiomed/common/certificate_manager.py
def __init__(self, db_path: str):
    """
    Args:
        db_path: Path of the certificate database.
    """
    self._db_path = db_path
    self._lock = threading.Lock()
    self._bundle: bytes = b""
    self._component_ids: Dict[bytes, str] = {}
    self._warned: set = set()

Methods:

component_id
component_id(certificate)

Component id the given certificate is registered under.

The authoritative identity of a peer: every registered certificate has a component id, taken from its own CN= field or supplied at registration, so this also identifies certificates embedding no Fed-BioMed identity.

Parameters:

Name Type Description Default
certificate Union[bytes, str]

PEM encoded certificate, as presented by the peer.

required

Returns:

Type Description
Optional[str]

The registered component id, or None if the certificate is unparsable,

Optional[str]

not registered, or registered under more than one component id.

Source code in fedbiomed/common/certificate_manager.py
def component_id(self, certificate: Union[bytes, str]) -> Optional[str]:
    """Component id the given certificate is registered under.

    The authoritative identity of a peer: every registered certificate has a
    component id, taken from its own `CN=` field or supplied at registration, so
    this also identifies certificates embedding no Fed-BioMed identity.

    Args:
        certificate: PEM encoded certificate, as presented by the peer.

    Returns:
        The registered component id, or None if the certificate is unparsable,
        not registered, or registered under more than one component id.
    """
    fingerprint = certificate_fingerprint(certificate)
    if fingerprint is None:
        return None

    with self._lock:
        self._refresh()
        return self._component_ids.get(fingerprint)

Functions:

back_up_file

back_up_file(path)

Copies a file aside under a fixed .bak name, returning where it went.

One backup is kept, of the file that was replaced last: a new one overwrites it, so a component never accumulates the keys it has retired. A copy rather than a move: the file stays readable at its own path until it is overwritten, so a failure midway leaves the component with the file it was already serving.

Returns:

Type Description
Optional[str]

Path of the backup, or None when there was no file to back up.

Source code in fedbiomed/common/certificate_manager.py
def back_up_file(path: str) -> Optional[str]:
    """Copies a file aside under a fixed `.bak` name, returning where it went.

    One backup is kept, of the file that was replaced last: a new one overwrites
    it, so a component never accumulates the keys it has retired. A copy rather
    than a move: the file stays readable at its own path until it is overwritten,
    so a failure midway leaves the component with the file it was already serving.

    Returns:
        Path of the backup, or None when there was no file to back up.
    """
    if not os.path.isfile(path):
        return None

    backup = f"{path}.bak"
    shutil.copy2(path, backup)

    return backup

certificate_audit_fields

certificate_audit_fields(certificate)

Identifying fields of a peer certificate, for security audit events.

Reports the certificate a peer authenticated with precisely enough to trace it back to an issued credential, without emitting the certificate itself. Called while logging a connection, so a certificate that cannot be described yields an empty dict instead of raising into the connection path.

Source code in fedbiomed/common/certificate_manager.py
def certificate_audit_fields(certificate: Union[bytes, str]) -> Dict[str, str]:
    """Identifying fields of a peer certificate, for security audit events.

    Reports the certificate a peer authenticated with precisely enough to trace
    it back to an issued credential, without emitting the certificate itself.
    Called while logging a connection, so a certificate that cannot be described
    yields an empty dict instead of raising into the connection path.
    """
    if isinstance(certificate, str):
        certificate = certificate.encode("utf-8")
    try:
        cert = x509.load_pem_x509_certificate(certificate)
        fields = {
            "cert_subject": cert.subject.rfc4514_string(),
            "cert_issuer": cert.issuer.rfc4514_string(),
            # Hex, as serials exceed what JSON consumers hold exactly as integers.
            "cert_serial": f"{cert.serial_number:x}",
            "cert_not_after": f"{cert.not_valid_after_utc:%Y-%m-%dT%H:%M:%SZ}",
        }
    except (TypeError, ValueError, AttributeError):
        return {}

    try:
        extension = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName)
        san_names = [str(entry.value) for entry in extension.value]
    except (x509.ExtensionNotFound, TypeError, ValueError, AttributeError):
        san_names = []
    if san_names:
        fields["cert_san"] = ",".join(san_names)

    return fields

certificate_component_id

certificate_component_id(certificate)

Component id of a PEM certificate, or None if Fed-BioMed did not issue it.

The CommonName counts as a component id only on a certificate whose organization is Fed-BioMed; any other issuer puts what it likes there. Self-asserted, so it says how to read the field, not that the certificate is trusted.

Source code in fedbiomed/common/certificate_manager.py
def certificate_component_id(certificate: Union[bytes, str]) -> Optional[str]:
    """Component id of a PEM certificate, or None if Fed-BioMed did not issue it.

    The CommonName counts as a component id only on a certificate whose organization is
    Fed-BioMed; any other issuer puts what it likes there. Self-asserted, so it says how
    to read the field, not that the certificate is trusted.
    """
    if isinstance(certificate, str):
        certificate = certificate.encode("utf-8")

    organization = certificate_subject_field(certificate, NameOID.ORGANIZATION_NAME)
    if organization != CERT_ORGANIZATION:
        return None

    return certificate_subject_field(certificate, NameOID.COMMON_NAME)

certificate_expiry

certificate_expiry(certificate)

Expiry date (notAfter, UTC) of a PEM certificate, or None if unparsable.

Source code in fedbiomed/common/certificate_manager.py
def certificate_expiry(certificate: Union[bytes, str]) -> Optional[datetime]:
    """Expiry date (`notAfter`, UTC) of a PEM certificate, or None if unparsable."""
    if isinstance(certificate, str):
        certificate = certificate.encode("utf-8")
    try:
        return x509.load_pem_x509_certificate(certificate).not_valid_after_utc
    except (TypeError, ValueError):
        return None

certificate_fingerprint

certificate_fingerprint(certificate)

SHA-256 fingerprint of a PEM certificate, or None if unparsable.

Identifies a certificate by what it contains rather than by its PEM text, which TLS layers re-encode: the certificate a peer presents is compared to the registered one on this value.

Source code in fedbiomed/common/certificate_manager.py
def certificate_fingerprint(certificate: Union[bytes, str]) -> Optional[bytes]:
    """SHA-256 fingerprint of a PEM certificate, or None if unparsable.

    Identifies a certificate by what it contains rather than by its PEM text,
    which TLS layers re-encode: the certificate a peer presents is compared to
    the registered one on this value.
    """
    if isinstance(certificate, str):
        certificate = certificate.encode("utf-8")
    try:
        return x509.load_pem_x509_certificate(certificate).fingerprint(hashes.SHA256())
    except (TypeError, ValueError):
        return None

certificate_san_names

certificate_san_names(certificate)

Hosts and addresses a certificate is valid for.

Read from the Subject Alternative Name, the only place a certificate states them: the Common Name is free text and carries no host.

Only dNSName and iPAddress entries, the two TLS matches a server name against; an e-mail address, a URI or a blank entry names no server.

Parameters:

Name Type Description Default
certificate Union[bytes, str]

PEM encoded certificate.

required

Returns:

Type Description
List[str]

The host names and addresses the certificate is valid for, empty when it

List[str]

declares none or cannot be read.

Source code in fedbiomed/common/certificate_manager.py
def certificate_san_names(certificate: Union[bytes, str]) -> List[str]:
    """Hosts and addresses a certificate is valid for.

    Read from the Subject Alternative Name, the only place a certificate states
    them: the Common Name is free text and carries no host.

    Only `dNSName` and `iPAddress` entries, the two TLS matches a server name
    against; an e-mail address, a URI or a blank entry names no server.

    Args:
        certificate: PEM encoded certificate.

    Returns:
        The host names and addresses the certificate is valid for, empty when it
        declares none or cannot be read.
    """
    if isinstance(certificate, str):
        certificate = certificate.encode("utf-8")

    try:
        extensions = x509.load_pem_x509_certificate(certificate).extensions
        return [
            str(entry.value)
            for entry in extensions.get_extension_for_class(
                x509.SubjectAlternativeName
            ).value
            if isinstance(entry, (x509.DNSName, x509.IPAddress))
            # Kept as written, since that is the name TLS matches
            and str(entry.value).strip()
        ]
    except (x509.ExtensionNotFound, TypeError, ValueError, AttributeError):
        return []

certificate_subject_field

certificate_subject_field(certificate, oid)

Extracts a subject field (e.g. CN= or O=) from a PEM certificate.

Parameters:

Name Type Description Default
certificate bytes

PEM encoded certificate.

required
oid ObjectIdentifier

Subject attribute OID, e.g. x509.oid.NameOID.COMMON_NAME.

required

Returns:

Type Description
Optional[str]

The field value, or None if absent or unparsable.

Source code in fedbiomed/common/certificate_manager.py
def certificate_subject_field(
    certificate: bytes, oid: x509.ObjectIdentifier
) -> Optional[str]:
    """Extracts a subject field (e.g. `CN=` or `O=`) from a PEM certificate.

    Args:
        certificate: PEM encoded certificate.
        oid: Subject attribute OID, e.g. `x509.oid.NameOID.COMMON_NAME`.

    Returns:
        The field value, or None if absent or unparsable.
    """
    try:
        return (
            x509.load_pem_x509_certificate(certificate)
            .subject.get_attributes_for_oid(oid)[0]
            .value
        )
    except (IndexError, AttributeError, TypeError, ValueError):
        return None

generate_certificate

generate_certificate(
    root,
    component_id,
    component_type,
    prefix=None,
    host=None,
)

Issues a component its certificate, under its own root, at creation.

Refuses to replace one already there: the private key that goes with it is the component's identity, and the parties it talks to registered the certificate.

Parameters:

Name Type Description Default
root

Root directory of the component.

required
component_id

ID of the component for which the certificate will be generated

required
component_type str

Type of that component, which decides what the certificate declares and which hosts it is issued for.

required
prefix Optional[str]

Base name shared by the certificate files.

None
host Optional[str]

Host the component is reached at, required for a researcher.

None

Returns:

Name Type Description
key_file str

The path where private key file is saved

pem_file str

The path where public key file is saved

Raises:

Type Description
FedbiomedCertificateError

If certificate directory for the component has already certificate.pem or certificate.key files generated; if the component type is neither NODE nor RESEARCHER; or if a host is given for a component whose certificate names none, or missing for one that needs it.

Source code in fedbiomed/common/certificate_manager.py
def generate_certificate(
    root,
    component_id,
    component_type: str,
    prefix: Optional[str] = None,
    host: Optional[str] = None,
) -> Tuple[str, str]:
    """Issues a component its certificate, under its own root, at creation.

    Refuses to replace one already there: the private key that goes with it is the
    component's identity, and the parties it talks to registered the certificate.

    Args:
        root: Root directory of the component.
        component_id: ID of the component for which the certificate will be generated
        component_type: Type of that component, which decides what the certificate
            declares and which hosts it is issued for.
        prefix: Base name shared by the certificate files.
        host: Host the component is reached at, required for a researcher.

    Returns:
        key_file: The path where private key file is saved
        pem_file: The path where public key file is saved

    Raises:
        FedbiomedCertificateError: If certificate directory for the component has already
            `certificate.pem` or `certificate.key` files generated; if the component
            type is neither `NODE` nor `RESEARCHER`; or if a host is given for a
            component whose certificate names none, or missing for one that needs it.
    """

    certificate_path = os.path.join(root, CERTS_FOLDER_NAME)

    if os.path.isdir(certificate_path) and (
        os.path.isfile(os.path.join(certificate_path, "certificate.key"))
        or os.path.isfile(os.path.join(certificate_path, "certificate.pem"))
    ):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: Certificate generation is aborted. Directory "
            f"{certificate_path} has already certificates. Please remove those files to "
            "regenerate"
        )

    os.makedirs(certificate_path, exist_ok=True)

    return generate_component_certificate(
        component_type=component_type,
        component_id=component_id,
        folder=certificate_path,
        name=prefix if prefix else "",
        host=host,
    )

generate_component_certificate

generate_component_certificate(
    component_type,
    component_id,
    folder,
    name,
    host=None,
    extra_san=None,
)

Issues the certificate a component serves, as its type calls for.

Both the TLS role and the hosts the certificate is issued for follow from the component type alone, so every caller issuing on a component's behalf — its creation, the CLI, the GUI — produces the same certificate: a researcher serves and is verified by name, so it is issued for the host it is reached at; a node dials and is resolved by fingerprint, so it is issued for no host.

Parameters:

Name Type Description Default
component_type str

Type of the component the certificate identifies, NODE or RESEARCHER.

required
component_id str

ID of the component, which the certificate identifies.

required
folder str

Absolute path the .key and .pem files are written in.

required
name str

Base name shared by both files.

required
host Optional[str]

Host the component is reached at, required for a researcher.

None
extra_san Optional[List[str]]

Further hosts and addresses a researcher is reached at.

None

Returns:

Name Type Description
key_file str

The path where private key file is saved

pem_file str

The path where public key file is saved

Raises:

Type Description
FedbiomedCertificateError

the component type is neither NODE nor RESEARCHER; a host is given for a component whose certificate names none, or missing for one whose certificate needs it; or the files cannot be written.

Source code in fedbiomed/common/certificate_manager.py
def generate_component_certificate(
    component_type: str,
    component_id: str,
    folder: str,
    name: str,
    host: Optional[str] = None,
    extra_san: Optional[List[str]] = None,
) -> Tuple[str, str]:
    """Issues the certificate a component serves, as its type calls for.

    Both the TLS role and the hosts the certificate is issued for follow from the
    component type alone, so every caller issuing on a component's behalf — its
    creation, the CLI, the GUI — produces the same certificate: a researcher
    serves and is verified by name, so it is issued for the host it is reached at;
    a node dials and is resolved by fingerprint, so it is issued for no host.

    Args:
        component_type: Type of the component the certificate identifies, `NODE`
            or `RESEARCHER`.
        component_id: ID of the component, which the certificate identifies.
        folder: Absolute path the `.key` and `.pem` files are written in.
        name: Base name shared by both files.
        host: Host the component is reached at, required for a researcher.
        extra_san: Further hosts and addresses a researcher is reached at.

    Returns:
        key_file: The path where private key file is saved
        pem_file: The path where public key file is saved

    Raises:
        FedbiomedCertificateError: the component type is neither `NODE` nor
            `RESEARCHER`; a host is given for a component whose certificate names
            none, or missing for one whose certificate needs it; or the files
            cannot be written.
    """
    component_type = _validated_component_type(component_type)

    if component_type == ComponentType.NODE.name:
        if host or extra_san:
            raise FedbiomedCertificateError(
                f"{ErrorNumbers.FB619.value}: A node is never verified by name, so "
                "its certificate is issued for no host and takes none."
            )
        san = None
    else:
        if not host:
            raise FedbiomedCertificateError(
                f"{ErrorNumbers.FB619.value}: A researcher is verified by name, so "
                "its certificate is issued for the host nodes reach it at, which "
                "has to be given."
            )
        san = [host, *(extra_san or [])]

    return CertificateManager.generate_self_signed_ssl_certificate(
        certificate_folder=folder,
        certificate_name=name,
        component_id=component_id,
        purpose=_COMPONENT_PURPOSE[component_type],
        san=san,
    )

is_loopback_name

is_loopback_name(name)

Whether a host name or address is one of the forms of the local machine.

Source code in fedbiomed/common/certificate_manager.py
def is_loopback_name(name: str) -> bool:
    """Whether a host name or address is one of the forms of the local machine."""
    try:
        address = ipaddress.ip_address(name)
    except ValueError:
        return name.lower() == "localhost"

    # `is_loopback` follows the mapping itself only from CPython 3.11.10 on.
    mapped = getattr(address, "ipv4_mapped", None)
    return (address if mapped is None else mapped).is_loopback

san_entry

san_entry(name)

The SAN entry a host name or address belongs in.

TLS never matches an address against a dNSName entry, so an IP literal is issued as an iPAddress and everything else as a name.

Source code in fedbiomed/common/certificate_manager.py
def san_entry(name: str) -> x509.GeneralName:
    """The SAN entry a host name or address belongs in.

    TLS never matches an address against a `dNSName` entry, so an IP literal is
    issued as an `iPAddress` and everything else as a name.
    """
    try:
        return x509.IPAddress(ipaddress.ip_address(name))
    except ValueError:
        return x509.DNSName(name)

validate_certificate_pair

validate_certificate_pair(
    certificate, private_key, component_id=None
)

Checks a certificate and private key can serve as a component's identity.

What a component would otherwise discover at startup or mid-handshake is checked here instead, while the pair it currently serves is still in place.

Raises:

Type Description
FedbiomedCertificateError

either part is unreadable, the key does not belong to the certificate, the certificate is outside its validity window, or Fed-BioMed issued it for a component other than component_id.

Source code in fedbiomed/common/certificate_manager.py
def validate_certificate_pair(
    certificate: str, private_key: str, component_id: Optional[str] = None
) -> None:
    """Checks a certificate and private key can serve as a component's identity.

    What a component would otherwise discover at startup or mid-handshake is
    checked here instead, while the pair it currently serves is still in place.

    Raises:
        FedbiomedCertificateError: either part is unreadable, the key does not
            belong to the certificate, the certificate is outside its validity
            window, or Fed-BioMed issued it for a component other than
            `component_id`.
    """
    try:
        parsed = x509.load_pem_x509_certificate(certificate.encode("utf-8"))
    except (TypeError, ValueError) as exp:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate is not readable PEM: {exp}"
        ) from exp

    try:
        parsed_key = serialization.load_pem_private_key(
            private_key.encode("utf-8"), password=None
        )
    except (TypeError, ValueError, UnsupportedAlgorithm) as exp:
        # The underlying error is an OpenSSL dump that tells the user nothing.
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The private key could not be read. It has "
            "to be an unencrypted private key in PEM format."
        ) from exp

    if _public_key_bytes(parsed_key.public_key()) != _public_key_bytes(
        parsed.public_key()
    ):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The private key does not match the "
            "certificate, so this pair could never complete a handshake."
        )

    now = datetime.now(timezone.utc)
    if parsed.not_valid_after_utc < now:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate expired on "
            f"{parsed.not_valid_after_utc:%Y-%m-%d}, so every connection made with it "
            "would fail."
        )

    if parsed.not_valid_before_utc > now:
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate is not valid before "
            f"{parsed.not_valid_before_utc:%Y-%m-%d %H:%M} UTC, so every connection "
            "made with it would fail until then."
        )

    certificate_id = certificate_component_id(certificate)
    if component_id is not None and certificate_id not in (None, component_id):
        raise FedbiomedCertificateError(
            f"{ErrorNumbers.FB619.value}: The certificate was issued by Fed-BioMed "
            f"for `{certificate_id}`, not for this component, `{component_id}`. "
            "Install a pair issued for this component."
        )

write_certificate_pair

write_certificate_pair(config, certificate, private_key)

Writes a pair to the paths a component's configuration points at.

Every surface writes here rather than anywhere of its own, so the component keeps reading the files its configuration already names. The pair that was in place is kept as the single backup, replacing the one kept before it. The certificate is written re-encoded as PEM.

Returns:

Type Description
Dict[str, Optional[str]]

Where each displaced file was backed up, by role, with None for a role

Dict[str, Optional[str]]

that had no file in place.

Source code in fedbiomed/common/certificate_manager.py
def write_certificate_pair(
    config: Config, certificate: str, private_key: str
) -> Dict[str, Optional[str]]:
    """Writes a pair to the paths a component's configuration points at.

    Every surface writes here rather than anywhere of its own, so the component
    keeps reading the files its configuration already names. The pair that was in
    place is kept as the single backup, replacing the one kept before it. The
    certificate is written re-encoded as PEM.

    Returns:
        Where each displaced file was backed up, by role, with None for a role
        that had no file in place.
    """
    # `cryptography` reads a PEM whose line breaks were lost, e.g. pasted on one
    # line, which the OpenSSL gRPC loads it with does not: written re-encoded.
    certificate = (
        x509.load_pem_x509_certificate(certificate.encode("utf-8"))
        .public_bytes(serialization.Encoding.PEM)
        .decode("utf-8")
    )

    certificate_path = config.getpath("certificate", "public_key")
    private_key_path = config.getpath("certificate", "private_key")

    backups = {
        "certificate": back_up_file(certificate_path),
        "private_key": back_up_file(private_key_path),
    }
    # A retired key is still key material, and `back_up_file` copies the mode the
    # file had: one issued before the mode was restricted would stay readable.
    if backups["private_key"]:
        os.chmod(backups["private_key"], _PRIVATE_KEY_FILE_MODE)

    for path in (certificate_path, private_key_path):
        os.makedirs(os.path.dirname(path), exist_ok=True)

    with open(certificate_path, "w") as file:
        file.write(certificate)

    # The key may have arrived over HTTP; it is not left readable to anyone but
    # the component. Opened restricted, so it is never briefly readable either.
    descriptor = os.open(
        private_key_path,
        os.O_WRONLY | os.O_CREAT | os.O_TRUNC,
        _PRIVATE_KEY_FILE_MODE,
    )
    with open(descriptor, "w") as file:
        file.write(private_key)
    # `os.open` applies the mode only to a file it creates.
    os.chmod(private_key_path, _PRIVATE_KEY_FILE_MODE)

    return backups