The example below enumerates all personalities with application “IDevID”. This can be useful to select personalities usable for onboarding (cf. 5.2.2, Figure 9).

1. gta_instance_handle_t h_inst;
2. gta_context_handle_t h_ctx = GTA_HANDLE_INVALID;
3. gta_errinfo_t errinfo;
5. bool b_loop_pers = true;
6. gta_enum_handle_t h_enum_pers = GTA_HANDLE_ENUM_FIRST;
8. while (b_loop_pers) {
9. char pers_name[STR_LEN_MAX];
10. myio_obufstream_t ostream_pers_name = { 0 };
12. myio_open_obufstream(&ostream_pers_name, pers_name,
13. sizeof(pers_name), &errinfo);
15. if (gta_personality_enumerate_application(h_inst,
16. "IDevID", h_enum_pers, GTA_PERSONALITY_ENUM_ALL,
17. (gtaio_ostream_t *)&o_pers_name, &errinfo)) {
19. /*
20. * do something with personality pers_name
21. */
23. }
24. else {
25. b_loop_pers = false;
26. }
27. myio_close_obufstream(&ostream_pers_name, &errinfo);
28. }
29. }

The example below enumerates all personalities and checks for the attribute org.opcfoundation.product_instance_uri

1. bool b_loop = true;
2. char identifier_type_buffer[200];
3. char identifier_value_buffer[200];
4. myio_obufstream_t ostream_identifier_type = { 0 };
5. myio_obufstream_t ostream_identifier_value = { 0 };
6. gta_enum_handle_t h_enum = GTA_HANDLE_ENUM_FIRST;
8. gta_context_handle_t h_ctx = GTA_HANDLE_INVALID;
9. bool exit_loops = false;
10. char selected_personality[100];
12. /* enumerate all identifiers */
13. while (b_loop && !exit_loops) {
14. myio_open_obufstream(&ostream_identifier_type,
15. identifier_type_buffer,
16. sizeof(identifier_type_buffer),
17. &errinfo);
18. myio_open_obufstream(&ostream_identifier_value,
19. identifier_value_buffer,
20. sizeof(identifier_value_buffer),
21. &errinfo);
22. b_ret = gta_identifier_enumerate(
23. h_inst,
24. &h_enum,
25. (gtaio_ostream_t *)&ostream_identifier_type,
26. (gtaio_ostream_t *)&ostream_identifier_value,
27. &errinfo);
28. myio_close_obufstream(&ostream_identifier_type, &errinfo);
29. myio_close_obufstream(&ostream_identifier_value, &errinfo);
31. if (true == b_ret) {
32. bool b_inner_loop = true;
33. char personality_name_buffer[200];
34. myio_obufstream_t ostream_personality_name = { 0 };
35. gta_enum_handle_t h_enum_inner_loop = GTA_HANDLE_ENUM_FIRST;
37. /* enumerate all personalities belonging to identifier */
38. while (b_inner_loop && !exit_loops) {
39. myio_open_obufstream(&ostream_personality_name,
40. personality_name_buffer,
41. sizeof(personality_name_buffer),
42. &errinfo);
43. b_ret = gta_personality_enumerate(
44. h_inst,
45. identifier_value_buffer,
46. &h_enum_inner_loop,
47. GTA_PERSONALITY_ENUM_ALL,
48. (gtaio_ostream_t *)&ostream_personality_name,
49. &errinfo);
50. myio_close_obufstream(&ostream_personality_name, &errinfo);
52. if (true == b_ret) {
53. bool b_innermost_loop = true;
54. char attribute_type_buffer[200];
55. char attribute_value_buffer[200];
56. myio_obufstream_t ostream_attribute_type = { 0 };
57. myio_obufstream_t ostream_attribute_value = { 0 };
58. gta_enum_handle_t h_enum_innermost_loop
59. = GTA_HANDLE_ENUM_FIRST;
63. /* enumerate all attributes belonging to personality */
64. while (b_innermost_loop && !exit_loops) {
65. myio_open_obufstream(
66. &ostream_attribute_type,
67. attribute_type_buffer,
68. sizeof(attribute_type_buffer),
69. &errinfo);
70. myio_open_obufstream(
71. &ostream_attribute_value,
72. attribute_value_buffer,
73. sizeof(attribute_value_buffer),
74. &errinfo);
75. b_ret = gta_personality_attributes_enumerate(
76. h_inst,
77. personality_name_buffer,
78. &h_enum_innermost_loop,
79. (gtaio_ostream_t *)&ostream_attribute_type,
80. (gtaio_ostream_t *)&ostream_attribute_value,
81. &errinfo);
82. myio_close_obufstream(&ostream_attribute_type,
83. &errinfo);
84. myio_close_obufstream(&ostream_attribute_value,
85. &errinfo);
86. if (true == b_ret) {
87. if (0 == strcmp(
88. "org.opcfoundation.product_instance_uri",
89. attribute_type_buffer)) {
90. exit_loops = true;
91. strcpy(selected_personality,
92. personality_name_buffer);
93. }
94. }
95. else {
96. b_innermost_loop = false;
97. }
98. }
99. }
100. else {
101. errinfo = 0;
102. b_inner_loop = false;
103. }
104. }
105. }
106. else {
107. errinfo = 0;
108. b_loop = false;
109. }
110. }
112. /*
113. * do something with selected personality
114. */

The example below searches all attributes of a personality given by its name pers_name for an X.509 DeviceIdentity certificate.

1. bool b_loop_attr = true;
2. gta_enum_handle_t h_enum_attr = GTA_HANDLE_ENUM_FIRST;
4. while (b_loop_attr) {
5. char attr_name[STR_LEN_MAX];
6. char attr_type[STR_LEN_MAX];
7. myio_obufstream_t ostream_attr_name = { 0 };
8. myio_obufstream_t ostream_attr_type = { 0 };
10. myio_open_obufstream(&ostream_attr_name, attr_name,
11. sizeof(attr_name), &errinfo);
12. myio_open_obufstream(&ostream_attr_type, attr_type,
13. sizeof(attr_type), &errinfo);
15. if (gta_personality_attributes_enumerate(h_inst,
16. pers_name,
17. h_enum_attr,
18. (gtaio_ostream_t *)&ostream_attr_name,
19. (gtaio_ostream_t *)&ostream_attr_type,
20. &errinfo)) {
22. /* Get the attribute holding the
23. DeviceIdentity Certificate */
25. if (0 == strncmp(attr_type,
26. "ch.iec.30168.trustlist.certificate.self.x509",
27. STR_LEN_MAX)) {
28. h_ctx = gta_context_open(h_inst,
29. pers_name,
30. "org.opcfoundation.ECC-nistP256",
31. &errinfo);
33. /* get application certificate */
34. char devid_cert[CERT_SIZE_MAX];
35. myio_obufstream_t ostream_devid_cert = { 0 };
37. myio_open_obufstream(&ostream_devid_cert,
38. devid_cert, sizeof(devid_cert), &errinfo);
40. gta_personality_get_attribute(h_ctx,
41. attr_name, (gtaio_ostream_t *)&ostream_devid_cert,
42. &errinfo);
44. /* ... make use of this DeviceIdentity Cerficate
45. (e.g., add it to a list) ... */
47. gta_context_close(h_ctx, &errinfo);
48. }
49. }
50. else {
51. b_loop_attr = false;
52. }
53. myio_close_obufstream(&ostream_attr_name, &errinfo);
54. myio_close_obufstream(&ostream_attr_type, &errinfo);
55. }

The example code below illustrates the use of GTA API to implement the scenario outlined in section 5.2.3.1, Figure 12.

The following assumptions apply:

• Identifier used for the DCA Personality Set isurn:manufacturer.com:2024-10:myproduct:SN51235
• Name used for the DCA Identity Personality isurn:manufacturer.com:2024-10:myproduct:SN51235?cg=DefaultApplicationGroup&ct=EccNistP256&ix=1
• Name used for the DCA TrustList Personality isurn:manufacturer.com:2024-10:myproduct:SN51235?cg=DefaultApplicationGroup

Note that the example can be easily adjusted for any other profile by just switching to another profile (e.g., org.opcfoundation.Aes256-Sha256-RsaPss) and adjusting the identifier and personality names as desired.

1. gta_errinfo_t errinfo = 0;
3. char identifier_value[]
4. = "urn:manufacturer.com:2024-10:myproduct:SN51235";
5. char personality_name[]
6. = "urn:manufacturer.com:2024-10:myproduct:SN51235?"
7. "cg=DefaultApplicationGroup&ct=EccNistP256&ix=1";
8. char identity_profile[]
9. = "org.opcfoundation.ECC-nistP256";
10. char application[] = "DCA Identity";
11. char trustlist_personality_name[]
12. = "urn:manufacturer.com:2024-10:myproduct:SN51235?"
13. "cg=DefaultApplicationGroup";
14. char trustlist_application[] = "DCA TrustList";
15. char trustlist_profile[]
16. = "ch.iec.30168.basic.local_data_integrity_only";
18. /* Assign identifier */
19. gta_identifier_assign(
20. h_inst,
21. "org.opcfoundation.application_instance_uri",
22. identifier_value,
23. &errinfo);
25. /* Create DCA Identity Personality */
26. gta_access_policy_handle_t h_auth_use = GTA_HANDLE_INVALID;
27. h_auth_use = gta_access_policy_simple(
28. h_inst,
29. GTA_ACCESS_DESCRIPTOR_TYPE_INITIAL,
30. &errinfo);
31. gta_access_policy_handle_t h_auth_use = GTA_HANDLE_INVALID;
32. h_auth_admin = gta_access_policy_simple(
33. h_inst,
34. GTA_ACCESS_DESCRIPTOR_TYPE_INITIAL,
35. &errinfo);
37. struct gta_protection_properties_t protection_props = {0};
39. gta_personality_create(
40. h_inst,
41. identifier_value,
42. personality_name,
43. application,
44. identity_profile,
45. h_auth_use,
46. h_auth_admin,
47. protection_props,
48. &errinfo);
50. /* Generate CSR */
51. gta_context_handle_t h_ctx = GTA_HANDLE_INVALID;
52. h_ctx = gta_context_open(
53. h_inst,
54. personality_name,
55. "com.github.generic-trust-anchor-api.basic.enroll",
56. &errinfo);
58. /* Set context attribute org.opcfoundation.csr.subject */
59. const char subject_der[] = {…};
60. size_t subject_der_len = …;
61. myio_ibufstream_t istream_subject = { 0 };
62. myio_open_ibufstream(
63. &istream_subject,
64. subject_der, subject_der_len,
65. &errinfo);
66. gta_context_set_attribute(
67. h_ctx,
68. "org.opcfoundation.csr.subject",
69. (gtaio_istream_t*)&istream_subject,
70. &errinfo);
71. myio_close_ibufstream(&istream_subject, &errinfo);
73. /* Set context attribute org.opcfoundation.csr.subjectAltName */
74. const char subject_alt_name_der[] = {…};
75. size_t subject_alt_name_der_len = …;
76. myio_ibufstream_t istream_subject_alt_name = { 0 };
77. myio_open_ibufstream(
78. &istream_subject_alt_name,
79. subject_alt_name_der, subject_alt_name_der_len,
80. &errinfo);
81. gta_context_set_attribute(
82. h_ctx,
83. "org.opcfoundation.csr.subjectAltName",
84. (gtaio_istream_t*)&istream_subject_alt_name,
85. &errinfo);
86. myio_close_ibufstream(&istream_subject_alt_name, &errinfo);
88. char csr_buffer[CSR_SIZE];
89. myio_obufstream_t ostream_csr = { 0 };
90. myio_open_obufstream(
91. &ostream_csr,
92. csr_buffer, sizeof(csr_buffer),
93. &errinfo);
94. gta_personality_enroll(
95. h_ctx,
96. (gtaio_ostream_t*)&ostream_csr,
97. &errinfo);
98. myio_close_obufstream(&ostream_csr, &errinfo);
100. /* Send CSR and receive certificate */
101. char cert_buffer[] = {…};
102. size_t cert_len = …;
104. /* Store DCA certificate (optional) */
105. myio_ibufstream_t istream_cert = { 0 };
106. myio_open_ibufstream(
107. &istream_cert,
108. cert_buffer, cert_len,
109. &errinfo);
110. gta_personality_add_attribute(
111. h_ctx,
112. "ch.iec.30168.trustlist.certificate.self.x509",
113. "DCA certificate",
114. (gtaio_istream_t*)&istream_cert,
115. &errinfo);
116. myio_close_ibufstream(&istream_cert, &errinfo);
118. gta_context_close(h_ctx, &errinfo);
120. /* Receive TrustList */
121. char trustlist_buffer[] = {…};
122. size_t trustlist_len = …;
124. /* Create DCA TrustList Personality */
125. gta_personality_create(
126. h_inst,
127. identifier_value,
128. trustlist_personality_name,
129. trustlist_application,
130. trustlist_profile,
131. h_auth_use,
132. h_auth_admin,
133. protection_props,
134. &errinfo);
136. /* Protect DCA TrustList objects */
137. gta_context_handle_t h_ctx_seal = GTA_HANDLE_INVALID;
138. h_ctx_seal = gta_context_open(
139. h_inst,
140. trustlist_personality_name,
141. trustlist_profile,
142. &errinfo);
144. myio_ibufstream_t istream_trustlist = { 0 };
145. myio_open_ibufstream(
146. &istream_trustlist,
147. trustlist_buffer, trustlist_len,
148. &errinfo);
149. #define INTEGRITY_PROTECTION_SEAL_LENGTH 32
150. char seal_buffer[INTEGRITY_PROTECTION_SEAL_LENGTH];
151. myio_obufstream_t ostream_seal = { 0 };
152. myio_open_obufstream(
153. &ostream_seal,
154. seal_buffer, sizeof(seal_buffer),
155. &errinfo);
156. gta_authenticate_data_detached(
157. h_ctx_seal,
158. (gtaio_istream_t*)&istream_trustlist,
159. (gtaio_ostream_t*)&ostream_seal,
160. &errinfo);
161. myio_close_ibufstream(&istream_trustlist, &errinfo);
162. myio_close_obufstream(&ostream_seal, &errinfo);
164. gta_context_close(h_ctx_seal, &errinfo);

The example code below illustrates the use of GTA API to implement the scenario outlined in section 5.5.2, Figure 21. Note that functionality expected to be provided by the application is not elaborated but only addressed in comments. Error handling is omitted for the sake of clarity of the workflow.

The following pre-conditions apply:

• OPC UA application installed on device
• The OPC UA application has been successfully onboarded (cf. 5.4)
• The OPC UA security policy used in OpenSecureChannel Response is  Aes256-Sha256-RsaPss
• The GTA API profile used in the example is org.opcfoundation.Aes256-Sha256-RsaPss
• The name of the attribute used to store the Application Instance Certificate is my_server
• The GTA API personality name used in the example is urn:manufacturer.com:2024-10:myproduct:myserver_appid?cg=DefaultApplicationGroup&ct=Rsa2048&ix=1

1. gta_errinfo_t errinfo = 0;
3. char personality_name[]
4. = "urn:manufacturer.com:2024-10:myproduct:myserver_appid?"
5. "cg=DefaultApplicationGroup&ct=Rsa2048&ix=1";
6. char profile[]
7. = "org.opcfoundation.Aes256-Sha256-RsaPss";
8. char certificate_name = "my_server";
9. char trustlist_personality_name[]
10. = "urn:manufacturer.com:2024-10:myproduct:myserver_appid?"
11. "cg=DefaultApplicationGroup;
12. char trustlist_profile[]
13. = "ch.iec.30168.basic.local_data_integrity_only";
15. gta_context_handle_t h_ctx = GTA_HANDLE_INVALID;
16. h_ctx = gta_context_open(
17. h_inst,
18. personality_name,
19. profile,
20. &errinfo);
22. /* Get server certificate from personality attribute (optional) */
24. char cert_buffer[CERT_SIZE];
25. myio_obufstream_t ostream_cert = { 0 };
26. gta_personality_get_attribute(
27. h_ctx,
28. certificate_name,
29. (gtaio_ostream_t*)&ostream_cert,
30. &errinfo);
31. myio_close_obufstream(&ostream_cert, &errinfo);
33. /* Prepare OpenSecureChannel Response */
35. gta_context_handle_t h_ctx_seal = GTA_HANDLE_INVALID;
36. h_ctx_seal = gta_context_open(
37. h_inst,
38. trustlist_personality_name,
39. trustlist_profile,
40. &errinfo);
42. char trustlist_buffer[] = {…};
43. size_t trustlist_len = …;
44. myio_ibufstream_t istream_trustlist = { 0 };
45. myio_open_ibufstream(
46. &istream_trustlist,
47. trustlist_buffer, trustlist_len,
48. &errinfo);
49. char seal_buffer[] = {…};
50. size_t seal_len = …;
51. myio_ibufstream_t istream_seal = { 0 };
52. myio_open_ibufstream(
53. &istream_seal,
54. seal_buffer, seal_len,
55. &errinfo);
56. if (!gta_verify_data_detached(
57. h_ctx_seal,
58. (gtaio_istream_t*)&istream_trustlist,
59. (gtaio_istream_t*)&istream_seal,
60. &errinfo)) {
61. /* fail – TrustList has been tampered with */
62. }
63. myio_close_ibufstream(&istream_trustlist, &errinfo);
64. myio_close_ibufstream(&istream_seal, &errinfo);
66. gta_context_close(h_ctx_seal, &errinfo);
68. char encrypted_requestdata_buffer[] = {…};
69. size_t encrypted_requestdata_len = …;
70. myio_ibufstream_t istream_encrypted_requestdata = { 0 };
71. myio_open_ibufstream(
72. &istream_encrypted_requestdata,
73. encrypted_requestdata_buffer, encrypted_requestdata_len,
74. &errinfo);
75. #define REQUESTDATA_SIZE
76. char decrypted_requestdata_buffer[REQUESTDATA_SIZE];
77. myio_obufstream_t ostream_decrypted_requestdata = { 0 };
78. myio_open_obufstream(
79. &ostream_decrypted_requestdata,
80. decrypted_requestdata_buffer, sizeof(decrypted_requestdata_buffer),
81. &errinfo);
82. gta_unseal_data(
83. h_ctx,
84. (gtaio_istream_t*)&istream_encrypted_requestdata,
85. (gtaio_ostream_t*)&ostream_decrypted_requestdata,
86. &errinfo);
87. myio_close_ibufstream(&istream_encrypted_requestdata, &errinfo);
88. myio_close_obufstream(&ostream_decrypted_requestdata, &errinfo);
90. char tbs_responsedata_buffer[] = {…};
91. size_t tbs_responsedata_len = …;
92. myio_ibufstream_t istream_tbs_responsedata = { 0 };
93. myio_open_ibufstream(
94. &istream_tbs_responsedata,
95. tbs_responsedata_buffer, tbs_responsedata_len,
96. &errinfo);
97. #define SIGNATURE_SIZE
98. char signature_buffer[SIGNATURE_SIZE];
99. myio_obufstream_t ostream_signature = { 0 };
100. myio_open_obufstream(
101. &ostream_signature,
102. signature_buffer, sizeof(signature_buffer),
103. &errinfo);
104. gta_authenticate_data_detached(
105. h_ctx,
106. (gtaio_istream_t*)&istream_tbs_responsedata,
107. (gtaio_ostream_t*)&ostream_signature,
108. &errinfo);
109. myio_close_ibufstream(&istream_tbs_responsedata, &errinfo);
110. myio_close_obufstream(&ostream_signature, &errinfo);
112. gta_context_close(h_ctx, &errinfo);