ua_plugin_securitypolicy.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399
  1. /* This Source Code Form is subject to the terms of the Mozilla Public
  2. * License, v. 2.0. If a copy of the MPL was not distributed with this
  3. * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  4. *
  5. * Copyright 2017-2018 (c) Mark Giraud, Fraunhofer IOSB
  6. * Copyright 2017 (c) Fraunhofer IOSB (Author: Julius Pfrommer)
  7. * Copyright 2017 (c) Stefan Profanter, fortiss GmbH
  8. */
  9. #ifndef UA_PLUGIN_SECURITYPOLICY_H_
  10. #define UA_PLUGIN_SECURITYPOLICY_H_
  11. #include "ua_types.h"
  12. #include "ua_types_generated.h"
  13. #include "ua_plugin_log.h"
  14. #include "ua_plugin_pki.h"
  15. _UA_BEGIN_DECLS
  16. extern const UA_ByteString UA_SECURITY_POLICY_NONE_URI;
  17. struct UA_SecurityPolicy;
  18. typedef struct UA_SecurityPolicy UA_SecurityPolicy;
  19. /**
  20. * SecurityPolicy Interface Definition
  21. * ----------------------------------- */
  22. typedef struct {
  23. UA_String uri;
  24. /* Verifies the signature of the message using the provided keys in the context.
  25. *
  26. * @param securityPolicy the securityPolicy the function is invoked on.
  27. * @param channelContext the channelContext that contains the key to verify
  28. * the supplied message with.
  29. * @param message the message to which the signature is supposed to belong.
  30. * @param signature the signature of the message, that should be verified. */
  31. UA_StatusCode (*verify)(const UA_SecurityPolicy *securityPolicy,
  32. void *channelContext, const UA_ByteString *message,
  33. const UA_ByteString *signature) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  34. /* Signs the given message using this policys signing algorithm and the
  35. * provided keys in the context.
  36. *
  37. * @param securityPolicy the securityPolicy the function is invoked on.
  38. * @param channelContext the channelContext that contains the key to sign
  39. * the supplied message with.
  40. * @param message the message to sign.
  41. * @param signature an output buffer to which the signature is written. The
  42. * buffer needs to be allocated by the caller. The
  43. * necessary size can be acquired with the signatureSize
  44. * attribute of this module. */
  45. UA_StatusCode (*sign)(const UA_SecurityPolicy *securityPolicy,
  46. void *channelContext, const UA_ByteString *message,
  47. UA_ByteString *signature) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  48. /* Gets the signature size that depends on the local (private) key.
  49. *
  50. * @param securityPolicy the securityPolicy the function is invoked on.
  51. * @param channelContext the channelContext that contains the
  52. * certificate/key.
  53. * @return the size of the local signature. Returns 0 if no local
  54. * certificate was set. */
  55. size_t (*getLocalSignatureSize)(const UA_SecurityPolicy *securityPolicy,
  56. const void *channelContext);
  57. /* Gets the signature size that depends on the remote (public) key.
  58. *
  59. * @param securityPolicy the securityPolicy the function is invoked on.
  60. * @param channelContext the context to retrieve data from.
  61. * @return the size of the remote signature. Returns 0 if no
  62. * remote certificate was set previousely. */
  63. size_t (*getRemoteSignatureSize)(const UA_SecurityPolicy *securityPolicy,
  64. const void *channelContext);
  65. /* Gets the local signing key length.
  66. *
  67. * @param securityPolicy the securityPolicy the function is invoked on.
  68. * @param channelContext the context to retrieve data from.
  69. * @return the length of the signing key in bytes. Returns 0 if no length can be found.
  70. */
  71. size_t (*getLocalKeyLength)(const UA_SecurityPolicy *securityPolicy,
  72. const void *channelContext);
  73. /* Gets the local signing key length.
  74. *
  75. * @param securityPolicy the securityPolicy the function is invoked on.
  76. * @param channelContext the context to retrieve data from.
  77. * @return the length of the signing key in bytes. Returns 0 if no length can be found.
  78. */
  79. size_t (*getRemoteKeyLength)(const UA_SecurityPolicy *securityPolicy,
  80. const void *channelContext);
  81. } UA_SecurityPolicySignatureAlgorithm;
  82. typedef struct {
  83. UA_String uri;
  84. /* Encrypt the given data in place using an asymmetric algorithm and keys.
  85. *
  86. * @param securityPolicy the securityPolicy the function is invoked on.
  87. * @param channelContext the channelContext which contains information about
  88. * the keys to encrypt data.
  89. * @param data the data that is encrypted. The encrypted data will overwrite
  90. * the data that was supplied. */
  91. UA_StatusCode (*encrypt)(const UA_SecurityPolicy *securityPolicy,
  92. void *channelContext,
  93. UA_ByteString *data) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  94. /* Decrypts the given ciphertext in place using an asymmetric algorithm and
  95. * key.
  96. *
  97. * @param securityPolicy the securityPolicy the function is invoked on.
  98. * @param channelContext the channelContext which contains information about
  99. * the keys needed to decrypt the message.
  100. * @param data the data to decrypt. The decryption is done in place. */
  101. UA_StatusCode (*decrypt)(const UA_SecurityPolicy *securityPolicy,
  102. void *channelContext,
  103. UA_ByteString *data) UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  104. /* Returns the length of the key used locally to encrypt messages in bits
  105. *
  106. * @param securityPolicy the securityPolicy the function is invoked on.
  107. * @param channelContext the context to retrieve data from.
  108. * @return the length of the local key. Returns 0 if no
  109. * key length is known. */
  110. size_t (*getLocalKeyLength)(const UA_SecurityPolicy *securityPolicy,
  111. const void *channelContext);
  112. /* Returns the length of the key used remotely to encrypt messages in bits
  113. *
  114. * @param securityPolicy the securityPolicy the function is invoked on.
  115. * @param channelContext the context to retrieve data from.
  116. * @return the length of the remote key. Returns 0 if no
  117. * key length is known. */
  118. size_t (*getRemoteKeyLength)(const UA_SecurityPolicy *securityPolicy,
  119. const void *channelContext);
  120. /* Returns the size of encrypted blocks used by the local encryption algorithm.
  121. *
  122. * @param securityPolicy the securityPolicy the function is invoked on.
  123. * @param channelContext the context to retrieve data from.
  124. * @return the size of encrypted blocks in bytes. Returns 0 if no key length is known.
  125. */
  126. size_t (*getLocalBlockSize)(const UA_SecurityPolicy *securityPolicy,
  127. const void *channelContext);
  128. /* Returns the size of encrypted blocks used by the remote encryption algorithm.
  129. *
  130. * @param securityPolicy the securityPolicy the function is invoked on.
  131. * @param channelContext the context to retrieve data from.
  132. * @return the size of encrypted blocks in bytes. Returns 0 if no key length is known.
  133. */
  134. size_t (*getRemoteBlockSize)(const UA_SecurityPolicy *securityPolicy,
  135. const void *channelContext);
  136. /* Returns the size of plaintext blocks used by the local encryption algorithm.
  137. *
  138. * @param securityPolicy the securityPolicy the function is invoked on.
  139. * @param channelContext the context to retrieve data from.
  140. * @return the size of plaintext blocks in bytes. Returns 0 if no key length is known.
  141. */
  142. size_t (*getLocalPlainTextBlockSize)(const UA_SecurityPolicy *securityPolicy,
  143. const void *channelContext);
  144. /* Returns the size of plaintext blocks used by the remote encryption algorithm.
  145. *
  146. * @param securityPolicy the securityPolicy the function is invoked on.
  147. * @param channelContext the context to retrieve data from.
  148. * @return the size of plaintext blocks in bytes. Returns 0 if no key length is known.
  149. */
  150. size_t (*getRemotePlainTextBlockSize)(const UA_SecurityPolicy *securityPolicy,
  151. const void *channelContext);
  152. } UA_SecurityPolicyEncryptionAlgorithm;
  153. typedef struct {
  154. /*
  155. * The algorithm used to sign and verify certificates.
  156. */
  157. UA_SecurityPolicySignatureAlgorithm signatureAlgorithm;
  158. /*
  159. * The algorithm used to encrypt and decrypt messages.
  160. */
  161. UA_SecurityPolicyEncryptionAlgorithm encryptionAlgorithm;
  162. } UA_SecurityPolicyCryptoModule;
  163. typedef struct {
  164. /* Generates a thumbprint for the specified certificate.
  165. *
  166. * @param securityPolicy the securityPolicy the function is invoked on.
  167. * @param certificate the certificate to make a thumbprint of.
  168. * @param thumbprint an output buffer for the resulting thumbprint. Always
  169. * has the length specified in the thumbprintLength in the
  170. * asymmetricModule. */
  171. UA_StatusCode (*makeCertificateThumbprint)(const UA_SecurityPolicy *securityPolicy,
  172. const UA_ByteString *certificate,
  173. UA_ByteString *thumbprint)
  174. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  175. /* Compares the supplied certificate with the certificate in the endpoit context.
  176. *
  177. * @param securityPolicy the policy data that contains the certificate
  178. * to compare to.
  179. * @param certificateThumbprint the certificate thumbprint to compare to the
  180. * one stored in the context.
  181. * @return if the thumbprints match UA_STATUSCODE_GOOD is returned. If they
  182. * don't match or an error occurred an error code is returned. */
  183. UA_StatusCode (*compareCertificateThumbprint)(const UA_SecurityPolicy *securityPolicy,
  184. const UA_ByteString *certificateThumbprint)
  185. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  186. UA_SecurityPolicyCryptoModule cryptoModule;
  187. } UA_SecurityPolicyAsymmetricModule;
  188. typedef struct {
  189. /* Pseudo random function that is used to generate the symmetric keys.
  190. *
  191. * For information on what parameters this function receives in what situation,
  192. * refer to the OPC UA specification 1.03 Part6 Table 33
  193. *
  194. * @param securityPolicy the securityPolicy the function is invoked on.
  195. * @param secret
  196. * @param seed
  197. * @param out an output to write the data to. The length defines the maximum
  198. * number of output bytes that are produced. */
  199. UA_StatusCode (*generateKey)(const UA_SecurityPolicy *securityPolicy,
  200. const UA_ByteString *secret,
  201. const UA_ByteString *seed, UA_ByteString *out)
  202. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  203. /* Random generator for generating nonces.
  204. *
  205. * @param securityPolicy the securityPolicy this function is invoked on.
  206. * Example: myPolicy->generateNonce(myPolicy,
  207. * &outBuff);
  208. * @param out pointer to a buffer to store the nonce in. Needs to be
  209. * allocated by the caller. The buffer is filled with random
  210. * data. */
  211. UA_StatusCode (*generateNonce)(const UA_SecurityPolicy *securityPolicy,
  212. UA_ByteString *out)
  213. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  214. /*
  215. * The length of the nonce used in the SecureChannel as specified in the standard.
  216. */
  217. size_t secureChannelNonceLength;
  218. UA_SecurityPolicyCryptoModule cryptoModule;
  219. } UA_SecurityPolicySymmetricModule;
  220. typedef struct {
  221. /* This method creates a new context data object.
  222. *
  223. * The caller needs to call delete on the received object to free allocated
  224. * memory. Memory is only allocated if the function succeeds so there is no
  225. * need to manually free the memory pointed to by *channelContext or to
  226. * call delete in case of failure.
  227. *
  228. * @param securityPolicy the policy context of the endpoint that is connected
  229. * to. It will be stored in the channelContext for
  230. * further access by the policy.
  231. * @param remoteCertificate the remote certificate contains the remote
  232. * asymmetric key. The certificate will be verified
  233. * and then stored in the context so that its
  234. * details may be accessed.
  235. * @param channelContext the initialized channelContext that is passed to
  236. * functions that work on a context. */
  237. UA_StatusCode (*newContext)(const UA_SecurityPolicy *securityPolicy,
  238. const UA_ByteString *remoteCertificate,
  239. void **channelContext)
  240. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  241. /* Deletes the the security context. */
  242. void (*deleteContext)(void *channelContext);
  243. /* Sets the local encrypting key in the supplied context.
  244. *
  245. * @param channelContext the context to work on.
  246. * @param key the local encrypting key to store in the context. */
  247. UA_StatusCode (*setLocalSymEncryptingKey)(void *channelContext,
  248. const UA_ByteString *key)
  249. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  250. /* Sets the local signing key in the supplied context.
  251. *
  252. * @param channelContext the context to work on.
  253. * @param key the local signing key to store in the context. */
  254. UA_StatusCode (*setLocalSymSigningKey)(void *channelContext,
  255. const UA_ByteString *key)
  256. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  257. /* Sets the local initialization vector in the supplied context.
  258. *
  259. * @param channelContext the context to work on.
  260. * @param iv the local initialization vector to store in the context. */
  261. UA_StatusCode (*setLocalSymIv)(void *channelContext,
  262. const UA_ByteString *iv)
  263. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  264. /* Sets the remote encrypting key in the supplied context.
  265. *
  266. * @param channelContext the context to work on.
  267. * @param key the remote encrypting key to store in the context. */
  268. UA_StatusCode (*setRemoteSymEncryptingKey)(void *channelContext,
  269. const UA_ByteString *key)
  270. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  271. /* Sets the remote signing key in the supplied context.
  272. *
  273. * @param channelContext the context to work on.
  274. * @param key the remote signing key to store in the context. */
  275. UA_StatusCode (*setRemoteSymSigningKey)(void *channelContext,
  276. const UA_ByteString *key)
  277. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  278. /* Sets the remote initialization vector in the supplied context.
  279. *
  280. * @param channelContext the context to work on.
  281. * @param iv the remote initialization vector to store in the context. */
  282. UA_StatusCode (*setRemoteSymIv)(void *channelContext,
  283. const UA_ByteString *iv)
  284. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  285. /* Compares the supplied certificate with the certificate in the channel
  286. * context.
  287. *
  288. * @param channelContext the channel context data that contains the
  289. * certificate to compare to.
  290. * @param certificate the certificate to compare to the one stored in the context.
  291. * @return if the certificates match UA_STATUSCODE_GOOD is returned. If they
  292. * don't match or an errror occurred an error code is returned. */
  293. UA_StatusCode (*compareCertificate)(const void *channelContext,
  294. const UA_ByteString *certificate)
  295. UA_FUNC_ATTR_WARN_UNUSED_RESULT;
  296. } UA_SecurityPolicyChannelModule;
  297. struct UA_SecurityPolicy {
  298. /* Additional data */
  299. void *policyContext;
  300. /* The policy uri that identifies the implemented algorithms */
  301. UA_ByteString policyUri;
  302. /* The local certificate is specific for each SecurityPolicy since it
  303. * depends on the used key length. */
  304. UA_ByteString localCertificate;
  305. /* Function pointers grouped into modules */
  306. UA_SecurityPolicyAsymmetricModule asymmetricModule;
  307. UA_SecurityPolicySymmetricModule symmetricModule;
  308. UA_SecurityPolicySignatureAlgorithm certificateSigningAlgorithm;
  309. UA_SecurityPolicyChannelModule channelModule;
  310. UA_CertificateVerification *certificateVerification;
  311. UA_Logger logger;
  312. /*Updates the ApplicationInstanceCertificate and the corresponding
  313. * private key at runtime. */
  314. UA_StatusCode (*updateCertificateAndPrivateKey)(UA_SecurityPolicy *policy,
  315. const UA_ByteString newCertificate,
  316. const UA_ByteString newPrivateKey);
  317. /* Deletes the dynamic content of the policy */
  318. void (*deleteMembers)(UA_SecurityPolicy *policy);
  319. };
  320. typedef struct {
  321. UA_SecurityPolicy securityPolicy;
  322. UA_EndpointDescription endpointDescription;
  323. } UA_Endpoint;
  324. /* Gets the number of bytes that are needed by the encryption function in
  325. * addition to the length of the plaintext message. This is needed, since
  326. * most RSA encryption methods have their own padding mechanism included.
  327. * This makes the encrypted message larger than the plainText, so we need to
  328. * have enough room in the buffer for the overhead.
  329. *
  330. * @param securityPolicy the algorithms to use.
  331. * @param channelContext the retrieve data from.
  332. * @param maxEncryptionLength the maximum number of bytes that the data to
  333. * encrypt can be. */
  334. size_t
  335. UA_SecurityPolicy_getRemoteAsymEncryptionBufferLengthOverhead(const UA_SecurityPolicy *securityPolicy,
  336. const void *channelContext,
  337. size_t maxEncryptionLength);
  338. typedef UA_StatusCode (*UA_SecurityPolicy_Func)(UA_SecurityPolicy *policy,
  339. UA_CertificateVerification *certificateVerification,
  340. const UA_ByteString localCertificate,
  341. const UA_ByteString localPrivateKey,
  342. UA_Logger logger);
  343. _UA_END_DECLS
  344. #endif /* UA_PLUGIN_SECURITYPOLICY_H_ */