cert_store.h

Go to the documentation of this file.

/*
 * cert_store.h
 *
 * Certificate Store Header
 *
 * Copyright 2019-2024 DigiCert, Inc. All Rights Reserved.
 * Proprietary and Confidential Material.
 *
 */

#include "../common/initmocana.h"

#ifndef __CERT_STORE_HEADER__
#define __CERT_STORE_HEADER__

#ifdef __cplusplus
extern "C" {
#endif

/*------------------------------------------------------------------*/

#ifndef MAX_SIZE_CERT_STORE_TRUST_HASH_TABLE
#define MAX_SIZE_CERT_STORE_TRUST_HASH_TABLE        (0x1f)
#endif

/* left first octet is reserved */
#define CERT_STORE_ALGO_FLAG_RESERVED               (0xFF000000L)
/* left second octet is for ECDSA curves */
#define CERT_STORE_ALGO_FLAG_ECCURVES               (0x00FF0000L)
/* left third octet is for sign keyType */
#define CERT_STORE_ALGO_FLAG_SIGNKEYTYPE            (0x0000FF00L)
/* right most octet is for HASH algorithms */
#define CERT_STORE_ALGO_FLAG_HASHALGO               (0x000000FFL)

/* Function Like Macros for setting algo id's for a cert key or sign algo */
#define CERT_STORE_ALGO_ID_SET_KEYTYPE( id, value) (id) |= (((value) & 0xff) << 24 )
#define CERT_STORE_ALGO_ID_SET_HASH( id, value)    (id) |= (((value) & 0xff) << 16 )
#define CERT_STORE_ALGO_ID_SET_QSALG( id, value)   (id) |= (((value) & 0xffff) << 8 )
#define CERT_STORE_ALGO_ID_SET_CURVE( id, value)   (id) |= ((value) & 0xff)

#define CERT_STORE_ALGO_ID_GET_KEYTYPE(id)  ((id & 0xff000000) >> 24)
#define CERT_STORE_ALGO_ID_GET_HASH(id)     ((id & 0x00ff0000) >> 16)

#define CERT_STORE_ALGO_ID_HASH_MASK                (0x00ff0000L)

#define CERT_STORE_ALGO_ID_MASK_REMOVE_HASH_MASK    (~CERT_STORE_ALGO_ID_HASH_MASK)
#define CERT_STORE_ALGO_ID_MASK_REMOVE_CURVE_MASK   (0xffffff00L)

/* individual flags: ec curves */
#define CERT_STORE_ALGO_FLAG_EC192                  (0x00010000L)

#define CERT_STORE_ALGO_FLAG_EC224                  (0x00020000L)

#define CERT_STORE_ALGO_FLAG_EC256                  (0x00040000L)

#define CERT_STORE_ALGO_FLAG_EC384                  (0x00080000L)

#define CERT_STORE_ALGO_FLAG_EC521                  (0x00100000L)
#define CERT_STORE_ALGO_FLAG_EC25519                (0x00200000L)
#define CERT_STORE_ALGO_FLAG_EC448                  (0x00400000L)

/* individual flags: signing keyType */
#define CERT_STORE_ALGO_FLAG_RSA                    (0x00000100L)

#define CERT_STORE_ALGO_FLAG_ECDSA                  (0x00000200L)

#define CERT_STORE_ALGO_FLAG_DSA                    (0x00000400L)
#define CERT_STORE_ALGO_FLAG_EDDSA_25519            (0x00000800L)
#define CERT_STORE_ALGO_FLAG_EDDSA_448              (0x00001000L)
#define CERT_STORE_ALGO_FLAG_HYBRID                 (0x00002000L)

/* individual flags: hash algos */
#define CERT_STORE_ALGO_FLAG_MD5                    (0x00000001L)

#define CERT_STORE_ALGO_FLAG_SHA1                   (0x00000002L)

#define CERT_STORE_ALGO_FLAG_SHA224                 (0x00000004L)

#define CERT_STORE_ALGO_FLAG_SHA256                 (0x00000008L)

#define CERT_STORE_ALGO_FLAG_SHA384                 (0x00000010L)

#define CERT_STORE_ALGO_FLAG_SHA512                 (0x00000020L)
#define CERT_STORE_ALGO_FLAG_INTRINSIC              (0x00000040L)

/*------------------------------------------------------------------*/

enum authTypes
{
    CERT_STORE_AUTH_TYPE_RSA                        = 0,
    CERT_STORE_AUTH_TYPE_ECDSA                      = 1,
    CERT_STORE_AUTH_TYPE_DSA                        = 2,
    CERT_STORE_AUTH_TYPE_RSA_PSS                    = 3,
    CERT_STORE_AUTH_TYPE_EDDSA                      = 4,
    CERT_STORE_AUTH_TYPE_HYBRID                     = 5,
    CERT_STORE_AUTH_TYPE_ARRAY_SIZE                 = 6     /* needs to be last */
};

enum identityTypes
{
    CERT_STORE_IDENTITY_TYPE_NAKED                  = 0,
    CERT_STORE_IDENTITY_TYPE_CERT_X509_V3           = 1,
    CERT_STORE_IDENTITY_TYPE_ARRAY_SIZE             = 2     /* needs to be last */
};

/*------------------------------------------------------------------*/

struct AsymmetricKey;
struct certStore;
struct SizedBuffer;

typedef struct certStore* certStorePtr;

#if defined(__ENABLE_MOCANA_MINIMAL_CA__)
struct certStoreIssuer;
typedef struct certStoreIssuer* certStoreIssuerPtr;
#endif

typedef sbyte4 (*ExtendedDataCallback)(sbyte4 extDataIdentifier, enum dataType *pType, enum dataEncoding *pFormat,
                                     sbyte **ppBuffer, sbyte4 *pBufferLen);

/*------------------------------------------------------------------*/

MOC_EXTERN MSTATUS CERT_STORE_createStore (
  certStorePtr *ppNewStore
  );

MOC_EXTERN MSTATUS CERT_STORE_releaseStore (
  certStorePtr *ppReleaseStore
  );

/* Load a MocCtx into this cert store. If later operations need it, it's there.
 * This function will acquire a reference to the MocCtx, and then when the store
 * is released, it will release it. That is, the caller does not need to do
 * anything beyond calling _releaseStore (which it is already doing, right?).
 */
MOC_EXTERN MSTATUS CERT_STORE_loadMocCtx (
  certStorePtr pCertStore,
  MocCtx pMocCtx
  );

/* handy conversion functions */
MOC_EXTERN MSTATUS CERT_STORE_convertCertStoreKeyTypeToPubKeyType(ubyte4 certStoreKeyType, ubyte4 *pRetPubKeyType);

/* add identity */
#ifndef __DISABLE_MOCANA_CERTIFICATE_PARSING__

MOC_EXTERN MSTATUS CERT_STORE_addIdentity (
  certStorePtr pCertStore,
  const ubyte *pDerCert,
  ubyte4 derCertLength,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityEx (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  ubyte *pDerCert,
  ubyte4 derCertLength,
  ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChain (
  certStorePtr pCertStore,
  struct SizedBuffer *certificates,
  ubyte4 numCertificate,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

MOC_EXTERN MSTATUS
CERT_STORE_addIdentityWithCertificateChainExtData(certStorePtr pCertStore,
  struct SizedBuffer *certificates,
  ubyte4 numCertificate,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength,
  ExtendedDataCallback extDataFunc,
  sbyte4 extDataIdentifier
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChainExtDataEx (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct SizedBuffer *certificates,
  ubyte4 numCertificate,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength,
  ExtendedDataCallback extDataFunc,
  sbyte4 extDataIdentifier
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityWithCertificateChainEx (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct SizedBuffer *certificates,
  ubyte4 numCertificate,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

#endif /* ifndef __DISABLE_MOCANA_CERTIFICATE_PARSING__ */

MOC_EXTERN MSTATUS CERT_STORE_addIdentityNakedKey (
  certStorePtr pCertStore,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityNakedKeyEx (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  ubyte *pKeyBlob,
  ubyte4 keyBlobLength
  );

MOC_EXTERN MSTATUS CERT_STORE_addIdentityPSK(certStorePtr pCertStore,
                                             const ubyte *pPskIdentity,
                                             ubyte4 pskIdentityLength,
                                             const ubyte *pPskHint,
                                             ubyte4 pskHintLength,
                                             const ubyte *pPskSecret,
                                             ubyte4 pskSecretLength);

#ifndef __DISABLE_MOCANA_CERTIFICATE_PARSING__

MOC_EXTERN MSTATUS CERT_STORE_addTrustPoint(certStorePtr pCertStore,
                                            const ubyte *pDerTrustPoint,
                                            ubyte4 derTrustPointLength);

#ifdef __ENABLE_MOCANA_CV_CERT__

MOC_EXTERN MSTATUS CERT_STORE_CVC_addTrustPoint(certStorePtr pCertStore,
                                            const ubyte *pTrustPoint,
                                            ubyte4 trustPointLength);

#endif

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubjectFirst(const certStorePtr pCertStore,
                                                           const ubyte *subject,
                                                           ubyte4 subjectLength,
                                                           const ubyte **ppRetDerCert,
                                                           ubyte4 *pRetDerCertLength,
                                                           const void** iterator);

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubjectNext(const void** iterator,
                                                         const ubyte **ppRetDerCert,
                                                         ubyte4* pRetDerCertLength);


/* test function: return OK if  match, ERR_FALSE if no match, anything else to
 stop the search */
typedef MSTATUS (*CERT_STORE_MatchFun) (MOC_ASYM(hwAccelDescr hwAccelCtx)
                                        const void* arg,
                                        const ubyte* testCert,
                                        ubyte4 testCertLen);

MOC_EXTERN MSTATUS CERT_STORE_findTrustPointBySubject(MOC_ASYM(hwAccelDescr hwAccelCtx)
                                                      const certStorePtr pCertStore,
                                                      const ubyte* subject,
                                                      ubyte4 subjectLength,
                                                      const void* cbArg,
                                                      CERT_STORE_MatchFun cb,
                                                      const ubyte** ppRetDerCert,
                                                      ubyte4* pRetDerCertLength);

MOC_EXTERN MSTATUS CERT_STORE_traverseTrustPoints(MOC_ASYM(hwAccelDescr hwAccelCtx)
                                                  const certStorePtr pCertStore,
                                                  const void* cbArg,
                                                  CERT_STORE_MatchFun cb);
#endif

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByAlias (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct AsymmetricKey **ppReturnIdentityKey,
  ubyte **ppRetDerCert,
  ubyte4 *pRetDerCertLength
  );

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByAliasAndAlgo (
  certStorePtr pCertStore,
  ubyte4 pubKeyType,
  ubyte2 keyUsage,
  ubyte4 *pSupportedCertKeyAlgos,
  ubyte4 supportedCertKeyAlgosLen,
  ubyte4 *pSupportedSignAlgos,
  ubyte4 supportedSignAlgosLen, 
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct AsymmetricKey **ppReturnIdentityKey,
  struct SizedBuffer **ppRetCertificates,
  ubyte4 *pRetNumCertificates,
  void **ppRetHint
  );

/* Find the identity in the cert store associated with the given "alias".
 * <p>The function will look through the given store, and compare the alias in
 * each entry with the one passed in. If it is the same, it will return the key
 * and cert chain from that entry.
 * <p>Note that an entry might have only a key or a cert, or both a key and cert.
 * <p>The function will return references to the key and cert insde the store, it
 * will not build a new AsymmetricKey object, nor will it allocate memory for the
 * cert it returns. Do not alter or uninit the key and do not alter or free the
 * cert buffer returned.
 * <p>If the function cannot find an entry with the given alias, it will set the
 * return key and cert chain args to NULL/0 and return OK. That is, if it finds no
 * entry, that is not an error, it simply indicates there is no entry with that
 * alias.
 * <p>You might only want a key, and not a cert. If so, you can pass NULL for the
 * ppRetDerCert and pRetDerCertLen args. That is not an error. The function will
 * return a reference to the key and not a cert. Similarly, you can pass NULL for
 * the key and receive only a cert chain.
 * <p>It is possible an entry has no key, only a cert. This function will return
 * a pointer to an AsymmetricKey, but it might be empty. Check the return key's
 * type. If it is 0 (akt_undefined), there is no key.
 *
 * @param pCertStore The store to search.
 * @param pAlias The alias, or name of the entry, against which the cert will be
 * made.
 * @param aliasLen The length, in bytes, of the alias.
 * @param ppReturnIdentityKey If not NULL, the address where the function will
 * deposit a reference to the key object inside the cert store for the entry
 * associated with the alias.
 * @param ppRetCertificates If not NULL, the address where the function will
 * deposit a reference to the cert chain corresponding to the entry.
 * for the given alias.
 * @param pRetNumCertificates If not NULL, the address where the function will
 * deposit the number of certificates in the returned chain.
 * @return     \c OK (0) if successful; otherwise a negative number error code
 *             definition from merrors.h. To retrieve a string containing an
 *             English text error identifier corresponding to the function's
 *             returned error status, use the \c DISPLAY_ERROR macro.
 */
MOC_EXTERN MSTATUS CERT_STORE_findIdentityByAliasEx (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct AsymmetricKey **ppReturnIdentityKey,
  struct SizedBuffer **ppRetCertificates,
  ubyte4 *pRetNumCertificates
  );

MOC_EXTERN MSTATUS CERT_STORE_updateIdentityByAliasExtData (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct SizedBuffer *pCertChain,
  ubyte4 certChainCount,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLen,
  ExtendedDataCallback extDataFunc,
  sbyte4 extDataIdentifier
  );

MOC_EXTERN MSTATUS CERT_STORE_getIdentityPairExtData (
  void *pIdentity,
  ExtendedDataCallback *pExtDataFunc,
  sbyte4 *pExtDataIdentifier
);

MOC_EXTERN MSTATUS CERT_STORE_updateIdentityByAlias (
  certStorePtr pCertStore,
  ubyte *pAlias,
  ubyte4 aliasLen,
  struct SizedBuffer *pCertChain,
  ubyte4 certChainCount,
  const ubyte *pKeyBlob,
  ubyte4 keyBlobLen
  );

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByTypeFirst(const certStorePtr pCertStore,
                                                      enum authTypes authType,
                                                      enum identityTypes identityType,
                                                      const struct AsymmetricKey** ppRetIdentityKey,
                                                      const ubyte **ppRetDerCert,
                                                      ubyte4 *pRetDerCertLength,
                                                      void** ppRetHint);

MOC_EXTERN MSTATUS CERT_STORE_findIdentityByTypeNext(const certStorePtr pCertStore,
                                                     enum authTypes authType,
                                                     enum identityTypes identityType,
                                                     const struct AsymmetricKey** ppRetIdentityKey,
                                                     const ubyte **ppRetDerCert,
                                                     ubyte4 *pRetDerCertLength,
                                                     void** ppRetHint);

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirstEx(const certStorePtr pCertStore,
                                                           ubyte4 pubKeyType,
                                                           ubyte2 keyUsage,
                                                           ubyte4 supportedAlgoFlags,
                                                           const struct AsymmetricKey** ppRetIdentityKey,
                                                           const struct SizedBuffer** ppRetCertificates,
                                                           ubyte4 *pRetNumberCertificate,
                                                           void** ppRetHint);

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNextEx(const certStorePtr pCertStore,
                                                          ubyte4 pubKeyType,
                                                          ubyte2 keyUsage,
                                                          ubyte4 supportedKeyTypeAndAlgoFlags,
                                                          const struct AsymmetricKey** ppRetIdentityKey,
                                                          const struct SizedBuffer** ppRetCertificates,
                                                          ubyte4 *pRetNumberCertificate,
                                                          void** ppRetHint);



MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirstFromList(
                                                           const certStorePtr pCertStore,
                                                           ubyte4 pubKeyType,
                                                           ubyte2 keyUsage,
                                                           ubyte4 *pSupportedCertKeyIds,
                                                           ubyte4 supportedCertKeyIdsLen,
                                                           ubyte4 *pSupportedSignAlgoIds,
                                                           ubyte4 supportedSignAlgoIdsLen,                                                           
                                                           const struct AsymmetricKey** ppRetIdentityKey,
                                                           const struct SizedBuffer** ppRetCertificates,
                                                           ubyte4 *pRetNumberCertificate,
                                                           void** ppRetHint);


MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNextFromList(
                                                          const certStorePtr pCertStore,
                                                          ubyte4 pubKeyType,
                                                          ubyte2 keyUsage,
                                                          ubyte4 *pSupportedCertKeyIds,
                                                          ubyte4 supportedCertKeyIdsLen,
                                                          ubyte4 *pSupportedSignAlgoIds,
                                                          ubyte4 supportedSignAlgoIdsLen,  
                                                          const struct AsymmetricKey** ppRetIdentityKey,
                                                          const struct SizedBuffer** ppRetCertificates,
                                                          ubyte4 *pRetNumberCertificate,
                                                          void** ppRetHint);

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainFirst(const certStorePtr pCertStore,
                                                             ubyte4 pubKeyType,
                                                             ubyte4 supportedAlgoFlags,
                                                             const struct AsymmetricKey** ppRetIdentityKey,
                                                             const struct SizedBuffer** ppRetCertificates,
                                                             ubyte4 *pRetNumberCertificate,
                                                             void** ppRetHint);

MOC_EXTERN MSTATUS CERT_STORE_findIdentityCertChainNext(const certStorePtr pCertStore,
                                                            ubyte4 pubKeyType,
                                                            ubyte4 supportedKeyTypeAndAlgoFlags,
                                                            const struct AsymmetricKey** ppRetIdentityKey,
                                                            const struct SizedBuffer** ppRetCertificates,
                                                            ubyte4 *pRetNumberCertificate,
                                                            void** ppRetHint);

/* traverse/find a psk */
MOC_EXTERN MSTATUS CERT_STORE_traversePskListHead(const certStorePtr pCertStore,
                                                  ubyte **ppRetPskIdentity,
                                                  ubyte4 *pRetPskIdentityLength,
                                                  ubyte **ppRetPskHint,
                                                  ubyte4 *pRetPskHintLength,
                                                  ubyte **ppRetPskSecret,
                                                  ubyte4 *pRetPskSecretLength,
                                                  void** ppRetHint);
MOC_EXTERN MSTATUS CERT_STORE_traversePskListNext(const certStorePtr pCertStore,
                                                  ubyte **ppRetPskIdentity,
                                                  ubyte4 *pRetPskIdentityLength,
                                                  ubyte **ppRetPskHint,
                                                  ubyte4 *pRetPskHintLength,
                                                  ubyte **ppRetPskSecret,
                                                  ubyte4 *pRetPskSecretLength,
                                                  void** ppRetHint);
MOC_EXTERN MSTATUS CERT_STORE_findPskByIdentity(const certStorePtr pCertStore,
                                                ubyte *pPskIdentity,
                                                ubyte4 pskIdentityLength,
                                                ubyte **ppRetPskSecret,
                                                ubyte4 *pRetPskSecretLength);
/* find a certificate and possibly key by issuer/serial number */
MOC_EXTERN MSTATUS
CERT_STORE_findCertificateByIssuerSerialNumber(const certStorePtr pCertStore,
                                               const ubyte* pIssuer,
                                               ubyte4 issuerLength,
                                               const ubyte* serialNumber,
                                               ubyte4 serialNumberLength,
                                               const ubyte** ppRetDerCert,
                                               ubyte4* ppRetDerCertLength,
                                               const struct AsymmetricKey** pRetPrivateKey);

#if defined(__ENABLE_MOCANA_MINIMAL_CA__)

MOC_EXTERN MSTATUS
CERT_STORE_createIssuerStore(sbyte *pDirPath, certStoreIssuerPtr *pStore);

MOC_EXTERN MSTATUS
CERT_STORE_releaseIssuerStore(certStoreIssuerPtr *pStore);

MOC_EXTERN MSTATUS
CERT_STORE_traverseChildCertsByFile(
    certStoreIssuerPtr pStore, void **ppCookie, ubyte4 *pIndex, sbyte **ppFile);

#endif /* __ENABLE_MOCANA_MINIMAL_CA__ */

#ifdef __cplusplus
}
#endif

#endif /* __CERT_STORE_HEADER__ */