I'm attempting to use the QycdRenewCertificate to renew a certificate stored in DCM, using the RNWC0300 format.

The API call is failing with a CPF3CF2 escape message. The exception data portion of the error code parameter simple says "qycu_renewCertificate : RC=331 API". I've hunted high and low for some documentation on the return code values but I can't find anything.

Does anyone know how I can find out what RC=331 means?

I'm afraid I can't give you an answer to your questions as asked - but have you looked at 
Jesse Gorzinski's DCM tools to see if you could save yourself from writing code?  Cert renewal is one of the options. https://github.com/ThePrez/DCM-tools

Hi Jon

Yes, I tried using DCM tools a while back but couldn't get the `dcmrenew` command to work.

I raised an issue here https://github.com/ThePrez/DCM-tools/issues/43.

It would be really helpful if the API error gave an meaningful message of the problem rather than simply a return code or the API documentation specified what the return codes meant. Just looking for a clue here, any clue.

My hope is that an IBMer sees this and takes pity on an old IBM i developer!

The built in RSE API has DCM things in it:
Introducing RSE API (ibm.com)

New REST APIs to manage digital certificates (ibm.com)

Hi Bryan

Yes, I did have a look at the documentation for the new APIs but they don't appear to support certificate renewal. At least not in the documentation I found.

By way of an update. A support case was logged with IBM to clarify the return code values for the renew API and they were able to help.

They pointed me at some documentation for the GSKit errors: https://www.ibm.com/docs/en/db2/11.1?topic=errors-gskit-return-codes. It doesn't actually mention the 331 error but they did include the details for that one.

Return Code 331 is a GSKit error.

#define GSKKM_ERR_RENEW_CERT_ISSUER    331  

This means the certificate's issuer didn't match renewing certificate.

For my particular use case I am using the integrated Apache HTTP server as a reverse proxy server for a number of micro services all secured with a Let's Encrypt certificate stored in DCM.

The reason the renew API has just started to fail is because Let's Encrypt have recently changed their intermediate certificate to be one of either R10 or R11 (for RSA certs). The intermediate certificate used on a renewed certificate can now differ to the original certificate. If it does then the DCM renew API will issue the 331 error.

Here are the details on the Let's Encrypt change: https://letsencrypt.org/2024/04/12/changes-to-issuance-chains.html.

One option for me was to then look at deleting the existing certificate, import the renewed certificate and reapply the application definition association. This is not possible using the (programmatic) DCM APIs. It is possible using the new RSE DCM APIs and I've proved this, manually using the OpenAPI UI, but it is quite involved. You need to convert the certificate into a Base64 string to provide to the API, which is doable, but to "simply" renew a certificate in DCM it's feeling more complicated than it should be.

Note that the new RSE DCM APIs do not include a renew API.

My plan is to look at the option of using nginx as my reverse proxy server, which should eliminate the need to use DCM and the integration Apache HTTP server for this particular use case and the certificate renewal should just work.