auth-source 实践

Table of Contents

1 Overview

The auth-source library is simply a way for Emacs and Gnus, among others, to answer the old burning question “What are my user name and password?”

(This is different from the old question about burning “Where is the fire extinguisher, please?”.)

The auth-source library supports more than just the user name or the password (known as the secret).

Similarly, the auth-source library supports multiple storage backend, currently either the classic “netrc” backend, examples of which you can see later in this document, or the Secret Service API. This is done with EIEIO-based backends and you can write your own if you want.

Next: Secret Service API, Previous: Overview, Up: Top [Contents][Index]

2 Help for users

“Netrc” files are a de facto standard. They look like this:

“netrc”文件有一个事实标准,他们看起来是这个样子:

machine mymachine login myloginname password mypassword port myport

The machine is the server (either a DNS name or an IP address). It’s known as :host in auth-source-search queries. You can also use host.

machine指的是服务(可以是DNS名字或者是IP地址)。auth-source-search查询中的:host。也可以使用host代替

The port is the connection port or protocol. It’s known as :port in auth-source-search queries.

port是连接端口或协议。

The user is the user name. It’s known as :user in auth-source-search queries. You can also use login and account.

user是用户名。也可以使用login或者account。

Spaces are always OK as far as auth-source is concerned (but other programs may not like them). Just put the data in quotes, escaping quotes as you’d expect with ‘\’.

对于auth-source来说空格是没问题的(但是其他程序可能不喜欢他们)。可以把数据放在括号里,如你所想,括号可以通过‘\’进行转义。

All these are optional. You could just say (but we don’t recommend it, we’re just showing that it’s possible)

所有的这些都是可选的,也可以仅仅这样写(但是我们不推荐这样,我们只是展示一下这样是可行的)

password mypassword

to use the same password everywhere. Again, DO NOT DO THIS or you will be pwned as the kids say.

所有地方都是用相同的密码。再次强调,别这样做,否则你就会如同孩子所说的那样被玩弄。

“Netrc” files are usually called .authinfo or .netrc; nowadays .authinfo seems to be more popular and the auth-source library encourages this confusion by accepting both, as you’ll see later.

“netrc”文件通常被称作.authinfo或者.neterc;现在.authinfo看起来更流行。auto-source库也通过接手两者来鼓励这种混淆,正如你后面看到的。

If you have problems with the search, set auth-source-debug to 'trivia and see what host, port, and user the library is checking in the Messages buffer. Ditto for any other problems, your first step is always to see what’s being checked. The second step, of course, is to write a blog entry about it and wait for the answer in the comments.

如果搜索的过程中遇到了问题,将auth-source-debug设置为'trivia,可以在 Messages buffer中看到库正在检查的host port和user信息。同样对于任何其他问题,第一步总是查看在检查什么。第二步,当然,是写一个关于它的博客,在评论中等待答案。

You can customize the variable auth-sources. The following may be needed if you are using an older version of Emacs or if the auth-source library is not loaded for some other reason.

可以定制auto-soources变量。如果使用旧版本的Emacs或者由于某些问题auto-source库没有加载,你可能需要下面的代码:

(require 'auth-source)             ;; probably not necessary
(customize-variable 'auth-sources) ;; optional, do it once

Variable: auth-sources

The auth-sources variable tells the auth-source library where your netrc files or Secret Service API collection items live for a particular host and protocol. While you can get fancy, the default and simplest configuration is:

变量auth-sources告诉auto-source 库netrc文件或者一个特定主机和协议的Secret Service API集合条目。可以想象一下,默认和最简单的配置是这样的:

;;; old default: required :host and :port, not needed anymore
(setq auth-sources '((:source "~/.authinfo.gpg" :host t :port t)))
  ;;; mostly equivalent (see below about fallbacks) but shorter:
(setq auth-sources '((:source "~/.authinfo.gpg")))
  ;;; even shorter and the default:
(setq auth-sources '("~/.authinfo.gpg" "~/.authinfo" "~/.netrc"))
  ;;; use the Secrets API Login collection
  ;;; (see Secret Service API)
(setq auth-sources '("secrets:Login"))

By adding multiple entries to auth-sources with a particular host or protocol, you can have specific netrc files for that host or protocol. Usually this is unnecessary but may make sense if you have shared netrc files or some other unusual setup (90% of Emacs users have unusual setups and the remaining 10% are really unusual).

通过向auth-sources添加主机和协议相关的条目,可以为该主机和协议指定netrc文件。通常没必要这么做,但是如果共享netrc文件或有其他不寻常的设置,这样做可能有意义。(90%的Emacas用户有不寻常的配置,剩下的10%是真的不寻常)。

Here’s a mixed example using two sources:

这是使用两个source的混合例子:

(setq auth-sources '((:source (:secrets default)
							  :host "myserver" :user "joe")
					 "~/.authinfo.gpg"))

If you don’t customize auth-sources, you’ll have to live with the defaults: the unencrypted netrc file ~/.authinfo will be used for any host and any port.

如果不配置auth-sources,就要使用默认配置:没有加密的netrc文件~/.authinfo文件将会用于任何主机和端口。

If that fails, any host and any port are looked up in the netrc file ~/.authinfo.gpg, which is a GnuPG encrypted file (see GnuPG and EasyPG Assistant Configuration).

如果失败了,任何主机和端口就会在~/.authinfo.gpg文件中查看,这是GnuPG加密过的文件。

Finally, the unencrypted netrc file ~/.netrc will be used for any host and any port.

The typical netrc line example is without a port.

这个例子描述了netrc文件中行的典型格式:

machine YOURMACHINE login YOU password YOURPASSWORD

This will match any authentication port. Simple, right? But what if there’s a SMTP server on port 433 of that machine that needs a different password from the IMAP server? 这将会匹配任何验证端口。很简单,对吧?对单如果这台机器433端口开了SMTP服务需要一个和IMAP服务不同的密码怎么办?

machine YOURMACHINE login YOU password SMTPPASSWORD port 433
machine YOURMACHINE login YOU password GENERALPASSWORD

For url-auth authentication (HTTP/HTTPS), you need to put this in your netrc file:

对于url-auth验证来说(HTTP/HTTPS),要在netrc文件中这样写:

machine yourmachine.com:80 port http login testuser password testpass

This will match any realm and authentication method (basic or digest) over HTTP. HTTPS is set up similarly. If you want finer controls, explore the url-auth source code and variables. 这将会匹配基于HTTP的任何领域和认证方法(基本或digest)。HTTPS也是类似的,如果想要更好的控制,探索url-auth的源码和变量。

For Tramp authentication, use:

对于tram验证,使用:

machine yourmachine.com port scp login testuser password testpass

Note that the port denotes the Tramp connection method. When you don’t use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup.

注意port表示Tramp连接方法。如果不指定port字段,会匹配早先介绍的任意的Tramp方法。由于Tramp有大约88中连接方法,如果有不寻常的设置的话这可能是有用的。

3 Secret Service API

The Secret Service API is a standard from freedesktop.org to securely store passwords and other confidential information. This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should be available on most modern GNU/Linux systems).

Secret Service API是来自freedesktop.org的一个标准,用来安全的存储密码或其他机密信息。该API被系统守护进程,入GNOME Keyring或KDE Wallet实现。

The auth-source library uses the secrets.el library to connect through the Secret Service API. You can also use that library in other packages, it’s not exclusive to auth-source.

auth-source 使用secrets.el库来连接这些API。也可以在其他packages中使用该库,它并不是auth-source独有的。

  • Variable: secrets-enabled

After loading secrets.el, a non-nil value of this variable indicates the existence of a daemon providing the Secret Service API.

  • Command: secrets-show-secrets

This command shows all collections, items, and their attributes.

The atomic objects managed by the Secret Service API are secret items, which contain things an application wishes to store securely, like a password. Secret items have a label (a name), the secret (which is the string we want, like a password), and a set of lookup attributes. The attributes can be used to search and retrieve a secret item at a later date.

Secret items are grouped in collections. A collection is sometimes called a ‘keyring’ or ‘wallet’ in GNOME Keyring and KDE Wallet but it’s the same thing, a group of secrets. Collections are personal and protected so only the owner can open them.

The most common collection is called "login".

A collection can have an alias. The alias "default" is commonly used so the clients don’t have to know the specific name of the collection they open. Other aliases are not supported yet. Since aliases are globally accessible, set the "default" alias only when you’re sure it’s appropriate.

Function: secrets-list-collections This function returns all the collection names as a list.

Function: secrets-set-alias collection alias Set alias as alias of collection labeled collection. Currently only the alias "default" is supported.

Function: secrets-get-alias alias Return the collection name alias is referencing to. Currently only the alias "default" is supported.

Collections can be created and deleted by the functions secrets-create-collection and secrets-delete-collection. Usually, this is not done from within Emacs. Do not delete standard collections such as "login".

The special collection "session" exists for the lifetime of the corresponding client session (in our case, Emacs’s lifetime). It is created automatically when Emacs uses the Secret Service interface and it is deleted when Emacs is killed. Therefore, it can be used to store and retrieve secret items temporarily. The "session" collection is better than a persistent collection when the secret items should not live longer than Emacs. The session collection can be specified either by the string "session", or by nil, whenever a collection parameter is needed in the following functions.

Function: secrets-list-items collection Returns all the item labels of collection as a list.

Function: secrets-create-item collection item password &rest attributes This function creates a new item in collection with label item and password password. attributes are key-value pairs set for the created item. The keys are keyword symbols, starting with a colon. Example:

;;; The session "session", the label is "my item" ;;; and the secret (password) is "geheim" (secrets-create-item "session" "my item" "geheim"

:method "sudo" :user "joe" :host "remote-host") Function: secrets-get-secret collection item Return the secret of item labeled item in collection. If there is no such item, return nil.

Function: secrets-delete-item collection item This function deletes item item in collection.

The lookup attributes, which are specified during creation of a secret item, must be a key-value pair. Keys are keyword symbols, starting with a colon; values are strings. They can be retrieved from a given secret item and they can be used for searching of items.

Function: secrets-get-attribute collection item attribute Returns the value of key attribute of item labeled item in collection. If there is no such item, or the item doesn’t own this key, the function returns nil.

Function: secrets-get-attributes collection item Return the lookup attributes of item labeled item in collection. If there is no such item, or the item has no attributes, it returns nil. Example:

(secrets-get-attributes "session" "my item") ⇒ ((:user . "joe") (:host ."remote-host")) Function: secrets-search-items collection &rest attributes Search for the items in collection with matching attributes. The attributes are key-value pairs, as used in secrets-create-item. Example:

(secrets-search-items "session" :user "joe") ⇒ ("my item" "another item") The auth-source library uses the secrets.el library and thus the Secret Service API when you specify a source matching "secrets:COLLECTION". For instance, you could use "secrets:session" to use the "session" collection, open only for the lifetime of Emacs. Or you could use "secrets:Login" to open the "Login" collection. As a special case, you can use the symbol default in auth-sources (not a string, but a symbol) to specify the "default" alias. Here is a contrived example that sets auth-sources to search three collections and then fall back to ~/.authinfo.gpg.

(setq auth-sources '(default "secrets:session" "secrets:Login" "~/.authinfo.gpg")) Next: GnuPG and EasyPG Assistant Configuration, Previous: Secret Service API, Up: Top [Contents][Index]

4 Help for developers

The auth-source library lets you control logging output easily.

Variable: auth-source-debug Set this variable to 'trivia to see lots of output in Messages, or set it to a function that behaves like message to do your own logging.

The auth-source library only has a few functions for external use.

Function: auth-source-search &rest spec &key type max host user port secret require create delete &allow-other-keys This function searches (or modifies) authentication backends according to spec. See the function’s doc-string for details.

Let’s take a look at an example of using auth-source-search from Gnus’s nnimap.el.

(defun nnimap-credentials (address ports) (let* ((auth-source-creation-prompts '((user . "IMAP user at %h: ") (secret . "IMAP password for %u@%h: "))) (found (nth 0 (auth-source-search :max 1

:host address

:port ports

:require '(:user :secret)

:create t)))) (if found (list (plist-get found :user) (let ((secret (plist-get found :secret))) (if (functionp secret) (funcall secret) secret)) (plist-get found :save-function)) nil))) This call requires the user and password (secret) to be in the results. It also requests that an entry be created if it doesn’t exist already. While the created entry is being assembled, the shown prompts will be used to interact with the user. The caller can also pass data in auth-source-creation-defaults to supply defaults for any of the prompts.

Note that the password needs to be evaluated if it’s a function. It’s wrapped in a function to provide some security.

Later, after a successful login, nnimap.el calls the :save-function like so:

(when (functionp (nth 2 credentials)) (funcall (nth 2 credentials))) This will work whether the :save-function was provided or not. :save-function will be provided only when a new entry was created, so this effectively says “after a successful login, save the authentication information we just used, if it was newly created.”

After the first time it’s called, the :save-function will not run again (but it will log something if you have set auth-source-debug to 'trivia). This is so it won’t ask the same question again, which is annoying. This is so it won’t ask the same question again, which is annoying. This is so it won’t ask the same question again, which is annoying.

So the responsibility of the API user that specified :create t is to call the :save-function if it’s provided.

Function: auth-source-delete &rest spec &key delete &allow-other-keys This function deletes entries matching spec from the authentication backends. It returns the entries that were deleted. The backend may not actually delete the entries.

Function: auth-source-forget spec This function forgets any cached data that exactly matches spec. It returns t if it forget some data, and nil if no matching data was found.

Function: auth-source-forget+ &rest spec &allow-other-keys This function forgets any cached data matching spec. It returns the number of items forgotten.

4 Appendix A GnuPG and EasyPG Assistant Configuration

If the auth-sources variable contains ~/.authinfo.gpg before ~/.authinfo, the auth-source library will try to read the GnuPG encrypted .gpg file first, before the unencrypted file.

如果变量auth-source中~/.authifno.gpg在~/.authinfo之前,auth-source会先尝试限度去GnuPG加密的.gpg文件。

In Emacs 23 or later there is an option auto-encryption-mode to automatically decrypt *.gpg files. It is enabled by default. If you are using earlier versions of Emacs, you will need:

Emacs 23 和更高的版本中哟一个选项来auto-encryption-mode来自动解密 *.gpg文件。如果使用的是早期版本的Emacs,需要:

(require 'epa-file)
(epa-file-enable)

If you want your GnuPG passwords to be cached, set up gpg-agent or EasyPG Assistant (see (epa)Caching Passphrases).

如果想要缓存GnuPG密码,设置gpg-agent或者EasyPG Assistant。

To quick start, here are some questions:

为了快速开始,这里有一些问题:

  • Do you use GnuPG version 2 instead of GnuPG version 1?
  • Do you use symmetric encryption rather than public key encryption?
  • Do you want to use gpg-agent?

Here are configurations depending on your answers:

这里是根据答案进行的配置:

Author: lsl

Created: 2017-08-30 三 16:06

Emacs 25.2.2 (Org mode 8.2.10)

Validate