timestamp

README

RFC3161 Time-Stamp Protocol (TSP) package for Go

Time-Stamp Protocol (TSP) package for Go

General

The package timestamp implements the Time-Stamp Protocol (TSP) as specified in RFC3161 (Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP)).

Documentation

Overview

Package timestamp implements the Time-Stamp Protocol (TSP) as specified in RFC3161 (Internet X.509 Public Key Infrastructure Time-Stamp Protocol (TSP)).

Index

• func CreateErrorResponse(pkiStatus Status, pkiFailureInfo FailureInfo) ([]byte, error)
• func CreateRequest(r io.Reader, opts *RequestOptions) ([]byte, error)
• type FailureInfo
  • func (f FailureInfo) String() string
• type ParseError
  • func (p ParseError) Error() string
• type Request
  • func ParseRequest(bytes []byte) (*Request, error)
  • func (req *Request) Marshal() ([]byte, error)
• type RequestOptions
• type Status
  • func (s Status) String() string
• type Timestamp
  • func Parse(bytes []byte) (*Timestamp, error)
  • func ParseResponse(bytes []byte) (*Timestamp, error)
  • func (t *Timestamp) CreateResponse(signingCert *x509.Certificate, priv crypto.Signer) ([]byte, error)
  • func (t *Timestamp) CreateResponseWithOpts(signingCert *x509.Certificate, priv crypto.Signer, opts crypto.SignerOpts) ([]byte, error)

Examples

• CreateRequest
• CreateRequest (CustomHashingAlgorithm)
• ParseRequest

Functions

func CreateErrorResponse

func CreateErrorResponse(pkiStatus Status, pkiFailureInfo FailureInfo) ([]byte, error)

CreateErrorResponse is used to create response other than granted and granted with mod status

func CreateRequest

func CreateRequest(r io.Reader, opts *RequestOptions) ([]byte, error)

CreateRequest returns a DER-encoded, timestamp request for the status of cert. If opts is nil then sensible defaults are used.

Example

ExampleCreateRequest demonstrates how to create a new time-stamping request for an io.Reader.

_, err := CreateRequest(strings.NewReader("Content to be time-stamped"), nil)
if err != nil {
	panic(err)
}

Example (CustomHashingAlgorithm)

ExampleCreateRequest_customHashingAlgorithm demonstrates how to create a new time-stamping request with options

_, err := CreateRequest(
	strings.NewReader("Content to be time-stamped"),
	&RequestOptions{
		Hash: crypto.SHA512,
	})
if err != nil {
	panic(err)
}

Types

type FailureInfo

type FailureInfo int

FailureInfo contains the failure details of an Time-Stamp request. See https://tools.ietf.org/html/rfc3161#section-2.4.2

const (
	// UnknownFailureInfo mean that no known failure info was provided
	UnknownFailureInfo FailureInfo = -1
	// BadAlgorithm defines an unrecognized or unsupported Algorithm Identifier
	BadAlgorithm FailureInfo = 0
	// BadRequest indicates that the transaction not permitted or supported
	BadRequest FailureInfo = 2
	// BadDataFormat means tha data submitted has the wrong format
	BadDataFormat FailureInfo = 5
	// TimeNotAvailable indicates that TSA's time source is not available
	TimeNotAvailable FailureInfo = 14
	// UnacceptedPolicy indicates that the requested TSA policy is not supported
	// by the TSA
	UnacceptedPolicy FailureInfo = 15
	// UnacceptedExtension indicates that the requested extension is not supported
	// by the TSA
	UnacceptedExtension FailureInfo = 16
	// AddInfoNotAvailable means that the information requested could not be
	// understood or is not available
	AddInfoNotAvailable FailureInfo = 17
	// SystemFailure indicates that the request cannot be handled due to system
	// failure
	SystemFailure FailureInfo = 25
)

func (FailureInfo) String

func (f FailureInfo) String() string

type ParseError

type ParseError string

ParseError results from an invalid Time-Stamp request or response.

func (ParseError) Error

func (p ParseError) Error() string

type Request

type Request struct {
	HashAlgorithm crypto.Hash
	HashedMessage []byte

	// Certificates indicates if the TSA needs to return the signing certificate
	// and optionally any other certificates of the chain as part of the response.
	Certificates bool

	// The TSAPolicyOID field, if provided, indicates the TSA policy under
	// which the TimeStampToken SHOULD be provided
	TSAPolicyOID asn1.ObjectIdentifier

	// The nonce, if provided, allows the client to verify the timeliness of
	// the response.
	Nonce *big.Int

	// Extensions contains raw X.509 extensions from the Extensions field of the
	// Time-Stamp request. When parsing requests, this can be used to extract
	// non-critical extensions that are not parsed by this package. When
	// marshaling OCSP requests, the Extensions field is ignored, see
	// ExtraExtensions.
	Extensions []pkix.Extension

	// ExtraExtensions contains extensions to be copied, raw, into any marshaled
	// OCSP response (in the singleExtensions field). Values override any
	// extensions that would otherwise be produced based on the other fields. The
	// ExtraExtensions field is not populated when parsing Time-Stamp requests,
	// see Extensions.
	ExtraExtensions []pkix.Extension
}

Request represents an Time-Stamp request. See https://tools.ietf.org/html/rfc3161#section-2.4.1

func ParseRequest

func ParseRequest(bytes []byte) (*Request, error)

ParseRequest parses an timestamp request in DER form.

Example

ExampleParseRequest demonstrates how to parse a raw der time-stamping request

// CreateRequest returns the request in der bytes
createdRequest, err := CreateRequest(strings.NewReader("Content to be time-stamped"), nil)
if err != nil {
	panic(err)
}

// ParseRequest parses a request in der bytes
parsedRequest, err := ParseRequest(createdRequest)
if err != nil {
	panic(err)
}

fmt.Printf("%x\n", parsedRequest.HashedMessage)

Output:

51a3620a3b62ffaff41a434e932223b31bc69e86490c365fa1186033904f1132

func (*Request) Marshal

func (req *Request) Marshal() ([]byte, error)

Marshal marshals the Time-Stamp request to ASN.1 DER encoded form.

type RequestOptions

type RequestOptions struct {
	// Hash contains the hash function that should be used when
	// constructing the timestamp request. If zero, SHA-256 will be used.
	Hash crypto.Hash

	// Certificates sets Request.Certificates
	Certificates bool

	// The TSAPolicyOID field, if provided, indicates the TSA policy under
	// which the TimeStampToken SHOULD be provided
	TSAPolicyOID asn1.ObjectIdentifier

	// The nonce, if provided, allows the client to verify the timeliness of
	// the response.
	Nonce *big.Int
}

RequestOptions contains options for constructing timestamp requests.

type Status

type Status int

Status contains the status of an Time-Stamp request. See https://tools.ietf.org/html/rfc3161#section-2.4.2

const (
	// Granted PKIStatus contains the value zero a TimeStampToken, as requested,
	// is present.
	Granted Status = 0
	// GrantedWithMods PKIStatus contains the value one a TimeStampToken, with
	// modifications, is present.
	GrantedWithMods Status = 1
	// Rejection PKIStatus
	Rejection Status = 2
	// Waiting PKIStatus
	Waiting Status = 3
	// RevocationWarning PKIStatus
	RevocationWarning Status = 4
	// RevocationNotification PKIStatus
	RevocationNotification Status = 5
)

func (Status) String

func (s Status) String() string

type Timestamp

type Timestamp struct {
	// Timestamp token part of raw ASN.1 DER content.
	RawToken []byte

	HashAlgorithm crypto.Hash
	HashedMessage []byte

	Time         time.Time
	Accuracy     time.Duration
	SerialNumber *big.Int
	Policy       asn1.ObjectIdentifier
	Ordering     bool
	Nonce        *big.Int
	Qualified    bool

	Certificates []*x509.Certificate

	// If set to true, includes TSA certificate in timestamp response
	AddTSACertificate bool

	// Extensions contains raw X.509 extensions from the Extensions field of the
	// Time-Stamp. When parsing time-stamps, this can be used to extract
	// non-critical extensions that are not parsed by this package. When
	// marshaling time-stamps, the Extensions field is ignored, see
	// ExtraExtensions.
	Extensions []pkix.Extension

	// ExtraExtensions contains extensions to be copied, raw, into any marshaled
	// Time-Stamp response. Values override any extensions that would otherwise
	// be produced based on the other fields. The ExtraExtensions field is not
	// populated when parsing Time-Stamp responses, see Extensions.
	ExtraExtensions []pkix.Extension
}

Timestamp represents an Time-Stamp. See: https://tools.ietf.org/html/rfc3161#section-2.4.1

func Parse

func Parse(bytes []byte) (*Timestamp, error)

Parse parses an Time-Stamp in DER form. If the time-stamp contains a certificate then the signature over the response is checked.

Invalid signatures or parse failures will result in a ParseError. Error responses will result in a ResponseError.

func ParseResponse

func ParseResponse(bytes []byte) (*Timestamp, error)

ParseResponse parses an Time-Stamp response in DER form containing a TimeStampToken.

Invalid signatures or parse failures will result in a ParseError. Error responses will result in a ResponseError.

func (*Timestamp) CreateResponse

func (t *Timestamp) CreateResponse(signingCert *x509.Certificate, priv crypto.Signer) ([]byte, error)

CreateResponse returns a DER-encoded timestamp response with the specified contents. The fields in the response are populated as follows:

The responder cert is used to populate the responder's name field, and the certificate itself is provided alongside the timestamp response signature.

This function is equivalent to CreateResponseWithOpts, using a SHA256 hash.

Deprecated: Use CreateResponseWithOpts instead.

func (*Timestamp) CreateResponseWithOpts

func (t *Timestamp) CreateResponseWithOpts(signingCert *x509.Certificate, priv crypto.Signer, opts crypto.SignerOpts) ([]byte, error)

CreateResponseWithOpts returns a DER-encoded timestamp response with the specified contents. The fields in the response are populated as follows:

The responder cert is used to populate the responder's name field, and the certificate itself is provided alongside the timestamp response signature.