Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
pal_plat_Crypto.h
Go to the documentation of this file.
00001 /******************************************************************************* 00002 * Copyright 2016, 2017 ARM Ltd. 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 *******************************************************************************/ 00016 00017 #ifndef _PAL_PLAT_CRYPTO_H_ 00018 #define _PAL_PLAT_CRYPTO_H_ 00019 00020 #include "pal_Crypto.h" 00021 00022 /*! \file pal_plat_Crypto.h 00023 * \brief PAL cryptographic - platform. 00024 * This file contains cryptographic APIs that need to be implemented in the platform layer. 00025 */ 00026 00027 /*! Initiate the Crypto library. Initialization may not be required for some crypto libraries. In such 00028 * cases, the implementation may be empty. 00029 * 00030 \note This function must be called in the general PAL initializtion function. 00031 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00032 */ 00033 palStatus_t pal_plat_initCrypto (void); 00034 00035 /*! Free resources for the Crypto library. 00036 * 00037 \note This function must be called in the general PAL cleanup function. 00038 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00039 */ 00040 palStatus_t pal_plat_cleanupCrypto (void); 00041 00042 /*! Initialize AES context. 00043 * 00044 * @param[in,out] aes: AES context to be initialized. 00045 * 00046 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00047 */ 00048 palStatus_t pal_plat_initAes (palAesHandle_t *aes); 00049 00050 /*! Free AES context. 00051 * 00052 * @param[in,out] aes: AES context to be deallocated. 00053 * 00054 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00055 */ 00056 palStatus_t pal_plat_freeAes (palAesHandle_t *aes); 00057 00058 /*! Set AES key context for encryption or decryption. 00059 * 00060 * @param[in] aes: AES context. 00061 * @param[in] key: AES key. 00062 * @param[in] keybits: The size of the key in bits. 00063 * @param[in] keyTarget: The key target (encryption/decryption). 00064 * 00065 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00066 */ 00067 palStatus_t pal_plat_setAesKey (palAesHandle_t aes, const unsigned char* key, uint32_t keybits, palAesKeyType_t keyTarget); 00068 00069 /*! AES-CTR buffer encryption/decryption. 00070 * 00071 * @param[in] aes: AES context. 00072 * @param[in] input: The input data buffer. 00073 * @param[out] output: The output data buffer. 00074 * @param[in] inLen: The length of the input data. 00075 * @param[in] iv: The initialization vector for AES-CTR. 00076 * @param[in] zeroOffset: Send offset value zero to platform function. 00077 * 00078 \note Due to the nature of CTR you should use the same key schedule for both encryption and decryption. 00079 * So before calling this function you MUST call `pal_setAesKey()` with the key target PAL_KEY_TARGET_ENCRYPTION to set the key. 00080 * 00081 * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00082 */ 00083 palStatus_t pal_plat_aesCTR (palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16], bool zeroOffset); 00084 00085 /*! AES-ECB block encryption/decryption. 00086 * 00087 * @param[in] aes: AES context. 00088 * @param[in] input: A 16-byte input block. 00089 * @param[out] output: A 16-byte output block. 00090 * @param[in] mode: PAL_AES_ENCRYPT or PAL_AES_DECRYPT 00091 * 00092 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00093 */ 00094 palStatus_t pal_plat_aesECB (palAesHandle_t aes, const unsigned char input[PAL_CRYPT_BLOCK_SIZE], unsigned char output[PAL_CRYPT_BLOCK_SIZE], palAesMode_t mode); 00095 00096 /*! Process SHA256 over the input buffer. 00097 * 00098 * @param[in] input: A buffer for the input data. 00099 * @param[in] inLen: The length of the input data. 00100 * @param[out] output: SHA256 checksum result. 00101 * 00102 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00103 */ 00104 palStatus_t pal_plat_sha256 (const unsigned char* input, size_t inLen, unsigned char* output); 00105 00106 /*! Initialize a certificate (chain) context. 00107 * 00108 * @param[in,out] x509Cert: The certificate chain to initialize. 00109 * 00110 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00111 */ 00112 palStatus_t pal_plat_x509Initiate (palX509Handle_t* x509); 00113 00114 /*! Parse one or more certificates and add them to the chained list. 00115 * 00116 * @param[in] x509Cert: The start of the chain. 00117 * @param[in] input: A buffer holding the certificate data in PEM or DER format. 00118 * @param[in] inLen: The size of the input buffer. 00119 * 00120 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00121 */ 00122 palStatus_t pal_plat_x509CertParse (palX509Handle_t x509, const unsigned char* input, size_t inLen); 00123 00124 /*! Get attributes from the parsed certificate. 00125 * 00126 * @param[in] x509Cert: The parsed certificate. 00127 * @param[in] attr: The required attribute. 00128 * @param[out] output: A buffer to hold the attribute value. 00129 * @param[in] outLenBytes: The size of the allocated buffer. 00130 * @param[out] actualOutLenBytes: The actual size of the attribute. 00131 * 00132 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00133 */ 00134 palStatus_t pal_plat_x509CertGetAttribute (palX509Handle_t x509Cert, palX509Attr_t attr, void* output, size_t outLenBytes, size_t* actualOutLenBytes); 00135 00136 /*! Verify one or more X509 DER formatted certificates. 00137 * 00138 * @param[in] x509Cert: A handle holding the parsed certificate. 00139 * @param[in] x509CertChain: The start of the chain to verify the X509 DER certificate with. (Optional) 00140 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 00141 * relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00142 * 00143 \note In case platform doesn't support multipule errors for certificate verification, please return `PAL_ERR_X509_CERT_VERIFY_FAILED` and the reason should be specified in the `verifyResult` 00144 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00145 */ 00146 palStatus_t pal_plat_x509CertVerifyExtended (palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t* verifyResult); 00147 00148 /*! Deallocate all certificate data. 00149 * 00150 * @param[in,out] x509: The certificate chain to free. 00151 * 00152 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00153 */ 00154 palStatus_t pal_plat_x509Free (palX509Handle_t* x509); 00155 00156 /*! Initialize an MD context and set up the required data according to the given algorithm. 00157 * 00158 * @param[in,out] md: The MD context to be initialized. 00159 * @param[in] mdType: The MD algorithm. 00160 * 00161 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00162 */ 00163 palStatus_t pal_plat_mdInit (palMDHandle_t* md, palMDType_t mdType); 00164 00165 /*! Generic message digest process buffer. 00166 * 00167 * @param[in] md: The MD context. 00168 * @param[in] input: A buffer holding the input data. 00169 * @param[in] inLen: The length of the input data. 00170 * 00171 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00172 */ 00173 palStatus_t pal_plat_mdUpdate (palMDHandle_t md, const unsigned char* input, size_t inLen); 00174 00175 /*! Generic message digest output buffer size getter. 00176 * 00177 * @param[in] md: The MD context. 00178 * @param[out] bufferSize: A pointer to hold the output size of the` pal_mdFinal()` for the given handle. 00179 * 00180 \note You SHOULD call this function before calling `pal_mdFinal()`. 00181 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00182 */ 00183 palStatus_t pal_plat_mdGetOutputSize (palMDHandle_t md, size_t* bufferSize); 00184 00185 /*! Generic message digest final digest. 00186 * 00187 * @param[in] md: The MD context. 00188 * @param[in] output: The generic message digest checksum result. 00189 * 00190 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00191 */ 00192 palStatus_t pal_plat_mdFinal (palMDHandle_t md, unsigned char* output); 00193 00194 /*! Free and clear the MD context. 00195 * 00196 * @param[in,out] md: The AES context to be freed. 00197 * 00198 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00199 */ 00200 palStatus_t pal_plat_mdFree (palMDHandle_t* md); 00201 00202 /*! Verify the signature. 00203 * 00204 * @param[in] x509: The certificate context that holds the PK data. 00205 * @param[in] mdType: The MD algorithm used. 00206 * @param[in] hash: The hash of the message to sign. 00207 * @param[in] hashLen: The hash length. 00208 * @param[in] sig: The signature to verify. 00209 * @param[in] sigLen: The signature length. 00210 * 00211 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00212 */ 00213 palStatus_t pal_plat_verifySignature (palX509Handle_t x509, palMDType_t mdType, const unsigned char *hash, size_t hashLen, const unsigned char *sig, size_t sigLen ); 00214 00215 /*! Get the tag and its length, check for the requested tag. 00216 * Updates the pointer to immediately after the tag and length. 00217 * 00218 * @param[in,out] position: The position in the ASN.1 data. 00219 * @param[in] end: The end of data. 00220 * @param[out] len: The tag length. 00221 * @param[in] tag: The expected tag. 00222 * 00223 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00224 */ 00225 palStatus_t pal_plat_ASN1GetTag (unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag ); 00226 00227 /*! CCM initialization. 00228 * 00229 * @param[in] ctx: The CCM context to be initialized. 00230 * 00231 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00232 */ 00233 palStatus_t pal_plat_CCMInit (palCCMHandle_t* ctx); 00234 00235 /*! CCM destruction. 00236 * 00237 * @param[in] ctx: The CCM context to destroy. 00238 * 00239 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00240 */ 00241 palStatus_t pal_plat_CCMFree (palCCMHandle_t* ctx); 00242 00243 /*! CCM set key. 00244 * 00245 * @param[in] ctx: The CCM context. 00246 * @param[in] id: The cipher to use (a 128-bit block cipher). 00247 * @param[in] key: The encryption key. 00248 * @param[in] keybits: The key size in bits (must be acceptable by the cipher). 00249 * 00250 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00251 */ 00252 palStatus_t pal_plat_CCMSetKey (palCCMHandle_t ctx, palCipherID_t id, const unsigned char *key, unsigned int keybits); 00253 00254 /*! CCM buffer authenticated decryption. 00255 * 00256 * @param[in] ctx: The CCM context. 00257 * @param[in] input A buffer holding the input data. 00258 * @param[in] inLen: The length of the input data. 00259 * @param[in] iv: The initialization vector. 00260 * @param[in] ivLen: The length of the IV. 00261 * @param[in] add: Additional data. 00262 * @param[in] addLen: The length of additional data. 00263 * @param[in] tag: A buffer holding the tag. 00264 * @param[in] tag_len: The length of the tag. 00265 * @param[out] output: A buffer for holding the output data. 00266 * 00267 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00268 */ 00269 palStatus_t pal_plat_CCMDecrypt (palCCMHandle_t ctx, unsigned char* input, size_t inLen, unsigned char* iv, size_t ivLen, unsigned char* add, size_t addLen, unsigned char* tag, size_t tagLen, unsigned char* output); 00270 00271 /*! CCM buffer encryption. 00272 * 00273 * @param[in] ctx: The CCM context. 00274 * @param[in] input A buffer holding the input data. 00275 * @param[in] inLen: The length of the input data. 00276 * @param[in] iv: The initialization vector. 00277 * @param[in] ivLen: The length of the IV. 00278 * @param[in] add: Additional data. 00279 * @param[in] addLen: The length of additional data. 00280 * @param[out] output: A buffer for holding the output data, must be at least 'inLen' bytes wide. 00281 * @param[out] tag: A buffer for holding the tag. 00282 * @param[out] tag_len: The length of the tag to generate in bytes. 00283 * 00284 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00285 */ 00286 palStatus_t pal_plat_CCMEncrypt (palCCMHandle_t ctx, unsigned char* input, size_t inLen, unsigned char* iv, size_t ivLen, unsigned char* add, size_t addLen, unsigned char* output, unsigned char* tag, size_t tagLen); 00287 00288 /*! CTR_DRBG initialization. 00289 * 00290 * @param[in] ctx: The CTR_DRBG context to be initialized. 00291 * 00292 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00293 */ 00294 palStatus_t pal_plat_CtrDRBGInit (palCtrDrbgCtxHandle_t* ctx); 00295 00296 /*! CTR_DRBG destroy. 00297 * 00298 * @param[in] ctx: The CTR_DRBG context to destroy. 00299 * 00300 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00301 */ 00302 palStatus_t pal_plat_CtrDRBGFree (palCtrDrbgCtxHandle_t* ctx); 00303 00304 /*! CTR_DRBG initial seeding. 00305 * 00306 * @param[in] ctx: The CTR_DRBG context to be seeded. 00307 * @param[in] seed: The seed data. 00308 * @param[in] len: The seed data length. 00309 * 00310 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure. 00311 */ 00312 palStatus_t pal_plat_CtrDRBGSeed (palCtrDrbgCtxHandle_t ctx, const void* seed, size_t len); 00313 00314 /*! CTR_DRBG generate random. 00315 * 00316 * @param[in] ctx: The CTR_DRBG context. 00317 * @param[in] out: The buffer to fill. 00318 * @param[in] len: The length of the buffer. 00319 * 00320 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00321 */ 00322 palStatus_t pal_plat_CtrDRBGGenerate (palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len); 00323 00324 /*! CTR_DRBG generate random with additional update input. 00325 * 00326 * @param[in] ctx: The CTR_DRBG context. 00327 * @param[in] out: The buffer to fill. 00328 * @param[in] len: The length of the buffer. 00329 * @param[in] additional: Additional data to update with. 00330 * @param[in] additionalLen: Length of additional data. 00331 * 00332 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00333 */ 00334 palStatus_t pal_plat_CtrDRBGGenerateWithAdditional(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len, unsigned char* additional, size_t additionalLen); 00335 00336 #if PAL_CMAC_SUPPORT 00337 00338 /*! AES cipher CMAC. 00339 * 00340 * @param[in] ctx: The CMAC context to initialize. 00341 * @param[in] key: The encryption key. 00342 * @param[in] keyLenInBits: The key size in bits. 00343 * @param[in] input: A buffer for the input data. 00344 * @param[in] inputLenInBytes: The input data length in bytes. 00345 * @param[out] output: Generic CMAC result. 00346 * 00347 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00348 */ 00349 palStatus_t pal_plat_cipherCMAC (const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output); 00350 00351 /*! Iterative cipher CMAC start. 00352 * 00353 * @param[in] ctx: The CMAC context to initialize. 00354 * @param[in] key: The CMAC key. 00355 * @param[in] keyLenBits: The key size in bits. 00356 * @param[in] cipherID: A buffer for the input data. 00357 * 00358 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00359 */ 00360 palStatus_t pal_plat_CMACStart (palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID); 00361 00362 /*! Iterative cipher CMAC update. 00363 * 00364 * @param[in] ctx: The CMAC context to initialize. 00365 * @param[in] input: A buffer for the input data. 00366 * @param[in] inputLen: The input data length. 00367 * 00368 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00369 */ 00370 palStatus_t pal_plat_CMACUpdate (palCMACHandle_t ctx, const unsigned char *input, size_t inLen); 00371 00372 /*! Iterative cipher CMAC finish. 00373 * 00374 * @param[in] ctx: The CMAC context to initialize. 00375 * @param[out] output: A buffer for the output data. 00376 * @param[out] outLen: The output data length. 00377 * 00378 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00379 */ 00380 palStatus_t pal_plat_CMACFinish (palCMACHandle_t *ctx, unsigned char *output, size_t* outLen); 00381 00382 #endif //PAL_CMAC_SUPPORT 00383 00384 /*! One shot md HMAC. 00385 * 00386 * @param[in] key: The encryption key. 00387 * @param[in] keyLenInBytes: The key size in bytes. 00388 * @param[in] input: A buffer for the input data. 00389 * @param[in] inputLenInBytes: The input data length in bytes. 00390 * @param[out] output: The generic HMAC result. 00391 * @param[out] outputLenInBytes: Size of the HMAC result (optional). 00392 * 00393 \note Expects output to be 32 bytes long 00394 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00395 */ 00396 palStatus_t pal_plat_mdHmacSha256 (const unsigned char *key, size_t keyLenInBytes, const unsigned char *input, size_t inputLenInBytes, unsigned char *output, size_t* outputLenInBytes); 00397 00398 00399 /*! Check that the private and/or public key is a valid key and the public key is on this curve. 00400 * 00401 * @param[in] grp: The curve/group the point should belong to. 00402 * @param[in] key: A pointer to the struct that holds the keys to check. 00403 * @param[in] type: PAL_CHECK_PRIVATE_KEY/PAL_CHECK_PUBLIC_KEY/PAL_CHECK_BOTH_KEYS 00404 * @param[out] verified: The result of the verification. 00405 * 00406 \note The key can contain only private or public key or both. 00407 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00408 */ 00409 palStatus_t pal_plat_ECCheckKey (palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified); 00410 00411 /*! Allocate key context and initialize a key pair (as an invalid one). 00412 * 00413 * @Param[in] key: The key pair context to initialize 00414 * 00415 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure. 00416 */ 00417 palStatus_t pal_plat_ECKeyNew (palECKeyHandle_t* key); 00418 00419 /*! Free the components of a key pair. 00420 * 00421 * @param[in] key: The key to free. 00422 * 00423 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00424 */ 00425 palStatus_t pal_plat_ECKeyFree (palECKeyHandle_t* key); 00426 00427 /*! Parse a DER encoded private key. 00428 * 00429 * @param[in] prvDERKey: A buffer that holds the DER encoded private key. 00430 * @param[in] keyLen: The key length. 00431 * @param[out] key: A handle for the context that holds the parsed key. 00432 * 00433 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00434 */ 00435 palStatus_t pal_plat_parseECPrivateKeyFromDER (const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key); 00436 00437 /*! Parse a DER encoded public key. 00438 * 00439 * @param[in] pubDERKey: A buffer that holds the DER encoded public key. 00440 * @param[in] keyLen: The key length. 00441 * @param[out] key: A handle for the context that holds the parsed key. 00442 * 00443 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00444 */ 00445 palStatus_t pal_plat_parseECPublicKeyFromDER (const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key); 00446 00447 /*! Encode the given private key from the key handle to the DER buffer. 00448 * 00449 * @param[in] key: A handle to the private key. 00450 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00451 * @param[in] bufferSize: The size of the allocated buffer. 00452 * @param[out] actualSize: The actual size of the written data. 00453 * 00454 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00455 */ 00456 palStatus_t pal_plat_writePrivateKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00457 00458 /*! Encode the given public key from the key handle to the DER buffer. 00459 * 00460 * @param[in] key: A handle to the public key. 00461 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00462 * @param[in] bufferSize: The size of the allocated buffer. 00463 * @param[out] actualSize: The actual size of the written data. 00464 * 00465 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00466 */ 00467 palStatus_t pal_plat_writePublicKeyToDer (palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00468 00469 /*! Generate a keypair. 00470 * 00471 * @param[in] grpID: The ECP group identifier. 00472 * @param[in] key: A handle to the destination keypair. 00473 * 00474 \note The `key` parameter must be first allocated by `pal_ECKeyNew()`. 00475 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00476 */ 00477 palStatus_t pal_plat_ECKeyGenerateKey (palGroupIndex_t grpID, palECKeyHandle_t key); 00478 00479 /*! Retrieve the curve ID if it exists in the given key. 00480 * 00481 * @param[in] key: The key to retrieve its curve. 00482 * @param[out] grpID: The curve/group ID for the given key. In case of error, this pointer contains "PAL_ECP_DP_NONE". 00483 * 00484 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00485 */ 00486 palStatus_t pal_plat_ECKeyGetCurve (palECKeyHandle_t key, palGroupIndex_t* grpID); 00487 00488 /*! Allocate and initialize the x509 CSR context. 00489 * 00490 * @param[in] x509CSR: The CSR context to allocate and initialize. 00491 * 00492 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00493 */ 00494 palStatus_t pal_plat_x509CSRInit (palx509CSRHandle_t *x509CSR); 00495 00496 /*! Set the subject name for a CSR. The subject names should contain a comma-separated list of OIDs and values. 00497 * 00498 * @param[in] x509CSR: The CSR context to use. 00499 * @param[in] subjectName: The subject name to set. 00500 * 00501 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00502 */ 00503 palStatus_t pal_plat_x509CSRSetSubject (palx509CSRHandle_t x509CSR, const char* subjectName); 00504 00505 /*! Set the MD algorithm to use for the signature. 00506 * 00507 * @param[in] x509CSR: The CSR context to use. 00508 * @param[in] mdType: The MD algorithm to use. 00509 * 00510 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00511 */ 00512 palStatus_t pal_plat_x509CSRSetMD (palx509CSRHandle_t x509CSR, palMDType_t mdType); 00513 00514 /*! Set the key for a CSR. 00515 * 00516 * @param[in] x509CSR: The CSR context to use. 00517 * @param[in] pubKey: The public key to include. To use the keypair handle, see the note. 00518 * @param[in] prvKey: The public key to sign with. 00519 * 00520 \note To use the keypair, please send it as `pubKey` and NULL as `prvKey`. 00521 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00522 */ 00523 palStatus_t pal_plat_x509CSRSetKey (palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey); 00524 00525 /*! Set the key usage extension flags. 00526 * 00527 * @param[in] x509CSR: The CSR context to use. 00528 * @param[in] keyUsage: The key usage flags that should be taken from `palKeyUsage_t`. 00529 * 00530 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00531 */ 00532 palStatus_t pal_plat_x509CSRSetKeyUsage (palx509CSRHandle_t x509CSR, uint32_t keyUsage); 00533 00534 /*! Generic function to add to the CSR. 00535 * 00536 * @param[in] x509CSR: The CSR context to use. 00537 * @param[in] oid: The OID of the extension. 00538 * @param[in] oidLen: The OID length. 00539 * @param[in] value: The value of the extension OCTET STRING. 00540 * @param[in] valueLen: The value length. 00541 * 00542 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00543 */ 00544 palStatus_t pal_plat_x509CSRSetExtension (palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, const unsigned char* value, size_t valueLen); 00545 00546 /*! Write a CSR to a DER structure. 00547 * 00548 * @param[in] x509CSR: The CSR context to use. 00549 * @param[in] derBuf: A buffer to write to. 00550 * @param[in] derBufLen: The buffer length. 00551 * @param[in] actualDerLen: The actual length of the written data. 00552 * 00553 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00554 */ 00555 palStatus_t pal_plat_x509CSRWriteDER (palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen); 00556 00557 /*! Free the x509 CSR context. 00558 * 00559 * @param[in] x509CSR: The CSR context to free. 00560 * 00561 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00562 */ 00563 palStatus_t pal_plat_x509CSRFree (palx509CSRHandle_t *x509CSR); 00564 00565 /*! Compute a shared secret. 00566 * 00567 * @param[in] grp: The ECP group. 00568 * @param[in] peerPublicKey: The public key from a peer. 00569 * @param[in] privateKey: The private key. 00570 * @param[out] outKey: The shared secret. 00571 * 00572 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00573 */ 00574 palStatus_t pal_plat_ECDHComputeKey (const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey); 00575 00576 /*! Compute the ECDSA signature of a previously hashed message. 00577 * 00578 * @param[in] grp: The ECP group. 00579 * @param[in] prvKey: The private signing key- 00580 * @param[in] dgst: The message hash. 00581 * @param[in] dgstLen: The length of the message buffer. 00582 * @param[out] sig: A buffer to hold the computed signature. 00583 * @param[out] sigLen: The length of the computed signature. 00584 * 00585 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00586 */ 00587 palStatus_t pal_plat_ECDSASign (palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char* dgst, uint32_t dgstLen, unsigned char *sig, size_t *sigLen); 00588 00589 /*! Verify the ECDSA signature of a previously hashed message. 00590 * 00591 * @param[in] pubKey: The public key for verification. 00592 * @param[in] dgst: The message hash. 00593 * @param[in] dgstLen: The length of the message buffer. 00594 * @param[in] sign: The signature. 00595 * @param[in] sig: A buffer to hold the computed signature. 00596 * @param[in] sigLen: The length of the computed signature. 00597 * @param[out] verified: The boolean to hold the verification result. 00598 * 00599 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00600 */ 00601 palStatus_t pal_plat_ECDSAVerify (palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, unsigned char* sig, size_t sigLen, bool* verified); 00602 00603 /*! Free the components of an ECP group. 00604 * 00605 * @param[in] grp: The curve/group to free. 00606 * 00607 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00608 */ 00609 palStatus_t pal_plat_ECGroupFree (palCurveHandle_t* grp); 00610 00611 /*! ECP group initialize and set a group using well-known domain parameters. 00612 * 00613 * @param[in] grp: The destination group. 00614 * @param[in] index: The index in the list of well-known domain parameters. 00615 * 00616 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00617 */ 00618 palStatus_t pal_plat_ECGroupInitAndLoad (palCurveHandle_t* grp, palGroupIndex_t index); 00619 00620 #endif //_PAL_PLAT_CRYPTO_H_
Generated on Tue Jul 12 2022 19:01:36 by 1.7.2