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;
035
036public interface OpenPgpKeyStore {
037
038    /**
039     * Return the {@link PGPPublicKeyRingCollection} containing all public keys of {@code owner} that are locally
040     * available.
041     * This method might return null.
042     *
043     * @param owner {@link BareJid} of the user we want to get keys from.
044     * @return {@link PGPPublicKeyRingCollection} of the user.
045     *
046     * @throws IOException IO is dangerous
047     * @throws PGPException PGP is brittle
048     */
049    PGPPublicKeyRingCollection getPublicKeysOf(BareJid owner) throws IOException, PGPException;
050
051    /**
052     * Return the {@link PGPSecretKeyRingCollection} containing all secret keys of {@code owner} which are locally
053     * available.
054     * This method might return null.
055     *
056     * @param owner {@link BareJid} of the user we want to get keys from.
057     * @return {@link PGPSecretKeyRingCollection} of the user.
058     *
059     * @throws IOException IO is dangerous
060     * @throws PGPException PGP is brittle
061     */
062    PGPSecretKeyRingCollection getSecretKeysOf(BareJid owner) throws IOException, PGPException;
063
064    /**
065     * Return the {@link PGPPublicKeyRing} of {@code owner} which contains the key described by {@code fingerprint}.
066     * This method might return null.
067     *
068     * @param owner {@link BareJid} of the keys owner
069     * @param fingerprint {@link OpenPgpV4Fingerprint} of a key contained in the key ring
070     * @return {@link PGPPublicKeyRing} which contains the key described by {@code fingerprint}.
071     *
072     * @throws IOException IO is dangerous
073     * @throws PGPException PGP is brittle
074     */
075    PGPPublicKeyRing getPublicKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
076
077    /**
078     * Return the {@link PGPSecretKeyRing} of {@code owner} which contains the key described by {@code fingerprint}.
079     * This method might return null.
080     *
081     * @param owner {@link BareJid} of the keys owner
082     * @param fingerprint {@link OpenPgpV4Fingerprint} of a key contained in the key ring
083     * @return {@link PGPSecretKeyRing} which contains the key described by {@code fingerprint}.
084     *
085     * @throws IOException IO is dangerous
086     * @throws PGPException PGP is brittle
087     */
088    PGPSecretKeyRing getSecretKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
089
090    /**
091     * Remove a {@link PGPPublicKeyRing} which contains the key described by {@code fingerprint} from the
092     * {@link PGPPublicKeyRingCollection} of {@code owner}.
093     *
094     * @param owner owner of the key ring
095     * @param fingerprint fingerprint of the key whose key ring will be removed.
096     *
097     * @throws IOException IO is dangerous
098     * @throws PGPException PGP is brittle
099     */
100    void deletePublicKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
101
102    /**
103     * Remove a {@link PGPSecretKeyRing} which contains the key described by {@code fingerprint} from the
104     * {@link PGPSecretKeyRingCollection} of {@code owner}.
105     *
106     * @param owner owner of the key ring
107     * @param fingerprint fingerprint of the key whose key ring will be removed.
108     *
109     * @throws IOException IO is dangerous
110     * @throws PGPException PGP is brittle
111     */
112    void deleteSecretKeyRing(BareJid owner, OpenPgpV4Fingerprint fingerprint) throws IOException, PGPException;
113
114    /**
115     * Generate a new {@link PGPSecretKeyRing} for {@code owner}.
116     * The key will have a user-id containing the users {@link BareJid} (eg. "xmpp:juliet@capulet.lit").
117     * This method MUST NOT return null.
118     *
119     * @param owner owner of the key ring.
120     * @return key ring
121     *
122     * @throws PGPException PGP is brittle
123     * @throws NoSuchAlgorithmException in case there is no {@link java.security.Provider} registered for the used
124     * OpenPGP algorithms.
125     * @throws NoSuchProviderException in case there is no suitable {@link java.security.Provider} registered.
126     * @throws InvalidAlgorithmParameterException in case an invalid algorithms configuration is used.
127     */
128    PGPSecretKeyRing generateKeyRing(BareJid owner) throws PGPException, NoSuchAlgorithmException, NoSuchProviderException, InvalidAlgorithmParameterException;
129
130    /**
131     * Import a {@link PGPSecretKeyRing} of {@code owner}.
132     * In case the key ring is already available locally, the keys are skipped.
133     *
134     * @param owner owner of the keys
135     * @param secretKeys secret keys
136     *
137     * @throws IOException IO is dangerous
138     * @throws PGPException PGP is brittle
139     * @throws MissingUserIdOnKeyException in case the secret keys are lacking a user-id with the owners jid.
140     */
141    void importSecretKey(BareJid owner, PGPSecretKeyRing secretKeys) throws IOException, PGPException, MissingUserIdOnKeyException;
142
143    /**
144     * Import a {@link PGPPublicKeyRing} of {@code owner}.
145     * In case the key ring is already available locally, the keys are skipped.
146     *
147     * @param owner owner of the keys
148     * @param publicKeys public keys
149     *
150     * @throws IOException IO is dangerous
151     * @throws PGPException PGP is brittle
152     * @throws MissingUserIdOnKeyException in case the public keys are lacking a user-id with the owners jid.
153     */
154    void importPublicKey(BareJid owner, PGPPublicKeyRing publicKeys) throws IOException, PGPException, MissingUserIdOnKeyException;
155
156    /**
157     * Return the last date on which keys of {@code contact} were fetched from PubSub.
158     * This method MUST NOT return null.
159     *
160     * @param contact contact in which we are interested.
161     * @return dates of last key fetching.
162     *
163     * @throws IOException IO is dangerous
164     */
165    Map<OpenPgpV4Fingerprint, Date> getPublicKeyFetchDates(BareJid contact) throws IOException;
166
167    /**
168     * Set the last date on which keys of {@code contact} were fetched from PubSub.
169     *
170     * @param contact contact in which we are interested.
171     * @param dates dates of last key fetching.
172     *
173     * @throws IOException IO is dangerous
174     */
175    void setPublicKeyFetchDates(BareJid contact, Map<OpenPgpV4Fingerprint, Date> dates) throws IOException;
176}