varlink: add new calls for server-side user record filtering to varlink IDL + to...

This is preparation for adding server side filtering to the userdb
logic: it adds some fields for this to the userdb varlink API. This only
adds the IDL for it, no client will use it for now, no server implement
it. That's added in later commits.

diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md
index 15bbfaa0cdbc09f0ad6c8db5b894779b6a7202d5..e0f786ad899bd5fd3281806d10b471d1804dc3c5 100644 (file)
--- a/docs/USER_GROUP_API.md
+++ b/docs/USER_GROUP_API.md
@@ -171,6 +171,10 @@ interface io.systemd.UserDatabase
 method GetUserRecord(
         uid : ?int,
         userName : ?string,
+        fuzzyNames: ?[]string,
+        dispositionMask: ?[]string,
+        uidMin: ?int,
+        uidMax: ?int,
         service : string
 ) -> (
         record : object,
@@ -180,6 +184,10 @@ method GetUserRecord(
 method GetGroupRecord(
         gid : ?int,
         groupName : ?string,
+        fuzzyNames: ?[]string,
+        dispositionMask: ?[]string,
+        gidMin: ?int,
+        gidMax: ?int,
         service : string
 ) -> (
         record : object,
@@ -199,6 +207,7 @@ error NoRecordFound()
 error BadService()
 error ServiceNotAvailable()
 error ConflictingRecordFound()
+error NonMatchingRecordFound()
 error EnumerationNotSupported()
 ```
 
@@ -213,6 +222,40 @@ If neither of the two parameters are set the whole user database is enumerated.
 In this case the method call needs to be made with `more` set, so that multiple method call replies may be generated as
 effect, each carrying one user record.
 
+The `fuzzyNames`, `dispositionMask`, `uidMin`, `uidMax` fields permit
+*additional* filtering of the returned set of user records. The `fuzzyNames`
+parameter shall be one or more strings that shall be searched for in "fuzzy"
+way. What specifically this means is left for the backend to decide, but
+typically this should result in substring or string proximity matching of the
+primary user name, the real name of the record and possibly other fields that
+carry identifying information for the user. The `dispositionMask` field shall
+be one of more user record `disposition` strings. If specified only user
+records matching one of the specified dispositions should be enumerated. The
+`uidMin` and `uidMax` fields specify a minimum and maximum value for the UID of
+returned records. Inline searching for `uid` and `userName` support for
+filtering with these four additional parameters is optional, and clients are
+expected to be able to do client-side filtering in case the parameters are not
+supported by a service. The service should return the usual `InvalidParameter`
+error for the relevant parameter if one is passed and it does not support
+it. If a request is made specifying `uid` or `userName` and a suitable record
+is found, but the specified filter via `fuzzyNames`, `dispositionMask`,
+`uidMin`, or `uidMax` does not match, a `NonMatchingRecordFound` error should
+be returned.
+
+Or to say this differently: the *primary search keys* are
+`userName`/`groupName` and `uid`/`gid` and the *secondary search filters* are
+`fuzzyNames`, `dispositionMask`, `uidMin`, `uidMax`. If no entry matching
+either of the primary search keys are found `NoRecordFound()` is returned. If
+one is found that matches one but not the other primary search key
+`ConflictingRecordFound()` is returned. If an entry is found that matches the
+primary search key, but not the secondary match filters
+`NonMatchingRecordFound()` is returned. Finally, if an entry is found that
+matches both the primary search keys and the secondary search filters, they are
+returned as successful response. Note that both the primary search keys and the
+secondary search filters are optional, it is possible to use both, use one of
+the two, or the other of the two, or neither (the latter for a complete dump of
+the database).
+
 The `service` parameter is mandatory and should be set to the service name
 being talked to (i.e. to the same name as the `AF_UNIX` socket path, with the
 `/run/systemd/userdb/` prefix removed). This is useful to allow implementation

diff --git a/src/shared/varlink-io.systemd.UserDatabase.c b/src/shared/varlink-io.systemd.UserDatabase.c
index 905e2ba68182568423e939e0de6781f9ed8d5797..bdcba2be8a9cfa72f65cb085fcf584d59ef69acc 100644 (file)
--- a/src/shared/varlink-io.systemd.UserDatabase.c
+++ b/src/shared/varlink-io.systemd.UserDatabase.c
@@ -10,6 +10,15 @@ static SD_VARLINK_DEFINE_METHOD_FULL(
                 SD_VARLINK_FIELD_COMMENT("The UNIX user name of the record, if look-up by name is desired."),
                 SD_VARLINK_DEFINE_INPUT(userName, SD_VARLINK_STRING, SD_VARLINK_NULLABLE),
                 SD_VARLINK_FIELD_COMMENT("The userdb provider service to search on. Must be set to the base name of the userdb entrypoint socket. This is necessary in order to support services that implement multiple userdb services on the same socket."),
+                SD_VARLINK_FIELD_COMMENT("Names to search for in a fuzzy fashion."),
+                SD_VARLINK_DEFINE_INPUT(fuzzyNames, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
+                SD_VARLINK_FIELD_COMMENT("User dispositions to limit search by."),
+                SD_VARLINK_DEFINE_INPUT(dispositionMask, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
+                SD_VARLINK_FIELD_COMMENT("Minimum UID to restrict search too."),
+                SD_VARLINK_DEFINE_INPUT(uidMin, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
+                SD_VARLINK_FIELD_COMMENT("Maximum UID to restrict search too."),
+                SD_VARLINK_DEFINE_INPUT(uidMax, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
+                SD_VARLINK_FIELD_COMMENT("The userdb provider to search on. Must be set to the name of the userdb entrypoint socket. This is necessary in order to support services that implement multiple userdb services on the same socket."),
                 SD_VARLINK_DEFINE_INPUT(service, SD_VARLINK_STRING, 0),
                 SD_VARLINK_FIELD_COMMENT("The retrieved user record."),
                 SD_VARLINK_DEFINE_OUTPUT(record, SD_VARLINK_OBJECT, 0),
@@ -24,6 +33,15 @@ static SD_VARLINK_DEFINE_METHOD_FULL(
                 SD_VARLINK_FIELD_COMMENT("The UNIX group name of the record, if look-up by name is desired."),
                 SD_VARLINK_DEFINE_INPUT(groupName, SD_VARLINK_STRING, SD_VARLINK_NULLABLE),
                 SD_VARLINK_FIELD_COMMENT("The userdb provider service to search on. Must be set to the base name of the userdb entrypoint socket. This is necessary in order to support services that implement multiple userdb services on the same socket."),
+                SD_VARLINK_FIELD_COMMENT("Additional names to search for in a fuzzy fashion."),
+                SD_VARLINK_DEFINE_INPUT(fuzzyNames, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
+                SD_VARLINK_FIELD_COMMENT("Group dispositions to limit search by."),
+                SD_VARLINK_DEFINE_INPUT(dispositionMask, SD_VARLINK_STRING, SD_VARLINK_NULLABLE|SD_VARLINK_ARRAY),
+                SD_VARLINK_FIELD_COMMENT("Minimum GID to restrict search too."),
+                SD_VARLINK_DEFINE_INPUT(gidMin, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
+                SD_VARLINK_FIELD_COMMENT("Maximum GID to restrict search too."),
+                SD_VARLINK_DEFINE_INPUT(gidMax, SD_VARLINK_INT, SD_VARLINK_NULLABLE),
+                SD_VARLINK_FIELD_COMMENT("The userdb provider to search on. Must be set to the name of the userdb entrypoint socket. This is necessary in order to support services that implement multiple userdb services on the same socket."),
                 SD_VARLINK_DEFINE_INPUT(service, SD_VARLINK_STRING, 0),
                 SD_VARLINK_FIELD_COMMENT("The retrieved group record."),
                 SD_VARLINK_DEFINE_OUTPUT(record, SD_VARLINK_OBJECT, 0),
@@ -49,6 +67,7 @@ static SD_VARLINK_DEFINE_ERROR(BadService);
 static SD_VARLINK_DEFINE_ERROR(ServiceNotAvailable);
 static SD_VARLINK_DEFINE_ERROR(ConflictingRecordFound);
 static SD_VARLINK_DEFINE_ERROR(EnumerationNotSupported);
+static SD_VARLINK_DEFINE_ERROR(NonMatchingRecordFound);
 
 /* As per https://systemd.io/USER_GROUP_API/ */
 SD_VARLINK_DEFINE_INTERFACE(
@@ -69,5 +88,7 @@ SD_VARLINK_DEFINE_INTERFACE(
                 &vl_error_ServiceNotAvailable,
                 SD_VARLINK_SYMBOL_COMMENT("Error indicating that there's a user record matching either UID/GID or the user/group name, but not both at the same time."),
                 &vl_error_ConflictingRecordFound,
+                SD_VARLINK_SYMBOL_COMMENT("Error indicating that there's a user record matching the primary UID/GID or user/group, but that doesn't match the additional specified matches."),
+                &vl_error_NonMatchingRecordFound,
                 SD_VARLINK_SYMBOL_COMMENT("Error indicating that retrieval of user/group records on this service is only supported if either user/group name or UID/GID are specified, but not if nothing is specified."),
                 &vl_error_EnumerationNotSupported);