Skip to content

Home

Jump to bottom
Yishi Lin edited this page Mar 4, 2020 · 42 revisions

Welcome to the Pass for iOS wiki!

Table of Contents

Quick-start guide for Pass for iOS

Before using Pass for iOS, please make sure that you have your "password store" set up properly. To set up your "password store", please refer to the official Password Store homepage, or our Quick-start guide for pass.

Setting up password repository

HTTPS URL example

  • Git repository URL: https://gitlab.com/passforios-demo/demo.git
  • Username: passforios-demo
  • Supported authentication Method: Password
  • Remarks: https is a must

SSH URL example

  • Git repository URL: ssh://git@gitlab.com/passforios-demo/demo.git (original is git@gitlab.com:passforios-demo/demo.git)
    • remember to include username in the url
    • remember to change ":" to "/"
  • Username: git
  • Supported authentication Method: SSH Keys, Password (only for self-built Git server, but note that GitHub, GitLab, etc. don't support password authentication.)
  • Remarks: Username should be specified both in the "Git repository URL" field and in the "username" field

Importing SSH key

Execute the following codes or equivalence to get the ASCII-armored key.

cat ~/.ssh/id_rsa

Then, use one of the provided methods to import the key. See Setting up PGP key for more information.

Setting up PGP key

There are various ways to set up PGP keys.

Downloading from URL

Make sure that your keys can be accessed by https connection (e.g., test via wget). Then, fill in URLs for your public and private keys, tap "Save" and fill in your passphrase.

  • [More secure] A wonderful script that allows to transfer public/private keys from a server to Pass for iOS over https: goerz/gpg-serve-key
  • One quick example for uploading your keys to a temporary server manually. Remember to remove the keys from the server in time.
$ gpg --export -a D4763C61 > key.pub
$ gpg --export-secret-keys -a D4763C61 > key
$ scp key.pub key yourtemporaryserver
$ wget https://...yourtemporaryserver.../key    # make sure the key can be accessed by https connection
$ wget https://...yourtemporaryserver.../key.pub

Importing ASCII-armored keys

Execute the following codes or equivalence to get the ASCII-armored key. Copy and paste ASCII-armored keys to the app. Or, convert your ASCII-armored keys to QR codes and scan them using Pass for iOS (a handy script: yishilin14/asc-key-to-qr-code-gif).

$ gpg --export -a D4763C61
$ gpg --export-secret-keys -a D4763C61

Load from Files

Put your ASCII-armored keys somewhere (e.g., iCloud Drive, iPhone, and other cloud storage provides) and load them from Files. Just make sure you can see your keys in the Files app.

Using the iTunes File Sharing function

Use the iTunes File Sharing function to upload your keys with specific names (see "Tips" prompted in the App) to the document root directory. Then, click "Settings->PGP Key->iTunes File Sharing" to import your keys. Your uploaded files will be imported and removed from the document root directory.

Synchronizing your password store

Go to the "Passwords" tab in Pass for iOS, pull down to sync your passwords with the remote git (git pull and git push).

Data organization

"The password store does not impose any particular schema or type of organization of your data, as it is simply a flat text file, which can contain arbitrary data." From https://www.passwordstore.org/

YAML-like multiline field support

Pass supports the YAML-like multiline fields syntax | and > (respecting and not respecting new lines). For example:

password_line
notes_with_new_lines: |
  line one
  line two
notes_without_new_lines: >
  field1
  field2

Two-factor authentication support

Pass for iOS provides support for Time-based One-time password (TOTP) and HMAC-based one-time password (HOTP). It is compatible with password entries (files) generated by pass-otp, a pass extension for managing one-time-password (OTP) tokens.

Pass for iOS generates TOTP/HOTP for a password entry if there is enough information to construct a valid OTP token.

  • First, a valid OTPAuth URL (if existed) will be used to construct the OTP token.
  • If the first step failed, OTP-related fields (if any) will be used to construct the OTP token.

OTPAuth Uri

For what is a "valid OTPAuth Uri", please refer to Key Uri Format. Here is just a quick example:

otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example

Inserting new TOTP/HOTP entries

To insert a new TOTP/HOTP entry via Pass for iOS, you could scan the QR code of OTPAuth URL or manually type the OTPAuth URL.

Use the Pass extension to fill in Safari and apps

Basically, our app works in the same way as the 1Password extension. And we are also trying to be compatible with Browserpass. To make sure that your passwords could be filled automatically, the first line of your file should be your password, and your file must have a line starting with username: or Username: or login:, followed by your username. For example

$ pass website.com
your-super-secret-password
username: johndoe

Setup the Pass extension

  • Open Safari/Chrome and tap the Share icon.
  • Swipe left on the bottom row of icons and tap More.
  • Turn on Pass. Move Pass to the top of the list, if you like.

Use the Pass extension

Safari/Chrome Visit the web page where you want to use the Pass extension to fill in your username and password. Tap the Share icon, select Pass, and then select the correct entry.

Supported apps In the login page of a supported app, your will see a 1Password icon or a LastPass icon (what icon you will see depends on developers of the app). Click the icon and select Pass.

F&Q about Pass Settings

Note that not all key algorithms are supported by the upstream packages we use. Here goes a list of [Supported/Unsupported Key Algorithms](Supported/Unsupported Key Algorithms).

Table of contents generated with markdown-toc.

Clone this wiki locally