BACnetStack_SCCertificateReplaceOperational

bool BACnetStack_SCCertificateReplaceOperational(
  uint32_t * procedureId,
  const uint32_t targetNetworkPortInstance,
  const bool generateNewKeyPair,
  const uint8_t reinitializedStateOfDevice,
  const char * password,
  const uint8_t passwordLength,
  const uint8_t * connectionString,
  const uint8_t connectionStringLength,
  const uint32_t networkPortInstance,
  const uint16_t destinationNetwork,
  const uint8_t * destinationAddress,
  const uint8_t destinationAddressLength,
  const uint8_t passwordEncoding);

Replaces a BACnet/SC node’s operational certificate, as the certificate-management procedure of 135-2024 clause 19.8.3.2 describes.

Reads the target Network Port’s Certificate_Signing_Request_File and Operational_Certificate_File references; when generateNewKeyPair is true, writes GENERATE_CSR_FILE to its Command property (a node that generates its own key pair) and reads Command once a second until it is IDLE again, for up to two minutes (cl. 12.56.16: the command completes at a time that “is a local matter”); reads the CSR file (an empty one fails the procedure); hands the CSR to the host through the callback registered with BACnetStack_RegisterCallbackSCCertificateSignRequest() and waits for BACnetStack_SCCertificateProvideSignedCertificate(); writes the signed certificate to the operational certificate file (AtomicWriteFile, then WriteProperty File_Size := its length, which truncates any tail of a longer previous certificate); then sends ReinitializeDevice. The progress hook reports the steps in the order 1, 3 (only when generateNewKeyPair is true), 4, 5, 7, 6, 8. A Failed report at step 6 (ClearCertificateFile), or at step 7 once a block of the certificate was written (or when a write timed out or was aborted, and so may have been applied), comes after the stack has sent WriteProperty Command := DISCARD_CHANGES to the target Network Port, asking it to revert the partly written file rather than leave it pending; that also discards anything else pending on that port. Nothing is activated: no ReinitializeDevice is sent.

Parameters

Parameter	Direction	Description
`procedureId`	out	Identifies the procedure in the progress hook, the sign request, ProvideSignedCertificate and Cancel.
`targetNetworkPortInstance`	in	The BACnet/SC Network Port object instance in the target device.
`generateNewKeyPair`	in	True for a node that generates a new private/public key pair (cl. 19.8.3.2 step 1); false for a node with a fixed CSR.
`reinitializedStateOfDevice`	in	ACTIVATE_CHANGES (7) or WARMSTART (1) - the final ReinitializeDevice.
`password`	in	The ReinitializeDevice password, as for BACnetStack_SendReinitializeDevice(). May be NULL with passwordLength 0. NULL with a non-zero passwordLength, or a password BACnetStack_SendReinitializeDevice() would refuse, makes the call return false before anything is sent.
`passwordLength`	in	The number of bytes in password.
`connectionString`	in	The target device’s datalink address, as for BACnetStack_SendReinitializeDevice().
`connectionStringLength`	in	The number of bytes in connectionString.
`networkPortInstance`	in	The local Network Port object instance to send on, or BACNET_NETWORK_PORT_DEFAULT (4194303).
`destinationNetwork`	in	The target’s network number when it is behind a router; 0 for the local network.
`destinationAddress`	in	The target’s address on destinationNetwork; NULL for the local network.
`destinationAddressLength`	in	The number of bytes in destinationAddress.
`passwordEncoding`	in	The character set of password, as for BACnetStack_SendReinitializeDevice().

Returns

True when the procedure started (its first request was sent). False when STACK_OPTION_NM_SCCM_A is not compiled, CallbackGetSystemTime or the sign-request callback is not registered, procedureId is NULL, reinitializedStateOfDevice is neither ACTIVATE_CHANGES (7) nor WARMSTART (1), password is NULL with a non-zero passwordLength or would be refused by BACnetStack_SendReinitializeDevice(), a procedure is already running against this target (the same connectionString, destinationNetwork and destinationAddress - whichever Network Port it names), or the first request could not be sent.

Topic: BACnet/SC. Declared in CASBACnetStackDLL.h.