The Keybase API¶
Keybase Common Methods¶
The following common, convenience methods exist to make it easier to work with GnuPG and the Keybase API in your code.
- keybase.gpg(binary=None)[source]¶
Returns the full path to the gpg instance on this machine. It prefers gpg2 but will search for gpg if it cannot find gpg2.
>>> len(gpg()) > 0 True >>> len(gpg('gpg')) > 0 True
I implemented this because the gnupg.GPG class was having a hard time dealing with the fact that my Homebrew-installed GPG instance was a symlink in the /usr/local/bin directory instead of a real path to a real file.
If you want to use a binary with a specific name, supply the binary=bName option when you call gpg() and it will use your custom binary name instead.
On windows you shouldn’t need to supply an extension to the command like .exe or .cmd – it will figure it out for you.
Returns None if it cannot find a gpg2 or gpg instance in your PATH:
>>> gpg('notagpgbinary')
The Keybase Class – Accessing Public User Data¶
The Keybase class allows you to find users in the Keybase directory and access their stored public keys. Public keys let you encrypt messages and files for a user; only the person holding the private key from the pair can decrypt a file encrypted with the public key. Public keys also let you verify the signature on data; only the user with the private key can create a signature that can be validated with the specific public key.
- class keybase.Keybase(username)[source]¶
A read-only view of a keybase.io user and their publically available keys. This class allows you to do interesting things with someone’s public key data like encrypt a message for them or verify that a message they signed to you was actually signed by them.
The public information is automatically retrieved when you build a new instance of the class.
>>> kbase = Keybase('irc') >>> kbase.username 'irc'
If the user cannot be found a keybase.KeybaseUserNotFound exception is raised:
>>> kbase = Keybase('abcdefghijklmno123notauserhahaha') Traceback (most recent call last): ... KeybaseUserNotFound: User abcdefghijklmno123notauserhahaha not found
Note
It does not allow you to manipulate the key data in the keybase.io data store in any way.
- encrypt(data, **kwargs)[source]¶
Equivalent to:
kbase = Keybase('irc') pkey = kbase.get_public_key() verified = pkey.encrypt(data, **kwargs) assert verified
It’s a convenience method on the Keybase object to do data verification with the primary key.
For more information see keybase.KeybasePublicKey.encrypt.
- get_public_key(keyname='primary')[source]¶
Returns a key named keyname as a keybase.KeybasePublicKey object if it exists in the current Keybase instance. Defaults to a key named primary if you opt not to supply a keyname when you call the method.
>>> kbase = Keybase('irc') >>> primary_key = kbase.get_public_key() >>> primary_key.kid u'0101f56ecf27564e5bec1c50250d09efe963cad3138d4dc7f4646c77f6008c1e23cf0a'
Otherwise it returns None if a key by the name of keyname doesn’t exist for this user.
>>> kbase.get_public_key('thiskeydoesnotexist')
- location[source]¶
The geographical location of the person associated with this Keybase data.
>>> k = Keybase('irc') >>> k.location u'Bay Area, California'
- name[source]¶
The full name of the person associated with this Keybase data.
>>> k = Keybase('irc') >>> k.name u'Ian Chesal'
- public_keys[source]¶
A tuple of all the public keys available for this account. An empty tuple is returned if the instance isn’t bound to a user or the user has no keys.
>>> kbase = Keybase('irc') >>> kbase.public_keys (u'families', u'primary', u'sibkeys', u'subkeys')
- username[source]¶
The username of the person associated with this Keybase data.
>>> k = Keybase('irc') >>> k.username 'irc'
- verify(data, throw_error=False)[source]¶
Equivalent to:
kbase = Keybase('irc') pkey = kbase.get_public_key() verified = pkey.verify(some_message) assert verified
It’s a convenience method on the Keybase object to do data verification with the primary key.
For more information see keybase.KeybasePublicKey.verify.
- verify_file(fname, sigfname=None, throw_error=False)[source]¶
Equivalent to:
kbase = Keybase('irc') pkey = kbase.get_public_key() verified = pkey.verify_file(fname, signame) assert verified
It’s a convenience method on the Keybase object to do data verification with the primary key.
For more information see keybase.KeybasePublicKey.verify_file.
The KeybasePublicKey Class – Public Key Records from the Keybase.io Data Store¶
- class keybase.KeybasePublicKey(**kwargs)[source]¶
A class that represents the public key side of a public/private key pair.
It is tied very closely to the keybase.io data that’s stored for public keys in user profiles in the data store. As such, it’s meant to be initialized with a hash that contains the fields seen in a keybase.io public key record.
Under the hood it uses GnupGP’s gnupg.GPG class to do the heavy lifting. It creates a keystore that is unique to this instance of the class and loads the public key in to this keystore.
You won’t be able to decrypt with this class because it only contains a public key, not a private key. But you can encrypt and and sign:
>>> kbase = Keybase('irc') >>> pkey = kbase.get_public_key() >>> pkey.key_fingerprint u'7cc0ce678c37fc27da3ce494f56b7a6f0a32a0b9'
If a valid GPG instance cannot be created when you initialize a KeybasePublicKey a KeybasePublicKeyError will be raised.
- bundle[source]¶
The GPG key bundle. This is the ASCII representation of the public key data associated with the Keybase key.
- cipher_algos[source]¶
Returns a tuple of available cypher algorithms that you can use with this key to encrypt data. The available algorithms depend entirely on the GPG version installed on the machine though most, if not all GPG versions, support AES256.
>>> kbase = Keybase('irc') >>> pkey = kbase.get_public_key() >>> 'AES256' in pkey.cipher_algos True
- compress_algos[source]¶
Returns a tuple of available compression algorithms that you can use with this key to compress encrypted data. The available algorithms depend entirely on the GPG version installed on the machine though most, if not all GPG versions, support ZIP.
>>> kbase = Keybase('irc') >>> pkey = kbase.get_public_key() >>> 'ZIP' in pkey.compress_algos True
- digest_algos[source]¶
Returns a tuple of available digest algorithms that you can use with this key to hash data. The available algorithms depend entirely on the GPG version installed on the machine though most, if not all GPG versions, support SHA512.
>>> kbase = Keybase('irc') >>> pkey = kbase.get_public_key() >>> 'SHA512' in pkey.digest_algos True
- encrypt(data, armor=True, cipher_algo=None, digest_algo=None, compress_algo=None)[source]¶
Encrypt the message contained in the string data for the owner of this KeybasePublicKey instance.
If armor=True the output is ASCII armored; otherwise the output will be a gnupg._parsers.Crypt object.
If encryption fails a KeybasePublicKeyEncryptError is raised.
If it succeeds data object is returned. Assuming armor=True the returned data is just plain old ASCII text as a str().
Note
The remaining options are supplied for maximum flexibility with GPG but you can, for the most part, just ignore them and go with the defaults if you want the simpilest (but still secure) path to encrypting data with this API.
If cipher_algo is supplied it should be the name of a cipher algorithm to use. The default algorithm is AES256 and you can get a list of available algorithms from the keybase.KeybasePublicKey.crypto_algos() parameter.
If digest_algo is supplied it should be the name of a digest algorithm to use. The default is SHA512 and you can get a list of available algorithms from the keybase.KeybasePublicKey.digest_algos() parameter.
If compress_algo is supplied it should be the name of a compression algorithm to use. The default is ZIP and you can get a list of available algorithms from the keybase.KeybasePublicKey.compress_algos() parameter.
For more information on how encryption works please see the gnupg.encrypt manual page.
A simple example:
kbase = Keybase('irc') pkey = kbase.get_public_key() instring = 'Hello, world!' encrypted = pkey.encrypt(instring) assert encrypted assert not encrypted.isspace() assert encrypted != instring
- verify(data, throw_error=False)[source]¶
Verify the signature on the contents of the string data. Returns True if the signature was verified with the key, False if it was not. If you supply throw_error=True to the call then it will throw a KeybasePublicKeyVerifyError on verification failure with a status message that tells you more about why verification failed.
Failure status messages are:
- invalid gpg key
- signature bad
- signature error
- decryption failed
- no public key
- key exp
- key rev
For more information what these messages mean please see the gnupg._parsers.Verify manual page.
>>> message_good = """ ... -----BEGIN PGP SIGNED MESSAGE----- ... Hash: SHA1 ... ... Hello, world! ... -----BEGIN PGP SIGNATURE----- ... Version: GnuPG v1 ... ... iQEcBAEBAgAGBQJTWHSVAAoJEO7zMmcMHMCAYpEH/j2hJApaHXSj0ddgbrmUdJ2z ... vZ5DFDR9syTPHrwtRJLPH7tgdiAtUpyXLozL321JIR7sExzONl7IKdpH1Qn0y1I/ ... h6mV0Dm+AAJXWtbn08rDW2WWuW4+EBEy12Cfk2r1rF8KT+g3gcc2wLejSACkf7v+ ... jKo5SnvIwIMze+Msqjcz/+hbKRdEEoD2zihe6ilMfbR1tCt8GALQVa8YEoHpgkcL ... MWbXSCgM7Q0gf00kHWa3A8rClW0dzW5kJG+InbymtenaDNwoNlFb6DHUdyF//REx ... YjJ6qHf7qFwtXPBiwrZf+VYt5OnjeWW6ybYasfrJiXi1qnd6IM40QCGlR0UXhII= ... =oUn0 ... -----END PGP SIGNATURE----- ... """ >>> message_bad = """ ... -----BEGIN PGP SIGNED MESSAGE----- ... Hash: SHA1 ... ... Hello, another world! ... -----BEGIN PGP SIGNATURE----- ... Version: GnuPG v1 ... ... iQEcBAEBAgAGBQJTWHSVAAoJEO7zMmcMHMCAYpEH/j2hJApaHXSj0ddgbrmUdJ2z ... vZ5DFDR9syTPHrwtRJLPH7tgdiAtUpyXLozL321JIR7sExzONl7IKdpH1Qn0y1I/ ... h6mV0Dm+AAJXWtbn08rDW2WWuW4+EBEy12Cfk2r1rF8KT+g3gcc2wLejSACkf7v+ ... jKo5SnvIwIMze+Msqjcz/+hbKRdEEoD2zihe6ilMfbR1tCt8GALQVa8YEoHpgkcL ... MWbXSCgM7Q0gf00kHWa3A8rClW0dzW5kJG+InbymtenaDNwoNlFb6DHUdyF//REx ... YjJ6qHf7qFwtXPBiwrZf+VYt5OnjeWW6ybYasfrJiXi1qnd6IM40QCGlR0UXhII= ... =oUn0 ... -----END PGP SIGNATURE----- ... """ >>> kbase = Keybase('irc') >>> pkey = kbase.get_public_key() >>> verified = pkey.verify(message_good) >>> assert verified >>> verified = pkey.verify(message_bad) >>> assert not verified >>> pkey.verify(message_bad, throw_error=True) Traceback (most recent call last): ... KeybasePublicKeyVerifyError: signature bad
If you want to verify the signature on a file (either embedded or detached) please see keybase.KeybasePublicKey.verify_file() method.
- verify_file(fname, sigfname=None, throw_error=False)[source]¶
Verify the signature on a file named fname. This is a string file name, not a file object. If only a fname is provided the method assumes the signature is embedded in the file itself. An embedded signature is usually produced like so:
gpg -u keybase.io/irc --sign helloworld.txt
If a sigfname argument is prodived it’s assumed to be a path to signature file for a detached signature. A detached signature is usually produced like so:
gpg -u keybase.io/irc --detach-sign helloworld.txt
Returns True if the signature is verifiable with the key, False if it is not verifiable.
If you supply the throw_error=True option to the call then it will throw a KeybasePublicKeyVerifyError on verification failure with a status message that tells you more about why the verification failed.
Failure status messages are:
- invalid gpg key
- signature bad
- signature error
- decryption failed
- no public key
- key exp
- key rev
For more information what these messages mean please see the gnupg._parsers.Verify manual page.
An embedded signature example:
kbase = Keybase('irc') pkey = kbase.get_public_key() verified = pkey.verify_file('helloworld.txt.gpg') assert verified
A detached signature example:
kbase = Keybase('irc') pkey = kbase.get_public_key() fname = 'helloworld.txt' signame = 'helloworld.txt.sig' verified = pkey.verify_file(fname, signame) assert verified
The KeybaseAdmin Class – Manipulating User’s Public Key Data¶
The KeybaseAdmin class lets you authenticate as a user to the Keybase.io public data store and manipulate the stored public keys for the user. You can add and revoke keys, create new keys and validate other user’s keys.
Note
This class is currently not implemented! Anything you read here is planned, not real, at this point.
The Keybase Error Classes¶
- class keybase.KeybaseUnboundInstanceError[source]¶
Thrown when calling a Keybase object method that requires the object be bound to a real user in the keybase store and the instance hasn’t had such a binding established yet.
- class keybase.KeybaseUserNotFound[source]¶
Thrown when calling Keybase.lookup(username) and the username cannot be located in the keybase.io public key repository.
- class keybase.KeybaseLookupInvalidError[source]¶
Thrown when calling Keybase.lookup(username) on an instance that has already been bound to a valid user via another lookup() call.
- class keybase.KeybasePublicKeyError[source]¶
Thrown when a KeybasePublicKey cannot be created successfully.