All Classes Files Functions Variables Enumerations Enumerator Groups Pages
Certificates.idl
Go to the documentation of this file.
1 /**
2  * @file Certificates.idl
3  * @brief %Certificates settings
4  *
5  * @author Dusan Juhas, Martin Kuchar, Tomas Chmelar
6  *
7  * @copyright Copyright © 2011-2012 Kerio Technologies s.r.o.
8  */
9 #import <kerio/web/idl/SharedStructures.idl>
10 #import <kerio/web/idl/TimeRanges.idl>
11 
12 module kerio {
13 module web {
14 
15 /**
16  * Certificate Time properties info
17  */
18 enum ValidType {
19  Valid,
20  NotValidYet,
21  ExpireSoon,
22  Expired
23 };
24 
25 /**
26  * Certificate Time properties
27  */
28 struct ValidPeriod {
29  Date validFromDate; ///< @see SharedStructures.idl shared in lib
30  Time validFromTime; ///< @see SharedStructures.idl shared in lib
31  Date validToDate; ///< @see SharedStructures.idl shared in lib
32  Time validToTime; ///< @see SharedStructures.idl shared in lib
33 
34  ValidType validType;
35 };
36 
37 enum CertificateType {
38  ActiveCertificate,
39  InactiveCertificate,
40  CertificateRequest,
41  Authority,
42  LocalAuthority,
43  BuiltInAuthority,
44  ServerCertificate
45 };
46 
47 /**
48  * Certificate properties
49  * issuer & subject valid names:
50  * hostname; ///< max 127 bytes
51  * organizationName; ///< max 127 bytes
52  * organizationalUnitName; ///< max 127 bytes
53  * city; ///< max 127 bytes
54  * state; ///< max 127 bytes
55  * country; ///< ISO 3166 code
56  * emailAddress; ///< max 255 bytes
57  */
58 struct Certificate {
59  KId id;
60  StoreStatus status;
61  string name;
62  NamedValueList issuer;
63  NamedValueList subject;
64  NamedMultiValueList subjectAlternativeNameList;
65  string fingerprint; ///< 128-bit MD5, i.e. 16 hexa values separated by colons
66  string fingerprintSha1; ///< 160-bit SHA1, i.e. 20 hexa values separated by colons
67  ValidPeriod validPeriod;
68  boolean valid; ///< exists and valid content
69  CertificateType type;
70  boolean isUntrusted;
71 };
72 
73 typedef sequence<Certificate> CertificateList;
74 
75 /**
76  * Manager of Certificates
77  */
78 interface Certificates {
79 
80  /**
81  * Obtain a list of certificates
82  *
83  * @param certificates - current list of certificates
84  * @param totalItems - count of all services on server (before the start/limit applied)
85  * @param query - conditions and limits. Included from weblib.
86  * @throws kerio::web::ApiException on error:
87  * -32001 Session expired. - "The user is not logged in."
88  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
89  */
90  void get(out CertificateList certificates, out long totalItems, in SearchQuery query);
91 
92  /**
93  * Renames certificate
94  *
95  * @param id - ID of certificate to rename
96  * @param name - new name of the certificate
97  * @throws kerio::web::ApiException on error:
98  * -32001 Session expired. - "The user is not logged in."
99  * 1002 No such entity. - "Unable to find certificate."
100  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
101  */
102  void setName(in KId id, in string name);
103 
104  /**
105  * Remove list of certificate records
106  *
107  * @param errors - error message list
108  * @param ids - list of identifiers of deleted user templates
109  * @throws kerio::web::ApiException on error:
110  * -32001 Session expired. - "The user is not logged in."
111  * 1002 No such entity. - "Certificate not found."
112  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
113  */
114  void remove(out ErrorList errors, in KIdList ids);
115 
116  /**
117  * Generate certificate.
118  *
119  * @see Control team has generateEx(), which supports subjectAltNames (unity).
120  *
121  * @param id - ID of generated certificate
122  * @param subject - properties specified by user
123  * @param name - name of the new certificate
124  * @param type - type of certificate to be generated, valid input is one of: InactiveCertificate/CertificateRequest/LocalAuthority
125  * @param period - time properties specified by user, not relevant for CertificateRequest
126  * @throws kerio::web::ApiException on error:
127  * -32001 Session expired. - "The user is not logged in."
128  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
129  * Invalid params. - "Unable to generate certificate, expiration date has already passed."
130  * Invalid params. - "Unable to generate certificate, properties are invalid."
131  */
132  void generate(out KId id, in NamedValueList subject, in string name, in CertificateType type, in ValidPeriod period);
133 
134  /**
135  * Get a list of countries.
136  *
137  * @param countries - list of countries (name and ISO 3166 code)
138  * @throws kerio::web::ApiException on error:
139  * -32001 Session expired. - "The user is not logged in."
140  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
141  */
142  void getCountryList(out NamedValueList countries);
143 
144  /**
145  * Import certificate in PEM format
146  *
147  * @param id - ID of generated certificate
148  * @param keyId - ID assigned to imported private key, @see importPrivateKey
149  * @param fileId - id of uploaded file
150  * @param name - name of the new certificate
151  * @param type - type of certificate to be imported, valid input is one of: InactiveCertificate/Authority/LocalAuthority
152  * @throws kerio::web::ApiException on error:
153  * -32001 Session expired. - "The user is not logged in."
154  * 1000 OperationFailed. - "Unable to import certificate, certificate already imported."
155  * 1000 OperationFailed. - "Unable to import certificate, key is not valid for imported certificate."
156  * 1000 OperationFailed. - "Unable to import certificate, it's not a Certificate Authority."
157  * 1002 No such entity. - "Unable to import certificate, key not found."
158  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
159  * Invalid params. - "Unable to import certificate, the content is invalid."
160  */
161  void importCertificate(out KId id, in KId keyId, in string fileId, in string name, in CertificateType type);
162 
163  /**
164  * Import private key. It generates ID, so it can be linked to Certificate content imported later, @see importCertificate
165  *
166  * @param keyId - generated ID for new key
167  * @param needPassword - true if private key is encrypted with password
168  * @param fileId - id of uploaded file
169  * @throws kerio::web::ApiException on error:
170  * -32001 Session expired. - "The user is not logged in."
171  * 1002 No such entity. - "Uploaded file does not exist."
172  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
173  * Invalid params. - "Unable to import private key, content is invalid."
174  */
175  void importPrivateKey(out KId keyId, out boolean needPassword, in string fileId);
176 
177  /**
178  * Try to parse imported private key. Need to be called, when @importPrivateKey returns needPassword == true.
179  *
180  * @param keyId - ID assigned to imported private key, @see importPrivateKey
181  * @param password - certificate password
182  * @throws kerio::web::ApiException on error:
183  * -32001 Session expired. - "The user is not logged in."
184  * 1000 OperationFailed. - "Unable to import certificate, key already decrypted."
185  * 1000 OperationFailed. - "Unable to import certificate, password is not valid."
186  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
187  * Invalid params. - "Unable to parse private key with given password!"
188  */
189  void unlockPrivateKey(in KId keyId, in string password);
190 
191  /**
192  * Export of certificate or certificate request
193  * Note: "export" is a keyword in C++, so name of the method must be changed: exportCertificate
194  *
195  * @param fileDownload - description of the output file
196  * @param id - ID of the certificate or certificate request
197  * @throws kerio::web::ApiException on error:
198  * -32001 Session expired. - "The user is not logged in."
199  * 1000 OperationFailed. - "Unable to export certificate."
200  * 1002 No such entity. - "Unable to find certificate."
201  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
202  */
203  void exportCertificate(out Download fileDownload, in KId id);
204 
205  /**
206  * Export of certificate or request privatekey
207  * Note: "export" is a keyword in C++, so the name of the method must be changed: exportPrivateKey
208  *
209  * @param fileDownload - description of the output file
210  * @param id - ID of the certificate or certificate request
211  * @throws kerio::web::ApiException on error:
212  * -32001 Session expired. - "The user is not logged in."
213  * 1000 OperationFailed. - "Unable to export certificate."
214  * 1002 No such entity. - "Unable to find certificate."
215  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
216  */
217  void exportPrivateKey(out Download fileDownload, in KId id);
218 
219  /**
220  * Obtain source (plain-text representation) of the certificate
221  *
222  * @param source - certificate in plain text
223  * @param id - global identifier
224  * @throws kerio::web::ApiException on error:
225  * -32001 Session expired. - "The user is not logged in."
226  * 1002 No such entity. - "Unable to find certificate."
227  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
228  */
229  void toSource(out string source, in KId id);
230 
231 };
232 
233 }; // module web
234 }; // module kerio