Constructs a self-signed certificate and returns it to the
caller.
Format
#include <gskcms.h>
gsk_status gsk_construct_self_signed_certificate (
x509_algorithm_type signature_algorithm,
const_char * subject_name,
int num_days,
gsk_boolean ca_certificate,
x509_extensions * extensions,
x509_public_key_info * public_key,
pkcs_private_key_info * private_key,
x509_certificate * subject_certificate)
Parameters
- signature_algorithm
- Specifies the signature algorithm used to sign the constructed
certificate.
- subject_name
- Specifies the distinguished name for the certificate subject.
The distinguished name is specified in the local code page and consists
of one or more relative distinguished name components separated by
commas.
- num_days
- Specifies the number of days for the certificate validity period
as a value between 1 and 9999 (the maximum of 9999 will be used if
a larger value is specified and the minimum of 1 will be used if a
smaller value is specified).
- ca_certificate
- Specify TRUE if this is a certification authority certificate
or FALSE if this is an end user certificate.
- extensions
- Specifies the certificate extensions for the new certificate.
Specify NULL for this parameter if no certificate extensions are supplied.
- public_key
- Specifies the public key for the constructed certificate.
- private_key
- Specifies the private key for the constructed certificate.
- subject_certificate
- Contains the constructed certificate.
Results
The function return value will be
0 if no error is detected. Otherwise, it will be one of the return
codes listed in the
gskcms.h include file. These are some
possible errors:
- [CMSERR_ALG_NOT_SUPPORTED]
- The signature algorithm is not valid.
- [CMSERR_BAD_EC_PARAMS]
- Elliptic Curve parameters are not valid.
- [CMSERR_BAD_KEY_SIZE]
- The key size is not valid.
- [CMSERR_BAD_SUBJECT_NAME]
- The subject name is not valid.
- [CMSERR_DUPLICATE_EXTENSION]
- Supplied extensions contain a duplicate extension.
- [CMSERR_ECURVE_NOT_FIPS_APPROVED]
- Elliptic Curve not supported in FIPS mode.
- [CMSERR_ECURVE_NOT_SUPPORTED]
- Elliptic Curve is not supported.
- [CMSERR_ICSF_FIPS_DISABLED]
- ICSF PKCS #11 services are disabled.
- [CMSERR_ICSF_NOT_AVAILABLE]
- ICSF services are not available.
- [CMSERR_ICSF_NOT_FIPS]
- ICSF PKCS #11 not operating in FIPS mode.
- [CMSERR_ICSF_SERVICE_FAILURE]
- ICSF callable service returned an error.
- [CMSERR_KEY_MISMATCH]
- The signer key cannot be used to sign a certificate or the key
type is not supported for the requested signature algorithm.
- [CMSERR_NO_MEMORY]
- Insufficient storage is available.
Usage
The gsk_construct_self_signed_certificate() routine
will construct an X.509 certificate as described in RFC 5280: Internet X.509 Public
Key Infrastructure Certificate and Certificate Revocation List (CRL)
Profile. A certification authority certificate will have
basic constraints and key usage extensions which allow the certificate
to be used to sign other certificates and certificate revocation lists.
An end user certificate will have no basic constraints limitations
or key usage limitations. The constructed certificate is then returned
in the x509_certificate structure subject_certificate.
These
signature algorithms are supported:
- x509_alg_md2WithRsaEncryption
- RSA encryption with MD2 digest - {1.2.840.113549.1.1.2}
- x509_alg_md5WithRsaEncryption
- RSA encryption with MD5 digest - {1.2.840.113549.1.1.4}
- x509_alg_sha1WithRsaEncryption
- RSA encryption with SHA-1 digest - {1.2.840.113549.1.1.5}
- x509_alg_sha224WithRsaEncryption
- RSA encryption with SHA-224 digest - {1.2.840.113549.1.1.14}
- x509_alg_sha256WithRsaEncryption
- RSA encryption with SHA-256 digest - {1.2.840.113549.1.1.11}
- x509_alg_sha384WithRsaEncryption
- RSA encryption with SHA-384 digest - {1.2.840.113549.1.1.12}
- x509_alg_sha512WithRsaEncryption
- RSA encryption with SHA-512 digest - {1.2.840.113549.1.1.13}
- x509_alg_dsaWithSha1
- Digital Signature Standard with SHA-1 digest - {1.2.840.10040.4.3}
- x509_alg_dsaWithSha224
- Digital Signature Standard with SHA-224 digest – {2.16.840.1.101.3.4.3.1}
- x509_alg_dsaWithSha256
- Digital Signature Standard with SHA-256 digest – {2.16.840.1.101.3.4.3.2}
- x509_alg_ecdsaWithSha1
- Elliptic Curve Digital Signature Algorithm with SHA-1 digest -
{1.2.840.10045.4.1}
- x509_alg_ecdsaWithSha224
- Elliptic Curve Digital Signature Algorithm with SHA-224 digest
- {1.2.840.10045.4.3.1}
- x509_alg_ecdsaWithSha256
- Elliptic Curve Digital Signature Algorithm with SHA-256 digest
- {1.2.840.10045.4.3.2}
- x509_alg_ecdsaWithSha384
- Elliptic Curve Digital Signature Algorithm with SHA-384 digest
- {1.2.840.10045.4.3.3}
- x509_alg_ecdsaWithSha512
- Elliptic Curve Digital Signature Algorithm with SHA-512 digest
- {1.2.840.10045.4.3.4}
When executing in FIPS mode, signature algorithms
x509_alg_md2WithRSAEncryption and x509_alg_md5WithRsaEncryption are
not supported.
If not in FIPS mode, an RSA key size must be
between 512 and 4096 bits. A DSA key size must be between 512 and
2048 bits. A key size of 1024 or less should specify signature algorithm
x509_alg_dsaWithSha1, while a key size of 2048 bits should specify
either x509_alg_dsaWithSha224 or x509_alg_dsaWithSha256 as the signature
algorithm.
In FIPS mode, an RSA key size must be between 1024
and 4096 bits. A DSA key size must be either 1024 bits or 2048 bits.
A key size of 1024 bits should specify signature algorithm x509_alg_dsaWithSha1,
while a key size of 2048 bits should specify either x509_alg_dsaWithSha224
or x509_alg_dsaWithSha256 as the signature algorithm. An ECC key must
use a NIST recommended named curve.
Note: A self-signed end-entity
certificate (server or client certificate) is not recommended for
use in production environments and should only be used to facilitate
test environments before production. Self-signed certificates do not
imply any level of security or authenticity of the certificate because,
as their name implies, they are signed by the same key that is contained
in the certificate. However, certificates that are signed by a certificate
authority indicate that, at least at the time of signature, the certificate
authority approved the information contained in the certificate.