S2OPC OPCUA Toolkit
|
Defines the minimal PKI implementation provided by the stack. More...
#include "sopc_pki_stack_lib_itf.h"
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. | |
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.
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:
Optional updated trust list directory (for runtime update persistence) :
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 :
This function checks that :
SOPC_PKI_MAX_NB_CERT_AND_CRL
.directoryStorePath | The directory path where certificates are stored. | |
[out] | ppPKI | A valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free(). |
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 :
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.This function checks that :
SOPC_PKI_MAX_NB_CERT_AND_CRL
.pTrustedCerts
is provided.pIssuerCerts
is CA.pTrustedCerts | A valid pointer to the trusted certificate list. | |
pTrustedCrl | A valid pointer to the trusted CRL list. | |
pIssuerCerts | A valid pointer to the issuer certificate list. NULL if not used. | |
pIssuerCrl | A valid pointer to the issuer CRL list. NULL if not used. | |
[out] | ppPKI | A valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free(). |
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
securityPolicyUri | The URI describing the security policy. If NULL then an empty profile is created. | |
[out] | ppProfile | The newly created leaf profile. You should delete it with SOPC_PKIProvider_DeleteLeafProfile . |
securityPolicyUri
is NULL) then the functions that use this profile will not run any checks.SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURI | ( | SOPC_PKI_LeafProfile * | pProfile, |
const char * | applicationUri ) |
Set the application URI to the leaf profile.
pProfile | A valid pointer to the leaf profile. |
applicationUri | The application URI to set in pProfile . |
pProfile
, you can not define it again.SOPC_ReturnStatus SOPC_PKIProvider_LeafProfileSetURL | ( | SOPC_PKI_LeafProfile * | pProfile, |
const char * | url ) |
Set the endpoint URL used for connection to the leaf profile.
pProfile | A valid pointer to the leaf profile. |
url | The endpoint URL used for connection to set in pProfile . |
pProfile
, you can not define it again.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.
pProfile | A valid pointer to the leaf profile. |
PKIType | Defines the type of PKI (user, client or server) |
SOPC_ReturnStatus SOPC_PKIProvider_CheckLeafCertificate | ( | const SOPC_CertificateList * | pToValidate, |
const SOPC_PKI_LeafProfile * | pProfile, | ||
uint32_t * | error ) |
Check leaf certificate properties.
pToValidate | A valid pointer to the Certificate to validate. | |
pProfile | A valid pointer to the leaf profile. | |
[out] | error | Pointer to store the OpcUa error code when certificate validation failed. |
error
is only set if returned status is different from SOPC_STATUS_OK.void SOPC_PKIProvider_DeleteLeafProfile | ( | SOPC_PKI_LeafProfile ** | ppProfile | ) |
Delete a leaf profile.
ppProfile | The 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.
securityPolicyUri | The URI describing the security policy. Shall not be NULL. | |
[out] | ppProfile | The newly created profile. You should delete it with SOPC_PKIProvider_DeleteProfile . |
SOPC_ReturnStatus SOPC_PKIProvider_CreateMinimalUserProfile | ( | SOPC_PKI_Profile ** | ppProfile | ) |
Create a minimal PKI profile for user validation process.
ppProfile | The newly created profile. You should delete it with SOPC_PKIProvider_DeleteProfile . |
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.
pProfile | A valid pointer to the PKI profile. |
PKIType | Defines the type of PKI (user, client or server) |
SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURI | ( | SOPC_PKI_Profile * | pProfile, |
const char * | applicationUri ) |
Set the application URI to the PKI profile.
pProfile | A valid pointer to the PKI profile. |
applicationUri | The application URI to set in pProfile . |
pProfile
, you can not define it again.SOPC_ReturnStatus SOPC_PKIProvider_ProfileSetURL | ( | SOPC_PKI_Profile * | pProfile, |
const char * | url ) |
Set the endpoint URL used for connection to the PKI profile.
pProfile | A valid pointer to the PKI profile. |
url | The endpoint URL used for connection to set in pProfile . |
pProfile
, you can not define it again.void SOPC_PKIProvider_DeleteProfile | ( | SOPC_PKI_Profile ** | ppProfile | ) |
Delete a PKI profile.
ppProfile | The 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.
directoryStorePath | The directory path where the certificates will be stored. |
pPKI | A valid pointer to the PKIProvider. |
directoryStorePath
does not exist. pPKI
is unchanged.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.
pPKI | A valid pointer to the PKIProvider. | |
pToValidate | A valid pointer to the Certificate to validate. | |
pProfile | A valid pointer to the PKI profile. | |
[out] | error | Pointer to store the OpcUa error code when certificate validation failed. |
error
is only set if returned status is different from SOPC_STATUS_OK. The certificate is internally stored if it is rejected.pProfile
is not applied to the certificate. The user leaf properties should be checked separately with SOPC_PKIProvider_CheckLeafCertificate .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:
pPKI | A valid pointer to the PKIProvider. |
bEraseExistingFiles | whether the existing files of the updatedTrustList folder shall be deleted. |
pPKI
is built from lists ( SOPC_PKIProvider_CreateFromList ) then you shall define the directory store path with SOPC_PKIProvider_SetStorePath .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.
pPKI | A valid pointer to the PKIProvider. |
ppTrustedCerts | Write: 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. |
ppTrustedCrl | Write: 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. |
ppIssuerCerts | Write: 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. |
ppIssuerCrl | Write: 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. |
ppTrustedCerts
, ppTrustedCrl
, ppIssuerCerts
and ppIssuerCrl
) are free and set to NULL.pPKI
contains an empty list then nothing is write or append for this list.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.
pPKI | A valid pointer to the PKIProvider. |
SOPC_PKI_MAX_NB_CERT_REJECTED
. This function removes the existing files.pPKI
is built from lists ( SOPC_PKIProvider_CreateFromList ) then you shall define the directory store path with SOPC_PKIProvider_SetStorePath .SOPC_ReturnStatus SOPC_PKIProvider_CopyRejectedList | ( | SOPC_PKIProvider * | pPKI, |
SOPC_CertificateList ** | ppCert ) |
Copy the list of certificate that have been rejected.
pPKI | A valid pointer to the PKIProvider. | |
[out] | ppCert | A copy of the PKI rejected list (NULL if no certificate has been rejected). |
SOPC_PKI_MAX_NB_CERT_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.
pPKI | A valid pointer to the PKIProvider. |
securityPolicyUri | The URI describing the security policy of the secure channel. |
pTrustedCerts | A valid pointer to the trusted certificate list. NULL if this part shall not updated. |
pTrustedCrl | A valid pointer to the trusted CRL list. NULL if this part shall not updated. |
pIssuerCerts | A valid pointer to the issuer certificate list. NULL if this part shall not updated. |
pIssuerCrl | A valid pointer to the issuer CRL list. NULL if this part shall not updated. |
bIncludeExistingList | whether the update shall includes the existing certificates of pPKI plus pTrustedCerts , pTrustedCrl , pIssuerCerts and pIssuerCrl . |
securityPolicyUri
is not used yet and could be NULL. 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.
pThumbprint
does not match the SHA1 hex digest size. pPKI | A valid pointer to the PKIProvider. | |
pThumbprint | The 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) | |
bIsTrusted | whether the certificate to remove is a trusted certificate. | |
[out] | pIsRemoved | A valid pointer indicating whether the certificate has been found and deleted. |
[out] | pIsIssuer | A valid pointer indicating whether the deleted certificate is an issuer. |
SOPC_ReturnStatus SOPC_PKIPermissive_Create | ( | SOPC_PKIProvider ** | ppPKI | ) |
Creates a PKI Provider without security.
[out] | ppPKI | A valid pointer to the newly created PKIProvider. You should free such provider with SOPC_PKIProvider_Free(). |
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.
pPKI
.pPKI | A valid pointer to the PKIProvider for which an update callback will be defined |
pUpdateCb | The callback to be called when an update is done |
updateParam | A user defined parameter for the callback |
void SOPC_PKIProvider_Free | ( | SOPC_PKIProvider ** | ppPKI | ) |
Frees allocated PKIs.
ppPKI | A valid pointer to a PKI. |