IP*Works! OpenPGP 2016 C++ Edition
IP*Works! OpenPGP 2016 C++ Edition
Questions / Feedback?

CertMgr Configuration

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

CertMgr Configuration Settings

CertComment:   A comment to include in a saved certificate.

This settings specified the comment to use when calling SaveCertificate. This can only be used when CertificateOutputFormat is set to a value other than the default value. When CertificateOutputFormat is set to "SSH2PublicKey" the value of this setting should be the full header. For instance: "Comment: My Comment".

CertCustomExtensionCount:   The number of records in the CertCustomExtension arrays.

This property controls the size of the following arrays:

The array indices start at 0 and end at CertExtensionCount-1.

CertCustomExtensionCritical[i]:   Whether or not the extension is defined as critical.

Whether or not the certificate extension at index 'i' is defined as critical.

Valid array indices are from 0 to CertCustomExtensionCount - 1.

CertCustomExtensionOID[i]:   The ASN of the extension at index 'i'.

The ASN.1 Object-Identifier (OID) that defines the certificate extension at index 'i'.

Valid array indices are from 0 to CertCustomExtensionCount - 1.

CertCustomExtensionValue[i]:   The raw value of the extension at index 'i'.

The raw value of this certificate extension (as a byte string). This value is encoded according to the extension's ASN.1 specification.

Valid array indices are from 0 to CertCustomExtensionCount - 1.

CertificateOutputFormat:   The format of the certificate to save.

By default when SaveCertificate is called the certificate will be written in a PEM format. The format may be changed by setting CertificateOutputFormat to one of the following values:

"PEM" (default) A PEM formatted public certificate. Example:
-----BEGIN CERTIFICATE-----
MIIBkTCB+6ADAgECAgEBMA0GCSqGSIb3DQEBBQUAMA4xDDAKBgNVBAMTAzEwMDAgFw0wNzAx
...
Pg49SpQ+HcUibIpum2O0hmnySH7BPGfXD8Lu
-----END CERTIFICATE-----
"SSH2PublicKey" A SSH2 formated public key. Example:
---- BEGIN SSH2 PUBLIC KEY ----
AAAAB3NzaC1yc2EAAAADAQABAAAAgQD5/STHUd7YkN1JyoyYnUvCf+Fyx1+ZleBJxvwDcm3y
...
6bVPTODELil1PVWJDlfdwoLZZKY2ACFHzxBqaOlYv1rbd2JIYAuqGca2ow==
---- END SSH2 PUBLIC KEY ----
"OpenSSHPublicKey" An OpenSSH formatted public key. Example:
ssh-rsa AAAAB3NzaC1y...
"JWK"A JWK that contains a public key.
"XML" A XML file containing the public certificate. Example:
<X509Data><X509Certificate>MIIBkTCB+6ADAgECAgEBMA0GCSqGSIb3DQEBBQUAMA4xDDAKBgNVBAMTAzEwMDAgFw0wNzAx
...
Pg49SpQ+HcUibIpum2O0hmnySH7BPGfXD8Lu</X509Certificate></X509Data>

CertKeyLength:   The public key length for created certificates and keys.

When CreateCertificate creates a new certificate and associated key, or when CreateKey creates a key, this setting determines the length of the new public key (in bits). The default value is 1024.

CertKeyType:   The types of keys created for new certificates.

When CreateCertificate creates a new certificate and associated key, or when CreateKey creates a key, this setting determines the type of key generated: 1 for key exchange (encryption) keys, and 2 for digital signature keys. The default value is 1.

CertPublicKeyAlgorithm:   The public key algorithm used when a certificate is created.

When CreateCertificate creates a new certificate and associated key, this setting determines the public key algorithm of the generated keys. Valid values are:

  • RSA (default)
  • DSA
  • ECDSA_P256
  • ECDSA_P384
  • ECDSA_P521
  • Ed25519
  • Ed448

CertSignatureAlgorithm:   The signature algorithm used when creating certificates.

When CreateCertificate or IssueCertificate creates a new certificate, the signature algorithm used is specified by this setting. Possible values are:

  • MD2
  • MD5
  • SHA1
  • SHA256 (default)
  • SHA384
  • SHA512

CertValidityTime:   The validity period for the certificate.

This configuration setting determines the duration in days that a newly created certificate remains valid. The certificate becomes valid as soon as it is created, unless CertValidityOffset is set. The duration is not changed if CertValidityOffset is set; the certificate will still expire CertValidityTime days after the validity period begins. The default value is 365 days.

CertValidityOffset:   The number of days until the certificate becomes valid.

This configuration setting can be used to change when a newly created certificate becomes valid. By default, the certificate is valid as soon as it is created. Set CertValidityOffset to the number of days that this starting period should be offset from the current day. This setting also accepts negative values for back-dating the validity of a certificate. The default value is 0.

CSP:   The Cryptographic Service Provider.

The name of the Cryptographic Service Provider used to provide access to certificate signing operations.

CSRIgnoredExtensions:   Extensions to be ignorned when signing a CSR.

Set this configuration setting to a comma separated list of OID's of any extensions already present in the CSR that should be ignored when the CSR is signed.

For example if the SAN's in a CSR should be ignored the below code would work:

CertMgr1->Config("CSRIgnoredExtensions=2.5.29.17");

ExportedCert:   The exported certificate file.

This setting holds the certificate data that is exported when ExportCertificate is called with an empty CertFile parameter. If ExportFormat is set to "PFX" this setting holds the hex encoded PFX file data. If ExportFormat is set to any other value this holds the raw certificate content (not encoded).

ExportFormat:   The format of the exported certificate.

By default when ExportCertificate is called the certificate will be written as a PFX file. The format of the exported certificate may be changed by setting ExportFormat to one of the following values:

"PFX" or "PKCS12" (default) A PFX file (PKCS12).
"PEM" or "PKCS1" A PEM formatted PKCS1 private key file. Example:
-----BEGIN RSA PRIVATE KEY-----
MIICWwIBAAKBgQD5/STHUd7YkN1JyoyYnUvCf+Fyx1+ZleBJxvwDcm3yaZ98bvry
...
91y8ydb3mQ9l1hZudo2sj8tHnvEgph0r7B8hMM6Qaw==
-----END RSA PRIVATE KEY-----
"PKCS8" A PEM formatted PKCS8 private key file. Example:
-----BEGIN PRIVATE KEY-----
MIICdQIBADANBgkqhkiG9w0BAQEFAASCAl8wggJbAgEAAoGBAPn9JMdR3tiQ3UnK
...
HSvsHyEwzpBr
-----END PRIVATE KEY-----
"OpenSSHPrivateKey" An OpenSSH private key file. Example:
-----BEGIN OPENSSH PRIVATE KEY-----
b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAlwAAAAdzc2gtcnNh
...
AwQFBgcICQo=
-----END OPENSSH PRIVATE KEY-----
"PPK" A PuTTY private key file. Example:
PuTTY-User-Key-File-2: ssh-rsa
Encryption: none
Comment: rsa-key-20180822
Public-Lines: 4
AAAAB3NzaC1yc2EAAAADAQABAAAAgQCmz5j5kWUKxfwiv6J0LQ4wN9ekpeORXVaP
...
8pSSWejQ5Q==
Private-Lines: 8
AAAAgH87Sp/YcSw1dKoAZuWb0/2dKkKwMRIYEkS15caRpzAteay6WWX7l1sgBTU7
...
Oa0=
Private-MAC: d53e24f44bde8d1d3844a142fbb1fa7c88ea3585
"JWK"A JWK that contains a private key.

Note: On Linux/Unix the PFX/PKCS12 format is not supported. On Unix/Linux the default format is "PEM".

Note: ExportCertificate is not support on macOS.

ImportCertAction:   Specified the action to take if a matching certificate or a link to a matching certificate already exists.

When calling ImportCertificate if a matching certificate or a link to a matching certificate already exists in the Windows certificate store this setting governs what action will be taken. Possible values are:

1CERT_STORE_ADD_NEW - Imports a certificate only if no existing certificate is present.
2CERT_STORE_ADD_USE_EXISTING - If an existing certificate is found, it is not replaced.
3 (default)CERT_STORE_ADD_REPLACE_EXISTING - If an existing certificate is found it is replaced.
4CERT_STORE_ADD_ALWAYS - No checks are performed and a new certificate is always added to the store. This can result in duplicates.
5CERT_STORE_ADD_REPLACE_EXISTING_INHERIT_PROPERTIES - If an existing certificate is found it is replaced, and the new certificate inherits properties from the certificate it replaces.
6CERT_STORE_ADD_NEWER - Imports a certificate only if the certificate is newer than an existing matching certificate.
7CERT_STORE_ADD_NEWER_INHERIT_PROPERTIES - Imports a certificate only if the certificate is newer than an existing matching certificate, and inherits the properties of old certificate it replaces.

ImportCertStoreType:   The type of certificate store being specified for import.

When calling ImportCertificate, this value controls the type of the certificate store being specified in the first parameter.

This config can take one of the following values:

2 (cstPFXFile)The certificate store is the name of a PFX (PKCS12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or base64-encoded) representing a certificate store in PFX (PKCS12) format.
6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or base64-encoded) that contains an SSH-style public key.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.

Note that this functionality is currently for Windows platforms only.

JWKAlgorithm:   The JWK algorithm.

This setting specifies the JWK algorithm. It can be set before calling ExportCertificate (if ExportFormat is set to JWK) or SaveCertificate (if CertificateOutputFormat is set to JWK) to control the key Id used to create the JWK. It will be populated if a JWK-formatted is loaded into the class.

Valid values are:

  • (empty string)
  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
  • EC256
  • EC384
  • EC512

JWKKeyId:   The JWK key Id.

This setting specifies the JWK key Id. It can be set before calling ExportCertificate (if ExportFormat is set to JWK) or SaveCertificate (if CertificateOutputFormat is set to JWK) to control the key Id used to create the JWK. It will be populated if a JWK-formatted is loaded into the class.

JWKKeyOps:   The JWK intended key operations list.

This setting specifies the intended key operations for the JWK. It can be set before calling ExportCertificate (if ExportFormat is set to JWK) or SaveCertificate (if CertificateOutputFormat is set to JWK) to control the key Id used to create the JWK. It will be populated if a JWK-formatted is loaded into the class.

This setting format is a JSON array. Examples: ["sign","verify"] or ["encrypt"].

JWKUse:   The JWK use parameter value.

This setting specifies the JWK key Id. It can be set before calling ExportCertificate (if ExportFormat is set to JWK) or SaveCertificate (if CertificateOutputFormat is set to JWK) to control the key Id used to create the JWK. It will be populated if a JWK-formatted is loaded into the class.

Valid values are enc and sig.

KeyFormat:   How the public and private key are formatted.

This setting controls the format of CertPublicKey and CertPrivateKey. By default these properties hold PEM formatted public and private key data. When set to 1 (XML) the keys are stored in a XML format. This only affects the values returned by the class; the actual keys remain the same regardless of this setting. Possible values are:

  • 0 (PEM - default)
  • 1 (XML)
The default value is 0 (PEM).
ReplaceKey:   Whether or not to replace an existing key when creating a new key.

If this is false (default), the component will throw an error if a duplicate key exists while generating a new keyset using CreateKey. If set to true, the component will replace a key if it already exists when generating new keys.

RequestSubjectAltNames:   Subject Alternative Names for a Certificate Signing Request.

This allows Subject Alternative Names to be added to a Certificate Signing request. The setting only supports email, DNS, URI, and IPv4 addresses. Separate alternative names should be separated by commas. For example:


string altNames = "email:copy,dns:domain.com,dns.1:other.domain.com,uri:http://www.domain.com,ip:192.168.1.102"

SavedCert:   The saved certificate file.

This setting holds the certificate data that is saved when SaveCertificate is called with an empty FileName parameter. If CertificateOutputFormat is set to "P7B" this setting holds the hex encoded P7B file data. If CertificateOutputFormat is set to any other value this holds the raw certificate content (not encoded).

Base Configuration Settings

SelectWaitMillis:   The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.

If there are no events to process when DoEvents is called, the class will wait for the amount of time specified here before returning. The default value is 20.

CodePage:   The system code page used for Unicode to Multibyte translations.

The default code page is the Active Code Page (0).

The following is a list of valid code page identifiers:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multlingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangeul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8

The following is a list of valid code page identifiers for Mac OS only:

IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

UseInternalSecurityAPI:   Tells the class whether or not to use the system security libraries or an internal implementation.

By default the class will use the system security libraries to perform cryptographic functions. Setting this to True tells the class to use the internal implementation instead of using the system's security API.

 
 
Copyright (c) 2019 /n software inc. - All rights reserved.
IP*Works! OpenPGP 2016 C++ Edition - Version 16.0 [Build 7239]