Skip to content

doc: update certificate generation information #212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
FreddieAkeroyd wants to merge 2 commits into
base: master
Choose a base branch
from
Open

doc: update certificate generation information #212

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a8ff22a
doc: update certificate generation information
FreddieAkeroyd Aug 3, 2026
f5b677c
Formatting
FreddieAkeroyd Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions documentation/how-to/security_configuration.md
View file
Open in desktop

@ralphlange ralphlange Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was going for "one-liner or use a proper GUI tool (xca)".
I'm not sure if that in-between way of using command line with a config file is something we should recommend.
But - tbh - I was going back and forth with this myself, so I don't have a final answer yet.

@FreddieAkeroyd FreddieAkeroyd Aug 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The one liner for us (git bash on windows) set CA:TRUE which may have been a factor, my colleague ran 1.4 with a certificate generated this way and it didn't work, i ran it using one generated via the config file and it did work. Maybe there was an issue with his 1.4 build, but he's now on leave so i can't check that for a bit. So my experience at the moment is the one liner is possibly system/platform dependent and so not reliable, so I feel we may need a warning to check some of the attributes of the certificate.

@FreddieAkeroyd FreddieAkeroyd Aug 4, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure how critical all of the options are, we could do a longer one liner adding e.g. -addext "basicConstraints=critical,CA:FALSE" and similar

Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,9 @@ PEM format requires `.pem` extension.

### Creating Application Instance Certificates

**NOTE:** open62541 version 1.3 does not support using a client certificate,
you need to use 1.4 or higher.

@ralphlange ralphlange Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is not true.
I have developed the security stuff against 1.3 and used it in the "Secure OPC UA" Training at the last Collaboration Meeting.
I suspect that 1.3 might not support the specific version of openssl you use. In that case, open62541 compiles without security support.

@FreddieAkeroyd FreddieAkeroyd Aug 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm ... interesting, a quick glance at build logs says it found openssh and didn't complain, but it did find 3.0 and the release notes for 1.4 say core: Support for OpenSSL 3.0 . I'll check a bit more. The release notes for 1.4 also said New features and major changes compared to the previous release series 1.3 include: client/server: Authentication with x509 certificates (client and server) so i was thinking that supported my experience of it not working with 1.3? It may also be the CA attributes on certificates, when i googled some of the errors my colleague got that turned up too. So probably a mixture of all sorts of things. Certicicates were made by openssl in "git bash" on windows, so it could be that is not configured right for opcua

@FreddieAkeroyd FreddieAkeroyd Aug 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What version of OpenSSL did you use for the training course? open62541 pull request 5349 (i didn't want to paste link in case it made a reference to the ticket) whose commit exists on the 1.3 branch suggests both 3.0 and 1.1.1f should work. I suspect the cause may be a certificate attribute, i did a brief test before using 1.4 and it had failed, but something else may have been amiss with the PLC at that point. I'm not able to re-check again at the moment as the only PLC I have access to is running a soak test with 1.4 and has also been swapped to use a client certificate rather than username+password based authentication. I can retry after this soak test finishes, will i need to go back to username+password or do you think client certificate in the identity file works with 1.3?


Creating a self-signed certificate for OPC UA use is pretty straight-forward.
Follow the documented procedure,
giving your certificate/key pair the following properties:
Expand All @@ -141,3 +144,38 @@ using the `openssl` command line utility, e.g.:
```bash
openssl req -x509 -newkey rsa:2048 -keyout private_key.pem -out cert.pem -sha256 -days 365 -nodes -addext "subjectAltName=URI:urn:<IOC>@<HOST>:EPICS:IOC,IP:<IP>"
```
Depending on you openssl configuration the above command may not set all the required attributes and may also set `CA:TRUE`, you can display the certificate using

@ralphlange ralphlange Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo;
please use semantic line breaks.

```bash
openssl x509 -in cert.pem -noout -text
```
and check the `X509v3 extensions` section.

To control setting attributes you can create a `opcua_cert.conf` configuration file as follows after editing the `< >` parts of the `[ dn ]` section
```

@ralphlange ralphlange Aug 3, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

linters will complain about no language setting

[ req ]
default_bits = 2048
encrypt_key = no
distinguished_name = dn
x509_extensions = ext_x509
default_md = sha256
prompt = no

[ dn ]
CN = ${ENV::HOST}
emailAddress = <email address>
O = <Organisation>
OU = <Organisation Unit>
ST = <State/Province/County>
C = <Country abbreviation>

[ ext_x509 ]
basicConstraints = critical, CA:FALSE
keyUsage = critical, digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyCertSign
extendedKeyUsage = critical, serverAuth, clientAuth
subjectAltName = URI:urn:${ENV::IOC}@${ENV::HOST}:EPICS:IOC,IP:${ENV::IP}
```
You can then use this file with the openssl command
```bash
env IP=<IP> HOST=<HOST> IOC=<IOC> openssl req -x509 -config opcua_cert.conf -newkey rsa:2048 -keyout client_private_key.pem -out client_certificate.pem -days 365
```
where `<IP>`, `<HOST>` and `<IOC>` have the same meaning as described earlier