resource-container: Install unit tests
[iotivity.git] / resource / csdk / security / include / occertutility.h
1 //******************************************************************
2 //
3 // Copyright 2017 Microsoft
4 //
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
6 //
7 // Licensed under the Apache License, Version 2.0 (the "License");
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
10 //
11 //      http://www.apache.org/licenses/LICENSE-2.0
12 //
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an "AS IS" BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
18 //
19 //******************************************************************
20
21 #if defined(__WITH_TLS__) || defined(__WITH_DTLS__)
22
23 #ifndef OCCERTUTILITY_H_
24 #define OCCERTUTILITY_H_
25
26 #include "experimental/securevirtualresourcetypes.h"
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /**
33  * Generate a random serial number suitable for use with a certificate.
34  * Callers must record used serial numbers and ensure serial numbers do not
35  * get repeated!
36  *
37  * @param[OUT] serial      Pointer to a string that will be set to the location of the ASCII serial number.
38  *                         Memory for this buffer will be allocated internally; caller must call OICFree on serial
39  *                         when finished to free its memory.
40  * @param[OUT] serialLen   Variable to receive size of serial, which will include the terminating NULL.
41  *
42  * @return OC_STACK_OK if generated successfully; error otherwise.
43  */
44 OCStackResult OC_CALL OCGenerateRandomSerialNumber(char **serial, size_t *serialLen);
45
46 /**
47  * Generate a new NIST P-256 elliptic curve key pair and return the public and private
48  * keys as PEM encoded strings.
49  *
50  * @param[OUT] publicKey     Pointer to receive PEM encoded public key. Memory is allocated internally
51  *                           and must be freed by caller with OICFree.
52  * @param[OUT] publicKeyLen  Variable to receive length of publicKey, which will include terminating NULL.
53  * @param[OUT] privateKey    Pointer to receive PEM encoded private key. Memory is allocated internally
54  *                           and, when finished, caller should first call OICClearMemory to securely erase
55  *                           its contents and then freed with OICFree. Caller is responsible for ensuring
56  *                           this key remains protected and secret!
57  * @param[OUT] privateKeyLen Variable to receive length of privateKey, which will include terminating NULL.
58  */
59 OCStackResult OC_CALL OCGenerateKeyPair(char **publicKey, size_t *publicKeyLen,
60                                         char **privateKey, size_t *privateKeyLen);
61
62 /**
63  * Generate a certificate to act as a Root Certificate Authority (CA).
64  *
65  * @param subject               Comma-separated list of RDN types and values:
66  *                              e.g. "C=US, O=Open Connectivity Foundation, CN=Main CA"
67  * @param subjectPublicKey      Subject's public key in PEM format
68  * @param issuerCert            Issuer's certificate in PEM format
69  *                              If this certificate will be self-signed, pass in NULL.
70  * @param issuerPrivateKey      Issuer's private key in PEM format
71  *                              If self-signing (issuerCert is NULL), this must be the private
72  *                              key corresponding to subjectPublicKey.
73  * @param serial                String containing the serial number in ASCII numerals:
74  *                              e.g., "12345". Caller must ensure each certificate issued by a
75  *                              CA has a unique serial number, and it is recommended to generate
76  *                              them randomly by producing 19 random bytes and converting them to
77  *                              a numerical value. See GenerateRandomSerialNumber().
78  * @param notValidBefore        The notValidBefore date in UTC for the certificate in the form YYYYMMDDhhmmss
79  *                              e.g., "20131231235959" for December 31st 2013 at 23:59:59
80  * @param notValidAfter         The notValidAfter date in UTC for the certificate in the form YYYYMMDDhhmmss
81  *                              e.g., "20140101010203" for January 1st 2014 at 01:02:03
82  * @param[OUT] certificate      Pointer to a buffer that will receive the PEM-encoded certificate. Memory will be
83  *                              allocated internally; caller must call OICFree on certificate when finished to free
84  *                              its memory.
85  * @param[OUT] certificateLen   Variable to receive the size of certificate, which will include the terminating NULL.
86  *
87  * @return OC_STACK_OK if successful, error code otherwise
88  */
89 OCStackResult OC_CALL OCGenerateRootCACertificate(
90     const char *subject,
91     const char *subjectPublicKey,
92     const char *issuerCert,
93     const char *issuerPrivateKey,
94     const char *serial,
95     const char *notValidBefore,
96     const char *notValidAfter,
97     char **certificate,
98     size_t *certificateLen);
99
100 /**
101  * Generate a certificate to act as an Intermediate Certificate Authority (CA).
102  *
103  * @param subject               Comma-separated list of RDN types and values:
104  *                              e.g. "C=US, O=Open Connectivity Foundation, CN=Main CA"
105  * @param subjectPublicKey      Subject's public key in PEM format
106  * @param issuerCert            Issuer's certificate in PEM format
107  *                              If this certificate will be self-signed, pass in NULL.
108  * @param issuerPrivateKey      Issuer's private key in PEM format
109  *                              If self-signing (issuerCert is NULL), this must be the private
110  *                              key corresponding to subjectPublicKey.
111  * @param serial                String containing the serial number in ASCII numerals:
112  *                              e.g., "12345". Caller must ensure each certificate issued by a
113  *                              CA has a unique serial number, and it is recommended to generate
114  *                              them randomly by producing 19 random bytes and converting them to
115  *                              a numerical value. See GenerateRandomSerialNumber().
116  * @param notValidBefore        The notValidBefore date in UTC for the certificate in the form YYYYMMDDhhmmss
117  *                              e.g., "20131231235959" for December 31st 2013 at 23:59:59
118  * @param notValidAfter         The notValidAfter date in UTC for the certificate in the form YYYYMMDDhhmmss
119  *                              e.g., "20140101010203" for January 1st 2014 at 01:02:03
120  * @param[OUT] certificate      Pointer to a buffer that will receive the PEM-encoded certificate. Memory will be
121  *                              allocated internally; caller must call OICFree on certificate when finished to free
122  *                              its memory.
123  * @param[OUT] certificateLen   Variable to receive the size of certificate, which will include the terminating NULL.
124  *
125  * @return OC_STACK_OK if successful, error code otherwise
126  */
127 OCStackResult OC_CALL OCGenerateIntermediateCACertificate(
128     const char *subject,
129     const char *subjectPublicKey,
130     const char *issuerCert,
131     const char *issuerPrivateKey,
132     const char *serial,
133     const char *notValidBefore,
134     const char *notValidAfter,
135     char **certificate,
136     size_t *certificateLen);
137
138 /**
139  * Generate a certificate for a device's identity.
140  *
141  * @param subjectUuid           UUID for the device to use the certificate.
142  * @param subjectPublicKey      Subject's public key in PEM format
143  * @param issuerCert            Issuer's certificate in PEM format
144  * @param issuerPrivateKey      Issuer's private key in PEM format
145  * @param serial                String containing the serial number in ASCII numerals:
146  *                              e.g., "12345". Caller must ensure each certificate issued by a
147  *                              CA has a unique serial number, and it is recommended to generate
148  *                              them randomly by producing 19 random bytes and converting them to
149  *                              a numerical value. See GenerateRandomSerialNumber().
150  * @param notValidBefore        The notValidBefore date in UTC for the certificate in the form YYYYMMDDhhmmss
151  *                              e.g., "20131231235959" for December 31st 2013 at 23:59:59
152  * @param notValidAfter         The notValidAfter date in UTC for the certificate in the form YYYYMMDDhhmmss
153  *                              e.g., "20140101010203" for January 1st 2014 at 01:02:03
154  * @param[OUT] certificate      Pointer to a buffer that will receive the PEM-encoded certificate. Memory will be
155  *                              allocated internally; caller must call OICFree on certificate when finished to free
156  *                              its memory.
157  * @param[OUT] certificateLen   Variable to receive the size of certificate, which will include the terminating NULL.
158  *
159  * @return OC_STACK_OK if successful, error code otherwise
160  */
161 OCStackResult OC_CALL OCGenerateIdentityCertificate(
162     const OicUuid_t *subjectUuid,
163     const char *subjectPublicKey,
164     const char *issuerCert,
165     const char *issuerPrivateKey,
166     const char *serial,
167     const char *notValidBefore,
168     const char *notValidAfter,
169     char **certificate,
170     size_t *certificateLen);
171
172 /**
173  * Generate a role certificate for a device.
174  *
175  * @param subjectUuid           UUID for the device to use the certificate.
176  * @param subjectPublicKey      Subject's public key in PEM format
177  * @param issuerCert            Issuer's certificate in PEM format
178  * @param issuerPrivateKey      Issuer's private key in PEM format
179  * @param serial                String containing the serial number in ASCII numerals:
180  *                              e.g., "12345". Caller must ensure each certificate issued by a
181  *                              CA has a unique serial number, and it is recommended to generate
182  *                              them randomly by producing 19 random bytes and converting them to
183  *                              a numerical value. See GenerateRandomSerialNumber().
184  * @param notValidBefore        The notValidBefore date in UTC for the certificate in the form YYYYMMDDhhmmss
185  *                              e.g., "20131231235959" for December 31st 2013 at 23:59:59
186  * @param notValidAfter         The notValidAfter date in UTC for the certificate in the form YYYYMMDDhhmmss
187  *                              e.g., "20140101010203" for January 1st 2014 at 01:02:03
188  * @param role                  The role to encode in the certificate.
189  * @param authority             The role authority to encode in the certificate. This field is optional;
190  *                              to omit, use NULL, and authority is construed to be the certificate issuer.
191  * @param[OUT] certificate      Pointer to a buffer that will receive the PEM-encoded certificate. Memory will be
192  *                              allocated internally; caller must call OICFree on certificate when finished to free
193  *                              its memory.
194  * @param[OUT] certificateLen   Variable to receive the size of certificate, which will include the terminating NULL.
195  *
196  * @return OC_STACK_OK if successful, error code otherwise
197  */
198 OCStackResult OC_CALL OCGenerateRoleCertificate(
199     const OicUuid_t *subjectUuid,
200     const char *subjectPublicKey,
201     const char *issuerCert,
202     const char *issuerPrivateKey,
203     const char *serial,
204     const char *notValidBefore,
205     const char *notValidAfter,
206     const char *role,
207     const char *authority,
208     char **certificate,
209     size_t *certificateLen);
210
211 /**
212  * Extract a UUID from a CSR.
213  *
214  * @param[in]  csr  The CSR containing the UUID as null-terminated PEM.
215  * @param[out] uuid The UUID in the CSR
216  *
217  * @return OC_STACK_OK if successful, error code otherwise
218  */
219 OCStackResult OC_CALL OCGetUuidFromCSR(const char* csr, OicUuid_t* uuid);
220
221 /**
222  * Extract a public key from a CSR.
223  *
224  * @param[in]  csr       The CSR containing the public key, as null-terminated PEM.
225  * @param[out] publicKey The public key is output here as null-terminated PEM.
226  *                       Callers must call OICFree when finished.
227  *
228  * @return OC_STACK_OK if successful, error code otherwise
229  */
230 OCStackResult OC_CALL OCGetPublicKeyFromCSR(const char* csr, char** publicKey);
231
232 /**
233  * Verify the signature in a CSR is valid.
234  *
235  * @param[in] csr The CSR to check, as null-terminated PEM.
236  *
237  * @return OC_STACK_OK if successful, error code otherwise
238  *
239  * @remark Requires that ECDSA with SHA-256 be used for the signature.
240  */
241 OCStackResult OC_CALL OCVerifyCSRSignature(const char* csr);
242
243 /**
244  * Convert a CSR from DER encoding to PEM encoding.
245  *
246  * @param[in] derCSR The CSR to convert, encoded as DER
247  * @param[in] derCSRLen Then number of bytes in derCSR
248  * @param[out] pemCSR The output, PEM encoded, null-terminated CSR. Callers
249  *                    call OICFree when finished.
250  *
251  * @return OC_STACK_OK if successful, error code otherwise
252  */
253 OCStackResult OC_CALL OCConvertDerCSRToPem(const char* derCSR, size_t derCSRLen, char** pemCSR);
254
255 #ifdef __cplusplus
256 }
257 #endif
258
259 #endif /* OCCERTUTILITY_H_ */
260
261 #endif /* defined(__WITH_TLS__) || defined(__WITH_DTLS__) */