Toyomasa Watarai
Simple interface for Mbed Cloud Client
Embed:
(wiki syntax)
Show/hide line numbers
pal_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_CRYPTO_H_ 00018 #define _PAL_CRYPTO_H_ 00019 00020 00021 #ifndef _PAL_H 00022 #error "Please do not include this file directly, use pal.h instead" 00023 #endif 00024 00025 /*! \file pal_Crypto.h 00026 * \brief PAL cryptographic. 00027 * This file contains cryptographic APIs and is part of the PAL service API. 00028 * It contains a variety of cryptographic APIs, such as: 00029 * - AES-CTR 00030 - AES-DRBG 00031 - CMAC 00032 - Message Digest 00033 */ 00034 00035 typedef uintptr_t palAesHandle_t; 00036 typedef uintptr_t palX509Handle_t; 00037 typedef uintptr_t palMDHandle_t; 00038 typedef uintptr_t palCCMHandle_t; 00039 typedef uintptr_t palCMACHandle_t; 00040 typedef uintptr_t palCtrDrbgCtxHandle_t; 00041 typedef uintptr_t palCurveHandle_t; 00042 typedef uintptr_t palGroupIDHandle_t; 00043 typedef uintptr_t palECKeyHandle_t; 00044 typedef uintptr_t palSignatureHandle_t; 00045 typedef uintptr_t palx509CSRHandle_t; 00046 00047 //! Key types to be set to the AES engine. 00048 typedef enum palAesKeyType{ 00049 PAL_KEY_TARGET_ENCRYPTION, 00050 PAL_KEY_TARGET_DECRYPTION 00051 }palAesKeyType_t; 00052 00053 //! Message digest algorithms supported by PAL. 00054 typedef enum palMDType{ 00055 PAL_SHA256 00056 }palMDType_t; 00057 00058 //! AES mode for ECB encryption/decryption. 00059 typedef enum palAesMode{ 00060 PAL_AES_ENCRYPT, 00061 PAL_AES_DECRYPT 00062 }palAesMode_t; 00063 00064 //! The supported enum tags by PAL for ASN1. 00065 typedef enum palASNTag{ 00066 PAL_ASN1_BOOLEAN = 0x01, 00067 PAL_ASN1_INTEGER = 0x02, 00068 PAL_ASN1_BIT_STRING = 0x03, 00069 PAL_ASN1_OCTET_STRING = 0x04, 00070 PAL_ASN1_NULL = 0x05, 00071 PAL_ASN1_OID = 0x06, 00072 PAL_ASN1_UTF8_STRING = 0x0C, 00073 PAL_ASN1_SEQUENCE = 0x10, 00074 PAL_ASN1_SET = 0x11, 00075 PAL_ASN1_PRINTABLE_STRING = 0x13, 00076 PAL_ASN1_T61_STRING = 0x14, 00077 PAL_ASN1_IA5_STRING = 0x16, 00078 PAL_ASN1_UTC_TIME = 0x17, 00079 PAL_ASN1_GENERALIZED_TIME = 0x18, 00080 PAL_ASN1_UNIVERSAL_STRING = 0x1C, 00081 PAL_ASN1_BMP_STRING = 0x1E, 00082 PAL_ASN1_PRIMITIVE = 0x00, 00083 PAL_ASN1_CONSTRUCTED = 0x20, 00084 PAL_ASN1_CONTEXT_SPECIFIC = 0x80, 00085 }palASNTag_t; 00086 00087 #define PAL_ASN1_CLASS_BITS 0xC0 00088 #define PAL_ASN1_TAG_BITS 0x1F 00089 #define PAL_CRYPT_BLOCK_SIZE 16 00090 #define PAL_SHA256_SIZE 32 00091 00092 typedef enum palFormat{ 00093 PAL_POINT_CONVERSION_UNCOMPRESSED 00094 /*PAL_POINT_CONVERSION_COMPRESSED*/ 00095 }palFormat_t; 00096 00097 typedef enum palCipherID{ 00098 PAL_CIPHER_ID_AES 00099 /*PAL_CIPHER_ID_DES*/ 00100 }palCipherID_t; 00101 00102 //! Supported curves. 00103 typedef enum palGroupIndex{ 00104 PAL_ECP_DP_NONE, 00105 PAL_ECP_DP_SECP256R1 00106 }palGroupIndex_t; 00107 00108 typedef enum palKeyUsage{ 00109 PAL_X509_KU_DIGITAL_SIGNATURE = 0x1, 00110 PAL_X509_KU_NON_REPUDIATION = 0x2, 00111 PAL_X509_KU_KEY_CERT_SIGN = 0x4 00112 }palKeyUsage_t; 00113 00114 //! Key check options. 00115 typedef enum palKeyToCheck{ 00116 PAL_CHECK_PRIVATE_KEY = 0x01, 00117 PAL_CHECK_PUBLIC_KEY = 0x10, 00118 PAL_CHECK_BOTH_KEYS = 0x11 00119 }palKeyToCheck_t; 00120 00121 //! Attributes to be retrieved from the x509 cert. 00122 typedef enum palX509Attr{ 00123 PAL_X509_ISSUER_ATTR, 00124 PAL_X509_SUBJECT_ATTR, 00125 PAL_X509_CN_ATTR, 00126 PAL_X509_OU_ATTR, 00127 PAL_X509_VALID_FROM, 00128 PAL_X509_VALID_TO, 00129 PAL_X509_CERT_ID_ATTR 00130 }palX509Attr_t; 00131 00132 00133 /***************************************************/ 00134 /**** PAL Crypto Client APIs ***********************/ 00135 /***************************************************/ 00136 00137 /*! Initialize AES context 00138 * 00139 * @param[in,out] aes: The AES context to be initialized. 00140 * 00141 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00142 */ 00143 palStatus_t pal_initAes(palAesHandle_t *aes); 00144 00145 /*! Free AES context. 00146 * 00147 * @param[in,out] aes: The AES context to be deallocated. 00148 * 00149 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00150 */ 00151 palStatus_t pal_freeAes(palAesHandle_t *aes); 00152 00153 /*! Set AES key context for encryption or decryption. 00154 * 00155 * @param[in] aes: The AES context. 00156 * @param[in] key: The AES key. 00157 * @param[in] keybits: The size of the key in bits. 00158 * @param[in] keyTarget: The key target (encryption/decryption). 00159 * 00160 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00161 */ 00162 palStatus_t pal_setAesKey(palAesHandle_t aes, const unsigned char* key, uint32_t keybits, palAesKeyType_t keyTarget); 00163 00164 /*! AES-CTR buffer encryption/decryption. 00165 * 00166 * @param[in] aes: The AES context. 00167 * @param[in] input: The input data buffer. 00168 * @param[out] output: The output data buffer. 00169 * @param[in] inLen: The input data length. 00170 * @param[in] iv: The initialization vector for AES-CTR. 00171 * 00172 \note Due to the nature of CTR, you should use the same key schedule for 00173 * both encryption and decryption. So before calling this function, you MUST set the key 00174 * by calling `pal_setAesKey()` with key target PAL_KEY_TARGET_ENCRYPTION. 00175 * 00176 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00177 */ 00178 palStatus_t pal_aesCTR(palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16]); 00179 00180 /*! AES-CTR buffer encryption/decryption with zero offset. 00181 * 00182 * @param[in] aes: The AES context. 00183 * @param[in] input: The input data buffer. 00184 * @param[out] output: The output data buffer. 00185 * @param[in] inLen: The input data length. 00186 * @param[in] iv: The initialization vector for AES-CTR. 00187 * 00188 \note Due to the nature of CTR, you should use the same key schedule for 00189 * both encryption and decryption. So before calling this function, you MUST set the key 00190 * by calling `pal_setAesKey()` with key target PAL_KEY_TARGET_ENCRYPTION. 00191 * 00192 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00193 */ 00194 palStatus_t pal_aesCTRWithZeroOffset(palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16]); 00195 00196 00197 /*! AES-ECB block encryption/decryption. 00198 * 00199 * @param[in] aes: The AES context. 00200 * @param[in] input: A 16-byte input block. 00201 * @param[out] output: A 16-byte output block. 00202 * @param[in] mode: PAL_AES_ENCRYPT or PAL_AES_DECRYPT. 00203 * 00204 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00205 */ 00206 palStatus_t pal_aesECB(palAesHandle_t aes, const unsigned char input[PAL_CRYPT_BLOCK_SIZE], unsigned char output[PAL_CRYPT_BLOCK_SIZE], palAesMode_t mode); 00207 00208 /*! Process SHA256 over the input buffer. 00209 * 00210 * @param[in] input: A buffer for the input data. 00211 * @param[in] inLen: The length of the input data. 00212 * @param[out] output: The SHA256 checksum result. 00213 * 00214 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00215 */ 00216 palStatus_t pal_sha256 (const unsigned char* input, size_t inLen, unsigned char output[PAL_SHA256_SIZE]); 00217 00218 /*! Initialize a certificate (chain) context. 00219 * 00220 * @param[in,out] x509Cert: The certificate chain to initialize. 00221 * 00222 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00223 */ 00224 palStatus_t pal_x509Initiate(palX509Handle_t* x509Cert); 00225 00226 /*! Parse one or more certificates and add them to the chained list. 00227 * 00228 * @param[in] x509Cert: The beginning of the chain. 00229 * @param[in] input: A buffer holding the certificate data in PEM or DER format. 00230 * @param[in] inLen: The size of the input buffer. 00231 * 00232 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00233 */ 00234 palStatus_t pal_x509CertParse(palX509Handle_t x509Cert, const unsigned char* input, size_t inLen); 00235 00236 /*! Get attributes from the parsed certificate. 00237 * 00238 * @param[in] x509Cert: The parsed certificate. 00239 * @param[in] attr: The required attribute. 00240 * @param[out] output: A buffer to hold the attribute value. 00241 * @param[in] outLenBytes: The size of the allocated buffer. 00242 * @param[out] actualOutLenBytes: The actual size of the attribute. 00243 * 00244 \note In case of PAL_ERR_BUFFER_TOO_SMALL, the required size is assigned into the `actualOutLen` parameter. 00245 \note `PAL_X509_CERT_ID_ATTR` required 33 bytes buffer size. 00246 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00247 */ 00248 palStatus_t pal_x509CertGetAttribute(palX509Handle_t x509Cert, palX509Attr_t attr, void* output, size_t outLenBytes, size_t* actualOutLenBytes); 00249 00250 /*! Verify one or more X509 DER formatted certificates. 00251 * 00252 * @param[in] x509Cert: A handle holding the parsed certificate. 00253 * @param[in] x509Cert: The beginning of the chain to verify the X509 DER certificate with. (Optional) 00254 * 00255 \return PAL_SUCCESS on success. In case of failure: 00256 * - PAL_ERR_X509_BADCERT_EXPIRED 00257 * - PAL_ERR_X509_BADCERT_FUTURE 00258 * - PAL_ERR_X509_BADCERT_BAD_MD 00259 * - PAL_ERR_X509_BADCERT_BAD_PK 00260 * - PAL_ERR_X509_BADCERT_NOT_TRUSTED 00261 * - PAL_ERR_X509_BADCERT_BAD_KEY 00262 */ 00263 palStatus_t pal_x509CertVerify(palX509Handle_t x509Cert, palX509Handle_t x509CertChain); 00264 00265 /*! Verify one or more X509 DER formatted certificates. 00266 * 00267 * @param[in] x509Cert: A handle holding the parsed certificate. 00268 * @param[in] x509Cert: The beginning of the chain to verify the X509 DER certificate with. (Optional) 00269 * @param[out] verifyResult: bitmask of errors that cause the failure, this value is 00270 * relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00271 * 00272 \return PAL_SUCCESS on success. In case of failure returns `PAL_ERR_X509_CERT_VERIFY_FAILED`. 00273 */ 00274 palStatus_t pal_x509CertVerifyExtended(palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t* verifyResult); 00275 00276 /*! Deallocate all certificate data. 00277 * 00278 * @param[in,out] x509Cert: The certificate chain to free. 00279 * 00280 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00281 */ 00282 palStatus_t pal_x509Free(palX509Handle_t* x509Cert); 00283 00284 /*! Initialize the MD context and set up the required data according to the given algorithm. 00285 * 00286 * @param[in,out] md: The MD context to be initialized. 00287 * @param[in] mdType: The MD algorithm. 00288 * 00289 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00290 */ 00291 palStatus_t pal_mdInit(palMDHandle_t* md, palMDType_t mdType); 00292 00293 /*! Generic message digest process buffer. 00294 * 00295 * @param[in] md: The MD context. 00296 * @param[in] input: A buffer holding the input data. 00297 * @param[in] inLen: The length of the input data. 00298 * 00299 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00300 */ 00301 palStatus_t pal_mdUpdate(palMDHandle_t md, const unsigned char* input, size_t inLen); 00302 00303 /*! Generic message digest output buffer size getter. 00304 * 00305 * @param[in] md: The MD context. 00306 * @param[out] bufferSize: A pointer to hold the output size of the `pal_mdFinal()` for the given handle. 00307 * 00308 \note This function SHOULD be called before calling `pal_mdFinal()`. 00309 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00310 */ 00311 palStatus_t pal_mdGetOutputSize(palMDHandle_t md, size_t* bufferSize); 00312 00313 /*! Generic message digest final calculation. 00314 * 00315 * @param[in] md: The MD context. 00316 * @param[out] ouput: The checksum result of the generic message digest. 00317 * 00318 \note `pal_mdGetOutputSize()` SHOULD be called before calling `pal_mdFinal()` to get the needed size for the ouptut. 00319 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00320 */ 00321 palStatus_t pal_mdFinal(palMDHandle_t md, unsigned char* output); 00322 00323 /*! Free and clear the MD context. 00324 * 00325 * @param[in,out] md: The MD context to be free. 00326 * 00327 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00328 */ 00329 palStatus_t pal_mdFree(palMDHandle_t* md); 00330 00331 /*! Verify the signature. 00332 * 00333 * @param[in] x509: The certificate context that holds the PK data. 00334 * @param[in] mdType: The MD algorithm used. 00335 * @param[in] hash: The hash of the message to sign. 00336 * @param[in] hashLen: The hash length. 00337 * @param[in] sig: The signature to verify. 00338 * @param[in] sigLen: The signature length. 00339 * 00340 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00341 */ 00342 palStatus_t pal_verifySignature(palX509Handle_t x509, palMDType_t mdType, const unsigned char *hash, size_t hashLen, const unsigned char *sig, size_t sigLen); 00343 00344 /*! Get the tag and length of the tag, check for the requested tag. \n 00345 * Updates the pointer to immediately after the tag and length. 00346 * 00347 * @param[in,out] position: The position in the ASN.1 data. 00348 * @param[in] end: The end of data. 00349 * @param[out] len: The tag length. 00350 * @param[in] tag: The expected tag. 00351 * 00352 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00353 */ 00354 palStatus_t pal_ASN1GetTag(unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag); 00355 00356 /*! CCM initialization. 00357 * 00358 * @param[in] ctx: The CCM context to be initialized. 00359 * 00360 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00361 */ 00362 palStatus_t pal_CCMInit(palCCMHandle_t* ctx); 00363 00364 /*! CCM destruction. 00365 * 00366 * @param[in] ctx: The CCM context to destroy. 00367 * 00368 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00369 */ 00370 palStatus_t pal_CCMFree(palCCMHandle_t* ctx); 00371 00372 /*! CCM set key. 00373 * 00374 * @param[in] ctx: The CCM context to be initialized. 00375 * @param[in] id: The cipher to use (a 128-bit block cipher). 00376 * @param[in] key: The encryption key. 00377 * @param[in] keybits: The key size in bits (must be acceptable by the cipher). 00378 * 00379 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00380 */ 00381 palStatus_t pal_CCMSetKey(palCCMHandle_t ctx, const unsigned char *key, uint32_t keybits, palCipherID_t id); 00382 00383 /*! CCM buffer authenticated decryption. 00384 * 00385 * @param[in] ctx: The CCM context to be initialized. 00386 * @param[in] input A buffer holding the input data. 00387 * @param[in] inLen: The length of the input data. 00388 * @param[in] iv: The initialization vector. 00389 * @param[in] ivLen: The length of IV. 00390 * @param[in] add: Additional data. 00391 * @param[in] addLen: The length of additional data. 00392 * @param[in] tag: A buffer holding the tag. 00393 * @param[in] tag_len: The length of the tag. 00394 * @param[out] output: A buffer for holding the output data. 00395 * 00396 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00397 */ 00398 palStatus_t pal_CCMDecrypt(palCCMHandle_t ctx, unsigned char* input, size_t inLen, 00399 unsigned char* iv, size_t ivLen, unsigned char* add, 00400 size_t addLen, unsigned char* tag, size_t tagLen, 00401 unsigned char* output); 00402 00403 /*! CCM buffer encryption. 00404 * 00405 * @param[in] ctx: The CCM context to be initialized. 00406 * @param[in] input A buffer holding the input data. 00407 * @param[in] inLen: The length of the input data. 00408 * @param[in] iv: The initialization vector. 00409 * @param[in] ivLen: The length of IV. 00410 * @param[in] add: Additional data. 00411 * @param[in] addLen: The length of additional data. 00412 * @param[out] output: A buffer for holding the output data, must be at least `inLen` bytes wide. 00413 * @param[out] tag: A buffer for holding the tag. 00414 * @param[out] tagLen: The length of the tag to generate in bytes. 00415 * 00416 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00417 */ 00418 palStatus_t pal_CCMEncrypt(palCCMHandle_t ctx, unsigned char* input, 00419 size_t inLen, unsigned char* iv, size_t ivLen, 00420 unsigned char* add, size_t addLen, unsigned char* output, 00421 unsigned char* tag, size_t tagLen); 00422 00423 /*! Initiate CTR_DRBG context with given seed. 00424 * 00425 * @param[in] ctx: The CTR_DRBG context to be seeded. 00426 * @param[in] seed: The seed data. 00427 * @param[in] len: The seed data length.. 00428 * 00429 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00430 */ 00431 palStatus_t pal_CtrDRBGInit(palCtrDrbgCtxHandle_t* ctx, const void* seed, size_t len); 00432 00433 /*! CTR_DRBG pseudo random generation. 00434 * 00435 * @param[in] ctx: The CTR_DRBG context. 00436 * @param[out] output: The buffer to fill. 00437 * @param[in] len: The length of the buffer. 00438 * 00439 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00440 */ 00441 palStatus_t pal_CtrDRBGGenerate(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len); 00442 00443 /*! CTR_DRBG destroy 00444 * 00445 * @param[in] ctx: The CTR_DRBG context to destroy. 00446 * 00447 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00448 */ 00449 palStatus_t pal_CtrDRBGFree(palCtrDrbgCtxHandle_t* ctx); 00450 00451 00452 /*! One shot AES cipher CMAC. 00453 * 00454 * @param[in] ctx: The CMAC context to initialize. 00455 * @param[in] key: The encryption key. 00456 * @param[in] keyLenInBits: The key size in bits. 00457 * @param[in] input: A buffer for the input data. 00458 * @param[in] inputLenInBytes: The input data length in bytes. 00459 * @param[out] output: The generic CMAC result. 00460 * 00461 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00462 */ 00463 palStatus_t pal_cipherCMAC(const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output); 00464 00465 /*! Iterative cipher CMAC start 00466 * 00467 * @param[in] ctx: The CMAC context. 00468 * @param[in] key: The CMAC key. 00469 * @param[in] keyLenBits: The key size in bits. 00470 * @param[in] cipherID: A buffer for the input data. 00471 * 00472 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00473 */ 00474 palStatus_t pal_CMACStart(palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID); 00475 00476 /*! Iterative cipher CMAC update. 00477 * 00478 * @param[in] ctx: The CMAC context. 00479 * @param[in] input: A buffer for the input data. 00480 * @param[in] inputLen: The input data length. 00481 * 00482 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00483 */ 00484 palStatus_t pal_CMACUpdate(palCMACHandle_t ctx, const unsigned char *input, size_t inLen); 00485 00486 /*! Iterative cipher CMAC finish. 00487 * 00488 * @param[in] ctx: The CMAC context. 00489 * @param[out] output: A buffer for the output data. 00490 * @param[out] outLen: The output data length. 00491 * 00492 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00493 */ 00494 palStatus_t pal_CMACFinish(palCMACHandle_t *ctx, unsigned char *output, size_t* outLen); 00495 00496 /*! One shot md HMAC. 00497 * 00498 * @param[in] key: The encryption key. 00499 * @param[in] keyLenInBytes: The key size in bytes. 00500 * @param[in] input: A buffer for the input data. 00501 * @param[in] inputLenInBytes: The input data length in bytes. 00502 * @param[out] output: The generic HMAC result. 00503 * @param[out] outputLenInBytes: Size of the HMAC result (optional). 00504 * 00505 \note Expects output to be 32 bytes long 00506 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00507 */ 00508 palStatus_t pal_mdHmacSha256(const unsigned char *key, size_t keyLenInBytes, const unsigned char *input, size_t inputLenInBytes, unsigned char *output, size_t* outputLenInBytes); 00509 00510 00511 /*! Check that the private and/or public key is a valid and the public key is on this curve. 00512 * 00513 * @param[in] grp: The curve/group that the point should belong to. 00514 * @param[in] key: A pointer to a struct holding the raw data of the keys to check. 00515 * @param[in] type: PAL_CHECK_PRIVATE_KEY/PAL_CHECK_PUBLIC_KEY/PAL_CHECK_BOTH_KEYS from `palKeyToCheck_t`. 00516 * @param[out] verified: The result of verification. 00517 * 00518 \note The key can contain only private or public key or both. 00519 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00520 */ 00521 palStatus_t pal_ECCheckKey(palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified); 00522 00523 /*! Allocate key context and initialize a key pair (as an invalid one). 00524 * 00525 * @param[in] key: The key to initialize. 00526 * 00527 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00528 */ 00529 palStatus_t pal_ECKeyNew(palECKeyHandle_t* key); 00530 00531 /*! Release private/public key context related memory. 00532 * 00533 * @param[in] key: A handle for the key context to be freed. 00534 * 00535 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00536 */ 00537 palStatus_t pal_ECKeyFree(palECKeyHandle_t* key); 00538 00539 /*! Parse DER encoded private key. 00540 * 00541 * @param[in] prvDERKey: A buffer that holds the DER encoded private key. 00542 * @param[in] keyLen: The key length. 00543 * @param[out] key: A handle for the context that holds the parsed key. 00544 * 00545 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00546 */ 00547 palStatus_t pal_parseECPrivateKeyFromDER(const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key); 00548 00549 /*! Parse DER encoded public key. 00550 * 00551 * @param[in] pubDERKey: A buffer that holds the DER encoded public key. 00552 * @param[in] keyLen: The key length. 00553 * @param[out] key: A handle for the context that holds the parsed key. 00554 * 00555 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00556 */ 00557 palStatus_t pal_parseECPublicKeyFromDER(const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key); 00558 00559 /*! Encode given private key from key handle to DER buffer. 00560 * 00561 * @param[in] key: A handle to the private key. 00562 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00563 * @param[in] bufferSize: The size of the allocated buffer. 00564 * @param[out] actualSize: The actual size of the written data. 00565 * 00566 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00567 */ 00568 palStatus_t pal_writePrivateKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00569 00570 /*! Encode given public key from key handle to DER buffer. 00571 * 00572 * @param[in] key: A handle to the public key. 00573 * @param[out] derBuffer: A buffer to hold the result of the DER encoding. 00574 * @param[in] bufferSize: The size of the allocated buffer. 00575 * @param[out] actualSize: The actual size of the written data. 00576 * 00577 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00578 */ 00579 palStatus_t pal_writePublicKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize); 00580 00581 /*! Generate a key pair for a given curve. 00582 * 00583 * @param[in] grpID: The ECP group identifier. 00584 * @param[in,out] key: The destination key pair handle. 00585 * 00586 \note The `key` parameter must be first allocated by `pal_ECKeyNew()`. 00587 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00588 */ 00589 palStatus_t pal_ECKeyGenerateKey(palGroupIndex_t grpID, palECKeyHandle_t key); 00590 00591 /*! Retrieve the curve ID if it exists in the given key. 00592 * 00593 * @param[in] key: The key to retrieve its curve. 00594 * @param[out] grpID: The curve/group ID for the given key. In case of error, this pointer contains PAL_ECP_DP_NONE. 00595 * 00596 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00597 */ 00598 palStatus_t pal_ECKeyGetCurve(palECKeyHandle_t key, palGroupIndex_t* grpID); 00599 00600 /*! ECP group initialize and set a group using well-known domain parameters. 00601 * 00602 * @param[in] grp: The destination group. 00603 * @param[in] index: The index in the list of well-known domain parameters. 00604 * 00605 \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure. 00606 */ 00607 palStatus_t pal_ECGroupInitAndLoad(palCurveHandle_t* grp, palGroupIndex_t index); 00608 00609 /*! Free the ECP group context. 00610 * 00611 * @param[in] grp: The curve/group to free. 00612 * 00613 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00614 */ 00615 palStatus_t pal_ECGroupFree(palCurveHandle_t* grp); 00616 00617 /*! Allocate and initialize x509 CSR context. 00618 * 00619 * @param[in] x509CSR: The CSR context to allocate and initialize. 00620 * 00621 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00622 */ 00623 palStatus_t pal_x509CSRInit(palx509CSRHandle_t *x509CSR); 00624 00625 /*! Set the subject name for a CSR. Subject names should contain a comma-separated list of OIDs and values. 00626 * 00627 * @param[in] x509CSR: The CSR context to use. 00628 * @param[in] subjectName: The subject name to set 00629 * 00630 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00631 */ 00632 palStatus_t pal_x509CSRSetSubject(palx509CSRHandle_t x509CSR, const char* subjectName); 00633 00634 /*! Set the MD algorithm to use for the signature. 00635 * 00636 * @param[in] x509CSR: The CSR context to use. 00637 * @param[in] mdType: The MD algorithm to use. 00638 * 00639 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00640 */ 00641 palStatus_t pal_x509CSRSetMD(palx509CSRHandle_t x509CSR, palMDType_t mdType); 00642 00643 /*! Set the key for a CSR. 00644 * 00645 * @param[in] x509CSR: The CSR context to use. 00646 * @param[in] pubKey: The public key to include. To use a key pair handle, see the note. 00647 * @param[in] prvKey: The public key to sign with. 00648 * 00649 \note To use key pair, send it as `pubKey` and NULL as `prvKey`. 00650 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00651 */ 00652 palStatus_t pal_x509CSRSetKey(palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey); 00653 00654 /*! Set the key usage extension flags. 00655 * 00656 * @param[in] x509CSR: The CSR context to use. 00657 * @param[in] keyUsage: The key usage flags, should be taken from `palKeyUsage_t`. 00658 * 00659 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00660 */ 00661 palStatus_t pal_x509CSRSetKeyUsage(palx509CSRHandle_t x509CSR, uint32_t keyUsage); 00662 00663 /*! Generic function to add to the CSR. 00664 * 00665 * @param[in] x509CSR: The CSR context to use. 00666 * @param[in] oid: The OID of the extension. 00667 * @param[in] oidLen: The OID length. 00668 * @param[in] value: The value of the extension OCTET STRING. 00669 * @param[in] valueLen: The value length. 00670 * 00671 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00672 */ 00673 palStatus_t pal_x509CSRSetExtension(palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, 00674 const unsigned char* value, size_t valueLen); 00675 00676 /*! Write a CSR to a DER structure 00677 * 00678 * @param[in] x509CSR: The CSR context to use. 00679 * @param[in] derBuf: A buffer to write to. 00680 * @param[in] derBufLen: The buffer length. 00681 * @param[in] actualDerLen: The actual length of the written data. 00682 * 00683 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00684 */ 00685 palStatus_t pal_x509CSRWriteDER(palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen); 00686 00687 /*! Free the x509 CSR context. 00688 * 00689 * @param[in] x509CSR: The CSR context to free. 00690 * 00691 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00692 */ 00693 palStatus_t pal_x509CSRFree(palx509CSRHandle_t *x509CSR); 00694 00695 /*! Compute the shared secret using elliptic curve Diffie–Hellman. 00696 * 00697 * @param[in] grp: The ECP group. 00698 * @param[in] peerPublicKey: The public key from a peer. 00699 * @param[in] key: The private key. 00700 * @param[out] out: The shared secret. 00701 * 00702 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00703 */ 00704 palStatus_t pal_ECDHComputeKey(const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, 00705 const palECKeyHandle_t privateKey, palECKeyHandle_t outKey); 00706 00707 /*! Compute the ECDSA signature of a previously hashed message. 00708 * 00709 * @param[in] grp: The ECP group. 00710 * @param[in] prvKey: The private signing key. 00711 * @param[in] dgst: The message hash. 00712 * @param[in] dgstLen: The length ofthe message buffer. 00713 * @param[out] sig: A buffer to hold the computed signature. 00714 * @param[out] sigLen: The length of the computed signature. 00715 * 00716 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00717 */ 00718 palStatus_t pal_ECDSASign(palCurveHandle_t grp, palMDType_t mdType, palECKeyHandle_t prvKey, unsigned char* dgst, 00719 uint32_t dgstLen, unsigned char *sig, size_t *sigLen); 00720 00721 /*! Verify the ECDSA signature of a previously hashed message. 00722 * 00723 * @param[in] pubKey: The public key for verification. 00724 * @param[in] dgst: The message hash. 00725 * @param[in] dgstLen: The length of the message buffer. 00726 * @param[in] sign: The signature. 00727 * @param[in] sig: A buffer to hold the computed signature. 00728 * @param[in] sigLen: The length of the computed signature. 00729 * @param[out] verified: A boolean to hold the verification result. 00730 * 00731 \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure. 00732 */ 00733 palStatus_t pal_ECDSAVerify(palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, 00734 unsigned char* sig, size_t sigLen, bool* verified); 00735 00736 00737 #endif //_PAL_CRYPTO_H_
Generated on Tue Jul 12 2022 19:01:36 by
1.7.2