Add a ReadMe file and an example how to run refaster patches.

I would like to expand these patches in the following weeks.

PiperOrigin-RevId: 517150589

4 files changed, 129 insertions, 0 deletions

diff --git a/java_src/tools/refaster/README.md b/java_src/tools/refaster/README.md
new file mode 100644
index 000000000..af48b2522
--- /dev/null
+++ b/java_src/tools/refaster/README.md
@@ -0,0 +1,49 @@
+# Refaster templates for Tink
+
+In this directory, we store refaster templates for usage with Tink. These
+help users modernize the code and move to preferred APIs.
+
+We sometimes run these templates manually, but do not test them via continuous
+integration.
+
+```bash
+tink_version="1.8.0"
+errorprone_version="2.18.0"
+
+## STEP 1: We get the 3 jar files:
+## tink-{version}-jar, error_prone_refaster-{version}.jar, and error_prone_core-{version}.jar
+## (For good measure, we verify the 3 sha256sums.)
+
+maven_base="repo1.maven.org/maven2/com/google"
+
+tink_jar="tink-${tink_version}.jar"
+tink_sha256="92b8676c15b11a7faa15f3d1f05ed776a2897da3deba18c528ff32043339f248"
+
+refaster_jar="error_prone_refaster-${errorprone_version}.jar"
+refaster_sha256="0cde0a3db5c2f748fae4633ccd8c66a9ba9c5a0f7a380c9104b99372fd0c4959"
+errorprone_jar="error_prone_core-${errorprone_version}-with-dependencies.jar"
+errorprone_sha256="2b3f2d21e7754bece946cf8f7b0e2b2f805c46f58b4839eb302c3d2498a3a55e"
+
+wget "https://${maven_base}/crypto/tink/tink/${tink_version}/${tink_jar}"
+echo "${tink_sha256} ${tink_jar}" | sha256sum -c
+
+wget "https://${maven_base}/errorprone/error_prone_refaster/${errorprone_version}/${refaster_jar}"
+echo "${refaster_sha256} ${refaster_jar}" | sha256sum -c
+
+wget "https://${maven_base}/errorprone/error_prone_core/${errorprone_version}/${errorprone_jar}"
+echo "${errorprone_sha256} ${errorprone_jar}" | sha256sum -c
+
+## STEP 2: Use the current file in tink1to2 to create a "tinkrule.refaster":
+javac -cp "${tink_jar}:${refaster_jar}" \
+    "-Xplugin:RefasterRuleCompiler --out ${PWD}/tinkrule.refaster" \
+    java/com/google/tink1to2/KeysetHandleChanges.java
+
+## STEP 3: Use error prone to create a patch:
+javac -cp "${tink_jar}:${errorprone_jar}" \
+           -XDcompilePolicy=byfile  \
+           -processorpath "${errorprone_jar}" \
+           "-Xplugin:ErrorProne -XepPatchChecks:refaster:${PWD}/tinkrule.refaster -XepPatchLocation:${PWD}" \
+           java/com/google/tinkuser/TinkUser.java
+
+cmp error-prone.patch expected-error-prone.patch
+```
diff --git a/java_src/tools/refaster/expected-error-prone.patch b/java_src/tools/refaster/expected-error-prone.patch
new file mode 100644
index 000000000..81f4b61aa
--- /dev/null
+++ b/java_src/tools/refaster/expected-error-prone.patch
@@ -0,0 +1,15 @@
+--- java/com/google/tinkuser/TinkUser.java
++++ java/com/google/tinkuser/TinkUser.java
+@@ -19,4 +19,5 @@
+ import com.google.crypto.tink.Aead;
+ import com.google.crypto.tink.KeysetHandle;
++import com.google.crypto.tink.TinkProtoKeysetFormat;
+ import java.security.GeneralSecurityException;
+ 
+@@ -24,5 +25,5 @@
+ public final class TinkUser {
+   public Aead useReadNoSecret(byte[] b) throws GeneralSecurityException {
+-    return KeysetHandle.readNoSecret(b).getPrimitive(Aead.class);
++    return TinkProtoKeysetFormat.parseKeysetWithoutSecret(b).getPrimitive(Aead.class);
+   }
+ }
diff --git a/java_src/tools/refaster/java/com/google/tink1to2/KeysetHandleChanges.java b/java_src/tools/refaster/java/com/google/tink1to2/KeysetHandleChanges.java
new file mode 100644
index 000000000..ffe3ac814
--- /dev/null
+++ b/java_src/tools/refaster/java/com/google/tink1to2/KeysetHandleChanges.java
@@ -0,0 +1,37 @@
+// Copyright 2023 Google LLC
+//
+// 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 com.google.tink1to2;
+
+import com.google.crypto.tink.KeysetHandle;
+import com.google.crypto.tink.TinkProtoKeysetFormat;
+import com.google.errorprone.refaster.annotation.AfterTemplate;
+import com.google.errorprone.refaster.annotation.BeforeTemplate;
+import java.security.GeneralSecurityException;
+
+final class KeysetHandleChanges {
+  class CleanupKeysetHandleReaderNoSecret {
+    @BeforeTemplate
+    public KeysetHandle beforeTemplate(byte[] b) throws GeneralSecurityException {
+      return KeysetHandle.readNoSecret(b);
+    }
+
+    @AfterTemplate
+    public KeysetHandle afterTemplate(byte[] b) throws GeneralSecurityException {
+      return TinkProtoKeysetFormat.parseKeysetWithoutSecret(b);
+    }
+  }
+}
diff --git a/java_src/tools/refaster/java/com/google/tinkuser/TinkUser.java b/java_src/tools/refaster/java/com/google/tinkuser/TinkUser.java
new file mode 100644
index 000000000..eda5ca015
--- /dev/null
+++ b/java_src/tools/refaster/java/com/google/tinkuser/TinkUser.java
@@ -0,0 +1,28 @@
+// Copyright 2023 Google LLC
+//
+// 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 com.google.tinkuser;
+
+import com.google.crypto.tink.Aead;
+import com.google.crypto.tink.KeysetHandle;
+import java.security.GeneralSecurityException;
+
+/** Example user code */
+public final class TinkUser {
+  public Aead useReadNoSecret(byte[] b) throws GeneralSecurityException {
+    return KeysetHandle.readNoSecret(b).getPrimitive(Aead.class);
+  }
+}