/** * * Copyright 2017 Florian Schmaus. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.jivesoftware.smackx.ox; import java.io.IOException; import java.security.InvalidAlgorithmParameterException; import java.security.NoSuchAlgorithmException; import java.security.NoSuchProviderException; import org.jivesoftware.smack.util.MultiMap; import org.jivesoftware.smackx.ox.callback.backup.SmackMissingOpenPgpPublicKeyCallback; import org.jivesoftware.smackx.ox.element.CryptElement; import org.jivesoftware.smackx.ox.element.OpenPgpContentElement; import org.jivesoftware.smackx.ox.element.OpenPgpElement; import org.jivesoftware.smackx.ox.element.SignElement; import org.jivesoftware.smackx.ox.element.SigncryptElement; import org.jivesoftware.smackx.ox.exception.MissingOpenPgpKeyPairException; import org.jivesoftware.smackx.ox.exception.MissingOpenPgpPublicKeyException; import org.jivesoftware.smackx.ox.exception.MissingUserIdOnKeyException; import org.jivesoftware.smackx.ox.exception.SmackOpenPgpException; import org.jivesoftware.smackx.ox.util.DecryptedBytesAndMetadata; import org.jivesoftware.smackx.ox.util.KeyBytesAndFingerprint; import org.jxmpp.jid.BareJid; public interface OpenPgpProvider { /** * Sign and encrypt a {@link SigncryptElement} element for usage within the context of instant messaging. * The resulting byte array can be decrypted by each recipient, as well as all devices of the user. * The message contains a signature made by our key. * * @see XEP-0373 §3 * @see XEP-0374 §2.1 * * @param element {@link SigncryptElement} which contains the content of the message as plaintext. * @param signingKey {@link OpenPgpV4Fingerprint} of the signing key. * @param encryptionKeys {@link MultiMap} containing all {@link OpenPgpV4Fingerprint}s of recipients which will * be able to decrypt the message. * @return encrypted and signed data which contains the encrypted, encoded message. * * @throws MissingOpenPgpKeyPairException if the OpenPGP key pair with the given {@link OpenPgpV4Fingerprint} * is not available. * @throws MissingOpenPgpPublicKeyException if any of the OpenPGP public keys whose {@link OpenPgpV4Fingerprint} * is listed in {@code encryptionKeys} is not available. * @throws SmackOpenPgpException in case of an OpenPGP error * @throws IOException IO is dangerous */ byte[] signAndEncrypt(SigncryptElement element, OpenPgpV4Fingerprint signingKey, MultiMap encryptionKeys) throws MissingOpenPgpKeyPairException, MissingOpenPgpPublicKeyException, SmackOpenPgpException, IOException; /** * Sign a {@link SignElement} with the users signing key. * The resulting byte array contains the signed byte representation of the {@link SignElement}. * * @see XEP-0373 §3.1 * @see XEP-0374 §2.1 * * @param element {@link SignElement} which will be signed. * @param singingKeyFingerprint {@link OpenPgpV4Fingerprint} of the key that is used for signing. * @return byte array which contains the signed {@link SignElement}. * * @throws MissingOpenPgpKeyPairException if we don't have the key pair for the * {@link OpenPgpV4Fingerprint} available. * @throws IOException IO is dangerous * @throws SmackOpenPgpException in case of an OpenPGP error */ byte[] sign(SignElement element, OpenPgpV4Fingerprint singingKeyFingerprint) throws MissingOpenPgpKeyPairException, IOException, SmackOpenPgpException; /** * Encrypt a {@link CryptElement} for all keys which fingerprints are contained in * {@code encryptionKeyFingerprints}. * The resulting byte array contains the encrypted {@link CryptElement} * which can be decrypted by all recipients, as well as by ourselves. *
* Note: DO NOT use this method in the context of instant messaging, as XEP-0374 forbids that. * * @see XEP-0374 §2.1 * * @param element plaintext {@link CryptElement} which will be encrypted. * @param encryptionKeyFingerprints {@link MultiMap} of recipients and {@link OpenPgpV4Fingerprint}s of the * keys which are used for encryption. * @return byte array which contains the encrypted {@link CryptElement}. * @throws MissingOpenPgpPublicKeyException if any of the OpenPGP public keys whose * {@link OpenPgpV4Fingerprint} is listed in {@code encryptionKeys} * is not available. * @throws IOException IO is dangerous * @throws SmackOpenPgpException in case of an OpenPGP error */ byte[] encrypt(CryptElement element, MultiMap encryptionKeyFingerprints) throws MissingOpenPgpPublicKeyException, IOException, SmackOpenPgpException; /** * Process an incoming {@link OpenPgpElement}. * If its content is encrypted ({@link CryptElement} or {@link SigncryptElement}), the content will be decrypted. * If its content is signed ({@link SignElement} or {@link SigncryptElement}), signatures are verified using * the announced public keys of the sender. * The resulting byte array will contain the decrypted {@link OpenPgpContentElement}. * * @see XEP-0373 §3.1 * * @param bytes byte array which contains the encrypted {@link OpenPgpContentElement}. * @param sender sender of the message * @param missingPublicKeyCallback callback to handle missing public keys * @return byte array which contains the decrypted {@link OpenPgpContentElement}, as well as metadata. * * @throws MissingOpenPgpKeyPairException if we don't have an OpenPGP key pair available that to decrypt * the message. * @throws SmackOpenPgpException in case of an OpenPGP error */ DecryptedBytesAndMetadata decrypt(byte[] bytes, BareJid sender, SmackMissingOpenPgpPublicKeyCallback missingPublicKeyCallback) throws MissingOpenPgpKeyPairException, SmackOpenPgpException; /** * Encrypt some data symmetrically using a password. * @param bytes data * @param password password * @return encrypted data * @throws SmackOpenPgpException in case of an OpenPGP error * @throws IOException IO is dangerous */ byte[] symmetricallyEncryptWithPassword(byte[] bytes, String password) throws SmackOpenPgpException, IOException; /** * Decrypt a symmetrically encrypted array of data using the provided password. * * @param bytes symmetrically encrypted data * @param password password for decryption * @return decrypted data * @throws SmackOpenPgpException if the password is incorrect * @throws IOException io is dangerous */ byte[] symmetricallyDecryptWithPassword(byte[] bytes, String password) throws SmackOpenPgpException, IOException; /** * Generate a fresh OpenPGP key pair. * * @param owner JID of the keys owner. * @return byte array representation + {@link OpenPgpV4Fingerprint} of the generated key pair. * @throws SmackOpenPgpException in case of an OpenPGP error * @throws InvalidAlgorithmParameterException if invalid algorithm parameters are used for crypto * @throws NoSuchAlgorithmException if the JVM is lacking support for a used algorithm * @throws NoSuchProviderException if the JVM is missing a security provider * @throws IOException IO is dangerous */ KeyBytesAndFingerprint generateOpenPgpKeyPair(BareJid owner) throws SmackOpenPgpException, InvalidAlgorithmParameterException, NoSuchAlgorithmException, NoSuchProviderException, IOException; /** * Import a public key. The bytes are expected to be decoded from base64. * * @param owner owner of the public key * @param bytes byte representation of the publick key * * @return fingerprint of the imported public key * * @throws MissingUserIdOnKeyException if the key is missing a user id with {@code owner}. * @throws IOException IO is dangerous * @throws SmackOpenPgpException if an OpenPGP error occurs */ OpenPgpV4Fingerprint importPublicKey(BareJid owner, byte[] bytes) throws MissingUserIdOnKeyException, IOException, SmackOpenPgpException; /** * Import a secret key. The bytes are expected to be decoded from base64. * * @param owner owner of the secret key * @param bytes byte representation of the secret key * * @return fingerprint of the imported secret key * * @throws MissingUserIdOnKeyException if the key is missing a user-id of {@code owner} * @throws SmackOpenPgpException in case of an OpenPGP error * @throws IOException IO is dangerous */ OpenPgpV4Fingerprint importSecretKey(BareJid owner, byte[] bytes) throws MissingUserIdOnKeyException, SmackOpenPgpException, IOException; /** * Import a secret key that belong to ourselves. * * @param bytes byte representation of the secret key. * * @return fingerprint of the imported secret key. * * @throws MissingUserIdOnKeyException if the secret key is missing a user-id with our jid * @throws SmackOpenPgpException in case of an OpenPGP error * @throws IOException IO is dangerous */ OpenPgpV4Fingerprint importSecretKey(byte[] bytes) throws MissingUserIdOnKeyException, SmackOpenPgpException, IOException; /** * Return the underlying {@link OpenPgpStore}. * @return store */ OpenPgpStore getStore(); }