Debuginfod Credential Helper RFC

I’ve been scoping out a use-case for debuginfod that would require authentication and authorization of users accessing debug information, and I’ve put together a RFC on how this might work, based on Git and Docker credential helpers. I’ve also started a parallel discussion in elfutils-devel, given that this would affect debuginfod users/implementors generally. Please take a look!

debuginfod Credential Helper RFC

Background

debuginfod is a simple HTTP-based protocol allowing clients to obtain debug information from servers. The de-facto standard includes environment variables for pointing clients at available debuginfod servers, but it includes no mechanism to provide credentials.

This approach works well for fully open-source projects, but debuginfod is also particuarly useful for the highly-stripped binaries and constrained environments found in the embedded space. There, it’s common for licensing constraints to require access to source and debug information to be restricted to specific users.

Proposal

debuginfod clients could support a new DEBUGINFOD_CREDENTIAL_HELPER environment variable. This would provide a command that a debuginfod client could run to obtain credentials to supply to the server, much like Git or Docker credential helpers do.

No modifications are proposed to generic debuginfod server implementations, since specific authentication and authorization decisions are usually quite domain-specific, and it’s fairly easy to write or configure a custom debuginfod server to make them.

The proposal also omits any mechanism for the client to interactively prompt the user for their credentials or to retrieve them from storage; this is left to the credential helper.

Protocol

The behavior of the credential helpers broadly follows the example set by Git and Docker.

The DEBUGINFOD_CREDENTIAL_HELPER environment variable contains a string indicating the command to run. If the string begins with an absolute path, the command is the verbatim string. Otherwise, the command is the string prepended with debuginfod-credential-.

Once interpreted, the given command is executed in the shell with one additional argument to indicate the operation type. This is always get.

The helper reads a description of the requested credential from stdin and writes a description of the found credential to stdout. Errors may be reported to stderr.

Credential Format

Credential requests and found credentials are both broadly described using Git credential helpers’ input/output format, with some modifications.

Only the http and https protocols are supported, since debuginfod only operates over HTTP(S).

The url attribute is unsupported; URL components must instead be passed separately.

An added bearer attribute can supply OAuth2 bearer tokens in Base64. This attribute is mutually exclusive with username and password.

After a fairly thorough discussion in the elfutils devel mailing list, this proposal ended up being a bit heavyweight for libdebuginfod. In particular, libdebuginfod is used in environments (e.g. gdb) where forking subprocesses creates additional difficulties.

A counter-proposal was developed: instead of forking out to a credential helper subprocess, HTTP headers could be directly provided using a DEBUGINFOD_HEADERS or DEBUGINFOD_HEADERS_FILE environment variable. The file option would allow restricting access to a header file to a particular user. A local HTTP server could use this to verify the identity of incoming requests, allowing it to federate out to remote debuginfod servers, supplying whatever credentials are appropriate for the outbound server.

Just a note that if you’re using libcurl, you can enable support for reading a username/password from ~/.netrc with 1 LOC, and you can also pass user/pass in the url, like https://user:pw@host/path, by default.