5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 - 2003 Pekka Riikonen
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; version 2 of the License.
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
20 /****h* silccore/SILC Attribute Interface
24 * Implementation of the Attribute Payload that may be used to send and
25 * retrieve user online precense information in the SILC network. This
26 * implements the draft-riikonen-precense-attrs draft.
33 /****s* silccore/SilcAttributesAPI/SilcAttributePayload
37 * typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
41 * This context is the actual Attribute Payload and is allocated
42 * by silc_attribute_payload_parse and given as attribute usually to
43 * all silc_attribute_payload_* functions. It is freed by the
44 * silc_attribute_payload_free function.
47 typedef struct SilcAttributePayloadStruct *SilcAttributePayload;
49 /****d* silccore/SilcAttributesAPI/SilcAttribute
53 * typedef SilcUInt8 SilcAttribute;
57 * The SilcAttribute type definition and the attributes. The attributes
58 * listed here are the official attributes defined in the internet
59 * draft. They define the contents of the attribute payload and the
60 * type of the attribute.
64 typedef SilcUInt8 SilcAttribute;
66 /* All defined attributes. See the specs for detailed information. The
67 comment is the structure or data type that must be used with the
68 silc_attribute_get_object function to fetch parsed attribute. */
69 #define SILC_ATTRIBUTE_NONE 0
70 #define SILC_ATTRIBUTE_USER_INFO 1 /* SilcVCard */
71 #define SILC_ATTRIBUTE_SERVICE 2 /* SilcAttributeObjService */
72 #define SILC_ATTRIBUTE_STATUS_MOOD 3 /* SilcAttributeMood */
73 #define SILC_ATTRIBUTE_STATUS_FREETEXT 4 /* char * (UTF-8 string) */
74 #define SILC_ATTRIBUTE_STATUS_MESSAGE 5 /* SilcAttributeObjMime */
75 #define SILC_ATTRIBUTE_PREFERRED_LANGUAGE 6 /* char * (UTF-8 string) */
76 #define SILC_ATTRIBUTE_PREFERRED_CONTACT 7 /* SilcAttributeContact */
77 #define SILC_ATTRIBUTE_TIMEZONE 8 /* char * (UTF-8 string) */
78 #define SILC_ATTRIBUTE_GEOLOCATION 9 /* SilcAttributeObjGeo */
79 #define SILC_ATTRIBUTE_DEVICE_INFO 10 /* SilcAttributeObjDevice */
80 #define SILC_ATTRIBUTE_EXTENSION 11 /* SilcAttributeObjMime */
81 #define SILC_ATTRIBUTE_USER_PUBLIC_KEY 12 /* SilcAttributeObjPk */
82 #define SILC_ATTRIBUTE_SERVER_PUBLIC_KEY 13 /* SilcAttributeObjPk */
83 #define SILC_ATTRIBUTE_USER_DIGITAL_SIGNATURE 14 /* SilcAttributeObjPk */
84 #define SILC_ATTRIBUTE_SERVER_DIGITAL_SIGNATURE 15 /* SilcAttributeObjPk */
85 #define SILC_ATTRIBUTE_USER_ICON 16 /* SilcAttributeObjMime */
88 /* Maximum length of attribute request packet */
89 #define SILC_ATTRIBUTE_MAX_REQUEST_LEN (4 * 255)
91 /****d* silccore/SilcAttributesAPI/SilcAttributeFlags
95 * typedef SilcUInt8 SilcAttributeFlags;
99 * Attribute Payload flags defined by the specification.
103 typedef SilcUInt8 SilcAttributeFlags;
105 /* All defined flags */
106 #define SILC_ATTRIBUTE_FLAG_NONE 0x00 /* No flags */
107 #define SILC_ATTRIBUTE_FLAG_INVALID 0x01 /* Invalid attribute */
108 #define SILC_ATTRIBUTE_FLAG_VALID 0x02 /* Valid attribute */
111 /****d* silccore/SilcAttributesAPI/SilcAttributeMood
115 * typedef enum { ... } SilcAttributeMood;
119 * The user mood indicators defined by the specification. This is
125 SILC_ATTRIBUTE_MOOD_NORMAL = 0x00000000, /* normal mood */
126 SILC_ATTRIBUTE_MOOD_HAPPY = 0x00000001, /* user feel happy */
127 SILC_ATTRIBUTE_MOOD_SAD = 0x00000002, /* user feel sad */
128 SILC_ATTRIBUTE_MOOD_ANGRY = 0x00000004, /* user feel angry */
129 SILC_ATTRIBUTE_MOOD_JEALOUS = 0x00000008, /* user feel jealous */
130 SILC_ATTRIBUTE_MOOD_ASHAMED = 0x00000010, /* user feel ashamed */
131 SILC_ATTRIBUTE_MOOD_INVINCIBLE = 0x00000020, /* user feel invincible */
132 SILC_ATTRIBUTE_MOOD_INLOVE = 0x00000040, /* user feel in love */
133 SILC_ATTRIBUTE_MOOD_SLEEPY = 0x00000080, /* user feel sleepy */
134 SILC_ATTRIBUTE_MOOD_BORED = 0x00000100, /* user feel bored */
135 SILC_ATTRIBUTE_MOOD_EXCITED = 0x00000200, /* user feel exited */
136 SILC_ATTRIBUTE_MOOD_ANXIOUS = 0x00000400, /* user feel anxious */
140 /****d* silccore/SilcAttributesAPI/SilcAttributeContact
144 * typedef enum { ... } SilcAttributeContact;
148 * The defined preferred contact methods defined by the specification.
154 SILC_ATTRIBUTE_CONTACT_NONE = 0x00000000, /* no specific method */
155 SILC_ATTRIBUTE_CONTACT_EMAIL = 0x00000001, /* email preferred */
156 SILC_ATTRIBUTE_CONTACT_CALL = 0x00000002, /* phone call preferred */
157 SILC_ATTRIBUTE_CONTACT_PAGE = 0x00000004, /* "paging" preferred */
158 SILC_ATTRIBUTE_CONTACT_SMS = 0x00000008, /* SMS preferred */
159 SILC_ATTRIBUTE_CONTACT_MMS = 0x00000010, /* MMS preferred */
160 SILC_ATTRIBUTE_CONTACT_CHAT = 0x00000020, /* chatting preferred */
161 SILC_ATTRIBUTE_CONTACT_VIDEO = 0x00000040, /* video conferencing */
162 } SilcAttributeContact;
165 /****d* silccore/SilcAttributesAPI/SilcAttributeDevice
169 * typedef enum { ... } SilcAttributeDevice;
173 * The defined device types defined by the specification.
178 SILC_ATTRIBUTE_DEVICE_COMPUTER = 0, /* device is computer */
179 SILC_ATTRIBUTE_DEVICE_MOBILE_PHONE = 1, /* device is mobile phone */
180 SILC_ATTRIBUTE_DEVICE_PDA = 2, /* device is PDA */
181 SILC_ATTRIBUTE_DEVICE_TERMINAL = 3, /* device is terminal */
182 } SilcAttributeDevice;
185 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_alloc
189 * SilcAttributesPayload
190 * silc_attribute_payload_alloc(SilcAttribute attribute,
191 * SilcAttributeFlags flags,
193 * SilcUInt32 object_size);
197 * Allocates and encodes the attribute indicated by `attribute' and
198 * returns pointer to the attribute.
200 * The `object' must always be the same data type as defined with
201 * SilcAttribute (see the comments) for all attributes.
204 SilcAttributePayload silc_attribute_payload_alloc(SilcAttribute attribute,
205 SilcAttributeFlags flags,
207 SilcUInt32 object_size);
209 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse
214 * silc_attribute_payload_parse(const unsigned char *payload,
215 * SilcUInt32 payload_len);
219 * Parses list of Attribute payloads returning list of payloads.
220 * One entry in the returned list is SilcAttributesPayload. You
221 * can produce such a list with silc_attribute_payload_encode
225 SilcDList silc_attribute_payload_parse(const unsigned char *payload,
226 SilcUInt32 payload_len);
228 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode
232 * SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
233 * SilcAttribute attribute,
234 * SilcAttributeFlags flags,
236 * SilcUInt32 object_size);
240 * Encodes one attribute payload into the `attrs' buffer and returns
241 * pointer to the buffer, which may be different in case the buffer
242 * was reallocated. If `attrs' is NULL for first attribute this
243 * allocates the buffer and returns it. This can be called multiple
244 * times to add multiple attributes to the `attrs' buffer. The `flags'
245 * indicates the validity of the added attribute. Returns NULL on
248 * The `object' must always be the same data type as defined with
249 * SilcAttribute (see the comments) for all attributes.
252 SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
253 SilcAttribute attribute,
254 SilcAttributeFlags flags,
256 SilcUInt32 object_size);
258 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_data
263 * silc_attribute_payload_encode_data(SilcBuffer attrs,
264 * SilcAttribute attribute,
265 * SilcAttributeFlags flags,
266 * const unsigned char *data,
267 * SilcUInt32 data_len);
271 * Same function as silc_attribute_payload_encode except the attribute
272 * is already encoded into `data' of `data_len' bytes in length.
273 * Encodes the attribute into the `attrs' buffer and returns pointer
274 * to the buffer, which may be different in case the buffer was
275 * reallocated. If `attrs' is NULL for first attribute this allocates
276 * the buffer and returns it. Returns NULL on error.
279 SilcBuffer silc_attribute_payload_encode_data(SilcBuffer attrs,
280 SilcAttribute attribute,
281 SilcAttributeFlags flags,
282 const unsigned char *data,
283 SilcUInt32 data_len);
285 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free
289 * void silc_attribute_payload_free(SilcAttributePayload payload);
293 * Frees the Attribute Payload and all data in it.
296 void silc_attribute_payload_free(SilcAttributePayload payload);
298 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free
302 * void silc_attribute_payload_list_free(SilcDList list);
306 * Frees list of Attribute Payloads and all data in them.
309 void silc_attribute_payload_list_free(SilcDList list);
311 /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute
315 * SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
319 * Return the attribute type from the payload indicated by `payload'.
322 SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
324 /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags
329 * silc_attribute_get_flags(SilcAttributePayload payload);
333 * Return the attribute flags from the payload indicated by `payload'.
336 SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload);
338 /****f* silccore/SilcAttributesAPI/silc_attribute_get_data
342 * const unsigned char *
343 * silc_attribute_get_data(SilcAttributePayload payload,
344 * SilcUInt32 *data_len);
348 * Returns the attribute data from the payload indicated by the `payload'
349 * The caller must not free the returned data pointer.
352 const unsigned char *silc_attribute_get_data(SilcAttributePayload payload,
353 SilcUInt32 *data_len);
355 /****f* silccore/SilcAttributesAPI/silc_attribute_get_verify_data
360 * silc_attribute_get_verify_data(SilcDList attrs,
361 * bool server_verification,
362 * SilcUInt32 *data_len);
366 * Constructs the data to be verified with the sender's digital
367 * signature and sender's public key. This allocates the data from
368 * the list of attribute payloads and returns the buffer. The caller
369 * must free it. If `server_verification' is FALSE then data is
370 * constructed for user's digital signature verification, if it is
371 * TRUE then it is constructed for server's digital signature
375 unsigned char *silc_attribute_get_verify_data(SilcDList attrs,
376 bool server_verification,
377 SilcUInt32 *data_len);
379 /* Object structures */
381 /****s* silccore/SilcAttributesAPI/SilcAttributeObjService
385 * typedef struct { ... } SilcAttributeObjService;
389 * SILC_ATTRIBUTE_SERVICE type object structure.
393 typedef struct SilcAttributeObjServiceStruct {
394 SilcUInt32 port; /* IANA specified service port */
395 SilcUInt32 idle; /* Idle time in the service */
396 char signon[64]; /* Signon date and time (UTC) */
397 char address[256]; /* service address */
398 bool status; /* online status (TRUE present in service) */
399 } SilcAttributeObjService;
402 /****s* silccore/SilcAttributesAPI/SilcAttributeObjMime
406 * typedef struct { ... } SilcAttributeObjMime;
410 * Data type for MIME object as attribute. The data in the structure
411 * is valid as long as the payload structure is valid.
415 typedef struct SilcAttributeObjMimeStruct {
416 const unsigned char *mime; /* MIME buffer */
417 SilcUInt32 mime_len; /* length of the MIME buffer */
418 } SilcAttributeObjMime;
421 /****s* silccore/SilcAttributesAPI/SilcAttributeObjGeo
425 * typedef struct { ... } SilcAttributeObjGeo;
429 * SILC_ATTRIBUTE_GEOLOCATION type object. The caller must free the
430 * strings inside the structure.
434 typedef struct SilcAttributeObjGeoStruct {
435 char *longitude; /* Longitude */
436 char *latitude; /* Latitude */
437 char *altitude; /* Altitude */
438 char *accuracy; /* Accuracy in meters */
439 } SilcAttributeObjGeo;
442 /****s* silccore/SilcAttributesAPI/SilcAttributeObjDevice
446 * typedef struct { ... } SilcAttributeObjDevice;
450 * SILC_ATTRIBUTE_DEVICE_INFO type object. The caller must free the
451 * strings inside the structure.
455 typedef struct SilcAttributeObjDeviceStruct {
456 SilcAttributeDevice type; /* device type */
457 char *manufacturer; /* manufacturer of the device */
458 char *version; /* device version string */
459 char *model; /* device model string */
460 char *language; /* device language (ISO 639-2/T) */
461 } SilcAttributeObjDevice;
464 /****s* silccore/SilcAttributesAPI/SilcAttributeObjPk
468 * typedef struct { ... } SilcAttributeObjPk;
472 * Data type for public key, certificate or digital signatures. The
473 * caller must free the data inside the structure. The 'type' is one
474 * of following: "silc-rsa", "silc-dss, "ssh-rsa", "ssh-dss",
475 * "pgp-sign-rsa", "pgp-sign-dss", "x509v3-sign-rsa", "x509v3-sign-dss".
476 * See the draft-riikonen-precense-attrs draft for more detailed
477 * information. The 'type' is NULL when this structure includes a
480 * In SILC, at least the "silc-rsa" must be supported. In this case
481 * the key is normal SILC Public key. To verify a signature with the
482 * SILC Public key, construct the signature data with the
483 * silc_attribute_get_verify_data and verify the signature with
484 * for example silc_pkcs_verify_with_hash function. The public key
485 * to the verification is the `data' and `data_len', and can be decoded
486 * with silc_pkcs_public_key_decode function.
490 typedef struct SilcAttributeObjPkStruct {
491 char *type; /* public key/certificate type, NULL
492 when contains digital signature. */
493 unsigned char *data; /* public key/cert/signature data. The
494 encoding depends of the `type'. */
495 SilcUInt32 data_len; /* data length */
496 } SilcAttributeObjPk;
499 /****f* silccore/SilcAttributesAPI/silc_attribute_get_object
503 * bool silc_attribute_get_object(SilcAttributePayload payload,
505 * SilcUInt32 object_size);
509 * Returns the already parsed attribute object from the payload
510 * indicated by `payload'. Copies the data into the `object' which
511 * must be sent as argument (and must be of correct type and size).
512 * The `object_size' indicates the size of the `*object' sent.
513 * Returns TRUE if the `attribute' attribute was found and FALSE
514 * if such attribute is not present in the `payload', or the `object_size'
515 * is not sufficient. See the definition of SilcAttribute for the
516 * list of attributes and the required object types for attributes.
517 * You can use silc_attribute_get_attribute to get the SilcAttribute
518 * type from the `payload'.
522 * SilcAttributeObjDevice dev;
525 * case SILC_ATTRIBUTE_DEVICE_INFO:
526 * memset(&dev, 0, sizeof(dev));
527 * if (!silc_attribute_get_object(payload, (void *)&dev, sizeof(dev)))
532 bool silc_attribute_get_object(SilcAttributePayload payload,
533 void *object, SilcUInt32 object_size);
535 #endif /* SILCATTRS_H */