| blob | 01d12c2614138d51c353dfcca098d62ef987ad3b |
1 ;;; auth-source.el --- authentication sources for Gnus and Emacs -*- lexical-binding: t -*-
3 ;; Copyright (C) 2008-2017 Free Software Foundation, Inc.
5 ;; Author: Ted Zlatanov <tzz@lifelogs.com>
6 ;; Keywords: news
8 ;; This file is part of GNU Emacs.
10 ;; GNU Emacs is free software: you can redistribute it and/or modify
11 ;; it under the terms of the GNU General Public License as published by
12 ;; the Free Software Foundation, either version 3 of the License, or
13 ;; (at your option) any later version.
15 ;; GNU Emacs is distributed in the hope that it will be useful,
16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 ;; GNU General Public License for more details.
20 ;; You should have received a copy of the GNU General Public License
21 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;; Commentary:
25 ;; This is the auth-source.el package. It lets users tell Gnus how to
26 ;; authenticate in a single place. Simplicity is the goal. Instead
27 ;; of providing 5000 options, we'll stick to simple, easy to
28 ;; understand options.
30 ;; See the auth.info Info documentation for details.
32 ;; TODO:
34 ;; - never decode the backend file unless it's necessary
35 ;; - a more generic way to match backends and search backend contents
36 ;; - absorb netrc.el and simplify it
37 ;; - protect passwords better
38 ;; - allow creating and changing netrc lines (not files) e.g. change a password
40 ;;; Code:
75 "Authentication sources."
79 ;;;###autoload
81 "How many seconds passwords are cached, or nil to disable
82 expiring. Overrides `password-cache-expiry' through a
83 let-binding."
92 ;; The slots below correspond with the `auth-source-search' spec,
93 ;; so a backend with :host set, for instance, would match only
94 ;; searches for that host. Normally they are nil.
98 :type symbol
99 :custom symbol
102 :type string
103 :custom string
106 :initform t
107 :type t
108 :custom string
111 :initform t
112 :type t
113 :custom string
116 :initform t
117 :type t
118 :custom string
121 :initform nil
124 :initform ignore
125 :type function
126 :custom function
129 :initform ignore
130 :type function
131 :custom function
139 "List of authentication protocols and their names"
149 ;; Generate all the protocols in a format Customize can use.
150 ;; TODO: generate on the fly from auth-source-protocols
156 p)))
157 auth-source-protocols))
160 ;; FIXME: AFAICT this is not set (or let-bound) anywhere!
169 "If set, auth-source will respect it for save behavior."
178 ;; TODO: make the default (setq auth-source-netrc-use-gpg-tokens `((,(if (boundp 'epa-file-auto-mode-alist-entry) (car epa-file-auto-mode-alist-entry) "\\.gpg\\'") never) (t gpg)))
179 ;; TODO: or maybe leave as (setq auth-source-netrc-use-gpg-tokens 'never)
182 "Set this to tell auth-source when to create GPG password
183 tokens in netrc files. It's either an alist or `never'.
184 Note that if EPA/EPG is not available, this should NOT be used."
206 "Whether auth-source should cache information with `password-cache'."
212 "Whether auth-source should log debug messages.
214 If the value is nil, debug messages are not logged.
216 If the value is t, debug messages are logged with `message'. In
217 that case, your authentication data will be in the clear (except
218 for passwords).
220 If the value is a function, debug messages are logged by calling
221 that function using the same arguments as `message'."
228 trivia)
233 "List of authentication sources.
234 Each entry is the authentication type with optional properties.
235 Entries are tried in the order in which they appear.
236 See Info node `(auth)Help for users' for details.
239 EPA/EPG set up, the file will be encrypted and decrypted
240 automatically. See Info node `(epa)Encrypting/decrypting gpg files'
241 for details.
244 can get pretty complex."
255 macos-keychain-internet)
258 macos-keychain-generic)
312 "List of recipient keys that `authinfo.gpg' encrypted to.
313 If the value is not a list, symmetric encryption will be used."
331 ;; set logger to either the function in auth-source-debug or 'message
332 ;; note that it will be 'message if auth-source-debug is nil
334 auth-source-debug
336 msg))
339 "Read one of CHOICES by `read-char-choice', or `read-char'.
340 `dropdown-list' support is disabled because it doesn't work reliably.
341 Only one of CHOICES will be returned. The PROMPT is augmented
349 k)
353 k)))
356 "List of auth-source parser functions.
357 Each function takes an entry from `auth-sources' as parameter and
358 returns a backend or nil if the entry is not supported. Add a
359 parser function to this list with `add-hook'. Searching for a
360 backend starts with the first element on the list and stops as
364 "Create an auth-source-backend from an ENTRY in `auth-sources'."
372 ;; none of the parsers worked
381 ;; take just a file name use it as a netrc/plist file
382 ;; matching any user, host, and protocol
386 ;; a file name with parameters
403 ;; Note this function should be last in the parser functions, so we add it first
407 ;; take macos-keychain-{internet,generic}:XYZ and use it as macOS
408 ;; Keychain "XYZ" matching any user, host, and protocol
410 entry))
414 entry))
417 ;; take 'macos-keychain-internet or generic and use it as a Mac OS
418 ;; Keychain collection matching any user, host, and protocol
424 ;; the macOS Keychain
435 'macos-keychain-generic
438 :macos-keychain-generic
446 :source source
447 :type keychain-type
454 ;; take secrets:XYZ and use it as Secrets API collection "XYZ"
455 ;; matching any user, host, and protocol
458 ;; take 'default and use it as a Secrets API default collection
459 ;; matching any user, host, and protocol
463 ;; the Secrets API. We require the package, in order to have a
464 ;; defined value for `secrets-enabled'.
474 ;; the source is either the :secrets key in ENTRY or
475 ;; if that's missing or nil, it's "session"
478 ;; if the source is a symbol, we look for the alias named so,
479 ;; and if that alias is missing, we use "Login"
487 :source source
501 "Fills in the extra auth-source-backend parameters of ENTRY.
502 Using the plist ENTRY, get the :host, :port, and :user search
503 parameters."
505 nil
506 entry))
507 val)
514 backend)
516 ;; (mapcar 'auth-source-backend-parse auth-sources)
519 &key max require create delete
521 "Search or modify authentication backends according to SPEC.
523 This function parses `auth-sources' for matches of the SPEC
524 plist. It can optionally create or update an authentication
525 token if requested. A token is just a standard Emacs property
526 list with a :secret property that can be a function; all the
527 other properties will always hold scalar values.
529 Typically the :secret property, if present, contains a password.
531 Common search keys are :max, :host, :port, and :user. In
532 addition, :create specifies if and how tokens will be created.
533 Finally, :type can specify which backend types you want to check.
535 A string value is always matched literally. A symbol is matched
536 as its string value, literally. All the SPEC values can be
537 single values (symbol or string) or lists thereof (in which case
538 any of the search terms matches).
540 :create t means to create a token if possible.
542 A new token will be created if no matching tokens were found.
543 The new token will have only the keys the backend requires. For
544 the netrc backend, for instance, that's the user, host, and
545 port keys.
547 Here's an example:
553 :create t))
555 which says:
558 `netrc', maximum one result.
560 Create a new entry if you found none. The netrc backend will
561 automatically require host, user, and port. The host will be
562 `mine'. We prompt for the user with default `defaultUser' and
563 for the port without a default. We will not prompt for A, Q,
564 or P. The resulting token will only have keys user, host, and
569 The behavior is like :create t but if the list contains any
570 parameter, that parameter will be required in the resulting
571 token. The value for that parameter will be obtained from the
572 search parameters or from user input. If any queries are needed,
573 the alist `auth-source-creation-defaults' will be checked for the
574 default value. If the user, host, or port are missing, the alist
575 `auth-source-creation-prompts' will be used to look up the
576 prompts IN THAT ORDER (so the `user' prompt will be queried first,
577 then `host', then `port', and finally `secret'). Each prompt string
578 can use %u, %h, and %p to show the user, host, and port.
580 Here's an example:
584 (auth-source-creation-prompts
590 which says:
593 or `twosuch' in backends of type `netrc', maximum one result.
595 Create a new entry if you found none. The netrc backend will
596 automatically require host, user, and port. The host will be
597 `nonesuch' and Q will be `qqqq'. We prompt for the password
598 with the shown prompt. We will not prompt for Q. The resulting
599 token will have keys user, host, port, A, B, and Q. It will not
600 have P with any value, even though P is used in the search to
603 When multiple values are specified in the search parameter, the
604 user is prompted for which one. So :host (X Y Z) would ask the
605 user to choose between X, Y, and Z.
607 This creation can fail if the search was not specific enough to
608 create a new token (it's up to the backend to decide that). You
609 should `catch' the backend-specific error as usual. Some
610 backends (netrc, at least) will prompt the user rather than throw
611 an error.
613 :require (A B C) means that only results that contain those
614 tokens will be returned. Thus for instance requiring :secret
615 will ensure that any results will actually have a :secret
616 property.
618 :delete t means to delete any found entries. nil by default.
619 Use `auth-source-delete' in ELisp code instead of calling
620 `auth-source-search' directly with this parameter.
622 :type (X Y Z) will check only those backend types. `netrc' and
623 `secrets' are the only ones supported right now.
625 :max N means to try to return at most N items (defaults to 1).
626 More than N items may be returned, depending on the search and
627 the backend.
629 When :max is 0 the function will return just t or nil to indicate
630 if any matches were found.
632 :host (X Y Z) means to match only hosts X, Y, or Z according to
633 the match rules above. Defaults to t.
635 :user (X Y Z) means to match only users X, Y, or Z according to
636 the match rules above. Defaults to t.
638 :port (P Q R) means to match only protocols P, Q, or R.
639 Defaults to t.
641 :K (V1 V2 V3) for any other key K will match values V1, V2, or
642 V3 (note the match rules above).
644 The return value is a list with at most :max tokens. Each token
645 is a plist with keys :backend :host :port :user, plus any other
646 keys provided by the backend (notably :secret). But note the
647 exception for :max 0, which see above.
649 The token can hold a :save-function key. If you call that, the
650 user will be prompted to save the data to the backend. You can't
651 request that this should happen right after creation, because
652 `auth-source-search' has no way of knowing if the token is
653 actually useful. So the caller must arrange to call this function.
655 The token's :secret key can hold a function. In that case you
656 must call it to obtain the actual value."
664 ;; note that we may have cached results but found is still nil
665 ;; (there were no results from the search)
667 filtered-backends)
671 "auth-source-search: found %d CACHED results matching %S"
685 ;; ignore invalid slots
695 "auth-source-search: found %d backends matching %S"
698 ;; (debug spec "filtered" filtered-backends)
699 ;; First go through all the backends without :create, so we can
700 ;; query them all.
702 spec
703 ;; to exit early
704 max
705 ;; create is always nil here
706 nil delete
707 require))
710 "auth-source-search: found %d results (max %d) matching %S"
713 ;; If we didn't find anything, then we allow the backend(s) to
714 ;; create the entries.
718 spec
719 ;; to exit early
720 max
721 create delete
722 require))
724 "auth-source-search: CREATED %d results (max %d) matching %S"
727 ;; note we remember the lack of result too, if it's applicable
733 found)))
737 matches)
742 :backend backend
744 ;; note we're overriding whatever the spec
745 ;; has for :max, :require, :create, and :delete
746 :max max
747 :require require
748 :create create
749 :delete delete
750 spec)))
753 "auth-source-search-backend: got %d (max %d) in %s:%s matching %S"
757 spec)
759 matches))
762 "Delete entries from the authentication backends according to SPEC.
763 Calls `auth-source-search' with the :delete property in SPEC set to t.
764 The backend may not actually delete the entries.
766 Returns the deleted entries."
770 "Returns t is VALUE is t or COLLECTION is t or COLLECTION contains VALUE."
774 ;; (debug :collection collection :value value)
783 "Forget all cached auth-source data."
786 ;; when the symbol name starts with auth-source-magic
788 ;; remove that key
793 "Format SPEC entry to put it in the password cache."
797 "Remember FOUND search results for SPEC."
803 "Recall FOUND search results for SPEC."
807 "Check if SPEC is remembered."
812 "Forget any cached data matching SPEC exactly.
814 This is the same SPEC you passed to `auth-source-search'.
815 Returns t or nil for forgotten or not found."
819 "Forget any cached data matching SPEC. Returns forgotten count.
821 This is not a full `auth-source-search' spec but works similarly.
823 cached data that was found with a search for those two hosts,
824 while \(:host t) would find all host entries."
826 sname)
828 ;; when the symbol name matches with auth-source-magic
831 sname)
832 ;; and the spec matches what was stored in the cache
834 ;; remove that key
837 count))
850 "Pick the first secret found from applying SPEC to `auth-source-search'."
856 secret)))
859 "Format PROMPT using %x (for any character x) specifiers in ALIST."
866 prompt nil t)))))
867 prompt)
871 values
877 value))
878 values)))
880 ;;; Backend specific parsing: netrc/authinfo backend
897 ;; (auth-source-netrc-parse :file "~/.authinfo.gpg")
900 "Parse FILE and return a list of all entries in the file.
901 Note that the MAX parameter is used so we can exit the parse early."
903 ;; We got already parsed contents; just return it.
904 file
916 host
920 t))
922 user
927 t))
929 port
933 t))
935 ;; the required list of keys is nil, or
937 ;; every element of require is in n(ormalized)
942 result)
949 "auth-source-netrc-parse: using CACHED file data for %s"
950 file)
953 ;; cache all netrc files (used to be just .gpg files)
954 ;; Store the contents of the file heavily encrypted in memory.
955 ;; (note for the irony-impaired: they are just obfuscated)
957 auth-source-netrc-cache file
963 alist)
969 ;; (see bug#7487) making `epa-file-encrypt-to' local to
970 ;; this buffer lets epa-file skip the key selection query
971 ;; (see the `local-variable-p' check in
972 ;; `epa-file-write-region').
978 ;; ask AFTER we've successfully opened the file
980 file modified))
983 "auth-source-netrc-parse: modified %d lines in %s"
984 modified file)))
989 "Advance to the next interesting position in the current buffer."
990 ;; If we're looking at a comment or are at the end of the line, move forward
998 "Read one thing from the current buffer."
1008 ;; with thanks to org-mode
1012 ;; works also in narrowed buffer, because we start at 1, not point-min
1016 "Parse up to MAX netrc entries, passed by CHECK, from the current buffer."
1019 alist
1023 all))
1024 item item2 all alist default)
1027 ;; We're starting a new machine. Save the old one.
1031 ;; (auth-source-do-trivia
1032 ;; "auth-source-netrc-parse-entries: got entry %S" alist)
1034 alist nil))
1035 ;; In default entries, we don't have a next token.
1036 ;; We store them as ("machine" . t)
1039 ;; Not a default entry. Grab the next item.
1041 ;; Did we get a "machine" value?
1044 "%s: Unexpected `machine' token at line %d"
1045 "auth-source-netrc-parse-entries"
1049 ;; Clean up: if there's an entry left over, use it.
1052 ;; (auth-source-do-trivia
1053 ;; "auth-source-netrc-parse-entries: got2 entry %S" alist)
1054 )
1062 passphrase)
1063 ;; return the saved passphrase, calling a function if needed
1074 t))
1077 passphrase))))
1080 "Pass either the decoded SECRET or the gpg:BASE64DATA version.
1081 FILE is the file from which we obtained this token."
1086 context
1088 file))
1096 cipher)
1099 context
1101 file))
1120 ;; apply key aliases
1127 ;; send back the secret in a function (lexical binding)
1132 ;; it's a GPG token: create a token decoder
1133 ;; which unsets itself once
1138 val
1139 filename)
1144 lexv))))
1147 v))))
1148 ret))
1149 alist))
1152 &key backend require create
1153 type max host user port
1155 "Given a property list SPEC, return search matches from the :backend.
1156 See `auth-source-search' for details on SPEC."
1157 ;; just in case, check that the type is correct (null or same as the backend)
1163 :max max
1164 :require require
1171 ;; if we need to create an entry AND none were found to match
1175 ;; create based on the spec and record the value
1177 ;; if the user did not want to create the entry
1178 ;; in the file, it will be returned
1180 ;; if not, we do the search again without :create
1181 ;; to get the updated data.
1183 ;; the result will be returned, even if the search fails
1186 results))
1191 v))
1193 ;; (auth-source-search :host "nonesuch" :type 'netrc :max 1 :create t)
1194 ;; (auth-source-search :host "nonesuch" :type 'netrc :max 1 :create t :create-extra-keys '((A "default A") (B)))
1197 &key backend host port create
1200 ;; we know (because of an assertion in auth-source-search) that the
1201 ;; :create parameter is either t or a list (which includes nil)
1204 :host host
1209 ;; `valist' is an alist
1210 valist
1211 ;; `artificial' will be returned if no creation is needed
1212 artificial)
1214 ;; only for base required elements (defined as function parameters):
1215 ;; fill in the valist with whatever data we may have from the search
1216 ;; we complete the first value if it's a list and use the value otherwise
1221 ;; all-accepting choice (predicate is t)
1223 ;; just the value otherwise
1228 ;; for extra required elements, see if the spec includes a value for them
1236 ;; for each required element
1239 ;; take the first element if the data is a list
1243 ;; this is the default to be offered
1245 auth-source-creation-defaults r))
1246 ;; the default supplementals are simple:
1247 ;; for the user, try `given-default' and then (user-login-name);
1248 ;; otherwise take `given-default'
1280 prompt
1285 ;; Store the data, prompting for the password if needed.
1288 ;; Special case prompt for passwords.
1289 ;; TODO: make the default (setq auth-source-netrc-use-gpg-tokens `((,(if (boundp 'epa-file-auto-mode-alist-entry) (car epa-file-auto-mode-alist-entry) "\\.gpg\\'") nil) (t gpg)))
1290 ;; TODO: or maybe leave as (setq auth-source-netrc-use-gpg-tokens 'never)
1298 auth-source-netrc-use-gpg-tokens))
1299 item ret)
1306 ;; FIXME: `ret' unused.
1307 ;; Should we return it here?
1308 ))
1311 ;; ask if we don't know what to do (in which case
1312 ;; auth-source-netrc-use-gpg-tokens must be a list)
1315 ;; TODO: save the defcustom now? or ask?
1318 auth-source-netrc-use-gpg-tokens)))
1321 plain))
1327 nil nil default)
1336 data))))
1338 ;; When r is not an empty string...
1341 ;; this function is not strictly necessary but I think it
1342 ;; makes the code clearer -tzz
1344 ;; append the key (the symbol name of r)
1345 ;; and the value in r
1347 ;; prepend a space
1349 ;; remap auth-source tokens to netrc
1358 data)))))
1362 artificial
1363 :save-function
1371 "Save a line ADD in FILE, prompting along the way.
1372 Respects `auth-source-save-behavior'. Uses
1373 `auth-source-netrc-cache' to avoid prompting more than once."
1379 "auth-source-netrc-saver: found previous run for key %s, returning"
1380 key)
1385 ;; (see bug#7487) making `epa-file-encrypt-to' local to
1386 ;; this buffer lets epa-file skip the key selection query
1387 ;; (see the `local-variable-p' check in
1388 ;; `epa-file-write-region').
1393 ;; we want the new data to be found first, so insert at beginning
1396 ;; Ask AFTER we've successfully opened the file.
1400 k)
1413 ;; Why? Doesn't with-output-to-temp-buffer already do
1414 ;; the exact same thing anyway? --Stef
1418 done t))
1419 (?N
1421 done t)
1429 ;; Make sure the info is not saved.
1439 ;; Make the .authinfo file non-world-readable.
1442 "auth-source-netrc-create: wrote 1 new line to %s"
1443 file)
1445 nil))))
1448 ;;; Backend specific parsing: Secrets API backend
1451 "Convert a pattern with lists to a list of string patterns.
1456 only string values for patterns, so this routine returns a list
1457 of patterns that is equivalent to the single original pattern
1458 when interpreted such that if a secret matches any pattern in the
1459 list, it matches the original pattern."
1472 &key backend create delete label max
1474 "Search the Secrets API; spec is like `auth-source'.
1476 The :label key specifies the item's label. It is the only key
1477 that can specify a substring. Any :label value besides a string
1478 will allow any label.
1480 All other search keys must match exactly. If you need substring
1481 matching, do a wider search and narrow it down yourself.
1483 You'll get back all the properties of the token as a plist.
1485 Here's an example that looks for the first item in the `Login'
1486 Secrets collection:
1489 (auth-source-search :max 1)
1491 Here's another that looks for the first item in the `Login'
1492 Secrets collection whose label contains `gnus':
1497 And this one looks for the first item in the `Login' Secrets
1498 collection that's a Google Chrome entry for the git.gnus.org site
1499 authentication tokens:
1503 "
1505 ;; TODO
1508 ;; TODO
1509 ;; (secrets-delete-item coll elt)
1519 ;; build a search spec without the ignored keys
1520 ;; if a search key is nil or t (match anything), we skip it
1526 nil
1528 search-keys))))
1529 ;; needed keys (always including host, login, port, and secret)
1532 search-keys)))
1535 for search-spec in search-specs
1536 nconc
1540 collect item)))
1541 ;; TODO: respect max in `secrets-search-items', not after the fact
1543 ;; convert the item name to a full plist
1546 ;; make an entry for the secret (password) element
1548 :secret
1551 ;; rewrite the entry from ((k1 v1) (k2 v2)) to plist
1556 items))
1557 ;; ensure each item has each key in `returned-keys'
1563 nil
1565 returned-keys))
1566 plist))
1567 items)))
1568 items))
1571 ;; TODO
1572 ;; (apply 'secrets-create-item (auth-get-source entry) name passwd spec)
1575 ;;; Backend specific parsing: Mac OS Keychain (using /usr/bin/security) backend
1578 &key backend create delete type max
1580 "Search the macOS Keychain; spec is like `auth-source'.
1582 All search keys must match exactly. If you need substring
1583 matching, do a wider search and narrow it down yourself.
1585 You'll get back all the properties of the token as a plist.
1587 The :type key is either `macos-keychain-internet' or
1588 `macos-keychain-generic'.
1590 For the internet keychain type, the :label key searches the
1594 \(note PROT has to be a 4-character string).
1596 For the generic keychain type, the :label key searches the item's
1601 Here's an example that looks for the first item in the default
1602 generic macOS Keychain:
1605 (auth-source-search :max 1)
1607 Here's another that looks for the first item in the internet
1608 macOS Keychain collection whose label is `gnus':
1613 And this one looks for the first item in the internet keychain
1614 entries for git.gnus.org:
1618 "
1619 ;; TODO
1622 ;; TODO
1623 ;; (macos-keychain-delete-item coll elt)
1629 ;; Filter out ignored keys from the spec
1631 ;; Build a search spec without the ignored keys
1632 ;; FIXME make this loop a function? it's used in at least 3 places
1636 ;; If a search key value is nil or t (match anything), we skip it
1641 nil
1643 search-keys)))
1644 ;; needed keys (always including host, login, port, and secret)
1647 search-keys)))
1648 ;; Extract host and port from spec
1653 ;; Loop through all combinations of host/port and pass each of these to
1654 ;; auth-source-macos-keychain-search-items
1660 coll
1661 type
1662 max
1663 host port
1664 search-spec)))
1668 ;; ensure each item has each key in `returned-keys'
1674 nil
1676 returned-keys))
1677 plist))
1678 items)))
1679 items))
1694 else
1695 collect var))
1699 &key label type user
1703 "find-generic-password"
1719 port)))))
1731 ret
1732 keychain-generic
1733 "secret"
1737 ;; TODO: check if this is really the label
1738 ;; match 0x00000007 <blob>="AppleID"
1742 ret
1743 keychain-generic
1744 "label"
1746 ;; match "crtr"<uint32>="aapl"
1747 ;; match "svce"<blob>="AppleID"
1751 ret
1752 keychain-generic
1756 ;; return `ret' iff it has the :secret key
1764 ;; for generic keychains, creator is host, service is port
1767 ;; for internet keychains, protocol is port, server is host
1771 result))
1774 ;; TODO
1777 ;;; Backend specific parsing: PLSTORE backend
1780 &key backend create delete max
1782 "Search the PLSTORE; spec is like `auth-source'."
1789 ;; build a search spec without the ignored keys
1790 ;; if a search key is nil or t (match anything), we skip it
1796 nil
1800 search-keys)))
1801 ;; needed keys (always including host, login, port, and secret)
1804 search-keys)))
1808 ;; convert the item to a full plist
1817 plist))
1818 items))
1819 ;; ensure each item has each key in `returned-keys'
1825 nil
1827 returned-keys))
1828 plist))
1829 items)))
1831 ;; if we need to create an entry AND none were found to match
1835 ;; create based on the spec and record the value
1837 ;; if the user did not want to create the entry
1838 ;; in the file, it will be returned
1840 ;; if not, we do the search again without :create
1841 ;; to get the updated data.
1843 ;; the result will be returned, even if the search fails
1847 item-names)
1851 items))
1854 &key backend host port create
1858 ;; we know (because of an assertion in auth-source-search) that the
1859 ;; :create parameter is either t or a list (which includes nil)
1862 :host host
1865 ;; `valist' is an alist
1866 valist
1867 ;; `artificial' will be returned if no creation is needed
1868 artificial
1869 secret-artificial)
1871 ;; only for base required elements (defined as function parameters):
1872 ;; fill in the valist with whatever data we may have from the search
1873 ;; we complete the first value if it's a list and use the value otherwise
1878 ;; all-accepting choice (predicate is t)
1880 ;; just the value otherwise
1885 ;; for extra required elements, see if the spec includes a value for them
1893 ;; for each required element
1896 ;; take the first element if the data is a list
1900 ;; this is the default to be offered
1902 auth-source-creation-defaults r))
1903 ;; the default supplementals are simple:
1904 ;; for the user, try `given-default' and then (user-login-name);
1905 ;; otherwise take `given-default'
1937 prompt
1942 ;; Store the data, prompting for the password if needed.
1952 nil nil default)
1960 data))
1963 data))))))
1969 artificial secret-artificial)
1974 ;;; older API
1976 ;; (auth-source-user-or-password '("login" "password") "imap.myhost.com" t "tzz")
1978 ;; deprecate the old interface
1986 "Find MODE (string or list of strings) matching HOST and PORT.
1988 DEPRECATED in favor of `auth-source-search'!
1991 across the Secret Service API (see secrets.el) if the resulting
1992 items don't have a username. This means that if you search for
1996 A non nil DELETE-EXISTING means deleting any matching password
1997 entry in the respective sources. This is useful only when
1998 CREATE-MISSING is non nil as well; the intended use case is to
1999 remove wrong password entries.
2001 If no matching entry is found, and CREATE-MISSING is non nil,
2002 the password will be retrieved interactively, and it will be
2003 stored in the password database which matches best (see
2004 `auth-sources').
2008 "auth-source-user-or-password: DEPRECATED get %s for %s (%s) + user=%s"
2009 mode host port username)
2013 ;; (cname (if username
2014 ;; (format "%s %s:%s %s" mode host port username)
2015 ;; (format "%s %s:%s" mode host port)))
2020 search))
2023 search))
2024 ;; (found (if (not delete-existing)
2025 ;; (gethash cname auth-source-cache)
2026 ;; (remhash cname auth-source-cache)
2027 ;; nil)))
2032 "auth-source-user-or-password: DEPRECATED cached %s=%s for %s (%s) + %s"
2033 mode
2034 ;; don't show the password
2036 "SECRET"
2037 found)
2038 host port username)
2040 ;; else, if not found, search with a max of 1
2055 found))
2061 :host host
2062 :user user
2067 :host host
2079 ;;; auth-source.el ends here