Add validation caching interface.

src/trusted/validator/validation_cache.h

Index: src/trusted/validator/validation_cache.h
diff --git a/src/trusted/validator/validation_cache.h b/src/trusted/validator/validation_cache.h
new file mode 100644
index 0000000000000000000000000000000000000000..eca4985f71bc4e6fd8eecdc983ddc034e5a59306
--- /dev/null
+++ b/src/trusted/validator/validation_cache.h
@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2012 The Native Client Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_
+#define NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_
+
+#include "native_client/src/include/nacl_base.h"
+
+EXTERN_C_BEGIN
+
+/*
+ * This interface allows the validator to query a database of validation results
+ * while hiding details of how the database is implemented.
+ *
+ * query = cache->CreateQuery(cache->handle);
+ * CreateQuery: create an opaque query object, given an opaque context object.
+ * The context object contains persistent variables that will be used for all
+ * queries, whereas the query object contains information relevant to a single
+ * validation result.
+ *
+ * cache->AddData(query, data, data_size);
+ * AddData: add a blob of binary data to the query.  Conceptually, the query
+ * will concatenate all the binary data it is given, in the order it is given,
+ * and use the concatenated blob as a key to look up validation results in a
+ * database.  In practice, all of the data is hashed into a reasonabally sized
+ * key.  The validation cache doesn't care what data it is given, it is the
+ * responsibility of the validator to provide enough information to uniquely
+ * identify the validation result.  This gives flexibility to use different
+ * types of keys for different validators and different sources of code.
+ *
+ * validation_passed = cache->QueryCodeValidates(query);
+ * QueryCodeValidates: the key is complete, query the validation status.
+ * AddData must not be called after calling this function.

[bsy, 2012/03/01 19:22:50]

can this be invoked more than once?

[Nick Bray (chromium), 2012/03/01 21:16:58]

Done.

+ *
+ * cache->SetCodeValidates(query);
+ * SetCodeValidates: set the database entry for the given key.
+ * QueryCodeValidates must be called first.

[bsy, 2012/03/01 19:22:50]

monotonic cache:  no way to clear the bit, except by hoping for the cache to
fill and evict an entry?  so the cache exhibits one-sided error, so that if
cache->QueryCodeValides(query) returns "false", that really means "unknown"? 
maybe rename it to something that suggests "KnownToValidate"?

[Nick Bray (chromium), 2012/03/01 21:16:58]

Done.

+ *
+ * cache->DestroyQuery(query);
+ * DestroyQuery: cleanup and deallocate the query object.

[bsy, 2012/03/01 19:22:50]

if query could be NULL here, it would make some cleanup code simpler.  if it
took the address of the query, then it could also automatically set the variable
to be NULL, so that unless the caller copied the pointer after invoking
CreateQuery, we're unlikely to have use-after-free issues.

[Nick Bray (chromium), 2012/03/01 21:16:58]

Skipping.  It's a marginal safety improvement for bad code, and it makes an
assumption there is a single, mutable query pointer - not a bad assumption, but
still an assumption.

+ */
+
+typedef struct NaClValidationCache {
+  void *handle;
+  void *(*CreateQuery)(void *handle);
+  void (*AddData)(void *query, const unsigned char *data, size_t length);
+  int (*QueryCodeValidates)(void *query);
+  void (*SetCodeValidates)(void *query);
+  void (*DestroyQuery)(void *query);
+} NaClValidationCache;
+
+EXTERN_C_END
+
+#endif /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_ */