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       * 
82       * @deprecated use {@link EncryptionProvider#createEncryptedCertificate(String, PrivateKey, String, String)}
83       */
84      EncryptedCertificate createEncryptedCertificate(String userName, PrivateKey privateKey, String appId);
85  
86      /**
87       * Create a new encrypted certificate for transmission to another application
88       * 
89       * @param userName the username to certify
90       * @param privateKey the private key of this application
91       * @param appId the ID of this application
92       * @param urlToSign the target URL of this request, or <code>null</code> for a v1 request
93       * @since 2.4
94       */
95      EncryptedCertificate createEncryptedCertificate(String userName, PrivateKey privateKey, String appId, String urlToSign);
96      
97      /**
98       * Convert an encoded private key into a PrivateKey instance
99       * 
100      * @param encodedForm
101      *            the byte-array representation of the key
102      * @return the object representation of the key
103      * @throws NoSuchAlgorithmException
104      *             if the algorithm to generate the keypair is not available
105      * @throws NoSuchProviderException
106      *             if no appropriate cryptographic provider is available
107      * @throws InvalidKeySpecException
108      *             if the encoded form does not contain a valid key
109      */
110     PrivateKey toPrivateKey(byte[] encodedForm) throws NoSuchAlgorithmException, InvalidKeySpecException, NoSuchProviderException;
111 
112     /**
113      * Convert an encoded public key into a PublicKey instance
114      * 
115      * @param encodedForm
116      *            the byte-array representation of the key
117      * @return the object representation of the key
118      * @throws NoSuchAlgorithmException
119      *             if the algorithm to generate the keypair is not available
120      * @throws NoSuchProviderException
121      *             if no appropriate cryptographic provider is available
122      * @throws InvalidKeySpecException
123      *             if the encoded form does not contain a valid key
124      */
125     PublicKey toPublicKey(byte[] encodedForm) throws NoSuchAlgorithmException, InvalidKeySpecException, NoSuchProviderException;
126 }