modules/gnupg/API.txt

// $Id$

GnuPG API for Drupal
====================
This is a developers' guide to the GnuPG API for Drupal 6.x.


CONSTANTS
---------

  GNUPG_HOMEDIR

    The GnuPG home directory, passed to `gpg' using the `--homedir'
    command-line parameter.

    The constant's value is configurable by the Drupal administrator via the
    <admin/settings/gnupg> settings screen.

  GNUPG_KEYID

    The default key ID to pass to `gpg' using the `--recipient' command-line
    parameter when no other key IDs have been explicitly given in
    gnupg_encrypt() or gnupg_decrypt().

    The constant's value is configurable by the Drupal administrator via the
    <admin/settings/gnupg> settings screen.


VARIABLES
---------

  string variable_get('gnupg_exec', gnupg_guess_binpath())

    A file system path to the `gpg' binary. On Unix systems, this would
    typically be `/usr/bin/gpg' or `/usr/local/bin/gpg'.
    On Mac OS X with MacPorts the path is `/opt/local/bin/gpg'.

    The variable's value is configurable by the Drupal administrator via the
    <admin/settings/gnupg> settings screen.

    The path given by this variable would typically be used for calling
    gnupg_exec().


FUNCTIONS
---------

  Generic
  ~~~~~~~

    string gnupg_version()

      Returns the GnuPG version number by calling `gpg --version'.
      If there is a problem executing this command (e.g. because GnuPG
      isn't installed, or because the binary paths given in the module's
      configuration settings are incorrect), NULL is returned.

  Encryption
  ~~~~~~~~~~

    string gnupg_encrypt(string $plaintext, mixed $key_id = GNUPG_KEYID,
                         array $options = array())

      Encrypts the given plaintext using the specified public key(s).

      The $plaintext argument should contain a string with the data to be
      encrypted.

      The $key_id argument can contain one or multiple key IDs that the
      ciphertext will be encrypted for. It should be given as a string (one
      key) or an array of strings (for multiple keys).

      If encryption is successful, the function returns the corresponding
      ciphertext. Returns FALSE if the encryption fails for any reason.

      The $options array is passed through to gnupg_exec().

      To use symmetric encryption, use NULL as the $key_id and pass the
      following options to gnupg_encrypt():

        $options = array('symmetric' => TRUE, 'passphrase' => $password);

  Decryption
  ~~~~~~~~~~

    string gnupg_decrypt(string $ciphertext, string $key_id = GNUPG_KEYID,
                         array $options = array())

      Decrypts the given ciphertext using the specified key.

      The $plaintext argument should contain a string with the data to be
      encrypted.

      To use symmetric decryption, use NULL as the $key_id and pass the
      following options to gnupg_decrypt():

        $options = array('symmetric' => TRUE, 'passphrase' => $password);

  Internal
  ~~~~~~~~

    mixed gnupg_exec(array $options = array(), $proc_open = FALSE,
                     array &$pipes = NULL, [$arg1, $arg2, ..., $argN])

      Invokes the `gpg' executable using exec()/proc_open().

      When called with $proc_open = FALSE, the default, delegates to exec()
      and returns an array containing every line of output from the command.

      When called with $proc_open = TRUE, delegates to proc_open() and
      returns a process handle as well as a set of stdin/stdout/stderr
      streams in $pipes (the caller is responsible for calling fclose() on
      each stream and proc_close() to close the process handle).

      Indiscriminately returns FALSE on failure, whether the problem was in
      not being able to execute the command in the first place (e.g. the
      binary doesn't exist) or in getting a failed exit status from the
      invoked program. No warnings are triggered.

      The $options array should contain key/value pairs that will be
      transformed to command-line options for the command to be executed.

      For example, this input array:

        $options = array('homedir' => 'DIR', 'lock-never' => TRUE)

      ...will get transformed into these command-line options:

        --homedir DIR --lock-never

      Note that all the values given in $options will get passed through
      escapeshellarg(). The keys will get passed through as they are.

      Any further arguments to this function will be filtered through
      escapeshellarg() and get appended to the command line as they are,
      each one prepended with a space. This is how you would pass in e.g.
      file paths.


MISCELLANEOUS
-------------
To add the GnuPG module as a dependency in your own Drupal module, simply
include the following line in your module's .info file:

  dependencies[] = gnupg


CREDITS
-------
Developed and maintained by Arto Bendiken <http://bendiken.net/>
1	// $Id$
2
3	GnuPG API for Drupal
4	====================
5	This is a developers' guide to the GnuPG API for Drupal 6.x.
6
7
8	CONSTANTS
9	---------
10
11	GNUPG_HOMEDIR
12
13	The GnuPG home directory, passed to `gpg' using the `--homedir'
14	command-line parameter.
15
16	The constant's value is configurable by the Drupal administrator via the
17	<admin/settings/gnupg> settings screen.
18
19	GNUPG_KEYID
20
21	The default key ID to pass to `gpg' using the `--recipient' command-line
22	parameter when no other key IDs have been explicitly given in
23	gnupg_encrypt() or gnupg_decrypt().
24
25	The constant's value is configurable by the Drupal administrator via the
26	<admin/settings/gnupg> settings screen.
27
28
29	VARIABLES
30	---------
31
32	string variable_get('gnupg_exec', gnupg_guess_binpath())
33
34	A file system path to the `gpg' binary. On Unix systems, this would
35	typically be `/usr/bin/gpg' or `/usr/local/bin/gpg'.
36	On Mac OS X with MacPorts the path is `/opt/local/bin/gpg'.
37
38	The variable's value is configurable by the Drupal administrator via the
39	<admin/settings/gnupg> settings screen.
40
41	The path given by this variable would typically be used for calling
42	gnupg_exec().
43
44
45	FUNCTIONS
46	---------
47
48	Generic
49	~~~~~~~
50
51	string gnupg_version()
52
53	Returns the GnuPG version number by calling `gpg --version'.
54	If there is a problem executing this command (e.g. because GnuPG
55	isn't installed, or because the binary paths given in the module's
56	configuration settings are incorrect), NULL is returned.
57
58	Encryption
59	~~~~~~~~~~
60
61	string gnupg_encrypt(string $plaintext, mixed $key_id = GNUPG_KEYID,
62	array $options = array())
63
64	Encrypts the given plaintext using the specified public key(s).
65
66	The $plaintext argument should contain a string with the data to be
67	encrypted.
68
69	The $key_id argument can contain one or multiple key IDs that the
70	ciphertext will be encrypted for. It should be given as a string (one
71	key) or an array of strings (for multiple keys).
72
73	If encryption is successful, the function returns the corresponding
74	ciphertext. Returns FALSE if the encryption fails for any reason.
75
76	The $options array is passed through to gnupg_exec().
77
78	To use symmetric encryption, use NULL as the $key_id and pass the
79	following options to gnupg_encrypt():
80
81	$options = array('symmetric' => TRUE, 'passphrase' => $password);
82
83	Decryption
84	~~~~~~~~~~
85
86	string gnupg_decrypt(string $ciphertext, string $key_id = GNUPG_KEYID,
87	array $options = array())
88
89	Decrypts the given ciphertext using the specified key.
90
91	The $plaintext argument should contain a string with the data to be
92	encrypted.
93
94	To use symmetric decryption, use NULL as the $key_id and pass the
95	following options to gnupg_decrypt():
96
97	$options = array('symmetric' => TRUE, 'passphrase' => $password);
98
99	Internal
100	~~~~~~~~
101
102	mixed gnupg_exec(array $options = array(), $proc_open = FALSE,
103	array &$pipes = NULL, [$arg1, $arg2, ..., $argN])
104
105	Invokes the `gpg' executable using exec()/proc_open().
106
107	When called with $proc_open = FALSE, the default, delegates to exec()
108	and returns an array containing every line of output from the command.
109
110	When called with $proc_open = TRUE, delegates to proc_open() and
111	returns a process handle as well as a set of stdin/stdout/stderr
112	streams in $pipes (the caller is responsible for calling fclose() on
113	each stream and proc_close() to close the process handle).
114
115	Indiscriminately returns FALSE on failure, whether the problem was in
116	not being able to execute the command in the first place (e.g. the
117	binary doesn't exist) or in getting a failed exit status from the
118	invoked program. No warnings are triggered.
119
120	The $options array should contain key/value pairs that will be
121	transformed to command-line options for the command to be executed.
122
123	For example, this input array:
124
125	$options = array('homedir' => 'DIR', 'lock-never' => TRUE)
126
127	...will get transformed into these command-line options:
128
129	--homedir DIR --lock-never
130
131	Note that all the values given in $options will get passed through
132	escapeshellarg(). The keys will get passed through as they are.
133
134	Any further arguments to this function will be filtered through
135	escapeshellarg() and get appended to the command line as they are,
136	each one prepended with a space. This is how you would pass in e.g.
137	file paths.
138
139
140	MISCELLANEOUS
141	-------------
142	To add the GnuPG module as a dependency in your own Drupal module, simply
143	include the following line in your module's .info file:
144
145	dependencies[] = gnupg
146
147
148	CREDITS
149	-------
150	Developed and maintained by Arto Bendiken <http://bendiken.net/>