Implement SHA-224 and SHA-384 hashes
[libisds.git] / src / isds.h
blobac3f5e68cdac2eaf31b1e4fec39614135e4da93b
1 #ifndef __ISDS_ISDS_H__
2 #define __ISDS_ISDS_H__
4 /* Public interface for libisds.
5 * Private declarations in isds_priv.h. */
7 #include <stdlib.h> /* For size_t */
8 #include <sys/time.h> /* For struct timeval */
10 /* _deprecated macro marks library symbols as deprecated. Application should
11 * avoid using such function as soon as possible. */
12 #if defined(__GNUC__)
13 #define _deprecated __attribute__((deprecated))
14 #else
15 #define _deprecated
16 #endif
19 struct isds_ctx; /* Context for specific ISDS box */
21 typedef enum {
22 IE_SUCCESS = 0, /* No error, just for C conveniece (0 means Ok) */
23 IE_ERROR, /* Unspecified error */
24 IE_NOTSUP,
25 IE_INVAL,
26 IE_INVALID_CONTEXT,
27 IE_NOT_LOGGED_IN,
28 IE_CONNECTION_CLOSED,
29 IE_TIMED_OUT,
30 IE_NOEXIST,
31 IE_NOMEM,
32 IE_NETWORK,
33 IE_HTTP,
34 IE_SOAP,
35 IE_XML,
36 IE_ISDS,
37 IE_ENUM,
38 IE_DATE,
39 IE_2BIG,
40 IE_2SMALL,
41 IE_NOTUNIQ,
42 IE_NOTEQUAL,
43 IE_PARTIAL_SUCCESS
44 } isds_error;
46 typedef enum {
47 ILL_NONE = 0,
48 ILL_CRIT = 10,
49 ILL_ERR = 20,
50 ILL_WARNING = 30,
51 ILL_INFO = 40,
52 ILL_DEBUG = 50,
53 ILL_ALL = 100
54 } isds_log_level;
56 typedef enum {
57 ILF_NONE = 0x0,
58 ILF_HTTP = 0x1,
59 ILF_SOAP = 0x2,
60 ILF_ISDS = 0x4,
61 ILF_FILE = 0x8,
62 ILF_SEC = 0x10,
63 ILF_XML = 0x20,
64 ILF_ALL = 0xFF
65 } isds_log_facility;
67 /* Return text description of ISDS error */
68 const char *isds_strerror(const isds_error error);
70 /* TLS libisds options */
71 typedef enum {
72 ITLS_VERIFY_SERVER, /* _Bool: Verify server idetity? */
73 ITLS_CA_FILE, /* char *: File name with CA certificates */
74 ITLS_CA_DIRECTORY /* char *: Directory name with CA certificates */
75 } isds_tls_option;
77 /* Box type */
78 typedef enum {
79 DBTYPE_SYSTEM = 0, /* This is special sender value for messages
80 sent by ISDS. */
81 DBTYPE_OVM = 10,
82 DBTYPE_OVM_NOTAR = 11,
83 DBTYPE_OVM_EXEKUT = 12,
84 DBTYPE_OVM_REQ = 13,
85 DBTYPE_PO = 20,
86 DBTYPE_PO_ZAK = 21,
87 DBTYPE_PO_REQ = 22,
88 DBTYPE_PFO = 30,
89 DBTYPE_PFO_ADVOK = 31,
90 DBTYPE_PFO_DANPOR = 32,
91 DBTYPE_PFO_INSSPR = 33,
92 DBTYPE_FO = 40
93 } isds_DbType;
95 /* Box status from point of view of accesibilty */
96 typedef enum {
97 DBSTATE_ACCESSIBLE = 1,
98 DBSTATE_TEMP_UNACCESSIBLE = 2,
99 DBSTATE_NOT_YET_ACCESSIBLE = 3,
100 DBSTATE_PERM_UNACCESSIBLE = 4,
101 DBSTATE_REMOVED = 5
102 } isds_DbState;
104 /* User permissions from point of view of ISDS.
105 * Instances can be bitmaps of any discrete values. */
106 typedef enum {
107 PRIVIL_READ_NON_PERSONAL = 0x1, /* Can download and read messages with
108 dmPersonalDelivery == false */
109 PRIVIL_READ_ALL = 0x2, /* Can download and read messages with
110 dmPersonalDelivery == true */
111 PRIVIL_CREATE_DM = 0x4, /* Can create and sent messages,
112 can dowload outgoing (sent) messages */
113 PRIVIL_VIEW_INFO = 0x8, /* Can list messages and data about
114 post and delivery */
115 PRIVIL_SEARCH_DB = 0x10, /* Can search for boxes */
116 PRIVIL_OWNER_ADM = 0x20, /* Can administer his box (add/remove
117 permitted users and theirs
118 permissions) */
119 PRIVIL_READ_VAULT = 0x40, /* Cen read message stored in data safe */
120 PRIVIL_ERASE_VAULT = 0x80 /* Can delete messages from data safe */
121 } isds_priviledges;
123 /* Message status */
124 typedef enum {
125 MESSAGESTATE_SENT = 0x2, /* Message has been put into ISDS */
126 MESSAGESTATE_STAMPED = 0x4, /* Message stamped by TSA */
127 MESSAGESTATE_INFECTED = 0x8, /* Message included virues,
128 infected document has been removed */
129 MESSAGESTATE_DELIVERED = 0x10, /* Message delivered
130 (dmDeliveryTime stored) */
131 MESSAGESTATE_SUBSTITUTED = 0x20, /* Message delivered through fiction,
132 dmAcceptanceTime stored */
133 MESSAGESTATE_RECEIVED = 0x40, /* Message accepted (by user login or
134 user explicit request),
135 dmAcceptanceTime stored */
136 MESSAGESTATE_READ = 0x80, /* Message has been read by user */
137 MESSAGESTATE_UNDELIVERABLE = 0x100, /* Message could not been delivered
138 (e.g. recipent box has been made
139 unaccessible meantime) */
140 MESSAGESTATE_REMOVED = 0x200, /* Message content deleted */
141 MESSAGESTATE_IN_SAFE = 0x400 /* Message stored in data safe */
143 } isds_message_status;
144 #define MESSAGESTATE_ANY 0x7FE /* Union of all isds_message_status
145 values */
147 /* Hash algoritm types */
148 typedef enum {
149 HASH_ALGORITHM_MD5,
150 HASH_ALGORITHM_SHA_1,
151 HASH_ALGORITHM_SHA_224,
152 HASH_ALGORITHM_SHA_256,
153 HASH_ALGORITHM_SHA_384,
154 HASH_ALGORITHM_SHA_512,
155 } isds_hash_algorithm;
157 /* Buffer storage strategy.
158 * How function should embed application provided buffer into raw element of
159 * output structure. */
160 typedef enum {
161 BUFFER_DONT_STORE, /* Don't fill raw memeber */
162 BUFFER_COPY, /* Copy buffer content into newly allocated raw */
163 BUFFER_MOVE /* Just copy pointer.
164 But leave deallocation to isds_*_free(). */
165 } isds_buffer_strategy;
167 /* Hash value storage */
168 struct isds_hash {
169 isds_hash_algorithm algorithm; /* Hash algoritgm */
170 size_t length; /* Hash value lenght in bytes */
171 void *value; /* Hash value */
174 /* Name of person */
175 struct isds_PersonName {
176 char *pnFirstName;
177 char *pnMiddleName;
178 char *pnLastName;
179 char *pnLastNameAtBirth;
182 /* Date and place of birth */
183 struct isds_BirthInfo {
184 struct tm *biDate; /* Date of Birth in local time at birth place,
185 only tm_year, tm_mon and tm_mday carry sane
186 value */
187 char *biCity;
188 char *biCounty; /* German: Bezirk, Czech: okres */
189 char *biState;
192 /* Post address */
193 struct isds_Address {
194 char *adCity;
195 char *adStreet;
196 char *adNumberInStreet;
197 char *adNumberInMunicipality;
198 char *adZipCode;
199 char *adState;
202 /* Data about box and his owner.
203 * NULL pointer means undefined value */
204 struct isds_DbOwnerInfo {
205 char *dbID; /* Box ID [Max. 7 chars] */
206 isds_DbType *dbType; /* Box Type */
207 char *ic; /* ID */
208 struct isds_PersonName *personName; /* Name of person */
209 char *firmName; /* Name of firm */
210 struct isds_BirthInfo *birthInfo; /* Birth of person */
211 struct isds_Address *address; /* Post address */
212 char *nationality;
213 char *email;
214 char *telNumber;
215 char *identifier; /* External box identifier for data
216 provider (OVM, PO, maybe PFO)
217 [Max. 20 chars] */
218 char *registryCode; /* PFO External registry code
219 [Max. 5 chars] */
220 long int *dbState; /* Box state; 1 <=> active box;
221 long int beacause xsd:integer
222 TODO: enum? */
223 _Bool *dbEffectiveOVM; /* Box has OVM role (§ 5a) */
224 _Bool *dbOpenAddressing; /* Non-OVM Box is free to recieve
225 messages from anybody */
228 /* User type */
229 typedef enum {
230 USERTYPE_PRIMARY, /* Owner of the box */
231 USERTYPE_ENTRUSTED, /* User with limited access to the box */
232 USERTYPE_ADMINISTRATOR, /* User to manage ENTRUSTED_USERs */
233 USERTYPE_OFFICIAL /* ??? */
234 } isds_UserType;
236 /* Data about user.
237 * NULL pointer means undefined value */
238 struct isds_DbUserInfo {
239 char *userID; /* User ID [Min. 6, max. 12 characters] */
240 isds_UserType *userType; /* User type */
241 long int *userPrivils; /* Set of user permissions */
242 struct isds_PersonName *personName; /* Name of the person */
243 struct isds_Address *address; /* Post address */
244 struct tm *biDate; /* Date of birth in local time,
245 only tm_year, tm_mon and tm_mday carry sane
246 value */
247 char *ic; /* ID of a supervising firm [Max. 8 chars] */
248 char *firmName; /* Name of a supervising firm
249 [Max. 100 chars] */
250 char *caStreet; /* Street and number of contact address */
251 char *caCity; /* Czech City of contact address */
252 char *caZipCode; /* Post office code of contact address */
255 /* Message event type */
256 typedef enum {
257 EVENT_UKNOWN, /* Event unknown to this library */
258 EVENT_ACCEPTED_BY_RECIPIENT, /* Message has been delivered and accepted
259 by recipeint action */
260 EVENT_ACCEPTED_BY_FICTION, /* Message has been delivered, acceptance
261 timed out, considered as accepted */
262 EVENT_UNDELIVERABLE, /* Recipient box made unaccessible,
263 thus message is undelivarable */
264 EVENT_COMMERCIAL_ACCEPTED /* Recipient confirmed acceptace of
265 commercial message */
266 } isds_event_type;
268 /* Message event
269 * Alle members are optional as specification states so. */
270 struct isds_event {
271 struct timeval *time; /* When the event occurred */
272 isds_event_type *type; /* Type of the event */
273 char *description; /* Human readable event description
274 generated by ISDS (Czech) */
277 /* Message envelope
278 * Be ware that the string length contraints are forced only on output
279 * memebers transmitted to ISDS. The other direction (downloded from ISDS)
280 * can break these rules. It should not happen, but nobody knows how much
281 * incompatible new version of ISDS protocol will be. This is the gold
282 * Internet rule: be strict on what you put, be tollerant on what you get. */
283 struct isds_envelope {
284 /* Following memebers apply to incoming messages only: */
285 char *dmID; /* Message ID.
286 Maximal length is 20 characters. */
287 char *dbIDSender; /* Box ID of sender.
288 Special value "aaaaaaa" means sent by
289 ISDS.
290 Maximal length is 7 characters. */
291 char *dmSender; /* Sender name;
292 Maximal length is 100 characters. */
293 char *dmSenderAddress; /* Postal address of sender;
294 Maximal length is 100 characters. */
295 long int *dmSenderType; /* Gross Box type of sender
296 TODO: isds_DbType ? */
297 char *dmRecipient; /* Recipient name;
298 Maximal length is 100 characters. */
299 char *dmRecipientAddress; /* Postal address of recipient;
300 Maximal length is 100 characters. */
301 _Bool *dmAmbiguousRecipient; /* Recipient has OVM role */
302 char *dmType; /* Message type:
303 "V" is public message
304 "K" is commercial message */
306 /* Following memebers are assigned by ISDS in different phases of message
307 * life cycle. */
308 unsigned long int *dmOrdinal; /* Ordinal number in list of
309 incoming/outgoing messages */
310 isds_message_status *dmMessageStatus; /* Message state */
311 long int *dmAttachmentSize; /* Size of message documents in
312 kilobytes (rounded). */
313 struct timeval *dmDeliveryTime; /* Time of delivery into a box
314 NULL, if message has not been
315 delivered yet */
316 struct timeval *dmAcceptanceTime; /* Time of accpetance of the message
317 by an user. NULL if message has not
318 been accepted yet. */
319 struct isds_hash *hash; /* Message hash.
320 This is hash of isds:dmDM subtree. */
321 void *timestamp; /* Qualified time stamp */
322 size_t timestamp_length; /* Lenght of timestamp in bytes */
323 struct isds_list *events; /* Events message passed trough;
324 List of isds_event's. */
327 /* Following members apply to both outgoing and incoming messages: */
328 char *dmSenderOrgUnit; /* Organisation unit of sender as string;
329 Optional. */
330 long int *dmSenderOrgUnitNum; /* Organisation unit of sender as number;
331 Optional. */
332 char *dbIDRecipient; /* Box ID of recipient; Mandatory.
333 Maximal length is 7 characters. */
334 char *dmRecipientOrgUnit; /* Organisation unit of recipient as
335 string; Optional. */
336 long int *dmRecipientOrgUnitNum; /* Organisation unit of recipient as
337 number; Optional. */
338 char *dmToHands; /* Person in recipient organisation;
339 Optional. */
340 char *dmAnnotation; /* Subject (title) of the message.
341 Maximal length is 255 characters. */
342 char *dmRecipientRefNumber; /* Czech: číslo jednací příjemce; Optional.
343 Maximal length is 50 characters. */
344 char *dmSenderRefNumber; /* Czech: číslo jednací odesílatele;
345 Optional. Maximal lenght is 50 chars. */
346 char *dmRecipientIdent; /* Czech: spisová značka příjemce; Optional.
347 Maximal length is 50 characters. */
348 char *dmSenderIdent; /* Czech: spisová značka odesílatele;
349 Optional. Maximal lenght is 50 chars. */
351 /* Act addressing in Czech Republic:
352 * Point (Parahraph) § Section Law/Year Coll. */
353 long int *dmLegalTitleLaw; /* Number of act mandating authority */
354 long int *dmLegalTitleYear; /* Year of act issue mandating authority */
355 char *dmLegalTitleSect; /* Section of act mandating authority.
356 Czech: paragraf */
357 char *dmLegalTitlePar; /* Parahraph of act mandating authority.
358 Czech: odstavec */
359 char *dmLegalTitlePoint; /* Point of act mandating authority.
360 Czech: písmeno */
362 _Bool *dmPersonalDelivery; /* If true, only person with higher
363 priviledges can read this message */
364 _Bool *dmAllowSubstDelivery; /* Allow delivery through fiction.
365 I.e. Even if recipient did not read this
366 message, message is considered as
367 delivered after (currently) 10 days.
368 This is delivery through fiction.
369 Applies only to OVM dbType sender. */
370 _Bool *dmOVM; /* OVM sending mode.
371 Non-OVM dbType boxes that has
372 dbEffectiveOVM == true MUST select
373 between true (OVM mode) and
374 false (non-OVM mode).
375 Optionable; Implicit value is true. */
379 /* Document type from point of hiearchy */
380 typedef enum {
381 FILEMETATYPE_MAIN, /* Main document */
382 FILEMETATYPE_ENCLOSURE, /* Appendix */
383 FILEMETATYPE_SIGNATURE, /* Digital signature of other document */
384 FILEMETATYPE_META /* XML document for ESS (electronic
385 document information system) purposes */
386 } isds_FileMetaType;
388 /* Document */
389 struct isds_document {
390 void *data; /* Document content.
391 The encoding and interpretation depends
392 on dmMimeType.
393 TODO: inline XML */
394 size_t data_length; /* Length of the data in bytes */
395 char *dmMimeType; /* MIME type of data; Mandatory. */
396 isds_FileMetaType dmFileMetaType; /* Document type to create hierarchy */
397 char *dmFileGuid; /* Message-local document identifier;
398 Optional. */
399 char *dmUpFileGuid; /* Reference to upper document identifier
400 (dmFileGuid); Optional. */
401 char *dmFileDescr; /* Document name (title). E.g. file name;
402 Mandatory. */
403 char *dmFormat; /* Reference to XML form definition;
404 Defines howto interpret XML document;
405 Optional. */
408 /* Raw message representation content type.
409 * This is necessary to distinguish between different representations without
410 * expensive repated detection.
411 * Infix explanation:
412 * PLAIN_SIGNED data are XML with namespace mangled to signed alternative
413 * CMS_SIGNED data are XML with signed namespace encapsulated in CMS */
414 typedef enum {
415 RAWTYPE_INCOMING_MESSAGE,
416 RAWTYPE_PLAIN_SIGNED_INCOMING_MESSAGE,
417 RAWTYPE_CMS_SIGNED_INCOMING_MESSAGE,
418 RAWTYPE_PLAIN_SIGNED_OUTGOING_MESSAGE,
419 RAWTYPE_CMS_SIGNED_OUTGOING_MESSAGE,
420 RAWTYPE_DELIVERYINFO,
421 RAWTYPE_PLAIN_SIGNED_DELIVERYINFO,
422 RAWTYPE_CMS_SIGNED_DELIVERYINFO
423 } isds_raw_type;
425 /* Message */
426 struct isds_message {
427 void *raw; /* Raw message in XML format as send to or
428 from the ISDS. You can use it to store
429 local copy. This is binary buffer. */
430 size_t raw_length; /* Lenght of raw message in bytes */
431 isds_raw_type raw_type; /* Content type of raw representation
432 Meaningfull only with non-NULL raw
433 member */
434 struct isds_envelope *envelope; /* Message envelope */
435 struct isds_list *documents; /* List of isds_document's.
436 Valid message must contain exactly one
437 document of type FILEMETATYPE_MAIN and
438 can contain any number of other type
439 documents. Totol size of documents
440 must not exceed 10 MB. */
443 /* Message copy recipient and assigned message ID */
444 struct isds_message_copy {
445 /* Input members defined by application */
446 char *dbIDRecipient; /* Box ID of recipient; Mandatory.
447 Maximal length is 7 characters. */
448 char *dmRecipientOrgUnit; /* Organisation unit of recipient as
449 string; Optional. */
450 long int *dmRecipientOrgUnitNum; /* Organisation unit of recipient as
451 number; Optional. */
452 char *dmToHands; /* Person in recipient organisation;
453 Optional. */
455 /* Output members returned from ISDS */
456 isds_error error; /* libisds compatible error of delivery to o ne recipient */
457 char *dmStatus; /* Error description returned by ISDS;
458 Optional. */
459 char *dmID; /* Assigned message ID; Meaningfull only
460 for error == IE_SUCCESS */
463 /* General linked list */
464 struct isds_list {
465 struct isds_list *next; /* Next list item,
466 or NULL if current is last */
467 void *data; /* Payload */
468 void (*destructor) (void **); /* Payload deallocator */
471 /* External box approval */
472 struct isds_approval {
473 _Bool approved; /* True if request for box has been
474 approvedout of ISDS */
475 char *refference; /* Identifier of the approval */
479 /* Initialize ISDS library.
480 * Global function, must be called before other functions.
481 * If it failes you can not use ISDS library and must call isds_cleanup() to
482 * free partially inititialized global variables. */
483 isds_error isds_init(void);
485 /* Deinicialize ISDS library.
486 * Global function, must be called as last library function. */
487 isds_error isds_cleanup(void);
489 /* Create ISDS context.
490 * Each context can be used for different sessions to (possibly) different
491 * ISDS server with different credentials.
492 * Returns new context, or NULL */
493 struct isds_ctx *isds_ctx_create(void);
495 /* Destroy ISDS context and free memmory.
496 * @context will be NULLed on success. */
497 isds_error isds_ctx_free(struct isds_ctx **context);
499 /* Return long message text produced by library fucntion, e.g. detailed error
500 * mesage. Returned pointer is only valid until new library function is
501 * called for the same context. Could be NULL, especially if NULL context is
502 * supplied. Return string is locale encoded. */
503 char *isds_long_message(const struct isds_ctx *context);
505 /* Set logging up.
506 * @facilities is bitmask of isds_log_facility values,
507 * @level is verbosity level. */
508 void isds_set_logging(const unsigned int facilities,
509 const isds_log_level level);
512 /* Set timeout in miliseconds for each network job like connecting to server
513 * or sending message. Use 0 to disable timeout limits. */
514 isds_error isds_set_timeout(struct isds_ctx *context,
515 const unsigned int timeout);
517 /* Function provided by application libsds will call with
518 * following five arguments. Value zero of any argument means the value is
519 * unknown.
520 * @upload_total is expected total upload,
521 * @upload_current is cumulative current upload progress
522 * @dowload_total is expected total download
523 * @download_current is cumulative current download progress
524 * @data is pointer that will be passed unchanged to this function at run-time
525 * @return 0 to continue HTTP transfaer, or non-zero to abort transfer */
526 typedef int (*isds_progress_callback)(
527 double upload_total, double upload_current,
528 double download_total, double download_current,
529 void *data);
531 /* Register callback function libisds calls periodocally during HTTP data
532 * transfer.
533 * @context is session context
534 * @callback is function provided by application libsds will call. See type
535 * defition for @callback argument explanation.
536 * @data is application specific data @callback gets as last argument */
537 isds_error isds_set_progress_callback(struct isds_ctx *context,
538 isds_progress_callback callback, void *data);
540 /* Change SSL/TLS settings.
541 * @context is context which setting vill be applied to
542 * @option is name of option. It determines the type of last argument. See
543 * isds_tls_option definition for more info.
544 * @... is value of new setting. Type is determined by @option
545 * */
546 isds_error isds_set_tls(struct isds_ctx *context, const isds_tls_option option,
547 ...);
549 /* Connect and log in into ISDS server.
550 * @url is address of ISDS web service
551 * @username is user name of ISDS user
552 * @password is user's secret password
553 * @certificate is NULL terminated string with PEM formated client's
554 * certificate. Use NULL if only password autentication should be performed.
555 * @key is private key for client's certificate as (base64 encoded?) NULL
556 * terminated string. Use NULL if only password autentication is desired.
557 * */
558 isds_error isds_login(struct isds_ctx *context, const char *url,
559 const char *username, const char *password,
560 const char *certificate, const char* key);
562 /* Log out from ISDS server and close connection. */
563 isds_error isds_logout(struct isds_ctx *context);
565 /* Verify connection to ISDS is alive and server is responding.
566 * Sent dumy request to ISDS and expect dummy response. */
567 isds_error isds_ping(struct isds_ctx *context);
569 /* Get data about logged in user and his box. */
570 isds_error isds_GetOwnerInfoFromLogin(struct isds_ctx *context,
571 struct isds_DbOwnerInfo **db_owner_info);
573 /* Get data about logged in user. */
574 isds_error isds_GetUserInfoFromLogin(struct isds_ctx *context,
575 struct isds_DbUserInfo **db_user_info);
577 /* Get expiration time of current password
578 * @context is session context
579 * @expiration is automatically reallocated time when password expires, In
580 * case of error will be nulled. */
581 isds_error isds_get_password_expiration(struct isds_ctx *context,
582 struct timeval **expiration);
584 /* Change user password in ISDS.
585 * User must supply old password, new password will takes effect after some
586 * time, current session can continue. Password must fulfill some constraints.
587 * @context is session context
588 * @old_password is current password.
589 * @new_password is requested new password */
590 isds_error isds_change_password(struct isds_ctx *context,
591 const char *old_password, const char *new_password);
593 /* Create new box.
594 * @context is session context
595 * @box is box description to create including single primary user (in case of
596 * FO box type). It outputs box ID assigned by ISDS in dbID element.
597 * @users is list of struct isds_DbUserInfo (primary users in case of non-FO
598 * box, or contact address of PFO box owner)
599 * @former_names is optional undocumented string. Pass NULL if you don't care.
600 * @upper_box_id is optional ID of supper box if currently created box is
601 * subordinated.
602 * @ceo_label is optional title of OVM box owner (e.g. mayor)
603 * @approval is optional external approval of box manipulation
604 * @refnumber is reallocated serial number of request assigned by ISDS. Use
605 * NULL, if you don't care.*/
606 isds_error isds_add_box(struct isds_ctx *context,
607 struct isds_DbOwnerInfo *box, const struct isds_list *users,
608 const char *former_names, const char *upper_box_id,
609 const char *ceo_label, const struct isds_approval *approval,
610 char **refnumber);
612 /* Notify ISDS about new PFO entity.
613 * This function has no real effect.
614 * @context is session context
615 * @box is PFO description including single primary user.
616 * @users is list of struct isds_DbUserInfo (contact address of PFO box owner)
617 * @former_names is optional undocumented string. Pass NULL if you don't care.
618 * @upper_box_id is optional ID of supper box if currently created box is
619 * subordinated.
620 * @ceo_label is optional title of OVM box owner (e.g. mayor)
621 * @approval is optional external approval of box manipulation
622 * @refnumber is reallocated serial number of request assigned by ISDS. Use
623 * NULL, if you don't care.*/
624 isds_error isds_add_pfoinfo(struct isds_ctx *context,
625 const struct isds_DbOwnerInfo *box, const struct isds_list *users,
626 const char *former_names, const char *upper_box_id,
627 const char *ceo_label, const struct isds_approval *approval,
628 char **refnumber);
630 /* Remove given given box permanetly.
631 * @context is session context
632 * @box is box description to delete
633 * @since is date of box owner cancalation. Only tm_year, tm_mon and tm_mday
634 * carry sane value.
635 * @approval is optional external approval of box manipulation
636 * @refnumber is reallocated serial number of request assigned by ISDS. Use
637 * NULL, if you don't care.*/
638 isds_error isds_delete_box(struct isds_ctx *context,
639 const struct isds_DbOwnerInfo *box, const struct tm *since,
640 const struct isds_approval *approval, char **refnumber);
642 /* Update data about given box.
643 * @context is session context
644 * @old_box current box description
645 * @new_box are updated data about @old_box
646 * @approval is optional external approval of box manipulation
647 * @refnumber is reallocated serial number of request assigned by ISDS. Use
648 * NULL, if you don't care.*/
649 isds_error isds_UpdateDataBoxDescr(struct isds_ctx *context,
650 const struct isds_DbOwnerInfo *old_box,
651 const struct isds_DbOwnerInfo *new_box,
652 const struct isds_approval *approval, char **refnumber);
654 /* Get data about all users assigned to given box.
655 * @context is session context
656 * @box_id is box ID
657 * @users is automatically reallocated list of struct isds_DbUserInfo */
658 isds_error isds_GetDataBoxUsers(struct isds_ctx *context, const char *box_id,
659 struct isds_list **users);
661 /* Update data about user assigned to given box.
662 * @context is session context
663 * @box is box identification
664 * @old_user identifies user to update
665 * @new_user are updated data about @old_user
666 * @refnumber is reallocated serial number of request assigned by ISDS. Use
667 * NULL, if you don't care.*/
668 isds_error isds_UpdateDataBoxUser(struct isds_ctx *context,
669 const struct isds_DbOwnerInfo *box,
670 const struct isds_DbUserInfo *old_user,
671 const struct isds_DbUserInfo *new_user,
672 char **refnumber);
674 /* Reset credentials of user assigned to given box.
675 * @context is session context
676 * @box is box identification
677 * @user identifies user to reset password
678 * @fee_paid is true if fee has been paid, false otherwise
679 * @approval is optional external approval of box manipulation
680 * @token is NULL if new password should be delivered off-line to the user.
681 * It is valid pointer if user should obtain new password on-line on dedicated
682 * web server. Then it output automatically reallocated token user needs to
683 * use to athtorize on the web server to view his new password.
684 * @refnumber is reallocated serial number of request assigned by ISDS. Use
685 * NULL, if you don't care.*/
686 isds_error isds_reset_password(struct isds_ctx *context,
687 const struct isds_DbOwnerInfo *box,
688 const struct isds_DbUserInfo *user,
689 const _Bool fee_paid, const struct isds_approval *approval,
690 char **token, char **refnumber);
692 /* Assign new user to given box.
693 * @context is session context
694 * @box is box identification
695 * @user defines new user to add
696 * @approval is optional external approval of box manipulation
697 * @refnumber is reallocated serial number of request assigned by ISDS. Use
698 * NULL, if you don't care.*/
699 isds_error isds_add_user(struct isds_ctx *context,
700 const struct isds_DbOwnerInfo *box, const struct isds_DbUserInfo *user,
701 const struct isds_approval *approval, char **refnumber);
703 /* Remove user assigned to given box.
704 * @context is session context
705 * @box is box identification
706 * @user identifies user to removve
707 * @approval is optional external approval of box manipulation
708 * @refnumber is reallocated serial number of request assigned by ISDS. Use
709 * NULL, if you don't care.*/
710 isds_error isds_delete_user(struct isds_ctx *context,
711 const struct isds_DbOwnerInfo *box, const struct isds_DbUserInfo *user,
712 const struct isds_approval *approval, char **refnumber);
714 /* Find boxes suiting given criteria.
715 * @context is ISDS session context.
716 * @criteria is filter. You should fill in at least some members.
717 * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
718 * possibly empty. Input NULL or valid old structure.
719 * @return:
720 * IE_SUCCESS if search sucseeded, @boxes contains usefull data
721 * IE_NOEXIST if no such box exists, @boxes will be NULL
722 * IE_2BIG if too much boxes exist and server truncated the resuluts, @boxes
723 * contains still valid data
724 * other code if something bad happens. @boxes will be NULL. */
725 isds_error isds_FindDataBox(struct isds_ctx *context,
726 const struct isds_DbOwnerInfo *criteria,
727 struct isds_list **boxes);
729 /* Get status of a box.
730 * @context is ISDS session context.
731 * @box_id is UTF-8 encoded box identifier as zero terminated string
732 * @box_status is return value of box status.
733 * @return:
734 * IE_SUCCESS if box has been found and its status retrieved
735 * IE_NOEXIST if box is not known to ISDS server
736 * or other appropriate error.
737 * You can use isds_DbState to enumerate box status. However out of enum
738 * range value can be returned too. This is feature because ISDS
739 * specification leaves the set of values open.
740 * Be ware that status DBSTATE_REMOVED is signaled as IE_SUCCESS. That means
741 * the box has been deleted, but ISDS still lists its former existence. */
742 isds_error isds_CheckDataBox(struct isds_ctx *context, const char *box_id,
743 long int *box_status);
745 /* Switch box into state where box can receive commercial messages (off by
746 * default)
747 * @context is ISDS session context.
748 * @box_id is UTF-8 encoded box identifier as zero terminated string
749 * @allow is true for enable, false for disable commercial messages income
750 * @approval is optional external approval of box manipulation
751 * @refnumber is reallocated serial number of request assigned by ISDS. Use
752 * NULL, if you don't care. */
753 isds_error isds_switch_commercial_receiving(struct isds_ctx *context,
754 const char *box_id, const _Bool allow,
755 const struct isds_approval *approval, char **refnumber);
757 /* Switch box into / out of state where non-OVM box can act as OVM (e.g. force
758 * message acceptance). This is just a box permission. Sender must apply
759 * such role by sending each message.
760 * @context is ISDS session context.
761 * @box_id is UTF-8 encoded box identifier as zero terminated string
762 * @allow is true for enable, false for disable OVM role permission
763 * @approval is optional external approval of box manipulation
764 * @refnumber is reallocated serial number of request assigned by ISDS. Use
765 * NULL, if you don't care. */
766 isds_error isds_switch_effective_ovm(struct isds_ctx *context,
767 const char *box_id, const _Bool allow,
768 const struct isds_approval *approval, char **refnumber);
770 /* Switch box accessibility state on request of box owner.
771 * Despite the name, owner must do the request off-line. This function is
772 * designed for such off-line meeting points (e.g. Czech POINT).
773 * @context is ISDS session context.
774 * @box identifies box to swith accesibilty state.
775 * @allow is true for making accesibale, false to disallow access.
776 * @approval is optional external approval of box manipulation
777 * @refnumber is reallocated serial number of request assigned by ISDS. Use
778 * NULL, if you don't care. */
779 isds_error isds_switch_box_accessibility_on_owner_request(
780 struct isds_ctx *context, const struct isds_DbOwnerInfo *box,
781 const _Bool allow, const struct isds_approval *approval,
782 char **refnumber);
784 /* Disable box accessibility on law enforcement (e.g. by prison) since exact
785 * date.
786 * @context is ISDS session context.
787 * @box identifies box to swith accesibilty state.
788 * @since is date since accesseibility has been denied. This can be past too.
789 * Only tm_year, tm_mon and tm_mday carry sane value.
790 * @approval is optional external approval of box manipulation
791 * @refnumber is reallocated serial number of request assigned by ISDS. Use
792 * NULL, if you don't care. */
793 isds_error isds_disable_box_accessibility_externaly(
794 struct isds_ctx *context, const struct isds_DbOwnerInfo *box,
795 const struct tm *since, const struct isds_approval *approval,
796 char **refnumber);
798 /* Send a message via ISDS to a recipent
799 * @context is session context
800 * @outgoing_message is message to send; Some memebers are mandatory (like
801 * dbIDRecipient), some are optional and some are irrelevant (especialy data
802 * about sender). Included pointer to isds_list documents must contain at
803 * least one document of FILEMETATYPE_MAIN. This is read-write structure, some
804 * members will be filled with valid data from ISDS. Exact list of write
805 * members is subject to change. Currently dmId is changed.
806 * @return ISDS_SUCCESS, or other error code if something goes wrong. */
807 isds_error isds_send_message(struct isds_ctx *context,
808 struct isds_message *outgoing_message);
810 /* Send a message via ISDS to a multiple recipents
811 * @context is session context
812 * @outgoing_message is message to send; Some memebers are mandatory,
813 * some are optional and some are irrelevant (especialy data
814 * about sender). Data about recipient will be substituted by ISDS from
815 * @copies. Included pointer to isds_list documents must
816 * contain at least one document of FILEMETATYPE_MAIN.
817 * @copies is list of isds_message_copy structures addressing all desired
818 * recipients. This is read-write structure, some members will be filled with
819 * valid data from ISDS (message IDs, error codes, error descriptions).
820 * @return
821 * ISDS_SUCCESS if all messages have been sent
822 * ISDS_PARTIAL_SUCCESS if sending of some messages has failed (failed and
823 * succesed messages can be identified by copies->data->error),
824 * or other error code if something other goes wrong. */
825 isds_error isds_send_message_to_multiple_recipients(struct isds_ctx *context,
826 const struct isds_message *outgoing_message,
827 struct isds_list *copies);
829 /* Get list of outgoing (already sent) messages.
830 * Any criterion argument can be NULL, if you don't care about it.
831 * @context is session context. Must not be NULL.
832 * @from_time is minimal time and date of message sending inclusive.
833 * @to_time is maximal time and date of message sending inclusive
834 * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
835 * @status_filter is bit field of isds_message_status values. Use special
836 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
837 * all values, you can use bitwise arithmetic if you want.)
838 * @offset is index of first message we are interested in. First message is 1.
839 * Set to 0 (or 1) if you don't care.
840 * @number is maximal length of list you want to get as input value, outputs
841 * number of messages matching these criteria. Can be NULL if you don't care
842 * (applies to output value either).
843 * @messages is automatically reallocated list of isds_message's. Be ware that
844 * it returns only brief overview (envelope and some other fields) about each
845 * message, not the complete message. FIXME: Specify exact fields.
846 * The list is sorted by delivery time in ascending order.
847 * Use NULL if you don't care about the metadata (useful if you want to know
848 * only the @number). If you provide &NULL, list will be allocated on heap,
849 * if you provide pointer to non-NULL, list will be freed automacally at first.
850 * Also in case of error the list will be NULLed.
851 * @return IE_SUCCESS or appropriate error code. */
852 isds_error isds_get_list_of_sent_messages(struct isds_ctx *context,
853 const struct timeval *from_time, const struct timeval *to_time,
854 const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
855 const unsigned long int offset, unsigned long int *number,
856 struct isds_list **messages);
858 /* Get list of incoming (addressed to you) messages.
859 * Any criterion argument can be NULL, if you don't care about it.
860 * @context is session context. Must not be NULL.
861 * @from_time is minimal time and date of message sending inclusive.
862 * @to_time is maximal time and date of message sending inclusive
863 * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
864 * @status_filter is bit field of isds_message_status values. Use special
865 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
866 * all values, you can use bitwise arithmetic if you want.)
867 * @offset is index of first message we are interested in. First message is 1.
868 * Set to 0 (or 1) if you don't care.
869 * @number is maximal length of list you want to get as input value, outputs
870 * number of messages matching these criteria. Can be NULL if you don't care
871 * (applies to output value either).
872 * @messages is automatically reallocated list of isds_message's. Be ware that
873 * it returns only brief overview (envelope and some other fields) about each
874 * message, not the complete message. FIXME: Specify exact fields.
875 * Use NULL if you don't care about the metadata (useful if you want to know
876 * only the @number). If you provide &NULL, list will be allocated on heap,
877 * if you provide pointer to non-NULL, list will be freed automacally at first.
878 * Also in case of error the list will be NULLed.
879 * @return IE_SUCCESS or appropriate error code. */
880 isds_error isds_get_list_of_received_messages(struct isds_ctx *context,
881 const struct timeval *from_time, const struct timeval *to_time,
882 const long int *dmSenderOrgUnitNum, const unsigned int status_filter,
883 const unsigned long int offset, unsigned long int *number,
884 struct isds_list **messages);
886 /* Download incoming message envelope identified by ID.
887 * @context is session context
888 * @message_id is message identifier (you can get them from
889 * isds_get_list_of_received_messages())
890 * @message is automatically reallocated message retrieved from ISDS.
891 * It will miss documents per se. Use isds_get_received_message(), if you are
892 * interrested in documents (content) too.
893 * Returned hash and timestamp require documents to be verifiable. */
894 isds_error isds_get_received_envelope(struct isds_ctx *context,
895 const char *message_id, struct isds_message **message);
897 /* Download signed delivery infosheet of given message identified by ID.
898 * @context is session context
899 * @message_id is message identifier (you can get them from
900 * isds_get_list_of_{sent,received}_messages())
901 * @message is automatically reallocated message retrieved from ISDS.
902 * It will miss documents per se. Use isds_get_signed_received_message(),
903 * if you are interrested in documents (content). OTOH, only this function
904 * can get list events message has gone through. */
905 isds_error isds_get_signed_delivery_info(struct isds_ctx *context,
906 const char *message_id, struct isds_message **message);
908 /* Load delivery info of any format from buffer.
909 * @context is session context
910 * @raw_type advertises format of @buffer content. Only delivery info types
911 * are accepted.
912 * @buffer is DER encoded PKCS#7 structure with signed delivery info. You can
913 * retrieve such data from message->raw after calling
914 * isds_get_signed_delivery_info().
915 * @length is length of buffer in bytes.
916 * @message is automatically reallocated message parsed from @buffer.
917 * @strategy selects how buffer will be attached into raw isds_message member.
918 * */
919 isds_error isds_load_delivery_info(struct isds_ctx *context,
920 const isds_raw_type raw_type,
921 const void *buffer, const size_t length,
922 struct isds_message **message, const isds_buffer_strategy strategy);
924 /* Download delivery infosheet of given message identified by ID.
925 * @context is session context
926 * @message_id is message identifier (you can get them from
927 * isds_get_list_of_{sent,received}_messages())
928 * @message is automatically reallocated message retrieved from ISDS.
929 * It will miss documents per se. Use isds_get_received_message(), if you are
930 * interrested in documents (content). OTOH, only this function can get list
931 * events message has gone through. */
932 isds_error isds_get_delivery_info(struct isds_ctx *context,
933 const char *message_id, struct isds_message **message);
935 /* Deprecated: Use isds_load_message() instead. */
936 /* Load incoming message from buffer.
937 * @context is session context
938 * @buffer XML stream with unsigned message. You can retrieve such data from
939 * message->raw after calling isds_get_received_message().
940 * @length is length of buffer in bytes.
941 * @message is automatically reallocated message parsed from @buffer.
942 * @strategy selects how buffer will be attached into raw isds_message member.
943 * */
944 isds_error isds_load_received_message(struct isds_ctx *context,
945 const void *buffer, const size_t length,
946 struct isds_message **message, const isds_buffer_strategy strategy)
947 _deprecated;
949 /* Download incoming message identified by ID.
950 * @context is session context
951 * @message_id is message identifier (you can get them from
952 * isds_get_list_of_received_messages())
953 * @message is automatically reallocated message retrieved from ISDS */
954 isds_error isds_get_received_message(struct isds_ctx *context,
955 const char *message_id, struct isds_message **message);
957 /* Deprecated: Use isds_load_message() instead. */
958 /* Load signed message from buffer.
959 * @context is session context
960 * @outgoing is true if message is outgoing, false if message is incoming
961 * @buffer is DER encoded PKCS#7 structure with signed message. You can
962 * retrieve such data from message->raw after calling
963 * isds_get_signed{received,sent}_message().
964 * @length is length of buffer in bytes.
965 * @message is automatically reallocated message parsed from @buffer.
966 * @strategy selects how buffer will be attached into raw isds_message member.
967 * */
968 isds_error isds_load_signed_message(struct isds_ctx *context,
969 const _Bool outgoing, const void *buffer, const size_t length,
970 struct isds_message **message, const isds_buffer_strategy strategy)
971 _deprecated;
973 /* Load message of any type from buffer.
974 * @context is session context
975 * @raw_type defines content type of @buffer. Only message types are allowed.
976 * @buffer is message raw representation. Format (CMS, plain signed,
977 * message direction) is defined in @raw_type. You can retrieve such data
978 * from message->raw after calling isds_get_[signed]{received,sent}_message().
979 * @length is length of buffer in bytes.
980 * @message is automatically reallocated message parsed from @buffer.
981 * @strategy selects how buffer will be attached into raw isds_message member.
982 * */
983 isds_error isds_load_message(struct isds_ctx *context,
984 const isds_raw_type raw_type, const void *buffer, const size_t length,
985 struct isds_message **message, const isds_buffer_strategy strategy);
987 /* Download signed incoming message identified by ID.
988 * @context is session context
989 * @message_id is message identifier (you can get them from
990 * isds_get_list_of_received_messages())
991 * @message is automatically reallocated message retrieved from ISDS. The raw
992 * memeber will be filled with PKCS#7 structure in DER format. */
993 isds_error isds_get_signed_received_message(struct isds_ctx *context,
994 const char *message_id, struct isds_message **message);
996 /* Download signed outgoing message identified by ID.
997 * @context is session context
998 * @message_id is message identifier (you can get them from
999 * isds_get_list_of_sent_messages())
1000 * @message is automatically reallocated message retrieved from ISDS. The raw
1001 * memeber will be filled with PKCS#7 structure in DER format. */
1002 isds_error isds_get_signed_sent_message(struct isds_ctx *context,
1003 const char *message_id, struct isds_message **message);
1005 /* Retrieve hash of message identified by ID stored in ISDS.
1006 * @context is session context
1007 * @message_id is message identifier
1008 * @hash is automatically reallocated message hash downloaded from ISDS.
1009 * Message must exist in system and must not be deleted. */
1010 isds_error isds_download_message_hash(struct isds_ctx *context,
1011 const char *message_id, struct isds_hash **hash);
1013 /* Compute hash of message from raw representation and store it into envelope.
1014 * Original hash structure will be destroyed in envelope.
1015 * @context is session context
1016 * @message is message carrying raw XML message blob
1017 * @algorithm is desired hash algorithm to use */
1018 isds_error isds_compute_message_hash(struct isds_ctx *context,
1019 struct isds_message *message, const isds_hash_algorithm algorithm);
1021 /* Compare two hashes.
1022 * @h1 is first hash
1023 * @h2 is another hash
1024 * @return
1025 * IE_SUCCESS if hashes equal
1026 * IE_NOTUNIQ if hashes are comparable, but they don't equal
1027 * IE_ENUM if not comparable, but both structures defined
1028 * IE_INVAL if some of the structures are undefined (NULL)
1029 * IE_ERROR if internal error occurs */
1030 isds_error isds_hash_cmp(const struct isds_hash *h1,
1031 const struct isds_hash *h2);
1033 /* Check message has gone through ISDS by comparing message hash stored in
1034 * ISDS and locally computed hash. You must provide message with valid raw
1035 * member (do not use isds_load_message(..., BUFFER_DONT_STORE)).
1036 * This is convenient wrapper for isds_download_message_hash(),
1037 * isds_compute_message_hash(), and isds_hash_cmp() sequence.
1038 * @context is session context
1039 * @message is message with valid raw and envelope member; envelope->hash
1040 * member will be changed during funcion run. Use envelope on heap only.
1041 * @return
1042 * IE_SUCCESS if message originates in ISDS
1043 * IE_NOTEQUAL if message is unknown to ISDS
1044 * other code for other errors */
1045 isds_error isds_verify_message_hash(struct isds_ctx *context,
1046 struct isds_message *message);
1048 /* Mark message as read. This is a transactional commit function to acknoledge
1049 * to ISDS the message has been downloaded and processed by client properly.
1050 * @context is session context
1051 * @message_id is message identifier. */
1052 isds_error isds_mark_message_read(struct isds_ctx *context,
1053 const char *message_id);
1055 /* Mark message as received by recipient. This is applicable only to
1056 * commercial message. There is no specified way how to distinguishe
1057 * commercial message from government message yet. Government message is
1058 * received automatically (by law), commenrcial message on recipient request.
1059 * @context is session context
1060 * @message_id is message identifier. */
1061 isds_error isds_mark_message_received(struct isds_ctx *context,
1062 const char *message_id);
1064 /* Send bogus request to ISDS.
1065 * Just for test purposes */
1066 isds_error isds_bogus_request(struct isds_ctx *context);
1068 /* Search for document by document ID in list of documents. IDs are compared
1069 * as UTF-8 string.
1070 * @documents is list of isds_documents
1071 * @id is document identifier
1072 * @return first matching document or NULL. */
1073 const struct isds_document *isds_find_document_by_id(
1074 const struct isds_list *documents, const char *id);
1076 /* Free isds_list with all member data.
1077 * @list list to free, on return will be NULL */
1078 void isds_list_free(struct isds_list **list);
1080 /* Deallocate structure isds_hash and NULL it.
1081 * @hash hash to to free */
1082 void isds_hash_free(struct isds_hash **hash);
1084 /* Deallocate structure isds_DbOwnerInfo recursively and NULL it */
1085 void isds_DbOwnerInfo_free(struct isds_DbOwnerInfo **db_owner_info);
1087 /* Deallocate structure isds_DbUserInfo recursively and NULL it */
1088 void isds_DbUserInfo_free(struct isds_DbUserInfo **db_user_info);
1090 /* Deallocate struct isds_event recursively and NULL it */
1091 void isds_event_free(struct isds_event **event);
1093 /* Deallocate struct isds_envelope recursively and NULL it */
1094 void isds_envelope_free(struct isds_envelope **envelope);
1096 /* Deallocate struct isds_document recursively and NULL it */
1097 void isds_document_free(struct isds_document **document);
1099 /* Deallocate struct isds_message recursively and NULL it */
1100 void isds_message_free(struct isds_message **message);
1102 /* Deallocate struct isds_message_copy recursively and NULL it */
1103 void isds_message_copy_free(struct isds_message_copy **copy);
1105 /* Deallocate struct isds_approval recursively and NULL it */
1106 void isds_approval_free(struct isds_approval **approval);
1108 /* Copy structure isds_PersonName recursively */
1109 struct isds_PersonName *isds_PersonName_duplicate(
1110 const struct isds_PersonName *template);
1112 /* Copy structure isds_Address recursively */
1113 struct isds_Address *isds_Address_duplicate(
1114 const struct isds_Address *template);
1116 /* Copy structure isds_DbOwnerInfo recursively */
1117 struct isds_DbOwnerInfo *isds_DbOwnerInfo_duplicate(
1118 const struct isds_DbOwnerInfo *template);
1120 /* Copy structure isds_DbUserInfo recursively */
1121 struct isds_DbUserInfo *isds_DbUserInfo_duplicate(
1122 const struct isds_DbUserInfo *template);
1124 #endif