Package org.pgpainless.key.modification.secretkeyring

Interface SecretKeyRingEditorInterface

  • All Known Implementing Classes:
    SecretKeyRingEditor
    public interface SecretKeyRingEditorInterface

    • Method Detail

      • addUserId

        SecretKeyRingEditorInterface addUserId​(@Nonnull
                                       java.lang.CharSequence userId,
                                       @Nonnull
                                       SecretKeyRingProtector secretKeyRingProtector)
                                throws org.bouncycastle.openpgp.PGPException
        Add a user-id to the key ring.
        Parameters:
        userId - user-id
        secretKeyRingProtector - protector to unlock the secret key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a signature for the user-id

      • addUserId

        SecretKeyRingEditorInterface addUserId​(@Nonnull
                                       java.lang.CharSequence userId,
                                       @Nullable
                                       SelfSignatureSubpackets.Callback signatureSubpacketCallback,
                                       @Nonnull
                                       SecretKeyRingProtector protector)
                                throws org.bouncycastle.openpgp.PGPException
        Add a user-id to the key ring.
        Parameters:
        userId - user-id
        signatureSubpacketCallback - callback that can be used to modify signature subpackets of the certification signature.
        protector - protector to unlock the primary secret key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a signature for the user-id

      • addPrimaryUserId

        SecretKeyRingEditorInterface addPrimaryUserId​(@Nonnull
                                              java.lang.CharSequence userId,
                                              @Nonnull
                                              SecretKeyRingProtector protector)
                                       throws org.bouncycastle.openpgp.PGPException
        Add a user-id to the key ring and mark it as primary. If the user-id is already present, a new certification signature will be created.
        Parameters:
        userId - user id
        protector - protector to unlock the secret key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a signature for the user-id

      • removeUserId

        SecretKeyRingEditorInterface removeUserId​(SelectUserId userIdSelector,
                                          SecretKeyRingProtector protector)
                                   throws org.bouncycastle.openpgp.PGPException
        Convenience method to revoke selected user-ids using soft revocation signatures. The revocation will use RevocationAttributes.Reason.USER_ID_NO_LONGER_VALID, so that the user-id can be re-certified at a later point.
        Parameters:
        userIdSelector - selector to select user-ids
        protector - protector to unlock the primary key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • removeUserId

        SecretKeyRingEditorInterface removeUserId​(java.lang.CharSequence userId,
                                          SecretKeyRingProtector protector)
                                   throws org.bouncycastle.openpgp.PGPException
        Convenience method to revoke a single user-id using a soft revocation signature. The revocation will use RevocationAttributes.Reason.USER_ID_NO_LONGER_VALID. so that the user-id can be re-certified at a later point.
        Parameters:
        userId - user-id to revoke
        protector - protector to unlock the primary key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • replaceUserId

        SecretKeyRingEditorInterface replaceUserId​(java.lang.CharSequence oldUserId,
                                           java.lang.CharSequence newUserId,
                                           SecretKeyRingProtector protector)
                                    throws org.bouncycastle.openpgp.PGPException
        Replace a user-id on the key with a new one. The old user-id gets soft revoked and the new user-id gets bound with the same signature subpackets as the old one, with one exception: If the old user-id was implicitly primary (did not carry a PrimaryUserID packet, but effectively was primary, then the new user-id will be explicitly marked as primary.
        Parameters:
        oldUserId - old user-id
        newUserId - new user-id
        protector - protector to unlock the secret key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation and certification signature
        java.util.NoSuchElementException - if the old user-id was not found on the key; or if the oldUserId was already invalid

      • addSubKey

        SecretKeyRingEditorInterface addSubKey​(@Nonnull
                                       KeySpec keySpec,
                                       @Nonnull
                                       Passphrase subKeyPassphrase,
                                       @Nonnull
                                       SecretKeyRingProtector secretKeyRingProtector)
                                throws java.security.InvalidAlgorithmParameterException,
                                       java.security.NoSuchAlgorithmException,
                                       org.bouncycastle.openpgp.PGPException,
                                       java.io.IOException
        Add a subkey to the key ring. The subkey will be generated from the provided KeySpec.
        Parameters:
        keySpec - key specification
        subKeyPassphrase - passphrase to encrypt the sub key
        secretKeyRingProtector - protector to unlock the secret key of the key ring
        Returns:
        the builder
        Throws:
        java.security.InvalidAlgorithmParameterException - in case the user wants to use invalid parameters for the key
        java.security.NoSuchAlgorithmException - in case of missing algorithm support in the crypto backend
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a binding signature for the subkey
        java.io.IOException - in case of an IO error

      • addSubKey

        SecretKeyRingEditorInterface addSubKey​(@Nonnull
                                       KeySpec keySpec,
                                       @Nonnull
                                       Passphrase subkeyPassphrase,
                                       @Nullable
                                       SelfSignatureSubpackets.Callback subpacketsCallback,
                                       @Nonnull
                                       SecretKeyRingProtector secretKeyRingProtector)
                                throws org.bouncycastle.openpgp.PGPException,
                                       java.security.InvalidAlgorithmParameterException,
                                       java.security.NoSuchAlgorithmException,
                                       java.io.IOException
        Add a subkey to the key ring. The subkey will be generated from the provided KeySpec.
        Parameters:
        keySpec - key spec of the subkey
        subkeyPassphrase - passphrase to encrypt the subkey
        subpacketsCallback - callback to modify the subpackets of the subkey binding signature
        secretKeyRingProtector - protector to unlock the primary key
        Returns:
        builder
        Throws:
        java.security.InvalidAlgorithmParameterException - in case the user wants to use invalid parameters for the key
        java.security.NoSuchAlgorithmException - in case of missing algorithm support in the crypto backend
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a binding signature for the subkey
        java.io.IOException - in case of an IO error

      • addSubKey

        SecretKeyRingEditorInterface addSubKey​(@Nonnull
                                       org.bouncycastle.openpgp.PGPKeyPair subkey,
                                       @Nullable
                                       SelfSignatureSubpackets.Callback bindingSignatureCallback,
                                       @Nonnull
                                       SecretKeyRingProtector subkeyProtector,
                                       @Nonnull
                                       SecretKeyRingProtector primaryKeyProtector,
                                       @Nonnull
                                       KeyFlag keyFlag,
                                       KeyFlag... additionalKeyFlags)
                                throws org.bouncycastle.openpgp.PGPException,
                                       java.io.IOException,
                                       java.security.NoSuchAlgorithmException
        Add a subkey to the key ring.
        Parameters:
        subkey - subkey key pair
        bindingSignatureCallback - callback to modify the subpackets of the subkey binding signature
        subkeyProtector - protector to unlock and encrypt the subkey
        primaryKeyProtector - protector to unlock the primary key
        keyFlag - first key flag for the subkey
        additionalKeyFlags - optional additional key flags
        Returns:
        builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a binding signature for the subkey
        java.io.IOException - in case of an IO error
        java.security.NoSuchAlgorithmException - in case of missing algorithm support in the crypto backend

      • revoke

        default SecretKeyRingEditorInterface revoke​(@Nonnull
                                            SecretKeyRingProtector secretKeyRingProtector)
                                     throws org.bouncycastle.openpgp.PGPException
        Revoke the key ring. The revocation will be a hard revocation, rendering the whole key invalid for any past or future signatures.
        Parameters:
        secretKeyRingProtector - protector of the primary key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature

      • revoke

        SecretKeyRingEditorInterface revoke​(@Nonnull
                                    SecretKeyRingProtector secretKeyRingProtector,
                                    @Nullable
                                    RevocationAttributes revocationAttributes)
                             throws org.bouncycastle.openpgp.PGPException
        Revoke the key ring using the provided revocation attributes. The attributes define, whether the revocation was a hard revocation or not.
        Parameters:
        secretKeyRingProtector - protector of the primary key
        revocationAttributes - reason for the revocation
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature

      • revoke

        SecretKeyRingEditorInterface revoke​(@Nonnull
                                    SecretKeyRingProtector secretKeyRingProtector,
                                    @Nullable
                                    RevocationSignatureSubpackets.Callback subpacketsCallback)
                             throws org.bouncycastle.openpgp.PGPException
        Revoke the key ring. You can use the RevocationSignatureSubpackets.Callback to modify the revocation signatures subpackets, e.g. in order to define whether this is a hard or soft revocation.
        Parameters:
        secretKeyRingProtector - protector to unlock the primary secret key
        subpacketsCallback - callback to modify the revocations subpackets
        Returns:
        builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature

      • revokeSubKey

        default SecretKeyRingEditorInterface revokeSubKey​(@Nonnull
                                                  OpenPgpFingerprint fingerprint,
                                                  @Nonnull
                                                  SecretKeyRingProtector secretKeyRingProtector)
                                           throws org.bouncycastle.openpgp.PGPException
        Revoke the subkey binding signature of a subkey. The subkey with the provided fingerprint will be revoked. If no suitable subkey is found, a NoSuchElementException will be thrown. Note: This method will hard-revoke the provided subkey, meaning it cannot be re-certified at a later point. If you instead want to temporarily "deactivate" the subkey, provide a soft revocation reason, e.g. by calling revokeSubKey(OpenPgpFingerprint, SecretKeyRingProtector, RevocationAttributes) and provide a suitable RevocationAttributes object.
        Parameters:
        fingerprint - fingerprint of the subkey to be revoked
        secretKeyRingProtector - protector to unlock the secret key ring
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the subkey

      • revokeSubKey

        default SecretKeyRingEditorInterface revokeSubKey​(OpenPgpFingerprint fingerprint,
                                                  SecretKeyRingProtector secretKeyRingProtector,
                                                  RevocationAttributes revocationAttributes)
                                           throws org.bouncycastle.openpgp.PGPException
        Revoke the subkey binding signature of a subkey. The subkey with the provided fingerprint will be revoked. If no suitable subkey is found, a NoSuchElementException will be thrown.
        Parameters:
        fingerprint - fingerprint of the subkey to be revoked
        secretKeyRingProtector - protector to unlock the primary key
        revocationAttributes - reason for the revocation
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the subkey

      • revokeSubKey

        SecretKeyRingEditorInterface revokeSubKey​(long subKeyId,
                                          SecretKeyRingProtector secretKeyRingProtector,
                                          RevocationAttributes revocationAttributes)
                                   throws org.bouncycastle.openpgp.PGPException
        Revoke the subkey binding signature of a subkey. The subkey with the provided key-id will be revoked. If no suitable subkey is found, a NoSuchElementException will be thrown.
        Parameters:
        subKeyId - id of the subkey
        secretKeyRingProtector - protector to unlock the primary key
        revocationAttributes - reason for the revocation
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the subkey

      • revokeSubKey

        default SecretKeyRingEditorInterface revokeSubKey​(long subKeyId,
                                                  @Nonnull
                                                  SecretKeyRingProtector secretKeyRingProtector)
                                           throws org.bouncycastle.openpgp.PGPException
        Revoke the subkey binding signature of a subkey. The subkey with the provided key-id will be revoked. If no suitable subkey is found, q NoSuchElementException will be thrown. Note: This method will hard-revoke the subkey, meaning it cannot be re-bound at a later point. If you intend to re-bind the subkey in order to make it usable again at a later point in time, consider using revokeSubKey(long, SecretKeyRingProtector, RevocationAttributes) and provide a soft revocation reason.
        Parameters:
        subKeyId - id of the subkey
        secretKeyRingProtector - protector to unlock the secret key ring
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the subkey

      • revokeSubKey

        SecretKeyRingEditorInterface revokeSubKey​(long keyID,
                                          @Nonnull
                                          SecretKeyRingProtector secretKeyRingProtector,
                                          @Nullable
                                          RevocationSignatureSubpackets.Callback subpacketsCallback)
                                   throws org.bouncycastle.openpgp.PGPException
        Revoke the subkey binding signature of a subkey. The subkey with the provided key-id will be revoked. If no suitable subkey is found, q NoSuchElementException will be thrown. The provided subpackets callback is used to modify the revocation signatures subpackets.
        Parameters:
        keyID - id of the subkey
        secretKeyRingProtector - protector to unlock the secret key ring
        subpacketsCallback - callback which can be used to modify the subpackets of the revocation signature
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the subkey

      • revokeUserId

        default SecretKeyRingEditorInterface revokeUserId​(@Nonnull
                                                  java.lang.CharSequence userId,
                                                  @Nonnull
                                                  SecretKeyRingProtector secretKeyRingProtector)
                                           throws org.bouncycastle.openpgp.PGPException
        Revoke the given userID. The revocation will be a hard revocation, rendering the user-id invalid for any past or future signatures. If you intend to re-certify the user-id at a later point in time, consider using revokeUserId(CharSequence, SecretKeyRingProtector, RevocationAttributes) instead and provide a soft revocation reason.
        Parameters:
        userId - userId to revoke
        secretKeyRingProtector - protector to unlock the primary key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • revokeUserId

        SecretKeyRingEditorInterface revokeUserId​(@Nonnull
                                          java.lang.CharSequence userId,
                                          @Nonnull
                                          SecretKeyRingProtector secretKeyRingProtector,
                                          @Nullable
                                          RevocationAttributes revocationAttributes)
                                   throws org.bouncycastle.openpgp.PGPException
        Revoke the given userID using the provided revocation attributes.
        Parameters:
        userId - userId to revoke
        secretKeyRingProtector - protector to unlock the primary key
        revocationAttributes - reason for the revocation
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • revokeUserId

        SecretKeyRingEditorInterface revokeUserId​(@Nonnull
                                          java.lang.CharSequence userId,
                                          @Nonnull
                                          SecretKeyRingProtector secretKeyRingProtector,
                                          @Nullable
                                          RevocationSignatureSubpackets.Callback subpacketCallback)
                                   throws org.bouncycastle.openpgp.PGPException
        Revoke the provided user-id. Note: If you don't provide a RevocationSignatureSubpackets.Callback which sets a revocation reason (RevocationAttributes), the revocation might be considered hard. So if you intend to re-certify the user-id at a later point to make it valid again, make sure to set a soft revocation reason in the signatures hashed area using the subpacket callback.
        Parameters:
        userId - userid to be revoked
        secretKeyRingProtector - protector to unlock the primary secret key
        subpacketCallback - callback to modify the revocations subpackets
        Returns:
        builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • revokeUserIds

        SecretKeyRingEditorInterface revokeUserIds​(@Nonnull
                                           SelectUserId userIdSelector,
                                           @Nonnull
                                           SecretKeyRingProtector secretKeyRingProtector,
                                           @Nullable
                                           RevocationAttributes revocationAttributes)
                                    throws org.bouncycastle.openpgp.PGPException
        Revoke all user-ids that match the provided SelectUserId filter. The provided RevocationAttributes will be set as reason for revocation in each revocation signature. Note: If you intend to re-certify these user-ids at a later point, make sure to choose a soft revocation reason. See RevocationAttributes.Reason for more information.
        Parameters:
        userIdSelector - user-id selector
        secretKeyRingProtector - protector to unlock the primary secret key
        revocationAttributes - revocation attributes
        Returns:
        builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • revokeUserIds

        SecretKeyRingEditorInterface revokeUserIds​(@Nonnull
                                           SelectUserId userIdSelector,
                                           @Nonnull
                                           SecretKeyRingProtector secretKeyRingProtector,
                                           @Nullable
                                           RevocationSignatureSubpackets.Callback subpacketsCallback)
                                    throws org.bouncycastle.openpgp.PGPException
        Revoke all user-ids that match the provided SelectUserId filter. The provided RevocationSignatureSubpackets.Callback will be used to modify the revocation signatures subpackets. Note: If you intend to re-certify these user-ids at a later point, make sure to set a soft revocation reason in the revocation signatures hashed subpacket area using the callback. See RevocationAttributes.Reason for more information.
        Parameters:
        userIdSelector - user-id selector
        secretKeyRingProtector - protector to unlock the primary secret key
        subpacketsCallback - callback to modify the revocations subpackets
        Returns:
        builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature for the user-id

      • setExpirationDate

        SecretKeyRingEditorInterface setExpirationDate​(@Nullable
                                               java.util.Date expiration,
                                               @Nonnull
                                               SecretKeyRingProtector secretKeyRingProtector)
                                        throws org.bouncycastle.openpgp.PGPException
        Set the expiration date for the primary key of the key ring. If the key is supposed to never expire, then an expiration date of null is expected.
        Parameters:
        expiration - new expiration date or null
        secretKeyRingProtector - to unlock the secret key
        Returns:
        the builder
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a new self-signature with the changed expiration date

      • createRevocationCertificate

        org.bouncycastle.openpgp.PGPSignature createRevocationCertificate​(@Nonnull
                                                                  SecretKeyRingProtector secretKeyRingProtector,
                                                                  @Nullable
                                                                  RevocationAttributes revocationAttributes)
                                                           throws org.bouncycastle.openpgp.PGPException
        Create a detached revocation certificate, which can be used to revoke the whole key.
        Parameters:
        secretKeyRingProtector - protector to unlock the primary key.
        revocationAttributes - reason for the revocation
        Returns:
        revocation certificate
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation certificate

      • createRevocationCertificate

        org.bouncycastle.openpgp.PGPSignature createRevocationCertificate​(long subkeyId,
                                                                  @Nonnull
                                                                  SecretKeyRingProtector secretKeyRingProtector,
                                                                  @Nullable
                                                                  RevocationAttributes revocationAttributes)
                                                           throws org.bouncycastle.openpgp.PGPException
        Create a detached revocation certificate, which can be used to revoke the specified subkey.
        Parameters:
        subkeyId - id of the subkey to be revoked
        secretKeyRingProtector - protector to unlock the primary key.
        revocationAttributes - reason for the revocation
        Returns:
        revocation certificate
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation certificate

      • createRevocationCertificate

        org.bouncycastle.openpgp.PGPSignature createRevocationCertificate​(long subkeyId,
                                                                  @Nonnull
                                                                  SecretKeyRingProtector secretKeyRingProtector,
                                                                  @Nullable
                                                                  RevocationSignatureSubpackets.Callback certificateSubpacketsCallback)
                                                           throws org.bouncycastle.openpgp.PGPException
        Create a detached revocation certificate, which can be used to revoke the specified subkey.
        Parameters:
        subkeyId - id of the subkey to be revoked
        secretKeyRingProtector - protector to unlock the primary key.
        certificateSubpacketsCallback - callback to modify the subpackets of the revocation certificate.
        Returns:
        revocation certificate
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation certificate

      • createRevocationCertificate

        default org.bouncycastle.openpgp.PGPSignature createRevocationCertificate​(OpenPgpFingerprint subkeyFingerprint,
                                                                          SecretKeyRingProtector secretKeyRingProtector,
                                                                          @Nullable
                                                                          RevocationAttributes revocationAttributes)
                                                                   throws org.bouncycastle.openpgp.PGPException
        Create a detached revocation certificate, which can be used to revoke the specified subkey.
        Parameters:
        subkeyFingerprint - fingerprint of the subkey to be revoked
        secretKeyRingProtector - protector to unlock the primary key.
        revocationAttributes - reason for the revocation
        Returns:
        revocation certificate
        Throws:
        org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation certificate

      • changeSubKeyPassphraseFromOldPassphrase

        default SecretKeyRingEditorInterface.WithKeyRingEncryptionSettings changeSubKeyPassphraseFromOldPassphrase​(@Nonnull
                                                                                                           java.lang.Long keyId,
                                                                                                           @Nullable
                                                                                                           Passphrase oldPassphrase)
        Change the passphrase of a single subkey in the key ring. Note: While it is a valid use-case to have different passphrases per subKey, this is one of the reasons why OpenPGP sucks in practice.
        Parameters:
        keyId - id of the subkey
        oldPassphrase - old passphrase
        Returns:
        next builder step

      • done

        org.bouncycastle.openpgp.PGPSecretKeyRing done()
        Return the PGPSecretKeyRing.
        Returns:
        the key