pal_plat_Crypto.h

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 /*! \brief Initiate the Crypto library.
00028  *
00029  * Initialization is not required for some crypto libraries. In such
00030  * cases, the implementation may be empty.
00031  *
00032  * \note This function must be called in the general PAL initializtion function.
00033  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00034  */
00035 palStatus_t pal_plat_initCrypto(void);
00036 
00037 /*! \brief Free resources for the Crypto library.
00038  *
00039  * \note This function must be called in the general PAL cleanup function.
00040  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00041  */
00042 palStatus_t pal_plat_cleanupCrypto(void);
00043 
00044 /*! \brief Initialize an AES context.
00045  *
00046  * @param[in,out] aes: The AES context to be initialized.
00047  *
00048  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00049  */
00050 palStatus_t pal_plat_initAes(palAesHandle_t *aes);
00051 
00052 /*! \brief Free an AES context.
00053  *
00054  * @param[in,out] aes: The AES context to be deallocated.
00055  *
00056  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00057  */
00058 palStatus_t pal_plat_freeAes(palAesHandle_t *aes);
00059 
00060 /*! \brief Set an AES key context for encryption or decryption.
00061  *
00062  * @param[in] aes: The AES context.
00063  * @param[in] key: AES key.
00064  * @param[in] keybits: The size of the key in bits.
00065  * @param[in] keyTarget: The key target, either encryption or decryption.
00066  *
00067  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00068  */
00069 palStatus_t pal_plat_setAesKey(palAesHandle_t aes, const unsigned char* key, uint32_t keybits, palAesKeyType_t keyTarget);
00070 
00071 /*! \brief Use AES-CTR encryption or decryption on a buffer.
00072  *
00073  * @param[in] aes: The AES context.
00074  * @param[in] input: The input data buffer.
00075  * @param[out] output: The output data buffer.
00076  * @param[in] inLen: The length of the input data in bytes.
00077  * @param[in] iv: The initialization vector for AES-CTR.
00078  * @param[in] zeroOffset: Send offset value zero to platform function.
00079  *
00080  * \note Due to the nature of CTR you should use the same key schedule for both encryption and decryption.
00081  * So before calling this function you MUST call `pal_setAesKey()` with the key target PAL_KEY_TARGET_ENCRYPTION to set the key.
00082  *
00083  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00084  */
00085 palStatus_t pal_plat_aesCTR(palAesHandle_t aes, const unsigned char* input, unsigned char* output, size_t inLen, unsigned char iv[16], bool zeroOffset);
00086 
00087 /*! \brief Use AES-ECB encryption or decryption on a block.
00088  *
00089  * @param[in] aes: The AES context.
00090  * @param[in] input: A 16-byte input block.
00091  * @param[out] output: A 16-byte output block.
00092  * @param[in] mode: Choose between encryption (PAL_AES_ENCRYPT) or decryption (PAL_AES_DECRYPT).
00093  *
00094  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00095  */
00096 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);
00097 
00098 /*! \brief Process SHA-256 over the input buffer.
00099  *
00100  * @param[in] input: A buffer for the input data.
00101  * @param[in] inLen: The length of the input data in bytes.
00102  * @param[out] output: SHA-256 checksum result.
00103  *
00104  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00105  */
00106 palStatus_t pal_plat_sha256(const unsigned char* input, size_t inLen, unsigned char* output);
00107 
00108 /*! \brief Initialize a certificate chain context.
00109  *
00110  * @param[in,out] x509: The certificate chain to initialize.
00111  *
00112  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00113  */
00114 palStatus_t pal_plat_x509Initiate(palX509Handle_t* x509);
00115 
00116 /*! \brief Parse one or more certificates and add them to the chained list.
00117  *
00118  * @param[in] x509: The start of the chain.
00119  * @param[in] input: A buffer holding the certificate data in PEM or DER format.
00120  * @param[in] inLen: The size of the input buffer in bytes.
00121  *
00122  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00123  */
00124 palStatus_t pal_plat_x509CertParse(palX509Handle_t x509, const unsigned char* input, size_t inLen);
00125 
00126 /*! \brief Get attributes from the parsed certificate.
00127 *
00128 * @param[in] x509Cert: The parsed certificate.
00129 * @param[in] attr: The required attribute.
00130 * @param[out] output: A buffer to hold the attribute value.
00131 * @param[in] outLenBytes: The size of the allocated buffer in bytes.
00132 * @param[out] actualOutLenBytes: The actual size of the attribute in bytes.
00133 *
00134 * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00135 */
00136 palStatus_t pal_plat_x509CertGetAttribute(palX509Handle_t x509Cert, palX509Attr_t attr, void* output, size_t outLenBytes, size_t* actualOutLenBytes);
00137 
00138 /*! \brief Verify one or more X.509 DER formatted certificates.
00139  *
00140  * @param[in] x509Cert: A handle holding the parsed certificate.
00141  * @param[in] x509CertChain: The start of the chain to verify the X.509 DER certificate with. This is optional.
00142  * @param[out] verifyResult: Bitmask of errors that cause the failure. This value is
00143  *                       relevant ONLY in case that the return value of the function is `PAL_ERR_X509_CERT_VERIFY_FAILED`.
00144  *
00145  * \note In case a platform doesn't support multiple errors for certificate verification, please return `PAL_ERR_X509_CERT_VERIFY_FAILED` and the reason should be specified in the `verifyResult`
00146  * \return PAL_SUCCESS on success.
00147  * \return PAL_ERR_X509_CERT_VERIFY_FAILED in case of failure.
00148  */
00149 palStatus_t pal_plat_x509CertVerifyExtended(palX509Handle_t x509Cert, palX509Handle_t x509CertChain, int32_t* verifyResult);
00150 
00151 /*! \brief Deallocate all certificate data.
00152  *
00153  * @param[in,out] x509: The certificate chain to free.
00154  *
00155  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00156  */
00157 palStatus_t pal_plat_x509Free(palX509Handle_t* x509);
00158 
00159 /*! \brief Initialize an message digest (MD) context and set up the required data according to the given algorithm.
00160  *
00161  * @param[in,out] md: The MD context to be initialized.
00162  * @param[in] mdType: The MD algorithm.
00163  *
00164  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00165  */
00166 palStatus_t pal_plat_mdInit(palMDHandle_t* md, palMDType_t mdType);
00167 
00168 /*! \brief Generic message digest (MD) process buffer.
00169  *
00170  * @param[in] md: The MD context.
00171  * @param[in] input: A buffer holding the input data.
00172  * @param[in] inLen: The length of the input data in bytes.
00173  *
00174  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00175  */
00176 palStatus_t pal_plat_mdUpdate(palMDHandle_t md, const unsigned char* input, size_t inLen);
00177 
00178 /*! \brief Generic message digest (MD) output buffer size getter.
00179  *
00180  * @param[in] md: The MD context.
00181  * @param[out] bufferSize: A pointer to hold the output size of the `pal_mdFinal()` for the given handle.
00182  *
00183  * \note You SHOULD call this function before calling `pal_mdFinal()`.
00184  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00185  */
00186 palStatus_t pal_plat_mdGetOutputSize(palMDHandle_t md, size_t* bufferSize);
00187 
00188 /*! \brief Generic message digest (MD) final digest.
00189  *
00190  * @param[in] md: The MD context.
00191  * @param[in] output: The generic message digest checksum result.
00192  *
00193  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00194  */
00195 palStatus_t pal_plat_mdFinal(palMDHandle_t md, unsigned char* output);
00196 
00197 /*! \brief Free and clear the message digest (MD) context.
00198  *
00199  * @param[in,out] md: The MD context to be freed.
00200  *
00201  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00202  */
00203 palStatus_t pal_plat_mdFree(palMDHandle_t* md);
00204 
00205 /*! \brief Verify the signature.
00206  *
00207  * @param[in] x509: The certificate context that holds the PK data.
00208  * @param[in] mdType: The MD algorithm used.
00209  * @param[in] hash: The hash of the message to sign.
00210  * @param[in] hashLen: The hash length in bytes.
00211  * @param[in] sig: The signature to verify.
00212  * @param[in] sigLen: The signature length in bytes.
00213  *
00214  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00215  */
00216 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 );
00217 
00218 /*! \brief Check for a specific tag.
00219 *   Updates the pointer to immediately after the tag and length.
00220  *
00221  * @param[in,out] position: The initial position in the ASN.1 data.
00222  * @param[in] end: The end of data.
00223  * @param[out] len: The tag length in bytes.
00224  * @param[in] tag: The expected tag.
00225  *
00226  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00227  */
00228 palStatus_t pal_plat_ASN1GetTag(unsigned char **position, const unsigned char *end, size_t *len, uint8_t tag );
00229 
00230 /*! \brief Initialize a CCM context.
00231  *
00232  * @param[in] ctx: The CCM context to be initialized.
00233  *
00234  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00235  */
00236 palStatus_t pal_plat_CCMInit(palCCMHandle_t* ctx);
00237 
00238 /*! \brief Destroy a CCM context.
00239  *
00240  * @param[in] ctx: The CCM context to destroy.
00241  *
00242  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00243  */
00244 palStatus_t pal_plat_CCMFree(palCCMHandle_t* ctx);
00245 
00246 /*! \brief Set the CCM key.
00247  *
00248  * @param[in] ctx:       The CCM context.
00249  * @param[in] id:        The cipher to use (a 128-bit block cipher).
00250  * @param[in] key:       The encryption key.
00251  * @param[in] keybits:   The key size in bits. Must be acceptable by the cipher.
00252  *
00253  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00254  */
00255 palStatus_t pal_plat_CCMSetKey(palCCMHandle_t ctx, palCipherID_t id, const unsigned char *key, unsigned int keybits);
00256 
00257 /*! \brief Apply authenticated CCM decryption on a buffer.
00258  *
00259  * @param[in] ctx:       The CCM context.
00260  * @param[in] input      A buffer holding the input data.
00261  * @param[in] inLen:     The length of the input data in bytes.
00262  * @param[in] iv:        The initialization vector.
00263  * @param[in] ivLen:     The length of the IV in bytes.
00264  * @param[in] add:       Additional data.
00265  * @param[in] addLen:    The length of the additional data in bytes.
00266  * @param[in] tag:       A buffer holding the tag.
00267  * @param[in] tagLen:    The length of the tag in bytes.
00268  * @param[out] output:   A buffer for holding the output data.
00269  *
00270  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00271  */
00272 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);
00273 
00274 /*! \brief Apply CCM encryption on a buffer.
00275  *
00276  * @param[in] ctx:       The CCM context.
00277  * @param[in] input      A buffer holding the input data.
00278  * @param[in] inLen:        The length of the input data in bytes.
00279  * @param[in] iv:        The initialization vector.
00280  * @param[in] ivLen:        The length of the IV in bytes.
00281  * @param[in] add:       Additional data.
00282  * @param[in] addLen:       The length of additional data in bytes.
00283  * @param[out] output:   A buffer for holding the output data, must be at least 'inLen' bytes wide.
00284  * @param[out] tag:      A buffer for holding the tag.
00285  * @param[out] tagLen:   The length of the tag to generate in bytes.
00286  *
00287  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00288  */
00289 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);
00290 
00291 /*! \brief Initializes a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.
00292  *
00293  * @param[in] ctx:   The CTR-DRBG context to be initialized.
00294  *
00295  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00296  */
00297 palStatus_t pal_plat_CtrDRBGInit(palCtrDrbgCtxHandle_t* ctx);
00298 
00299 /*! \brief Destroys a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.
00300  *
00301  * @param[in] ctx:   The CTR-DRBG context to destroy.
00302  *
00303  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00304  */
00305 palStatus_t pal_plat_CtrDRBGFree(palCtrDrbgCtxHandle_t* ctx);
00306 
00307 /*! \brief Check whether a Counter mode Deterministic Random Byte Generator (CTR-DRBG) context is seeded.
00308  *
00309  * Calls to `pal_plat_CtrDRBGGenerate()` only succeed when the context is seeded.
00310  *
00311  * @param[in] ctx:  The CTR-DRBG context to be checked.
00312  *
00313  * \return PAL_SUCCESS if the CTR-DRBG is seeded.
00314  * \return PAL_ERR_CTR_DRBG_NOT_SEEDED if the CTR-DRBG is not yet seeded, meaning calls to `pal_plat_CtrDRBGGenerate()` will fail.
00315  * \return Any other negative value indicating a specific error code in case of failure.
00316  */
00317 palStatus_t pal_plat_CtrDRBGIsSeeded(palCtrDrbgCtxHandle_t ctx);
00318 
00319 /*! \brief Set the initial seed for a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.
00320  *
00321  * @param[in] ctx:  The CTR-DRBG context to be seeded.
00322  * @param[in] seed: The seed data.
00323  * @param[in] len:  The seed data length in bytes.
00324  *
00325  * \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00326  */
00327 palStatus_t pal_plat_CtrDRBGSeed(palCtrDrbgCtxHandle_t ctx, const void* seed, size_t len);
00328 
00329 /*! \brief Generate a random value using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.
00330  *
00331  * @param[in] ctx:  The CTR-DRBG context.
00332  * @param[in] out:  The buffer to fill.
00333  * @param[in] len:  The length of the buffer in bytes.
00334  *
00335  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00336  */
00337 palStatus_t pal_plat_CtrDRBGGenerate(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len);
00338 
00339 /*! \brief Generate a random value with additional input using a Counter mode Deterministic Random Byte Generation (CTR-DRBG) context.
00340  *
00341  * @param[in] ctx:  The CTR-DRBG context.
00342  * @param[in] out:  The buffer to fill.
00343  * @param[in] len:  The length of the buffer in bytes.
00344  * @param[in] additional:   Additional data to update with.
00345  * @param[in] additionalLen:    Length of additional data in bytes.
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_CtrDRBGGenerateWithAdditional(palCtrDrbgCtxHandle_t ctx, unsigned char* out, size_t len, unsigned char* additional, size_t additionalLen);
00350 
00351 #if PAL_CMAC_SUPPORT
00352 
00353 /*! \brief Initialize a Cipher-based Message Authentication Code (CMAC) context with a AES cipher.
00354  *
00355  * @param[in] ctx:               The CMAC context to initialize.
00356  * @param[in] key:               The encryption key.
00357  * @param[in] keyLenInBits:      The key size in bits.
00358  * @param[in] input:             A buffer for the input data.
00359  * @param[in] inputLenInBytes:   The input data length in bytes.
00360  * @param[out] output:           Generic CMAC result.
00361  *
00362  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00363  */
00364 palStatus_t pal_plat_cipherCMAC(const unsigned char *key, size_t keyLenInBits, const unsigned char *input, size_t inputLenInBytes, unsigned char *output);
00365 
00366 /*! \brief Start an iterative cipher CMAC context.
00367  *
00368  * @param[in] ctx:       The CMAC context to initialize.
00369  * @param[in] key:           The CMAC key.
00370  * @param[in] keyLenBits: The key size in bits.
00371  * @param[in] cipherID:   A buffer for the input data.
00372  *
00373  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00374  */
00375 palStatus_t pal_plat_CMACStart(palCMACHandle_t *ctx, const unsigned char *key, size_t keyLenBits, palCipherID_t cipherID);
00376 
00377 /*! \brief Update an iterative cipher CMAC context.
00378  *
00379  * @param[in] ctx:      The CMAC context to initialize.
00380  * @param[in] input:    A buffer for the input data.
00381  * @param[in] inputLen:  The input data length in bytes.
00382  *
00383  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00384  */
00385 palStatus_t pal_plat_CMACUpdate(palCMACHandle_t ctx, const unsigned char *input, size_t inLen);
00386 
00387 /*! \brief Finish an iterative cipher CMAC context.
00388  *
00389  * @param[in] ctx:      The CMAC context to initialize.
00390  * @param[out] output:      A buffer for the output data.
00391  * @param[out] outLen:   The output data length in bytes.
00392  *
00393  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00394  */
00395 palStatus_t pal_plat_CMACFinish(palCMACHandle_t *ctx, unsigned char *output, size_t* outLen);
00396 
00397 #endif //PAL_CMAC_SUPPORT
00398 
00399 /*! \brief Apply a one-shot Message Digest HMAC cipher.
00400  *
00401  * @param[in] key:                  The encryption key.
00402  * @param[in] keyLenInBytes:    The key size in bytes.
00403  * @param[in] input:            A buffer for the input data.
00404  * @param[in] inputLenInBytes:   The input data length in bytes.
00405  * @param[out] output:           The generic HMAC result.
00406  * @param[out] outputLenInBytes: Size of the HMAC result in bytes. Optional.
00407  *
00408  * \note Expects output to be 32 bytes long
00409  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00410  */
00411 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);
00412 
00413 /*! \brief Check that a private or public key is a valid key and the public key is on this curve.
00414  *
00415  * @param[in] grp:      The curve the point should belong to.
00416  * @param[in] key:      A pointer to the struct that holds the keys to check.
00417  * @param[in] type:      Determines whether to check the private key (PAL_CHECK_PRIVATE_KEY), public key (PAL_CHECK_PUBLIC_KEY), or both (PAL_CHECK_BOTH_KEYS).
00418  * @param[out] verified:    The result of the verification.
00419  *
00420  * \note    The key can contain only private or public key or both.
00421  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00422  */
00423 palStatus_t pal_plat_ECCheckKey(palCurveHandle_t grp, palECKeyHandle_t key, uint32_t type, bool *verified);
00424 
00425 /*! \brief Allocate key context and initialize a key pair as an invalid pair.
00426  *
00427  * @param[in] key:  The key pair context to initialize
00428  *
00429  * \return PAL_SUCCESS on success, negative value indicating a specific error code in case of failure.
00430  */
00431 palStatus_t pal_plat_ECKeyNew(palECKeyHandle_t* key);
00432 
00433 /*! \brief Free the components of a key pair.
00434  *
00435  * @param[in] key:  The key pair to free.
00436  *
00437  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00438  */
00439 palStatus_t pal_plat_ECKeyFree(palECKeyHandle_t* key);
00440 
00441 /*! \brief Parse a DER encoded private key.
00442  *
00443  * @param[in] prvDERKey:    A buffer that holds the DER encoded private key.
00444  * @param[in] keyLen:   The key length in bytes.
00445  * @param[out] key:     A handle for the context that holds the parsed key.
00446  *
00447  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00448  */
00449 palStatus_t pal_plat_parseECPrivateKeyFromDER(const unsigned char* prvDERKey, size_t keyLen, palECKeyHandle_t key);
00450 
00451 /*! \brief Parse a DER encoded public key.
00452  *
00453  * @param[in] pubDERKey:    A buffer that holds the DER encoded public key.
00454  * @param[in] keyLen:    The key length in bytes.
00455  * @param[out] key:     A handle for the context that holds the parsed key.
00456  *
00457  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00458  */
00459 palStatus_t pal_plat_parseECPublicKeyFromDER(const unsigned char* pubDERKey, size_t keyLen, palECKeyHandle_t key);
00460 
00461 /*! \brief Encode the given private key from the key handle to the DER buffer.
00462  *
00463  * @param[in] key:       A handle to the private key.
00464  * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00465  * @param[in] bufferSize: The size of the allocated buffer in bytes.
00466  * @param[out] actualSize: The actual size of the written data in bytes.
00467  *
00468  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00469  */
00470 palStatus_t pal_plat_writePrivateKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00471 
00472 /*! \brief Encode the given public key from the key handle to the DER buffer.
00473  *
00474  * @param[in] key:       A handle to the public key.
00475  * @param[out] derBuffer: A buffer to hold the result of the DER encoding.
00476  * @param[in] bufferSize: The size of the allocated buffer in bytes.
00477  * @param[out] actualSize: The actual size of the written data in bytes.
00478  *
00479  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00480  */
00481 palStatus_t pal_plat_writePublicKeyToDer(palECKeyHandle_t key, unsigned char* derBuffer, size_t bufferSize, size_t* actualSize);
00482 
00483 /*! \brief Generate a curve ID for a keypair.
00484  *
00485  * @param[in] grpID:    The generated curve ID.
00486  * @param[in] key:  A handle to the destination keypair.
00487  *
00488  * \note The `key` parameter must be first allocated by `pal_ECKeyNew()`.
00489  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00490  */
00491 palStatus_t pal_plat_ECKeyGenerateKey(palGroupIndex_t grpID, palECKeyHandle_t key);
00492 
00493 /*! \brief Retrieve the curve ID, if it exists, from the given key.
00494  *
00495  * @param[in] key: The key from which to retrieve the curve ID.
00496  * @param[out] grpID: The curve ID for the given key. In case of error, this pointer contains "PAL_ECP_DP_NONE".
00497  *
00498  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00499  */
00500 palStatus_t pal_plat_ECKeyGetCurve(palECKeyHandle_t key, palGroupIndex_t* grpID);
00501 
00502 /*! \brief Allocate and initialize the X.509 certificate signing request (CSR) context.
00503  *
00504  * @param[in] x509CSR:  The CSR context to allocate and initialize.
00505  *
00506  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00507  */
00508 palStatus_t pal_plat_x509CSRInit(palx509CSRHandle_t *x509CSR);
00509 
00510 /*! \brief Set the subject name for a certificate signing request (CSR). The subject name should contain a comma-separated list of OIDs and values.
00511  *
00512  * @param[in] x509CSR:    The CSR context to use.
00513  * @param[in] subjectName: The subject name to set.
00514  *
00515  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00516  */
00517 palStatus_t pal_plat_x509CSRSetSubject(palx509CSRHandle_t x509CSR, const char* subjectName);
00518 
00519 /*! \brief Set the message digest (MD) algorithm to use for the signature.
00520  *
00521  * @param[in] x509CSR:   The CSR context to use.
00522  * @param[in] mdType:    The MD algorithm to use.
00523  *
00524  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00525  */
00526 palStatus_t pal_plat_x509CSRSetMD(palx509CSRHandle_t x509CSR, palMDType_t mdType);
00527 
00528 /*! \brief Set the key for a CSR.
00529  *
00530  * @param[in] x509CSR:   The CSR context to use.
00531  * @param[in] pubKey:    The public key to include. To use a keypair handle, see the note.
00532  * @param[in] prvKey:    The public key to sign with.
00533  *
00534  * \note To use a keypair, please send it as `pubKey` and NULL as `prvKey`.
00535  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00536  */
00537 palStatus_t pal_plat_x509CSRSetKey(palx509CSRHandle_t x509CSR, palECKeyHandle_t pubKey, palECKeyHandle_t prvKey);
00538 
00539 /*! \brief Set flags for key usage extension.
00540  *
00541  * @param[in] x509CSR:   The CSR context to use.
00542  * @param[in] keyUsage:  The key usage flags. See `palKeyUsage_t` for options.
00543  *
00544  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00545  */
00546 palStatus_t pal_plat_x509CSRSetKeyUsage(palx509CSRHandle_t x509CSR, uint32_t keyUsage);
00547 
00548 /*! \brief Set flags for extended key usage extension.
00549  *
00550  * @param[in] x509CSR:   The CSR context to use.
00551  * @param[in] extKeyUsage:  The extended key usage flags, should be taken from `palExtKeyUsage_t`.
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_x509CSRSetExtendedKeyUsage(palx509CSRHandle_t x509CSR, uint32_t extKeyUsage);
00556 
00557 /*! \brief Generic function to add to the CSR.
00558  *
00559  * @param[in] x509CSR:  The CSR context to use.
00560  * @param[in] oid:         The OID of the extension.
00561  * @param[in] oidLen:   The OID length in bytes.
00562  * @param[in] value:    The value of the extension OCTET STRING.
00563  * @param[in] valueLen:  The value length in bytes.
00564  *
00565  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00566  */
00567 palStatus_t pal_plat_x509CSRSetExtension(palx509CSRHandle_t x509CSR,const char* oid, size_t oidLen, const unsigned char* value, size_t valueLen);
00568 
00569 /*! \brief Write a CSR to a DER structure.
00570  *
00571  * @param[in] x509CSR:       The CSR context to use.
00572  * @param[in] derBuf:       A buffer to write to.
00573  * @param[in] derBufLen:    The buffer length in bytes.
00574  * @param[in] actualDerLen:     The actual length of the written data in bytes.
00575  *
00576  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00577  */
00578 palStatus_t pal_plat_x509CSRWriteDER(palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerLen);
00579 
00580 /*! \brief Write a CSR from a given X.509 Certificate
00581  *
00582  * @param[in] x509Cert:      The parsed X.509 certificate.
00583  * @param[in,out] x509CSR:   A valid handle to a CSR that has already been initialized with at least private key.
00584  * @param[out] derBuf:          A buffer to write to.
00585  * @param[out] derBufLen:   The buffer length in bytes.
00586  * @param[out] actualDerBufLen: The actual length of the written data in bytes.
00587  *
00588  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00589  */
00590 palStatus_t pal_plat_x509CSRFromCertWriteDER(palX509Handle_t x509Cert, palx509CSRHandle_t x509CSR, unsigned char* derBuf, size_t derBufLen, size_t* actualDerBufLen);
00591 
00592 /*! \brief Calculate the hash of the To Be Signed (TBS) part of an X.509 certificate.
00593  *
00594  * This function may be used to validate a certificate signature. To do so, use this function to retrieve the hash, then verify the signature using the hash, the public key and the signature of the X.509
00595  *
00596  * @param[in] x509Cert:         Handle to the certificate to hash the TBS.
00597  * @param[in] hash_type:            The hash type. Currently only PAL_SHA256 supported
00598  * @param[out] output:          Pointer to a buffer that will contain the hash digest. This buffer must be at least the size of the digest. When `hash_type` is PAL_SHA256, then buffer pointed to by output must be at least 32 bytes.
00599  * @param[in] outLenBytes:       The size of the buffer pointed to by output in bytes. Must be at least the size of the digest.
00600  * @param[out] actualOutLenBytes:    Size of the digest copied to output in bytes. In case of success, will always be the length of the hash digest.
00601  *
00602  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00603  */
00604 palStatus_t pal_plat_x509CertGetHTBS(palX509Handle_t x509Cert, palMDType_t hash_type, unsigned char* output, size_t outLenBytes, size_t* actualOutLenBytes);
00605 
00606 /*! \brief Free the X.509 CSR context.
00607  *
00608  * @param[in] x509CSR:  The CSR context to free.
00609  *
00610  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00611  */
00612 palStatus_t pal_plat_x509CSRFree(palx509CSRHandle_t *x509CSR);
00613 
00614 /*! \brief Compute a shared secret.
00615  *
00616  * @param[in] grp:          The ECP group.
00617  * @param[in] peerPublicKey:    The public key from a peer.
00618  * @param[in] privateKey:   The private key.
00619  * @param[out] outKey:      The shared secret.
00620  *
00621  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00622  */
00623 palStatus_t pal_plat_ECDHComputeKey(const palCurveHandle_t grp, const palECKeyHandle_t peerPublicKey, const palECKeyHandle_t privateKey, palECKeyHandle_t outKey);
00624 
00625 /*! \brief Compute the ECDSA signature of a previously hashed message.
00626  *
00627  * @param[in] grp:      The ECP group.
00628  * @param[in] prvKey:   The private signing key-
00629  * @param[in] dgst:     The message hash.
00630  * @param[in] dgstLen:  The length of the message buffer in bytes.
00631  * @param[out] sig:     A buffer to hold the computed signature.
00632  * @param[out] sigLen:  The length of the computed signature in bytes.
00633  *
00634  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00635  */
00636 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);
00637 
00638 /*! \brief Verify the ECDSA signature of a previously hashed message.
00639  *
00640  * @param[in] pubKey:   The public key for verification.
00641  * @param[in] dgst:     The message hash.
00642  * @param[in] dgstLen:  The length of the message buffer in bytes.
00643  * @param[in] sign:     The signature.
00644  * @param[in] sig:      A buffer to hold the computed signature.
00645  * @param[in] sigLen:    The length of the computed signature in bytes.
00646  * @param[out] verified: The boolean to hold the verification result.
00647  *
00648  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00649  */
00650 palStatus_t pal_plat_ECDSAVerify(palECKeyHandle_t pubKey, unsigned char* dgst, uint32_t dgstLen, unsigned char* sig, size_t sigLen, bool* verified);
00651 
00652 /*! \brief Free the components of an ECP group.
00653  *
00654  * @param[in] grp:  The group to free.
00655  *
00656  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00657  */
00658 palStatus_t pal_plat_ECGroupFree(palCurveHandle_t* grp);
00659 
00660 /*! \brief Initialize an ECP group and set it using well-known domain parameters.
00661  *
00662  * @param[in] grp:  The destination group.
00663  * @param[in] index:    The index in the list of well-known domain parameters.
00664  *
00665  * \return PAL_SUCCESS on success. A negative value indicating a specific error code in case of failure.
00666  */
00667 palStatus_t pal_plat_ECGroupInitAndLoad(palCurveHandle_t* grp, palGroupIndex_t index);
00668 
00669 
00670 #endif //_PAL_PLAT_CRYPTO_H_