Home

---

Welcome to the Pass for iOS wiki!

---

Table of Contents

• Quick-start guide for Pass for iOS
  • Setting up password repository
    • HTTPS URL example
    • SSH URL example
  • Setting up PGP key
    • Downloading from URL
    • Importing ASCII-armor encrypted key
    • Using keys uploaded via iTunes file sharing
  • Synchronizing your password store
• Two-factor authentication support
  • OTPAuth Uri [recommended]
  • Time-based One-time password (TOTP) fields [legacy]
  • HMAC-based one-time password (HOTP) fields [legacy]
  • Inserting new TOTP/HOTP entries

---

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, SSH Keys

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.)

The valid SSH URL should be ssh://server:port/url/to/repository.git (ssh://github.com:22/mssun/pass.git) and the username should be put in the next field under URL (e.g., git).

Setting up PGP key

There are various ways to set up PGP keys.

Downloading from URL

First, upload your keys to a temporary server. Make sure the uploaded key 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. Finally, remember to remove the key from the server. Here goes one quick example:

$ 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-armor encrypted key

Adding PGP key in ASCII armored format is supported. Just copy and paste. Here are some example codes to generate the ASCII-armored key.

$ gpg --export -a D4763C61               # copy to the app
$ gpg --export-secret-keys -a D4763C61   # copy to the app

Using keys uploaded via iTunes file sharing

You may also use iTunes file sharing function to upload your keys with names gpg_key.pub and gpg_key to the document root directory. The app will automatically use the keys for encryption and decryption.

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).

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 [recommended]

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

Time-based One-time password (TOTP) fields [legacy]

To generate one-time passwords for TOTP tokens, the password entry should contain fields otp_secret and otp_type. And the value for otp_type should be totp (case insensitive). An example (decrypted) TOTP password entry is as follows.

otp_secret: AAAAAAAAAAAAAAAAAAAAA
otp_type: totp
otp_algorithm: sha1
otp_period: 30
otp_digits: 6

These lines could be in any order. It is ok if there are other none-related lines. Fields otp_algorithm (case insensitive), otp_period, and otp_digits are optional. Their default values are sha1, 30 (seconds), and 6 (digits), respectively.

HMAC-based one-time password (HOTP) fields [legacy]

To generate one-time passwords for HOTP tokens, the password entry should contain fields otp_secret, otp_counter, and otp_type. And the value for otp_type should be htop (case insensitive). An example (decrypted) HOTP password entry is as follows.

otp_secret: AAAAAAAAAAAAAAAAAAAAA
otp_type: hotp
otp_counter: 1
otp_digits: 6

These lines could be in any order. It is ok if there are other none-related lines. Fields otp_algorithm (case insensitive) and otp_digits are optional. Their default values are sha1 and 6 (digits), respectively. (For a new HTOP password, if you do not know otp_counter, it is probably 1.)

Inserting new TOTP/HOTP entries

Currently, to insert a new TOTP/HOTP entry via Pass for iOS, user have to manually type a valid OTPAuth URL. A better UI is on its way (e.g., inserting entries by scanning QR codes), stay tuned. :-)