doc/man/libauth.3

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "libauth 3"
 132 .TH libauth 3 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
 133 .SH "NAME"
 134 libauth \- routines for writing nnrpd resolvers and authenticators
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&    #include "libauth.h"
 139 .Ve
 140 .PP
 141 .Vb 5
 142 \&    struct res_info {
 143 \&        struct sockaddr *client;
 144 \&        struct sockaddr *local;
 145 \&        char *clienthostname;
 146 \&    };
 147 .Ve
 148 .PP
 149 .Vb 4
 150 \&    struct auth_info {
 151 \&        char *username;
 152 \&        char *password;
 153 \&    };
 154 .Ve
 155 .PP
 156 .Vb 2
 157 \&    struct auth_info *get_auth_info(FILE *);
 158 \&    struct res_info  *get_res_info (FILE *);
 159 .Ve
 160 .PP
 161 .Vb 2
 162 \&    void free_auth_info(struct auth_info*);
 163 \&    void free_res_info (struct res_info*);
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 These functions provide a convenient C frontend to the nnrpd external
 168 authentication interface documented in \fIdoc/external\-auth\fR.  Use of
 169 this library is \fBnot\fR required; in particular, external resolvers and
 170 authenticators written in languages other than C will need to implement
 171 the necessary functionality themselves.
 172 .PP
 173 The \fIget_auth_info()\fR and \fIget_res_info()\fR functions allocate sufficient
 174 memory for a \fBstruct auth_info\fR or \fBstruct res_info\fR and any necessary
 175 fields, and return a pointer to the struct with the fields filled in
 176 from information supplied by nnrpd (the \fBFILE*\fR parameter generally
 177 should be \f(CW\*(C`stdin\*(C'\fR).  Both functions return \s-1NULL\s0 on error.  The caller
 178 is responsible for deallocating the memory by using the functions below.
 179 .PP
 180 The string fields of both structs are straightforward.  The \fBclient\fR
 181 and \fBlocal\fR fields of \fBstruct res_info\fR actually point to instances of
 182 \&\fBstruct sockaddr_in\fR (or \fBstruct sockaddr_in6\fR if IPv6 support is
 183 compiled in).
 184 .PP
 185 The \fIfree_auth_info()\fR and \fIfree_res_info()\fR functions free the struct
 186 passed in as argument and all necessary fields.
 187 .SH "BUGS"
 188 .IX Header "BUGS"
 189 In many cases, nnrpd provides more information than is normally useful
 190 (for example, even when calling an authenticator, the resolver
 191 information is often provided.)  On the other hand, in certain cases it
 192 provides less information than might be expected (for example, if nnrpd
 193 is reading from stdin rather than a socket).  The implementation is
 194 capable of handling at least the first of these issues, but that
 195 functionality is not exposed in the interface.
 196 .PP
 197 At present, \fIlibauth.h\fR and its implementation are located in
 198 \&\fIauthprogs/\fR; perhaps they should be moved to \fIinclude/\fR and \fIlib/\fR,
 199 respectively?
 200 .SH "HISTORY"
 201 .IX Header "HISTORY"
 202 Written by Jeffrey M. Vinocur <jeff@litech.org> for InterNetNews.
 203 .PP
 204 $Id: libauth.3 7880 2008-06-16 20:37:13Z iulius $
 205 .SH "SEE ALSO"
 206 .IX Header "SEE ALSO"
 207 \&\fInnrpd\fR\|(8), \fIreaders.conf\fR\|(5), \fIdoc/external\-auth\fR