Interface SecretKeyRingEditorInterface

All Known Implementing Classes:
SecretKeyRingEditor

public interface SecretKeyRingEditorInterface
  • Method Details

    • getReferenceTime

      @Nonnull Date getReferenceTime()
      Return the editors reference time.
      Returns:
      reference time
    • addUserId

      SecretKeyRingEditorInterface addUserId(@Nonnull 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 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 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(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(CharSequence oldUserId, 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
      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 InvalidAlgorithmParameterException, NoSuchAlgorithmException, org.bouncycastle.openpgp.PGPException, 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:
      InvalidAlgorithmParameterException - in case the user wants to use invalid parameters for the key
      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
      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, InvalidAlgorithmParameterException, NoSuchAlgorithmException, 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:
      InvalidAlgorithmParameterException - in case the user wants to use invalid parameters for the key
      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
      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, IOException
      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
      IOException - in case of an IO error
    • 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 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 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 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 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
    • setExpirationDateOfSubkey

      SecretKeyRingEditorInterface setExpirationDateOfSubkey(@Nullable Date expiration, long keyId, @Nonnull SecretKeyRingProtector secretKeyRingProtector) throws org.bouncycastle.openpgp.PGPException
      Set the expiration date for the subkey identified by the given keyId to the given expiration date. If the key is supposed to never expire, then an expiration date of null is expected.
      Parameters:
      expiration - new expiration date of null
      keyId - id of the subkey
      secretKeyRingProtector - to unlock the secret key
      Returns:
      the builder
      Throws:
      org.bouncycastle.openpgp.PGPException - in case we cannot generate a new subkey-binding or self-signature with the changed expiration date
    • createMinimalRevocationCertificate

      org.bouncycastle.openpgp.PGPPublicKeyRing createMinimalRevocationCertificate(@Nonnull SecretKeyRingProtector secretKeyRingProtector, @Nullable RevocationAttributes keyRevocationAttributes) throws org.bouncycastle.openpgp.PGPException
      Create a minimal, self-authorizing revocation certificate, containing only the primary key and a revocation signature. This type of revocation certificates was introduced in OpenPGP v6. This method has no side effects on the original key and will leave it intact.
      Parameters:
      secretKeyRingProtector - protector to unlock the primary key.
      keyRevocationAttributes - reason for the revocation (key revocation)
      Returns:
      minimal revocation certificate
      Throws:
      org.bouncycastle.openpgp.PGPException - in case we cannot generate a revocation signature
    • createRevocation

      org.bouncycastle.openpgp.PGPSignature createRevocation(@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. The original key will not be modified by this method.
      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
    • createRevocation

      org.bouncycastle.openpgp.PGPSignature createRevocation(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. The original key will not be modified by this method.
      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
    • createRevocation

      org.bouncycastle.openpgp.PGPSignature createRevocation(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. The original key will not be modified by this method.
      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
    • createRevocation

      default org.bouncycastle.openpgp.PGPSignature createRevocation(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. The original key will not be modified by this method.
      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
    • changePassphraseFromOldPassphrase

      default SecretKeyRingEditorInterface.WithKeyRingEncryptionSettings changePassphraseFromOldPassphrase(@Nullable Passphrase oldPassphrase)
      Change the passphrase of the whole key ring.
      Parameters:
      oldPassphrase - old passphrase or null, if the key was unprotected
      Returns:
      next builder step
    • changePassphraseFromOldPassphrase

      SecretKeyRingEditorInterface.WithKeyRingEncryptionSettings changePassphraseFromOldPassphrase(@Nullable Passphrase oldPassphrase, @Nonnull KeyRingProtectionSettings oldProtectionSettings)
      Change the passphrase of the whole key ring.
      Parameters:
      oldPassphrase - old passphrase or null, if the key was unprotected
      oldProtectionSettings - custom settings for the old passphrase
      Returns:
      next builder step
    • changeSubKeyPassphraseFromOldPassphrase

      default SecretKeyRingEditorInterface.WithKeyRingEncryptionSettings changeSubKeyPassphraseFromOldPassphrase(@Nonnull 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
    • changeSubKeyPassphraseFromOldPassphrase

      SecretKeyRingEditorInterface.WithKeyRingEncryptionSettings changeSubKeyPassphraseFromOldPassphrase(@Nonnull Long keyId, @Nullable Passphrase oldPassphrase, @Nonnull KeyRingProtectionSettings oldProtectionSettings)
    • done

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