ua_plugin_securitypolicy.h 18 KB

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