pdu

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 26, 2020 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package pdu defines the KSI data structures and provides their manipulation methods.

Index

Constants

View Source 
const (
	// TreeMaxLevel is the maximum height of a tree.
	TreeMaxLevel byte = 0xff

	// MaxSize is the maximum size in bytes of a PDU.
	MaxSize = 0xffff + 4
)

Variables

This section is empty.

Functions

func LevelAdd 

func LevelAdd(l, r byte) (byte, error)

LevelAdd is aggregation chain level correction calculation strategy for summing provided values. The sum of the value must not exceed maximum tree level.

func LevelSubtract 

func LevelSubtract(l, r byte) (byte, error)

LevelSubtract is aggregation chain level correction calculation strategy for subtracting the value r from l. Value l must be greater than r, otherwise an error is returned.

Types

type AggrAck 

type AggrAck struct {
	// contains filtered or unexported fields
}

AggrAck is a client that can send acknowledgment requests to a server to verify if the server is reachable, and to estimate network latency for tuning its own aggregation schedule. The client sends a request message where the payload contains the 'aggregator acknowledgment request' record, optionally containing the time when client sent the request (according to client's local clock) in the 'request time' field. The server should respond immediately (without waiting for the end of its aggregation round) with an 'aggregator acknowledgment' message where all applicable fields are populated as follows:

  • 'request time': the same value as in the corresponding client request, if present there;
  • 'receipt time': the time when the request was received (according to server's local clock). If an aggregation request was received in the same PDU as the acknowledgment request, the 'request time' metadata field of the generated aggregation hash chain will have the same value as the 'receipt time' of the acknowledgment;
  • 'acknowledgment time': the time when the acknowledgment was generated (according to server's local clock). Present only if it substantially differs from 'receipt time' (added at the discretion of the server's implementation);
  • 'aggregation delay': the time from receiving the client's request to the end of the server's current aggregation round in milliseconds;
  • 'aggregation period': duration of server's aggregation round in milliseconds;
  • 'aggregation drift': the drift of the server's aggregation schedule in milliseconds. Normally the server would start a new aggregation round every time the number of milliseconds since 1970-01-01T00:00:00Z is evenly divisible by 'aggregation period'. To compensate for network latency and better align its aggregation schedule with its parents, the server instead starts a new round when the division yields 'aggregation drift' as the remainder.

type AggrChainInit 

type AggrChainInit func(*aggregationChainBuilder) error

AggrChainInit is initializer for AggregationChainBuilder.

func BuildFromAggregationChain 

func BuildFromAggregationChain(aggrChain *AggregationChain) AggrChainInit

BuildFromAggregationChain will initialize AggregationChainBuilder with specified AggregationChain. Builder operations will not affect original input aggregation hash chain.

func BuildFromImprint 

func BuildFromImprint(aggrAlgo hash.Algorithm, inputHash hash.Imprint) AggrChainInit

BuildFromImprint will initialize AggregationChainBuilder with aggregation hash algorithm and input hash.

type AggrReq 

type AggrReq struct {
	// contains filtered or unexported fields
}

AggrReq is an aggregation request message containing following data fields:

  • 'request identifier': a number used to establish a relation between the request and the corresponding responses;
  • 'request hash': either a hash value of the data to be signed or the root hash value of the client's aggregation tree;
  • 'request level': the level value of the aggregation tree node from which the 'request hash' comes, or absent if 'request hash' is a direct hash of client data (not an aggregation result).

func (*AggrReq) RequestHash 

func (r *AggrReq) RequestHash() (hash.Imprint, error)

RequestHash returns aggregation request document hash. In case the request hash is missing, an error is returned.

func (*AggrReq) RequestID 

func (r *AggrReq) RequestID() (uint64, error)

RequestID returns aggregation request ID.

func (*AggrReq) RequestLevel 

func (r *AggrReq) RequestLevel() (byte, error)

RequestLevel returns aggregation request input hash level. In case the aggregation request is missing, 0 is returned.

type AggrResp 

type AggrResp struct {
	// contains filtered or unexported fields
}

AggrResp is a server's reaction to an aggregation request message. There may be several responses associated with an aggregation request. The responses can be matched to a request using the 'request identifier' field. An aggregator response message has the following data fields:

  • 'request identifier': normally the same value as in the corresponding client request, with the following exceptions:
  • if the request identifier was missing in the client request, the server responds with an INVALID PAYLOAD error with the request identifier set to 0. Clients should avoid using 0 as a request identifier to prevent confusion with this placeholder value;
  • if the request identifier in the client request was too long, it is truncated to contain as many least significant bits as the server can handle;
  • handling of simultaneous requests with equal identifiers is implementation-defined. Possible actions include ignoring the condition and responding to all requests, treating the requests as duplicates and only responding to one of them, etc;
  • 'status': a status code, where 0 means success and non-zero value is an error code;
  • 'error message': an optional free-form error message;
  • 'KSI item': a part of a KSI signature. There may be several KSI items in one aggregator response.

func (*AggrResp) AggregationChainList 

func (r *AggrResp) AggregationChainList() ([]*AggregationChain, error)

AggregationChainList returns aggregation chain list. If not present, an error is returned.

func (*AggrResp) CalendarAuthRec 

func (r *AggrResp) CalendarAuthRec() (*CalendarAuthRec, error)

CalendarAuthRec returns calendar authentication record. If not present, nil is returned.

func (*AggrResp) CalendarChain 

func (r *AggrResp) CalendarChain() (*CalendarChain, error)

CalendarChain returns calendar hash chain. If not present, nil is returned.

func (*AggrResp) Err 

func (r *AggrResp) Err() error

Err returns aggregation response error if present, otherwise nil is returned.

func (*AggrResp) ErrorMsg 

func (r *AggrResp) ErrorMsg() (string, error)

ErrorMsg returns aggregation response error message. See also (AggrResp).Status().

func (*AggrResp) PublicationRec 

func (r *AggrResp) PublicationRec() (*PublicationRec, error)

PublicationRec returns publication record. If not present, nil is returned.

func (*AggrResp) RFC3161 

func (r *AggrResp) RFC3161() (*RFC3161, error)

RFC3161 returns RFC3161 record. If not present, nil is returned.

func (*AggrResp) RequestID 

func (r *AggrResp) RequestID() (uint64, error)

RequestID returns aggregation response request identifier.

func (*AggrResp) Status 

func (r *AggrResp) Status() (uint64, error)

Status returns aggregation response status code. In case the status is not 0, call (AggrResp).ErrorMsg() for description message.

type AggregationChain 

type AggregationChain struct {
	// contains filtered or unexported fields
}

AggregationChain is the aggregation hash chain structure consisting of the following fields:

  • 'aggregation time': the completion time of the aggregation round from which the hash chain starts;
  • 'chain index': a location pointer. Bit-strings that indicate the location of the component in a hash tree. The bits represent the path from the root of the tree to the location of a hash value as a sequence of moves from a parent node in the tree to either the left or right child (bit values 0 and 1, respectively);
  • 'input hash' and an optional 'input data': the input for the computation specified by the hash chain;
  • 'aggregation algorithm': the one-octet identifier of the hash function used to compute the output hash values of the link structures;
  • 'chain links': a sequence of left and right 'chain link' structures.

func (*AggregationChain) Aggregate 

func (c *AggregationChain) Aggregate(startLevel byte) (hash.Imprint, byte, error)

Aggregate aggregates the aggregation hash chain. The 'startLevel' parameter is the level of the first chain link. Returns the resulting root hash and aggregation chain height.

func (*AggregationChain) AggregationAlgo 

func (c *AggregationChain) AggregationAlgo() (hash.Algorithm, error)

AggregationAlgo returns aggregation chain aggregation algorithm. If algorithm is not present, an error is returned.

func (*AggregationChain) AggregationTime 

func (c *AggregationChain) AggregationTime() (time.Time, error)

AggregationTime returns aggregation chain aggregation time. If time is not present, an error is returned.

func (*AggregationChain) CalculateShape 

func (c *AggregationChain) CalculateShape() (uint64, error)

CalculateShape represents the shape of the aggregation chain as a bit-field. The bits represent the path from the root of the tree to the location of a hash value as a sequence of moves from a parent node in the tree to either the left or right child (bit values 0 and 1, respectively). Each bit sequence starts with a 1-bit to make sure no left most 0-bits are lost.

func (*AggregationChain) ChainIndex 

func (c *AggregationChain) ChainIndex() ([]uint64, error)

ChainIndex returns aggregation chain index. If chain index is not present, an error is returned. 

func (c *AggregationChain) ChainLinks() ([]*ChainLink, error)

ChainLinks returns aggregation chain links. If links are not present, an error is returned.

func (*AggregationChain) Identity 

func (c *AggregationChain) Identity() (HashChainLinkIdentityList, error)

Identity returns aggregation hash chain identity. The returned list consists of individual hash chain link identities. The identities in the list are ordered - the higher-link identity is before lower-link identity.

func (*AggregationChain) InputData 

func (c *AggregationChain) InputData() ([]byte, error)

InputData returns aggregation chain input data. If data is not present, nil is returned.

func (*AggregationChain) InputHash 

func (c *AggregationChain) InputHash() (hash.Imprint, error)

InputHash returns aggregation chain input hash. If hash is not present, an error is returned.

func (*AggregationChain) String 

func (c *AggregationChain) String() string

String implements the Stringer interface. Returns an empty string in case of an error.

type AggregationChainBuilder 

type AggregationChainBuilder struct {
	// contains filtered or unexported fields
}

AggregationChainBuilder provides the ability for constructing aggregation chains.

func NewAggregationChainBuilder 

func NewAggregationChainBuilder(init AggrChainInit) (*AggregationChainBuilder, error)

NewAggregationChainBuilder returns a new builder instance. Use the init option for setting the builder initial state. 

func (b *AggregationChainBuilder) AddChainLink(isLeft bool, lvlCorrection byte, siblingData LinkSiblingDataSetter) error

AddChainLink appends a new chain link. The sibling data can be applied via functional setters (see LinkSiblingMetaData, LinkSiblingHash)

func (*AggregationChainBuilder) AdjustLevelCorrection 

func (b *AggregationChainBuilder) AdjustLevelCorrection(calc LevelCalculator, lvl byte) error

AdjustLevelCorrection applies newly calculated level correction value to the aggregation chain first chain link. The calculation of the new level correction value is performed based on the provided calculation strategy calc.

func (*AggregationChainBuilder) Build 

func (b *AggregationChainBuilder) Build() (*AggregationChain, error)

Build constructs and returns the resulting aggregation hash chain. The receiver's internal state is reset after this method returns AggregationChain.

func (*AggregationChainBuilder) PrependChainIndex 

func (b *AggregationChainBuilder) PrependChainIndex(i []uint64) error

PrependChainIndex adds a new index to the front of the aggregation chain index.

func (*AggregationChainBuilder) SetAggregationTime 

func (b *AggregationChainBuilder) SetAggregationTime(t time.Time) error

SetAggregationTime is setter for aggregation chain time.

type AggregationChainList 

type AggregationChainList []*AggregationChain

AggregationChainList is alias type for []*AggregationChain.

func (AggregationChainList) Aggregate 

func (l AggregationChainList) Aggregate(lvl byte) (hash.Imprint, error)

Aggregate aggregates the aggregation hash chain list and returns the result root hash. The aggregation result is the input hash of the calendar hash chain (CalendarChain). Note that the aggregation chain must be sequential, meaning that the root hash of previous aggregation chain must match the input hash of the following aggregation chain, otherwise an error is returned.

func (AggregationChainList) Identity 

func (l AggregationChainList) Identity() (HashChainLinkIdentityList, error)

Identity returns a list of the identities present in all aggregation hash chains.

func (AggregationChainList) Len 

func (l AggregationChainList) Len() int

Len implements sort.(Interface).

func (AggregationChainList) Less 

func (l AggregationChainList) Less(i, j int) bool

Less implements sort.(Interface).

func (AggregationChainList) Swap 

func (l AggregationChainList) Swap(i, j int)

Swap implements sort.(Interface).

type AggregationReqSetting 

type AggregationReqSetting func(*aggregatorReq) error

AggregationReqSetting is a functional option setter for various aggregation request settings.

func AggrReqSetRequestID 

func AggrReqSetRequestID(id uint64) AggregationReqSetting

AggrReqSetRequestID is aggregation requests' configuration method for setting request ID. Should be used with care.

func AggrReqSetRequestLevel 

func AggrReqSetRequestLevel(level byte) AggregationReqSetting

AggrReqSetRequestLevel is aggregation requests' configuration method for setting input hash input level.

type AggregatorPdu 

type AggregatorPdu struct {
	// contains filtered or unexported fields
}

AggregatorPdu is the KSI Aggregator Protocol (KSIAP) used to deliver client requests to the server and KSI items (and also configuration parameters) from the server to the client. Different message types are used for upstream (child to parent) and downstream (parent to child) traffic.

type AggregatorReq 

type AggregatorReq struct {
	// contains filtered or unexported fields
}

AggregatorReq is used to deliver client requests to the server.

func NewAggregationReq 

func NewAggregationReq(requestHash hash.Imprint, settings ...AggregationReqSetting) (*AggregatorReq, error)

NewAggregationReq constructs a new aggregation request wrapped into the AggregatorReq container. Optionally additional configuration settings can be added via settings parameter.

func NewAggregatorConfigReq 

func NewAggregatorConfigReq() (*AggregatorReq, error)

NewAggregatorConfigReq constructs a new aggregator configuration request.

func (*AggregatorReq) AggregationReq 

func (r *AggregatorReq) AggregationReq() (*AggrReq, error)

AggregationReq returns aggregation request component from the receiver container. In case the aggregation request is missing, nil is returned.

func (*AggregatorReq) Clone 

func (r *AggregatorReq) Clone() (*AggregatorReq, error)

Clone returns a deep copy of the origin, or nil in case of an error. Note that only request part of the AggregatorReq will be cloned, meaning header and HMAC are ignored.

func (*AggregatorReq) Config 

func (r *AggregatorReq) Config() (*Config, error)

Config returns request config instance. In case the configuration is not part of the request, nil is returned.

func (*AggregatorReq) Context 

func (r *AggregatorReq) Context() context.Context

Context returns the request's context.

The returned context is always non-nil, it defaults to the background context.

func (*AggregatorReq) Encode 

func (r *AggregatorReq) Encode() ([]byte, error)

Encode serializes the aggregator request into TLV binary representation.

func (*AggregatorReq) HMAC 

func (r *AggregatorReq) HMAC() (hash.Imprint, error)

HMAC returns the request message authentication code, or nil if not present.

func (*AggregatorReq) Header 

func (r *AggregatorReq) Header() (*Header, error)

Header returns aggregator request header.

func (*AggregatorReq) SetHeader 

func (r *AggregatorReq) SetHeader(hdr *Header) error

SetHeader is request header setter.

func (*AggregatorReq) UpdateHMAC 

func (r *AggregatorReq) UpdateHMAC(alg hash.Algorithm, key string) error

UpdateHMAC updates the request HMAC. The MAC is computed over all PDU message bytes up to (but excluding) the hash value within the imprint in the MAC field:

  1. the TLV header of the PDU element itself;
  2. the complete header element (both the TLV header and the value of the element);
  3. the complete payload elements in the order in which they appear in the PDU;
  4. the TLV header of the MAC element;
  5. the hash algorithm identifier part of the imprint representing the MAC value.

func (*AggregatorReq) UpdateRequestID 

func (r *AggregatorReq) UpdateRequestID(id uint64) error

UpdateRequestID updates aggregation request ID in case it is not set explicitly. Note that if the aggregator request does not contain aggregation request component, no operation is performed.

func (*AggregatorReq) WithContext 

func (r *AggregatorReq) WithContext(ctx context.Context) *AggregatorReq

WithContext returns the original r with its context changed to ctx. In case of an error, nil is returned.

type AggregatorResp 

type AggregatorResp struct {
	// contains filtered or unexported fields
}

AggregatorResp used to deliver KSI items (and also configuration parameters) from the server to the client, as reaction to an aggregator request.

func (*AggregatorResp) AggregationResp 

func (r *AggregatorResp) AggregationResp() (*AggrResp, error)

AggregationResp returns aggregation response. Note that if the aggregator response does not contain aggregation response, nil is returned.

func (*AggregatorResp) Clone 

func (r *AggregatorResp) Clone() (*AggregatorResp, error)

Clone returns a deep copy of the origin, or nil in case of an error. Note that only response part of the AggregatorResp will be cloned, meaning header and HMAC are ignored.

func (*AggregatorResp) Config 

func (r *AggregatorResp) Config() (*Config, error)

Config returns configuration response, or nil if not present.

func (*AggregatorResp) Decode 

func (r *AggregatorResp) Decode(raw []byte) error

Decode de-serializes the raw TLV into the receiver aggregator response. Note that the AggregatorResp has to be created prior to calling this method.

func (*AggregatorResp) Encode 

func (r *AggregatorResp) Encode() ([]byte, error)

Encode returns the serialized aggregator response.

func (*AggregatorResp) Err 

func (r *AggregatorResp) Err() error

Err returns the response error if present, otherwise nil is returned.

func (*AggregatorResp) SetConfig 

func (r *AggregatorResp) SetConfig(c *Config) error

SetConfig sets new configuration instance into the response container.

func (*AggregatorResp) Verify 

func (r *AggregatorResp) Verify(alg hash.Algorithm, key string) error

Verify verifies the aggregator response consistency. Returns an error in following cases:

  • contains a service response error;
  • the response is missing mandatory element;
  • HMAC calculation result does not match with the response. The HMAC is calculated based on the provided hash function ('alg') and the secret cryptographic key ('key').

type CalendarAuthRec 

type CalendarAuthRec struct {
	// contains filtered or unexported fields
}

CalendarAuthRec contains the following fields:

  • 'published data': consists of a 'publication time' and a 'published hash';
  • 'signature data': an authentication record for a calendar hash chain is created in the following way: 1. The 'publication time' of the calendar hash chain is stored as the 'publication time' field of the 'published data' structure. 2. The output hash of the calendar hash chain is computed and stored as the 'published hash' field of the 'published data' structure. 3. The whole 'published data' structure (including the TLV header) is signed and the result is saved as the 'signature data' structure.

func (*CalendarAuthRec) PublicationData 

func (c *CalendarAuthRec) PublicationData() (*PublicationData, error)

PublicationData returns the published data, or error if not present.

func (*CalendarAuthRec) SignatureData 

func (c *CalendarAuthRec) SignatureData() (*SignatureData, error)

SignatureData returns the signature data of the published data, or error if not present.

type CalendarChain 

type CalendarChain struct {
	// contains filtered or unexported fields
}

CalendarChain is calendar hash chain structure consisting of:

  • pubTime: publication time (time of the calendar root hash);
  • aggrTime: aggregation time (optional, default value pubTime);
  • input hash: the input for the computation specified by the hash chain;
  • chainLinks: a sequence of 'left link' and 'right link' structures.

func (*CalendarChain) Aggregate 

func (c *CalendarChain) Aggregate() (hash.Imprint, error)

Aggregate aggregates the calendar hash chain. Returns the resulting root hash.

func (*CalendarChain) AggregationTime 

func (c *CalendarChain) AggregationTime() (time.Time, error)

AggregationTime returns calendar hash chain aggregation time, or 0 if not present (see (time.(Time).IsZero())).

func (*CalendarChain) CalculateAggregationTime 

func (c *CalendarChain) CalculateAggregationTime() (time.Time, error)

CalculateAggregationTime returns aggregation time calculated based on the shape of the calendar hash chain. 

func (c *CalendarChain) ChainLinks() ([]*ChainLink, error)

ChainLinks returns calendar hash chain links. If not present, an error is returned.

func (*CalendarChain) InputHash 

func (c *CalendarChain) InputHash() (hash.Imprint, error)

InputHash returns calendar hash chain input hash. If not present, an error is returned.

func (*CalendarChain) PublicationTime 

func (c *CalendarChain) PublicationTime() (time.Time, error)

PublicationTime returns calendar hash chain publication time. If not present, an error is returned.

func (*CalendarChain) RightLinkMatch 

func (c *CalendarChain) RightLinkMatch(l *CalendarChain) error

RightLinkMatch verifies that the right links are pairwise equal.

func (*CalendarChain) String 

func (c *CalendarChain) String() string

String implements fmt.(Stringer) interface.

func (*CalendarChain) VerifyCompatibility 

func (c *CalendarChain) VerifyCompatibility(with *CalendarChain) error

VerifyCompatibility checks if the two calendar hash chains are compatible with each other. The function performs the following checks:

  • The input hashes match.
  • The aggregation times match. Note that the publication times may differ.
  • The right links from both calendar hash chains are pairwise equal.

The publication time from the two aggregation hash chains and also the left-links from both of the chains can differ.

type CertificateRecord 

type CertificateRecord struct {
	// contains filtered or unexported fields
}

CertificateRecord is a representation of a public key certificate for verifying authentication records, consisting of 'certificate identifier' and 'certificate value'.

func (*CertificateRecord) Cert 

func (c *CertificateRecord) Cert() ([]byte, error)

Cert returns x509 certificate, or error if not present.

func (*CertificateRecord) CertID 

func (c *CertificateRecord) CertID() ([]byte, error)

CertID returns certificate ID, or error if not present.

func (*CertificateRecord) IsValid 

func (c *CertificateRecord) IsValid(at time.Time) (bool, error)

IsValid verifies that the certificate is valid at the given time.

func (*CertificateRecord) VerifySigType 

func (c *CertificateRecord) VerifySigType(sigType string) error

VerifySigType compares the signature type OID string representation to the one included in the x509 certificate. As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key. See also asn1.(ObjectIdentifier).String(). 

type ChainLink struct {
	// contains filtered or unexported fields
}

ChainLink is hash chain link.

For several reasons, each node in the aggregation tree includes a level indicator that must be strictly larger than the indicator in either child node. In most cases, the value in the parent node is one more than the values in the child nodes and can then be computed from the value of either child (one of which precedes the parent in the hash chain). However, if the aggregation tree is not perfectly balanced, the values in the child nodes may differ and, in this case, the level indicator must increase by more than one on the step from one child to the parent. The optional 'level correction' is used in the hash chain to indicate the correction amount (additional increase) in this case. Sibling data must consist of one, and only one, of the following three fields:

  • 'sibling hash': an 'imprint' representing a hash value from the sibling node in the tree;
  • 'metadata': a sub-structure that provides the ability to incorporate client identity and other information about the request into the hash chain;
  • 'legacy client identifier': a client identifier converted from a legacy signature.

In case of calendar hash chain, each link field contains only a hash value from the calendar hash tree.

func (*ChainLink) FromTlv 

func (l *ChainLink) FromTlv(objTlv *tlv.Tlv) error

FromTlv populates the receiver chain link with the data from TLV.

func (*ChainLink) Identity 

func (l *ChainLink) Identity() (*HashChainLinkIdentity, error)

Identity return link identity, or nil if not present.

func (*ChainLink) IsLeft 

func (l *ChainLink) IsLeft() (bool, error)

IsLeft returns the orientation of the chain link.

func (*ChainLink) LegacyID 

func (l *ChainLink) LegacyID() (*LegacyID, error)

LegacyID returns legacy ID value, or nil if not present.

func (*ChainLink) LevelCorrection 

func (l *ChainLink) LevelCorrection() (uint64, error)

LevelCorrection returns chain link level correction value.

func (*ChainLink) MetaData 

func (l *ChainLink) MetaData() (*MetaData, error)

MetaData returns the metadata value, or nil if not present. See also (ChainLink).SiblingHash

func (*ChainLink) SiblingHash 

func (l *ChainLink) SiblingHash() (hash.Imprint, error)

SiblingHash returns the sibling link hash value, or nil if not present. See also (ChainLink).MetaData

func (*ChainLink) String 

func (l *ChainLink) String() string

String implement Stringer interface. Returns an empty string in case of an error.

func (*ChainLink) ToTlv 

func (l *ChainLink) ToTlv(enc *tlv.Encoder) (*tlv.Tlv, error)

ToTlv returns a TLV object constructed based on the receiver link data. 

type ChainLinkList []*ChainLink

ChainLinkList is alias for '[]*ChainLink'.

func (ChainLinkList) String 

func (l ChainLinkList) String() string

String implements Stringer interface. Returns an empty string in case of an error.

type Config 

type Config struct {
	// contains filtered or unexported fields
}

Config is service configuration. In order to start using KSIAP, a client must have the following information:

  • parent server URI;
  • its own client identifier;
  • an (HMAC) authentication key.

Using this minimal information, the client can obtain additional configuration data by sending the 'configuration request' within a protocol PDU. The server responds with a 'configuration' message with all applicable fields populated as follows:

  • 'maximal level': maximum level value that the nodes in the client's aggregation tree are allowed to have (relevant only in case of aggregator service);
  • 'aggregation hash algorithm': identifier of the hash function that the client is recommended to use in its aggregation trees (relevant only in case of aggregator service);
  • 'aggregation period': recommended duration of client's aggregation round in milliseconds (relevant only in case of aggregator service);
  • 'maximum requests': maximum number of requests the client is allowed to send within one period of the recommended duration;
  • 'parent URI': parent server URI. Note that there may be several parent servers listed in the configuration. Typically, these are all members of one cluster;
  • 'calendar first time': aggregation time of the oldest calendar record the extender has (relevant only in case of extender service);
  • 'calendar last time': aggregation time of the newest calendar record the extender has (relevant only in case of extender service).

The server may also send configuration messages without an explicit request from the client. These may be triggered by a change in the server's own configuration, for example.

func (*Config) AggrAlgo 

func (c *Config) AggrAlgo() (hash.Algorithm, error)

AggrAlgo returns identifier of the hash function that the client is recommended to use in its aggregation trees. Applicable for aggregation service only.

func (*Config) AggrPeriod 

func (c *Config) AggrPeriod() (uint64, error)

AggrPeriod returns recommended duration of client's aggregation round in milliseconds. Applicable for aggregation service only.

func (*Config) CalFirst 

func (c *Config) CalFirst() (uint64, error)

CalFirst returns aggregation time of the oldest calendar record the extender has. Applicable for extending service only.

func (*Config) CalLast 

func (c *Config) CalLast() (uint64, error)

CalLast returns aggregation time of the newest calendar record the extender has. Applicable for extending service only.

func (*Config) Consolidate 

func (c *Config) Consolidate(cfg *Config, limits ConfigLimits, logic ConfigConsStrategy) error

Consolidate merges the provided configuration cfg into the receiver configuration based on the provided limits and strategy.

func (*Config) MaxLevel 

func (c *Config) MaxLevel() (byte, error)

MaxLevel returns maximum level value that the nodes in the client's aggregation tree are allowed to have. Applicable for aggregation service only.

func (*Config) MaxReq 

func (c *Config) MaxReq() (uint64, error)

MaxReq returns maximum number of requests the client is allowed to send within the recommended duration. Applicable for aggregation and extending services.

func (*Config) ParentURI 

func (c *Config) ParentURI() ([]string, error)

ParentURI returns parent server URI list. Typically, these are all members of one cluster. Applicable for aggregation and extending services.

func (*Config) String 

func (c *Config) String() string

String implements fmt.(Stringer) interface.

type ConfigConsStrategy 

type ConfigConsStrategy struct {
	// MaxLevelKeepLargest: if set, the largest value is preserved.
	MaxLevelKeepLargest bool
	// AggrAlgorithm: if set to hash.SHA_NA, the latest valid value is preserved. Otherwise the applied algorithm will
	// override the value from 'cfg'.
	// Note that the applied algorithm is not verified, only the new algorithm from 'cfg' is verified (see (Algorithm).Trusted()).
	AggrAlgorithm hash.Algorithm
	// AggrPeriodKeepLargest: if set, the largest value is preserved.
	AggrPeriodKeepLargest bool
	// MaxRequestsKeepLargest: if set, the largest value is preserved.
	MaxRequestsKeepLargest bool
	// ParentUriAppend: if set, URIs from the new 'cfg' will be appended to the already present list. Otherwise only
	// latest will be preserved.
	// Note that only unique entries are kept.
	ParentUriAppend bool
	// CalFirstKeepEarliest: if set, the earliest value is preserved.
	// Note that the aggregation time of the newest calendar record can not be limited, thus all values
	// greater than CalFirstLow will be accepted. For the same reason calendar last time is not limited and the latest value
	// is preserved (values before calendar first time are discarded).
	CalFirstKeepEarliest bool
}

ConfigConsStrategy is the logic upon which configuration values are consolidated. See (Config).Consolidate().

type ConfigLimits 

type ConfigLimits struct {
	// MaxLevelLow limits the lower bound of the maximum level value.
	MaxLevelLow uint64
	// MaxLevelHigh limits the upper bound of the maximum level value.
	MaxLevelHigh uint64

	// AggrPeriodLow limits the lower bound of the recommended duration of aggregation round.
	AggrPeriodLow uint64
	// AggrPeriodHigh limits the upper bound of the recommended duration of aggregation round.
	AggrPeriodHigh uint64

	// MaxReqLow limits the lower bound of the maximum number of requests within of the recommended duration.
	MaxReqLow uint64
	// MaxReqHigh limits the upper bound of the maximum number of requests within of the recommended duration.
	MaxReqHigh uint64

	// CalFirstLow limits the aggregation time of the oldest calendar record to be accepted.
	// Note that the aggregation time of the newest calendar record can not be limited, thus all values
	// greater than CalFirstLow will be accepted.
	CalFirstLow uint64
}

ConfigLimits is used for configuration consolidation. See (Config).Consolidate().

type Error 

type Error struct {
	// contains filtered or unexported fields
}

Error is as a special case, where an error is returned in a reduced message, because the server lacks the information needed to populate at least some of the normally mandatory fields of the 'header' and 'mac' components of the full response.

type ExtReq 

type ExtReq struct {
	// contains filtered or unexported fields
}

ExtReq is an extension request message containing following data fields:

  • 'request identifier: a number used to establish a relation between the request and the corresponding responses;
  • 'aggregation time': the time of the aggregation round from which the calendar hash chain should start;
  • 'publication time': the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. Its absence means a request for a calendar hash chain from aggregation time to the most recent calendar record the server has (the 'calendar last time' field in the response and configuration messages).

func (*ExtReq) AggregationTime 

func (r *ExtReq) AggregationTime() (time.Time, error)

AggregationTime returns the time of the aggregation round from which the calendar hash chain should start.

func (*ExtReq) PublicationTime 

func (r *ExtReq) PublicationTime() (time.Time, error)

PublicationTime returns the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. If not present, 0 is returned (see time.(Time).IsZero()).

func (*ExtReq) RequestID 

func (r *ExtReq) RequestID() (uint64, error)

RequestID returns the request identifier.

type ExtResp 

type ExtResp struct {
	// contains filtered or unexported fields
}

ExtResp is server's reaction to an extension request message. The response can be matched to the request using the 'request identifier' field. An extender response message has the following data fields:

  • 'request identifier': normally the same value as in the corresponding client request, with the following exceptions:
  • if the request identifier was missing in the client request, the server responds with an INVALID PAYLOAD error with the request identifier set to 0. Clients should avoid using 0 as a request identifier to prevent confusion with this placeholder value;
  • if the request identifier in the client request was too long, it is truncated to contain as many least significant bits as the server can handle;
  • handling of simultaneous requests with equal identifiers is implementation-defined. Possible actions include ignoring the condition and responding to all requests, treating the requests as duplicates and only responding to one of them, etc;
  • 'status': a status code, where 0 means success and non-zero value is an error code;
  • 'error message': an optional free-form error message;
  • 'calendar last time': aggregation time of the newest calendar record the extender has;
  • 'calendar chain': a calendar hash chain that connects the global root hash value of the aggregation tree of the round specified in the request to the published hash value specified in the request.

func (*ExtResp) CalendarChain 

func (r *ExtResp) CalendarChain() (*CalendarChain, error)

CalendarChain returns a calendar hash chain that connects the global root hash value of the aggregation tree of the round specified in the request to the published hash value specified in the request.

func (*ExtResp) CalendarLast 

func (r *ExtResp) CalendarLast() (uint64, error)

CalendarLast returns aggregation time of the newest calendar record the extender has. If not present, 0 is returned.

func (*ExtResp) Err 

func (r *ExtResp) Err() error

Err returns extending response error if present, otherwise nil is returned.

func (*ExtResp) ErrorMsg 

func (r *ExtResp) ErrorMsg() (string, error)

ErrorMsg returns extending response error message. See also (ExtResp).Status().

func (*ExtResp) RequestID 

func (r *ExtResp) RequestID() (uint64, error)

RequestID returns extending response request identifier.

func (*ExtResp) Status 

func (r *ExtResp) Status() (uint64, error)

Status returns extending response status code. In case the status is not 0, call (ExtResp).ErrorMsg() for description message.

type ExtenderPdu 

type ExtenderPdu struct {
	// contains filtered or unexported fields
}

ExtenderPdu is the KSI Extender Protocol (KSIEP) used to deliver client requests to the server and calendar hash chains (and also configuration parameters) from the server to the client. Different message types are used for upstream (child to parent) and downstream (parent to child) traffic.

type ExtenderReq 

type ExtenderReq struct {
	// contains filtered or unexported fields
}

ExtenderReq is used to deliver client requests to the server.

func NewExtenderConfigReq 

func NewExtenderConfigReq() (*ExtenderReq, error)

NewExtenderConfigReq constructs a new aggregator configuration request.

func NewExtendingReq 

func NewExtendingReq(start time.Time, settings ...ExtendingReqSetting) (*ExtenderReq, error)

NewExtendingReq constructs a new extending request. Start parameter is the time of the aggregation round from which the calendar hash chain should start. Optionally additional configuration settings can be added via settings parameter.

func (*ExtenderReq) Clone 

func (r *ExtenderReq) Clone() (*ExtenderReq, error)

Clone returns a deep copy of the origin, or nil in case of an error. Note that only request part of the ExtenderReq will be cloned, meaning header and HMAC are ignored.

func (*ExtenderReq) Config 

func (r *ExtenderReq) Config() (*Config, error)

Config returns request config instance. Note that in case the configuration is not part of the request, nil is returned.

func (*ExtenderReq) Context 

func (r *ExtenderReq) Context() context.Context

Context returns the request's context.

The returned context is always non-nil, it defaults to the background context.

func (*ExtenderReq) Encode 

func (r *ExtenderReq) Encode() ([]byte, error)

Encode serializes the extender request into binary TLV.

func (*ExtenderReq) ExtendingReq 

func (r *ExtenderReq) ExtendingReq() (*ExtReq, error)

ExtendingReq returns extending request component from the receiver container. In case the extending request is missing, nil is returned.

func (*ExtenderReq) HMAC 

func (r *ExtenderReq) HMAC() (hash.Imprint, error)

HMAC returns the request message authentication code, or nil if not present.

func (*ExtenderReq) Header 

func (r *ExtenderReq) Header() (*Header, error)

Header returns the request message header, or nil if not present.

func (*ExtenderReq) SetHeader 

func (r *ExtenderReq) SetHeader(hdr *Header) error

SetHeader is request header setter.

func (*ExtenderReq) UpdateHMAC 

func (r *ExtenderReq) UpdateHMAC(alg hash.Algorithm, key string) error

UpdateHmac updates the request HMAC. The MAC is computed over all PDU message bytes up to (but excluding) the hash value within the imprint in the MAC field:

  1. the TLV header of the PDU element itself;
  2. the complete header element (both the TLV header and the value of the element);
  3. the complete payload elements in the order in which they appear in the PDU;
  4. the TLV header of the MAC element;
  5. the hash algorithm identifier part of the imprint representing the MAC value.

func (*ExtenderReq) UpdateRequestID 

func (r *ExtenderReq) UpdateRequestID(id uint64) error

UpdateRequestID updates extending request ID in case it is not set explicitly.

func (*ExtenderReq) WithContext 

func (r *ExtenderReq) WithContext(ctx context.Context) *ExtenderReq

WithContext returns the original r with its context changed to ctx. In case of an error, nil is returned.

type ExtenderResp 

type ExtenderResp struct {
	// contains filtered or unexported fields
}

ExtenderResp is used to deliver calendar hash chains (and also configuration parameters) from the server to the client.

func (*ExtenderResp) Clone 

func (r *ExtenderResp) Clone() (*ExtenderResp, error)

Clone returns a deep copy of the origin, or nil in case of an error. Note that only response part of the ExtenderResp will be cloned.

func (*ExtenderResp) Config 

func (r *ExtenderResp) Config() (*Config, error)

Config returns configuration response, or nil if not present.

func (*ExtenderResp) Decode 

func (r *ExtenderResp) Decode(raw []byte) error

Decode de-serializes the raw TLV into the receiver extender response. Note that the ExtenderResp has to be created prior to calling this method.

func (*ExtenderResp) Encode 

func (r *ExtenderResp) Encode() ([]byte, error)

Encode returns the serialized extender response.

func (*ExtenderResp) Err 

func (r *ExtenderResp) Err() error

Err returns the response error if present, otherwise nil is returned.

func (*ExtenderResp) ExtendingResp 

func (r *ExtenderResp) ExtendingResp() (*ExtResp, error)

ExtendingResp returns extending response. Note that if the extender response does not contain extending response, nil is returned.

func (*ExtenderResp) SetConfig 

func (r *ExtenderResp) SetConfig(c *Config) error

SetConfig sets new configuration instance into the response container.

func (*ExtenderResp) Verify 

func (r *ExtenderResp) Verify(alg hash.Algorithm, key string) error

Verify verifies the extender response consistency. Returns an error in following cases:

  • contains a service response error;
  • the response is missing mandatory element;
  • HMAC calculation result does not match with the response. The HMAC is calculated based on the provided hash function ('alg') and the secret cryptographic key ('key').

type ExtendingReqSetting 

type ExtendingReqSetting func(*extenderReq) error

ExtendingReqSetting is functional option setter for extending request.

func ExtReqSetPubTime 

func ExtReqSetPubTime(end time.Time) ExtendingReqSetting

ExtReqSetPubTime sets the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. Its absence means a request for a calendar hash chain from aggregation time to the most recent calendar record the server has (the 'calendar last time' field in the response and configuration messages).

func ExtReqSetRequestID 

func ExtReqSetRequestID(id uint64) ExtendingReqSetting

ExtReqSetRequestID is aggregation request configuration method for setting request ID, a number used to establish a relation between the request and the corresponding responses. Should be used with care.

type HashChainLinkIdentity 

type HashChainLinkIdentity struct {
	// contains filtered or unexported fields
}

HashChainLinkIdentity is hash chain link identity.

func (*HashChainLinkIdentity) ClientID 

func (id *HashChainLinkIdentity) ClientID() (string, error)

ClientID returns (human-readable) textual representation of metadata client identity, or legacy ID.

func (*HashChainLinkIdentity) MachineID 

func (id *HashChainLinkIdentity) MachineID() (string, error)

MachineID returns a (human-readable) identifier of the machine that requested the link structure (unique at least within the cluster that shares a 'client identifier'). If not present, an empty string is returned.

func (*HashChainLinkIdentity) RequestTime 

func (id *HashChainLinkIdentity) RequestTime() (uint64, error)

RequestTime returns the time when the server received the request from the client, recorded as precisely as the server's clock allows. This is another option for ordering of requests processed by the same machine within one aggregation round. If not present, 0 is returned.

func (*HashChainLinkIdentity) SequenceNr 

func (id *HashChainLinkIdentity) SequenceNr() (uint64, error)

SequenceNr returns a local sequence number of a request assigned by the machine that created the link. Sequence numbers enable determination of the temporal order of requests processed by the same machine even within one aggregation round. If not present, 0 is returned.

func (*HashChainLinkIdentity) String 

func (id *HashChainLinkIdentity) String() string

String implements fmt.(Stringer) interface.

func (*HashChainLinkIdentity) Type 

func (id *HashChainLinkIdentity) Type() HashChainLinkIdentityType

Type returns the link identity type.

type HashChainLinkIdentityList 

type HashChainLinkIdentityList []*HashChainLinkIdentity

HashChainLinkIdentityList is alias for []*HashChainLinkIdentity.

func (HashChainLinkIdentityList) String 

func (l HashChainLinkIdentityList) String() string

String implements fmt.(Stringer) interface.

type HashChainLinkIdentityType 

type HashChainLinkIdentityType byte

HashChainLinkIdentityType is hash chain link identity type. 

const (
	// IdentityTypeUnknown is invalid type.
	IdentityTypeUnknown HashChainLinkIdentityType = iota
	// IdentityTypeLegacyID is Legacy client identifier.
	// A client identifier converted from a legacy signature.
	IdentityTypeLegacyID
	// IdentityTypeMetadata is a structure that provides the ability to incorporate client
	// identity and other information about the request into the hash chain.
	IdentityTypeMetadata
)
type Header struct {
	// contains filtered or unexported fields
}

Header is the message header consisting of the following fields:

  • 'login identifier': identifier of the client host for MAC key lookup. For portability, it is recommended to limit the login identifiers to valid POSIX usernames (that is, they should contain only uppercase and lowercase letters 'a' to 'z' and 'A' to 'Z', digits '0' to '9', periods '.', underscores '_', and dashes '-'.
  • 'instance identifier': a number identifying invocation of the sender.
  • 'message identifier': message number for duplicate filtering.

The instance and message identifier fields, when present, are used for filtering duplicate messages. The value of the 'instance identifier' field should increase every time the sending process is restarted. The 'message identifier' should sequentially number the messages within a process invocation. Having seen messages with a higher 'instance identifier' value from a client, a server may drop future messages with lower 'instance identifier' values assuming these are delayed messages from a previous invocation and thus no longer relevant. Similarly, a server may prioritize messages from a given client invocation by 'message identifier' values under the assumption that messages with lower values are more likely to be stale. Messages where the 'instance identifier' and 'message identifier' fields are absent should be considered unique. This is to accommodate short-lived client applications that typically send only a single request. For long-lived processes, the 'instance identifier' and 'message identifier' fields should be considered mandatory.

func NewHeader 

func NewHeader(loginID string, f RequestHeaderFunc) (*Header, error)

NewHeader returns PDU Header instance. Use parameter 'f' for applying optional Header values.

func (*Header) InstanceID 

func (h *Header) InstanceID() (uint64, error)

InstanceID returns a number identifying invocation of the sender. If not present, 0 is returned.

func (*Header) LoginID 

func (h *Header) LoginID() (string, error)

LoginID returns the identifier of the client host for MAC key lookup. If not present, an error is returned.

func (*Header) MessageID 

func (h *Header) MessageID() (uint64, error)

MessageID returns message number for duplicate filtering. If not present, 0 is returned.

func (*Header) SetInstID 

func (h *Header) SetInstID(id uint64) error

SetInstID is setter for the header instance ID.

func (*Header) SetMsgID 

func (h *Header) SetMsgID(id uint64) error

SetMsgID setter to for the header message ID.

type LegacyID 

type LegacyID struct {
	// contains filtered or unexported fields
}

LegacyID is a wrapper type for the legacy client identifier.

A client identifier converted from a legacy signature. The value must consist of exactly 29 octets:

  • The first two octets are fixed values 03 and 00.
  • The value of the third octet (at most 25) defines the length of the embedded name and is followed by that many octets of an UTF-8 string.
  • Finally, the value is padded with 00 octets to the final length (note that at least one padding octet will exist in any valid structure). For example, the name 'Test' is encoded as the sequence: 03 00 04 54=T 65=e 73=s 74=t 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 (all octet values in the example are given in hexadecimal).

This option is present only to support conversion of existing signatures created before the structured 'metadata' field was introduced and thus must not be used in new signatures. Note that 03 is marked as invalid value for hash function identifier to ensure that a 'legacy client identifier' value can't be confused with a 'sibling hash' imprint.

func (*LegacyID) Bytes 

func (l *LegacyID) Bytes() ([]byte, error)

Bytes returns raw structure. 

+------+------+---------+------------------+------------------+
|    Header   |  StrLen |    UTF8 string   |      Padding     |
+------+------+---------+------------------+------------------+
| 0x03 | 0x00 |    x    |        ...       |0x00{1..25-StrLen}|
+------+------+---------+------------------+------------------+

For example, the name 'Test' is encoded as the sequence: 

03 00 04 54=T 65=e 73=s 74=t 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
(all octet values in the example are given in hexadecimal).

func (*LegacyID) ClientID 

func (l *LegacyID) ClientID() (string, error)

ClientID returns string representation of the legacy ID octet string.

func (*LegacyID) FromTlv 

func (l *LegacyID) FromTlv(objTlv *tlv.Tlv) error

FromTlv implements tlv.(TlvObj) interface.

func (*LegacyID) ToTlv 

func (l *LegacyID) ToTlv(enc *tlv.Encoder) (*tlv.Tlv, error)

ToTlv implements tlv.(TlvObj) interface.

type LevelCalculator 

type LevelCalculator func(byte, byte) (byte, error)

LevelCalculator is aggregation chain level correction calculation strategy.

type LinkSiblingDataSetter 

type LinkSiblingDataSetter func(*chainLink) error

LinkSiblingDataSetter is functional value setter for the chain link value.

func LinkSiblingHash 

func LinkSiblingHash(hsh hash.Imprint) LinkSiblingDataSetter

LinkSiblingHash is sibling hash setter.

func LinkSiblingMetaData 

func LinkSiblingMetaData(md *MetaData) LinkSiblingDataSetter

LinkSiblingMetaData is sibling metadata setter.

type MetaData 

type MetaData struct {
	// contains filtered or unexported fields
}

MetaData is a sub-structure that provides the ability to incorporate client identity and other information about the request into the hash chain. It must contain the 'client identifier' field and may contain any combination of the 'machine identifier', 'sequence number', and 'request time' fields:

  • 'client identifier': a (human-readable) textual representation of client identity;
  • 'machine identifier': a (human-readable) identifier of the machine that requested the link structure (unique at least within the cluster that shares a 'client identifier');
  • 'sequence number': a local sequence number of a request assigned by the machine that created the link. Sequence numbers enable determination of the temporal order of requests processed by the same machine even within one aggregation round.
  • 'request time': the time when the server received the request from the client, recorded as precisely as the server's clock allows. This is another option for ordering of requests processed by the same machine within one aggregation round.
  • 'padding': an element whose purpose is to ensure that a 'metadata' value can't be confused with a 'sibling hash' imprint. This element, with the 'non-critical' and 'forward' flags set, must be the first field in the 'metadata' structure (thus the first octet of the value part of the structure is 7E, which is marked as invalid hash function identifier. The value of this element must be either one octet 01 or two octets 01 01 to make the total length of the metadata an even number (since hash functions have even-length output, the imprints embedding them have odd length and consequently even-length metadata can't be confused with an imprint).

func NewMetaData 

func NewMetaData(clientID string, optionals ...MetaDataOptional) (*MetaData, error)

NewMetaData returns a new metadata instance. Additional value can be applied via optionals.

func (*MetaData) ClientID 

func (m *MetaData) ClientID() (string, error)

ClientID returns a (human-readable) textual representation of client identity, or nil if not present.

func (*MetaData) Encode 

func (m *MetaData) Encode() ([]byte, error)

Encode returns the metadata in binary TLV representation.

func (*MetaData) EncodeToTlv 

func (m *MetaData) EncodeToTlv() (*tlv.Tlv, error)

EncodeToTlv returns the metadata in TLV representation.

func (*MetaData) FromTlv 

func (m *MetaData) FromTlv(objTlv *tlv.Tlv) error

FromTlv implements tlv.(TlvObj) interface.

func (*MetaData) HasPadding 

func (m *MetaData) HasPadding() bool

HasPadding returns true in case the metadata structure contains padding bytes, otherwise false.

func (*MetaData) MachineID 

func (m *MetaData) MachineID() (string, error)

MachineID returns a (human-readable) identifier of the machine that requested the link structure. If not present, an empty string is returned.

func (*MetaData) ReqTime 

func (m *MetaData) ReqTime() (uint64, error)

ReqTime returns the time when the server received the request from the client. If not present, 0 is returned.

func (*MetaData) SequenceNr 

func (m *MetaData) SequenceNr() (uint64, error)

SequenceNr returns a local sequence number of a request assigned by the machine that created the link. If not present, 0 is returned.

func (*MetaData) String 

func (m *MetaData) String() string

func (*MetaData) ToTlv 

func (m *MetaData) ToTlv(enc *tlv.Encoder) (*tlv.Tlv, error)

ToTlv implements tlv.(TlvObj) interface.

type MetaDataOptional 

type MetaDataOptional func(*metaData) error

MetaDataOptional is functional optional value setter.

func MetaDataMachineID 

func MetaDataMachineID(id string) MetaDataOptional

MetaDataMachineID is setter for the optional machine ID value.

func MetaDataReqTime 

func MetaDataReqTime(t uint64) MetaDataOptional

MetaDataReqTime is setter for the optional request time value.

func MetaDataSequenceNr 

func MetaDataSequenceNr(n uint64) MetaDataOptional

MetaDataSequenceNr is setter for the optional sequence number value.

type PublicationData 

type PublicationData struct {
	// contains filtered or unexported fields
}

PublicationData is the published data containing:

  • 'publication time': represented as a 64-bit unsigned integer;
  • 'published hash': output hash value of the calendar hash chain at the publication time.

func NewPublicationData 

func NewPublicationData(builder PublicationDataBuilder) (*PublicationData, error)

NewPublicationData returns a new publication data instance. Use the builder parameter for providing an initializer.

func (*PublicationData) Base32 

func (p *PublicationData) Base32() (string, error)

Base32 returns a publication string representing the fields of the published data structure, formatted in a way suitable for printed media and manual entry into a verification tool. The representation is limited to letters and numbers and embeds a checksum to detect typing errors.

func (*PublicationData) Bytes 

func (p *PublicationData) Bytes() ([]byte, error)

Bytes returns the binary TLV structure.

func (*PublicationData) Equal 

func (p *PublicationData) Equal(u *PublicationData) bool

Equal reports whether p and u represent the same publication data instance.

func (*PublicationData) PublicationTime 

func (p *PublicationData) PublicationTime() (time.Time, error)

PublicationTime returns the publication time.

func (*PublicationData) PublishedHash 

func (p *PublicationData) PublishedHash() (hash.Imprint, error)

PublishedHash returns published hash.

func (*PublicationData) String 

func (p *PublicationData) String() string

String implements fmt.(Stringer) interface.

type PublicationDataBuilder 

type PublicationDataBuilder func(*publicationData) error

PublicationDataBuilder is the concrete publication data constructor.

func PubDataFromImprint 

func PubDataFromImprint(t time.Time, h hash.Imprint) PublicationDataBuilder

PubDataFromImprint returns an initializer for constructing publication data from published data, where h is the output hash of the calendar hash chain at time t.

func PubDataFromString 

func PubDataFromString(s string) PublicationDataBuilder

PubDataFromString returns a builder for constructing publication data from publication string.

A publication string represents the fields of the published data structure, formatted in a way suitable for printed media and manual entry into a verification tool. The representation is limited to letters and numbers and embeds a checksum to detect typing errors. The publication string is constructed as follows:

  1. The publication data is assembled as a concatenation of - publication time, represented as a 64-bit unsigned integer, with the bits ordered from the most significant to the least significant. Note that the publication string is not a TLV structure and, in contrast with the TLV encoding rules, the leading zeros are preserved in this encoding to ensure consistent length of the publication strings. - publication imprint, consisting of the one-byte identifier of the hash algorithm and the hash value itself.
  2. The CRC-32 checksum of the publication data is computed and appended to the data.
  3. The resulting octet sequence is represented in base32 and optionally broken into groups of 6 or 8 characters by dashes.

For example, the encoding of a publication string for 2009-02-15T00:00:00Z: 

Raw data:
1.1 8-byte integer 1234656000, the POSIX time value for 2009-02-15 00:00:00
    00 00 00 00 49 97 5B 00
1.2 Imprint of the root hash value, the first 01 identifies the hash algorithm as SHA2-256
    01 EE 1F BC 8F D3 FD 78 FD 11 B9 E2 67 DF 9A F2 36 11 B1 C5 BE 44 F0 20 AB 8B 14 19 C9 36 72 C4 D6
2.  4-byte CRC-32 checksum of the preceding bytes
    EE 57 DB C6
3.  In base32 encoded printable form:
    AAAAAA-CJS5NQ-AAPOD6-6I7U75-PD6RDO-PCM7PZV4RWCG-Y4LPSE-6AQKXC-YUDHET-M4WE23-XFPW6G

type PublicationRec 

type PublicationRec struct {
	// contains filtered or unexported fields
}

PublicationRec represents the information related to a published hash value, possibly including the publication reference. Publication may also point (via a URI) to a hash database that is in electronic form and may contain several published hash values. A 'publication record' structure contains the following fields:

  • 'published data': consists of a 'publication time' and a 'published hash';
  • 'publication reference': an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared;
  • 'publications repository URI': URI of a publications' repository (publication file).

func NewPublicationRec 

func NewPublicationRec(pubData *PublicationData, optionals ...PublicationRecOptional) (*PublicationRec, error)

NewPublicationRec is the publication record constructor.

A publication record represents the information related to a published hash value, possibly including the publication reference. Publication may also point (via a URI) to a hash database that is in electronic form and may contain several published hash values.

func (*PublicationRec) Clone 

func (p *PublicationRec) Clone() (*PublicationRec, error)

Clone returns a deep copy of the receiver publication record.

func (*PublicationRec) PublicationData 

func (p *PublicationRec) PublicationData() (*PublicationData, error)

PublicationData returns the published data.

func (*PublicationRec) PublicationRef 

func (p *PublicationRec) PublicationRef() ([]string, error)

PublicationRef returns an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared.

func (*PublicationRec) PublicationRepURI 

func (p *PublicationRec) PublicationRepURI() ([]string, error)

PublicationRepURI returns URI of a publication's repository (publication file).

type PublicationRecOptional 

type PublicationRecOptional func(r *publicationRec) error

PublicationRecOptional is an optional functional parameter to be set while publication data construction.

func PubRecOptPublicationRef 

func PubRecOptPublicationRef(pubRef []string) PublicationRecOptional

PubRecOptPublicationRef sets an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared.

func PubRecOptPublicationRepURI 

func PubRecOptPublicationRepURI(pubRepURI []string) PublicationRecOptional

PubRecOptPublicationRepURI sets the URI of a publication's repository.

type PublicationsHeader 

type PublicationsHeader struct {
	// contains filtered or unexported fields
}

PublicationsHeader is the publications file header consisting of:

  • the version number of the file format;
  • the creation time of the file;
  • URI of the canonical distribution point of the file.

The two latter fields are for the benefit of clients that may receive cached copies of the file and want to ensure these copies are not stale.

type RFC3161 

type RFC3161 struct {
	// contains filtered or unexported fields
}

RFC3161 is the RFC 3161 compatibility record. An older implementation of the KSI service used the formats and protocols specified in the X.509 time-stamping standard. In that format, the hash value of the time-stamped datum was not signed directly, but via several intermediate structures:

  1. The hash value of the original datum was entered into the MessageImprint field of the TSTInfo structure.
  2. The hash value of the TSTInfo structure was entered into the MessageDigest field of the SignedAttributes structure.
  3. Finally, the hash value of the SignedAttributes structure was actually signed.

To facilitate conversion of legacy KSI signatures issued in the RFC 3161 format, the helper data structure is used, where the fields have the following meaning:

  • 'aggregation time', 'chain index', 'input data' and 'input hash' fields have the same meaning as in the 'aggregation chain' structure.
  • 'tstinfo prefix' and 'tstinfo suffix' fields contain the data preceding and succeeding the hash value within the TSTInfo structure.
  • 'tstinfo algorithm' field contains the one-octet identifier (as defined in Table 2) of the hash function used to hash the TSTInfo structure.
  • 'signed attributes prefix' and 'signed attributes suffix' fields contain the data preceding and succeeding the hash value within the SignedAttributes structure.
  • 'signed attributes algorithm' field contains the one-octet identifier of the hash function used to hash the SignedAttributes structure.

The record:

  • belongs to the aggregation hash chain component that has the same 'aggregation time' value and the same sequence of 'chain index' values;
  • may only be applied to the first component of the aggregation chain (that is, where the input to the aggregation is client data, not output of a previous aggregation);
  • acts as a data conversion filter preprocessing the data before it becomes input to the aggregation chain.

func (*RFC3161) AggregationTime 

func (r *RFC3161) AggregationTime() (time.Time, error)

AggregationTime returns aggregation chain aggregation time. If time is not present, an error is returned.

func (*RFC3161) ChainIndex 

func (r *RFC3161) ChainIndex() ([]uint64, error)

ChainIndex returns aggregation chain index. If chain index is not present, an error is returned.

func (*RFC3161) InputData 

func (r *RFC3161) InputData() ([]byte, error)

InputData returns input data. If data is not present, nil is returned.

func (*RFC3161) InputHash 

func (r *RFC3161) InputHash() (hash.Imprint, error)

InputHash returns input hash. If hash is not present, an error is returned.

func (*RFC3161) OutputHash 

func (r *RFC3161) OutputHash(algorithm hash.Algorithm) (hash.Imprint, error)

OutputHash calculates and returns the output hash of the RFC3161 record.

func (*RFC3161) SigAttrAlgo 

func (r *RFC3161) SigAttrAlgo() (hash.Algorithm, error)

SigAttrAlgo returns the hash function used to hash the SignedAttributes structure. If hash is not present, an error is returned.

func (*RFC3161) TstInfoAlgo 

func (r *RFC3161) TstInfoAlgo() (hash.Algorithm, error)

TstInfoAlgo returns the hash function used to hash the TSTInfo structure. If hash is not present, an error is returned.

type RequestHeaderFunc 

type RequestHeaderFunc func(*Header) error

RequestHeaderFunc is request header manipulation callback which is executed on every request 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.

type SignatureData 

type SignatureData struct {
	// contains filtered or unexported fields
}

SignatureData consists of:

  • 'signature type': a signing algorithm and signature format identifier, as assigned by IANA, represented as an UTF-8 string containing a dotted decimal object identifier (OID);
  • 'signature value': the signature itself, computed and formatted according to the specified method;
  • 'certificate identifier' and optionally 'certificate repository URI', with the latter pointing to a repository (e.g. a publication file) that contains the certificate identified by the 'certificate identifier'.

As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key.

func (*SignatureData) CertID 

func (s *SignatureData) CertID() ([]byte, error)

CertID returns the certificate identifier. If not set, an error is returned.

func (*SignatureData) CertRepURI 

func (s *SignatureData) CertRepURI() (string, error)

CertRepURI returns the optional certificate repository URI, pointing to a repository (e.g. a publication file) that contains the certificate identified by the 'certificate identifier' (see (SignatureData).CertID()).

func (*SignatureData) SignatureType 

func (s *SignatureData) SignatureType() (string, error)

SignatureType returns the signature type. If not set, an error is returned.

A signing algorithm and signature format identifier, as assigned by IANA, represented as an UTF-8 string containing a dotted decimal object identifier (OID).

As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key.

func (*SignatureData) SignatureValue 

func (s *SignatureData) SignatureValue() ([]byte, error)

SignatureValue returns the signature itself, computed and formatted according to the specified method. If not set, an error is returned.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.