Key construction in Tink for KeysetHandle

Question

The following lines show how to generate a key in Tink:

• keysetHandle=KeysetHandle.generateNew(AeadKeyTemplates.AES128_GCM)
• privateKeysetHandle = KeysetHandle.generateNew(SignatureKeyTemplates.ECDSA_P256)

Could you show me how to construct a key given the parameters such as key bytes and related parameters?

---

It is also possible to create a key by loading the parameters from JSON:

  String keysetFilename = "my_keyset.json";
  KeysetHandle keysetHandle = CleartextKeysetHandle.read(
          JsonKeysetReader.withFile(new File(keysetFilename)));

How is the key format in JSON defined?

Travis

@MaartenBodewes you can try: tinkey create-keyset --key-template AES128_GCM --out example.json and tinkey add-key --key-template ECDSA_P256 --in example.json --out example2.json or something like that. – Porker

Answer 1

Maarten Bodewes: would you mind tell us what wrong with the APIs, and how you think it should be changed? We're all ears for feedback.

Ursa Major: we don't want users to deal with keys directly, because it's easy to mess up. It's why we provide APIs that generate, persist and load keys. The Java HOWTO [1] shows how to do this.

It looks like you have an existing key, in some other format, that you want to use it with Tink. Tink's keys are stored in protobuf. Each key type is defined in its own protobuf. You can find all definitions at https://github.com/google/tink/tree/master/proto. Tink doesn't work with individual keys, but keysets which are also protobuf. You can convert existing keys to Tink's keysets by providing an implementation of KeysetReader. SignaturePemKeysetReader [2] is an example that converts certain PEM keys to Tink.

If you encounter any further issue, feel free to comment or email the mailing list at [email protected].

Hope that helps, Thai.

[1] https://github.com/google/tink/blob/master/docs/JAVA-HOWTO.md [2] https://github.com/google/tink/blob/master/java_src/src/main/java/com/google/crypto/tink/signature/SignaturePemKeysetReader.java

edit: update the second link.

Hector

how Tink should be used with Kubernetes secrets? – Porker

Answer 2

I've had a similar problem, but with HMAC in unit tests. Hope it helps.

Example JSON:

{
    "primaryKeyId": 2061245617,
    "key": [{
        "keyData": {
            "typeUrl": "type.googleapis.com/google.crypto.tink.HmacKey",
            "keyMaterialType": "SYMMETRIC",
            "value": "EgQIAxAgGiB9qbGjo1sA41kHHKbELAKmFzj3cNev0GJ3PpvhR00vuw=="
        },
        "outputPrefixType": "TINK",
        "keyId": 2061245617,
        "status": "ENABLED"
    }]
}

code used to generate it (Scala):

  import com.google.crypto.tink.mac.MacConfig
  MacConfig.register()

  def generate(): Unit = {
    import java.io.ByteArrayOutputStream
    import java.nio.charset.StandardCharsets
    import com.google.crypto.tink.mac.HmacKeyManager
    import com.google.crypto.tink.{CleartextKeysetHandle, JsonKeysetWriter, KeysetHandle}
    
    val generatedKeyset = KeysetHandle.generateNew(HmacKeyManager.hmacSha256Template())
    val output = new ByteArrayOutputStream
    CleartextKeysetHandle.write(generatedKeyset, JsonKeysetWriter.withOutputStream(output))
    println(output.toString(StandardCharsets.UTF_8))
  }
  generate()

Loading the JSON and usage:

import com.google.crypto.tink.{CleartextKeysetHandle, JsonKeysetReader}
val hmacKeyset = CleartextKeysetHandle.read(
    JsonKeysetReader.withString(...)
)
val mac = hmacKeyset.getPrimitive(classOf[Mac])
mac.computeMac(...)

Keep in mind this is totally insecure and should never be used outside tests.

---

Relevant parts of the implementation:

• JsonKeysetReader.keyFromJson
• hmac.proto
• MacIntegrationTest

---

EDIT: Even easier way to generate a keyset JSON:

$ tinkey create-keyset --key-template HMAC_SHA256_256BITTAG
{
    "primaryKeyId": 1132518908,
    "key": [{
        "keyData": {
            "typeUrl": "type.googleapis.com/google.crypto.tink.HmacKey",
            "keyMaterialType": "SYMMETRIC",
            "value": "EgQIAxAgGiDwIucBpWJ8WHVIEKIdEVQlfynm+4QS8sKUVUga2JzRlw=="
        },
        "outputPrefixType": "TINK",
        "keyId": 1132518908,
        "status": "ENABLED"
    }]
}

Populous