|
|
pki:create-template(
|
|
$name as xs:string,
|
|
$description as xs:string,
|
|
$key-type as xs:string?,
|
|
$key-options as element()?,
|
|
$csr as element(x509:req)
|
| ) as element(pki:template) |
|
|
|
Summary:
This function creates a new X.509 certificate request template. Each time
a new certificate request is generated, a new public/private key pair is
generated. A new random ID is generated and returned as part of the
element. This ID is used for identifying this template and its related
key pairs and certificates. The returned element must be separately
inserted into the database with pki:insert-template.
|
Parameters:
|
$name
:
The name of the certificate request template.
|
|
$description
:
A description of the certificate request template.
|
|
$key-type
:
The type of key to use (enter "rsa").
|
|
$key-options
:
The options for generating new keys. The valid options are
key-length, which
specifies the number of bits in a key (512, 1024, 2048, 4096), and
pass-phrase, which specifies the pass phrase for
encrypting/decrypting a private key.
|
|
$csr
:
An XML representation of the certificate request template.
|
|
Example:
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
declare namespace x509 = "http://marklogic.com/xdmp/x509";
declare namespace ssl = "http://marklogic.com/xdmp/ssl";
let $x509 :=
<x509:req>
<x509:version>2</x509:version>
<x509:subject>
<x509:countryName>US</x509:countryName>
<x509:stateOrProvinceName>CA</x509:stateOrProvinceName>
<x509:localityName>San Carlos</x509:localityName>
<x509:organizationName>Mark Logic</x509:organizationName>
<x509:organizationalUnitName>Engineering</x509:organizationalUnitName>
<x509:commonName>my.host.com</x509:commonName>
<x509:emailAddress>user@marklogic.com</x509:emailAddress>
</x509:subject>
<x509:v3ext>
<x509:basicConstraints critical="false">CA:TRUE</x509:basicConstraints>
<x509:keyUsage critical="false">Certificate Sign, CRL Sign</x509:keyUsage>
<x509:nsCertType critical="false">SSL Server</x509:nsCertType>
<x509:subjectKeyIdentifier critical="false">B2:2C:0C:F8:5E:A7:44:B7</x509:subjectKeyIdentifier>
</x509:v3ext>
</x509:req>
let $options :=
<pki:key-options xmlns="ssl:options">
<key-length>2048</key-length>
</pki:key-options>
return pki:create-template(
"testTemplate",
"Creating a new template",
"rsa",
$options,
$x509)
(: Creates a new certificate template, named "testTemplate." :)
|
|
|
|
pki:generate-certificate-request(
|
|
$template-id as xs:unsignedLong,
|
|
$common-name as xs:string,
|
|
$dns-name as xs:string?,
|
|
$ip-addr as xs:string?
|
| ) as xs:string |
|
|
Summary:
This function generates a PEM encoded X.509 certificate request from the template
for the specified id. If $dns-name or $ip-addr are specified,
those values will override any values specified in the template. A new public/private
key pair is generated for the request and inserted as a temporary document in the
database. When the signed certificate is inserted later, it is matched up against
this document and any previously in use private key / certificate is replaced with
the new one.
The Admin UI will only set common-name, and leave both dns-name and ip-addr
unspecified. Control over these values is provided only for power users to
use through custom administration scripts.
|
Parameters:
|
$template-id
:
The certificate template id for which to generate the certificate request.
|
|
$common-name
:
The common name to put into the template.
|
|
$dns-name
:
The DNS name, if any, to substitute into the template.
|
|
$ip-addr
:
The IP address, if any, to substitute into the template.
|
|
Example:
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
let $tid := pki:get-template-ids()[1]
return
pki:generate-certificate-request($tid, (), "marklogic.com", "127.0.0.1")
=>
-----BEGIN CERTIFICATE REQUEST-----
MIIByDCCATECAQIwRDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAkNBMRMwEQYDVQQH
EwpTYW4gQ2FybG9zMRMwEQYDVQQKEwpNYXJrIExvZ2ljMIGfMA0GCSqGSIb3DQEB
AQUAA4GNADCBiQKBgQC6g8iGk1cgO4fFc+3f9kncQ/jEZLlTQESeKTfzglKL7YjS
Eb85EjrND9MMnj/fEPxgRnoD6nfmiG54/xnj9A/0SnjtN1EVKb0XZaa6wh9KN8b4
jzlPPYzJ0sLkwBtesrCW3So4gdBYC+xExjDWzdILVj78wzaDMNA4lm9wR2oMHQID
AQABoEQwQgYJKoZIhvcNAQkOMTUwMzARBglghkgBhvhCAQEEBAMCBkAwHgYDVR0R
BBcwFYINbWFya2xvZ2ljLmNvbYcEfwAAATANBgkqhkiG9w0BAQUFAAOBgQCwey7j
JXYsGBf+D4YADIC9Qtcx7Y528S3XDlnhsySA7U9+bILoV55OdSwswL194faIkBGD
uG77BNsbtf332rmWit8AQPfTQF50agDYwZoall3OeVUp1b5ZPemC/9kp20PgsIOG
jcxcxla0ZCvzdid4gB+1NfP5mnNrCLhMHsJ1IQ==
-----END CERTIFICATE REQUEST-----
|
|
|
|
pki:generate-temporary-certificate(
|
|
$template-id as xs:unsignedLong,
|
|
$valid-for as xs:unsignedInt,
|
|
$common-name as xs:string,
|
|
$dns-name as xs:string?,
|
|
$ip-addr as xs:string?
|
| ) as empty-sequence() |
|
|
|
Summary:
This function generates a new key pair and temporary certificate from the specified
certificate template. If $dns-name or $ip-addr are specified,
those portions of the template are replaced with the specified values. The certificate
is inserted into the database. This is used to ensure that secure app servers are
initially usable while waiting for signed certificates.
|
Parameters:
|
$template-id
:
The certificate template id to use for the creating the certificate.
|
|
$valid-for
:
The number of days the certificate should be valid for
|
|
$common-name
:
The common name to put into the template
|
|
$dns-name
:
The DNS name, if any, to substitute into the template.
|
|
$ip-addr
:
The IP address, if any, to substitute into the template
|
|
Example:
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
let $tid := pki:template-get-id(pki:get-template-by-name("test"))
return
pki:generate-temporary-certificate($tid, 150, "My.Host.com", (), ())
(: Generates a temporary certificate from the "test" template. :)
|
|
|
|
pki:generate-temporary-certificate-if-necessary(
|
|
$template-id as xs:unsignedLong,
|
|
$valid-for as xs:unsignedInt,
|
|
$common-name as xs:string,
|
|
$dns-name as xs:string?,
|
|
$ip-addr as xs:string?
|
| ) as empty-sequence() |
|
|
|
Summary:
This function generates a new key pair and temporary certificate
from the specified certificate template. If a temporary certificate
already exists for the template, this function does nothing. If
$dns-name or $ip-addr are specified,
those portions of the template are replaced with the specified
values. The certificate is inserted into the database. This is used
to ensure that secure app servers are initially usable while waiting
for signed certificates.
|
Parameters:
|
$template-id
:
The certificate template id to use for the creating the certificate.
|
|
$valid-for
:
The number of days the certificate should be valid for
|
|
$common-name
:
The common name to put into the template.
|
|
$dns-name
:
The DNS name, if any, to substitute into the template.
|
|
$ip-addr
:
The IP address, if any, to substitute into the template
|
|
Example:
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
let $tid := pki:template-get-id(pki:get-template-by-name("test"))
return
pki:generate-temporary-certificate-if-necessary($tid, 150, "My.Host.com", (), ())
(: Generates a temporary certificate, if one does not already exist for the template :)
|
|
|
|
pki:insert-certificate-revocation-list(
|
|
$url as xs:string,
|
|
$crl as item()
|
| ) as empty-sequence() |
|
|
Summary:
This function inserts a PEM- or DER-encoded Certificate Revocation List
(CRL) into the security database. A CRL is a list of certificate serial numbers
that have been revoked, and the revocation date of each. The CRL is signed by
the Certificate Authority to verify its accuracy.
The CRL contains two dates, one indicating when it was published and the other
indicating when it will next be published. This is useful in determining whether a
newer CRL should be fetched.
Certificate Authorities typically allow the CRL to be downloaded via HTTP.
The document
URL in the database is derived from the URL passed in to the function, so Inserting a
newer CRL retrieved from the same URL will replace the previous one in the database.
|
Parameters:
|
$url
:
The URL from which the CRL was downloaded.
|
|
$crl
:
The PEM- or DER-encoded CRL.
|
|
Example:
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
let $URI := "http://crl.verisign.com/pca3.crl"
return
pki:insert-certificate-revocation-list(
$URI,
xdmp:document-get($URI)/binary() )
(: Inserts a CRL from Verisign into the database. :)
|
|
|
|
pki:need-certificate(
|
|
$template-id as xs:unsignedLong,
|
|
$common-name as xs:string,
|
|
$dns-name as xs:string?,
|
|
$ip-addr as xs:string?
|
| ) as xs:boolean |
|
|
|
Summary:
This function returns true if the certificate specified by the template id and host
combination are not signed by a trusted certificate authority. Otherwise, false is
returned. The common name must be specified. The DNS name and IP address
are optional.
|
Parameters:
|
$template-id
:
The certificate template id for the certificate.
|
|
$common-name
:
The common hostname (e.g., myhost.company.com
or company.com) in the certificate.
|
|
$dns-name
:
The DNS name in the certificate.
|
|
$ip-addr
:
The IP address name in the certificate.
|
|
Example:
(: execute this against the security database :)
xquery version "1.0-ml";
import module namespace pki = "http://marklogic.com/xdmp/pki"
at "/MarkLogic/pki.xqy";
import module namespace admin = "http://marklogic.com/xdmp/admin"
at "/MarkLogic/admin.xqy";
"The certificates for the following templates are unsigned:", "",
let $config := admin:get-configuration()
let $hostname := admin:host-get-name(
$config,
admin:host-get-id($config, xdmp:host-name()))
for $tid in pki:get-template-ids()
return if (pki:need-certificate($tid, $hostname, (), ()))
then pki:template-get-name(pki:get-template($tid))
else ()
(: Returns the list templates for which there are unsigned certificates. :)
|
|
|