Bad hyperlink, typos, possible small errors in "Introduction to Java Encryption/Decryption" tutorial ( https://dev.java/learn/security/intro/ )

[willy-b]

Hello dev.java team!

Thanks again for all this excellent content. To contribute back, I am reporting the typos/bad hyperlinks and other such issues I have found as usual.

---

In the latest version of https://dev.java/learn/security/intro/ (archived as is at https://web.archive.org/web/20260712074541/https://dev.java/learn/security/intro/ )

• In the sentence

  Given the algorithm selected, the KeyPairGenerator object uses a 3072-bit key size
  and a random number initialized via the SecureRandom class:

  "SecureRandom" links to https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/security/KeyPairGenerator.html ,
  when it should instead link to https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/security/SecureRandom.html .

• In the sentences

  Asymmetrical encryption uses a pair of mathematical related keys, one for encryption and the other for decryption.
  In the example bellow Key1 is used for encryption and Key2 is used for decryption.

  "Asymmetrical encryption" should probably be "asymmetric encryption" (the latter is the typical term and compare to e.g. Oracle's upstream documentation at https://docs.oracle.com/en/java/javase/26/security/java-security-overview1.html#:~:text=Asymmetric%20encryption ),
  "mathematical related keys" should be "mathematically related keys",
  and "In the example bellow" should be "In the example below" ("bellow" should be "below").

• In the "Implementing Basic Asymmetric Encryption/Decryption" example,
  Was the method "generateRSAKKeyPair" intended to be "generateRSAKeyPair"?
  (the "KKey" instead of "Key" seems unintentional)

• In the sentence

  Electronic handling contracts or archives with highly sensitive information are valid real-world examples.

  "Electronic handling contracts" may have been intended to be "Electronically handling contracts".

• In the sentence

  Usually, encryption or decryption processes are based on algorithms publicly available, but the control to the data is obtained using a secured key.

  "algorithms publicly available" is a less common phrasing than "publicly available algorithms",
  and the meaning of "control to the data" may be unclear.
  Just a humble suggestion, but it may be useful to invoke a named principle here so that readers who are not familiar can do additional research as necessary, by quoting
  "Kerckhoffs's principle [...which] holds that a cryptosystem should be secure, even if everything about the system, except the key, is public knowledge." ( https://en.wikipedia.org/w/index.php?title=Kerckhoffs%27s_principle&oldid=1361573367 ).

• In the sentence

  You can use a hash function to map an arbitrary sized set of bytes into a finite size of a relatively unique set of bytes.

  "map an arbitrary sized set of bytes into a finite size of a relatively unique set of bytes" should probably be "map an arbitrarily large input data byte sequence to a fixed length, relatively unique, output byte sequence"
  or something similar as the inputs/outputs are not set-typed.

• In the sentence

  You can increase security by introducing an additional cryptographic variance using an initialization vector (IV) for encryption of plaintext BLOCK sequence.

  When using the term initialization vector, it seems this might be clearer if moved up to the paragraph on encryption/decryption, and instead of being mentioned later at the end of the paragraph on hashing, as
  https://docs.oracle.com/en/java/javase/26/docs/api/java.base/javax/crypto/Cipher.html#init(int,java.security.Key,java.security.AlgorithmParameters) , https://docs.oracle.com/en/java/javase/26/docs/api/java.base/javax/crypto/spec/IvParameterSpec.html are used to initialize Cipher ( https://docs.oracle.com/en/java/javase/26/docs/api/java.base/javax/crypto/Cipher.html ) , NOT MessageDigest ( https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/security/MessageDigest.html) to my understanding. Maybe if this was moved up to the paragraph on encryption/decryption, then when mentioning the use of "salt" for hashing in this subsequent paragraph salt can be noted as analogous to the use of the initialization vector with encryption/decryption to maintain the existing connection between the concepts.

• In the symmetric cryptography example, the encrypted ciphertext is printed by using byte[] toString:

  // Encrypt the message using the symmetric key
  byte[] cipherText = encrypt(plainText, symmetricKey, iv);
  
  IO.println("The encrypted message is: " + cipherText);
  

  which produces output like [B@421faab1 (from Object.toString(): getClass().getName() + '@' + Integer.toHexString(hashCode())).
  It would be more useful to actually show the encrypted String data, not its hashcode, and that is what is done in the subsequent example.
  Thus the IO.println above should probably be replaced with:

IO.println("The encrypted message is: " + HexFormat.of().formatHex(cipherText));

(this would also be consistent with how ciphertext is printed in later examples)
which would print the full ciphertext hex-encoded as "bbe01eb98d135368893d8c5d4a33f98d" .

• In the text

  you can write a small program to simulate how asymmetrical encryption and decryption works

  "asymmetrical encryption" was probably intended to be "asymmetric encryption" (the latter is the typical term and compare to e.g. Oracle's upstream documentation at https://docs.oracle.com/en/java/javase/26/security/java-security-overview1.html#:~:text=Asymmetric%20encryption )

• (Nit, optional) In the sentence

  Its goals are to offer cryptography algorithm independence and extensibility, interoperability, and an implementation agnostic from security providers.

  "agnostic from security providers" might be clearer as "agnostic about security providers" ("agnostic about" is the much more frequent phrasing).

• In the code example demonstrating digital signatures

  Below you can find a sample call that would make use of the above methods:

  public static void main(String[] args) throws Exception{
   byte[] digitalSignature = generateDigitalSignature(plainText.getBytes(), keypair.getPrivate());
   IO.println("Signature Value: " + HexFormat.of().formatHex(digitalSignature));
   IO.println("Verification: " + verify(plainText.getBytes(), digitalSignature, keypair.getPublic()));
  }
  

  the example seems to be incomplete, unlike the prior examples, as keypair and plainText are undeclared.

  Since the prior examples all are compilable (provided one puts all the snippets for a given example into an enclosing class and imports the referenced classes),
  I suspect the omitted declarations here were unintentional. The full main method could be updated as follows for a complete copy-pasteable example (when combined with other snippets provided):

  public static void main(String[] args) throws Exception {
   KeyPair keypair = generateRSAKeyPair();
   Scanner message = new Scanner(System.in);
   IO.print("Enter the message you want to digitally sign using RSA: ");  
   String plainText = message.nextLine();
   message.close();
   byte[] digitalSignature = generateDigitalSignature(plainText.getBytes(), keypair.getPrivate());
   IO.println("Signature Value: " + HexFormat.of().formatHex(digitalSignature));
   IO.println("Verification: " + verify(plainText.getBytes(), digitalSignature, keypair.getPublic()));
  }
  

---

Thanks very much!

[willy-b]

(Noting the example ciphertext I gave bbe01eb98d135368893d8c5d4a33f98d is only to illustrate the format; the actual ciphertext will vary each run due to random key and other randomness. Same with the expected byte[].toString() output I gave, [B@421faab1 (from Object.toString(): getClass().getName() + '@' + Integer.toHexString(hashCode()) which is the format that the code the dev.java team has currently provided would show for the ciphertext in the symmetric encryption example (which appears unintentional). I am suggesting the full ciphertext hex format consistent with later examples be used again, not that the specific result numbers should be the preceding.)