![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to q-dsap.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual|
Return to q-dsap.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
1.1 root 1: % run this through LaTeX with the appropriate wrapper
2:
3: \chapter {Programming the Directory}
4:
5: This part of the manual is written for implementors who wish to access the
6: Directory using the \man libdsap(3n) library.
7: This might be an OSI application wishing to look up information,
8: or an interactive Directory user-interface.
9: The interface to the Directory is defined as a series of procedures which
10: closely parallel the service defined in \cite{CCITT.Directory}. This section
11: defines the procedures,
12: and shows how they relate to the standard.
13: To avoid unnecessary wordiness, the user is expected to be familiar with
14: the standard.
15:
16: \section {Conventions}
17: \label{quipu_conv}
18:
19: The library defines various C structures, described in the
20: following sections
21: Associated with the C structures, are routines which:
22:
23: \begin{itemize}
24: \item allocate structures
25:
26: \item free structures, including sub-structures
27:
28: \item compare structures
29:
30: \item copy structures
31:
32: \item print structures
33:
34: \item parse structures
35: \end{itemize}
36:
37: The following conventions are followed in many routines, which are then
38: briefly identified later.
39: For a general structure x, there will be the following routines:
40: \begin{itemize}
41: \item Allocation:
42: \begin{quote}\small\begin{verbatim}
43: struct x *x_alloc ()
44: \end{verbatim}\end{quote}
45: Allocate memory for structure \verb"x".
46:
47: \item Freeing:
48: \begin{quote}\small\begin{verbatim}
49: x_free (a)
50: struct x * a;
51: \end{verbatim}\end{quote}
52: Free structure \verb"x", and any nested structures.
53:
54: If the structure, \verb"x", is a linked-list type of structure, then as well
55: as the routines described above, there will be routines of the
56: form \verb"x_comp_function" (where \verb"function" is \verb"alloc",
57: \verb"free", and so on). These act upon a single element of the
58: list rather than the list as a whole.
59:
60: \item Copying:
61: \begin{quote}\small\begin{verbatim}
62: struct x * x_cpy (a)
63: struct x *a;
64: \end{verbatim}\end{quote}
65: Return a copy of structure \verb"a".
66:
67: \item Comparing:
68: \begin{quote}\small\begin{verbatim}
69: int x_cmp (a, b)
70: struct x *a, *b;
71: \end{verbatim}\end{quote}
72: Return \verb"0" if the structures \verb"a" and \verb"b" same. Return
73: \verb"-1" if \verb"a<b", or \verb"1" if \verb"a>b".
74: For some structures the notion of \verb"a>b" and \verb"a<b" is not defined,
75: but will be consistent.
76:
77: \item Printing:
78: \begin{quote}
79: \index{rdn\_print}\index{dn\_print}\index{as\_print}\index{avs\_print}
80: \index{AttrT\_print}\index{AttrV\_print}
81: \small\begin{verbatim}
82: int x_print (ps, a, format)
83: PS ps;
84: struct x *a;
85: int format;
86: \end{verbatim}\end{quote}
87: Print the structure \verb"a" to the presentation stream \verb"ps", using the
88: specified format, either \verb"READOUT", for a pretty-printed format (for
89: example the output of a showentry from \pgm{dish}); or,
90: \verb"EDBOUT", for a format suitable for inclusion in an EDB file.
91: The \verb"PS" structure is described in \volone/ of this manual.
92:
93: For the structures representing a DN and RDN there is an extra format:-
94: \verb"DIROUT", which is used to get a representation of the name suitable
95: for inclusion in a \unix/ filename (essentially \verb"EDBOUT" with the
96: \verb"@" symbols replaced with \verb"/" separators).
97:
98: \item String format:
99: \begin{quote}
100: \index{str2rdn}\index{str2dn}\index{str2as}
101: \index{str2AttrV}\index{str2AttrT}
102: \small\begin{verbatim}
103: struct x * str2x (str)
104: char * str;
105: \end{verbatim}\end{quote}
106: Most attribute syntaxes have a string representation.
107: A string of the required
108: syntax can be converted to the relevant c structure with the ``str2x''
109: function.
110: Each of the string parsers assumes the input string has had multiple spaces
111: and tabs removed, and replaced with single spaces.
112: The function
113: \begin{quote}\small\begin{verbatim}
114: char * Tidy_String (a)
115: char * a;
116: \end{verbatim}\end{quote}
117: will do the relevant tidying if required.
118: Strings printed with the \verb"EDBOUT" format of x\_print should be parsable.
119:
120: NOTE \verb"str2AttrV()" \index{str2AttrV} does not follow the ``convention''
121: and has an extra parameter,
122: which is the expected syntax
123: of the string.
124:
125: \item Decoding:
126: \begin{quote}\small\begin{verbatim}
127: x_decode (a)
128: struct x *a;
129: \end{verbatim}\end{quote}
130: For efficiency reasons,
131: when information is read from a DSA any
132: structures that contain nested AttributeTypes and
133: AttributeValues will not be fully decoded.
134: This will not matter if
135: you only intend to use the structures internally, but if you
136: intend to show the structure to a ``user'' or write to a log file,
137: you should call this
138: routine to complete the decoding, which will replace the
139: various ``unfriendly'' structures (such as OID) with string
140: representations.
141: \end{itemize}
142:
143: The structures following the ``convention'' are listed below.
144: The ``prefix'' column shows the value
145: \verb"x" should be replaced by to use the routines for the associated
146: structure.
147: \index{RDN}
148: \index{DN}
149: \index{AttributeType}\index{AttrT}
150: \index{AttributeValue}\index{AttrV}
151: \index{AV\_Sequence}\index{avs}
152: \index{Attr\_Sequence}\index{as}
153: \index{EntryInfo}
154:
155:
156: \[\begin{tabular}{|l|l|} \hline
157: Structure & Prefix \\ \hline
158: RDN & rdn \\
159: DN & dn \\
160: AttributeType & AttrT \\
161: AttributeValue & AttrV \\
162: AV\_Sequence & avs \\
163: Attr\_Sequence & as \\
164: EntryInfo& entryinfo \\ \hline
165: \end{tabular}\]
166:
167: \section {Attributes}
168:
169: Attributes are fundamental
170: components of the directory.
171: Attributes have two parts, types and values, which are
172: (respectfully) represented by two structures,
173: \verb"AttributeType" and \verb"AttributeValue".
174:
175: For programing purposes you should include the file \file{quipu/attrvalue.h}
176: into your programs, which contains the following structure definitions:-
177:
178: \begin{quote}\index{AttributeType}\small\begin{verbatim}
179: typedef struct {
180: OID at_oid;
181: oid_table_attr * at_table;
182: } attrType, * AttributeType;
183: #define NULLAttrT (AttributeType) NULL
184: \end{verbatim}\end{quote}
185:
186:
187: The \verb"AttributeType" structure contains two components, only one
188: of which is used at any one time. An \verb"AttributeType" is defined
189: in \cite{CCITT.Directory} as an OBJECT IDENTIFIER, hence the field
190: \verb"at_oid".
191:
192: But
193: \man libdsap(3n) goes further than this, and has a table (described in
194: Section~\ref{oidtables}) which maps strings onto these OIDs. The
195: second field (\verb"at_table") is a pointer to this table. The table
196: then contains the OID.
197:
198: This table must be loaded by calling
199: \begin{quote}\index{load\_oid\_table}\small\begin{verbatim}
200: load_oid_table(name)
201: char * name;
202: \end{verbatim}\end{quote}
203: The \verb"name" parameter should be the name of the oidtable to load.
204: For most purposes this should be ``\verb"oidtable"''.
205:
206: Before you load the table, any syntaxes you want special attribute handlers
207: for should be loaded. To do this you will probably want to call
208: \label{quipusyntaxes}
209: \begin{quote}
210: \index{quipu\_syntaxes}
211: \begin{verbatim}
212: quipu_syntaxes()
213: \end{verbatim}
214: \end{quote}
215: which will load all the syntax handlers defined in Chapter~\ref{syntaxes}.
216: If not all there syntaxes are required, then a subset can be loaded by
217: calling only the handlers required.
218:
219:
220: The call
221: \begin{quote}\index{dsap\_init}\small\begin{verbatim}
222: dsap_init(argc,argv)
223: int *argc;
224: char *** argv;
225: \end{verbatim}\end{quote}
226: can be used to load the oidtable for you, with the additional
227: benifit that it will
228: read the file \file{/etc/dsaptailor} to
229: find the location on the oidtable.
230: The parameters it expects are the pointers to the
231: \verb"argc" and \verb"argv"
232: parameters passed to your ``main()'' routine
233: (Beware: \verb"dsap_init" removes certain flags from the parameter list, if you care,
234: pass a copy of them, or pass nulls!).
235: If a ``\tt -c\rm '' flag is found then this is used as the name of
236: the DSA to contact as per dish (see Section~\ref{dish_bind}).
237: Other parameters are ignored.
238: As with loading the tables, the syntaxes you require should have been loaded
239: before you make this call.
240:
241: The oidtables are represented using the following structures:-
242: \begin{quote}\index{oid\_table}\small\begin{verbatim}
243: typedef struct {
244: char ot_name [BUFSIZE];
245: char ot_stroid [BUFSIZE];
246: OID ot_oid;
247: } oid_table;
248: #define NULLTABLE ((oid_table * )0)
249:
250: typedef struct {
251: oid_table oa_ot;
252: int oa_syntax;
253: } oid_table_attr;
254: #define NULLTABLE_ATTR ((oid_table_attr *)0)
255: \end{verbatim}\end{quote}
256:
257:
258: As structures come across the network,
259: the AttributeType is decoded into the \verb"at_oid" field. If you
260: want to use the string representation you must call
261: \verb"AttrT_decode" (described in Section~\ref{quipu_conv}),
262: if you do not decode the structure, the
263: print routines will still work, but the result will numeric
264: OIDs.
265: If successfully decoded the field \verb"at_oid" will be set to \verb"NULLOID",
266: to indicate that there is a table version of the oid.
267:
268: The table consists to two fields, an integer syntax :- \verb"oa_syntax".
269: This is an integer handle onto the abstract syntax of the attribute value.
270: The value `\verb"0"' indicates an unknown syntax hence ``ASN'' is used.
271:
272: The second field \verb"oa_ot" is a reference to a \verb"oid_table" structure,
273: which contain the oid -- \verb"ot_oid", a numeric string representation of the oid
274: -- \verb"ot_stroid", and the local key string -- \verb"ot_name".
275:
276: To create an \verb"AttributeType" given a string representation of an
277: OID, you should use
278: \begin{quote}\index{str2AttrT}\small\begin{verbatim}
279: AttributeType str2AttrT (str)
280: char *str;
281: \end{verbatim}\end{quote}
282: which looks up the string ``\verb"str"'' in the OID table, and creates an
283: \verb"AttributeType" structure.
284:
285: There are various low level routines to manipulate entries in
286: the OID table, however the \verb"AttributeType" routines described in
287: Section~\ref{quipu_conv}
288: will be sufficient for most uses, so the details of these
289: ``invisible'' routines are omitted here.
290:
291:
292: Attribute values are represented by the structure \verb"AttributeValue":-
293:
294: \begin{quote}\index{AttributeValue}\small\begin{verbatim}
295: typedef struct attrVal {
296: short av_syntax;
297: caddr_t av_struct;
298: } * AttributeValue;
299:
300: #define NULLAttrV (AttributeValue) NULL
301: \end{verbatim}\end{quote}
302:
303: The \verb"AttributeValue" structure can hold attribute values in two
304: formats. Firstly as a specialised {\em C\/} structure pointed to by
305: \verb"av_struct", the
306: field \verb"av_syntax" defines the syntax represented by the
307: \verb"av_struct" field.
308: Secondly as a presentation element (also in the \verb"av_struct" field), this is the case when an attribute has
309: been received from the net, but not decoded (indicated by
310: the syntax being zero). The routine \verb"AttrV_decode"
311: will burst this presentation element into the relevant \verb"av_struct"
312: field.
313: Section ~\ref{add_syntax} describes this more fully.
314:
315:
316: Attribute values can now be linked together to form a multi-value attribute
317: value.
318: For this the \verb"AV_Sequence" structure is used.
319:
320: \begin{quote}\index{AV\_Sequence}\small\begin{verbatim}
321: typedef struct avseqcomp {
322: attrVal avseq_av;
323: struct avseqcomp *avseq_next;
324: } avseqcomp, *AV_Sequence;
325:
326: #define NULLAV ((AV_Sequence) 0)
327: \end{verbatim}\end{quote}
328:
329: This is simply a linked list of AttributeValues\footnote{
330: For those of you who wrote interfaces using ISODE-5.0, you should note that
331: the field \verb+avseq\_av+ is now an \verb+attrVal+ and not an
332: \verb+attrVal *+.
333: }.
334:
335: To create an \verb"AV_Sequence" the two routines
336: \begin{quote}\index{avs\_comp\_new}\index{avs\_merge}\small\begin{verbatim}
337: AV_Sequence avs_comp_new (av)
338: AttributeValue av;
339:
340: AV_Sequence avs_merge (a,b)
341: AV_Sequence a,b;
342: \end{verbatim}\end{quote}
343: can be used.
344:
345: Finally an attribute can now be formed by linking the attribute type, and
346: multiple attribute values using the \verb"AttrSequence" structure:-
347:
348: \begin{quote}\index{Attr\_Sequence}\small\begin{verbatim}
349: typedef struct attrcomp {
350: attrType attr_type;
351: AV_Sequence attr_value;
352: struct attrcomp *attr_link;
353: struct acl_info *attr_acl;
354: } attrcomp, *Attr_Sequence;
355:
356: #define NULLATTR ((Attr_Sequence) 0)
357: \end{verbatim}\end{quote}
358:
359: This structure is used singularly to represent an attribute, and as a linked
360: list (linked using \verb"attr_link") to represent a set of attributes.
361:
362: To create an \verb"Attr_Sequence" the two routines
363: \begin{quote}\index{as\_comp\_new}\index{as\_merge}\small\begin{verbatim}
364: Attr_Sequence as_comp_new (at,as,acl)
365: AttributeType at;
366: AV_Sequence as;
367: struct acl_info * acl;
368:
369: Attr_Sequence as_merge (a,b)
370: Attr_Sequence a,b;
371: \end{verbatim}\end{quote}
372:
373: can be used.
374: The \verb"acl" parameter is only used by the DSA, for use in a DUA it should be
375: set to \verb"NULLACL_INFO".
376:
377: The routine
378: \begin{quote}\index{as\_combine}\small\begin{verbatim}
379: Attr_Sequence as_combine (as,str)
380: AV_Sequence as;
381: char * str;
382: \end{verbatim}\end{quote}
383: is also provided, as an optimisation of
384: \begin{quote}\small\begin{verbatim}
385: as_merge(as,str2as(str));
386: \end{verbatim}\end{quote}
387:
388: \section {Distinguished Names}
389: The structures which define names are critical.
390: Names are essentially made up of attributes, but because of their
391: importance, a different --- more specific structure is used.
392:
393: \begin{quote}\index{RDN}\small\begin{verbatim}
394: typedef struct rdncomp {
395: attrType rdn_at;
396: attrVal rdn_av;
397: struct rdncomp *rdn_next;
398: } rdncomp, *RDN;
399:
400: #define NULLRDN ((RDN) 0)
401: \end{verbatim}\end{quote}
402:
403: An RDN consists of a set of Attribute Types
404: (\verb"rdn_at"\footnote{This was an \verb+attrType *+ in ISODE-5.0})
405: and Attribute Values
406: (\verb"rdn_av"\footnote{This was an \verb+attrVal *+ in ISODE-5.0}),
407: the set is linked using \verb"rdn_next".
408:
409: RDNs can the be joined in a sequence to form a Distinguished Name (DN):-
410: \begin{quote}\index{DN}\small\begin{verbatim}
411: typedef struct dncomp {
412: RDN dn_rdn;
413: struct dncomp *dn_parent;
414: } dncomp, *DN;
415:
416: #define NULLDN ((DN) 0)
417: \end{verbatim}\end{quote}
418:
419: The following routines are provided in addition to the routines defined is
420: Section~\ref{quipu_conv} to allow the user to create and manipulate names
421:
422: \begin{itemize}
423: \item Create a DN given an RDN:
424: \begin{quote}\index{dn\_comp\_new}\small\begin{verbatim}
425: dn_comp_new (rdn)
426: RDN rdn;
427: \end{verbatim}\end{quote}
428:
429: \item Append a DN to the end of another DN:
430: \begin{quote}\index{dn\_append}\small\begin{verbatim}
431: dn_append (dn1, dn2)
432: DN dn1,
433: dn2;
434: \end{verbatim}\end{quote}
435: \verb"dn2" is added to \verb"dn1".
436:
437: \item Create a RDN given and AttributeType and AttributeValue:
438: \begin{quote}\small\index{rdn\_comp\_new}\begin{verbatim}
439: RDN rdn_comp_new (at, av)
440: AttributeType at;
441: AttributeValue av;
442: \end{verbatim}\end{quote}
443:
444: \item Merge two RDNs:
445: \begin{quote}\small\index{rdn\_merge}\begin{verbatim}
446: RDN rdn_merge (rdn1, rdn2)
447: RDN rdn1,
448: rdn2;
449: \end{verbatim}\end{quote}
450: RDN's form a set, to make comparisons easier, this
451: implementation assumes them to be ordered sets. This routine
452: takes two ordered RDN sets, and merges them.
453: If RDNs received across the network are not ordered, the decoding
454: process will order them for you.
455: \end{itemize}
456:
457: The approach to access control is defined in
458: \cite{QUIPU.Design}.
459: The representation of the attribute for access control is given by the
460: structure shown below. This closely follows the ASN.1
461: definition.
462:
463: \begin{quote}\small\begin{verbatim}
464: struct acl_info {
465: int acl_categories;
466: #define ACL_NONE 0
467: #define ACL_DETECT 1
468: #define ACL_COMPARE 2
469: #define ACL_READ 3
470: #define ACL_ADD 4
471: #define ACL_WRITE 5
472: int acl_selector_type;
473: #define ACL_ENTRY 0
474: #define ACL_OTHER 1
475: #define ACL_PREFIX 2
476: #define ACL_GROUP 3
477: DN acl_name;
478: struct acl_info *acl_next;
479: };
480: \end{verbatim}\end{quote}
481:
482: The DN \verb"acl_name" is used for the type \verb"ACL_PREFIX" and
483: \verb"ACL_OTHER" only.
484:
485: \section {Adding New Syntaxes to QUIPU}
486: \label{add_syntax}
487:
488: It will probably be necessary to add knowledge of extra syntaxes to
489: Directory User Interfaces as the range of applications grow.
490: QUIPU has been designed to make this as easy as possible.
491:
492: This section describes how you might do this, by adding knowledge
493: of a \verb"FOOBAR" syntax to \man libdsap(3n) library.
494: \verb"FOOBAR" is represented by the c structure
495: ``\tt struct foobar \{\ldots\};\rm ''.
496:
497: The DSA does not need to know about the new structure, as it will
498: handle unknown syntaxes as blocks of ASN.1.
499:
500: The procedure call
501: \begin{quote}\small\begin{verbatim}
502: add_attribute_syntax (sntx,enc,dec,parse,
503: print,cpy,cmp,sfree,
504: print_pe,approx,multiline)
505: char * sntx;
506: IFP enc,dec,parse,print,cpy,cmp,sfree,approx;
507: char * print_pe;
508: char multiline;
509: \end{verbatim}\end{quote}
510: is used to add knowledge of new attribute syntaxes to quipu.
511:
512: The parameters are used as follows:-
513:
514: \begin{describe}
515: \item [\verb"sntx":] The string defining the syntax, in this case it should
516: be \verb"Foobar". Any attributes defined as having the syntax ``Foobar'' in
517: the oidtables will the be handled using the following routines.
518:
519: \item [\verb"enc":] This is a function pointer to a routine that will convert
520: a C structure representation of foobar into a presentation element that can
521: be sent across the network.
522: The routine is given a single parameter --- a pointer to the foobar structure,
523: and is expected to return a PE.
524: You are reminded of the \man pepy(1c) and \man posy(1c) utilities described
525: in \volfour/ of this manual, they may be of help in creating this encoder.
526:
527: \item [\verb"dec":] This performs the inverse of the above, it is passed a
528: PE, and should return a C structure representation.
529:
530: \item [\verb"parse":] Each syntax needs to have a representation that can
531: be read from and written to an EDB file. This defined routine should take
532: a single
533: \verb"char *" argument and return a C structure representation.
534:
535: \item [\verb"print":] This routine is used to print the syntax to a
536: \verb+PStream+\footnote{\verb+PStream+'s are discussed in \volone/ of this
537: manual.}.
538: The arguments are:
539: \begin{quote}\small\begin{verbatim}
540: foobar_print (ps,fb,format)
541: PS ps;
542: struct foobar * fb;
543: int format;
544: \end{verbatim}\end{quote}
545: If \verb"format" is \verb"READOUT" the structure should be printed to the
546: stream PS in a ``human readable'' manner, otherwise is should be printed
547: in a form that can be parsed by the ``parse'' function.
548: NOTE in many case both formats will be the same.
549:
550: \item [\verb"cpy":] This function should take a foobar structure as a
551: parameter and returns a copy of it.
552:
553: \item [\verb"cmp":] A function that takes two foobar structures and compares
554: them --- returning 0 if they are the same, 1 is the first is considered
555: ``greater'' than the second, -1 otherwise.
556: If there is no appropriate ordering for the syntax, return 2.
557: If an error occurs during the comparison return -2.
558:
559: \item[\verb"sfree":] A routine to free the structure foobar.
560:
561: \item[\verb"print\_pe":] The name of an external process to `exec' when the
562: \verb+READOUT+ option is supplied to the print routine.
563: This is generally set to \verb+NULLCP+ which means the default `print'
564: routine is used.
565:
566: \item[\verb"approx":] A routine to perform approximate matching (if
567: required).
568: The routine should expect two parameters as shown:
569: \begin{quote}
570: \begin{verbatim}
571: foobar_approx (a,b)
572: struct filter_item * a;
573: AV_Sequence b;
574: \end{verbatim}
575: \end{quote}
576: The routine should return \verb+OK+ or \verb+NOTOK+ depending on whether
577: any attribute value in the \verb+AV_Sequence+ approximately matches the
578: \verb+filter_item+.
579:
580: \item[\verb"multiline":] If \verb"TRUE" the multi-value attributes will be
581: printed on separate lines:
582: \begin{quote}\small\begin{verbatim}
583: foobar = value1
584: foobar = value2
585: \end{verbatim}\end{quote}
586: otherwise the attribute will be printed on one
587: line:
588: \begin{quote}\small\begin{verbatim}
589: foobar = value1 & value2
590: \end{verbatim}\end{quote}
591:
592: \end{describe}
593:
594: \subsection {Where to Add the Syntax Definition}
595:
596: Where should you add this procedure call, to define the new syntaxes?
597:
598: This depends on which applications you want to know about the syntax.
599: If you want the DSA and all DUAs to know about the syntax, then this call
600: should be added to libdsap, in the directory dsap/common.
601: The file dsap/common/quipu\_sntx.c is where other similar calls are made.
602: A small test program \verb"test" is included in the common directory, and is
603: made with ``\verb+make test+''. It takes as input a string representation of
604: attributes, and exercises the handlers.
605: If this works for your new attribute, then it should be safe to re-compile the
606: DSA/DUA and try them.
607:
608: If you only wish your DUAs to know about the new syntax, then add the call
609: into you DUAs code, before loading the oidtables of calling \verb+dsap_init+.
610:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.