Legrand / Raritan / Server Technology Xerus™ JSON-RPC API
Loading...
Searching...
No Matches
ServerSSLCert.idl
1/* SPDX-License-Identifier: BSD-3-Clause */
2/*
3 * Copyright 2010 Raritan Inc. All rights reserved.
4 */
5
6/**
7 * TLS Certificate Management
8 */
9module cert {
10
11 /** TLS certificate management interface */
12 interface ServerSSLCert {
13
14 /** success code */
15 constant int SUCCESS = 0;
16
17 /** shared error codes */
18 constant int ERR_BUSY = 1;
19 constant int ERR_CSR_OR_CERT_PENDING = 101;
20 constant int ERR_KEY_MISSING = 200;
21 constant int ERR_CERT_MISSING = 201;
22 constant int ERR_CERT_FORMAT_INVALID = 202;
23 constant int ERR_CERT_KEY_MISMATCH = 203;
24 constant int ERR_KEY_FORMAT_INVALID = 204;
25
26 /** key-pair generation specific error codes */
27 constant int ERR_GEN_KEY_LEN_INVALID = 100;
28 constant int ERR_GEN_CSR_OR_CERT_PENDING = 101; ///< same as ERR_CSR_OR_CERT_PENDING
29 constant int ERR_GEN_KEY_GEN_FAILED = 102;
30 constant int ERR_GEN_KEY_TYPE_INVALID = 103;
31 constant int ERR_GEN_ELLIPTIC_CURVE_INVALID = 104;
32 constant int ERR_GEN_VALIDITY_OUT_OF_RANGE = 105;
33
34 /** key-pair installation specific error codes (backward compatibility) */
35 constant int ERR_INSTALL_KEY_MISSING = 200; ///< same as ERR_KEY_MISSING
36 constant int ERR_INSTALL_CERT_MISSING = 201; ///< same as ERR_CERT_MISSING
37 constant int ERR_INSTALL_CERT_FORMAT_INVALID = 202; ///< same as ERR_CERT_FORMAT_INVALID
38 constant int ERR_INSTALL_CERT_KEY_MISMATCH = 203; ///< same as ERR_CERT_KEY_MISMATCH
39 constant int ERR_INSTALL_KEY_FORMAT_INVALID = 204; ///> same as ERR_KEY_FORMAT_INVALID
40
41 /** Certificate issuer or subject attributes */
42 structure CommonAttributes {
43 string country; ///< Country code
44 string stateOrProvince; ///< State or province
45 string locality; ///< Locality or city
46 string organization; ///< Organization
47 string organizationalUnit; ///< Organizational Unit
48 string commonName; ///< Common Name
49 string emailAddress; ///< Email Address
50 };
51
52 /** Supported key types */
53 enumeration KeyType {
54 KEY_TYPE_UNKNOWN, ///< Key type unknown (only allowed as return value)
55 KEY_TYPE_RSA, ///< RSA key
56 KEY_TYPE_ECDSA ///< ECDSA key
57 };
58
59 /** Supported elliptic curves for key type ECDSA */
60 enumeration EllipticCurve {
61 EC_CURVE_UNKNOWN, ///< Curve unknown (only allowed as return value)
62 EC_CURVE_NIST_P256, ///< NIST curve P-256 (also known as secp256r1 and prime256v1)
63 EC_CURVE_NIST_P384, ///< NIST curve P-384 (also known as secp384r1)
64 EC_CURVE_NIST_P521 ///< NIST curve P-521 (also known as secp521r1)
65 };
66
67 /** Public key information */
68 structure KeyInfo {
69 KeyType type; ///< Key type
70 EllipticCurve ecCurve; ///< Selected elliptic curve (only relevant if key type is ECDSA)
71 int rsaKeyLength; ///< Length of the RSA key in bits (only relevant if key type is RSA)
72 boolean inSecureElement; ///< \c true if located in a Secure Element
73 };
74
75 /**
76 * Certificate signing request information
77 *
78 * If names is empty then commonName from the subject is used as single entry.
79 */
80 structure ReqInfo {
81 CommonAttributes subject; ///< Certificate subject attributes
82 vector<string> names; ///< DNS names and/or IP addresses
83 KeyInfo keyInfo; ///< Key information
84 };
85
86 /** Certificate information */
87 structure CertInfo {
88 CommonAttributes subject; ///< Subject attributes
89 CommonAttributes issuer; ///< Issuer attributes
90 vector<string> names; ///< DNS names and/or IP addresses
91 string invalidBefore; ///< Begin of validity period
92 string invalidAfter; ///< End of validity period
93 string serialNumber; ///< Serial number
94 KeyInfo keyInfo; ///< Key information
95 };
96
97 /** Certificate manager information */
98 structure Info {
99 boolean havePendingReq; ///< \c true if a CSR is pending
100 boolean havePendingCert; ///< \c true if an uploaded certificate is pending activation
101 ReqInfo pendingReqInfo; ///< Information about pending CSR
102 CertInfo pendingCertInfo; ///< Information about pending certificate file (device certificate)
103 vector<CertInfo> pendingCertChainInfos; ///< Information about pending certificate file (remaining certificate chain if available)
104 CertInfo activeCertInfo; ///< Information about active certificate file (device certificate)
105 vector<CertInfo> activeCertChainInfos; ///< Information about active certificate file (remaining certificate chain if available)
106 int maxSignDays; ///< Maximum number of days a self signed certificate will be valid.
107 };
108
109 /**
110 * Get all supported key variants.
111 *
112 * @return Vector of KeyInfo structures representing all supported key variants
113 */
114 vector<KeyInfo> getSupportedKeyInfos();
115
116 /**
117 * Generate an unsigned key pair.
118 *
119 * @param reqInfo Certificate signing request information
120 * @param challenge Challenge password
121 *
122 * @return SUCCESS or one of the error code constants
123 */
124 int generateUnsignedKeyPair(in ReqInfo reqInfo, in string challenge);
125
126 /**
127 * Generate a self-signed key pair.
128 *
129 * @param reqInfo Certificate signing request information
130 * @param days Number of days the certificate will be valid
131 *
132 * @return SUCCESS or one of the error code constants
133 */
134 int generateSelfSignedKeyPair(in ReqInfo reqInfo, in int days);
135
136 /**
137 * Remove pending key and certificate signing request or certificate.
138 */
140
141 /**
142 * Retrieve certificate manager information.
143 *
144 * @param info Result: Certificate manager information
145 */
146 void getInfo(out Info info);
147
148 /**
149 * Get the active cert chain in PEM format.
150 *
151 * Currently not available via JSON-RPC.
152 *
153 * @return Cert chain in PEM format.
154 */
156
157 /**
158 * Get the active private key in PEM format.
159 *
160 * Currently not available via JSON-RPC.
161 *
162 * @param keyPassword Password to encrypt the returned key (currently not used)
163 *
164 * @return The private key in PEM format.
165 */
166 string getActiveKeyPEM(in string keyPassword);
167
168 /**
169 * Get the pending cert signing request (CSR) in PEM format.
170 *
171 * Currently not available via JSON-RPC.
172 *
173 * @return Cert signing request in PEM format.
174 */
176
177 /**
178 * Get the pending cert chain in PEM format.
179 *
180 * Currently not available via JSON-RPC.
181 *
182 * @return Cert chain in PEM format.
183 */
185
186 /**
187 * Get the pending private key in PEM format.
188 *
189 * Currently not available via JSON-RPC.
190 *
191 * @param keyPassword Password to encrypt the returned key (currently not used)
192 *
193 * @return The private key in PEM format.
194 */
195 string getPendingKeyPEM(in string keyPassword);
196
197 /**
198 * Set the pending cert chain in PEM format.
199 *
200 * Currently not available via JSON-RPC.
201 *
202 * @param certChain Cert chain in PEM format.
203 *
204 * @return SUCCESS or one of the error code constants
205 */
206 int setPendingCertChainPEM(in string certChain);
207
208 /**
209 * Set the pending private key and cert chain in PEM format.
210 *
211 * Currently not available via JSON-RPC.
212 *
213 * @param key Private key in PEM format.
214 * @param certChain Cert chain in PEM format.
215 * @param keyPassword Password to decrypt the private key (currently not used)
216 *
217 * @return SUCCESS or one of the error code constants
218 */
219 int setPendingKeyAndCertChainPEM(in string key, in string certChain, in string keyPassword);
220
221 /**
222 * Activate a pending key pair.
223 *
224 * @return SUCCESS or one of the error code constants
225 */
227
228 };
229
230}
TLS certificate management interface.
KeyType
Supported key types.
@ KEY_TYPE_UNKNOWN
Key type unknown (only allowed as return value)
vector< KeyInfo > getSupportedKeyInfos()
Get all supported key variants.
void deletePending()
Remove pending key and certificate signing request or certificate.
int generateSelfSignedKeyPair(in ReqInfo reqInfo, in int days)
Generate a self-signed key pair.
int setPendingKeyAndCertChainPEM(in string key, in string certChain, in string keyPassword)
Set the pending private key and cert chain in PEM format.
EllipticCurve
Supported elliptic curves for key type ECDSA.
@ EC_CURVE_NIST_P256
NIST curve P-256 (also known as secp256r1 and prime256v1)
@ EC_CURVE_NIST_P384
NIST curve P-384 (also known as secp384r1)
@ EC_CURVE_UNKNOWN
Curve unknown (only allowed as return value)
string getActiveCertChainPEM()
Get the active cert chain in PEM format.
string getPendingCertChainPEM()
Get the pending cert chain in PEM format.
string getActiveKeyPEM(in string keyPassword)
Get the active private key in PEM format.
int installPendingKeyPair()
Activate a pending key pair.
string getPendingKeyPEM(in string keyPassword)
Get the pending private key in PEM format.
int setPendingCertChainPEM(in string certChain)
Set the pending cert chain in PEM format.
void getInfo(out Info info)
Retrieve certificate manager information.
string getPendingRequestPEM()
Get the pending cert signing request (CSR) in PEM format.
int generateUnsignedKeyPair(in ReqInfo reqInfo, in string challenge)
Generate an unsigned key pair.
TLS Certificate Management.
Certificate information.
vector< string > names
DNS names and/or IP addresses.
string invalidAfter
End of validity period.
KeyInfo keyInfo
Key information.
string serialNumber
Serial number.
CommonAttributes issuer
Issuer attributes.
CommonAttributes subject
Subject attributes.
string invalidBefore
Begin of validity period.
‍same as ERR_KEY_FORMAT_INVALID
string stateOrProvince
State or province.
string organizationalUnit
Organizational Unit.
Certificate manager information.
boolean havePendingCert
true if an uploaded certificate is pending activation
boolean havePendingReq
true if a CSR is pending
CertInfo activeCertInfo
Information about active certificate file (device certificate)
ReqInfo pendingReqInfo
Information about pending CSR.
int maxSignDays
Maximum number of days a self signed certificate will be valid.
vector< CertInfo > pendingCertChainInfos
Information about pending certificate file (remaining certificate chain if available)
CertInfo pendingCertInfo
Information about pending certificate file (device certificate)
vector< CertInfo > activeCertChainInfos
Information about active certificate file (remaining certificate chain if available)
Public key information.
EllipticCurve ecCurve
Selected elliptic curve (only relevant if key type is ECDSA)
int rsaKeyLength
Length of the RSA key in bits (only relevant if key type is RSA)
boolean inSecureElement
true if located in a Secure Element
Certificate signing request information.
KeyInfo keyInfo
Key information.
vector< string > names
DNS names and/or IP addresses.
CommonAttributes subject
Certificate subject attributes.