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 Certificate Group 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 name 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 name 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- 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 Certificate Group that provides context for the request. If null the CertificateManager shall choose the DefaultApplicationGroup. The set of available Certificate Groups are found in the CertificateGroups folder described in 7.6.2. The Certificate Groups allowed for an Application are returned by the GetCertificateGroups Method (see 7.6.6).

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 name 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 name is a logical domain used to qualify the subject name 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 name shall have an organization (O=) field.

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

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 can be invoked by a configuration tool which has provided user credentials with necessary access permissions.

If auditing is supported, the CertificateManager shall generate the CertificateRequested AuditEventType (see 7.6.8.1) 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.
Bad_InvalidArgument	The certificateGroupId, certificateTypeId, subjectName, domainNames or privateKeyFormat parameter 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 32 specifies the AddressSpace representation for the StartNewKeyPairRequest Method.

Table 32 – StartNewKeyPairRequest Method AddressSpace Definition

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