5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2002 - 2007 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 /* SilcMime */
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 /* SilcMime */
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 /* SilcMime */
86 #define SILC_ATTRIBUTE_PHONE_NUMBER 17 /* SilcAttributeObjPN */
89 /* Maximum length of attribute request packet */
90 #define SILC_ATTRIBUTE_MAX_REQUEST_LEN (4 * 255)
92 /****d* silccore/SilcAttributesAPI/SilcAttributeFlags
96 * typedef SilcUInt8 SilcAttributeFlags;
100 * Attribute Payload flags defined by the specification.
104 typedef SilcUInt8 SilcAttributeFlags;
106 /* All defined flags */
107 #define SILC_ATTRIBUTE_FLAG_NONE 0x00 /* No flags */
108 #define SILC_ATTRIBUTE_FLAG_INVALID 0x01 /* Invalid attribute */
109 #define SILC_ATTRIBUTE_FLAG_VALID 0x02 /* Valid attribute */
112 /****d* silccore/SilcAttributesAPI/SilcAttributeMood
116 * typedef enum { ... } SilcAttributeMood;
120 * The user mood indicators defined by the specification. This is
126 SILC_ATTRIBUTE_MOOD_NORMAL = 0x00000000, /* normal mood */
127 SILC_ATTRIBUTE_MOOD_HAPPY = 0x00000001, /* user feel happy */
128 SILC_ATTRIBUTE_MOOD_SAD = 0x00000002, /* user feel sad */
129 SILC_ATTRIBUTE_MOOD_ANGRY = 0x00000004, /* user feel angry */
130 SILC_ATTRIBUTE_MOOD_JEALOUS = 0x00000008, /* user feel jealous */
131 SILC_ATTRIBUTE_MOOD_ASHAMED = 0x00000010, /* user feel ashamed */
132 SILC_ATTRIBUTE_MOOD_INVINCIBLE = 0x00000020, /* user feel invincible */
133 SILC_ATTRIBUTE_MOOD_INLOVE = 0x00000040, /* user feel in love */
134 SILC_ATTRIBUTE_MOOD_SLEEPY = 0x00000080, /* user feel sleepy */
135 SILC_ATTRIBUTE_MOOD_BORED = 0x00000100, /* user feel bored */
136 SILC_ATTRIBUTE_MOOD_EXCITED = 0x00000200, /* user feel exited */
137 SILC_ATTRIBUTE_MOOD_ANXIOUS = 0x00000400, /* user feel anxious */
141 /****d* silccore/SilcAttributesAPI/SilcAttributeContact
145 * typedef enum { ... } SilcAttributeContact;
149 * The defined preferred contact methods defined by the specification.
155 SILC_ATTRIBUTE_CONTACT_NONE = 0x00000000, /* no specific method */
156 SILC_ATTRIBUTE_CONTACT_EMAIL = 0x00000001, /* email preferred */
157 SILC_ATTRIBUTE_CONTACT_CALL = 0x00000002, /* phone call preferred */
158 SILC_ATTRIBUTE_CONTACT_PAGE = 0x00000004, /* "paging" preferred */
159 SILC_ATTRIBUTE_CONTACT_SMS = 0x00000008, /* SMS preferred */
160 SILC_ATTRIBUTE_CONTACT_MMS = 0x00000010, /* MMS preferred */
161 SILC_ATTRIBUTE_CONTACT_CHAT = 0x00000020, /* chatting preferred */
162 SILC_ATTRIBUTE_CONTACT_VIDEO = 0x00000040, /* video conferencing */
163 } SilcAttributeContact;
166 /****d* silccore/SilcAttributesAPI/SilcAttributeDevice
170 * typedef enum { ... } SilcAttributeDevice;
174 * The defined device types defined by the specification.
179 SILC_ATTRIBUTE_DEVICE_COMPUTER = 0, /* device is computer */
180 SILC_ATTRIBUTE_DEVICE_MOBILE_PHONE = 1, /* device is mobile phone */
181 SILC_ATTRIBUTE_DEVICE_PDA = 2, /* device is PDA */
182 SILC_ATTRIBUTE_DEVICE_TERMINAL = 3, /* device is terminal */
183 } SilcAttributeDevice;
186 /****d* silccore/SilcAttributesAPI/SilcAttributePNFormat
190 * typedef enum { ... } SilcAttributePNFormat;
194 * The defined phone number formats.
199 SILC_ATTRIBUTE_NUMBER_ITU_E164 = 0, /* ITU E.164 */
200 SILC_ATTRIBUTE_NUMBER_ITU_E123_PHONE = 1, /* ITU E.123 */
201 SILC_ATTRIBUTE_NUMBER_ENUM = 2, /* ENUM, RFC 3761 */
202 } SilcAttributePNFormat;
205 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_alloc
209 * SilcAttributesPayload
210 * silc_attribute_payload_alloc(SilcAttribute attribute,
211 * SilcAttributeFlags flags,
213 * SilcUInt32 object_size);
217 * Allocates and encodes the attribute indicated by `attribute' and
218 * returns pointer to the attribute.
220 * The `object' must always be the same data type as defined with
221 * SilcAttribute (see the comments) for all attributes.
224 SilcAttributePayload silc_attribute_payload_alloc(SilcAttribute attribute,
225 SilcAttributeFlags flags,
227 SilcUInt32 object_size);
229 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse
234 * silc_attribute_payload_parse(const unsigned char *payload,
235 * SilcUInt32 payload_len);
239 * Parses list of Attribute payloads returning list of payloads.
240 * One entry in the returned list is SilcAttributesPayload. You
241 * can produce such a list with silc_attribute_payload_encode
245 SilcDList silc_attribute_payload_parse(const unsigned char *payload,
246 SilcUInt32 payload_len);
248 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode
252 * SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
253 * SilcAttribute attribute,
254 * SilcAttributeFlags flags,
256 * SilcUInt32 object_size);
260 * Encodes one attribute payload into the `attrs' buffer and returns
261 * pointer to the buffer, which may be different in case the buffer
262 * was reallocated. If `attrs' is NULL for first attribute this
263 * allocates the buffer and returns it. This can be called multiple
264 * times to add multiple attributes to the `attrs' buffer. The `flags'
265 * indicates the validity of the added attribute. Returns NULL on
268 * The `object' must always be the same data type as defined with
269 * SilcAttribute (see the comments) for all attributes.
272 SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs,
273 SilcAttribute attribute,
274 SilcAttributeFlags flags,
276 SilcUInt32 object_size);
278 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_data
283 * silc_attribute_payload_encode_data(SilcBuffer attrs,
284 * SilcAttribute attribute,
285 * SilcAttributeFlags flags,
286 * const unsigned char *data,
287 * SilcUInt32 data_len);
291 * Same function as silc_attribute_payload_encode except the attribute
292 * is already encoded into `data' of `data_len' bytes in length.
293 * Encodes the attribute into the `attrs' buffer and returns pointer
294 * to the buffer, which may be different in case the buffer was
295 * reallocated. If `attrs' is NULL for first attribute this allocates
296 * the buffer and returns it. Returns NULL on error.
299 SilcBuffer silc_attribute_payload_encode_data(SilcBuffer attrs,
300 SilcAttribute attribute,
301 SilcAttributeFlags flags,
302 const unsigned char *data,
303 SilcUInt32 data_len);
305 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free
309 * void silc_attribute_payload_free(SilcAttributePayload payload);
313 * Frees the Attribute Payload and all data in it.
316 void silc_attribute_payload_free(SilcAttributePayload payload);
318 /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free
322 * void silc_attribute_payload_list_free(SilcDList list);
326 * Frees list of Attribute Payloads and all data in them.
329 void silc_attribute_payload_list_free(SilcDList list);
331 /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute
335 * SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
339 * Return the attribute type from the payload indicated by `payload'.
342 SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload);
344 /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags
349 * silc_attribute_get_flags(SilcAttributePayload payload);
353 * Return the attribute flags from the payload indicated by `payload'.
356 SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload);
358 /****f* silccore/SilcAttributesAPI/silc_attribute_get_data
362 * const unsigned char *
363 * silc_attribute_get_data(SilcAttributePayload payload,
364 * SilcUInt32 *data_len);
368 * Returns the attribute data from the payload indicated by the `payload'
369 * The caller must not free the returned data pointer.
372 const unsigned char *silc_attribute_get_data(SilcAttributePayload payload,
373 SilcUInt32 *data_len);
375 /****f* silccore/SilcAttributesAPI/silc_attribute_get_verify_data
380 * silc_attribute_get_verify_data(SilcDList attrs,
381 * SilcBool server_verification,
382 * SilcUInt32 *data_len);
386 * Constructs the data to be verified with the sender's digital
387 * signature and sender's public key. This allocates the data from
388 * the list of attribute payloads and returns the buffer. The caller
389 * must free it. If `server_verification' is FALSE then data is
390 * constructed for user's digital signature verification, if it is
391 * TRUE then it is constructed for server's digital signature
395 unsigned char *silc_attribute_get_verify_data(SilcDList attrs,
396 SilcBool server_verification,
397 SilcUInt32 *data_len);
399 /* Object structures */
401 /****s* silccore/SilcAttributesAPI/SilcAttributeObjService
405 * typedef struct { ... } SilcAttributeObjService;
409 * SILC_ATTRIBUTE_SERVICE type object structure.
413 typedef struct SilcAttributeObjServiceStruct {
414 SilcUInt32 port; /* IANA specified service port */
415 SilcUInt32 idle; /* Idle time in the service */
416 char signon[64]; /* Signon date and time (UTC) */
417 char address[256]; /* service address */
418 SilcBool status; /* online status (TRUE present in service) */
419 } SilcAttributeObjService;
422 /****s* silccore/SilcAttributesAPI/SilcAttributeObjGeo
426 * typedef struct { ... } SilcAttributeObjGeo;
430 * SILC_ATTRIBUTE_GEOLOCATION type object. The caller must free the
431 * strings inside the structure.
435 typedef struct SilcAttributeObjGeoStruct {
436 char *longitude; /* Longitude */
437 char *latitude; /* Latitude */
438 char *altitude; /* Altitude */
439 char *accuracy; /* Accuracy in meters */
440 } SilcAttributeObjGeo;
443 /****s* silccore/SilcAttributesAPI/SilcAttributeObjDevice
447 * typedef struct { ... } SilcAttributeObjDevice;
451 * SILC_ATTRIBUTE_DEVICE_INFO type object. The caller must free the
452 * strings inside the structure.
456 typedef struct SilcAttributeObjDeviceStruct {
457 SilcAttributeDevice type; /* device type */
458 char *manufacturer; /* manufacturer of the device */
459 char *version; /* device version string */
460 char *model; /* device model string */
461 char *language; /* device language (ISO 639-2/T) */
462 } SilcAttributeObjDevice;
465 /****s* silccore/SilcAttributesAPI/SilcAttributeObjPk
469 * typedef struct { ... } SilcAttributeObjPk;
473 * Data type for public key, certificate or digital signatures. The
474 * caller must free the data inside the structure. The 'type' is one
475 * of following: "silc-rsa", "silc-dss, "ssh-rsa", "ssh-dss",
476 * "pgp-sign-rsa", "pgp-sign-dss", "x509v3-sign-rsa", "x509v3-sign-dss".
477 * The 'type' is NULL when this structure includes a digital signature.
479 * In SILC, at least the "silc-rsa" must be supported. In this case
480 * the key is normal SILC Public key. To verify a signature with the
481 * SILC Public key, construct the signature data with the
482 * silc_attribute_get_verify_data and verify the signature with
483 * for example silc_pkcs_verify_with_hash function. The public key
484 * to the verification is the `data' and `data_len', and can be decoded
485 * with silc_pkcs_public_key_decode function.
489 typedef struct SilcAttributeObjPkStruct {
490 char *type; /* public key/certificate type, NULL
491 when contains digital signature. */
492 unsigned char *data; /* public key/cert/signature data. The
493 encoding depends of the `type'. */
494 SilcUInt32 data_len; /* data length */
495 } SilcAttributeObjPk;
498 /****s* silccore/SilcAttributesAPI/SilcAttributeObjPN
502 * typedef struct { ... } SilcAttributeObjPN;
506 * SILC_ATTRIBUTE_PHONE_NUMBER type object. The caller must free the
507 * phone number string inside the structure.
511 typedef struct SilcAttributeObjPNStruct {
512 SilcAttributePNFormat format; /* Phone number format */
513 char *number; /* Phone number */
514 } SilcAttributeObjPN;
517 /****f* silccore/SilcAttributesAPI/silc_attribute_get_object
521 * SilcBool silc_attribute_get_object(SilcAttributePayload payload,
523 * SilcUInt32 object_size);
527 * Returns the already parsed attribute object from the payload
528 * indicated by `payload'. Copies the data into the `object' which
529 * must be sent as argument (and must be of correct type and size).
530 * The `object_size' indicates the size of the `*object' sent.
531 * Returns TRUE if the `attribute' attribute was found and FALSE
532 * if such attribute is not present in the `payload', or the `object_size'
533 * is not sufficient. See the definition of SilcAttribute for the
534 * list of attributes and the required object types for attributes.
535 * You can use silc_attribute_get_attribute to get the SilcAttribute
536 * type from the `payload'.
540 * SilcAttributeObjDevice dev;
543 * case SILC_ATTRIBUTE_DEVICE_INFO:
544 * memset(&dev, 0, sizeof(dev));
545 * if (!silc_attribute_get_object(payload, (void *)&dev, sizeof(dev)))
548 * case SILC_ATTRIBUTE_USER_ICON:
549 * mime = silc_mime_alloc();
550 * if (!silc_attribute_get_object(payload, (void *)mime, sizeof(*mime)))
555 SilcBool silc_attribute_get_object(SilcAttributePayload payload,
556 void *object, SilcUInt32 object_size);
558 #endif /* SILCATTRS_H */