Developers

Drive iPGMail from your own app.

iPGMail supports integration with other apps via the x-callback-url protocol. It registers the following URL scheme:

x-ipgmail://x-callback-url

Actions

/encrypt

Encrypt a block of plaintext and either save it to a file or return it to the requesting app in the x-success callback.

datasource [string, optional] — currently the only datasource supported is "clipboard".
text [string, optional] — the text to be encrypted. Must be properly URL escaped.
keyid [string, optional] — the 8-character KeyID of the public key to encrypt with. If the KeyID isn't in the iPGMail keychain, the operation fails.
signkey [string, optional] — the 8-character KeyID of the private key to sign with. The caller may be prompted for the private key password if password caching is off.
result [string, optional] — result=clipboard copies the ASCII-armored result to the system clipboard; result=somefilename saves it into the app's file space. Without it, the result still returns in the x-success callback.
symmetric=true [boolean, optional] — use password-based crypto instead of a public key, so anyone with the password can decrypt. Use with passwd.
passwd [string, optional] — the password used when symmetric is true.

/sign

Sign a block of plaintext and either save it to a file or return it to the requesting app in the x-success callback.

datasource [string, optional] — "clipboard".
text [string, optional] — the text to be signed. Must be properly URL escaped.
signkey [string, optional] — the 8-character KeyID of the signing private key.
result [string, optional] — clipboard or a filename, as with /encrypt.

/compose

Put text directly into the iPGMail compose view so it can be edited and encrypted as an email in the app.

text [string] — the text to be edited in the compose view. Must be properly URL escaped.

/decrypt

Decrypt a PGP message and return the status to the caller.

pgpmsg [string] — the PGP message to decrypt. The keyword "clipboard" decrypts the system clipboard instead. The message must be a complete ASCII-armor block, from BEGIN PGP MESSAGE to END PGP MESSAGE.
result=clipboard [optional] — copy the result of the decryption back to the system clipboard.

Examples

x-ipgmail://x-callback-url/encrypt?datasource=clipboard&keyid=47E3234C&result=clipboard

Copies plaintext from the system clipboard, encrypts it with keyID 47E3234C, and puts the resulting encrypted PGP message back into the clipboard. 47E3234C is only an example — use your own KeyID.

x-ipgmail://x-callback-url/encrypt?datasource=clipboard&keyid=47E3234C&result=savefile.pgp

The same, but the encrypted message is written to a file named savefile.pgp in the iPGMail file space.

x-ipgmail://x-callback-url/encrypt?text=This%20is%20a%20test...%0A

Prompts the user to select a public key, encrypts the text, and returns it to the caller with the x-success callback.

x-ipgmail://x-callback-url/compose?text=This%20is%20a%20test...%0A

Opens iPGMail on the Compose tab with the text in the compose window, ready to edit and send encrypted.

x-ipgmail://x-callback-url/decrypt?pgpmsg=clipboard&result=clipboard

Asks iPGMail to decrypt the contents of the system clipboard. A JSON dictionary with the result status and decrypted message is copied back to the clipboard.

Encrypt results

On success the caller receives a JSON dictionary containing the resulting PGP message under the ipgmail-response key; the sub-message key is pgp-encrypted-msg.

{"pgp-encrypted-msg":
  "-----BEGIN PGP MESSAGE-----\n
   Version: iPGMail (1.48)\n\n
   hQEMA/Lu3LbUsEKQAQf/byhvj+tZanyy0k9WfAegkcEG…\n
   =FLsO\n
   -----END PGP MESSAGE-----\n"}

With result=clipboard, the armored text is also copied to the system clipboard. If the operation fails, the caller gets an error message describing the problem.

Decrypt results

{"ipgmail-response": {
  "decryptedBlocks": [{
    "data": "dGVzdGluZwo=",
    "encoding": "base64",
    "filename": "pgp12060952-0.txt"
  }],
  "decryptStatus": 2,
  "signatureStatus": 0
}}

data — the decrypted data, encoded per the encoding field. Some PGP messages decrypt to binary.
encoding — base64 is the only implemented encoding; decode it even for ASCII results.
filename — the filename embedded in the encrypted MIME header, where one is found.
decryptStatus — 0 not encrypted, 1 failed, 2 succeeded.
signatureStatus — 0 not signed, 1 verification failed, 2 verified, 3 signer's public key not in the keyring.