Guardtime KSI c SDK
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Macros | Typedefs | Enumerations | Functions
KSI Base Functionality

Macros

#define KSI_CTX_PUBFILE_CACHE_DEFAULT_TTL   (8 * 60 * 60)
 
#define KSI_CTX_HA_MAX_SUBSERVICES   3
 
#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_UNKNOWN_HASH_ALGORITHM_ID = 0x10b, KSI_HASH_ALGORITHM_DEPRECATED = 0x10c, KSI_HASH_ALGORITHM_OBSOLETE = 0x10d,
  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_INCOMPATIBLE_HASH_CHAIN = 0x213, KSI_NETWORK_PROVIDER_DISABLED = 0x214,
  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_PDUver_en { KSI_ENUM_DEPRECATED =(KSI_PDU_VERSION_1, Only PDU v2 is supported.) = 1, KSI_PDU_VERSION_2 = 2 }
 
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_OPT_PUBFILE_CACHE_TTL_SECONDS,
  KSI_OPT_HA_SAFEGUARD, __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

#define KSI_CERT_COMMON_NAME   "2.5.4.3"
#define KSI_CERT_COUNTRY   "2.5.4.6"
#define KSI_CERT_EMAIL   "1.2.840.113549.1.9.1"
#define KSI_CERT_ORGANIZATION   "2.5.4.10"
#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.

#define KSI_CTX_FLAG_EXT_PDU_VER   KSI_OPT_EXT_PDU_VER
#define KSI_CTX_HA_MAX_SUBSERVICES   3
#define KSI_CTX_PUBFILE_CACHE_DEFAULT_TTL   (8 * 60 * 60)
#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_setFlag (   ctx,
  flag,
  param 
)    KSI_CTX_setOption((ctx), (flag), (param))
#define KSI_CtxFlag   KSI_Option_en
#define KSI_extendSignature (   ctx,
  sig,
  extended 
)    KSI_extendSignatureWithPolicy(ctx, sig, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)
#define KSI_sendExtendRequest (   ctx,
  request,
  handle 
)    KSI_sendExtenderRequest(ctx, request, handle)
#define KSI_sendSignRequest (   ctx,
  request,
  handle 
)    KSI_sendAggregatorRequest(ctx, request, handle)

Typedef Documentation

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

Service configuration receive callback.

Parameters
[in]ctxKSI context object.
[in]confPointer to the configuration.
Returns
Implementation must return status code (KSI_OK, when operation succeeded, otherwise an error code).
typedef enum KSI_Option_en KSI_Option

Enumeration Type Documentation

Enumerator
KSI_OPT_AGGR_PDU_VER 

PDU version for KSI aggregation messages.

Parameters
versionPDU version. Paramer of type size_t.
Note
Range: KSI_PDUver_en
KSI_OPT_EXT_PDU_VER 

PDU version for KSI extending messages.

Parameters
versionPDU version. Paramer of type size_t.
Note
Range: KSI_PDUver_en
KSI_OPT_AGGR_HMAC_ALGORITHM 

Aggregator HMAC algorithm.

Parameters
algorithmHash algorithm. Paramer of type KSI_HashAlgorithm.
KSI_OPT_EXT_HMAC_ALGORITHM 

Extender HMAC algorithm.

Parameters
algorithmHash algorithm. Paramer of type KSI_HashAlgorithm.
KSI_OPT_DATAHASH_CACHE_SIZE 

The size of the dynamic recycle pool for KSI_DataHash objects.

Parameters
countCache size. Paramer of type size_t.
KSI_OPT_AGGR_CONF_RECEIVED_CALLBACK 

Aggregator configuration received callback.

Parameters
p_funcCallback method. Paramer of 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 

Extender configuration received callback.

Parameters
p_funcCallback method. Paramer of 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_PUBFILE_CACHE_TTL_SECONDS 

Publications file cache timeout. After the timeout expires a call to the KSI_receivePublicationsFile will trigger a new publications file download.

Parameters
timeoutTimeout in seconds. Paramer of type size_t.
See also
KSI_receivePublicationsFile
Note
Setting the timeout to 0 will always trigger the file download.
KSI_OPT_HA_SAFEGUARD 

High availability service maximum number of subservices.

Parameters
countNumber of subservices. Paramer of type size_t.
See also
KSI_SigningHighAvailabilityService_new for creating aggregations service.
KSI_ExtendingHighAvailabilityService_new for creating extending service.
KSI_CTX_HA_MAX_SUBSERVICES for default value.
__KSI_NUMBER_OF_OPTIONS 

Default PDU versions for KSI aggregation and extending messages.

Enumerator
KSI_ENUM_DEPRECATED 
KSI_PDU_VERSION_2 

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_UNKNOWN_HASH_ALGORITHM_ID 

The hash algorithm ID is invalid or unknown to the implementation.

KSI_HASH_ALGORITHM_DEPRECATED 
KSI_HASH_ALGORITHM_OBSOLETE 
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_INCOMPATIBLE_HASH_CHAIN 

Incompatible calendar hash chain.

KSI_NETWORK_PROVIDER_DISABLED 

Network provider is disabled (at compile time). This meens that the desired network provider can not be used runtime anymore.

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

void* KSI_calloc ( size_t  num,
size_t  size 
)

Allocates num times of size bytes of memory.

Parameters
[in]numNumber of blocks to allocate.
[in]sizeSize 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.
int KSI_createSignature ( KSI_CTX ctx,
KSI_DataHash dataHash,
KSI_Signature **  sig 
)

Create a KSI signature from a given data hash.

Parameters
[in]ctxKSI context.
[in]dataHashData hash object from the document to be signed.
[out]sigPointer 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
void KSI_CTX_free ( KSI_CTX ctx)

Destructor for KSI context object KSI_CTX.

Parameters
[in]ctxKSI ctx.
Note
This function should not be called when there still exist some objects created using this context.
int KSI_CTX_getLastFailedSignature ( KSI_CTX ctx,
KSI_Signature **  lastFailedSignature 
)

Getter method for lastFailedSignature.

Parameters
[in]ctxPointer to KSI_CTX.
[out]lastFailedSignaturePointer 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.
Deprecated:
Use KSI_VERIFICATION_POLICY_EMPTY instead.
int KSI_CTX_getPKITruststore ( KSI_CTX ctx,
KSI_PKITruststore **  pki 
)

Getter function for the PKI truststore object.

Parameters
[in]ctxKSI context.
[out]pkiPointer to the receiving PKI trust store pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[out]addressPointer 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.
int KSI_CTX_getPublicationsFile ( KSI_CTX ctx,
KSI_PublicationsFile **  var 
)

Getter function for the publications file.

Parameters
[in]ctxKSI context.
[out]varPointer to the receiving pointer to publications file.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[in]initFnGlobal initiation function.
[in]cleanupFnGlobal cleanup function.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setAggregator ( KSI_CTX ctx,
const char *  uri,
const char *  loginId,
const char *  key 
)

Configuration method for the aggregator.

Parameters
[in]ctxKSI context.
[in]uriAggregation service URI.
[in]loginIdThe login id for the service.
[in]keyKey for the loginId.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setConnectionTimeoutSeconds ( KSI_CTX ctx,
int  timeout 
)

Setter for connection timeout.

Parameters
[in]ctxKSI context.
[in]timeoutConnection timeout in seconds.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[in]arrArray 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_CERT_EMAIL, "publications@guardtime.com"},
{ NULL, NULL }
};
int KSI_CTX_setExtender ( KSI_CTX ctx,
const char *  uri,
const char *  loginId,
const char *  key 
)

Configuration method for the extender.

Parameters
[in]ctxKSI context.
[in]uriExtending service URI.
[in]loginIdThe login id for the service.
[in]keyKey for the loginId.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[in]cbLogger callback function.
[in]logCtxPointer 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.
int KSI_CTX_setLogLevel ( KSI_CTX ctx,
int  level 
)

Setter for the internal log level.

Parameters
[in]ctxKSI context.
[in]levelLog level.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_LOG_LVL_en, KSI_CTX_setLoggerCallback.
int KSI_CTX_setNetworkProvider ( KSI_CTX ctx,
KSI_NetworkClient net 
)

Setter for the network provider.

Parameters
[in]ctxKSI context,.
[in]netNetwork provider.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setOption ( KSI_CTX ctx,
KSI_Option  opt,
void *  param 
)

Configuration method for the KSI option.

Parameters
[in]ctxKSI context.
[in]optKSI option.
[in]paramValue 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.
int KSI_CTX_setPKITruststore ( KSI_CTX ctx,
KSI_PKITruststore pki 
)

Setter for the PKI truststore.

Parameters
[in]ctxKSI context.
[in]pkiPKI trust store.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setPublicationCertEmail ( KSI_CTX ctx,
const char *  email 
)
Deprecated:
Use KSI_CTX_setDefaultPubFileCertConstraints with # "1.2.840.113549.1.9.1" instead.
int KSI_CTX_setPublicationsFile ( KSI_CTX ctx,
KSI_PublicationsFile var 
)

Setter function for the publications file.

Parameters
[in]ctxKSI context.
[in]varPublications file.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setPublicationUrl ( KSI_CTX ctx,
const char *  uri 
)

Setter for publications file url.

Parameters
[in]ctxKSI_context.
[in]uriURL to the publications file.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The publications file cache will be reset.
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]ctxKSI context.
[in]cbRequest header callback function.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_CTX_setTransferTimeoutSeconds ( KSI_CTX ctx,
int  timeout 
)

Setter for transfer timeout.

Parameters
[in]ctxKSI context.
[in]timeoutTransfer timeout in seconds.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context object.
[out]bufBuffer for storing error message.
[in]lenThe length of the buffer.
[out]errorPointer to buffer for base error code. Can be NULL.
[out]extPointer to buffer for external component error code. Can be NULL.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_ERR_statusDump ( KSI_CTX ctx,
FILE *  f 
)

Dump error stack trace to stream.

Parameters
[in]ctxKSI context object.
[in]fOutput stream.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
char* KSI_ERR_toString ( KSI_CTX ctx,
char *  buf,
size_t  buf_len 
)

Get error stack trace NUL terminated c string representation.

Parameters
[in]ctxKSI context object.
[in]bufPointer to receiving buffer.
[in]buf_lenSize of buf.
Returns
buf if successful, NULL otherwise;
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]ctxKSI context.
[in]sigSignature to be extended.
[in]policyVerification policy.
[in]contextVerification context.
[out]extendedPointer 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
void KSI_free ( void *  ptr)

Free memory allocated by KSI_malloc or KSI_calloc.

Parameters
[in]ptrPointer to the memory to be freed.
const char* KSI_getErrorString ( int  statusCode)

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

Parameters
[in]statusCodeKSI_StatusCode value.
Returns
A pointer to a statically allocated string value. This pointer may not be freed by the caller.
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.
void* KSI_malloc ( size_t  size)

Allocates size bytes of memory.

Parameters
[in]sizeSize 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.
int KSI_receiveAggregatorConfig ( KSI_CTX ctx,
KSI_Config **  config 
)

Get aggregator service configuration.

Parameters
[in]ctxKSI context.
[out]configPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_receiveExtenderConfig ( KSI_CTX ctx,
KSI_Config **  config 
)

Get extender service configuration.

Parameters
[in]ctxKSI context.
[out]configPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[out]pubFilePointer 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.
The downloaded publications file is cached. Sequential calls to this method will return the cached file, except the cache timeout KSI_OPT_PUBFILE_CACHE_TTL_SECONDS has expired in which case a new download is triggered.
See also
KSI_CTX_setPublicationUrl for setting Publications file URL.
KSI_PublicationsFile_verify for publication file verification.
KSI_CTX_setOption(KSI_OPT_PUBFILE_CACHE_TTL_SECONDS) for setting cache timeout.
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]ctxKSI context object.
[in]requestRequest object.
[out]handlePointer to the receiving pointer of the network handle.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context object.
[in]requestRequest object.
[out]handlePointer to the receiving pointer of the network handle.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context object.
[in]requestPointer to the binary request.
[in]request_lengthLength of the binary request.
[out]handlePointer to the receiving pointer of the network handle.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
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]ctxKSI context.
[in]sigKSI signature.
[in]hshDocument data hash.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_verifyPublicationsFile ( KSI_CTX ctx,
const KSI_PublicationsFile pubFile 
)

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

Parameters
[in]ctxKSI context.
[in]pubFilePublications file.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_verifySignature ( KSI_CTX ctx,
KSI_Signature sig 
)

Use the KSI context to verify the signature.

Parameters
[in]ctxKSI context.
[in]sigKSI signature.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).