Authentication Handler
Custom authentication can be implemented by providing servedat with the path to an executable which will be run to determine whether given user credentials should be accepted or denied. The path may be given in the configuration file or on the command line using the AuthHandler option.
Execution
When a username is not matched in an AuthFile and is not cached, the AuthHandler with be run with a limited set of environment variables, including SV_USER and SV_PASSWORD containing the username and password from the client. See Environment below for a full list.
The handler must evaluate the credentials, determine whether to permit their use, and output to stdout either a user record or error message in one of the formats below. The handler may consult whatever resources are required, but it must return an answer quickly. To avoid degrading server performance, the handler should output its answer in less than 50 milliseconds. If authentication is likely to require substantially more time per lookup, consider increasing AuthCache or implementing your own caching mechanism. If the handler does not return a result within AuthHandlerTimeout milliseconds, the credentials will be rejected with code MTP_APP_DENIED (25).
Unlike an ObjectHandler, servedat does not monitor the status of AuthHandler processes or wait for them to exit. Runaway processes will not be killed and their exit codes are ignored. Their only output is through stdout.
Rejection
If the credentials are rejected, the handler must output to stdout one line of text in the following format:
-<Error Code>[:Optional Text]
The error code is a value from the MTP Application error class. At this time, only two codes are recognized:
| Value | Name | Description |
|---|---|---|
| -10 | MTP_APP_BADCRED | The credentials are invalid |
| -15 | MTP_APP_REDIR | Pass the credentials to SysAuth, if it is enabled. |
All other responses starting with "-" will be interpreted as "-10". The Optional Text, if given, will be logged in as a comment in the server log file.
For example:
-10:User token has expired
Acceptance
If the credentials are accepted, the handler must output to stdout one line of text in the following format:
::<UID>:<GID>:<Home Directory>:[Options]
These fields have the same meaning as for AuthFile, except that the first two must be empty as they are redundant with SV_USER and SV_PASSWORD and may be used for some other purpose in the future.
For example:
::99:99:/mnt/storage/folder:ReadOnly
Or for Windows:
::::E:\folder:ReadOnly
To minimize calls to the AuthHandler during rapid transaction processing, accepted credentials will be cached for AuthCache seconds.
Environment
The handler program is launched directly, without shell interpretation. It should expect no command line options or shell environment variables. The only communication with servedat is from the servedat environment variables described below, and stdout. The program will be launched with the system privileges associated with the servedat process.
Some command line utilities depend on the existence of HOME or PATH environment variables. The AuthHandler must create these variables if they are needed.
Windows based handlers must pay special attention to the formatting of text and paths. All environment variables are Unicode and all paths are forward-slash delimited. When using a command shell as an AuthHandler, set its code page to UTF-8 with the command "chcp 65001".
The following environment variables are provided:
| Name | Value |
| Credentials | These values should be the primary consideration for authentication. |
| SV_USER | <Username> |
| The username given by the client and to be authenticated by the AuthHandler. It may be up to 63 UTF-8 bytes. | |
| SV_PASSWORD | <Password> |
| The password given by the client and to be authenticated by the AuthHandler. It may be up to 63 UTF-8 bytes for standard ExpeDat and SyncDat clients, or up to 95 bytes for custom ExpeDat Client SDK clients. | |
| Defaults | Server-wide defaults which you may override on acceptance. |
| SV_GETONLY | 0 or 1 |
| Indicates the whether the global GetOnly restriction is enabled. You may use the Options field to override this on acceptance. | |
| SV_HOME | <Pathname> |
| The default home directory for the server which you may override using the Home Directory field on acceptance. | |
| SV_NOOVERWRITE | 0 or 1 |
| Indicates the whether the global NoOverwrite restriction is enabled. You may use the Options field to override this on acceptance. | |
| SV_READONLY | 0 or 1 |
| Indicates the whether the global ReadOnly restriction is enabled. You may use the Options field to override this on acceptance. | |
| SV_RESTRICTHOME | 0 or 1 |
| Indicates the whether the global RestrictHome restriction is enabled. You may use the Options field to override this on acceptance. | |
| SV_WRITEONLY | 0 or 1 |
| Indicates the whether the global WriteOnly restriction is enabled. You may use the Options field to override this on acceptance. | |
| SV_WRITELISTONLY | 0 or 1 |
| Indicates the whether the global WriteListOnly restriction is enabled. You may use the Options field to override this on acceptance. | |
| Environment | Information about the state of the server. |
| SV_DOCID | <Hexadecimal> |
| An 8 character hexadecimal number which uniquely identifies the transaction triggering this request. It corresponds to the "DocID" field in the log file. This should be included in any warning, error, or diagnostic logs produced by the AuthHandler. | |
| SV_LOGPREFIX | DocID SEND|GET Client User Encrypt "Path" "Action" |
| A pre-formatted log line using the same format as that of I and F log file records. This may be used to in warning, error, or diagnostic logs produced by the AuthHandler. | |
| SV_SERVEDAT | servedat - 1.20.1 February 2022 - DEI, DOC-2.3.7 MTP-osx-4.4.1 3969 |
| The server's identification string. See Tech Note 0001 for more information about interpreting identification strings. | |
| SV_SERVERLOAD | 0 to Capacity |
| The number of simultaneous transactions currently being served, including this one. | |
| SV_SERVERCAP | <Integer> |
| The maximum number of simultaneous transactions supportable by this server. | |
| SV_TIMEOUT | <Milliseconds> |
| The maximum number of milliseconds the AuthHandler will be permitted to run. | |
| Transaction | Information about the transaction triggering this authentication request. Because accepted credentials will be cached, this information may change without further calls to the AuthHandler and should be used with caution if at all. |
| SV_ACTION | <Action> |
| The action or object handler code associated with this transaction. | |
| SV_ARG | <String> |
| An additional string provided by the client. For move/rename actions, it provides the destination path. For mkdir and touch actions it provides file meta-data. For all other actions, standard clients will leave SV_ARG empty and the ExpeDat Client SDK may specify a custom string. | |
| SV_CLIENTIP | <IP Address> |
| The client IP address, as seen by the server. If the client is behind an NAT gateway, this may be a public address of that gateway. | |
| SV_CLIENTPORT | 1 to 65535 |
| The UDP port of the client, as seen by the server. If the client is behind an NAT gateway, this may be a public port of that gateway. | |
| SV_ENCRYPT | [AES] |
| If non-empty, this variable indicates that content encryption is being used with the named type. Currently, only AES is supported. | |
| SV_FEATURES | <String> |
| If non-empty, this variable contains a comma separated list of transaction feature codes requested by the client. | |
| SV_PATHRAW | <Target String> |
| The raw target string as given by the client. Depending on whether the filesystem or an object handler is being used, this string may represent arbitrary data. | |
| SV_TYPE | GET or SEND |
| The type of transaction. GET includes both downloads and file maintenance operations. SEND indicates an upload. |
Additional environment variables may be introduced in future releases.