Synopsis

LONG secAccess_Control(
         ULONG contextflags,
         APTR context,
         struct secExtOwner * task,
         ULONG objectowner,
         LONG objectprot,
         LONG access_type );

Function

Filesystem API: decide whether a task may access an object.

Inputs

contextflags - secAC_IGNORE_CONTEXT or secAC_FILESYSTEM_CONTEXT.
context      - the filesystem's MsgPort for secAC_FILESYSTEM_CONTEXT.
task         - the requesting task's owner (see secGetPktOwner()),
               NULL for nobody.
objectowner  - owner of the object (uid<<16 | gid).
objectprot   - protection bits of the object.
access_type  - secAt_#? flags.

Result

secAC_PERMISSION_GRANTED, or secAC_PERMISSION_DENIED with secAC_#?
detail flags.

Synopsis

BOOL secAddMonitor(
         struct secMonitor * monitor );

Function

Add a monitor: a task interested in login/passwd/owner-change
events. Root only. The structure must stay valid until
secRemMonitor().

Result

success

Synopsis

struct secGroupInfo * secAllocGroupInfo();

Function

Allocate a Group Information Structure. Free it with secFreeGroupInfo().

Synopsis

struct secUserInfo * secAllocUserInfo();

Function

Allocate a User Information Structure. Free it with secFreeUserInfo().

Result

info - the structure, or NULL.

Synopsis

BOOL secAuthControlA(
         struct TagItem * taglist );

BOOL secAuthControl(
         TAG tag, ... );

Function

List or clear the failure records of the authentication process:
the hold-back per user name after failed logins, and the lock-out
of a user from a remote host. Only for root.

Tags

secT_AuthList     - (struct secAuthRecord *) array to fill.
secT_AuthListSize - (ULONG) entries in that array.
secT_AuthCount    - (ULONG *) receives the number of records, which
                    may be larger than the array.
secT_AuthClear    - (BOOL) clear instead of listing: the records of
                    secT_UserID and/or secT_RemoteHost, or all of
                    them when neither is given.
secT_UserID       - (STRPTR) see secT_AuthClear.
secT_RemoteHost   - (STRPTR) see secT_AuthClear.
secT_LockAccount  - (STRPTR) lock this user's account: no password
                    matches it any more (the stored hash is kept,
                    marked with '!'). Nothing else is done.
secT_UnlockAccount - (STRPTR) unlock it again.

Result

TRUE on success; FALSE if the caller is not root or the
authentication process does not run.

Notes

Hold-back records are kept per hashed user name: the name shown is
the last one that failed in that slot.

See also

secVerifyUserA() C:Lockouts

Synopsis

BOOL secCheckPasswdA(
         struct TagItem * taglist );

BOOL secCheckPasswd(
         TAG tag, ... );

Function

Check the password of the owner of the calling task; asks for it
unless secT_Password is given.

Tags

secT_Input, secT_Output, secT_Graphical, secT_PubScrName - as for
secLoginA(). secT_Password - (STRPTR) the password to check.

Result

valid - TRUE if the password is correct.

Synopsis

APTR secContextLocate(
         secPluginModule * module,
         ULONG id,
         struct Task * caller,
         ULONG size );

Function

Plugin API: locate (or allocate) the context memory of size 'size'
that a module keeps for a caller under the given id. The memory is
freed automatically when the caller closes the library or exits.

Result

The context memory, or NULL.

Synopsis

LONG secEnumChildren(
         struct Task * parent,
         struct Task ** children,
         LONG size );

Function

Enumerate the children of a task.

Inputs

parent   - the task, NULL for the current one.
children - array to fill (may be NULL to query the count).
size     - number of entries in the array.

Result

The number of children, negative if the array was too small (the
absolute value is the required size).

Synopsis

BOOL secExpandPathA(
         CONST_STRPTR template,
         STRPTR buffer,
         struct TagItem * taglist );

BOOL secExpandPath(
         CONST_STRPTR template,
         STRPTR buffer,
         TAG tag, ... );

Function

Expand the user tokens of a path for the owner of a task: the
per-user assigns of dos.library ("Assign T: RAM:T/%u USER") are
resolved with it, each time and in the task that uses them.

  %u  the user ID ("root" for the super user, "nobody" for a task
      that no user owns)
  %h  the user's home directory
  %g  the ID of the user's primary group
  %%  a '%'

Inputs

template - the path with tokens
buffer   - receives the expanded path
taglist  - secT_Task (struct Task *): the task whose owner counts
           (default: the caller);
           secT_BufferSize (ULONG): the size of buffer (required)

Result

TRUE if the path was expanded. FALSE with IoErr() set otherwise:
ERROR_NOT_IMPLEMENTED on a system that is not multi-user (the
template is not expanded there), ERROR_BAD_TEMPLATE for an unknown
token, ERROR_OBJECT_NOT_FOUND when the user has no home directory
or group, ERROR_LINE_TOO_LONG.

See also

dos.library/GetDeviceProc() C:Assign

Synopsis

void secFreeExtOwner(
         struct secExtOwner * owner );

Function

Free an extended owner structure returned by secGetTaskExtOwner(),
secGetPktOwner() or secUserInfo2ExtOwner(). NULL is allowed.

Synopsis

void secFreeGroupInfo(
         struct secGroupInfo * info );

Function

Free a structure allocated with secAllocGroupInfo().

Synopsis

void secFreeUserInfo(
         struct secUserInfo * info );

Function

Free a structure allocated with secAllocUserInfo().

Synopsis

BOOL secFreeze(
         struct Task * task );

Function

Freeze (suspend) a task. Root only.

Result

success. Fails on SMP systems (not supported yet).

Synopsis

BOOL secFSRendezVous();

Function

Called by a multi-user aware filesystem when it comes up, so that the
library rescans the volumes and key files.

Result

TRUE if the server is running.

Synopsis

BPTR secGetConfigDirLock();

Function

Get a shared lock on the configuration directory.

Result

lock, or BNULL. UnLock() it when done.

Synopsis

ULONG secGetDefProtection(
         struct Task * task );

Function

Get the default protection bits of a task.

Inputs

task - the task, NULL for the current one.

Synopsis

UWORD secgetgid();

Function

POSIX: the real group id of the calling task.

Synopsis

struct secGroupInfo * secGetGroupInfo(
         struct secGroupInfo * info,
         ULONG keytype );

Function

Fill in a Group Information Structure according to the key.

Result

info, or NULL if no (more) group matches.

Synopsis

BPTR secGetPasswdDirLock();

Function

Get a shared lock on the directory holding the password file.

Result

lock, or BNULL. UnLock() it when done.

Synopsis

int secgetpgid(
         int pid );

Function

POSIX: the session id of a process (0 = the calling one).

Result

The session id, 0 if not in a session, -1 for an unknown pid.

Synopsis

LONG secGetPktDefProtection(
         struct DosPacket * pkt );

Function

Filesystem API: get the default protection bits of the task that
sent a packet, to be used for newly created objects.

Synopsis

struct secExtOwner * secGetPktOwner(
         struct DosPacket * pkt );

Function

Filesystem API: get the owner of the task that sent a packet. Must
be called before the packet is replied.

Result

owner - free with secFreeExtOwner(). NULL for nobody.

Synopsis

ULONG secGetRelationshipA(
         struct secExtOwner * user,
         ULONG owner,
         struct TagItem * taglist );

ULONG secGetRelationship(
         struct secExtOwner * user,
         ULONG owner,
         TAG tag, ... );

Function

Determine the relationship between a user and the owner of an
object.

Inputs

user    - the user (NULL = nobody).
owner   - the object's owner (uid<<16 | gid).
taglist - reserved, pass NULL.

Result

secRelF_#? flags.

Synopsis

struct secExtOwner * secGetTaskExtOwner(
         struct Task * task );

Function

Get the extended owner (uid, gid and secondary groups) of a task.

Inputs

task - the task, NULL for the current one.

Result

owner - free with secFreeExtOwner(). NULL if owned by nobody.

Synopsis

ULONG secGetTaskOwner(
         struct Task * task );

Function

Get the owner of a task.

Inputs

task - the task, NULL for the current one.

Result

owner - uid<<16 | gid, secOWNER_NOBODY if the task is owned by nobody.

Synopsis

UWORD secgetuid();

Function

POSIX: the real user id of the calling task.

Synopsis

struct secUserInfo * secGetUserInfo(
         struct secUserInfo * info,
         ULONG keytype );

Function

Fill in a User Information Structure according to the key. Repeated
calls with secKeyType_Next (and the #?Next keys) iterate.

Inputs

info    - structure allocated with secAllocUserInfo(), the key field
          filled in.
keytype - secKeyType_#?, see <libraries/security.h>.

Result

info, or NULL if no (more) user matches.

Synopsis

BOOL secIsConfigured();

Function

Is the system configured for multi-user operation, i.e. has a
password file been found and parsed? On an unconfigured system
every task is treated as privileged and no access checks are made.

Result

TRUE if configured and no security violation was detected.

Synopsis

BOOL secIsVolumeSecured(
         CONST_STRPTR volname,
         ULONG dostype );

Function

Filesystem API: should the handler of this volume enforce
ownership? TRUE for multi-user dostypes (muF#?, muAF, muPF) and for
volumes that carry a valid key file (secKey_FileName) in their root
directory, which is how a filesystem without a multi-user dostype
(e.g. SFS) is marked as multi-user. The server (re)scans volumes at
startup and whenever secFSRendezVous() is called, so a handler should
call secFSRendezVous() when a volume comes online and ask again.

Inputs

volname - the volume or device name, with or without ':' (may be NULL)
dostype - the volume's dostype

Result

TRUE if the handler should enforce. Note that enforcement only
makes sense while secIsConfigured() is TRUE as well.

Synopsis

ULONG secKeyAdminA(
         struct TagItem * taglist );

ULONG secKeyAdmin(
         TAG tag, ... );

Function

Register, list or remove a user's hardware authentication tokens
("security keys"). A user with tokens must present one at every
login besides the password: a secKEY_OTP token types a one-time
code directly after the password, and the login takes it apart.
Which codes a token makes is the business of its scheme's plugin
(ID_PLUGIN_HWAUTH); the library keeps the records and refuses a
code that does not advance the token's counter.

root may change anybody's tokens. Users may list their own, and
add or remove them with a fresh ticket of their own
(secVerifyUserA() with secT_Ticket): the password is asked for
again that way.

Tags

secT_KAOperation  - (ULONG) secKA_ADD, secKA_LIST or secKA_REMOVE.
                    Required.
secT_UserID       - (STRPTR) the account. Required.
secT_Ticket       - (struct secLoginTicket *) a ticket for that
                    user, from secVerifyUserA(); used up here.
                    Required for ADD and REMOVE unless root.
secT_KeyLabel     - (STRPTR) the token's name, 1-31 characters,
                    no spaces; unique per user. ADD, REMOVE.
secT_KeyType      - (ULONG) ADD: secKEY_#?.
secT_KeyScheme    - (STRPTR) ADD: the scheme, as its plugin names
                    it ("yubico" for Yubico OTP).
secT_KeyPublicID  - (STRPTR) ADD: the id the token presents with
                    every code (for Yubico OTP the modhex public
                    id it types first).
secT_KeySecret    - (STRPTR) ADD: the token's secret, hex digits,
                    up to secKEYSECRETMAX bytes; the layout is the
                    scheme's (yubico: the AES-128 key followed by
                    the 6-byte private id, 44 digits).
secT_KeyEnrol     - (BOOL) ADD, secKEY_CHALLENGE: enrol the token
                    that is plugged in instead of giving
                    secT_KeyPublicID and secT_KeySecret: the scheme
                    plugin talks to it (a touch) and returns them.
                    secT_StatusHook and secT_KeyTimeout as for
                    secKeyClientA().
secT_KeyList      - (struct secKeyInfo *) LIST: array to fill.
secT_KeyListSize  - (ULONG) LIST: entries in that array.
secT_KeyCount     - (ULONG *) LIST: receives the number of tokens,
                    which may exceed the array.

Result

secKAERR_OK, or a secKAERR_#? code.

Notes

A scheme's plugin must be loaded (Security.config: LOADPLUGIN
yubikey for "yubico"). Without it nothing of that scheme can be
registered (secKAERR_UNAVAILABLE), and a user who has such a
token cannot log in.

See also

secVerifyUserA() secQueryUserA() C:AuthKey

Synopsis

ULONG secKeyClientA(
         struct TagItem * taglist );

ULONG secKeyClient(
         TAG tag, ... );

Function

Talk to a hardware token of the challenge kind (secKEY_CHALLENGE)
that is plugged in: have it answer a challenge, or enrol it. The
token's scheme plugin does the talking, in the caller's context;
this call waits for a token to be present and touched, telling a
hook what to show meanwhile.

secKC_ASSERT: the user's tokens (secT_KeyList, as secVerifyUserA()
returned them with secVERIFY_KEYNEEDED) are offered the challenge;
the answer of the first token that holds one of them is returned,
to be given to secVerifyUserA() with the ticket.

secKC_ENROL: a present token of secT_KeyScheme is enrolled; the id
and key material it returns are what secKeyAdminA(secKA_ADD) takes
(secKeyAdminA() does this itself with secT_KeyEnrol).

Tags

secT_KCOperation    - (ULONG) secKC_ASSERT or secKC_ENROL. Required.
secT_StatusHook     - (struct Hook *) called with a struct
                      secKeyStatus * (object) while waiting: what to
                      tell the user; returns FALSE to give up.
secT_KeyTimeout     - (ULONG) seconds to wait [KEYTIMEOUT].

secKC_ASSERT:
secT_KeyList        - (struct secKeyInfo *) the tokens. Required.
secT_KeyListSize    - (ULONG) how many. Required.
secT_KeyChallenge   - (UBYTE *) secKEYCHALLENGESIZE bytes. Required.
secT_KeyAssertion   - (UBYTE *) receives the answer. Required.
secT_KeyAssertionSize - (ULONG *) the buffer's size, then the
                      answer's. Required.
secT_KeyIndex       - (ULONG *) receives the index in secT_KeyList
                      of the token that answered.

secKC_ENROL:
secT_KeyScheme      - (STRPTR) the scheme. Required.
secT_KeyPublicID    - (STRPTR) receives the id (secKEYPUBIDSIZE).
                      Required.
secT_KeySecret      - (STRPTR) receives the key material as hex
                      digits (2 * secKEYSECRETMAX + 1). Required.

Result

secKCERR_OK, or a secKCERR_#? code.

See also

secVerifyUserA() secKeyAdminA()

Synopsis

BOOL secKill(
         struct Task * task );

Function

Kill a task. Root only. Processes are asked to quit with
SIGBREAKF_CTRL_C; plain tasks are removed with RemTask().

Result

success

Synopsis

BOOL secLimitDOSSetProtection(
         BOOL flag );

Function

Limit dos.library/SetProtection() to changing only the protection
bits for the owner of a file; the GROUP and OTHER bits can then only
be changed via secSetProtection(). Root only.

Inputs

flag - TRUE to turn limiting on.

Result

success

Synopsis

LONG secLimitProtection(
         CONST_STRPTR name,
         LONG protect );

Function

Used by dos.library/SetProtection(): apply the LIMITDOSSETPROTECTION
policy. If limiting is on and the caller is neither root nor inside
secSetProtection(), the GROUP and OTHER bits of the existing object
are preserved.

Inputs

name    - the object SetProtection() is about to change.
protect - the requested protection bits.

Result

The protection bits to apply.

Synopsis

BOOL secLoadPlugin(
         CONST_STRPTR name );

Function

Load and initialise a plugin from the configuration directory.
Root only.

Inputs

name - the plugin name without the .secplugin suffix.

Synopsis

struct secPointers * secLocksecBase();

Function

Lock the library's internal lists for inspection by privileged
tools. Root only. Release with secUnlocksecBase() as soon as
possible.

Result

pointers to the lists, or NULL.

Synopsis

ULONG secLoginA(
         struct TagItem * taglist );

ULONG secLogin(
         TAG tag, ... );

Function

Login to the system and remember the previous user of the task.

Tags

secT_Graphical  - (BOOL) use a graphical login instead of a console
                  one. Default FALSE.
secT_Input      - (BPTR) filehandle to read from. Default Input().
secT_Output     - (BPTR) filehandle to write to. Default Output().
secT_PubScrName - (STRPTR) public screen for the requester.
secT_Task       - (struct Task *) the task to login. Only your own
                  tasks or tasks owned by nobody, unless you are root.
                  Default: the current task.
secT_Own        - (BOOL) make the task owned by the caller's owner.
secT_Global     - (BOOL) also login all descendants of the task.
secT_UserID     - (STRPTR) do not ask for a UserID.
secT_Password   - (STRPTR) do not ask for a password (needs secT_UserID).
secT_NoLog      - (BOOL) do not log this action (root only).
secT_Ticket     - (struct secLoginTicket *) a ticket from
                  secVerifyUserA() for this task: log in the
                  user it was issued for, without prompting.

Result

The user that logged in (uid<<16 | gid), or secOWNER_NOBODY for a
failure.

Notes

On an unconfigured system (no password file) any login succeeds as
root, so that Security-Startup scripts work before the system is set
up.

See also

secLogoutA()

Synopsis

ULONG secLogoutA(
         struct TagItem * taglist );

ULONG secLogout(
         TAG tag, ... );

Function

Logout and restore the previous user. If there was no previous user
or the previous user was nobody, a login request will appear (unless
secT_Quiet). A login from this request also sets the local variable
"Home", the current directory, shows the last login information and
executes the .profile from the configuration directory.

Inputs

taglist - see secLoginA(); additionally
    secT_Quiet - (BOOL) never request a login, simply logout.
    secT_All   - (BOOL) logout all previous users.

Result

The user you are now (uid<<16 | gid), secOWNER_NOBODY for nobody.

See also

secLoginA()

Synopsis

BOOL secPasswd(
         STRPTR oldpwd,
         STRPTR newpwd );

Function

Change the password of the owner of the calling task.

Inputs

oldpwd - the old password.
newpwd - the new password.

Result

success - TRUE if the password was changed.

Synopsis

void secPluginOperationComplete(
         APTR context,
         ULONG result );

Function

Plugin API: complete an operation that returned secpiASYNC.

Inputs

context - the server packet handed to the plugin.
result  - the secpi#? result.

Synopsis

BOOL secQueryUserA(
         struct TagItem * taglist );

BOOL secQueryUser(
         TAG tag, ... );

Function

Answer questions about a user's account that secGetUserInfo() does
not: whether a password is set, and whether the user may change it.

Tags

secT_UserID            - (STRPTR) the user. Required.
secT_HasPassword       - (BOOL *) set to TRUE if a password is set.
secT_MayChangePassword - (BOOL *) set to TRUE if secPasswd() would
                         be allowed for this user (PASSWDUIDLEVEL /
                         PASSWDGIDLEVEL in Security.config).
secT_AccountLocked     - (BOOL *) set to TRUE if the account is
                         locked (secAuthControlA(), Passwd LOCK).
secT_HasKeys           - (BOOL *) set to TRUE if security keys are
                         registered for the user (secKeyAdminA()):
                         a code from one is typed after the
                         password then.

Result

TRUE if the user exists, FALSE otherwise (or on an unconfigured
system).

See also

secGetUserInfo() secVerifyUserA() secPasswd()

Synopsis

ULONG secRegisterHandler(
         struct plugin_ops * ops );

Function

Plugin API: register an operation table with the subsystem named
by its HandlerType.

Result

secpiTRUE on success.

Synopsis

BOOL secRegisterSegment(
         BPTR seglist,
         BPTR fh );

Function

Called by dos.library after loading an executable. If the file has
the secFIBF_SET_UID bit set and a real owner, the seglist is
remembered as a setuid executable.

Inputs

seglist - the loaded segment list
fh      - the file it was loaded from (still open)

Result

TRUE if the segment was registered as setuid.

Synopsis

void secRemMonitor(
         struct secMonitor * monitor );

Function

Remove a monitor added with secAddMonitor().

Synopsis

BOOL secSetDefProtectionA(
         struct TagItem * taglist );

BOOL secSetDefProtection(
         TAG tag, ... );

Function

Set the default protection bits ('umask') used for new files.

Tags

secT_Task          - (struct Task *) the task, default the current one.
secT_DefProtection - (ULONG) the protection bits, default
                     FIBF_OTR_READ|FIBF_GRP_READ.
secT_Global        - (BOOL) also change all descendants of the task.

Result

success

Synopsis

int secsetegid(
         UWORD gid );

Function

POSIX: set the effective group id.

Synopsis

int secseteuid(
         UWORD uid );

Function

POSIX: set the effective user id.

Synopsis

int secsetgid(
         UWORD gid );

Function

POSIX: set the group id (see secsetuid()).

Synopsis

BOOL secSetProtection(
         CONST_STRPTR name,
         LONG mask );

Function

Change the protection bits of a file or directory, including the
GROUP and OTHER bits, regardless of secLimitDOSSetProtection().

Inputs

name - the file or directory.
mask - the new protection bits.

Result

success

Synopsis

int secsetreuid(
         int ruid,
         int euid );

Function

POSIX: set the real and effective user ids. -1 leaves an id
unchanged.

Synopsis

BOOL secSetTaskOwnerFromSegment(
         struct Task * task,
         BPTR seglist );

Function

Called by dos.library's CreateNewProc() (under Forbid(), before the
new process runs) when the process is created from a seglist. If
the seglist is a setuid executable the new process gets the owner
of the executable.

Result

TRUE if the owner was changed.

Synopsis

int secsetuid(
         UWORD uid );

Function

POSIX: set the user id. Root may set any id (real, effective and
saved); others may only switch between their real and saved ids.

Result

0 on success, -1 on failure.

Synopsis

APTR secSetUIDBegin(
         BPTR seglist );

Function

Called by dos.library's RunCommand() before running a seglist. If
the seglist is a setuid executable the calling task's effective
owner is switched to the owner of the executable.

Result

A cookie to pass to secSetUIDEnd() when the command returns, or
NULL if nothing was changed.

Synopsis

void secSetUIDEnd(
         APTR cookie );

Function

Restore the credentials saved by secSetUIDBegin().

Synopsis

BOOL secUnfreeze(
         struct Task * task );

Function

Unfreeze a task frozen with secFreeze(). Root only.

Result

success

Synopsis

BOOL secUnloadPlugin(
         CONST_STRPTR name );

Function

Unload a plugin loaded with secLoadPlugin(). Root only.

Synopsis

void secUnlocksecBase(
         struct secPointers * secP );

Function

Release the lists locked with secLocksecBase().

Synopsis

void secUnRegisterHandler(
         struct plugin_ops * ops );

Function

Plugin API: unregister an operation table.

Synopsis

void secUnregisterSegment(
         BPTR seglist );

Function

Called by dos.library before a seglist is unloaded.

Synopsis

ULONG secUserAdminA(
         struct TagItem * taglist );

ULONG secUserAdmin(
         TAG tag, ... );

Function

Add, change or remove a user account or a group, set an account's
password, or set the members of a group. Only root may do this.
The password and group files are rewritten by the library (a new
file, renamed into place once complete; nothing changes if that
fails).

Tags

secT_UAOperation - (ULONG) secUA_ADD, secUA_MODIFY, secUA_DELETE,
                   secUA_PASSWORD, secUA_GROUPADD,
                   secUA_GROUPMODIFY or secUA_GROUPDELETE.
                   Required.
secT_UserID      - (STRPTR) the account; for secUA_ADD the new user
                   ID. Required for the account operations.
secT_NewUserID   - (STRPTR) secUA_MODIFY: rename the account. An
                   account with a password must be given a new one
                   (secT_Password) when renamed, as the stored hash
                   depends on the user ID.
secT_UID         - (ULONG) user number, 1..65535, unique.
                   Required for secUA_ADD.
secT_GID         - (ULONG) primary group number; the group must
                   exist. Required for secUA_ADD.
secT_UserName    - (STRPTR) full name.
secT_HomeDir     - (STRPTR) home directory.
secT_Shell       - (STRPTR) shell.
secT_Password    - (STRPTR) secUA_ADD, secUA_PASSWORD (and a
                   rename): the clear-text password; "" for none.
                   secUA_PASSWORD also unlocks a locked account.

For secUA_MODIFY only the fields given are changed. Fields may not
contain '|' or control characters; user IDs neither ':' nor spaces.

Groups:

secT_GroupID     - (STRPTR) the group; for secUA_GROUPADD the new
                   group ID. Required for the group operations.
secT_NewGroupID  - (STRPTR) secUA_GROUPMODIFY: rename the group.
secT_GID         - (ULONG) group number, 0..65535, unique.
                   Required for secUA_GROUPADD. A group that is a
                   user's primary group keeps its number.
secT_GroupName   - (STRPTR) description.
secT_GroupMgr    - (ULONG) uid of the manager; root by default.
secT_GroupMembers - (STRPTR *) NULL-terminated array of user IDs:
                   the members of the group besides the users
                   whose primary group it is. Replaces the list;
                   every user must exist.

For secUA_GROUPMODIFY only the fields given are changed. Group IDs
may not contain ':' or spaces either.

Result

secUAERR_OK, or a secUAERR_#? code.

Notes

root cannot be deleted, renamed or given another uid; root's group
cannot be deleted, renamed or renumbered. A group that is the
primary group of a user cannot be deleted (secUAERR_INUSE).

See also

secAuthControlA() secGetUserInfo() SYS:System/Accounts

Synopsis

struct secExtOwner * secUserInfo2ExtOwner(
         struct secUserInfo * info );

Function

Convert a User Information Structure to an extended owner.

Result

owner - free with secFreeExtOwner().

Synopsis

ULONG secVerifyUserA(
         struct TagItem * taglist );

ULONG secVerifyUser(
         TAG tag, ... );

Function

Check whether a token (normally a password) is the right one for a
user, without logging anybody in. This is the operation a service
uses to authenticate somebody who is not at the console: the
pluggable authentication layer, network servers, Envoy.

The check is made by the library's authentication process, not by
the caller and not by the database server; the stored hash is never
handed out. After a failure for a user name, further requests for
that name are held back - the call returns later - for up to
LOGINDELAYMAX seconds (Security.config), however many tasks send
them. Requests that name a remote host are in addition refused for
LOCKTIME seconds after MAXTRIES failures from that host.

Tags

secT_UserID       - (STRPTR) the user. Required.
secT_Password     - (STRPTR) the clear-text password.
secT_PasswordHash - (STRPTR) a pre-hashed token instead of the
                    password; secT_HashType says which form.
                    Default secHASH_ACRYPT_LC, accepted only when
                    HASHEDLOGIN=1 is set in Security.config and
                    only from a task owned by root (a stored hash
                    is as good as the password).
secT_HashType     - (ULONG) secHASH_#?.
secT_Service      - (STRPTR) the service asking (for the log).
secT_RemoteHost   - (STRPTR) where the request comes from (log,
                    lock-out). Only honoured for a caller owned by
                    root - the network services - and ignored
                    otherwise. An empty password is never accepted
                    from a remote host.
secT_UserInfo     - (struct secUserInfo *) from secAllocUserInfo();
                    filled in on success.
secT_Ticket       - (struct secLoginTicket *) receives a login
                    ticket on success (cleared otherwise). Passing
                    it to secLoginA() as secT_Ticket from the same
                    task logs that user in without a prompt. A
                    ticket is valid once, for a few seconds, and
                    only for the task it was issued to; give back
                    one that will not be used with
                    secT_DiscardTicket.
secT_DiscardTicket - (struct secLoginTicket *) give an unused
                    ticket back. Nothing else is done; the result
                    is secVERIFY_OK.

Challenge tokens (secKEY_CHALLENGE, see secKeyAdminA()): a user who
has one is verified in two calls. The first, with the password and
secT_Ticket, returns secVERIFY_KEYNEEDED, the ticket, the challenge
in secT_KeyChallenge (UBYTE[secKEYCHALLENGESIZE]) and the tokens in
secT_KeyList / secT_KeyListSize / secT_KeyCount (struct secKeyInfo
array, the number filled in). secKeyClientA() obtains a token's
answer; the second call gives it back with the same secT_Ticket,
secT_KeyAssertion / secT_KeyAssertionSize and the answering token's
secT_KeyPublicID, and returns secVERIFY_OK (the ticket is then a
login ticket) or a failure. Nothing is said about the password
until then. Tokens of that kind are not asked for from the
network (secT_RemoteHost).

Result

secVERIFY_OK, secVERIFY_KEYNEEDED (see above), or one of the
secVERIFY_#? failure codes. Unknown user and wrong token both give
secVERIFY_FAILED.

Notes

On an unconfigured system (no password file) the result is
secVERIFY_UNAVAILABLE: there is nobody to verify against, although
secLoginA() would succeed as root there.

See also

secLoginA() secQueryUserA() secCheckPasswdA()