src/include/krad.h

   1 /* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
   2 /*
   3  * Copyright 2013 Red Hat, Inc.  All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are met:
   7  *
   8  *    1. Redistributions of source code must retain the above copyright
   9  *       notice, this list of conditions and the following disclaimer.
  10  *
  11  *    2. Redistributions in binary form must reproduce the above copyright
  12  *       notice, this list of conditions and the following disclaimer in
  13  *       the documentation and/or other materials provided with the
  14  *       distribution.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  17  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  18  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  19  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
  20  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  21  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  23  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  24  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  25  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  26  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /*
  30  * This API is not considered as stable as the main krb5 API.
  31  *
  32  * - We may make arbitrary incompatible changes between feature releases
  33  *   (e.g. from 1.12 to 1.13).
  34  * - We will make some effort to avoid making incompatible changes for
  35  *   bugfix releases, but will make them if necessary.
  36  */
  37
  38 #ifndef KRAD_H_
  39 #define KRAD_H_
  40
  41 #include <krb5.h>
  42 #include <verto.h>
  43 #include <stddef.h>
  44 #include <stdio.h>
  45
  46 #define KRAD_PACKET_SIZE_MAX 4096
  47
  48 #define KRAD_SERVICE_TYPE_LOGIN 1
  49 #define KRAD_SERVICE_TYPE_FRAMED 2
  50 #define KRAD_SERVICE_TYPE_CALLBACK_LOGIN 3
  51 #define KRAD_SERVICE_TYPE_CALLBACK_FRAMED 4
  52 #define KRAD_SERVICE_TYPE_OUTBOUND 5
  53 #define KRAD_SERVICE_TYPE_ADMINISTRATIVE 6
  54 #define KRAD_SERVICE_TYPE_NAS_PROMPT 7
  55 #define KRAD_SERVICE_TYPE_AUTHENTICATE_ONLY 8
  56 #define KRAD_SERVICE_TYPE_CALLBACK_NAS_PROMPT 9
  57 #define KRAD_SERVICE_TYPE_CALL_CHECK 10
  58 #define KRAD_SERVICE_TYPE_CALLBACK_ADMINISTRATIVE 11
  59
  60 typedef struct krad_attrset_st krad_attrset;
  61 typedef struct krad_packet_st krad_packet;
  62 typedef struct krad_client_st krad_client;
  63 typedef unsigned char krad_code;
  64 typedef unsigned char krad_attr;
  65
  66 /* Called when a response is received or the request times out. */
  67 typedef void
  68 (*krad_cb)(krb5_error_code retval, const krad_packet *request,
  69            const krad_packet *response, void *data);
  70
  71 /*
  72  * Called to iterate over a set of requests.  Either the callback will be
  73  * called until it returns NULL, or it will be called with cancel = TRUE to
  74  * terminate in the middle of an iteration.
  75  */
  76 typedef const krad_packet *
  77 (*krad_packet_iter_cb)(void *data, krb5_boolean cancel);
  78
  79 /*
  80  * Code
  81  */
  82
  83 /* Convert a code name to its number. Only works for codes defined
  84  * by RFC 2875 or 2882. Returns 0 if the name was not found. */
  85 krad_code
  86 krad_code_name2num(const char *name);
  87
  88 /* Convert a code number to its name. Only works for attributes defined
  89  * by RFC 2865 or 2882. Returns NULL if the name was not found. */
  90 const char *
  91 krad_code_num2name(krad_code code);
  92
  93 /*
  94  * Attribute
  95  */
  96
  97 /* Convert an attribute name to its number. Only works for attributes defined
  98  * by RFC 2865. Returns 0 if the name was not found. */
  99 krad_attr
 100 krad_attr_name2num(const char *name);
 101
 102 /* Convert an attribute number to its name. Only works for attributes defined
 103  * by RFC 2865. Returns NULL if the name was not found. */
 104 const char *
 105 krad_attr_num2name(krad_attr type);
 106
 107 /*
 108  * Attribute set
 109  */
 110
 111 /* Create a new attribute set. */
 112 krb5_error_code
 113 krad_attrset_new(krb5_context ctx, krad_attrset **set);
 114
 115 /* Create a deep copy of an attribute set. */
 116 krb5_error_code
 117 krad_attrset_copy(const krad_attrset *set, krad_attrset **copy);
 118
 119 /* Free an attribute set. */
 120 void
 121 krad_attrset_free(krad_attrset *set);
 122
 123 /* Add an attribute to a set. */
 124 krb5_error_code
 125 krad_attrset_add(krad_attrset *set, krad_attr type, const krb5_data *data);
 126
 127 /* Add a four-octet unsigned number attribute to the given set. */
 128 krb5_error_code
 129 krad_attrset_add_number(krad_attrset *set, krad_attr type, krb5_ui_4 num);
 130
 131 /* Delete the specified attribute. */
 132 void
 133 krad_attrset_del(krad_attrset *set, krad_attr type, size_t indx);
 134
 135 /* Get the specified attribute. */
 136 const krb5_data *
 137 krad_attrset_get(const krad_attrset *set, krad_attr type, size_t indx);
 138
 139 /*
 140  * Packet
 141  */
 142
 143 /* Determine the bytes needed from the socket to get the whole packet.  Don't
 144  * cache the return value as it can change! Returns -1 on EBADMSG. */
 145 ssize_t
 146 krad_packet_bytes_needed(const krb5_data *buffer);
 147
 148 /* Free a packet. */
 149 void
 150 krad_packet_free(krad_packet *pkt);
 151
 152 /*
 153  * Create a new request packet.
 154  *
 155  * This function takes the attributes specified in set and converts them into a
 156  * radius packet. The packet will have a randomized id. If cb is not NULL, it
 157  * will be called passing data as the argument to iterate over a set of
 158  * outstanding requests. In this case, the id will be both random and unique
 159  * across the set of requests.
 160  */
 161 krb5_error_code
 162 krad_packet_new_request(krb5_context ctx, const char *secret, krad_code code,
 163                         const krad_attrset *set, krad_packet_iter_cb cb,
 164                         void *data, krad_packet **request);
 165
 166 /*
 167  * Create a new response packet.
 168  *
 169  * This function is similar to krad_packet_new_requst() except that it crafts a
 170  * packet in response to a request packet. This new packet will borrow values
 171  * from the request such as the id and the authenticator.
 172  */
 173 krb5_error_code
 174 krad_packet_new_response(krb5_context ctx, const char *secret, krad_code code,
 175                          const krad_attrset *set, const krad_packet *request,
 176                          krad_packet **response);
 177
 178 /*
 179  * Decode a request radius packet from krb5_data.
 180  *
 181  * The resulting decoded packet will be a request packet stored in *reqpkt.
 182  *
 183  * If cb is NULL, *duppkt will always be NULL.
 184  *
 185  * If cb is not NULL, it will be called (with the data argument) to iterate
 186  * over a set of requests currently being processed. In this case, if the
 187  * packet is a duplicate of an already received request, the original request
 188  * will be set in *duppkt.
 189  */
 190 krb5_error_code
 191 krad_packet_decode_request(krb5_context ctx, const char *secret,
 192                            const krb5_data *buffer, krad_packet_iter_cb cb,
 193                            void *data, const krad_packet **duppkt,
 194                            krad_packet **reqpkt);
 195
 196 /*
 197  * Decode a response radius packet from krb5_data.
 198  *
 199  * The resulting decoded packet will be a response packet stored in *rsppkt.
 200  *
 201  * If cb is NULL, *reqpkt will always be NULL.
 202  *
 203  * If cb is not NULL, it will be called (with the data argument) to iterate
 204  * over a set of requests awaiting responses. In this case, if the response
 205  * packet matches one of these requests, the original request will be set in
 206  * *reqpkt.
 207  */
 208 krb5_error_code
 209 krad_packet_decode_response(krb5_context ctx, const char *secret,
 210                             const krb5_data *buffer, krad_packet_iter_cb cb,
 211                             void *data, const krad_packet **reqpkt,
 212                             krad_packet **rsppkt);
 213
 214 /* Encode packet. */
 215 const krb5_data *
 216 krad_packet_encode(const krad_packet *pkt);
 217
 218 /* Get the code for the given packet. */
 219 krad_code
 220 krad_packet_get_code(const krad_packet *pkt);
 221
 222 /* Get the specified attribute. */
 223 const krb5_data *
 224 krad_packet_get_attr(const krad_packet *pkt, krad_attr type, size_t indx);
 225
 226 /*
 227  * Client
 228  */
 229
 230 /* Create a new client. */
 231 krb5_error_code
 232 krad_client_new(krb5_context kctx, verto_ctx *vctx, krad_client **client);
 233
 234 /* Free the client. */
 235 void
 236 krad_client_free(krad_client *client);
 237
 238 /*
 239  * Send a request to a radius server.
 240  *
 241  * The remote host may be specified by one of the following formats:
 242  *  - /path/to/unix.socket
 243  *  - IPv4
 244  *  - IPv4:port
 245  *  - IPv4:service
 246  *  - [IPv6]
 247  *  - [IPv6]:port
 248  *  - [IPv6]:service
 249  *  - hostname
 250  *  - hostname:port
 251  *  - hostname:service
 252  *
 253  * The timeout parameter (milliseconds) is the total timeout across all remote
 254  * hosts (when DNS returns multiple entries) and all retries.  For stream
 255  * sockets, the retries parameter is ignored and no retries are performed.
 256  *
 257  * The cb function will be called with the data argument when either a response
 258  * is received or the request times out on all possible remote hosts.
 259  */
 260 krb5_error_code
 261 krad_client_send(krad_client *rc, krad_code code, const krad_attrset *attrs,
 262                  const char *remote, const char *secret, int timeout,
 263                  size_t retries, krad_cb cb, void *data);
 264
 265 #endif /* KRAD_H_ */