Update setup.py, add certificate authority design documentation

doc/P-SLAPOS.Certificate.Authority.Plantuml.Sequence.Diagram.Signing.Request.txt

+@startuml
+title Automated Certificate Authority Service
+
+
+actor User
+actor Trusted
+actor Service
+autonumber
+
+== Signing Request Submission ==
+
+User -> Authority : POST the CRL
+alt Sining request passes all checks
+  Authority --> User : Signing request identifier
+else
+  Authority --> User : Error
+end
+Note over User : See "Certificate Retrieval"
+
+== Certificate Production ==
+
+Note over Trusted : See "Signing Request Submission"
+Trusted -> Authority : GET (optional: with result range expression)
+Authority --> Trusted : List of pending signing requests with their identifiers
+Trusted -> Authority : GET with request identifier
+Authority --> Trusted : Signing request content
+alt Trusted agrees to prvoduce a signed certificate from the signing request
+  Trusted -> Authority : POST with the signing request identifier
+  alt Sining request was still pending
+    Authority --> Trusted : Success
+  else
+    Authority --> Trusted : Not found
+  end
+else
+  Trusted -> Authority : DELETE with the signing request identifier
+  Authority --> Trusted : Ok
+end
+
+== Certificate Retrieval ==
+
+loop Until certificate obtained or request rejected
+  User -> Authority : GET with signing request identifier
+  alt Signing request was signed
+    Authority --> User : Certificate content
+  else
+    Authority --> User : Not found
+    opt User wants to check request is still pending
+      User -> Authority : GET with signing request identifier
+      alt Sining request is still pending
+        Authority --> User : Signing request content
+      else
+        Authority --> User : Not found
+      end
+    end
+  end
+end
+
+== Certificate Renewal ==
+
+User -> Authority : POST with the still-valid CRT and a CRL
+alt Renewal parameters consistent
+  Authority --> User : signing request identifier
+else
+  Authority --> User : Error
+end
+Note over User : See "Certificate Retrieval"
+
+== Certificate Revocation ==
+
+User -> Authority : POST with the CRT
+alt Revocation parameters consistent
+  Authority --> User : Ok
+else
+  Authority --> User : Error
+end
+
+== Certificate Validity Check ==
+
+Service -> Authority : GET (optional: with OCSP parameter)
+Authority --> Service : Certificate revocation list
+@enduml

doc/P-SLAPOS.Certificate.Authority.Swagger.API.Specification-en-001.yml

+swagger: '2.0'
+info:
+  title: Certificate Authority
+  description: Automated x509 certificate authority for use with non-http services
+  version: 0.0.1
+  contact:
+    name: Vincent Pelletier (Nexedi)
+    url: 'http://www.nexedi.com'
+    email: vincent@nexedi.com
+basePath: /
+schemes:
+  - http
+  - https
+consumes:
+  - application/json
+  - application/pkcs10
+produces:
+  - application/xml
+  - application/json
+  - application/pkix-cert
+  - application/x-x509-ca-cert
+tags:
+  - name: todo
+    description: Known as not fully specified yet
+paths:
+  /csr:
+    get:
+      tags:
+        - todo
+      summary: List pending certificate signing requests - XXX PROPFIND, not GET !
+      operationId: getPendingCertificateRequestList
+      schemes:
+        - https
+      parameters:
+        - $ref: '#/parameters/x-auth'
+      responses:
+        '401':
+          $ref: '#/responses/401'
+        '403':
+          $ref: '#/responses/403'
+        '500':
+          $ref: '#/responses/500'
+    put:
+      summary: Request a new certificate signature
+      operationId: createCertificateSigningRequest
+      consumes:
+        - application/pkcs10
+      parameters:
+        - $ref: '#/parameters/csr'
+      responses:
+        '201':
+          description: Created - Signing request was accepted
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+        '507':
+          $ref: '#/responses/507'
+  /csr/{crt-id}:
+    delete:
+      summary: Reject a pending certificate signing request
+      operationId: deletePendingCertificateRequest
+      schemes:
+        - https
+      parameters:
+        - $ref: '#/parameters/x-auth'
+        - $ref: '#/parameters/crt-id'
+      responses:
+        '204':
+          description: No Content - CSR was rejected
+        '401':
+          $ref: '#/responses/401'
+        '403':
+          $ref: '#/responses/403'
+        '404':
+          $ref: '#/responses/404'
+        '500':
+          $ref: '#/responses/500'
+    get:
+      summary: Retrieve a pending certificate signing request
+      operationId: getCertificateSigningRequest
+      produces:
+        - application/pkcs10
+      parameters:
+        - $ref: '#/parameters/crt-id'
+      responses:
+        '200':
+          description: OK - CSR retrieved
+        '404':
+          $ref: '#/responses/404'
+        '500':
+          $ref: '#/responses/500'
+  /crt:
+    put:
+      summary: Accept pending certificate signing request
+      operationId: createCertificate
+      schemes:
+        - https
+      consumes:
+        - application/pkcs10
+      parameters:
+        - $ref: '#/parameters/x-auth'
+        - $ref: '#/parameters/csr'
+      responses:
+        '201':
+          description: Created - Certificate was signed
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '401':
+          $ref: '#/responses/401'
+        '404':
+          $ref: '#/responses/404'
+        '403':
+          $ref: '#/responses/403'
+        '500':
+          $ref: '#/responses/500'
+  /crt/{crt-id}:
+    get:
+      summary: Retrieve a signed certificate
+      operationId: getCertificate
+      produces:
+        - application/pkix-cert
+      parameters:
+        - $ref: '#/parameters/crt-id'
+      responses:
+        '200':
+          description: OK - CRT retrieved
+        '404':
+          $ref: '#/responses/404'
+        '500':
+          $ref: '#/responses/500'
+  /crt/revoke:
+    put:
+      summary: Revoke a certificate
+      description: >
+        Response status 400 may mean operation could not be authenticated (signature hash mechanism not supported by server, signature did not match...). Signed operation payload schema is described separately.
+      operationId: revokeCertificate
+      consumes:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/signed-operation'
+      responses:
+        '201':
+          description: Created - Signing request was revoked
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+  /crt/renew:
+    put:
+      summary: Renew a certificate
+      description: >
+        Response status 400 may mean operation could not be authenticated (signature hash mechanism not supported by server, signature did not match...), in addition to createCertificateSigningRequest status 400 reasons. Signed operation payload schema is described separately.
+      operationId: renewCertificate
+      consumes:
+        - application/json
+      parameters:
+        - $ref: '#/parameters/signed-operation'
+      responses:
+        '201':
+          description: Created - Renewwal request was accepted
+          headers:
+            Location:
+              description: URL of created resource
+              type: string
+        '400':
+          $ref: '#/responses/400'
+        '500':
+          $ref: '#/responses/500'
+  /crl:
+    get:
+      summary: Retrieve latest certificate revocation list
+      operationId: getCertificateRevocationList
+      produces:
+        - application/x-x509-ca-cert
+      responses:
+        '200':
+          description: OK - CRL retrieved
+        '500':
+          $ref: '#/responses/500'
+definitions:
+  csr:
+    type: string
+    description: application/pkcs10 data
+  Error:
+    type: object
+    required:
+      - code
+      - name
+      - message
+    properties:
+      code:
+        type: integer
+        description: application-specific error code
+      name:
+        type: string
+        description: the explicit error name
+      message:
+        type: string
+        description: describes the error
+  signed-operation:
+    type: object
+    required:
+      - signature
+      - payload
+      - digest
+    properties:
+      digest:
+        type: string
+        description: Digest method name used to generate the signature (like "sha256", "sha512", etc)
+      signature:
+        type: string
+        description: Base64-encoded signature generated by concatenating payload, digest and the space character (0x20), in this order.
+      payload:
+        type: string
+        description: Operation parameters. This is a json-encoded value whose structure depends on the operation.
+parameters:
+  crt-id:
+    name: crt-id
+    in: path
+    description: Opaque certificate signing request identifier
+    required: true
+    type: string
+  x-auth:
+    name: Authorization
+    in: header
+    description: Credentials for this request
+    type: string
+    required: true
+  csr:
+    name: csr
+    in: body
+    description: x509 Certificate Signing Request
+    required: true
+    schema:
+      $ref: '#/definitions/csr'
+  signed-operation:
+    name: signed-operation
+    in: body
+    description: An operation, signed with requester's private key
+    schema:
+      $ref: '#/definitions/signed-operation'
+responses:
+  '400':
+    description: Bad Request - you probably provided wrong parameters
+    schema:
+      $ref: '#/definitions/Error'
+  '401':
+    description: Unauthorized - No Authorization header provided
+    headers:
+      Authenticate:
+        type: string
+        description: Requests that client provides credentials
+    schema:
+      $ref: '#/definitions/Error'
+  '403':
+    description: Forbidden - Authorization headed provided, but does not grant access
+    schema:
+      $ref: '#/definitions/Error'
+  '404':
+    description: Not Found - Requested resource does not exist
+    schema:
+      $ref: '#/definitions/Error'
+  '500':
+    description: Internal Server Error
+  '507':
+    description: Insufficient Storage

setup.py

@@ -15,3 +15,63 @@
 #
 # You should have received a copy of the GNU General Public License
 # along with caucase.  If not, see <http://www.gnu.org/licenses/>.
+
+from setuptools import setup, find_packages
+import glob
+import os
+
+version = '0.1'
+name = 'caucase'
+long_description = open("README.rst").read() + "\n"
+
+for f in sorted(glob.glob(os.path.join('slapos', 'README.*.rst'))):
+  long_description += '\n' + open(f).read() + '\n'
+
+# long_description += open("CHANGES.txt").read() + "\n"
+
+# Provide a way to install additional requirements
+additional_install_requires = []
+try:
+  import argparse
+except ImportError:
+  additional_install_requires.append('argparse')
+
+setup(name=name,
+      version=version,
+      description="Certificate Authority.",
+      long_description=long_description,
+      classifiers=[
+          "Programming Language :: Python",
+        ],
+      keywords='certificate authority',
+      license='GPLv3',
+      namespace_packages=['caucase'],
+      packages=find_packages(),
+      include_package_data=True,
+      install_requires=[
+        'Flask', # needed by servers
+        'flask_user',
+        'setuptools', # namespaces
+        'pyOpenSSL', # manage ssl certificates
+        'pyasn1', # ASN.1 types and codecs for certificates
+        'pyasn1-modules',
+        'requests', # http requests
+        'pem', # Parse PEM files
+      ] + additional_install_requires,
+      extras_require = {
+
+      },
+      tests_require = [
+        'Flask-Testing',
+      ],
+      zip_safe=False, # proxy depends on Flask, which has issues with
+                      # accessing templates
+      entry_points={
+        'console_scripts': [
+          'ca-bin = caucase.web:start',
+          'ca-cli = caucase.cli:main',
+          'ca-cliweb = caucase.cli_flask:main',
+        ]
+      },
+      test_suite='caucase.test',
+    )