pymobiledevice3 4.14.6__py3-none-any.whl → 7.0.6__py3-none-any.whl

pymobiledevice3/ca.py

@@ -1,6 +1,6 @@
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
 from cryptography import x509
 from cryptography.hazmat.primitives import hashes, serialization
@@ -10,8 +10,242 @@ from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption,
 from cryptography.x509 import Certificate
 from cryptography.x509.oid import NameOID
 
+_SERIAL = 1
+
+
+def select_hash_algorithm(device_version: Union[tuple[int, int, int], str, None]) -> hashes.HashAlgorithm:
+    """
+    Choose hash algorithm to match libimobiledevice (idevicepair) logic.
+
+    :param device_version: Device version tuple (major, minor, patch) or "a.b.c" string.
+                           If None, defaults to SHA-256 (modern).
+    :returns: SHA-1 if version < 4.0.0, else SHA-256.
+    """
+    if device_version is None:
+        return hashes.SHA256()
+    parts = tuple(int(x) for x in device_version.split(".")) if isinstance(device_version, str) else device_version
+    return hashes.SHA1() if parts < (4, 0, 0) else hashes.SHA256()
+
+
+def get_validity_bounds(years: int = 10) -> tuple[datetime, datetime]:
+    """
+    Compute notBefore / notAfter validity window.
+
+    :param years: Number of years for certificate validity.
+    :returns: (not_before, not_after) in UTC.
+    """
+    now = datetime.now(timezone.utc)
+    return now - timedelta(minutes=1), now + timedelta(days=365 * years)
+
+
+def serialize_cert_pem(cert: Certificate) -> bytes:
+    """
+    Serialize an X.509 certificate in PEM format.
+
+    :param cert: Certificate object.
+    :returns: PEM-encoded certificate bytes.
+    """
+    return cert.public_bytes(Encoding.PEM)
+
+
+def serialize_private_key_pkcs8_pem(key: RSAPrivateKey) -> bytes:
+    """
+    Serialize a private key in PKCS#8 PEM format (like OpenSSL's PEM_write_bio_PrivateKey).
+
+    :param key: RSA private key.
+    :returns: PEM-encoded PKCS#8 key bytes (unencrypted).
+    """
+    return key.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption())
+
+
+# =======================================
+# Certificate builders (empty DN, v3, KU)
+# =======================================
+
+
+def build_root_certificate(root_key: RSAPrivateKey, alg: hashes.HashAlgorithm) -> Certificate:
+    """
+    Build a self-signed root (CA) certificate:
+    - Empty subject/issuer (x509.Name([]))
+    - Serial = 1
+    - X.509 v3 with BasicConstraints CA:TRUE (critical)
+    - Signed with root_key using the chosen hash
+
+    :param root_key: RSA private key for the root CA.
+    :param alg: Hash algorithm (SHA-1 or SHA-256).
+    :returns: Root CA certificate.
+    """
+    not_before, not_after = get_validity_bounds()
+    empty = x509.Name([])
+    builder = (
+        x509.CertificateBuilder()
+        .subject_name(empty)
+        .issuer_name(empty)
+        .public_key(root_key.public_key())
+        .serial_number(_SERIAL)
+        .not_valid_before(not_before)
+        .not_valid_after(not_after)
+        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
+    )
+    return builder.sign(root_key, alg)
+
+
+def build_host_certificate(
+    host_key: RSAPrivateKey,
+    root_cert: Certificate,
+    root_key: RSAPrivateKey,
+    alg: hashes.HashAlgorithm,
+) -> Certificate:
+    """
+    Build the host (leaf) certificate signed by the root:
+    - Empty subject
+    - Issuer = root's (empty) subject
+    - Serial = 1
+    - BasicConstraints CA:FALSE (critical)
+    - KeyUsage: digitalSignature, keyEncipherment (critical)
+    - Signed with root_key
+
+    :param host_key: Host RSA private key (leaf).
+    :param root_cert: Root CA certificate.
+    :param root_key: Root RSA private key.
+    :param alg: Hash algorithm (SHA-1 or SHA-256).
+    :returns: Host certificate (leaf).
+    """
+    not_before, not_after = get_validity_bounds()
+    builder = (
+        x509.CertificateBuilder()
+        .subject_name(x509.Name([]))
+        .issuer_name(root_cert.subject)  # empty
+        .public_key(host_key.public_key())
+        .serial_number(_SERIAL)
+        .not_valid_before(not_before)
+        .not_valid_after(not_after)
+        .add_extension(x509.BasicConstraints(ca=False, path_length=None), critical=True)
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                key_encipherment=True,
+                key_cert_sign=False,
+                crl_sign=False,
+                content_commitment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=True,
+        )
+    )
+    return builder.sign(root_key, alg)
+
+
+def build_device_certificate(
+    device_public_key: RSAPublicKey,
+    root_cert: Certificate,
+    root_key: RSAPrivateKey,
+    alg: hashes.HashAlgorithm,
+) -> Certificate:
+    """
+    Build the device certificate (leaf) signed by the root:
+    - Empty subject
+    - Issuer = root's (empty) subject
+    - Serial = 1
+    - BasicConstraints CA:FALSE (critical)
+    - KeyUsage: digitalSignature, keyEncipherment (critical)
+    - SubjectKeyIdentifier = hash
+    - Signed with root_key
+
+    :param device_public_key: Device's RSA public key (as advertised by lockdown).
+    :param root_cert: Root CA certificate.
+    :param root_key: Root RSA private key.
+    :param alg: Hash algorithm (SHA-1 or SHA-256).
+    :returns: Device certificate (leaf).
+    """
+    not_before, not_after = get_validity_bounds()
+    builder = (
+        x509.CertificateBuilder()
+        .subject_name(x509.Name([]))
+        .issuer_name(root_cert.subject)  # empty
+        .public_key(device_public_key)
+        .serial_number(_SERIAL)
+        .not_valid_before(not_before)
+        .not_valid_after(not_after)
+        .add_extension(x509.BasicConstraints(ca=False, path_length=None), critical=True)
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                key_encipherment=True,
+                key_cert_sign=False,
+                crl_sign=False,
+                content_commitment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=True,
+        )
+        .add_extension(x509.SubjectKeyIdentifier.from_public_key(device_public_key), critical=False)
+    )
+    return builder.sign(root_key, alg)
+
+
+# ==========================================
+# Public API for your pairing flow (renamed)
+# ==========================================
+
+
+def generate_pairing_cert_chain(
+    device_public_key_pem: bytes,
+    private_key: Optional[RSAPrivateKey] = None,
+    device_version: Union[tuple[int, int, int], str, None] = (4, 0, 0),
+) -> tuple[bytes, bytes, bytes, bytes, bytes]:
+    """
+    Generate a root→host certificate chain and a device certificate that mirror the
+    libimobiledevice C behavior (empty DN, serial=1, BC/KU/SKI, SHA1 flip for < 4.0).
+
+    :param device_public_key_pem: Device RSA public key in PEM ("RSA PUBLIC KEY") format.
+    :param private_key: Optional host RSA private key to reuse; if None, a new one is generated.
+    :param device_version: Version to select hash (tuple or "a.b.c"). < 4.0.0 => SHA-1; else SHA-256.
+    :returns: (host_cert_pem, host_key_pem, device_cert_pem, root_cert_pem, root_key_pem)
+    """
+    alg = select_hash_algorithm(device_version)
+
+    # Root CA (self-signed)
+    root_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    root_cert = build_root_certificate(root_key, alg)
+
+    # Host leaf (reuse provided key if given)
+    host_key = private_key or rsa.generate_private_key(public_exponent=65537, key_size=2048)
+    host_cert = build_host_certificate(host_key, root_cert, root_key, alg)
+
+    # Device leaf (public key provided by the device)
+    dev_pub = load_pem_public_key(device_public_key_pem)
+    if not isinstance(dev_pub, RSAPublicKey):
+        raise TypeError("device_public_key_pem must be an RSA PUBLIC KEY in PEM format")
+    device_cert = build_device_certificate(dev_pub, root_cert, root_key, alg)
+
+    return (
+        serialize_cert_pem(host_cert),
+        serialize_private_key_pkcs8_pem(host_key),
+        serialize_cert_pem(device_cert),
+        serialize_cert_pem(root_cert),
+        serialize_private_key_pkcs8_pem(root_key),
+    )
+
 
 def make_cert(key: RSAPrivateKey, public_key: RSAPublicKey, common_name: Optional[str] = None) -> Certificate:
+    """
+    Create a simple self-signed certificate for the provided key.
+
+    NOTE: This is not suitable for pairing (it sets subject/issuer and lacks C-style fields).
+    It is preserved as-is for your keybag usage.
+
+    :param key: RSA private key for signing.
+    :param public_key: RSA public key to embed in the certificate.
+    :param common_name: Optional CN to include in subject/issuer.
+    :returns: Self-signed certificate.
+    """
     attributes = [x509.NameAttribute(NameOID.COMMON_NAME, common_name)] if common_name else []
     subject = issuer = x509.Name(attributes)
     cert = x509.CertificateBuilder()
@@ -27,27 +261,30 @@ def make_cert(key: RSAPrivateKey, public_key: RSAPublicKey, common_name: Optiona
     return cert
 
 
-def dump_cert(cert):
-    return cert.public_bytes(Encoding.PEM)
-
-
-def ca_do_everything(device_public_key, private_key: Optional[rsa.RSAPrivateKey] = None):
-    if private_key is None:
-        private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+def dump_cert(cert: Certificate) -> bytes:
+    """
+    Serialize a certificate in PEM format.
 
-    cert = make_cert(private_key, private_key.public_key())
-    dev_key = load_pem_public_key(device_public_key)
-    dev_cert = make_cert(private_key, dev_key, 'Device')
-    return dump_cert(cert), private_key.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption()), dump_cert(
-        dev_cert)
+    :param cert: Certificate object.
+    :returns: PEM-encoded certificate bytes.
+    """
+    return cert.public_bytes(Encoding.PEM)
 
 
 def create_keybag_file(file: Path, common_name: str) -> None:
+    """
+    Write a private key and a simple self-signed certificate to a file (PEM concatenated).
+
+    :param file: Destination file path.
+    :param common_name: Common Name to embed in the self-signed certificate.
+    """
     private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
     cer = make_cert(private_key, private_key.public_key(), common_name)
     file.write_bytes(
         private_key.private_bytes(
             encoding=serialization.Encoding.PEM,
             format=PrivateFormat.TraditionalOpenSSL,
-            encryption_algorithm=serialization.NoEncryption()
-        ) + cer.public_bytes(encoding=serialization.Encoding.PEM))
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+        + cer.public_bytes(encoding=serialization.Encoding.PEM)
+    )

pymobiledevice3/cli/activation.py

@@ -1,38 +1,46 @@
-import click
+from typing import Annotated
 
-from pymobiledevice3.cli.cli_common import Command
-from pymobiledevice3.lockdown import LockdownClient
-from pymobiledevice3.services.mobile_activation import MobileActivationService
-
-
-@click.group()
-def cli() -> None:
-    pass
+import typer
+from typer_injector import InjectingTyper
 
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.mobile_activation import MobileActivationService
 
-@cli.group()
-def activation() -> None:
-    """ Perform iCloud activation/deactivation or query the current state """
-    pass
+cli = InjectingTyper(
+    name="activation",
+    help="Perform iCloud activation/deactivation or query the current state",
+    no_args_is_help=True,
+)
 
 
-@activation.command(cls=Command)
-def state(service_provider: LockdownClient):
-    """ Get current activation state """
+@cli.command()
+def state(service_provider: ServiceProviderDep) -> None:
+    """Get current activation state"""
     print(MobileActivationService(service_provider).state)
 
 
-@activation.command(cls=Command)
-@click.option('--now', is_flag=True, help='when --offline is used, dont wait for next nonce cycle')
-def activate(service_provider: LockdownClient, now):
-    """ Activate device """
+@cli.command()
+def activate(
+    service_provider: ServiceProviderDep,
+    now: Annotated[
+        bool,
+        typer.Option(help="do not wait for next nonce cycle"),
+    ] = False,
+) -> None:
+    """Activate device"""
     activation_service = MobileActivationService(service_provider)
     if not now:
         activation_service.wait_for_activation_session()
     activation_service.activate()
 
 
-@activation.command(cls=Command)
-def deactivate(service_provider: LockdownClient):
-    """ Deactivate device """
+@cli.command()
+def deactivate(service_provider: ServiceProviderDep) -> None:
+    """Deactivate device"""
     MobileActivationService(service_provider).deactivate()
+
+
+@cli.command()
+def itunes(service_provider: ServiceProviderDep) -> None:
+    """Tell the device that it has been connected to iTunes (useful for < iOS 4)"""
+    service_provider.set_value(True, key="iTunesHasConnected")

pymobiledevice3/cli/afc.py

@@ -1,55 +1,64 @@
-import click
-
-from pymobiledevice3.cli.cli_common import Command
-from pymobiledevice3.lockdown import LockdownClient
-from pymobiledevice3.lockdown_service_provider import LockdownServiceProvider
-from pymobiledevice3.services.afc import AfcService, AfcShell
+from pathlib import Path
+from typing import Annotated
 
+import typer
+from typer_injector import InjectingTyper
 
-@click.group()
-def cli() -> None:
-    pass
-
+from pymobiledevice3.cli.cli_common import ServiceProviderDep
+from pymobiledevice3.services.afc import AfcService, AfcShell
 
-@cli.group()
-def afc() -> None:
-    """ Manage device multimedia files """
-    pass
+cli = InjectingTyper(
+    name="afc",
+    help="Browse, push, and pull files via the AFC service (/var/mobile/Media).",
+    no_args_is_help=True,
+)
 
 
-@afc.command('shell', cls=Command)
-def afc_shell(service_provider: LockdownClient):
-    """ open an AFC shell rooted at /var/mobile/Media """
+@cli.command("shell")
+def afc_shell(service_provider: ServiceProviderDep) -> None:
+    """Open an interactive AFC shell rooted at /var/mobile/Media."""
     AfcShell.create(service_provider)
 
 
-@afc.command('pull', cls=Command)
-@click.argument('remote_file', type=click.Path(exists=False))
-@click.argument('local_file', type=click.Path(exists=False))
-def afc_pull(service_provider: LockdownServiceProvider, remote_file: str, local_file: str) -> None:
-    """ pull remote file from /var/mobile/Media """
-    AfcService(lockdown=service_provider).pull(remote_file, local_file)
+@cli.command("pull")
+def afc_pull(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    local_file: Path,
+    ignore_errors: Annotated[
+        bool,
+        typer.Option(
+            "--ignore-errors",
+            "-i",
+            help="Continue downloading even if some files error (best-effort pull).",
+        ),
+    ],
+) -> None:
+    """Download a remote path under /var/mobile/Media to the local filesystem."""
+    AfcService(lockdown=service_provider).pull(str(remote_file), str(local_file), ignore_errors=ignore_errors)
 
 
-@afc.command('push', cls=Command)
-@click.argument('local_file', type=click.Path(exists=False))
-@click.argument('remote_file', type=click.Path(exists=False))
-def afc_push(service_provider: LockdownServiceProvider, local_file: str, remote_file: str) -> None:
-    """ push local file into /var/mobile/Media """
-    AfcService(lockdown=service_provider).push(local_file, remote_file)
+@cli.command("push")
+def afc_push(service_provider: ServiceProviderDep, local_file: Path, remote_file: Path) -> None:
+    """Upload a local file into /var/mobile/Media."""
+    AfcService(lockdown=service_provider).push(str(local_file), str(remote_file))
 
 
-@afc.command('ls', cls=Command)
-@click.argument('remote_file', type=click.Path(exists=False))
-@click.option('-r', '--recursive', is_flag=True)
-def afc_ls(service_provider: LockdownClient, remote_file, recursive):
-    """ perform a dirlist rooted at /var/mobile/Media """
-    for path in AfcService(lockdown=service_provider).dirlist(remote_file, -1 if recursive else 1):
+@cli.command("ls")
+def afc_ls(
+    service_provider: ServiceProviderDep,
+    remote_file: Path,
+    recursive: Annotated[
+        bool,
+        typer.Option("--recursive", "-r", help="Recurse into subdirectories when listing."),
+    ] = False,
+) -> None:
+    """List files under /var/mobile/Media (optionally recursively)."""
+    for path in AfcService(lockdown=service_provider).dirlist(str(remote_file), -1 if recursive else 1):
         print(path)
 
 
-@afc.command('rm', cls=Command)
-@click.argument('remote_file', type=click.Path(exists=False))
-def afc_rm(service_provider: LockdownClient, remote_file):
-    """ remove a file rooted at /var/mobile/Media """
-    AfcService(lockdown=service_provider).rm(remote_file)
+@cli.command("rm")
+def afc_rm(service_provider: ServiceProviderDep, remote_file: Path) -> None:
+    """Delete a file under /var/mobile/Media."""
+    AfcService(lockdown=service_provider).rm(str(remote_file))

pymobiledevice3/cli/amfi.py

@@ -1,38 +1,33 @@
 import logging
 
-import click
+from typer_injector import InjectingTyper
 
-from pymobiledevice3.cli.cli_common import Command, print_json
-from pymobiledevice3.lockdown import LockdownClient
+from pymobiledevice3.cli.cli_common import ServiceProviderDep, print_json
 from pymobiledevice3.services.amfi import AmfiService
 
 logger = logging.getLogger(__name__)
 
 
-@click.group()
-def cli() -> None:
-    pass
+cli = InjectingTyper(
+    name="amfi",
+    help="Enable developer-mode or query its state",
+    no_args_is_help=True,
+)
 
 
-@cli.group()
-def amfi() -> None:
-    """ Enable developer-mode or query its state """
-    pass
-
-
-@amfi.command(cls=Command)
-def reveal_developer_mode(service_provider: LockdownClient):
-    """ reveal developer mode option in device's UI """
+@cli.command()
+def reveal_developer_mode(service_provider: ServiceProviderDep) -> None:
+    """reveal developer mode option in device's UI"""
     AmfiService(service_provider).reveal_developer_mode_option_in_ui()
 
 
-@amfi.command(cls=Command)
-def enable_developer_mode(service_provider: LockdownClient):
-    """ enable developer mode """
+@cli.command()
+def enable_developer_mode(service_provider: ServiceProviderDep) -> None:
+    """enable developer mode"""
     AmfiService(service_provider).enable_developer_mode()
 
 
-@amfi.command(cls=Command)
-def developer_mode_status(service_provider: LockdownClient):
-    """ query developer mode status """
+@cli.command()
+def developer_mode_status(service_provider: ServiceProviderDep) -> None:
+    """query developer mode status"""
     print_json(service_provider.developer_mode_status)