Purdue University

Identity and Access Management

IAMO Home > Services > Web Page / Application Authentication > I2A2 >

Man page for puidnetdz_asmch

Introduction to Library Functions              puidnetdz_asmch(3)

NAME
     puidnetdz_asmch() - assemble PUIDNETD protocol authorization
     characteristics structures

SYNOPSIS
     #include "puidnetd.h"

     int puidnetdz_asmch(
          char *str, size_t len, puidnetdz_chasm_t **ch, int nch
     );

DESCRIPTION
     The puidnetdz_asmch() function assembles authorization
     characteristics structures from an external protocol string.
     (The 'z' in its name stands for authoriZation.)

     Authorization characteristics are the mechanism for indicat-
     ing relationships associated with PUIDs (Purdue University
     IDentification numbers).  PUID authorization characteristics
     are stored in an authorization data base, controlled by an
     authorization DBM (Data Base Manager) of the Purdue I2A2
     (Infrastructure for Identification, Authentication, and
     Authorization) system, and may be accessed via network dae-
     mons.  See puidnetd(4) for more information on the network
     daemons and a discussion of their external protocol.

     The puidnetdz_asmch() function has these arguments:

         * str
             addresses the input string.  See the CHARACTERISTICS
             STRINGS section of this document for their descrip-
             tion.

         len supplies the length of *str.

         **ch
             addresses a variable where puidnetdz_asmch() will
             return the address of a statically allocated array
             of puidnetd_chasm_t structures.

         *n  addresses an integer variable where
             puidnetdz_asmch() will return a count of the number
             of puidnetd_chasm_t structures in **ch.

     The puidnetd_chasm_t structure is defined in puidnetd.h.

CHARACTERISTICS STRINGS
     Authorization characteristics strings consist of one or more
     clauses, separated by commas, that define authorization
     characteristics values.  There are three types of fields
     whose defining type codes may be found as PUIDNETDZ_CHTY_*
     symbols in puidnetd.h.  A null clause - e.g., one with

SunOS 5.8                 Last change:                          1

Introduction to Library Functions              puidnetdz_asmch(3)

     nothing in it, like ",," - is ignored.

     PUIDNETDZ_CHTY_BWD ('w')
         defines "Basic WorD" characteristics.  These are charac-
         teristics represented by single bits in an internal word
         array, since their definitions are common and general.
         Values following this type code are in hexadecimal; when
         there are multiple basic characteristic words, they are
         separated with the vertical bar ('|') character.  (See
         the PUIDNETDZ_CHTY_BCWORDS definition in puidnetd.h to
         determine how many words there are; currently there is
         one.)

         In a hexadecimal value, the power of given bit defines a
         characteristic whose value is the power of two for the
         bit - e.g., characteristic three occupies the 2**3 posi-
         tion; fifteen, 2**15.  Here's an example of a basic word
         characteristics definition for characteristics two,
         three, and four:

             w1c

     PUIDNETDZ_CHTY_CONT ('+')
         is an internal type code that never appears in external
         protocol strings.

     PUIDNETDZ_CHTY_GLOB ('g')
         defines "global" characteristics.  Global characteris-
         tics are defined by official data sources and are
         updated daily.  A characteristic clause that begins with
         a decimal digit is assumed to be global.  Here's the
         basic word definition of the previous example, coupled
         with a clause for global characteristic 1234:

             w1c,g1234

         That could be represented more tersely without the 'g'
         as:

             w1c,1234

     PUIDNETD_CHTY_PRIV ('p')
         defines "private" characteristics.  Private characteris-
         tics are usually temporary ones, assigned immediately
         after an authorization record has been created for a
         PUID, and before the characteristic can be generated by
         official records.  For example, a new employee might be
         given a private characteristic noting employment, but
         official records won't show employment for some inter-
         val.

         When a global characteristic, matching a private one,

SunOS 5.8                 Last change:                          2

Introduction to Library Functions              puidnetdz_asmch(3)

         appears during a daily update, the private one is
         erased.  Private characteristics may occasionally be
         expired at the discretion of the I2A2 administrator.

         Here's an example that: sets basic word bits two, three,
         and four; has a null characteristic clause that
         puidnetdz_asmch() ignores; sets global characteristic
         1234; and sets private characteristic 5678.

             w1c,,g1234,p5678

     Additional information on definitions for and descriptions
     of authorization characteristics strings may be found in
     puidnetd.h.

RETURN VALUES
     The puidnetdz_asmch() function returns 0 if characteristics
     were assembled without error.  Otherwise it returns a
     non-zero PUIDNETD error code that may also be found in the
     puidnetd_errno external variable.  These errors may be
     returned:

     PUIDNETD_ECHCRIT
          indicates that an illegal or ill-formed creator PUID or
          creation time is associated with a characteristic in
          the input string.

     PUIDNETD_ECHFMT
          indicates a general format error in the input string.

     PUIDNETD_ECHTY
          indicates there is an illegal characteristics type in
          the input string.  Legal characteristics types are
          defined by the PUIDNETDZ_CHTY_* symbol definitions in
          puidnetd.h.

     PUIDNETD_ECHVAL
          indicates a characteristics value that is too large or
          too small.  An illegal value specified after a
          PUIDNETDZ_CHTY_BWD type is either unspecified or too
          large for the word arrays.

          An illegal value of any other type must be greater than
          or equal to zero and less than or equal to
          PUIDNETDZ_MAXCH.  PUIDNETDZ_MAXCH is defined in
          puidnetd.h.

     PUIDNETD_ENOMEM
          indicates that the puidnetdz_asmch() function could not
          allocate memory with calloc(3) or malloc(3).

SunOS 5.8                 Last change:                          3

Introduction to Library Functions              puidnetdz_asmch(3)

     The puidnetd_errno external variable is defined in the
     puidnetd.h header file.

EXAMPLES
     The following example unpacks the string "w1f,p21,g32,44" to
     four puidnetdz_chasm_t structures.

          #include "puidnetd.h"

          puidnetdz_chasm_t *c;
          int n;
          char *str = "w1f,p21,g32,44";

          if (puidnetdz_asmch(str, strlen(str), &c, &n)) {
               /* Process puidnetd_errno. */
          }
          /* Process the n (4) puidnetdz_chasm_t structures
           * in c[]. */

AUTHOR
     The puidnetdz_asmch() function was written by Victor A.
     Abell <abe@purdue.edu>.

SEE ALSO
     puidnetd_strerror(3), puidnetd(4).

SunOS 5.8                 Last change:                          4