improve javadoc

Yubico · Jan 20, 2025 · 6e9ed5b · 6e9ed5b
1 parent 7492ae0
commit 6e9ed5b
Showing 1 changed file with 14 additions and 19 deletions.
diff --git a/core/src/main/java/com/yubico/yubikit/core/smartcard/scp/SecurityDomainSession.java b/core/src/main/java/com/yubico/yubikit/core/smartcard/scp/SecurityDomainSession.java
@@ -337,7 +337,8 @@ public void deleteKey(KeyRef keyRef, boolean deleteLast) throws ApduException, I
    * <p>Requires off-card entity verification.
    *
    * @param keyRef the KID-KVN pair to assign the new key
-   * @param replaceKvn 0 to generate a new keypair, non-zero to replace an existing KVN
+   * @param replaceKvn if 0x00, creates key with KVN from keyRef; if non-zero, replaces key with
+   *     KVN=replaceKvn
    * @return the public key from the generated key pair
    */
   public PublicKeyValues.Ec generateEcKey(KeyRef keyRef, int replaceKvn)
@@ -366,12 +367,10 @@ public PublicKeyValues.Ec generateEcKey(KeyRef keyRef, int replaceKvn)
    *
    * @param keyRef the KID-KVN pair to assign the new key set, KID must be 1
    * @param keys the key material to import
-   * @param kvn defines a Key Version Number and whether more PUT KEY commands will follow this one.
-   *     The kvn identifies a key or group of keys that is already present on the card. A value of
-   *     00 indicates that a new key or group of keys is being added. The kvn is coded from 0x01 to
-   *     0x7F.
+   * @param replaceKvn if 0x00, creates key with KVN from keyRef; if non-zero, replaces key with
+   *     KVN=replaceKvn
    */
-  public void putKey(KeyRef keyRef, StaticKeys keys, int kvn)
+  public void putKey(KeyRef keyRef, StaticKeys keys, int replaceKvn)
       throws ApduException, IOException, BadResponseException {
     Logger.debug(logger, "Importing SCP03 key set into {}", keyRef);
     if (keyRef.getKid() != ScpKid.SCP03) {
@@ -401,7 +400,7 @@ public void putKey(KeyRef keyRef, StaticKeys keys, int kvn)
 
     byte[] resp =
         protocol.sendAndReceive(
-            new Apdu(0x80, INS_PUT_KEY, kvn, 0x80 | keyRef.getKid(), data.array()));
+            new Apdu(0x80, INS_PUT_KEY, replaceKvn, 0x80 | keyRef.getKid(), data.array()));
     if (!MessageDigest.isEqual(resp, expected.array())) {
       throw new BadResponseException("Incorrect key check value");
     }
@@ -415,12 +414,10 @@ public void putKey(KeyRef keyRef, StaticKeys keys, int kvn)
    *
    * @param keyRef the KID-KVN pair to assign the new secret key, KID must be 0x11, 0x13, or 0x15
    * @param secretKey a private EC key used to authenticate the SD
-   * @param kvn defines a Key Version Number and whether more PUT KEY commands will follow this one.
-   *     The kvn identifies a key or group of keys that is already present on the card. A value of
-   *     00 indicates that a new key or group of keys is being added. The kvn is coded from 0x01 to
-   *     0x7F.
+   * @param replaceKvn if 0x00, creates key with KVN from keyRef; if non-zero, replaces key with
+   *     KVN=replaceKvn
    */
-  public void putKey(KeyRef keyRef, PrivateKeyValues secretKey, int kvn)
+  public void putKey(KeyRef keyRef, PrivateKeyValues secretKey, int replaceKvn)
       throws ApduException, IOException, BadResponseException {
     Logger.debug(logger, "Importing SCP11 private key into {}", keyRef);
     if (!(secretKey instanceof PrivateKeyValues.Ec)
@@ -448,7 +445,7 @@ public void putKey(KeyRef keyRef, PrivateKeyValues secretKey, int kvn)
 
     byte[] resp =
         protocol.sendAndReceive(
-            new Apdu(0x80, INS_PUT_KEY, kvn, keyRef.getKid(), data.toByteArray()));
+            new Apdu(0x80, INS_PUT_KEY, replaceKvn, keyRef.getKid(), data.toByteArray()));
     if (!MessageDigest.isEqual(resp, expected)) {
       throw new BadResponseException("Incorrect key check value");
     }
@@ -462,12 +459,10 @@ public void putKey(KeyRef keyRef, PrivateKeyValues secretKey, int kvn)
    *
    * @param keyRef the KID-KVN pair to assign the new public key
    * @param publicKey a public EC key used as CA to authenticate the off-card entity
-   * @param kvn defines a Key Version Number and whether more PUT KEY commands will follow this one.
-   *     The kvn identifies a key or group of keys that is already present on the card. A value of
-   *     00 indicates that a new key or group of keys is being added. The kvn is coded from 0x01 to
-   *     0x7F.
+   * @param replaceKvn if 0x00, creates key with KVN from keyRef; if non-zero, replaces key with
+   *     KVN=replaceKvn
    */
-  public void putKey(KeyRef keyRef, PublicKeyValues publicKey, int kvn)
+  public void putKey(KeyRef keyRef, PublicKeyValues publicKey, int replaceKvn)
       throws ApduException, IOException, BadResponseException {
     Logger.debug(logger, "Importing SCP11 public key into {}", keyRef);
     if (!(publicKey instanceof PublicKeyValues.Ec)
@@ -489,7 +484,7 @@ public void putKey(KeyRef keyRef, PublicKeyValues publicKey, int kvn)
 
     byte[] resp =
         protocol.sendAndReceive(
-            new Apdu(0x80, INS_PUT_KEY, kvn, keyRef.getKid(), data.toByteArray()));
+            new Apdu(0x80, INS_PUT_KEY, replaceKvn, keyRef.getKid(), data.toByteArray()));
     if (!MessageDigest.isEqual(resp, expected)) {
       throw new BadResponseException("Incorrect key check value");
     }