libenatsc3ssp

libentasc3ssp provides a mechanism for implementing A/360 Security and Service Protection. libenatsc3ssp manages an SSP certificate store populated via Certification Data Tables and which can then be used to verify Signed Multitables. The present implementation of libenatsc3ssp uses the OpenSSL library for cryptography.

Note that full certificate chain verification requires the root certificate from A3SA (as well as any intermediate certificates not provided in the CDT). A callback function is provided so that the application can load these certificate(s) into an OpenSSL X509_STORE.

For development and testing libenatsc3ssp functions allow for excluding certain checks such as signing certificate verification.  Warning message such as “WARN: Not verifying certificate chain” will be printed when these checks are excluded.

Usage

    • Clients instantiate an SSP store via ENATSC3SSPCreate. Clients that have certificates in secure storage should supply an ENATSC3SSPLoadCertificatesCallback so that they can be loaded into the SSP.
    • Clients populate the store by providing Certification Data Tables via ENATSC3SSPVerifyAndLoadCertificationData. ENATSC3SSPLoadCertificatesCallback is called when the SSP (re)initializes the store in response to processing a Certification Data Table.
    • Clients call SSP functions to verify signatures against the SSP certificate store.
    • When the application is done with the store it is destroyed by ENATSC3SSPDestroy.

Callback Functions

typedef ENStatus (*ENATSC3SSPLoadCertificatesCallback)(
    ENATSC3SSPHandle_t hSSP, 
    STACK_OF(X509) *pCertificatesStack,
    void *pUserData
);

ENATSC3SSPLoadCertificatesCallback provides an opportunity for clients to provide certificates that are not supplied OTA via the broadcast but are instead stored in a platform’s secure storage. The client can load these certificates directly into the supplied OpenSSL X509 certificates stack.

Parameters
    • hSSP: The SSP requesting the certificates.
    • pCertificatesStack: An OpenSSL X509 certificates stack into which the client should load certificates.
    • pUserData: Client-supplied user data pointer that was registered when the SSP was created via ENATSC3SSPCreate.

Function Reference

ENStatus ENATSC3SSPCreate(
    ENATSC3SSPLoadCertificatesCallback LoadCertificatesCallback,
    void *pCallbackUserData,
    ENATSC3SSPHandle_t *phSSP
);

ENATSC3SSPCreate creates an SSP certificate store.

Parameters
    • LoadCertificatesCallback: A callback function allowing clients to load certificates into the OpenSSL X509 certificate store. This parameter may be NULL.
    • pCallbackUserData: A pointer passed as the pUserData argument of LoadCertificatesCallback.
    • phSSP: On successful return contains a handle to the certificate store.
Return Values
    • ENStatus_Success: An SSP certificate store was instantiated and a handle to the it is returned in *phSSP. The store must be destroyed with ENATSC3SSPDestroy when it is no longer needed by the application.
    • ENStatus_Failure: An error was encountered while instantiating the store . The value of *phSSP is undefined.
ENStatus ENATSC3SSPDestroy(
    ENATSC3SSPHandle_t hSSP)
);

ENATSC3SSPDestroy destroys an SSP store created with ENATSC3SSPCreate.

Parameters
    • hSSP: A handle to the SSP store to destroy.
Return Values
    • ENStatus_Success: The store was destroyed.
    • ENStatus_Failure: An error was encountered while destroying the store.
ENStatus ENATSC3SSPVerifyAndLoadCertificationData(
    ENATSC3SSPHandle_t hSSP, 
    char *pXML,
    int32_t xmlLength, 
    ATSC3LLSCDT_CertificationDataNode *pParsedCDT,
    struct timespec *pAbsMonoTimeout, 
    int32_t fDontVerifyCertificate,
    int32_t fIgnoreOCSPResponseExpired
);

ENATSC3SSPVerifyAndLoadCertificationData verifies a Certification Data Table and, upon successful verification, loads its contents into the store.

Parameters
    • hSSP: A handle to the SSP certificate store.
    • pXML: A pointer to the CDT XML document.
    • xmlLength: The length in bytes of the XML document pointed to by pXML.
    • pParsedCDT: The CDT parsed into the EnXML format.
    • pAbsMonoTimeout: A timeout bounding how long the SSP will wait for modification access to the certificate store. SSP functions lock the certificate store against modification while they operate. pAbsMonoTime is specified as an absolute time against CLOCK_MONOTONIC.
    • fDontVerifyCertificateChain: Do not verify the signing certificate when verifying the CDT’s signature. This is intended for use during development.
    • fIgnoreOCSPResponseExpired: Ignore OCSP Response expirations. This may be useful during development or testing against captured bitstreams.
Return Values
    • ENStatus_Success: The Certification Data Table was successfully processed. The certificates in the SSP’s store are replaced by those from the Certification Data Table and any certificates provided by ENATSC3SSPLoadCertificatesCallback.
    • ENStatus_Failure: An error was encountered while processing the Certification Data Table. The SSP’s certificate store is unchanged.
    • ENStatus_Retry: The SSP timed out while waiting for access to the certificate store. The SSP’s certificate store is unchanged.
ENStatus ENATSC3SSPVerifySignedMultitableSignature(
    ENATSC3SSPHandle_t hSSP,
    const uint8_t *pSignedMultitable, 
    int32_t signedMultitableLen,
    int32_t fDontVerifySigningCertificate
);

Clients call ENATSC3SSPVerifySignedMultitableSignature to verify the signature of a Signed Multitable XML document. ENATSC3SSPVerifySignedMultitableSignature will fail if the SSP store has not been populated via a successful call to ENATSC3SSPVerifyAndLoadCertificationData.

Parameters
    • hSSP: A handle to the SSP store which will validate the signature.
    • pSignedMultitable: A pointer to the Signed Multitable XML document.
    • : The length in bytes of the XML Signed Multitable document pointed to by pSignedMultitable.
    • fDontVerifySigningCertificate: If non-zero, then the certificate used to sign the Signed Multitable is not verified. This is intended for development or testing environments where the root and/or intermediate certificates required to validate the signing certificate are not available.
Return Values
    • ENStatus_Success: The signature was verified.
    • ENStatus_Failure: The signature did not pass verification.