BACnetStack_SCCertificateAddIssuer

bool BACnetStack_SCCertificateAddIssuer(
  uint32_t * procedureId,
  const uint32_t targetNetworkPortInstance,
  const uint8_t * currentIssuerCertificate,
  const uint32_t currentIssuerCertificateLength,
  const uint8_t * newIssuerCertificate,
  const uint32_t newIssuerCertificateLength,
  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);

Adds a new issuer certificate to a BACnet/SC node, as the certificate-management procedure of 135-2024 clause 19.8.3.1 describes.

Reads the target Network Port’s Issuer_Certificate_Files, reads the issuer files and compares them with currentIssuerCertificate to find the one in use, writes newIssuerCertificate into the OTHER 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, 2, 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, ProvideSignedCertificate and Cancel.
`targetNetworkPortInstance`	in	The BACnet/SC Network Port object instance in the target device.
`currentIssuerCertificate`	in	The issuer certificate the network uses now, byte for byte as it is stored in the target’s issuer file (the comparison is exact: a PEM/DER or line-ending difference reports CurrentIssuerNotFound).
`currentIssuerCertificateLength`	in	The number of bytes in currentIssuerCertificate.
`newIssuerCertificate`	in	The issuer certificate to add.
`newIssuerCertificateLength`	in	The number of bytes in newIssuerCertificate.
`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 is not registered, a certificate is missing, 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.