15.3 OpenPGP

Bigloo implements parts of OpenPGP (RFC 2440, RFC 4880). All OpenPGP functions are accessible via the openpgp library.

Here is an example of a module that uses this library:

;; Encrypt a string using openpgp default encryption.
(module pgp-encrypt
   (library openpgp)
   (main main))

(define (main argv)
   (when (and (pair? (cdr argv)) (pair? (cddr argv)))
      (let ((encrypt? (string=? "-e" (cadr argv)))
            (passwd (caddr argv))
            (input (read-string)))
         (if encrypt?
             (display (pgp-write-string (pgp-encrypt input
                                                     '()  ;; no public keys
                                                     (list passwd))))
             (let ((composition (pgp-read-string input)))
               (display (pgp-decrypt composition
                                     :passkey-provider (lambda () passwd))))))))

Bigloo OpenPGP procedure: pgp-read-string str

Bigloo OpenPGP procedure: pgp-read-port iport

Bigloo OpenPGP procedure: pgp-read-file file-name

These functions read and decode PGP data. OpenPGP allows several keys to be stored in the same message. Therefore pgp-read will return keys always in a list (even if the message only contains one key).

The return value is either a list of PGP-compositions (PGP-Keys), or a single PGP-composition.

Bigloo OpenPGP procedure: pgp-write-string composition [:format 'armored]

Bigloo OpenPGP procedure: pgp-write-port oport composition [:format 'armored]

Bigloo OpenPGP procedure: pgp-write-file file-name composition [:format 'armored]

The counter-part of pgp-read. These functions encode PGP-compositions. By default the result is armored (i.e. encoded with ASCII characters). If the optional :format parameter is different than the symbol armored, then the composition is encoded in binary.

Note that there is no means to encode a list of PGP-keys.

Bigloo OpenPGP procedure: pgp-encrypt msg-string keys passwords [:hash-algo 'sha-1] [:symmetric-algo 'cast5]

Encrypts the given string. The returned composition can be decrypted by the owners of the keys, or with one of the passwords.

In the following example Alice and Bob may use their private key to decrypt the secret message. Users knowing the one of the passwords (“foo” and “bar”) will also be able to decrypt the message.

(pgp-write-file "encrypted.pgp"
   (pgp-encrypt "my secret message"
                (list alice-key bob-key)
                '("foo" "bar")))

The given keys should be subkeys of a PGP-key, but if a PGP-key is given Bigloo will do its best to pick the correct subkey for encryption.

• If only one subkey exists (the main-key) then this subkey is used.
• If two subkeys exist, and the non-main key is suitable for encryption, then the non-main key is used.
• If only one of many subkeys (including the main-key) is suitable for encryption, then this subkey is used.
• Else Bigloo raises an error.

Bigloo OpenPGP procedure: pgp-password-encrypt msg-string password [:hash-algo 'sha-1] [:symmetric-algo 'cast5] [:mdc #t]

Deprecated. Encrypts msg-string with the given password. The returned PGP-composition does not contain any information which hash-algorithm and symmetric encryption algorithm has been used. RFC 4880 specifies that IDEA and MD5 should be used. However GnuPG uses SHA-1 and CAST5. Therefore Bigloo defaults to the latter algorithms.

Even though the usage of this PGP message is deprecated it yields the smallest encrypted data. It may be of interest when compatibility with other tools is not a requirement (but why use OpenPGP then).

The optional mdc flag triggers the usage of a modification detection code. It is more secure against tampering but requires more space and might not be recognized by old openpgp implementations.

Bigloo OpenPGP procedure: pgp-decrypt encrypted [:passkey-provider (lambda () #f)] [:password-provider (lambda (key) #f)] [:key-manager (lambda (key-id) '())] [:hash-algo 'sha-1] [:symmetric-algo 'cast5]

Decrypts a PGP-composition that has been generated by pgp-encrypt or by pgp-password-encrypt. The function returns the decrypted message (a string) or #f if decryption was not possible.

If the message can be decrypted with a private key, then Bigloo will call the key-manager and request a list of PGP-subkeys that match the given key-id.

If a subkey (returned by the key-manager) is not yet decrypted, Bigloo will invoke the password-provider with the subkey, and request a password to decrypt the private part of the subkey.

If the message can be decrypted with a password Bigloo will then request a passkey by invoking the passkey-provider.

The optional arguments hash-algo and symmetric-algo are only used for messages that have been encrypted with pgp-password-encrypt.

Bigloo OpenPGP procedure: pgp-sign msg-string key password-provider [:detached-signature? #t] [:one-pass? #f] [:hash-algo 'sha-1]

Signs msg-string with the given key. Ideally the key should be a subkey, but if a complete PGP-Key is given, Bigloo will use the main-key instead. If the main-key is not suitable for signing, then an error is raised.

If the private part of the key has not yet been decrypted then Bigloo will call the password-provider (a procedure) with the subkey to get a password (a string).

The function returns a PGP-composition.

If the optional detached-signature? parameter is set to #f then the msg-string is not included in the returned composition.

The one-pass? and hash-algo parameters are usually left at its default values.

Example:

(let ((my-key (car (pgp-read-file "my-key.pgp"))))
  (pgp-write-file "msg.sig"
     (pgp-sign "my signed message"
               my-key
               (lambda (key) "my-password")
               :detached-signature? #f)))

Bigloo OpenPGP procedure: pgp-verify signature key-manager [:msg #f]

Verifies a signature.

The key-manager is a function that takes a substring identifier and returns a list of keys matching this id. Since a signature composition may contain several signatures this function may be invoked several times.

The result is a list of subkeys that signed the message. If the key-manager doesn’t have any of the signature-keys then the result is the empty list.

A message (string) needs only be given if the signature is detached. Otherwise the original message is encoded in the signature-composition.

Example:

(let ((sig (pgp-read-file "msg.sig")))
  (let ((signers (pgp-verify sig my-key-manager)))
   (for-each (lambda (subkey)
               (print (subkey->string subkey) " signed the message"))
             signers)))

Bigloo OpenPGP procedure: pgp-signature-message signature

Returns the signature’s message, or #f if the signature is a detached signature.

Bigloo OpenPGP procedure: pgp-key? key

Bigloo OpenPGP procedure: pgp-subkey? key

Predicates for PGP-Key and PGP-Subkey.

Bigloo OpenPGP procedure: pgp-subkeys key

Returns a list of PGP-Subkeys of the PGP-Key. The first key in the list is the main-key. The main-key is used as default for signatures.

Bigloo OpenPGP procedure: pgp-key->string key

Bigloo OpenPGP procedure: pgp-subkey->string key

Returns a string representation of the key (resp. subkey).

Example outputs:

(pgp-key->string key)
⇒ John Doe john.doe@gmail.com
⇒ bd4df3b2ddef790c RSA (Encrypt or Sign)
⇒ 424610a65032c42e RSA (Encrypt or Sign)

(pgp-subkey->string (car (pgp-subkeys key)))
⇒ John Doe john.doe@gmail.com
⇒ bd4df3b2ddef790c RSA (Encrypt or Sign)

Bigloo OpenPGP procedure: pgp-key-id subkey

Bigloo OpenPGP procedure: pgp-key-fingerprint subkey

Returns the id (resp. fingerprint) of a subkey.

A subkey-id is a 8-character binary string.

A fingerprint is a 20-character binary string.

Bigloo OpenPGP procedure: pgp-make-key-db

Bigloo OpenPGP procedure: pgp-add-key-to-db db key

Bigloo OpenPGP procedure: pgp-add-keys-to-db db keys

Bigloo OpenPGP procedure: pgp-resolve-key db id

Bigloo OpenPGP procedure: pgp-db-print-keys db

A simple key-manager implementation based on lists.

This document was generated on March 31, 2014 using texi2html 5.0.