Developers

iPGMail: x-ipgmail://x-callback-url

Actions:

/encrypt

1. Action: encrypt
2. Description: Encrypt a block of plaintext and either save it to a file or return it to the requesting app in the x-success callback
3. Parameters:
   • 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 that you wish to use to encrypt the data. If the KeyID is not currently in the iPGMail keychain, the operation will fail.
   • signkey [string, optional]: The 8 character KeyID of the private key that you wish to use to sign the data. If the KeyID is not currently in the iPGMail keychain, the operation will fail. The caller may be prompted for the private key password if password caching is not enabled.
   • result [string, optional]: Direct the resulting PGP armor text to a file or the clipboard. If this option is not present, the result is still sent back to the calluser in the x-success callback.
   • symmetric=true [boolean, optional] – Use symmetric (i.e. password-based) crypto to encrypt the data. Instead of choosing a public key, indicate a password and the app will encrypt it using PGP symmetric encryption s the file can be decrypted by anyone with the password. Use with the “passwd” option.
   • passwd=PASSWORD [string, optional] – password to use when the symmetric option is set to true
   • result=clipboard – This will cause iPGMail to copy the encrypted ASCII Armored result text to the system clipboard so it can be copied into another app if necessary.
   • result=somefilename – save results to a file in the app’s filespace

/sign

1. Action: sign
2. Description: sign a block of plaintext and either save it to a file or return it to the requesting app in the x-success callback
3. Parameters:
   • datasource [string, optional]: Currently the only datasource supported is “clipboard”.
   • text [string, optional]: The text to be encrypted. Must be properly URL escaped.
   • signkey [string, optional]: The 8 character KeyID of the private key that you wish to use to sign the data. If the KeyID is not currently in the iPGMail keychain, the operation will fail. The caller may be prompted for the private key password if password caching is not enabled.
   • result [string, optional]: Direct the resulting PGP armor text to a file or the clipboard. If this option is not present, the result is still sent back to the calluser in the x-success callback.
     • result=clipboard – This will cause iPGMail to copy the encrypted ASCII Armored result text to the system clipboard so it can be copied into another app if necessary.
     • result=somefilename – save results to a file in the app’s filespace

/compose

1. Action: compose
2. Description:Put text directly into the iPGMail compose view so it can be edited and encrypted as an email in the app.
3. Parameters:
   • text [string]: The text to be edited in the compose view. Must be properly URL escaped.

/decrypt

1. Action: decrypt
2. Description:Decrypt a PGP message and return the status to the caller
3. Parameters:
   • pgpmsg [string]: The pgp message to be decrypted. If the special keyword “clipboard” is used, ipgmail will copy the contents of the system clipboard and attempt to decrypt it. The message must be a complete ASCII-ARMOR PGP message, starting with “—– BEGIN PGP MESSAGE —–” and ending with “—– END PGP MESSAGE —–“
   • result=clipboard [optional]: iPGMail will copy the results of the decryption back to the system clipboard upon completion.

Examples:

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

1. This copies plaintext from the system clipboard, encrypts it with keyID 47E3234C, and puts the resulting encrypted PGP message back into the system clipboard. NOTE: 47E3234C is just an example, in practice, you would use your own KeyID

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

1. This copies plaintext from the system clipboard, encrypts it with keyID 47E3234C, and puts the resulting encrypted PGP message into a file named ‘savefile.pgp’ in the iPGMail file space. NOTE: 47E3234C is just an example, in practice, you would use your own KeyID

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

1. This will cause iPGMail to prompt the user to select a public key, then encrypt the text (“This is a test…”) and return it to the caller with the x-success callback.

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

1. This will open iPGMail to the “compose” tab and put the text (“This is a test…”) in the compose window. The user can then edit the text further and either send it in an encrypted email or to the clipboard.

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

1. Request that iPGMail take the contents of the system clipboard and attempt to decrypt them. A JSON dictionary containing the result status and resulting decrypted message is copied back to the system clipboard

x-ipgmail://x-callback-url/decrypt?&pgpmsg=-----BEGIN%20PGP%20MESSAGE-----%0AVersion%3A%20iPGMail%20%282.0.4%29%0A%0AhQEMA%2FLu3LbUsEKQAQgAm34urKiLNAAxyL%2BO9psvgEw7Cu96GvHxQoE81qn1Yn5z1TdGEAQ31Bgs%0Aj8W%2FZqWV%2BRaB%2BmIbaaSnYR6x6%2FqO7bIaOk4ImNZcwWP%2BzqnSCYCgGzsamrwV5Z9hMhUJvKDwh%2BJ%2B%0A4IA96QVDfiXK8N%2BLWQOgM0PGmkO3AE%2BDE%2FmzA6qDGsEKgMsK9M0wFjTNfimKwadAkDISnlGiyDtW%0AqQIHWFoq%2FI8MNghW0vOVTF1%2BkqL8rncRr%2BxuxkMRH8toXBwPho6CQka2vBqzOrtansT%2By694P1nY%0AjErSy75HVJvVRCuax5qX92xcuOtSxxW2CMwaDnvB%2F4ZXZq3aNUHmtmWhvNJVATpuxOYXOCSnPChh%0A9UBMu%2Bi6Bx3iku%2Be3IdGy2oEeaeuY%2B0Txjsuf%2B8ZpimnESpVDi%2FtUDTSuKjKJ2ml9JwpFrWrV8qg%0ABUIO87BYOhYmQ8zeVgncJg%3D%3D%0A%3DdlrQ%0A%0A-----END%20PGP%20MESSAGE-----%0A&result=clipboard&

1. Request that iPGMail decrypt the PGP message as given. A JSON dictionary containing the result status and resulting decrypted message is copied back to the system clipboard.

Encrypt Results:

If the encryption request succeeds, the caller will be sent a json dictionary containing the resulting PGP message in the ‘ipgmail-response’ key. The sub-message in the ipgmail-response will have a key of ‘pgp-encrypted-message’. For example:

{"pgp-encrypted-msg":"-----BEGIN PGP MESSAGE-----\n
Version: iPGMail (1.48)\n\n

hQEMA\/Lu3LbUsEKQAQf\/byhvj+tZanyy0k9WfAegkcEGQR7HpX+MKhsi+pe\/BXu6LdCNiiH+So+B\n
3\/4XDpzqV\/Pouzu5DROGH+D7SAJixLIl6i50cpFcFSQO1Q2DxJSrZKhh1FIq7zoTbf7DwKlYqWeD\n
YP1CsGaKbwJWK\/nuj+mX\/on9PWWyiwzc+uoYYI6s3BpHUUGx\/LEgYOG4qemQXIocCF0GWjjCpH8s\n
pQ8TldR+bzN3sYaDB3udopjjCJ3vCKZHubGkhdMg4uMC3H4WAraf0+RqaX+Fl02AS53PpM\/PUo4y\n
RtoGWeCMRXJguIBur2AR+ZAlq0hadivL7Pxr1G1fl8hcvr3SqHMJDG\/vUtJGAcWwB0WrzhmeSv1k\n
5NFttO\/87xdUOiBXJ6txhJBQUBOWN8rHf55xo7QiWgj4Mv9h2Juz0fvZt5Ne3Xnf0jQkyQdI6xZ5\n
FQ==\n
=FLsO\n\n
—–END PGP MESSAGE—–\n”}

Additionally, if the request contained the “results=clipboard” parameter, the ASCII Armor PGP Encrypted text will be copied to the system clipboard so that apps can then paste the contents of the clipboard as needed.

If the operation fails, the caller will get an error message indicating the problem.

Decrypt Results:

If the decryption request succeeds, the caller will be sent a json dictionary containing the resulting PGP message in the ‘ipgmail-response’ key. The sub-message in the ipgmail-response will be a dictionary containing the status of the decryption and the message (if it succeeded). For example:

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


Where:
decryptedBlocks = A list of items that were found in the decrypted message.
data:

1. decrypted data. This is encoded according to the “encoding” parameter. This is necessary because some PGP messages decrypt as a binary result such as an image or song or other non-ASCII result.

encoding:

1. encoding applied to the decrypted “data” block. ‘base64’ is the only currently implemented encoding. The caller must base64-decode the “data” field to get the raw message, even if it is ASCII.

filename:

1. Name of the file that was decrypted. This can probably be ignored, but some PGP email messages have a filename embedded in the encrypted MIME header, if found, then this is indicated here.

decryptStatus:

1. 0 = Original message was not encrypted
2. 1 = Decryption failed
3. 2 = Decryption succeeded

signatureStatus:

1. 0 = Message was not signed, no signature found
2. 1 = Signature verification failed
3. 2 = Signature verification succeeded
4. 3 = Signature key not found (public key for the signer was not in the ipgmail keyring)

Additionally, if the request contained the “results=clipboard” parameter, the JSON dictionary will also be copied to the system clipboard so that apps process it from the clipboard.
If the operation fails, the caller will get an error message indicating the problem.