policy.h File Reference

#include "types.h"
#include "ksi.h"
#include "common.h"

Go to the source code of this file.

Data Structures
struct	KSI_VerificationContext_st
struct	KSI_RuleVerificationResult_st
struct	KSI_RuleVerificationResult_list_st
struct	KSI_PolicyVerificationResult_st
struct	KSI_Rule_st

Macros
#define	KSI_VERIFICATION_ERROR_CODE_LIST
#define	_(type, code, offset, cor, desc)   KSI_VER_ERR_##type##_##code = (offset + code),
#define	KSI_RuleVerificationResultList_append(lst, o)   KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))
#define	KSI_RuleVerificationResultList_remove(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))
#define	KSI_RuleVerificationResultList_indexOf(lst, o, i)   KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))
#define	KSI_RuleVerificationResultList_insertAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))
#define	KSI_RuleVerificationResultList_replaceAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))
#define	KSI_RuleVerificationResultList_elementAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))
#define	KSI_RuleVerificationResultList_length(lst)   (((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)
#define	KSI_TlvElementList_sort(lst, cmp)   KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))
#define	KSI_TlvElementList_foldl(lst, foldCtx, foldFn)   (((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)

Typedefs
typedef enum KSI_VerificationResultCode_en	KSI_VerificationResultCode
typedef enum KSI_VerificationErrorCode_en	KSI_VerificationErrorCode
typedef struct KSI_RuleVerificationResult_st	KSI_RuleVerificationResult
typedef struct KSI_RuleVerificationResult_list_st	KSI_RuleVerificationResultList
typedef enum RuleType_en	KSI_RuleType
typedef struct KSI_Rule_st	KSI_Rule

Enumerations
enum	KSI_VerificationResultCode_en { KSI_VER_RES_OK = 0x00, KSI_VER_RES_NA = 0x01, KSI_VER_RES_FAIL = 0x02 }
enum	KSI_VerificationErrorCode_en { KSI_VER_ERR_NONE = 0x00, __NOF_VER_ERRORS }
enum	RuleType_en { KSI_RULE_TYPE_BASIC, KSI_RULE_TYPE_COMPOSITE_AND, KSI_RULE_TYPE_COMPOSITE_OR }

Functions
int	KSI_RuleVerificationResultList_new (KSI_RuleVerificationResultList **list)
void	KSI_RuleVerificationResultList_free (KSI_RuleVerificationResultList *list)
const char *	KSI_VerificationErrorCode_toString (int errorCode)
int	KSI_VerificationErrorCode_fromString (const char *errCodeStr)
const char *	KSI_Policy_getErrorString (int errorCode)
int	KSI_Policy_create (KSI_CTX *ctx, const KSI_Rule *rules, const char *name, KSI_Policy **policy)
int	KSI_Policy_clone (KSI_CTX *ctx, const KSI_Policy *policy, KSI_Policy **clone)
int	KSI_Policy_setFallback (KSI_CTX *ctx, KSI_Policy *policy, const KSI_Policy *fallback)
int	KSI_SignatureVerifier_verify (const KSI_Policy *policy, KSI_VerificationContext *context, KSI_PolicyVerificationResult **result)
void	KSI_Policy_free (KSI_Policy *policy)
void	KSI_PolicyVerificationResult_free (KSI_PolicyVerificationResult *result)
void	KSI_VerificationContext_clean (KSI_VerificationContext *context)
int	KSI_VerificationContext_init (KSI_VerificationContext *context, KSI_CTX *ctx)

Variables
const KSI_Policy *	KSI_VERIFICATION_POLICY_EMPTY
const KSI_Policy *	KSI_VERIFICATION_POLICY_INTERNAL
const KSI_Policy *	KSI_VERIFICATION_POLICY_CALENDAR_BASED
const KSI_Policy *	KSI_VERIFICATION_POLICY_KEY_BASED
const KSI_Policy *	KSI_VERIFICATION_POLICY_PUBLICATIONS_FILE_BASED
const KSI_Policy *	KSI_VERIFICATION_POLICY_USER_PUBLICATION_BASED
const KSI_Policy *	KSI_VERIFICATION_POLICY_GENERAL

Macro Definition Documentation

_

#define _	(		type,
			code,
			offset,
			cor,
			desc
	)		KSI_VER_ERR_##type##_##code = (offset + code),

KSI_RuleVerificationResultList_append

#define KSI_RuleVerificationResultList_append	(		lst,
			o
	)		KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))

KSI_RuleVerificationResultList_elementAt

#define KSI_RuleVerificationResultList_elementAt	(		lst,
			pos,
			o
	)		KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))

KSI_RuleVerificationResultList_indexOf

#define KSI_RuleVerificationResultList_indexOf	(		lst,
			o,
			i
	)		KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))

KSI_RuleVerificationResultList_insertAt

#define KSI_RuleVerificationResultList_insertAt	(		lst,
			pos,
			o
	)		KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))

KSI_RuleVerificationResultList_length

#define KSI_RuleVerificationResultList_length

(

lst

)

(((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)

KSI_RuleVerificationResultList_remove

#define KSI_RuleVerificationResultList_remove	(		lst,
			pos,
			o
	)		KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))

KSI_RuleVerificationResultList_replaceAt

#define KSI_RuleVerificationResultList_replaceAt	(		lst,
			pos,
			o
	)		KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))

KSI_TlvElementList_foldl

#define KSI_TlvElementList_foldl	(		lst,
			foldCtx,
			foldFn
	)		(((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)

KSI_TlvElementList_sort

#define KSI_TlvElementList_sort	(		lst,
			cmp
	)		KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))

KSI_VERIFICATION_ERROR_CODE_LIST

#define KSI_VERIFICATION_ERROR_CODE_LIST

Helper macro containing a list of KSI signature verification error codes.

Typedef Documentation

KSI_Rule

typedef struct KSI_Rule_st KSI_Rule

KSI_RuleType

typedef enum RuleType_en KSI_RuleType

KSI_RuleVerificationResult

typedef struct KSI_RuleVerificationResult_st KSI_RuleVerificationResult

KSI_RuleVerificationResultList

typedef struct KSI_RuleVerificationResult_list_st KSI_RuleVerificationResultList

KSI_VerificationErrorCode

typedef enum KSI_VerificationErrorCode_en KSI_VerificationErrorCode

Enumeration of all KSI policy (KSI_Policy) verification error codes.

KSI_VerificationResultCode

typedef enum KSI_VerificationResultCode_en KSI_VerificationResultCode

Enumeration of all KSI policy (KSI_Policy) verification result codes.

Enumeration Type Documentation

KSI_VerificationErrorCode_en

enum KSI_VerificationErrorCode_en

Enumeration of all KSI policy (KSI_Policy) verification error codes.

Enumerator
KSI_VER_ERR_NONE	No error.
__NOF_VER_ERRORS

KSI_VerificationResultCode_en

enum KSI_VerificationResultCode_en

Enumeration of all KSI policy (KSI_Policy) verification result codes.

Enumerator
KSI_VER_RES_OK	Verification succeeded, which means there's a way to prove the correctness of the signature.
KSI_VER_RES_NA	Verification not possible, which means there is not enough data to prove or disprove the correctness of the signature.
KSI_VER_RES_FAIL	Verification failed, which means the signature is definitely invalid or the document does not match with the signature.

RuleType_en

enum RuleType_en

Enumerator
KSI_RULE_TYPE_BASIC	Basic rule type means that the rule pointer in KSI_Rule is a pointer to a verifying function. If the rule type is KSI_RULE_TYPE_BASIC, it calls the verifying function and examines the verification result of this function. If the function returns KSI_OK and verification result is KSI_VER_RES_OK, it continues with the next rule in the array and does so until it encounters the final empty rule. In this case the verification is successful. If at some point any of the functions does not return KSI_OK or the verification result is not KSI_VER_RES_OK, the verification fails and no more rules are processed.
KSI_RULE_TYPE_COMPOSITE_AND	Composite rule type means that the rule pointer in KSI_Rule is not a function pointer (as was the case with the basic rule type), but instead a pointer to another array of rules. The array of rules can contain both basic and composite rules, meaning that composite rules can be nested. The composite rule is also verified in a linear fashion until a rule fails, or until all rules including the last one are successful. AND-type rule result must be successful for the verification to continue. If an AND-type rule fails, the whole rule array of which it is part of, fails as well (no further rules are verified).
KSI_RULE_TYPE_COMPOSITE_OR	Composite rule type means that the rule pointer in KSI_Rule is not a function pointer (as was the case with the basic rule type), but instead a pointer to another array of rules. The array of rules can contain both basic and composite rules, meaning that composite rules can be nested. The composite rule is also verified in a linear fashion until a rule fails, or until all rules including the last one are successful. If an OR-type rule is successfully verified, further rules in the rule array are skipped and the whole rule of which the OR-type rule is part of, is considered successfully verified.

Function Documentation

KSI_Policy_clone()

int KSI_Policy_clone	(	KSI_CTX *	ctx,
		const KSI_Policy *	policy,
		KSI_Policy **	clone
	)

Clones a predefined KSI_Policy, allowing the user to change the default fallback policy later. User gets ownership of the cloned policy and is responsible for freeing the policy.

Parameters

[in]	ctx	KSI context.
[in]	policy	Policy to be cloned.
[out]	clone	Pointer to the receiving pointer.

Returns

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

See also

KSI_Policy_setFallback, KSI_SignatureVerifier_verify, KSI_Policy_free

KSI_Policy_create()

int KSI_Policy_create	(	KSI_CTX *	ctx,
		const KSI_Rule *	rules,
		const char *	name,
		KSI_Policy **	policy
	)

Creates a policy based on user defined rules. User gets ownership of the policy and is responsible for freeing the policy later with KSI_Policy_free. As the policy owner, the user is free to set a fallback policy with KSI_Policy_setFallback.

Parameters

[in]	ctx	KSI context.
[in]	rules	Pointer to user defined rules to be assigned to the policy.
[in]	name	Name to be given to the policy.
[out]	policy	Pointer to the receiving pointer.

Returns

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

See also

KSI_Policy_free, KSI_SignatureVerifier_verify, KSI_Policy_setFallback

KSI_Policy_free()

void KSI_Policy_free

(

KSI_Policy *

policy

)

Frees a user created or cloned KSI_Policy object. Predefined policies cannot be freed. The function does not free any potential fallback policy objects which the user must free separately.

Parameters

[in]

policy

Returns

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

See also

KSI_Policy_create, KSI_Policy_clone

KSI_Policy_getErrorString()

const char* KSI_Policy_getErrorString

(

int

errorCode

)

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

Parameters

[in]

errorCode

KSI_VerificationErrorCode value.

Returns

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

KSI_Policy_setFallback()

int KSI_Policy_setFallback	(	KSI_CTX *	ctx,
		KSI_Policy *	policy,
		const KSI_Policy *	fallback
	)

Sets a fallback policy for a primary policy. The primary policy must be owned by the user, so it can be either a user created or cloned policy, but not a predefined policy.

Parameters

[in]	ctx	KSI context.
[in]	policy	Primary policy to be secured with a fallback policy.
[in]	fallback	Fallback policy.

Returns

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

See also

KSI_Policy_create, KSI_Policy_clone, KSI_SignatureVerifier_verify, KSI_Policy_free

KSI_PolicyVerificationResult_free()

void KSI_PolicyVerificationResult_free

(

KSI_PolicyVerificationResult *

result

)

Frees the verification result object.

Parameters

[in]

result

List of verification results to be freed.

Returns

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

See also

KSI_SignatureVerifier_verify

KSI_RuleVerificationResultList_free()

void KSI_RuleVerificationResultList_free

(

KSI_RuleVerificationResultList *

list

)

KSI_RuleVerificationResultList_new()

int KSI_RuleVerificationResultList_new

(

KSI_RuleVerificationResultList **

list

)

KSI_SignatureVerifier_verify()

int KSI_SignatureVerifier_verify	(	const KSI_Policy *	policy,
		KSI_VerificationContext *	context,
		KSI_PolicyVerificationResult **	result
	)

Verifies a KSI signature (provided in context) according to specified policy. If the verification fails with KSI_VER_RES_NA or KSI_VER_RES_FAIL and a fallback policy has been set with KSI_Policy_setFallback, the verification continues according to the fallback policy. A list of verification results is created into result, containing the result and error codes for the primary policy and potential fallback policies. The user is responsible for freeing the result object with KSI_PolicyVerificationResult_free.

Parameters

[in]	policy	Policy to be verified.
[in]	context	Context for verifying the policy.
[out]	result	List of verification results

Returns

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

See also

KSI_Policy_setFallback, KSI_PolicyVerificationResult_free

KSI_VerificationContext_clean()

void KSI_VerificationContext_clean

(

KSI_VerificationContext *

context

)

Frees the temporary data in the context object.

Parameters

[in]

context

Verification context to be cleaned.

Returns

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

See also

KSI_VerificationContext_init

KSI_VerificationContext_init()

int KSI_VerificationContext_init	(	KSI_VerificationContext *	context,
		KSI_CTX *	ctx
	)

Initializes the context with default values.

Parameters

[in]	context	The verification context.
[in]	ctx	The KSI context.

Returns

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

KSI_VerificationErrorCode_fromString()

int KSI_VerificationErrorCode_fromString

(

const char *

errCodeStr

)

Get KSI_VerificationErrorCode from its string representation.

Parameters

[in]

errCodeStr

C string.

Returns

KSI_VerificationErrorCode value. If not found KSI_VER_ERR_NONE is returned.

KSI_VerificationErrorCode_toString()

const char* KSI_VerificationErrorCode_toString

(

int

errorCode

)

Get KSI_VerificationErrorCode string representation.

Parameters

[in]

errorCode

KSI_VerificationErrorCode value.

Returns

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

Variable Documentation

KSI_VERIFICATION_POLICY_CALENDAR_BASED

const KSI_Policy* KSI_VERIFICATION_POLICY_CALENDAR_BASED

KSI_VERIFICATION_POLICY_EMPTY

const KSI_Policy* KSI_VERIFICATION_POLICY_EMPTY

KSI_VERIFICATION_POLICY_GENERAL

const KSI_Policy* KSI_VERIFICATION_POLICY_GENERAL

KSI_VERIFICATION_POLICY_INTERNAL

const KSI_Policy* KSI_VERIFICATION_POLICY_INTERNAL

KSI_VERIFICATION_POLICY_KEY_BASED

const KSI_Policy* KSI_VERIFICATION_POLICY_KEY_BASED

KSI_VERIFICATION_POLICY_PUBLICATIONS_FILE_BASED

const KSI_Policy* KSI_VERIFICATION_POLICY_PUBLICATIONS_FILE_BASED

KSI_VERIFICATION_POLICY_USER_PUBLICATION_BASED

const KSI_Policy* KSI_VERIFICATION_POLICY_USER_PUBLICATION_BASED