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 disable the InsecureCipherMode Error Prone checker after a proper 27 * review by ISE. A comment including a tracking bug for the security review should accompany the 28 * annotation. 29 * 30 * <p>A {@link Cipher} object is created using one of the overloads of the 31 * {@link Cipher#getInstance()} method. This method takes a specification of the transformer either 32 * as a triple "Algorithm/Mode/Padding" or just "Algorithm", using the provider's default settings. 33 * The InsecureCipherMode checker implemented in Error Prone flags all call sites of 34 * {@link Cipher#getInstance()}, where either the insecure ECB mode or the provider's default mode 35 * is used. This method annotation is used to suppress the Error Prone checker in use cases where an 36 * exception has been granted by ISE after proper review. The annotation is BUILD-visibility 37 * restricted and every use must be vetted by the ISE team. 38 * 39 * <p>Example of usage: 40 * <pre> 41 * {@code 42 * @SuppressInsecureCipherModeCheckerReviewed // Tracking bug for the review: b/... 43 * private String decrypt(String[] input) { 44 * Cipher aesCipher = Cipher.getInstance("AES"); 45 * aesCipher.init(Cipher.DECRYPT_MODE, new SecretKeySpec(rawKeyMaterial, "AES")); 46 * // ... 47 * } 48 * } 49 * </pre> 50 * 51 * @author avenet@google.com (Arnaud J. Venet) 52 * 53 */ 54 @Documented 55 @Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.CONSTRUCTOR, 56 ElementType.LOCAL_VARIABLE}) 57 @Retention(RetentionPolicy.SOURCE) 58 public @interface SuppressInsecureCipherModeCheckerReviewed {} 59