feat: add tspclient package

errors.go

@@ -0,0 +1,110 @@
+// Copyright The Notary Project Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tspclient
+
+// CertificateNotFoundError is used when identified certificate is not found
+// in the timestampe token
+type CertificateNotFoundError error
+
+// MalformedRequestError is used when timestamping request is malformed.
+type MalformedRequestError struct {
+	Msg    string
+	Detail error
+}
+
+// Error returns error message.
+func (e *MalformedRequestError) Error() string {
+	msg := "malformed timestamping request"
+	if e.Msg != "" {
+		msg += ": " + e.Msg
+	}
+	if e.Detail != nil {
+		msg += ": " + e.Detail.Error()
+	}
+	return msg
+}
+
+// Unwrap returns the internal error.
+func (e *MalformedRequestError) Unwrap() error {
+	return e.Detail
+}
+
+// InvalidResponseError is used when timestamping response is invalid.
+type InvalidResponseError struct {
+	Msg    string
+	Detail error
+}
+
+// Error returns error message.
+func (e *InvalidResponseError) Error() string {
+	msg := "invalid timestamping response"
+	if e.Msg != "" {
+		msg += ": " + e.Msg
+	}
+	if e.Detail != nil {
+		msg += ": " + e.Detail.Error()
+	}
+	return msg
+}
+
+// Unwrap returns the internal error.
+func (e *InvalidResponseError) Unwrap() error {
+	return e.Detail
+}
+
+// SignedTokenVerificationError is used when fail to verify signed token.
+type SignedTokenVerificationError struct {
+	Msg    string
+	Detail error
+}
+
+// Error returns error message.
+func (e *SignedTokenVerificationError) Error() string {
+	msg := "failed to verify signed token"
+	if e.Msg != "" {
+		msg += ": " + e.Msg
+	}
+	if e.Detail != nil {
+		msg += ": " + e.Detail.Error()
+	}
+	return msg
+}
+
+// Unwrap returns the internal error.
+func (e *SignedTokenVerificationError) Unwrap() error {
+	return e.Detail
+}
+
+// TSTInfoError is used when fail a TSTInfo is invalid.
+type TSTInfoError struct {
+	Msg    string
+	Detail error
+}
+
+// Error returns error message.
+func (e *TSTInfoError) Error() string {
+	msg := "invalid TSTInfo"
+	if e.Msg != "" {
+		msg += ": " + e.Msg
+	}
+	if e.Detail != nil {
+		msg += ": " + e.Detail.Error()
+	}
+	return msg
+}
+
+// Unwrap returns the internal error.
+func (e *TSTInfoError) Unwrap() error {
+	return e.Detail
+}

errors_test.go

@@ -0,0 +1,105 @@
+// Copyright The Notary Project Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tspclient
+
+import (
+	"errors"
+	"testing"
+)
+
+var errTestInner = errors.New("test inner error")
+
+func TestMalformedRequestError(t *testing.T) {
+	newErr := MalformedRequestError{}
+	expectedErrMsg := "malformed timestamping request"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+
+	newErr = MalformedRequestError{
+		Detail: errTestInner,
+	}
+	expectedErrMsg = "malformed timestamping request: test inner error"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+	innerErr := newErr.Unwrap()
+	expectedErrMsg = "test inner error"
+	if innerErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, innerErr)
+	}
+}
+
+func TestInvalidResponseError(t *testing.T) {
+	newErr := InvalidResponseError{}
+	expectedErrMsg := "invalid timestamping response"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+
+	newErr = InvalidResponseError{
+		Detail: errTestInner,
+	}
+	expectedErrMsg = "invalid timestamping response: test inner error"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+	innerErr := newErr.Unwrap()
+	expectedErrMsg = "test inner error"
+	if innerErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, innerErr)
+	}
+}
+
+func TestSignedTokenVerificationError(t *testing.T) {
+	newErr := SignedTokenVerificationError{Msg: "test error msg"}
+	expectedErrMsg := "failed to verify signed token: test error msg"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+
+	newErr = SignedTokenVerificationError{
+		Detail: errTestInner,
+	}
+	expectedErrMsg = "failed to verify signed token: test inner error"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+	innerErr := newErr.Unwrap()
+	expectedErrMsg = "test inner error"
+	if innerErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+}
+
+func TestTSTInfoError(t *testing.T) {
+	newErr := TSTInfoError{}
+	expectedErrMsg := "invalid TSTInfo"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+
+	newErr = TSTInfoError{
+		Detail: errTestInner,
+	}
+	expectedErrMsg = "invalid TSTInfo: test inner error"
+	if newErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, newErr)
+	}
+	innerErr := newErr.Unwrap()
+	expectedErrMsg = "test inner error"
+	if innerErr.Error() != expectedErrMsg {
+		t.Fatalf("expected error %s, but got %v", expectedErrMsg, innerErr)
+	}
+}

go.mod

@@ -1,3 +1,3 @@
 module github.com/notaryproject/tspclient-go
 
-go 1.20
+go 1.21

http.go

@@ -0,0 +1,121 @@
+// Copyright The Notary Project Authors.
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tspclient
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+// maxBodyLength specifies the max content can be received from the remote
+// server.
+// The legnth of a regular TSA response with certificates is usually less than
+// 10 KiB.
+var maxBodyLength = 1 * 1024 * 1024 // 1 MiB
+
+// const for MediaTypes defined in RFC 3161 3.4
+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"
+)
+
+// httpTimestamper is a HTTP-based timestamper.
+type httpTimestamper struct {
+	httpClient *http.Client
+	endpoint   string
+}
+
+// NewHTTPTimestamper creates a HTTP-based timestamper with the endpoint
+// provided by the TSA.
+// http.DefaultTransport is used if nil RoundTripper is passed.
+func NewHTTPTimestamper(httpClient *http.Client, endpoint string) (Timestamper, error) {
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: 5 * time.Second}
+	}
+	if _, err := url.Parse(endpoint); err != nil {
+		return nil, err
+	}
+	return &httpTimestamper{
+		httpClient: httpClient,
+		endpoint:   endpoint,
+	}, nil
+}
+
+// Timestamp sends the request to the remote TSA server for timestamping.
+//
+// Reference: RFC 3161 3.4 Time-Stamp Protocol via HTTP
+func (ts *httpTimestamper) Timestamp(ctx context.Context, req *Request) (*Response, error) {
+	// sanity check
+	if err := req.Validate(); err != nil {
+		return nil, err
+	}
+
+	// prepare for http request
+	reqBytes, err := req.MarshalBinary()
+	if err != nil {
+		return nil, err
+	}
+	hReq, err := http.NewRequestWithContext(ctx, http.MethodPost, ts.endpoint, bytes.NewReader(reqBytes))
+	if err != nil {
+		return nil, err
+	}
+	hReq.Header.Set("Content-Type", MediaTypeTimestampQuery)
+
+	// send the request to the remote TSA server
+	hResp, err := ts.httpClient.Do(hReq)
+	if err != nil {
+		return nil, err
+	}
+	defer hResp.Body.Close()
+
+	// verify HTTP response
+	if hResp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("%s %q: https response bad status: %s", http.MethodPost, ts.endpoint, hResp.Status)
+	}
+	if contentType := hResp.Header.Get("Content-Type"); contentType != MediaTypeTimestampReply {
+		return nil, fmt.Errorf("%s %q: unexpected response content type: %s", http.MethodPost, ts.endpoint, contentType)
+	}
+
+	// read TSA response
+	lr := &io.LimitedReader{
+		R: hResp.Body,
+		N: int64(maxBodyLength),
+	}
+	respBytes, err := io.ReadAll(lr)
+	if err != nil {
+		return nil, err
+	}
+	if lr.N == 0 {
+		return nil, fmt.Errorf("%s %q: unexpected large http response, max response body size allowed is %d MiB", hResp.Request.Method, hResp.Request.URL, maxBodyLength/1024/1024)
+	}
+	var resp Response
+	if err := resp.UnmarshalBinary(respBytes); err != nil {
+		return nil, err
+	}
+	// validate response against RFC 3161
+	if err := resp.Validate(req); err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}