Mercurial > p > roundup > code
comparison doc/admin_guide.txt @ 8478:ed4ef394d5d6
doc: initial attempt to document setup of pgp support for email.
Used an AI assistant to help write this. Basic gpg commands seem to
work, but I have not tested this totally. Docs basically follow the
setup used for pgp testing in the test suite.
It looks like roundup accepts signed emails as well as encrypted
and signed emails. But it does not generate signed emails.
Also it looks like there is no PGP support for alternate email
addresses. Only primary addresses can do PGP emails.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sat, 15 Nov 2025 16:59:24 -0500 |
| parents | d36bd4c521ac |
| children | 0fda84bc7584 b09ef85f0da6 |
comparison
equal
deleted
inserted
replaced
| 8477:d36bd4c521ac | 8478:ed4ef394d5d6 |
|---|---|
| 1868 | 1868 |
| 1869 Because environment variables can be inadvertently exposed in | 1869 Because environment variables can be inadvertently exposed in |
| 1870 logs or process listings, Roundup does not currently support | 1870 logs or process listings, Roundup does not currently support |
| 1871 loading secrets from environment variables. | 1871 loading secrets from environment variables. |
| 1872 | 1872 |
| 1873 .. _pgpconfig: | |
| 1874 | |
| 1875 Configuring PGP Email Support | |
| 1876 ============================= | |
| 1877 | |
| 1878 .. note:: | |
| 1879 This section was written with the help of the Devin/DeepWiki AI. | |
| 1880 | |
| 1881 You have to install the gpg module using pip. See :ref:`directions for | |
| 1882 installing gpg <gpginstall>` | |
| 1883 in the upgrading document for more information. | |
| 1884 | |
| 1885 In your tracker's config.ini configure the following settings in the | |
| 1886 ``[pgp]`` section:: | |
| 1887 | |
| 1888 enable = yes | |
| 1889 homedir = /path/to/pgp/configdir | |
| 1890 roles = admin | |
| 1891 | |
| 1892 This will allow any user with the admin role to send signed pgp | |
| 1893 email. If ``roles`` is not set, all users will need to use signed | |
| 1894 emails. If it is not signed it will be rejected. Note that ``homedir`` | |
| 1895 must be an absolute path. Unlike other path settings, a relative path | |
| 1896 is not interpreted relative to the tracker home. See the documentation | |
| 1897 in config.ini for more information and other settings (e.g. to send | |
| 1898 encrypted emails from the tracker). | |
| 1899 | |
| 1900 When PGP is enabled and a message is signed with a valid signature, | |
| 1901 the database transaction source (db.tx_Source) is set to | |
| 1902 ``email-sig-openpgp`` instead of ``email``. This allows you to | |
| 1903 restrict certain operations (e.g. changing a private flag) to | |
| 1904 authenticated/signed emails. | |
| 1905 | |
| 1906 Creating GPG Keys for the Tracker | |
| 1907 --------------------------------- | |
| 1908 | |
| 1909 To generate a keypair use:: | |
| 1910 | |
| 1911 gpg --homedir /path/to/pgp/configdir --gen-key | |
| 1912 | |
| 1913 where the homedir directory matches the one you set in | |
| 1914 config.ini. Note the gpg homedir must be created before you run the | |
| 1915 command. You will be prompted for the full name of your tracker and | |
| 1916 the email address for your tracker. You also need to do with as the | |
| 1917 user who runs roundup (aka the roundup user) and the roundup email | |
| 1918 gateway. Do not encrypt the key. | |
| 1919 | |
| 1920 Roundup has no mechanism for reading the private key if it is | |
| 1921 encrypted. So make sure the permissions on the homedir only allow the | |
| 1922 roundup user to read the files. | |
| 1923 | |
| 1924 You can export the public key for use by clients using:: | |
| 1925 | |
| 1926 gpg --homedir /path/to/pgp/configdir --export -a tracker@example.com > tracker-public.key | |
| 1927 | |
| 1928 with homedir and email matching the values used to generate the | |
| 1929 key. This will allow users to import the public key and encrypt emails | |
| 1930 to the tracker. | |
| 1931 | |
| 1932 The public gpg key for each user's email address must be imported. To | |
| 1933 do this, obtain the user's public key for their primary email address | |
| 1934 and import it using:: | |
| 1935 | |
| 1936 gpg --homedir /path/to/tracker/gpg --import user-public-key.asc | |
| 1937 | |
| 1938 While Roundup supports multiple addresses for each user, only the | |
| 1939 primary address supports PGP signed or encrypted messages. | |
| 1940 | |
| 1941 .. comment: | |
| 1942 Questions: | |
| 1943 | |
| 1944 Can roundup send signed emails? (looks like no, why??) | |
| 1945 | |
| 1946 Why are alternate addresses not supported for receiving PGP emails? | |
| 1947 | |
| 1948 Does Roundup ever send an email to an alternate email address? | |
| 1949 | |
| 1950 Should there be some way for a user to upload their own public key? | |
| 1951 If so what ui (paste armored asci cert in textbox, upload ascii | |
| 1952 file from user page and process)? | |
| 1953 | |
| 1873 Tasks | 1954 Tasks |
| 1874 ===== | 1955 ===== |
| 1875 | 1956 |
| 1876 Maintenance of Roundup can involve one of the following: | 1957 Maintenance of Roundup can involve one of the following: |
| 1877 | 1958 |