feat: crl cache

dir/fs.go

@@ -58,3 +58,8 @@ func ConfigFS() SysFS {
 func PluginFS() SysFS {
 	return NewSysFS(filepath.Join(userLibexecDirPath(), PathPlugins))
 }
+
+// CacheFS is the cache SysFS
+func CacheFS() SysFS {
+	return NewSysFS(userCacheDirPath())
+}

dir/fs_test.go

@@ -71,3 +71,14 @@ func TestPluginFS(t *testing.T) {
 		t.Fatalf(`SysPath() failed. got: %q, want: %q`, path, filepath.Join(userLibexecDirPath(), PathPlugins, "plugin"))
 	}
 }
+
+func TestCacheFS(t *testing.T) {
+	cacheFS := CacheFS()
+	path, err := cacheFS.SysPath()
+	if err != nil {
+		t.Fatalf("SysPath() failed. err = %v", err)
+	}
+	if path != filepath.Join(UserCacheDir) {
+		t.Fatalf(`SysPath() failed. got: %q, want: %q`, path, UserConfigDir)
+	}
+}

dir/path.go

@@ -12,7 +12,7 @@
 // limitations under the License.
 
 // Package dir implements Notation directory structure.
-// [directory spec]: https://github.com/notaryproject/notation/blob/main/specs/directory.md
+// [directory spec]: https://notaryproject.dev/docs/user-guides/how-to/directory-structure/
 //
 // Example:
 //
@@ -31,7 +31,7 @@
 //   - Set custom configurations directory:
 //     dir.UserConfigDir = '/path/to/configurations/'
 //
-// Only user level directory is supported for RC.1, and system level directory
+// Only user level directory is supported, and system level directory
 // may be added later.
 package dir
 
@@ -44,6 +44,7 @@ import (
 var (
 	UserConfigDir  string // Absolute path of user level {NOTATION_CONFIG}
 	UserLibexecDir string // Absolute path of user level {NOTATION_LIBEXEC}
+	UserCacheDir   string // Absolute path of user level {NOTATION_CACHE}
 )
 
 const (
@@ -77,7 +78,12 @@ const (
 	TrustStoreDir = "truststore"
 )
 
-var userConfigDir = os.UserConfigDir // for unit test
+// for unit tests
+var (
+	userConfigDir = os.UserConfigDir
+
+	userCacheDir = os.UserCacheDir
+)
 
 // userConfigDirPath returns the user level {NOTATION_CONFIG} path.
 func userConfigDirPath() string {
@@ -103,6 +109,21 @@ func userLibexecDirPath() string {
 	return UserLibexecDir
 }
 
+// userCacheDirPath returns the user level {NOTATION_CACHE} path.
+func userCacheDirPath() string {
+	if UserCacheDir == "" {
+		userDir, err := userCacheDir()
+		if err != nil {
+			// fallback to current directory
+			UserCacheDir = filepath.Join("."+notation, "cache")
+			return UserCacheDir
+		}
+		// set user cache
+		UserCacheDir = filepath.Join(userDir, notation)
+	}
+	return UserCacheDir
+}
+
 // LocalKeyPath returns the local key and local cert relative paths.
 func LocalKeyPath(name string) (keyPath, certPath string) {
 	basePath := path.Join(LocalKeysDir, name)

dir/path_test.go

@@ -15,20 +15,22 @@ package dir
 
 import (
 	"os"
+	"path/filepath"
 	"testing"
 )
 
-func mockGetUserConfig() (string, error) {
+func mockUserPath() (string, error) {
 	return "/path/", nil
 }
 
 func setup() {
 	UserConfigDir = ""
 	UserLibexecDir = ""
+	UserCacheDir = ""
 }
 
 func Test_UserConfigDirPath(t *testing.T) {
-	userConfigDir = mockGetUserConfig
+	userConfigDir = mockUserPath
 	setup()
 	got := userConfigDirPath()
 	if got != "/path/notation" {
@@ -39,25 +41,40 @@ func Test_UserConfigDirPath(t *testing.T) {
 func Test_NoHomeVariable(t *testing.T) {
 	t.Setenv("HOME", "")
 	t.Setenv("XDG_CONFIG_HOME", "")
+	t.Setenv("XDG_CACHE_HOME", "")
 	setup()
 	userConfigDir = os.UserConfigDir
 	got := userConfigDirPath()
 	if got != ".notation" {
-		t.Fatalf(`UserConfigDirPath() = %q, want ".notation"`, UserConfigDir)
+		t.Fatalf(`userConfigDirPath() = %q, want ".notation"`, got)
+	}
+	got = userCacheDirPath()
+	want := filepath.Join("."+notation, "cache")
+	if got != want {
+		t.Fatalf(`userCacheDirPath() = %q, want %q`, got, want)
 	}
 }
 
 func Test_UserLibexecDirPath(t *testing.T) {
-	userConfigDir = mockGetUserConfig
+	userConfigDir = mockUserPath
 	setup()
 	got := userLibexecDirPath()
 	if got != "/path/notation" {
 		t.Fatalf(`UserConfigDirPath() = %q, want "/path/notation"`, got)
 	}
 }
 
+func Test_UserCacheDirPath(t *testing.T) {
+	userCacheDir = mockUserPath
+	setup()
+	got := userCacheDirPath()
+	if got != "/path/notation" {
+		t.Fatalf(`UserCacheDirPath() = %q, want "/path/notation"`, got)
+	}
+}
+
 func TestLocalKeyPath(t *testing.T) {
-	userConfigDir = mockGetUserConfig
+	userConfigDir = mockUserPath
 	setup()
 	_ = userConfigDirPath()
 	_ = userLibexecDirPath()
@@ -71,7 +88,7 @@ func TestLocalKeyPath(t *testing.T) {
 }
 
 func TestX509TrustStoreDir(t *testing.T) {
-	userConfigDir = mockGetUserConfig
+	userConfigDir = mockUserPath
 	setup()
 	_ = userConfigDirPath()
 	_ = userLibexecDirPath()

go.mod

@@ -4,7 +4,7 @@ go 1.22.0
 
 require (
 	github.com/go-ldap/ldap/v3 v3.4.8
-	github.com/notaryproject/notation-core-go v1.1.1-0.20240918011623-695ea0c1ad1f
+	github.com/notaryproject/notation-core-go v1.1.1-0.20240920045731-0786f51de737
 	github.com/notaryproject/notation-plugin-framework-go v1.0.0
 	github.com/notaryproject/tspclient-go v0.2.0
 	github.com/opencontainers/go-digest v1.0.0

go.sum

@@ -32,8 +32,8 @@ github.com/jcmturner/gokrb5/v8 v8.4.4 h1:x1Sv4HaTpepFkXbt2IkL29DXRf8sOfZXo8eRKh6
 github.com/jcmturner/gokrb5/v8 v8.4.4/go.mod h1:1btQEpgT6k+unzCwX1KdWMEwPPkkgBtP+F6aCACiMrs=
 github.com/jcmturner/rpc/v2 v2.0.3 h1:7FXXj8Ti1IaVFpSAziCZWNzbNuZmnvw/i6CqLNdWfZY=
 github.com/jcmturner/rpc/v2 v2.0.3/go.mod h1:VUJYCIDm3PVOEHw8sgt091/20OJjskO/YJki3ELg/Hc=
-github.com/notaryproject/notation-core-go v1.1.1-0.20240918011623-695ea0c1ad1f h1:TmwJtM3AZ7iQ1LJEbHRPAMRw4hA52/AbVrllSVjCNP0=
-github.com/notaryproject/notation-core-go v1.1.1-0.20240918011623-695ea0c1ad1f/go.mod h1:+6AOh41JPrnVLbW/19SJqdhVHwKgIINBO/np0e7nXJA=
+github.com/notaryproject/notation-core-go v1.1.1-0.20240920045731-0786f51de737 h1:Hp93KBCABE29+6zdS0GTg0T1SXj6qGatJyN1JMvTQqk=
+github.com/notaryproject/notation-core-go v1.1.1-0.20240920045731-0786f51de737/go.mod h1:b/70rA4OgOHlg0A7pb8zTWKJadFO6781zS3a37KHEJQ=
 github.com/notaryproject/notation-plugin-framework-go v1.0.0 h1:6Qzr7DGXoCgXEQN+1gTZWuJAZvxh3p8Lryjn5FaLzi4=
 github.com/notaryproject/notation-plugin-framework-go v1.0.0/go.mod h1:RqWSrTOtEASCrGOEffq0n8pSg2KOgKYiWqFWczRSics=
 github.com/notaryproject/tspclient-go v0.2.0 h1:g/KpQGmyk/h7j60irIRG1mfWnibNOzJ8WhLqAzuiQAQ=

verifier/crl/crl.go

@@ -0,0 +1,185 @@
+// 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 crl provides functionalities for crl revocation check.
+package crl
+
+import (
+	"context"
+	"crypto/sha256"
+	"crypto/x509"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"time"
+
+	corecrl "github.com/notaryproject/notation-core-go/revocation/crl"
+	"github.com/notaryproject/notation-go/log"
+)
+
+const (
+	// tmpFileName is the prefix of the temporary file
+	tmpFileName = "notation-*"
+)
+
+// FileCache implements corecrl.Cache.
+//
+// Key: url of the CRL.
+//
+// Value: corecrl.Bundle.
+//
+// This cache builds on top of the UNIX file system to leverage the file system's
+// atomic operations. The `rename` and `remove` operations will unlink the old
+// file but keep the inode and file descriptor for existing processes to access
+// the file. The old inode will be dereferenced when all processes close the old
+// file descriptor. Additionally, the operations are proven to be atomic on
+// UNIX-like platforms, so there is no need to handle file locking.
+//
+// NOTE: For Windows, the `open`, `rename` and `remove` operations need file
+// locking to ensure atomicity. The current implementation does not handle
+// file locking, so the concurrent write from multiple processes may be failed.
+// Please do not use this cache in a multi-process environment on Windows.
+type FileCache struct {
+	// root is the root directory of the cache
+	root string
+}
+
+// fileCacheContent is the actual content saved in a FileCache
+type fileCacheContent struct {
+	// RawBaseCRL is baseCRL.Raw
+	RawBaseCRL []byte `json:"rawBaseCRL"`
+
+	// RawDeltaCRL is deltaCRL.Raw
+	RawDeltaCRL []byte `json:"rawDeltaCRL,omitempty"`
+}
+
+// NewFileCache creates a FileCache with root as the root directory
+func NewFileCache(root string) (*FileCache, error) {
+	if err := os.MkdirAll(root, 0700); err != nil {
+		return nil, fmt.Errorf("failed to create crl file cache: %w", err)
+	}
+	return &FileCache{
+		root: root,
+	}, nil
+}
+
+// Get retrieves CRL bundle from c given url as key. If the key does not exist
+// or the content has expired, corecrl.ErrCacheMiss is returned.
+func (c *FileCache) Get(ctx context.Context, url string) (*corecrl.Bundle, error) {
+	logger := log.GetLogger(ctx)
+	logger.Infof("Retrieving crl bundle from file cache with key %q ...", url)
+
+	// get content from file cache
+	f, err := os.Open(filepath.Join(c.root, c.fileName(url)))
+	if err != nil {
+		if errors.Is(err, fs.ErrNotExist) {
+			logger.Infof("CRL file cache miss. Key %q does not exist", url)
+			return nil, corecrl.ErrCacheMiss
+		}
+		return nil, fmt.Errorf("failed to get crl bundle from file cache with key %q: %w", url, err)
+	}
+	defer f.Close()
+
+	// decode content to crl Bundle
+	var content fileCacheContent
+	err = json.NewDecoder(f).Decode(&content)
+	if err != nil {
+		return nil, fmt.Errorf("failed to decode file retrieved from file cache: %w", err)
+	}
+	var bundle corecrl.Bundle
+	bundle.BaseCRL, err = x509.ParseRevocationList(content.RawBaseCRL)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse base CRL of file retrieved from file cache: %w", err)
+	}
+	if content.RawDeltaCRL != nil {
+		bundle.DeltaCRL, err = x509.ParseRevocationList(content.RawDeltaCRL)
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse delta CRL of file retrieved from file cache: %w", err)
+		}
+	}
+
+	// check expiry
+	if err := checkExpiry(ctx, bundle.BaseCRL.NextUpdate); err != nil {
+		return nil, err
+	}
+	if bundle.DeltaCRL != nil {
+		if err := checkExpiry(ctx, bundle.DeltaCRL.NextUpdate); err != nil {
+			return nil, err
+		}
+	}
+
+	return &bundle, nil
+}
+
+// Set stores the CRL bundle in c with url as key.
+func (c *FileCache) Set(ctx context.Context, url string, bundle *corecrl.Bundle) error {
+	logger := log.GetLogger(ctx)
+	logger.Infof("Storing crl bundle to file cache with key %q ...", url)
+
+	// sanity check
+	if bundle == nil {
+		return errors.New("failed to store crl bundle in file cache: bundle cannot be nil")
+	}
+	if bundle.BaseCRL == nil {
+		return errors.New("failed to store crl bundle in file cache: bundle BaseCRL cannot be nil")
+	}
+
+	// actual content to be saved in the cache
+	content := fileCacheContent{
+		RawBaseCRL: bundle.BaseCRL.Raw,
+	}
+	if bundle.DeltaCRL != nil {
+		content.RawDeltaCRL = bundle.DeltaCRL.Raw
+	}
+
+	// save content to tmp file
+	tmpFile, err := os.CreateTemp("", tmpFileName)
+	if err != nil {
+		return fmt.Errorf("failed to store crl bundle in file cache: failed to create temp file: %w", err)
+	}
+	err = json.NewEncoder(tmpFile).Encode(content)
+	if err != nil {
+		return fmt.Errorf("failed to store crl bundle in file cache: failed to encode content: %w", err)
+	}
+
+	// rename is atomic on UNIX-like platforms
+	err = os.Rename(tmpFile.Name(), filepath.Join(c.root, c.fileName(url)))
+	if err != nil {
+		return fmt.Errorf("failed to store crl bundle in file cache: %w", err)
+	}
+	return nil
+}
+
+// fileName returns the filename of the content stored in c
+func (c *FileCache) fileName(url string) string {
+	hash := sha256.Sum256([]byte(url))
+	return hex.EncodeToString(hash[:])
+}
+
+// checkExpiry returns nil when nextUpdate is bounded before current time
+func checkExpiry(ctx context.Context, nextUpdate time.Time) error {
+	logger := log.GetLogger(ctx)
+
+	if nextUpdate.IsZero() {
+		return errors.New("crl bundle retrieved from file cache does not contain valid NextUpdate")
+	}
+	if time.Now().After(nextUpdate) {
+		logger.Infof("CRL bundle retrieved from file cache has expired at %s", nextUpdate)
+		return corecrl.ErrCacheMiss
+	}
+	return nil
+}