@@ -73,6 +73,9 @@ def validate_args(args):
     if args.load_profile and not os.path.exists(args.load_profile):
         raise argparse.ArgumentError(None, 'iLEAPP Profile file not found! Run the program again.')
 
+    if args.keychain and not os.path.isfile(args.keychain):
+        raise argparse.ArgumentError(None, 'Keychain file not found! Run the program again.')
+
     try:
         pytz.timezone(args.timezone)
     except pytz.UnknownTimeZoneError as ex:
@@ -195,6 +198,10 @@ def main():
     parser.add_argument('--custom_output_folder', required=False, action="store", help="Custom name for the output folder")
     parser.add_argument('--custom_artifacts_path', required=False, action="store", help="Additional path to load artifacts from (e.g., scripts/alternate_artifacts)")
     parser.add_argument('--itunes_password', required=False, action="store", help="Password used for encrypted iTunes backup")
+    parser.add_argument('--keychain', required=False, action="store",
+                        help=("Path to a keychain file captured from the device. Some apps keep "
+                              "their database key in the keychain, which is collected separately "
+                              "from the file system extraction."))
 
     # Check if no arguments were provided
     if len(sys.argv) == 1:
@@ -333,6 +340,7 @@ def main():
     time_offset = args.timezone
     custom_output_folder = args.custom_output_folder
     itunes_backup_password = args.itunes_password
+    Context.set_keychain_path(args.keychain)
 
     # ios file system extractions contain paths > 260 char, which causes problems
     # This fixes the problem by prefixing \\?\ on each windows path.
 
@@ -493,6 +493,13 @@ def process(casedata):
         casedata = {key: value.get() for key, value in casedata.items()}
         out_params = OutputParameters(output_folder, output_folder_name_entry.get().strip())
         Context.set_output_params(out_params)
+        keychain_path = keychain_entry.get().strip()
+        if keychain_path and not os.path.isfile(keychain_path):
+            tk_msgbox.showerror(title='Error',
+                                message=f'Keychain file not found:\n{keychain_path}',
+                                parent=main_window)
+            return
+        Context.set_keychain_path(keychain_path or None)
         wrap_text = True
         time_offset = timezone_set.get()
         if time_offset == '':
@@ -594,6 +601,22 @@ def select_input(button_type):
         history.record_input_path(input_filename)
 
 
+def select_keychain():
+    '''Select a keychain file and insert its path into the keychain field'''
+    keychain_filename = tk_filedialog.askopenfilename(
+        parent=main_window,
+        title='Select a keychain file',
+        filetypes=(('Keychain files', '*.plist *.xml *.json'), ('All files', '*.*')))
+    if keychain_filename:
+        keychain_entry.delete(0, 'end')
+        keychain_entry.insert(0, keychain_filename)
+
+
+def clear_keychain():
+    '''Forget the selected keychain so it is not reused on the next case'''
+    keychain_entry.delete(0, 'end')
+
+
 def select_output():
     '''Select target and insert its path into output field'''
     output_filename = tk_filedialog.askdirectory(parent=main_window, title='Select a folder')
@@ -879,6 +902,20 @@ def close_case_window():
 input_folder_button = ttk.Button(input_frame, text='Browse Folder', command=lambda: select_input('folder'))
 input_folder_button.pack(side='left', padx=5, pady=4)
 
+### Keychain (optional)
+# iOS keychains are captured separately from the file system extraction, so apps
+# that keep their database key in the keychain need it supplied here
+keychain_frame = ttk.LabelFrame(
+    main_window,
+    text=' Optional: select a keychain file captured from the device (used to decrypt apps such as Signal): ')
+keychain_frame.pack(padx=14, pady=2, fill='x')
+keychain_entry = ttk.Entry(keychain_frame)
+keychain_entry.pack(side='left', padx=5, pady=4, fill='x', expand=True)
+keychain_clear_button = ttk.Button(keychain_frame, text='Clear', width=6, command=lambda: clear_keychain())
+keychain_clear_button.pack(side='left', padx=2, pady=4)
+keychain_file_button = ttk.Button(keychain_frame, text='Browse File', command=lambda: select_keychain())
+keychain_file_button.pack(side='left', padx=5, pady=4)
+
 output_frame = ttk.LabelFrame(main_window, text=' Select Output Path ')
 output_frame.pack(padx=14, pady=5, fill='x')
 output_path_row = ttk.Frame(output_frame)
 
@@ -27,6 +27,9 @@ class Context:
     _data_folder = None
     _metadata = {}
     _installed_os_version = ""
+    # Run-level, like the output parameters: set once from the CLI or GUI and
+    # deliberately not reset by clear() between artifacts
+    _keychain_path = None
 
     @staticmethod
     def set_output_params(output_params):
@@ -186,6 +189,27 @@ def set_installed_os_version(os_version):
         if not Context._installed_os_version:
             Context._installed_os_version = os_version
 
+    @staticmethod
+    def set_keychain_path(keychain_path):
+        """
+        Records the path to a keychain file supplied by the examiner.
+
+        iOS keychains are captured separately from the file system extraction,
+        so apps that keep their database key in the keychain cannot find it in
+        the extraction itself.
+        """
+        Context._keychain_path = keychain_path
+
+    @staticmethod
+    def get_keychain_path():
+        """
+        Returns the examiner-supplied keychain path, or None when none was given.
+
+        Artifacts must treat None as "no keychain available" and degrade rather
+        than fail, since supplying one is optional.
+        """
+        return Context._keychain_path
+
     @staticmethod
     def _build_lookup_map():
         """Builds and returns a dictionary mapping filenames to a list
 
@@ -0,0 +1,106 @@
+"""Lookup of app secrets in an examiner-supplied iOS keychain.
+
+iOS keychains are captured separately from the file system extraction, so an
+app that keeps its database key in the keychain cannot find that key inside the
+extraction. The examiner supplies the keychain with --keychain (or the field in
+the GUI) and artifacts read it through here.
+
+Apps whose keys live in the keychain include Signal and Session (both a 48 byte
+GRDBDatabaseCipherKeySpec that is a 32 byte key followed by a 16 byte salt),
+Snapchat, Trust Wallet and what3words, so the lookup is deliberately generic
+rather than written around one app.
+
+Supported inputs are the plist keychain dumps produced by extraction tools,
+which hold generic passwords under a 'genp' list. Entries carry an access group
+('agrp') naming the owning app, an account ('acct'), a service ('svce') and the
+secret itself in 'v_Data'.
+"""
+import plistlib
+
+from scripts.context import Context
+from scripts.ilapfuncs import logfunc
+
+GENERIC_PASSWORD_KEY = 'genp'
+
+_cache = {}
+
+
+def _text(entry, field):
+    """Keychain string fields are sometimes bytes and sometimes str."""
+    value = entry.get(field)
+    if isinstance(value, bytes):
+        return value.decode('utf-8', 'ignore').rstrip('\x00')
+    return str(value) if value is not None else ''
+
+
+def load_keychain_entries(keychain_path):
+    """Return the generic-password entries of a keychain plist, cached per path."""
+    if keychain_path in _cache:
+        return _cache[keychain_path]
+
+    _cache[keychain_path] = []
+    try:
+        with open(keychain_path, 'rb') as keychain_file:
+            parsed = plistlib.load(keychain_file)
+    except (OSError, ValueError) as error:
+        logfunc(f'Keychain: could not read {keychain_path}: {error}')
+        return _cache[keychain_path]
+
+    if not isinstance(parsed, dict) or GENERIC_PASSWORD_KEY not in parsed:
+        logfunc(f'Keychain: {keychain_path} is not a supported keychain dump '
+                '(no generic password entries found)')
+        return _cache[keychain_path]
+
+    entries = parsed.get(GENERIC_PASSWORD_KEY) or []
+    _cache[keychain_path] = [entry for entry in entries if isinstance(entry, dict)]
+    return _cache[keychain_path]
+
+
+def find_keychain_secrets(keychain_path, access_group=None, account=None, service=None):
+    """Return the raw secrets matching the given access group, account and service.
+
+    Each filter is optional and matched case-insensitively as a substring, so
+    'whispersystems' matches the full 'TEAMID.org.whispersystems.signal'.
+    """
+    matches = []
+    for entry in load_keychain_entries(keychain_path):
+        if access_group and access_group.lower() not in _text(entry, 'agrp').lower():
+            continue
+        if account and account.lower() not in _text(entry, 'acct').lower():
+            continue
+        if service and service.lower() not in _text(entry, 'svce').lower():
+            continue
+        secret = entry.get('v_Data')
+        if isinstance(secret, (bytes, bytearray)):
+            matches.append(bytes(secret))
+    return matches
+
+
+def get_app_secret(access_group, account=None, service=None, expected_length=None):
+    """Return one secret for an app from the examiner-supplied keychain, or None.
+
+    Args:
+        access_group: substring of the owning app's access group, for example
+            'org.whispersystems.signal'.
+        account: substring of the account name, for example
+            'GRDBDatabaseCipherKeySpec'.
+        service: substring of the service name, when needed to disambiguate.
+        expected_length: if given, only a secret of exactly this many bytes is
+            returned, which guards against picking up an unrelated entry.
+
+    Returns:
+        The secret as bytes, or None when no keychain was supplied or nothing matched.
+    """
+    keychain_path = Context.get_keychain_path()
+    if not keychain_path:
+        return None
+
+    matches = find_keychain_secrets(keychain_path, access_group, account, service)
+    if expected_length is not None:
+        matches = [secret for secret in matches if len(secret) == expected_length]
+    if not matches:
+        return None
+    if len(matches) > 1:
+        logfunc(f'Keychain: {len(matches)} entries matched {access_group}/{account}, '
+                'using the first')
+    return matches[0]