Back to

Package atum

Latest Go to latest

The latest major version is .

Published: Jan 24, 2019 | License: MIT | Module:


Atum is a post-quantum secure easy-to-use trusted time-stamping protocol.


func EncodeTimeNonce

func EncodeTimeNonce(time int64, nonce []byte) []byte

Pack time and nonce as one byteslice

func SendRequest

func SendRequest(serverUrl string, req Request) (*Timestamp, Error)

Request a timestamp.

For a simpler interface, use Stamp() or JsonStamp().

func SetCache

func SetCache(newCache Cache)

Set the cache used by the Atum client to store server info and public keys.

See the Cache interface.

func Stamp

func Stamp(serverUrl string, nonce []byte) (*Timestamp, Error)

Request a timestamp for the given nonce.

For more flexibility, use SendRequest().

type Cache

type Cache interface {

	// Caches that the given public key is valid for the server
	StorePublicKey(serverUrl string, alg SignatureAlgorithm,
		pk []byte, expires time.Time)

	// Returns until when this public key should be trusted for the given
	// server (and nil if the public key is not to be trusted).
	GetPublicKey(serverUrl string, alg SignatureAlgorithm, pk []byte) *time.Time

	// Caches the server information.
	StoreServerInfo(serverUrl string, info ServerInfo)

	//  Retreieves cached server information, if available.
	GetServerInfo(serverUrl string) *ServerInfo

Caches for each known Atum server its public keys (for faster verification) and the ServerInfo (for faster stamping).

type Error

type Error interface {
	Inner() error // Returns the wrapped error, if any

func JsonStamp

func JsonStamp(serverUrl string, nonce []byte) ([]byte, Error)

Request a timestamp for the given nonce and returns it json encoded.

For more flexibility, use Stamp() or SendRequest().

func Verify

func Verify(jsonTs []byte, msgOrNonce []byte) (
	valid bool, tsTime time.Time, serverUrl string, err Error)

Verifies whether a Json encoded timestamp is valid. Returns the server which set the timestamp.

NOTE anyone can create a "valid" Atum timestamp by setting up their own

server.  You should check that you trust the server.

func VerifyFrom

func VerifyFrom(jsonTs []byte, msg io.Reader) (
	valid bool, tsTime time.Time, serverUrl string, err Error)

Like Verify(), but reads the message from an io.Reader.

type ErrorCode

type ErrorCode string
const (
	// There is too much lag between the time requested for the timestamp
	// and the time at which the request is processed.
	ErrorCodeLag ErrorCode = "too much lag"

	ErrorMissingNonce ErrorCode = "missing nonce"
	ErrorNonceTooLong ErrorCode = "nonce is too long"
	ErrorMissingPow   ErrorCode = "proof of work is missing"
	ErrorPowInvalid   ErrorCode = "proof of work is invalid"

type Hash

type Hash string

A possible hash

const (
	Shake256 Hash = "shake256"

type Hashing

type Hashing struct {

	// The hash function used to compress the message into a nonce
	Hash Hash

	// A prefix to hide the hash of the message from the Atum server
	Prefix []byte

See the Timestamp.Hashing field

func (*Hashing) ComputeNonce

func (h *Hashing) ComputeNonce(msg io.Reader) ([]byte, Error)

Computes the nonce associated to a message, when hashing is enabled.

type PublicKeyCheckResponse

type PublicKeyCheckResponse struct {
	// Should we trust this public key
	Trusted bool

	// When should you check again?
	Expires time.Time

Response of the Atum server to a public key check

type Request

type Request struct {

	// The nonce to timestamp.  The server might reject the timestamp if it
	// is too long.  See ServerInfo.MaxNonceSize.
	Nonce []byte

	// The proof of work (if required).
	// THe SendRequest() function will fill this field if it is required by
	// ServerInfo.RequiredProofOfWork.
	ProofOfWork *pow.Proof

	// Unix time to put on the timestamp.  The server will reject the request
	// if this time is too far of its own time.  See ServerInfo.AcceptableLag.
	Time *int64

	// Preferred signature algorithm.  If the specified signature algorithm
	// is not supported or this field is omitted, the server will revert
	// to the default.
	PreferredSigAlg *SignatureAlgorithm

A request to put a timestamp on a nonce.

type Response

type Response struct {
	// Error
	Error *ErrorCode

	// The timestamp
	Stamp *Timestamp

	// In case of most errors, the server will include server information.
	Info *ServerInfo

The response of the Atum server to a request

func (*Response) SetError

func (resp *Response) SetError(err ErrorCode)

Convenience function to set the Error field

type ServerInfo

type ServerInfo struct {
	// The maximum size of nonce accepted
	MaxNonceSize int64

	// Maximum lag to accept in number of seconds
	AcceptableLag int64

	// Default signature algorithm the server uses
	DefaultSigAlg SignatureAlgorithm

	// The necessary proof-of-work required for the different signature
	// algorithms.
	RequiredProofOfWork map[SignatureAlgorithm]pow.Request

Information published by an Atum server.

type Signature

type Signature struct {

	// The signature algorithm used
	Alg SignatureAlgorithm

	// The serialized signature
	Data []byte

	// The serialized public key with which the signature was set
	PublicKey []byte

The signature of the timestamp

func (*Signature) DangerousVerifySignatureButNotPublicKey

func (sig *Signature) DangerousVerifySignatureButNotPublicKey(
	time int64, nonce []byte) (valid bool, err Error)

Verifies the signature on a nonce, but not the public key.

You should only use this function if you have checked the public key should be trusted.

type SignatureAlgorithm

type SignatureAlgorithm string

Supported signature algorithms.

const (
	// Ed25519 EdDSA signatures. See rfc8032
	Ed25519 SignatureAlgorithm = "ed25519"

	// XMSS[MT] signatures.
	// See
	XMSSMT = "xmssmt"

type Timestamp

type Timestamp struct {

	// The unix time at which the timestamp was set
	Time int64

	// The server by which the timestamp was set
	ServerUrl string

	// The signature.
	Sig Signature

	// The Atum server only signs short nonces.  To timestamp a longer message,
	// the Atum server first hashes the long message to a nonce, which
	// in turn is signed by the Atum server.  If this is the case, the following
	// field contains the hash used.
	Hashing *Hashing `json:",omitempty"`

A signed timestamp on a nonce or longer message.

The message/nonce are not included.

func (*Timestamp) GetTime

func (ts *Timestamp) GetTime() time.Time

Returns the time at which the timestamp was set.

NOTE Don't forget to Verify() the timestamp!

func (*Timestamp) Verify

func (ts *Timestamp) Verify(msgOrNonce []byte) (valid bool, err Error)

Verifies the timestamp.

NOTE anyone can create a "valid" Atum timestamp by setting up their own

server.  You should check that you trust the server, which is
set in TimeStamp.ServerUrl.

func (*Timestamp) VerifyFrom

func (ts *Timestamp) VerifyFrom(r io.Reader) (valid bool, err Error)

Like Verify(), but reads the message from an io.Reader.

func (*Timestamp) VerifyPublicKey

func (ts *Timestamp) VerifyPublicKey() (trusted bool, err Error)

Asks the Atum server if the public key on the signature should be trusted

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier