S2OPC OPCUA Toolkit
Loading...
Searching...
No Matches
sopc_pki_stack.h File Reference

Defines the minimal PKI implementation provided by the stack. More...

Go to the source code of this file.

Functions

SOPC_ReturnStatus SOPC_PKIProvider_CreateFromStore (const char *directoryStorePath, SOPC_PKIProvider **ppPKI)
 Creates the PKIProvider from a directory where certificates are stored.
 
SOPC_ReturnStatus SOPC_PKIProvider_CreateFromList (SOPC_CertificateList *pTrustedCerts, SOPC_CRLList *pTrustedCrl, SOPC_CertificateList *pIssuerCerts, SOPC_CRLList *pIssuerCrl, SOPC_PKIProvider **ppPKI)
 Create the PKIProvider from list representation.
 
SOPC_ReturnStatus SOPC_PKIProvider_CreateLeafProfile (const char *securityPolicyUri, SOPC_PKI_LeafProfile **ppProfile)
 Create a leaf certificate profile from security policy to check certificate properties.
 
SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURI (SOPC_PKI_LeafProfile *pProfile, const char *applicationUri)
 Set the application URI to the leaf profile.
 
SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURL (SOPC_PKI_LeafProfile *pProfile, const char *url)
 Set the endpoint URL used for connection to the leaf profile.
 
SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetUsageFromType (SOPC_PKI_LeafProfile *pProfile, SOPC_PKI_Type PKIType)
 Set the keyUsage and extendedKeyUsage to the leaf profile from the PKI type.
 
SOPC_ReturnStatus SOPC_PKIProvider_CheckLeafCertificate (const SOPC_CertificateList *pToValidate, const SOPC_PKI_LeafProfile *pProfile, uint32_t *error)
 Check leaf certificate properties.
 
void SOPC_PKIProvider_DeleteLeafProfile (SOPC_PKI_LeafProfile **ppProfile)
 Delete a leaf profile.
 
SOPC_ReturnStatus SOPC_PKIProvider_CreateProfile (const char *securityPolicyUri, SOPC_PKI_Profile **ppProfile)
 Create a PKI profile for a validation process. Backward interoperability is enabled. Leaf profile and chain profile are created according the security policy. KeyUsage, extendedKeyUsage, URI and HostName of subjectAltName are not configured here then these properties have to be defined manually or though specific functions eg SOPC_PKIProvider_ProfileSetUsageFromType , SOPC_PKIProvider_ProfileSetURI and SOPC_PKIProvider_ProfileSetURL.
 
SOPC_ReturnStatus SOPC_PKIProvider_CreateMinimalUserProfile (SOPC_PKI_Profile **ppProfile)
 Create a minimal PKI profile for user validation process.
 
SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetUsageFromType (SOPC_PKI_Profile *pProfile, SOPC_PKI_Type PKIType)
 Set the properties to the PKI profile from the PKI type.
 
SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURI (SOPC_PKI_Profile *pProfile, const char *applicationUri)
 Set the application URI to the PKI profile.
 
SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURL (SOPC_PKI_Profile *pProfile, const char *url)
 Set the endpoint URL used for connection to the PKI profile.
 
void SOPC_PKIProvider_DeleteProfile (SOPC_PKI_Profile **ppProfile)
 Delete a PKI profile.
 
SOPC_ReturnStatus SOPC_PKIProvider_SetStorePath (const char *directoryStorePath, SOPC_PKIProvider *pPKI)
 Redefines the directory store where the certificates will be stored with SOPC_PKIProvider_WriteToStore.
 
SOPC_ReturnStatus SOPC_PKIProvider_ValidateCertificate (SOPC_PKIProvider *pPKI, const SOPC_CertificateList *pToValidate, const SOPC_PKI_Profile *pProfile, uint32_t *error)
 Validation function for a certificate with the PKI chain.
 
SOPC_ReturnStatus SOPC_PKIProvider_WriteToStore (SOPC_PKIProvider *pPKI, const bool bEraseExistingFiles)
 Write the certificate files in the updatedTrustList folder of the PKI storage. The updatedTrustList folder is created if it is missing. The format of the written files is DER. The updatedTrustList folder is organized as follows:
 
SOPC_ReturnStatus SOPC_PKIProvider_WriteOrAppendToList (SOPC_PKIProvider *pPKI, SOPC_CertificateList **ppTrustedCerts, SOPC_CRLList **ppTrustedCrl, SOPC_CertificateList **ppIssuerCerts, SOPC_CRLList **ppIssuerCrl)
 Extracts certificates from the PKI object.
 
SOPC_ReturnStatus SOPC_PKIProvider_WriteRejectedCertToStore (SOPC_PKIProvider *pPKI)
 Write the rejected certificates files in the rejected folder of the PKI storage. The format of the written files is DER.
 
SOPC_ReturnStatus SOPC_PKIProvider_CopyRejectedList (SOPC_PKIProvider *pPKI, SOPC_CertificateList **ppCert)
 Copy the list of certificate that have been rejected.
 
SOPC_ReturnStatus SOPC_PKIProvider_UpdateFromList (SOPC_PKIProvider *pPKI, const char *securityPolicyUri, SOPC_CertificateList *pTrustedCerts, SOPC_CRLList *pTrustedCrl, SOPC_CertificateList *pIssuerCerts, SOPC_CRLList *pIssuerCrl, const bool bIncludeExistingList)
 Update the PKI with new lists of certificates and CRL.
 
SOPC_ReturnStatus SOPC_PKIProvider_RemoveCertificate (SOPC_PKIProvider *pPKI, const char *pThumbprint, const bool bIsTrusted, bool *pIsRemoved, bool *pIsIssuer)
 Remove all the certificates matching with the given thumbprint. If the Certificate is a CA Certificate then all the CRLs for that CA are removed.
 
SOPC_ReturnStatus SOPC_PKIPermissive_Create (SOPC_PKIProvider **ppPKI)
 Creates a PKI Provider without security.
 
SOPC_ReturnStatus SOPC_PKIProvider_SetUpdateCb (SOPC_PKIProvider *pPKI, SOPC_PKIProviderUpdateCb *pUpdateCb, uintptr_t updateParam)
 Defines the callback to be called when a PKI certificates update is done with SOPC_PKIProvider_UpdateFromList or SOPC_PKIProvider_RemoveCertificate.
 
void SOPC_PKIProvider_Free (SOPC_PKIProvider **ppPKI)
 Frees allocated PKIs.
 

Detailed Description

Defines the minimal PKI implementation provided by the stack.

The stack will not to provide a full-blown configurable PKI. The stack provides only a minimal, always safe validating PKI. The stack provides a thread-safe PKI, it is necessary for OPC UA client use case (shared between services and secure channel layers) and PKI trust list update feature (shared between S2OPC library layers and possibly application thread).

See sopc_pki_stack_lib_itf.h for API.

Function Documentation

◆ SOPC_PKIProvider_CreateFromStore()

SOPC_ReturnStatus SOPC_PKIProvider_CreateFromStore ( const char * directoryStorePath,
SOPC_PKIProvider ** ppPKI )

Creates the PKIProvider from a directory where certificates are stored.

The directory store shall be organized as follows:

  • <Directory_store_name>/trusted/certs (.DER or .PEM files)
  • <Directory_store_name>/trusted/crl (.DER or .PEM files)
  • <Directory_store_name>/issuers/certs (.DER or .PEM files)
  • <Directory_store_name>/issuers/crl (.DER or .PEM files

Optional updated trust list directory (for runtime update persistence) :

  • <Directory_store_name>/updatedTrustList/trusted/certs (.DER or .PEM files)
  • <Directory_store_name>/updatedTrustList/trusted/crl (.DER or .PEM files)
  • <Directory_store_name>/updatedTrustList/issuers/certs (.DER or .PEM files)
  • <Directory_store_name>/updatedTrustList/issuers/crl (.DER or .PEM files)
Note
: file extension names are not checked and all files are considered valid certificates or CRL except for file names starting with a '.' in order to allow placeholders for empty directories.

The function attempts to build the PKI from the updatedTrustList directory and in case of error (missing, empty or malformed), it switches to the root trusted and issuers directories.

Notions :

  • CA is a root CA if it is self-signed.
  • trusted/certs = trusted root CA + trusted link CA + trusted cert.
  • trusted/crl = CRLs of the trusted root CA + trusted link CA.
  • issuer/certs = untrusted root CA + untrusted link CA.
  • issuer/crl = CRLs of the untrusted root CA + untrusted link CA.
  • CAs from trusted/certs and issuers/certs allow to verify the signing chain of a cert which is included into trusted/certs.
  • CAs from trusted/certs allow to verify the signing chain of a cert which is not included into trusted/certs.

This function checks that :

  • the number of certificates plus CRLs does not exceed SOPC_PKI_MAX_NB_CERT_AND_CRL .
  • the certificate store is not empty.
  • at least one trusted certificate is provided.
  • each certificate from subfolder issuer/certs is CA.
  • each CA has exactly one Certificate Revocation List (CRL).
Note
Content of the PKI is NULL when return value is not SOPC_STATUS_OK.
Parameters
directoryStorePathThe directory path where certificates are stored.
[out]ppPKIA valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free().
Returns
SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_PKIProvider_CreateFromList()

SOPC_ReturnStatus SOPC_PKIProvider_CreateFromList ( SOPC_CertificateList * pTrustedCerts,
SOPC_CRLList * pTrustedCrl,
SOPC_CertificateList * pIssuerCerts,
SOPC_CRLList * pIssuerCrl,
SOPC_PKIProvider ** ppPKI )

Create the PKIProvider from list representation.

Notions :

  • CA is a root CA if it is self-signed.
  • pTrustedCerts = trusted root CA + trusted link CA + trusted cert.
  • pTrustedCrl = CRLs of the trusted root CA + trusted link CA.
  • pIssuerCerts = untrusted root CA + untrusted link CA.
  • pIssuerCrl = CRLs of the untrusted root CA + untrusted link CA.
  • CAs from trusted/certs and issuers/certs allow to verify the signing chain of a cert which is included into trusted/certs.
  • CAs from trusted/certs allow to verify the signing chain of a cert which is not included into trusted/certs.

This function checks that :

  • the number of certificates plus CRLs does not exceed SOPC_PKI_MAX_NB_CERT_AND_CRL .
  • at least one cert from pTrustedCerts is provided.
  • each certificate from pIssuerCerts is CA.
  • each CA has exactly one Certificate Revocation List (CRL).
Parameters
pTrustedCertsA valid pointer to the trusted certificate list.
pTrustedCrlA valid pointer to the trusted CRL list.
pIssuerCertsA valid pointer to the issuer certificate list. NULL if not used.
pIssuerCrlA valid pointer to the issuer CRL list. NULL if not used.
[out]ppPKIA valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free().
Returns
SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_PKIProvider_CreateLeafProfile()

SOPC_ReturnStatus SOPC_PKIProvider_CreateLeafProfile ( const char * securityPolicyUri,
SOPC_PKI_LeafProfile ** ppProfile )

Create a leaf certificate profile from security policy to check certificate properties.

   KeyUsage, extendedKeyUsage, URI and HostName of subjectAltName are not configured here then
   these properties have to be defined manually or though specific functions eg
   ::SOPC_PKIProvider_LeafProfileSetUsageFromType , ::SOPC_PKIProvider_LeafProfileSetURI
   and ::SOPC_PKIProvider_LeafProfileSetURL
Parameters
securityPolicyUriThe URI describing the security policy. If NULL then an empty profile is created.
[out]ppProfileThe newly created leaf profile. You should delete it with SOPC_PKIProvider_DeleteLeafProfile .
Note
If the profile is empty ( securityPolicyUri is NULL) then the functions that use this profile will not run any checks.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_LeafProfileSetURI()

SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURI ( SOPC_PKI_LeafProfile * pProfile,
const char * applicationUri )

Set the application URI to the leaf profile.

Parameters
pProfileA valid pointer to the leaf profile.
applicationUriThe application URI to set in pProfile .
Warning
If the application URI is already defined in pProfile, you can not define it again.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_LeafProfileSetURL()

SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURL ( SOPC_PKI_LeafProfile * pProfile,
const char * url )

Set the endpoint URL used for connection to the leaf profile.

Parameters
pProfileA valid pointer to the leaf profile.
urlThe endpoint URL used for connection to set in pProfile .
Warning
If the URL is already defined in pProfile , you can not define it again.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_LeafProfileSetUsageFromType()

SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetUsageFromType ( SOPC_PKI_LeafProfile * pProfile,
SOPC_PKI_Type PKIType )

Set the keyUsage and extendedKeyUsage to the leaf profile from the PKI type.

  For users : the keyUsage is expected to be filled with digitalSignature and the extendedKeyUsage is not
  checked.
  For clients : the keyUsage is expected to be filled with digitalSignature, nonRepudiation, keyEncipherment
  and dataEncipherment. The extendedKeyUsage is filled with serverAuth.
  For server : the keyUsage is expected to be filled with digitalSignature, nonRepudiation, keyEncipherment
  and dataEncipherment. The extendedKeyUsage is filled with clientAuth.
Parameters
pProfileA valid pointer to the leaf profile.
PKITypeDefines the type of PKI (user, client or server)
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_CheckLeafCertificate()

SOPC_ReturnStatus SOPC_PKIProvider_CheckLeafCertificate ( const SOPC_CertificateList * pToValidate,
const SOPC_PKI_LeafProfile * pProfile,
uint32_t * error )

Check leaf certificate properties.

Parameters
pToValidateA valid pointer to the Certificate to validate.
pProfileA valid pointer to the leaf profile.
[out]errorPointer to store the OpcUa error code when certificate validation failed.
Note
error is only set if returned status is different from SOPC_STATUS_OK.
Returns
SOPC_STATUS_OK when the certificate properties are successfully validated, and SOPC_STATUS_INVALID_PARAMETERS, SOPC_STATUS_INVALID_STATE or SOPC_STATUS_NOK.

◆ SOPC_PKIProvider_DeleteLeafProfile()

void SOPC_PKIProvider_DeleteLeafProfile ( SOPC_PKI_LeafProfile ** ppProfile)

Delete a leaf profile.

Parameters
ppProfileThe leaf profile.

◆ SOPC_PKIProvider_CreateProfile()

SOPC_ReturnStatus SOPC_PKIProvider_CreateProfile ( const char * securityPolicyUri,
SOPC_PKI_Profile ** ppProfile )

Create a PKI profile for a validation process. Backward interoperability is enabled. Leaf profile and chain profile are created according the security policy. KeyUsage, extendedKeyUsage, URI and HostName of subjectAltName are not configured here then these properties have to be defined manually or though specific functions eg SOPC_PKIProvider_ProfileSetUsageFromType , SOPC_PKIProvider_ProfileSetURI and SOPC_PKIProvider_ProfileSetURL.

Parameters
securityPolicyUriThe URI describing the security policy. Shall not be NULL.
[out]ppProfileThe newly created profile. You should delete it with SOPC_PKIProvider_DeleteProfile .
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_CreateMinimalUserProfile()

SOPC_ReturnStatus SOPC_PKIProvider_CreateMinimalUserProfile ( SOPC_PKI_Profile ** ppProfile)

Create a minimal PKI profile for user validation process.

Parameters
ppProfileThe newly created profile. You should delete it with SOPC_PKIProvider_DeleteProfile .
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_ProfileSetUsageFromType()

SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetUsageFromType ( SOPC_PKI_Profile * pProfile,
SOPC_PKI_Type PKIType )

Set the properties to the PKI profile from the PKI type.

  For users : the backward interoperability is disabled and the leaf profile will not be applied during
  ::SOPC_PKIProvider_ValidateCertificate.
  For clients : the keyUsage is expected to be filled with digitalSignature,
  nonRepudiation, keyEncipherment and dataEncipherment. The extendedKeyUsage is filled with serverAuth. Finally
  the backward interoperability is enabled.
  For Server : the keyUsage is expected to be filled with digitalSignature, nonRepudiation, keyEncipherment
  and dataEncipherment. The extendedKeyUsage is filled with clientAuth. Finally the backward interoperability
  is enabled.
Parameters
pProfileA valid pointer to the PKI profile.
PKITypeDefines the type of PKI (user, client or server)
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_ProfileSetURI()

SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURI ( SOPC_PKI_Profile * pProfile,
const char * applicationUri )

Set the application URI to the PKI profile.

Parameters
pProfileA valid pointer to the PKI profile.
applicationUriThe application URI to set in pProfile.
Warning
If the application URI is already defined in pProfile, you can not define it again.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_ProfileSetURL()

SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURL ( SOPC_PKI_Profile * pProfile,
const char * url )

Set the endpoint URL used for connection to the PKI profile.

Parameters
pProfileA valid pointer to the PKI profile.
urlThe endpoint URL used for connection to set in pProfile.
Warning
If the URL is already defined in pProfile, you can not define it again.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_DeleteProfile()

void SOPC_PKIProvider_DeleteProfile ( SOPC_PKI_Profile ** ppProfile)

Delete a PKI profile.

Parameters
ppProfileThe PKI profile.

◆ SOPC_PKIProvider_SetStorePath()

SOPC_ReturnStatus SOPC_PKIProvider_SetStorePath ( const char * directoryStorePath,
SOPC_PKIProvider * pPKI )

Redefines the directory store where the certificates will be stored with SOPC_PKIProvider_WriteToStore.

Parameters
directoryStorePathThe directory path where the certificates will be stored.
pPKIA valid pointer to the PKIProvider.
Note
The directory is created if directoryStorePath does not exist.
Warning
In case of error, pPKI is unchanged.
Returns
SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_NOK in case of error.

◆ SOPC_PKIProvider_ValidateCertificate()

SOPC_ReturnStatus SOPC_PKIProvider_ValidateCertificate ( SOPC_PKIProvider * pPKI,
const SOPC_CertificateList * pToValidate,
const SOPC_PKI_Profile * pProfile,
uint32_t * error )

Validation function for a certificate with the PKI chain.

It implements the validation with the certificate chain of the PKI.

Parameters
pPKIA valid pointer to the PKIProvider.
pToValidateA valid pointer to the Certificate to validate.
pProfileA valid pointer to the PKI profile.
[out]errorPointer to store the OpcUa error code when certificate validation failed.
Note
error is only set if returned status is different from SOPC_STATUS_OK. The certificate is internally stored if it is rejected.
Warning
In case of user PKI, the leaf profile part of pProfile is not applied to the certificate. The user leaf properties should be checked separately with SOPC_PKIProvider_CheckLeafCertificate .
Returns
SOPC_STATUS_OK when the certificate is successfully validated, and SOPC_STATUS_INVALID_PARAMETERS or SOPC_STATUS_NOK.

◆ SOPC_PKIProvider_WriteToStore()

SOPC_ReturnStatus SOPC_PKIProvider_WriteToStore ( SOPC_PKIProvider * pPKI,
const bool bEraseExistingFiles )

Write the certificate files in the updatedTrustList folder of the PKI storage. The updatedTrustList folder is created if it is missing. The format of the written files is DER. The updatedTrustList folder is organized as follows:

  • updatedTrustList/trusted/certs
  • updatedTrustList/trusted/crl
  • updatedTrustList/issuers/certs
  • updatedTrustList/issuers/crl
Parameters
pPKIA valid pointer to the PKIProvider.
bEraseExistingFileswhether the existing files of the updatedTrustList folder shall be deleted.
Warning
If the pPKI is built from lists ( SOPC_PKIProvider_CreateFromList ) then you shall define the directory store path with SOPC_PKIProvider_SetStorePath .
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_WriteOrAppendToList()

SOPC_ReturnStatus SOPC_PKIProvider_WriteOrAppendToList ( SOPC_PKIProvider * pPKI,
SOPC_CertificateList ** ppTrustedCerts,
SOPC_CRLList ** ppTrustedCrl,
SOPC_CertificateList ** ppIssuerCerts,
SOPC_CRLList ** ppIssuerCrl )

Extracts certificates from the PKI object.

Parameters
pPKIA valid pointer to the PKIProvider.
ppTrustedCertsWrite: a valid pointer to a copy of the trusted certificate list. Append: a pointer to a pointer to a certificate list to which append the trusted certificate list. In either cases, you should free this object.
ppTrustedCrlWrite: a valid pointer to a copy of the trusted CRL list. Append: a pointer to a pointer to a certificate list to which append the trusted CRL list. In either cases, you should free this object.
ppIssuerCertsWrite: a valid pointer to a copy of the issuer certificate list. Append: a pointer to a pointer to a certificate list to which append the issuer certificate list. In either cases, you should free this object.
ppIssuerCrlWrite: a valid pointer to a copy of the issuer CRL list. Append: a pointer to a pointer to a certificate list to which append the issuer CRL list. In either cases, you should free this object.
Note
In case of error, the whole lists ( ppTrustedCerts , ppTrustedCrl , ppIssuerCerts and ppIssuerCrl ) are free and set to NULL.
If the pPKI contains an empty list then nothing is write or append for this list.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_WriteRejectedCertToStore()

SOPC_ReturnStatus SOPC_PKIProvider_WriteRejectedCertToStore ( SOPC_PKIProvider * pPKI)

Write the rejected certificates files in the rejected folder of the PKI storage. The format of the written files is DER.

Parameters
pPKIA valid pointer to the PKIProvider.
Note
The maximum number of certificates written in the rejected folder is SOPC_PKI_MAX_NB_CERT_REJECTED . This function removes the existing files.
Warning
If the pPKI is built from lists ( SOPC_PKIProvider_CreateFromList ) then you shall define the directory store path with SOPC_PKIProvider_SetStorePath .
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_CopyRejectedList()

SOPC_ReturnStatus SOPC_PKIProvider_CopyRejectedList ( SOPC_PKIProvider * pPKI,
SOPC_CertificateList ** ppCert )

Copy the list of certificate that have been rejected.

Parameters
pPKIA valid pointer to the PKIProvider.
[out]ppCertA copy of the PKI rejected list (NULL if no certificate has been rejected).
Note
The maximum number of certificates returned is SOPC_PKI_MAX_NB_CERT_REJECTED.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_UpdateFromList()

SOPC_ReturnStatus SOPC_PKIProvider_UpdateFromList ( SOPC_PKIProvider * pPKI,
const char * securityPolicyUri,
SOPC_CertificateList * pTrustedCerts,
SOPC_CRLList * pTrustedCrl,
SOPC_CertificateList * pIssuerCerts,
SOPC_CRLList * pIssuerCrl,
const bool bIncludeExistingList )

Update the PKI with new lists of certificates and CRL.

Parameters
pPKIA valid pointer to the PKIProvider.
securityPolicyUriThe URI describing the security policy of the secure channel.
pTrustedCertsA valid pointer to the trusted certificate list. NULL if this part shall not updated.
pTrustedCrlA valid pointer to the trusted CRL list. NULL if this part shall not updated.
pIssuerCertsA valid pointer to the issuer certificate list. NULL if this part shall not updated.
pIssuerCrlA valid pointer to the issuer CRL list. NULL if this part shall not updated.
bIncludeExistingListwhether the update shall includes the existing certificates of pPKI plus pTrustedCerts , pTrustedCrl , pIssuerCerts and pIssuerCrl .
Warning
securityPolicyUri is not used yet and could be NULL.
A callback shall have been defined using SOPC_PKIProvider_SetUpdateCb otherwise update is not authorized.
Returns
SOPC_STATUS_OK when successful (SOPC_STATUS_INVALID_STATE in case update callback is not set).

◆ SOPC_PKIProvider_RemoveCertificate()

SOPC_ReturnStatus SOPC_PKIProvider_RemoveCertificate ( SOPC_PKIProvider * pPKI,
const char * pThumbprint,
const bool bIsTrusted,
bool * pIsRemoved,
bool * pIsIssuer )

Remove all the certificates matching with the given thumbprint. If the Certificate is a CA Certificate then all the CRLs for that CA are removed.

Warning
This function will fail if pThumbprint does not match the SHA1 hex digest size.
A callback shall have been defined using SOPC_PKIProvider_SetUpdateCb otherwise update is not authorized.
Parameters
pPKIA valid pointer to the PKIProvider.
pThumbprintThe SHA1 of the certificate formatted as an hexadecimal C string (NULL terminated) 40 bytes shall be allocated in pThumbprint (+ 1 byte for the NULL character)
bIsTrustedwhether the certificate to remove is a trusted certificate.
[out]pIsRemovedA valid pointer indicating whether the certificate has been found and deleted.
[out]pIsIssuerA valid pointer indicating whether the deleted certificate is an issuer.
Returns
SOPC_STATUS_OK when successful (SOPC_STATUS_INVALID_STATE in case update callback is not set).

◆ SOPC_PKIPermissive_Create()

SOPC_ReturnStatus SOPC_PKIPermissive_Create ( SOPC_PKIProvider ** ppPKI)

Creates a PKI Provider without security.

Parameters
[out]ppPKIA valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free().
Warning
Using this PKI is considered harmful for the security of the connection. This PKI shall be used for tests or to set a new configuration from a TOFU state.
Returns
SOPC_STATUS_OK when successful.

◆ SOPC_PKIProvider_SetUpdateCb()

SOPC_ReturnStatus SOPC_PKIProvider_SetUpdateCb ( SOPC_PKIProvider * pPKI,
SOPC_PKIProviderUpdateCb * pUpdateCb,
uintptr_t updateParam )

Defines the callback to be called when a PKI certificates update is done with SOPC_PKIProvider_UpdateFromList or SOPC_PKIProvider_RemoveCertificate.

Warning
It is mandatory to define an associated behavior to allow calls to these functions.
Note
Callback is used to re-evaluate the currently used certificates or to leave a TOFU state. (As example, SOPC_ToolkitClient_AsyncReEvalSecureChannels is used for the callback of the application PKI and SOPC_ToolkitServer_AsyncReEvalUserCertSessions is used for the callback of the user PKI)
Warning
The callback shall not do anything blocking and shall not modify the content of its associated pPKI .
Parameters
pPKIA valid pointer to the PKIProvider for which an update callback will be defined
pUpdateCbThe callback to be called when an update is done
updateParamA user defined parameter for the callback
Returns
SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameter and SOPC_STATUS_INVALID_STATE in case a callback is already defined.

◆ SOPC_PKIProvider_Free()

void SOPC_PKIProvider_Free ( SOPC_PKIProvider ** ppPKI)

Frees allocated PKIs.

Parameters
ppPKIA valid pointer to a PKI.