Back: CSharp Reference Implementation

Table of Contents


ConfigConsole.exe is a command line tool used to administer your .NET Direct Gateway. It invokes operations on the .NET Middle Tier Config Service.

You can execute commands in two ways:
  1. ConfigConsole command args
  2. Interactively:
  • Launch ConfigConsole.exe
  • type commands
Command names are case-insensitive.

Commands Summary

  • type commands for a full list
  • type commands [namePrefix] for a list of commands with this prefix
  • type help [commandName] for help
  • type search [text] for a list of command names containing given text

To display categories of commands:
  • commands anchor

  • commands cert
  • commands domain
  • commands address
  • commands dns

General Commands

COMMANDS

List the commands available
commands [nameprefix]

HELP

Show help

help ['all' | name]
  • all: All commands
  • name: This command name or names with this PREFIX

EXIT

Exit the application

QUIT

Exit the application

SEARCH

Search for commands matching the given wildcard pattern
search pattern
  • pattern: (optional) pattern, containing '*' wildcards

BATCH

Run a series of commands from a file
Each command is on its own line. Comments begin with //
batch filepath [echo command (default true)]

ECHO

Echo the args to the console

Anchor Management

ANCHOR_ADD

Import an anchor certificate from a file and push it into the config store. The anchor is used for both incoming & outgoing trust.

anchor_add owner options
  • owner: the domain or email address that trusts this anchor.
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

ANCHOR_ENSURE

Import an anchor certificate from a file and push it into the config store. The anchor is used for both incoming & outgoing trust.

anchor_ensure owner options
  • owner: the domain or email address that trusts this anchor.
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

ANCHORS_GET

Get all anchors for an owner.

anchors_get owner [options]
  • owner: The domain or email address whose trusted anchors should be retrieved
  • options: [certData] [privatekey] [status]
    • certData: (True/False) Fetch actual certificate data.
    • privateKey: (True/False) Include private key
    • status: New | Enabled | Disabled
      • Only retrieve anchors with this status

ANCHOR_REMOVE

Remove anchors with given ID. To get the anchorID, use the anchors_get command.

anchor_remove anchorID

ANCHOR_ADD_MACHINE

Import an anchor certificate from a file and push it into the Windows LocalMachine certificate store. The anchor is used for both incoming & outgoing trust.

anchor_add_machine options
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

ANCHOR_RESOLVE

Resolves anchors that will apply for a emailaddress- like the Smtp Gateway would.
anchor_resolve owner [options]
  • owner: email address
  • options: [certData] [privatekey] [status]
    • certData: (True/False) Fetch certificate data
    • privateKey: (True/False) Include private key
    • status: New | Enabled | Disabled

ANCHOR_STATUS_SET

Set the status for ALL anchors for an owner.
anchor_status_set owner status
  • owner: Anchor owner
  • status: New | Enabled | Disabled

ANCHORS_LIST

List all anchors

anchors_list [options]
  • options: [certData] [privatekey] [status]
    • certData: (True/False) Fetch certificate data
    • privateKey: (True/False) Include private key
    • status: New | Enabled | Disabled (list anchors in this status)

Certificate Management

CERTIFICATE_ADD

Import a certificate from a file and push it into the config system.

certificate_add filePath [options]
  • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
  • options
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

CERTIFICATE_ENSURE

Import a certificate from a file and push it into the config system.

certificate_ensure filePath [options]
  • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
  • options
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

CERTIFICATE_ADD_MACHINE

Import a certificate from a file and push it into the named local Machine store.

certificate_add_machine storeName options
  • storeName: (Private | Public)
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

CERTIFICATE_ENSURE_MACHINE

Import a certificate from a file and push it into the named local Machine store.

certificate_ensure_machine storeName options
  • storeName: (Private | Public)
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

CERTIFICATE_GET

Retrieve all certificates for the domain or email address that owns this certificate.

certificate_get owner [options]
  • owner: The domain or email address that owns this certificate
  • options: [certData] [privatekey] [status]
    • certData: (True/False) Fetch certificate data
    • privateKey: (True/False) Include private key
    • status: New | Enabled | Disabled

CERTIFICATE_DNSRESOLVE

Resolve certificates for an address or domain from Dns
certificate_dnsresolve domain | email [server]
  • server : (optional) - resolve using this Dns Server

CERTIFICATE_RESOLVE

Resolves certificates for an email address - like the Smtp Gateway would. Returns the certificates that apply.
certificate_resolve emailAddress [options]
  • emailaddress: Certificate owner
  • options: [certData] [privatekey] [status]
    • certData: (True/False) Fetch certificate data
    • privateKey: (True/False) Include private key
    • status: New | Enabled | Disabled

CERTIFICATE_REMOVE

Remove certificate with given ID
certificate_remove certificateID

CERTIFICATE_STATUS_SET

Set the status for ALL certificates for an owner (domain or email address).
certificate_status_set owner status
  • owner: Certificate owner
  • status: New | Enabled | Disabled

CERTIFICATE_EXPORT

Export certificates for an owner in BIND Zone file format - CERT Record
certificate_export owner [outputFile]
  • owner: certificate owner (domain or email address)
  • outputFile: (Optional) Export to file. Else write to Console

CERTIFICATE_EXPORT_ALL

Export all Enabled public certificates in BIND zone file format. You can place this output directly into your zone file.

certificate_export_all [outputFile] [chunkSize]
  • outputFile: (Optional) Export to file. Else write to Console
  • chunkSize: (Optional) Enumeration size. Default is 25

CERTIFICATE_EXPORT_FROMFILE

Exports public certificates in given PFX/DER file or folder in BIND zone file format - CERT Record

certificate_export_fromfile fileName | folderPath [outputFile]
  • fileName or folderPath: If file, exports file. If folder, exports all certificates in folder
  • outputFile: (optional) Export to this file. Else write to Console

CERTIFICATE_EXPORT_MACHINE

Exports public certificates for all certs in the given Windows certificate store in BIND zone file format - CERT Record

certificate_export_machine [storeName] [outputFile]
  • storeName: (optional) Default is NHINDPrivate.
  • outputFile: (optional) Export to file. Else write to Console

Domain Management


DOMAIN_ADD

Add a new domain.

domain_add domainName [status] [agentName]
  • domainName: New domain name
  • status: New | Enabled | Disabled
  • agentName: Domain grouping identifier (v1.1)

DOMAIN_LIST

List all domains

DOMAIN_GET

Retrieve information for an existing domain.

domain_get domainName

DOMAIN_REMOVE

Remove a domain.

domain_remove domainName

DOMAIN_STATUS_SET

Change a domain's status

domain_status_set domainName status
  • domainName: Set status for this domain
  • status: New | Enabled | Disabled

DOMAIN_ADDRESS_STATUS_SET

Set the status of all addresses in this domain

domain_address_set domainName status
  • domainName: Set status for this domain
  • status: New | Enabled | Disabled

DOMAIN_COUNT

Retrieve # of domains.

DOMAIN_AGENT_SET (v1.1)

Change a domain's agent name

domain_agent_set domainName agentName
  • domainName: Set agent name for this domain
  • agentName: Optional domain grouping identifier


Address Management

ADDRESS_ADD

Add a new email address. The address domain must already exist.

address_add emailAddress [addressType] [displayName]
  • emailAddress: valid email address. Verifies that the domain already exists.
  • addressType: (optional) such as XDR. Used for routing. default:SMTP
  • displayName: (optional)

ADDRESS_GET

Retrieve an existing address.

address_get emailAddress

ADDRESS_STATUS_SET

Set the status of an address

address_status_set emailAddress status
  • emailAddress: set the status of this address
  • status: New | Enabled | Disabled

ADDRESS_REMOVE

Remove an existing address.

address_remove emailAddress

ADDRESS_LIST

List addresses for a domain.

address_list domainName [chunkSize]
  • domainName: list addresses for this domain
  • chunkSize: (optional) Number of addresses to download from service at a time. Default is 25

ADDRESS_LISTALL

List all addresses.

address_listall [chunkSize]
  • chunkSize: Number of addresses to download from service at a time.

ADDRESS_DISPLAYNAME_SET

Set the display name for the given address

address_displayname_set emailAddress displayname
  • emailAddress: existing email address.
  • displayname: new display name.

Dns Record Management

Supported Record Types:
  • MX
  • ANAME
  • NS
  • CNAME
  • SOA
  • CERT
  • SRV

You use the following commands to manage all records EXCEPT CERT.

You manage CERT records using Certificate Management commands (see above).

The Dns Server automatically serves up installed X509 Certificates.

DNS_MATCH

Resolve ALL Dns records Registered in the Config System for the given domain.

dns_match domain

Note: this does not actually go to a DNS server, but instead calls the Config System middle tier.

DNS_MX_ADD

Add a new MX dns record.

dns_mx_add domainname exchange [ttl] [preference] [notes]
  • domainname: domain name for the record
  • exchange: smtp domain name for the record
  • [ttl]: time to live in seconds
  • [preference]: short value indicating preference of the record. Default 10
  • [notes]: description for the record

DNS_MX_ENSURE

Adds a new MX dns record if an identical one does't already exist.

dns_mx_ensure domainname exchange [ttl] [preference] [notes]
  • domainname: domain name for the record
  • exchange: smtp domain name for the record
  • [ttl]: time to live in seconds
  • [preference]: short value indicating preference of the record. Default 10
  • [notes]: description for the record

DNS_ANAME_ADD

Add a new ANAME dns record.

dns_aname_add domainname ipaddress [ttl] [notes]
  • domainname: domain name for the record
  • ipaddress: IP address in dot notation
  • [ttl]: time to live in seconds, 32bit int
  • [notes]: description for the record

DNS_ANAME_ENSURE

Add a new ANAME dns record if an identical one does not exist.

dns_aname_ensure domainname ipaddress ttl [notes]
  • domainname: domain name for the record
  • ipaddress: IP address in dot notation
  • ttl: time to live in seconds, 32bit int
  • [notes]: description for the record

DNS_NS_ADD

Add a new NS dns record.

dns_ns_add domainname nameserver ttl [notes]
  • domainname: domain name for the record
  • nameserver: nameserver
  • ttl: time to live in seconds
  • [notes]: description for the record

DNS_NS_ENSURE

Add a new NS dns record if an identical one does not exist.

dns_ns_ensure domainname nameserver ttl [notes]
  • domainname: domain name for the record
  • nameserver: nameserver
  • ttl: time to live in seconds
  • [notes]: description for the record

DNS_CNAME_ADD

Add a new NS dns record.

dns_cname_add domainname cname ttl [notes]
  • domainname: domain name for the record
  • cname: alias for this domain
  • ttl: time to live in seconds
  • [notes]: description for the record

DNS_CNAME_ENSURE

Add a new CNAME dns record if an identical one does not exist.

dns_cname_ensure domainname cname ttl [notes]
  • domainname: domain name for the record
  • cname: alias for this domain
  • ttl: time to live in seconds
  • [notes]: description for the record

DNS_SOA_ADD

Add a new SOA dns record.

dns_soa_add domainname primarysourcedomain responsibleemail serialnumber ttl [refresh] [retry] [expire] [minimum] [notes]
  • domainname: The domain name of the name server that was the primary source for this zone
  • responsibleemail: Email mailbox of the hostmaster
  • serialnumber: Version number of the original copy of the zone.
  • ttl: time to live in seconds, 32bit int
  • [refresh]: Number of seconds before the zone should be refreshed. Default is 10800 seconds
  • [retry]: Number of seconds before failed refresh should be retried. Default is 3600 seconds
  • [expire]: Number of seconds before records should be expired if not refreshed. Default is 86400 seconds
  • [minimum]: Minimum TTL for this zone. Default is 10800 seconds
  • [notes]: description for the record

DNS_SOA_ENSURE

Add a new SOA dns record if an identical one does not exist.

dns_soa_add domainname primarysourcedomain responsibleemail serialnumber ttl [refresh] [retry] [expire] [minimum] [notes]
  • domainname: The domain name of the name server that was the primary source for this zone
  • responsibleemail: Email mailbox of the hostmaster
  • serialnumber: Version number of the original copy of the zone.
  • ttl: time to live in seconds, 32bit int
  • [refresh]: Number of seconds before the zone should be refreshed. Default is 10800 seconds
  • [retry]: Number of seconds before failed refresh should be retried. Default is 3600 seconds
  • [expire]: Number of seconds before records should be expired if not refreshed. Default is 86400 seconds
  • [minimum]: Minimum TTL for this zone. Default is 10800 seconds
  • [notes]: description for the record

DNS_SRV_ADD

Add a new SRV resource dns record.

domainname weight port target [priority] [ttl] [notes]
  • domainname: The domain this RR refers to. RFC2782
  • weight: A server selection mechanism. RFC2782
  • port: The port on this target host of this service. RFC2782
  • target: The domain name of the target host. RFC2782
  • [priority]: The priority of this target host. RFC2782
  • [ttl]: time to live in seconds, 32bit int
  • [notes]: description for the record

DNS_RECORD_REMOVE

Remove an existing record by its ID.

dns_record_remove recordid
recordid: record id to be removed from the database

To get the record id, use any of the dns_match* commands.

DNS_MX_MATCH

Resolve MX records for the given domain

dns_mx_match domain

DNS_ANAME_MATCH

Resolve Address records for the given domain

dns_aname_match domain

DNS_NS_MATCH

Resolve NS records for the given domain

dns_ns_match domain

DNS_CNAME_MATCH

Resolve CNAME records for the given domain

dns_cname_match domain

DNS_SOA_MATCH

Resolve SOA records for the given domain

dns_soa_match domain

DNS_SRV_MATCH

Resolve SRV records for the given domain

dns_srv_match domain

DNS_MX_GET

Gets an existing MX record by ID.

dns_mx_get recordid
  • recordid: record id to be retrieved from the database

DNS_ANAME_GET

Gets an existing ANAME record by ID.

dns_aname_get recordid
  • recordid: record id to be retrieved from the database

DNS_CNAME_GET

Gets an existing CName record by ID.

dns_cname_get recordid
  • recordid: record id to be retrieved from the database

DNS_NS_GET

Gets an existing NS record by ID.

dns_ns_get recordid
  • recordid: record id to be retrieved from the database

DNS_SOA_GET

Gets an existing SOA record by ID.

dns_soa_get recordid
  • recordid: record id to be retrieved from the database

DNS_SRV_GET

Gets an existing SRV record by ID.

dns_srv_get recordid
  • recordid: record id to be retrieved from the database


Policy Management New in V1.3


See example policy setup for hosting single use certificates

POLICY_ADD

Import a certificate policy from a file and push it into the config store. Policies are associated to policy groups. Policy groups are linked to owners(domains or emails).
name filePath options
  • name: The name of the policy. Place the policy name in quotes ("") if there are spaces in the name.
  • filePath: path of the policy file. Typically named with a .dpol extension.
  • options:
    • description: (optional) additional description

POLICY_ENSURE

Import a certificate policy from a file and push it into the config store - if not already there.
Policies are associated to policy groups. Policy groups are linked to owners(domains or emails).
name filePath options
  • name: The name of the policy
  • filePath: path of the policy file. Typically named with a .dpol extension.
  • options:
    • description: (optional) additional description

POLICY_ADDTOGROUP

Adds an existing policy to a group with a provided usage.
policyName groupNames policyUse incoming outgoing
  • policyName: Name of the policy to add to the group. Place the policy name in quotes (") if there are spaces in the name.
  • groupName: Name of the policy group to add the policy to. Place the policy group name in quotes (") if there are spaces in the name.
  • policyUse: Usage name of the policy in the group. Must be one of the following values: TRUST, PRIVATE_RESOLVER, PUBLIC_RESOLVER.
  • forIncoming: Indicates if policy is used for incoming messages. Defaults to true
  • forOutgoing: Indicates if policy is used for outgoing messages. Defaults to true

POLICY_ENSURETOGROUP

Adds an existing policy to a group with a provided usage - if not already there.
policyName groupNames policyUse incoming outgoing
  • policyName: Name of the policy to add to the group. Place the policy name in quotes (") if there are spaces in the name.
  • groupName: Name of the policy group to add the policy to. Place the policy group name in quotes (") if there are spaces in the name.
  • policyUse: Usage name of the policy in the group. Must be one of the following values: TRUST, PRIVATE_RESOLVER, PUBLIC_RESOLVER.
  • forIncoming: Indicates if policy is used for incoming messages. Defaults to true
  • forOutgoing: Indicates if policy is used for outgoing messages. Defaults to true

POLICY_DELETE

Delete policy from system by policy name.
  • policyName: Name of the policy. Place the policy name in quotes ("") if there are spaces in the name.

POLICY_DELETEFROMGROUP

Delete policy from a policy group .mapId
  • mapId: Id that associates a group to a policy usage.

POLICY_GET

Retrieve information for an existing certificate policy by name.
name
  • name: Name of the policy. Place the policy name in quotes ("") if there are spaces in the name.

POLICYGROUP_ADD

Create a certificate policy group.notes: Use CertPolicy_AddToGroup to join policies to groups and assign usage. Use CertPolicy_AddToOwner to join groups to Domains or emailsname options
  • name: Name of the policy group. Place the policy group name in quotes ("") if there are spaces in the name.
  • options:
    • description: (optional) additional description

POLICYGROUP_ENSURE

Create a certificate policy group - if not already there.notes: Use CertPolicy_AddToGroup to join policies to groups and assign usage. Use CertPolicy_AddToOwner to join groups to Domains or emailsname options
  • name: Name of the policy group. Place the policy group name in quotes ("") if there are spaces in the name.
  • options:
    • description: (optional) additional description

POLICYGROUP_ADDOWNER

Adds an existing policy group to an existing owner.groupName owner
  • groupName: Name of the policy group. Place the policy group name in quotes (") if there are spaces in the name.
  • owner: Name of the owner to associate with groupName.

POLICYGROUP_ENSUREOWNER

Adds an existing policy group to an existing owner - if not already there.groupName owner
  • groupName: Name of the policy group. Place the policy group name in quotes (") if there are spaces in the name.
  • owner: Name of the owner to associate with groupName.

POLICYGROUP_DELETE

Delete policy group from system by group name.
groupName
  • groupName: Name of the policy group. Place the group name in quotes ("") if there are spaces in the name.

POLICYGROUP_DELETEFROMOWNER

Deletes an existing policy group from a owner.
groupName, ownerName
  • groupId: Name of the policy group to delete from the owner. Place the policy group name in quotes ("") if there are spaces in the name.
  • ownerName: Name of the owner to delete the policy group from.

POLICYGROUP_GET

Retrieve information for an existing certificate policy group by name.name
  • name: The name of the policy. Place the policy name in quotes ("") if there are spaces in the name.

POLICYGROUP_OWNERSLIST

List owners associated with in a policy group.groupName
  • groupName: Name of the policy group to search on. Place the policy group name in quotes (") if there are spaces in the name.

POLICYGROUPS_COUNT

Retrieve # of certificate policy groups.

POLICYGROUPS_LIST

List all policy groups

POLICYUSAGE_LIST

List policies and their usage with in a policy group.
  • groupName: Name of the policy group to search on. Place the policy group name in quotes (") if there are spaces in the name.

POLICY_UPDATE

Import a certificate policy from a file and update an existing policy. Policies are associated to policy groups. Policy groups are linked to owners(domains or emails).
  • name
  • filePath
  • options
    • description: (optional) additional description


PKCS#11 Hardware Management New in V1.3

PKCS11_CREATE_CSR

Create certificate signing request. CN of distinguishedName will typically be the same as directDomain
directDomain distinguishedName [defaultBits] [out]
  • directDomain: New direct domain name. Will be the SubjectAlt name in format DNS:{directDomain}
  • distinguishedName: X500DistinguishedName
    • Example distinguisedName: "CN=hsm.DirectInt.lab, OU=DirectInt.Lab, O=Surescripts, C=US"
  • defaultBits: Default key length is 2048 bits
out: folder path.

PKCS11_ADD_CERT

Import a certificate from a file and push it into the store.
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

PKCS11_DELETE_BYID

Remove certificate by Id (CKA_ID)
  • certificateID: The id is found using PKCS11_LISTKEY_ALL or PKCS11_SEARCH_BYOWNER

PKCS11_EXPORTPKCS8KEY_PFX

This command does not interact with the hardware token. It is not used for any FHA activities.
Import a p12 (.pfx) certificate from a file.
Extract the private key to pkcs#8 format.
  • options:
    • filePath: path fo the certificate file. Can be .DER, .CER or .PFX
    • password: (optional) file password. Enter 'null' if no password.
    • status: (optional) New | Enabled | Disabled

PKCS11_LISTKEY_ALL

List all keys
  • [chunkSize]
    • chunkSize: (Optional) Enumeration size. Default is 25

PKCS11_SEARCH_BYOWNER

Search for a certificate by email or domain owner
Case sensitive search
owner
  • owner name: Should be the same as the value of the certificate subjecAlt name.