Mailing List Archive: GnuPG: devel

gpgme-tool documentation updates

Index | Next | Previous | View Threaded

wking at drexel

Mar 27, 2012, 5:45 AM

Post #1 of 16 (554 views)
Permalink

gpgme-tool documentation updates

On Mon, Mar 26, 2012 at 05:16:15PM +0200, Marcus Brinkmann wrote:
> Documentation is badly needed for sure. I don't really remember any
> details about all the functions it provides, and what gaps there may be.

I've started moving through the docs trying to get a feel for
gpgme-agent, and making corrections or additions as I see the need.
How should I submit the changes? Should I mail patches to this thread
(`git send-email …`) or publish my git repository somewhere and email
pull requests?

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wk at gnupg

Mar 27, 2012, 8:53 AM

Post #2 of 16 (527 views)
Permalink

Re: gpgme-tool documentation updates [In reply to]

On Tue, 27 Mar 2012 14:45, wking [at] drexel said:

> How should I submit the changes? Should I mail patches to this thread
> (`git send-email …`) or publish my git repository somewhere and email

Please send patches. That is easier for us to handle. If they are too
long, please send them by private mail to Marcus.

Note, that gpg-tool has an online help system. Most of the documentation
can go there.

Shalom-Salam,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wking at drexel

Mar 27, 2012, 11:00 AM

Post #3 of 16 (529 views)
Permalink

Re: gpgme-tool documentation updates [In reply to]

On Tue, Mar 27, 2012 at 04:32:00PM +0200, Marcus Brinkmann wrote:
> For substantial contributions, we face the legal issues. GPGME is
> currently copyright by g10 Code GmbH, the company by GnuPG author
> Werner Koch. GPGME used to be GPLv2 or later for a long time, but
> eventually we did a license change to the more liberal LGPLv2.1 or
> later, so more people can use it.
>
> We currently do not have formal copyright assignments for GPGME
> prepared, but, informally, would you be ok with it if in the future we
> want to change the GPGME license to another FSF-approved free software
> license?

I would be ok with any free license, although I'd prefer at least
LGPL.

On Tue, Mar 27, 2012 at 05:53:38PM +0200, Werner Koch wrote:
> Please send patches. That is easier for us to handle. If they are too
> long, please send them by private mail to Marcus.

Well, the new help strings is 160 new lines, not that there's anything
complicated going on, so maybe that qualifies as too long ;).

> Note, that gpg-tool has an online help system. Most of the
> documentation can go there.

I assume you mean the `hlp_*` strings in `gpgme-tool.c`, which is what
I was fleshing out. I think it would also be useful to add some
comments to the texinfo in `doc/` giving a general overview, but I
have little texinfo-fu ;).

If the documentation patches look good, I think I'll add support for a
~/.gnupg/S.gpgme-tool socket next, to increase the similarity with
gpg-agent operation.

Cheers,
Trevor

p.s. Marcus, you signed your last message with FCD2A293, which I
haven't been able to find anywhere. Your only keys on
pool.sks-keyservers.net seem to be 87978569 and 36E7CD09. Could you
point me to a copy of your key?

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wking at drexel

Apr 6, 2012, 12:38 PM

Post #4 of 16 (509 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Tue, Mar 27, 2012 at 02:00:44PM -0400, W. Trevor King wrote:
> If the documentation patches look good, I think I'll add support for a
> ~/.gnupg/S.gpgme-tool socket next, to increase the similarity with
> gpg-agent operation.

I started looking into this today, and here are my thoughts so far.

1) Creating an Assuan server that listens at a standard socket
(e.g. ~/.assuan/S.<program-name>) should probably be part of
libassuan. Then I could avoid duplicating a lot of gpg-agent.c's
socket handling code. Should I move that code over?

2) gnupg/jnlib is ~10k lines, which seems big enough to be a
stand-alone library to me ;). If you don't want to release it as a
stand-alone library, it should probably at least have its own git
repository. That way you could use git submodules to include it in
gnupg, and still easily borrow the code to use it in other
projects.

Cheers,
Trevor

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wking at drexel

Apr 6, 2012, 1:25 PM

Post #5 of 16 (509 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Fri, Apr 06, 2012 at 03:38:41PM -0400, W. Trevor King wrote:
> 1) Creating an Assuan server that listens at a standard socket
> (e.g. ~/.assuan/S.<program-name>) should probably be part of
> libassuan. Then I could avoid duplicating a lot of gpg-agent.c's
> socket handling code. Should I move that code over?

Since there is already a reasonable amount of socket handling code in
libassuan, I though I'd be a bit more explicit about what I wanted to
move over:

* General server-related option definition and handling (oServer,
oDaemon, oNoDetach, …)
* Server-related global variables and handling (shutdown_pending,
check_own_socket_running, socket_name, socket_nonce,
create_socket_name, check_for_running_agent, …)
* Cleanup and signal handling (remove_socket, handle_signal, …). In
order to allow flexible signal handling, there should be stand-alone
handlers for common signals (i.e. assuan_handle_sigint,
assuan_handle_sigterm). Users would have to use nPth themselves to
handle signals.

That would be a good start anyway ;). I'll probably run into some
others if I get a green light to start working on this.

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wk at g10code

Apr 7, 2012, 3:16 AM

Post #6 of 16 (508 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Fri, 6 Apr 2012 21:38, wking [at] drexel said:

> 1) Creating an Assuan server that listens at a standard socket
> (e.g. ~/.assuan/S.<program-name>) should probably be part of
> libassuan. Then I could avoid duplicating a lot of gpg-agent.c's
> socket handling code. Should I move that code over?

In theory you are right. However, I prefer to keep the code separated.

> 2) gnupg/jnlib is ~10k lines, which seems big enough to be a
> stand-alone library to me ;). If you don't want to release it as a

GIT master has no more jnlib; it is part of gnupg/common. Marcus and me
already talked about having GnuPG runtime library. However, a
standalone library is a lot of work because you have to design a solid
and stable API and maintain it for a long time. Thus the current idea
is to gradually move certain functionality over to libgpg-error and
eventually rename libgpg-error. If we start to support 64 bit Windows,
we will likely need something like this.

> stand-alone library, it should probably at least have its own git
> repository. That way you could use git submodules to include it in
> gnupg, and still easily borrow the code to use it in other

Hmmm, this still requires to limit changes to the API to a minumum.
There is also the lincese question.

Salam-Shalom,

Werner

--
g10 Code GmbH http://g10code.com AmtsGer. Wuppertal HRB 14459
Hüttenstr. 61 Geschäftsführung Werner Koch
D-40699 Erkrath -=- The GnuPG Experts -=- USt-Id DE215605608

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wk at gnupg

Apr 7, 2012, 3:30 AM

Post #7 of 16 (504 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Fri, 6 Apr 2012 22:25, wking [at] drexel said:

> * Cleanup and signal handling (remove_socket, handle_signal, …). In
> order to allow flexible signal handling, there should be stand-alone

I think it is better to avoid signals as much as we can. We can't use
them under Windows anyway and thus we need Assuan commands insteads.

Salam-Shalom,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wking at drexel

Apr 7, 2012, 8:23 AM

Post #8 of 16 (506 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Sat, Apr 07, 2012 at 12:16:00PM +0200, Werner Koch wrote:
> On Fri, 6 Apr 2012 21:38, wking [at] drexel said:
>
> > 1) Creating an Assuan server that listens at a standard socket
> > (e.g. ~/.assuan/S.<program-name>) should probably be part of
> > libassuan. Then I could avoid duplicating a lot of gpg-agent.c's
> > socket handling code. Should I move that code over?
>
> In theory you are right. However, I prefer to keep the code separated.

Separated is fine, duplicated is bad ;). I'd like to duplicate
gpg-agent's approach, since it's a well-tested example of doing what I
want gpgme-tool to do, but if you want me to implement that approach
from scratch, I could try and do that instead… Do you mean "don't copy
code from GnuPG into libassuan" or "don't put this socket handling
stuff in libassuan"?

> > 2) gnupg/jnlib is ~10k lines, which seems big enough to be a
> > stand-alone library to me ;). If you don't want to release it as a
>
> GIT master has no more jnlib; it is part of gnupg/common.

Ah, yes. I've pulled the Git repo now instead of looking at the
tarball used to install GnuPG on my system.

> Marcus and me already talked about having GnuPG runtime library.
> However, a standalone library is a lot of work because you have to
> design a solid and stable API and maintain it for a long time.

You only have to maintain the old API it if people use it ;). In my
opinion, reducing code duplication would make it easier to maintain
the libassuan ecosystem, not harder.

> Thus the current idea is to gradually move certain functionality
> over to libgpg-error and eventually rename libgpg-error.

Socket handling and filename creation are probably not going to end up
in libgpg-error, are they?

On Sat, Apr 07, 2012 at 12:30:56PM +0200, Werner Koch wrote:
> On Fri, 6 Apr 2012 22:25, wking [at] drexel said:
>
> > * Cleanup and signal handling (remove_socket, handle_signal, …). In
> > order to allow flexible signal handling, there should be stand-alone
>
> I think it is better to avoid signals as much as we can. We can't use
> them under Windows anyway and thus we need Assuan commands insteads.

While I agree that `gpg-connect-agent SHUTDOWN` would work as well as
`killall gpg-agent`, some users will still be killing gpg-agent by
shutting down their computer. On Linux anyway, that means you'll be
getting a SIGTERM, and you'll want to unlink your socket before
exiting. I don't see a way to do that without using signal handling.
I suppose you could drop Unix sockets entirely in favor of inet
sockets?

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wking at drexel

Apr 7, 2012, 8:58 AM

Post #9 of 16 (505 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Sat, Apr 07, 2012 at 12:30:56PM +0200, Werner Koch wrote:
> On Fri, 6 Apr 2012 22:25, wking [at] drexel said:
>
> > * Cleanup and signal handling (remove_socket, handle_signal, …). In
> > order to allow flexible signal handling, there should be stand-alone
>
> I think it is better to avoid signals as much as we can. We can't use
> them under Windows anyway and thus we need Assuan commands insteads.

Actually, this is a great reason to extract the socket server code in
a sharable library. I'm definately not going to want to write Windows
code for gpgme-tool, because (1) I don't know anything about Windows
and (2) I don't have access to any Windows machines for testing. If
libassuan had that part of the gpg-agent logic internally,
libassuan-based servers would run on Windows out-of-the-box, without
needing a Windows-capable dev attached to each server project.

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.48 KB)

wking at tremily

Oct 7, 2012, 4:41 PM

Post #10 of 16 (244 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

With Python 3.3 officially released, I can now use socket.sendmsg() to
send FDs to Assuan servers listening on Unix sockets. This means
pgp-mime can communicate with a persistent gpgme-tool server (sweet!),
where I used to use subprocess.Popen() to fork/exec a client for every
transaction and pass the file descriptors via process inheritance
(yuck!).

This works on my local system, with a patched version of gpgme-tool
that uses the cues off the existing -s/--server option to run as a
fork/exec server listening on a Unix socket instead of running as a
pipe server.

The problem is getting this to a releasable state without forking
gpgme-tool. We discussed this back in April [1], but I was pushing
for additional socket-server utility code in libassuan, and that
didn't seem to be going over very well. I still think that's the best
way to go, but if changes to GPGME are more likely to be accepted, I
can go that way instead. I'll volunteer myself to work up patches for
any of the following:

a) libassuan: Some variation on my original suggestion: a helper
function to spawn an Assuan server (either pipe or socket) which
handles all the usual setup/teardown internally. Both gpg-agent
and gpgme-tool would then use this function, so it would have to be
sufficiently flexible to handle both cases. API to-be-determined.

b) gpgme: copy gpg-agent's socket handling code into gpgme-tool (with
copy-paste commits for proper attribution, followed by integration
commits by me).

c) same as (b), but I'll write up the socket handling from scratch
(man pages, etc.) to keep the code-base distinct from GnuPG. Since
I can't look at gpg-agent's code, I'll probably someone else to
handle the MS Windows side, if people want that to be supported.
Since we're just adding functionality, I see no reason why Windows
*must* be supported.

d) Other approaches?

Of course, if someone else wants to do the legwork, I'm happy to sit
back and use your code ;).

Cheers,
Trevor

[1]: http://thread.gmane.org/gmane.comp.encryption.gpg.devel/16843/focus=16865

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.82 KB)

wking at tremily

Oct 10, 2012, 8:22 AM

Post #11 of 16 (243 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Sun, Oct 07, 2012 at 07:41:41PM -0400, W. Trevor King wrote:
> b) gpgme: copy gpg-agent's socket handling code into gpgme-tool (with
> copy-paste commits for proper attribution, followed by integration
> commits by me).
>
> c) same as (b), but I'll write up the socket handling from scratch
> (man pages, etc.) to keep the code-base distinct from GnuPG. Since
> I can't look at gpg-agent's code, I'll probably someone else to
> handle the MS Windows side, if people want that to be supported.
> Since we're just adding functionality, I see no reason why Windows
> *must* be supported.

A very rough commit along the lines of (c) is in my `socket` branch
[1], if anyone wants to poke about.

[1]: http://git.tremily.us/?p=gpgme.git

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.82 KB)

wk at gnupg

Oct 11, 2012, 8:18 AM

Post #12 of 16 (244 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Mon, 8 Oct 2012 01:41, wking [at] tremily said:

> for additional socket-server utility code in libassuan, and that
> didn't seem to be going over very well. I still think that's the best

Right, it is too hard to get this into Libassuan in a flexible way. You
would end up with something as complicated as the gpgme event code.

> a) libassuan: Some variation on my original suggestion: a helper
> function to spawn an Assuan server (either pipe or socket) which
> handles all the usual setup/teardown internally. Both gpg-agent

If it ever turns out that this is required by a lot of other code, we
can revisit this then.

> b) gpgme: copy gpg-agent's socket handling code into gpgme-tool (with
> copy-paste commits for proper attribution, followed by integration

Fine. However, gpg-agent heavily relies on nPth semantics. This is
probably not what you want.

> c) same as (b), but I'll write up the socket handling from scratch
> (man pages, etc.) to keep the code-base distinct from GnuPG. Since
> I can't look at gpg-agent's code, I'll probably someone else to
> handle the MS Windows side, if people want that to be supported.

Actually we have a platform independent socket abstraction in libassuan
for that purpose. Check out how it is done in dirmngr or gpg-agent.

> Since we're just adding functionality, I see no reason why Windows
> *must* be supported.

We can talk about neglecting WindowsCE, but Windows is a/the mainstream
platform and thus we should support it.

Shalom-Salam,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wk at gnupg

Oct 11, 2012, 8:20 AM

Post #13 of 16 (242 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Wed, 10 Oct 2012 17:22, wking [at] tremily said:

> A very rough commit along the lines of (c) is in my `socket` branch

Is there a reason why you do not use assuan_sock_new et al?

Salam-Shalom,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wking at tremily

Oct 11, 2012, 12:07 PM

Post #14 of 16 (239 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Thu, Oct 11, 2012 at 05:18:30PM +0200, Werner Koch wrote:
> > b) gpgme: copy gpg-agent's socket handling code into gpgme-tool (with
> > copy-paste commits for proper attribution, followed by integration
>
> Fine. However, gpg-agent heavily relies on nPth semantics. This is
> probably not what you want.

The socket setup and teardown shouldn't be too tied up in the
threading, so I'll take a look.

> > c) same as (b), but I'll write up the socket handling from scratch
> > (man pages, etc.) to keep the code-base distinct from GnuPG. Since
> > I can't look at gpg-agent's code, I'll probably someone else to
> > handle the MS Windows side, if people want that to be supported.
>
> Actually we have a platform independent socket abstraction in libassuan
> for that purpose. Check out how it is done in dirmngr or gpg-agent.

Good point. I'm talking a look at that now.

On Thu, Oct 11, 2012 at 05:20:24PM +0200, Werner Koch wrote:
> On Wed, 10 Oct 2012 17:22, wking [at] tremily said:
> > A very rough commit along the lines of (c) is in my `socket` branch
>
> Is there a reason why you do not use assuan_sock_new et al?

I didn't read the libassuan manual thoroughly enough ;).

I'm a bit confused about how to handle listen() and accept(), which
are not wrapped by libassuan. libassuan's test/ce-server.c uses
SOCKET2HANDLE() and HANDLE2SOCKET() defined in assuan-def.h to convert
between `assuan_fd_t`s and `int`s, while gpg-agent uses INT2FD() and
FD2INT() defined in sysutils.h to convert between `gnupg_fd_t`s and
`int`s. Perhaps I should be using assuan_fdopen() instead of
INT2FD()? I'm not sure what the most idomatic approach is.

I've rebased my socket branch against the new master, and slacked off
on commit messages. I'll beat them back into shape once the code gets
to a merge-able state.

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.82 KB)

wk at gnupg

Oct 11, 2012, 12:59 PM

Post #15 of 16 (239 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Thu, 11 Oct 2012 21:07, wking [at] tremily said:

> I'm a bit confused about how to handle listen() and accept(), which

There was no immediate need to wrap them. We can do that of course.

> are not wrapped by libassuan. libassuan's test/ce-server.c uses
> SOCKET2HANDLE() and HANDLE2SOCKET() defined in assuan-def.h to convert
> between `assuan_fd_t`s and `int`s, while gpg-agent uses INT2FD() and
> FD2INT() defined in sysutils.h to convert between `gnupg_fd_t`s and

That is all a mess. The casting won't work on 64 bit Windows due to
sizeof(void*) > sizeof(int); i.e. HANDLE vs. int. There are also a lot
of other maintenance problems with them due to the non-unified usage of
file descriptors in Windows (System handles, several different libc fd,
sockets, etc). Back then when I ported GnuPG to CE, the plan was to
soon start with a clean way of addressing this. However a 64 bit GnuPG
port is not on the horizon anymore. The code in Libassuan is likely
better.

> `int`s. Perhaps I should be using assuan_fdopen() instead of
> INT2FD()? I'm not sure what the most idomatic approach is.

Better try to stay away from that mess ;-).

Salam-Shalom,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.

_______________________________________________
Gnupg-devel mailing list
Gnupg-devel [at] gnupg
http://lists.gnupg.org/mailman/listinfo/gnupg-devel

wking at tremily

Oct 11, 2012, 1:15 PM

Post #16 of 16 (240 views)
Permalink

Re: gpgme-tool socket interface [In reply to]

On Thu, Oct 11, 2012 at 09:59:06PM +0200, Werner Koch wrote:
> On Thu, 11 Oct 2012 21:07, wking [at] tremily said:
>
> > I'm a bit confused about how to handle listen() and accept(), which
>
> There was no immediate need to wrap them. We can do that of course.
>
> [snip discussion of ce-server.c vs. gpg-agent]
>
> The code in Libassuan is likely better.

I've updated my socket branch to use the libassuan socket wrappers.

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

Attachments:

signature.asc (0.82 KB)

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads