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}