Seahorse DBUS API

The Seahorse DBUS API allows other programs to:

  • Query information about the user's keys, and watch for changes
  • Perform import/export and other basic operations on the user's keys
  • Import keys from key servers.

What follows is basic documentation on how to this API. The API is currently in flux.

Service

The Seahorse DBUS service name is: 

org.gnome.seahorse

It is implemented by the seahorse-daemon process, which will be started automatically as needed (using DBUS activation).

Key Types

The key types represent the various encryption systems (such as OpenPGP and SSH) that Seahorse supports. Key types are a short alpha-numeric string. Known types: 

openpgp
openssh

Keys

Keys are identified by a unique string. The string begins with the Key Type (above) a colon followed by an implementation specific string. This identifier is not meant to be displayed to the user. For example: 

openpgp:B8098FB063E2C811

UIDs are represented as separate keys.

org.gnome.seahorse.KeyService

Import and exporting of keys, as well as some other misc stuff.

The DBUS Path where this interface is implemented is: 

/org/gnome/seahorse/keys

Functions

GetKeyTypes(out STRING[] keytypes)

Returns a set of keytype supported by Seahorse (see explanation above). 

GetKeyset(in STRING keytype, out STRING keysetpath)

Gets the DBUS path for a org.gnome.seahorse.Keys keyset which contains all keytype keys.

This method is provided for completeness. A caller can simply create a path like /org/gnome/seahorse/keys/openpgp and bypass this method call all together. 

ImportKeys(in STRING keytype, in STRING data, out STRING[] keys)

Imports data into the key ring of type keytype. Returns the keys imported. 

ExportKeys(in STRING keytype, in STRING[] keys, out STRING data)

Exports keys of type keytype and returns the exported text in data. 

GenerateCredentials(in STRING keytype, in {STRING/VARIANT}[] values)

Generates a new key. At the moment only the "openpgp" keytype is supported. The value parameter accepts "name", "email and "comment" as additional data for the new key. 

DisplayNotification(in STRING heading, in STRING text, in STRING icon, in BOOLEAN urgent)

Displays a notification (using libnotify when available). The heading and text can be markup and can include the special <key> tag, which is replaced with key specific information.

The <key> tag should have an id="" attribute which contains the id of the key in question. It can also have a field="" attribute containing a field name. For example: 

  • Signed by <i><key id="openpgp:B8098FB063E2C811" field="display-name"/></i>

Text interpolated with <key> tags will be updated automatically as new information is discovered about the key.

org.gnome.seahorse.Keys

Allows one to list, and query information keys of a specific keytype. Keys have 'fields' which contain information about the key. The basic fields are listed below. 

/org/gnome/seahorse/keys

Functions

ListKeys(out STRING[] keys)

Returns all keys in this keyset. This will include all known local, remote, and maybe even some missing keys. See the 'location' field. 

GetKeyField(in STRING key, in STRING field, out BOOLEAN has, out VARIANT value)

Get information in a certain field of a key. Make sure to check has to see if value contains valid information. (This is necessary due to deficiencies in DBUS variant handling). 

GetKeyFields(in STRING key, in STRING[] fields, out {STRING/VARIANT}[] values)

Get a number of fields of information about key. The info is returned in values. This is represented as a string/variant hashtable by most DBus bindings. values will only contain info for those fields that exist on the key. 

DiscoverKeys(in STRING[] keyids, in UINT flags, out STRING[] keys)

Given a set of raw keyids for a certain key type, this method will search for (on key servers, on the local network, etc...) and start the process of importing those keys into the key ring. The keys returned may initially be 'missing' (see the location field below). flags should be set to zero. 

MatchKeys(in STRING[] patterns, in UINT flags, out STRING[] keys, out STRING[] unmatched)

Find keys that match the given patterns. Patterns that are not found are returned in unmatched. Currently Seahorse only looks in the local key stores, but eventually this will include searching for remote keys. flags is a combination of: 

  •   local-only: 0x00000010

Note that MatchKeys may take a long time to return. You probably want to call it asynchronously.

Signals

KeyAdded(in STRING key)

A key was added to the keyset. 

KeyRemoved(in STRING key)

A key was removed from the keyset. 

KeyChanged(in STRING key)

A key was changed in the keyset.

Fields

display-name: (STRING) The name to show to the user.

display-id: (STRING) A Key ID to show to the user.

simple-name: (STRING) A simple name (to use in filenames and such).

fingerprint: (STRING) A displayable fingerprint for the key.

trust: (INT) 

  •   never    = -1 : Never trust this key (and all below zero)
  unknown  =  0 : Key trust is unknown
  marginal =  1 : Marginal trust of this key.
  full     =  5 : Full trust of this key
  ultimate = 10 : Ultimate trust (used for private keys).

expires: (UINT) Date key expires at (in seconds since 1970). zero means never expires.

location: (UINT) The location this key is in. The highest value is always used (eg: if a key is 'local' and 'remote', 'local' is used) 

  •   missing   = 10 : The key exists somewhere, but it's not available to us.
  searching = 20 : Seahorse is currently trying to find the key.
  remote    = 50 : The key is on a key server. 
  local    = 100 : The key is in our local key ring.

enc-type: (INT) The type of encryption done by this key. 

  •   symmetric = 1 : A symmetric encryption key.
  public    = 2 : An asymmetric key for which we only have the public part.
  private   = 3 : An asymmetric key for which we have both public and private parts.

flags: (UINT) Flags about a key 

  •   is-valid    = 0x0001 : Is a valid key.
  can-encrypt = 0x0002 : Key can encrypt a message.
  can-sign    = 0x0004 : Key can sign a message.
  expired     = 0x0100 : Key has expired.
  revoked     = 0x0200 : Key has been revoked 
  disabled    = 0x0400 : Key is disabled 
  trusted     = 0x1000 : Key is trusted by user

length: (UINT) Length of the key in bits.

org.gnome.seahorse.CryptoService

A basic interface for encryption and decryption of text messages.

This interface is still very much in flux. Note that the goal of this interface is not to provide an API useful for any and all encryption operations. This is a very simple API and for more involved use cases (encryption of files, megabytes of data, streaming) this will not be appropriate. 

/org/gnome/seahorse/crypto

Functions

EncryptText(in STRING[] recipients, in STRING signer, in STRING cleartext , out STRING crypttext)

Given a string array of recipients, a signer, and text to be signed, this function returns encrypted and/or signed text. A NULL string for the signer results in only encrypted text. 

EncryptFile(in STRING[] recipients, in STRING signer, in INT flags, in STRING clearuri , in STRING crypturi)

Similar to EncryptText this function uses the file in clearuri as input and writes the results to crypturi. 

SignText(in STRING signer, in UINT flags, in STRING cleartext, out STRING crypttext)

Returns text signed by the key indicated in signer. 

DecryptText(in STRING keytype, in UINT flags, in STRING crypttext, out STRING cleartext, out STRING signer)

Returns decrypted text and the signer if the text is signed. 

DecryptFile(in STRING keytype, in UINT flags, in STRING crypturi, in STRING clearuri, out STRING signer)

Similar to DecryptText this command decrypts data in the file crypturi and writes the results to the file clearuri. 

VerifyText(in STRING keytype, in UINT flags, in STRING crypttext, out STRING cleartext, out STRING signer)

Returns the verified text and the signer.

flags consists of 

  •   quiet = 0x00000001 : Don't display unnecessary UI

Apps/Seahorse/DBus (last edited 2013-11-19 17:27:10 by WilliamJonMcCann)