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 <time.h> /* For struct tm */
9 #include <sys/time.h> /* For struct timeval */
10 #include <libxml/tree.h> /* For xmlDoc and xmlNodePtr */
12 #ifdef __cplusplus /* For C++ linker sake */
16 /* _deprecated macro marks library symbols as deprecated. Application should
17 * avoid using such function as soon as possible. */
19 #define _deprecated __attribute__((deprecated))
24 /* Service locators */
25 /* Base URL of production ISDS instance */
26 extern const char isds_locator
[]; /* Without client certificate auth. */
27 extern const char isds_cert_locator
[]; /* With client certificate auth. */
28 extern const char isds_otp_locator
[]; /* With OTP authentication */
29 /* Base URL of testing ISDS instance */
30 extern const char isds_testing_locator
[]; /* Without client certificate */
31 extern const char isds_cert_testing_locator
[]; /* With client certificate */
32 extern const char isds_otp_testing_locator
[]; /* With OTP authentication */
35 struct isds_ctx
; /* Context for specific ISDS box */
38 IE_SUCCESS
= 0, /* No error, just for C convenience (0 means Ok) */
39 IE_ERROR
, /* Unspecified error */
85 /* Return text description of ISDS error */
86 const char *isds_strerror(const isds_error error
);
90 IOPT_TLS_VERIFY_SERVER
, /* _Bool: Verify server identity?
91 Default value is true. */
92 IOPT_TLS_CA_FILE
, /* char *: File name with CA certificates.
93 Default value depends on cryptographic
95 IOPT_TLS_CA_DIRECTORY
, /* char *: Directory name with CA certificates.
96 Default value depends on cryptographic
98 IOPT_TLS_CRL_FILE
, /* char *: File name with CRL in PEM format.
99 Default value depends on cryptographic
101 IOPT_NORMALIZE_MIME_TYPE
, /* _Bool: Normalize MIME type values?
102 Default value is false. */
105 /* TLS libisds options */
107 ITLS_VERIFY_SERVER
, /* _Bool: Verify server identity? */
108 ITLS_CA_FILE
, /* char *: File name with CA certificates */
109 ITLS_CA_DIRECTORY
, /* char *: Directory name with CA certificates */
110 ITLS_CRL_FILE
/* char *: File name with CRL in PEM format */
113 /* Cryptographic material encoding */
115 PKI_FORMAT_PEM
, /* PEM format */
116 PKI_FORMAT_DER
, /* DER format */
117 PKI_FORMAT_ENG
/* Stored in crypto engine */
120 /* Public key crypto material to authenticate client */
121 struct isds_pki_credentials
{
122 char *engine
; /* String identifier of crypto engine to use
123 (where key is stored). Use NULL for no engine */
124 isds_pki_format certificate_format
; /* Certificate format */
125 char *certificate
; /* Path to client certificate, or certificate
126 nickname in case of NSS as curl back-end,
127 or key slot identifier inside crypto engine.
128 Some crypto engines can pair certificate with
129 key automatically (NULL value) */
130 isds_pki_format key_format
; /* Private key format */
131 char *key
; /* Path to client private key, or key identifier
132 in case of used engine */
133 char *passphrase
; /* Zero terminated string with password for
134 decrypting private key, or engine PIN.
135 Use NULL for no pass-phrase or question by
139 /* One-time password authentication method */
141 OTP_HMAC
= 0, /* HMAC-based OTP method */
142 OTP_TIME
/* Time-based OTP method */
145 /* One-time passwed authentication resolution */
147 OTP_RESOLUTION_SUCCESS
= 0, /* Authentication succeded */
148 OTP_RESOLUTION_UNKNOWN
, /* Status is unkown */
149 OTP_RESOLUTION_BAD_AUTHENTICATION
, /* Bad log-in, retry */
150 OTP_RESOLUTION_ACCESS_BLOCKED
, /* Access blocked for 60 minutes
151 (brute force attack detected) */
152 OTP_RESOLUTION_PASSWORD_EXPIRED
, /* Password has expired.
153 ???: OTP or regular password
155 OTP_RESOLUTION_TO_FAST
, /* OTP cannot be sent repeatedly
156 at this rate (minimal delay
157 depends on TOTP window setting) */
158 OTP_RESOLUTION_UNAUTHORIZED
, /* User name is not allowed to
159 access requested URI */
160 OTP_RESOLUTION_TOTP_SENT
, /* OTP has been generated and sent by
162 OTP_RESOLUTION_TOTP_NOT_SENT
, /* OTP could not been sent.
164 } isds_otp_resolution
;
166 /* One-time password to authenticate client */
169 isds_otp_method method
; /* Select OTP method to use */
170 char *otp_code
; /* One-time password to use. Pass NULL,
171 if you do not know it yet (e.g. in case
172 of first phase of time-based OTP to
173 request new code from ISDS.) */
175 isds_otp_resolution resolution
; /* Fine-grade resolution of OTP
176 authentication attempt. */
181 DBTYPE_OVM_MAIN
= -1, /* Special value for
182 isds_find_box_by_fulltext(). */
183 DBTYPE_SYSTEM
= 0, /* This is special sender value for messages
186 DBTYPE_OVM_NOTAR
= 11,
187 DBTYPE_OVM_EXEKUT
= 12,
193 DBTYPE_PFO_ADVOK
= 31,
194 DBTYPE_PFO_DANPOR
= 32,
195 DBTYPE_PFO_INSSPR
= 33,
199 /* Box status from point of view of accessibility */
201 DBSTATE_ACCESSIBLE
= 1,
202 DBSTATE_TEMP_UNACCESSIBLE
= 2,
203 DBSTATE_NOT_YET_ACCESSIBLE
= 3,
204 DBSTATE_PERM_UNACCESSIBLE
= 4,
206 DBSTATE_TEMP_UNACCESSIBLE_LAW
= 6
209 /* User permissions from point of view of ISDS.
210 * Instances can be bitmaps of any discrete values. */
212 PRIVIL_READ_NON_PERSONAL
= 0x1, /* Can download and read messages with
213 dmPersonalDelivery == false */
214 PRIVIL_READ_ALL
= 0x2, /* Can download and read messages with
215 dmPersonalDelivery == true */
216 PRIVIL_CREATE_DM
= 0x4, /* Can create and sent messages,
217 can download outgoing (sent) messages */
218 PRIVIL_VIEW_INFO
= 0x8, /* Can list messages and data about
220 PRIVIL_SEARCH_DB
= 0x10, /* Can search for boxes */
221 PRIVIL_OWNER_ADM
= 0x20, /* Can administer his box (add/remove
222 permitted users and theirs
224 PRIVIL_READ_VAULT
= 0x40, /* Can read message stored in long term
225 storage (does not exists since
227 PRIVIL_ERASE_VAULT
= 0x80 /* Can delete messages from long term
233 MESSAGESTATE_SENT
= 0x2, /* Message has been put into ISDS */
234 MESSAGESTATE_STAMPED
= 0x4, /* Message stamped by TSA */
235 MESSAGESTATE_INFECTED
= 0x8, /* Message included viruses,
236 infected document has been removed */
237 MESSAGESTATE_DELIVERED
= 0x10, /* Message delivered
238 (dmDeliveryTime stored) */
239 MESSAGESTATE_SUBSTITUTED
= 0x20, /* Message delivered through fiction,
240 dmAcceptanceTime stored */
241 MESSAGESTATE_RECEIVED
= 0x40, /* Message accepted (by user log-in or
242 user explicit request),
243 dmAcceptanceTime stored */
244 MESSAGESTATE_READ
= 0x80, /* Message has been read by user */
245 MESSAGESTATE_UNDELIVERABLE
= 0x100, /* Message could not been delivered
246 (e.g. recipient box has been made
247 inaccessible meantime) */
248 MESSAGESTATE_REMOVED
= 0x200, /* Message content deleted */
249 MESSAGESTATE_IN_SAFE
= 0x400 /* Message stored in long term storage */
250 } isds_message_status
;
251 #define MESSAGESTATE_ANY 0x7FE /* Union of all isds_message_status
254 /* Hash algorithm types */
257 HASH_ALGORITHM_SHA_1
,
258 HASH_ALGORITHM_SHA_224
,
259 HASH_ALGORITHM_SHA_256
,
260 HASH_ALGORITHM_SHA_384
,
261 HASH_ALGORITHM_SHA_512
,
262 } isds_hash_algorithm
;
264 /* Buffer storage strategy.
265 * How function should embed application provided buffer into raw element of
266 * output structure. */
268 BUFFER_DONT_STORE
, /* Don't fill raw member */
269 BUFFER_COPY
, /* Copy buffer content into newly allocated raw */
270 BUFFER_MOVE
/* Just copy pointer.
271 But leave deallocation to isds_*_free(). */
272 } isds_buffer_strategy
;
274 /* Hash value storage */
276 isds_hash_algorithm algorithm
; /* Hash algorithm */
277 size_t length
; /* Hash value length in bytes */
278 void *value
; /* Hash value */
282 struct isds_PersonName
{
286 char *pnLastNameAtBirth
;
289 /* Date and place of birth */
290 struct isds_BirthInfo
{
291 struct tm
*biDate
; /* Date of Birth in local time at birth place,
292 only tm_year, tm_mon and tm_mday carry sane
295 char *biCounty
; /* German: Bezirk, Czech: okres */
300 struct isds_Address
{
301 long int *adCode
; /* RUIN address code */
303 char *adDistrict
; /* Municipality part */
305 char *adNumberInStreet
;
306 char *adNumberInMunicipality
;
311 /* Data about box and his owner.
312 * NULL pointer means undefined value */
313 struct isds_DbOwnerInfo
{
314 char *dbID
; /* Box ID [Max. 7 chars] */
315 isds_DbType
*dbType
; /* Box Type */
317 struct isds_PersonName
*personName
; /* Name of person */
318 char *firmName
; /* Name of firm */
319 struct isds_BirthInfo
*birthInfo
; /* Birth of person */
320 struct isds_Address
*address
; /* Post address */
324 char *identifier
; /* External box identifier for data
325 provider (OVM, PO, maybe PFO)
327 _Bool
*aifoIsds
; /* Reference to citizen registry exists */
328 char *registryCode
; /* PFO External registry code
330 long int *dbState
; /* Box state; 1 <=> active box;
331 long int because xsd:integer
333 _Bool
*dbEffectiveOVM
; /* Box has OVM role (§ 5a) */
334 _Bool
*dbOpenAddressing
; /* Non-OVM Box is free to receive
335 messages from anybody */
340 USERTYPE_PRIMARY
, /* Owner of the box */
341 USERTYPE_ENTRUSTED
, /* User with limited access to the box */
342 USERTYPE_ADMINISTRATOR
, /* User to manage ENTRUSTED_USERs */
343 USERTYPE_OFFICIAL
, /* ??? */
344 USERTYPE_OFFICIAL_CERT
, /* ??? */
345 USERTYPE_LIQUIDATOR
/* Company liquidator */
349 * NULL pointer means undefined value */
350 struct isds_DbUserInfo
{
351 char *userID
; /* User ID [Min. 6, max. 12 characters] */
352 isds_UserType
*userType
; /* User type */
353 long int *userPrivils
; /* Set of user permissions */
354 struct isds_PersonName
*personName
; /* Name of the person */
355 struct isds_Address
*address
; /* Post address */
356 struct tm
*biDate
; /* Date of birth in local time,
357 only tm_year, tm_mon and tm_mday carry sane
359 char *ic
; /* ID of a supervising firm [Max. 8 chars] */
360 char *firmName
; /* Name of a supervising firm
362 char *caStreet
; /* Street and number of contact address */
363 char *caCity
; /* Czech City of contact address */
364 char *caZipCode
; /* Post office code of contact address */
365 char *caState
; /* Abbreviated country of contact address;
366 Implicit value is "CZ"; Optional. */
367 char *aifo_ticket
; /* AIFO ticket; Optional. */
370 /* Message event type */
372 EVENT_UKNOWN
, /* Event unknown to this library */
373 EVENT_ACCEPTED_BY_RECIPIENT
, /* Message has been delivered and accepted
374 by recipient action */
375 EVENT_ACCEPTED_BY_FICTION
, /* Message has been delivered, acceptance
376 timed out, considered as accepted */
377 EVENT_UNDELIVERABLE
, /* Recipient box made inaccessible,
378 thus message is undeliverable */
379 EVENT_COMMERCIAL_ACCEPTED
, /* Recipient confirmed acceptance of
380 commercial message */
381 EVENT_ENTERED_SYSTEM
, /* Message entered ISDS, i.e. has been just
383 EVENT_DELIVERED
, /* Message has been delivered */
384 EVENT_PRIMARY_LOGIN
, /* Primary user has logged in */
385 EVENT_ENTRUSTED_LOGIN
, /* Entrusted user with capability to read
387 EVENT_SYSCERT_LOGIN
/* Application authenticated by `system'
388 certificate has logged in */
392 * All members are optional as specification states so. */
394 struct timeval
*time
; /* When the event occurred */
395 isds_event_type
*type
; /* Type of the event */
396 char *description
; /* Human readable event description
397 generated by ISDS (Czech) */
401 * Be ware that the string length constraints are forced only on output
402 * members transmitted to ISDS. The other direction (downloaded from ISDS)
403 * can break these rules. It should not happen, but nobody knows how much
404 * incompatible new version of ISDS protocol will be. This is the gold
405 * Internet rule: be strict on what you put, be tolerant on what you get. */
406 struct isds_envelope
{
407 /* Following members apply to incoming messages only: */
408 char *dmID
; /* Message ID.
409 Maximal length is 20 characters. */
410 char *dbIDSender
; /* Box ID of sender.
411 Special value "aaaaaaa" means sent by
413 Maximal length is 7 characters. */
414 char *dmSender
; /* Sender name;
415 Maximal length is 100 characters. */
416 char *dmSenderAddress
; /* Postal address of sender;
417 Maximal length is 100 characters. */
418 long int *dmSenderType
; /* Gross Box type of sender
419 TODO: isds_DbType ? */
420 char *dmRecipient
; /* Recipient name;
421 Maximal length is 100 characters. */
422 char *dmRecipientAddress
; /* Postal address of recipient;
423 Maximal length is 100 characters. */
424 _Bool
*dmAmbiguousRecipient
; /* Recipient has OVM role */
426 /* Following members are assigned by ISDS in different phases of message
428 unsigned long int *dmOrdinal
; /* Ordinal number in list of
429 incoming/outgoing messages */
430 isds_message_status
*dmMessageStatus
; /* Message state */
431 long int *dmAttachmentSize
; /* Size of message documents in
432 kilobytes (rounded). */
433 struct timeval
*dmDeliveryTime
; /* Time of delivery into a box
434 NULL, if message has not been
436 struct timeval
*dmAcceptanceTime
; /* Time of acceptance of the message
437 by an user. NULL if message has not
438 been accepted yet. */
439 struct isds_hash
*hash
; /* Message hash.
440 This is hash of isds:dmDM subtree. */
441 void *timestamp
; /* Qualified time stamp; Optional. */
442 size_t timestamp_length
; /* Length of timestamp in bytes */
443 struct isds_list
*events
; /* Events message passed trough;
444 List of isds_event's. */
447 /* Following members apply to both outgoing and incoming messages: */
448 char *dmSenderOrgUnit
; /* Organisation unit of sender as string;
450 long int *dmSenderOrgUnitNum
; /* Organisation unit of sender as number;
452 char *dbIDRecipient
; /* Box ID of recipient; Mandatory.
453 Maximal length is 7 characters. */
454 char *dmRecipientOrgUnit
; /* Organisation unit of recipient as
456 long int *dmRecipientOrgUnitNum
; /* Organisation unit of recipient as
458 char *dmToHands
; /* Person in recipient organisation;
460 char *dmAnnotation
; /* Subject (title) of the message.
461 Maximal length is 255 characters. */
462 char *dmRecipientRefNumber
; /* Czech: číslo jednací příjemce; Optional.
463 Maximal length is 50 characters. */
464 char *dmSenderRefNumber
; /* Czech: číslo jednací odesílatele;
465 Optional. Maximal length is 50 chars. */
466 char *dmRecipientIdent
; /* Czech: spisová značka příjemce; Optional.
467 Maximal length is 50 characters. */
468 char *dmSenderIdent
; /* Czech: spisová značka odesílatele;
469 Optional. Maximal length is 50 chars. */
471 /* Act addressing in Czech Republic:
472 * Point (Paragraph) § Section Law/Year Coll. */
473 long int *dmLegalTitleLaw
; /* Number of act mandating authority */
474 long int *dmLegalTitleYear
; /* Year of act issue mandating authority */
475 char *dmLegalTitleSect
; /* Section of act mandating authority.
477 char *dmLegalTitlePar
; /* Paragraph of act mandating authority.
479 char *dmLegalTitlePoint
; /* Point of act mandating authority.
482 _Bool
*dmPersonalDelivery
; /* If true, only person with higher
483 privileges can read this message */
484 _Bool
*dmAllowSubstDelivery
; /* Allow delivery through fiction.
485 I.e. Even if recipient did not read this
486 message, message is considered as
487 delivered after (currently) 10 days.
488 This is delivery through fiction.
489 Applies only to OVM dbType sender. */
490 char *dmType
; /* Message type (commercial subtypes or
492 Input values (when sending a message):
493 "I" is commercial message offering
494 paying the response (initiatory
496 it's necessary to define
498 "K" is commercial message paid by sender
500 "O" is commercial response paid by
501 sender of initiatory message; it's
502 necessary to copy value from
503 dmSenderRefNumber of initiatory
504 message to dmRecipientRefNumber
506 "V" is noncommercial government message
507 Default value while sending is undefined
508 which has the same meaning as "V".
509 Output values (when retrieving
511 "A" is subsidized initiatory commercial
512 message which can pay a response
513 "B" is subsidized initiatory commercial
514 message which has already paid the
516 "C" is subsidized initiatory commercial
517 message where the response offer has
519 "D" is externally subsidized commercial
521 "E" is commercial message prepaid by
523 "G" is commerical message paid by
529 "X" is initiatory commercial message
530 where the response offer has expired
531 "Y" initiatory commercial message which
532 has already paid the response
533 "Z" is limitedly subsidized commercial
535 Length: Exactly 1 UTF-8 character if
538 /* Following members apply to outgoing messages only: */
539 _Bool
*dmOVM
; /* OVM sending mode.
540 Non-OVM dbType boxes that has
541 dbEffectiveOVM == true MUST select
542 between true (OVM mode) and
543 false (non-OVM mode).
544 Optional; Implicit value is true. */
545 _Bool
*dmPublishOwnID
; /* Allow sender to express his name shall
546 be available to recipient by
547 isds_get_message_sender(). Sender type
548 will be always available.
549 Optional; Default value is false. */
553 /* Document type from point of hierarchy */
555 FILEMETATYPE_MAIN
, /* Main document */
556 FILEMETATYPE_ENCLOSURE
, /* Appendix */
557 FILEMETATYPE_SIGNATURE
, /* Digital signature of other document */
558 FILEMETATYPE_META
/* XML document for ESS (electronic
559 document information system) purposes */
563 struct isds_document
{
564 _Bool is_xml
; /* True if document is ISDS XML document.
565 False if document is ISDS binary
567 xmlNodePtr xml_node_list
; /* XML node-set presenting current XML
568 document content. This is pointer to
569 first node of the document in
570 isds_message.xml tree. Use `children'
571 and `next' members to iterate the
573 It will be NULL if document is empty.
574 Valid only if is_xml is true. */
575 void *data
; /* Document content.
576 The encoding and interpretation depends
578 Valid only if is_xml is false. */
579 size_t data_length
; /* Length of the data in bytes.
580 Valid only if is_xml is false. */
582 char *dmMimeType
; /* MIME type of data; Mandatory. */
583 isds_FileMetaType dmFileMetaType
; /* Document type to create hierarchy */
584 char *dmFileGuid
; /* Message-local document identifier;
586 char *dmUpFileGuid
; /* Reference to upper document identifier
587 (dmFileGuid); Optional. */
588 char *dmFileDescr
; /* Document name (title). E.g. file name;
590 char *dmFormat
; /* Reference to XML form definition;
591 Defines how to interpret XML document;
595 /* Raw message representation content type.
596 * This is necessary to distinguish between different representations without
597 * expensive repeated detection.
599 * PLAIN_SIGNED data are XML with namespace mangled to signed alternative
600 * CMS_SIGNED data are XML with signed namespace encapsulated in CMS */
602 RAWTYPE_INCOMING_MESSAGE
,
603 RAWTYPE_PLAIN_SIGNED_INCOMING_MESSAGE
,
604 RAWTYPE_CMS_SIGNED_INCOMING_MESSAGE
,
605 RAWTYPE_PLAIN_SIGNED_OUTGOING_MESSAGE
,
606 RAWTYPE_CMS_SIGNED_OUTGOING_MESSAGE
,
607 RAWTYPE_DELIVERYINFO
,
608 RAWTYPE_PLAIN_SIGNED_DELIVERYINFO
,
609 RAWTYPE_CMS_SIGNED_DELIVERYINFO
613 struct isds_message
{
614 void *raw
; /* Raw message in XML format as send to or
615 from the ISDS. You can use it to store
616 local copy. This is binary buffer. */
617 size_t raw_length
; /* Length of raw message in bytes */
618 isds_raw_type raw_type
; /* Content type of raw representation
619 Meaningful only with non-NULL raw
621 xmlDocPtr xml
; /* Parsed XML document with attached ISDS
622 message XML documents.
623 Can be NULL. May be freed AFTER deallocating
624 documents member structure. */
625 struct isds_envelope
*envelope
; /* Message envelope */
626 struct isds_list
*documents
; /* List of isds_document's.
627 Valid message must contain exactly one
628 document of type FILEMETATYPE_MAIN and
629 can contain any number of other type
630 documents. Total size of documents
631 must not exceed 20 MB. */
634 /* Message copy recipient and assigned message ID */
635 struct isds_message_copy
{
636 /* Input members defined by application */
637 char *dbIDRecipient
; /* Box ID of recipient; Mandatory.
638 Maximal length is 7 characters. */
639 char *dmRecipientOrgUnit
; /* Organisation unit of recipient as
641 long int *dmRecipientOrgUnitNum
; /* Organisation unit of recipient as
643 char *dmToHands
; /* Person in recipient organisation;
646 /* Output members returned from ISDS */
647 isds_error error
; /* libisds compatible error of delivery to o ne recipient */
648 char *dmStatus
; /* Error description returned by ISDS;
650 char *dmID
; /* Assigned message ID; Meaningful only
651 for error == IE_SUCCESS */
654 /* Message state change event */
655 struct isds_message_status_change
{
656 char *dmID
; /* Message ID. */
657 isds_message_status
*dmMessageStatus
; /* Message state */
658 struct timeval
*time
; /* When the state changed */
661 /* How outgoing commercial message gets paid */
663 PAYMENT_SENDER
, /* Payed by a sender */
664 PAYMENT_STAMP
, /* Pre-paid by a sender */
665 PAYMENT_SPONSOR
, /* A sponsor pays all messages */
666 PAYMENT_RESPONSE
, /* Recipient pays a response */
667 PAYMENT_SPONSOR_LIMITED
, /* Undocumented */
668 PAYMENT_SPONSOR_EXTERNAL
/* Undocomented */
671 /* Permission to send commercial message */
672 struct isds_commercial_permission
{
673 isds_payment_type type
; /* Payment method */
674 char *recipient
; /* Send to this box ID only;
675 NULL means to anybody. */
676 char *payer
; /* Owner of this box ID pays */
677 struct timeval
*expiration
; /* This permissions is valid until;
678 NULL means indefinitivly. */
679 unsigned long int *count
; /* Number of messages that can be sent
681 NULL means unlimited. */
682 char *reply_identifier
; /* Identifier to pair request and response
683 message. Meaningful only with type
687 /* Type of credit change event */
689 ISDS_CREDIT_CHARGED
, /* Credit has been charged */
690 ISDS_CREDIT_DISCHARGED
, /* Credit has been discharged */
691 ISDS_CREDIT_MESSAGE_SENT
, /* Credit has been spent for sending
692 a commerical message */
693 ISDS_CREDIT_STORAGE_SET
, /* Credit has been spent for setting
694 a long-term storage */
695 ISDS_CREDIT_EXPIRED
/* Credit has expired */
696 } isds_credit_event_type
;
698 /* Data specific for ISDS_CREDIT_CHARGED isds_credit_event_type */
699 struct isds_credit_event_charged
{
700 char *transaction
; /* Transaction identifier;
701 NULL-terminated string. */
704 /* Data specific for ISDS_CREDIT_DISCHARGED isds_credit_event_type */
705 struct isds_credit_event_discharged
{
706 char *transaction
; /* Transaction identifier;
707 NULL-terminated string. */
710 /* Data specific for ISDS_CREDIT_MESSAGE_SENT isds_credit_event_type */
711 struct isds_credit_event_message_sent
{
712 char *recipient
; /* Recipent's box ID of the sent message */
713 char *message_id
; /* ID of the sent message */
716 /* Data specific for ISDS_CREDIT_STORAGE_SET isds_credit_event_type */
717 struct isds_credit_event_storage_set
{
718 long int new_capacity
; /* New storage capacity. The unit is
720 struct tm
*new_valid_from
; /* The new capacity is available since
722 struct tm
*new_valid_to
; /* The new capacity expires on date. */
723 long int *old_capacity
; /* Previous storage capacity; Optional.
724 The unit is a message. */
725 struct tm
*old_valid_from
; /* Date; Optional; Only tm_year,
726 tm_mon, and tm_mday carry sane value. */
727 struct tm
*old_valid_to
; /* Date; Optional. */
728 char *initiator
; /* Name of a user who initiated this
732 /* Event about change of credit for sending commerical services */
733 struct isds_credit_event
{
735 struct timeval
*time
; /* When the credit was changed. */
736 long int credit_change
; /* Difference in credit value caused by
737 this event. The unit is 1/100 CZK. */
738 long int new_credit
; /* Credit value after this event.
739 The unit is 1/100 CZK. */
740 isds_credit_event_type type
; /* Type of the event */
742 /* Datails specific for the type */
744 struct isds_credit_event_charged charged
;
745 /* ISDS_CREDIT_CHARGED */
746 struct isds_credit_event_discharged discharged
;
747 /* ISDS_CREDIT_DISCHAGED */
748 struct isds_credit_event_message_sent message_sent
;
749 /* ISDS_CREDIT_MESSAGE_SENT */
750 struct isds_credit_event_storage_set storage_set
;
751 /* ISDS_CREDIT_STORAGE_SET */
755 /* General linked list */
757 struct isds_list
*next
; /* Next list item,
758 or NULL if current is last */
759 void *data
; /* Payload */
760 void (*destructor
) (void **); /* Payload deallocator;
761 Use NULL to have static data member. */
764 /* External box approval */
765 struct isds_approval
{
766 _Bool approved
; /* True if request for box has been
767 approved out of ISDS */
768 char *refference
; /* Identifier of the approval */
771 /* Message sender type.
772 * Similar but not equivalent to isds_UserType. */
774 SENDERTYPE_PRIMARY
, /* Owner of the box */
775 SENDERTYPE_ENTRUSTED
, /* User with limited access to the box */
776 SENDERTYPE_ADMINISTRATOR
, /* User to manage ENTRUSTED_USERs */
777 SENDERTYPE_OFFICIAL
, /* ISDS; sender of system message */
778 SENDERTYPE_VIRTUAL
, /* An application (e.g. document
779 information system) */
780 SENDERTYPE_OFFICIAL_CERT
, /* ???; Non-normative */
781 SENDERTYPE_LIQUIDATOR
/* Liquidator of the company; Non-normative */
784 /* Digital delivery of credentials */
785 struct isds_credentials_delivery
{
787 char *email
; /* e-mail address where to send
788 notification with link to service where
789 user can get know his new credentials */
791 char *token
; /* token user needs to use to authorize on
792 the web server to view his new
794 char *new_user_name
; /* user's log-in name that ISDS created/
795 changed up on a call. */
798 /* Box attribute to search while performing full-text search */
800 FULLTEXT_ALL
, /* search in address, organization identifier, and
802 FULLTEXT_ADDRESS
, /* search in address */
803 FULLTEXT_IC
, /* search in organization identifier */
804 FULLTEXT_BOX_ID
/* search in box ID */
805 } isds_fulltext_target
;
807 /* A box matching full-text search */
808 struct isds_fulltext_result
{
809 char *dbID
; /* Box ID */
810 isds_DbType dbType
; /* Box Type */
811 char *name
; /* Subject owning the box */
812 struct isds_list
*name_match_start
; /* List of pointers into `name'
813 field string. Point to first
814 characters of a matched query
816 struct isds_list
*name_match_end
; /* List of pointers into `name'
817 field string. Point after last
818 characters of a matched query
820 char *address
; /* Post address */
821 struct isds_list
*address_match_start
; /* List of pointers into `address'
822 field string. Point to first
823 characters of a matched query
825 struct isds_list
*address_match_end
; /* List of pointers into `address'
826 field string. Point after last
827 characters of a matched query
829 char *ic
; /* Organization identifier */
830 struct tm
*biDate
; /* Date of birth in local time at birth place,
831 only tm_year, tm_mon and tm_mday carry sane
833 _Bool dbEffectiveOVM
; /* Box has OVM role (§ 5a) */
834 _Bool active
; /* Box is active */
835 _Bool public_sending
; /* Current box can send non-commercial
836 messages into this box */
837 _Bool commercial_sending
; /* Current box can send commercial messages
841 /* A box state valid in the time range */
842 struct isds_box_state_period
{
843 struct timeval from
; /* Time range beginning */
844 struct timeval to
; /* Time range end */
845 long int dbState
; /* Box state; 1 <=> active box, otherwise
846 inaccessible; use isds_DbState enum to
847 identify some states. */
850 /* Initialize ISDS library.
851 * Global function, must be called before other functions.
852 * If it fails you can not use ISDS library and must call isds_cleanup() to
853 * free partially initialized global variables. */
854 isds_error
isds_init(void);
856 /* Deinitialize ISDS library.
857 * Global function, must be called as last library function. */
858 isds_error
isds_cleanup(void);
860 /* Return version string of this library. Version of dependencies can be
861 * embedded. Do no try to parse it. You must free it. */
862 char *isds_version(void);
864 /* Create ISDS context.
865 * Each context can be used for different sessions to (possibly) different
866 * ISDS server with different credentials.
867 * Returns new context, or NULL */
868 struct isds_ctx
*isds_ctx_create(void);
870 /* Destroy ISDS context and free memory.
871 * @context will be NULLed on success. */
872 isds_error
isds_ctx_free(struct isds_ctx
**context
);
874 /* Return long message text produced by library function, e.g. detailed error
875 * message. Returned pointer is only valid until new library function is
876 * called for the same context. Could be NULL, especially if NULL context is
877 * supplied. Return string is locale encoded. */
878 char *isds_long_message(const struct isds_ctx
*context
);
881 * @facilities is bit mask of isds_log_facility values,
882 * @level is verbosity level. */
883 void isds_set_logging(const unsigned int facilities
,
884 const isds_log_level level
);
886 /* Function provided by application libisds will call to pass log message.
887 * The message is usually locale encoded, but raw strings (UTF-8 usually) can
888 * occur when logging raw communication with ISDS servers. Infixed zero byte
889 * is not excluded, but should not present. Use @length argument to get real
890 * length of the message.
891 * TODO: We will try to fix the encoding issue
892 * @facility is log message class
893 * @level is log message severity
894 * @message is string with zero byte terminator. This can be any arbitrary
895 * chunk of a sentence with or without new line, a sentence can be splitted
896 * into more messages. However it should not happen. If you discover message
897 * without new line, report it as a bug.
898 * @length is size of @message string in bytes excluding trailing zero
899 * @data is pointer that will be passed unchanged to this function at run-time
901 typedef void (*isds_log_callback
)(
902 isds_log_facility facility
, isds_log_level level
,
903 const char *message
, int length
, void *data
);
905 /* Register callback function libisds calls when new global log message is
906 * produced by library. Library logs to stderr by default.
907 * @callback is function provided by application libisds will call. See type
908 * definition for @callback argument explanation. Pass NULL to revert logging to
910 * @data is application specific data @callback gets as last argument */
911 void isds_set_log_callback(isds_log_callback callback
, void *data
);
913 /* Set timeout in milliseconds for each network job like connecting to server
914 * or sending message. Use 0 to disable timeout limits. */
915 isds_error
isds_set_timeout(struct isds_ctx
*context
,
916 const unsigned int timeout
);
918 /* Function provided by application libisds will call with
919 * following five arguments. Value zero of any argument means the value is
921 * @upload_total is expected total upload,
922 * @upload_current is cumulative current upload progress
923 * @dowload_total is expected total download
924 * @download_current is cumulative current download progress
925 * @data is pointer that will be passed unchanged to this function at run-time
926 * @return 0 to continue HTTP transfer, or non-zero to abort transfer */
927 typedef int (*isds_progress_callback
)(
928 double upload_total
, double upload_current
,
929 double download_total
, double download_current
,
932 /* Register callback function libisds calls periodically during HTTP data
934 * @context is session context
935 * @callback is function provided by application libisds will call. See type
936 * definition for @callback argument explanation.
937 * @data is application specific data @callback gets as last argument */
938 isds_error
isds_set_progress_callback(struct isds_ctx
*context
,
939 isds_progress_callback callback
, void *data
);
941 /* Change context settings.
942 * @context is context which setting will be applied to
943 * @option is name of option. It determines the type of last argument. See
944 * isds_option definition for more info.
945 * @... is value of new setting. Type is determined by @option
947 isds_error
isds_set_opt(struct isds_ctx
*context
, const isds_option option
,
950 /* Connect and log into ISDS server.
951 * All required arguments will be copied, you do not have to keep them after
953 * ISDS supports six different authentication methods. Exact method is
954 * selected on @username, @password, @pki_credentials, and @otp arguments:
955 * - If @pki_credentials == NULL, @username and @password must be supplied
957 * - If @otp == NULL, simple authentication by username and password will
959 * - If @otp != NULL, authentication by username and password and OTP
961 * - If @pki_credentials != NULL, then
962 * - If @username == NULL, only certificate will be used
963 * - If @username != NULL, then
964 * - If @password == NULL, then certificate will be used and
965 * @username shifts meaning to box ID. This is used for hosted
967 * - Otherwise all three arguments will be used.
968 * Please note, that different cases require different certificate type
969 * (system qualified one or commercial non qualified one). This library
970 * does not check such political issues. Please see ISDS Specification
972 * @url is base address of ISDS web service. Pass extern isds_locator
973 * variable to use production ISDS instance without client certificate
974 * authentication (or extern isds_cert_locator with client certificate
975 * authentication or extern isds_otp_locators with OTP authentication).
976 * Passing NULL has the same effect, autoselection between isds_locator,
977 * isds_cert_locator, and isds_otp_locator is performed in addition. You can
978 * pass extern isds_testing_locator (or isds_cert_testing_locator or
979 * isds_otp_testing_locator) variable to select testing instance.
980 * @username is user name of ISDS user or box ID
981 * @password is user's secret password
982 * @pki_credentials defines public key cryptographic material to use in client
984 * @otp selects one-time password authentication method to use, defines OTP
985 * code (if known) and returns fine grade resolution of OTP procedure.
987 * IE_SUCCESS if authentication succeeds
988 * IE_NOT_LOGGED_IN if authentication fails. If OTP authentication has been
989 * requested, fine grade reason will be set into @otp->resolution. Error
990 * message from server can be obtained by isds_long_message() call.
991 * IE_PARTIAL_SUCCESS if time-based OTP authentication has been requested and
992 * server has sent OTP code through side channel. Application is expected to
993 * fill the code into @otp->otp_code, keep other arguments unchanged, and retry
994 * this call to complete second phase of TOTP authentication;
995 * or other appropriate error. */
996 isds_error
isds_login(struct isds_ctx
*context
, const char *url
,
997 const char *username
, const char *password
,
998 const struct isds_pki_credentials
*pki_credentials
,
999 struct isds_otp
*otp
);
1001 /* Log out from ISDS server and close connection. */
1002 isds_error
isds_logout(struct isds_ctx
*context
);
1004 /* Verify connection to ISDS is alive and server is responding.
1005 * Send dummy request to ISDS and expect dummy response. */
1006 isds_error
isds_ping(struct isds_ctx
*context
);
1008 /* Get data about logged in user and his box.
1009 * @context is session context
1010 * @db_owner_info is reallocated box owner description. It will be freed on
1012 * @return error code from lower layer, context message will be set up
1014 isds_error
isds_GetOwnerInfoFromLogin(struct isds_ctx
*context
,
1015 struct isds_DbOwnerInfo
**db_owner_info
);
1017 /* Get data about logged in user. */
1018 isds_error
isds_GetUserInfoFromLogin(struct isds_ctx
*context
,
1019 struct isds_DbUserInfo
**db_user_info
);
1021 /* Get expiration time of current password
1022 * @context is session context
1023 * @expiration is automatically reallocated time when password expires. If
1024 * password expiration is disabled, NULL will be returned. In case of error
1025 * it will be nulled too. */
1026 isds_error
isds_get_password_expiration(struct isds_ctx
*context
,
1027 struct timeval
**expiration
);
1029 /* Change user password in ISDS.
1030 * User must supply old password, new password will takes effect after some
1031 * time, current session can continue. Password must fulfill some constraints.
1032 * @context is session context
1033 * @old_password is current password.
1034 * @new_password is requested new password
1035 * @otp auxiliary data required if one-time password authentication is in use,
1036 * defines OTP code (if known) and returns fine grade resolution of OTP
1037 * procedure. Pass NULL, if one-time password authentication is not needed.
1038 * Please note the @otp argument must match OTP method used at log-in time. See
1039 * isds_login() function for more details.
1040 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1041 * NULL, if you don't care.
1042 * @return IE_SUCCESS, if password has been changed. Or returns appropriate
1043 * error code. It can return IE_PARTIAL_SUCCESS if OTP is in use and server is
1044 * awaiting OTP code that has been delivered by side channel to the user. */
1045 isds_error
isds_change_password(struct isds_ctx
*context
,
1046 const char *old_password
, const char *new_password
,
1047 struct isds_otp
*otp
, char **refnumber
);
1050 * @context is session context
1051 * @box is box description to create including single primary user (in case of
1052 * FO box type). aifoIsds, address->adCode, address->adDistrict members are
1053 * ignored. It outputs box ID assigned by ISDS in dbID element.
1054 * @users is list of struct isds_DbUserInfo (primary users in case of non-FO
1055 * box, or contact address of PFO box owner)
1056 * @former_names is optional former name of box owner. Pass NULL if you don't care.
1057 * @upper_box_id is optional ID of supper box if currently created box is
1059 * @ceo_label is optional title of OVM box owner (e.g. mayor)
1060 * @credentials_delivery is NULL if new password should be delivered off-line
1061 * to box owner. It is valid pointer if owner should obtain new password on-line
1062 * on dedicated web server. Then input @credentials_delivery.email value is
1063 * his e-mail address he must provide to dedicated web server together
1064 * with output reallocated @credentials_delivery.token member. Output
1065 * member @credentials_delivery.new_user_name is unused up on this call.
1066 * @approval is optional external approval of box manipulation
1067 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1068 * NULL, if you don't care.*/
1069 isds_error
isds_add_box(struct isds_ctx
*context
,
1070 struct isds_DbOwnerInfo
*box
, const struct isds_list
*users
,
1071 const char *former_names
, const char *upper_box_id
,
1072 const char *ceo_label
,
1073 struct isds_credentials_delivery
*credentials_delivery
,
1074 const struct isds_approval
*approval
, char **refnumber
);
1076 /* Notify ISDS about new PFO entity.
1077 * This function has no real effect.
1078 * @context is session context
1079 * @box is PFO description including single primary user. aifoIsds,
1080 * address->adCode, address->adDistrict members are ignored.
1081 * @users is list of struct isds_DbUserInfo (contact address of PFO box owner)
1082 * @former_names is optional undocumented string. Pass NULL if you don't care.
1083 * @upper_box_id is optional ID of supper box if currently created box is
1085 * @ceo_label is optional title of OVM box owner (e.g. mayor)
1086 * @approval is optional external approval of box manipulation
1087 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1088 * NULL, if you don't care.*/
1089 isds_error
isds_add_pfoinfo(struct isds_ctx
*context
,
1090 const struct isds_DbOwnerInfo
*box
, const struct isds_list
*users
,
1091 const char *former_names
, const char *upper_box_id
,
1092 const char *ceo_label
, const struct isds_approval
*approval
,
1095 /* Remove given box permanently.
1096 * @context is session context
1097 * @box is box description to delete. aifoIsds, address->adCode,
1098 * address->adDistrict members are ignored.
1099 * @since is date of box owner cancellation. Only tm_year, tm_mon and tm_mday
1101 * @approval is optional external approval of box manipulation
1102 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1103 * NULL, if you don't care.*/
1104 isds_error
isds_delete_box(struct isds_ctx
*context
,
1105 const struct isds_DbOwnerInfo
*box
, const struct tm
*since
,
1106 const struct isds_approval
*approval
, char **refnumber
);
1108 /* Undocumented function.
1109 * @context is session context
1110 * @box is box description to delete. aifoIsds, address->adCode,
1111 * address->adDistrict members are ignored.
1112 * @approval is optional external approval of box manipulation
1113 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1114 * NULL, if you don't care.*/
1115 isds_error
isds_delete_box_promptly(struct isds_ctx
*context
,
1116 const struct isds_DbOwnerInfo
*box
,
1117 const struct isds_approval
*approval
, char **refnumber
);
1119 /* Update data about given box.
1120 * @context is session context
1121 * @old_box current box description. aifoIsds, address->adCode,
1122 * address->adDistrict members are ignored.
1123 * @new_box are updated data about @old_box. aifoIsds, address->adCode,
1124 * address->adDistrict members are ignored.
1125 * @approval is optional external approval of box manipulation
1126 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1127 * NULL, if you don't care.*/
1128 isds_error
isds_UpdateDataBoxDescr(struct isds_ctx
*context
,
1129 const struct isds_DbOwnerInfo
*old_box
,
1130 const struct isds_DbOwnerInfo
*new_box
,
1131 const struct isds_approval
*approval
, char **refnumber
);
1133 /* Get data about all users assigned to given box.
1134 * @context is session context
1136 * @users is automatically reallocated list of struct isds_DbUserInfo */
1137 isds_error
isds_GetDataBoxUsers(struct isds_ctx
*context
, const char *box_id
,
1138 struct isds_list
**users
);
1140 /* Update data about user assigned to given box.
1141 * @context is session context
1142 * @box is box identification. aifoIsds, address->adCode,
1143 * address->adDistrict members are ignored.
1144 * @old_user identifies user to update, aifo_ticket member is ignored
1145 * @new_user are updated data about @old_user, aifo_ticket member is ignored
1146 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1147 * NULL, if you don't care.*/
1148 isds_error
isds_UpdateDataBoxUser(struct isds_ctx
*context
,
1149 const struct isds_DbOwnerInfo
*box
,
1150 const struct isds_DbUserInfo
*old_user
,
1151 const struct isds_DbUserInfo
*new_user
,
1154 /* Undocumented function.
1155 * @context is session context
1156 * @box_id is UTF-8 encoded box identifier
1157 * @token is UTF-8 encoded temporary password
1158 * @user_id outputs UTF-8 encoded reallocated user identifier
1159 * @password outpus UTF-8 encoded reallocated user password
1160 * Output arguments will be nulled in case of error */
1161 isds_error
isds_activate(struct isds_ctx
*context
,
1162 const char *box_id
, const char *token
,
1163 char **user_id
, char **password
);
1165 /* Reset credentials of user assigned to given box.
1166 * @context is session context
1167 * @box is box identification. aifoIsds, address->adCode, address->adDistrict
1168 * members are ignored.
1169 * @user identifies user to reset password, aifo_ticket member is ignored
1170 * @fee_paid is true if fee has been paid, false otherwise
1171 * @approval is optional external approval of box manipulation
1172 * @credentials_delivery is NULL if new password should be delivered off-line
1173 * to the user. It is valid pointer if user should obtain new password on-line
1174 * on dedicated web server. Then input @credentials_delivery.email value is
1175 * user's e-mail address user must provide to dedicated web server together
1176 * with @credentials_delivery.token. The output reallocated token user needs
1177 * to use to authorize on the web server to view his new password. Output
1178 * reallocated @credentials_delivery.new_user_name is user's log-in name that
1179 * ISDS changed up on this call. (No reason why server could change the name
1181 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1182 * NULL, if you don't care.*/
1183 isds_error
isds_reset_password(struct isds_ctx
*context
,
1184 const struct isds_DbOwnerInfo
*box
,
1185 const struct isds_DbUserInfo
*user
,
1186 const _Bool fee_paid
, const struct isds_approval
*approval
,
1187 struct isds_credentials_delivery
*credentials_delivery
,
1190 /* Assign new user to given box.
1191 * @context is session context
1192 * @box is box identification. aifoIsds, address->adCode, address->adDistrict
1193 * members are ignored.
1194 * @user defines new user to add
1195 * @credentials_delivery is NULL if new user's password should be delivered
1196 * off-line to the user. It is valid pointer if user should obtain new
1197 * password on-line on dedicated web server. Then input
1198 * @credentials_delivery.email value is user's e-mail address user must
1199 * provide to dedicated web server together with @credentials_delivery.token.
1200 * The output reallocated token user needs to use to authorize on the web
1201 * server to view his new password. Output reallocated
1202 * @credentials_delivery.new_user_name is user's log-in name that ISDS
1203 * assingned up on this call.
1204 * @approval is optional external approval of box manipulation
1205 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1206 * NULL, if you don't care.*/
1207 isds_error
isds_add_user(struct isds_ctx
*context
,
1208 const struct isds_DbOwnerInfo
*box
, const struct isds_DbUserInfo
*user
,
1209 struct isds_credentials_delivery
*credentials_delivery
,
1210 const struct isds_approval
*approval
, char **refnumber
);
1212 /* Remove user assigned to given box.
1213 * @context is session context
1214 * @box is box identification. aifoIsds, address->adCode, address->adDistrict
1215 * members are ignored.
1216 * @user identifies user to remove, aifo_ticket member is ignored
1217 * @approval is optional external approval of box manipulation
1218 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1219 * NULL, if you don't care.*/
1220 isds_error
isds_delete_user(struct isds_ctx
*context
,
1221 const struct isds_DbOwnerInfo
*box
, const struct isds_DbUserInfo
*user
,
1222 const struct isds_approval
*approval
, char **refnumber
);
1224 /* Get list of boxes in ZIP archive.
1225 * @context is session context
1226 * @list_identifier is UTF-8 encoded string identifying boxes of interrest.
1227 * System recognizes following values currently: ALL (all boxes), UPG
1228 * (effectively OVM boxes), POA (active boxes allowing receiving commercial
1229 * messages), OVM (OVM gross type boxes), OPN (boxes allowing receiving
1230 * commercial messages). This argument is a string because specification
1231 * states new values can appear in the future. Not all list types are
1232 * available to all users.
1233 * @buffer is automatically reallocated memory to store the list of boxes. The
1234 * list is zipped CSV file.
1235 * @buffer_length is size of @buffer data in bytes.
1236 * In case of error @buffer will be freed and @buffer_length will be
1238 isds_error
isds_get_box_list_archive(struct isds_ctx
*context
,
1239 const char *list_identifier
, void **buffer
, size_t *buffer_length
);
1241 /* Find boxes suiting given criteria.
1242 * @context is ISDS session context.
1243 * @criteria is filter. You should fill in at least some members. aifoIsds,
1244 * address->adCode, address->adDistrict members are ignored.
1245 * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
1246 * possibly empty. Input NULL or valid old structure.
1248 * IE_SUCCESS if search succeeded, @boxes contains useful data
1249 * IE_NOEXIST if no such box exists, @boxes will be NULL
1250 * IE_2BIG if too much boxes exist and server truncated the results, @boxes
1251 * contains still valid data
1252 * other code if something bad happens. @boxes will be NULL. */
1253 isds_error
isds_FindDataBox(struct isds_ctx
*context
,
1254 const struct isds_DbOwnerInfo
*criteria
,
1255 struct isds_list
**boxes
);
1257 /* Find accessible FO-type boxes suiting given criteria.
1258 * @criteria is filter. You should fill in at least some members. dbType, ic,
1259 * personName->pnLastNameAtBirth, firmName, email, telNumber, identifier,
1260 * registryCode, dbState, dbEffectiveOVM, dbOpenAdressing members are ignored.
1261 * @boxes is automatically reallocated list of isds_DbOwnerInfo structures,
1262 * possibly empty. Input NULL or valid old structure.
1264 * IE_SUCCESS if search succeeded, @boxes contains useful data
1265 * IE_NOEXIST if no such box exists, @boxes will be NULL
1266 * IE_2BIG if too much boxes exist and server truncated the results, @boxes
1267 * contains still valid data
1268 * other code if something bad happens. @boxes will be NULL. */
1269 isds_error
isds_FindPersonalDataBox(struct isds_ctx
*context
,
1270 const struct isds_DbOwnerInfo
*criteria
,
1271 struct isds_list
**boxes
);
1273 /* Find boxes matching a given full-text criteria.
1274 * @context is a session context
1275 * @query is a non-empty string which consists of words to search
1276 * @target selects box attributes to search for @query words. Pass NULL if you
1278 * @box_type restricts searching to given box type. Value DBTYPE_SYSTEM means
1279 * to search in all box types. Value DBTYPE_OVM_MAIN means to search in
1280 * non-subsudiary OVM box types. Pass NULL to let server to use default value
1281 * which is DBTYPE_SYSTEM.
1282 * @page_size defines count of boxes to constitute a response page. It counts
1283 * from zero. Pass NULL to let server to use a default value (50 now).
1284 * @page_number defines ordinar number of the response page to return. It
1285 * counts from zero. Pass NULL to let server to use a default value (0 now).
1286 * @track_matches points to true for marking @query words found in the box
1287 * attributes. It points to false for not marking. Pass NULL to let the server
1288 * to use default value (false now).
1289 * @total_matching_boxes outputs reallocated number of all boxes matching the
1290 * query. Will be pointer to NULL if server did not provide the value.
1291 * Pass NULL if you don't care.
1292 * @current_page_beginning outputs reallocated ordinar number of the first box
1293 * in this @boxes page. It counts from zero. It will be pointer to NULL if the
1294 * server did not provide the value. Pass NULL if you don't care.
1295 * @current_page_size outputs reallocated count of boxes in the this @boxes
1296 * page. It will be pointer to NULL if the server did not provide the value.
1297 * Pass NULL if you don't care.
1298 * @last_page outputs pointer to reallocated boolean. True if this @boxes page
1299 * is the last one, false if more boxes match, NULL if the server did not
1300 * provude the value. Pass NULL if you don't care.
1301 * @boxes outputs reallocated list of isds_fulltext_result structures,
1304 * IE_SUCCESS if search succeeded
1305 * IE_2BIG if @page_size is too large
1306 * other code if something bad happens; output arguments will be NULL. */
1307 isds_error
isds_find_box_by_fulltext(struct isds_ctx
*context
,
1309 const isds_fulltext_target
*target
,
1310 const isds_DbType
*box_type
,
1311 const unsigned long int *page_size
,
1312 const unsigned long int *page_number
,
1313 const _Bool
*track_matches
,
1314 unsigned long int **total_matching_boxes
,
1315 unsigned long int **current_page_beginning
,
1316 unsigned long int **current_page_size
,
1318 struct isds_list
**boxes
);
1320 /* Get status of a box.
1321 * @context is ISDS session context.
1322 * @box_id is UTF-8 encoded box identifier as zero terminated string
1323 * @box_status is return value of box status.
1325 * IE_SUCCESS if box has been found and its status retrieved
1326 * IE_NOEXIST if box is not known to ISDS server
1327 * or other appropriate error.
1328 * You can use isds_DbState to enumerate box status. However out of enum
1329 * range value can be returned too. This is feature because ISDS
1330 * specification leaves the set of values open.
1331 * Be ware that status DBSTATE_REMOVED is signaled as IE_SUCCESS. That means
1332 * the box has been deleted, but ISDS still lists its former existence. */
1333 isds_error
isds_CheckDataBox(struct isds_ctx
*context
, const char *box_id
,
1334 long int *box_status
);
1336 /* Get history of box state changes.
1337 * @context is ISDS session context.
1338 * @box_id is UTF-8 encoded sender box identifier as zero terminated string.
1339 * @from_time is first second of history to return in @history. Server ignores
1340 * subseconds. NULL means time of creating the box.
1341 * @to_time is last second of history to return in @history. Server ignores
1342 * subseconds. It's valid to have the @from_time equaled to the @to_time. The
1343 * interval is closed from both ends. NULL means now.
1344 * @history outputs auto-reallocated list of pointers to struct
1345 * isds_box_state_period. Each item describes a continues time when the box
1346 * was in one state. The state is 1 for accessible box. Otherwise the box
1347 * is inaccessible (priviledged users will get exact box state as enumerated
1348 * in isds_DbState, other users 0).
1350 * IE_SUCCESS if the history has been obtained correctly,
1351 * or other appropriate error. Please note that server allows to retrieve
1352 * the history only to some users. */
1353 isds_error
isds_get_box_state_history(struct isds_ctx
*context
,
1355 const struct timeval
*from_time
, const struct timeval
*to_time
,
1356 struct isds_list
**history
);
1358 /* Get list of permissions to send commercial messages.
1359 * @context is ISDS session context.
1360 * @box_id is UTF-8 encoded sender box identifier as zero terminated string
1361 * @permissions is a reallocated list of permissions (struct
1362 * isds_commercial_permission*) to send commercial messages from @box_id. The
1363 * order of permissions is significant as the server applies the permissions
1364 * and associated pre-paid credits in the order. Empty list means no
1367 * IE_SUCCESS if the list has been obtained correctly,
1368 * or other appropriate error. */
1369 isds_error
isds_get_commercial_permissions(struct isds_ctx
*context
,
1370 const char *box_id
, struct isds_list
**permissions
);
1372 /* Get details about credit for sending pre-paid commercial messages.
1373 * @context is ISDS session context.
1374 * @box_id is UTF-8 encoded sender box identifier as zero terminated string.
1375 * @from_date is first day of credit history to return in @history. Only
1376 * tm_year, tm_mon and tm_mday carry sane value.
1377 * @to_date is last day of credit history to return in @history. Only
1378 * tm_year, tm_mon and tm_mday carry sane value.
1379 * @credit outputs current credit value into pre-allocated memory. Pass NULL
1380 * if you don't care. This and all other credit values are integers in
1381 * hundredths of Czech Crowns.
1382 * @email outputs notification e-mail address where notifications about credit
1383 * are sent. This is automatically reallocated string. Pass NULL if you don't
1384 * care. It can return NULL if no address is defined.
1385 * @history outputs auto-reallocated list of pointers to struct
1386 * isds_credit_event. Events in closed interval @from_time to @to_time are
1387 * returned. Pass NULL @to_time and @from_time if you don't care. The events
1388 * are sorted by time.
1390 * IE_SUCCESS if the credit details have been obtained correctly,
1391 * or other appropriate error. Please note that server allows to retrieve
1392 * only limited history of events. */
1393 isds_error
isds_get_commercial_credit(struct isds_ctx
*context
,
1395 const struct tm
*from_date
, const struct tm
*to_date
,
1396 long int *credit
, char **email
, struct isds_list
**history
);
1398 /* Switch box into state where box can receive commercial messages (off by
1400 * @context is ISDS session context.
1401 * @box_id is UTF-8 encoded box identifier as zero terminated string
1402 * @allow is true for enable, false for disable commercial messages income
1403 * @approval is optional external approval of box manipulation
1404 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1405 * NULL, if you don't care. */
1406 isds_error
isds_switch_commercial_receiving(struct isds_ctx
*context
,
1407 const char *box_id
, const _Bool allow
,
1408 const struct isds_approval
*approval
, char **refnumber
);
1410 /* Switch box into / out of state where non-OVM box can act as OVM (e.g. force
1411 * message acceptance). This is just a box permission. Sender must apply
1412 * such role by sending each message.
1413 * @context is ISDS session context.
1414 * @box_id is UTF-8 encoded box identifier as zero terminated string
1415 * @allow is true for enable, false for disable OVM role permission
1416 * @approval is optional external approval of box manipulation
1417 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1418 * NULL, if you don't care. */
1419 isds_error
isds_switch_effective_ovm(struct isds_ctx
*context
,
1420 const char *box_id
, const _Bool allow
,
1421 const struct isds_approval
*approval
, char **refnumber
);
1423 /* Switch box accessibility state on request of box owner.
1424 * Despite the name, owner must do the request off-line. This function is
1425 * designed for such off-line meeting points (e.g. Czech POINT).
1426 * @context is ISDS session context.
1427 * @box identifies box to switch accessibility state. aifoIsds,
1428 * address->adCode, address->adDistrict members are ignored.
1429 * @allow is true for making accessible, false to disallow access.
1430 * @approval is optional external approval of box manipulation
1431 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1432 * NULL, if you don't care. */
1433 isds_error
isds_switch_box_accessibility_on_owner_request(
1434 struct isds_ctx
*context
, const struct isds_DbOwnerInfo
*box
,
1435 const _Bool allow
, const struct isds_approval
*approval
,
1438 /* Disable box accessibility on law enforcement (e.g. by prison) since exact
1440 * @context is ISDS session context.
1441 * @box identifies box to switch accessibility state. aifoIsds,
1442 * address->adCode, address->adDistrict members are ignored.
1443 * @since is date since accessibility has been denied. This can be past too.
1444 * Only tm_year, tm_mon and tm_mday carry sane value.
1445 * @approval is optional external approval of box manipulation
1446 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1447 * NULL, if you don't care. */
1448 isds_error
isds_disable_box_accessibility_externaly(
1449 struct isds_ctx
*context
, const struct isds_DbOwnerInfo
*box
,
1450 const struct tm
*since
, const struct isds_approval
*approval
,
1453 /* Send a message via ISDS to a recipient
1454 * @context is session context
1455 * @outgoing_message is message to send; Some members are mandatory (like
1456 * dbIDRecipient), some are optional and some are irrelevant (especially data
1457 * about sender). Included pointer to isds_list documents must contain at
1458 * least one document of FILEMETATYPE_MAIN. This is read-write structure, some
1459 * members will be filled with valid data from ISDS. Exact list of write
1460 * members is subject to change. Currently dmID is changed.
1461 * @return ISDS_SUCCESS, or other error code if something goes wrong. */
1462 isds_error
isds_send_message(struct isds_ctx
*context
,
1463 struct isds_message
*outgoing_message
);
1465 /* Send a message via ISDS to a multiple recipients
1466 * @context is session context
1467 * @outgoing_message is message to send; Some members are mandatory,
1468 * some are optional and some are irrelevant (especially data
1469 * about sender). Data about recipient will be substituted by ISDS from
1470 * @copies. Included pointer to isds_list documents must
1471 * contain at least one document of FILEMETATYPE_MAIN.
1472 * @copies is list of isds_message_copy structures addressing all desired
1473 * recipients. This is read-write structure, some members will be filled with
1474 * valid data from ISDS (message IDs, error codes, error descriptions).
1476 * ISDS_SUCCESS if all messages have been sent
1477 * ISDS_PARTIAL_SUCCESS if sending of some messages has failed (failed and
1478 * succeeded messages can be identified by copies->data->error),
1479 * or other error code if something other goes wrong. */
1480 isds_error
isds_send_message_to_multiple_recipients(struct isds_ctx
*context
,
1481 const struct isds_message
*outgoing_message
,
1482 struct isds_list
*copies
);
1484 /* Get list of outgoing (already sent) messages.
1485 * Any criterion argument can be NULL, if you don't care about it.
1486 * @context is session context. Must not be NULL.
1487 * @from_time is minimal time and date of message sending inclusive.
1488 * @to_time is maximal time and date of message sending inclusive
1489 * @dmSenderOrgUnitNum is the same as isds_envelope.dmSenderOrgUnitNum
1490 * @status_filter is bit field of isds_message_status values. Use special
1491 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
1492 * all values, you can use bit-wise arithmetic if you want.)
1493 * @offset is index of first message we are interested in. First message is 1.
1494 * Set to 0 (or 1) if you don't care.
1495 * @number is maximal length of list you want to get as input value, outputs
1496 * number of messages matching these criteria. Can be NULL if you don't care
1497 * (applies to output value either).
1498 * @messages is automatically reallocated list of isds_message's. Be ware that
1499 * it returns only brief overview (envelope and some other fields) about each
1500 * message, not the complete message. FIXME: Specify exact fields.
1501 * The list is sorted by delivery time in ascending order.
1502 * Use NULL if you don't care about the meta data (useful if you want to know
1503 * only the @number). If you provide &NULL, list will be allocated on heap,
1504 * if you provide pointer to non-NULL, list will be freed automatically at
1505 * first. Also in case of error the list will be NULLed.
1506 * @return IE_SUCCESS or appropriate error code. */
1507 isds_error
isds_get_list_of_sent_messages(struct isds_ctx
*context
,
1508 const struct timeval
*from_time
, const struct timeval
*to_time
,
1509 const long int *dmSenderOrgUnitNum
, const unsigned int status_filter
,
1510 const unsigned long int offset
, unsigned long int *number
,
1511 struct isds_list
**messages
);
1513 /* Get list of incoming (addressed to you) messages.
1514 * Any criterion argument can be NULL, if you don't care about it.
1515 * @context is session context. Must not be NULL.
1516 * @from_time is minimal time and date of message sending inclusive.
1517 * @to_time is maximal time and date of message sending inclusive
1518 * @dmRecipientOrgUnitNum is the same as isds_envelope.dmRecipientOrgUnitNum
1519 * @status_filter is bit field of isds_message_status values. Use special
1520 * value MESSAGESTATE_ANY to signal you don't care. (It's defined as union of
1521 * all values, you can use bit-wise arithmetic if you want.)
1522 * @offset is index of first message we are interested in. First message is 1.
1523 * Set to 0 (or 1) if you don't care.
1524 * @number is maximal length of list you want to get as input value, outputs
1525 * number of messages matching these criteria. Can be NULL if you don't care
1526 * (applies to output value either).
1527 * @messages is automatically reallocated list of isds_message's. Be ware that
1528 * it returns only brief overview (envelope and some other fields) about each
1529 * message, not the complete message. FIXME: Specify exact fields.
1530 * Use NULL if you don't care about the meta data (useful if you want to know
1531 * only the @number). If you provide &NULL, list will be allocated on heap,
1532 * if you provide pointer to non-NULL, list will be freed automatically at
1533 * first. Also in case of error the list will be NULLed.
1534 * @return IE_SUCCESS or appropriate error code. */
1535 isds_error
isds_get_list_of_received_messages(struct isds_ctx
*context
,
1536 const struct timeval
*from_time
, const struct timeval
*to_time
,
1537 const long int *dmRecipientOrgUnitNum
,
1538 const unsigned int status_filter
,
1539 const unsigned long int offset
, unsigned long int *number
,
1540 struct isds_list
**messages
);
1542 /* Get list of sent message state changes.
1543 * Any criterion argument can be NULL, if you don't care about it.
1544 * @context is session context. Must not be NULL.
1545 * @from_time is minimal time and date of status changes inclusive
1546 * @to_time is maximal time and date of status changes inclusive
1547 * @changed_states is automatically reallocated list of
1548 * isds_message_status_change's. If you provide &NULL, list will be allocated
1549 * on heap, if you provide pointer to non-NULL, list will be freed
1550 * automatically at first. Also in case of error the list will be NULLed.
1551 * XXX: The list item ordering is not specified.
1552 * XXX: Server provides only `recent' changes.
1553 * @return IE_SUCCESS or appropriate error code. */
1554 isds_error
isds_get_list_of_sent_message_state_changes(
1555 struct isds_ctx
*context
,
1556 const struct timeval
*from_time
, const struct timeval
*to_time
,
1557 struct isds_list
**changed_states
);
1559 /* Download incoming message envelope identified by ID.
1560 * @context is session context
1561 * @message_id is message identifier (you can get them from
1562 * isds_get_list_of_received_messages())
1563 * @message is automatically reallocated message retrieved from ISDS.
1564 * It will miss documents per se. Use isds_get_received_message(), if you are
1565 * interested in documents (content) too.
1566 * Returned hash and timestamp require documents to be verifiable. */
1567 isds_error
isds_get_received_envelope(struct isds_ctx
*context
,
1568 const char *message_id
, struct isds_message
**message
);
1570 /* Download signed delivery info-sheet of given message identified by ID.
1571 * @context is session context
1572 * @message_id is message identifier (you can get them from
1573 * isds_get_list_of_{sent,received}_messages())
1574 * @message is automatically reallocated message retrieved from ISDS.
1575 * It will miss documents per se. Use isds_get_signed_received_message(),
1576 * if you are interested in documents (content). OTOH, only this function
1577 * can get list events message has gone through. */
1578 isds_error
isds_get_signed_delivery_info(struct isds_ctx
*context
,
1579 const char *message_id
, struct isds_message
**message
);
1581 /* Load delivery info of any format from buffer.
1582 * @context is session context
1583 * @raw_type advertises format of @buffer content. Only delivery info types
1585 * @buffer is DER encoded PKCS#7 structure with signed delivery info. You can
1586 * retrieve such data from message->raw after calling
1587 * isds_get_signed_delivery_info().
1588 * @length is length of buffer in bytes.
1589 * @message is automatically reallocated message parsed from @buffer.
1590 * @strategy selects how buffer will be attached into raw isds_message member.
1592 isds_error
isds_load_delivery_info(struct isds_ctx
*context
,
1593 const isds_raw_type raw_type
,
1594 const void *buffer
, const size_t length
,
1595 struct isds_message
**message
, const isds_buffer_strategy strategy
);
1597 /* Download delivery info-sheet of given message identified by ID.
1598 * @context is session context
1599 * @message_id is message identifier (you can get them from
1600 * isds_get_list_of_{sent,received}_messages())
1601 * @message is automatically reallocated message retrieved from ISDS.
1602 * It will miss documents per se. Use isds_get_received_message(), if you are
1603 * interested in documents (content). OTOH, only this function can get list
1604 * of events message has gone through. */
1605 isds_error
isds_get_delivery_info(struct isds_ctx
*context
,
1606 const char *message_id
, struct isds_message
**message
);
1608 /* Download incoming message identified by ID.
1609 * @context is session context
1610 * @message_id is message identifier (you can get them from
1611 * isds_get_list_of_received_messages())
1612 * @message is automatically reallocated message retrieved from ISDS */
1613 isds_error
isds_get_received_message(struct isds_ctx
*context
,
1614 const char *message_id
, struct isds_message
**message
);
1616 /* Load message of any type from buffer.
1617 * @context is session context
1618 * @raw_type defines content type of @buffer. Only message types are allowed.
1619 * @buffer is message raw representation. Format (CMS, plain signed,
1620 * message direction) is defined in @raw_type. You can retrieve such data
1621 * from message->raw after calling isds_get_[signed]{received,sent}_message().
1622 * @length is length of buffer in bytes.
1623 * @message is automatically reallocated message parsed from @buffer.
1624 * @strategy selects how buffer will be attached into raw isds_message member.
1626 isds_error
isds_load_message(struct isds_ctx
*context
,
1627 const isds_raw_type raw_type
, const void *buffer
, const size_t length
,
1628 struct isds_message
**message
, const isds_buffer_strategy strategy
);
1630 /* Determine type of raw message or delivery info according some heuristics.
1631 * It does not validate the raw blob.
1632 * @context is session context
1633 * @raw_type returns content type of @buffer. Valid only if exit code of this
1634 * function is IE_SUCCESS. The pointer must be valid. This is no automatically
1635 * reallocated memory.
1636 * @buffer is message raw representation.
1637 * @length is length of buffer in bytes. */
1638 isds_error
isds_guess_raw_type(struct isds_ctx
*context
,
1639 isds_raw_type
*raw_type
, const void *buffer
, const size_t length
);
1641 /* Download signed incoming message identified by ID.
1642 * @context is session context
1643 * @message_id is message identifier (you can get them from
1644 * isds_get_list_of_received_messages())
1645 * @message is automatically reallocated message retrieved from ISDS. The raw
1646 * member will be filled with PKCS#7 structure in DER format. */
1647 isds_error
isds_get_signed_received_message(struct isds_ctx
*context
,
1648 const char *message_id
, struct isds_message
**message
);
1650 /* Download signed outgoing message identified by ID.
1651 * @context is session context
1652 * @message_id is message identifier (you can get them from
1653 * isds_get_list_of_sent_messages())
1654 * @message is automatically reallocated message retrieved from ISDS. The raw
1655 * member will be filled with PKCS#7 structure in DER format. */
1656 isds_error
isds_get_signed_sent_message(struct isds_ctx
*context
,
1657 const char *message_id
, struct isds_message
**message
);
1659 /* Get type and name of user who sent a message identified by ID.
1660 * @context is session context
1661 * @message_id is message identifier
1662 * @sender_type is pointer to automatically allocated type of sender detected
1663 * from @raw_sender_type string. If @raw_sender_type is unknown to this
1664 * library or to the server, NULL will be returned. Pass NULL if you don't
1666 * @raw_sender_type is automatically reallocated UTF-8 string describing
1667 * sender type or NULL if not known to server. Pass NULL if you don't care.
1668 * @sender_name is automatically reallocated UTF-8 name of user who sent the
1669 * message, or NULL if not known to ISDS. Pass NULL if you don't care. */
1670 isds_error
isds_get_message_sender(struct isds_ctx
*context
,
1671 const char *message_id
, isds_sender_type
**sender_type
,
1672 char **raw_sender_type
, char **sender_name
);
1674 /* Retrieve hash of message identified by ID stored in ISDS.
1675 * @context is session context
1676 * @message_id is message identifier
1677 * @hash is automatically reallocated message hash downloaded from ISDS.
1678 * Message must exist in system and must not be deleted. */
1679 isds_error
isds_download_message_hash(struct isds_ctx
*context
,
1680 const char *message_id
, struct isds_hash
**hash
);
1682 /* Compute hash of message from raw representation and store it into envelope.
1683 * Original hash structure will be destroyed in envelope.
1684 * @context is session context
1685 * @message is message carrying raw XML message blob
1686 * @algorithm is desired hash algorithm to use */
1687 isds_error
isds_compute_message_hash(struct isds_ctx
*context
,
1688 struct isds_message
*message
, const isds_hash_algorithm algorithm
);
1690 /* Compare two hashes.
1692 * @h2 is another hash
1694 * IE_SUCCESS if hashes equal
1695 * IE_NOTUNIQ if hashes are comparable, but they don't equal
1696 * IE_ENUM if not comparable, but both structures defined
1697 * IE_INVAL if some of the structures are undefined (NULL)
1698 * IE_ERROR if internal error occurs */
1699 isds_error
isds_hash_cmp(const struct isds_hash
*h1
,
1700 const struct isds_hash
*h2
);
1702 /* Check message has gone through ISDS by comparing message hash stored in
1703 * ISDS and locally computed hash. You must provide message with valid raw
1704 * member (do not use isds_load_message(..., BUFFER_DONT_STORE)).
1705 * This is convenient wrapper for isds_download_message_hash(),
1706 * isds_compute_message_hash(), and isds_hash_cmp() sequence.
1707 * @context is session context
1708 * @message is message with valid raw and envelope member; envelope->hash
1709 * member will be changed during function run. Use envelope on heap only.
1711 * IE_SUCCESS if message originates in ISDS
1712 * IE_NOTEQUAL if message is unknown to ISDS
1713 * other code for other errors */
1714 isds_error
isds_verify_message_hash(struct isds_ctx
*context
,
1715 struct isds_message
*message
);
1717 /* Submit CMS signed message to ISDS to verify its originality. This is
1718 * stronger form of isds_verify_message_hash() because ISDS does more checks
1719 * than simple one (potentialy old weak) hash comparison.
1720 * @context is session context
1721 * @message is memory with raw CMS signed message bit stream
1722 * @length is @message size in bytes
1724 * IE_SUCCESS if message originates in ISDS
1725 * IE_NOTEQUAL if message is unknown to ISDS
1726 * other code for other errors */
1727 isds_error
isds_authenticate_message(struct isds_ctx
*context
,
1728 const void *message
, size_t length
);
1730 /* Submit CMS signed message or delivery info to ISDS to re-sign the content
1731 * including adding new CMS time stamp. Only CMS blobs without time stamp can
1733 * @context is session context
1734 * @input_data is memory with raw CMS signed message or delivery info bit
1736 * @input_length is @input_data size in bytes
1737 * @output_data is pointer to auto-allocated memory where to store re-signed
1738 * input data blob. Caller must free it.
1739 * @output_data is pointer where to store @output_data size in bytes
1740 * @valid_to is pointer to auto-allocated date of time stamp expiration.
1741 * Only tm_year, tm_mon and tm_mday will be set. Pass NULL, if you don't care.
1743 * IE_SUCCESS if CMS blob has been re-signed successfully
1744 * other code for other errors */
1745 isds_error
isds_resign_message(struct isds_ctx
*context
,
1746 const void *input_data
, size_t input_length
,
1747 void **output_data
, size_t *output_length
, struct tm
**valid_to
);
1749 /* Erase message specified by @message_id from long term storage. Other
1750 * message cannot be erased on user request.
1751 * @context is session context
1752 * @message_id is message identifier.
1753 * @incoming is true for incoming message, false for outgoing message.
1755 * IE_SUCCESS if message has ben removed
1756 * IE_INVAL if message does not exist in long term storage or message
1757 * belongs to different box
1758 * TODO: IE_NOEPRM if user has no permission to erase a message */
1759 isds_error
isds_delete_message_from_storage(struct isds_ctx
*context
,
1760 const char *message_id
, _Bool incoming
);
1762 /* Mark message as read. This is a transactional commit function to acknowledge
1763 * to ISDS the message has been downloaded and processed by client properly.
1764 * @context is session context
1765 * @message_id is message identifier. */
1766 isds_error
isds_mark_message_read(struct isds_ctx
*context
,
1767 const char *message_id
);
1769 /* Mark message as received by recipient. This is applicable only to
1770 * commercial message. Use envelope->dmType message member to distinguish
1771 * commercial message from government message. Government message is
1772 * received automatically (by law), commercial message on recipient request.
1773 * @context is session context
1774 * @message_id is message identifier. */
1775 isds_error
isds_mark_message_received(struct isds_ctx
*context
,
1776 const char *message_id
);
1778 /* Send bogus request to ISDS.
1779 * Just for test purposes */
1780 isds_error
isds_bogus_request(struct isds_ctx
*context
);
1782 /* Send document for authorized conversion into Czech POINT system.
1783 * This is public anonymous service, no log-in necessary. Special context is
1784 * used to reuse keep-a-live HTTPS connection.
1785 * @context is Czech POINT session context. DO NOT use context connected to
1786 * ISDS server. Use new context or context used by this function previously.
1787 * @document is document to convert. Only data, data_length, dmFileDescr and
1788 * is_xml members are significant. Be ware that not all document formats can be
1789 * converted (signed PDF 1.3 and higher only (2010-02 state)).
1790 * @id is reallocated identifier assigned by Czech POINT system to
1791 * your document on submit. Use is to tell it to Czech POINT officer.
1792 * @date is reallocated document submit date (submitted documents
1793 * expires after some period). Only tm_year, tm_mon and tm_mday carry sane
1795 isds_error
czp_convert_document(struct isds_ctx
*context
,
1796 const struct isds_document
*document
,
1797 char **id
, struct tm
**date
);
1799 /* Close possibly opened connection to Czech POINT document deposit.
1800 * @context is Czech POINT session context. */
1801 isds_error
czp_close_connection(struct isds_ctx
*context
);
1803 /* Send request for new box creation in testing ISDS instance.
1804 * It's not possible to request for a production box currently, as it
1805 * communicates via e-mail.
1806 * XXX: This function does not work either. Server complains about invalid
1808 * XXX: Remove context->type hacks in isds.c and validator.c when removing
1810 * @context is special session context for box creation request. DO NOT use
1811 * standard context as it could reveal your password. Use fresh new context or
1812 * context previously used by this function.
1813 * @box is box description to create including single primary user (in case of
1814 * FO box type). aifoIsds, address->adCode, address->adDistrict members are
1815 * ignored. It outputs box ID assigned by ISDS in dbID element.
1816 * @users is list of struct isds_DbUserInfo (primary users in case of non-FO
1817 * box, or contact address of PFO box owner). The email member is mandatory as
1818 * it will be used to deliver credentials.
1819 * @former_names is optional undocumented string. Pass NULL if you don't care.
1820 * @approval is optional external approval of box manipulation
1821 * @refnumber is reallocated serial number of request assigned by ISDS. Use
1822 * NULL, if you don't care.*/
1823 isds_error
isds_request_new_testing_box(struct isds_ctx
*context
,
1824 struct isds_DbOwnerInfo
*box
, const struct isds_list
*users
,
1825 const char *former_names
, const struct isds_approval
*approval
,
1828 /* Search for document by document ID in list of documents. IDs are compared
1830 * @documents is list of isds_documents
1831 * @id is document identifier
1832 * @return first matching document or NULL. */
1833 const struct isds_document
*isds_find_document_by_id(
1834 const struct isds_list
*documents
, const char *id
);
1836 /* Normalize @mime_type to be proper MIME type.
1837 * ISDS servers pass invalid MIME types (e.g. "pdf"). This function tries to
1838 * guess regular MIME type (e.g. "application/pdf").
1839 * @mime_type is UTF-8 encoded MIME type to fix
1840 * @return original @mime_type if no better interpretation exists, or
1841 * constant static UTF-8 encoded string with proper MIME type. */
1842 const char *isds_normalize_mime_type(const char *mime_type
);
1844 /* Deallocate structure isds_pki_credentials and NULL it.
1845 * Pass-phrase is discarded.
1846 * @pki credentials to to free */
1847 void isds_pki_credentials_free(struct isds_pki_credentials
**pki
);
1849 /* Free isds_list with all member data.
1850 * @list list to free, on return will be NULL */
1851 void isds_list_free(struct isds_list
**list
);
1853 /* Deallocate structure isds_hash and NULL it.
1854 * @hash hash to to free */
1855 void isds_hash_free(struct isds_hash
**hash
);
1857 /* Deallocate structure isds_PersonName recursively and NULL it */
1858 void isds_PersonName_free(struct isds_PersonName
**person_name
);
1860 /* Deallocate structure isds_BirthInfo recursively and NULL it */
1861 void isds_BirthInfo_free(struct isds_BirthInfo
**birth_info
);
1863 /* Deallocate structure isds_Address recursively and NULL it */
1864 void isds_Address_free(struct isds_Address
**address
);
1866 /* Deallocate structure isds_DbOwnerInfo recursively and NULL it */
1867 void isds_DbOwnerInfo_free(struct isds_DbOwnerInfo
**db_owner_info
);
1869 /* Deallocate structure isds_DbUserInfo recursively and NULL it */
1870 void isds_DbUserInfo_free(struct isds_DbUserInfo
**db_user_info
);
1872 /* Deallocate struct isds_event recursively and NULL it */
1873 void isds_event_free(struct isds_event
**event
);
1875 /* Deallocate struct isds_envelope recursively and NULL it */
1876 void isds_envelope_free(struct isds_envelope
**envelope
);
1878 /* Deallocate struct isds_document recursively and NULL it */
1879 void isds_document_free(struct isds_document
**document
);
1881 /* Deallocate struct isds_message recursively and NULL it */
1882 void isds_message_free(struct isds_message
**message
);
1884 /* Deallocate struct isds_message_copy recursively and NULL it */
1885 void isds_message_copy_free(struct isds_message_copy
**copy
);
1887 /* Deallocate struct isds_message_status_change recursively and NULL it */
1888 void isds_message_status_change_free(
1889 struct isds_message_status_change
**message_status_change
);
1891 /* Deallocate struct isds_approval recursively and NULL it */
1892 void isds_approval_free(struct isds_approval
**approval
);
1894 /* Deallocate struct isds_commercial_permission recursively and NULL it */
1895 void isds_commercial_permission_free(
1896 struct isds_commercial_permission
**permission
);
1898 /* Deallocate struct isds_credit_event recursively and NULL it */
1899 void isds_credit_event_free(struct isds_credit_event
**event
);
1901 /* Deallocate struct isds_credentials_delivery recursively and NULL it.
1902 * The email string is deallocated too. */
1903 void isds_credentials_delivery_free(
1904 struct isds_credentials_delivery
**credentials_delivery
);
1906 /* Deallocate struct isds_fulltext_result recursively and NULL it */
1907 void isds_fulltext_result_free(
1908 struct isds_fulltext_result
**result
);
1910 /* Deallocate struct isds_box_state_period recursively and NULL it */
1911 void isds_box_state_period_free(struct isds_box_state_period
**period
);
1913 /* Copy structure isds_PersonName recursively */
1914 struct isds_PersonName
*isds_PersonName_duplicate(
1915 const struct isds_PersonName
*src
);
1917 /* Copy structure isds_Address recursively */
1918 struct isds_Address
*isds_Address_duplicate(
1919 const struct isds_Address
*src
);
1921 /* Copy structure isds_DbOwnerInfo recursively */
1922 struct isds_DbOwnerInfo
*isds_DbOwnerInfo_duplicate(
1923 const struct isds_DbOwnerInfo
*src
);
1925 /* Copy structure isds_DbUserInfo recursively */
1926 struct isds_DbUserInfo
*isds_DbUserInfo_duplicate(
1927 const struct isds_DbUserInfo
*src
);
1929 /* Copy structure isds_box_state_period recursively */
1930 struct isds_box_state_period
*isds_box_state_period_duplicate(
1931 const struct isds_box_state_period
*src
);
1933 #ifdef __cplusplus /* For C++ linker sake */