Moonshot ships with a tool, moonshot-webp, to securely and correctly provision credentials onto clients. A basic template is provided at
/usr/share/moonshot-ui/default-identity.msht. The format for credential files is simple XML:
<?xml version="1.0" encoding="UTF-8"?> <identities> <identity> <display-name>[i.e. John Smith from Camford University]</display-name> <user>[i.e. johnsmith]</user> <password>[i.e. correct-horse-battery-staple]</password> <realm>[i.e. camford.ac.uk]</realm> <services>[optional, see Services]</services> <selection-rules>[optional, see Selection Rules]</selection-rules> <trust-anchor> <!-- Either ca-cert and subject, or ca-cert and subject-alt --> <ca-cert>[Base64-encoded representation of the APC/IdP's CA root certificate, see Trust Anchors]</ca-cert> <subject>[CN value of the APC/IdP's server certificate, see Trust Anchors]</subject> <subject-alt>[The DNS/FQDN or IP value in the X509v3 extension of the APC/IdP's server certificate, see Trust Anchors]</subject-alt> <!-- Or, alternatively, server-cert only --> <server-cert>[SHA-256 hash of the APC/IdP's server certificate, see Trust Anchors]</server-cert> </trust-anchor> </identity> </identities>
Inclusion of the trust anchor is vital - without it credentials may be exposed to malicious resource providers. This credential format is also used to secure communication between RP's, IdP's and trust routers.
You must use either the Certificate Authority (CA) root certificate or the server certificate as trust anchor.
We recommend that a CA certificate is generated with a long expiry time (in years or decades), and that it is kept safe for subsequent server and user certificate generation cycles.
To use the CA root certificate as a trust anchor, you must populate the one or more of the following tags in the
<ca-cert>: The value of this tag is either a Base64-encoded version of the CA certificate in DER form, or the contents of
ca.pem, excluding the BEGIN and END lines.
<subject>: The value of this tag is the CN value of the DN in the text representation of the server certificate.
This value is required when
<subject-alt> is not specified.
<subject-alt>: The value of this should be the DNS name, FQDN or the IP address information in the X509v3 information of the server certificate.
<subject>is not specified.
To retrieve either the
subject-alt information, dump the server certificate's text information. Use OpenSSL as follows:
openssl x509 -noout -text -in server.pem
A sample output of the command would yield:
Certificate: Data: Version: 3 (0x2) Serial Number: 1 (0x1) Signature Algorithm: sha256WithRSAEncryption Issuer: C=FR, ST=Radius, L=Somewhere, O=Example Inc./emailAddressfirstname.lastname@example.org, CN=Example Certificate Authority Validity Not Before: Nov 14 16:22:19 2017 GMT Not After : Jan 13 16:22:19 2018 GMT Subject: C=FR, ST=Radius, O=Example Inc., CN=Example Server Certificate/emailAddressemail@example.com Subject Public Key Info: Public Key Algorithm: rsaEncryption Public-Key: (2048 bit) Modulus: [trimmed] Exponent: 65537 (0x10001) X509v3 extensions: X509v3 Subject Alternative Name: DNS:example.org, DNS:radius.example.org X509v3 Extended Key Usage: TLS Web Server Authentication X509v3 CRL Distribution Points: Full Name: URI:http://www.example.com/example_ca.crl Signature Algorithm: sha256WithRSAEncryption [trimmed]
subject value to specify would be:
C=FR/ST=Radius/O=Example Inc./CN=Example Server Certificate/emailAddressfirstname.lastname@example.org
subject-alt value to specify would be the value of the
X509v3 Subject Alternative Name value in the text:
|When your server certificate expires, the credentials must be updated and re-provisioned with the new fingerprint.|
To use the server certificate itself as a trust anchor, you must populate the <server-cert> tag in the <trust-anchor> section with the SHA-256 fingerprint of the server certificate.
To obtain this fingerprint, run OpenSSL as follows and strip the colon symbols from the resulting value:
openssl x509 -noout -fingerprint -sha256 -in server.pem
A sample output of the command would yield:
server-cert value to specify would be:
services section is used to determine which services the credential will be automatically used for - each service will be contained in its own tag. For use with a trust router, it is better to use the
selection-rules section instead.
<services> <service>xmpp/jabber.project-moonshot.org</service> <service>email/project-moonshot.org</service> <service>host/ssh.project-moonshot.org</service> </services>
selection-rules section is used to restrict which services the credential will be automatically used for - for use with a trust router identity, the service type is "trustidentity" for all services. Wildcards are acceptable.
<selection-rules> <rule> <pattern>trustidentity/*</pattern> <always-confirm>false</always-confirm> </rule> </selection-rules>