1IMCLIENT(3)                       Cyrus IMAP                       IMCLIENT(3)
2
3
4

NAME

6       imclient - Cyrus IMAP documentation
7
8       Authenticating callback interface to IMAP/IMSP servers
9

SYNOPSIS

11       #include <cyrus/imclient.h>
12
13       int imclient_connect(struct imclient **imclient , const char *host ,
14           const char *port);
15
16       void imclient_close (struct imclient *imclient);
17       void imclient_setflags(struct imclient *imclient , int flags);
18       void imclient_clearflags (struct imclient *imclient , int flags);
19       char* imclient_servername (struct imclient *imclient);
20       void imclient_addcallback (struct imclient *imclient,...);
21       void imclient_send (struct imclient *imclient, void (*finishproc)(),
22           void *finishrock, const char *fmt,...);
23       void imclient_getselectinfo (struct imclient *imclient, int * fd,
24           int * wanttowrite);
25       void imclient_processoneevent (struct imclient *imclient);
26       int imclient_authenticate (struct imclient *imclient,
27           struct sasl_client **availmech, const char *service,
28           const char *user, int protallowed);
29       int imclient_havetls ();
30       int imclient_starttls (struct imclient *imclient, char *cert_file,
31           char *key_file, char *CAfile, char *CApath);
32

DESCRIPTION

34       The  imclient  library  functions  are  distributed with Cyrus IMAP and
35       IMSP.  These functions are used for building IMAP/IMSP client software.
36       These  functions  handle  Kerberos authentication and can set callbacks
37       based on the keyword in untagged replies or based on the command tag at
38       the end of command replies.
39
40       Users  must  link  with  the -lcyrus switch, and must supply a function
41       called fatal to be called in case of any error within libcyrus.la.
42
43       All of the imclient functions begin with the prefix imclient  and  take
44       an   argument  of type struct imclient * as the first argument which is
45       initialized by imclient_connect and freed by imclient_close.
46
47       See below for a description of each function.
48
49       imclient_connect()
50              Connects the client  server  to  the  host.  If  successful,  it
51              returns  0  and  sets  the  imclient argument to a pointer to an
52              imclient struct.  The imclient  struct  represents  the  current
53              connection, flags, and callbacks.  On failure, the current errno
54              is returned if a system call failed, -1 is returned if the  host
55              name  was  not found, and -2 is returned if the service name was
56              not found.
57
58       imclient_close()
59              Closes and frees the imclient connection.
60
61       imclient_setflags()
62              Sets the flags specified by the flags argument on  the  imclient
63              connection.    Currently    the    only     flag    allowed   is
64              IMCLIENT_CONN_NONSYNCLITERAL  (this  flag  indicates  that   the
65              server supports non-synchronizing literals described by the LIT‐
66              ERAL+ extension).
67
68       imclient_clearflags()
69              Clears the flags specified by the flags argument on the imclient
70              connection.
71
72       imclient_servername()
73              Returns  a char * pointer to the name of the server connected to
74              by imclient.
75
76       imclient_addcallback()
77              Adds an untagged data callback to the imclient  connection.  The
78              function   imclient_addcallback  takes  callbacks  of  the  type
79              imclient_proc_t which is defined to be:
80
81                 typedef void imclient_proc_t (struct imclient *imclient, void *rock, struct imclient_reply *reply);
82
83              and struct imclient_reply * is defined to be:
84
85                 struct imclient_reply {
86                     char *keyword;
87                     long msgno;
88                     char *text;
89                 };
90
91              After the first argument, imclient, there can be  zero  or  more
92              instances  of  the  set  of keyword, flags, proc, and rock, each
93              adding or changing a single callback.   Each  instance  adds  or
94              changes  the callback for keyword.  The argument flags specifies
95              information about the parsing of the untagged  data.   proc  and
96              rock  specify  the callback function and rock to invoke when the
97              untagged data is received.  proc may be a null pointer, in which
98              case no function is invoked.  The callback function may not call
99              the functions imclient_close(), imclient_send(), imclient_eof(),
100              imclient_processoneevent(),  or  imclient_authenticate()  on the
101              connection. The callback function may  overwrite   the  text  of
102              untagged data.
103
104       imclient_send()
105              Sends  a new command to the imclient connection.  finishproc and
106              finishrock are the function and rock  called  when  the  command
107              completes.  functionproc may be a null pointer, in which case no
108              callback is made. The callback function may not call  the  func‐
109              tions    imclient_close(),    imclient_send(),   imclient_eof(),
110              imclient_processoneevent(), or  imclient_authenticate()  on  the
111              connection.   The argument fmt is a printf(3) like specification
112              of the command. It must not include the tag as the tag is  auto‐
113              matically added by imclient_send().
114
115              The defined %-sequences are:
116
117                 %% for %
118                 %a for an IMAP atom
119                 %s for an astring (which will be quoted or literalized as needed)
120                 %d for a decimal
121                 %u for an unsigned decimal
122                 %v for #astring (argument is a null-terminated array of char *
123                 which are written as space separated astrings)
124
125       imclient_getselectinfo()
126              Gets  the  information  for  calling select(2).  fd is filled in
127              with the file descriptor to select(2) for read.  wanttowrite  is
128              filled  in  with  a  nonzero  value if select should be used for
129              write as well.
130
131       imclient_processoneevent()
132              Processes one input or output event on the imclient connection.
133
134       imclient_authenticate()
135              Authenticates the imclient connection using one  of  the  mecha‐
136              nisms  in  availmech.  The argument user, if not NULL, specifies
137              the user to authenticate as. If the user is  NULL,  the  current
138              user  is used.  The argument protallowed is a bitmask of permis‐
139              sible protection mechanisms.  On success,  0  is  returned.   On
140              failure  (i.e.,  "BAD" keyboard, or no authentication mechanisms
141              worked), 1 is returned. On extreme failure (premature  "OK"),  2
142              is returned.
143
144       imclient_havetls()
145              Returns  a  Boolean  indicating whether the imclient library was
146              compiled with TLS (SSL) support.  If so, imclient_starttls() may
147              be used to secure the IMAP connection.
148
149       imclient_starttls()
150              Issues  a  STARTTLS  command  on an existing IMAP connection and
151              negotiates the secure link.  The cert_file  and  key_file  argu‐
152              ments  specify  the  client certificate and secret key to use to
153              authenticate ourselves to the server.  If client  authentication
154              is not needed, set both of these arguments to NULL.
155
156              The  CAfile  and  CApath  arguments specify a file or directory,
157              respectively, of CA certificates for validating server  certifi‐
158              cates.  (See  SSL_CTX_load_verify_locations(3) for details.)  If
159              both of these are NULL, the client will be  unable  to  validate
160              the  server's certificate, in which case the connection may suc‐
161              ceed but a warning will be printed to stdout.
162

EXAMPLES

164       The following code is a possible skeleton of imclient  that  relies  on
165       Kerberos  to  do authentication.  This code performs an IMAP CAPABILITY
166       request and prints out the result.
167
168          #include <cyrus/xmalloc.h> /* example uses xstrdup */
169          #include <cyrus/sasl.h>
170          #include <cyrus/imclient.h>
171          #include <stdio.h>
172
173          extern struct sasl_client krb_sasl_client;
174
175          struct sasl_client *login_sasl_client[] = {
176              &krb_sasl_client,
177              NULL
178          };
179          struct imclient *imclient;
180          char server[] = "cyrus.andrew.cmu.edu" ;
181          char port[] = "imap";
182
183          void fatal(char* message, int rc) {
184              fprintf(stderr, "fatal error: %s\en", message);
185              exit(rc);
186          }
187
188          static void callback_capability(struct imclient *imclient,
189                                          void *rock,
190                                          struct imclient_reply *reply) {
191              if (reply->text != NULL) {
192                  *((char**)rock) = xstrdup( reply->text );
193              }
194          }
195
196          static void end_command(struct imclient *connection, void*
197                                  rock,  struct imclient_reply *inmsg) {
198              (*(int*)rock)--;
199          }
200
201          main() {
202              char* capability_string;
203              int nc;
204
205              if (imclient_connect(&imclient, server, port)) {
206                  fprintf(stderr,
207                          "error: Couldn't connect to %s %s\en",
208                          server, port);
209                  exit(1);
210              }
211
212              if (imclient_authenticate(imclient, login_sasl_client, "imap"
213                                        /* service */,
214                                        NULL /* user */, SASL_PROT_ANY)) {
215                  exit(1);
216              }
217
218              imclient_addcallback(imclient, "CAPABILITY",
219                                   CALLBACK_NOLITERAL,
220                                   callback_capability,
221                                   &capability_string,
222                                   NULL);
223
224              nc = 1;
225
226              imclient_send(imclient, end_command,
227                            (void*) &nc, "CAPABILITY");
228
229              while(nc > 0) {
230                  imclient_processoneevent(imclient);
231              }
232
233              if (strstr("LITERAL+", capability_string)) {
234                  imclient_setflags(imclient, IMCLIENT_CONN_NONSYNCLITERAL);
235              }
236
237              imclient_send(imclient, NULL, NULL, "LOGOUT");
238              imclient_close(imclient);
239
240              printf("capability text is: %s\en", capability_string);
241
242              free(capability_string);
243          }
244

BUGS

246       No known bugs.
247

SEE ALSO

249       cyradm(8), imapd(8), RFC  2033  (IMAP  LITERAL+  extension),  RFC  2060
250       (IMAP4rev1 specification), and select(2)
251

KEYWORDS

253       IMAP, ACAP, IMSP, Kerberos, Authentication
254

AUTHOR

256       The Cyrus Team, Nic Bernstein (Onlight)
257
259       1993-2017, The Cyrus Team
260
261
262
263
2643.0.12                         November 15, 2019                   IMCLIENT(3)
Impressum