Guardtime KSI c SDK
Typedefs | Functions
Publications

Typedefs

typedef struct KSI_PublicationsFile_st KSI_PublicationsFile
 

Functions

int KSI_PublicationsFile_parse (KSI_CTX *ctx, const void *raw, size_t raw_len, KSI_PublicationsFile **pubFile)
 
KSI_PublicationsFileKSI_PublicationsFile_ref (KSI_PublicationsFile *o)
 
int KSI_PublicationsFile_fromFile (KSI_CTX *ctx, const char *fileName, KSI_PublicationsFile **pubFile)
 
int KSI_PublicationsFile_serialize (KSI_CTX *ctx, KSI_PublicationsFile *pubFile, char **raw, size_t *raw_len)
 
int KSI_PublicationsFile_verify (const KSI_PublicationsFile *pubFile, KSI_CTX *ctx)
 
int KSI_PublicationsFile_getHeader (const KSI_PublicationsFile *pubFile, KSI_PublicationsHeader **header)
 
int KSI_PublicationsFile_getCertificates (const KSI_PublicationsFile *pubFile, KSI_LIST(KSI_CertificateRecord)**certificates)
 
int KSI_PublicationsFile_getPublications (const KSI_PublicationsFile *pubFile, KSI_LIST(KSI_PublicationRecord)**publications)
 
int KSI_PublicationsFile_getSignature (const KSI_PublicationsFile *pubFile, KSI_PKISignature **signature)
 
int KSI_PublicationsFile_getSignedDataLength (const KSI_PublicationsFile *pubFile, size_t *signedDataLength)
 
int KSI_PublicationsFile_getCertConstraints (const KSI_PublicationsFile *pubFile, KSI_CertConstraint **certConstraints)
 
int KSI_PublicationsFile_getPKICertificateById (const KSI_PublicationsFile *pubFile, const KSI_OctetString *id, KSI_PKICertificate **cert)
 
int KSI_PublicationsFile_getPublicationDataByTime (const KSI_PublicationsFile *pubFile, const KSI_Integer *pubTime, KSI_PublicationRecord **pubRec)
 
int KSI_PublicationsFile_getPublicationDataByPublicationString (const KSI_PublicationsFile *pubFile, const char *pubString, KSI_PublicationRecord **pubRec)
 
int KSI_PublicationsFile_getNearestPublication (const KSI_PublicationsFile *pubFile, const KSI_Integer *pubTime, KSI_PublicationRecord **pubRec)
 
int KSI_PublicationsFile_getLatestPublication (const KSI_PublicationsFile *pubFile, const KSI_Integer *pubTime, KSI_PublicationRecord **pubRec)
 
int KSI_PublicationsFile_setHeader (KSI_PublicationsFile *pubFile, KSI_PublicationsHeader *header)
 
int KSI_PublicationsFile_setCertificates (KSI_PublicationsFile *pubFile, KSI_LIST(KSI_CertificateRecord)*certificates)
 
int KSI_PublicationsFile_setPublications (KSI_PublicationsFile *pubFile, KSI_LIST(KSI_PublicationRecord)*publications)
 
int KSI_PublicationsFile_setSignature (KSI_PublicationsFile *pubFile, KSI_PKISignature *signature)
 
int KSI_PublicationsFile_new (KSI_CTX *ctx, KSI_PublicationsFile **pubFile)
 
void KSI_PublicationsFile_free (KSI_PublicationsFile *pubFile)
 
int KSI_PublicationsFile_findPublicationByTime (const KSI_PublicationsFile *trust, const KSI_Integer *time, KSI_PublicationRecord **outRec)
 
int KSI_PublicationsFile_findPublication (const KSI_PublicationsFile *trust, const KSI_PublicationRecord *inRec, KSI_PublicationRecord **outRec)
 
int KSI_PublicationsFile_setCertConstraints (KSI_PublicationsFile *pubFile, const KSI_CertConstraint *arr)
 
int KSI_PublicationData_fromBase32 (KSI_CTX *ctx, const char *publication, KSI_PublicationData **published_data)
 
int KSI_PublicationData_toBase32 (const KSI_PublicationData *published_data, char **publication)
 
void KSI_PublicationData_free (KSI_PublicationData *t)
 
int KSI_PublicationData_new (KSI_CTX *ctx, KSI_PublicationData **t)
 
int KSI_PublicationData_getBaseTlv (const KSI_PublicationData *o, KSI_TLV **baseTlv)
 
int KSI_PublicationData_getTime (const KSI_PublicationData *t, KSI_Integer **time)
 
int KSI_PublicationData_getImprint (const KSI_PublicationData *t, KSI_DataHash **imprint)
 
int KSI_PublicationData_setBaseTlv (KSI_PublicationData *o, KSI_TLV *baseTlv)
 
int KSI_PublicationData_setTime (KSI_PublicationData *t, KSI_Integer *time)
 
int KSI_PublicationData_setImprint (KSI_PublicationData *t, KSI_DataHash *imprint)
 
char * KSI_PublicationData_toString (const KSI_PublicationData *t, char *buffer, size_t buffer_len)
 
int KSI_PublicationData_fromTlv (KSI_TLV *tlv, KSI_PublicationData **data)
 
int KSI_PublicationData_toTlv (KSI_CTX *ctx, const KSI_PublicationData *data, unsigned tag, int isNonCritical, int isForward, KSI_TLV **tlv)
 
KSI_PublicationDataKSI_PublicationData_ref (KSI_PublicationData *o)
 
void KSI_PublicationRecord_free (KSI_PublicationRecord *t)
 
int KSI_PublicationRecord_new (KSI_CTX *ctx, KSI_PublicationRecord **t)
 
int KSI_PublicationRecord_getPublishedData (const KSI_PublicationRecord *t, KSI_PublicationData **publishedData)
 
int KSI_PublicationRecord_getPublicationRefList (const KSI_PublicationRecord *t, KSI_LIST(KSI_Utf8String)**publicationRef)
 
int KSI_PublicationRecord_getRepositoryUriList (const KSI_PublicationRecord *t, KSI_LIST(KSI_Utf8String)**repUriList)
 
int KSI_PublicationRecord_setPublishedData (KSI_PublicationRecord *t, KSI_PublicationData *publishedData)
 
int KSI_PublicationRecord_setPublicationRefList (KSI_PublicationRecord *t, KSI_LIST(KSI_Utf8String)*publicationRef)
 
int KSI_PublicationRecord_setRepositoryUriList (KSI_PublicationRecord *t, KSI_LIST(KSI_Utf8String)*repUriList)
 
char * KSI_PublicationRecord_toString (const KSI_PublicationRecord *t, char *buffer, size_t buffer_len)
 
int KSI_PublicationRecord_clone (const KSI_PublicationRecord *rec, KSI_PublicationRecord **clone)
 
KSI_PublicationRecordKSI_PublicationRecord_ref (KSI_PublicationRecord *o)
 
int KSI_PublicationRecord_writeBytes (KSI_PublicationRecord *o, unsigned char *buf, size_t buf_size, size_t *buf_len, int opt)
 

Detailed Description

Publication file is a trust anchor for verifying KSI Blockchain signatures. It contains a list of public-key certificates for verifying authentication records and publications for verifying calendar hash chains. Publication file has the following components that must appear in the following order:

Typedef Documentation

typedef struct KSI_PublicationsFile_st KSI_PublicationsFile

Function Documentation

void KSI_PublicationData_free ( KSI_PublicationData t)

KSI_PublicationData

int KSI_PublicationData_fromBase32 ( KSI_CTX ctx,
const char *  publication,
KSI_PublicationData **  published_data 
)

Converts the base-32 encoded publicationstring into KSI_PublicationData object.

Parameters
[in]ctxKSI context.
[in]publicationPointer to base-32 encoded publications string.
[out]published_dataPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output memory has to be freed by the caller using KSI_PublicationData_free.
int KSI_PublicationData_fromTlv ( KSI_TLV tlv,
KSI_PublicationData **  data 
)
int KSI_PublicationData_getBaseTlv ( const KSI_PublicationData o,
KSI_TLV **  baseTlv 
)
int KSI_PublicationData_getImprint ( const KSI_PublicationData t,
KSI_DataHash **  imprint 
)
int KSI_PublicationData_getTime ( const KSI_PublicationData t,
KSI_Integer **  time 
)
int KSI_PublicationData_new ( KSI_CTX ctx,
KSI_PublicationData **  t 
)
KSI_PublicationData* KSI_PublicationData_ref ( KSI_PublicationData o)
int KSI_PublicationData_setBaseTlv ( KSI_PublicationData o,
KSI_TLV baseTlv 
)
int KSI_PublicationData_setImprint ( KSI_PublicationData t,
KSI_DataHash imprint 
)
int KSI_PublicationData_setTime ( KSI_PublicationData t,
KSI_Integer time 
)
int KSI_PublicationData_toBase32 ( const KSI_PublicationData published_data,
char **  publication 
)

Function to concert the published data into a base-32 encoded null-terminated string.

Parameters
[in]published_dataPointer to the published data object.
[out]publicationPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output memory has to be freed by the caller using KSI_free.
char* KSI_PublicationData_toString ( const KSI_PublicationData t,
char *  buffer,
size_t  buffer_len 
)
int KSI_PublicationData_toTlv ( KSI_CTX ctx,
const KSI_PublicationData data,
unsigned  tag,
int  isNonCritical,
int  isForward,
KSI_TLV **  tlv 
)
int KSI_PublicationRecord_clone ( const KSI_PublicationRecord rec,
KSI_PublicationRecord **  clone 
)
void KSI_PublicationRecord_free ( KSI_PublicationRecord t)

KSI_PublicationRecord

int KSI_PublicationRecord_getPublicationRefList ( const KSI_PublicationRecord t,
KSI_LIST(KSI_Utf8String)**  publicationRef 
)
int KSI_PublicationRecord_getPublishedData ( const KSI_PublicationRecord t,
KSI_PublicationData **  publishedData 
)
int KSI_PublicationRecord_getRepositoryUriList ( const KSI_PublicationRecord t,
KSI_LIST(KSI_Utf8String)**  repUriList 
)
int KSI_PublicationRecord_new ( KSI_CTX ctx,
KSI_PublicationRecord **  t 
)
KSI_PublicationRecord* KSI_PublicationRecord_ref ( KSI_PublicationRecord o)
int KSI_PublicationRecord_setPublicationRefList ( KSI_PublicationRecord t,
KSI_LIST(KSI_Utf8String)*  publicationRef 
)
int KSI_PublicationRecord_setPublishedData ( KSI_PublicationRecord t,
KSI_PublicationData publishedData 
)
int KSI_PublicationRecord_setRepositoryUriList ( KSI_PublicationRecord t,
KSI_LIST(KSI_Utf8String)*  repUriList 
)
char* KSI_PublicationRecord_toString ( const KSI_PublicationRecord t,
char *  buffer,
size_t  buffer_len 
)
int KSI_PublicationRecord_writeBytes ( KSI_PublicationRecord o,
unsigned char *  buf,
size_t  buf_size,
size_t *  buf_len,
int  opt 
)
  • This function serializes the # KSI_PublicationRecord object and writes the result into a pre-allocated buffer. *
    Parameters
    [in]oObject to be serialized. *
    [in]bufPointer to pre-allocated buffer. *
    [in]buf_sizeBuffer size. *
    [out]buf_lenSerialized buffer length. *
    [in]optSerialization options. *
    Returns
    status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_findPublication ( const KSI_PublicationsFile trust,
const KSI_PublicationRecord inRec,
KSI_PublicationRecord **  outRec 
)
int KSI_PublicationsFile_findPublicationByTime ( const KSI_PublicationsFile trust,
const KSI_Integer time,
KSI_PublicationRecord **  outRec 
)
void KSI_PublicationsFile_free ( KSI_PublicationsFile pubFile)

Function for freeing publicationsfile object.

Parameters
[in]pubFilePublicationsfile to be freed.
int KSI_PublicationsFile_fromFile ( KSI_CTX ctx,
const char *  fileName,
KSI_PublicationsFile **  pubFile 
)

A convenience function for loading a publications file from an actual file.

Parameters
[in]ctxKSI context.
[in]fileNamePublications file filename.
[out]pubFilePointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
It must be noted that access to metadata, supported by some file systems, is limited by the use of function fopen. Alternate Data Streams (WIndows NTFS) and Resource Forks (OS X HFS) may or may not be supported, depending on the C standard library used in the application.
int KSI_PublicationsFile_getCertConstraints ( const KSI_PublicationsFile pubFile,
KSI_CertConstraint **  certConstraints 
)

Publicationsfile certificate constraints getter method.

Parameters
[in]pubFilePublications file.
[out]certConstraintsPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getCertificates ( const KSI_PublicationsFile pubFile,
KSI_LIST(KSI_CertificateRecord)**  certificates 
)

Publicationsfile certificate list getter method.

Parameters
[in]pubFilePublications file.
[out]certificatesPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getHeader ( const KSI_PublicationsFile pubFile,
KSI_PublicationsHeader **  header 
)

Publicationsfile header getter method.

Parameters
[in]pubFilePublicationsfile object.
[out]headerPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getLatestPublication ( const KSI_PublicationsFile pubFile,
const KSI_Integer pubTime,
KSI_PublicationRecord **  pubRec 
)

Search latest publication by time. The last available publication (published after the given time pubTime) is returned via the output parameter pubRec if found, otherwise pubRec is evaluated to NULL.

Parameters
[in]pubFilePublications file.
[in]pubTimePublication time. If this is NULL, latest publication in the file is returned.
[out]pubRecPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getNearestPublication ( const KSI_PublicationsFile pubFile,
const KSI_Integer pubTime,
KSI_PublicationRecord **  pubRec 
)

Search nearest publication by time. The next available publication (published after the given time pubTime) is returned via the output parameter pubRec if found, otherwise pubRec is evaluated to NULL.

Parameters
[in]pubFilePublications file.
[in]pubTimePublication time.
[out]pubRecPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_getPKICertificateById ( const KSI_PublicationsFile pubFile,
const KSI_OctetString id,
KSI_PKICertificate **  cert 
)

PKI Certificate search function by certificate Id.

Parameters
[in]pubFilePublications file.
[in]idCertificate id.
[out]certPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getPublicationDataByPublicationString ( const KSI_PublicationsFile pubFile,
const char *  pubString,
KSI_PublicationRecord **  pubRec 
)

Search publication by publication string. The publication is returned via output parameter pubRec if found, otherwise pubRec is evaluated to NULL.

Parameters
[in]pubFilePublications file.
[in]pubStringPublication string.
[out]pubRecPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getPublicationDataByTime ( const KSI_PublicationsFile pubFile,
const KSI_Integer pubTime,
KSI_PublicationRecord **  pubRec 
)

Search publication by exact time. The publication is returned via output parameter pubRec if found, otherwise pubRec is evaluated to NULL.

Parameters
[in]pubFilePublications file.
[in]pubTimePublication time.
[out]pubRecPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getPublications ( const KSI_PublicationsFile pubFile,
KSI_LIST(KSI_PublicationRecord)**  publications 
)

Publicationsfile publications list getter method.

Parameters
[in]pubFilePublications file.
[out]publicationsPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getSignature ( const KSI_PublicationsFile pubFile,
KSI_PKISignature **  signature 
)

Publicationsfile signature getter method.

Parameters
[in]pubFilePublications file.
[out]signaturePointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output object may not be freed by the user.
int KSI_PublicationsFile_getSignedDataLength ( const KSI_PublicationsFile pubFile,
size_t *  signedDataLength 
)

Publications file signed data length getter. It describes how many first bytes of serialized publications file are or are going to be signed with PKI signature. If publications file is changed it must be serialized to get valid result

See also
KSI_PublicationsFile_serialize.
Parameters
[in]pubFilePublications file.
signedDataLength
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_new ( KSI_CTX ctx,
KSI_PublicationsFile **  pubFile 
)

This function creates an empty publications file.

Parameters
[in]ctxKSI context.
[out]pubFilePointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_parse ( KSI_CTX ctx,
const void *  raw,
size_t  raw_len,
KSI_PublicationsFile **  pubFile 
)

Function to parse the raw publicationsfile.

Parameters
[in]ctxKSI context.
[in]rawPointer to the raw publications file.
[in]raw_lenLength of the raw publications file.
[out]pubFilePointer to the receiving pointer to the publications file object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
KSI_PublicationsFile* KSI_PublicationsFile_ref ( KSI_PublicationsFile o)
int KSI_PublicationsFile_serialize ( KSI_CTX ctx,
KSI_PublicationsFile pubFile,
char **  raw,
size_t *  raw_len 
)

This function serializes the publications file object into raw data.

Parameters
[in]ctxKSI context.
[in]pubFilePublications file.
[out]rawPointer to the pointer to output buffer.
[out]raw_lenPointer to the length of the buffer variable.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_setCertConstraints ( KSI_PublicationsFile pubFile,
const KSI_CertConstraint arr 
)

Specifies file-specific constraints for verifying the publications file PKI certificate. The file-specific constraints, if set, override the default constraints in the KSI context. 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 return KSI_INVALID_ARGUMENT. File-specific constraints can be cleared with a NULL in place of arr.

Parameters
[in]pubFilePublications file for which to set the constraints.
[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 }
};
res = KSI_PublicationsFile_setCertConstraints(ctx->publicationsFile, arr);
int KSI_PublicationsFile_setCertificates ( KSI_PublicationsFile pubFile,
KSI_LIST(KSI_CertificateRecord)*  certificates 
)

Publicationsfile certificate list setter method.

Parameters
[in]pubFilePublications file.
[in]certificatesPointer to the list of certificates.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_setHeader ( KSI_PublicationsFile pubFile,
KSI_PublicationsHeader header 
)

Publicationsfile header setter method.

Parameters
[in]pubFilePublications file.
[in]headerPointer to the list of certificates.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_setPublications ( KSI_PublicationsFile pubFile,
KSI_LIST(KSI_PublicationRecord)*  publications 
)

Publicationsfile publications list setter method.

Parameters
[in]pubFilePublications file.
[in]publicationsPointer to the list of publications.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_setSignature ( KSI_PublicationsFile pubFile,
KSI_PKISignature signature 
)

Publicationsfile signature setter method.

Parameters
[in]pubFilePublications file.
[in]signaturePointer to KSI signature object.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_PublicationsFile_verify ( const KSI_PublicationsFile pubFile,
KSI_CTX ctx 
)

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

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