/* silcattrs.h Author: Pekka Riikonen Copyright (C) 2002 - 2007 Pekka Riikonen This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 of the License. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. */ /****h* silccore/SILC Attribute Interface * * DESCRIPTION * * Implementation of the Attribute Payload that may be used to send and * retrieve user online precense information in the SILC network. This * implements the draft-riikonen-precense-attrs draft. * ***/ #ifndef SILCATTRS_H #define SILCATTRS_H /****s* silccore/SilcAttributesAPI/SilcAttributePayload * * NAME * * typedef struct SilcAttributePayloadStruct *SilcAttributePayload; * * DESCRIPTION * * This context is the actual Attribute Payload and is allocated * by silc_attribute_payload_parse and given as attribute usually to * all silc_attribute_payload_* functions. It is freed by the * silc_attribute_payload_free function. * ***/ typedef struct SilcAttributePayloadStruct *SilcAttributePayload; /****d* silccore/SilcAttributesAPI/SilcAttribute * * NAME * * typedef SilcUInt8 SilcAttribute; * * DESCRIPTION * * The SilcAttribute type definition and the attributes. The attributes * listed here are the official attributes defined in the internet * draft. They define the contents of the attribute payload and the * type of the attribute. * * SOURCE */ typedef SilcUInt8 SilcAttribute; /* All defined attributes. See the specs for detailed information. The comment is the structure or data type that must be used with the silc_attribute_get_object function to fetch parsed attribute. */ #define SILC_ATTRIBUTE_NONE 0 #define SILC_ATTRIBUTE_USER_INFO 1 /* SilcVCard */ #define SILC_ATTRIBUTE_SERVICE 2 /* SilcAttributeObjService */ #define SILC_ATTRIBUTE_STATUS_MOOD 3 /* SilcAttributeMood */ #define SILC_ATTRIBUTE_STATUS_FREETEXT 4 /* char * (UTF-8 string) */ #define SILC_ATTRIBUTE_STATUS_MESSAGE 5 /* SilcMime */ #define SILC_ATTRIBUTE_PREFERRED_LANGUAGE 6 /* char * (UTF-8 string) */ #define SILC_ATTRIBUTE_PREFERRED_CONTACT 7 /* SilcAttributeContact */ #define SILC_ATTRIBUTE_TIMEZONE 8 /* char * (UTF-8 string) */ #define SILC_ATTRIBUTE_GEOLOCATION 9 /* SilcAttributeObjGeo */ #define SILC_ATTRIBUTE_DEVICE_INFO 10 /* SilcAttributeObjDevice */ #define SILC_ATTRIBUTE_EXTENSION 11 /* SilcMime */ #define SILC_ATTRIBUTE_USER_PUBLIC_KEY 12 /* SilcAttributeObjPk */ #define SILC_ATTRIBUTE_SERVER_PUBLIC_KEY 13 /* SilcAttributeObjPk */ #define SILC_ATTRIBUTE_USER_DIGITAL_SIGNATURE 14 /* SilcAttributeObjPk */ #define SILC_ATTRIBUTE_SERVER_DIGITAL_SIGNATURE 15 /* SilcAttributeObjPk */ #define SILC_ATTRIBUTE_USER_ICON 16 /* SilcMime */ #define SILC_ATTRIBUTE_PHONE_NUMBER 17 /* SilcAttributeObjPN */ /***/ /* Maximum length of attribute request packet */ #define SILC_ATTRIBUTE_MAX_REQUEST_LEN (4 * 255) /****d* silccore/SilcAttributesAPI/SilcAttributeFlags * * NAME * * typedef SilcUInt8 SilcAttributeFlags; * * DESCRIPTION * * Attribute Payload flags defined by the specification. * * SOURCE */ typedef SilcUInt8 SilcAttributeFlags; /* All defined flags */ #define SILC_ATTRIBUTE_FLAG_NONE 0x00 /* No flags */ #define SILC_ATTRIBUTE_FLAG_INVALID 0x01 /* Invalid attribute */ #define SILC_ATTRIBUTE_FLAG_VALID 0x02 /* Valid attribute */ /***/ /****d* silccore/SilcAttributesAPI/SilcAttributeMood * * NAME * * typedef enum { ... } SilcAttributeMood; * * DESCRIPTION * * The user mood indicators defined by the specification. This is * bit mask. * * SOURCE */ typedef enum { SILC_ATTRIBUTE_MOOD_NORMAL = 0x00000000, /* normal mood */ SILC_ATTRIBUTE_MOOD_HAPPY = 0x00000001, /* user feel happy */ SILC_ATTRIBUTE_MOOD_SAD = 0x00000002, /* user feel sad */ SILC_ATTRIBUTE_MOOD_ANGRY = 0x00000004, /* user feel angry */ SILC_ATTRIBUTE_MOOD_JEALOUS = 0x00000008, /* user feel jealous */ SILC_ATTRIBUTE_MOOD_ASHAMED = 0x00000010, /* user feel ashamed */ SILC_ATTRIBUTE_MOOD_INVINCIBLE = 0x00000020, /* user feel invincible */ SILC_ATTRIBUTE_MOOD_INLOVE = 0x00000040, /* user feel in love */ SILC_ATTRIBUTE_MOOD_SLEEPY = 0x00000080, /* user feel sleepy */ SILC_ATTRIBUTE_MOOD_BORED = 0x00000100, /* user feel bored */ SILC_ATTRIBUTE_MOOD_EXCITED = 0x00000200, /* user feel exited */ SILC_ATTRIBUTE_MOOD_ANXIOUS = 0x00000400, /* user feel anxious */ } SilcAttributeMood; /***/ /****d* silccore/SilcAttributesAPI/SilcAttributeContact * * NAME * * typedef enum { ... } SilcAttributeContact; * * DESCRIPTION * * The defined preferred contact methods defined by the specification. * This is bit mask. * * SOURCE */ typedef enum { SILC_ATTRIBUTE_CONTACT_NONE = 0x00000000, /* no specific method */ SILC_ATTRIBUTE_CONTACT_EMAIL = 0x00000001, /* email preferred */ SILC_ATTRIBUTE_CONTACT_CALL = 0x00000002, /* phone call preferred */ SILC_ATTRIBUTE_CONTACT_PAGE = 0x00000004, /* "paging" preferred */ SILC_ATTRIBUTE_CONTACT_SMS = 0x00000008, /* SMS preferred */ SILC_ATTRIBUTE_CONTACT_MMS = 0x00000010, /* MMS preferred */ SILC_ATTRIBUTE_CONTACT_CHAT = 0x00000020, /* chatting preferred */ SILC_ATTRIBUTE_CONTACT_VIDEO = 0x00000040, /* video conferencing */ } SilcAttributeContact; /***/ /****d* silccore/SilcAttributesAPI/SilcAttributeDevice * * NAME * * typedef enum { ... } SilcAttributeDevice; * * DESCRIPTION * * The defined device types defined by the specification. * * SOURCE */ typedef enum { SILC_ATTRIBUTE_DEVICE_COMPUTER = 0, /* device is computer */ SILC_ATTRIBUTE_DEVICE_MOBILE_PHONE = 1, /* device is mobile phone */ SILC_ATTRIBUTE_DEVICE_PDA = 2, /* device is PDA */ SILC_ATTRIBUTE_DEVICE_TERMINAL = 3, /* device is terminal */ } SilcAttributeDevice; /***/ /****d* silccore/SilcAttributesAPI/SilcAttributePNFormat * * NAME * * typedef enum { ... } SilcAttributePNFormat; * * DESCRIPTION * * The defined phone number formats. * * SOURCE */ typedef enum { SILC_ATTRIBUTE_NUMBER_ITU_E164 = 0, /* ITU E.164 */ SILC_ATTRIBUTE_NUMBER_ITU_E123 = 1, /* ITU E.123 */ SILC_ATTRIBUTE_NUMBER_ENUM = 2, /* ENUM, RFC 3761 */ } SilcAttributePNFormat; /***/ /****f* silccore/SilcAttributesAPI/silc_attribute_payload_alloc * * SYNOPSIS * * SilcAttributesPayload * silc_attribute_payload_alloc(SilcAttribute attribute, * SilcAttributeFlags flags, * void *object, * SilcUInt32 object_size); * * DESCRIPTION * * Allocates and encodes the attribute indicated by `attribute' and * returns pointer to the attribute. * * The `object' must always be the same data type as defined with * SilcAttribute (see the comments) for all attributes. * ***/ SilcAttributePayload silc_attribute_payload_alloc(SilcAttribute attribute, SilcAttributeFlags flags, void *object, SilcUInt32 object_size); /****f* silccore/SilcAttributesAPI/silc_attribute_payload_parse * * SYNOPSIS * * SilcDList * silc_attribute_payload_parse(const unsigned char *payload, * SilcUInt32 payload_len); * * DESCRIPTION * * Parses list of Attribute payloads returning list of payloads. * One entry in the returned list is SilcAttributesPayload. You * can produce such a list with silc_attribute_payload_encode * function. * ***/ SilcDList silc_attribute_payload_parse(const unsigned char *payload, SilcUInt32 payload_len); /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode * * SYNOPSIS * * SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs, * SilcAttribute attribute, * SilcAttributeFlags flags, * void *object, * SilcUInt32 object_size); * * DESCRIPTION * * Encodes one attribute payload into the `attrs' buffer and returns * pointer to the buffer, which may be different in case the buffer * was reallocated. If `attrs' is NULL for first attribute this * allocates the buffer and returns it. This can be called multiple * times to add multiple attributes to the `attrs' buffer. The `flags' * indicates the validity of the added attribute. Returns NULL on * error. * * The `object' must always be the same data type as defined with * SilcAttribute (see the comments) for all attributes. * ***/ SilcBuffer silc_attribute_payload_encode(SilcBuffer attrs, SilcAttribute attribute, SilcAttributeFlags flags, void *object, SilcUInt32 object_size); /****f* silccore/SilcAttributesAPI/silc_attribute_payload_encode_data * * SYNOPSIS * * SilcBuffer * silc_attribute_payload_encode_data(SilcBuffer attrs, * SilcAttribute attribute, * SilcAttributeFlags flags, * const unsigned char *data, * SilcUInt32 data_len); * * DESCRIPTION * * Same function as silc_attribute_payload_encode except the attribute * is already encoded into `data' of `data_len' bytes in length. * Encodes the attribute into the `attrs' buffer and returns pointer * to the buffer, which may be different in case the buffer was * reallocated. If `attrs' is NULL for first attribute this allocates * the buffer and returns it. Returns NULL on error. * ***/ SilcBuffer silc_attribute_payload_encode_data(SilcBuffer attrs, SilcAttribute attribute, SilcAttributeFlags flags, const unsigned char *data, SilcUInt32 data_len); /****f* silccore/SilcAttributesAPI/silc_attribute_payload_free * * SYNOPSIS * * void silc_attribute_payload_free(SilcAttributePayload payload); * * DESCRIPTION * * Frees the Attribute Payload and all data in it. * ***/ void silc_attribute_payload_free(SilcAttributePayload payload); /****f* silccore/SilcAttributesAPI/silc_attribute_payload_list_free * * SYNOPSIS * * void silc_attribute_payload_list_free(SilcDList list); * * DESCRIPTION * * Frees list of Attribute Payloads and all data in them. * ***/ void silc_attribute_payload_list_free(SilcDList list); /****f* silccore/SilcAttributesAPI/silc_attribute_get_attribute * * SYNOPSIS * * SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload); * * DESCRIPTION * * Return the attribute type from the payload indicated by `payload'. * ***/ SilcAttribute silc_attribute_get_attribute(SilcAttributePayload payload); /****f* silccore/SilcAttributesAPI/silc_attribute_get_flags * * SYNOPSIS * * SilcAttributeFlags * silc_attribute_get_flags(SilcAttributePayload payload); * * DESCRIPTION * * Return the attribute flags from the payload indicated by `payload'. * ***/ SilcAttributeFlags silc_attribute_get_flags(SilcAttributePayload payload); /****f* silccore/SilcAttributesAPI/silc_attribute_get_data * * SYNOPSIS * * const unsigned char * * silc_attribute_get_data(SilcAttributePayload payload, * SilcUInt32 *data_len); * * DESCRIPTION * * Returns the attribute data from the payload indicated by the `payload' * The caller must not free the returned data pointer. * ***/ const unsigned char *silc_attribute_get_data(SilcAttributePayload payload, SilcUInt32 *data_len); /****f* silccore/SilcAttributesAPI/silc_attribute_get_verify_data * * SYNOPSIS * * unsigned char * * silc_attribute_get_verify_data(SilcDList attrs, * SilcBool server_verification, * SilcUInt32 *data_len); * * DESCRIPTION * * Constructs the data to be verified with the sender's digital * signature and sender's public key. This allocates the data from * the list of attribute payloads and returns the buffer. The caller * must free it. If `server_verification' is FALSE then data is * constructed for user's digital signature verification, if it is * TRUE then it is constructed for server's digital signature * verification. * ***/ unsigned char *silc_attribute_get_verify_data(SilcDList attrs, SilcBool server_verification, SilcUInt32 *data_len); /* Object structures */ /****s* silccore/SilcAttributesAPI/SilcAttributeObjService * * NAME * * typedef struct { ... } SilcAttributeObjService; * * DESCRIPTION * * SILC_ATTRIBUTE_SERVICE type object structure. * * SOURCE */ typedef struct SilcAttributeObjServiceStruct { SilcUInt32 port; /* IANA specified service port */ SilcUInt32 idle; /* Idle time in the service */ char signon[64]; /* Signon date and time (UTC) */ char address[256]; /* service address */ SilcBool status; /* online status (TRUE present in service) */ } SilcAttributeObjService; /***/ /****s* silccore/SilcAttributesAPI/SilcAttributeObjGeo * * NAME * * typedef struct { ... } SilcAttributeObjGeo; * * DESCRIPTION * * SILC_ATTRIBUTE_GEOLOCATION type object. The caller must free the * strings inside the structure. * * SOURCE */ typedef struct SilcAttributeObjGeoStruct { char *longitude; /* Longitude */ char *latitude; /* Latitude */ char *altitude; /* Altitude */ char *accuracy; /* Accuracy in meters */ } SilcAttributeObjGeo; /***/ /****s* silccore/SilcAttributesAPI/SilcAttributeObjDevice * * NAME * * typedef struct { ... } SilcAttributeObjDevice; * * DESCRIPTION * * SILC_ATTRIBUTE_DEVICE_INFO type object. The caller must free the * strings inside the structure. * * SOURCE */ typedef struct SilcAttributeObjDeviceStruct { SilcAttributeDevice type; /* device type */ char *manufacturer; /* manufacturer of the device */ char *version; /* device version string */ char *model; /* device model string */ char *language; /* device language (ISO 639-2/T) */ } SilcAttributeObjDevice; /***/ /****s* silccore/SilcAttributesAPI/SilcAttributeObjPk * * NAME * * typedef struct { ... } SilcAttributeObjPk; * * DESCRIPTION * * Data type for public key, certificate or digital signatures. The * caller must free the data inside the structure. The 'type' is one * of following: "silc-rsa", "silc-dss, "ssh-rsa", "ssh-dss", * "pgp-sign-rsa", "pgp-sign-dss", "x509v3-sign-rsa", "x509v3-sign-dss". * The 'type' is NULL when this structure includes a digital signature. * * In SILC, at least the "silc-rsa" must be supported. In this case * the key is normal SILC Public key. To verify a signature with the * SILC Public key, construct the signature data with the * silc_attribute_get_verify_data and verify the signature with * for example silc_pkcs_verify_with_hash function. The public key * to the verification is the `data' and `data_len', and can be decoded * with silc_pkcs_public_key_decode function. * * SOURCE */ typedef struct SilcAttributeObjPkStruct { char *type; /* public key/certificate type, NULL when contains digital signature. */ unsigned char *data; /* public key/cert/signature data. The encoding depends of the `type'. */ SilcUInt32 data_len; /* data length */ } SilcAttributeObjPk; /***/ /****s* silccore/SilcAttributesAPI/SilcAttributeObjPN * * NAME * * typedef struct { ... } SilcAttributeObjPN; * * DESCRIPTION * * SILC_ATTRIBUTE_PHONE_NUMBER type object. The caller must free the * phone number string inside the structure. * * SOURCE */ typedef struct SilcAttributeObjPNStruct { SilcAttributePNFormat format; /* Phone number format */ char *number; /* Phone number */ } SilcAttributeObjPN; /***/ /****f* silccore/SilcAttributesAPI/silc_attribute_get_object * * SYNOPSIS * * SilcBool silc_attribute_get_object(SilcAttributePayload payload, * void *object, * SilcUInt32 object_size); * * DESCRIPTION * * Returns the already parsed attribute object from the payload * indicated by `payload'. Copies the data into the `object' which * must be sent as argument (and must be of correct type and size). * The `object_size' indicates the size of the `*object' sent. * Returns TRUE if the `attribute' attribute was found and FALSE * if such attribute is not present in the `payload', or the `object_size' * is not sufficient. See the definition of SilcAttribute for the * list of attributes and the required object types for attributes. * You can use silc_attribute_get_attribute to get the SilcAttribute * type from the `payload'. * * EXAMPLE * * SilcAttributeObjDevice dev; * * ... * case SILC_ATTRIBUTE_DEVICE_INFO: * memset(&dev, 0, sizeof(dev)); * if (!silc_attribute_get_object(payload, (void *)&dev, sizeof(dev))) * error(); * * case SILC_ATTRIBUTE_USER_ICON: * mime = silc_mime_alloc(); * if (!silc_attribute_get_object(payload, (void *)mime, sizeof(*mime))) * error(); * ... * ***/ SilcBool silc_attribute_get_object(SilcAttributePayload payload, void *object, SilcUInt32 object_size); #endif /* SILCATTRS_H */