Novell Documentation: Novell Certificate Server Libraries for C

NPKICreateOrganizationalCA

Creates the Organizational (that is, Tree) Certificate Authority (CA) if one does not already exist (formerly NWPKICreateOrganizationalCA).

Syntax

    #include "npki.h"
    
    NWRCODE NPKICreateOrganizationalCA(
       const NPKIContext            context,
       const unicode               *serverDN,          
       const unicode               *organizationalCAName,
       const nuint32                keyType,
       const nuint32                keySize,
       const unicode               *subjectDN, 
       const nuint32                signatureAlgorithm,
       const nuint32                dateFlags,
       const nuint32                validFrom,
       const nuint32                validTo, 
       const nuint32                publicKeyFlags,
       const nuint32                privateKeyFlags,
       const NPKI_Extension        *keyUsage,
       const NPKI_Extension        *basicConstraints,
       const NPKI_ExtAltNames      *altNames,
       const NPKI_Extension        *NovellAttr,
       const NPKI_ASN1_Extensions  *extensions,   
       unicode const              **organizationalCADN,
       const nuint32                retryFlag,
       void                        *reserved1,
       void                        *reserved2);

Parameters

context: (IN) Specifies the NPKI context for the request.
serverDN: (IN) Specifies the eDirectory Server that will host the organizational CA. This must be a valid eDirectory server in contextDN.
organizationalCAName: (IN) Specifies the CA object name.
keyType: (IN) Specifies the type of key that you want generated. For this release, the only supported key type is RSA or a value of PKI_RSA_ALGORITHM. (See Key Generation Algorithms Defines).
keySize: (IN) Specifies the size of the key that the caller wants to generate. If the key size requested cannot be generated, the server returns an error and no key is generated. Calling NPKIGetServerInfo with flags set to PKI_CA_INFO, NPKIGetAlgorithmInfo obtains the supported key size on the server.
subjectDN: (IN) Specifies the subjectDN. This is the name to be encoded in the subject field in the X.509 certificate. The subject field identifies the entity associated with the public/private key pair. (For more information, see RFC 2459*, Section 4.1.2.6.)
signatureAlgorithm: (IN) Specifies the algorithm to use to sign the certificate. You can call NPKIGetServerInfo to determine which signature algorithms are supported.
dateFlags: (IN) Specifies whether dates have a two-digit or four-digit year. For this release, set this to DEFAULT_YEAR_ENCODING.
validFrom: (IN) Specifies the beginning of the period of validity, represented as the number of seconds since 00:00:00 UTC Jan 1, 1970, or as 0xFFFFFFFF to represent the current time on the server.
validTo: (IN) Specifies the end of the period of validity, represented as the number of seconds since 00:00:00 UTC Jan 1, 1970, or as 0xFFFFFFFF to represent the greatest validity period available on the server.
You can call NPKIGetServerInfo to determine the validity period supported by the server.
publicKeyFlags: (IN) Specifies the public key options to use when creating the key pair. For this release, use the define PUBLIC_KEY_SINGLE_SERVER together with any optional public key flags.
privateKeyFlags: (IN) Specifies the private key options to use when creating the key pair. For this release, use the define PRIVATE_KEY.

NOTE:There currently is one Optional Private Key Flag (PRIVATE_KEY _EXTRACTABLE). To use this optional flag, it must be ORed with the value PRIVATE_KEY to enable extraction of the CA’s private key into a PKCS #12 file. (PKCS #12 is the standard format for extracting and importing keys). This flag must be used to enable backup of the CA’s private key.

For a sample implementation of this task, see BackupCA.

When using the PRIVATE_KEY_EXTRACTABLE flag and including the Novell Security Attributes™ extension, it is necessary to bitwise-OR the extractable option (that is, NOVELL_EXTENSION_EXTRACTABLE_KEY in Additional Flags) along with the appropriate Novell attribute (see NOVELL_EXTENSION_ORGCA_DEFAULT (0x00400) in Mutually Exclusive Flags) to the flags field in the Novell Security Attributes extension.
keyUsage: (IN) Specifies the X.509 key usage extension. For more information, see Section 4.16, X.509 Extensions and Section 4.4, Key Usage Extension. The key usage extension is not included in the certificate if this parameter is NULL.
basicConstraints: (IN) Specifies the X.509 basic constraints extension. For more information, see Section 4.16, X.509 Extensions and the Section 4.1, Basic Constraints Extension. The basic constraints extension is not included in the certificate if this parameter is NULL.
altNames: (IN) Specifies the X.509 subject alternative name extension. For more information, see Section 4.16, X.509 Extensions and the Section 5.3, Subject Alternative Names Extension for more details. The subject alternative names extension is not included in the certificate if this parameter is NULL.
NovellAttr: (IN) Specifies the Novell Security Attributes extension. For more information, see the sections Section 4.16, X.509 Extensions and Section 4.5, Novell Security Attributes Extension. If this parameter is NULL, the default Novell Security Attributes extension for a CA is included in the certificate.
extensions: (IN) Not implemented for CA certificates in this release. Pass in NULL.
organizationalCADN: (OUT) Returns the CA object’s distinguished name (DN). The leaf name is supplied by the caller in the field organizationalCAName and the system concatenates it with the Security container’s name to get the CA object's FDN.
retryFlag: (IN) Specifies whether the call is a retry. When NPKICreateOrganizationalCA is called, a Certificate Authority object is created; however, eDirectory may take some time to replicate the object.
Because of the possibility of replication delay, subsequent calls to NPKICreateOrganizationalCA might be necessary (for example, if previous calls fail due to replication delay); however, subsequent calls should be made with the retryFlag set to PKI_RETRY so that the system does not try to create a new CA object. The error code that is usually associated with a replication delay is ERR_NO_SUCH_ENTRY, -601.
reserved1: Reserved for future use.
reserved2: Reserved for future use.

Return Values

Returns 0 if successful, or an eDirectory, NICI, or PKI error code if not successful.

PKI NCP Calls

0x 2222 92 02 Install CA

Remarks

NPKICreateOrganizationalCA creates a Certificate Authority (CA) object in the Security container if one does not exist.

This function gives serverDN supervisor (S) rights to the All_Attributes ACL of the CA object, sets the NDSPKI:Organizational CA DN attribute of the Security container to be the distinguished name of the CA object, and gives [Public] read (R) rights to the NDSPKI:Organizational CA DN attribute of the Security container.

This function makes the Install CA NCP call to serverDN. This causes PKI services to generate an RSA key pair, create two X.509 certificates (one self-signed and one signed by the server’s machine unique key), and store all of this information in the CA object.

To have the ability to backup the CA’s private key, you must use the optional private key flag, PRIVATE_KEY_EXTRACTABLE.

For a sample implementation of how to back up the CA, see BackupCA.

Syntax

Parameters

Return Values

PKI NCP Calls

Remarks

See Also