<apidoc:module name="PKIModule" category="PKI" lib="pki" 
	bucket="XQuery Library Modules"
	xmlns:apidoc="http://marklogic.com/xdmp/apidoc" 
	xmlns="http://www.w3.org/1999/xhtml">
  <apidoc:summary>
     <p>
      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).
      </p><p>
      All of these functions automatically invoke against the appropriate 
      security database, and require that the user have the necessary 
      invoke/invoke-in privileges.
      </p><p>
      The pki function module is installed as the following file:</p> 
      <p><code><em>install_dir</em>/Modules/MarkLogic/pki.xqy</code></p>
      <p>where <code><em>install_dir</em></code> is the directory in which 
      MarkLogic Server is installed.</p><p> To use the pki.xqy module in your own
      XQuery modules, include the following line in your XQuery prolog:</p><p>
      <code>import module namespace pki = "http://marklogic.com/xdmp/pki" 
                  at "/MarkLogic/pki.xqy";</code>
      </p><p>
      The library uses the <code>pki:</code> namespace, which is 
    <code>not</code> predefined in the server.</p>
    </apidoc:summary>
  <apidoc:function name="create-template" lib="pki" 
	  category="PKI" bucket="XQuery Library Modules">
    <apidoc: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 <code>pki:insert-template</code>.   
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="name" type="xs:string">
         The name of the certificate request template.
      </apidoc:param>
      <apidoc:param name="description" type="xs:string">
         A description of the certificate request template.
      </apidoc:param>
      <apidoc:param name="key-type" type="xs:string?">
         The type of key to use (enter "rsa").
      </apidoc:param>
      <apidoc:param name="key-options" type="element()?">
	  The options for generating new keys.  The valid options are 
	  <code>key-length</code>, which 
	  specifies the number of bits in a key (512, 1024, 2048, 4096), and 
	  <code>pass-phrase</code>, which specifies the pass phrase for 
	  encrypting/decrypting a private key.	  
      </apidoc:param>
      <apidoc:param name="csr" type="element(x509:req)">
          An XML representation of the certificate request template.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
     (: 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." :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="insert-template" lib="pki" 
	  category="PKI" bucket="XQuery Library Modules">
  <apidoc:summary>
     This function inserts the specified certificate request template into the
     Security database and returns the certificate template id.
  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
	      The certificate request template created by the 
	      <code>pki:create-template()</code> function.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
     (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="delete-certificate" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
     <apidoc:summary>
         This function removes the specified certificate from the
         Security database.
     </apidoc:summary>
    <apidoc:params>
       <apidoc:param name="certificate-id" type="xs:unsignedLong">
         The id of the certificate to be removed.
       </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="delete-template" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
      <apidoc:summary>
         This function removes the specified certificate request template from the
         Security database.
     </apidoc:summary>
    <apidoc:params>
       <apidoc:param name="template-id" type="xs:unsignedLong">
         The id of the certificate request template to be removed.
       </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
   (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-get-id" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>
       This function returns the id of the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
    <apidoc:param name="template" type="element(pki:template)">
       A certificate request template created by the 
       <code>pki:create-template()</code> function.
    </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-get-name" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the name of the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
        The certificate template from which to get the name.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-set-name" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function changes the name of the specified certificate 
    template and returns the XML containing the change.  Use <code>pki:insert-template</code> 
    to save the change to the Security database.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template for which to change the name.</apidoc:param>
      <apidoc:param name="name" type="xs:string">
         The new name for the certificate template.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-get-description" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>
      This function returns the description of the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to get the description.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-set-description" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function changes the description of the specified certificate 
    template and returns the XML containing the change.  Use <code>pki:insert-template</code>
    to save the change to the Security database. </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template for which to change the description.
      </apidoc:param>
      <apidoc:param name="description" type="xs:string">
         The new description for the certificate template.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function> 
  <apidoc:function name="template-get-key-type" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
      This function returns the key type for the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to get the key type.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-set-key-type" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>This function changes the key type for the specified certificate 
    template and returns the XML containing the change.  Use <code>pki:insert-template</code>
    to save the change to the Security database. </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template for which to change the key type.
      </apidoc:param>
      <apidoc:param name="key-type" type="xs:string">
         The new key type for the certificate template.  The key 
         type must be "rsa" and entered in lower case.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-get-version" lib="pki" 
       category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
      This function returns the version number for the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to get the version number.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-get-key-options" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
       This function returns all of the template key options set in the 
       specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to get the key options.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:key-options)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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." :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-set-key-options" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc: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 <code>pki:insert-template</code>. 
 </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template for which to set the key options.
      </apidoc:param>
      <apidoc:param name="key-options" type="element(pki:key-options)">
      	 The options for generating new keys.  The valid options are 
      	 <code>key-length</code>, which 
	 specifies the number of bits in a key (512, 1024, 2048, 4096), and 
         <code>pass-phrase</code>, which specifies the pass phrase for encrypting/decrypting 
	 a private key.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
     (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>

  <apidoc:function name="template-get-request" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the request portion of the certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to extract the request portion.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(x509:req)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="template-set-request" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function sets the request portion for the specified
    certificate template.  Use <code>pki:insert-template</code> to save the change to the
    Security database.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template" type="element(pki:template)">
         The certificate template from which to set the request portion.
      </apidoc:param>
      <apidoc:param name="req" type="element(x509:req)">
         The request portion to be set in the certificate template.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
   (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-template-ids" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the ids for all of the certificate 
    templates.</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[		  
  (: 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 
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-template" lib="pki" category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the certificate template for the 
    specified id.</apidoc:summary>
    <apidoc:params>
    <apidoc:param name="template-id" type="xs:unsignedLong*">
        The id of the certificate template to be returned.
    </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="generate-certificate-request" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc: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.
       <p>
       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.</p>
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
          The certificate template id for which to generate the certificate request. 
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
          The common name to put into the template.
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
          The DNS name, if any, to substitute into the template.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
          The IP address, if any, to substitute into the template.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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-----
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-pending-certificate-requests-pem" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
       This function returns any pending certificate requests for the specified template. 
       The pending requests are returned as PEM encoded strings. 
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
          The certificate template id for the certificate requests to be returned. 
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-pending-certificate-requests-xml" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
       This function returns any pending certificate requests for the specified template. 
       The pending requests are returned as XML.</apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
          The certificate template id for the certificate requests to be returned. 
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(x509:req)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="insert-signed-certificates" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc: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.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="certs" type="xs:string">
          One or more PEM-encoded signed certificates to be inserted into the database.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="insert-trusted-certificates" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc: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. </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="certs" type="xs:string">
          One or more PEM-encoded certificates to be inserted into the database.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-trusted-certificate-ids" lib="pki" 
    category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the ids of all of the trusted certificates in the 
    Security database.</apidoc:summary>
    <apidoc:params/>
    <apidoc:return>xs:unsignedLong*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
   (: 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
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-certificate" lib="pki" category="PKI" bucket="XQuery Library Modules">
    <apidoc: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. 
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
            The certificate template id for the certificate to be returned.
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
	    The common hostname (e.g., <code>myhost.company.com</code> 
	    or <code>company.com</code>) in the certificate.
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
           The DNS name in the certificate.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
           The IP address name in the certificate.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:certificate)?</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="need-certificate" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc: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. 
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
            The certificate template id for the certificate.     
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
           The common hostname (e.g., <code>myhost.company.com</code> 
           or <code>company.com</code>) in the certificate.
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
           The DNS name in the certificate.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
           The IP address name in the certificate.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-pending-certificate-request" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc: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. 
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong"> 
           The certificate template id for the certificate request to be returned.
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
           The common hostname (e.g., <code>myhost.company.com</code> 
           or <code>company.com</code>) in the certificate request.
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
           The DNS name in the certificate request.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
           The IP address name in the certificate request.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:request)?</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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 :)
  ]]></pre></apidoc:example>
  </apidoc:function>			
  <apidoc:function name="generate-temporary-certificate-if-necessary" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc: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.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
           The certificate template id to use for the creating the certificate.
      </apidoc:param>
      <apidoc:param name="valid-for" type="xs:unsignedInt">
           The number of days the certificate should be valid for
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
           The common name to put into the template.
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
           The DNS name, if any, to substitute into the template.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
           The IP address, if any, to substitute into the template 
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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 :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="generate-temporary-certificate" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc: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.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
           The certificate template id to use for the creating the certificate.
      </apidoc:param>
      <apidoc:param name="valid-for" type="xs:unsignedInt">
           The number of days the certificate should be valid for
      </apidoc:param>
      <apidoc:param name="common-name" type="xs:string">
           The common name to put into the template
      </apidoc:param>
      <apidoc:param name="dns-name" type="xs:string?">
           The DNS name, if any, to substitute into the template.
      </apidoc:param>
      <apidoc:param name="ip-addr" type="xs:string?">
           The IP address, if any, to substitute into the template 
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
   (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="is-temporary" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
     <apidoc:summary>
        This function returns true if the certificate is temporary.  
        Otherwise, it returns false.
     </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="cert" type="element(pki:certificate)">
        The certificate to be tested.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:boolean</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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'. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-certificate-xml" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
    This function returns the XML representation of the certificate for the 
    specified id and common host name combination.    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
           The certificate template id for the certificate to be returned.
      </apidoc:param>
      <apidoc:param name="hostname" type="xs:string">
           The common host name, if any.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(x509:cert)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-certificates-for-template-xml" lib="pki" 
   category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
       This function returns all of the certificates for the specified
       certificate template in XML format.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
           The certificate template id for the certificates to be returned.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(x509:cert)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-certificate-pem" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the PEM encoded certificate for the specified 
    certificate template and common name combination.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
           The certificate template id for the certificate to be returned.
      </apidoc:param>
      <apidoc:param name="hostname" type="xs:string">
           The common host name, if any.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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-----
  ]]></pre></apidoc:example>
  </apidoc:function>
    <apidoc:function name="get-template-by-name" lib="pki" category="PKI" 
    bucket="XQuery Library Modules">
    <apidoc:summary>This function returns the certificate template with the specified name. 
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-name" type="xs:string">
      The name of the template to be returned.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:template)*</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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". :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="get-template-certificate-authority" lib="pki" category="PKI" 
  bucket="XQuery Library Modules">
    <apidoc:summary>
    This function returns the certificate authority for the specified certificate 
    template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
        The certificate template for which to return the certificate authority.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>element(pki:certificate)?</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
  <apidoc:function name="generate-template-certificate-authority" lib="pki" 
  category="PKI" bucket="XQuery Library Modules">
    <apidoc:summary>
    This function creates a common temporary certificate authority to sign all 
    the certificates for the specified certificate template.
    </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="template-id" type="xs:unsignedLong">
        The certificate template for which to create the certificate authority.
      </apidoc:param>
      <apidoc:param name="valid-for" type="xs:unsignedInt">
         The number of days the generated certificate will be valid.
      </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:example><pre xml:space="preserve"><![CDATA[
    (: 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. :)
  ]]></pre></apidoc:example>
  </apidoc:function>
<apidoc:function name="get-certificates" lib="pki" category="PKI" 
bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>This function returns the certificate data for the specified certificates.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="cert-id" type="xs:unsignedLong*">
    One or more certificate ids.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>element(pki:certificate)*</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  (: 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. :)
     ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="get-certificates-for-template" lib="pki" category="PKI" 
bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>
      This function returns all of the certificates for the specified certificate template.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="template-id" type="xs:unsignedLong">
       The certificate template id for the certificates to be returned.
  </apidoc:param>
  </apidoc:params>
  <apidoc:return>element(pki:certificate)*</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  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. :)
     ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="template-in-use" lib="pki" category="PKI"
  bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
  <apidoc:summary>This function checks whether a certificate template is in
  use by an App Server.  Returns <code>true</code> if the template is in use. 
  Otherwise <code>false</code> is returned.
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="template-id" type="xs:unsignedLong">
         The id of the certificate template to be tested.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>xs:boolean</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  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'. :)
     ]]></pre>
  </apidoc:example>
</apidoc:function>
<apidoc:function name="insert-certificate-revocation-list" lib="pki" 
category="PKI" bucket="XQuery Library Modules" xmlns:apidoc="http://marklogic.com/xdmp/apidoc">
<apidoc: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.
        <p/>
	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.	
  </apidoc:summary>
  <apidoc:params>
    <apidoc:param name="url" type="xs:string">
      The URL from which the CRL was downloaded.
    </apidoc:param>
    <apidoc:param name="crl" type="item()">
      The PEM- or DER-encoded CRL.
    </apidoc:param>
  </apidoc:params>
  <apidoc:return>empty-sequence()</apidoc:return>
  <apidoc:example><pre xml:space="preserve"><![CDATA[
  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. :)
     ]]></pre>
  </apidoc:example>
</apidoc:function>

</apidoc:module>
