Improved the Javadoc

Author: ebourg

jsign-core/src/main/java/net/jsign/AuthenticodeSigner.java

@@ -76,7 +76,22 @@
 /**
  * Sign a file with Authenticode. Timestamping is enabled by default and relies
  * on the Sectigo server (http://timestamp.sectigo.com).
- * 
+ *
+ * <p>Example:</p>
+ * <pre>
+ * KeyStore keystore = new KeyStoreBuilder().keystore("keystore.p12").storepass("password").build();
+ *
+ * AuthenticodeSigner signer = new AuthenticodeSigner(keystore, "alias", "secret");
+ * signer.withProgramName("My Application")
+ * .withProgramURL("http://www.example.com")
+ * .withTimestamping(true)
+ * .withTimestampingAuthority("http://timestamp.sectigo.com");
+ *
+ * try (Signable file = Signable.of(new File("application.exe"))) {
+ * signer.sign(file);
+ * }
+ * </pre>
+ *
  * @author Emmanuel Bourg
  * @since 3.0
  */
@@ -536,6 +551,7 @@ protected CMSSignedData addNestedSignature(CMSSignedData primary, CMSSignedData
  * By default looks up the default identifier but also makes sure it includes
  * the algorithm parameters and if not includes a DER NULL in order to align
  * with what signtool currently does.
+ *
  * @param signatureAlgorithm to get the corresponding digest algorithm identifier for
  * @return an AlgorithmIdentifier for the digestAlgorithm and including parameters
  */

jsign-core/src/main/java/net/jsign/DigestAlgorithm.java

@@ -29,10 +29,20 @@
 * @since 1.3
 */
 public enum DigestAlgorithm {
+
+ /** MD5 Message-Digest Algorithm (128 bits) */
  MD5("MD5", TSPAlgorithms.MD5),
+
+ /** Secure Hash Algorithm 1 (160 bits) */
  SHA1("SHA-1", TSPAlgorithms.SHA1),
+
+ /** Secure Hash Algorithm 2 (256 bits) */
  SHA256("SHA-256", TSPAlgorithms.SHA256),
+
+ /** Secure Hash Algorithm 2 (384 bits) */
  SHA384("SHA-384", TSPAlgorithms.SHA384),
+
+ /** Secure Hash Algorithm 2 (512 bits) */
  SHA512("SHA-512", TSPAlgorithms.SHA512);
 
  /** The JCE name of the algorithm */

jsign-core/src/main/java/net/jsign/KeyStoreBuilder.java

@@ -68,10 +68,17 @@ String parameterName() {
  return parameterName;
  }
 
+ /**
+ * Sets the file containing the keystore.
+ */
  public KeyStoreBuilder keystore(File keystore) {
  return keystore(keystore.getPath());
  }
 
+ /**
+ * Sets the name of the resource containing the keystore. Either the path of the keystore file,
+ * the SunPKCS11 configuration file or the cloud keystore name depending on the type of keystore.
+ */
  public KeyStoreBuilder keystore(String keystore) {
  this.keystore = keystore;
  return this;
@@ -81,6 +88,11 @@ String keystore() {
  return keystore;
  }
 
+ /**
+ * Sets the password to access the keystore. The password can be loaded from a file by using the <code>file:</code>
+ * prefix followed by the path of the file, or from an environment variable by using the <code>env:</code> prefix
+ * followed by the name of the variable.
+ */
  public KeyStoreBuilder storepass(String storepass) {
  this.storepass = storepass;
  return this;
@@ -91,11 +103,20 @@ String storepass() {
  return storepass;
  }
 
+ /**
+ * Sets the type of the keystore.
+ */
  public KeyStoreBuilder storetype(KeyStoreType storetype) {
  this.storetype = storetype;
  return this;
  }
 
+ /**
+ * Sets the type of the keystore.
+ *
+ * @param storetype the type of the keystore
+ * @throws IllegalArgumentException if the type is not recognized
+ */
  public KeyStoreBuilder storetype(String storetype) {
  try {
  this.storetype = storetype != null ? KeyStoreType.valueOf(storetype) : null;
@@ -124,6 +145,11 @@ KeyStoreType storetype() {
  return storetype;
  }
 
+ /**
+ * Sets the password to access the private key. The password can be loaded from a file by using the <code>file:</code>
+ * prefix followed by the path of the file, or from an environment variable by using the <code>env:</code> prefix
+ * followed by the name of the variable.
+ */
  public KeyStoreBuilder keypass(String keypass) {
  this.keypass = keypass;
  return this;
@@ -134,10 +160,16 @@ String keypass() throws SignerException {
  return keypass;
  }
 
+ /**
+ * Sets the file containing the private key.
+ */
  public KeyStoreBuilder keyfile(String keyfile) {
  return keyfile(createFile(keyfile));
  }
 
+ /**
+ * Sets the file containing the private key.
+ */
  public KeyStoreBuilder keyfile(File keyfile) {
  this.keyfile = keyfile;
  return this;
@@ -147,10 +179,18 @@ File keyfile() {
  return keyfile;
  }
 
+ /**
+ * Sets the file containing the certificate chain.
+ * The certificate used for signing must be the first one.
+ */
  public KeyStoreBuilder certfile(String certfile) {
  return certfile(createFile(certfile));
  }
 
+ /**
+ * Sets the file containing the certificate chain.
+ * The certificate used for signing must be the first one.
+ */
  public KeyStoreBuilder certfile(File certfile) {
  this.certfile = certfile;
  return this;
@@ -234,6 +274,9 @@ public Provider provider() {
 
  /**
  * Builds the keystore.
+ *
+ * @throws IllegalArgumentException if the parameters are invalid
+ * @throws KeyStoreException if the keystore can't be loaded
  */
  public KeyStore build() throws KeyStoreException {
  validate();

jsign-core/src/main/java/net/jsign/KeyStoreType.java

@@ -134,7 +134,11 @@ void validate(KeyStoreBuilder params) {
  }
  },
 
- /** PKCS#11 hardware token */
+ /**
+ * PKCS#11 hardware token. The keystore parameter specifies either the name of the provider defined
+ * in <code>jre/lib/security/java.security</code> or the path to the
+ * <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/p11guide.html#Config">SunPKCS11 configuration file</a>.
+ */
  PKCS11(false, true, true) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -160,7 +164,13 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** OpenPGP card */
+ /**
+ * OpenPGP card. OpenPGP cards contain up to 3 keys, one for signing, one for encryption, and one for authentication.
+ * All of them can be used for code signing (except encryption keys based on an elliptic curve). The alias
+ * to select the key is either, <code>SIGNATURE</code>, <code>ENCRYPTION</code> or <code>AUTHENTICATION</code>.
+ * This keystore can be used with a Nitrokey (non-HSM models) or a Yubikey. It doesn't require any external library
+ * to be installed.
+ */
  OPENPGP(false, false, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -186,23 +196,36 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** OpenSC supported smart card */
+ /**
+ * OpenSC supported smart card.
+ * This keystore requires the installation of <a href="https://github.com/OpenSC/OpenSC">OpenSC</a>.
+ * If multiple devices are connected, the keystore parameter can be used to specify the name of the one to use.
+ */
  OPENSC(false, true, true) {
  @Override
  Provider getProvider(KeyStoreBuilder params) {
  return OpenSC.getProvider(params.keystore());
  }
  },
 
- /** Nitrokey HSM */
+ /**
+ * Nitrokey HSM. This keystore requires the installation of <a href="https://github.com/OpenSC/OpenSC">OpenSC</a>.
+ * Other Nitrokeys based on the OpenPGP card standard are also supported with this storetype, but an X.509
+ * certificate must be imported into the Nitrokey (using the gnupg writecert command). Keys without certificates
+ * are ignored. Otherwise the {@link #OPENPGP} type should be used.
+ */
  NITROKEY(false, true, true) {
  @Override
  Provider getProvider(KeyStoreBuilder params) {
  return OpenSC.getProvider(params.keystore() != null ? params.keystore() : "Nitrokey");
  }
  },
 
- /** YubiKey PIV */
+ /**
+ * YubiKey PIV. This keystore requires the ykcs11 library from the <a href="https://developers.yubico.com/yubico-piv-tool/">Yubico PIV Tool</a>
+ * to be installed at the default location. On Windows, the path to the library must be specified in the
+ * <code>PATH</code> environment variable.
+ */
  YUBIKEY(false, true, true) {
  @Override
  Provider getProvider(KeyStoreBuilder params) {
@@ -218,7 +241,18 @@ Set<String> getAliases(KeyStore keystore) throws KeyStoreException {
  }
  },
 
- /** AWS KMS */
+ /**
+ * AWS Key Management Service (KMS). AWS KMS stores only the private key, the certificate must be provided
+ * separately. The keystore parameter references the AWS region.
+ *
+ * <p>The AWS access key, secret key, and optionally the session token, are concatenated and used as
+ * the storepass parameter; if the latter is not provided, Jsign attempts to fetch the credentials from
+ * the environment variables (<code>AWS_ACCESS_KEY_ID</code>, <code>AWS_SECRET_ACCESS_KEY</code> and
+ * <code>AWS_SESSION_TOKEN</code>) or from the IMDSv2 service when running on an AWS EC2 instance.</p>
+ *
+ * <p>In any case, the credentials must allow the following actions: <code>kms:ListKeys</code>,
+ * <code>kms:DescribeKey</code> and <code>kms:Sign</code>.</p>
+ * */
  AWS(false, false, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -257,7 +291,11 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** Azure Key Vault */
+ /**
+ * Azure Key Vault. The keystore parameter specifies the name of the key vault, either the short name
+ * (e.g. <code>myvault</code>), or the full URL (e.g. <code>https://myvault.vault.azure.net</code>).
+ * The Azure API access token is used as the keystore password.
+ */
  AZUREKEYVAULT(false, true, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -275,7 +313,11 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** DigiCert ONE */
+ /**
+ * DigiCert ONE. Certificates and keys stored in the DigiCert ONE Secure Software Manager can be used directly
+ * without installing the DigiCert client tools. The API key, the PKCS#12 keystore holding the client certificate
+ * and its password are combined to form the storepass parameter: <code>&lt;api-key&gt;|&lt;keystore&gt;|&lt;password&gt;</code>.
+ */
  DIGICERTONE(false, true, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -291,7 +333,10 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** SSL.com eSigner */
+ /**
+ * SSL.com eSigner. The SSL.com username and password are used as the keystore password (<code>&lt;username&gt;|&lt;password&gt;</code>),
+ * and the base64 encoded TOTP secret is used as the key password.
+ */
  ESIGNER(false, true, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -317,7 +362,11 @@ boolean reuseKeyStorePassword() {
  }
  },
 
- /** Google Cloud KMS */
+ /**
+ * Google Cloud KMS. Google Cloud KMS stores only the private key, the certificate must be provided separately.
+ * The keystore parameter references the path of the keyring. The alias can specify either the full path of the key,
+ * or only the short name. If the version is omitted the most recent one will be picked automatically.
+ */
  GOOGLECLOUD(false, false, false) {
  @Override
  void validate(KeyStoreBuilder params) {
@@ -344,7 +393,12 @@ Provider getProvider(KeyStoreBuilder params) {
  }
  },
 
- /** HashiCorp Vault secrets engine (GCP only) */
+ /**
+ * HashiCorp Vault secrets engine (GCP only). Since Google Cloud KMS stores only the private key, the certificate
+ * must be provided separately. The keystore parameter references the URL of the HashiCorp Vault secrets engine
+ * (<code>https://vault.example.com/v1/gcpkms</code>). The alias specifies the name of the key in Vault and the key version
+ * in Google Cloud separated by a colon character (<code>mykey:1</code>).
+ */
  HASHICORPVAULT(false, false, false) {
  @Override
  void validate(KeyStoreBuilder params) {

jsign-core/src/main/java/net/jsign/asn1/authenticode/AuthenticodeTimeStampRequest.java

@@ -27,7 +27,7 @@
 /**
  * <pre>
  * TimeStampRequest ::= SEQUENCE {
- * countersignatureType OBJECT IDENTIFIER,
+ * countersignatureType OBJECT IDENTIFIER, // 1.3.6.1.4.1.311.3.2.1
  * attributes Attributes OPTIONAL, 
  * content ContentInfo
  * }

jsign-core/src/main/java/net/jsign/cat/CatalogFile.java

@@ -58,7 +58,6 @@ public class CatalogFile implements Signable {
  *
  * @param file the file to check
  * @return <code>true</code> if the file is a Windows catalog, <code>false</code> otherwise
- * @throws IOException if an I/O error occurs
  */
  public static boolean isCatalogFile(File file) {
  if (!file.exists() || !file.isFile()) {

jsign-core/src/main/java/net/jsign/jca/DigiCertOneSigningService.java

@@ -98,7 +98,7 @@ public String getName() {
  /**
  * Returns the certificate details
  *
- * @param alias the id of alias of the certificate
+ * @param alias the id or alias of the certificate
  */
  private Map<String, ?> getCertificateInfo(String alias) throws IOException {
  if (!certificates.containsKey(alias)) {

jsign-core/src/main/java/net/jsign/jca/HashiCorpVaultSigningService.java

@@ -33,7 +33,7 @@
 import net.jsign.DigestAlgorithm;
 
 /**
- * Signing service using the HashiCorp Vault API.
+ * Signing service using the HashiCorp Vault API. It supports the Google Cloud KMS secrets engine only.
  *
  * @see <a href="https://developer.hashicorp.com/vault/api-docs/secret/gcpkms">HashiCorp Vault API - Google Cloud KMS Secrets Engine</a>
  * @since 5.0

jsign-core/src/main/java/net/jsign/jca/OpenPGPCard.java

@@ -393,7 +393,7 @@ private ResponseAPDU transmit(CommandAPDU command) throws CardException {
  }
 
  /**
- * Get the OpenPGP card matching the specified name.
+ * Get the OpenPGP card.
  */
  public static OpenPGPCard getCard() throws CardException {
  killSmartCardDaemon();

jsign-core/src/main/java/net/jsign/jca/SigningServiceJcaProvider.java

@@ -26,6 +26,12 @@
 /**
  * JCA Provider using a signing service.
  *
+ * <p>Example:</p>
+ * <pre>
+ * Provider provider = new SigningServiceJcaProvider(new AzureKeyVaultSigningService(vault, token));
+ * KeyStore keystore = KeyStore.getInstance("AZUREKEYVAULT", provider);
+ * </pre>
+ *
  * @since 4.0
  */
 public class SigningServiceJcaProvider extends Provider {