1 package com.atlassian.security.auth.trustedapps;
2
3 import com.atlassian.security.auth.trustedapps.ApplicationRetriever.RetrievalException;
4
5 import java.security.KeyPair;
6 import java.security.NoSuchAlgorithmException;
7 import java.security.NoSuchProviderException;
8 import java.security.PrivateKey;
9 import java.security.PublicKey;
10 import java.security.spec.InvalidKeySpecException;
11
12 /**
13 * Abstracts out the provision of encryption to the trusted app service. For two applications to communicate
14 * effectively, they <i>must</i> use the same encryption provider. In our experience, even using the same algorithms
15 * but different providers will cause issues.
16 * <p>
17 * This abstraction is mostly used in unit testing, to avoid having to bring up a fully-fledged crypto provider
18 */
19 public interface EncryptionProvider
20 {
21 /**
22 * Retrieve the application certificate from some other application, over HTTP. Will look for the certificate at
23 * <code>${baseUrl}/admin/appTrustCertificate</code>. TODO: document the exception policy
24 *
25 * @param baseUrl
26 * the base URL of the application to be queried
27 * @return the retrieved application certificate
28 * @throws RetrievalException
29 * if there are problems with the certificate retrieved from the remote server or the server cannot be
30 * contacted
31 * @throws RuntimeException
32 * if there are problems retrieving the certificate from the remote server
33 */
34 Application getApplicationCertificate(String baseUrl) throws RetrievalException;
35
36 /**
37 * Generate a new public/private key pair for an application
38 *
39 * @return a new public/private key pair
40 * @throws NoSuchAlgorithmException
41 * if the algorithm to generate the keypair is not available
42 * @throws NoSuchProviderException
43 * if no appropriate cryptographic provider is available
44 */
45 KeyPair generateNewKeyPair() throws NoSuchAlgorithmException, NoSuchProviderException;
46
47 /**
48 * Generate a unique 32 character String ID. The default implementation combines the local IP address, a secure
49 * random number, the current time, and the identity hashcode of a newly created object.
50 *
51 * @return a 32 character unique ID string
52 */
53 String generateUID();
54
55 /**
56 * Decode an encrypted certificate to retrieve its ApplicationCertificate
57 *
58 * @param encCert
59 * the encrypted certificate of the application
60 * @param publicKey
61 * the application's public key
62 * @param appId
63 * the application's ID
64 * @return the decrypted ApplicationCertificate
65 * @throws InvalidCertificateException
66 * if the certificate was malformed, or could not be decrypted
67 */
68 ApplicationCertificate decodeEncryptedCertificate(EncryptedCertificate encCert, PublicKey publicKey, String appId) throws InvalidCertificateException;
69
70 /**
71 * Create a new encrypted certificate for transmission to another application
72 *
73 * @param userName
74 * the username to certify
75 * @param privateKey
76 * the private key of this application
77 * @param appId
78 * the ID of this application
79 * @return
80 */
81 EncryptedCertificate createEncryptedCertificate(String userName, PrivateKey privateKey, String appId);
82
83 /**
84 * Convert an encoded private key into a PrivateKey instance
85 *
86 * @param encodedForm
87 * the byte-array representation of the key
88 * @return the object representation of the key
89 * @throws NoSuchAlgorithmException
90 * if the algorithm to generate the keypair is not available
91 * @throws NoSuchProviderException
92 * if no appropriate cryptographic provider is available
93 * @throws InvalidKeySpecException
94 * if the encoded form does not contain a valid key
95 */
96 PrivateKey toPrivateKey(byte[] encodedForm) throws NoSuchAlgorithmException, InvalidKeySpecException, NoSuchProviderException;
97
98 /**
99 * Convert an encoded public key into a PublicKey instance
100 *
101 * @param encodedForm
102 * the byte-array representation of the key
103 * @return the object representation of the key
104 * @throws NoSuchAlgorithmException
105 * if the algorithm to generate the keypair is not available
106 * @throws NoSuchProviderException
107 * if no appropriate cryptographic provider is available
108 * @throws InvalidKeySpecException
109 * if the encoded form does not contain a valid key
110 */
111 PublicKey toPublicKey(byte[] encodedForm) throws NoSuchAlgorithmException, InvalidKeySpecException, NoSuchProviderException;
112 }