Back to index

opendkim  2.6.6
vbr.h
Go to the documentation of this file.
00001 /*
00002 **  Copyright (c) 2007 Sendmail, Inc. and its suppliers.
00003 **    All rights reserved.
00004 **
00005 **  Copyright (c) 2009, 2010, The OpenDKIM Project.  All rights reserved.
00006 */
00007 
00008 #ifndef _VBR_H_
00009 #define _VBR_H_
00010 
00011 #ifndef lint
00012 static char vbr_h_id[] = "@(#)$Id: vbr.h,v 1.2.48.1 2010/10/27 21:43:09 cm-msk Exp $";
00013 #endif /* !lint */
00014 
00015 /* system includes */
00016 #include <sys/types.h>
00017 
00018 /* strings */
00019 #define       VBR_ALL                     "all"
00020 #define       VBR_INFOHEADER              "VBR-Info"
00021 #define       VBR_PREFIX           "_vouch"
00022 
00023 /* definitions */
00024 #define       VBR_MAXHEADER        1024
00025 #define       VBR_MAXHOSTNAMELEN   256
00026 
00027 /* return codes */
00028 typedef int VBR_STAT;
00029 
00030 #define VBR_STAT_OK         0
00031 #define VBR_STAT_INVALID    1
00032 #define VBR_STAT_DNSERROR   2
00033 #define VBR_STAT_NORESOURCE 3
00034 #define VBR_STAT_NOTIMPLEMENT      4
00035 
00036 #define       VBR_OPT_TRUSTEDONLY  0x01
00037 
00038 /* types */
00039 struct vbr_handle;
00040 typedef struct vbr_handle VBR;
00041 
00042 /* prototypes */
00043 
00044 /*
00045 **  VBR_INIT -- initialize a VBR handle
00046 **
00047 **  Parameters:
00048 **     caller_mallocf -- caller-provided memory allocation function
00049 **     caller_freef -- caller-provided memory release function
00050 **     closure -- memory closure to pass to the above when used
00051 **
00052 **  Return value:
00053 **     A new VBR handle suitable for use with other VBR functions, or
00054 **     NULL on failure.
00055 **  
00056 **  Side effects:
00057 **     Strange radar returns at Indianapolis ARTCC.
00058 */
00059 
00060 extern VBR * vbr_init __P((void *(*caller_mallocf)(void *closure,
00061                                                    size_t nbytes),
00062                            void (*caller_freef)(void *closure, void *p),
00063                            void *closure));
00064 
00065 /*
00066 **  VBR_OPTIONS -- set VBR options
00067 **
00068 **  Parameters:
00069 **     vbr -- VBR handle to modify
00070 **     opts -- bitmask of options to use
00071 **
00072 **  Return value:
00073 **     None.
00074 */
00075 
00076 extern void vbr_options __P((VBR *, unsigned int));
00077 
00078 /*
00079 **  VBR_CLOSE -- shut down a VBR instance
00080 **
00081 **  Parameters:
00082 **     vbr -- VBR handle to shut down
00083 **
00084 **  Return value:
00085 **     None.
00086 */
00087 
00088 extern void vbr_close __P((VBR *));
00089 
00090 /*
00091 **  VBR_GETERROR -- return any stored error string from within the VBR
00092 **                  context handle
00093 **
00094 **  Parameters:
00095 **     vbr -- VBR handle from which to retrieve an error string
00096 **
00097 **  Return value:
00098 **     A pointer to the stored string, or NULL if none was stored.
00099 */
00100 
00101 extern const u_char *vbr_geterror __P((VBR *));
00102 
00103 /*
00104 **  VBR_GETHEADER -- generate and store the VBR-Info header
00105 **
00106 **  Parameters:
00107 **     vbr -- VBR handle, created by vbr_init()
00108 **     hdr -- header buffer
00109 **     len -- number of bytes available at "hdr"
00110 **
00111 **  Return value:
00112 **     STAT_OK -- success
00113 **     STAT_NORESOURCE -- "hdr" was too short
00114 */
00115 
00116 extern VBR_STAT vbr_getheader __P((VBR *, unsigned char *, size_t));
00117 
00118 /*
00119 **  VBR_SETCERT -- store the VBR certifiers of this message
00120 **
00121 **  Parameters:
00122 **     vbr -- VBR handle, created by vbr_init()
00123 **     cert -- certifiers string
00124 **
00125 **  Return value:
00126 **     None (yet).
00127 */
00128 
00129 extern void vbr_setcert __P((VBR *, u_char *));
00130 
00131 /*
00132 **  VBR_SETTYPE -- store the VBR type of this message
00133 **
00134 **  Parameters:
00135 **     vbr -- VBR handle, created by vbr_init()
00136 **     type -- type string
00137 **
00138 **  Return value:
00139 **     None (yet).
00140 */
00141 
00142 extern void vbr_settype __P((VBR *, u_char *));
00143 
00144 /*
00145 **  VBR_SETDOMAIN -- declare the sender's domain
00146 **
00147 **  Parameters:
00148 **     vbr -- VBR handle, created by vbr_init()
00149 **     cert -- certifiers string
00150 **
00151 **  Return value:
00152 **     None (yet).
00153 */
00154 
00155 extern void vbr_setdomain __P((VBR *, u_char *));
00156 
00157 /*
00158 **  VBR_TRUSTEDCERTS -- set list of trusted certifiers
00159 **
00160 **  Parameters:
00161 **     vbr -- VBR handle, created by vbr_init()
00162 **     certs -- NULL terminted vector of trusted certifier names
00163 **
00164 **  Return value:
00165 **     None (yet).
00166 */
00167 
00168 extern void vbr_trustedcerts __P((VBR *, u_char **));
00169 
00170 /*
00171 **  VBR_QUERY -- query the vouching servers for results
00172 **
00173 **  Parameters:
00174 **     vbr -- VBR handle, created by vbr_init()
00175 **     res -- result string (one of "fail", "pass"); returned
00176 **     cert -- name of the certifier that returned a "pass"; returned
00177 **
00178 **  Return value:
00179 **     VBR_STAT_OK -- able to determine a result
00180 **     VBR_STAT_INVALID -- vbr_trustedcerts(), vbr_settype() and
00181 **                          vbr_setcert() were not all called
00182 **     VBR_STAT_CANTVRFY -- DNS issue prevented resolution
00183 **
00184 **  Notes:
00185 **     - "pass" is the result if ANY certifier vouched for the message.
00186 **     - "res" is not modified if no result could be determined
00187 **     - "cert" and "domain" are not modified if a "pass" is not returned
00188 **     - there's no attempt to validate the values found
00189 */
00190 
00191 extern VBR_STAT vbr_query __P((VBR *, u_char **, u_char **));
00192 
00193 /*
00194 **  VBR_SETTIMEOUT -- set the DNS timeout
00195 **
00196 **  Parameters:
00197 **     vbr -- VBR handle, created by vbr_init()
00198 **     timeout -- requested timeout (seconds)
00199 **
00200 **  Return value:
00201 **     A VBR_STAT_* constant.
00202 */
00203 
00204 extern VBR_STAT vbr_settimeout __P((VBR *, u_int));
00205 
00206 /*
00207 **  VBR_SETCALLBACKINT -- set the DNS callback interval
00208 **
00209 **  Parameters:
00210 **     vbr -- VBR handle, created by vbr_init()
00211 **     cbint -- requested callback interval (seconds)
00212 **
00213 **  Return value:
00214 **     A VBR_STAT_* constant.
00215 */
00216 
00217 extern VBR_STAT vbr_setcallbackint __P((VBR *, u_int));
00218 
00219 /*
00220 **  VBR_SETCALLBACKCTX -- set the DNS callback context
00221 **
00222 **  Parameters:
00223 **     vbr -- VBR handle, created by vbr_init()
00224 **     ctx -- context to pass to the DNS callback
00225 **
00226 **  Return value:
00227 **     A VBR_STAT_* constant.
00228 */
00229 
00230 extern VBR_STAT vbr_setcallbackctx __P((VBR *, void *));
00231 
00232 /*
00233 **  VBR_SETDNSCALLBACK -- set the DNS wait callback
00234 **
00235 **  Parameters:
00236 **     vbr -- VBR handle, created by vbr_init()
00237 **     func -- function to call; should take an opaque context pointer
00238 **
00239 **  Return value:
00240 **     A VBR_STAT_* constant.
00241 */
00242 
00243 extern VBR_STAT vbr_setdnscallback __P((VBR *vbr,
00244                                         void (*func)(const void *context)));
00245 
00246 /*
00247 **  VBR_DNS_SET_QUERY_SERVICE -- stores a handle representing the DNS
00248 **                               query service to be used, returning any
00249 **                               previous handle
00250 **
00251 **  Parameters:
00252 **     vbr -- VBR library handle
00253 **     h -- handle to be used
00254 **
00255 **  Return value:
00256 **     Previously stored handle, or NULL if none.
00257 */
00258 
00259 extern void *vbr_dns_set_query_service __P((VBR *, void *));
00260 
00261 /*
00262 **  VBR_DNS_SET_QUERY_START -- stores a pointer to a query start function
00263 **
00264 **  Parameters:
00265 **     vbr -- VBR library handle
00266 **     func -- function to use to start queries
00267 **
00268 **  Return value:
00269 **     None.
00270 **
00271 **  Notes:
00272 **     "func" should match the following prototype:
00273 **            returns int (status)
00274 **            void *dns -- receives handle stored by
00275 **                         vbr_dns_set_query_service()
00276 **            int type -- DNS RR query type (C_IN assumed)
00277 **            char *query -- question to ask
00278 **            char *buf -- buffer into which to write reply
00279 **            size_t buflen -- size of buf
00280 **            void **qh -- returned query handle
00281 */
00282 
00283 extern void vbr_dns_set_query_start __P((VBR *, int (*)(void *, int,
00284                                                         unsigned char *,
00285                                                         unsigned char *,
00286                                                         size_t, void **)));
00287 
00288 /*
00289 **  VBR_DNS_SET_QUERY_CANCEL -- stores a pointer to a query cancel function
00290 **
00291 **  Parameters:
00292 **     vbr -- VBR library handle
00293 **     func -- function to use to cancel running queries
00294 **
00295 **  Return value:
00296 **     None.
00297 **
00298 **  Notes:
00299 **     "func" should match the following prototype:
00300 **            returns int (status)
00301 **            void *dns -- DNS service handle
00302 **            void *qh -- query handle to be canceled
00303 */
00304 
00305 extern void vbr_dns_set_query_cancel __P((VBR *, int (*)(void *, void *)));
00306 
00307 /*
00308 **  VBR_DNS_SET_QUERY_WAITREPLY -- stores a pointer to wait for a DNS reply
00309 **
00310 **  Parameters:
00311 **     vbr -- VBR library handle
00312 **     func -- function to use to wait for a reply
00313 **
00314 **  Return value:
00315 **     None.
00316 **
00317 **  Notes:
00318 **     "func" should match the following prototype:
00319 **            returns int (status)
00320 **            void *dns -- DNS service handle
00321 **            void *qh -- handle of query that has completed
00322 **            struct timeval *timeout -- how long to wait
00323 **            size_t *bytes -- bytes returned
00324 **            int *error -- error code returned
00325 **            int *dnssec -- DNSSEC status returned
00326 */
00327 
00328 extern void vbr_dns_set_query_waitreply __P((VBR *, int (*)(void *, void *,
00329                                                             struct timeval *,
00330                                                             size_t *, int *,
00331                                                             int *)));
00332 
00333 #endif /* _VBR_H_ */