Macros
#define	KSI_PDU_VERSION_1 1

#define	KSI_PDU_VERSION_2 2

#define	KSI_sendSignRequest(ctx, request, handle) KSI_sendAggregatorRequest(ctx, request, handle)

#define	KSI_sendExtendRequest(ctx, request, handle) KSI_sendExtenderRequest(ctx, request, handle)

#define	KSI_extendSignature(ctx, sig, extended) KSI_extendSignatureWithPolicy(ctx, sig, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)

#define	KSI_CTX_setAggregatorHmacAlgorithm(ctx, alg_id) KSI_CTX_setOption(ctx, KSI_OPT_AGGR_HMAC_ALGORITHM, (void*)(alg_id))

#define	KSI_CTX_setExtenderHmacAlgorithm(ctx, alg_id) KSI_CTX_setOption(ctx, KSI_OPT_EXT_HMAC_ALGORITHM, (void*)(alg_id))

#define	KSI_CTX_FLAG_AGGR_PDU_VER KSI_OPT_AGGR_PDU_VER

#define	KSI_CTX_FLAG_EXT_PDU_VER KSI_OPT_EXT_PDU_VER

#define	KSI_CtxFlag KSI_Option_en

#define	KSI_CTX_setFlag(ctx, flag, param) KSI_CTX_setOption((ctx), (flag), (param))

#define	KSI_CERT_EMAIL "1.2.840.113549.1.9.1"

#define	KSI_CERT_COMMON_NAME "2.5.4.3"

#define	KSI_CERT_COUNTRY "2.5.4.6"

#define	KSI_CERT_ORGANIZATION "2.5.4.10"

Typedefs
typedef int(*	KSI_Config_Callback) (KSI_CTX ctx, KSI_Config conf)

typedef enum KSI_Option_en	KSI_Option

Enumerations
enum	KSI_StatusCode { KSI_OK = 0, KSI_AGGREGATOR_NOT_CONFIGURED = 0x01, KSI_EXTENDER_NOT_CONFIGURED = 0x02, KSI_PUBLICATIONS_FILE_NOT_CONFIGURED = 0x03, KSI_PUBFILE_VERIFICATION_NOT_CONFIGURED = 0x04, KSI_INVALID_VERIFICATION_INPUT = 0x05, KSI_INVALID_ARGUMENT = 0x100, KSI_INVALID_FORMAT = 0x101, KSI_UNTRUSTED_HASH_ALGORITHM = 0x102, KSI_UNAVAILABLE_HASH_ALGORITHM = 0x103, KSI_BUFFER_OVERFLOW = 0x104, KSI_TLV_PAYLOAD_TYPE_MISMATCH = 0x105, KSI_ASYNC_NOT_FINISHED = 0x106, KSI_INVALID_SIGNATURE = 0x107, KSI_INVALID_PKI_SIGNATURE = 0x108, KSI_PKI_CERTIFICATE_NOT_TRUSTED = 0x109, KSI_INVALID_STATE = 0x10a, KSI_OUT_OF_MEMORY = 0x200, KSI_IO_ERROR = 0x201, KSI_NETWORK_ERROR = 0x202, KSI_NETWORK_CONNECTION_TIMEOUT = 0x203, KSI_NETWORK_SEND_TIMEOUT = 0x204, KSI_NETWORK_RECIEVE_TIMEOUT = 0x205, KSI_HTTP_ERROR = 0x206, KSI_EXTEND_WRONG_CAL_CHAIN = 0x207, KSI_EXTEND_NO_SUITABLE_PUBLICATION = 0x208, KSI_VERIFICATION_FAILURE = 0x20a, KSI_INVALID_PUBLICATION = 0x20b, KSI_PUBLICATIONS_FILE_NOT_SIGNED_WITH_PKI = 0x20c, KSI_CRYPTO_FAILURE = 0x20d, KSI_HMAC_MISMATCH = 0x20e, KSI_REQUEST_PENDING = 0x20f, KSI_REQUEST_ID_MISMATCH = 0x210, KSI_HMAC_ALGORITHM_MISMATCH = 0x211, KSI_UNSUPPORTED_PDU_VERSION = 0x212, KSI_SERVICE_INVALID_REQUEST = 0x400, KSI_SERVICE_AUTHENTICATION_FAILURE = 0x401, KSI_SERVICE_INVALID_PAYLOAD = 0x402, KSI_SERVICE_INTERNAL_ERROR = 0x403, KSI_SERVICE_UPSTREAM_ERROR = 0x404, KSI_SERVICE_UPSTREAM_TIMEOUT = 0x405, KSI_SERVICE_UNKNOWN_ERROR = 0x406, KSI_SERVICE_AGGR_REQUEST_TOO_LARGE = 0x407, KSI_SERVICE_AGGR_REQUEST_OVER_QUOTA = 0x408, KSI_SERVICE_AGGR_TOO_MANY_REQUESTS = 0x409, KSI_SERVICE_AGGR_INPUT_TOO_LONG = 0x40a, KSI_SERVICE_AGGR_PDU_V2_RESPONSE_TO_PDU_V1_REQUEST = 0x40b, KSI_SERVICE_AGGR_PDU_V1_RESPONSE_TO_PDU_V2_REQUEST = 0x40c, KSI_SERVICE_EXTENDER_INVALID_TIME_RANGE = 0x501, KSI_SERVICE_EXTENDER_DATABASE_MISSING = 0x502, KSI_SERVICE_EXTENDER_DATABASE_CORRUPT = 0x503, KSI_SERVICE_EXTENDER_REQUEST_TIME_TOO_OLD = 0x504, KSI_SERVICE_EXTENDER_REQUEST_TIME_TOO_NEW = 0x505, KSI_SERVICE_EXTENDER_REQUEST_TIME_IN_FUTURE = 0x506, KSI_SERVICE_EXTENDER_PDU_V2_RESPONSE_TO_PDU_V1_REQUEST = 0x507, KSI_SERVICE_EXTENDER_PDU_V1_RESPONSE_TO_PDU_V2_REQUEST = 0x508, KSI_ASYNC_CONNECTION_CLOSED = 0x604, KSI_ASYNC_REQUEST_CACHE_FULL = 0x607, KSI_UNKNOWN_ERROR = 0xffff }

enum	KSI_Option_en { KSI_OPT_AGGR_PDU_VER, KSI_OPT_EXT_PDU_VER, KSI_OPT_AGGR_HMAC_ALGORITHM, KSI_OPT_EXT_HMAC_ALGORITHM, KSI_OPT_DATAHASH_CACHE_SIZE, KSI_OPT_AGGR_CONF_RECEIVED_CALLBACK, KSI_OPT_EXT_CONF_RECEIVED_CALLBACK, __KSI_NUMBER_OF_OPTIONS }

Functions
const char *	KSI_getVersion (void)

const char *	KSI_getErrorString (int statusCode)

int	KSI_CTX_new (KSI_CTX **ctx)

void	KSI_CTX_free (KSI_CTX *ctx)

int	KSI_CTX_registerGlobals (KSI_CTX ctx, int(initFn)(void), void(*cleanupFn)(void))

int	KSI_ERR_statusDump (KSI_CTX ctx, FILE f)

char *	KSI_ERR_toString (KSI_CTX ctx, char buf, size_t buf_len)

int	KSI_ERR_getBaseErrorMessage (KSI_CTX ctx, char buf, size_t len, int error, int ext)

void *	KSI_malloc (size_t size)

void *	KSI_calloc (size_t num, size_t size)

void	KSI_free (void *ptr)

int	KSI_sendAggregatorRequest (KSI_CTX ctx, KSI_AggregationReq request, KSI_RequestHandle **handle)

int	KSI_sendExtenderRequest (KSI_CTX ctx, KSI_ExtendReq request, KSI_RequestHandle **handle)

int	KSI_sendPublicationRequest (KSI_CTX ctx, const unsigned char request, size_t request_length, KSI_RequestHandle **handle)

int	KSI_receivePublicationsFile (KSI_CTX ctx, KSI_PublicationsFile *pubFile)

int	KSI_verifyPublicationsFile (KSI_CTX ctx, const KSI_PublicationsFile pubFile)

int	KSI_receiveAggregatorConfig (KSI_CTX ctx, KSI_Config *config)

int	KSI_receiveExtenderConfig (KSI_CTX ctx, KSI_Config *config)

int	KSI_verifySignature (KSI_CTX ctx, KSI_Signature sig)

int	KSI_verifyDataHash (KSI_CTX ctx, KSI_Signature sig, const KSI_DataHash *hsh)

int	KSI_createSignature (KSI_CTX ctx, KSI_DataHash dataHash, KSI_Signature **sig)

int	KSI_extendSignatureWithPolicy (KSI_CTX ctx, const KSI_Signature sig, const KSI_Policy policy, KSI_VerificationContext context, KSI_Signature **extended)

int	KSI_CTX_setLogLevel (KSI_CTX *ctx, int level)

int	KSI_CTX_setLoggerCallback (KSI_CTX ctx, KSI_LoggerCallback cb, void logCtx)

int	KSI_CTX_setRequestHeaderCallback (KSI_CTX *ctx, KSI_RequestHeaderCallback cb)

int	KSI_CTX_setPublicationUrl (KSI_CTX ctx, const char uri)

int	KSI_CTX_setExtender (KSI_CTX ctx, const char uri, const char loginId, const char key)

int	KSI_CTX_setAggregator (KSI_CTX ctx, const char uri, const char loginId, const char key)

int	KSI_CTX_setOption (KSI_CTX ctx, KSI_Option opt, void param)

int	KSI_CTX_setTransferTimeoutSeconds (KSI_CTX *ctx, int timeout)

int	KSI_CTX_setConnectionTimeoutSeconds (KSI_CTX *ctx, int timeout)

int	KSI_CTX_setPublicationsFile (KSI_CTX ctx, KSI_PublicationsFile var)

int	KSI_CTX_setPKITruststore (KSI_CTX ctx, KSI_PKITruststore pki)

int	KSI_CTX_setNetworkProvider (KSI_CTX ctx, KSI_NetworkClient net)

int	KSI_CTX_setPublicationCertEmail (KSI_CTX ctx, const char email)

int	KSI_CTX_setDefaultPubFileCertConstraints (KSI_CTX ctx, const KSI_CertConstraint arr)

int	KSI_CTX_getPKITruststore (KSI_CTX ctx, KSI_PKITruststore *pki)

int	KSI_CTX_getPublicationsFile (KSI_CTX ctx, KSI_PublicationsFile *var)

int	KSI_CTX_getPublicationCertEmail (KSI_CTX ctx, const char *address)

int	KSI_CTX_getLastFailedSignature (KSI_CTX ctx, KSI_Signature *lastFailedSignature)

Detailed Description

Macro Definition Documentation

◆ KSI_CERT_COMMON_NAME

#define KSI_CERT_COMMON_NAME "2.5.4.3"

◆ KSI_CERT_COUNTRY

#define KSI_CERT_COUNTRY "2.5.4.6"

◆ KSI_CERT_EMAIL

#define KSI_CERT_EMAIL "1.2.840.113549.1.9.1"

◆ KSI_CERT_ORGANIZATION

#define KSI_CERT_ORGANIZATION "2.5.4.10"

◆ KSI_CTX_FLAG_AGGR_PDU_VER

#define KSI_CTX_FLAG_AGGR_PDU_VER KSI_OPT_AGGR_PDU_VER

Deprecated. Defined for backwards compatibility. See KSI_Option and KSI_CTX_setOption for replacement.

◆ KSI_CTX_FLAG_EXT_PDU_VER

#define KSI_CTX_FLAG_EXT_PDU_VER KSI_OPT_EXT_PDU_VER

◆ KSI_CTX_setAggregatorHmacAlgorithm

#define KSI_CTX_setAggregatorHmacAlgorithm	(	ctx,
		alg_id
	)	KSI_CTX_setOption(ctx, KSI_OPT_AGGR_HMAC_ALGORITHM, (void*)(alg_id))

◆ KSI_CTX_setExtenderHmacAlgorithm

#define KSI_CTX_setExtenderHmacAlgorithm	(	ctx,
		alg_id
	)	KSI_CTX_setOption(ctx, KSI_OPT_EXT_HMAC_ALGORITHM, (void*)(alg_id))

◆ KSI_CTX_setFlag

#define KSI_CTX_setFlag	(	ctx,
		flag,
		param
	)	KSI_CTX_setOption((ctx), (flag), (param))

◆ KSI_CtxFlag

#define KSI_CtxFlag KSI_Option_en

◆ KSI_extendSignature

#define KSI_extendSignature	(	ctx,
		sig,
		extended
	)	KSI_extendSignatureWithPolicy(ctx, sig, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)

◆ KSI_PDU_VERSION_1

#define KSI_PDU_VERSION_1 1

Default PDU versions for KSI aggregation and extending messages.

◆ KSI_PDU_VERSION_2

#define KSI_PDU_VERSION_2 2

◆ KSI_sendExtendRequest

#define KSI_sendExtendRequest	(	ctx,
		request,
		handle
	)	KSI_sendExtenderRequest(ctx, request, handle)

◆ KSI_sendSignRequest

#define KSI_sendSignRequest	(	ctx,
		request,
		handle
	)	KSI_sendAggregatorRequest(ctx, request, handle)

Typedef Documentation

◆ KSI_Config_Callback

typedef int(* KSI_Config_Callback) (KSI_CTX *ctx, KSI_Config *conf)

Service configuration receive callback.

Parameters

[in]	ctx	KSI context object.
[in]	conf	Pointer to the configuration.

Returns: Implementation must return status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_Option

typedef enum KSI_Option_en KSI_Option

Enumeration Type Documentation

◆ KSI_Option_en

enum KSI_Option_en

Enumerator
KSI_OPT_AGGR_PDU_VER	Description: PDU version for KSI aggregation messages. Type: size_t. Range: KSI_PDU_VERSION_1 .. KSI_PDU_VERSION_2
KSI_OPT_EXT_PDU_VER	Description: PDU version for KSI extending messages. Type: size_t. Range: KSI_PDU_VERSION_1 .. KSI_PDU_VERSION_2
KSI_OPT_AGGR_HMAC_ALGORITHM	Description: Aggregator HMAC algorithm. Type: KSI_HashAlgorithm. Range: See KSI_HashAlgorithm.
KSI_OPT_EXT_HMAC_ALGORITHM	Description: Extender HMAC algorithm. Type: KSI_HashAlgorithm. Range: See KSI_HashAlgorithm.
KSI_OPT_DATAHASH_CACHE_SIZE	The size of the dynamic recycle pool for KSI_DataHash objects.
KSI_OPT_AGGR_CONF_RECEIVED_CALLBACK	Description: Aggregator configuration received callback. Type: KSI_Config_Callback. Note: The ownership of the KSI_Config object is not transfered to the callback. However, the user can call KSI_Config_ref in order to keep a reference of the object.
KSI_OPT_EXT_CONF_RECEIVED_CALLBACK	Description: Extender configuration received callback. Type: KSI_Config_Callback. Note: The ownership of the KSI_Config object is not transfered to the callback. However, the user can call KSI_Config_ref in order to keep a reference of the object.
__KSI_NUMBER_OF_OPTIONS

◆ KSI_StatusCode

enum KSI_StatusCode

KSI function returnvalues.

Enumerator
KSI_OK
KSI_AGGREGATOR_NOT_CONFIGURED	The aggregator has not been configured.
KSI_EXTENDER_NOT_CONFIGURED	The extender has not been configured.
KSI_PUBLICATIONS_FILE_NOT_CONFIGURED	The publications file url has not been configured.
KSI_PUBFILE_VERIFICATION_NOT_CONFIGURED	The publications file can not be verified, as the constraints are not configured.
KSI_INVALID_VERIFICATION_INPUT	The signature verification can not be completed due to invalid user data.
KSI_INVALID_ARGUMENT	Argument to function was invalid. Mostly this indicates `NULL` pointer.
KSI_INVALID_FORMAT	Either arguments to function or responses from the server had invalid format.
KSI_UNTRUSTED_HASH_ALGORITHM	The given hash algorithm is considered as untrusted by the verification policy.
KSI_UNAVAILABLE_HASH_ALGORITHM	This hash algorithm is not implemented.
KSI_BUFFER_OVERFLOW	Buffer too small to perform operation.
KSI_TLV_PAYLOAD_TYPE_MISMATCH	TLV payload has wrong type for operation.
KSI_ASYNC_NOT_FINISHED	The async operation has not finished.
KSI_INVALID_SIGNATURE	Invalid KSI signature.
KSI_INVALID_PKI_SIGNATURE	Invalid PKI signature.
KSI_PKI_CERTIFICATE_NOT_TRUSTED	The PKI signature is not trusted by the API.
KSI_INVALID_STATE	The objects used are in an invalid state.
KSI_OUT_OF_MEMORY	Out of memory.
KSI_IO_ERROR	IO error occurred.
KSI_NETWORK_ERROR	A network error occurred.
KSI_NETWORK_CONNECTION_TIMEOUT	A network connection timeout occurred.
KSI_NETWORK_SEND_TIMEOUT	A network send timeout occurred.
KSI_NETWORK_RECIEVE_TIMEOUT	A network receive timeout occurred.
KSI_HTTP_ERROR	A HTTP error occurred.
KSI_EXTEND_WRONG_CAL_CHAIN	The extender returned a wrong calendar chain.
KSI_EXTEND_NO_SUITABLE_PUBLICATION	No suitable publication to extend to.
KSI_VERIFICATION_FAILURE	The publication in the signature was not found in the publications file.
KSI_INVALID_PUBLICATION	Invalid publication.
KSI_PUBLICATIONS_FILE_NOT_SIGNED_WITH_PKI	The publications file is not signed.
KSI_CRYPTO_FAILURE	Cryptographic operation could not be performed. Likely causes are unsupported cryptographic algorithms, invalid keys and lack of resources.
KSI_HMAC_MISMATCH	HMAC mismatch occurred
KSI_REQUEST_PENDING	The request is still pending.
KSI_REQUEST_ID_MISMATCH	The request ID in response does not match with request ID in request.
KSI_HMAC_ALGORITHM_MISMATCH	HMAC algorithm mismatch occurred.
KSI_UNSUPPORTED_PDU_VERSION	Unsupporder PDU version.
KSI_SERVICE_INVALID_REQUEST	Pattern for errors with client request.
KSI_SERVICE_AUTHENTICATION_FAILURE	The request could not be authenticated (missing or unknown login identifier, MAC check failure, etc).
KSI_SERVICE_INVALID_PAYLOAD	The request contained invalid payload (unknown payload type, missing mandatory elements, unknown critical elements, etc).
KSI_SERVICE_INTERNAL_ERROR	The server encountered an unspecified internal error.
KSI_SERVICE_UPSTREAM_ERROR	The server encountered unspecified critical errors connecting to upstream servers.
KSI_SERVICE_UPSTREAM_TIMEOUT	No response from upstream aggregators.
KSI_SERVICE_UNKNOWN_ERROR	The extender returned an error.
KSI_SERVICE_AGGR_REQUEST_TOO_LARGE	The request indicated client-side aggregation tree larger than allowed for the client (retrying would not succeed either).
KSI_SERVICE_AGGR_REQUEST_OVER_QUOTA	The request combined with other requests from the same client in the same round would create an aggregation sub-tree larger than allowed for the client (retrying in a later round could succeed).
KSI_SERVICE_AGGR_TOO_MANY_REQUESTS	Too many requests from the client in the same round (retrying in a later round could succeed)
KSI_SERVICE_AGGR_INPUT_TOO_LONG	Input hash value in the client request is longer than the server allows.
KSI_SERVICE_AGGR_PDU_V2_RESPONSE_TO_PDU_V1_REQUEST	Received PDU v2 response to PDU v1 request. Configure the SDK to use PDU v2 format for the given aggregator.
KSI_SERVICE_AGGR_PDU_V1_RESPONSE_TO_PDU_V2_REQUEST	Received PDU v1 response to PDU v2 request. Configure the SDK to use PDU v1 format for the given aggregator.
KSI_SERVICE_EXTENDER_INVALID_TIME_RANGE	The request asked for a hash chain going backwards in time Pattern for local errors in the server.
KSI_SERVICE_EXTENDER_DATABASE_MISSING	The server misses the internal database needed to service the request (most likely it has not been initialized yet).
KSI_SERVICE_EXTENDER_DATABASE_CORRUPT	The server's internal database is in an inconsistent state.
KSI_SERVICE_EXTENDER_REQUEST_TIME_TOO_OLD	The request asked for hash values older than the oldest round in the server's database.
KSI_SERVICE_EXTENDER_REQUEST_TIME_TOO_NEW	The request asked for hash values newer than the newest round in the server's database.
KSI_SERVICE_EXTENDER_REQUEST_TIME_IN_FUTURE	The request asked for hash values newer than the current real time.
KSI_SERVICE_EXTENDER_PDU_V2_RESPONSE_TO_PDU_V1_REQUEST	Received PDU v2 response to PDU v1 request. Configure the SDK to use PDU v2 format for the given extender.
KSI_SERVICE_EXTENDER_PDU_V1_RESPONSE_TO_PDU_V2_REQUEST	Received PDU v1 response to PDU v2 request. Configure the SDK to use PDU v1 format for the given extender.
KSI_ASYNC_CONNECTION_CLOSED	The async connection was closed.
KSI_ASYNC_REQUEST_CACHE_FULL	The async request cache is full. Meaning that no more requests can be added temporarely.
KSI_UNKNOWN_ERROR	Unknown error occurred.

Function Documentation

◆ KSI_calloc()

void* KSI_calloc	(	size_t	num,
		size_t	size
	)

Allocates num times of size bytes of memory.

Parameters

[in]	num	Number of blocks to allocate.
[in]	size	Size of a single block.

Returns: Pointer to the allocated memory, or NULL if an error occurred.

Note: The caller needs to free the allocated memory with KSI_free.

◆ KSI_createSignature()

int KSI_createSignature	(	KSI_CTX *	ctx,
		KSI_DataHash *	dataHash,
		KSI_Signature **	sig
	)

Create a KSI signature from a given data hash.

Parameters

[in]	ctx	KSI context.
[in]	dataHash	Data hash object from the document to be signed.
[out]	sig	Pointer to the receiving pointer to the KSI signature object.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_Signature_free, KSI_extendSignature

◆ KSI_CTX_free()

void KSI_CTX_free ( KSI_CTX * ctx )

Destructor for KSI context object KSI_CTX.

Parameters

[in] ctx KSI ctx.

Note: This function should not be called when there still exist some objects created using this context.

◆ KSI_CTX_getLastFailedSignature()

int KSI_CTX_getLastFailedSignature	(	KSI_CTX *	ctx,
		KSI_Signature **	lastFailedSignature
	)

Getter method for lastFailedSignature.

Parameters

[in]	ctx	Pointer to KSI_CTX.
[out]	lastFailedSignature	Pointer to receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: Ownership of lastFailedSignature is passed to the caller who is responsible for freeing the object.

◆ KSI_CTX_getPKITruststore()

int KSI_CTX_getPKITruststore	(	KSI_CTX *	ctx,
		KSI_PKITruststore **	pki
	)

Getter function for the PKI truststore object.

Parameters

[in]	ctx	KSI context.
[out]	pki	Pointer to the receiving PKI trust store pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_getPublicationCertEmail()

int KSI_CTX_getPublicationCertEmail	(	KSI_CTX *	ctx,
		const char **	address
	)

Getter function for the e-mail address used to verify the publications file PKI signature.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Parameters

[in]	ctx	KSI context.
[out]	address	Pointer to the receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The user may not free the output pointer, as it belongs to the context.

◆ KSI_CTX_getPublicationsFile()

int KSI_CTX_getPublicationsFile	(	KSI_CTX *	ctx,
		KSI_PublicationsFile **	var
	)

Getter function for the publications file.

Parameters

[in]	ctx	KSI context.
[out]	var	Pointer to the receiving pointer to publications file.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_new()

int KSI_CTX_new ( KSI_CTX ** ctx )

Constructor for the central KSI object KSI_CTX. For thread safety, this object may not be shared between threads. Also, this object may be freed only if there are no other objects created using this object - this applies recursively to other objects created by the user.

Parameters

[in] ctx Pointer to the receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_registerGlobals()

int KSI_CTX_registerGlobals	(	KSI_CTX *	ctx,
		int(*)(void)	initFn,
		void(*)(void)	cleanupFn
	)

This function is used to call global init functions and to register the appropriate global cleanup method. The init function will be called only once per KSI context and the cleanup method will be called when KSI_CTX_free is called on the context object. The global init and cleanup functions must keep track how many times they are called (if multiple calls cause issues) and allow multiple calls.

Parameters

[in]	ctx	KSI context.
[in]	initFn	Global initiation function.
[in]	cleanupFn	Global cleanup function.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setAggregator()

int KSI_CTX_setAggregator	(	KSI_CTX *	ctx,
		const char *	uri,
		const char *	loginId,
		const char *	key
	)

Configuration method for the aggregator.

Parameters

[in]	ctx	KSI context.
[in]	uri	Aggregation service URI.
[in]	loginId	The login id for the service.
[in]	key	Key for the loginId.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setConnectionTimeoutSeconds()

int KSI_CTX_setConnectionTimeoutSeconds	(	KSI_CTX *	ctx,
		int	timeout
	)

Setter for connection timeout.

Parameters

[in]	ctx	KSI context.
[in]	timeout	Connection timeout in seconds.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setDefaultPubFileCertConstraints()

int KSI_CTX_setDefaultPubFileCertConstraints	(	KSI_CTX *	ctx,
		const KSI_CertConstraint *	arr
	)

This method specifies the default constraints for verifying the publications file PKI certificate. The input consists of an array of OID and expected value pairs terminated by a pair of two NULLs. Except in the last terminating NULL pair, the expected value may not be NULL - this will make the function to return KSI_INVALID_ARGUMENT.

Parameters

[in]	ctx	KSI context.
[in]	arr	Array of OID and value pairs, terminated by a pair of NULLs.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The function does not take ownership of the input array and makes a copy of it, thus the caller is responsible for freeing the memory which can be done right after a successful call to this function.
KSI_CertConstraint arr[] = {
{ KSI_CERT_EMAIL, "publications@guardtime.com"},
{ NULL, NULL }
};
res = KSI_CTX_setDefaultPubFileCertConstraints(ctx, arr);

◆ KSI_CTX_setExtender()

int KSI_CTX_setExtender	(	KSI_CTX *	ctx,
		const char *	uri,
		const char *	loginId,
		const char *	key
	)

Configuration method for the extender.

Parameters

[in]	ctx	KSI context.
[in]	uri	Extending service URI.
[in]	loginId	The login id for the service.
[in]	key	Key for the loginId.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setLoggerCallback()

int KSI_CTX_setLoggerCallback	(	KSI_CTX *	ctx,
		KSI_LoggerCallback	cb,
		void *	logCtx
	)

This function sets the callback for logging for the context. For logging to streams KSI_LOG_StreamLogger can be used.

Parameters

[in]	ctx	KSI context.
[in]	cb	Logger callback function.
[in]	logCtx	Pointer to logger context, may be `NULL`.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_LOG_StreamLogger, KSI_CTX_setLogLevel

Note: The stream must be freed by the caller.

◆ KSI_CTX_setLogLevel()

int KSI_CTX_setLogLevel	(	KSI_CTX *	ctx,
		int	level
	)

Setter for the internal log level.

Parameters

[in]	ctx	KSI context.
[in]	level	Log level.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_LOG_LVL_en, KSI_CTX_setLoggerCallback.

◆ KSI_CTX_setNetworkProvider()

int KSI_CTX_setNetworkProvider	(	KSI_CTX *	ctx,
		KSI_NetworkClient *	net
	)

Setter for the network provider.

Parameters

[in]	ctx	KSI context,.
[in]	net	Network provider.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setOption()

int KSI_CTX_setOption	(	KSI_CTX *	ctx,
		KSI_Option	opt,
		void *	param
	)

Configuration method for the KSI option.

Parameters

[in]	ctx	KSI context.
[in]	opt	KSI option.
[in]	param	Value for specified KSI option.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_Option for individual option descriptions.

Note: Interpretation of param is dependent on the KSI option.

◆ KSI_CTX_setPKITruststore()

int KSI_CTX_setPKITruststore	(	KSI_CTX *	ctx,
		KSI_PKITruststore *	pki
	)

Setter for the PKI truststore.

Parameters

[in]	ctx	KSI context.
[in]	pki	PKI trust store.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setPublicationCertEmail()

int KSI_CTX_setPublicationCertEmail	(	KSI_CTX *	ctx,
		const char *	email
	)

Deprecated:: Use KSI_CTX_setDefaultPubFileCertConstraints with # "1.2.840.113549.1.9.1" instead.

◆ KSI_CTX_setPublicationsFile()

int KSI_CTX_setPublicationsFile	(	KSI_CTX *	ctx,
		KSI_PublicationsFile *	var
	)

Setter function for the publications file.

Parameters

[in]	ctx	KSI context.
[in]	var	Publications file.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setPublicationUrl()

int KSI_CTX_setPublicationUrl	(	KSI_CTX *	ctx,
		const char *	uri
	)

Setter for publications file url.

Parameters

[in]	ctx	KSI_context.
[in]	uri	URL to the publications file.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setRequestHeaderCallback()

int KSI_CTX_setRequestHeaderCallback	(	KSI_CTX *	ctx,
		KSI_RequestHeaderCallback	cb
	)

This function sets the callback which is executed on every requests header KSI_Header prior to serializing and submitting the request. The callback should be used when additional data (i.e session id and message id) should be added to the header.

Parameters

[in]	ctx	KSI context.
[in]	cb	Request header callback function.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_CTX_setTransferTimeoutSeconds()

int KSI_CTX_setTransferTimeoutSeconds	(	KSI_CTX *	ctx,
		int	timeout
	)

Setter for transfer timeout.

Parameters

[in]	ctx	KSI context.
[in]	timeout	Transfer timeout in seconds.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_ERR_getBaseErrorMessage()

int KSI_ERR_getBaseErrorMessage	(	KSI_CTX *	ctx,
		char *	buf,
		size_t	len,
		int *	error,
		int *	ext
	)

Get base error message and optional internal and external error code. If there are no errors, buf will contain string returned by KSI_getErrorString(KSI_OK), error will be equal to KSI_OK and ext will be equal to 0.

Parameters

[in]	ctx	KSI context object.
[out]	buf	Buffer for storing error message.
[in]	len	The length of the buffer.
[out]	error	Pointer to buffer for base error code. Can be NULL.
[out]	ext	Pointer to buffer for external component error code. Can be NULL.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_ERR_statusDump()

int KSI_ERR_statusDump	(	KSI_CTX *	ctx,
		FILE *	f
	)

Dump error stack trace to stream.

Parameters

[in]	ctx	KSI context object.
[in]	f	Output stream.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_ERR_toString()

char* KSI_ERR_toString	(	KSI_CTX *	ctx,
		char *	buf,
		size_t	buf_len
	)

Get error stack trace NUL terminated c string representation.

Parameters

[in]	ctx	KSI context object.
[in]	buf	Pointer to receiving buffer.
[in]	buf_len	Size of buf.

Returns: buf if successful, NULL otherwise;

◆ KSI_extendSignatureWithPolicy()

int KSI_extendSignatureWithPolicy	(	KSI_CTX *	ctx,
		const KSI_Signature *	sig,
		const KSI_Policy *	policy,
		KSI_VerificationContext *	context,
		KSI_Signature **	extended
	)

Extend the signature to the earliest available publication. Verify the extended signature with the provided policy and context.

Parameters

[in]	ctx	KSI context.
[in]	sig	Signature to be extended.
[in]	policy	Verification policy.
[in]	context	Verification context.
[out]	extended	Pointer to the receiving pointer to the extended signature.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

See also: KSI_Signature_free, KSI_createSignature

◆ KSI_free()

void KSI_free ( void * ptr )

Free memory allocated by KSI_malloc or KSI_calloc.

Parameters

[in] ptr Pointer to the memory to be freed.

◆ KSI_getErrorString()

const char* KSI_getErrorString ( int statusCode )

Function to convert a KSI_StatusCode value to a human readable string value.

Parameters

[in] statusCode KSI_StatusCode value.

Returns: A pointer to a statically allocated string value. This pointer may not be freed by the caller.

◆ KSI_getVersion()

const char* KSI_getVersion ( void )

This function returns a pointer to a constant string describing the version number of the package.

Returns: A constant pointer to a string.

◆ KSI_malloc()

void* KSI_malloc ( size_t size )

Allocates size bytes of memory.

Parameters

[in] size Size of allocated block.

Returns: Pointer to the allocated memory, or NULL if an error occurred.

Note: The caller needs to free the allocated memory with KSI_free.

◆ KSI_receiveAggregatorConfig()

int KSI_receiveAggregatorConfig	(	KSI_CTX *	ctx,
		KSI_Config **	config
	)

Get aggregator service configuration.

Parameters

[in]	ctx	KSI context.
[out]	config	Pointer to the receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_receiveExtenderConfig()

int KSI_receiveExtenderConfig	(	KSI_CTX *	ctx,
		KSI_Config **	config
	)

Get extender service configuration.

Parameters

[in]	ctx	KSI context.
[out]	config	Pointer to the receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_receivePublicationsFile()

int KSI_receivePublicationsFile	(	KSI_CTX *	ctx,
		KSI_PublicationsFile **	pubFile
	)

Accessor method for the publications file. It will download the publications file from the uri specified by the KSI context.

Parameters

[in]	ctx	KSI context.
[out]	pubFile	Pointer to the receiving pointer.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Note: The publications file is not verified, use KSI_PublicationsFile_verify to do so.

See also: KSI_PublicationsFile_verify

◆ KSI_sendAggregatorRequest()

int KSI_sendAggregatorRequest	(	KSI_CTX *	ctx,
		KSI_AggregationReq *	request,
		KSI_RequestHandle **	handle
	)

Send a binary request to aggregator using the specified KSI context.

Parameters

[in]	ctx	KSI context object.
[in]	request	Request object.
[out]	handle	Pointer to the receiving pointer of the network handle.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_sendExtenderRequest()

int KSI_sendExtenderRequest	(	KSI_CTX *	ctx,
		KSI_ExtendReq *	request,
		KSI_RequestHandle **	handle
	)

Send a binary request to extender using the specified KSI context.

Parameters

[in]	ctx	KSI context object.
[in]	request	Request object.
[out]	handle	Pointer to the receiving pointer of the network handle.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_sendPublicationRequest()

int KSI_sendPublicationRequest	(	KSI_CTX *	ctx,
		const unsigned char *	request,
		size_t	request_length,
		KSI_RequestHandle **	handle
	)

Send a binary request to download publications file using the specified KSI context.

Parameters

[in]	ctx	KSI context object.
[in]	request	Pointer to the binary request.
[in]	request_length	Length of the binary request.
[out]	handle	Pointer to the receiving pointer of the network handle.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_verifyDataHash()

int KSI_verifyDataHash	(	KSI_CTX *	ctx,
		KSI_Signature *	sig,
		const KSI_DataHash *	hsh
	)

Use the KSI context to verify the signature and the datahash.

Parameters

[in]	ctx	KSI context.
[in]	sig	KSI signature.
[in]	hsh	Document data hash.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_verifyPublicationsFile()

int KSI_verifyPublicationsFile	(	KSI_CTX *	ctx,
		const KSI_PublicationsFile *	pubFile
	)

Verify the PKI signature of the publications file using the context.

Parameters

[in]	ctx	KSI context.
[in]	pubFile	Publications file.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

◆ KSI_verifySignature()

int KSI_verifySignature	(	KSI_CTX *	ctx,
		KSI_Signature *	sig
	)

Use the KSI context to verify the signature.

Parameters

[in]	ctx	KSI context.
[in]	sig	KSI signature.

Returns: status code (KSI_OK, when operation succeeded, otherwise an error code).

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ KSI_CERT_COMMON_NAME

◆ KSI_CERT_COUNTRY

◆ KSI_CERT_EMAIL

◆ KSI_CERT_ORGANIZATION

◆ KSI_CTX_FLAG_AGGR_PDU_VER

◆ KSI_CTX_FLAG_EXT_PDU_VER

◆ KSI_CTX_setAggregatorHmacAlgorithm

◆ KSI_CTX_setExtenderHmacAlgorithm

◆ KSI_CTX_setFlag

◆ KSI_CtxFlag

◆ KSI_extendSignature

◆ KSI_PDU_VERSION_1

◆ KSI_PDU_VERSION_2

◆ KSI_sendExtendRequest

◆ KSI_sendSignRequest

Typedef Documentation

◆ KSI_Config_Callback

◆ KSI_Option

Enumeration Type Documentation

◆ KSI_Option_en

◆ KSI_StatusCode

Function Documentation

◆ KSI_calloc()

◆ KSI_createSignature()

◆ KSI_CTX_free()

◆ KSI_CTX_getLastFailedSignature()

◆ KSI_CTX_getPKITruststore()

◆ KSI_CTX_getPublicationCertEmail()

◆ KSI_CTX_getPublicationsFile()

◆ KSI_CTX_new()

◆ KSI_CTX_registerGlobals()

◆ KSI_CTX_setAggregator()

◆ KSI_CTX_setConnectionTimeoutSeconds()

◆ KSI_CTX_setDefaultPubFileCertConstraints()

◆ KSI_CTX_setExtender()

◆ KSI_CTX_setLoggerCallback()

◆ KSI_CTX_setLogLevel()

◆ KSI_CTX_setNetworkProvider()

◆ KSI_CTX_setOption()

◆ KSI_CTX_setPKITruststore()

◆ KSI_CTX_setPublicationCertEmail()

◆ KSI_CTX_setPublicationsFile()

◆ KSI_CTX_setPublicationUrl()

◆ KSI_CTX_setRequestHeaderCallback()

◆ KSI_CTX_setTransferTimeoutSeconds()

◆ KSI_ERR_getBaseErrorMessage()

◆ KSI_ERR_statusDump()

◆ KSI_ERR_toString()

◆ KSI_extendSignatureWithPolicy()

◆ KSI_free()

◆ KSI_getErrorString()

◆ KSI_getVersion()

◆ KSI_malloc()

◆ KSI_receiveAggregatorConfig()

◆ KSI_receiveExtenderConfig()

◆ KSI_receivePublicationsFile()

◆ KSI_sendAggregatorRequest()

◆ KSI_sendExtenderRequest()

◆ KSI_sendPublicationRequest()

◆ KSI_verifyDataHash()

◆ KSI_verifyPublicationsFile()

◆ KSI_verifySignature()