From 52925f4e4a503c8149f33cb81c1ba5a7449b8177 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Petr=20P=C3=ADsa=C5=99?= Date: Tue, 1 Sep 2015 20:53:02 +0200 Subject: [PATCH] doc: Part of isds.h(3) Unfinishied isds.h(3) transcribtion. --- doc/libisds.xml | 1277 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 1272 insertions(+), 5 deletions(-) diff --git a/doc/libisds.xml b/doc/libisds.xml index 3b870b9..d4ad17e 100644 --- a/doc/libisds.xml +++ b/doc/libisds.xml @@ -266,13 +266,1280 @@ err = isds_cleanup(); See Also - - libcurl - 3 - + + + isds.h + 3 + + + libcurl + 3 + + - + + + + isds.h + 3 + + + + isds.h + API definition for libisds + + + + +]]> + + + + Description + + This header file declares inteface for libisds library. + + + + Constants + + + Service locators + + Addresses of known ISDS servers. + + + Base <abbrev>URL</abbrev>s of production <abbrev>ISDS</abbrev> instance + + + <varname>isds_locator</varname> + extern const char isds_locator[]; + Without client certificate authentication. + + + + <varname>isds_cert_locator</varname> + extern const char isds_cert_locator[]; + With client certificate authentication. + + + + <varname>isds_otp_locator</varname> + extern const char isds_otp_locator[]; + Without OTP authentication. + + + + + Base <abbrev>URL</abbrev>s of testing <abbrev>ISDS</abbrev> instance + + + <varname>isds_testing_locator</varname> + extern const char isds_testing_locator[]; + Without client certificate authentication. + + + + <varname>isds_cert_testing_locator</varname> + extern const char isds_cert_testing_locator[]; + With client certificate authentication. + + + + <varname>isds_otp_testing_locator</varname> + extern const char isds_otp_testing_locator[]; + Without OTP authentication. + + + + + + + + Data types + + + struct <structname>isds_ctx</structname> + struct isds_ctx; + Context for specific ISDS box. + + + + <type>isds_error</type> + typedef enum isds_error; + Error code. Known values: + + + IE_SUCCESS + No error. Numeric value 0. + + + + IE_ERROR + Unspecified error. + + + + IE_NOTSUP + Operation is not supported. + + + + IE_INVAL + Invalid value. + + + + IE_INVALID_CONTEXT + The context is not valid. + + + + IE_NOT_LOGGED_IN + The context has not been logged in. + + + + IE_CONNECTION_CLOSED + Network connection has been closed. + + + + IE_TIMED_OUT + Time limit for network operation exceeded. + + + + IE_NOEXIST + Requested entity does exist. + + + + IE_NOMEM + Not enough memory. + + + + IE_NETWORK + Network error. + + + + IE_HTTP + Error on HTTP level. + + + + IE_SOAP + Error on SOAP level. + + + + IE_XML + Error on XML level. + + + + IE_ISDS + Problem with ISDS server. + + + + IE_ENUM + Invalid enum value. + + + + IE_DATE + Invalid date value. + + + + IE_2BIG + Value is too big. + + + + IE_2SMALL + Value is too small. + + + + IE_NOTUNIQ + Value is not uniq. + + + + IE_NOTEQUAL + Compared values are not equal. + + + + IE_PARTIAL_SUCCESS + Operaration on a vector succeded for some values, but failed for others. + + + + IE_ABORTED + Operation was aborted by application request. + + + + IE_SECURITY + Security requirements were not satisfied. + + + + + + <type>isds_log_level</type> + typedef enum isds_log_level; + Log level. Know values: + + + ILL_NONE + 0 + + + + ILL_CRIT + 10 + + + + ILL_ERR + 20 + + + + ILL_WARNING + 30 + + + + ILL_INFO + 40 + + + + ILL_DEBUG + 50 + + + + ILL_ALL + 100 + + + + + + <type>isds_log_facility</type> + typedef enum isds_log_facility; + Log facility. Know values: + + + ILF_NONE + 0x0 + + + + ILF_HTTP + 0x1 + + + + ILF_SOAP + 0x2 + + + + ILF_ISDS + 0x4 + + + + ILF_FILE + 0x8 + + + + ILF_SEC + 0x10 + + + + ILF_XML + 0x20 + + + + ILF_ALL + 0xFF + + + + + + <type>isds_option</type> + typedef enum isds_option; + libisds option identifiers. Known values: + + + IOPT_TLS_VERIFY_SERVER + Option type is _Bool. Whether to + verify server identity. Default value is + true. + + + + IOPT_TLS_CA_FILE + Option type is char *. Option value + is a file name with certificate authority + certificates. Default value depends on used cryptographic + library. + + + + IOPT_TLS_CA_DIRECTORY + Option type is char *, Option value + is a directory with certificate authority certificates. + Default value depends on used cryptographic + library. + + + + IOPT_TLS_CRL_FILE + Option type is char *. Option value + is a file name with certificat revocation list in + PEM format. Default value depends on used + cryptographic library. + + + + IOPT_NORMALIZE_MIME_TYPE + Optiona type is _Bool. Whether to + normalize MIME type values. Default value is + false. + + + + + + <type>isds_tls_option</type> + typedef enum isds_tls_option; + This type is deprecated. + TLS libisds option identifiers. Known values: + + + ITLS_VERIFY_SERVER + Option type is _Bool. Whether to + verify server identity. + + + + ITLS_CA_FILE + Option type is char *. Option value + is a file name with certificate authority + certificates. + + + + ITLS_CA_DIRECTORY + Option type is char *. Option value + is a directory name with certificate authority + certificates. + + + + ITLS_CRL_FILE + Option type is char *. Option value + is a file name with certificate revocation list in + PEM format. + + + + + + <type>isds_pki_format</type> + typedef enum isds_pki_format; + Cryptographic material encoding. Known values: + + + PKI_FORMAT_PEM + PEM format. + + + + PKI_FORMAT_DER + DER format. + + + + PKI_FORMAT_ENG + The material is stored in a cryptographic engine. + + + + + + struct <structname>isds_pki_credentials</structname> + struct isds_pki_credentials; + This structure holds public key infrastructure cryptographic + material to authenticate a client. Members are: + + + char *engine; + String identifier of cryptographic engine to use + (where key is stored). Use NULL for no + engine. + + + + isds_pki_format certificate_format; + Certificate format. + + + + char *certificate; + A path to client certificate, or a certificate + nickname in case of NSS as curl back-end, or + key slot identifier inside cryptographic engine. Some + cryptographinc engines can pair certificate with key + automatically (NULL value). + + + + isds_pki_format key_format; + Private key format. + + + + char *key; + A path to client private key, or key identifier in + case an engine is used. + + + + char *passphrase; + Zero terminated string with password for + decrypting private key, or engine PIN. Use + NULL for no pass-phrase or to let the engine to ask for + it. + + + + + + <type>isds_otp_method</type> + typedef enum isds_otp_method; + One-time password authentication method. Known values: + + + OTP_HMAC + HMAC-based OTP method. + + + + OTP_TIME + Time-based OTP method. + + + + + + <type>isds_otp_resolution</type> + typedef enum isds_otp_resolution; + One-time password authentication resolution. Known values: + + + OTP_RESOLUTION_SUCCESS + Authentication succeded. + + + + OTP_RESOLUTION_UNKNOWN + Status is unkown. + + + + OTP_RESOLUTION_BAD_AUTHENTICATION + Bad log-in. You can retry to log in. + + + + OTP_RESOLUTION_ACCESS_BLOCKED + Access blocked for 60 minutes. (Because a brute + force attack was detected.) + + + + OTP_RESOLUTION_PASSWORD_EXPIRED + + Password has expired. + + It's not clear which password expired: + OTP or regular password? + + + + + + OTP_RESOLUTION_TO_FAST + OTP cannot be sent repeatedly at + this rate. (Minimal delay depends on TOTP + window setting.) + + + + OTP_RESOLUTION_UNAUTHORIZED + User name is not allowed to access requested + URI. + + + + OTP_RESOLUTION_TOTP_SENT + OTP has been generated and sent + by the ISDS to the user. + + + + OTP_RESOLUTION_TOTP_NOT_SENT + OTP could not been sent by the + ISDS. Retry later. + + + + + + struct <structname>isds_otp</structname> + struct isds_otp; + This structure holds one-time password when authenticating + a client and resolution of the authentication. + + Input members are: + + + isds_otp_method method; + Select OTP method to use. + + + + char *otp_code; + One-time password to use. Pass NULL, if you do not + know it yet (e.g. in case of first phase of + time-based OTP authentication to request new + code from ISDS.) + + + + Output members are: + + + isds_otp_resolution resolution; + Fine-grade resolution of this OTP + authentication attempt. + + + + + + <type>isds_DbType</type> + typedef enum isds_DbType; + Box type. It classify box owner by his legal status. Known + values: + + + DBTYPE_SYSTEM + This is a special value for sender of messages sent + by the ISDS. You can find it only in + incomming messages. It's not accepted by any other + services. + + + + DBTYPE_OVM + Standard government (state or municipality or + similar) office. + + + + DBTYPE_OVM_NOTAR + Notary. + + + + DBTYPE_OVM_EXEKUT + Executor. + + + + DBTYPE_OVM_REQ + Subsidiary office with OVM + (governing) status assigned on request (section 6 and 7 of the + act). + + + + DBTYPE_PO + Standard commercial organization (listed in trade + registry). + + + + DBTYPE_PO_ZAK + Other organization founded by an act. + + + + DBTYPE_PO_REQ + An organization with a box assigned on its + request. + + + + DBTYPE_PFO + Person in bussiness. + + + + DBTYPE_PFO_ADVOK + Lawyer. + + + + DBTYPE_PFO_DANPOR + Tax consultant. + + + + DBTYPE_PFO_INSSPR + Administrator of insolvency. + + + + DBTYPE_FO + Standard person. + + + + + + <type>isds_DbState</type> + typedef enum isds_DbState; + Box status from point of view of accessibility. Known + values: + + + DBSTATE_ACCESSIBLE + The box is accessible. + + + + DBSTATE_TEMP_UNACCESSIBLE + The box is temporarily inaccessible. + + + + DBSTATE_NOT_YET_ACCESSIBLE + The box has not yet been activated. + + + + DBSTATE_PERM_UNACCESSIBLE + The box is permanently inaccessible. + + + + DBSTATE_REMOVED + The box has been removed. + + + + + + <type>isds_priviledges</type> + typedef enum isds_priviledges; + Distinct user permissions from point of view of ISDS. + Instances can be bitmaps of any of these distinct values. Distinct known + values are: + + + PRIVIL_READ_NON_PERSONAL + The user can download and read messages with + dmPersonalDelivery equaled to + false. + + + + PRIVIL_READ_ALL + The user can download and read messages with + dmPersonalDelivery equaled to + true. + + + + PRIVIL_CREATE_DM + The user can create and send messages, the user + can download outgoing (sent) messages. + + + + PRIVIL_VIEW_INFO + The user can list messages and read data about + a message post and delivery. + + + + PRIVIL_SEARCH_DB + The user can can search for + boxes. + + + + PRIVIL_OWNER_ADM + The user can administer his box (to add and remove + permitted users and to modify theirs + permissions.) + + + + PRIVIL_READ_VAULT + + The user can read messages stored in the long term storage. + This permission is not used since 2012-05. + + + + + PRIVIL_ERASE_VAULT + The user can delete messages from the long term + storage. + + + + + + <type>isds_message_status</type> + typedef enum isds_message_status; + Message status. Known values are: + + + MESSAGESTATE_SENT + The message has been put into + ISDS. + + + + MESSAGESTATE_STAMPED + Message was stamped by a time stamp + authority. + + + + MESSAGESTATE_INFECTED + The message included viruses. Infected documents + have been removed from the message. + + + + MESSAGESTATE_DELIVERED + The message was delivered. + (dmDeliveryTime is + populated.) + + + + MESSAGESTATE_SUBSTITUTED + The message was delivered through fiction, + dmAcceptanceTime is + populated. + + + + MESSAGESTATE_RECEIVED + The message was accepted (by user's log-in or + user's explicit request). + dmAcceptanceTime is + populated. + + + + MESSAGESTATE_READ + The message has been read by + a user. + + + + MESSAGESTATE_UNDELIVERABLE + The message could not been delivered. + (E.g.The recipient's box has been made + inaccessible meantime.) + + + + MESSAGESTATE_REMOVED + The message's content was + deleted. + + + + MESSAGESTATE_IN_SAFE + The message is stored in the long term + storage. + + + + The values can be combined into a bit mask for some functions. + A special MESSAGESTATE_ANY macro denotes any of + the states. + + + + <type>isds_hash_algorithm</type> + typedef enum isds_hash_algorithm; + Hash algorithm types. Known values are: + + + HASH_ALGORITHM_MD5 + MD5. + + + + HASH_ALGORITHM_SHA_1 + SHA-1. + + + + HASH_ALGORITHM_SHA_224 + SHA-224. + + + + HASH_ALGORITHM_SHA_256 + SHA-256. + + + + HASH_ALGORITHM_SHA_384 + SHA-384. + + + + HASH_ALGORITHM_SHA_512 + SHA-256. + + + + + + <type>isds_buffer_strategy</type> + typedef enum isds_buffer_strategy; + Buffer storage strategy. This type defines how a function should + embed application provided buffer into + raw element of output structure. Known + values are: + + + BUFFER_DONT_STORE + Don't fill raw + member. + + + + BUFFER_COPY + Copy buffer content into newly allocated + raw member. + + + + BUFFER_MOVE + Copy pointer. Leave deallocation to structure + destructor + (isds_*_free()). + + + + + + struct <structname>isds_hash</structname> + struct isds_hash; + This is a hash value storage. Members are: + + + isds_hash_algorithm + algorithm; + Hash algorithm. + + + + size_t length; + Hash value length in bytes. + + + + void *value; + Hash value as a byte stream. + + + + + + struct <structname>isds_PersonName</structname> + struct isds_PersonName; + Name of a person. Members are: + + + char *pnFirstName; + First name. + + + + char *pnMiddleName; + Middle name. + + + + char *pnLastName; + Current last name. + + + + char *pnLastNameAtBirth; + Last name at birth. + + + + + + struct <structname>isds_BirthInfo</structname> + struct isds_BirthInfo; + Date and place of a birth. Members are: + + + struct tm *biDate; + Date of birth in local time at the birth place. + Only tm_year, + tm_mon and + tm_mday members of the struct + tm carry sane value. Others are + undefined. + + + + char *biCity; + City where a person was born. + + + + char *biCounty; + Region where a person was born. This is the kind + of region that is called Bezirk in + German and okres in + Czech. + + + + char *biState; + State wher a person was born. + + + + + + struct <structname>isds_Address</structname> + struct isds_Address; + Postal address. Members are: + + + char *adCity; + City. + + + + char *adStreet; + Street. + + + + char *adNumberInStreet; + Identification of an entrance on the + street. Číslo orientační in + Czech. + + + + char *adNumberInMunicipality; + Identification of a building in the municipality. + Číslo popisné in + Czech. + + + + char *adZipCode; + Postal code for mail routing. + + + + char *adState; + State. + + + + + + struct <structname>isds_DbOwnerInfo</structname> + struct isds_DbOwnerInfo; + Data about a box and his owner. NULL pointer values mean + undefined values. Members are: + + + char *dbID; + Box identifier. Specification limits the length to + 7 characters. + + + + isds_DbType *dbType; + Box type. + + + + char *ic; + Identifier of the owner. + + + + isds_PersonName *personName; + Name of a person owning the box. + + + + char *firmName; + Name of a firm owning the box. + + + + isds_BirthInfo *birthInfo; + Birth details of the person. + + + + isds_Address *address; + Postal address of the owner. + + + + char *nationality; + Nationality of the owner. + + + + char *email; + E-mail addres of the owner. + + + + char *telNumber; + Telephone number of the owner. + + + + char *identifier; + External box identifier for data provider + (OVM, PO, maybe + PFO box types.) Specification limits the + length to 20 characters. + + + + char *registryCode; + PFO external registry code. + Specification limits the length to + 5 characters. + + + + long int *dbState; + + Box state. 1 means the box is active. + The type is long int because specification declares it + as xsd:integer. + TODO: enum? + + + + _Bool *dbEffectiveOVM; + The Box has OVM role (section 5a + of the act). + + + + _Bool *dbOpenAddressing; + This non-OVM box is free to + receive messages from anybody. + + + + + + <type>isds_UserType</type> + typedef enum isds_UserType; + User type. Known values are: + + + USERTYPE_PRIMARY + Owner of the box. + + + + USERTYPE_ENTRUSTED + User with limited access to the box. + + + + USERTYPE_ADMINISTRATOR + User who can manage + USERTYPE_ENTRUSTED + users. + + + + USERTYPE_OFFICIAL + ??? + + + + USERTYPE_OFFICIAL_CERT + ??? + + + + USERTYPE_LIQUIDATOR + Company liquidator. + + + + + + struct <structname>isds_DbUserInfo</structname> + struct isds_DbUserInfo; + Data about a user. NULL pointer values mean + undefined values. Members are: + + + char *userID; + User identifier. Specification limits the length + from 6 to 12 characters. + + + + isds_UserType *userType; + User type. + + + + long int *userPrivils; + Set of user permissions. + + + + isds_PersonName *personName; + Name of the user. + + + + isds_Address *address; + Postal address of the user. + + + + struct tm *biDate; + Date of birth in local time. + Only tm_year, + tm_mon and + tm_mday members of the struct + tm carry sane value. Others are + undefined. + + + + char *ic; + Identifier a supervising firm. Specification + limits the length to 8 characters. + + + + char *firmName; + Name of a supervising firm. Specification limits + the length to 100 characters. + + + + char *caStreet; + Contact address. Street and number. + + + + char *caCity; + Czech city of the contact address. + + + + char *caZipCode; + Postal code of the contact address. + + + + char *caState; + Abbreviated country of contact address. This value + is optional and implicit meaning is + CZ. + + + + + + + + + Functions + + + + const char *isds_strerror + const isds_error error + + + + struct isds_ctx *isds_ctx_create + + + + + + + See Also + + + + + libcurl + 3 + + + libisds + 3 + + + time.h + 0p + + + + + -- 2.11.4.GIT