Annotation Type AccessesPartialKey


  • @Target({TYPE,METHOD,CONSTRUCTOR,FIELD,LOCAL_VARIABLE})
    @Retention(CLASS)
    public @interface AccessesPartialKey
    Annotates methods and classes which access parts of keys.

    In Tink, a key is a representation of a mathematical function (e.g. the function Encrypt, or the function 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 n, the public exponent 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 AccessesPartialKey:

       class KeyExporter {
          ...
          @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();
          }
       }