Miln Keysafe

Keysafe reads and decrypts Apple Keychain files. Use Keysafe to securely access your passwords and credentials without a Mac.

Keysafe is a command line tool. This means it is used from the terminal and may not be suitable for non-technical users.

Using keysafe

To get started with Miln Keysafe, download and expand the executable file onto your computer.

Keysafe is a single executable file. It does not need to be installed, can be run from any directory, and can be removed by deleting the file.

How to Look Up a Password

Calling keysafe with a Keychain path will read the file and list the encrypted password records. After showing the available records, you can choose to exit immediately or enter the number of the record to decrypt:

./keysafe -path sample.keychain -licence ~/Downloads
-  1: tax office
        Name: tax office
        Account: accounts@organisation.org
-  2: Accounting Access
        Name: Accounting Access
        Account:

Found 2 encrypted records.
Record number 1 or 2 to decrypt (leave blank to exit): 1
Password for Keychain file "sample.keychain":
-  1: tax office
        Creation Date: 03 Apr 22 13:05 +0000
        Modification Date: 03 Apr 22 13:05 +0000
        Name: tax office
        Account: accounts@organisation.org
        Service: tax office
        Secret: Secret Password

A Miln App Licence is required to fully decrypt a record. Without a licence, only the first few characters of the decrypted value will be displayed. For short values, no characters will be shown. Below is the same command but without a licence:

./keysafe -path sample.keychain
-  1: tax office
        Name: tax office
        Account: accounts@organisation.org
-  2: Accounting Access
        Name: Accounting Access
        Account:

Found 2 encrypted records.
Record number 1 or 2 to decrypt (leave blank to exit): 1
** A licence is required to fully decrypt. Without a licence, secrets will be redacted.
   Purchase your licence from https://miln.eu/keysafe
Password for Keychain file "sample.keychain":
-  1: tax office
        Creation Date: 03 Apr 22 13:05 +0000
        Modification Date: 03 Apr 22 13:05 +0000
        Name: tax office
        Account: accounts@organisation.org
        Service: tax office
        Secret (redacted/unlicensed): Secr*********

Filtering/Searching

Adding words or phrases to the command will filter the results. If a password record’s name or account contains any of the provided words, it will be listed:

./keysafe -path sample.keychain work
./keysafe -path sample.keychain work tax

In the examples above, the first command will show records containing work. The second command will show records containing either work or tax. The filter is case insensitive; use the filter WORK will match Work and work.

Phrases can also be used to filter the records:

./keysafe -path sample.keychain "work tax"

In this example above, the command will show records containing the complete phrase work tax.

Encoding

If a decrypted value contains unprintable values, the output will be base64 encoded.

How to Export a Keychain

Calling keysafe with a Keychain path and an export path, will create a compressed archive containing the contents of the Keychain.

./keysafe -path sample.keychain -export sample.tar.gz

Archive Contents

The archive is a gzip compressed tar file (.tar.gz or .tgz). This widely supported combination of formats can be decompressed using built-in tools on most operating systems:

• On macOS and Windows, double click on the file;
• On the command line use tar -xjf sample.tar.gz.

The archive contains a set of files and folders, including:

keychain.xml

A file containing the Keychain contents in XML (xml) format. This is the best format to post process. The XML structure is self documenting with descriptive tag names and deliberately verbose.

keychain.json

A file containing the Keychain contents in a JavaScript Object Notation (json) format.

bitwarden.json

A file containing the Keychain passwords and secure notes in a JavaScript Object Notation (json) format suitable for importing into Bitwarden or VaultWarden.

cert-x509/

A directory of X.509 certificate files in their original encoding. Typically Keychain stores certificates in ASN.1/der format.

private-key/

A directory of private keys in their original encoding. Each key will be present in two files; a .bin file and a .key.bin file. The latter contains only the encoded key from the first file.

The key files may be encrypted. Please contact me if these files are critical to you - and you are able to fund further development.

public-key/

A directory of public keys in their original encoding. See the private-key description for their structure.

secure-note/

A directory of secure notes in multiple formats. Each secure note appears at least once, in the original encoding. Where multiple formats exist in the Keychain, the note will typically be:

• a Property List (plist) file,
• a plain text (txt) file,
• and an Rich Text Format Directory (rtfd) bundle.

Other directories may also be included. The directories above are the most common.

Password Required

Keysafe can read encrypted passwords and credentials from a Keychain file. To view encrypted information, the Keychain’s password is required. Keysafe does not cirmuvent the security of the Keychain file.

Recovering Passwords

Keysafe can help recover lost and forgotten passwords using the -recover flag. For step-by-step instructions, see the practical guide for recovering lost and forgotten Keychain passwords.

Use the -recover flag to display the master password hash of a keychain file:

keysafe -recover -path sample.keychain

The master password hash is not the password but the means by which the password is checked. Other tools can use this information to determine if a password is likely to decrypt the keychain or not.

System.keychain

Decrypting the System.keychain requires a SystemKey file. Use the -system-key flag to pass a path to the SystemKey file.

keysafe -system-key /var/db/SystemKey -path /Library/Keychains/System.keychain

keysafe Options

Below are the available options and flags supported by keysafe:

% ./keysafe -h
Usage of ./keysafe:
  -config string
        File path to configuration.
  -export string
        path to write exported contents as .tar.gz, or hypen (-) to write to standard output (stdout)
  -h    Show this help message and exit. (shorthand)
  -help
        Show this help message and exit.
  -l string
        Directory path to licence certificate files (PEM encoded) (shorthand) (default "~/.miln/")
  -legal
        Show legal notices and exit.
  -licence string
        Directory path to licence certificate files (PEM encoded) (default "~/.miln/")
  -path string
        path to Keychain file or hypen (-) to read from standard input (stdin) (default "~/Library/Keychains/login.keychain-db")
  -recover
        extract the Keychain file's master hash for password recovery
  -show-licence
        Show licence details and exit.
  -system-key string
        path to a SystemKey file
  -v    Show version details and exit. (shorthand)
  -version
        Show version details and exit.

The Keychain password may be provided by the environment variable KEYSAFE_PASSWORD. If this variable is empty, an interactive prompt will be used.

What is Apple’s Keychain?

Keychain is Apple’s technology for storing confidential information on macOS. The files associated with the Keychain are encoded in the Keychain file format. These files typically contain web site passwords, service credentials, and secure notes. A Keychain file can also include certificates and private keys used to encrypt and secure connections.

On macOS, the Keychain is accessible through the Keychain Access application and the security command line tool. User Keychain files are stored in their ~/Library/Keychains folder. Computer and System scoped Keychain files are found in the /Library/Keychains and /System/Library/Keychains folders.

Keysafe is a tool that understands the Keychain file format. It was written to securely access passwords when using non-Apple hardware.

Going Further

If you need forensic analysis or specialist treatment of Keychain files, please get in touch.