001/**
002 *
003 * Copyright 2018 Paul Schaub.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.jivesoftware.smackx.ox.store.definition;
018
019import java.io.IOException;
020import java.security.InvalidAlgorithmParameterException;
021import java.security.NoSuchAlgorithmException;
022import java.security.NoSuchProviderException;
023import java.util.Date;
024import java.util.Map;
025
026import org.jivesoftware.smackx.ox.exception.MissingUserIdOnKeyException;
027
028import org.bouncycastle.openpgp.PGPException;
029import org.bouncycastle.openpgp.PGPPublicKeyRing;
030import org.bouncycastle.openpgp.PGPPublicKeyRingCollection;
031import org.bouncycastle.openpgp.PGPSecretKeyRing;
032import org.bouncycastle.openpgp.PGPSecretKeyRingCollection;
033import org.jxmpp.jid.BareJid;
034import org.pgpainless.key.OpenPgpV4Fingerprint;
035import org.pgpainless.key.collection.PGPKeyRing;
036
037public interface OpenPgpKeyStore {
038
039    /**
040     * Return the {@link PGPPublicKeyRingCollection} containing all public keys of {@code owner} that are locally
041     * available.
042     * This method might return null.
043     *
044     * @param owner {@link BareJid} of the user we want to get keys from.
045     * @return {@link PGPPublicKeyRingCollection} of the user.
046     *
047     * @throws IOException IO is dangerous
048     * @throws PGPException PGP is brittle
049     */
050    PGPPublicKeyRingCollection getPublicKeysOf(BareJid owner) throws IOException, PGPException;
051
052    /**
053     * Return the {@link PGPSecretKeyRingCollection} containing all secret keys of {@code owner} which are locally
054     * available.
055     * This method might return null.
056     *
057     * @param owner {@link BareJid} of the user we want to get keys from.
058     * @return {@link PGPSecretKeyRingCollection} of the user.
059     *
060     * @throws IOException IO is dangerous
061     * @throws PGPException PGP is brittle
062     */
063    PGPSecretKeyRingCollection getSecretKeysOf(BareJid owner) throws IOException, PGPException;
064
065    /**
066     * Return the {@link PGPPublicKeyRing} of {@code owner} which contains the key described by {@code fingerprint}.
067     * This method might return null.
068     *
069     * @param owner {@link BareJid} of the keys owner
070     * @param fingerprint {@link OpenPgpV4Fingerprint} of a key contained in the key ring
071     * @return {@link PGPPublicKeyRing} which contains the key described by {@code fingerprint}.
072     *
073     * @throws IOException IO is dangerous
074     * @throws PGPException PGP is brittle
075     */
076    PGPPublicKeyRing getPublicKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
077
078    /**
079     * Return the {@link PGPSecretKeyRing} of {@code owner} which contains the key described by {@code fingerprint}.
080     * This method might return null.
081     *
082     * @param owner {@link BareJid} of the keys owner
083     * @param fingerprint {@link OpenPgpV4Fingerprint} of a key contained in the key ring
084     * @return {@link PGPSecretKeyRing} which contains the key described by {@code fingerprint}.
085     *
086     * @throws IOException IO is dangerous
087     * @throws PGPException PGP is brittle
088     */
089    PGPSecretKeyRing getSecretKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
090
091    /**
092     * Remove a {@link PGPPublicKeyRing} which contains the key described by {@code fingerprint} from the
093     * {@link PGPPublicKeyRingCollection} of {@code owner}.
094     *
095     * @param owner owner of the key ring
096     * @param fingerprint fingerprint of the key whose key ring will be removed.
097     *
098     * @throws IOException IO is dangerous
099     * @throws PGPException PGP is brittle
100     */
101    void deletePublicKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
102
103    /**
104     * Remove a {@link PGPSecretKeyRing} which contains the key described by {@code fingerprint} from the
105     * {@link PGPSecretKeyRingCollection} of {@code owner}.
106     *
107     * @param owner owner of the key ring
108     * @param fingerprint fingerprint of the key whose key ring will be removed.
109     *
110     * @throws IOException IO is dangerous
111     * @throws PGPException PGP is brittle
112     */
113    void deleteSecretKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
114
115    /**
116     * Generate a new {@link PGPKeyRing} for {@code owner}.
117     * The key will have a user-id containing the users {@link BareJid} (eg. "xmpp:juliet@capulet.lit").
118     * This method MUST NOT return null.
119     *
120     * @param owner owner of the key ring.
121     * @return key ring
122     *
123     * @throws PGPException PGP is brittle
124     * @throws NoSuchAlgorithmException in case there is no {@link java.security.Provider} registered for the used
125     * OpenPGP algorithms.
126     * @throws NoSuchProviderException in case there is no suitable {@link java.security.Provider} registered.
127     * @throws InvalidAlgorithmParameterException in case an invalid algorithms configuration is used.
128     */
129    PGPKeyRing generateKeyRing(BareJid owner) throws PGPException, NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException;
130
131    /**
132     * Import a {@link PGPSecretKeyRing} of {@code owner}.
133     * In case the key ring is already available locally, the keys are skipped.
134     *
135     * @param owner owner of the keys
136     * @param secretKeys secret keys
137     *
138     * @throws IOException IO is dangerous
139     * @throws PGPException PGP is brittle
140     * @throws MissingUserIdOnKeyException in case the secret keys are lacking a user-id with the owners jid.
141     */
142    void importSecretKey(BareJid owner, PGPSecretKeyRing secretKeys) throws IOException, PGPException, MissingUserIdOnKeyException;
143
144    /**
145     * Import a {@link PGPPublicKeyRing} of {@code owner}.
146     * In case the key ring is already available locally, the keys are skipped.
147     *
148     * @param owner owner of the keys
149     * @param publicKeys public keys
150     *
151     * @throws IOException IO is dangerous
152     * @throws PGPException PGP is brittle
153     * @throws MissingUserIdOnKeyException in case the public keys are lacking a user-id with the owners jid.
154     */
155    void importPublicKey(BareJid owner, PGPPublicKeyRing publicKeys) throws IOException, PGPException, MissingUserIdOnKeyException;
156
157    /**
158     * Return the last date on which keys of {@code contact} were fetched from PubSub.
159     * This method MUST NOT return null.
160     *
161     * @param contact contact in which we are interested.
162     * @return dates of last key fetching.
163     *
164     * @throws IOException IO is dangerous
165     */
166    Map<OpenPgpV4Fingerprint, Date> getPublicKeyFetchDates(BareJid contact) throws IOException;
167
168    /**
169     * Set the last date on which keys of {@code contact} were fetched from PubSub.
170     *
171     * @param contact contact in which we are interested.
172     * @param dates dates of last key fetching.
173     *
174     * @throws IOException IO is dangerous
175     */
176    void setPublicKeyFetchDates(BareJid contact, Map<OpenPgpV4Fingerprint, Date> dates) throws IOException;
177}