Creating Private Keys and Certificates for Ingress Gateway

A Creating Private Keys and Certificates for Ingress Gateway

Caution:

Creating keys and certificates are outside UDR scope and user or operator should perform this at their discretion.

Following are the certificate requirements when signed by a Certificate authority (CA):

Ingress Gateway and Egress Gateway does not support certificates with Distinguished Encoding Rules (DER) binary encoding. You must decode the certificates before creating secret.
Certificates must be signed with a valid hash algorithm. For example, SHA256. Deprecated or weak algorithms, for example SHA1 will raise exceptions.
Additional restriction imposed in the certificate must be performed carefully. For example, when configuring certificates with extended key usage, you must consider that Ingress Gateway works as a TLS Web server and Egress Gateway work as a TLS Web client.

Gateway supports both RSA and ECDSA signing for ingress and egress traffic. Initial algorithm selection is configured by using initialAlgorithm flag in the custom-values.yaml for each gateway. Select as follow:

For RSA use RS256
For ECDSA use ES256

Certificates for selected initialAlgorithm must be included in the ocudr-gateway-secret.

To create the private keys and certificates:

Run the following command to generate RSA private key:

openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout rsa_private_key -out rsa_certificate.crt -config ssl.conf -passin pass:"keystorepasswd" -passout pass:"keystorepasswd"

Run the following command to convert the private key to .pem format:

openssl rsa -in rsa_private_key -outform PEM -out rsa_private_key_pkcs1.pem -passin pass:"keystorepasswd" -passout pass:"keystorepasswd"

Run the following command to generate a certificate using private key:

openssl req -new -key rsa_private_key -out apigatewayrsa.csr -config ssl.conf -passin pass:"keystorepasswd" -passout pass:"keystorepasswd"

Note:

Use the following sample file of ssl.conf to configure default entries along with storage area network (SAN) details for your certificate.

#ssl.conf
[ req ]
default_bits = 4096
distinguished_name = req_distinguished_name
req_extensions = req_ext
[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_default = IN
stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName_default = Karnataka
localityName = Locality Name (eg, city)
localityName_default = Bangalore
organizationName = Organization Name (eg, company)
organizationName_default = Oracle
commonName = Common Name (e.g. server FQDN or YOUR name)
commonName_max = 64
commonName_default = localhost
[ req_ext ]
subjectAltName = @alt_names
[alt_names]
IP = 127.0.0.1
DNS.1 = localhost

Run the following set of commands to create root certificate authority (CA):

openssl req -new -keyout cakey.pem -out careq.pem -config ssl.conf -passin pass:"keystorepasswd" -passout pass:"keystorepasswd"
openssl x509 -signkey cakey.pem -req -days 3650 -in careq.pem -out caroot.cer -extensions v3_ca -passin pass:"keystorepasswd" 
echo 1234 > serial.txt

Run the following command to sign the server certificate with root CA private key:

openssl x509 -CA caroot.cer -CAkey cakey.pem -CAserial serial.txt -req -in apigatewayrsa.csr -out apigatewayrsa.cer -days 365 -extfile ssl.conf -extensions req_ext -passin pass:"keystorepasswd"

Run the following command to generate ECDSA private key:

openssl ecparam -genkey -name prime256v1 -noout -out ecdsa_private_key.pem
openssl pkcs8 -topk8 -in ecdsa_private_key.pem -inform pem -out ecdsa_private_key_pkcs8.pem -outform pem -nocrypt

Run the following command to generate a certificate using private key:

openssl req -new -key ecdsa_private_key_pkcs8.pem -x509 -nodes -days 365 -out ecdsa_certificate.crt -config ssl.conf
openssl req -new -key ecdsa_private_key_pkcs8.pem -out apigatewayecdsa.csr -config ssl.conf -passin pass:"keystorepasswd" -passout pass:"keystorepasswd"

Run the following command to sign the server certificate with root CA private key:

openssl x509 -CA caroot.cer -CAkey cakey.pem -CAserial serial.txt -req -in apigatewayecdsa.csr -out apigatewayecdsa.cer -days 365 -extfile ssl.conf -extensions req_ext -passin pass:"keystorepasswd"

Create key.txt by entering any password.
Example: echo "keystorepasswd" > key.txt

This password is used to configure gateway key store.
Create trust.txt by entering any password.
Example: echo "truststorepasswd" > trust.txt

This password is used to configure gateway trust store.

Run the following commands to create a secret:

kubectl create ns NameSpace
kubectl create secret generic ocudr-gateway-secret --from-file=apigatewayrsa.cer --from-file=caroot.cer --from-file=apigatewayecdsa.cer --from-file=rsa_private_key_pkcs1.pem --from-file=ecdsa_private_key_pkcs8.pem --from-file=key.txt --from-file=trust.txt -n <Namespace>

Updating Keys and Certificates in the Existing Secrets

Prerequsite: The certificates and files that need to be updated must be present in the secret.

Perform the following steps to update the existing certificates in secrets:

Run the following command to add a certificate:
```
TLS_CRT=$(base64 < "<certificate-name>" | tr -d '\n')
kubectl patch secret <secret-name> -p "{\"data\":{\"<certificatename>\":\"${TLS_CRT}\"}}"
```
Here,

<certificate-name> is the certificate file name.

<secret-name> is the name of the secret, for example, ocudr-gateway-secret.

Example:

Run the following command to add a Certificate Authority (CA) Root from the caroot.cer file to the ocudr-gateway-secret:
```
TLS_CRT=$(base64 < "caroot.cer" | tr -d '\n')
kubectl patch secret ocudr-gateway-secret -p "{\"data\":{\"caroot.cer\":\"${TLS_CRT}\"}}" -n udr
```
Similarly, you can also add other certificates and keys to the ocudr-gateway-secret.
Run the following command to update an existing certificate:
```
TLS_CRT=$(base64 < "<updated-certificate-name>" | tr -d '\n')
kubectl patch secret <secret-name> -p "{\"data\":{\"<certificatename>\":\"${TLS_CRT}\"}}"
```
Here,

<updated-certificate-name> is the certificate file that contains the updated content.

Example:
Run the following command to update the private key present in the rsa_private_key_pkcs1.pem file to the ocudr-gateway-secret.
```
TLS_CRT=$(base64 < "rsa_private_key_pkcs1.pem" | tr -d '\n')
kubectl patch secret ocudr-gateway-secret -p "{\"data\":{\"rsa_private_key_pkcs1.pem\":\"${TLS_CRT}\"}}" -n udr
```
Similarly, you can also update other certificates and keys to the ocudr-gateway-secret.
Run the following command to remove an existing certificate:
```
kubectl patch secret <secret-name> -p "{\"data\":{\"<certificatename>\":null}}"
```

Here,

<certificate-name> is the name of the certificate to be removed.

The certificate must be removed when it expires or needs to be revoked.

Example:

Run the following command to remove the CA Root from the ocudr-gateway-secret:

kubectl patch secret ocudr-gateway-secret -p "{\"data\":{\"caroot.cer\":null}}" -n udr

Similarly, you can also remove other certificates and keys from the ocudr-gateway-secret.

Note:

The following are the certificate update and renewal impacts:

Updating, adding, deleting the certificate, ot terminates all the existing connections gracefully and re-establishes new connections for new requests.
When the certificates expires, no new connections are established for new requests, however, the existing connections remain active. After the renewal of the certificates all the existing connections are gracefully terminated. And, new connections are established with the renewed certificates.