authkeyline 0.2.0__py3-none-any.whl

authkeyline/__init__.py

@@ -0,0 +1,27 @@
+"""Parse, check and safely build OpenSSH authorized_keys lines into typed records."""
+
+from __future__ import annotations
+
+from ._codec import LineProblem, build_line, check_file, parse_file, parse_line
+from ._errors import AuthKeyError
+from ._keytypes import KEY_TYPES as _KEY_TYPES
+from ._model import AuthorizedKey, KeyOption
+from ._records import Certificate, PublicKey
+
+__version__ = "0.2.0"
+
+KEY_TYPES: frozenset[str] = frozenset(_KEY_TYPES)
+
+__all__ = [
+    "KEY_TYPES",
+    "AuthKeyError",
+    "AuthorizedKey",
+    "Certificate",
+    "KeyOption",
+    "LineProblem",
+    "PublicKey",
+    "build_line",
+    "check_file",
+    "parse_file",
+    "parse_line",
+]

authkeyline/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m authkeyline``."""
+
+from __future__ import annotations
+
+import sys
+
+from ._cli import main
+
+sys.exit(main())

authkeyline/_blob.py

@@ -0,0 +1,94 @@
+"""Decode and check a public key blob the way sshkey_fromb does."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+
+from ._cert import read_certificate
+from ._curves import CURVES, check_point
+from ._errors import AuthKeyError
+from ._keytypes import KEY_TYPES, PLAIN_NAMES, KeyType, short_name
+from ._records import PublicKey
+from ._wire import Reader, put_mpint, put_string
+
+# sshkey.h SSH_RSA_MINIMUM_MODULUS_SIZE; crypto_api.h sizes of the raw public keys.
+RSA_MIN_BITS = 1024
+ED25519_SIZE = 32
+MLDSA44_ED25519_SIZE = 1312 + 32
+# sshkey_size falls back to the impl keybits for key types without a size function.
+_FIXED_BITS = {"ed25519": 256, "ed25519-sk": 256, "mldsa44-ed25519": 512}
+# isspace() in the C locale; b64_pton skips these anywhere in the blob.
+_C_SPACE = frozenset(" \t\n\v\f\r")
+
+
+def decode_base64(text: str) -> bytes:
+    """Decode as OpenSSH's b64_pton: whitespace skipped, padding and zero spare bits required."""
+    clean = "".join(char for char in text if char not in _C_SPACE)
+    try:
+        raw = base64.b64decode(clean, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise AuthKeyError(f"key blob is not valid base64: {text[:40]!r}") from exc
+    if base64.b64encode(raw).decode("ascii") != clean:
+        raise AuthKeyError(f"key blob is not canonical base64: {text[:40]!r}")
+    return raw
+
+
+def decode_key(blob: bytes, *, allow_cert: bool = True) -> PublicKey:
+    """Decode a public key blob, checking every field; raise AuthKeyError if any is wrong."""
+    reader = Reader(blob)
+    name = reader.cstring()
+    kind = KEY_TYPES.get(name)
+    if kind is None:
+        raise AuthKeyError(f"key blob holds an unsupported key type {name!r}")
+    if kind.cert and not allow_cert:
+        raise AuthKeyError("a certificate cannot sign a certificate")
+    if kind.cert:
+        reader.string()  # nonce
+    plain, bits, application = _read_fields(reader, kind)
+    certificate = None
+    if kind.cert:
+        certificate = read_certificate(reader, lambda ca: decode_key(ca, allow_cert=False))
+    reader.finish()
+    return PublicKey(
+        key_type=name,
+        short_type=short_name(kind),
+        bits=bits,
+        blob=blob,
+        plain_blob=plain,
+        application=application,
+        certificate=certificate,
+    )
+
+
+def _read_fields(reader: Reader, kind: KeyType) -> tuple[bytes, int, str | None]:
+    """Read the key fields; return the plain blob ssh-keygen would write, bits, application."""
+    head = put_string(PLAIN_NAMES[(kind.family, kind.curve)].encode())
+    if kind.family == "rsa":
+        exponent, modulus = reader.mpint(), reader.mpint()
+        bits = modulus.bit_length()
+        if bits < RSA_MIN_BITS:
+            raise AuthKeyError(f"RSA modulus of {bits} bits is below the {RSA_MIN_BITS} bit floor")
+        return head + put_mpint(exponent) + put_mpint(modulus), bits, None
+    if kind.family in ("ed25519", "ed25519-sk", "mldsa44-ed25519"):
+        public = reader.string()
+        size = ED25519_SIZE if kind.family != "mldsa44-ed25519" else MLDSA44_ED25519_SIZE
+        if len(public) != size:
+            raise AuthKeyError(f"{kind.short} public key must be {size} bytes, not {len(public)}")
+        fields, bits = put_string(public), _FIXED_BITS[kind.family]
+    else:
+        assert kind.curve is not None
+        curve = reader.cstring()
+        if curve != kind.curve:
+            raise AuthKeyError(f"key blob names curve {curve!r}, its type needs {kind.curve!r}")
+        point = reader.string()
+        try:
+            check_point(kind.curve, point)
+        except ValueError as exc:
+            raise AuthKeyError(f"ECDSA public key {exc}") from None
+        fields, bits = put_string(curve.encode()) + put_string(point), CURVES[curve].bits
+    if not kind.family.endswith("-sk"):
+        return head + fields, bits, None
+    application = reader.cstring_bytes()
+    text = application.decode("utf-8", errors="replace")
+    return head + fields + put_string(application), bits, text

authkeyline/_cert.py

@@ -0,0 +1,65 @@
+"""The certificate body that follows the key fields (draft-miller-ssh-cert-06 section 2)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Literal
+
+from ._errors import AuthKeyError
+from ._keytypes import KEY_TYPES, SIGNATURE_NAMES
+from ._records import Certificate, PublicKey
+from ._wire import Reader
+
+# sshkey.h SSHKEY_CERT_MAX_PRINCIPALS
+MAX_PRINCIPALS = 256
+_CERT_TYPES: dict[int, Literal["user", "host"]] = {1: "user", 2: "host"}
+
+
+def read_certificate(reader: Reader, decode_ca: Callable[[bytes], PublicKey]) -> Certificate:
+    """Read serial through signature; the CA key is decoded by ``decode_ca``."""
+    serial = reader.u64()
+    type_code = reader.u32()
+    key_id = reader.cstring()
+    principals = Reader(reader.string(), "certificate principals")
+    valid_after, valid_before = reader.u64(), reader.u64()
+    critical = _pairs(reader.string(), "certificate critical options")
+    extensions = _pairs(reader.string(), "certificate extensions")
+    reader.string()  # reserved
+    ca_blob = reader.string()
+    signature = Reader(reader.string(), "certificate signature")
+    signature_type = signature.cstring()
+    ca_key = decode_ca(ca_blob)
+    ca_kind = KEY_TYPES[ca_key.key_type]
+    if signature_type not in SIGNATURE_NAMES[(ca_kind.family, ca_kind.curve)]:
+        raise AuthKeyError(
+            f"certificate signature {signature_type!r} cannot come from a {ca_kind.short} CA"
+        )
+    cert_type = _CERT_TYPES.get(type_code)
+    if cert_type is None:
+        raise AuthKeyError(f"certificate type {type_code} is neither user (1) nor host (2)")
+    names: list[str] = []
+    while not principals.at_end():
+        if len(names) >= MAX_PRINCIPALS:
+            raise AuthKeyError(f"certificate lists more than {MAX_PRINCIPALS} principals")
+        names.append(principals.cstring())
+    return Certificate(
+        cert_type=cert_type,
+        serial=serial,
+        key_id=key_id,
+        principals=tuple(names),
+        valid_after=valid_after,
+        valid_before=valid_before,
+        critical_options=critical,
+        extensions=extensions,
+        ca_key=ca_key,
+        signature_type=signature_type,
+    )
+
+
+def _pairs(data: bytes, what: str) -> tuple[tuple[str, bytes], ...]:
+    reader = Reader(data, what)
+    pairs: list[tuple[str, bytes]] = []
+    while not reader.at_end():
+        name = reader.string().decode("utf-8", errors="replace")
+        pairs.append((name, reader.string()))
+    return tuple(pairs)

authkeyline/_cli.py

@@ -0,0 +1,125 @@
+"""Command line: list the keys of authorized_keys files like ``ssh-keygen -l``, or lint them."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from typing import Any, Literal, TextIO
+
+from ._codec import check_file, parse_line
+from ._errors import AuthKeyError
+from ._model import AuthorizedKey
+from ._records import PublicKey
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line; return 1 when a line is broken, 2 when a file cannot be read."""
+    parser = argparse.ArgumentParser(
+        prog="authkeyline",
+        description="List or check the keys of OpenSSH authorized_keys files.",
+    )
+    parser.add_argument("files", nargs="*", metavar="FILE", help="files to read, - for stdin")
+    parser.add_argument("-E", dest="hash", choices=["sha256", "md5"], default="sha256")
+    parser.add_argument("--json", action="store_true", help="print the keys as JSON")
+    parser.add_argument("--check", action="store_true", help="only report broken lines")
+    args = parser.parse_args(argv)
+    names = args.files or ["-"]
+    status = 0
+    report: list[dict[str, Any]] = []
+    for name in names:
+        try:
+            text = _read(name)
+        except OSError as exc:
+            _write(sys.stderr, f"authkeyline: {name}: {exc.strerror or exc}")
+            status = 2
+            continue
+        problems = {problem.line: problem.message for problem in check_file(text)}
+        for number, message in problems.items():
+            _write(sys.stderr, f"{name}:{number}: {message}")
+        if problems:
+            status = max(status, 1)
+        if args.check:
+            continue
+        for number, raw in enumerate(text.split("\n"), start=1):
+            if number in problems:
+                continue
+            try:
+                key = parse_line(raw)
+            except AuthKeyError:
+                continue  # blank or comment line
+            if args.json:
+                report.append(_as_json(name, number, key, args.hash))
+            else:
+                _write(sys.stdout, _listing(key, args.hash))
+    if args.json:
+        _write(sys.stdout, json.dumps(report, indent=2))
+    return status
+
+
+def _read(name: str) -> str:
+    """Bytes that are not UTF-8 survive as surrogates and are written back unchanged."""
+    if name == "-":
+        stream = getattr(sys.stdin, "buffer", None)
+        return sys.stdin.read() if stream is None else _decode(stream.read())
+    with open(name, "rb") as handle:
+        return _decode(handle.read())
+
+
+def _decode(data: bytes) -> str:
+    return data.decode("utf-8", errors="surrogateescape")
+
+
+def _write(stream: TextIO, text: str) -> None:
+    raw = getattr(stream, "buffer", None)
+    if raw is None:
+        stream.write(text + "\n")
+        return
+    stream.flush()
+    raw.write(text.encode("utf-8", errors="surrogateescape") + b"\n")
+    raw.flush()
+
+
+def _listing(key: AuthorizedKey, hash: Literal["sha256", "md5"]) -> str:
+    public = key.public_key()
+    # ssh-keygen -l reads lines up to the first CR, so the shown comment stops there too.
+    comment = key.comment.split("\r", 1)[0] or "no comment"
+    return f"{public.bits} {public.fingerprint(hash)} {comment} ({public.short_type})"
+
+
+def _as_json(
+    name: str, number: int, key: AuthorizedKey, hash: Literal["sha256", "md5"]
+) -> dict[str, Any]:
+    public = key.public_key()
+    entry: dict[str, Any] = {
+        "file": name,
+        "line": number,
+        "options": [[option.name, option.value] for option in key.options],
+        "key_type": key.key_type,
+        "bits": public.bits,
+        "fingerprint": public.fingerprint(hash),
+        "comment": key.comment,
+    }
+    if public.application is not None:
+        entry["application"] = public.application
+    if public.certificate is not None:
+        entry["certificate"] = _certificate(public, hash)
+    return entry
+
+
+def _certificate(public: PublicKey, hash: Literal["sha256", "md5"]) -> dict[str, Any]:
+    cert = public.certificate
+    assert cert is not None
+    return {
+        "type": cert.cert_type,
+        "serial": cert.serial,
+        "key_id": cert.key_id,
+        "principals": list(cert.principals),
+        "valid_after": cert.valid_after,
+        "valid_before": cert.valid_before,
+        "critical_options": [name for name, _ in cert.critical_options],
+        "extensions": [name for name, _ in cert.extensions],
+        "ca_fingerprint": cert.ca_key.fingerprint(hash),
+        "signature_type": cert.signature_type,
+    }

authkeyline/_codec.py

@@ -0,0 +1,142 @@
+"""Parse, check and rebuild OpenSSH authorized_keys lines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ._errors import AuthKeyError
+from ._keytypes import KEY_TYPES
+from ._model import AuthorizedKey, KeyOption
+from ._options import read_options
+from ._optrules import VALUED, flag_name
+
+_BLANK = " \t"
+
+
+@dataclass(frozen=True)
+class LineProblem:
+    """A line of a file that sshd would not use, with the reason."""
+
+    line: int
+    message: str
+
+
+def parse_line(line: str) -> AuthorizedKey:
+    """Parse one authorized_keys line, checking it the way sshd does.
+
+    Certificate signatures are the one thing not verified (that needs a crypto library);
+    see :class:`Certificate`.
+
+    Raises :class:`AuthKeyError` for blank and comment lines, unknown or malformed options,
+    unknown key types, and blobs that do not decode to a key of the stated type.
+    """
+    text = line.removesuffix("\n")
+    if "\n" in text:
+        raise AuthKeyError("text holds more than one line")
+    # sshd works on C strings: a NUL ends the line; the comment is never looked at.
+    text = text.split("\0", 1)[0].lstrip(_BLANK).rstrip(" \t\r")
+    if not text or text.startswith("#"):
+        raise AuthKeyError("not an authorized_keys entry")
+    options: tuple[KeyOption, ...] = ()
+    if _first_field(text) not in KEY_TYPES:
+        options, end = read_options(text)
+        text = text[end:].lstrip(_BLANK)
+    key_type = _first_field(text)
+    if not key_type:
+        raise AuthKeyError("missing key type")
+    if key_type not in KEY_TYPES:
+        raise AuthKeyError(f"unsupported key type {key_type!r}")
+    rest = text[len(key_type) :].lstrip(_BLANK)
+    blob = _first_field(rest)
+    if not blob:
+        raise AuthKeyError("missing key blob")
+    comment = rest[len(blob) :].lstrip(_BLANK)
+    key = AuthorizedKey(key_type=key_type, key_base64=blob, options=options, comment=comment)
+    key.public_key()
+    return key
+
+
+def parse_file(text: str) -> list[AuthorizedKey]:
+    """Parse every key in a file, skipping blank and ``#`` comment lines.
+
+    The first bad line raises :class:`AuthKeyError` with its ``line`` number set.
+    """
+    keys: list[AuthorizedKey] = []
+    for number, raw in _entries(text):
+        try:
+            keys.append(parse_line(raw))
+        except AuthKeyError as exc:
+            raise AuthKeyError(exc.reason, number) from None
+    return keys
+
+
+def check_file(text: str) -> list[LineProblem]:
+    """Every line that sshd would skip as broken, in order; an empty list means clean.
+
+    A certificate whose signature does not verify is not caught, see :func:`parse_line`.
+    """
+    problems: list[LineProblem] = []
+    for number, raw in _entries(text):
+        try:
+            parse_line(raw)
+        except AuthKeyError as exc:
+            problems.append(LineProblem(number, exc.reason))
+    return problems
+
+
+def build_line(key: AuthorizedKey) -> str:
+    """Render an :class:`AuthorizedKey` as one line, refusing anything that would not read back.
+
+    Option names must be known flags or valued options, values cannot hold NUL, CR or LF or
+    end with a backslash, the comment cannot hold them either (sshd would cut or ignore
+    them, so a written line keeps to plain text), and the result must parse back to the
+    same record.
+    """
+    if key.key_type not in KEY_TYPES:
+        raise AuthKeyError(f"unsupported key type {key.key_type!r}")
+    if not key.key_base64 or any(char in key.key_base64 for char in " \t\r\n\0"):
+        raise AuthKeyError("key blob must be one base64 word")
+    fields = []
+    if key.options:
+        fields.append(",".join(_build_option(option) for option in key.options))
+    fields += [key.key_type, key.key_base64]
+    if key.comment:
+        if any(char in key.comment for char in "\0\r\n"):
+            raise AuthKeyError("comment holds a NUL or a line break")
+        fields.append(key.comment)
+    line = " ".join(fields)
+    if parse_line(line) != key:
+        raise AuthKeyError("the record does not read back the same; check the fields' spacing")
+    return line
+
+
+def _build_option(option: KeyOption) -> str:
+    name = option.name
+    if option.value is None:
+        if flag_name(name) is None:
+            raise AuthKeyError(f"{name!r} is not a flag option")
+        return name
+    if name.lower() not in VALUED:
+        raise AuthKeyError(f"{name!r} is not a valued option")
+    value = option.value
+    if any(char in value for char in "\0\r\n"):
+        raise AuthKeyError(f"value of {name!r} holds a NUL or a line break")
+    if value.endswith("\\"):
+        raise AuthKeyError(f"value of {name!r} ends with a backslash, which sshd cannot read")
+    return name + '="' + value.replace('"', '\\"') + '"'
+
+
+def _first_field(text: str) -> str:
+    for index, char in enumerate(text):
+        if char in _BLANK:
+            return text[:index]
+    return text
+
+
+def _entries(text: str) -> list[tuple[int, str]]:
+    entries = []
+    for number, raw in enumerate(text.split("\n"), start=1):
+        stripped = raw.lstrip(_BLANK)
+        if stripped.strip() and not stripped.startswith("#"):
+            entries.append((number, raw))
+    return entries

authkeyline/_curves.py

@@ -0,0 +1,64 @@
+"""Point checks for the NIST curves of ECDSA keys.
+
+The primes and curve coefficients are those of RFC 5903 section 3,
+https://www.rfc-editor.org/rfc/rfc5903.txt (tests/test_sources.py compares them with it).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Curve:
+    bits: int
+    p: int
+    b: int
+
+    @property
+    def size(self) -> int:
+        return (self.bits + 7) // 8
+
+
+CURVES: dict[str, Curve] = {
+    "nistp256": Curve(
+        256,
+        2**256 - 2**224 + 2**192 + 2**96 - 1,
+        int("5AC635D8AA3A93E7B3EBBD55769886BC651D06B0CC53B0F63BCE3C3E27D2604B", 16),
+    ),
+    "nistp384": Curve(
+        384,
+        2**384 - 2**128 - 2**96 + 2**32 - 1,
+        int(
+            "B3312FA7E23EE7E4988E056BE3F82D19181D9C6EFE8141120314088F5013875A"
+            "C656398D8A2ED19D2A85C8EDD3EC2AEF",
+            16,
+        ),
+    ),
+    "nistp521": Curve(
+        521,
+        2**521 - 1,
+        int(
+            "0051953EB9618E1C9A1F929A21A0B68540EEA2DA725B99B315F3B8B489918EF1"
+            "09E156193951EC7E937B1652C0BD3BB1BF073573DF883D2C34F1EF451FD46B50"
+            "3F00",
+            16,
+        ),
+    ),
+}
+
+
+def check_point(curve_name: str, point: bytes) -> None:
+    """Raise ValueError unless ``point`` is an uncompressed point on the curve.
+
+    The curves have cofactor 1, so a point on the curve that is not at infinity is in the
+    prime order group: this is what sshkey_ec_validate_public needs as well.
+    """
+    curve = CURVES[curve_name]
+    if len(point) != 1 + 2 * curve.size or point[0] != 0x04:
+        raise ValueError(f"is not an uncompressed {curve_name} point")
+    x = int.from_bytes(point[1 : 1 + curve.size], "big")
+    y = int.from_bytes(point[1 + curve.size :], "big")
+    p = curve.p
+    if x >= p or y >= p or (y * y - (x * x * x - 3 * x + curve.b)) % p:
+        raise ValueError(f"is not on the {curve_name} curve")

authkeyline/_errors.py

@@ -0,0 +1,15 @@
+"""The single error type of the library."""
+
+from __future__ import annotations
+
+
+class AuthKeyError(ValueError):
+    """Raised when text cannot be read, or a record cannot be written, as an authorized_keys entry.
+
+    ``line`` holds the 1-based line number when the error comes from a whole file.
+    """
+
+    def __init__(self, message: str, line: int | None = None) -> None:
+        super().__init__(message if line is None else f"line {line}: {message}")
+        self.reason = message
+        self.line = line

authkeyline/_keycheck.py

@@ -0,0 +1,15 @@
+"""The line-level key checks of sshkey_read."""
+
+from __future__ import annotations
+
+from ._errors import AuthKeyError
+from ._keytypes import KEY_TYPES
+
+
+def check_type_agrees(line_type: str, blob_type: str) -> None:
+    """sshd compares the key type, and the curve for ECDSA, not the exact name."""
+    line_kind = KEY_TYPES.get(line_type)
+    if line_kind is None:
+        raise AuthKeyError(f"unsupported key type {line_type!r}")
+    if line_kind.identity != KEY_TYPES[blob_type].identity:
+        raise AuthKeyError(f"line says {line_type!r} but the key blob holds {blob_type!r}")

authkeyline/_keytypes.py

@@ -0,0 +1,75 @@
+"""The key type names OpenSSH accepts in authorized_keys, from the keyimpls table of sshkey.c."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class KeyType:
+    name: str
+    family: str  # rsa, ed25519, ecdsa, ecdsa-sk, ed25519-sk, mldsa44-ed25519
+    curve: str | None
+    cert: bool
+    short: str
+
+    @property
+    def identity(self) -> tuple[str, str | None, bool]:
+        """What sshd compares between the line and the blob: key type and curve."""
+        return (self.family, self.curve, self.cert)
+
+
+def _pair(name: str, family: str, short: str, curve: str | None = None) -> list[KeyType]:
+    cert = name.replace("@openssh.com", "") + "-cert-v01@openssh.com"
+    return [KeyType(name, family, curve, False, short), KeyType(cert, family, curve, True, short)]
+
+
+_TYPES: list[KeyType] = [
+    *_pair("ssh-ed25519", "ed25519", "ED25519"),
+    *_pair("sk-ssh-ed25519@openssh.com", "ed25519-sk", "ED25519-SK"),
+    # ssh-mldsa-eddsa.c names the certificate without the -v01@openssh.com suffix.
+    KeyType("ssh-mldsa44-ed25519", "mldsa44-ed25519", None, False, "MLDSA44-ED25519"),
+    KeyType("ssh-mldsa44-ed25519-cert", "mldsa44-ed25519", None, True, "MLDSA44-ED25519"),
+    *_pair("ecdsa-sha2-nistp256", "ecdsa", "ECDSA", "nistp256"),
+    *_pair("ecdsa-sha2-nistp384", "ecdsa", "ECDSA", "nistp384"),
+    *_pair("ecdsa-sha2-nistp521", "ecdsa", "ECDSA", "nistp521"),
+    *_pair("sk-ecdsa-sha2-nistp256@openssh.com", "ecdsa-sk", "ECDSA-SK", "nistp256"),
+    *_pair("webauthn-sk-ecdsa-sha2-nistp256@openssh.com", "ecdsa-sk", "ECDSA-SK", "nistp256"),
+    *_pair("ssh-rsa", "rsa", "RSA"),
+    # RFC 8332 signature names map to the RSA key type in sshkey.c, so sshd reads them too.
+    *_pair("rsa-sha2-256", "rsa", "RSA"),
+    *_pair("rsa-sha2-512", "rsa", "RSA"),
+]
+
+KEY_TYPES: dict[str, KeyType] = {kind.name: kind for kind in _TYPES}
+
+# The name ssh-keygen writes for each plain key when it fingerprints it.
+PLAIN_NAMES: dict[tuple[str, str | None], str] = {
+    ("ed25519", None): "ssh-ed25519",
+    ("ed25519-sk", None): "sk-ssh-ed25519@openssh.com",
+    ("mldsa44-ed25519", None): "ssh-mldsa44-ed25519",
+    ("ecdsa", "nistp256"): "ecdsa-sha2-nistp256",
+    ("ecdsa", "nistp384"): "ecdsa-sha2-nistp384",
+    ("ecdsa", "nistp521"): "ecdsa-sha2-nistp521",
+    ("ecdsa-sk", "nistp256"): "sk-ecdsa-sha2-nistp256@openssh.com",
+    ("rsa", None): "ssh-rsa",
+}
+
+
+def short_name(kind: KeyType) -> str:
+    return kind.short + ("-CERT" if kind.cert else "")
+
+
+# Signature names each CA key type can produce (the sigalg entries of the sshkey.c impls).
+SIGNATURE_NAMES: dict[tuple[str, str | None], frozenset[str]] = {
+    ("ed25519", None): frozenset({"ssh-ed25519"}),
+    ("ed25519-sk", None): frozenset({"sk-ssh-ed25519@openssh.com"}),
+    ("mldsa44-ed25519", None): frozenset({"ssh-mldsa44-ed25519"}),
+    ("ecdsa", "nistp256"): frozenset({"ecdsa-sha2-nistp256"}),
+    ("ecdsa", "nistp384"): frozenset({"ecdsa-sha2-nistp384"}),
+    ("ecdsa", "nistp521"): frozenset({"ecdsa-sha2-nistp521"}),
+    ("ecdsa-sk", "nistp256"): frozenset(
+        {"sk-ecdsa-sha2-nistp256@openssh.com", "webauthn-sk-ecdsa-sha2-nistp256@openssh.com"}
+    ),
+    ("rsa", None): frozenset({"ssh-rsa", "rsa-sha2-256", "rsa-sha2-512"}),
+}

authkeyline/_model.py

@@ -0,0 +1,69 @@
+"""Typed records for a single OpenSSH authorized_keys line."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ._blob import decode_base64, decode_key
+from ._keycheck import check_type_agrees
+from ._records import PublicKey
+
+
+@dataclass(frozen=True)
+class KeyOption:
+    """One entry of the leading options field.
+
+    A flag (``no-pty``) has ``value`` set to ``None``. A valued option (``command="..."``)
+    keeps the text between the quotes in ``value``, with ``\\"`` turned into ``"``.
+    ``name`` is kept as written; sshd compares option names case-insensitively.
+    """
+
+    name: str
+    value: str | None = None
+
+
+@dataclass(frozen=True)
+class AuthorizedKey:
+    """A parsed authorized_keys line: options, key type, base64 blob and comment."""
+
+    key_type: str
+    key_base64: str
+    options: tuple[KeyOption, ...] = ()
+    comment: str = ""
+
+    def key_bytes(self) -> bytes:
+        """Decode the base64 blob to raw bytes."""
+        return decode_base64(self.key_base64)
+
+    def public_key(self) -> PublicKey:
+        """Decode and check the blob; its type must agree with ``key_type``."""
+        key = decode_key(self.key_bytes())
+        check_type_agrees(self.key_type, key.key_type)
+        return key
+
+    def fingerprint(self, hash: Literal["sha256", "md5"] = "sha256") -> str:
+        """The key fingerprint as ``ssh-keygen -l -E <hash>`` prints it."""
+        return self.public_key().fingerprint(hash)
+
+    def values(self, name: str) -> tuple[str, ...]:
+        """The values of every option called ``name``, compared case-insensitively."""
+        wanted = name.lower()
+        return tuple(
+            option.value
+            for option in self.options
+            if option.value is not None and option.name.lower() == wanted
+        )
+
+    def environment(self) -> dict[str, str]:
+        """The ``environment`` options as a mapping; the first value of a name wins, as in sshd."""
+        variables: dict[str, str] = {}
+        for value in self.values("environment"):
+            name, _, text = value.partition("=")
+            variables.setdefault(name, text)
+        return variables
+
+    def has_flag(self, name: str) -> bool:
+        """Whether the flag ``name`` (``restrict``, ``no-pty``) is set, case-insensitively."""
+        wanted = name.lower()
+        return any(o.value is None and o.name.lower() == wanted for o in self.options)

authkeyline/_options.py

@@ -0,0 +1,97 @@
+"""Read the options field exactly as sshauthopt_parse walks it."""
+
+from __future__ import annotations
+
+from ._errors import AuthKeyError
+from ._model import KeyOption
+from ._optrules import (
+    ENV_MAX,
+    PERMIT_MAX,
+    SINGLE_VALUED,
+    VALUED,
+    check_value,
+    flag_name,
+)
+
+_END = " \t"
+
+
+def read_options(text: str) -> tuple[tuple[KeyOption, ...], int]:
+    """Parse options from the start of ``text``; return them and the offset where they end.
+
+    Like sshd, an empty element between commas is skipped and a comma followed by
+    whitespace ends the field; a comma at the very end is an error.
+    """
+    options: list[KeyOption] = []
+    pos = 0
+    while pos < len(text) and text[pos] not in _END:
+        if text[pos] != ",":
+            option, pos = _read_one(text, pos)
+            options.append(option)
+            if pos == len(text) or text[pos] in _END:
+                break
+            if text[pos] != ",":
+                raise AuthKeyError(f"unexpected {text[pos]!r} after option {option.name!r}")
+        pos += 1
+        if pos == len(text):
+            raise AuthKeyError("options end with a comma")
+    check_options(options)
+    return tuple(options), pos
+
+
+def _read_one(text: str, pos: int) -> tuple[KeyOption, int]:
+    end = pos
+    while end < len(text) and text[end] not in ',= \t"':
+        end += 1
+    name = text[pos:end]
+    if end < len(text) and text[end] == "=":
+        if name.lower() not in VALUED:
+            raise AuthKeyError(f"unknown option {name!r}" if name else "empty option name")
+        value, end = dequote(text, end + 1, name)
+        return KeyOption(name, value), end
+    if flag_name(name) is None:
+        raise AuthKeyError(f"unknown option {name!r}" if name else f"unexpected {text[pos]!r}")
+    return KeyOption(name), end
+
+
+def dequote(text: str, pos: int, name: str) -> tuple[str, int]:
+    """opt_dequote: a backslash escapes only a double quote and is otherwise kept."""
+    if pos >= len(text) or text[pos] != '"':
+        raise AuthKeyError(f"value of {name!r} must be in double quotes")
+    out: list[str] = []
+    pos += 1
+    while pos < len(text) and text[pos] != '"':
+        if text[pos] == "\\" and text[pos + 1 : pos + 2] == '"':
+            pos += 1
+        out.append(text[pos])
+        pos += 1
+    if pos >= len(text):
+        raise AuthKeyError(f"value of {name!r} has no closing quote")
+    return "".join(out), pos + 1
+
+
+def check_options(options: list[KeyOption]) -> None:
+    """The rules across options: single-use names, value formats, sshd's count limits."""
+    seen: set[str] = set()
+    env_names: set[str] = set()
+    permits = {"permitopen": 0, "permitlisten": 0}
+    for option in options:
+        name = option.name.lower()
+        if option.value is None:
+            if flag_name(name) is None:
+                raise AuthKeyError(f"option {option.name!r} needs a value")
+            continue
+        if name not in VALUED:
+            raise AuthKeyError(f"option {option.name!r} takes no value")
+        if name in SINGLE_VALUED and name in seen:
+            raise AuthKeyError(f"option {name!r} appears more than once")
+        seen.add(name)
+        if name == "environment" and len(env_names) > ENV_MAX:
+            raise AuthKeyError("too many environment options")
+        if name in permits:
+            if permits[name] > PERMIT_MAX:
+                raise AuthKeyError(f"too many {name} options")
+            permits[name] += 1
+        check_value(name, option.value)
+        if name == "environment":
+            env_names.add(option.value.partition("=")[0])

authkeyline/_optrules.py

@@ -0,0 +1,101 @@
+"""Value rules of the valued options, as sshauthopt_parse and its helpers in misc.c apply them."""
+
+from __future__ import annotations
+
+import re
+
+from ._errors import AuthKeyError
+
+# The flags of sshd(8); the second group also takes a "no-" prefix (opt_flag allow_negate).
+PLAIN_FLAGS = frozenset({"restrict", "cert-authority"})
+NEGATABLE_FLAGS = frozenset(
+    {
+        "port-forwarding",
+        "agent-forwarding",
+        "x11-forwarding",
+        "touch-required",
+        "verify-required",
+        "pty",
+        "user-rc",
+    }
+)
+SINGLE_VALUED = frozenset({"command", "principals", "from"})
+VALUED = SINGLE_VALUED | {"expiry-time", "environment", "permitopen", "permitlisten", "tunnel"}
+
+# auth-options.h SSH_AUTHOPT_ENV_MAX and SSH_AUTHOPT_PERMIT_MAX; misc.h SSH_TUNID_MAX.
+ENV_MAX = 1024
+PERMIT_MAX = 4096
+TUNNEL_MAX = 0x7FFFFFFF - 2
+NI_MAXHOST = 1025
+
+_ENV_NAME = re.compile(r"[A-Za-z0-9_]+\Z")
+_DIGITS = re.compile(r"[0-9]+\Z")
+# strtonum (through strtoll) takes leading C whitespace and a sign before the digits.
+_STRTONUM = re.compile(r"[ \t\n\v\f\r]*[+-]?[0-9]+\Z")
+_TIME_RANGES = ((4, 6, 1, 12), (6, 8, 1, 31), (8, 10, 0, 23), (10, 12, 0, 59), (12, 14, 0, 60))
+
+
+def flag_name(name: str) -> str | None:
+    """The canonical flag a name spells, or None when it is not a flag."""
+    lower = name.lower()
+    if lower in PLAIN_FLAGS or lower in NEGATABLE_FLAGS:
+        return lower
+    if lower.startswith("no-") and lower[3:] in NEGATABLE_FLAGS:
+        return lower
+    return None
+
+
+def check_value(name: str, value: str) -> None:
+    """Raise AuthKeyError when sshd would refuse ``value`` for the valued option ``name``."""
+    if name == "environment":
+        env_name, sep, _ = value.partition("=")
+        if not sep or not _ENV_NAME.match(env_name):
+            raise AuthKeyError(f"environment={value!r} is not NAME=value with a word NAME")
+    elif name in ("permitopen", "permitlisten"):
+        _check_permit(name, value)
+    elif name == "tunnel":
+        if value.lower() != "any" and not _number_in(value, 0, TUNNEL_MAX):
+            raise AuthKeyError(f"tunnel={value!r} is not a device number or 'any'")
+    elif name == "expiry-time":
+        _check_time(value)
+
+
+def _check_permit(name: str, value: str) -> None:
+    if name == "permitlisten" and ":" not in value:
+        value = "*:" + value  # a bare port listens on every address
+    if value.startswith("["):
+        close = value.find("]")
+        if close < 0:
+            raise AuthKeyError(f"{name}={value!r} has an unclosed IPv6 bracket")
+        host, rest = value[: close + 1], value[close + 1 :]
+        if rest[:1] not in (":", "/"):
+            raise AuthKeyError(f"{name}={value!r} needs host:port")
+        port = rest[1:]
+    else:
+        cut = re.search(r"[:/]", value)
+        if cut is None:
+            raise AuthKeyError(f"{name}={value!r} needs host:port")
+        host, port = value[: cut.start()], value[cut.end() :]
+    if len(host.encode()) >= NI_MAXHOST:
+        raise AuthKeyError(f"{name} host name is too long")
+    if port != "*" and not _number_in(port, 1, 65535):
+        raise AuthKeyError(f"{name}={value!r} needs a port from 1 to 65535 or *")
+
+
+def _number_in(text: str, low: int, high: int) -> bool:
+    return bool(_STRTONUM.match(text)) and low <= int(text) <= high
+
+
+def _check_time(value: str) -> None:
+    text, utc = value, False
+    if len(text) > 1 and text[-1] in "zZ":
+        text, utc = text[:-1], True
+    elif len(text) > 3 and text[-3:].upper() == "UTC":
+        text, utc = text[:-3], True
+    if len(text) not in (8, 12, 14) or not _DIGITS.match(text):
+        raise AuthKeyError(f"expiry-time={value!r} is not YYYYMMDD[Z] or YYYYMMDDHHMM[SS][Z]")
+    for start, end, low, high in _TIME_RANGES:
+        if end <= len(text) and not low <= int(text[start:end]) <= high:
+            raise AuthKeyError(f"expiry-time={value!r} is out of range")
+    if utc and text.ljust(14, "0") == "19700101000000":
+        raise AuthKeyError(f"expiry-time={value!r} is the epoch, which sshd refuses")

authkeyline/_records.py

@@ -0,0 +1,58 @@
+"""Typed views of a decoded public key and of an OpenSSH certificate."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from dataclasses import dataclass
+from typing import Literal
+
+from ._errors import AuthKeyError
+
+
+@dataclass(frozen=True)
+class Certificate:
+    """The body of an OpenSSH certificate (draft-miller-ssh-cert).
+
+    The signature type is checked against the CA key, but the signature itself is not
+    verified: sshd verifies it and skips the line when it does not match.
+    """
+
+    cert_type: Literal["user", "host"]
+    serial: int
+    key_id: str
+    principals: tuple[str, ...]
+    valid_after: int
+    valid_before: int
+    critical_options: tuple[tuple[str, bytes], ...]
+    extensions: tuple[tuple[str, bytes], ...]
+    ca_key: PublicKey
+    signature_type: str
+
+
+@dataclass(frozen=True)
+class PublicKey:
+    """A decoded key blob.
+
+    ``key_type`` is the name inside the blob, ``short_type`` the label ssh-keygen prints
+    (``ED25519``, ``RSA-CERT``), ``bits`` the size ssh-keygen prints. ``plain_blob`` is the
+    blob of the bare key that a fingerprint is computed over, also for a certificate.
+    """
+
+    key_type: str
+    short_type: str
+    bits: int
+    blob: bytes
+    plain_blob: bytes
+    application: str | None = None
+    certificate: Certificate | None = None
+
+    def fingerprint(self, hash: Literal["sha256", "md5"] = "sha256") -> str:
+        """The fingerprint as ``ssh-keygen -l -E <hash>`` prints it."""
+        if hash == "sha256":
+            digest = hashlib.sha256(self.plain_blob).digest()
+            return "SHA256:" + base64.b64encode(digest).decode("ascii").rstrip("=")
+        if hash == "md5":
+            digest = hashlib.md5(self.plain_blob, usedforsecurity=False).digest()
+            return "MD5:" + ":".join(f"{byte:02x}" for byte in digest)
+        raise AuthKeyError(f"unknown fingerprint hash {hash!r}, use 'sha256' or 'md5'")

authkeyline/_wire.py

@@ -0,0 +1,76 @@
+"""Reader for the SSH wire types of RFC 4251 section 5, with the limits OpenSSH applies."""
+
+from __future__ import annotations
+
+from ._errors import AuthKeyError
+
+# sshbuf.h: SSHBUF_MAX_BIGNUM, 16384 bits; one extra zero byte may keep the top bit clear.
+MAX_BIGNUM_BYTES = 16384 // 8
+
+
+class Reader:
+    """Consume a byte string field by field; any shortfall raises AuthKeyError."""
+
+    def __init__(self, data: bytes, what: str = "key blob") -> None:
+        self._data = data
+        self._pos = 0
+        self._what = what
+
+    def _take(self, size: int) -> bytes:
+        end = self._pos + size
+        if end > len(self._data):
+            raise AuthKeyError(f"{self._what} is truncated")
+        chunk = self._data[self._pos : end]
+        self._pos = end
+        return chunk
+
+    def u32(self) -> int:
+        return int.from_bytes(self._take(4), "big")
+
+    def u64(self) -> int:
+        return int.from_bytes(self._take(8), "big")
+
+    def string(self) -> bytes:
+        return self._take(self.u32())
+
+    def cstring_bytes(self) -> bytes:
+        """A string that OpenSSH reads as C text: no NUL before its last byte."""
+        raw = self.string()
+        if b"\0" in raw[:-1]:
+            raise AuthKeyError(f"{self._what} has a NUL inside a text field")
+        return raw
+
+    def cstring(self) -> str:
+        return self.cstring_bytes().decode("utf-8", errors="replace")
+
+    def mpint(self) -> int:
+        raw = self.string()
+        if raw and raw[0] & 0x80:
+            raise AuthKeyError(f"{self._what} has a negative integer")
+        if len(raw) > MAX_BIGNUM_BYTES + 1 or (len(raw) == MAX_BIGNUM_BYTES + 1 and raw[0]):
+            raise AuthKeyError(f"{self._what} has an integer larger than 16384 bits")
+        return int.from_bytes(raw, "big")
+
+    def offset(self) -> int:
+        return self._pos
+
+    def at_end(self) -> bool:
+        return self._pos == len(self._data)
+
+    def finish(self) -> None:
+        if not self.at_end():
+            raise AuthKeyError(f"{self._what} has trailing bytes")
+
+
+def put_string(data: bytes) -> bytes:
+    return len(data).to_bytes(4, "big") + data
+
+
+def put_mpint(value: int) -> bytes:
+    """Minimal two's complement encoding of a non-negative integer, as sshbuf writes it."""
+    if value == 0:
+        return put_string(b"")
+    raw = value.to_bytes((value.bit_length() + 7) // 8, "big")
+    if raw[0] & 0x80:
+        raw = b"\0" + raw
+    return put_string(raw)

authkeyline-0.2.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.5
+Name: authkeyline
+Version: 0.2.0
+Summary: Parse, check and safely build OpenSSH authorized_keys lines the way sshd reads them, with fingerprints, typed and zero-dependency
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/authkeyline
+Project-URL: Issues, https://github.com/JaviLianes8/authkeyline/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/authkeyline/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authorized_keys,certificate,ecdsa,ed25519,fingerprint,openssh,public-key,security-key,ssh,sshd
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# authkeyline
+
+Parse, check and safely build OpenSSH `authorized_keys` lines into typed records,
+the way sshd reads them. Zero dependencies.
+
+## Install
+
+```
+pip install authkeyline
+```
+
+## Usage
+
+The examples use a made-up Ed25519 key (its 32 bytes are 0 to 31); every block runs as
+part of the test suite and prints what its comments say.
+
+```python
+from authkeyline import parse_line
+
+BLOB = "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"
+key = parse_line(
+    f'restrict,command="/usr/bin/backup --all",from="10.0.0.1,10.0.0.2" ssh-ed25519 {BLOB} alice@host'
+)
+
+print(key.key_type, key.comment)
+print(key.values("from"))
+print(key.has_flag("RESTRICT"))
+print(key.fingerprint())
+print(key.fingerprint("md5"))
+# ssh-ed25519 alice@host
+# ('10.0.0.1,10.0.0.2',)
+# True
+# SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA
+# MD5:0f:a2:0a:d7:38:3e:65:45:08:6b:63:84:1c:ff:dc:ba
+```
+
+Option values come back exactly as sshd sees them. Only `\"` is an escape inside the
+quotes; every other backslash is kept:
+
+```python
+from authkeyline import parse_line
+
+BLOB = "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"
+key = parse_line(f'command="echo \\"hi\\" c:\\\\temp",environment="LANG=C" ssh-ed25519 {BLOB}')
+print(key.options[0].value)
+print(key.environment())
+# echo "hi" c:\\temp
+# {'LANG': 'C'}
+```
+
+`parse_line` refuses what sshd refuses, with the reason: unknown options, unquoted
+values, a repeated `command`, a malformed `permitopen`, `environment` or `expiry-time`,
+an unknown key type, a blob that is not base64, whose embedded type differs from the line,
+whose Ed25519 key is not 32 bytes, whose ECDSA point is off the curve, or whose RSA modulus
+is under 1024 bits:
+
+```python
+from authkeyline import AuthKeyError, parse_line
+
+BLOB = "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"
+for line in [f"command=ls ssh-ed25519 {BLOB}", f"ssh-rsa {BLOB}", "no-pty ssh-ed25519 AAAA"]:
+    try:
+        parse_line(line)
+    except AuthKeyError as error:
+        print(error)
+# value of 'command' must be in double quotes
+# line says 'ssh-rsa' but the key blob holds 'ssh-ed25519'
+# key blob is truncated
+```
+
+### Building lines safely
+
+`build_line` writes a record back and refuses anything that would not read back as the
+same record: unknown option names, values with line breaks or a trailing backslash, a
+comment that breaks the line. Values cannot smuggle in other options or keys.
+
+```python
+from authkeyline import AuthKeyError, KeyOption, build_line, parse_line
+import dataclasses
+
+BLOB = "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"
+public = parse_line(f"ssh-ed25519 {BLOB} deploy")
+restricted = dataclasses.replace(
+    public, options=(KeyOption("restrict"), KeyOption("command", 'rsync --server "a b"'))
+)
+print(build_line(restricted))
+try:
+    build_line(dataclasses.replace(public, comment="x\nssh-ed25519 AAAA intruder"))
+except AuthKeyError as error:
+    print(error)
+# restrict,command="rsync --server \"a b\"" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f deploy
+# comment holds a NUL or a line break
+```
+
+### Whole files
+
+```python
+from authkeyline import check_file, parse_file
+
+BLOB = "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"
+text = f"# team keys\nssh-ed25519 {BLOB} one\n\nbogus ssh-ed25519 {BLOB} two\n"
+print(check_file(text))
+print(len(parse_file(text.replace("bogus ", ""))))
+# [LineProblem(line=4, message="unknown option 'bogus'")]
+# 2
+```
+
+`parse_file` raises on the first bad line with `error.line` set; `check_file` lists them
+all. Blank lines and `#` comments are skipped, as sshd does. To read a real file, pass
+its text: `parse_file(Path.home().joinpath(".ssh/authorized_keys").read_text())`.
+
+### Command line
+
+```
+authkeyline ~/.ssh/authorized_keys          # one line per key, like ssh-keygen -l
+authkeyline -E md5 authorized_keys           # MD5 fingerprints
+authkeyline --json authorized_keys           # options, sizes, certificate details
+authkeyline --check authorized_keys          # only report broken lines
+```
+
+Broken lines go to standard error as `FILE:LINE: reason` and the exit status is 1; a file
+that cannot be read gives status 2. The listing matches `ssh-keygen -l` byte for byte,
+comments in any encoding included (the test suite compares them).
+
+## API
+
+| Name | What it does |
+| --- | --- |
+| `parse_line(line)` | One line to an `AuthorizedKey`, checked like sshd; raises `AuthKeyError` |
+| `parse_file(text)` | Every key of a file; the first bad line raises with `.line` set |
+| `check_file(text)` | Every broken line as a `LineProblem(line, message)` |
+| `build_line(key)` | A record back to a line that reads back the same, or `AuthKeyError` |
+| `AuthorizedKey` | `options`, `key_type`, `key_base64`, `comment`; `public_key()`, `fingerprint()`, `values()`, `has_flag()`, `environment()`, `key_bytes()` |
+| `KeyOption` | `name` as written and `value` (`None` for a flag) |
+| `PublicKey` | `key_type`, `short_type`, `bits`, `application`, `certificate`, `fingerprint()` |
+| `Certificate` | `cert_type`, `serial`, `key_id`, `principals`, validity, critical options, extensions, `ca_key`, `signature_type` |
+| `LineProblem` | `line` number and `message` |
+| `KEY_TYPES` | The key type names sshd accepts, certificates included |
+| `AuthKeyError` | A `ValueError` with `reason` and `line` |
+
+## What it follows
+
+- The options grammar and rules of OpenSSH's `sshauthopt_parse` and the option list of
+  sshd(8): case-insensitive names, quoted values, `no-` forms, single `command`,
+  `principals` and `from`, `permitopen` and `permitlisten` targets, `tunnel`,
+  `expiry-time`, `environment` (first value of a name wins).
+- The key type table of OpenSSH (`ssh-ed25519`, `sk-ssh-ed25519@openssh.com`,
+  `ecdsa-sha2-nistp256/384/521`, `sk-ecdsa-sha2-nistp256@openssh.com`, `ssh-rsa`,
+  `ssh-mldsa44-ed25519`, their certificates, and the `rsa-sha2-256/512` names that sshd
+  reads as RSA keys), the blob layouts of RFC 4253, RFC 5656 and RFC 8709, and the
+  certificate format of draft-miller-ssh-cert.
+- Fingerprints are computed over the bare key, as `ssh-keygen -l` does, so a certificate
+  has the fingerprint of its key.
+
+Where it differs from sshd, on purpose:
+
+- Certificate signatures are not verified (that needs a crypto library), so a certificate
+  with a forged signature parses while sshd skips it. The signature type is checked
+  against the CA key. Certificates are rare in `authorized_keys`; CA keys marked
+  `cert-authority` are plain keys and fully checked.
+- `from=` patterns are kept as text, not matched against a client.
+- Port names such as `host:ssh` in `permitopen` are refused, since sshd resolves them
+  through the local services database, which differs per system.
+- `build_line` keeps comments and values to one line of text without NUL or CR. sshd
+  would cut a line at a NUL and ignore a CR in the comment, and `parse_line` reads such
+  lines the same way, but a written line never contains them.
+
+## Why
+
+An `authorized_keys` line packs an options field, a key type, a base64 blob and a comment
+into one string, and the options field has its own grammar. Splitting on whitespace or
+commas gets it wrong, and a builder that quotes values naively lets a value add options or
+whole keys. This library reads a line as sshd does (with the differences listed above),
+says why sshd would skip it, and writes lines that cannot be steered.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

authkeyline-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+authkeyline/__init__.py,sha256=ozP-kurDXWYdy72z9P_nc3Iir0GL6uleLJ_Lv6GI2Kc,665
+authkeyline/__main__.py,sha256=LMQBFbLv27s22HznxSiCSDcYE2h16o-9w4mufwAAeTM,129
+authkeyline/_blob.py,sha256=cmQiJgDtoPEwPgPaUgMYcgAuZdit2VtzcNo5-QcA7wM,4008
+authkeyline/_cert.py,sha256=R9oxN55z1fVD1eg7Up-hIeJnqF2gxlR16rkX59SEqGA,2502
+authkeyline/_cli.py,sha256=LaSok-MyRvfT1kV0b-eJP7o1oyULRCqi7a4gEHyQRdc,4541
+authkeyline/_codec.py,sha256=CCXc3J5typb02NuWhx3ZoV88UqEe_Kal3ehCoUmmAwc,5179
+authkeyline/_curves.py,sha256=HPPxaG_vtV_FdAAvFkXD4AQErnSouQjmjnXeaUbfv3Q,1919
+authkeyline/_errors.py,sha256=jfBujTyzSnTSfnkfgXnlCwRWZC2pTvwtG119Zs6_0pU,514
+authkeyline/_keycheck.py,sha256=swcuM0ylsJ32s6SrAxFAjhdVh3_M2Z4e9I_ZJodAnJE,585
+authkeyline/_keytypes.py,sha256=nsaLzpbsIqKPWjjpbbBJOwHxg7drZHwA-Er5Uw-CFd0,3263
+authkeyline/_model.py,sha256=zqtJjJ9KhM1zrRoRiGC8r1_R7yhiuxH3QkJxrECC3e8,2434
+authkeyline/_options.py,sha256=lj_Imth6Nj4fmvwj8Y3E4KIduKFEMtWECr653KF6ZzI,3579
+authkeyline/_optrules.py,sha256=isswOXQrEeap2Jr9LHhlgI996fIK14CDK2mGSywVP9A,4028
+authkeyline/_records.py,sha256=qYfnSu1IS_eaIds4Yw66J-pfkmtrewp8c-00e06MClE,1914
+authkeyline/_wire.py,sha256=8J8LxqUQ7-1V5FfV0Nk6UawwYcs9mPO43DFjVnqpHjs,2436
+authkeyline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+authkeyline-0.2.0.dist-info/METADATA,sha256=J7GNLdkO7B_PB4QsMZc9OWxM1-iL_WWfCPeH7in0LL4,9355
+authkeyline-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+authkeyline-0.2.0.dist-info/entry_points.txt,sha256=pBMnMfRVEqfh-9ME47a87hJWkU_Ds9BAtLCq3Nf69cg,54
+authkeyline-0.2.0.dist-info/licenses/LICENSE,sha256=_WmABlQG__oqlx4Rzp-qDJ10xND5KCLScftbhXbLC_c,1070
+authkeyline-0.2.0.dist-info/RECORD,,

authkeyline-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

authkeyline-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+authkeyline = authkeyline._cli:main

authkeyline-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+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.