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 © 2017 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  string fingerprintSha256; ///< 512-bit SHA256, i.e. 64 hexa values separated by colons
68  ValidPeriod validPeriod;
69  boolean valid; ///< exists and valid content
70  CertificateType type;
71  boolean isUntrusted;
72  string verificationMessage;
73  StringList chainInfo;
74  boolean isSelfSigned;
75 };
76 
77 typedef sequence<Certificate> CertificateList;
78 
79 /**
80  * Manager of Certificates
81  */
82 interface Certificates {
83 
84  /**
85  * Obtain a list of certificates
86  *
87  * @param certificates - current list of certificates
88  * @param totalItems - count of all services on server (before the start/limit applied)
89  * @param query - conditions and limits. Included from weblib.
90  * @throws kerio::web::ApiException on error:
91  * -32001 Session expired. - "The user is not logged in."
92  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
93  */
94  void get(out CertificateList certificates, out long totalItems, in SearchQuery query);
95 
96  /**
97  * Renames certificate
98  *
99  * @param id - ID of certificate to rename
100  * @param name - new name of the certificate
101  * @throws kerio::web::ApiException on error:
102  * -32001 Session expired. - "The user is not logged in."
103  * 1002 No such entity. - "Unable to find certificate."
104  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
105  */
106  void setName(in KId id, in string name);
107 
108  /**
109  * Remove list of certificate records
110  *
111  * @param errors - error message list
112  * @param ids - list of identifiers of deleted user templates
113  * @throws kerio::web::ApiException on error:
114  * -32001 Session expired. - "The user is not logged in."
115  * 1002 No such entity. - "Certificate not found."
116  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
117  */
118  void remove(out ErrorList errors, in KIdList ids);
119 
120  /**
121  * Generate certificate.
122  *
123  * @see Control team has generateEx(), which supports subjectAltNames (unity).
124  *
125  * @param id - ID of generated certificate
126  * @param subject - properties specified by user
127  * @param name - name of the new certificate
128  * @param type - type of certificate to be generated, valid input is one of: InactiveCertificate/CertificateRequest/LocalAuthority
129  * @param period - time properties specified by user, not relevant for CertificateRequest
130  * @throws kerio::web::ApiException on error:
131  * -32001 Session expired. - "The user is not logged in."
132  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
133  * Invalid params. - "Unable to generate certificate, expiration date has already passed."
134  * Invalid params. - "Unable to generate certificate, properties are invalid."
135  */
136  void generate(out KId id, in NamedValueList subject, in string name, in CertificateType type, in ValidPeriod period);
137 
138  /**
139  * Get a list of countries.
140  *
141  * @param countries - list of countries (name and ISO 3166 code)
142  * @throws kerio::web::ApiException on error:
143  * -32001 Session expired. - "The user is not logged in."
144  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
145  */
146  void getCountryList(out NamedValueList countries);
147 
148  /**
149  * Import certificate in PEM format
150  *
151  * @param id - ID of generated certificate
152  * @param keyId - ID assigned to imported private key, @see importPrivateKey
153  * @param fileId - id of uploaded file
154  * @param name - name of the new certificate
155  * @param type - type of certificate to be imported, valid input is one of: InactiveCertificate/Authority/LocalAuthority
156  * @throws kerio::web::ApiException on error:
157  * -32001 Session expired. - "The user is not logged in."
158  * 1000 OperationFailed. - "Unable to import certificate, certificate already imported."
159  * 1000 OperationFailed. - "Unable to import certificate, key is not valid for imported certificate."
160  * 1000 OperationFailed. - "Unable to import certificate, it's not a Certificate Authority."
161  * 1002 No such entity. - "Unable to import certificate, key not found."
162  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
163  * Invalid params. - "Unable to import certificate, the content is invalid."
164  */
165  void importCertificate(out KId id, in KId keyId, in string fileId, in string name, in CertificateType type);
166 
167  /**
168  * Import private key. It generates ID, so it can be linked to Certificate content imported later, @see importCertificate
169  *
170  * @param keyId - generated ID for new key
171  * @param needPassword - true if private key is encrypted with password
172  * @param fileId - id of uploaded file
173  * @throws kerio::web::ApiException on error:
174  * -32001 Session expired. - "The user is not logged in."
175  * 1002 No such entity. - "Uploaded file does not exist."
176  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
177  * Invalid params. - "Unable to import private key, content is invalid."
178  */
179  void importPrivateKey(out KId keyId, out boolean needPassword, in string fileId);
180 
181  /**
182  * Try to parse imported private key. Need to be called, when @importPrivateKey returns needPassword == true.
183  *
184  * @param keyId - ID assigned to imported private key, @see importPrivateKey
185  * @param password - certificate password
186  * @throws kerio::web::ApiException on error:
187  * -32001 Session expired. - "The user is not logged in."
188  * 1000 OperationFailed. - "Unable to import certificate, key already decrypted."
189  * 1000 OperationFailed. - "Unable to import certificate, password is not valid."
190  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
191  * Invalid params. - "Unable to parse private key with given password!"
192  */
193  void unlockPrivateKey(in KId keyId, in string password);
194 
195  /**
196  * Export of certificate or certificate request
197  * Note: "export" is a keyword in C++, so name of the method must be changed: exportCertificate
198  *
199  * @param fileDownload - description of the output file
200  * @param id - ID of the certificate or certificate request
201  * @throws kerio::web::ApiException on error:
202  * -32001 Session expired. - "The user is not logged in."
203  * 1000 OperationFailed. - "Unable to export certificate."
204  * 1002 No such entity. - "Unable to find certificate."
205  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
206  */
207  void exportCertificate(out Download fileDownload, in KId id);
208 
209  /**
210  * Export of certificate or request privatekey
211  * Note: "export" is a keyword in C++, so the name of the method must be changed: exportPrivateKey
212  *
213  * @param fileDownload - description of the output file
214  * @param id - ID of the certificate or certificate request
215  * @throws kerio::web::ApiException on error:
216  * -32001 Session expired. - "The user is not logged in."
217  * 1000 OperationFailed. - "Unable to export certificate."
218  * 1002 No such entity. - "Unable to find certificate."
219  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
220  */
221  void exportPrivateKey(out Download fileDownload, in KId id);
222 
223  /**
224  * Obtain source (plain-text representation) of the certificate
225  *
226  * @param source - certificate in plain text
227  * @param id - global identifier
228  * @throws kerio::web::ApiException on error:
229  * -32001 Session expired. - "The user is not logged in."
230  * 1002 No such entity. - "Unable to find certificate."
231  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
232  */
233  void toSource(out string source, in KId id);
234 
235 };
236 
237 }; // module web
238 }; // module kerio