spotify/crtauth

a public key backed client/server authentication system

crtauth - a public key backed client/server authentication system

The latest version of this software can be fetched from GitHub.

crtauth is a system for authenticating a user to a centralized server. The initial use case is to create a convenient authentication for command line tools that interacts with a central server without resorting to authentication using a shared secret, such as a password.

The code available in this project is written in Python. There is also a Java version, implementing the same protocol available at https://github.com/spotify/crtauth-java

crtauth leverages the public key cryptography mechanisms that is commonly used by ssh(1) to authenticate users to remote systems. The goal of the system is to make the user experience as seamless as possible using the ssh-agent program to manage access to encrypted private keys without asking for a password each time the command is run

The name of the project is derived from the central concepts challenge, response, token and authentication, while at the same time reminding us old timers of the soon to be forgotten cathode ray tube screen technology.

Using the library

For the server side functionality there is a high level API available in the wsgi module. It provides wsgi middleware functionality that can be used to protect a service using the crtauth authentication mechanism. hello_world_server gives a minimal example on how this API is used. If crtauth is to be used in a non-WSGI environment, there is a lower level API available in the server module.

For clients an authentication plugin for Python Requests is available. An example use of the client module can be seen in the hello_world_client example.

Technical details

This section gives big picture overview of how crtauth operates. For the specifics of the protocol and it's messages, please see the specification.

Command line tools that connect to a central server to perform some action or fetch some information can be a very useful thing. crtauth is currently specified to work with HTTP as transport, but it is entirely possible to re-use that exposes information about servers using an HTTP-based API.

The basic operation of the protocol follows the following pattern

• The client requests a challenge from the server, providing a username.
• The server creates a challenge that gets sent back to the client.
• The client signs the challenge and returns the response to the server.
• The server verifies that the response is valid and if so it issues an access token to the client.
• The access token is provided to when calling protected services.
• The server validates that the token is valid and if so, provides access to the client.

The that implement this mechanism has two parts, one for the server and one for the client. A server that wants to authenticate clients instantiates an AuthServer instance (defined in the crtauth.server module) with a secret and a KeyProvider instance as constructor arguments. The very simple FileKeyProvider reads public keys from a filesystem directory using a filename pattern derived from the username of the connecting user.

Once there is an AuthServer instance, it can generate a challenge string for a specific user using the create_challenge() method.

The client part of the mechanism is also contained in the crtauth.server module, in the create_response() function. It takes a challenge string provided by the server and returns a response string suitable for sending back to the server.

The server in turn validates the response from the client and if it checks out it returns an access token that can be used by the client to make authenticated requests. This validation is done in the create_token() method of the AuthServer class.

For subsequent calls to protected services, the provided access token can be verified using the validate_token() method of the AuthServer instance.

SSH keys from LDAP

This library also provides functionality to extract public ssh keys for connecting users using an LDAP directory. To use this functionality, which is available in the ldap_key_provider.py module, the python-ldap module needs to be installed.

License

crtauth is free software, this code is released under the Apache Software License, version 2. The original code is written by Noa Resare with contributions from John-John Tedro, Erwan Lemmonier, Martin Parm and Gunnar Kreitz

All code is Copyright (c) 2011-2017 Spotify AB

crtauth's Issues

v0 tokens are used even in the v1 use case

_make_token() in server.py makes v0 tokens for all code paths. This is not an interoperability problem as the client treats the token as an opaque string, but it is polite to adhere to spec.

Do we have the wrong copyright header?

@nresare Most files have Licensed to the Apache Software Foundation in the header. Should it be Licensed under the Apache License as specified in the LICENSE?

What does the client verifying the server name in the challenge == configured server name prevent?

Hi @nresare,

The client checks the server name in the challenge equals the server name the client itself was given (here

crtauth/crtauth/client.py

Line 57 in 6a62457

if challenge.server_name != server_name:

). @gimaker, @rohansingh, and I were wondering what kind of attack this would prevent.

If client-to-server communication is over TLS, the attacker can't inject a challenge in the middle of the handshake unless they had the TLS private key in which case there would probably be bigger problems.

The attacker can simply set its crtauth server name to match that of the legit crtauth server. And if it managed to get the client to send back a signed challenge , the attacker would only have some bytes signed by the client. This response doesn't seem like it can be used for much as the attacker shouldn't know the crtauth secret the legit server is using. So any signed challenge couldn't be used to get a real auth token.

We have multiple crtauth servers and the client might want to round-robin requests to all of them. So the server names will change. We're thinking of setting all the clients and servers to just have a fixed crtauth server name like foo.com just to work around this check. Maybe we're missing something?

crtauth gives misleading error message when no public keys present on challenge server

While using a CLI tool that uses crtauth, I came across the following exception:

crtauth.exceptions.SshAgentError: Your ssh-agent does not have the required key added. This usually indicates that ssh-add has not been run.

However, ssh-add -L showed that my key was added to the SSH agent on my local machine.

It turns out that there were no public keys present on the challenge server. When I added the appropriate public key to the challenge server, this exception disappeared and the CLI auth worked and proceeded as normal.

The error message feels a bit misleading. I imagine it'd be even more frustrating to come across that error message and not have access to the challenge server to see if there's any issues with the challenge server.

authentication fails if there is a trailing slash on a base URL

CrtauthMiddleware in wsgi.py checks for an exact match for /_auth on the path component of incoming request PATH_INFO values. Unfortunately, sometimes PATH_INFO willb e //_auth (if you provide a base URL for your service including a trailing slash) which breaks authentication.

Request For Comments: Version 1 spec

I have rewritten the internal version 0 spec into a version 1 spec, available at the following location:

https://github.com/noaresare/crtauth/blob/wip-protocol/PROTOCOL.md

Besides introducing the Version 1 protocol (which is already mostly implemented in the master branch) it introduces some changes. Feel free to read and comment.

Any reason we don't use paramiko?

I've only briefly read a bit of paramiko but it looks pretty full-featured in talking to ssh-agent. Do we not use for any reason?

Deprecate and/or archive this project

If this project is no longer in use, it should be archived. Looks like the version of requests it's using has a CVE on it.

Multiple key support

Any thoughts on how to support multiple keys? Make the client pass the key fingerprint and try all available keys?

AgentSigner socket blocks forever when SSH agent has no identities

https://github.com/spotify/crtauth/blob/master/crtauth/ssh.py#L134
http://docs.python.org/2.6/library/socket.html#socket.socket.setblocking

When using crtauth with the AgentSigner plug and a functioning SSH agent without any identities, crtauth will block forever on self.sock.recv(). This can lead to consumer code mysteriously waiting forever, as crtauth defaults to using the AgentSigner plug.

AgentSigner should setblocking or settimeout on its socket to prevent this.

crtauth should not raise RuntimeErrors

https://github.com/spotify/crtauth/search?q=RuntimeError&type=Code
http://docs.python.org/release/2.6.8/library/exceptions.html#exceptions.RuntimeError

crtauth seems to use RuntimeError for a subset of its exceptions. This makes it difficult for consumer code to isolate crtauth exceptions. crtauth should use its own Exception classes.

It also seems like a misleading error to raise - while the documentation doesn't say explicitly I would expect RuntimeErrors to be raised by the Python runtime for things that didn't fall elsewhere.