Debian Codegraph @

pkg/storage/value/transformer.go

raw
1 /*
2 Copyright 2017 The Kubernetes Authors.
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 // Package value contains methods for assisting with transformation of values in storage.
18 package value
19
20 import (
21 "bytes"
22 "context"
23 "fmt"
24 "time"
25
26 "k8s.io/apimachinery/pkg/runtime/schema"
27 "k8s.io/apimachinery/pkg/util/errors"
28 genericapirequest "k8s.io/apiserver/pkg/endpoints/request"
29 "k8s.io/klog/v2"
30 )
31
32 func init() {
33 RegisterMetrics()
34 }
35
36 // Context is additional information that a storage transformation may need to verify the data at rest.
37 type Context interface {
38 // AuthenticatedData should return an array of bytes that describes the current value. If the value changes,
39 // the transformer may report the value as unreadable or tampered. This may be nil if no such description exists
40 // or is needed. For additional verification, set this to data that strongly identifies the value, such as
41 // the key and creation version of the stored data.
42 AuthenticatedData() []byte
43 }
44
45 type Read interface {
46 // TransformFromStorage may transform the provided data from its underlying storage representation or return an error.
47 // Stale is true if the object on disk is stale and a write to etcd should be issued, even if the contents of the object
48 // have not changed.
49 TransformFromStorage(ctx context.Context, data []byte, dataCtx Context) (out []byte, stale bool, err error)
50 }
51
52 type Write interface {
53 // TransformToStorage may transform the provided data into the appropriate form in storage or return an error.
54 TransformToStorage(ctx context.Context, data []byte, dataCtx Context) (out []byte, err error)
55 }
56
57 // Transformer allows a value to be transformed before being read from or written to the underlying store. The methods
58 // must be able to undo the transformation caused by the other.
59 type Transformer interface {
60 Read
61 Write
62 }
63
64 // ResourceTransformers returns a transformer for the provided resource.
65 type ResourceTransformers interface {
66 TransformerForResource(resource schema.GroupResource) Transformer
67 }
68
69 // DefaultContext is a simple implementation of Context for a slice of bytes.
70 type DefaultContext []byte
71
72 // AuthenticatedData returns itself.
73 func (c DefaultContext) AuthenticatedData() []byte { return c }
74
75 // PrefixTransformer holds a transformer interface and the prefix that the transformation is located under.
76 type PrefixTransformer struct {
77 Prefix []byte
78 Transformer Transformer
79 }
80
81 type prefixTransformers struct {
82 transformers []PrefixTransformer
83 err error
84 }
85
86 var _ Transformer = &prefixTransformers{}
87
88 // NewPrefixTransformers supports the Transformer interface by checking the incoming data against the provided
89 // prefixes in order. The first matching prefix will be used to transform the value (the prefix is stripped
90 // before the Transformer interface is invoked). The first provided transformer will be used when writing to
91 // the store.
92 func NewPrefixTransformers(err error, transformers ...PrefixTransformer) Transformer {
93 if err == nil {
94 err = fmt.Errorf("the provided value does not match any of the supported transformers")
95 }
96 return &prefixTransformers{
97 transformers: transformers,
98 err: err,
99 }
100 }
101
102 // TransformFromStorage finds the first transformer with a prefix matching the provided data and returns
103 // the result of transforming the value. It will always mark any transformation as stale that is not using
104 // the first transformer.
105 func (t *prefixTransformers) TransformFromStorage(ctx context.Context, data []byte, dataCtx Context) ([]byte, bool, error) {
106 start := time.Now()
107 var errs []error
108 resource := getResourceFromContext(ctx)
109 for i, transformer := range t.transformers {
110 if bytes.HasPrefix(data, transformer.Prefix) {
111 result, stale, err := transformer.Transformer.TransformFromStorage(ctx, data[len(transformer.Prefix):], dataCtx)
112 // To migrate away from encryption, user can specify an identity transformer higher up
113 // (in the config file) than the encryption transformer. In that scenario, the identity transformer needs to
114 // identify (during reads from disk) whether the data being read is encrypted or not. If the data is encrypted,
115 // it shall throw an error, but that error should not prevent the next subsequent transformer from being tried.
116 if len(transformer.Prefix) == 0 && err != nil {
117 continue
118 }
119 if len(transformer.Prefix) == 0 {
120 RecordTransformation(resource, "from_storage", "identity", time.Since(start), err)
121 } else {
122 RecordTransformation(resource, "from_storage", string(transformer.Prefix), time.Since(start), err)
123 }
124
125 // It is valid to have overlapping prefixes when the same encryption provider
126 // is specified multiple times but with different keys (the first provider is
127 // being rotated to and some later provider is being rotated away from).
128 //
129 // Example:
130 //
131 // {
132 // "aescbc": {
133 // "keys": [
134 // {
135 // "name": "2",
136 // "secret": "some key 2"
137 // }
138 // ]
139 // }
140 // },
141 // {
142 // "aescbc": {
143 // "keys": [
144 // {
145 // "name": "1",
146 // "secret": "some key 1"
147 // }
148 // ]
149 // }
150 // },
151 //
152 // The transformers for both aescbc configs share the prefix k8s:enc:aescbc:v1:
153 // but a failure in the first one should not prevent a later match from being attempted.
154 // Thus we never short-circuit on a prefix match that results in an error.
155 if err != nil {
156 errs = append(errs, err)
157 continue
158 }
159
160 return result, stale || i != 0, err
161 }
162 }
163 if err := errors.Reduce(errors.NewAggregate(errs)); err != nil {
164 logTransformErr(ctx, err, "failed to decrypt data")
165 return nil, false, err
166 }
167 RecordTransformation(resource, "from_storage", "unknown", time.Since(start), t.err)
168 return nil, false, t.err
169 }
170
171 // TransformToStorage uses the first transformer and adds its prefix to the data.
172 func (t *prefixTransformers) TransformToStorage(ctx context.Context, data []byte, dataCtx Context) ([]byte, error) {
173 start := time.Now()
174 transformer := t.transformers[0]
175 resource := getResourceFromContext(ctx)
176 result, err := transformer.Transformer.TransformToStorage(ctx, data, dataCtx)
177 RecordTransformation(resource, "to_storage", string(transformer.Prefix), time.Since(start), err)
178 if err != nil {
179 logTransformErr(ctx, err, "failed to encrypt data")
180 return nil, err
181 }
182 prefixedData := make([]byte, len(transformer.Prefix), len(result)+len(transformer.Prefix))
183 copy(prefixedData, transformer.Prefix)
184 prefixedData = append(prefixedData, result...)
185 return prefixedData, nil
186 }
187
188 func logTransformErr(ctx context.Context, err error, message string) {
189 requestInfo := getRequestInfoFromContext(ctx)
190 if klogLevel6 := klog.V(6); klogLevel6.Enabled() {
191 klogLevel6.InfoSDepth(
192 1,
193 message,
194 "err", err,
195 "group", requestInfo.APIGroup,
196 "version", requestInfo.APIVersion,
197 "resource", requestInfo.Resource,
198 "subresource", requestInfo.Subresource,
199 "verb", requestInfo.Verb,
200 "namespace", requestInfo.Namespace,
201 "name", requestInfo.Name,
202 )
203
204 return
205 }
206
207 klog.ErrorSDepth(1, err, message)
208 }
209
210 func getRequestInfoFromContext(ctx context.Context) *genericapirequest.RequestInfo {
211 if reqInfo, found := genericapirequest.RequestInfoFrom(ctx); found {
212 return reqInfo
213 }
214 klog.V(4).InfoSDepth(1, "no request info on context")
215 return &genericapirequest.RequestInfo{}
216 }
217
218 func getResourceFromContext(ctx context.Context) string {
219 reqInfo := getRequestInfoFromContext(ctx)
220 return schema.GroupResource{Group: reqInfo.APIGroup, Resource: reqInfo.Resource}.String()
221 }