| XQUERY/XSLT API DOCUMENTATION 4.2 |
All XQuery & XSLT Functions MarkLogic Built-In Functions Admin (xdmp:) AppServer (xdmp:) Classifier (cts:) Debug (dbg:) Document Conversion (xdmp:) Extension (xdmp:) Documents, Directories, Properties, and Locks Functions Extension Functions Function Values Functions HTTP Functions JSON Functions MarkLogic Server Functions Search Functions XML Functions XQuery Context Functions XSLT Functions map (map:) Math (math:) Profile (prof:) Search (cts:) cts:query Constructors Functions Geospatial Functions Geospatial Lexicon Functions Lexicon Functions Search Functions Search Clustering Functions Security (xdmp:) Server Monitoring (xdmp:) Spell (spell:) Update (xdmp:) XQuery Library Modules Admin Library (admin:) Actions Functions Appserver Functions Database Functions Forest Functions Group Functions Host Functions Mimetypes Functions Scheduler Functions Alerting (alert:) Elastic Compute Cloud (ec2:) Entity Enrichment (entity:) Flexible Replication (flexrep:) Geospatial Supporting Functions GEO Functions GeoRSS Functions GML Functions KML Functions MCGM Functions Information Studio (info:) Information Studio Developer (infodev:) Library Services (dls:) cts:query Constructor Functions Document Management Functions Document Update Functions Retention Policy Functions XInclude Functions Modular Documents XInclude Functions XPointer Functions PKI (pki:) Plugin (plugin:) Search (search:) Security-sec (sec:) Spelling Dictionary Management (spell:) Thesaurus (thsr:) Triggers (trgr:) Triggers Library (trgr:) WordProcessingML (ooxml:) ZIP Package (ooxml:) CPF Functions Content Processing Framework (cpf:) CSS Conversion (css:) DocBook Conversion (dbk:) Domains (dom:) Excel Conversion (excel:) Generic Conversion (cvt:) Links (lnk:) MSWord Conversion (msword:) PDF Conversion (pdf:) Pipelines (p:) Powerpoint Conversion (ppt:) XHTML Conversion (xhtml:) W3C-Standard Functions Accessor (fn:) AnyURI (fn:) Boolean (fn:) Context (fn:) DurationDateTime (fn:) Error and Trace (fn:) Node (fn:) Numeric (fn:) QName (fn:) Sequence (fn:) String (fn:) XSLT (fn:) W3C XQuery/XSLT Reference W3C XQuery Functions W3C XQuery Language W3C XSLT Language
This page was generated September 12, 2012 6:02 AM | XQuery & XSLT Built-In & Modules Function Reference
Module: PKI
The PKI library manages public key infrastructure state in the security database. All functions require that the caller have either a read or a write PKI execute privilege (http://marklogic.com/xdmp/privileges/pki-read, http://marklogic.com/xdmp/privileges/pki-write). All documents are in the PKI collection (http://marklogic.com/xdmp/pki). All of these functions automatically invoke against the appropriate security database, and require that the user have the necessary invoke/invoke-in privileges. The pki function module is installed as the following file: `install_dir/Modules/MarkLogic/pki.xqy` where `install_dir` is the directory in which MarkLogic Server is installed. To use the pki.xqy module in your own XQuery modules, include the following line in your XQuery prolog: `import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy";` The library uses the `pki:` namespace, which is `not` predefined in the server.
Function Summary
pki:create-template | This function creates a new X.509 certificate request template.
pki:delete-certificate | This function removes the specified certificate from the Security database.
pki:delete-template | This function removes the specified certificate request template from the Security database.
pki:generate-certificate-request | This function generates a PEM encoded X.509 certificate request from the template for the specified id.
pki:generate-template-certificate-authority | This function creates a common temporary certificate authority to sign all the certificates for the specified certificate template.
pki:generate-temporary-certificate | This function generates a new key pair and temporary certificate from the specified certificate template.
pki:generate-temporary-certificate-if-necessary | This function generates a new key pair and temporary certificate from the specified certificate template.
pki:get-certificate | This function returns the certificate for the specified template and host.
pki:get-certificate-pem | This function returns the PEM encoded certificate for the specified certificate template and common name combination.
pki:get-certificate-xml | This function returns the XML representation of the certificate for the specified id and common host name combination.
pki:get-certificates | This function returns the certificate data for the specified certificates.
pki:get-certificates-for-template | This function returns all of the certificates for the specified certificate template.
pki:get-certificates-for-template-xml | This function returns all of the certificates for the specified certificate template in XML format.
pki:get-pending-certificate-request | This function returns any pending certificate requests for the specified template id and host combination.
pki:get-pending-certificate-requests-pem | This function returns any pending certificate requests for the specified template.
pki:get-pending-certificate-requests-xml | This function returns any pending certificate requests for the specified template.
pki:get-template | This function returns the certificate template for the specified id.
pki:get-template-by-name | This function returns the certificate template with the specified name.
pki:get-template-certificate-authority | This function returns the certificate authority for the specified certificate template.
pki:get-template-ids | This function returns the ids for all of the certificate templates.
pki:get-trusted-certificate-ids | This function returns the ids of all of the trusted certificates in the Security database.
pki:insert-certificate-revocation-list | This function inserts a PEM- or DER-encoded Certificate Revocation List (CRL) into the security database.
pki:insert-signed-certificates | This function inserts one or more PEM-encoded signed certificates into the database.
pki:insert-template | This function inserts the specified certificate request template into the Security database and returns the certificate template id.
pki:insert-trusted-certificates | This function inserts PEM-encoded certificates into the database without checking for a matching certificate request.
pki:is-temporary | This function returns true if the certificate is temporary.
pki:need-certificate | This function returns true if the certificate specified by the template id and host combination are not signed by a trusted certificate authority.
pki:template-get-description | This function returns the description of the specified certificate template.
pki:template-get-id | This function returns the id of the specified certificate template.
pki:template-get-key-options | This function returns all of the template key options set in the specified certificate template.
pki:template-get-key-type | This function returns the key type for the specified certificate template.
pki:template-get-name | This function returns the name of the specified certificate template.
pki:template-get-request | This function returns the request portion of the certificate template.
pki:template-get-version | This function returns the version number for the specified certificate template.
pki:template-in-use | This function checks whether a certificate template is in use by an App Server.
pki:template-set-description | This function changes the description of the specified certificate template and returns the XML containing the change.
pki:template-set-key-options | This function sets the options for generating new keys in the specified certificate template.
pki:template-set-key-type | This function changes the key type for the specified certificate template and returns the XML containing the change.
pki:template-set-name | This function changes the name of the specified certificate template and returns the XML containing the change.
pki:template-set-request | This function sets the request portion for the specified certificate template.
Function Detail
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>MarkLogic</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:delete-certificate(
| $certificate-id as xs:unsignedLong
) as empty-sequence()
Summary: This function removes the specified certificate from the Security database.
Parameters:
$certificate-id : The id of the certificate to be removed.
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";

      let $cert-id := pki:get-certificates(pki:get-trusted-certificate-ids())
        [x509:cert/x509:subject/x509:organizationName eq "Bad Company"]/pki:certificate-id

      return  pki:delete-certificate($cert)

      (: Removes the certificates issued by "Bad Company" from the database. :)
pki:delete-template(
| $template-id as xs:unsignedLong
) as empty-sequence()
Summary: This function removes the specified certificate request template from the Security database.
Parameters:
$template-id : The id of the certificate request template to be removed.
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 (fn:concat("Removed:  ", $tid), pki:delete-template($tid))

       (: Deletes the template, named "test," from the database. :)
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-template-certificate-authority(
| $template-id as xs:unsignedLong,
| $valid-for as xs:unsignedInt
) as empty-sequence()
Summary: This function creates a common temporary certificate authority to sign all the certificates for the specified certificate template.
Parameters:
$template-id : The certificate template for which to create the certificate authority.
$valid-for : The number of days the generated certificate will be valid.
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("mycert"))

        return
            pki:generate-template-certificate-authority($tid, 250)

        (: Generate a certificate authority for the "mycert" template. :)
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:get-certificate(
| $template-id as xs:unsignedLong,
| $common-name as xs:string,
| $dns-name as xs:string?,
| $ip-addr as xs:string?
) as element(pki:certificate)?
Summary: This function returns the certificate for the specified template and host. The certificate data is return in both PEM-encoded and XML formats. The common name must be specified. The DNS name and IP address are optional.
Parameters:
$template-id : The certificate template id for the certificate to be returned.
$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";

      declare namespace x509=  "http://marklogic.com/xdmp/x509";

      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
        pki:get-certificate($tid, $hostname, (), ())
          [x509:cert/x509:issuer/x509:commonName eq "mycert Certificate Authority"]

      (: Returns all of the certificates on the local host that were issued
         by the "mycert" Certificate Authority. :)
pki:get-certificate-pem(
| $template-id as xs:unsignedLong,
| $hostname as xs:string
) as xs:string*
Summary: This function returns the PEM encoded certificate for the specified certificate template and common name combination.
Parameters:
$template-id : The certificate template id for the certificate to be returned.
$hostname : The common host name, if any.
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";

        let $config := admin:get-configuration()
        let $tid := pki:template-get-id(pki:get-template-by-name("mycert"))
        let $hostname := admin:host-get-name(
                           $config,
                           admin:host-get-id($config, xdmp:host-name()))

        return pki:get-certificate-pem($tid, $hostname)

      =>
          -----BEGIN CERTIFICATE-----
          MIICbzCCAdigAwIBAgIEL9pBCTANBgkqhkiG9w0BAQUFADBrMQswCQYDVQQGEwJV
          UzELMAkGA1UECBMCQ0ExEzARBgNVBAcTClNhbiBDYXJsb3MxEzARBgNVBAoTCk1h
          cmsgTG9naWMxJTAjBgNVBAMTHGhwNjkxMC02MjR2NjRiLm1hcmtsb2dpYy5jb20w
          HhcNMDkwMjE4MjAxOTA4WhcNMTAwMjE4MjAxOTA4WjBrMQswCQYDVQQGEwJVUzEL
          MAkGA1UECBMCQ0ExEzARBgNVBAcTClNhbiBDYXJsb3MxEzARBgNVBAoTCk1hcmsg
          TG9naWMxJTAjBgNVBAMTHGhwNjkxMC02MjR2NjRiLm1hcmtsb2dpYy5jb20wgZ8w
          DQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAM/gj+cfWnL2IOsUgbiKhEahbdbCye57
          NcschJ0mMzBaHcJ43u/HhJI11RhW9rCUaF9h8JAMmtP03TFEkFzaUs9NZNTqvVzH
          mWjk71oKvy/JJUley15Lbs/twqmDo6punvsWFbjxKt6kzjrg6NMNTxn2pGOtYEf6
          yymUfL19J069AgMBAAGjIDAeMAkGA1UdEwQCMAAwEQYJYIZIAYb4QgEBBAQDAgZA
          MA0GCSqGSIb3DQEBBQUAA4GBAJvN5UVn/b6S2XUYge9aQDiIhyc1EwbWyuXxvA6i
          WCiTWUl/2Dbh+UNjK+KwLvxO8wR4RLO4TtX86XA0Up+3fpLDyY+Q3W0Q2uj6ZzMe
          pRmQyo67qQDrfJU8bgUzx0uqTEbgYhGyJ3IQuNpUWt9tZty6+4i6WdCgGVA9CWuU
          ujPm
          -----END CERTIFICATE-----
pki:get-certificate-xml(
| $template-id as xs:unsignedLong,
| $hostname as xs:string
) as element(x509:cert)*
Summary: This function returns the XML representation of the certificate for the specified id and common host name combination.
Parameters:
$template-id : The certificate template id for the certificate to be returned.
$hostname : The common host name, if any.
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";

      let $config := admin:get-configuration()
      let $tid := pki:template-get-id(pki:get-template-by-name("test"))
      let $hostname := admin:host-get-name(
                           $config,
                           admin:host-get-id($config, xdmp:host-name()))

      return
         pki:get-certificate-xml($tid, $hostname)

      (: Returns the certificate in XML format for the local host. :)
pki:get-certificates(
| $cert-id as xs:unsignedLong*
) as element(pki:certificate)*
Summary: This function returns the certificate data for the specified certificates.
Parameters:
$cert-id : One or more certificate ids.
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";

      pki:get-certificates(
               pki:get-trusted-certificate-ids()) [pki:authority = fn:true()]

      (: Returns all of the certificates generated by a certificate authority. :)
pki:get-certificates-for-template(
| $template-id as xs:unsignedLong
) as element(pki:certificate)*
Summary: This function returns all of the certificates for the specified certificate template.
Parameters:
$template-id : The certificate template id for the certificates to be returned.
Example:
      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("mycert"))

      return
         pki:get-certificates-for-template($tid)

      (: Returns the certificates for the "mycert" template. :)
pki:get-certificates-for-template-xml(
| $template-id as xs:unsignedLong
) as element(x509:cert)*
Summary: This function returns all of the certificates for the specified certificate template in XML format.
Parameters:
$template-id : The certificate template id for the certificates to be returned.
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("mycert"))

      return
         pki:get-certificates-for-template-xml($tid)

      (: Returns the certificates for the "mycert" template in XML format. :)
pki:get-pending-certificate-request(
| $template-id as xs:unsignedLong,
| $common-name as xs:string,
| $dns-name as xs:string?,
| $ip-addr as xs:string?
) as element(pki:request)?
Summary: This function returns any pending certificate requests for the specified template id and host combination. The certificate request data is return in both PEM-encoded and XML formats. The common name must be specified. The DNS name and IP address are optional.
Parameters:
$template-id : The certificate template id for the certificate request to be returned.
$common-name : The common hostname (e.g., `myhost.company.com` or `company.com`) in the certificate request.
$dns-name : The DNS name in the certificate request.
$ip-addr : The IP address name in the certificate request.
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";

      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
          pki:get-pending-certificate-request($tid, $hostname, (), ())

      (: Returns all of the pending certificate requests for the local host :)
pki:get-pending-certificate-requests-pem(
| $template-id as xs:unsignedLong
) as xs:string*
Summary: This function returns any pending certificate requests for the specified template. The pending requests are returned as PEM encoded strings.
Parameters:
$template-id : The certificate template id for the certificate requests to be returned.
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";

      for $tid in pki:get-template-ids()
         return pki:get-pending-certificate-requests-pem($tid)

      (: Returns all of the pending certificate requests in the security database in PEM
      encoded format. :)
pki:get-pending-certificate-requests-xml(
| $template-id as xs:unsignedLong
) as element(x509:req)*
Summary: This function returns any pending certificate requests for the specified template. The pending requests are returned as XML.
Parameters:
$template-id : The certificate template id for the certificate requests to be returned.
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";

      for $tid in pki:get-template-ids()
         return pki:get-pending-certificate-requests-xml($tid)

      (: Returns all of the pending certificate requests in the security database in XML format. :)
pki:get-template(
| $template-id as xs:unsignedLong*
) as element(pki:template)*
Summary: This function returns the certificate template for the specified id.
Parameters:
$template-id : The id of the certificate template to be returned.
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";

      for $tid in pki:get-template-ids()
         return (pki:get-template($tid))

      (: Returns all of the certificate templates in the security database. :)
pki:get-template-by-name(
| $template-name as xs:string
) as element(pki:template)*
Summary: This function returns the certificate template with the specified name.
Parameters:
$template-name : The name of the template to be returned.
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";

        pki:get-template-by-name("test")

        (: Returns the certificate template, named "test". :)
pki:get-template-certificate-authority(
| $template-id as xs:unsignedLong
) as element(pki:certificate)?
Summary: This function returns the certificate authority for the specified certificate template.
Parameters:
$template-id : The certificate template for which to return the certificate authority.
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("mycert"))

        return
            pki:get-template-certificate-authority($tid)

        (: Return the certificate authority for the "mycert" template. :)
pki:get-template-ids( ) as xs:unsignedLong*
Summary: This function returns the ids for all of the certificate templates.
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";

      pki:get-template-ids()

       => 8197058186045144130
          10553510181853787005
          1457227631685032024
          8898647899939825066
pki:get-trusted-certificate-ids( ) as xs:unsignedLong*
Summary: This function returns the ids of all of the trusted certificates in the Security database.
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";

       pki:get-trusted-certificate-ids()

       =>
           5182918040410509551
           14829635941505935843
           17428733531660907126
           1566218877500482981
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:insert-signed-certificates(
| $certs as xs:string
) as empty-sequence()
Summary: This function inserts one or more PEM-encoded signed certificates into the database. The signed certificates are matched up against previously generated certificate requests and any previous certificate is replaced. If there is no matching certifcate request for the specified certificate, the certificate is not inserted into the database.
Parameters:
$certs : One or more PEM-encoded signed certificates to be inserted into the database.
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";

      pki:insert-signed-certificates(
         xdmp:document-get(
             "c:\SignedCertificates\Signed_cert.cer",
             <options xmlns="xdmp:document-get"><format>text</format></options>))

      (: Inserts the PEM-encoded signed certificate from the Signed_cert.cer file into
         the database. :)
pki:insert-template(
| $template as element(pki:template)
) as xs:unsignedLong
Summary: This function inserts the specified certificate request template into the Security database and returns the certificate template id.
Parameters:
$template : The certificate request template created by the `pki:create-template()` function.
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>MarkLogic</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>

         let $template := pki:create-template(
                "testTemplate",
                "Creating a new template",
                "rsa",
                 $options,
                 $x509)

         return
           pki:insert-template($template)

      (: Creates a new certificate template, named "testTemplate," and inserts it into the database. :)
pki:insert-trusted-certificates(
| $certs as xs:string
) as xs:unsignedLong*
Summary: This function inserts PEM-encoded certificates into the database without checking for a matching certificate request. This allows you to insert temporary certificates and those from new Certificate Authorities.
Parameters:
$certs : One or more PEM-encoded certificates to be inserted into the database.
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";

      pki:insert-trusted-certificates(
         xdmp:document-get(
             "c:\TrustedCertificates\Trusted_cert.cer",
             <options xmlns="xdmp:document-get"><format>text</format></options>))

      (: Inserts the PEM-encoded trusted certificate from the Trusted_cert.cer file into
         the database. :)
pki:is-temporary(
| $cert as element(pki:certificate)
) as xs:boolean
Summary: This function returns true if the certificate is temporary. Otherwise, it returns false.
Parameters:
$cert : The certificate to be tested.
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";

      let $config := admin:get-configuration()
      let $tid := pki:template-get-id(pki:get-template-by-name("mycert"))
      let $hostname := admin:host-get-name(
                           $config,
                           admin:host-get-id($config, xdmp:host-name()))

      return pki:is-temporary(pki:get-certificate($tid, $hostname, (), ()))

      (: Returns 'true' if certificate is temporary; otherwise 'false'. :)
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. :)
pki:template-get-description(
| $template as element(pki:template)
) as xs:string
Summary: This function returns the description of the specified certificate template.
Parameters:
$template : The certificate template from which to get the description.
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";

      for $tid in pki:get-template-ids()
        return  pki:template-get-description(pki:get-template($tid))

      (: Returns the descriptions of the certificate templates. :)
pki:template-get-id(
| $template as element(pki:template)
) as xs:unsignedLong
Summary: This function returns the id of the specified certificate template.
Parameters:
$template : A certificate request template created by the `pki:create-template()` function.
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";

      pki:template-get-id(pki:get-template-by-name("test"))

      (: Returns the id for the "test" certificate template. :)
pki:template-get-key-options(
| $template as element(pki:template)
) as element(pki:key-options)
Summary: This function returns all of the template key options set in the specified certificate template.
Parameters:
$template : The certificate template from which to get the key options.
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";

        pki:template-get-key-options(pki:get-template-by-name("test"))

        (: Return all of the key options in the certificate template, named "test." :)
pki:template-get-key-type(
| $template as element(pki:template)
) as xs:string
Summary: This function returns the key type for the specified certificate template.
Parameters:
$template : The certificate template from which to get the key type.
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";;

      for $tid in pki:get-template-ids()
         return  pki:template-get-key-type(pki:get-template($tid))

      (: Returns the key types of the certificate templates. :)
pki:template-get-name(
| $template as element(pki:template)
) as xs:string
Summary: This function returns the name of the specified certificate template.
Parameters:
$template : The certificate template from which to get the name.
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";

      for $tid in pki:get-template-ids()
        return  pki:template-get-name(pki:get-template($tid))

      =>
        mycert3
        mycert2
        mycert
pki:template-get-request(
| $template as element(pki:template)
) as element(x509:req)
Summary: This function returns the request portion of the certificate template.
Parameters:
$template : The certificate template from which to extract the request portion.
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";

        pki:template-get-request(pki:get-template-by-name("test"))

        (: Returns the request portion of the "test" template. :)
pki:template-get-version(
| $template as element(pki:template)
) as xs:unsignedLong
Summary: This function returns the version number for the specified certificate template.
Parameters:
$template : The certificate template from which to get the version number.
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";

      for $tid in pki:get-template-ids()
      return
        pki:template-get-version(pki:get-template($tid))

      (: Returns the version numbers of the certificate templates. :)
pki:template-in-use(
| $template-id as xs:unsignedLong
) as xs:boolean
Summary: This function checks whether a certificate template is in use by an App Server. Returns `true` if the template is in use. Otherwise `false` is returned.
Parameters:
$template-id : The id of the certificate template to be tested.
Example:
      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("mycert"))

      return
         pki:template-in-use($tid)

      (: Returns 'true' if the template is in use by an App Server.  Otherwise, 'false'. :)
pki:template-set-description(
| $template as element(pki:template),
| $description as xs:string
) as element(pki:template)
Summary: This function changes the description of the specified certificate template and returns the XML containing the change. Use `pki:insert-template` to save the change to the Security database.
Parameters:
$template : The certificate template for which to change the description.
$description : The new description for the certificate 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:template-set-description(
             pki:get-template($tid),
             "The new description of the certificate.")

      (: Returns the XML for the certificate template with the new description. :)
pki:template-set-key-options(
| $template as element(pki:template),
| $key-options as element(pki:key-options)
) as element(pki:template)
Summary: This function sets the options for generating new keys in the specified certificate template. The returned element must be separately inserted into the database with `pki:insert-template`.
Parameters:
$template : The certificate template for which to set the key options.
$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.
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 ssl = "http://marklogic.com/xdmp/ssl";

         let $options :=  <pki:key-options xmlns="ssl:options">
                             <key-length>2048</key-length>
                          </pki:key-options>

         return
           pki:template-set-key-options(
              pki:get-template-by-name("test"), $options)

         (: Sets the key options in the "test" template. :)
pki:template-set-key-type(
| $template as element(pki:template),
| $key-type as xs:string
) as element(pki:template)
Summary: This function changes the key type for the specified certificate template and returns the XML containing the change. Use `pki:insert-template` to save the change to the Security database.
Parameters:
$template : The certificate template for which to change the key type.
$key-type : The new key type for the certificate template. The key type must be "rsa" and entered in lower case.
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:template-set-key-type(pki:get-template($tid), "rsa")

      (: Returns the XML for the certificate template with the new key type. :)
pki:template-set-name(
| $template as element(pki:template),
| $name as xs:string
) as element(pki:template)
Summary: This function changes the name of the specified certificate template and returns the XML containing the change. Use `pki:insert-template` to save the change to the Security database.
Parameters:
$template : The certificate template for which to change the name.
$name : The new name for the certificate 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:template-set-name(pki:get-template($tid), "foo")

      (: Returns the XML for the certificate template with the new name. :)
pki:template-set-request(
| $template as element(pki:template),
| $req as element(x509:req)
) as element(pki:template)
Summary: This function sets the request portion for the specified certificate template. Use `pki:insert-template` to save the change to the Security database.
Parameters:
$template : The certificate template from which to set the request portion.
$req : The request portion to be set in the certificate 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";

         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>MarkLogic</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>

      return
        pki:insert-template(
        pki:template-set-request(
          pki:get-template-by-name("test"), $x509))

      (: Updates the request portion of the "test" template. :)

© Copyright 2002-2012 MarkLogic Corporation. All rights reserved.