nl::Weave::Profiles::Security::CASE::WeaveCASEAuthDelegate

Called at the start of certificate validation.

Implementations must initialize the supplied WeaveCertificateSet object with sufficient resources to handle the upcoming certificate validation. At this time Implementations may load trusted root or CA certificates into the certificate set, or wait until OnPeerCertsLoaded() is called.

Each certificate loaded into the certificate set will be assigned a default certificate type by the load function. Implementations should adjust these types as necessary to ensure the correct treatment of the certificate during validation, and the correct assignment of WeaveAuthMode for CASE interactions.

The supplied validation context will be initialized with a set of default validation criteria, which the implementation may alter as necessary. The implementation must either set the EffectiveTime field, or set the appropriate validation flags to suppress certificate lifetime validation.

If detailed validation results are desired, the implementation may initialize the CertValidationResults and CertValidationLen fields.

Implementations are required to maintain any resources allocated during BeginValidation() until the corresponding EndValidation() is called is made. Implementations are guaranteed that EndValidation() will be called exactly once for each successful call to BeginValidation().

Encode CASE Certificate Information for the local node.

Implementations can use this call to override the default encoding of the CASE CertificateInformation structure for the local node. When called, the implementation should write a CertificateInformation structure containing, at a minimum, the local node's entity certificate. Implementation may optionally include a set of related certificates and/or trust anchors.

Encode an application-specific payload to be included in the CASE message to the peer.

Implementing this method is optional. The default implementation returns a zero-length payload.

Called at the end of certificate validation.

Implementations may use this call to perform cleanup after certification validation completes. Implementations are guaranteed that EndValidation() will be called exactly once for each successful call to BeginValidation().

Generate a signature using local node's private key.

When invoked, implementations must compute a signature on the given hash value using the node's private key. The generated signature should then be written in the form of a CASE ECDSASignature structure to the supplied TLV writing using the specified tag.

In cases where the node's private key is held in a local buffer, the GenerateAndEncodeWeaveECDSASignature() utility function can be useful for implementing this method.

Called with the result of certificate validation.

Implementations may use this call to inspect, and possibly alter, the result of validation of the peer's certificate. If validation was successful, validRes will be set to WEAVE_NO_ERROR. In this case, the validation context will contain details regarding the result. In particular, the TrustAnchor field will be set to the trust anchor certificate.

If the implementation initialized the CertValidationResults and CertValidationLen fields within the ValidationContext structure during the BeginValidation() called, then these fields will contained detailed validation results for each certificate in the certificate set.

Implementations may override this by setting validRes to an error value, thereby causing validation to fail.

If validation failed, validRes will reflect the reason for the failure. Implementations may override the result to a different error value, but MUST NOT set the result to WEAVE_NO_ERROR.

Called after the peer's certificates have been loaded.

Implementations may use this call to finalize the input certificates and the validation criteria that will be used to perform validation of the peer's certificate. At call time, the certificates supplied by the peer will have been loaded into the certificate set (including its own certificate, if present). Additionally, the subjectDN and subjectKeyId arguments will have been initialized to values that will be used to resolve the peer's certificate from the certificate set. If the peer supplied its own certificate (rather than a certificate reference) then the EntityCert field within the validCtx argument will contain a pointer to that certificate.

During this called, implementations may modify the contents of the certificate set, including adding new certificates. They may also alter the subjectDN, subjectKeyId or validCtx arguments as necessary. Most importantly, implementations should adjust the certificate type fields with the certificate set prior to returning to ensure correct treatment of certificates during validation and subsequent access control checks.

NOTE: In the event that the peer supplies a certificate reference for itself, rather than a full certificate, the EntityCert field in the validation context will contain a NULL. If an implementation wishes to support certificate references, it must add a certificate matching the peer's subject DN and key id to the certificate set prior to returning.

Implementing this method is optional. The default implementation does nothing.