Update documentation, add withKeyPassphrase(CharArray) methods

sop-java/src/main/kotlin/sop/operation/AbstractSign.kt

@@ -61,9 +61,18 @@ interface AbstractSign<T> {
      * @param password password
      * @return builder instance
      * @throws UnsupportedOption if key passwords are not supported
-     * @throws PasswordNotHumanReadable if the provided passphrase is not human-readable
      */
-    @Throws(UnsupportedOption::class, PasswordNotHumanReadable::class)
+    @Throws(UnsupportedOption::class)
+    fun withKeyPassword(password: CharArray): T = withKeyPassword(password.concatToString())
+
+    /**
+     * Provide the password for the secret key used for signing.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if key passwords are not supported
+     */
+    @Throws(UnsupportedOption::class)
     fun withKeyPassword(password: String): T = withKeyPassword(password.toByteArray(UTF8Util.UTF8))
 
     /**

sop-java/src/main/kotlin/sop/operation/Armor.kt

@@ -9,6 +9,7 @@ import java.io.InputStream
 import sop.Ready
 import sop.exception.SOPGPException.BadData
 
+/** Interface for armoring binary OpenPGP data. */
 interface Armor {
 
     /**

sop-java/src/main/kotlin/sop/operation/CertifyUserId.kt

@@ -7,35 +7,111 @@ package sop.operation
 import java.io.IOException
 import java.io.InputStream
 import sop.Ready
-import sop.exception.SOPGPException
+import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for issuing certifications over UserIDs on certificates. */
 interface CertifyUserId {
 
-    @Throws(SOPGPException.UnsupportedOption::class) fun noArmor(): CertifyUserId
+    /** Disable ASCII armor for the output. */
+    @Throws(UnsupportedOption::class) fun noArmor(): CertifyUserId
 
-    @Throws(SOPGPException.UnsupportedOption::class) fun userId(userId: String): CertifyUserId
+    /**
+     * Add a user-id that shall be certified on the certificates.
+     *
+     * @param userId user-id
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     */
+    @Throws(UnsupportedOption::class) fun userId(userId: String): CertifyUserId
 
-    @Throws(SOPGPException.PasswordNotHumanReadable::class, SOPGPException.UnsupportedOption::class)
+    /**
+     * Provide the password for the secret key used for signing.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if key passwords are not supported
+     */
+    @Throws(UnsupportedOption::class)
+    fun withKeyPassword(password: CharArray): CertifyUserId =
+        withKeyPassword(password.concatToString())
+
+    /**
+     * Provide the password for the secret key used for signing.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if key passwords are not supported
+     */
+    @Throws(UnsupportedOption::class)
     fun withKeyPassword(password: String): CertifyUserId =
         withKeyPassword(password.toByteArray(UTF8Util.UTF8))
 
-    @Throws(SOPGPException.PasswordNotHumanReadable::class, SOPGPException.UnsupportedOption::class)
+    /**
+     * Provide the password for the secret key used for signing.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if key passwords are not supported
+     * @throws PasswordNotHumanReadable if the provided password is not human-readable
+     */
+    @Throws(PasswordNotHumanReadable::class, UnsupportedOption::class)
     fun withKeyPassword(password: ByteArray): CertifyUserId
 
-    @Throws(SOPGPException.UnsupportedOption::class) fun noRequireSelfSig(): CertifyUserId
+    /**
+     * If this option is provided, it is possible to certify user-ids on certificates, which do not
+     * have a self-certification for the user-id. You can use this option to add pet-name
+     * certifications to certificates, e.g. "Mom".
+     *
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     */
+    @Throws(UnsupportedOption::class) fun noRequireSelfSig(): CertifyUserId
 
-    @Throws(SOPGPException.BadData::class, IOException::class, SOPGPException.KeyIsProtected::class)
-    fun keys(keys: InputStream): CertifyUserId
+    /**
+     * Provide signing keys for issuing the certifications.
+     *
+     * @param keys input stream containing one or more signing key
+     * @return builder instance
+     * @throws BadData if the keys cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class) fun keys(keys: InputStream): CertifyUserId
 
-    @Throws(SOPGPException.BadData::class, IOException::class, SOPGPException.KeyIsProtected::class)
+    /**
+     * Provide signing keys for issuing the certifications.
+     *
+     * @param keys byte array containing one or more signing key
+     * @return builder instance
+     * @throws BadData if the keys cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class)
     fun keys(keys: ByteArray): CertifyUserId = keys(keys.inputStream())
 
-    @Throws(
-        SOPGPException.BadData::class, IOException::class, SOPGPException.CertUserIdNoMatch::class)
+    /**
+     * Provide the certificates that you want to create certifications for.
+     *
+     * @param certs input stream containing the certificates
+     * @return object to require the certified certificates from
+     * @throws BadData if the certificates cannot be read
+     * @throws IOException if an IO error occurs
+     * @throws KeyIsProtected if one or more signing keys are passphrase protected and cannot be
+     *   unlocked
+     */
+    @Throws(BadData::class, IOException::class, CertUserIdNoMatch::class, KeyIsProtected::class)
     fun certs(certs: InputStream): Ready
 
-    @Throws(
-        SOPGPException.BadData::class, IOException::class, SOPGPException.CertUserIdNoMatch::class)
+    /**
+     * Provide the certificates that you want to create certifications for.
+     *
+     * @param certs byte array containing the certificates
+     * @return object to require the certified certificates from
+     * @throws BadData if the certificates cannot be read
+     * @throws IOException if an IO error occurs
+     * @throws KeyIsProtected if one or more signing keys are passphrase protected and cannot be
+     *   unlocked
+     */
+    @Throws(BadData::class, IOException::class, CertUserIdNoMatch::class, KeyIsProtected::class)
     fun certs(certs: ByteArray): Ready = certs(certs.inputStream())
 }

sop-java/src/main/kotlin/sop/operation/ChangeKeyPassword.kt

@@ -11,6 +11,7 @@ import sop.exception.SOPGPException.KeyIsProtected
 import sop.exception.SOPGPException.PasswordNotHumanReadable
 import sop.util.UTF8Util
 
+/** Interface for changing key passwords. */
 interface ChangeKeyPassword {
 
     /**
@@ -28,13 +29,8 @@ interface ChangeKeyPassword {
      * @param oldPassphrase old passphrase
      * @return builder instance
      */
-    @Throws(PasswordNotHumanReadable::class)
-    fun oldKeyPassphrase(oldPassphrase: ByteArray): ChangeKeyPassword =
-        try {
-            oldKeyPassphrase(UTF8Util.decodeUTF8(oldPassphrase))
-        } catch (e: CharacterCodingException) {
-            throw PasswordNotHumanReadable("Password MUST be a valid UTF8 string.")
-        }
+    fun oldKeyPassphrase(oldPassphrase: CharArray): ChangeKeyPassword =
+        oldKeyPassphrase(oldPassphrase.concatToString())
 
     /**
      * Provide a passphrase to unlock the secret key. This method can be provided multiple times to
@@ -47,21 +43,33 @@ interface ChangeKeyPassword {
     fun oldKeyPassphrase(oldPassphrase: String): ChangeKeyPassword
 
     /**
-     * Provide a passphrase to re-lock the secret key with. This method can only be used once, and
-     * all key material encountered will be encrypted with the given passphrase. If this method is
-     * not called, the key material will not be protected.
+     * Provide a passphrase to unlock the secret key. This method can be provided multiple times to
+     * provide separate passphrases that are tried as a means to unlock any secret key material
+     * encountered.
      *
-     * @param newPassphrase new passphrase
+     * @param oldPassphrase old passphrase
      * @return builder instance
+     * @throws PasswordNotHumanReadable if the old key passphrase is not human-readable
      */
     @Throws(PasswordNotHumanReadable::class)
-    fun newKeyPassphrase(newPassphrase: ByteArray): ChangeKeyPassword =
+    fun oldKeyPassphrase(oldPassphrase: ByteArray): ChangeKeyPassword =
         try {
-            newKeyPassphrase(UTF8Util.decodeUTF8(newPassphrase))
+            oldKeyPassphrase(UTF8Util.decodeUTF8(oldPassphrase))
         } catch (e: CharacterCodingException) {
             throw PasswordNotHumanReadable("Password MUST be a valid UTF8 string.")
         }
 
+    /**
+     * Provide a passphrase to re-lock the secret key with. This method can only be used once, and
+     * all key material encountered will be encrypted with the given passphrase. If this method is
+     * not called, the key material will not be protected.
+     *
+     * @param newPassphrase new passphrase
+     * @return builder instance
+     */
+    fun newKeyPassphrase(newPassphrase: CharArray): ChangeKeyPassword =
+        newKeyPassphrase(newPassphrase.concatToString())
+
     /**
      * Provide a passphrase to re-lock the secret key with. This method can only be used once, and
      * all key material encountered will be encrypted with the given passphrase. If this method is
@@ -72,6 +80,23 @@ interface ChangeKeyPassword {
      */
     fun newKeyPassphrase(newPassphrase: String): ChangeKeyPassword
 
+    /**
+     * Provide a passphrase to re-lock the secret key with. This method can only be used once, and
+     * all key material encountered will be encrypted with the given passphrase. If this method is
+     * not called, the key material will not be protected.
+     *
+     * @param newPassphrase new passphrase
+     * @return builder instance
+     * @throws PasswordNotHumanReadable if the passphrase is not human-readable
+     */
+    @Throws(PasswordNotHumanReadable::class)
+    fun newKeyPassphrase(newPassphrase: ByteArray): ChangeKeyPassword =
+        try {
+            newKeyPassphrase(UTF8Util.decodeUTF8(newPassphrase))
+        } catch (e: CharacterCodingException) {
+            throw PasswordNotHumanReadable("Password MUST be a valid UTF8 string.")
+        }
+
     /**
      * Provide the key material.
      *

sop-java/src/main/kotlin/sop/operation/Dearmor.kt

@@ -10,6 +10,7 @@ import sop.Ready
 import sop.exception.SOPGPException.BadData
 import sop.util.UTF8Util
 
+/** Interface for removing ASCII armor from OpenPGP data. */
 interface Dearmor {
 
     /**

sop-java/src/main/kotlin/sop/operation/Decrypt.kt

@@ -13,6 +13,7 @@ import sop.SessionKey
 import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for decrypting encrypted OpenPGP messages. */
 interface Decrypt {
 
     /**

sop-java/src/main/kotlin/sop/operation/DetachedSign.kt

@@ -11,6 +11,7 @@ import sop.SigningResult
 import sop.enums.SignAs
 import sop.exception.SOPGPException.*
 
+/** Interface for creating detached signatures over plaintext messages. */
 interface DetachedSign : AbstractSign<DetachedSign> {
 
     /**

sop-java/src/main/kotlin/sop/operation/DetachedVerify.kt

@@ -8,6 +8,7 @@ import java.io.IOException
 import java.io.InputStream
 import sop.exception.SOPGPException.BadData
 
+/** Interface for verifying detached OpenPGP signatures over plaintext messages. */
 interface DetachedVerify : AbstractVerify<DetachedVerify>, VerifySignatures {
 
     /**

sop-java/src/main/kotlin/sop/operation/Encrypt.kt

@@ -13,6 +13,7 @@ import sop.enums.EncryptAs
 import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for creating encrypted OpenPGP messages. */
 interface Encrypt {
 
     /**

sop-java/src/main/kotlin/sop/operation/ExtractCert.kt

@@ -9,6 +9,7 @@ import java.io.InputStream
 import sop.Ready
 import sop.exception.SOPGPException.BadData
 
+/** Interface for extracting certificates from OpenPGP keys. */
 interface ExtractCert {
 
     /**

sop-java/src/main/kotlin/sop/operation/GenerateKey.kt

@@ -10,6 +10,7 @@ import sop.Ready
 import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for generating OpenPGP keys. */
 interface GenerateKey {
 
     /**

sop-java/src/main/kotlin/sop/operation/InlineDetach.kt

@@ -10,6 +10,7 @@ import sop.ReadyWithResult
 import sop.Signatures
 import sop.exception.SOPGPException.BadData
 
+/** Interface for detaching inline signatures from OpenPGP messages. */
 interface InlineDetach {
 
     /**

sop-java/src/main/kotlin/sop/operation/InlineSign.kt

@@ -10,6 +10,7 @@ import sop.Ready
 import sop.enums.InlineSignAs
 import sop.exception.SOPGPException.*
 
+/** Interface for creating inline-signed OpenPGP messages. */
 interface InlineSign : AbstractSign<InlineSign> {
 
     /**

sop-java/src/main/kotlin/sop/operation/InlineVerify.kt

@@ -11,7 +11,7 @@ import sop.Verification
 import sop.exception.SOPGPException.BadData
 import sop.exception.SOPGPException.NoSignature
 
-/** API for verification of inline-signed messages. */
+/** Interface for verification of inline-signed messages. */
 interface InlineVerify : AbstractVerify<InlineVerify> {
 
     /**

sop-java/src/main/kotlin/sop/operation/ListProfiles.kt

@@ -6,7 +6,7 @@ package sop.operation
 
 import sop.Profile
 
-/** Subcommand to list supported profiles of other subcommands. */
+/** Interface to list supported profiles of other subcommands. */
 interface ListProfiles {
 
     /**

sop-java/src/main/kotlin/sop/operation/MergeCerts.kt

@@ -7,21 +7,58 @@ package sop.operation
 import java.io.IOException
 import java.io.InputStream
 import sop.Ready
-import sop.exception.SOPGPException
+import sop.exception.SOPGPException.*
 
+/** Interface for merging multiple copies of the same certificate into one. */
 interface MergeCerts {
 
-    @Throws(SOPGPException.UnsupportedOption::class) fun noArmor(): MergeCerts
+    /**
+     * Disable ASCII armor for the output certificate.
+     *
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     */
+    @Throws(UnsupportedOption::class) fun noArmor(): MergeCerts
 
-    @Throws(SOPGPException.BadData::class, IOException::class)
-    fun updates(updateCerts: InputStream): MergeCerts
+    /**
+     * Provide updated copies of the base certificate.
+     *
+     * @param updateCerts input stream containing an updated copy of the base cert
+     * @return builder instance
+     * @throws BadData if the update cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class) fun updates(updateCerts: InputStream): MergeCerts
 
-    @Throws(SOPGPException.BadData::class, IOException::class)
+    /**
+     * Provide updated copies of the base certificate.
+     *
+     * @param updateCerts byte array containing an updated copy of the base cert
+     * @return builder instance
+     * @throws BadData if the update cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class)
     fun updates(updateCerts: ByteArray): MergeCerts = updates(updateCerts.inputStream())
 
-    @Throws(SOPGPException.BadData::class, IOException::class)
-    fun baseCertificates(certs: InputStream): Ready
+    /**
+     * Provide the base certificate into which updates shall be merged.
+     *
+     * @param certs input stream containing the base OpenPGP certificate
+     * @return object to require the merged certificate from
+     * @throws BadData if the base certificate cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class) fun baseCertificates(certs: InputStream): Ready
 
-    @Throws(SOPGPException.BadData::class, IOException::class)
+    /**
+     * Provide the base certificate into which updates shall be merged.
+     *
+     * @param certs byte array containing the base OpenPGP certificate
+     * @return object to require the merged certificate from
+     * @throws BadData if the base certificate cannot be read
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, IOException::class)
     fun baseCertificates(certs: ByteArray): Ready = baseCertificates(certs.inputStream())
 }

sop-java/src/main/kotlin/sop/operation/RevokeKey.kt

@@ -4,12 +4,13 @@
 
 package sop.operation
 
+import java.io.IOException
 import java.io.InputStream
 import sop.Ready
-import sop.exception.SOPGPException.PasswordNotHumanReadable
-import sop.exception.SOPGPException.UnsupportedOption
+import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for creating certificate revocations. */
 interface RevokeKey {
 
     /**
@@ -25,9 +26,18 @@ interface RevokeKey {
      * @param password password
      * @return builder instance
      * @throws UnsupportedOption if the implementation does not support key passwords
-     * @throws PasswordNotHumanReadable if the password is not human-readable
      */
-    @Throws(UnsupportedOption::class, PasswordNotHumanReadable::class)
+    @Throws(UnsupportedOption::class)
+    fun withKeyPassword(password: CharArray): RevokeKey = withKeyPassword(password.concatToString())
+
+    /**
+     * Provide the decryption password for the secret key.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if the implementation does not support key passwords
+     */
+    @Throws(UnsupportedOption::class)
     fun withKeyPassword(password: String): RevokeKey =
         withKeyPassword(password.toByteArray(UTF8Util.UTF8))
 
@@ -42,7 +52,27 @@ interface RevokeKey {
     @Throws(UnsupportedOption::class, PasswordNotHumanReadable::class)
     fun withKeyPassword(password: ByteArray): RevokeKey
 
+    /**
+     * Provide the key that you want to revoke.
+     *
+     * @param bytes byte array containing the OpenPGP key
+     * @return object to require the revocation certificate from
+     * @throws BadData if the key cannot be read
+     * @throws KeyIsProtected if the key is protected and cannot be unlocked
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, KeyIsProtected::class, IOException::class)
     fun keys(bytes: ByteArray): Ready = keys(bytes.inputStream())
 
+    /**
+     * Provide the key that you want to revoke.
+     *
+     * @param keys input stream containing the OpenPGP key
+     * @return object to require the revocation certificate from
+     * @throws BadData if the key cannot be read
+     * @throws KeyIsProtected if the key is protected and cannot be unlocked
+     * @throws IOException if an IO error occurs
+     */
+    @Throws(BadData::class, KeyIsProtected::class, IOException::class)
     fun keys(keys: InputStream): Ready
 }

sop-java/src/main/kotlin/sop/operation/UpdateKey.kt

@@ -7,9 +7,10 @@ package sop.operation
 import java.io.IOException
 import java.io.InputStream
 import sop.Ready
-import sop.exception.SOPGPException
+import sop.exception.SOPGPException.*
 import sop.util.UTF8Util
 
+/** Interface for bringing an OpenPGP key up to date. */
 interface UpdateKey {
 
     /**
@@ -22,21 +23,39 @@ interface UpdateKey {
     /**
      * Allow key to be used for signing only. If this option is not present, the operation may add a
      * new, encryption-capable component key.
+     *
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
      */
-    @Throws(SOPGPException.UnsupportedOption::class) fun signingOnly(): UpdateKey
+    @Throws(UnsupportedOption::class) fun signingOnly(): UpdateKey
 
     /**
      * Do not allow adding new capabilities to the key. If this option is not present, the operation
      * may add support for new capabilities to the key.
+     *
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
      */
-    @Throws(SOPGPException.UnsupportedOption::class) fun noAddedCapabilities(): UpdateKey
+    @Throws(UnsupportedOption::class) fun noAddedCapabilities(): UpdateKey
 
     /**
      * Provide a passphrase for unlocking the secret key.
      *
      * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
      */
-    @Throws(SOPGPException.PasswordNotHumanReadable::class, SOPGPException.UnsupportedOption::class)
+    @Throws(UnsupportedOption::class)
+    fun withKeyPassword(password: CharArray): UpdateKey = withKeyPassword(password.concatToString())
+
+    /**
+     * Provide a passphrase for unlocking the secret key.
+     *
+     * @param password password
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     */
+    @Throws(UnsupportedOption::class)
     fun withKeyPassword(password: String): UpdateKey =
         withKeyPassword(password.toByteArray(UTF8Util.UTF8))
 
@@ -44,8 +63,11 @@ interface UpdateKey {
      * Provide a passphrase for unlocking the secret key.
      *
      * @param password password
+     * @return builder instance
+     * @throws PasswordNotHumanReadable if the password is not human-readable
+     * @throws UnsupportedOption if this option is not supported
      */
-    @Throws(SOPGPException.PasswordNotHumanReadable::class, SOPGPException.UnsupportedOption::class)
+    @Throws(PasswordNotHumanReadable::class, UnsupportedOption::class)
     fun withKeyPassword(password: ByteArray): UpdateKey
 
     /**
@@ -53,9 +75,12 @@ interface UpdateKey {
      * These certificates will be merged into the key.
      *
      * @param certs input stream of certificates
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     * @throws BadData if the certificate cannot be read
+     * @throws IOException if an IO error occurs
      */
-    @Throws(
-        SOPGPException.UnsupportedOption::class, SOPGPException.BadData::class, IOException::class)
+    @Throws(UnsupportedOption::class, BadData::class, IOException::class)
     fun mergeCerts(certs: InputStream): UpdateKey
 
     /**
@@ -63,9 +88,12 @@ interface UpdateKey {
      * These certificates will be merged into the key.
      *
      * @param certs binary certificates
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     * @throws BadData if the certificate cannot be read
+     * @throws IOException if an IO error occurs
      */
-    @Throws(
-        SOPGPException.UnsupportedOption::class, SOPGPException.BadData::class, IOException::class)
+    @Throws(UnsupportedOption::class, BadData::class, IOException::class)
     fun mergeCerts(certs: ByteArray): UpdateKey = mergeCerts(certs.inputStream())
 
     /**
@@ -73,12 +101,12 @@ interface UpdateKey {
      *
      * @param key input stream containing the key
      * @return handle to acquire the updated OpenPGP key from
+     * @throws BadData if the key cannot be read
+     * @throws IOException if an IO error occurs
+     * @throws KeyIsProtected if the key is passphrase protected and cannot be unlocked
+     * @throws PrimaryKeyBad if the primary key is bad (e.g. expired, too weak)
      */
-    @Throws(
-        SOPGPException.BadData::class,
-        IOException::class,
-        SOPGPException.KeyIsProtected::class,
-        SOPGPException.PrimaryKeyBad::class)
+    @Throws(BadData::class, IOException::class, KeyIsProtected::class, PrimaryKeyBad::class)
     fun key(key: InputStream): Ready
 
     /**
@@ -86,11 +114,11 @@ interface UpdateKey {
      *
      * @param key binary OpenPGP key
      * @return handle to acquire the updated OpenPGP key from
+     * @throws BadData if the key cannot be read
+     * @throws IOException if an IO error occurs
+     * @throws KeyIsProtected if the key is passphrase protected and cannot be unlocked
+     * @throws PrimaryKeyBad if the primary key is bad (e.g. expired, too weak)
      */
-    @Throws(
-        SOPGPException.BadData::class,
-        IOException::class,
-        SOPGPException.KeyIsProtected::class,
-        SOPGPException.PrimaryKeyBad::class)
+    @Throws(BadData::class, IOException::class, KeyIsProtected::class, PrimaryKeyBad::class)
     fun key(key: ByteArray): Ready = key(key.inputStream())
 }

sop-java/src/main/kotlin/sop/operation/ValidateUserId.kt

@@ -7,9 +7,9 @@ package sop.operation
 import java.io.IOException
 import java.io.InputStream
 import java.util.*
-import sop.exception.SOPGPException
+import sop.exception.SOPGPException.*
 
-/** Subcommand to validate UserIDs on certificates. */
+/** Interface to validate UserIDs on certificates. */
 interface ValidateUserId {
 
     /**
@@ -17,15 +17,16 @@ interface ValidateUserId {
      * e-mail address part of each correctly bound User ID. The rest of each correctly bound User ID
      * is ignored.
      *
-     * @return this
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
      */
-    @Throws(SOPGPException.UnsupportedOption::class) fun addrSpecOnly(): ValidateUserId
+    @Throws(UnsupportedOption::class) fun addrSpecOnly(): ValidateUserId
 
     /**
      * Set the UserID to validate. To match only the email address, call [addrSpecOnly].
      *
      * @param userId UserID or email address
-     * @return this
+     * @return builder instance
      */
     fun userId(userId: String): ValidateUserId
 
@@ -34,19 +35,22 @@ interface ValidateUserId {
      * if it was bound by an authoritative certificate.
      *
      * @param certs authoritative certificates
-     * @return this
+     * @return builder instance
+     * @throws BadData if the authority certificates cannot be read
+     * @throws IOException if an IO error occurs
      */
-    @Throws(SOPGPException.BadData::class, IOException::class)
-    fun authorities(certs: InputStream): ValidateUserId
+    @Throws(BadData::class, IOException::class) fun authorities(certs: InputStream): ValidateUserId
 
     /**
      * Add certificates, which act as authorities. The [userId] is only considered correctly bound,
      * if it was bound by an authoritative certificate.
      *
      * @param certs authoritative certificates
-     * @return this
+     * @return builder instance
+     * @throws BadData if the authority certificates cannot be read
+     * @throws IOException if an IO error occurs
      */
-    @Throws(SOPGPException.BadData::class, IOException::class)
+    @Throws(BadData::class, IOException::class)
     fun authorities(certs: ByteArray): ValidateUserId = authorities(certs.inputStream())
 
     /**
@@ -54,13 +58,12 @@ interface ValidateUserId {
      *
      * @param certs subject certificates
      * @return true if all subject certificates have a correct binding to the UserID.
-     * @throws SOPGPException.BadData if the subject certificates are malformed
+     * @throws BadData if the subject certificates are malformed
      * @throws IOException if a parser exception happens
-     * @throws SOPGPException.CertUserIdNoMatch if any subject certificate does not have a correctly
-     *   bound UserID that matches [userId].
+     * @throws CertUserIdNoMatch if any subject certificate does not have a correctly bound UserID
+     *   that matches [userId].
      */
-    @Throws(
-        SOPGPException.BadData::class, IOException::class, SOPGPException.CertUserIdNoMatch::class)
+    @Throws(BadData::class, IOException::class, CertUserIdNoMatch::class)
     fun subjects(certs: InputStream): Boolean
 
     /**
@@ -68,14 +71,20 @@ interface ValidateUserId {
      *
      * @param certs subject certificates
      * @return true if all subject certificates have a correct binding to the UserID.
-     * @throws SOPGPException.BadData if the subject certificates are malformed
+     * @throws BadData if the subject certificates are malformed
      * @throws IOException if a parser exception happens
-     * @throws SOPGPException.CertUserIdNoMatch if any subject certificate does not have a correctly
-     *   bound UserID that matches [userId].
+     * @throws CertUserIdNoMatch if any subject certificate does not have a correctly bound UserID
+     *   that matches [userId].
      */
-    @Throws(
-        SOPGPException.BadData::class, IOException::class, SOPGPException.CertUserIdNoMatch::class)
+    @Throws(BadData::class, IOException::class, CertUserIdNoMatch::class)
     fun subjects(certs: ByteArray): Boolean = subjects(certs.inputStream())
 
-    fun validateAt(date: Date): ValidateUserId
+    /**
+     * Provide a reference time for user-id validation.
+     *
+     * @param date reference time
+     * @return builder instance
+     * @throws UnsupportedOption if this option is not supported
+     */
+    @Throws(UnsupportedOption::class) fun validateAt(date: Date): ValidateUserId
 }

sop-java/src/main/kotlin/sop/operation/VerifySignatures.kt

@@ -10,6 +10,7 @@ import sop.Verification
 import sop.exception.SOPGPException.BadData
 import sop.exception.SOPGPException.NoSignature
 
+/** API handle for verifying signatures. */
 interface VerifySignatures {
 
     /**

sop-java/src/main/kotlin/sop/operation/Version.kt

@@ -10,6 +10,7 @@ import java.util.*
 import kotlin.jvm.Throws
 import sop.exception.SOPGPException
 
+/** Interface for acquiring version information about the SOP implementation. */
 interface Version {
 
     /**