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

NAME

6       imclient - Cyrus IMAP documentation
7
8       Authenticating callback interface to IMAP 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.  These
35       functions are used for building IMAP client software.  These  functions
36       handle  Kerberos authentication and can set callbacks based on the key‐
37       word in untagged replies or based on the command tag at the end of com‐
38       mand 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  re‐
51              turns  0  and  sets the imclient argument to a pointer to an im‐
52              client struct.  The imclient struct represents the current  con‐
53              nection, flags, and callbacks.  On failure, the current errno is
54              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  IM‐
64              CLIENT_CONN_NONSYNCLITERAL (this flag indicates that the  server
65              supports  non-synchronizing  literals  described by the LITERAL+
66              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 im‐
79              client_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 un‐
102              tagged 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(),  im‐
110              client_processoneevent(), or imclient_authenticate() on the con‐
111              nection.   The argument fmt is a printf(3) like specification of
112              the command. It must not include the tag as the tag is automati‐
113              cally 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 ne‐
151              gotiates the secure link.  The cert_file and key_file  arguments
152              specify  the client certificate and secret key to use to authen‐
153              ticate ourselves to the server.  If client authentication is not
154              needed, set both of these arguments to NULL.
155
156              The CAfile and CApath arguments specify a file or directory, re‐
157              spectively, 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, Kerberos, Authentication
254

AUTHOR

256       The Cyrus Team, Nic Bernstein (Onlight)
257
259       1993–2022, The Cyrus Team
260
261
262
263
2643.6.0                          December 12, 2022                   IMCLIENT(3)
Impressum