tspclient

README

tspclient-go

tspclient-go provides implementation of the Time-Stamp Protocol (TSP) client as specified in RFC 3161.

Table of Contents

• Documentation
• Code of Conduct
• License

Documentation

Library documentation is available at Go Reference.

Code of Conduct

This project has adopted the CNCF Code of Conduct.

License

This project is covered under the Apache 2.0 license. You can read the license here.

Documentation

Overview

Package tspclient generates timestamping requests to TSA servers, fetches and verifies the responses according to RFC 3161 and RFC 5816

Index

• Constants
• type Accuracy
• type CertificateNotFoundError
• type InvalidResponseError
  • func (e *InvalidResponseError) Error() string
  • func (e *InvalidResponseError) Unwrap() error
• type MalformedRequestError
  • func (e *MalformedRequestError) Error() string
  • func (e *MalformedRequestError) Unwrap() error
• type MessageImprint
  • func (m MessageImprint) Equal(n MessageImprint) bool
• type Request
  • func NewRequest(opts RequestOptions) (*Request, error)
  • func (r *Request) MarshalBinary() ([]byte, error)
  • func (r *Request) UnmarshalBinary(data []byte) error
  • func (r *Request) Validate() error
• type RequestOptions
• type Response
  • func (r *Response) MarshalBinary() ([]byte, error)
  • func (r *Response) SignedToken() (*SignedToken, error)
  • func (r *Response) UnmarshalBinary(data []byte) error
  • func (r *Response) Validate(req *Request) error
• type SignedToken
  • func ParseSignedToken(berData []byte) (*SignedToken, error)
  • func (t *SignedToken) Info() (*TSTInfo, error)
  • func (t *SignedToken) SigningCertificate(signerInfo *cms.SignerInfo) (*x509.Certificate, error)
  • func (t *SignedToken) Verify(ctx context.Context, opts x509.VerifyOptions) ([]*x509.Certificate, error)
• type SignedTokenVerificationError
  • func (e *SignedTokenVerificationError) Error() string
  • func (e *SignedTokenVerificationError) Unwrap() error
• type TSTInfo
  • func (tst *TSTInfo) Validate(message []byte) (*Timestamp, error)
• type TSTInfoError
  • func (e *TSTInfoError) Error() string
  • func (e *TSTInfoError) Unwrap() error
• type Timestamp
  • func (t *Timestamp) BoundedAfter(u time.Time) bool
  • func (t *Timestamp) BoundedBefore(u time.Time) bool
  • func (t *Timestamp) Format(layout string) string
• type Timestamper
  • func NewHTTPTimestamper(httpClient *http.Client, endpoint string) (Timestamper, error)

Constants

const (
	// MediaTypeTimestampQuery is the content-type of timestamp query.
	// RFC 3161 3.4
	MediaTypeTimestampQuery = "application/timestamp-query"

	// MediaTypeTimestampReply is the content-type of timestamp reply
	// RFC 3161 3.4
	MediaTypeTimestampReply = "application/timestamp-reply"
)

const for MediaTypes defined in RFC 3161 3.4

Types

type Accuracy

type Accuracy struct {
	Seconds      int `asn1:"optional"`
	Milliseconds int `asn1:"optional,tag:0"`
	Microseconds int `asn1:"optional,tag:1"`
}

Accuracy ::= SEQUENCE {
 seconds     INTEGER             OPTIONAL,
 millis  [0] INTEGER (1..999)    OPTIONAL,
 micros  [1] INTEGER (1..999)    OPTIONAL }

type CertificateNotFoundError

type CertificateNotFoundError error

CertificateNotFoundError is used when identified certificate is not found in the timestampe token

type InvalidResponseError

type InvalidResponseError struct {
	Msg    string
	Detail error
}

InvalidResponseError is used when timestamping response is invalid.

func (*InvalidResponseError) Error

func (e *InvalidResponseError) Error() string

Error returns error message.

func (*InvalidResponseError) Unwrap

func (e *InvalidResponseError) Unwrap() error

Unwrap returns the internal error.

type MalformedRequestError

type MalformedRequestError struct {
	Msg    string
	Detail error
}

MalformedRequestError is used when timestamping request is malformed.

func (*MalformedRequestError) Error

func (e *MalformedRequestError) Error() string

Error returns error message.

func (*MalformedRequestError) Unwrap

func (e *MalformedRequestError) Unwrap() error

Unwrap returns the internal error.

type MessageImprint

type MessageImprint struct {
	HashAlgorithm pkix.AlgorithmIdentifier
	HashedMessage []byte
}

MessageImprint contains the hash of the datum to be time-stamped.

MessageImprint ::= SEQUENCE {
 hashAlgorithm   AlgorithmIdentifier,
 hashedMessage   OCTET STRING }

func (MessageImprint) Equal

func (m MessageImprint) Equal(n MessageImprint) bool

Equal compares if m and n are the same MessageImprint

Reference: RFC 3161 2.4.2

type Request

type Request struct {
	Version        int // fixed to 1 as defined in RFC 3161 2.4.1 Request Format
	MessageImprint MessageImprint
	ReqPolicy      asn1.ObjectIdentifier `asn1:"optional"`
	Nonce          *big.Int              `asn1:"optional"`
	CertReq        bool                  `asn1:"optional,default:false"`
	Extensions     []pkix.Extension      `asn1:"optional,tag:0"`
}

Request is a time-stamping request.

TimeStampReq ::= SEQUENCE {
 version         INTEGER                 { v1(1) },
 messageImprint  MessageImprint,
 reqPolicy       TSAPolicyID              OPTIONAL,
 nonce           INTEGER                  OPTIONAL,
 certReq         BOOLEAN                  DEFAULT FALSE,
 extensions      [0] IMPLICIT Extensions  OPTIONAL }

func NewRequest

func NewRequest(opts RequestOptions) (*Request, error)

NewRequest creates a timestamp request based on caller provided options.

func (*Request) MarshalBinary

func (r *Request) MarshalBinary() ([]byte, error)

MarshalBinary encodes the request to binary form. This method implements encoding.BinaryMarshaler.

Reference: https://pkg.go.dev/encoding#BinaryMarshaler

func (*Request) UnmarshalBinary

func (r *Request) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes the request from binary form. This method implements encoding.BinaryUnmarshaler.

Reference: https://pkg.go.dev/encoding#BinaryUnmarshaler

func (*Request) Validate

func (r *Request) Validate() error

Validate checks if req is a valid request against RFC 3161. It is used before a timstamp requestor sending the request to TSA.

type RequestOptions

type RequestOptions struct {
	// Content is the datum to be time stamped. REQUIRED.
	Content []byte

	// HashAlgorithm is the hash algorithm to be used to hash the Content.
	// REQUIRED and MUST be an available hash algorithm.
	HashAlgorithm crypto.Hash

	// HashAlgorithmParameters is the parameters for the HashAlgorithm.
	// OPTIONAL.
	//
	// Reference: https://www.rfc-editor.org/rfc/rfc5280#section-4.1.1.2
	HashAlgorithmParameters asn1.RawValue

	// ReqPolicy specifies the TSA policy ID. OPTIONAL.
	//
	// Reference: https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.1
	ReqPolicy asn1.ObjectIdentifier

	// NoCert tells the TSA to not include any signing certificate in its
	// response. By default, TSA signing certificate is included in the response.
	// OPTIONAL.
	NoCert bool

	// Extensions is a generic way to add additional information
	// to the request in the future. OPTIONAL.
	Extensions []pkix.Extension
}

RequestOptions provides options for caller to create a new timestamp request

type Response

type Response struct {
	Status         pki.StatusInfo
	TimestampToken asn1.RawValue `asn1:"optional"`
}

Response is a time-stamping response.

TimeStampResp ::= SEQUENCE {
 status          PKIStatusInfo,
 timeStampToken  TimeStampToken  OPTIONAL }

func (*Response) MarshalBinary

func (r *Response) MarshalBinary() ([]byte, error)

MarshalBinary encodes the response to binary form. This method implements encoding.BinaryMarshaler.

Reference: https://pkg.go.dev/encoding#BinaryMarshaler

func (*Response) SignedToken

func (r *Response) SignedToken() (*SignedToken, error)

SignedToken returns the timestamp token with signatures.

Callers should invoke SignedToken.Verify to verify the content before comsumption.

func (*Response) UnmarshalBinary

func (r *Response) UnmarshalBinary(data []byte) error

UnmarshalBinary decodes the response from binary form. This method implements encoding.BinaryUnmarshaler.

Reference: https://pkg.go.dev/encoding#BinaryUnmarshaler

func (*Response) Validate

func (r *Response) Validate(req *Request) error

Validate checks if resp is a successful timestamp response against its corresponding request based on RFC 3161. It is used when a timestamp requestor receives the response from TSA.

type SignedToken

type SignedToken cms.ParsedSignedData

SignedToken is a parsed timestamp token with signatures.

func ParseSignedToken

func ParseSignedToken(berData []byte) (*SignedToken, error)

ParseSignedToken parses ASN.1 BER-encoded structure to SignedToken without verification. berData is the full bytes of a TimestampToken defined in RFC 3161 2.4.2.

Callers should invoke SignedToken.Verify to verify the content before comsumption.

func (*SignedToken) Info

func (t *SignedToken) Info() (*TSTInfo, error)

Info returns the TSTInfo as defined in RFC 3161 2.4.2.

Caller should use TSTInfo.Timestamp for consumption.

func (*SignedToken) SigningCertificate

func (t *SignedToken) SigningCertificate(signerInfo *cms.SignerInfo) (*x509.Certificate, error)

SigningCertificate gets the signing certificate identified by SignedToken SignerInfo's SigningCertificateV2 attribute. If the IssuerSerial field of signing certificate is missing, use signerInfo's sid instead. The identified signing certificate MUST match the hash in SigningCertificateV2.

References: RFC 3161 2.4.1 & 2.4.2; RFC 5816

func (*SignedToken) Verify

func (t *SignedToken) Verify(ctx context.Context, opts x509.VerifyOptions) ([]*x509.Certificate, error)

Verify verifies the signed token as CMS SignedData. An empty list of KeyUsages in VerifyOptions implies ExtKeyUsageTimeStamping. The `Intermediates` in the verify options will be ignored and re-contrusted using the certificates in the parsed signed token. It returns success when the first signer info verification succeeds.

type SignedTokenVerificationError

type SignedTokenVerificationError struct {
	Msg    string
	Detail error
}

SignedTokenVerificationError is used when fail to verify signed token.

func (*SignedTokenVerificationError) Error

func (e *SignedTokenVerificationError) Error() string

Error returns error message.

func (*SignedTokenVerificationError) Unwrap

func (e *SignedTokenVerificationError) Unwrap() error

Unwrap returns the internal error.

type TSTInfo

type TSTInfo struct {
	Version        int // fixed to 1 as defined in RFC 3161 2.4.2
	Policy         asn1.ObjectIdentifier
	MessageImprint MessageImprint
	SerialNumber   *big.Int
	GenTime        time.Time        `asn1:"generalized"`
	Accuracy       Accuracy         `asn1:"optional"`
	Ordering       bool             `asn1:"optional,default:false"`
	Nonce          *big.Int         `asn1:"optional"`
	TSA            asn1.RawValue    `asn1:"optional,tag:0"`
	Extensions     []pkix.Extension `asn1:"optional,tag:1"`
}

TSTInfo ::= SEQUENCE {
 version         INTEGER                 { v1(1) },
 policy          TSAPolicyId,
 messageImprint  MessageImprint,
 serialNumber    INTEGER,
 genTime         GeneralizedTime,
 accuracy        Accuracy                OPTIONAL,
 ordering        BOOLEAN                 DEFAULT FALSE,
 nonce           INTEGER                 OPTIONAL,
 tsa             [0] GeneralName         OPTIONAL,
 extensions      [1] IMPLICIT Extensions OPTIONAL }

func (*TSTInfo) Validate

func (tst *TSTInfo) Validate(message []byte) (*Timestamp, error)

Validate validates tst and returns the Timestamp on success. tst MUST be valid and the time stamped datum MUST match message.

type TSTInfoError

type TSTInfoError struct {
	Msg    string
	Detail error
}

TSTInfoError is used when fail a TSTInfo is invalid.

func (*TSTInfoError) Error

func (e *TSTInfoError) Error() string

Error returns error message.

func (*TSTInfoError) Unwrap

func (e *TSTInfoError) Unwrap() error

Unwrap returns the internal error.

type Timestamp

type Timestamp struct {
	// Value is the GenTime of TSTInfo
	Value time.Time

	// Accuracy is the Accuracy of TSTInfo
	Accuracy time.Duration
}

Timestamp denotes the time at which the timestamp token was created by the TSA

Reference: RFC 3161 2.4.2

func (*Timestamp) BoundedAfter

func (t *Timestamp) BoundedAfter(u time.Time) bool

BoundedAfter returns true if the lower limit of the time at which the timestamp token was created is after or equal to u.

Reference: RFC 3161 2.4.2

func (*Timestamp) BoundedBefore

func (t *Timestamp) BoundedBefore(u time.Time) bool

BoundedBefore returns true if the upper limit of the time at which the timestamp token was created is before or equal to u.

Reference: RFC 3161 2.4.2

func (*Timestamp) Format

func (t *Timestamp) Format(layout string) string

Format returns a string of t in format layout. The output is a timestamp range calculated with its accuracy.

type Timestamper

type Timestamper interface {
	// Timestamp stamps the time with the given request.
	Timestamp(context.Context, *Request) (*Response, error)
}

Timestamper stamps the time.

func NewHTTPTimestamper

func NewHTTPTimestamper(httpClient *http.Client, endpoint string) (Timestamper, error)

NewHTTPTimestamper creates a HTTP-based timestamper with the endpoint provided by the TSA. http.DefaultTransport is used if nil RoundTripper is passed.