// Copyright 2022 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.crypto.tink; import static java.lang.annotation.ElementType.FIELD; import static java.lang.annotation.ElementType.LOCAL_VARIABLE; import static java.lang.annotation.ElementType.METHOD; import static java.lang.annotation.ElementType.TYPE; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** * Annotates methods and classes which access parts of keys. * *
In Tink, a key is a representation of a mathematical function (e.g. the function {@code * Encrypt}, or the function {@code Sign}). These functions typically require all fields in the * corresponding objects to be specified. A common mistake is to extract only parts of such a * description. This can lead to incompatibilities. * *
For example, suppose a user want to export an RSASSA-PSS key public key from Tink for use with * a different library. These keys consist of the modulus {@code n}, the public exponent {@code e}, * as well as the specification of two hash functions, and the length of salt used internally in the * algorithm. When exporting such a key, often users ignore the hash functions and the salt length. * However, this would be a mistake: even if it works at the moment, if later Tink is configured to * use a different hash function, and the resulting key is exported using such a method, the * signatures will not be compatible. * *
Hence, when users access a function which requires this annotation, they should ensure that * they will not get compatibility bugs in the future. In most cases, they probably should call the * other methods on the corresponding class too. * *
In order to use a function which calls such a method, the function using it has to be * annotated with {@code AccessesPartialKey}: * *
* class KeyExporter { * ... * {@literal @}AccessesPartialKey * public static SecretBytes exportHmacKey(HmacKey key) { * // The caller of this method can only handle keys without prefix, SHA256, 20 byte tags, * // and 32 byte keys. * if (key.getParameters().getVariant() != HmacParameters.Variant.NO_PREFIX || * key.getParameters().getHashType() != HMacParameters.Hash.SHA_256 || * key.getParameters().getTagSizeBytes() != 20 || * key.getParameters().getKeySizeBytes() != 32) { * throw new IllegalArgumentException("Parameters not supported by receiver."); * } * return key.getKeyBytes(); * } * } **/ @Target({TYPE, METHOD, FIELD, LOCAL_VARIABLE}) @Retention(RetentionPolicy.CLASS) public @interface AccessesPartialKey {}