Renew Certificate (QycdRenewCertificate) API
Required Parameter Group:
| 1 | Certificate request data | Input | Char(*) |
| 2 | Length of certificate request data | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Error Code | I/O | Char(*) |
Service Program: QICSS/QYCDRNWC
Default Public Authority: *USE
Threadsafe: No
The Renew Certificate (QycdRenewCertificate) API helps to automate the renew certificate process by creating and returning a CSR (Certificate Signing Request) based on an existing certificate and importing an issued certificate into the system certificate store.
Note: The QycdRenewCertificate API a is a multi-step process API.
- The API is called the first time with format RNWC0100 to request a new public/private key pair and receive a certificate signing request based on an expiring certificate.
- After the CSR has been sent to a certificate authority (CA) and an issued certificate has been received, the API is called a second time with format RNWC0200 to have the newly issued certificate imported into the system certificate store.
- If an existing CSR is used when requesting a renewed certificate, then import the renewed certificate and maintain the same key pair using format RNWC0300.
- Authority Required
- The caller of this API must have *ALLOBJ and *SECADM special authorities.
- The system certificate store (*SYSTEM)
- O_RDWR | O_SHARE_NONE
- The certificate signing request output file
- O_CREAT | O_WRONLY | O_SHARE_NONE
- The issued certificate file for import
- O_RDONLY | O_SHARE_RDONLY
- Certificate request data
- INPUT; CHAR(*)
The format specific information that defines the certificate request. Renewing a certificate is done in multiple steps using data contained in format RNWC0100 and RNWC0200. If renewing an existing certificate and maintaining the same key pair, then format RNWC0300 is used.
- Length of certificate request data
- INPUT; BINARY(4)
The length in bytes of the certificate request data.
- Format name
- INPUT; CHAR(8)
The format of the certificate request data parameter.
You must use one of the following format names:
RNWC0100 The data contains information about the current certificate to be renewed and the location to store a certificate signing request. Using this option will generate a new public/private key pair associated with a new certificate label. RNWC0200 The data contains information about a signed certificate to be imported into the system certificate store. This format is used when a new public/private key pair was created using RNWC0100 format. RNWC0300 The data contains information about a signed certificate using the same key pair as an existing certificate residing in the system certificate store. - Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
- The file is created during the generate process and therefore must not exist prior to calling the API.
- The specified path to the file must exist, but the specified file name must not exist.
Authorities and Locks
Required Parameter Group
Certificate Request Data Description
The following information is specified in the certificate request data field. For detailed descriptions of the fields in this table, see Field Descriptions.RNWC0100 format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary (4) | Offset to current certificate label |
| 4 | 4 | Binary (4) | Length of current certificate label |
| 8 | 8 | Binary (4) | CCSID of current certificate label |
| 12 | C | Binary (4) | Offset to new certificate label |
| 16 | 10 | Binary (4) | Length of new certificate label |
| 20 | 14 | Binary (4) | CCSID of new certificate label |
| 24 | 18 | Binary (4) | Offset to CSR path and file name |
| 28 | 1C | Binary (4) | Length of CSR path and file name |
| Char (*) | Current certificate label | ||
| Char (*) | New certificate label | ||
| Char (*) | CSR path and file name | ||
RNWC0200 and RNWC0300 format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | Binary (4) | Offset to certificate path and file name |
| 4 | 4 | Binary (4) | Length of certificate path and file name |
| Char (*) | Certificate path and file name | ||
Field Descriptions
CCSID of current certificate label. The CCSID (Coded Character Set Identifier) of the current certificate label parameter. If this value is 0, the default CCSID of the job will be used.
CCSID of new certificate label. The CCSID of the new certificate label parameter. If this value is 0, the default CCSID of the job will be used.
Certificate path and file name. The fully qualified path and file name containing the signed digital certificate.
CSR path and file name. The fully qualified path and file name where data will be stored as output from the generate certificate signing request process.
Current certificate label. The unique identifier of a certificate currently residing in the system certificate store selected for renewal.
Length of certificate path and file name. The length in bytes of the certificate path and file name parameter.
Length of CSR path and file name. The length in bytes of the CSR path and file name parameter.
Length of current certificate label. The length in bytes of the current certificate label parameter.
Length of new certificate label. The length in bytes of the new certificate label parameter.
New certificate label. A unique identifier for a certificate being created in the system certificate store.
Offset to certificate path and file name. The number of bytes from the beginning of the structure to the field that indicates the certificate path and file name.
Offset to CSR path and file name. The number of bytes from the beginning of the structure to the field that indicates the CSR path and file name.
Offset to current certificate label. The number of bytes from the beginning of the structure to the field that indicates the current certificate label.
Offset to new certificate label. The number of bytes from the beginning of the structure to the field that indicates the new certificate label.
Error Messages
The following messages may be sent from this function:
| Message ID | Error Message Text |
|---|---|
| CPF1F01 E | Directory name not valid. |
| CPF1F02 E | Directory not found. |
| CPF1F22 E | File not found. |
| CPF1F52 E | Error code not valid. |
| CPF222E E | &1 special authority is required. |
| CPF3C21 E | Value for parameter &1 not valid. |
| CPF3C3C E | Format name &1 is not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFA049 E | Certificate store does not exist. |
| CPFA09C E | User not authorized to certificate store. |
| CPFA0AA E | Error occurred while attempting to obtain space. |
| CPFA0C1 E | CCSID &1 not valid. |
| CPFA0CE E | Error occurred with path name parameter specified. |
| CPFB001 E | One or more input parameters is NULL or missing. |
| CPFB003 E | Certificate store password is not valid. |
| CPFB006 E | An error occurred. The error code is &1. |
API introduced: IBM® i 7.4