This Method is used to start a request for a new Certificate and Private Key. The Certificate and Private Key. are returned in the FinishRequest response.

Signature

StartNewKeyPairRequest(

[in] NodeId applicationId

[in] NodeId certificateGroupId

[in] NodeId certificateTypeId

[in] String subjectName

[in] String[] domainNames

[in] String privateKeyFormat

[in] String privateKeyPassword

[out] NodeId requestId

);

Argument	Description
applicationId	The identifier assigned to the Application Instance by the CertificateManager.
certificateGroupId	The NodeId of the CertificateGroup which provides the context for the new request. If null the CertificateManager shall choose the DefaultApplicationGroup.
certificateTypeId	The NodeId of the CertificateType for the new Certificate. If null the CertificateManager shall generate a Certificate based on the value of the certificateGroupId argument.
subjectName	The subject to use for the Certificate. If not specified the ApplicationName and/or domainNames are used to create a suitable default value. The format of the subject is a sequence of name value pairs separated by a ‘/’. The name shall be one of ‘CN’, ‘O’, ‘OU’, ‘DC’, ‘L’, ‘S’ or ‘C’ and shall be followed by a ‘=’ and then followed by the value. The value may be any printable character except for ‘”’. If the value contains a ‘/’ or a ‘=’ then it shall be enclosed in double quotes (‘”’).
domainNames	The domain names to include in the Certificate. If not specified the DiscoveryUrls are used to create suitable defaults.
privateKeyFormat	The format of the private key. The following values are always supported: PFX- PKCS #12 encoded PEM- PKCS #8 Base64 encoded DER (see RFC 5958).
privateKeyPassword	The password to use for the private key.
requestId	The NodeId that represents the request. This value is passed to FinishRequest.

The call returns the NodeId that is passed to the FinishRequest Method.

The certificateGroupId parameter allows the caller to specify a CertificateGroup that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. If the Application does not currently belong to the requested CertificateGroup the CertificateManager shall verify that the Application is allowed to join the CertificateGroup and then, if permitted, add the Application to the CertificateGroup.

The set of available CertificateGroups are found in the CertificateGroups folder described in 7.9.2. The CertificateGroups allowed for an Application are returned by the GetCertificateGroups Method (see 7.9.7).

The certificateTypeId parameter specifies the type of Certificate to return. The permitted values are specified by the CertificateTypes Property of the Object specified by the certificateGroupId parameter.

The subjectName parameter is a sequence of X.500 name value pairs separated by a ‘/’. For example: CN=ApplicationName/OU=Group/O=Company.

If the certificateType is a subtype of ApplicationCertificateType the Certificate subject shall have an organization (O=) or domain name (DC=) field. The public key length shall meet the length restrictions for the CertificateType. The domain name field specified in the subject is a logical domain used to qualify the subject that may or may not be the same as a domain or IP address in the subjectAltName field of the Certificate.

If the certificateType is a subtype of HttpsCertificateType the Certificate common name (CN=) shall be the same as a domain from a DiscoveryUrl which uses HTTPS and the subject shall have an organization (O=) field.

If the subjectName is blank or null the CertificateManager generates a suitable default.

The requested subject may be ignored by the CertificateManager. The CertificateManager may update the subject to comply with policy requirements and to ensure global uniqueness.

The domainNames parameter is list of domains to be includes in the Certificate. If it is null or empty the GDS uses the DiscoveryUrls of the Server to create a list. For Clients the domainNames are omitted from the Certificate if they are not explicitly provided.

The privateKeyFormat specifies the format of the private key returned. All CertificateManager implementations shall support “PEM” and “PFX”.

The privateKeyPassword specifies the password on the private key. The CertificateManager shall not persist this information and shall discard it once the new private key is generated.

This Method shall be called from an encrypted SecureChannel and from a Session that has access to the CertificateAuthorityAdmin Role, the ApplicationAdmin Privilege, or the ApplicationSelfAdmin Privilege (see 7.2).

If auditing is supported, the CertificateManager shall generate the CertificateRequested AuditEventType (see 7.9.12) if this Method succeeds or fails.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NodeIdUnknown	The applicationId does not refer to a registered Application (deprecated).
Bad_NotFound	The applicationId does not refer to a registered Application.
Bad_InvalidArgument	One or more of the certificateGroupId, certificateTypeId, subjectName, domainNames or privateKeyFormat parameters is not valid. The text associated with the error shall indicate the exact problem.
Bad_UserAccessDenied	The current user does not have the rights required.
Bad_RequestNotAllowed	The current configuration of the CertificateManager does not allow the request. The text associated with the error should indicate the exact reason.

Table 53 specifies the AddressSpace representation for the StartNewKeyPairRequest Method.

Table 53 – StartNewKeyPairRequest Method AddressSpace Definition

Attribute	Value
BrowseName	2:StartNewKeyPairRequest
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
0:HasProperty	Variable	0:InputArguments	0:Argument[]	0:PropertyType	Mandatory
0:HasProperty	Variable	0:OutputArguments	0:Argument[]	0:PropertyType	Mandatory