1 /* Copyright 2018 Google LLC 2 * 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * https://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 package com.google.security.annotations; 16 17 import java.lang.annotation.Documented; 18 import java.lang.annotation.ElementType; 19 import java.lang.annotation.Retention; 20 import java.lang.annotation.RetentionPolicy; 21 import java.lang.annotation.Target; 22 23 import javax.crypto.Cipher; 24 25 /** 26 * This annotation is used to temporarily disable the InsecureCipherMode Error Prone checker while 27 * the violation is being reviewed by ISE. A comment including a tracking bug for the ongoing 28 * security review should accompany the annotation. If the specific use is deemed a valid exception 29 * after review, the annotation should be changed to @SuppressInsecureCipherModeCheckerReviewed. 30 * 31 * <p>A {@link Cipher} object is created using one of the overloads of the 32 * {@link Cipher#getInstance()} method. This method takes a specification of the transformer either 33 * as a triple "Algorithm/Mode/Padding" or just "Algorithm", using the provider's default settings. 34 * The InsecureCipherMode checker implemented in Error Prone flags all call sites of 35 * {@link Cipher#getInstance()}, where either the insecure ECB mode or the provider's default mode 36 * is used. This method annotation is used to suppress the Error Prone checker in use cases where an 37 * exception has been granted by ISE after proper review. The annotation is BUILD-visibility 38 * restricted and every use must be vetted by the ISE team. 39 * 40 * <p>Example of usage: 41 * <pre> 42 * {@code 43 * @SuppressInsecureCipherModeCheckerPendingReview // Tracking bug for the review: b/... 44 * private String decrypt(String[] input) { 45 * Cipher aesCipher = Cipher.getInstance("AES"); 46 * aesCipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(rawKeyMaterial, "AES")); 47 * // ... 48 * } 49 * } 50 * </pre> 51 * 52 * @author avenet@google.com (Arnaud J. Venet) 53 * 54 */ 55 @Documented 56 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.CONSTRUCTOR, 57 ElementType.LOCAL_VARIABLE}) 58 @Retention(RetentionPolicy.SOURCE) 59 public @interface SuppressInsecureCipherModeCheckerPendingReview {} 60